@krischoichoi/channel-harness 0.6.0

package/lib/file-provider.d.ts

@@ -0,0 +1,96 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { StoredBinaryPart } from './message-converter.js';
+export interface ChannelAttachmentContext {
+    sessionId: string;
+    channelId: string;
+    accountId: string;
+    conversationId: string;
+    conversationType?: 'dm' | 'group';
+    threadId?: string;
+    messageId: string;
+}
+export interface ChannelAttachmentDescriptor {
+    attachmentId: string;
+    name: string;
+    mimeType?: string;
+    bytes: number;
+    durable: boolean;
+    readable: boolean;
+}
+export type ResolvedChannelAttachmentKind = 'image' | 'file' | 'audio' | 'video';
+export interface ResolvedChannelAttachment {
+    kind: ResolvedChannelAttachmentKind;
+    data: Uint8Array;
+    name: string;
+    mimeType?: string;
+}
+/** Input for mirroring one inbound image into the private asset store. */
+export interface ChannelImageStoreInput {
+    /**
+     * The HARNESS attachment id (the model-visible `sha256:…` ref id) — the
+     * mirror MUST be stored under exactly this id so the outbox can resolve
+     * the image for outbound sends (issue #7).
+     */
+    attachmentId: string;
+    data: Uint8Array;
+    mimeType?: string;
+    name?: string;
+}
+/**
+ * Optional generic-attachment capability supplied by an extension package.
+ * Core responsibility: `store` / `resolveAttachment` / session ACL.
+ * Tool registration (`read_channel_attachment`) is NOT part of the core
+ * contract — `installCompatibilityTools` is optional and keeps the tool
+ * registered while it is the compatibility path; once Harness
+ * ships a native generic-attachment surface this method can be dropped.
+ */
+export interface ChannelAttachmentProvider {
+    store(context: ChannelAttachmentContext, part: StoredBinaryPart): Promise<ChannelAttachmentDescriptor | undefined>;
+    resolveAttachment(attachmentId: string, sessionId: string): Promise<ResolvedChannelAttachment>;
+    /**
+     * Optional image mirror (issue #7): store the inbound image bytes under
+     * the harness attachment id so `send_channel_message` can re-send them.
+     * Best-effort by contract — absent or failing implementations leave the
+     * harness image seam authoritative; the outbound resolution then simply
+     * misses for images.
+     */
+    storeImage?(context: ChannelAttachmentContext, image: ChannelImageStoreInput): Promise<ChannelAttachmentDescriptor | undefined>;
+    installCompatibilityTools?(agentContext: Context): Promise<void>;
+    /**
+     * @deprecated implement {@link installCompatibilityTools} instead. Retained
+     * for one compatibility cycle so providers built against the former
+     * ChannelFileProvider contract keep registering their agent-scoped tools.
+     */
+    installTools?(agentContext: Context): Promise<void>;
+}
+/** @internal Install at most one provider tool hook, preferring the new name. */
+export declare function installAttachmentCompatibilityTools(provider: ChannelAttachmentProvider, agentContext: Context): Promise<void>;
+/**
+ * Live view over the OPTIONAL attachment-provider seam.
+ *
+ * The provider is resolved through `resolve()` on EVERY call instead of being
+ * captured once at bridge startup. The bundle's `channels-files` row starts
+ * CONCURRENTLY with `channels-harness` (the Cordis entry group creates every
+ * row through `Promise.allSettled`), so a startup snapshot is a race: the
+ * harness fiber can apply first and permanently wire itself to “no provider”
+ * while `channelFiles` mounts a moment later — which silently disables the
+ * outbound attachment resolver (issue #7) and the inbound image mirror.
+ *
+ * Resolving live also keeps the documented contract of the extension honest:
+ * deleting the `channels-files` row stays a supported configuration (absent
+ * stays absent, nothing becomes a hard dependency).
+ */
+export declare function liveAttachmentProvider(resolve: () => ChannelAttachmentProvider | undefined): ChannelAttachmentProvider;
+/**
+ * @deprecated use {@link ChannelAttachmentProvider}
+ */
+export type ChannelFileProvider = ChannelAttachmentProvider;
+/**
+ * @deprecated use {@link ChannelAttachmentContext}
+ */
+export type ChannelFileContext = ChannelAttachmentContext;
+/**
+ * @deprecated use {@link ChannelAttachmentDescriptor}
+ */
+export type ChannelFileDescriptor = ChannelAttachmentDescriptor;
+//# sourceMappingURL=file-provider.d.ts.map

