@krischoichoi/channel-harness 0.6.0

package/lib/lifecycle.js

@@ -0,0 +1,303 @@
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { createBindingStore } from './binding-store.js';
+import { AgentManager, HarnessAgentGateway, resolvePersistedInspection } from './agent-manager.js';
+import { confirmBindTarget, resolveBindTarget } from './bind-support.js';
+import { AgentRouter } from './agent-router.js';
+import { ReplyRouter } from './reply-router.js';
+import { ChannelHarnessBridge } from './bridge.js';
+import { ChannelOutboxService } from './outbox/service.js';
+import { OutboxError } from './outbox/types.js';
+import { HarnessChannelWorkspaceResolver } from './workspace-resolver.js';
+import { ReplyContextStore } from './reply-context-store.js';
+import { installDebugConsoleExporter } from './debug-logger.js';
+import { StoredChannelAccessPolicyResolver } from './access/resolver.js';
+import { liveAttachmentProvider } from './file-provider.js';
+import { createQuestionInteraction } from './interactions/question-backend.js';
+export function startBridge(ctx, config, resolvePersistence) {
+    installDebugConsoleExporter(ctx);
+    const logger = ctx.logger('channel-harness');
+    const channels = ctx.get('channels');
+    const bindingStore = createBindingStore(config.bindingStore);
+    const agentGateway = new HarnessAgentGateway(ctx, resolvePersistence);
+    const agentManager = new AgentManager(agentGateway, logger, config.maxConcurrency);
+    const agentRouter = new AgentRouter(config);
+    const workspaceResolver = new HarnessChannelWorkspaceResolver(ctx, config.workspace, logger);
+    const getAdapter = (channelId) => channels.get(channelId);
+    const replyContexts = new ReplyContextStore();
+    // Question answerer composition: the channel composes ONE PREPENDED answerer
+    // on the official `user-questions/request` waterfall — headless it is
+    // typically the only answerer; in the Web profile it must win over the
+    // official Remote/Web answerer (which registers at boot, before this bridge)
+    // or every channel-bound ask would be swallowed by the browser. A declined
+    // presentation still delegates via `next()`. Everything lives in
+    // interactions/question-backend.ts.
+    const questionPresenter = config.userQuestions.enabled
+        ? createQuestionInteraction({
+            ctx,
+            getUserQuestions: () => ctx.get('userQuestions'),
+            agentManager,
+            replyContexts,
+            getAdapter,
+            logger,
+            timeoutMs: config.userQuestions.timeoutMs,
+        })
+        : undefined;
+    questionPresenter?.start();
+    // Optional attachment service -> real image path (WX5). Resolved LIVE at
+    // every use, exactly like `sessionPersistence` above: the profile entry group
+    // creates every row concurrently (`Promise.allSettled`), so a startup
+    // snapshot can precede the service's own fiber. A deployment without an
+    // attachment backend keeps today's fallback — the hook throws, `imageBlock`
+    // catches, and the converter emits the deterministic text placeholder.
+    const saveImage = async (input) => {
+        const attachments = ctx.get('attachments');
+        if (!attachments) {
+            throw new Error('the Harness attachments service is not mounted');
+        }
+        return attachments.saveImage(input);
+    };
+    // Optional generic-file extension. Harness currently has a native image
+    // service but no generic FileBlock/FileAttachment surface, so deployments
+    // may provide this separately without coupling document parsers to the
+    // bridge. The provider is resolved LIVE per call (see
+    // `liveAttachmentProvider`): the bundle's `channels-files` row loads
+    // concurrently with this plugin, and deleting that row must stay supported.
+    const resolveFileProvider = () => ctx.get('channelFiles');
+    const fileProvider = liveAttachmentProvider(resolveFileProvider);
+    // Best-effort typing indicator wiring: a typing API failure must NEVER break
+    // the inbound/outbound flow, so every call is fire-and-forget with a swallow.
+    const startTyping = (sessionId, context) => {
+        const binding = agentManager.bindingFor(sessionId);
+        if (!binding)
+            return;
+        const adapter = getAdapter(binding.channelId);
+        if (adapter?.startTypingForTarget && context) {
+            void adapter.startTypingForTarget(typingTarget(binding, context)).catch(() => { });
+            return;
+        }
+        if (adapter?.startTyping)
+            void adapter.startTyping(binding.conversationId).catch(() => { });
+    };
+    const stopTyping = (sessionId, context) => {
+        const binding = agentManager.bindingFor(sessionId);
+        if (!binding)
+            return;
+        const adapter = getAdapter(binding.channelId);
+        if (adapter?.stopTypingForTarget && context) {
+            void adapter.stopTypingForTarget(typingTarget(binding, context)).catch(() => { });
+            return;
+        }
+        if (adapter?.stopTyping)
+            void adapter.stopTyping(binding.conversationId).catch(() => { });
+    };
+    ctx.on('agent/inbox/claimed', ({ agent, message, turn }) => {
+        const context = replyContexts.claim({
+            sessionId: String(agent.session.id),
+            messageId: String(message.id),
+            turn,
+        });
+        startTyping(String(agent.session.id), context);
+    });
+    ctx.on('agent/inbox/discarded', ({ message }) => {
+        // Resolve the session id BEFORE dropping the pending entry so we can
+        // cancel any typing the (never-claimed) inbound would have triggered.
+        const messageId = String(message.id);
+        const sessionId = replyContexts.pendingSessionId(messageId);
+        const context = replyContexts.pendingContext(messageId);
+        replyContexts.discard(messageId);
+        if (sessionId)
+            stopTyping(sessionId, context);
+    });
+    const replyRouter = new ReplyRouter({
+        config: config.reply,
+        getAdapter,
+        getBinding: (sessionId) => agentManager.bindingFor(sessionId),
+        replyContexts,
+        logger,
+    });
+    const stopListening = replyRouter.attach(ctx);
+    // Deferred bridge reference: `commandDeps` routes the /new command backed by
+    // the bridge back to the bridge's own fresh-session bootstrap. The arrow only
+    // calls `bridge.startNewSession` at runtime (when a command actually runs), by
+    // which point the bridge is assigned (definite-assignment assertion below).
+    // Durable outbox: the proactive send path. The
+    // binding authority is the DURABLE store (never AgentManager's hint cache),
+    // and the adapter lookup + asset store are the same ones the reply pipeline
+    // uses. Optional: absent -> the send_channel_message tool is not installed.
+    const outbox = new ChannelOutboxService({
+        bindingStore,
+        getAdapter,
+        // Live again: the resolver runs per send, so a provider mounted after the
+        // bridge started (or an HMR replacement) is picked up instead of leaving
+        // the outbox permanently without an attachment resolver (issue #7).
+        attachmentResolver: async (attachmentId, sessionId) => {
+            const provider = resolveFileProvider();
+            if (!provider) {
+                throw new OutboxError('OUTBOX_CAPABILITY_UNAVAILABLE', 'outbound attachments require a private asset store that is not configured', { sessionId });
+            }
+            return provider.resolveAttachment(attachmentId, sessionId);
+        },
+        logger,
+    });
+    let bridge;
+    const commandDeps = {
+        startNewSession: (agent) => bridge.startNewSession(agent),
+        // /mirror (issue #5): the toggle state lives on the durable binding.
+        mirror: {
+            get: async (agent) => (await bindingStore.findBySessionId(String(agent.id)))?.mirror === true,
+            set: async (agent, on) => {
+                const binding = await bindingStore.findBySessionId(String(agent.id));
+                if (!binding)
+                    throw new Error(`no session binding for '${String(agent.id)}'`);
+                await bindingStore.put({ ...binding, mirror: on, updatedAt: Date.now() });
+            },
+        },
+        // /bind (issue #6): fail-closed rebind support over the durable bindings
+        // and the persisted session universe.
+        bind: {
+            resolve: (agent, query) => resolveBindTarget(agentGateway, bindingStore, agent, query),
+            confirm: (agent, sessionId) => confirmBindTarget(agentGateway, bindingStore, agent, sessionId),
+        },
+    };
+    // Fail-closed Access Gate: production ALWAYS resolves the
+    // policy from the shared ChannelStorage and logs decisions on the
+    // `channel-access` namespace. Reads once per inbound — no policy caching (§16).
+    const accessResolver = new StoredChannelAccessPolicyResolver(() => channels.resources.storage);
+    const accessLogger = ctx.logger('channel-access');
+    bridge = new ChannelHarnessBridge({
+        config,
+        bindingStore,
+        agentManager,
+        agentRouter,
+        getAdapter,
+        replyContexts,
+        logger,
+        accessResolver,
+        accessLogger,
+        saveImage,
+        fileProvider,
+        ctx,
+        commandDeps,
+        workspaceResolver,
+        outbox,
+        questionPresenter,
+    });
+    const stopInbound = channels.on((event) => bridge.handleChannelEvent(event));
+    let disposed = false;
+    async function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        // 1. Stop new inbound (adapter events no longer reach the bridge).
+        stopInbound();
+        // Cancel channel-owned question waits before draining the blocked Agent.
+        await questionPresenter?.stop();
+        // Release this bridge's Agent-scoped commands before a replacement bridge
+        // can borrow the same live agents and install fresh handlers.
+        await bridge.disposeCommandSetups();
+        // 2. Drain active turns with a bounded wait (the session/event listener is
+        //    still attached here, but we do NOT depend on it for final-reply
+        //    correctness).
+        await drainActiveTurns(agentManager, replyRouter, logger, config.drainTimeoutMs);
+        // 3. RECONCILE replies from the Session durable log (final text delivery
+        //    does NOT rely on the listener still being attached).
+        await reconcileReplies(ctx, resolvePersistence, agentManager, replyRouter, logger);
+        // 4. Finalize any replies still marked active whose turn/end never arrived.
+        await replyRouter.flushAll();
+        // 5. Stop listening to session/event.
+        stopListening();
+        // 6. Dispose owned agent handles (each exactly once).
+        await agentManager.disposeAll();
+        // 7. Dispose the reply router (clear timers).
+        replyRouter.dispose();
+    }
+    return {
+        dispose,
+        handleChannelEvent: (event) => bridge.handleChannelEvent(event),
+    };
+}
+function typingTarget(binding, context) {
+    return {
+        channelId: binding.channelId,
+        accountId: binding.accountId,
+        conversationId: binding.conversationId,
+        threadId: binding.threadId,
+        conversationType: context.conversationType,
+        replyToMessageId: context.replyToMessageId,
+        raw: context.raw,
+        runId: context.runId,
+    };
+}
+async function drainActiveTurns(agentManager, replyRouter, logger, drainTimeoutMs) {
+    const sessionIds = replyRouter.activeSessions();
+    if (sessionIds.length === 0)
+        return;
+    await Promise.all(sessionIds.map(async (sessionId) => {
+        const ref = agentManager.refFor(sessionId);
+        if (!ref)
+            return;
+        const timedOut = await withTimeout(ref.whenIdle(), drainTimeoutMs);
+        if (timedOut) {
+            logger.warn(`[channel-harness] drain timed out for session '${sessionId}'`);
+        }
+    }));
+}
+/**
+ * Reconcile every active session's reply from the durable log. Reads the live
+ * Session when it is still in the store; otherwise inspects persistence
+ * (resolved LIVE at dispose time — the currently mounted backend, whatever
+ * the bridge started with). Skips gracefully when neither is available.
+ * Final-reply correctness comes from the Session log, not from the
+ * still-attached event listener.
+ */
+async function reconcileReplies(ctx, resolvePersistence, agentManager, replyRouter, logger) {
+    const sessionIds = agentManager.activeSessions();
+    if (sessionIds.length === 0)
+        return;
+    const sessions = ctx.get('sessions');
+    const persistence = resolvePersistence?.();
+    for (const sessionId of sessionIds) {
+        try {
+            const live = sessions?.get(SessionId(sessionId));
+            if (live) {
+                await replyRouter.reconcileSession({ id: sessionId, events: live.snapshotEvents() });
+                continue;
+            }
+            if (persistence) {
+                // V3 persistence inspection uses the public read handle.
+                const inspection = await resolvePersistedInspection(persistence, SessionId(sessionId));
+                if (inspection) {
+                    await replyRouter.reconcileSession({ id: sessionId, events: inspection.events });
+                }
+            }
+            // else: no live session and no persistence — skip gracefully.
+        }
+        catch (error) {
+            logger.warn(`[channel-harness] reconcile failed for session '${sessionId}'`, error);
+        }
+    }
+}
+/** Resolve true when the timeout elapses before the promise settles. */
+function withTimeout(promise, ms) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled)
+                resolve(true);
+        }, ms);
+        promise.then(() => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(false);
+        }, () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+//# sourceMappingURL=lifecycle.js.map

