aec-agent 1.0.1 → 1.0.4

package/dist/components/multi-agent-orchestration/agent/channel-manager/channel-manager.js

@@ -1,6 +1,1589 @@
+import { randomInt, randomUUID } from "node:crypto";
+import { ChannelError } from "../../../../kernel/errors/channel-error.js";
+import { SDKEventType } from "../../../event-handler/events.js";
+import { ChannelPrompts } from "./channel-prompts.js";
+import { parseCommand, splitMarkdown, splitMessage } from "./text.js";
+import { TurnView } from "./turn-view.js";
+import { helpLine } from "../command-manager/built-in-commands.js";
+/** Most channels one agent may have. */
+export const MAX_CHANNELS_PER_AGENT = 10;
+export const MAX_CHANNEL_NAME_LENGTH = 80;
+/** How long a pairing code stays valid. */
+export const PAIRING_TTL_MS = 60 * 60 * 1000;
+/** Most senders waiting for approval per channel; more are asked to try later. */
+export const MAX_PENDING_PAIRINGS = 3;
+/** "typing…" lasts about 5 seconds on most platforms, so it is renewed this often during a turn. */
+const TYPING_INTERVAL_MS = 4_000;
+/** Inbound message ids remembered to drop duplicates. */
+const MAX_SEEN_MESSAGES = 5_000;
+/** No 0/O or 1/I, so a code read aloud or retyped is not misread. */
+const PAIRING_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+const PAIRING_CODE_LENGTH = 8;
+const DEFAULT_ACCESS = {
+    dmPolicy: "pairing",
+    allowFrom: [],
+    groupPolicy: "disabled",
+    groups: [],
+    requireMention: true,
+};
+const DEFAULT_SETTINGS = {
+    streaming: true,
+    toolProgress: true,
+};
+/** Most models /model lists. */
+const MAX_LISTED_MODELS = 30;
+/** Commands answered at once, even while a turn of the chat is running. */
+// A-135: /yolo too, so YOLO mode can be switched off while a reply is running.
+// A-136: /permissions likewise, and the read-only /help, /context and /usage.
+const IMMEDIATE_COMMANDS = ["stop", "status", "whoami", "approve", "deny", "yolo", "permissions", "help", "context", "usage"];
+/**
+ * The commands shown in /help and published to the platform (adapter.setCommands),
+ * so the chat can suggest them. /start and /reset are answered too, as aliases.
+ */
+const CHANNEL_COMMANDS = [
+    { name: "new", description: "Start a new conversation" },
+    { name: "stop", description: "Stop the reply in progress" },
+    { name: "status", description: "Show this conversation" },
+    { name: "model", description: "Show or switch this conversation's model" },
+    { name: "approve", description: "Approve a pending tool call" },
+    { name: "deny", description: "Deny a pending tool call" },
+    { name: "yolo", description: "Run tools without asking (on/off)" },
+    { name: "whoami", description: "Show your id" },
+    { name: "sethome", description: "Send job results to this chat" },
+    { name: "help", description: "Show the commands" },
+];
+/**
+ * A-136: the commands the chat answers itself; every other one the agent has (its
+ * CommandManager: /compact, /resume, /permissions...) runs through agent.commands.
+ * /clear is the chat's /new (a chat's session is named after the chat).
+ */
+const CHAT_COMMANDS = new Set(["new", "reset", "clear", "start", "help", "stop", "approve", "deny", "whoami", "sethome"]);
+/** Platforms accept command names of lower-case letters, digits and "_" (Telegram: 1-32). */
+const PUBLISHABLE_NAME = /^[a-z0-9_]{1,32}$/;
+/** Most commands a platform takes (Telegram: 100). */
+const MAX_PUBLISHED_COMMANDS = 100;
 /**
  * communication gateway: slack, teams, telegram, ...
+ *
+ * One agent's chat-app channels (A-100), like the OpenClaw / Hermes Agent
+ * gateways: it connects each enabled channel through its platform's adapter
+ * and turns inbound messages into agent turns.
+ *
+ *  - Access: direct messages only (groups come later). dmPolicy "pairing"
+ *    gives an unknown sender a one-time code for the owner to approve.
+ *    -> Phase 2: group chats too, by groupPolicy ("disabled" by default), and
+ *    only when the bot is mentioned or replied to (requireMention).
+ *  - Sessions: one per chat, found again through the session's metadata
+ *    ({ source: "channel", channelId, chatKey }) after a restart. /new starts
+ *    a fresh one; the old one stays in the history.
+ *  - Turns of one chat run one after another; different chats run in parallel
+ *    (the agent's TurnGate and maxConcurrentTurns still apply).
+ *  - Commands: /start, /help, /new, /reset, /stop, /status, /whoami. Any other
+ *    "/..." text goes to the agent.
+ *    -> A-135: /yolo on|off switches the conversation's approval mode (owners only).
+ *  - Replies are plain text, split to the platform's message length.
+ *    -> Phase 2: Markdown rendered by the adapter when it can, streamed by
+ *    editing one message, with a tool-progress message (TurnView).
+ *  - Phase 2: approvals and clarify questions of a channel turn are asked in its
+ *    chat (ChannelPrompts) — interactionFor() is the channel side of the
+ *    agent's interaction router. /approve, /deny and /model are added.
  */
 export class ChannelManager {
+    deps;
+    live = new Map();
+    states = new Map();
+    /** channelId -> senders waiting for approval. */
+    pairings = new Map();
+    /** chat key -> the chat's current session. */
+    chatSessions = new Map();
+    /** chat key -> the last queued message of that chat. */
+    chatQueues = new Map();
+    /** chat key -> the running turn, for /stop. */
+    chatRuns = new Map();
+    /** channelId -> serialized connect/disconnect operations. */
+    ops = new Map();
+    seen = new Set();
+    /** sessionId -> the chat of the channel turn running in it (interaction routing). */
+    activeTurns = new Map();
+    prompts;
+    /** Scheduled-job results being sent (phase 3) — dispose() waits for them. */
+    deliveries = new Set();
+    unsubscribe;
+    generation = 0;
+    started = false;
+    disposed = false;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.prompts = new ChannelPrompts({
+            send: async (chat, message) => {
+                const live = this.live.get(chat.channelId);
+                if (!live)
+                    return undefined;
+                try {
+                    return await live.adapter.send(chat.target, message);
+                }
+                catch (err) {
+                    this.warn(chat.channelId, `could not ask in the chat: ${errorMessage(err)}`);
+                    return undefined;
+                }
+            },
+            edit: async (chat, ref, message) => {
+                const adapter = this.live.get(chat.channelId)?.adapter;
+                await adapter?.edit?.(ref, message).catch(() => undefined);
+            },
+            buttons: (channelId) => this.live.get(channelId)?.adapter.capabilities.buttons === true,
+            approvers: (channelId) => this.live.get(channelId)?.channel.access.allowFrom ?? [],
+            agentName: () => deps.getAgentName(),
+            ...(deps.promptTimeoutMs !== undefined
+                ? { timeoutMs: deps.promptTimeoutMs }
+                : {}),
+        });
+        // Phase 3: a prompt job that delivers to one of this agent's chats — the scheduler only
+        // publishes how the run ended; sending it is the channel side's job.
+        // A-70: a trigger run with a delivery — the trigger manager only publishes how it ended.
+        // Update (A-126): one event for both — job:run-finished, from the JobManager.
+        this.unsubscribe = [
+            deps.eventBus.on(SDKEventType.JobRunFinished, (event) => this.onJobRunFinished(event)),
+        ];
+    }
+    /**
+     * The InteractionHandler for a session while a channel turn runs in it: its
+     * approvals and questions are asked in the chat. Undefined for any other
+     * session (a web chat of the same session included) — the host's handler applies.
+     */
+    interactionFor(sessionId) {
+        const chat = this.activeTurns.get(sessionId);
+        if (!chat)
+            return undefined;
+        return {
+            askUser: (request) => this.prompts.askUser(chat, request),
+            requestApproval: (request) => this.prompts.requestApproval(chat, request),
+        };
+    }
+    /**
+     * A-100 phase 3: the delivery of a job scheduled from a session while a channel turn runs
+     * in it — back to that chat, as "home" when it is the channel's home chat (so a later
+     * /sethome moves it along). Undefined for any other session: a web chat schedules jobs
+     * that keep their results in their conversation.
+     * Update (A-127): deliveryOptions — that chat (here) and every running channel with a
+     * home chat (homes), so a job made outside the chat app (a web chat) still reports to
+     * the home chats, and one made in a chat can go to them all.
+     */
+    deliveryOptions(sessionId) {
+        const here = this.deliveryHere(sessionId);
+        return { ...(here ? { here } : {}), homes: this.homes() };
+    }
+    /** The chat of the channel turn running in the session; undefined when none does. */
+    deliveryHere(sessionId) {
+        const chat = this.activeTurns.get(sessionId);
+        if (!chat)
+            return undefined;
+        const home = this.live.get(chat.channelId)?.channel.home;
+        const atHome = home !== undefined &&
+            home.chatId === chat.target.chatId &&
+            (home.threadId ?? "") === (chat.target.threadId ?? "");
+        if (atHome)
+            return { channelId: chat.channelId, target: "home", when: "always" };
+        return {
+            channelId: chat.channelId,
+            target: chat.target.chatId,
+            ...(chat.target.threadId ? { threadId: chat.target.threadId } : {}),
+            when: "always",
+        };
+    }
+    /** The running channels that have a home chat, by name. */
+    homes() {
+        const homes = [];
+        for (const [id, live] of this.live) {
+            if (!live.channel.home || this.state(id).status === "failed")
+                continue;
+            homes.push({ channelId: id, name: live.channel.name, platform: live.channel.platform });
+        }
+        const order = (x, y) => (x < y ? -1 : x > y ? 1 : 0);
+        return homes.sort((a, b) => order(a.name, b.name) || order(a.channelId, b.channelId));
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    /**
+     * Connect this agent's stored, enabled channels. A channel that cannot connect
+     * shows "failed" in state(); it does not stop the others. Idempotent.
+     */
+    async start() {
+        if (this.started || this.disposed)
+            return;
+        this.started = true;
+        const channels = (await this.store().listByAgent(this.deps.agentId)).map(withDefaults);
+        await Promise.allSettled(channels
+            .filter((c) => c.enabled)
+            .map((c) => this.serial(c.id, () => this.connect(c))));
+    }
+    /** Disconnect every channel and stop the turns in progress. No new turns start after this. */
+    async dispose() {
+        this.disposed = true;
+        for (const off of this.unsubscribe)
+            off();
+        await Promise.allSettled([...this.deliveries]);
+        for (const controller of this.chatRuns.values())
+            controller.abort();
+        await Promise.allSettled([...this.live.keys()].map((id) => this.serial(id, () => this.disconnect(id))));
+        await Promise.allSettled([...this.chatQueues.values()]);
+    }
+    //#region Manage Channels
+    async list() {
+        return (await this.store().listByAgent(this.deps.agentId)).map(withDefaults);
+    }
+    async get(id) {
+        const channel = await this.store().get(id);
+        return channel && channel.agentId === this.deps.agentId
+            ? withDefaults(channel)
+            : null;
+    }
+    async create(input) {
+        if (this.disposed)
+            throw new ChannelError("The agent is disposed", "invalid_argument");
+        const platform = this.requirePlatform(input.platform);
+        const existing = await this.list();
+        if (existing.length >= MAX_CHANNELS_PER_AGENT) {
+            throw new ChannelError(`An agent can have at most ${MAX_CHANNELS_PER_AGENT} channels`, "limit_reached");
+        }
+        const nowIso = this.iso(this.now());
+        let channel = {
+            id: randomUUID(),
+            agentId: this.deps.agentId,
+            platform: platform.name,
+            name: input.name === undefined ? "" : validateName(input.name),
+            credentials: validateCredentials(platform, input.credentials),
+            access: validateAccess({ ...DEFAULT_ACCESS, ...input.access }),
+            settings: validateSettings({ ...DEFAULT_SETTINGS, ...input.settings }),
+            enabled: input.enabled ?? true,
+            createdAt: nowIso,
+            updatedAt: nowIso,
+        };
+        if (channel.enabled) {
+            // Connect first: a channel whose credentials the platform rejects is never saved.
+            const connected = await this.serial(channel.id, () => this.connect(channel));
+            if (!connected) {
+                const error = this.state(channel.id).error;
+                this.states.delete(channel.id);
+                throw new ChannelError(`Could not connect to ${platformLabel(platform)}: ${error ?? "unknown error"}`, "connect_failed", channel.id);
+            }
+            channel = { ...channel, account: connected };
+        }
+        if (!channel.name)
+            channel = {
+                ...channel,
+                name: channel.account?.displayName ?? platformLabel(platform),
+            };
+        await this.store().save(channel);
+        const live = this.live.get(channel.id);
+        if (live)
+            live.channel = channel;
+        return channel;
+    }
+    async update(id, patch) {
+        const current = await this.require(id);
+        const platform = this.requirePlatform(current.platform);
+        const credentials = patch.credentials
+            ? validateCredentials(platform, {
+                ...current.credentials,
+                ...patch.credentials,
+            })
+            : current.credentials;
+        const credentialsChanged = Object.keys(credentials).some((k) => credentials[k] !== current.credentials[k]);
+        let updated = {
+            ...current,
+            ...(patch.name !== undefined ? { name: validateName(patch.name) } : {}),
+            credentials,
+            access: patch.access
+                ? validateAccess({ ...current.access, ...patch.access })
+                : current.access,
+            settings: patch.settings
+                ? validateSettings({ ...current.settings, ...patch.settings })
+                : current.settings,
+            ...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
+            updatedAt: this.iso(this.now()),
+        };
+        if (patch.home === null)
+            delete updated.home;
+        else if (patch.home !== undefined)
+            updated.home = validateHome(patch.home, updated.updatedAt);
+        // A new bot token may be another bot: its account is read again on connect.
+        if (credentialsChanged)
+            delete updated.account;
+        await this.store().save(updated);
+        await this.serial(id, async () => {
+            const live = this.live.get(id);
+            if (!updated.enabled || this.disposed) {
+                if (live)
+                    await this.disconnect(id);
+                return;
+            }
+            if (live && !credentialsChanged) {
+                live.channel = updated;
+                return;
+            }
+            if (live)
+                await this.disconnect(id);
+            // A failed reconnect is reported through state(), not thrown: the change is saved.
+            await this.connect(updated);
+        });
+        updated = (await this.get(id)) ?? updated;
+        return updated;
+    }
+    async delete(id) {
+        await this.require(id);
+        await this.serial(id, () => this.disconnect(id));
+        this.pairings.delete(id);
+        for (const key of [...this.chatSessions.keys()]) {
+            if (key.startsWith(`${id}\u0000`))
+                this.chatSessions.delete(key);
+        }
+        this.states.delete(id);
+        await this.store().delete(id);
+    }
+    state(id) {
+        return this.states.get(id) ?? { status: "stopped", since: this.iso(0) };
+    }
+    async listPairings(id) {
+        await this.require(id);
+        return this.pendingPairings(id).map((p) => ({ ...p }));
+    }
+    async approvePairing(id, code) {
+        const channel = await this.require(id);
+        const pairing = this.takePairing(id, code);
+        const updated = channel.access.allowFrom.includes(pairing.senderId)
+            ? channel
+            : {
+                ...channel,
+                access: {
+                    ...channel.access,
+                    allowFrom: [...channel.access.allowFrom, pairing.senderId],
+                },
+                updatedAt: this.iso(this.now()),
+            };
+        if (updated !== channel)
+            await this.store().save(updated);
+        const live = this.live.get(id);
+        if (live) {
+            live.channel = updated;
+            await this.reply(live, { chatId: pairing.chatId }, `You're approved! Send a message to start talking to ${this.deps.getAgentName()}.`);
+        }
+        return updated;
+    }
+    async rejectPairing(id, code) {
+        await this.require(id);
+        this.takePairing(id, code);
+    }
+    async send(id, target, text) {
+        await this.require(id);
+        const live = this.live.get(id);
+        if (!live || this.state(id).status === "failed") {
+            throw new ChannelError("The channel is not connected", "not_running", id);
+        }
+        return this.sendText(live, target, text);
+    }
+    async handleWebhook(id, request) {
+        if (!(await this.get(id)))
+            return { status: 404, body: { error: "Channel not found" } };
+        const live = this.live.get(id);
+        if (!live || this.state(id).status === "failed")
+            return { status: 503, body: { error: "The channel is not connected" } };
+        if (!live.adapter.handleWebhook)
+            return {
+                status: 405,
+                body: { error: "This channel's platform takes no webhooks" },
+            };
+        return live.adapter.handleWebhook(request);
+    }
+    //#endregion
+    //#region Manage Channel's connection (connect, disconnect, ...)
+    /**
+     * Build the channel's adapter and connect it. Returns the bot account, or null
+     * when it failed (the reason is in state()). Runs inside serial(channel.id).
+     */
+    async connect(channel) {
+        const platform = this.deps.getPlatformHub()?.get(channel.platform);
+        if (!platform) {
+            this.setState(channel, "failed", `No "${channel.platform}" platform is registered on this host`);
+            return null;
+        }
+        const generation = ++this.generation;
+        let adapter;
+        try {
+            adapter = platform.create(channel);
+        }
+        catch (err) {
+            this.setState(channel, "failed", errorMessage(err));
+            return null;
+        }
+        const entry = { channel, platform, adapter, generation };
+        const current = () => this.live.get(channel.id)?.generation === generation;
+        this.live.set(channel.id, entry);
+        this.setState(channel, "connecting");
+        let account;
+        try {
+            account = await adapter.start({
+                message: (message) => {
+                    if (current())
+                        this.onInbound(entry, message);
+                },
+                button: (press) => {
+                    if (current())
+                        this.onButton(entry, press);
+                },
+                status: (status, error) => {
+                    if (!current())
+                        return;
+                    if (status === "failed") {
+                        // The adapter gave up and stopped itself.
+                        this.live.delete(channel.id);
+                        this.deps.getPlatformHub()?.release(channel.id);
+                        this.abortChats(channel.id);
+                    }
+                    this.setState(entry.channel, status, error);
+                },
+            });
+        }
+        catch (err) {
+            if (current())
+                this.live.delete(channel.id);
+            this.setState(channel, "failed", errorMessage(err));
+            return null;
+        }
+        if (!current())
+            return null;
+        const holder = this.deps
+            .getPlatformHub()
+            ?.claim(platform.name, account.id, channel.id);
+        if (holder !== undefined) {
+            this.live.delete(channel.id);
+            await adapter.stop().catch(() => undefined);
+            this.setState(channel, "failed", `This bot is already connected through another channel (${holder})`);
+            return null;
+        }
+        // Record the account on the stored channel (a new one may not be saved yet — create() saves it).
+        const storedRaw = await this.store().get(channel.id);
+        const stored = storedRaw ? withDefaults(storedRaw) : null;
+        if (stored && !sameAccount(stored.account, account)) {
+            const withAccount = { ...stored, account };
+            await this.store().save(withAccount);
+            entry.channel = withAccount;
+        }
+        else if (stored) {
+            entry.channel = stored;
+        }
+        if (current())
+            this.setState(entry.channel, "running");
+        if (current())
+            await this.publishCommands(entry);
+        return account;
+    }
+    /** Publish the chat commands to the platform, when the adapter can. A failure is logged, not thrown. */
+    async publishCommands(live) {
+        if (!live.adapter.setCommands)
+            return;
+        try {
+            await live.adapter.setCommands(this.botCommands());
+        }
+        catch (err) {
+            console.warn(`[channels] agent=${this.deps.agentId} channel=${live.channel.id} could not publish the commands: ${errorMessage(err)}`);
+        }
+    }
+    /** Stop the channel's adapter and its chats' turns. Runs inside serial(id). */
+    async disconnect(id) {
+        const live = this.live.get(id);
+        this.live.delete(id);
+        this.deps.getPlatformHub()?.release(id);
+        this.abortChats(id);
+        if (!live)
+            return;
+        try {
+            await live.adapter.stop();
+        }
+        catch (err) {
+            console.warn(`[channels] agent=${this.deps.agentId} channel=${id} did not stop cleanly:`, err);
+        }
+        this.setState(live.channel, "stopped");
+    }
+    /** Connect and disconnect calls of one channel run one at a time, in call order. */
+    serial(id, op) {
+        const prev = this.ops.get(id) ?? Promise.resolve();
+        const next = prev.catch(() => undefined).then(op);
+        this.ops.set(id, next);
+        void next
+            .finally(() => {
+            if (this.ops.get(id) === next)
+                this.ops.delete(id);
+        })
+            .catch(() => undefined);
+        return next;
+    }
+    setState(channel, status, error) {
+        const previous = this.states.get(channel.id);
+        if (previous?.status === status && previous.error === error)
+            return;
+        this.states.set(channel.id, {
+            status,
+            ...(error ? { error } : {}),
+            since: this.iso(this.now()),
+        });
+        if (status === "failed" || status === "retrying") {
+            console.warn(`[channels] agent=${this.deps.agentId} channel=${channel.id} (${channel.platform}) ${status}: ${error}`);
+        }
+        this.emit(SDKEventType.ChannelStatusChanged, "", {
+            agentId: this.deps.agentId,
+            channelId: channel.id,
+            platform: channel.platform,
+            status,
+            ...(error ? { error } : {}),
+        });
+    }
+    //#endregion
+    //#region Handle inbound messages
+    onInbound(live, message) {
+        if (this.disposed)
+            return;
+        const channel = live.channel;
+        if (this.isDuplicate(`${channel.id}\u0000${message.chat.id}\u0000${message.messageId}`))
+            return;
+        if (message.sender.isBot)
+            return;
+        // Only direct messages for now; group chats need mention rules first.
+        // -> Phase 2: group chats by groupPolicy and requireMention; broadcast channels stay ignored.
+        if (message.chat.type === "channel")
+            return;
+        const target = {
+            chatId: message.chat.id,
+            ...(message.chat.threadId ? { threadId: message.chat.threadId } : {}),
+        };
+        const command = parseCommand(message.text);
+        const username = channel.account?.username;
+        if (command?.target &&
+            username &&
+            command.target.toLowerCase() !== username.toLowerCase())
+            return;
+        if (message.chat.type === "group") {
+            // /whoami answers anywhere, so the owner can learn a group's id to allow it.
+            if (command?.name !== "whoami" &&
+                !this.groupAllowed(channel, message.chat.id))
+                return;
+            // A command counts as addressed to the bot (platforms deliver commands to it).
+            if (channel.access.requireMention &&
+                !command &&
+                !message.mentionsBot &&
+                !message.replyToBot)
+                return;
+        }
+        const handle = () => this.handleInbound(live, message, target, command).catch((err) => {
+            console.error(`[channels] agent=${this.deps.agentId} channel=${channel.id} could not handle a message:`, err);
+        });
+        const key = chatKey(channel.id, message);
+        // The answer to a question the running turn asked: it cannot wait in the queue behind that turn.
+        if (!command &&
+            this.mayTalk(channel, message) &&
+            this.prompts.hasQuestion(key)) {
+            if (this.prompts.answerText(key, message.sender, this.agentText(live, message, false)))
+                return;
+        }
+        if (command && IMMEDIATE_COMMANDS.includes(command.name)) {
+            // Answered at once, even while a turn of the chat is running.
+            void handle();
+            return;
+        }
+        // Everything else is handled in the chat's arrival order; other chats are not held up.
+        const prev = this.chatQueues.get(key) ?? Promise.resolve();
+        const next = prev.then(handle);
+        this.chatQueues.set(key, next);
+        void next.finally(() => {
+            if (this.chatQueues.get(key) === next)
+                this.chatQueues.delete(key);
+        });
+    }
+    async handleInbound(live, message, target, command) {
+        const channel = live.channel;
+        const label = platformLabel(live.platform);
+        // Answered for anyone, so a sender can tell the owner which id to allow.
+        if (command?.name === "whoami") {
+            const group = message.chat.type === "group"
+                ? `\nThis group's id is ${message.chat.id}.`
+                : "";
+            await this.reply(live, target, `Your ${label} id is ${message.sender.id}.${group}`);
+            return;
+        }
+        const access = channel.access;
+        // Group access was checked on arrival (groupAllowed); any member of an allowed group may talk.
+        if (message.chat.type === "dm" && access.dmPolicy === "disabled")
+            return;
+        if (!this.mayTalk(channel, message)) {
+            if (access.dmPolicy === "allowlist") {
+                await this.reply(live, target, `This bot is private. Ask its owner to add your ${label} id: ${message.sender.id}`);
+            }
+            else {
+                await this.requestPairing(live, message, target);
+            }
+            return;
+        }
+        const key = chatKey(channel.id, message);
+        // A-136: the agent's commands (its CommandManager) — all but the chat's own.
+        const commands = command && !CHAT_COMMANDS.has(command.name) ? this.deps.getCommands?.() : undefined;
+        const info = command && commands?.get(command.name, { client: "channel" });
+        if (command && commands && info) {
+            await this.runAgentCommand(live, message, target, key, command, commands, info);
+            return;
+        }
+        switch (command?.name) {
+            case "start":
+            case "help":
+                await this.reply(live, target, this.helpText());
+                return;
+            case "new":
+            case "reset":
+            // A-136: the CommandManager's /clear, done the chat's way (a session named after the chat).
+            case "clear": {
+                const session = await this.createSession(channel, message, live.platform);
+                this.chatSessions.set(key, session);
+                await this.reply(live, target, "Started a new conversation.");
+                return;
+            }
+            case "stop": {
+                const controller = this.chatRuns.get(key);
+                controller?.abort();
+                // Not running from now on, even before the turn has finished unwinding.
+                if (controller)
+                    this.chatRuns.delete(key);
+                await this.reply(live, target, controller ? "Stopped." : "Nothing is running.");
+                return;
+            }
+            case "status": {
+                await this.reply(live, target, await this.statusText(channel, message, key));
+                return;
+            }
+            case "approve":
+            case "deny": {
+                const answer = this.prompts.answerCommand(key, message.sender, command.name === "approve", command.args);
+                if (answer.handled && answer.notice)
+                    await this.reply(live, target, answer.notice);
+                return;
+            }
+            case "model":
+                await this.reply(live, target, await this.modelCommand(live, message, key, command.args));
+                return;
+            case "sethome":
+                await this.reply(live, target, await this.setHome(live, message));
+                return;
+            case "yolo":
+                await this.reply(live, target, await this.yoloCommand(live, message, key, command.args));
+                return;
+        }
+        if (!message.text.trim()) {
+            await this.reply(live, target, "I can only read text messages for now.");
+            return;
+        }
+        // handleInbound runs in the chat's queue here, so the turn runs in arrival order.
+        await this.runTurn(channel.id, message, target, key);
+    }
+    async runTurn(channelId, message, target, key, 
+    /** A-136: a command's prompt (/review, /init) to send instead of the message's text. */
+    prompt) {
+        // Read again: the channel may have been stopped or edited while this message waited.
+        const live = this.live.get(channelId);
+        if (!live || this.disposed)
+            return;
+        const channel = live.channel;
+        if (!this.mayTalk(channel, message))
+            return;
+        if (message.chat.type === "group" &&
+            !this.groupAllowed(channel, message.chat.id))
+            return;
+        const sessionId = await this.resolveSession(channel, message, live.platform, key);
+        const controller = new AbortController();
+        this.chatRuns.set(key, controller);
+        this.emit(SDKEventType.ChannelMessageReceived, sessionId, {
+            agentId: this.deps.agentId,
+            channelId,
+            platform: channel.platform,
+            chatId: message.chat.id,
+            senderId: message.sender.id,
+            messageId: message.messageId,
+        });
+        const typing = this.keepTyping(live, target);
+        const view = new TurnView({
+            adapter: live.adapter,
+            target,
+            settings: channel.settings,
+            onError: (err) => this.warn(channelId, `could not update the chat: ${errorMessage(err)}`),
+        });
+        // Approvals and questions of this turn are asked in the chat (interactionFor).
+        this.activeTurns.set(sessionId, {
+            channelId,
+            key,
+            target,
+            chatType: message.chat.type,
+            initiator: message.sender,
+        });
+        let output;
+        try {
+            const result = await this.deps.getRunner()({
+                agentId: this.deps.agentId,
+                channel,
+                sessionId,
+                message,
+                text: prompt?.text ?? this.agentText(live, message, true),
+                signal: controller.signal,
+                ...(prompt?.readOnly ? { readOnly: true } : {}),
+                onChunk: (chunk) => view.chunk(chunk),
+            });
+            if (result.aborted || controller.signal.aborted) {
+                await view.abandon();
+                return;
+            }
+            output = result.output?.trim() ?? "";
+            if (!output && result.stopReason)
+                output = `(The agent stopped without a reply: ${result.stopReason}.)`;
+        }
+        catch (err) {
+            await view.abandon();
+            if (controller.signal.aborted)
+                return;
+            const error = errorMessage(err);
+            console.error(`[channels] agent=${this.deps.agentId} channel=${channelId} chat=${message.chat.id} turn failed: ${error}`);
+            this.emit(SDKEventType.ChannelFailed, sessionId, {
+                agentId: this.deps.agentId,
+                channelId,
+                platform: channel.platform,
+                chatId: message.chat.id,
+                error,
+            });
+            await this.reply(live, target, `Sorry, something went wrong: ${error}`);
+            return;
+        }
+        finally {
+            typing();
+            if (this.chatRuns.get(key) === controller)
+                this.chatRuns.delete(key);
+            if (this.activeTurns.get(sessionId)?.key === key)
+                this.activeTurns.delete(sessionId);
+            this.prompts.cancelChat(key, "the turn ended before anyone answered");
+        }
+        if (!output) {
+            await view.abandon();
+            return;
+        }
+        try {
+            const refs = await view.finish(output);
+            this.emit(SDKEventType.ChannelMessageSent, sessionId, {
+                agentId: this.deps.agentId,
+                channelId,
+                platform: channel.platform,
+                chatId: message.chat.id,
+                parts: refs.length,
+            });
+        }
+        catch (err) {
+            const error = errorMessage(err);
+            console.error(`[channels] agent=${this.deps.agentId} channel=${channelId} chat=${message.chat.id} reply failed: ${error}`);
+            this.emit(SDKEventType.ChannelFailed, sessionId, {
+                agentId: this.deps.agentId,
+                channelId,
+                platform: channel.platform,
+                chatId: message.chat.id,
+                error,
+            });
+        }
+    }
+    /** Shows "typing…" until the returned function is called. */
+    keepTyping(live, target) {
+        const sendTyping = live.adapter.sendTyping?.bind(live.adapter);
+        if (!sendTyping)
+            return () => undefined;
+        const tick = () => {
+            void sendTyping(target).catch(() => undefined);
+        };
+        tick();
+        const timer = setInterval(tick, TYPING_INTERVAL_MS);
+        timer.unref?.();
+        return () => clearInterval(timer);
+    }
+    //#endregion
+    //#region Sessions
+    /** The chat's current session: cached, else the newest one stored for it, else a new one. */
+    async resolveSession(channel, message, platform, key) {
+        const sessions = this.deps.getSessions();
+        const cached = this.chatSessions.get(key);
+        if (cached && (await sessions.get(cached)))
+            return cached;
+        const found = await this.findSession(channel, chatKeyOf(message));
+        const id = found ?? (await this.createSession(channel, message, platform));
+        this.chatSessions.set(key, id);
+        return id;
+    }
+    /** A-136: the chat's current session when it has one (cached, else stored) — never a new one. */
+    async existingSession(channel, message, key) {
+        const cached = this.chatSessions.get(key);
+        if (cached && (await this.deps.getSessions().get(cached)))
+            return cached;
+        return this.findSession(channel, chatKeyOf(message));
+    }
+    /**
+     * Phase 3: the current session of a chat the agent posts to unprompted (a job's result):
+     * the one its messages use, else a new one, so the chat's next message continues it.
+     */
+    async chatSession(channel, platform, target) {
+        const sessions = this.deps.getSessions();
+        const chatKey = target.threadId
+            ? `${target.chatId}:${target.threadId}`
+            : target.chatId;
+        const key = `${channel.id}\u0000${chatKey}`;
+        const cached = this.chatSessions.get(key);
+        if (cached && (await sessions.get(cached)))
+            return cached;
+        let id = await this.findSession(channel, chatKey);
+        if (!id) {
+            const home = isHomeTarget(channel.home, target) ? channel.home : undefined;
+            id = (await sessions.create({
+                agentId: this.deps.agentId,
+                source: "channel",
+                channelId: channel.id,
+                platform: channel.platform,
+                chatKey,
+                chatId: target.chatId,
+                title: `${home?.title ?? target.chatId} · ${platformLabel(platform)}`,
+            })).id;
+        }
+        this.chatSessions.set(key, id);
+        return id;
+    }
+    async findSession(channel, chatKey) {
+        const stored = await this.deps.getSessions().list({
+            metadata: {
+                agentId: this.deps.agentId,
+                source: "channel",
+                channelId: channel.id,
+                chatKey,
+            },
+        });
+        // A-136: the most recently used one (was: the newest created), so a conversation /resume
+        // went back to stays the chat's after a restart.
+        let newest;
+        for (const session of stored) {
+            if (!newest || session.updatedAt > newest.updatedAt)
+                newest = session;
+        }
+        return newest?.id;
+    }
+    async createSession(channel, message, platform) {
+        const sender = message.sender.name ??
+            (message.sender.username
+                ? `@${message.sender.username}`
+                : message.sender.id);
+        const session = await this.deps.getSessions().create({
+            // Same ownership key the host routes use, so the session lists and opens like any other.
+            agentId: this.deps.agentId,
+            source: "channel",
+            channelId: channel.id,
+            platform: channel.platform,
+            chatKey: chatKeyOf(message),
+            chatId: message.chat.id,
+            chatType: message.chat.type,
+            senderId: message.sender.id,
+            ...(message.sender.name ? { senderName: message.sender.name } : {}),
+            // A group's session is shared by its members, so it is named after the group.
+            title: `${message.chat.type === "group" && message.chat.title ? message.chat.title : sender} · ${platformLabel(platform)}`,
+        });
+        return session.id;
+    }
+    //#endregion
+    //#region Pairing
+    async requestPairing(live, message, target) {
+        const channel = live.channel;
+        const pending = this.pendingPairings(channel.id);
+        let pairing = pending.find((p) => p.senderId === message.sender.id);
+        if (!pairing) {
+            if (pending.length >= MAX_PENDING_PAIRINGS) {
+                await this.reply(live, target, "This bot is private, and too many people are waiting for approval right now. Please try again later.");
+                return;
+            }
+            const now = this.now();
+            pairing = {
+                code: pairingCode(),
+                channelId: channel.id,
+                senderId: message.sender.id,
+                ...(message.sender.name ? { senderName: message.sender.name } : {}),
+                chatId: message.chat.id,
+                requestedAt: this.iso(now),
+                expiresAt: this.iso(now + PAIRING_TTL_MS),
+            };
+            this.pairings.set(channel.id, [...pending, pairing]);
+            this.emit(SDKEventType.ChannelPairingRequested, "", {
+                agentId: this.deps.agentId,
+                channelId: channel.id,
+                platform: channel.platform,
+                code: pairing.code,
+                senderId: pairing.senderId,
+                ...(pairing.senderName ? { senderName: pairing.senderName } : {}),
+                expiresAt: pairing.expiresAt,
+            });
+        }
+        await this.reply(live, target, `This bot is private. Your pairing code is ${pairing.code} — ask its owner to approve it. The code expires in an hour.`);
+    }
+    /** The channel's unexpired pairings (expired ones are dropped). */
+    pendingPairings(channelId) {
+        const nowIso = this.iso(this.now());
+        const pending = (this.pairings.get(channelId) ?? []).filter((p) => p.expiresAt > nowIso);
+        if (pending.length)
+            this.pairings.set(channelId, pending);
+        else
+            this.pairings.delete(channelId);
+        return pending;
+    }
+    takePairing(channelId, code) {
+        const wanted = code.trim().toUpperCase();
+        const pending = this.pendingPairings(channelId);
+        const pairing = pending.find((p) => p.code === wanted);
+        if (!pairing)
+            throw new ChannelError(`No pending pairing with code "${code}"`, "not_found", channelId);
+        const rest = pending.filter((p) => p !== pairing);
+        if (rest.length)
+            this.pairings.set(channelId, rest);
+        else
+            this.pairings.delete(channelId);
+        return pairing;
+    }
+    //#endregion
+    //#region Home chat and scheduled-job delivery (phase 3)
+    /**
+     * /sethome — make this chat the channel's home, where jobs delivering to "home" post.
+     * Only the bot's owners (allowFrom) may: in an open DM or group anyone can talk, and
+     * the home chat receives what the agent produces unattended.
+     */
+    async setHome(live, message) {
+        if (!live.channel.access.allowFrom.includes(message.sender.id))
+            return "Only the bot's owners (the senders on its allow list) can choose the home chat.";
+        // Re-read so a change saved since this channel connected is not lost.
+        const stored = await this.require(live.channel.id);
+        const nowIso = this.iso(this.now());
+        const sender = message.sender.name ??
+            (message.sender.username
+                ? `@${message.sender.username}`
+                : message.sender.id);
+        const title = message.chat.type === "dm" ? sender : (message.chat.title ?? sender);
+        const home = {
+            chatId: message.chat.id,
+            ...(message.chat.threadId ? { threadId: message.chat.threadId } : {}),
+            title,
+            setBy: message.sender.id,
+            setAt: nowIso,
+        };
+        const updated = { ...stored, home, updatedAt: nowIso };
+        await this.store().save(updated);
+        const current = this.live.get(updated.id);
+        if (current)
+            current.channel = updated;
+        return `This is now the home chat of ${updated.name}: jobs that deliver to "home" post their results here.`;
+    }
+    /**
+     * A prompt job of this agent ended; send its result when its delivery asks for it.
+     * A-70: a trigger run of this agent ended; send its result when the trigger's delivery asks
+     * for it. Sent with the run's session, so a delivery failure (channel:error) carries the
+     * run's depth and can't wake another trigger by default.
+     * Update (A-126): one handler for every job run (schedule, event or webhook).
+     */
+    onJobRunFinished(event) {
+        const payload = event.payload;
+        if (this.disposed || payload.agentId !== this.deps.agentId)
+            return;
+        // Update (A-127): each delivery on its own — its own "when", and one chat that fails
+        // does not stop the others.
+        for (const delivery of payload.deliveries ?? []) {
+            const result = jobResult(payload, delivery);
+            if (!result)
+                continue;
+            this.track(delivery, { name: payload.jobName ?? "job", id: payload.jobId }, event.sessionId, result);
+        }
+    }
+    /** Start one delivery; dispose waits for the ones still sending. */
+    track(delivery, origin, sessionId, result) {
+        const done = this.deliver(delivery, origin, sessionId, result).catch((err) => this.warn(delivery.channelId, `could not deliver ${originLabel(origin)}: ${errorMessage(err)}`));
+        this.deliveries.add(done);
+        void done.finally(() => this.deliveries.delete(done));
+    }
+    /** Send one job (or trigger run) result. Failures are logged and published as channel:error, never thrown. */
+    async deliver(delivery, origin, sessionId, result) {
+        const channel = await this.get(delivery.channelId);
+        const fail = (error, chatId) => {
+            this.warn(delivery.channelId, `could not deliver ${originLabel(origin)}: ${error}`);
+            this.emit(SDKEventType.ChannelFailed, sessionId, {
+                agentId: this.deps.agentId,
+                channelId: delivery.channelId,
+                platform: channel?.platform ?? "",
+                ...(chatId ? { chatId } : {}),
+                error,
+                ...originIds(origin),
+            });
+        };
+        if (!channel) {
+            fail("this agent has no such channel");
+            return;
+        }
+        let target;
+        if (delivery.target === "home") {
+            if (!channel.home) {
+                fail(`the channel "${channel.name}" has no home chat — send /sethome in the chat that should get the results`);
+                return;
+            }
+            target = {
+                chatId: channel.home.chatId,
+                ...(channel.home.threadId ? { threadId: channel.home.threadId } : {}),
+            };
+        }
+        else {
+            target = {
+                chatId: delivery.target,
+                ...(delivery.threadId ? { threadId: delivery.threadId } : {}),
+            };
+        }
+        // A channel still connecting (a catch-up run right after a restart) is waited for.
+        await this.ops.get(channel.id)?.catch(() => undefined);
+        const live = this.live.get(channel.id);
+        if (!live || this.state(channel.id).status === "failed") {
+            fail("the channel is not connected", target.chatId);
+            return;
+        }
+        try {
+            const refs = await this.sendResult(live, target, origin, result);
+            this.emit(SDKEventType.ChannelMessageSent, sessionId, {
+                agentId: this.deps.agentId,
+                channelId: channel.id,
+                platform: channel.platform,
+                chatId: target.chatId,
+                parts: refs.length,
+                ...originIds(origin),
+            });
+        }
+        catch (err) {
+            fail(errorMessage(err), target.chatId);
+            return;
+        }
+        await this.recordResult(channel, live.platform, target, origin, result);
+    }
+    /**
+     * Add a delivered result to the chat's conversation as the agent's message, so the
+     * chat's next turn knows what was posted. The job's own session keeps the run as before.
+     * A failure is logged: the result was delivered either way.
+     */
+    async recordResult(channel, platform, target, origin, result) {
+        if (!this.deps.appendMessage)
+            return;
+        try {
+            const sessionId = await this.chatSession(channel, platform, target);
+            await this.deps.appendMessage(sessionId, {
+                role: "assistant",
+                content: resultText(origin, result, true),
+            });
+        }
+        catch (err) {
+            this.warn(channel.id, `could not add ${originLabel(origin)} to the chat's conversation: ${errorMessage(err)}`);
+        }
+    }
+    /** The job's result as chat messages: Markdown when the adapter renders it, split to its length. */
+    async sendResult(live, target, origin, result) {
+        const { maxMessageLength, markdown } = live.adapter.capabilities;
+        const text = resultText(origin, result, markdown === true);
+        const parts = markdown
+            ? splitMarkdown(text, maxMessageLength)
+            : splitMessage(text, maxMessageLength);
+        const refs = [];
+        for (const part of parts) {
+            refs.push(await live.adapter.send(target, markdown ? { text: part, format: "markdown" } : { text: part }));
+        }
+        return refs;
+    }
+    //#endregion
+    //#region Helpers
+    async sendText(live, target, text) {
+        const refs = [];
+        for (const part of splitMessage(text, live.adapter.capabilities.maxMessageLength)) {
+            refs.push(await live.adapter.send(target, { text: part }));
+        }
+        return refs;
+    }
+    /** Send a short notice; a failure is logged, not thrown. */
+    async reply(live, target, text) {
+        try {
+            await this.sendText(live, target, text);
+        }
+        catch (err) {
+            console.warn(`[channels] agent=${this.deps.agentId} channel=${live.channel.id} could not reply: ${errorMessage(err)}`);
+        }
+    }
+    helpText() {
+        return [
+            `Hi! Send a message to talk to ${this.deps.getAgentName()}.`,
+            "",
+            ...CHANNEL_COMMANDS.filter((c) => c.name !== "help").map((c) => `/${c.name} — ${c.description.charAt(0).toLowerCase()}${c.description.slice(1)}`),
+            // A-136: and the agent's commands that work in a chat.
+            ...this.agentCommands().map(helpLine),
+        ].join("\n");
+    }
+    /** A-136: the agent's commands a chat can run (not the chat's own, none needing a client capability). */
+    agentCommands() {
+        return (this.deps.getCommands?.()?.list({ client: "channel" }) ?? []).filter((c) => c.available && !CHAT_COMMANDS.has(c.name));
+    }
+    /** The commands published to the platform: the chat's own, then the agent's (the names a platform takes). */
+    botCommands() {
+        const names = new Set(CHANNEL_COMMANDS.map((c) => c.name));
+        const extra = this.agentCommands()
+            .filter((c) => PUBLISHABLE_NAME.test(c.name) && !names.has(c.name))
+            .map((c) => ({ name: c.name, description: c.description }));
+        return [...CHANNEL_COMMANDS, ...extra].slice(0, MAX_PUBLISHED_COMMANDS);
+    }
+    /**
+     * A-136: run one of the agent's commands in the chat. Privileged ones that change something
+     * (/permissions yolo) are for the bot's owners only — they typed it, which counts as the
+     * confirmation the web app asks for. The result's action is carried out here: a session
+     * picked by /resume becomes the chat's, a prompt (/plan <prompt>, /init, /review) runs as a turn.
+     */
+    async runAgentCommand(live, message, target, key, command, commands, info) {
+        const channel = live.channel;
+        const owner = channel.access.allowFrom.includes(message.sender.id);
+        if (info.safety === "privileged" && command.args && !owner) {
+            await this.reply(live, target, info.name === "yolo"
+                ? "Only the bot's owners (the senders on its allow list) can switch YOLO mode."
+                : `Only the bot's owners (the senders on its allow list) can use /${info.name} to change things.`);
+            return;
+        }
+        // A read-only command does not start a conversation the chat does not have yet.
+        let sessionId;
+        if (info.safety === "read-only") {
+            const existing = await this.existingSession(channel, message, key);
+            if (!existing) {
+                await this.reply(live, target, info.name === "status" ? await this.statusText(channel, message, key) : "No conversation yet.");
+                return;
+            }
+            sessionId = existing;
+        }
+        else {
+            sessionId = await this.resolveSession(channel, message, live.platform, key);
+        }
+        const result = await commands.run(`/${info.name}${command.args ? ` ${command.args}` : ""}`, {
+            sessionId,
+            client: "channel",
+            confirmed: true,
+            sessionScope: { agentId: this.deps.agentId, source: "channel", channelId: channel.id, chatKey: chatKeyOf(message) },
+        });
+        let text = result.text;
+        if (info.name === "status" && !result.error) {
+            const extra = [];
+            if (isHome(channel.home, message))
+                extra.push("This is the home chat: job results are sent here.");
+            if (this.chatRuns.has(key))
+                extra.push("A reply is in progress (/stop to stop it).");
+            if (extra.length)
+                text = `${text}\n${extra.join("\n")}`;
+        }
+        await this.reply(live, target, text);
+        const action = result.action;
+        if (action?.type === "open-session")
+            this.chatSessions.set(key, action.sessionId);
+        else if (action?.type === "send-prompt") {
+            await this.runTurn(channel.id, message, target, key, {
+                text: action.prompt,
+                ...(action.readOnly ? { readOnly: true } : {}),
+            });
+        }
+    }
+    /** A button press: an approval or a question's choice. */
+    onButton(live, press) {
+        if (this.disposed || press.sender.isBot)
+            return;
+        const channel = live.channel;
+        const message = {
+            messageId: press.messageId,
+            chat: press.chat,
+            sender: press.sender,
+            text: "",
+        };
+        if (press.chat.type === "group"
+            ? !this.groupAllowed(channel, press.chat.id)
+            : !this.mayTalk(channel, message))
+            return;
+        const answer = this.prompts.answerButton(chatKey(channel.id, message), press.sender, press.data);
+        if (answer.handled && answer.notice) {
+            void this.reply(live, {
+                chatId: press.chat.id,
+                ...(press.chat.threadId ? { threadId: press.chat.threadId } : {}),
+            }, answer.notice);
+        }
+    }
+    /**
+     * Whether the sender may talk to the agent in this chat: in a direct message by
+     * dmPolicy and allowFrom; in a group, any member once the group is allowed.
+     */
+    mayTalk(channel, message) {
+        if (message.chat.type === "group")
+            return this.groupAllowed(channel, message.chat.id);
+        const access = channel.access;
+        if (access.dmPolicy === "disabled")
+            return false;
+        return (access.dmPolicy === "open" || access.allowFrom.includes(message.sender.id));
+    }
+    groupAllowed(channel, chatId) {
+        const access = channel.access;
+        return (access.groupPolicy === "open" ||
+            (access.groupPolicy === "allowlist" && access.groups.includes(chatId)));
+    }
+    /**
+     * The message as the agent reads it: the bot's @-mention removed, and in a group
+     * (`withSender`) prefixed with who wrote it, since several people share the session.
+     */
+    agentText(live, message, withSender) {
+        let text = message.text;
+        const username = live.channel.account?.username;
+        if (username)
+            text = text
+                .replace(new RegExp(`@${escapeRegExp(username)}\\b`, "gi"), " ")
+                .replace(/[ \t]{2,}/g, " ");
+        text = text.trim();
+        if (!withSender || message.chat.type !== "group")
+            return text;
+        const sender = message.sender.name ??
+            (message.sender.username
+                ? `@${message.sender.username}`
+                : message.sender.id);
+        return `[${sender}]: ${text}`;
+    }
+    /** /model — show the conversation's model, or switch it ("/model default" goes back to the agent's). */
+    async modelCommand(live, message, key, args) {
+        const sessions = this.deps.getSessions();
+        const sessionId = await this.resolveSession(live.channel, message, live.platform, key);
+        const session = await sessions.get(sessionId);
+        if (!session)
+            return "No conversation yet.";
+        const agentModel = this.deps.getDefaultModel?.();
+        let models;
+        try {
+            models = await this.deps.listModels?.();
+        }
+        catch {
+            models = undefined;
+        }
+        const wanted = args.trim();
+        if (!wanted) {
+            const lines = [
+                session.llmModel
+                    ? `Model: ${session.llmModel}`
+                    : `Model: ${agentModel ?? "the provider's default"} (the agent's default)`,
+            ];
+            if (models?.length) {
+                lines.push("", "Available:", ...models.slice(0, MAX_LISTED_MODELS).map((m) => `• ${m}`));
+                if (models.length > MAX_LISTED_MODELS)
+                    lines.push(`… and ${models.length - MAX_LISTED_MODELS} more`);
+            }
+            lines.push("", "Switch with /model <name>; /model default goes back to the agent's model.");
+            return lines.join("\n");
+        }
+        if (wanted.toLowerCase() === "default") {
+            delete session.llmModel;
+        }
+        else {
+            const match = models?.find((m) => m.toLowerCase() === wanted.toLowerCase());
+            if (models?.length && !match)
+                return `There is no model "${wanted}". Send /model to see the list.`;
+            session.llmModel = match ?? wanted;
+        }
+        session.updatedAt = this.now();
+        await sessions.update(session);
+        return session.llmModel
+            ? `This conversation now uses ${session.llmModel}.`
+            : `This conversation now uses the agent's model${agentModel ? ` (${agentModel})` : ""}.`;
+    }
+    /**
+     * A-135: /yolo [on|off] — show or switch the conversation's approval mode. In YOLO mode
+     * the agent runs tools that need approval without asking here. Only the bot's owners
+     * (allowFrom) may switch it: in an open DM or group anyone can talk.
+     */
+    async yoloCommand(live, message, key, args) {
+        const { getApprovalMode, setApprovalMode } = this.deps;
+        if (!getApprovalMode || !setApprovalMode)
+            return "YOLO mode is not available for this agent.";
+        const sessionId = await this.resolveSession(live.channel, message, live.platform, key);
+        const wanted = args.trim().toLowerCase();
+        if (!wanted) {
+            return (await getApprovalMode(sessionId)) === "yolo"
+                ? "YOLO mode is on: tools run without asking. Send /yolo off to ask again."
+                : "YOLO mode is off: tools that need approval ask here first. Send /yolo on to run them without asking.";
+        }
+        if (wanted !== "on" && wanted !== "off")
+            return "Send /yolo on or /yolo off.";
+        if (!live.channel.access.allowFrom.includes(message.sender.id))
+            return "Only the bot's owners (the senders on its allow list) can switch YOLO mode.";
+        await setApprovalMode(sessionId, wanted === "on" ? "yolo" : "ask");
+        return wanted === "on"
+            ? "YOLO mode is on: tools in this conversation run without asking, until /yolo off."
+            : "YOLO mode is off: tools that need approval ask here first.";
+    }
+    warn(channelId, text) {
+        console.warn(`[channels] agent=${this.deps.agentId} channel=${channelId} ${text}`);
+    }
+    async statusText(channel, message, key) {
+        const sessions = this.deps.getSessions();
+        const cached = this.chatSessions.get(key);
+        const sessionId = (cached && (await sessions.get(cached)) ? cached : undefined) ??
+            (await this.findSession(channel, chatKeyOf(message)));
+        const session = sessionId ? await sessions.get(sessionId) : null;
+        const lines = [`Agent: ${this.deps.getAgentName()}`];
+        lines.push(session
+            ? `Conversation started ${this.iso(session.createdAt).slice(0, 16).replace("T", " ")} UTC`
+            : "No conversation yet.");
+        const model = session?.llmModel ?? this.deps.getDefaultModel?.();
+        if (model)
+            lines.push(`Model: ${model}`);
+        if (session && (await this.deps.getApprovalMode?.(session.id)) === "yolo")
+            lines.push("YOLO mode: tools run without asking (/yolo off to stop).");
+        if (isHome(channel.home, message))
+            lines.push("This is the home chat: job results are sent here.");
+        if (this.chatRuns.has(key))
+            lines.push("A reply is in progress (/stop to stop it).");
+        return lines.join("\n");
+    }
+    abortChats(channelId) {
+        for (const [key, controller] of this.chatRuns) {
+            if (key.startsWith(`${channelId}\u0000`))
+                controller.abort();
+        }
+        this.prompts.cancelPrefix(`${channelId}\u0000`, "the channel stopped");
+    }
+    isDuplicate(key) {
+        if (this.seen.has(key))
+            return true;
+        this.seen.add(key);
+        if (this.seen.size > MAX_SEEN_MESSAGES) {
+            const oldest = this.seen.values().next().value;
+            if (oldest !== undefined)
+                this.seen.delete(oldest);
+        }
+        return false;
+    }
+    requirePlatform(name) {
+        const platform = this.deps.getPlatformHub()?.get(name);
+        if (!platform)
+            throw new ChannelError(`No "${name}" channel platform is registered on this host`, "unknown_platform");
+        return platform;
+    }
+    async require(id) {
+        const channel = await this.get(id);
+        if (!channel)
+            throw new ChannelError(`No channel "${id}" for this agent`, "not_found", id);
+        return channel;
+    }
+    emit(type, sessionId, payload) {
+        this.deps.eventBus.emit({ type, sessionId, payload });
+    }
+    store() {
+        return this.deps.getStore();
+    }
+    iso(ms) {
+        return new Date(ms).toISOString();
+    }
+}
+function originLabel(origin) {
+    return `job "${origin.name}"`;
+}
+/** The jobId field of channel events about a delivery. */
+function originIds(origin) {
+    return { jobId: origin.id };
+}
+/**
+ * The result to deliver for a finished trigger run, or undefined when there is nothing to send.
+ * Update (A-126): for any job run; a silent run ([[SILENT]]) has nothing to send.
+ */
+function jobResult(payload, delivery) {
+    // Suppressed (resolved, stale, disabled) and stopped runs did nothing worth reporting.
+    if (payload.status === "suppressed" || payload.status === "stopped")
+        return undefined;
+    if (payload.silent)
+        return undefined;
+    if (payload.status === "failed" || payload.status === "blocked") {
+        // A-103: a run that paused its job is always reported, so the job never goes quiet unseen.
+        if (delivery.when === "on-output" && !payload.paused)
+            return undefined;
+        const paused = payload.paused ? { paused: true } : {};
+        return payload.status === "failed"
+            ? { kind: "failed", error: payload.error ?? "the run failed", ...paused }
+            : {
+                kind: "blocked",
+                reason: payload.reason ?? "the run was blocked",
+                // What the agent said about it (e.g. which approval it needed).
+                ...(payload.output?.trim() ? { text: payload.output.trim() } : {}),
+                ...paused,
+            };
+    }
+    if (delivery.when === "on-failure")
+        return undefined;
+    const text = payload.output?.trim() ?? "";
+    if (text)
+        return { kind: "reply", text };
+    return delivery.when === "always" ? { kind: "empty" } : undefined;
+}
+/** What the chat sees for a job's (or trigger's) result; `markdown` bolds its name. */
+function resultText(origin, result, markdown) {
+    const name = origin.name;
+    const what = "Job";
+    if (result.kind === "reply")
+        return `${markdown ? `**${name}**` : name}\n\n${result.text}`;
+    if (result.kind === "empty")
+        return `${what} "${name}" finished without a reply.`;
+    // A-103: the job turned itself off after this run.
+    const pausedNote = "paused" in result && result.paused
+        ? `
+
+The job is now paused after too many failed runs in a row. Turn it back on on the agent's Jobs page once it's fixed.`
+        : "";
+    if (result.kind === "blocked")
+        return `${what} "${name}" stopped without finishing: ${result.reason}${result.text ? `
+
+${result.text}` : ""}${pausedNote}`;
+    return `${what} "${name}" failed: ${result.error}${pausedNote}`;
+}
+function isHomeTarget(home, target) {
+    return (home !== undefined &&
+        home.chatId === target.chatId &&
+        (home.threadId ?? "") === (target.threadId ?? ""));
+}
+function isHome(home, message) {
+    return (home !== undefined &&
+        home.chatId === message.chat.id &&
+        (home.threadId ?? "") === (message.chat.threadId ?? ""));
+}
+function validateHome(value, setAt) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new ChannelError('"home" must be { chatId, threadId?, title? } or null', "invalid_argument");
+    const v = value;
+    const field = (key) => {
+        const raw = v[key];
+        if (raw === undefined)
+            return undefined;
+        if (typeof raw !== "string")
+            throw new ChannelError(`"home.${key}" must be a string`, "invalid_argument");
+        return raw.trim() || undefined;
+    };
+    const chatId = field("chatId");
+    if (!chatId)
+        throw new ChannelError('"home.chatId" is required', "invalid_argument");
+    const threadId = field("threadId");
+    const title = field("title");
+    return {
+        chatId,
+        ...(threadId ? { threadId } : {}),
+        ...(title ? { title } : {}),
+        setAt,
+    };
+}
+/** A chat inside its channel: the chat id, plus the thread when there is one. */
+function chatKeyOf(message) {
+    return message.chat.threadId
+        ? `${message.chat.id}:${message.chat.threadId}`
+        : message.chat.id;
+}
+function chatKey(channelId, message) {
+    return `${channelId}\u0000${chatKeyOf(message)}`;
+}
+function platformLabel(platform) {
+    return platform.displayName ?? platform.name;
+}
+function sameAccount(a, b) {
+    return (a?.id === b?.id &&
+        a?.username === b?.username &&
+        a?.displayName === b?.displayName);
+}
+function pairingCode() {
+    let code = "";
+    for (let i = 0; i < PAIRING_CODE_LENGTH; i++)
+        code += PAIRING_ALPHABET[randomInt(PAIRING_ALPHABET.length)];
+    return code;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function validateName(value) {
+    const name = typeof value === "string" ? value.trim() : "";
+    if (!name)
+        throw new ChannelError('A channel "name" cannot be empty', "invalid_argument");
+    if (name.length > MAX_CHANNEL_NAME_LENGTH)
+        throw new ChannelError(`Channel name is longer than ${MAX_CHANNEL_NAME_LENGTH} characters`, "invalid_argument");
+    return name;
+}
+function validateCredentials(platform, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ChannelError('"credentials" must be an object of strings', "invalid_argument");
+    }
+    const credentials = {};
+    for (const [key, v] of Object.entries(value)) {
+        if (typeof v !== "string")
+            throw new ChannelError(`Credential "${key}" must be a string`, "invalid_argument");
+        credentials[key] = v.trim();
+    }
+    for (const key of platform.credentialKeys) {
+        if (!credentials[key])
+            throw new ChannelError(`${platformLabel(platform)} needs the "${key}" credential`, "invalid_argument");
+    }
+    return credentials;
+}
+function validateAccess(value) {
+    const policies = ["pairing", "allowlist", "open", "disabled"];
+    if (!policies.includes(value.dmPolicy)) {
+        throw new ChannelError(`"dmPolicy" must be one of ${policies.join(", ")}`, "invalid_argument");
+    }
+    if (!Array.isArray(value.allowFrom) ||
+        value.allowFrom.some((id) => typeof id !== "string")) {
+        throw new ChannelError('"allowFrom" must be a list of sender ids', "invalid_argument");
+    }
+    const allowFrom = [
+        ...new Set(value.allowFrom.map((id) => id.trim()).filter(Boolean)),
+    ];
+    const groupPolicies = ["disabled", "allowlist", "open"];
+    if (!groupPolicies.includes(value.groupPolicy)) {
+        throw new ChannelError(`"groupPolicy" must be one of ${groupPolicies.join(", ")}`, "invalid_argument");
+    }
+    if (!Array.isArray(value.groups) ||
+        value.groups.some((id) => typeof id !== "string")) {
+        throw new ChannelError('"groups" must be a list of group chat ids', "invalid_argument");
+    }
+    if (typeof value.requireMention !== "boolean") {
+        throw new ChannelError('"requireMention" must be true or false', "invalid_argument");
+    }
+    const groups = [
+        ...new Set(value.groups.map((id) => id.trim()).filter(Boolean)),
+    ];
+    return {
+        dmPolicy: value.dmPolicy,
+        allowFrom,
+        groupPolicy: value.groupPolicy,
+        groups,
+        requireMention: value.requireMention,
+    };
+}
+function validateSettings(value) {
+    if (typeof value.streaming !== "boolean")
+        throw new ChannelError('"streaming" must be true or false', "invalid_argument");
+    if (typeof value.toolProgress !== "boolean")
+        throw new ChannelError('"toolProgress" must be true or false', "invalid_argument");
+    return { streaming: value.streaming, toolProgress: value.toolProgress };
+}
+/** A stored channel with the fields added after it was saved (phase 2) set to their defaults. */
+function withDefaults(channel) {
+    const access = channel.access;
+    const settings = channel.settings;
+    return {
+        ...channel,
+        access: { ...DEFAULT_ACCESS, ...access },
+        settings: { ...DEFAULT_SETTINGS, ...settings },
+    };
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //# sourceMappingURL=channel-manager.js.map