package/lib/file-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-provider.d.ts","sourceRoot":"","sources":["../src/file-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,6BAA6B,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjF,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,6BAA6B,CAAC;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,KAAK,CACH,OAAO,EAAE,wBAAwB,EACjC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAAC;IACpD,iBAAiB,CACf,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACtC;;;;;;OAMG;IACH,UAAU,CAAC,CACT,OAAO,EAAE,wBAAwB,EACjC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAAC;IACpD,yBAAyB,CAAC,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;;OAIG;IACH,YAAY,CAAC,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,iFAAiF;AACjF,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,yBAAyB,EACnC,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,yBAAyB,GAAG,SAAS,GACnD,yBAAyB,CAuB3B;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,yBAAyB,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,2BAA2B,CAAC"}

package/lib/file-provider.js

@@ -0,0 +1,44 @@
+/** @internal Install at most one provider tool hook, preferring the new name. */
+export async function installAttachmentCompatibilityTools(provider, agentContext) {
+    const install = provider.installCompatibilityTools ?? provider.installTools;
+    await install?.call(provider, agentContext);
+}
+/**
+ * Live view over the OPTIONAL attachment-provider seam.
+ *
+ * The provider is resolved through `resolve()` on EVERY call instead of being
+ * captured once at bridge startup. The bundle's `channels-files` row starts
+ * CONCURRENTLY with `channels-harness` (the Cordis entry group creates every
+ * row through `Promise.allSettled`), so a startup snapshot is a race: the
+ * harness fiber can apply first and permanently wire itself to “no provider”
+ * while `channelFiles` mounts a moment later — which silently disables the
+ * outbound attachment resolver (issue #7) and the inbound image mirror.
+ *
+ * Resolving live also keeps the documented contract of the extension honest:
+ * deleting the `channels-files` row stays a supported configuration (absent
+ * stays absent, nothing becomes a hard dependency).
+ */
+export function liveAttachmentProvider(resolve) {
+    return {
+        async store(context, part) {
+            return resolve()?.store(context, part);
+        },
+        async resolveAttachment(attachmentId, sessionId) {
+            const provider = resolve();
+            if (!provider) {
+                throw new Error('no channel attachment provider is mounted (the channelFiles service is unavailable)');
+            }
+            return provider.resolveAttachment(attachmentId, sessionId);
+        },
+        async storeImage(context, image) {
+            return resolve()?.storeImage?.(context, image);
+        },
+        async installCompatibilityTools(agentContext) {
+            const provider = resolve();
+            if (!provider)
+                return;
+            await installAttachmentCompatibilityTools(provider, agentContext);
+        },
+    };
+}
+//# sourceMappingURL=file-provider.js.map

package/lib/file-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-provider.js","sourceRoot":"","sources":["../src/file-provider.ts"],"names":[],"mappings":"AAiFA,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,mCAAmC,CACvD,QAAmC,EACnC,YAAqB;IAErB,MAAM,OAAO,GAAG,QAAQ,CAAC,yBAAyB,IAAI,QAAQ,CAAC,YAAY,CAAC;IAC5E,MAAM,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAoD;IAEpD,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI;YACvB,OAAO,OAAO,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACzC,CAAC;QACD,KAAK,CAAC,iBAAiB,CAAC,YAAY,EAAE,SAAS;YAC7C,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;YACJ,CAAC;YACD,OAAO,QAAQ,CAAC,iBAAiB,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAC7D,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK;YAC7B,OAAO,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;QACD,KAAK,CAAC,yBAAyB,CAAC,YAAY;YAC1C,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ;gBAAE,OAAO;YACtB,MAAM,mCAAmC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QACpE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @krischoichoi/channel-harness — the only package that imports Harness public APIs.
+ *
+ * Bridges ChannelEvents (from `@krischoichoi/channel-core` adapters) to Harness
+ * sessions: inbound messages resolve to a SessionBinding, resolve/create an
+ * agent via `ctx.agents`, and call `agent.followup`; outbound assistant
+ * output flows back through the official `session/event` feed to the channel
+ * adapter's reply pipeline.
+ *
+ * This package never imports platform SDKs and never depends on concrete
+ * channel packages.
+ */
+export * from './config.js';
+export * from './channel-label.js';
+export * from './dsh-home.js';
+export * from './file-provider.js';
+export * from './outbox/index.js';
+export * from './session-router.js';
+export * from './binding-store.js';
+export * from './agent-router.js';
+export * from './agent-manager.js';
+export * from './message-converter.js';
+export * from './model-selection.js';
+export * from './reply-router.js';
+export * from './reply-context-store.js';
+export * from './interactions/index.js';
+export * from './bridge.js';
+export * from './lifecycle.js';
+export * from './workspace-resolver.js';
+export { name, inject, apply } from './plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/lib/index.js