package/lib/lifecycle.js.map

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

package/lib/loggable-error.d.ts

@@ -0,0 +1,10 @@
+/** JSON-safe shape for errors passed through logger exporters. */
+export interface LoggableError {
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: LoggableError;
+}
+/** Preserve useful Error fields without relying on non-enumerable properties. */
+export declare function toLoggableError(error: unknown): LoggableError;
+//# sourceMappingURL=loggable-error.d.ts.map

package/lib/loggable-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loggable-error.d.ts","sourceRoot":"","sources":["../src/loggable-error.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAE7D"}

package/lib/loggable-error.js

@@ -0,0 +1,32 @@
+/** Preserve useful Error fields without relying on non-enumerable properties. */
+export function toLoggableError(error) {
+    return normalizeError(error, new Set());
+}
+function normalizeError(error, seen) {
+    if (!(error instanceof Error)) {
+        return { name: 'NonErrorThrown', message: formatUnknown(error) };
+    }
+    if (seen.has(error)) {
+        return { name: error.name, message: `${error.message} (circular cause)` };
+    }
+    seen.add(error);
+    const result = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+    };
+    if (error.cause !== undefined)
+        result.cause = normalizeError(error.cause, seen);
+    return result;
+}
+function formatUnknown(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=loggable-error.js.map

package/lib/loggable-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loggable-error.js","sourceRoot":"","sources":["../src/loggable-error.ts"],"names":[],"mappings":"AAQA,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,cAAc,CAAC,KAAK,EAAE,IAAI,GAAG,EAAS,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,cAAc,CAAC,KAAc,EAAE,IAAgB;IACtD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IACnE,CAAC;IAED,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,mBAAmB,EAAE,CAAC;IAC5E,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAChB,MAAM,MAAM,GAAkB;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC;IACF,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/lib/message-converter.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Inbound conversion: `MessageReceived` -> a Harness `UserMessage`.
+ *
+ * Content is structured-text by default (red line 6): platform parts without
+ * downloadable local bytes are mapped to plain-text blocks — images/files/audio/video
+ * become `[type: ...]` placeholders instead of raw platform JSON. Conversation
+ * metadata (channel / sender / message id) is folded into a configurable text
+ * prefix so the model can still tell where a message came from.
+ *
+ * WX5 attachment path: when an image part carries `localData` (the adapter
+ * already downloaded + decrypted the bytes), and a `saveImage` hook is supplied,
+ * the converter registers the bytes with the Harness attachment service and emits
+ * a real `ImageBlock` (`{ type: 'image', attachment: ImageAttachmentRef }`) so
+ * the model receives a genuine multimodal image instead of the `[image]`
+ * placeholder. The hook is optional; without it (or on attachment failure) the
+ * converter falls back to the text placeholder so message delivery never breaks.
+ */
+import { type ContentBlock, type UserMessage } from '@deepseek-ai/dsh-llm';
+import type { ImageAttachmentRef, SaveImageAttachment } from '@deepseek-ai/dsh-attachment';
+import { type AudioPart, type FilePart, type MessagePart, type MessageReceived, type VideoPart } from '@krischoichoi/channel-core';
+import type { ChannelAttachmentDescriptor } from './file-provider.js';
+/** Type-level alias: the bridge always produces Harness user messages. */
+export type UserMessageLike = UserMessage;
+/**
+ * Bridge-provided seam to commit one image to the Harness attachment service.
+ * Mirrors `AttachmentStore.saveImage` so the converter stays decoupled from the
+ * concrete Cordis service (resolved at the use site and injected). Returns the
+ * durable reference used to build the `ImageBlock`.
+ */
+export type SaveImageHook = (input: SaveImageAttachment) => Promise<ImageAttachmentRef>;
+/** A binary (file / audio / video) part carrying local bytes. */
+export type StoredBinaryPart = FilePart | AudioPart | VideoPart;
+/**
+ * Optional bridge-provided seam that persists a file/audio/video part with
+ * `localData` into the private channel asset store and returns a compact
+ * model descriptor (plan \u00a750/\u00a754). Mirrors `SaveImageHook`: the
+ * converter stays decoupled from the concrete store (injected at the use
+ * site). Absent -> the part falls back to its `[file: name]` placeholder;
+ * a thrown/undefined result also falls back, never breaking delivery.
+ */
+export type FileStoreHook = (part: StoredBinaryPart) => Promise<ChannelAttachmentDescriptor | undefined>;
+export interface MessageConvertOptions {
+    /** Whether to prepend the `[channel=.. sender=.. message=..]` prefix. Defaults to false. */
+    includeMetadataPrefix?: boolean;
+    /** Optional image-commit hook enabling the real attachment path. */
+    saveImage?: SaveImageHook;
+    /** Optional file/audio/video store hook enabling the private asset path. */
+    fileStore?: FileStoreHook;
+}
+/** Convert a channel message-received event into a model-facing user message. */
+export declare function toHarnessUserMessage(event: MessageReceived, options?: MessageConvertOptions): Promise<UserMessageLike>;
+/**
+ * Map structured parts to a single text line. Never embeds raw payloads.
+ * Image parts with local bytes and a saveImage hook are surfaced via
+ * `onImage` instead of being folded into text; they never contribute a text
+ * placeholder (unless the attachment path is unavailable, in which case they
+ * fall back to the ordinary `[image]` placeholder).
+ */
+export declare function partsToText(parts: readonly MessagePart[], options?: {
+    saveImage?: SaveImageHook;
+    fileStore?: FileStoreHook;
+    onImage?: (block: ContentBlock) => void;
+}): Promise<string>;
+//# sourceMappingURL=message-converter.d.ts.map

package/lib/message-converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-converter.d.ts","sourceRoot":"","sources":["../src/message-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,kBAAkB,EAAkB,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC3G,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,QAAQ,EAEb,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEtE,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAExF,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,gBAAgB,KACnB,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAAC;AAEtD,MAAM,WAAW,qBAAqB;IACpC,4FAA4F;IAC5F,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,oEAAoE;IACpE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,iFAAiF;AACjF,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,CAAC,CAkB1B;AA0BD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CACpC,GACL,OAAO,CAAC,MAAM,CAAC,CA8CjB"}

package/lib/message-converter.js

@@ -0,0 +1,191 @@
+/**
+ * Inbound conversion: `MessageReceived` -> a Harness `UserMessage`.
+ *
+ * Content is structured-text by default (red line 6): platform parts without
+ * downloadable local bytes are mapped to plain-text blocks — images/files/audio/video
+ * become `[type: ...]` placeholders instead of raw platform JSON. Conversation
+ * metadata (channel / sender / message id) is folded into a configurable text
+ * prefix so the model can still tell where a message came from.
+ *
+ * WX5 attachment path: when an image part carries `localData` (the adapter
+ * already downloaded + decrypted the bytes), and a `saveImage` hook is supplied,
+ * the converter registers the bytes with the Harness attachment service and emits
+ * a real `ImageBlock` (`{ type: 'image', attachment: ImageAttachmentRef }`) so
+ * the model receives a genuine multimodal image instead of the `[image]`
+ * placeholder. The hook is optional; without it (or on attachment failure) the
+ * converter falls back to the text placeholder so message delivery never breaks.
+ */
+import { createUserMessage, } from '@deepseek-ai/dsh-llm';
+import { mimeHintFromFilename, normalizeMimeHint, } from '@krischoichoi/channel-core';
+/** Convert a channel message-received event into a model-facing user message. */
+export async function toHarnessUserMessage(event, options = {}) {
+    const blocks = [];
+    const includePrefix = options.includeMetadataPrefix ?? false;
+    if (includePrefix) {
+        const prefix = metadataPrefix(event);
+        if (prefix)
+            blocks.push({ type: 'text', text: prefix });
+    }
+    blocks.push(...await partsToBlocks(event.message.content, options));
+    if (blocks.length === 0)
+        blocks.push({ type: 'text', text: '' });
+    return createUserMessage({
+        content: blocks,
+        // Channel inbound messages are authored by the remote human. Marking
+        // them as plugin context makes Harness skip user-only behavior such as
+        // deterministic and LLM-backed session title generation.
+        source: { kind: 'user' },
+    });
+}
+/** Convert platform parts to Harness blocks without changing their order. */
+async function partsToBlocks(parts, options) {
+    const blocks = [];
+    for (const part of parts) {
+        if (part.type === 'image') {
+            const block = await imageBlock(part, options.saveImage);
+            if (block) {
+                blocks.push(block);
+                continue;
+            }
+        }
+        const text = await partsToText([part], { fileStore: options.fileStore });
+        if (text)
+            blocks.push({ type: 'text', text });
+    }
+    return blocks;
+}
+function metadataPrefix(event) {
+    return `[channel=${event.channel} sender=${event.sender.id} message=${event.message.id}] `;
+}
+/**
+ * Map structured parts to a single text line. Never embeds raw payloads.
+ * Image parts with local bytes and a saveImage hook are surfaced via
+ * `onImage` instead of being folded into text; they never contribute a text
+ * placeholder (unless the attachment path is unavailable, in which case they
+ * fall back to the ordinary `[image]` placeholder).
+ */
+export async function partsToText(parts, options = {}) {
+    const segments = [];
+    for (const part of parts) {
+        switch (part.type) {
+            case 'text':
+                segments.push(part.text);
+                break;
+            case 'image': {
+                const block = await imageBlock(part, options.saveImage);
+                if (block) {
+                    options.onImage?.(block);
+                }
+                else {
+                    segments.push(part.alt ? `[image: ${part.alt}]` : part.url ? `[image: ${part.url}]` : '[image]');
+                }
+                break;
+            }
+            case 'file':
+                segments.push((await storedDescriptor(part, options.fileStore)) ??
+                    (part.name ? `[file: ${part.name}]` : part.url ? `[file: ${part.url}]` : '[file]'));
+                break;
+            case 'audio':
+                segments.push((await storedDescriptor(part, options.fileStore)) ??
+                    (part.durationMs !== undefined ? `[audio: ${part.durationMs}ms]` : '[audio]'));
+                break;
+            case 'video':
+                segments.push((await storedDescriptor(part, options.fileStore)) ??
+                    (part.durationMs !== undefined ? `[video: ${part.durationMs}ms]` : '[video]'));
+                break;
+            case 'location':
+                segments.push(`[location: ${part.latitude},${part.longitude}]`);
+                break;
+            case 'card':
+                segments.push(`[card: ${part.kind}]`);
+                break;
+            case 'unsupported':
+                segments.push('[unsupported content]');
+                break;
+        }
+    }
+    return segments.join('');
+}
+/**
+ * Produce an image content block when the part carries local bytes and a
+ * saveImage hook commits them. A media type is inferred from `mimeType`
+ * (or the data URI / URL extension) and accepted only when it maps to a
+ * supported raster type; otherwise the bytes are committed as-is and the
+ * attachment service performs final validation. Any failure returns undefined
+ * so the caller falls back to the text placeholder (never breaks delivery).
+ */
+async function imageBlock(part, saveImage) {
+    if (!saveImage || !part.localData || part.localData.byteLength === 0)
+        return undefined;
+    const mediaType = inferImageMediaType(part);
+    if (!mediaType)
+        return undefined;
+    try {
+        const ref = await saveImage({
+            data: part.localData,
+            mediaType,
+            name: part.alt,
+        });
+        return { type: 'image', attachment: ref };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Infer a raster media type from a part's mimeType / url / dataUri. */
+function inferImageMediaType(part) {
+    const candidate = normalizeMimeHint(part.mimeType)
+        ?? normalizeMimeHint(mimeFromDataUri(part.dataUri))
+        ?? mimeHintFromFilename(part.url);
+    if (!candidate)
+        return undefined;
+    const normalized = candidate.split(';')[0].trim().toLowerCase();
+    switch (normalized) {
+        case 'image/png':
+        case 'image/jpeg':
+        case 'image/jpg':
+            return normalized === 'image/jpg' ? 'image/jpeg' : normalized;
+        case 'image/webp':
+        case 'image/gif':
+            return normalized;
+        default:
+            return undefined;
+    }
+}
+function mimeFromDataUri(dataUri) {
+    if (!dataUri)
+        return undefined;
+    const m = /^data:([^;,]+)/.exec(dataUri);
+    return m?.[1];
+}
+/**
+ * Render a stored file/audio/video descriptor line when the optional
+ * `fileStore` hook persists the part's local bytes. Returns `undefined`
+ * (fall back to the placeholder) on no local bytes, a missing hook, an
+ * unrecognized result, or a hook failure — delivery never breaks.
+ */
+async function storedDescriptor(part, fileStore) {
+    if (!fileStore || !part.localData || part.localData.byteLength === 0)
+        return undefined;
+    try {
+        const descriptor = await fileStore(part);
+        return descriptor ? renderDescriptor(descriptor) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function renderDescriptor(asset) {
+    const mime = asset.mimeType ? ' ' + asset.mimeType : '';
+    const readable = asset.readable ? ' readable' : '';
+    return `[attachment ${asset.attachmentId} ${asset.name}${mime} ${humanSize(asset.bytes)}${readable}]`;
+}
+function humanSize(bytes) {
+    if (bytes < 1024)
+        return bytes + ' B';
+    const kb = bytes / 1024;
+    if (kb < 1024)
+        return kb.toFixed(1) + ' KB';
+    return (kb / 1024).toFixed(1) + ' MB';
+}
+//# sourceMappingURL=message-converter.js.map

package/lib/message-converter.js.map

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