@borgee/agents-host 0.2.35 → 0.2.44

package/dist/context/prompt.js

@@ -3,6 +3,7 @@ import { buildAttentionSummaryLines } from './attention.js';
 import { buildCollaborationCapabilityDeclarationSummaryLines, buildMissedCollaborationDiagnosticSummaryLines, } from './collaboration-capabilities-diagnostics.js';
 import { buildCollaborationOutcomeSummaryLines } from './collaboration-outcome.js';
 import { MAIN_SESSION_DELEGATION_LINES } from './main-session-delegation.js';
+import { buildSkillManualLines } from './skill-manual.js';
 import { buildTaskThreadCollaborationSummaryLines } from './task-thread-collaboration.js';
 function providerLabel(provider) {
     if (provider === 'copilot') {
@@ -13,50 +14,39 @@ function providerLabel(provider) {
     }
     return 'Claude';
 }
-function buildSkillRuntimePromptLines(context) {
-    if (!context?.skillRuntime) {
+// Claude and Codex name the manual once on their session-scoped surfaces. Copilot has no
+// session-scoped surface — this prompt is its only model-facing text — so for Copilot alone the
+// pointer rides every turn.
+function buildSkillManualPromptLines(provider, context) {
+    if (provider !== 'copilot' || !context?.skillRuntime || !context.gatewayCredentialPath) {
         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.',
-    ];
+    return ['', ...buildSkillManualLines(context.skillRuntime)];
 }
+// Only the facts that change from turn to turn: which credential file authorizes this turn, which
+// task grammar the thread shape licenses, and whether the collaboration commands can be reached at
+// all. Everything else a model needs to invoke the CLI is in the manual, which does not change.
 function buildLocalhostGatewayPromptLines(context) {
     if (!context?.localhostGateway) {
         return [];
     }
-    if (!context.gatewayAuthPath) {
+    if (!context.gatewayCredentialPath) {
         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;
+    const lines = ['', `Gateway credential file for this turn: ${context.gatewayCredentialPath}`];
     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>"]`, `Node set current thread task property: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --set-property "<key>=<value>"`, `Node delete current thread task property: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --delete-property "<key>"`, `Python set current thread task property: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --set-property "<key>=<value>"`, `Python delete current thread task property: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --delete-property "<key>"`, 'Task property keys are a closed set: link.pr (the PR implementing the task) and link.issue (the originating issue). agent.session_id is written by agents-host — do not set it. One key per call; pass <key>=<value> as one argument.');
-    }
-    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 read task thread history: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-task-history --task-id "<task-id>" --limit 20`, `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 read task thread history: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-task-history --task-id "<task-id>" --limit 20`, `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>"]`, `Node set task property: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --set-property "<key>=<value>" --task-id "<task-id>"`, `Node delete task property: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --delete-property "<key>" --task-id "<task-id>"`, `Python set task property: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --set-property "<key>=<value>" --task-id "<task-id>"`, `Python delete task property: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --delete-property "<key>" --task-id "<task-id>"`, 'Task property keys are a closed set: link.pr (the PR implementing the task) and link.issue (the originating issue). agent.session_id is written by agents-host — do not set it. One key per call; pass <key>=<value> as one argument.');
+    lines.push(context.taskAssignmentContext?.active === true
+        ? 'This turn runs inside a task assignment thread.'
+        : 'This turn runs in a parent channel, not a task thread.');
+    const collaborationLive = context.localhostGateway.collaboration?.enabled === true
+        && (context.collaborationTurnMode ?? 'ordinary') === 'ordinary';
+    if (!collaborationLive) {
+        lines.push('Collaboration commands are not available this turn.');
     }
-    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`);
+    else if (context.collaborationTurnExecutionId) {
+        lines.push(`Pass --turn-execution-id ${context.collaborationTurnExecutionId} on send, mention and draft.`);
     }
     return lines;
 }
@@ -77,7 +67,6 @@ function buildTaskAssignmentPromptLines(params) {
         ];
     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.');
@@ -85,9 +74,8 @@ function buildTaskAssignmentPromptLines(params) {
     }
     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.');
+    lines.push('Return your normal final response in this thread, and do not move the main work back to the parent channel.');
     return lines;
 }
 function buildInboundMetadataLines(params) {
@@ -247,7 +235,7 @@ export function buildPrompt(params) {
             const lines = buildMissedCollaborationDiagnosticSummaryLines(params.promptContext?.missedCollaborationDiagnostic);
             return lines.length > 0 ? ['', ...lines] : [];
         })(),
-        ...buildSkillRuntimePromptLines(params.promptContext),
+        ...buildSkillManualPromptLines(params.provider, params.promptContext),
         ...buildLocalhostGatewayPromptLines(params.promptContext),
         '',
         `New message from ${params.incomingAuthorId}:`,

package/dist/context/skill-manual.d.ts

@@ -0,0 +1,13 @@
+import type { SkillRuntimeBootstrapMetadata } from '../types.js';
+/**
+ * What every model-facing surface says about the packaged CLI: what it is, where its manual is, and
+ * that the manual has to be opened before acting. Nothing else about the CLI is stated on a host
+ * surface — the manual is self-contained, so the invocation grammar, the command inventory, the
+ * limits and the credential-file rules have one home that cannot drift from the implementations.
+ *
+ * The authorization sentence is written against the credential file rather than against "this turn"
+ * because the surfaces disagree about scope: the per-turn prompt is turn-scoped while Claude's
+ * session append and Codex's projected document are session-scoped, and only the per-turn prompt
+ * knows whether a credential file exists.
+ */
+export declare function buildSkillManualLines(skillRuntime: SkillRuntimeBootstrapMetadata): string[];

package/dist/context/skill-manual.js

@@ -0,0 +1,18 @@
+/**
+ * What every model-facing surface says about the packaged CLI: what it is, where its manual is, and
+ * that the manual has to be opened before acting. Nothing else about the CLI is stated on a host
+ * surface — the manual is self-contained, so the invocation grammar, the command inventory, the
+ * limits and the credential-file rules have one home that cannot drift from the implementations.
+ *
+ * The authorization sentence is written against the credential file rather than against "this turn"
+ * because the surfaces disagree about scope: the per-turn prompt is turn-scoped while Claude's
+ * session append and Codex's projected document are session-scoped, and only the per-turn prompt
+ * knows whether a credential file exists.
+ */
+export function buildSkillManualLines(skillRuntime) {
+    return [
+        "A packaged local CLI reads this Borgee channel and acts on its tasks: channel history, visible participants, this channel's tasks and their properties, and short auxiliary mentions.",
+        `Read its manual at ${skillRuntime.skillMarkdownPath} before you act on this channel; you cannot form a working invocation without it.`,
+        'Every command the manual documents is already authorized on a turn whose prompt names a gateway credential file. Run them directly and do not ask the user for permission first.',
+    ];
+}

package/dist/context/turn-preparation.js

@@ -1,4 +1,5 @@
 import { HostLogger, summarizeError } from '../debug.js';
+import { buildHostedIncomingContentText, buildHostedTurnContentParts } from '../hosted-turn-content.js';
 import { ChannelContextPreparationError, } from './injection.js';
 import { buildPrompt } from './prompt.js';
 function providerLabel(provider) {
@@ -24,7 +25,7 @@ function toPromptContext(channelContext, input) {
         ...(channelContext
             ? {
                 channelContextPayloadPath: channelContext.payloadPath,
-                gatewayAuthPath: channelContext.gatewayAuthPath,
+                gatewayCredentialPath: channelContext.gatewayCredentialPath,
                 skillRuntime: channelContext.skillRuntime,
                 localhostGateway: channelContext.localhostGateway,
                 taskAssignmentContext: channelContext.payload.taskAssignmentContext,
@@ -75,6 +76,12 @@ export class ProviderTurnPreparer {
         this.logger = logger;
     }
     async prepare(input) {
+        const incomingParts = input.incomingParts ?? buildHostedTurnContentParts({
+            text: input.incomingContent,
+        });
+        const incomingContent = incomingParts.length > 0
+            ? buildHostedIncomingContentText(incomingParts)
+            : input.incomingContent;
         let channelContext;
         if (this.channelContextStore) {
             try {
@@ -97,8 +104,8 @@ export class ProviderTurnPreparer {
                     ...(input.incomingMessageType !== undefined
                         ? { incomingMessageType: input.incomingMessageType }
                         : {}),
-                    ...(input.incomingMessageType !== undefined && input.incomingContent !== undefined
-                        ? { incomingContent: input.incomingContent }
+                    ...(input.incomingMessageType !== undefined && incomingContent !== undefined
+                        ? { incomingContent }
                         : {}),
                 };
                 channelContext = await this.channelContextStore.prepare(prepareInput);
@@ -116,6 +123,8 @@ export class ProviderTurnPreparer {
         const promptContext = toPromptContext(channelContext, input);
         return {
             channelId: input.channelId,
+            incomingContent,
+            incomingParts,
             incomingEventKind: input.incomingEventKind,
             incomingMessageType: input.incomingMessageType,
             prompt: buildPrompt({
@@ -123,7 +132,7 @@ export class ProviderTurnPreparer {
                 provider: input.provider,
                 channelId: input.channelId,
                 incomingAuthorId: input.incomingAuthorId,
-                incomingContent: input.incomingContent,
+                incomingContent,
                 incomingEventKind: input.incomingEventKind,
                 incomingMessageType: input.incomingMessageType,
                 promptContext,

package/dist/gateway/localhost-gateway.js

@@ -655,8 +655,14 @@ class LoopbackLocalhostGatewayController {
         this.recordAudit('authorized', 200, decision.path, method ?? 'PUT', decision.binding);
     }
     async loadCurrentThreadTask(binding) {
+        // Only a task-thread binding has a current task at all. Without that context the scan below
+        // would list every visible channel's tasks to conclude what the binding already says, so the
+        // parent-channel answer is given here instead of after an O(channels x tasks) sweep.
+        if (binding.payload?.taskAssignmentContext?.active !== true) {
+            throw new GatewayHttpError(404, { error: 'not_found' }, 'not-found');
+        }
         let task;
-        const preferredTaskId = binding.payload?.taskAssignmentContext?.currentTaskId;
+        const preferredTaskId = binding.payload.taskAssignmentContext.currentTaskId;
         try {
             task = await findTaskForThread(this.controlPlane, binding.channelId, preferredTaskId);
         }
@@ -899,17 +905,19 @@ function mapGatewayControlPlaneError(error, fallbackReason) {
             case 'bpp.channel_id_required':
             case 'bpp.task_id_required':
                 return new GatewayHttpError(400, { error: 'bad_request' }, 'bad-request');
-            // An unregistered key or an oversized value is the caller's own mistake.
-            // Falling through to 502 would tell the agent the server is broken, and it
-            // would retry the same bad call instead of correcting it.
+            // An unregistered key, an oversized value or a status outside the enum is the
+            // caller's own mistake. Falling through to 502 would tell the agent the server
+            // is broken, and it would retry the same bad call instead of correcting it.
             case 'bpp.task_property_key_unknown':
                 return new GatewayHttpError(400, { error: 'unknown_property_key' }, 'bad-request');
             case 'bpp.task_property_value_too_long':
                 return new GatewayHttpError(400, { error: 'property_value_too_long' }, 'bad-request');
-            // A distinct body, not the bare `not_found` the other routes use: the CLI
-            // reads that one on a current-task request as "the thread's task could not
-            // be resolved" and tells the agent to pass --task-id, which is the wrong
-            // correction for a key that simply was not set.
+            case 'bpp.task_invalid_status':
+                return new GatewayHttpError(400, { error: 'invalid_status' }, 'bad-request');
+            // A distinct body, not the bare `not_found` the other routes use: on a
+            // current-task property request `not_found` means the thread's own task
+            // could not be resolved, and "pass the task id" is the wrong correction
+            // for a key that simply was not set.
             case 'bpp.task_property_not_found':
                 return new GatewayHttpError(404, { error: 'property_not_found' }, 'not-found');
             default:

package/dist/hosted-turn-content.d.ts

@@ -0,0 +1,15 @@
+import type { HostedMessageAttachment, HostedTurnContentPart } from './types.js';
+type CanonicalHostedMessageAttachment = HostedMessageAttachment & {
+    kind: NonNullable<HostedMessageAttachment['kind']>;
+};
+export declare function normalizeHostedMessageAttachment(attachment: HostedMessageAttachment): CanonicalHostedMessageAttachment;
+export declare function classifyHostedAttachmentKind(contentType: string | undefined): Extract<HostedTurnContentPart, {
+    type: 'image' | 'file';
+}>['type'];
+export declare function buildHostedTurnContentParts(input: {
+    text?: string;
+    attachments?: readonly HostedMessageAttachment[];
+}): HostedTurnContentPart[];
+export declare function extractHostedMessageAttachments(parts: readonly HostedTurnContentPart[]): HostedMessageAttachment[];
+export declare function buildHostedIncomingContentText(parts: readonly HostedTurnContentPart[]): string;
+export {};

package/dist/hosted-turn-content.js

@@ -0,0 +1,50 @@
+export function normalizeHostedMessageAttachment(attachment) {
+    return {
+        url: attachment.url,
+        ...(attachment.filename ? { filename: attachment.filename } : {}),
+        contentType: attachment.contentType,
+        kind: attachment.kind ?? classifyHostedAttachmentKind(attachment.contentType),
+        ...(attachment.sizeBytes !== undefined ? { sizeBytes: attachment.sizeBytes } : {}),
+    };
+}
+export function classifyHostedAttachmentKind(contentType) {
+    return contentType?.toLowerCase().startsWith('image/') ? 'image' : 'file';
+}
+export function buildHostedTurnContentParts(input) {
+    const text = input.text?.trim() ?? '';
+    const attachments = input.attachments ?? [];
+    const parts = [];
+    if (text.length > 0) {
+        parts.push({ type: 'text', text });
+    }
+    for (const attachment of attachments) {
+        const normalizedAttachment = normalizeHostedMessageAttachment(attachment);
+        parts.push({
+            type: normalizedAttachment.kind,
+            attachment: normalizedAttachment,
+        });
+    }
+    return parts;
+}
+export function extractHostedMessageAttachments(parts) {
+    return parts.flatMap((part) => ('attachment' in part ? [normalizeHostedMessageAttachment(part.attachment)] : []));
+}
+export function buildHostedIncomingContentText(parts) {
+    const text = parts
+        .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+        .join('\n')
+        .trim();
+    const nonTextParts = parts.filter((part) => part.type === 'image' || part.type === 'file');
+    if (nonTextParts.length === 0) {
+        return text;
+    }
+    const summaryLines = [
+        `[Attachment metadata was received for ${nonTextParts.length} attachment${nonTextParts.length === 1 ? '' : 's'}]`,
+        ...nonTextParts.map((part, index) => {
+            const filename = part.attachment.filename?.trim();
+            return `${index + 1}. ${part.type};${filename ? ` filename: ${filename};` : ''} content type: ${part.attachment.contentType}`;
+        }),
+    ];
+    const summary = summaryLines.join('\n');
+    return text ? `${text}\n\n${summary}` : summary;
+}

package/dist/managed-daemon.d.ts

@@ -95,6 +95,7 @@ export interface ManagedAgentsHostDaemonDeps {
     materialize?: (rootPath: string, spec: LocalConfigGenerateSpec) => Promise<unknown>;
     logger?: Pick<Console, 'log' | 'error'>;
     logPath?: string;
+    platform?: NodeJS.Platform;
 }
 export interface DescribeManagedSpecOptions {
     serverUrl: string;
@@ -192,7 +193,7 @@ export declare function applyManagedSpec(options: ApplyManagedSpecOptions, deps?
 export declare class ManagedAgentsHostDaemon {
     private readonly rootPath;
     private readonly hostConfigPath;
-    private readonly socketPath;
+    private readonly endpoint;
     private readonly createSupervisor;
     private readonly supervisor;
     private readonly loadSpec;
@@ -204,7 +205,7 @@ export declare class ManagedAgentsHostDaemon {
     private requestQueue;
     private started;
     private ready;
-    private ownsSocket;
+    private ownsEndpoint;
     private shutdownRequested;
     private ownedSocketInode;
     constructor(rootPath: string, debug?: boolean, deps?: ManagedAgentsHostDaemonDeps);

package/dist/managed-daemon.js

@@ -8,7 +8,7 @@ import { AgentsHostSupervisor } from './agents-host-supervisor.js';
 import { CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE, COMPATIBILITY_GATES_ENV, createManagedRuntimeSettingsFingerprint, INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveDisabledDefaultCompatibilityGates, resolveManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
 import { DEFAULT_PROVIDER_COMMAND_CONFIG, hasLegacyClaudeOneShotArgs, loadConfigFromEnv, } from './config.js';
 import { loadLocalConfigGenerateSpec, materializeLocalConfig, parseGenerateConfigSpec, resolveLocalConfigLayout, } from './local-config.js';
-import { normalizeManagedRuntimeKey, resolveManagedBootstrapLockPath, resolveManagedDaemonLogPath, resolveManagedDaemonSocketPath, resolveManagedRuntimeRoot, resolveManagedRuntimeSettingsPath, } from './state-paths.js';
+import { normalizeManagedRuntimeKey, resolveManagedBootstrapLockPath, resolveManagedDaemonEndpoint, resolveManagedDaemonLogPath, resolveManagedRuntimeRoot, resolveManagedRuntimeSettingsPath, } from './state-paths.js';
 const MANAGED_ROOT_MODE = 0o700;
 const MANAGED_CONFIG_MODE = 0o600;
 const BOOTSTRAP_LOCK_WAIT_MS = 10_000;
@@ -599,8 +599,11 @@ async function canConnectToSocket(socketPath) {
         socket.once('error', () => finalize(false));
     });
 }
-async function removeStaleControlSocket(socketPath) {
-    const stats = await fs.lstat(socketPath).catch((error) => {
+async function removeStaleControlSocket(endpoint) {
+    if (endpoint.kind === 'named-pipe') {
+        return false;
+    }
+    const stats = await fs.lstat(endpoint.address).catch((error) => {
         if (isNotFoundError(error)) {
             return undefined;
         }
@@ -610,15 +613,15 @@ async function removeStaleControlSocket(socketPath) {
         return false;
     }
     if (stats.isDirectory() || stats.isSymbolicLink()) {
-        throw new Error(`Managed control socket path has an unexpected value: ${socketPath}`);
+        throw new Error(`Managed control socket path has an unexpected value: ${endpoint.address}`);
     }
-    if (await canConnectToSocket(socketPath)) {
+    if (await canConnectToSocket(endpoint.address)) {
         return false;
     }
     if (!stats.isSocket() && !stats.isFile()) {
-        throw new Error(`Managed control socket path has an unexpected value: ${socketPath}`);
+        throw new Error(`Managed control socket path has an unexpected value: ${endpoint.address}`);
     }
-    await fs.rm(socketPath, { force: true });
+    await fs.rm(endpoint.address, { force: true });
     return true;
 }
 function parseDaemonResponse(raw) {
@@ -655,12 +658,12 @@ function isManagedDaemonConnectionError(error) {
         isNodeErrorWithCode(error, 'ECONNRESET'));
 }
 export async function sendManagedDaemonRequest(rootPath, request) {
-    const socketPath = resolveManagedDaemonSocketPath(rootPath);
+    const endpoint = resolveManagedDaemonEndpoint(rootPath);
     const requestTimeoutMs = request.type === 'upsertAgent' || request.type === 'applySpec'
         ? DAEMON_RECONCILE_WAIT_MS
         : DAEMON_READY_WAIT_MS;
     return new Promise((resolveRequest, rejectRequest) => {
-        const socket = createConnection(socketPath);
+        const socket = createConnection(endpoint.address);
         let settled = false;
         let responseBuffer = '';
         const rejectOnce = (error) => {
@@ -681,7 +684,7 @@ export async function sendManagedDaemonRequest(rootPath, request) {
         };
         socket.setEncoding('utf8');
         socket.setTimeout(requestTimeoutMs);
-        socket.once('timeout', () => rejectOnce(new Error(`Timed out talking to managed daemon: ${socketPath}`)));
+        socket.once('timeout', () => rejectOnce(new Error(`Timed out talking to managed daemon: ${endpoint.address}`)));
         socket.once('error', rejectOnce);
         socket.on('data', (chunk) => {
             responseBuffer += chunk;
@@ -790,9 +793,9 @@ async function readReadyManagedDaemonStatus(rootPath, sendRequest) {
 }
 async function waitForManagedDaemonShutdown(rootPath, canConnect) {
     const deadline = Date.now() + DAEMON_READY_WAIT_MS;
-    const socketPath = resolveManagedDaemonSocketPath(rootPath);
+    const endpoint = resolveManagedDaemonEndpoint(rootPath);
     while (Date.now() < deadline) {
-        const listening = await canConnect(socketPath).catch((error) => {
+        const listening = await canConnect(endpoint.address).catch((error) => {
             if (isNodeErrorWithCode(error, 'ENOENT')) {
                 return false;
             }
@@ -1481,7 +1484,7 @@ export async function applyManagedSpec(options, deps = {}) {
 export class ManagedAgentsHostDaemon {
     rootPath;
     hostConfigPath;
-    socketPath;
+    endpoint;
     createSupervisor;
     supervisor;
     loadSpec;
@@ -1493,14 +1496,14 @@ export class ManagedAgentsHostDaemon {
     requestQueue = Promise.resolve();
     started = false;
     ready = false;
-    ownsSocket = false;
+    ownsEndpoint = false;
     shutdownRequested = false;
     ownedSocketInode = null;
     constructor(rootPath, debug = false, deps = {}) {
         const layout = resolveLocalConfigLayout(rootPath);
         this.rootPath = layout.root;
         this.hostConfigPath = layout.hostConfigPath;
-        this.socketPath = resolveManagedDaemonSocketPath(this.rootPath);
+        this.endpoint = resolveManagedDaemonEndpoint(this.rootPath, deps.platform);
         this.createSupervisor =
             deps.createSupervisor ??
                 ((configPath, daemonDebug) => new AgentsHostSupervisor(configPath, { debug: daemonDebug }));
@@ -1535,22 +1538,34 @@ export class ManagedAgentsHostDaemon {
             this.logger.log('[agents-host] managed daemon ready', {
                 rootPath: this.rootPath,
                 hostConfigPath: this.hostConfigPath,
-                socketPath: this.socketPath,
+                socketPath: this.endpoint.address,
             });
         }
         catch (error) {
             this.started = false;
             this.ready = false;
-            await this.stop().catch(() => undefined);
+            try {
+                await this.stop();
+            }
+            catch (cleanupError) {
+                this.logger.error('[agents-host] managed daemon startup cleanup failed', {
+                    rootPath: this.rootPath,
+                    error: cleanupError,
+                });
+            }
             throw error;
         }
     }
     async stop() {
         this.ready = false;
+        let stopError;
         try {
             await this.supervisor.stop();
         }
-        finally {
+        catch (error) {
+            stopError = error;
+        }
+        try {
             await new Promise((resolveStop) => {
                 if (!this.server.listening) {
                     resolveStop();
@@ -1558,17 +1573,38 @@ export class ManagedAgentsHostDaemon {
                 }
                 this.server.close(() => resolveStop());
             });
-            if (this.ownsSocket) {
-                const socketStats = await fs.lstat(this.socketPath).catch(() => undefined);
+            if (this.ownsEndpoint && this.endpoint.kind === 'unix-socket') {
+                const socketStats = await fs.lstat(this.endpoint.address).catch((error) => {
+                    if (isNotFoundError(error)) {
+                        return undefined;
+                    }
+                    throw error;
+                });
                 if (socketStats && socketStats.ino === this.ownedSocketInode) {
-                    await fs.rm(this.socketPath, { force: true }).catch(() => undefined);
+                    await fs.rm(this.endpoint.address, { force: true });
                 }
-                this.ownsSocket = false;
-                this.ownedSocketInode = null;
             }
+        }
+        catch (cleanupError) {
+            if (stopError) {
+                this.logger.error('[agents-host] managed daemon control endpoint cleanup failed', {
+                    rootPath: this.rootPath,
+                    error: cleanupError,
+                });
+            }
+            else {
+                stopError = cleanupError;
+            }
+        }
+        finally {
+            this.ownsEndpoint = false;
+            this.ownedSocketInode = null;
             this.started = false;
             this.shutdownRequested = false;
         }
+        if (stopError) {
+            throw stopError;
+        }
     }
     async listen() {
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -1584,20 +1620,32 @@ export class ManagedAgentsHostDaemon {
                     };
                     this.server.once('error', onError);
                     this.server.once('listening', onListening);
-                    this.server.listen(this.socketPath);
+                    this.server.listen(this.endpoint.address);
                 });
-                await fs.chmod(this.socketPath, MANAGED_CONFIG_MODE);
-                this.ownedSocketInode = (await fs.lstat(this.socketPath)).ino;
-                this.ownsSocket = true;
+                if (this.endpoint.kind === 'unix-socket') {
+                    await fs.chmod(this.endpoint.address, MANAGED_CONFIG_MODE);
+                    this.ownedSocketInode = (await fs.lstat(this.endpoint.address)).ino;
+                }
+                this.ownsEndpoint = true;
                 return;
             }
             catch (error) {
-                if (!isSocketBusyError(error) || !(await removeStaleControlSocket(this.socketPath))) {
+                if (!isSocketBusyError(error)) {
+                    throw error;
+                }
+                if (this.endpoint.kind === 'named-pipe') {
+                    if (await canConnectToSocket(this.endpoint.address)) {
+                        throw error;
+                    }
+                    await delay(DAEMON_READY_RETRY_MS);
+                    continue;
+                }
+                if (!(await removeStaleControlSocket(this.endpoint))) {
                     throw error;
                 }
             }
         }
-        throw new Error(`Unable to bind managed daemon control socket: ${this.socketPath}`);
+        throw new Error(`Unable to bind managed daemon control endpoint: ${this.endpoint.address}`);
     }
     async handleSocket(socket) {
         let buffer = '';

package/dist/providers/claude/adapter.d.ts

@@ -1,10 +1,12 @@
-import type { ProviderAdapter } from '../provider-adapter.js';
+import { type ProviderAdapter } from '../provider-adapter.js';
 import type { ProviderGenerateOptions, ProviderInput, ProviderReply } from '../../types.js';
 import { ProviderTurnPreparer } from '../../context/turn-preparation.js';
 import { ClaudeCliClient } from './cli-client.js';
+export declare const CLAUDE_HOSTED_PROVIDER_CAPABILITIES: import("../provider-adapter.js").ProviderCapabilities;
 export declare class ClaudeProviderAdapter implements ProviderAdapter {
     private readonly cli;
     private readonly turnPreparer;
+    readonly capabilities: import("../provider-adapter.js").ProviderCapabilities;
     constructor(cli: ClaudeCliClient, turnPreparer: ProviderTurnPreparer);
     generateReply(input: ProviderInput, options?: ProviderGenerateOptions): Promise<ProviderReply>;
     dispose(): Promise<void>;

package/dist/providers/claude/adapter.js

@@ -1,7 +1,17 @@
+import { createHostedProviderCapabilities } from '../provider-adapter.js';
 import { createAwaitingUserProgressHandler, parseProviderReply } from '../awaiting-user.js';
+export const CLAUDE_HOSTED_PROVIDER_CAPABILITIES = createHostedProviderCapabilities({
+    imageInputTransport: {
+        source: 'transport-derived',
+        support: 'supported',
+        reason: 'real-media-delivered',
+        delivery: ['blob'],
+    },
+});
 export class ClaudeProviderAdapter {
     cli;
     turnPreparer;
+    capabilities = CLAUDE_HOSTED_PROVIDER_CAPABILITIES;
     constructor(cli, turnPreparer) {
         this.cli = cli;
         this.turnPreparer = turnPreparer;