@@ -0,0 +1,31 @@
+/**
+ * @krischoichoi/channel-harness — the only package that imports Harness public APIs.
+ *
+ * Bridges ChannelEvents (from `@krischoichoi/channel-core` adapters) to Harness
+ * sessions: inbound messages resolve to a SessionBinding, resolve/create an
+ * agent via `ctx.agents`, and call `agent.followup`; outbound assistant
+ * output flows back through the official `session/event` feed to the channel
+ * adapter's reply pipeline.
+ *
+ * This package never imports platform SDKs and never depends on concrete
+ * channel packages.
+ */
+export * from './config.js';
+export * from './channel-label.js';
+export * from './dsh-home.js';
+export * from './file-provider.js';
+export * from './outbox/index.js';
+export * from './session-router.js';
+export * from './binding-store.js';
+export * from './agent-router.js';
+export * from './agent-manager.js';
+export * from './message-converter.js';
+export * from './model-selection.js';
+export * from './reply-router.js';
+export * from './reply-context-store.js';
+export * from './interactions/index.js';
+export * from './bridge.js';
+export * from './lifecycle.js';
+export * from './workspace-resolver.js';
+export { name, inject, apply } from './plugin.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/lib/interactions/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Channel-side human interactions.
+ *
+ * `QuestionInteraction*` today; the directory and interface naming leave
+ * room for an `ApprovalInteraction` sibling (future) without sharing
+ * interfaces prematurely — the official question/approval domains compose
+ * answerers on the same Cordis waterfall mechanism.
+ */
+export * from './question-backend.js';
+export * from './question-presenter.js';
+export * from './question-state.js';
+export * from './question-waterfall-backend.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/interactions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interactions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC"}

package/lib/interactions/index.js

@@ -0,0 +1,13 @@
+/**
+ * Channel-side human interactions.
+ *
+ * `QuestionInteraction*` today; the directory and interface naming leave
+ * room for an `ApprovalInteraction` sibling (future) without sharing
+ * interfaces prematurely — the official question/approval domains compose
+ * answerers on the same Cordis waterfall mechanism.
+ */
+export * from './question-backend.js';
+export * from './question-presenter.js';
+export * from './question-state.js';
+export * from './question-waterfall-backend.js';
+//# sourceMappingURL=index.js.map

package/lib/interactions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/interactions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC"}

