@krischoichoi/channel-harness 0.6.0

package/lib/bridge.js

@@ -0,0 +1,961 @@
+/**
+ * ChannelHarnessBridge — the inbound half: `ChannelEvent` -> session binding
+ * -> agent resolution -> command plane / `agent.followup` (doc H0.3–H0.7,
+ * command plane spec §2–§12, §36).
+ *
+ * Only `message.received` is handled in v1; every other event type is logged
+ * at debug level. Conversations are isolated by their canonical key
+ * (channel:account:conversation[:thread]), never by account alone.
+ *
+ * Two input planes: a **human command plane** (official
+ * `@deepseek-ai/dsh-commands` `parseCommand`/`commands.execute`) and a
+ * **model message plane** (`agent.followup`). A syntactically valid command
+ * is resolved through the official registry and its `CommandResult` is
+ * rendered directly to the channel — it is never sent to the model and never
+ * creates `assistant/message` (`ReplyRouter` is bypassed). An UNREGISTERED
+ * slash command follows official Host semantics: it is rejected with a
+ * direct channel notice and never enters the Agent prompt — `commands.execute`
+ * returns `undefined` for admission misses, which (given the syntax already
+ * parsed) means `ctx.commands.find(agent, name)` missed.
+ *
+ * Per-conversation serialization: all `message.received` handling for one
+ * canonical key runs through a lightweight per-key promise chain so a `/new`
+ * fully completes (Binding → B) before the next message on the SAME
+ * conversation starts, while different conversations run in parallel. Errors
+ * are caught + logged and never poison the chain.
+ *
+ * `/stop` is the one scheduling exception (spec §4–§10): its COMMAND
+ * semantics belong to the registry (see commands/stop.ts), but its SCHEDULING
+ * is a FAST PATH executed outside the serial chain — it bumps the
+ * per-conversation generation first (invalidating every stale queued message),
+ * cancels the live agent, acknowledges immediately (never waiting for
+ * `whenIdle`), and enqueues an internal stop barrier that re-cancels the
+ * LATEST binding's agent after prior chain work converges (covering the /new
+ * race).
+ */
+import { randomUUID } from 'node:crypto';
+import {} from '@deepseek-ai/cordis';
+import { parseCommand } from '@deepseek-ai/dsh-commands';
+import { PersistenceUnavailableError, SessionNotFoundError } from './agent-manager.js';
+import { routesEqual } from './agent-router.js';
+import { sessionKey, } from './session-router.js';
+import { toHarnessUserMessage, } from './message-converter.js';
+import { installAttachmentCompatibilityTools, } from './file-provider.js';
+import { ReplyContextStore } from './reply-context-store.js';
+import { installSendChannelMessageTool } from './outbox/tool-send.js';
+import { installChannelCommands, } from './commands/index.js';
+import { ChannelModelSelectionController } from './model-selection.js';
+import { toLoggableError } from './loggable-error.js';
+import { ChannelSessionFactory } from './channel-session-factory.js';
+import { isReservedClaimCommand } from '@krischoichoi/channel-core';
+import { InboundAccessController } from './access/controller.js';
+import { commandLocaleFromSettings } from './commands/locale.js';
+function trimBrandedId(value) {
+    return value.trim();
+}
+/**
+ * Error historically raised when a Workspace attach failed inside fresh Session
+ * creation. Workspace attach is now non-fatal: the freshly-created session is
+ * kept (grouped as ungrouped) and the binding + followup continue, so the
+ * bridge no longer produces this error.
+ *
+ * @deprecated Workspace attachment failures are non-fatal and no longer raise
+ * this error. Retained as a public export for compatibility with existing
+ * imports; do not add new uses.
+ */
+export class ChannelWorkspaceAttachError extends Error {
+    sessionId;
+    workspaceId;
+    cwd;
+    channelId;
+    accountId;
+    constructor(input) {
+        super(`channel session '${input.sessionId}' could not attach to workspace '${input.workspaceId}'`);
+        this.name = 'ChannelWorkspaceAttachError';
+        this.sessionId = input.sessionId;
+        this.workspaceId = input.workspaceId;
+        this.cwd = input.cwd;
+        this.channelId = input.channelId;
+        this.accountId = input.accountId;
+    }
+}
+export class ChannelHarnessBridge {
+    options;
+    sessionFactory;
+    commandDisposers = new Set();
+    modelSelectionDisposers = new Set();
+    commandSetupsDisposed = false;
+    /** Thin view over Harness's session/default model semantics. */
+    modelSelection;
+    /** Normalized command deps handed to every agent setup. */
+    commandDeps;
+    /** Per-conversation generation counters, invalidated by /stop (spec §6). */
+    conversationGenerations = new Map();
+    /** Pure fail-closed access decision engine. No I/O. */
+    accessController = new InboundAccessController();
+    constructor(options) {
+        this.options = options;
+        if (!options.accessResolver) {
+            throw new Error('channel-harness requires an access policy resolver');
+        }
+        this.modelSelection =
+            options.commandDeps.modelSelection ?? new ChannelModelSelectionController(options.ctx);
+        // Every Harness service reach is bridged LAZILY from the plugin context
+        // (options.ctx): command handlers must never read services through
+        // invocation.agent.ctx — the agent-loop scoped context does not inject
+        // commands/llm, and Cordis throws "without inject" there. This mirrors the
+        // /new pattern: narrow deps, bridge-owned implementations (official
+        // compact/goal/plan commands close over their plugin ctx the same way).
+        this.commandDeps = {
+            ...options.commandDeps,
+            modelSelection: this.modelSelection,
+            listCommands: (agent) => this.options.ctx.commands.list(agent),
+            findCommand: (agent, name) => this.options.ctx.commands.find(agent, name),
+            locale: options.commandDeps.locale ?? (() => commandLocaleFromSettings(this.options.ctx.get('settings'))),
+            llm: {
+                listProviders: () => this.options.ctx.llm.listProviders(),
+                listModels: (provider) => this.options.ctx.llm.listModels(provider),
+                resolveModelInfo: (provider, model, signal) => this.options.ctx.llm.resolveModelInfo(provider, model, signal),
+                resolveCallConfig: (config, signal) => this.options.ctx.llm.resolveCallConfig(config, signal),
+            },
+            // /version's update hint: live probe of the (optional) control plane.
+            // `ctx.get` is the official detection API — safe on any scope, undefined
+            // when channel-control is not mounted (headless-without-control or the
+            // check disabled). The probe re-runs on every /version so an HMR reload
+            // of the control plugin is picked up without restarting the bridge.
+            versionInfo: async () => {
+                try {
+                    const control = this.options.ctx.get('channelControl');
+                    return await control?.getUpdateStatus();
+                }
+                catch {
+                    return undefined;
+                }
+            },
+        };
+        this.sessionFactory = new ChannelSessionFactory({
+            ctx: options.ctx,
+            cwd: options.config.cwd,
+            bindingStore: options.bindingStore,
+            agentManager: options.agentManager,
+            workspaceResolver: options.workspaceResolver,
+            commandSetup: this.commandSetup,
+            logger: options.logger,
+        });
+    }
+    /** Per-conversation promise chains; entries self-clean on settle. */
+    chains = new Map();
+    /**
+     * Per-conversation serialization. Each canonical key has an owning promise
+     * chain; `fn` is appended onto the previous entry for that key so it starts
+     * only after the prior one settles, while distinct keys run in parallel. The
+     * returned promise resolves only after THIS operation has been handled; the
+     * chain entry absorbs errors (logged, never rethrown) so ONE failing message
+     * never poisons the conversation chain, while this call still surfaces THIS
+     * operation's error to its await-er (preserving prior rejection semantics).
+     */
+    async enqueueSelf(key, fn) {
+        const prev = this.chains.get(key) ?? Promise.resolve();
+        const task = prev.then(fn);
+        const chain = task.catch((error) => {
+            this.options.logger.error(`[channel-harness] message handling failed for conversation '${key}'`, toLoggableError(error));
+        });
+        this.chains.set(key, chain);
+        void chain.finally(() => {
+            if (this.chains.get(key) === chain)
+                this.chains.delete(key);
+        });
+        await task;
+    }
+    /**
+     * Append work onto the per-conversation chain WITHOUT awaiting its
+     * completion (used by the /stop stop barrier — spec §9). The returned
+     * promise never rejects.
+     */
+    enqueueConversation(key, fn) {
+        const prev = this.chains.get(key) ?? Promise.resolve();
+        const task = prev.then(fn);
+        const chain = task.catch((error) => {
+            this.options.logger.error(`[channel-harness] queued message handling failed for conversation '${key}'`, toLoggableError(error));
+        });
+        this.chains.set(key, chain);
+        void chain.finally(() => {
+            if (this.chains.get(key) === chain)
+                this.chains.delete(key);
+        });
+        return task.catch(() => undefined);
+    }
+    async handleChannelEvent(event) {
+        // Connection/auth state is consumed by the control plane and Web status
+        // surface. It is expected to be frequent during startup/reconnect and is
+        // not an inbound message for the Harness Agent bridge.
+        if (event.type === 'connection.changed' || event.type === 'auth.changed') {
+            return;
+        }
+        if (event.type === 'interaction.received') {
+            const normalized = this.normalizeInteractionIdentity(event);
+            if (await this.enforceInteractionAccessGate(normalized))
+                return;
+            if (await this.options.questionPresenter?.handleChannelEvent(normalized))
+                return;
+            this.options.logger.debug('[channel-harness] ignoring unmatched interaction.received');
+            return;
+        }
+        if (event.type !== 'message.received') {
+            this.options.logger.debug(`[channel-harness] ignoring channel event '${event.type}'`);
+            return;
+        }
+        // The command parser operates on the RAW user text (the concatenated plain
+        // text blocks), never on the '[channel=.. sender=.. message=..] ' metadata
+        // prefix the model-facing converter prepends, and never after a trim (the
+        // official parseCommand requires '/' at byte zero — spec §5).
+        const normalizedEvent = this.normalizeInboundIdentity(event);
+        const text = normalizedEvent.message.content
+            .filter((part) => part.type === 'text')
+            .map((part) => part.text)
+            .join('');
+        // ------------------------------------------------------------------
+        // FAIL-CLOSED ACCESS GATE. Runs BEFORE any side effect:
+        // before conversationKey / parseCommand / /stop / binding writes /
+        // session / workspace / agent. A drop here means NO side effect at all
+        // (incl. /stop fast path — an unauthorized user can never cancel a live
+        // agent or bump the generation).
+        // ------------------------------------------------------------------
+        const accessPolicy = await this.enforceAccessGate(normalizedEvent, text);
+        if (!accessPolicy)
+            return;
+        if (await this.options.questionPresenter?.handleChannelEvent(normalizedEvent))
+            return;
+        const parsed = parseCommand(text);
+        if (parsed &&
+            normalizedEvent.conversation.type === 'group' &&
+            normalizedEvent.sender.id !== accessPolicy.ownerId) {
+            const accessLogger = this.options.accessLogger ?? this.options.logger;
+            accessLogger.info('[channel-access] group command denied', {
+                channel: normalizedEvent.channel,
+                account: normalizedEvent.accountId,
+                conversationType: normalizedEvent.conversation.type,
+                reason: 'command_owner_required',
+            });
+            await this.sendCommandNotice(normalizedEvent, '群聊指令仅所有者可用。');
+            return;
+        }
+        const key = this.conversationKey(normalizedEvent);
+        // P0: /stop is handled on a FAST PATH AND RUNS IMMEDIATELY — it must
+        // NEVER be chained behind queued conversation work (spec §4/§5), because
+        // the whole point is to interrupt an in-flight turn. `handleImmediateStop`
+        // bumps the generation synchronously before its first await, so every
+        // already-queued message (captured with the OLD generation) is invalidated
+        // at its next generation check and can never re-wake the agent.
+        if (parsed?.name === 'stop') {
+            try {
+                await this.handleImmediateStop(normalizedEvent, key, text);
+            }
+            catch (error) {
+                this.options.logger.error(`[channel-harness] /stop handling failed for conversation '${key}'`, toLoggableError(error));
+            }
+            return;
+        }
+        const generation = this.generationOf(key);
+        await this.enqueueSelf(key, () => this.handleQueuedMessage(normalizedEvent, key, text, parsed, generation));
+    }
+    /** Apply the contract's only identity normalization before any side effect. */
+    normalizeInboundIdentity(event) {
+        const senderId = trimBrandedId(event.sender.id);
+        const conversationId = trimBrandedId(event.conversation.id);
+        if (senderId === event.sender.id && conversationId === event.conversation.id) {
+            return event;
+        }
+        return {
+            ...event,
+            sender: { ...event.sender, id: senderId },
+            conversation: { ...event.conversation, id: conversationId },
+        };
+    }
+    normalizeInteractionIdentity(event) {
+        return {
+            ...event,
+            sender: { ...event.sender, id: trimBrandedId(event.sender.id) },
+            conversation: {
+                ...event.conversation,
+                id: trimBrandedId(event.conversation.id),
+            },
+        };
+    }
+    /** Interaction admission reuses Security Gate semantics; the click is activation. */
+    async enforceInteractionAccessGate(event) {
+        const accessLogger = this.options.accessLogger ?? this.options.logger;
+        if (!event.sender.id || event.sender.id === 'unknown') {
+            this.dropInteraction(accessLogger, event, 'unidentified_sender');
+            return true;
+        }
+        if (!event.conversation.id) {
+            this.dropInteraction(accessLogger, event, 'invalid_conversation');
+            return true;
+        }
+        let resolved;
+        try {
+            resolved = await this.options.accessResolver.resolve(event.channel, event.accountId);
+        }
+        catch (error) {
+            this.options.logger.warn('[channel-access] policy resolution failed', toLoggableError(error));
+            return true;
+        }
+        if (resolved.state !== 'present') {
+            this.dropInteraction(accessLogger, event, resolved.state === 'missing' ? 'missing_policy' : 'invalid_policy');
+            return true;
+        }
+        const decision = this.accessController.authorize({
+            conversationType: event.conversation.type,
+            senderId: event.sender.id,
+            conversationId: event.conversation.id,
+            policy: resolved.policy,
+        });
+        if (!decision.authorized) {
+            this.dropInteraction(accessLogger, event, decision.reason);
+            return true;
+        }
+        return false;
+    }
+    dropInteraction(logger, event, reason) {
+        logger.info('[channel-access] interaction dropped', {
+            channel: event.channel,
+            account: event.accountId,
+            conversationType: event.conversation.type,
+            reason,
+        });
+    }
+    /**
+     * One-time Agent-scoped command and model-hook setup. Installed onto an
+     * Agent's scoped context by every create/resolve and by the Session
+     * factory's recreate (borrow + create) so a fresh, resumed OR recreated
+     * session gets the channel commands and channel hooks before any driving
+     * happens. Harness still resolves the Session model at creation/resume.
+     * Channel images are NOT rewritten here: the inbound converter hands raw
+     * images to the Harness Attachment Store and the official image
+     * pipeline owns model-capability projection (vision variant / text-only
+     * deterministic placeholder), so the Agent-scoped history keeps the
+     * original ImageBlock.
+     */
+    // Bound arrow: passed to create/resolve/borrowIfLive as the official
+    // AgentSetup (invoked as a bare setup(agentCtx)), so this must stay the
+    // bridge instance.
+    commandSetup = async (agentCtx) => {
+        const disposeCommands = await installChannelCommands(agentCtx, this.commandDeps);
+        const disposeModelSelection = this.modelSelection.install(agentCtx);
+        if (this.commandSetupsDisposed) {
+            await disposeCommands();
+            disposeModelSelection();
+            throw new Error('channel-harness command setup continued after bridge disposal');
+        }
+        this.commandDisposers.add(disposeCommands);
+        this.modelSelectionDisposers.add(disposeModelSelection);
+        // M4: Agent-scoped read_channel_attachment tool. Registered on the agent's
+        // own scope so it is disposed with the agent. Best-effort: a tool-install
+        // failure must never roll back the agent setup. The tool stays registered
+        // through the provider's OPTIONAL compatibility path while it
+        // is the only generic-attachment reader. The deprecated installTools name
+        // remains a fallback for one cycle; providers with neither hook skip it.
+        if (this.options.fileProvider) {
+            try {
+                await installAttachmentCompatibilityTools(this.options.fileProvider, agentCtx);
+            }
+            catch (error) {
+                this.options.logger.warn('[channel-harness] failed to install read_channel_attachment tool', error);
+            }
+        }
+        // M6: Agent-scoped send_channel_message tool. Only installed when the
+        // durable outbox is wired. Best-effort, mirroring the attachment tool.
+        if (this.options.outbox) {
+            try {
+                await installSendChannelMessageTool(agentCtx, { outbox: this.options.outbox });
+            }
+            catch (error) {
+                this.options.logger.warn('[channel-harness] failed to install send_channel_message tool', error);
+            }
+        }
+    };
+    /** Release this bridge's Agent-scoped command and model-hook registrations. */
+    async disposeCommandSetups() {
+        this.commandSetupsDisposed = true;
+        const commandDisposers = [...this.commandDisposers];
+        this.commandDisposers.clear();
+        const modelDisposers = [...this.modelSelectionDisposers];
+        this.modelSelectionDisposers.clear();
+        await Promise.all([
+            ...commandDisposers.map((dispose) => dispose()),
+            ...modelDisposers.map((dispose) => Promise.resolve(dispose())),
+        ]);
+    }
+    conversationKey(event) {
+        return sessionKey({
+            channelId: event.channel,
+            accountId: event.accountId,
+            conversationId: event.conversation.id,
+            ...(event.conversation.threadId ? { threadId: event.conversation.threadId } : {}),
+        });
+    }
+    /** Conversation identity of an inbound event, as a bindable SessionKeyInput. */
+    conversationInput(event) {
+        return {
+            channelId: event.channel,
+            accountId: event.accountId,
+            conversationId: event.conversation.id,
+            // v3: stable conversation identity captured for the durable binding.
+            conversationType: event.conversation.type,
+            ...(event.sender.id ? { senderId: event.sender.id } : {}),
+            ...(event.conversation.threadId ? { threadId: event.conversation.threadId } : {}),
+        };
+    }
+    /**
+     * Whether the durable session behind an existing binding is MISSING — the
+     * stale condition behind both the EXPLICIT stale-binding repair (/new) and
+     * the loud SessionNotFoundError for every other request. A live agent is
+     * never stale (live-first: no persistence probe), and without a mounted
+     * sessionPersistence there is no durable identity to lose (ephemeral
+     * deployments recreate instead). One ATOMIC probe decides all three cases
+     * (live capability resolved once — no canResume/exists TOCTOU across a
+     * persistence HMR).
+     */
+    async isDurableSessionMissing(binding) {
+        if (this.options.agentManager.getLiveAgent(binding.sessionId))
+            return false;
+        const probe = await this.options.agentManager.probePersisted(binding.sessionId);
+        return probe === 'missing';
+    }
+    /** Bindings without the field predate the stable policy; fail closed. */
+    bindingDurability(binding) {
+        return binding.durability ?? 'durable';
+    }
+    /**
+     * FAIL-CLOSED Access Gate. Returns the validated policy only when the
+     * message is admitted. `undefined` means DROP with NO side effect (agent /
+     * command / session / binding / workspace / generation / /stop fast path).
+     *
+     * Order:
+     *   1. Reserved claim suppression (/dsh-claim never reaches anything).
+     *   2. Identity validation: sender + conversation ids.
+     *   3. Resolve policy (missing/invalid -> drop, fail closed).
+     *   4. Authorize (security gate) + activate (activation gate).
+     *
+     * Logging follows the `channel-access` logger convention: minimal fields
+     * (channel / account / conversationType / reason), never message body,
+     * challenge code, raw payload or tokens.
+     */
+    async enforceAccessGate(event, text) {
+        const accessLogger = this.options.accessLogger ?? this.options.logger;
+        // 1. Reserved owner-claim suppression: /dsh-claim must
+        //    NEVER reach model / command dispatcher / Session / Binding, even when
+        //    no access policy exists. Static drop — no policy read is needed.
+        if (isReservedClaimCommand(text)) {
+            accessLogger.debug('[channel-access] reserved claim message suppressed', {
+                channel: event.channel,
+                account: event.accountId,
+            });
+            return undefined;
+        }
+        // 2. Identity validation: sender.id must be a non-empty string
+        //    and !== 'unknown'; conversation.id must be non-empty.
+        const senderId = event.sender.id;
+        const conversationId = event.conversation.id;
+        if (typeof senderId !== 'string' ||
+            senderId.length === 0 ||
+            senderId === 'unknown') {
+            this.dropInbound(accessLogger, event, 'unidentified_sender');
+            return undefined;
+        }
+        if (typeof conversationId !== 'string' || conversationId.length === 0) {
+            this.dropInbound(accessLogger, event, 'invalid_conversation');
+            return undefined;
+        }
+        // 3. Resolve the policy (fail closed).
+        let resolved;
+        try {
+            resolved = await this.options.accessResolver.resolve(event.channel, event.accountId);
+        }
+        catch (error) {
+            this.options.logger.warn('[channel-access] policy resolution failed', toLoggableError(error));
+            return undefined;
+        }
+        if (resolved.state === 'missing') {
+            this.dropInbound(accessLogger, event, 'missing_policy');
+            return undefined;
+        }
+        if (resolved.state === 'invalid') {
+            this.dropInbound(accessLogger, event, 'invalid_policy');
+            return undefined;
+        }
+        // 4. Authorize (Security Gate) then activate (Activation Gate).
+        const decision = this.accessController.authorize({
+            conversationType: event.conversation.type,
+            senderId,
+            conversationId,
+            mentionedBot: event.message.activation?.mentionedBot,
+            policy: resolved.policy,
+        });
+        if (!decision.authorized) {
+            this.dropInbound(accessLogger, event, decision.reason);
+            return undefined;
+        }
+        if (!decision.activated) {
+            this.dropInbound(accessLogger, event, decision.reason);
+            return undefined;
+        }
+        return resolved.policy;
+    }
+    /** Log a fail-closed inbound drop with minimal plan-§42 fields. */
+    dropInbound(accessLogger, event, reason) {
+        accessLogger.info('[channel-access] inbound dropped', {
+            channel: event.channel,
+            account: event.accountId,
+            conversationType: event.conversation.type,
+            reason,
+        });
+    }
+    /**
+     * Queued (serialized) message handling for one conversation. Captures the
+     * generation at ENQUEUE time; /stop bumps it, so this callback drops out at
+     * either generation check and can never re-wake a stopped agent (spec §7).
+     */
+    async handleQueuedMessage(event, key, text, parsed, generation) {
+        // Check #1: fast-drop work already invalidated by /stop (spec §7).
+        if (!this.isGenerationCurrent(key, generation))
+            return;
+        const route = this.options.agentRouter.resolve({
+            channelId: event.channel,
+            accountId: event.accountId,
+            conversationId: event.conversation.id,
+        });
+        const now = Date.now();
+        const parsedName = parsed?.name ?? null;
+        let binding = await this.options.bindingStore.get(key);
+        let archivedSessionId;
+        if (binding && this.options.workspaceResolver.isSessionArchived?.(binding.sessionId)) {
+            archivedSessionId = binding.sessionId;
+            this.options.logger.info('[channel-harness] archived binding will roll to a fresh session', {
+                sessionId: archivedSessionId,
+                bindingKey: key,
+            });
+            // Treat an archived binding like an absent binding for admission. The
+            // durable entry is intentionally left untouched until the Session factory
+            // commits its replacement, preserving rollback semantics on failure.
+            binding = undefined;
+        }
+        // /new is the ONE EXPLICIT stale-binding repair path — NOT a
+        // session-recovery branch: the user is explicitly authorizing abandonment
+        // of the old session (its persisted data is gone, so ordinary recovery
+        // would throw session-not-found) and creation of a fresh one that replaces
+        // the binding. Every other request on the stale binding still fails loud:
+        // the inconsistency is never auto-repaired.
+        if (binding &&
+            parsed &&
+            parsedName === 'new' &&
+            (await this.isDurableSessionMissing(binding))) {
+            // Arg contract mirrors the registered handler (用法：/new).
+            if (parsed.rawInput.trim().length > 0) {
+                await this.sendCommandNotice(event, '用法：/new');
+                return;
+            }
+            const staleSessionId = binding.sessionId;
+            this.options.logger.info('[channel-harness] /new repairs a stale binding (persisted session missing)', {
+                sessionId: staleSessionId,
+                bindingKey: key,
+            });
+            await this.sessionFactory.create(this.conversationInput(event), route);
+            // Clear the stale session's reverse cache (never live/owned -> the
+            // retire is a no-op dispose); the factory has already overwritten the
+            // binding with the fresh session.
+            await this.options.agentManager.retireSession(staleSessionId);
+            await this.sendCommandNotice(event, '旧会话数据已丢失，已开启新会话。');
+            return;
+        }
+        let agentRef;
+        if (!binding) {
+            // --- Bootstrap: no receiving agent exists yet (spec §37/§38) -----------
+            if (parsed && parsedName === 'new') {
+                // First message is /new: boot a brand-new session directly — do NOT
+                // create session A and then run /new on it (no double-create). The
+                // arg contract mirrors the registered handler (用法：/new).
+                if (parsed.rawInput.trim().length > 0) {
+                    await this.sendCommandNotice(event, '用法：/new');
+                    return;
+                }
+                await this.sessionFactory.create(this.conversationInput(event), route);
+                if (archivedSessionId) {
+                    await this.options.agentManager.retireSession(archivedSessionId);
+                }
+                await this.sendCommandNotice(event, '已开启新会话。');
+                return;
+            }
+            // Every other first message (ordinary text, /help, /status, /models,
+            // /model, or an unknown /foo) mints the session and continues below —
+            // first-message /help/status/models/model must work (spec §38). An
+            // unknown /foo is then rejected at command admission (Host parity;
+            // the session must exist first because channel commands register in the
+            // Agent scope and cannot be resolved without one).
+            const fresh = await this.sessionFactory.create(this.conversationInput(event), route);
+            binding = fresh.binding;
+            agentRef = fresh.agentRef;
+            if (archivedSessionId) {
+                await this.options.agentManager.retireSession(archivedSessionId);
+            }
+        }
+        else {
+            // --- Existing conversation: reconcile route snapshot + resolve ----------
+            if (!routesEqual(binding.route, route)) {
+                binding = { ...binding, route, updatedAt: now };
+                await this.options.bindingStore.put(binding);
+            }
+            // Existing-binding resolution follows the official Host resolver order
+            // (live agent -> persistence membership -> resume), never the reverse:
+            //   ① a LIVE agent is borrowed FIRST — persistence is never scanned for
+            //      an agent already live in this process (with thousands of sessions
+            //      the per-inbound persistence scan would dominate);
+            //   ② one ATOMIC probe decides the rest; availability is not durability:
+            //      durable + unavailable -> fail loud (never recreate);
+            //      ephemeral + unavailable -> recreate via the Session factory;
+            //   ③ membership hit -> resume;
+            //   ④ membership MISS -> durable binding => session-not-found, while an
+            //      explicitly ephemeral binding may recreate the recorded id.
+            const borrowed = await this.options.agentManager.borrowIfLive(binding.sessionId, route, this.commandSetup);
+            if (borrowed) {
+                agentRef = borrowed;
+            }
+            else {
+                const probe = await this.options.agentManager.probePersisted(binding.sessionId);
+                if (probe === 'unavailable' && this.bindingDurability(binding) === 'ephemeral') {
+                    const recreated = await this.sessionFactory.recreate(binding, route);
+                    binding = recreated.binding;
+                    agentRef = recreated.agentRef;
+                }
+                else if (probe === 'present') {
+                    agentRef = await this.options.agentManager.resolve(binding.sessionId, route, this.commandSetup);
+                }
+                else if (probe === 'unavailable') {
+                    throw new PersistenceUnavailableError(binding.sessionId, key);
+                }
+                else if (this.bindingDurability(binding) === 'ephemeral') {
+                    const recreated = await this.sessionFactory.recreate(binding, route);
+                    binding = recreated.binding;
+                    agentRef = recreated.agentRef;
+                }
+                else {
+                    throw new SessionNotFoundError(binding.sessionId, key);
+                }
+            }
+            this.options.agentManager.registerBinding(binding);
+        }
+        // --- Command admission (Host parity) ------------------------------------
+        // Registered commands run on the Human Command Plane; an UNREGISTERED
+        // slash command is always rejected with a direct channel notice and never
+        // enters the Agent prompt.
+        if (parsed) {
+            const beforeSessionId = binding.sessionId;
+            const controller = new AbortController();
+            // `commands.execute` takes base64 composer images; channel command
+            // admission is text-only for now (command image parity is a later phase).
+            const execution = await this.options.ctx.commands.execute(agentRef.agent, text, [], controller.signal);
+            if (execution !== undefined) {
+                await this.renderCommandResult(event, execution.result);
+                // Generic post-command cleanup: whichever command switched the active
+                // binding gets its previous session retired. No command-name
+                // special-casing.
+                const currentBinding = await this.options.bindingStore.get(key);
+                if (currentBinding && currentBinding.sessionId !== beforeSessionId) {
+                    await this.options.agentManager.retireSession(beforeSessionId);
+                }
+                return;
+            }
+            // `execution === undefined` with syntax already parsed means the
+            // registry missed the name (`ctx.commands.find(agent, parsed.name)`
+            // returned nothing) — the official Host answers `unknown-command` and
+            // never forwards the line to the model.
+            this.options.logger.info('[channel-harness] rejected unknown command', {
+                channel: event.channel,
+                account: event.accountId,
+                conversationType: event.conversation.type,
+                command: parsed.name,
+            });
+            await this.sendCommandNotice(event, `未知命令：/${parsed.name}，输入 /help 查看命令。`);
+            return;
+        }
+        // Check #2: a /stop may have arrived while this message was resolving
+        // (spec §7) — do not re-wake a stopped agent.
+        if (!this.isGenerationCurrent(key, generation))
+            return;
+        // --- Ordinary message followup --------------------------------------------
+        const runId = randomUUID();
+        this.logInboundBinaryAvailability(event, binding.sessionId);
+        const userMessage = await toHarnessUserMessage(event, {
+            includeMetadataPrefix: this.options.config.includeMetadataPrefix,
+            saveImage: this.saveImageHook(event, binding.sessionId),
+            fileStore: this.fileStoreHook(event, binding.sessionId),
+        });
+        // Register the reply context keyed by the Harness UserMessage id strictly
+        // BEFORE followup.
+        this.options.replyContexts.register(userMessage.id, {
+            sessionId: binding.sessionId,
+            context: {
+                conversationType: event.conversation.type,
+                senderId: event.sender.id,
+                replyToMessageId: event.message.id,
+                // Platform reply handles such as DingTalk's per-message sessionWebhook
+                // are transient and must travel only with the triggering turn.
+                raw: event.raw,
+                runId,
+            },
+        });
+        agentRef.followup(userMessage);
+    }
+    /**
+     * /stop FAST PATH (spec §4–§10). Runs OUTSIDE the serial chain:
+     * ① bump the generation FIRST (synchronous, before any await) so every
+     *    queued/stale message on this conversation is invalidated;
+     * ② cancel the live agent — preferably by executing the registered /stop
+     *    command (lifecycle recorded, behavior owned by the handler), with a
+     *    direct `agent.cancel({ kind: 'user' })` fallback;
+     * ③ acknowledge immediately (never wait for `whenIdle`);
+     * ④ enqueue a fire-and-forget STOP BARRIER that, after prior chain work
+     *    converges, re-cancels the LATEST binding's agent (covers the /new race,
+     *    spec §9).
+     */
+    async handleImmediateStop(event, key, text) {
+        // ① Generation bump must happen before any await (spec §8).
+        this.bumpGeneration(key);
+        // ② Resolve + cancel.
+        const binding = await this.options.bindingStore.get(key);
+        if (binding) {
+            const agent = this.options.agentManager.getLiveAgent(binding.sessionId);
+            if (agent) {
+                try {
+                    const controller = new AbortController();
+                    // `commands.execute` takes base64 composer images; none accompany
+                    // an inbound IM stop command.
+                    const execution = await this.options.ctx.commands.execute(agent, text, [], controller.signal);
+                    if (execution !== undefined) {
+                        await this.renderCommandResult(event, execution.result);
+                    }
+                    else {
+                        agent.cancel({ kind: 'user' });
+                        await this.sendCommandNotice(event, '已停止当前任务。');
+                    }
+                }
+                catch {
+                    agent.cancel({ kind: 'user' });
+                    await this.sendCommandNotice(event, '已停止当前任务。');
+                }
+            }
+            else {
+                // Binding exists but no process-local live agent (cold/resumed
+                // elsewhere): nothing to cancel here; the barrier re-checks below.
+                await this.sendCommandNotice(event, '已停止当前任务。');
+            }
+        }
+        else {
+            // ③ No session: never create one for /stop (spec §39).
+            await this.sendCommandNotice(event, '当前没有可停止的任务。');
+        }
+        // ④ Stop barrier: after existing chain work converges, re-read the LATEST
+        // binding and cancel its agent (spec §9).
+        void this.enqueueConversation(key, async () => {
+            const latestBinding = await this.options.bindingStore.get(key);
+            if (!latestBinding)
+                return;
+            this.options.agentManager.getLiveAgent(latestBinding.sessionId)?.cancel({ kind: 'user' });
+        });
+    }
+    /** Generation helpers (spec §6). */
+    generationOf(key) {
+        return this.conversationGenerations.get(key) ?? 0;
+    }
+    bumpGeneration(key) {
+        const next = this.generationOf(key) + 1;
+        this.conversationGenerations.set(key, next);
+        return next;
+    }
+    isGenerationCurrent(key, generation) {
+        return this.generationOf(key) === generation;
+    }
+    /**
+     * Build the converter's per-message image hook: the official Harness
+     * attachment seam stays the sole authority for the durable image ref, and
+     * — best-effort — the same bytes are MIRRORED into the private channel
+     * asset store under the harness attachment id (the model-visible
+     * `sha256:…`), so `send_channel_message` can resolve the image for
+     * outbound sends (issue #7). A mirror failure never breaks delivery: the
+     * ref is already committed and the converter falls back exactly as before.
+     */
+    saveImageHook(event, sessionId) {
+        const commit = this.options.saveImage;
+        if (!commit)
+            return undefined;
+        const mirror = this.options.fileProvider?.storeImage?.bind(this.options.fileProvider);
+        if (!mirror)
+            return commit;
+        return async (input) => {
+            const ref = await commit(input);
+            try {
+                await mirror({
+                    sessionId,
+                    channelId: event.channel,
+                    accountId: event.accountId,
+                    conversationId: event.conversation.id,
+                    ...(event.conversation.type ? { conversationType: event.conversation.type } : {}),
+                    ...(event.conversation.threadId ? { threadId: event.conversation.threadId } : {}),
+                    messageId: event.message.id,
+                }, {
+                    attachmentId: ref.attachmentId,
+                    data: input.data,
+                    mimeType: input.mediaType,
+                    ...(input.name === undefined ? {} : { name: input.name }),
+                });
+            }
+            catch (error) {
+                this.options.logger.warn('[channel-harness] inbound image mirror failed', {
+                    sessionId,
+                    attachmentId: ref.attachmentId,
+                    error: toLoggableError(error),
+                });
+            }
+            return ref;
+        };
+    }
+    /**
+     * Build the converter's optional file/audio/video store hook. Absent
+     * `fileProvider` -> no hook -> the converter keeps `[file: name]`
+     * placeholders (unchanged fallback). The hook binds the current binding's
+     * session + event identity so a stored asset is correctly session-ACL'd.
+     */
+    fileStoreHook(event, sessionId) {
+        if (!this.options.fileProvider)
+            return undefined;
+        const provider = this.options.fileProvider;
+        return async (part) => {
+            const fields = this.attachmentLogFields(event, sessionId, part);
+            try {
+                const descriptor = await provider.store({
+                    sessionId,
+                    channelId: event.channel,
+                    accountId: event.accountId,
+                    conversationId: event.conversation.id,
+                    ...(event.conversation.type ? { conversationType: event.conversation.type } : {}),
+                    ...(event.conversation.threadId ? { threadId: event.conversation.threadId } : {}),
+                    messageId: event.message.id,
+                }, part);
+                if (!descriptor) {
+                    this.options.logger.warn('[channel-harness] inbound attachment was not stored', fields);
+                    return undefined;
+                }
+                this.options.logger.info('[channel-harness] inbound attachment stored', {
+                    ...fields,
+                    attachmentId: descriptor.attachmentId,
+                    bytes: descriptor.bytes,
+                    readable: descriptor.readable,
+                });
+                return descriptor;
+            }
+            catch (error) {
+                this.options.logger.warn('[channel-harness] inbound attachment storage failed', {
+                    ...fields,
+                    error: toLoggableError(error),
+                });
+                return undefined;
+            }
+        };
+    }
+    /** Log the adapter-to-asset-store boundary once for every binary inbound part. */
+    logInboundBinaryAvailability(event, sessionId) {
+        for (const part of event.message.content) {
+            if (part.type !== 'file' && part.type !== 'audio' && part.type !== 'video')
+                continue;
+            if (part.localData?.byteLength)
+                continue;
+            this.options.logger.warn('[channel-harness] inbound attachment has no local bytes', {
+                ...this.attachmentLogFields(event, sessionId, part),
+                hasUrl: Boolean(part.url),
+                reason: 'adapter did not provide downloaded bytes',
+            });
+        }
+    }
+    attachmentLogFields(event, sessionId, part) {
+        return {
+            channel: event.channel,
+            accountId: event.accountId,
+            conversationId: event.conversation.id,
+            sessionId,
+            messageId: event.message.id,
+            kind: part.type,
+            name: part.type === 'file' ? part.name : undefined,
+            mimeType: part.mimeType,
+            localBytes: part.localData?.byteLength,
+        };
+    }
+    /**
+     * The `commandDeps.startNewSession` implementation. Resolves the
+     * conversation from the CURRENT binding of the invoking agent (the session id
+     * IS the agent id), then asks the Session factory to mint a NEW session id
+     * (never a copy of the old one). The factory also attaches the new session to
+     * the same channel Workspace and registers its binding. The OLD agent is NOT
+     * disposed here; the bridge's post-command retire handles that. If the
+     * factory throws, the old binding stays untouched.
+     */
+    async startNewSession(agent) {
+        const sessionId = String(agent.id);
+        const oldBinding = this.options.agentManager.bindingFor(sessionId);
+        if (!oldBinding) {
+            throw new Error("startNewSession: no binding for session '" + sessionId + "'");
+        }
+        // Re-resolve through the current routing rules before creating the Session,
+        // so /new follows today's overrides rather than the old binding snapshot.
+        const route = this.options.agentRouter.resolve({
+            channelId: oldBinding.channelId,
+            accountId: oldBinding.accountId,
+            conversationId: oldBinding.conversationId,
+        });
+        await this.sessionFactory.create({
+            channelId: oldBinding.channelId,
+            accountId: oldBinding.accountId,
+            conversationId: oldBinding.conversationId,
+            conversationType: oldBinding.conversationType,
+            ...(oldBinding.senderId ? { senderId: oldBinding.senderId } : {}),
+            ...(oldBinding.threadId ? { threadId: oldBinding.threadId } : {}),
+        }, route);
+    }
+    /**
+     * Deliver a command-plane notice directly through the channel adapter — never
+     * through ReplyRouter and never as an assistant/model message.
+     */
+    async sendCommandNotice(event, text) {
+        const adapter = this.options.getAdapter(event.channel);
+        if (!adapter) {
+            this.options.logger.warn(`[channel-harness] no adapter for channel '${event.channel}' — could not deliver command notice`);
+            return;
+        }
+        await adapter.send(this.targetForEvent(event), { text });
+    }
+    /** Render a settled CommandResult to the channel (success/error text). */
+    async renderCommandResult(event, result) {
+        if (result.kind === 'error') {
+            await this.sendCommandNotice(event, result.text);
+            return;
+        }
+        if (result.text) {
+            await this.sendCommandNotice(event, result.text);
+        }
+    }
+    /** Build the outbound ChannelTarget from the inbound conversation + message. */
+    targetForEvent(event) {
+        const target = {
+            channelId: event.channel,
+            accountId: event.accountId,
+            conversationId: event.conversation.id,
+            conversationType: event.conversation.type,
+            raw: event.raw,
+            ...(event.conversation.threadId
+                ? { threadId: event.conversation.threadId, replyToMessageId: event.message.id }
+                : { replyToMessageId: event.message.id }),
+        };
+        return target;
+    }
+}
+//# sourceMappingURL=bridge.js.map