@borgee/agents-host 0.2.2 → 0.2.26

package/dist/context/prompt.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderKind } from '../types.js';
+import type { PreparedPromptContext, ProviderKind } from '../types.js';
 /**
  * Builds the per-turn prompt. Conversation memory is intentionally NOT
  * assembled here: each provider's CLI client resumes a native per-channel
@@ -12,4 +12,7 @@ export declare function buildPrompt(params: {
     channelId: string;
     incomingAuthorId: string;
     incomingContent: string;
+    incomingEventKind?: string;
+    incomingMessageType?: string;
+    promptContext?: PreparedPromptContext;
 }): string;

package/dist/context/prompt.js

@@ -1,5 +1,165 @@
+import { AWAITING_USER_CONTROL_PREFIX } from '../providers/awaiting-user.js';
 function providerLabel(provider) {
-    return provider === 'copilot' ? 'GitHub Copilot' : 'Claude';
+    if (provider === 'copilot') {
+        return 'GitHub Copilot';
+    }
+    if (provider === 'codex') {
+        return 'Codex';
+    }
+    return 'Claude';
+}
+function buildSkillRuntimePromptLines(context) {
+    if (!context?.skillRuntime) {
+        return [];
+    }
+    return [
+        '',
+        'Read-only local skill runtime bootstrap is available for this turn.',
+        `Channel context payload: ${context.channelContextPayloadPath}`,
+        `Skill guide: ${context.skillRuntime.skillMarkdownPath}`,
+        `Node CLI: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --print-bootstrap`,
+        `Python CLI: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --print-bootstrap`,
+        'These CLIs are local-only, may only access the loopback gateway described below, must not mutate files or the local environment, and may only send auxiliary collaboration messages when that gateway surface is explicitly advertised below.',
+    ];
+}
+function buildLocalhostGatewayPromptLines(context) {
+    if (!context?.localhostGateway) {
+        return [];
+    }
+    if (!context.gatewayAuthPath) {
+        return [];
+    }
+    const lines = [
+        '',
+        'A loopback-only localhost gateway is available for this turn.',
+        'Use the packaged local CLI with the existing --context payload to access the documented gateway surface.',
+        `Gateway auth sidecar for this turn: ${context.gatewayAuthPath}`,
+    ];
+    const isTaskAssignmentThread = context.taskAssignmentContext?.active === true;
+    if (!context.skillRuntime) {
+        return lines;
+    }
+    lines.push('The read-only gateway commands listed in this prompt are already authorized for this turn and may be executed directly.', 'Do not ask the user for permission before using the read-only gateway commands listed below.', 'If the user asks about channel history, visible participants, or your current agent identity, run the relevant read command first and answer from its result instead of speculating about authorization.', `Node gateway checks: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --health`, `Node channel bootstrap: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-bootstrap`, `Node agent identity: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-me`, `Node channel history: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-history --limit 20`, `Python gateway checks: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --health`, `Python channel bootstrap: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-bootstrap`, `Python agent identity: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-me`, `Python channel history: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-history --limit 20`);
+    if (isTaskAssignmentThread) {
+        lines.push('Task-collection commands remain disabled inside this task thread; use the parent channel for create/list task operations.', `Node get current thread task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task`, `Node update current thread task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`, `Python get current thread task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task`, `Python update current thread task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`);
+    }
+    else {
+        lines.push(`Node create task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --create-task --title "<title>" [--description "<description>"] [--assignee-id "<assignee-id>"]`, `Node list tasks: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-tasks`, `Node get task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task --task-id "<task-id>"`, `Node update task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task --task-id "<task-id>" [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`, `Python create task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --create-task --title "<title>" [--description "<description>"] [--assignee-id "<assignee-id>"]`, `Python list tasks: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-tasks`, `Python get task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task --task-id "<task-id>"`, `Python update task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task --task-id "<task-id>" [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`);
+    }
+    if (context.localhostGateway.collaboration?.enabled &&
+        (context.collaborationTurnMode ?? 'ordinary') === 'ordinary') {
+        const turnExecutionArgument = context.collaborationTurnExecutionId
+            ? ` --turn-execution-id ${context.collaborationTurnExecutionId}`
+            : '';
+        lines.push('Auxiliary collaboration commands are available for this turn. Use them only for short targeted escalation, mention, or reply notices, never for the main final answer body.', 'When you need the host-private in-flight draft for this live collaboration turn, use the dedicated read-draft command rather than inspecting public channel messages.', 'When --list-users is listed below, it is a read-only command for this turn and may be executed directly without asking for permission.', 'When the user explicitly asks you to mention, ping, notify, or send a short note to another visible participant, use the dedicated send-mention command directly and include a visible <@targetId> token in the body.', 'If the user asks you to @ another agent now, send the short auxiliary mention first, then confirm what you sent.', 'If the user says "the other agent" and only one other visible agent is present, resolve that target from --list-users and then use --send-mention with that participant id.', 'If collaboration with another visible agent would help, use these auxiliary commands to send a short targeted mention or reply-thread note yourself rather than asking AgentsHost to orchestrate a special protocol.', `Node private draft snapshot: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --read-draft`, `Node user directory: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-users`, `Node auxiliary mention: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --send-mention user-id --body "Need review from <@user-id>"`, `Node reply thread notice: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --send-message --body "Following up here" --reply-to message-id`, `Python private draft snapshot: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --read-draft`, `Python user directory: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-users`, `Python auxiliary mention: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --send-mention user-id --body "Need review from <@user-id>"`, `Python reply thread notice: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --send-message --body "Following up here" --reply-to message-id`);
+    }
+    return lines;
+}
+function buildTaskAssignmentPromptLines(params) {
+    const isTaskAssignmentTurn = params.incomingMessageType?.trim() === 'task_assignment';
+    const taskAssignmentContext = params.promptContext?.taskAssignmentContext;
+    if (!isTaskAssignmentTurn && taskAssignmentContext?.active !== true) {
+        return [];
+    }
+    const lines = isTaskAssignmentTurn
+        ? [
+            'This message is a task assignment.',
+            'The assigned work belongs to this thread. Do the work here.',
+        ]
+        : [
+            'This thread is continuing an existing task assignment.',
+            'Keep the main work in this thread.',
+        ];
+    if (taskAssignmentContext?.currentTaskId) {
+        lines.push(`Current assigned task id: ${taskAssignmentContext.currentTaskId}.`);
+        lines.push('Inside this task thread, the packaged Node and Python CLIs may omit --task-id for --get-task and --update-task because the current task id is already persisted in the injected thread context.');
+        if (params.promptContext?.taskWorkspace) {
+            lines.push(`Task-scoped writable workspace root: ${params.promptContext.taskWorkspace.rootPath}.`);
+            lines.push('This writable workspace is local to agents-host for the current task thread. It does not imply that the target repository has already been checked out there.');
+        }
+    }
+    else if (taskAssignmentContext?.active === true) {
+        lines.push('No current task id is persisted in the injected thread context for this task thread.');
+        lines.push('Inside this task thread, shorthand --get-task/--update-task calls without --task-id use an agents-host local fallback that scans visible parent-channel tasks for this thread; pass --task-id explicitly if that fallback cannot resolve a unique task.');
+    }
+    lines.push('Set the task status to in_progress when you start.', 'When you finish, set the task status to in_review and return your normal final response in this thread.', 'Do not use an auxiliary message command for the main completion report; reserve it for intentional targeted escalation or cross-channel notification.', 'Do not use create/list task operations inside this task thread; those remain parent-channel operations.', 'Do not move the main work back to the parent channel.');
+    return lines;
+}
+function buildInboundMetadataLines(params) {
+    return [
+        `Incoming transport event kind: ${params.incomingEventKind?.trim() || 'message'}`,
+        `Incoming semantic message type: ${params.incomingMessageType?.trim() || 'default'}`,
+        ...buildTaskAssignmentPromptLines(params),
+    ];
+}
+function describeIdentity(identity) {
+    if (!identity) {
+        return null;
+    }
+    const name = identity.displayName?.trim();
+    const label = name && name.length > 0 ? `${name} (${identity.id})` : identity.id;
+    return `${label}, kind=${identity.kind}`;
+}
+function buildTurnControlPromptLines(context) {
+    if (!context) {
+        return [
+            `Only when you need host-local turn control, append exactly one final non-empty line starting with ${AWAITING_USER_CONTROL_PREFIX}.`,
+            `For ordinary blocked-on-human turns, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"awaiting-user","question":"<short question>","reason":"<short reason>"}`,
+            'Do not emit multiple control lines, and do not use a control footer for ordinary answers.',
+        ];
+    }
+    if (context.collaborationTurnMode === 'protocol-managed' && context.protocol) {
+        const selfIdentity = describeIdentity(context.grounding?.self);
+        const incomingIdentity = describeIdentity(context.grounding?.incomingAuthor);
+        const peerIdentity = describeIdentity(context.grounding?.peer);
+        return [
+            `Protocol-managed collaboration is already active for this turn. Your host-managed role is ${context.protocol.role}, and your target peer is ${context.protocol.targetPeerId}.`,
+            ...(selfIdentity ? [`Your self identity for this turn: ${selfIdentity}.`] : []),
+            ...(peerIdentity ? [`Your peer for this turn: ${peerIdentity}.`] : []),
+            ...(incomingIdentity ? [`The incoming author for this turn is ${incomingIdentity}.`] : []),
+            'The host will deliver the visible protocol reply body for you; you only decide the body plus exactly one control footer.',
+            'Do not use auxiliary collaboration send commands during this turn, even if other turns can use them.',
+            'Do not attempt a localhost gateway message post during this turn.',
+            `When handing off to the named peer, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"continue-to-peer"}`,
+            `When finishing locally, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"conclude-locally"}`,
+            `If you are blocked on the human instead, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"awaiting-user","question":"<short question>","reason":"<short reason>"}`,
+            'Do not emit multiple control lines, and do not use start-protocol while host-managed collaboration is already active.',
+        ];
+    }
+    if (context.collaborationTurnMode === 'silent-kickoff' && context.kickoff) {
+        const kickoff = context.kickoff;
+        const otherParticipantId = kickoff.participantIds.find((participantId) => participantId !== kickoff.issuerId);
+        const selfIdentity = describeIdentity(context.grounding?.self);
+        const incomingIdentity = describeIdentity(context.grounding?.incomingAuthor);
+        const peerIdentity = describeIdentity(context.grounding?.peer);
+        const participantSummary = context.grounding?.participants
+            ?.map((participant) => describeIdentity(participant))
+            .filter((participant) => participant != null)
+            .join('; ');
+        return [
+            `Silent protocol kickoff evaluation is active for anchor ${kickoff.anchorMessageId}. The issuer is ${kickoff.issuerId}${otherParticipantId ? ` and the other participant is ${otherParticipantId}` : ''}.`,
+            ...(context.grounding?.hostRecognizedKickoffCandidate
+                ? [
+                    'The host has already recognized this message as a structurally valid kickoff candidate and is asking you to decide whether host-managed collaboration should start.',
+                ]
+                : []),
+            ...(selfIdentity ? [`Your self identity for this decision: ${selfIdentity}.`] : []),
+            ...(peerIdentity ? [`Your peer candidate for this decision: ${peerIdentity}.`] : []),
+            ...(incomingIdentity
+                ? [`The incoming author for this decision is ${incomingIdentity}.`]
+                : []),
+            ...(participantSummary ? [`Visible kickoff participants: ${participantSummary}.`] : []),
+            'This evaluation is read-only and silent: do not use auxiliary collaboration send commands, and do not draft a user-visible reply body for this turn.',
+            `If the anchor message is genuinely requesting host-managed collaboration between the named agents, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"start-protocol","rounds":<positive integer>}`,
+            'If collaboration should not start, omit the control footer entirely.',
+            'Do not emit multiple control lines.',
+        ];
+    }
+    return [
+        `Only when you need host-local turn control, append exactly one final non-empty line starting with ${AWAITING_USER_CONTROL_PREFIX}.`,
+        `For ordinary blocked-on-human turns, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"awaiting-user","question":"<short question>","reason":"<short reason>"}`,
+        'Do not emit multiple control lines, and do not use a control footer for ordinary answers.',
+    ];
 }
 /**
  * Builds the per-turn prompt. Conversation memory is intentionally NOT
@@ -15,8 +175,17 @@ export function buildPrompt(params) {
         'You are replying inside a shared collaboration channel.',
         'Be concise, helpful, and honest about uncertainty.',
         'Do not claim to have performed actions you did not actually perform.',
+        'Keep the visible reply text concise.',
+        ...buildTurnControlPromptLines(params.promptContext),
         `If the user asks who you are, what powers you, or which backend/provider you use, mention that you are currently running on ${providerLabel(params.provider)}.`,
         `Channel: ${params.channelId}`,
+        ...buildInboundMetadataLines({
+            incomingEventKind: params.incomingEventKind,
+            incomingMessageType: params.incomingMessageType,
+            promptContext: params.promptContext,
+        }),
+        ...buildSkillRuntimePromptLines(params.promptContext),
+        ...buildLocalhostGatewayPromptLines(params.promptContext),
         '',
         `New message from ${params.incomingAuthorId}:`,
         params.incomingContent,

package/dist/context/turn-preparation.d.ts

@@ -0,0 +1,9 @@
+import { type DebugLogger } from '../debug.js';
+import type { PreparedProviderTurnInput, ProviderInput } from '../types.js';
+import { type ChannelContextStore } from './injection.js';
+export declare class ProviderTurnPreparer {
+    private readonly channelContextStore?;
+    private readonly logger;
+    constructor(channelContextStore?: ChannelContextStore | undefined, logger?: DebugLogger);
+    prepare(input: ProviderInput): Promise<PreparedProviderTurnInput>;
+}

package/dist/context/turn-preparation.js

@@ -0,0 +1,106 @@
+import { HostLogger, summarizeError } from '../debug.js';
+import { ChannelContextPreparationError, } from './injection.js';
+import { buildPrompt } from './prompt.js';
+function providerLabel(provider) {
+    if (provider === 'copilot') {
+        return 'Copilot';
+    }
+    if (provider === 'codex') {
+        return 'Codex';
+    }
+    return 'Claude';
+}
+function toPromptContext(channelContext, input) {
+    if (!channelContext && !input.collaboration) {
+        return undefined;
+    }
+    return {
+        ...(channelContext
+            ? {
+                channelContextPayloadPath: channelContext.payloadPath,
+                gatewayAuthPath: channelContext.gatewayAuthPath,
+                skillRuntime: channelContext.skillRuntime,
+                localhostGateway: channelContext.localhostGateway,
+                taskAssignmentContext: channelContext.payload.taskAssignmentContext,
+                taskWorkspace: channelContext.taskWorkspace,
+            }
+            : {}),
+        collaborationTurnExecutionId: input.collaboration?.turnExecutionId,
+        collaborationTurnMode: input.collaboration?.turnMode,
+        kickoff: input.collaboration?.kickoff,
+        protocol: input.collaboration?.protocol,
+        grounding: input.collaboration?.grounding,
+    };
+}
+function resolveProviderSessionRouting(input) {
+    const kickoff = input.collaboration?.kickoff;
+    if (input.collaboration?.turnMode === 'silent-kickoff' && kickoff) {
+        return {
+            key: `${input.channelId}::kickoff::${kickoff.anchorMessageId}`,
+            persistence: 'ephemeral',
+        };
+    }
+    return {
+        key: input.channelId,
+        persistence: 'persistent',
+    };
+}
+export class ProviderTurnPreparer {
+    channelContextStore;
+    logger;
+    constructor(channelContextStore, logger = new HostLogger()) {
+        this.channelContextStore = channelContextStore;
+        this.logger = logger;
+    }
+    async prepare(input) {
+        let channelContext;
+        if (this.channelContextStore) {
+            try {
+                const prepareInput = {
+                    channelId: input.channelId,
+                    collaboration: input.collaboration
+                        ? {
+                            ...input.collaboration,
+                            sendRoutesAllowed: input.collaboration.turnMode !== 'protocol-managed'
+                                && input.collaboration.turnMode !== 'silent-kickoff',
+                        }
+                        : undefined,
+                    ...(input.incomingMessageType !== undefined
+                        ? { incomingMessageType: input.incomingMessageType }
+                        : {}),
+                    ...(input.incomingMessageType !== undefined && input.incomingContent !== undefined
+                        ? { incomingContent: input.incomingContent }
+                        : {}),
+                };
+                channelContext = await this.channelContextStore.prepare(prepareInput);
+            }
+            catch (error) {
+                if (error instanceof ChannelContextPreparationError) {
+                    channelContext = error.partialContext;
+                }
+                this.logger.error(`failed to materialize ${providerLabel(input.provider)} channel context payload; keeping prompt delivery`, {
+                    channelId: input.channelId,
+                    error: summarizeError(error),
+                });
+            }
+        }
+        const promptContext = toPromptContext(channelContext, input);
+        return {
+            channelId: input.channelId,
+            incomingEventKind: input.incomingEventKind,
+            incomingMessageType: input.incomingMessageType,
+            prompt: buildPrompt({
+                agentName: input.agentName,
+                provider: input.provider,
+                channelId: input.channelId,
+                incomingAuthorId: input.incomingAuthorId,
+                incomingContent: input.incomingContent,
+                incomingEventKind: input.incomingEventKind,
+                incomingMessageType: input.incomingMessageType,
+                promptContext,
+            }),
+            promptContext,
+            providerSessionRouting: resolveProviderSessionRouting(input),
+        };
+    }
+}

package/dist/debug.d.ts

@@ -0,0 +1,44 @@
+export interface LoggerLike {
+    log(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export interface DebugLogger {
+    readonly enabled: boolean;
+    error(message: string, details?: unknown): void;
+    debug(message: string, details?: unknown): void;
+    debugError(message: string, details?: unknown): void;
+    childStderr(label: string, summary: ChildStderrSummary): void;
+}
+export interface AgentsHostRuntimeOptions {
+    debug?: boolean;
+    logger?: LoggerLike;
+    logPrefix?: string;
+}
+export interface ChildStderrSummary {
+    bytes: number;
+    lineCount: number;
+}
+export interface SafeErrorSummary {
+    name: string;
+    messageBytes?: number;
+    messageLineCount?: number;
+    code?: number | string;
+    exitCode?: number;
+    signal?: string;
+    stderrBytes?: number;
+    stderrLineCount?: number;
+}
+export declare function resolveAgentsHostDebugMode(cliDebugFlag?: boolean, env?: NodeJS.ProcessEnv): boolean;
+export declare function summarizeChildStderr(chunk: string): ChildStderrSummary;
+export declare function summarizeError(error: unknown): SafeErrorSummary;
+export declare class HostLogger implements DebugLogger {
+    readonly enabled: boolean;
+    private readonly logger;
+    private readonly prefix;
+    constructor(options?: AgentsHostRuntimeOptions);
+    log(message: string, details?: unknown): void;
+    error(message: string, details?: unknown): void;
+    debug(message: string, details?: unknown): void;
+    debugError(message: string, details?: unknown): void;
+    childStderr(label: string, summary: ChildStderrSummary): void;
+}

package/dist/debug.js

@@ -0,0 +1,135 @@
+const DEFAULT_LOG_PREFIX = '[agents-host]';
+export function resolveAgentsHostDebugMode(cliDebugFlag = false, env = process.env) {
+    return cliDebugFlag || env.AGENTS_HOST_DEBUG?.trim() === '1';
+}
+export function summarizeChildStderr(chunk) {
+    if (chunk.length === 0) {
+        return { bytes: 0, lineCount: 0 };
+    }
+    const segments = chunk.split(/\r?\n/u);
+    return {
+        bytes: Buffer.byteLength(chunk, 'utf8'),
+        lineCount: chunk.endsWith('\n') ? segments.length - 1 : segments.length,
+    };
+}
+function asObject(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+function readFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function readNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+export function summarizeError(error) {
+    if (error instanceof Error) {
+        const summary = {
+            name: error.name || 'Error',
+        };
+        if (error.message.length > 0) {
+            const messageSummary = summarizeChildStderr(error.message);
+            summary.messageBytes = messageSummary.bytes;
+            summary.messageLineCount = messageSummary.lineCount;
+        }
+        const errorRecord = asObject(error);
+        const code = readFiniteNumber(errorRecord?.code) ?? readNonEmptyString(errorRecord?.code);
+        if (code !== undefined) {
+            summary.code = code;
+        }
+        const exitCode = readFiniteNumber(errorRecord?.exitCode);
+        if (exitCode !== undefined) {
+            summary.exitCode = exitCode;
+        }
+        const signal = readNonEmptyString(errorRecord?.signal);
+        if (signal !== undefined) {
+            summary.signal = signal;
+        }
+        const stderrBytes = readFiniteNumber(errorRecord?.stderrBytes);
+        if (stderrBytes !== undefined) {
+            summary.stderrBytes = stderrBytes;
+        }
+        const stderrLineCount = readFiniteNumber(errorRecord?.stderrLineCount);
+        if (stderrLineCount !== undefined) {
+            summary.stderrLineCount = stderrLineCount;
+        }
+        return summary;
+    }
+    if (typeof error === 'string') {
+        const summary = summarizeChildStderr(error);
+        return {
+            name: 'NonErrorThrow',
+            messageBytes: summary.bytes,
+            messageLineCount: summary.lineCount,
+        };
+    }
+    return {
+        name: 'NonErrorThrow',
+    };
+}
+function sanitizeDebugDetails(details, seen = new WeakSet()) {
+    if (details instanceof Error) {
+        return summarizeError(details);
+    }
+    if (Array.isArray(details)) {
+        return details.map((item) => sanitizeDebugDetails(item, seen));
+    }
+    const record = asObject(details);
+    if (record === null) {
+        return details;
+    }
+    const prototype = Object.getPrototypeOf(record);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return details;
+    }
+    if (seen.has(record)) {
+        return '[Circular]';
+    }
+    seen.add(record);
+    const sanitized = {};
+    for (const [key, value] of Object.entries(record)) {
+        sanitized[key] = sanitizeDebugDetails(value, seen);
+    }
+    return sanitized;
+}
+function emit(sink, prefix, message, details) {
+    const rendered = `${prefix} ${message}`;
+    if (details === undefined) {
+        sink(rendered);
+        return;
+    }
+    sink(rendered, details);
+}
+export class HostLogger {
+    enabled;
+    logger;
+    prefix;
+    constructor(options = {}) {
+        this.enabled = options.debug === true;
+        this.logger = options.logger ?? console;
+        this.prefix = options.logPrefix?.trim() || DEFAULT_LOG_PREFIX;
+    }
+    log(message, details) {
+        emit(this.logger.log.bind(this.logger), this.prefix, message, details);
+    }
+    error(message, details) {
+        emit(this.logger.error.bind(this.logger), this.prefix, message, details);
+    }
+    debug(message, details) {
+        if (!this.enabled) {
+            return;
+        }
+        this.log(message, details);
+    }
+    debugError(message, details) {
+        if (!this.enabled) {
+            return;
+        }
+        this.error(message, details === undefined ? undefined : sanitizeDebugDetails(details));
+    }
+    childStderr(label, summary) {
+        if (!this.enabled) {
+            return;
+        }
+        this.error(`${label} summary`, summary);
+    }
+}

package/dist/gateway/localhost-gateway.d.ts

@@ -0,0 +1,52 @@
+import type { ChatControlPlane } from '../chat/chat-control-plane.js';
+import type { DebugLogger } from '../debug.js';
+import type { InternalPolicyMode } from '../compatibility-gates.js';
+import type { CollaborationDraftSnapshot } from '../types.js';
+import type { LocalhostGatewayContextPublisher } from '../context/injection.js';
+import { type ConnectionsStateStore } from '../connections-state-store.js';
+import type { AuthorizationAuditSinkLike } from '../policy/authorization-audit.js';
+export declare const LOCALHOST_GATEWAY_HISTORY_LIMIT = 20;
+export declare const LOCALHOST_GATEWAY_COLLABORATION_BODY_LIMIT_BYTES = 512;
+export declare const LOCALHOST_GATEWAY_COLLABORATION_BODY_MAX_WORDS = 12;
+export declare const LOCALHOST_GATEWAY_COLLABORATION_TARGET_COOLDOWN_MS = 5000;
+export interface GatewayCollaborationSendAuthorizationInput {
+    channelId: string;
+    turnExecutionId: string;
+    mentions: string[];
+    replyToId?: string;
+}
+export interface GatewayCollaborationSendAuthorizationResult {
+    ok: boolean;
+    statusCode: number;
+    error?: string;
+    commit?: () => void;
+    rollback?: () => void;
+}
+export interface GatewayCollaborationDraftReadInput {
+    channelId: string;
+    turnExecutionId: string;
+}
+export interface LocalhostGatewayController {
+    readonly enabled: boolean;
+    readonly contextPublisher?: LocalhostGatewayContextPublisher;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+interface CreateLocalhostGatewayOptions {
+    gateEnabled: boolean;
+    collaborationEnabled?: boolean;
+    tokenBindingGateEnabled?: boolean;
+    policyAuditGateEnabled?: boolean;
+    policyMode?: InternalPolicyMode;
+    controlPlane: ChatControlPlane;
+    stateRootDir?: string;
+    resolveStableAgentId?: () => string | undefined;
+    tokenBindingStore?: ConnectionsStateStore;
+    logger?: DebugLogger;
+    tokenFactory?: () => string;
+    auditSink?: AuthorizationAuditSinkLike;
+    authorizeCollaborationSend?: (input: GatewayCollaborationSendAuthorizationInput) => GatewayCollaborationSendAuthorizationResult;
+    readCollaborationDraft?: (input: GatewayCollaborationDraftReadInput) => CollaborationDraftSnapshot | null;
+}
+export declare function createLocalhostGatewayController(options: CreateLocalhostGatewayOptions): LocalhostGatewayController;
+export {};