Overview

Owner commands let you monitor and control your AI assistant directly from your messaging app. The OwnerCommandsMiddleware intercepts slash commands from the configured owner before they reach the agent.

Setup

import { ownerCommands } from '@cogitator-ai/channels';

const gateway = new Gateway({
  // ...
  middleware: [
    ownerCommands({
      ownerIds: {
        telegram: '123456789',
        discord: '987654321',
      },
      onStatus: () => `Up 2h, 5 sessions, 847 messages`,
      onSessions: () => `Active: @john (telegram), @jane (discord)`,
      onModel: (model, forUser) => `Model switched to ${model}`,
      onCompact: async (target) => `Compacted ${target}`,
    }),
  ],
});

Available Commands

Command	Description
`/status`	Show uptime, sessions, message count
`/sessions`	List active sessions
`/users`	List approved/blocked users
`/model <name> [@user]`	Switch model globally or for a specific user
`/compact [target]`	Trigger conversation compaction
`/restart`	Graceful restart
`/help`	Show available commands

Configuration

interface OwnerCommandsConfig {
  ownerIds: Record<string, string>;
  onStatus?: () => string;
  onSessions?: () => string;
  onUsers?: () => string;
  onCompact?: (target: string) => Promise<string>;
  onModel?: (model: string, forUser?: string) => string;
  onRestart?: () => Promise<void>;
}

Callback Handlers

Each command maps to an optional callback. If a callback is not provided, the command returns a default message. Implement callbacks to hook into your gateway's runtime state:

ownerCommands({
  ownerIds: { telegram: process.env.OWNER_TG_ID! },
  onStatus: () => {
    const stats = gateway.stats;
    return [
      `Uptime: ${formatDuration(stats.uptime)}`,
      `Sessions: ${stats.activeSessions} active / ${stats.totalSessions} total`,
      `Messages: ${stats.messagesToday} today`,
    ].join('\n');
  },
  onModel: (model, forUser) => {
    // update model configuration
    return `Switched to ${model}${forUser ? ` for ${forUser}` : ''}`;
  },
})

Security

Commands are only processed from users matching ownerIds for the current channel type
Non-owners sending /status or other commands see them passed through to the agent as regular messages
Unknown slash commands (e.g., /random) pass through to the agent

Owner Commands