package/lib/interactions/question-backend.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Question interaction backend contract + answerer assembly.
+ *
+ * The official question domain (`ask_user_question` -> `ctx.userQuestions`)
+ * dispatches the `user-questions/request` Cordis waterfall; answerers claim a
+ * request by returning an answer or delegate with `next()`. The channel
+ * composes ONE waterfall answerer that serves every profile:
+ *
+ * - **Headless**: the channel is typically the only answerer, so a declined
+ *   presentation fails the ask (`NO_PROVIDER` from the official service).
+ * - **Web profile**: the official Remote/Web answerer is composed on the same
+ *   waterfall and claims first unless the channel answerer is PREPENDED (see
+ *   `question-waterfall-backend.ts`); a channel decline still delegates to it.
+ *
+ * There is no version branching here: the waterfall is the only transport,
+ * and the `userQuestions` probe is diagnostic (never an admission gate).
+ *
+ * Naming leaves room for the upcoming approval interaction:
+ * everything here is `QuestionInteraction*` under `interactions/`,
+ * and the official domain already carries approval requests a future
+ * `ApprovalInteraction` can compose the same way.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AskUserQuestionAnswer, AskUserQuestionItem } from '@deepseek-ai/dsh-user-questions/types';
+import type { ChannelAdapter, ChannelLogger } from '@krischoichoi/channel-core';
+import type { AgentManager } from '../agent-manager.js';
+import type { ReplyContextStore } from '../reply-context-store.js';
+import { type ChannelUserQuestionService } from './question-waterfall-backend.js';
+import { ChannelQuestionPresenter } from './question-presenter.js';
+/** One question batch arriving from the Harness question domain. */
+export interface QuestionInteractionRequest {
+    /** Correlation key the backend minted (the waterfall ask key). */
+    key: string;
+    sessionId: string;
+    /** Official question items; every field (incl. `intent`) is carried verbatim. */
+    questions: AskUserQuestionItem[];
+}
+/**
+ * The channel presentation side, as seen by a backend. Backends push
+ * harness-origin question traffic through this sink; the presenter resolves
+ * answers back through {@link QuestionInteractionBackend}.
+ */
+export interface QuestionInteractionSink {
+    /**
+     * Present a question batch on its bound channel conversation.
+     *
+     * @returns true when the channel took ownership (it will later resolve or
+     * cancel through the backend); false when the channel declined (no bound
+     * conversation, adapter absent / text unsupported, or a question already
+     * pending there) and the backend must delegate the ask to the next
+     * answerer.
+     */
+    questionRequested(request: QuestionInteractionRequest): Promise<boolean>;
+    /**
+     * The question settled WITHOUT the channel — the owning tool call aborted.
+     * Removes stale channel controls.
+     */
+    questionSettledExternally(key: string, state?: 'aborted' | 'externally-settled'): Promise<void>;
+}
+/** A channel-collected answer batch submitted to the Harness question domain. */
+export interface QuestionInteractionResolution {
+    key: string;
+    sessionId: string;
+    answer: AskUserQuestionAnswer;
+}
+/** The channel could not / will not answer a question it had taken. */
+export interface QuestionInteractionCancellation {
+    key: string;
+    /** Human-readable reason; also the code-carrying message headless. */
+    reason: string;
+}
+/** Which official transport a backend speaks. */
+export type QuestionBackendKind = 'waterfall';
+/**
+ * Transport-neutral question domain port consumed by the presenter.
+ * `QuestionInteraction*` naming keeps room for a future approval sibling
+ * without sharing this interface prematurely.
+ */
+export interface QuestionInteractionBackend {
+    readonly kind: QuestionBackendKind;
+    /** Connect the presenter sink and begin consuming the question domain. */
+    start(sink: QuestionInteractionSink): void;
+    /** Tear the transport down and settle every still-open question. */
+    stop(): Promise<void>;
+    /** Submit a complete answer batch (one entry per question, in order). */
+    resolve(submission: QuestionInteractionResolution): Promise<void>;
+    /** Cancel an open question with a human-readable reason. */
+    cancel(cancellation: QuestionInteractionCancellation): Promise<void>;
+}
+/**
+ * Live service probes. The waterfall answerer registers on `ctx` and never
+ * calls the service, so `getUserQuestions()` is a DIAGNOSTIC probe: it only
+ * decides whether the startup miss is logged.
+ */
+export interface QuestionBackendProbe {
+    /** The official `ctx.userQuestions` service, when the host spine provides it. */
+    getUserQuestions(): ChannelUserQuestionService | undefined;
+    /** Root Cordis context the waterfall listener registers on. */
+    ctx: Context;
+}
+/** Channel presentation dependencies shared by every backend mode. */
+export interface QuestionInteractionDeps {
+    agentManager: AgentManager;
+    replyContexts: ReplyContextStore;
+    getAdapter(channelId: string): ChannelAdapter | undefined;
+    logger: ChannelLogger;
+    timeoutMs: number;
+}
+export interface QuestionInteractionOptions extends QuestionInteractionDeps, Omit<QuestionBackendProbe, 'ctx'> {
+    ctx: Context;
+}
+/**
+ * Backend selection: the waterfall answerer always exists, because it needs
+ * only the ROOT context — `ctx.userQuestions` dispatches the event, and this
+ * backend never calls the service. The probe is therefore DIAGNOSTIC ONLY.
+ *
+ * Treating a missing service as fatal (the pre-waterfall behavior) made a
+ * transient startup state permanent: profile rows are composed concurrently
+ * and `cordis.patch.yml` layers hot-reload, so a `userQuestions` service that
+ * mounts after the bridge used to leave channel question presentation
+ * disabled for the whole process — every channel-bound ask silently answered
+ * by the Web UI instead. A registered listener with no service is inert, so
+ * the answerer is composed unconditionally and the miss is only logged.
+ */
+export declare function selectQuestionBackend(probe: Omit<QuestionBackendProbe, 'ctx'> & {
+    ctx: Context;
+}, deps: Pick<QuestionInteractionDeps, 'logger'>): QuestionInteractionBackend;
+/**
+ * Assemble the whole question interaction stack: probe the service (diagnostic
+ * only), build the waterfall backend, and wire the channel presenter on top.
+ */
+export declare function createQuestionInteraction(options: QuestionInteractionOptions): ChannelQuestionPresenter;
+//# sourceMappingURL=question-backend.d.ts.map

