@krischoichoi/channel-harness 0.6.0

package/lib/bridge.d.ts

@@ -0,0 +1,248 @@
+import { type Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ChannelAdapter, ChannelLogger, ChannelEvent } from '@krischoichoi/channel-core';
+import type { Config } from './config.js';
+import type { SessionBindingStore } from './binding-store.js';
+import type { AgentManager } from './agent-manager.js';
+import type { AgentRouter } from './agent-router.js';
+import type { ChannelWorkspaceResolver } from './workspace-resolver.js';
+import { type SaveImageHook } from './message-converter.js';
+import { type ChannelAttachmentProvider } from './file-provider.js';
+import { ReplyContextStore } from './reply-context-store.js';
+import type { ChannelOutboxService } from './outbox/service.js';
+import { type ChannelCommandDependencies } from './commands/index.js';
+import { ChannelModelSelectionController } from './model-selection.js';
+import type { ChannelAccessPolicyResolver } from './access/resolver.js';
+import type { ChannelQuestionPresenter } from './interactions/question-presenter.js';
+export interface ChannelHarnessBridgeOptions {
+    config: Config;
+    bindingStore: SessionBindingStore;
+    agentManager: AgentManager;
+    agentRouter: AgentRouter;
+    getAdapter(channelId: string): ChannelAdapter | undefined;
+    replyContexts: ReplyContextStore;
+    logger: ChannelLogger;
+    /** Fail-closed Access Gate resolver. */
+    accessResolver: ChannelAccessPolicyResolver;
+    /**
+     * Namespaced logger for access decisions (namespace
+     * `channel-access`). Falls back to `logger` when not provided. Never logs
+     * message body / challenge codes / raw payload / tokens.
+     */
+    accessLogger?: ChannelLogger;
+    /** Optional attachment-commit seam (WX5 real image path). */
+    saveImage?: SaveImageHook;
+    /** Optional generic-file extension. Absent keeps ordinary file placeholders. */
+    fileProvider?: ChannelAttachmentProvider;
+    /**
+     * The Cordis context on which the official `commands` registry is mounted.
+     * `ctx.commands.execute` is the official command dispatcher.
+     */
+    ctx: Context;
+    /**
+     * Bridge hook the channel commands need (`startNewSession` + optional
+     * model-selection controller; absent -> the bridge owns a default instance).
+     */
+    commandDeps: Omit<ChannelCommandDependencies, 'modelSelection' | 'listCommands' | 'findCommand' | 'locale' | 'llm' | 'versionInfo'> & {
+        modelSelection?: ChannelModelSelectionController;
+        listCommands?: ChannelCommandDependencies['listCommands'];
+        findCommand?: ChannelCommandDependencies['findCommand'];
+        locale?: ChannelCommandDependencies['locale'];
+        llm?: ChannelCommandDependencies['llm'];
+        versionInfo?: ChannelCommandDependencies['versionInfo'];
+    };
+    /**
+     * Resolves a channel conversation to a Session working directory and (when
+     * applicable) a Harness `WorkspaceRegistry` member.
+     */
+    workspaceResolver: ChannelWorkspaceResolver;
+    /**
+     * Optional durable outbox. Presence enables the Model-facing
+     * `send_channel_message` tool. Absent -> no proactive send tool.
+     */
+    outbox?: ChannelOutboxService;
+    /**
+     * Optional question interaction presenter (the channel composes an answerer
+     * on the official `user-questions/request` waterfall). Absent when the
+     * user-questions feature is disabled or the userQuestions service was not
+     * probed.
+     */
+    questionPresenter?: ChannelQuestionPresenter;
+}
+/**
+ * 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 declare class ChannelWorkspaceAttachError extends Error {
+    readonly sessionId: string;
+    readonly workspaceId: string;
+    readonly cwd: string;
+    readonly channelId: string;
+    readonly accountId: string;
+    constructor(input: {
+        sessionId: string;
+        workspaceId: string;
+        cwd: string;
+        channelId: string;
+        accountId: string;
+    });
+}
+export declare class ChannelHarnessBridge {
+    private readonly options;
+    private readonly sessionFactory;
+    private readonly commandDisposers;
+    private readonly modelSelectionDisposers;
+    private commandSetupsDisposed;
+    /** Thin view over Harness's session/default model semantics. */
+    private readonly modelSelection;
+    /** Normalized command deps handed to every agent setup. */
+    private readonly commandDeps;
+    /** Per-conversation generation counters, invalidated by /stop (spec §6). */
+    private readonly conversationGenerations;
+    /** Pure fail-closed access decision engine. No I/O. */
+    private readonly accessController;
+    constructor(options: ChannelHarnessBridgeOptions);
+    /** Per-conversation promise chains; entries self-clean on settle. */
+    private readonly chains;
+    /**
+     * 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).
+     */
+    private enqueueSelf;
+    /**
+     * Append work onto the per-conversation chain WITHOUT awaiting its
+     * completion (used by the /stop stop barrier — spec §9). The returned
+     * promise never rejects.
+     */
+    private enqueueConversation;
+    handleChannelEvent(event: ChannelEvent): Promise<void>;
+    /** Apply the contract's only identity normalization before any side effect. */
+    private normalizeInboundIdentity;
+    private normalizeInteractionIdentity;
+    /** Interaction admission reuses Security Gate semantics; the click is activation. */
+    private enforceInteractionAccessGate;
+    private dropInteraction;
+    /**
+     * 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.
+     */
+    private commandSetup;
+    /** Release this bridge's Agent-scoped command and model-hook registrations. */
+    disposeCommandSetups(): Promise<void>;
+    private conversationKey;
+    /** Conversation identity of an inbound event, as a bindable SessionKeyInput. */
+    private conversationInput;
+    /**
+     * 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).
+     */
+    private isDurableSessionMissing;
+    /** Bindings without the field predate the stable policy; fail closed. */
+    private bindingDurability;
+    /**
+     * 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.
+     */
+    private enforceAccessGate;
+    /** Log a fail-closed inbound drop with minimal plan-§42 fields. */
+    private dropInbound;
+    /**
+     * 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).
+     */
+    private handleQueuedMessage;
+    /**
+     * /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).
+     */
+    private handleImmediateStop;
+    /** Generation helpers (spec §6). */
+    private generationOf;
+    private bumpGeneration;
+    private isGenerationCurrent;
+    /**
+     * 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.
+     */
+    private saveImageHook;
+    /**
+     * 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.
+     */
+    private fileStoreHook;
+    /** Log the adapter-to-asset-store boundary once for every binary inbound part. */
+    private logInboundBinaryAvailability;
+    private attachmentLogFields;
+    /**
+     * 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.
+     */
+    startNewSession(agent: Agent): Promise<void>;
+    /**
+     * Deliver a command-plane notice directly through the channel adapter — never
+     * through ReplyRouter and never as an assistant/model message.
+     */
+    private sendCommandNotice;
+    /** Render a settled CommandResult to the channel (success/error text). */
+    private renderCommandResult;
+    /** Build the outbound ChannelTarget from the inbound conversation + message. */
+    private targetForEvent;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/lib/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,KAAK,EACV,cAAc,EAEd,aAAa,EACb,YAAY,EAKb,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,oBAAoB,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,mBAAmB,CAAC;AAOrE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,OAAO,EAGL,KAAK,0BAA0B,EAEhC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,+BAA+B,EAAE,MAAM,sBAAsB,CAAC;AAKvE,OAAO,KAAK,EACV,2BAA2B,EAE5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAOrF,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,mBAAmB,CAAC;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC1D,aAAa,EAAE,iBAAiB,CAAC;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,wCAAwC;IACxC,cAAc,EAAE,2BAA2B,CAAC;IAC5C;;;;OAIG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gFAAgF;IAChF,YAAY,CAAC,EAAE,yBAAyB,CAAC;IACzC;;;OAGG;IACH,GAAG,EAAE,OAAO,CAAC;IACb;;;OAGG;IACH,WAAW,EAAE,IAAI,CACf,0BAA0B,EAC1B,gBAAgB,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,aAAa,CACrF,GAAG;QACF,cAAc,CAAC,EAAE,+BAA+B,CAAC;QACjD,YAAY,CAAC,EAAE,0BAA0B,CAAC,cAAc,CAAC,CAAC;QAC1D,WAAW,CAAC,EAAE,0BAA0B,CAAC,aAAa,CAAC,CAAC;QACxD,MAAM,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC;QAC9C,GAAG,CAAC,EAAE,0BAA0B,CAAC,KAAK,CAAC,CAAC;QACxC,WAAW,CAAC,EAAE,0BAA0B,CAAC,aAAa,CAAC,CAAC;KAEzD,CAAC;IACF;;;OAGG;IACH,iBAAiB,EAAE,wBAAwB,CAAC;IAC5C;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED;;;;;;;;;GASG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,KAAK,EAAE;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB;CASF;AAED,qBAAa,oBAAoB;IAcnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAbpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAyB;IACjE,OAAO,CAAC,qBAAqB,CAAS;IACtC,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;IACjE,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAA6B;IACrE,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAiC;gBAErC,OAAO,EAAE,2BAA2B;IAsDjE,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAE3D;;;;;;;;OAQG;YACW,WAAW;IAgBzB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAgBrB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAoF5D,+EAA+E;IAC/E,OAAO,CAAC,wBAAwB;IAahC,OAAO,CAAC,4BAA4B;IAWpC,qFAAqF;YACvE,4BAA4B;IAsC1C,OAAO,CAAC,eAAe;IAavB;;;;;;;;;;;OAWG;IAIH,OAAO,CAAC,YAAY,CAgClB;IAEF,+EAA+E;IACzE,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3C,OAAO,CAAC,eAAe;IASvB,gFAAgF;IAChF,OAAO,CAAC,iBAAiB;IAYzB;;;;;;;;;OASG;YACW,uBAAuB;IAMrC,yEAAyE;IACzE,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;;;;;;;;OAcG;YACW,iBAAiB;IAuE/B,mEAAmE;IACnE,OAAO,CAAC,WAAW;IAanB;;;;OAIG;YACW,mBAAmB;IA8MjC;;;;;;;;;;;OAWG;YACW,mBAAmB;IA2CjC,oCAAoC;IACpC,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,mBAAmB;IAI3B;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAoCrB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAuCrB,kFAAkF;IAClF,OAAO,CAAC,4BAA4B;IAYpC,OAAO,CAAC,mBAAmB;IAc3B;;;;;;;;OAQG;IACG,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BlD;;;OAGG;YACW,iBAAiB;IAW/B,0EAA0E;YAC5D,mBAAmB;IAUjC,gFAAgF;IAChF,OAAO,CAAC,cAAc;CAavB"}