package/lib/interactions/question-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-backend.d.ts","sourceRoot":"","sources":["../../src/interactions/question-backend.ts"],"names":[],"mappings":"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"}

package/lib/interactions/question-backend.js

@@ -0,0 +1,37 @@
+import { WaterfallQuestionBackend } from './question-waterfall-backend.js';
+import { ChannelQuestionPresenter } from './question-presenter.js';
+/**
+ * Backend selection: the waterfall answerer always exists, because it needs
+ * only the ROOT context — `ctx.userQuestions` dispatches the event, and this
+ * backend never calls the service. The probe is therefore DIAGNOSTIC ONLY.
+ *
+ * Treating a missing service as fatal (the pre-waterfall behavior) made a
+ * transient startup state permanent: profile rows are composed concurrently
+ * and `cordis.patch.yml` layers hot-reload, so a `userQuestions` service that
+ * mounts after the bridge used to leave channel question presentation
+ * disabled for the whole process — every channel-bound ask silently answered
+ * by the Web UI instead. A registered listener with no service is inert, so
+ * the answerer is composed unconditionally and the miss is only logged.
+ */
+export function selectQuestionBackend(probe, deps) {
+    if (!probe.getUserQuestions()) {
+        deps.logger.warn('[channel-harness] the userQuestions service is not mounted yet; the channel question answerer is registered anyway and claims asks as soon as the service appears');
+    }
+    return new WaterfallQuestionBackend({ ctx: probe.ctx, logger: deps.logger });
+}
+/**
+ * Assemble the whole question interaction stack: probe the service (diagnostic
+ * only), build the waterfall backend, and wire the channel presenter on top.
+ */
+export function createQuestionInteraction(options) {
+    const backend = selectQuestionBackend(options, options);
+    return new ChannelQuestionPresenter({
+        backend,
+        agentManager: options.agentManager,
+        replyContexts: options.replyContexts,
+        getAdapter: options.getAdapter,
+        logger: options.logger,
+        timeoutMs: options.timeoutMs,
+    });
+}
+//# sourceMappingURL=question-backend.js.map

package/lib/interactions/question-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-backend.js","sourceRoot":"","sources":["../../src/interactions/question-backend.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,wBAAwB,EAAmC,MAAM,iCAAiC,CAAC;AAC5G,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAgGnE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA2D,EAC3D,IAA6C;IAE7C,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,mKAAmK,CACpK,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,wBAAwB,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAmC;IAEnC,MAAM,OAAO,GAAG,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACxD,OAAO,IAAI,wBAAwB,CAAC;QAClC,OAAO;QACP,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;AACL,CAAC"}

package/lib/interactions/question-presenter.d.ts

@@ -0,0 +1,68 @@
+import type { ChannelAdapter, ChannelEvent, ChannelLogger } from '@krischoichoi/channel-core';
+import type { AgentManager } from '../agent-manager.js';
+import type { ReplyContextStore } from '../reply-context-store.js';
+import type { QuestionInteractionBackend, QuestionInteractionRequest, QuestionInteractionSink } from './question-backend.js';
+export interface ChannelQuestionPresenterOptions {
+    backend: QuestionInteractionBackend;
+    agentManager: AgentManager;
+    replyContexts: ReplyContextStore;
+    getAdapter(channelId: string): ChannelAdapter | undefined;
+    logger: ChannelLogger;
+    timeoutMs: number;
+}
+/**
+ * Presents Harness-origin questions (the official `user-questions/request`
+ * waterfall) through generic channel actions.
+ */
+export declare class ChannelQuestionPresenter implements QuestionInteractionSink {
+    private readonly options;
+    private readonly state;
+    constructor(options: ChannelQuestionPresenterOptions);
+    /** Connect the sink and open the backend transport. */
+    start(): void;
+    /** Cancel every open question, then tear the backend transport down. */
+    stop(): Promise<void>;
+    /**
+     * Present one question batch on the channel conversation bound to the
+     * asking session. Returns false when the channel cannot take ownership
+     * (no active reply context, no binding, adapter absent / text unsupported,
+     * or another question already pending on that conversation) — the backend
+     * decides what a decline means per transport.
+     *
+     * `interactiveActions` decides only presentation quality, never admission:
+     * any `text: true` adapter can answer via numbered plain text; a
+     * `interactiveActions: true` adapter upgrades to native buttons.
+     */
+    questionRequested(request: QuestionInteractionRequest): Promise<boolean>;
+    /** Another client answered, or the owning tool call aborted: drop controls. */
+    questionSettledExternally(key: string, state?: 'aborted' | 'externally-settled'): Promise<void>;
+    /** Consume an already-authorized channel answer before it reaches the Agent inbox. */
+    handleChannelEvent(event: ChannelEvent): Promise<boolean>;
+    private present;
+    private handleInteraction;
+    /**
+     * Route one authorized text message into the question flow. DM answers parse
+     * directly; group/thread answers must correlate via the platform `replyTo`
+     * mapping or the per-question `replyToken` (stripped before parsing).
+     * Returns true when the message was consumed by a pending question (never
+     * falls through to Agent routing); false otherwise.
+     */
+    private handleMessage;
+    /**
+     * Resolve the answerable text of an inbound message against a pending
+     * question. Returns:
+     * - the message body for DMs (parse directly), or
+     * - the token-stripped body when the platform `replyTo` maps to the prompt,
+     *   or
+     * - the token-stripped body when the reply carries `pending.replyToken`
+     *   anywhere (`Q-XXXX 2`, `Q-XXXX: 2`, `@bot Q-XXXX 2`), or
+     * - `undefined` when nothing correlates (leave for ordinary routing).
+     */
+    private correlateMessageBody;
+    private advance;
+    private submit;
+    private cancel;
+    private removeButtons;
+    private cleanup;
+}
+//# sourceMappingURL=question-presenter.d.ts.map

package/lib/interactions/question-presenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-presenter.d.ts","sourceRoot":"","sources":["../../src/interactions/question-presenter.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,aAAa,EAKd,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EACV,0BAA0B,EAC1B,0BAA0B,EAC1B,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAU/B,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,0BAA0B,CAAC;IACpC,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,iBAAiB,CAAC;IACjC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC1D,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAkBD;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,uBAAuB;IAG1D,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;gBAErB,OAAO,EAAE,+BAA+B;IAErE,uDAAuD;IACvD,KAAK,IAAI,IAAI;IAIb,wEAAwE;IAClE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;;;;;;;;;OAUG;IACG,iBAAiB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,OAAO,CAAC;IAuE9E,+EAA+E;IACzE,yBAAyB,CAC7B,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,SAAS,GAAG,oBAA2C,GAC7D,OAAO,CAAC,IAAI,CAAC;IAahB,sFAAsF;IAChF,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;YAMjD,OAAO;YAmDP,iBAAiB;IA+C/B;;;;;;OAMG;YACW,aAAa;IAwD3B;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;YA0Bd,OAAO;YAiBP,MAAM;YAqBN,MAAM;YAeN,aAAa;YAUb,OAAO;CAItB"}