@borgee/agents-host 0.2.33 → 0.2.44

package/dist/cli-args.d.ts

@@ -85,4 +85,4 @@ export declare function parseCleanupManagedArgs(argv: string[]): ParsedCleanupMa
 export declare function parseApplyManagedArgs(argv: string[]): ParsedApplyManagedArgs;
 /** `update` always installs the latest published release; it takes no options. */
 export declare function assertNoUpdateArgs(argv: string[]): void;
-export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n  agents-host update\n\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)\n  --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\n  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)\n  --copilot-args <args>           Ignored by the Copilot ACP prototype\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for Copilot ACP sessions (default: 2880)\n\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n  update                          Update the globally installed @borgee/agents-host to the latest release\n\nStartup update check:\n  Startup commands print an advisory notice on stderr when a newer release is published.\n  Set AGENTS_HOST_DISABLE_UPDATE_CHECK=1 to turn that check off.\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host generate-config --root ./runtime-root --stdin\n  agents-host update\n";
+export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n  agents-host update\n\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)\n  --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\n  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)\n  --copilot-args <args>           Ignored by the Copilot ACP prototype\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for Copilot ACP sessions (default: 2880)\n  --provider-idle-shutdown-minutes <minutes>\n                                   Shut the shared ACP adapter process down after this much idle\n                                   time and re-spawn it on the next turn; 0 keeps it resident\n                                   (default: 10)\n\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n  update                          Update the globally installed @borgee/agents-host to the latest release\n\nStartup update check:\n  Startup commands print an advisory notice on stderr when a newer release is published.\n  Set AGENTS_HOST_DISABLE_UPDATE_CHECK=1 to turn that check off.\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host generate-config --root ./runtime-root --stdin\n  agents-host update\n";

package/dist/cli-args.js

@@ -15,6 +15,7 @@ export const CLI_FLAG_TO_ENV = {
     'copilot-command': 'COPILOT_COMMAND',
     'copilot-args': 'COPILOT_ARGS',
     'copilot-session-ttl-minutes': 'COPILOT_SESSION_TTL_MINUTES',
+    'provider-idle-shutdown-minutes': 'PROVIDER_IDLE_SHUTDOWN_MINUTES',
 };
 const SINGLE_AGENT_FLAG_NAMES = new Set(Object.keys(CLI_FLAG_TO_ENV));
 const FLAGS_ALLOWING_DASH_PREFIX_VALUE = new Set(['claude-args', 'codex-args', 'copilot-args']);
@@ -512,6 +513,10 @@ Single-agent agent options:
   --copilot-args <args>           Ignored by the Copilot ACP prototype
   --copilot-session-ttl-minutes <minutes>
                                    Idle session TTL for Copilot ACP sessions (default: 2880)
+  --provider-idle-shutdown-minutes <minutes>
+                                   Shut the shared ACP adapter process down after this much idle
+                                   time and re-spawn it on the next turn; 0 keeps it resident
+                                   (default: 10)
 
 Command summary:
   start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)

package/dist/compatibility-gates.d.ts

@@ -13,6 +13,7 @@ export declare const COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE =
 export declare const TOKEN_BINDING_COMPATIBILITY_GATE = "token-binding";
 export declare const POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE = "policy-audit-enforcement";
 export declare const MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE = "managed-runtime-convergence";
+export declare const PROVIDER_IDLE_SHUTDOWN_COMPATIBILITY_GATE = "provider-idle-shutdown";
 export declare const COMPATIBILITY_GATES_ENV = "AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES";
 export declare const INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV = "AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES";
 export declare const INTERNAL_POLICY_MODE_ENV = "AGENTS_HOST_INTERNAL_POLICY_MODE";

package/dist/compatibility-gates.js

@@ -14,6 +14,7 @@ export const COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE = 'collab
 export const TOKEN_BINDING_COMPATIBILITY_GATE = 'token-binding';
 export const POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE = 'policy-audit-enforcement';
 export const MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE = 'managed-runtime-convergence';
+export const PROVIDER_IDLE_SHUTDOWN_COMPATIBILITY_GATE = 'provider-idle-shutdown';
 export const COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES';
 export const INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES';
 export const INTERNAL_POLICY_MODE_ENV = 'AGENTS_HOST_INTERNAL_POLICY_MODE';
@@ -30,6 +31,7 @@ export const DEFAULT_INTERNAL_COMPATIBILITY_GATES = Object.freeze([
     LOCALHOST_GATEWAY_COMPATIBILITY_GATE,
     MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE,
     POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE,
+    PROVIDER_IDLE_SHUTDOWN_COMPATIBILITY_GATE,
     SKILL_RUNTIME_COMPATIBILITY_GATE,
     TASK_THREAD_COLLABORATION_CONTRACT_COMPATIBILITY_GATE,
     TOKEN_BINDING_COMPATIBILITY_GATE,

package/dist/config.d.ts

@@ -1,6 +1,8 @@
 import type { AgentsHostConfig, ProviderCommandConfig, ProviderKind } from './types.js';
-export declare const MAX_COPILOT_SESSION_TTL_MINUTES: number;
+export declare const MAX_TIMER_DELAY_MINUTES: number;
 export declare const DEFAULT_COPILOT_SESSION_TTL_MINUTES: number;
+export declare const PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES = 0;
+export declare const DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES = 10;
 export declare const DEFAULT_CLAUDE_COMMAND = "claude-agent-acp";
 export declare const LEGACY_CLAUDE_COMMAND = "claude";
 export declare const LEGACY_CLAUDE_ONE_SHOT_ARGS: readonly ["--print", "--permission-mode", "bypassPermissions"];
@@ -10,6 +12,7 @@ export declare function optionalNonEmptyString(value: unknown, fieldName: string
 export declare function parseArgs(value: string): string[];
 export declare function optionalStringArray(value: unknown, fieldName: string, sourceLabel: string): string[] | undefined;
 export declare function parseCopilotSessionTtlMinutesValue(value: unknown, sourceLabel: string): number;
+export declare function parseProviderIdleShutdownMinutesValue(value: unknown, sourceLabel: string): number;
 export declare function resolveProvider(rawValue: string, sourceLabel: string): ProviderKind;
 export declare function assertProviderCompatibility(provider: ProviderKind, sourceLabel: string, env?: NodeJS.ProcessEnv): void;
 export declare function isLegacyClaudeCompatibilityAlias(command: string, args: string[]): boolean;

package/dist/config.js

@@ -2,8 +2,10 @@ import { basename } from 'node:path';
 import { resolveSingleAgentStateRoot } from './state-paths.js';
 import { CODEX_PROVIDER_COMPATIBILITY_GATE, resolveInternalCompatibilityGates, } from './compatibility-gates.js';
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
-export const MAX_COPILOT_SESSION_TTL_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
+export const MAX_TIMER_DELAY_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
 export const DEFAULT_COPILOT_SESSION_TTL_MINUTES = 2 * 24 * 60;
+export const PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES = 0;
+export const DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES = 10;
 export const DEFAULT_CLAUDE_COMMAND = 'claude-agent-acp';
 export const LEGACY_CLAUDE_COMMAND = 'claude';
 export const LEGACY_CLAUDE_ONE_SHOT_ARGS = ['--print', '--permission-mode', 'bypassPermissions'];
@@ -15,6 +17,7 @@ export const DEFAULT_PROVIDER_COMMAND_CONFIG = {
     copilotCommand: 'copilot',
     copilotArgs: ['-s', '--no-color', '--allow-all-tools', '--output-format', 'text'],
     copilotSessionTtlMinutes: DEFAULT_COPILOT_SESSION_TTL_MINUTES,
+    providerIdleShutdownMinutes: DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES,
 };
 function requireEnv(name, env) {
     return requireNonEmptyString(env[name], `Missing required environment variable: ${name}`);
@@ -57,8 +60,18 @@ export function parseCopilotSessionTtlMinutesValue(value, sourceLabel) {
     if (!Number.isFinite(parsed) || parsed <= 0) {
         throw new Error(`Invalid COPILOT_SESSION_TTL_MINUTES in ${sourceLabel}: expected a positive number`);
     }
-    if (parsed > MAX_COPILOT_SESSION_TTL_MINUTES) {
-        throw new Error(`Invalid COPILOT_SESSION_TTL_MINUTES in ${sourceLabel}: must be <= ${MAX_COPILOT_SESSION_TTL_MINUTES.toFixed(2)} minutes to fit within the Node.js timer limit`);
+    if (parsed > MAX_TIMER_DELAY_MINUTES) {
+        throw new Error(`Invalid COPILOT_SESSION_TTL_MINUTES in ${sourceLabel}: must be <= ${MAX_TIMER_DELAY_MINUTES.toFixed(2)} minutes to fit within the Node.js timer limit`);
+    }
+    return parsed;
+}
+export function parseProviderIdleShutdownMinutesValue(value, sourceLabel) {
+    const parsed = typeof value === 'number' ? value : Number(String(value).trim());
+    if (!Number.isFinite(parsed) || parsed < PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES) {
+        throw new Error(`Invalid PROVIDER_IDLE_SHUTDOWN_MINUTES in ${sourceLabel}: expected a non-negative number, where ${PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES} keeps the shared adapter process resident`);
+    }
+    if (parsed > MAX_TIMER_DELAY_MINUTES) {
+        throw new Error(`Invalid PROVIDER_IDLE_SHUTDOWN_MINUTES in ${sourceLabel}: must be <= ${MAX_TIMER_DELAY_MINUTES.toFixed(2)} minutes to fit within the Node.js timer limit`);
     }
     return parsed;
 }
@@ -119,6 +132,8 @@ export function resolveProviderCommandConfig(overrides = {}) {
         copilotCommand: overrides.copilotCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotCommand,
         copilotArgs: [...(overrides.copilotArgs ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotArgs)],
         copilotSessionTtlMinutes: overrides.copilotSessionTtlMinutes ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
+        providerIdleShutdownMinutes: overrides.providerIdleShutdownMinutes
+            ?? DEFAULT_PROVIDER_COMMAND_CONFIG.providerIdleShutdownMinutes,
     };
 }
 export function loadConfigFromEnv(env = process.env) {
@@ -135,6 +150,9 @@ export function loadConfigFromEnv(env = process.env) {
         copilotSessionTtlMinutes: env.COPILOT_SESSION_TTL_MINUTES && env.COPILOT_SESSION_TTL_MINUTES.trim().length > 0
             ? parseCopilotSessionTtlMinutesValue(env.COPILOT_SESSION_TTL_MINUTES, 'environment variable COPILOT_SESSION_TTL_MINUTES')
             : DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
+        providerIdleShutdownMinutes: env.PROVIDER_IDLE_SHUTDOWN_MINUTES && env.PROVIDER_IDLE_SHUTDOWN_MINUTES.trim().length > 0
+            ? parseProviderIdleShutdownMinutesValue(env.PROVIDER_IDLE_SHUTDOWN_MINUTES, 'environment variable PROVIDER_IDLE_SHUTDOWN_MINUTES')
+            : DEFAULT_PROVIDER_COMMAND_CONFIG.providerIdleShutdownMinutes,
     });
     assertProviderCommandCompatibility(provider, providerConfig, 'environment variables');
     return {

package/dist/context/injection.d.ts

@@ -21,7 +21,7 @@ export interface PreparedChannelContext {
     directoryPath: string;
     payload: ChannelContextPayload;
     payloadPath?: string;
-    gatewayAuthPath?: string;
+    gatewayCredentialPath?: string;
     skillRuntime?: SkillRuntimeBootstrapMetadata;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
     taskWorkspace?: TaskWorkspaceContext;
@@ -83,6 +83,7 @@ interface ContextFileSystem {
         mode?: number;
     }): Promise<void>;
     unlink(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
     access(path: string): Promise<void>;
 }
 interface FileChannelContextStoreOptions {
@@ -98,8 +99,9 @@ export declare function resolveChannelContextDirectory(stateRootDir: string, cha
 export declare function resolveChannelContextPayloadPath(stateRootDir: string, channelId: string): string;
 export declare function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir: string): string;
 export declare function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir: string, channelId: string, taskId: string): string;
-export declare function resolveChannelContextGatewayAuthPath(stateRootDir: string, channelId: string, turnExecutionId?: string): string;
-export declare function resolveGatewayAuthPathFromPayloadPath(payloadPath: string): string;
+export declare function resolveChannelGatewayCredentialPath(stateRootDir: string, channelId: string): string;
+export declare function resolveGatewayCredentialPathFromPayloadPath(payloadPath: string): string;
+export declare function isGatewayCredentialSidecarBasename(basename: string): boolean;
 export declare function resolveBorgeeAgentSkillRuntimeAssets(moduleUrl: string, fileSystem?: Pick<ContextFileSystem, 'access'>): Promise<SkillRuntimeBootstrapMetadata>;
 export declare class FileChannelContextStore implements ChannelContextStore {
     private readonly stateRootDir;

package/dist/context/injection.js

@@ -1,9 +1,10 @@
 import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 const CHANNEL_CONTEXT_ROOT_DIRNAME = 'channel-context';
 const CHANNEL_CONTEXT_PAYLOAD_FILENAME = 'context.json';
-const CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME = '.localhost-gateway-auth.json';
+const CHANNEL_GATEWAY_CREDENTIAL_FILENAME = '.borgee-agent-gateway.json';
 const TASK_WORKSPACE_ROOT_DIRNAME = '.borgee-task-workspaces';
 export class ChannelContextPreparationError extends Error {
     partialContext;
@@ -29,6 +30,9 @@ const DEFAULT_FILE_SYSTEM = {
     async unlink(path) {
         await fs.unlink(path);
     },
+    async rename(oldPath, newPath) {
+        await fs.rename(oldPath, newPath);
+    },
     async access(path) {
         await fs.access(path);
     },
@@ -45,7 +49,7 @@ function toSkillRuntimePayload(skillRuntime) {
         pythonCliPath: skillRuntime.pythonCliPath,
     };
 }
-function buildLocalhostGatewayAuthPayload(channelId, localhostGateway) {
+function buildBorgeeAgentGatewayCredential(channelId, localhostGateway) {
     if (!localhostGateway) {
         return undefined;
     }
@@ -53,6 +57,7 @@ function buildLocalhostGatewayAuthPayload(channelId, localhostGateway) {
         schemaVersion: 1,
         channelId,
         localhostGateway: {
+            baseUrl: localhostGateway.baseUrl,
             token: localhostGateway.token,
         },
     };
@@ -144,17 +149,28 @@ export function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir) {
 export function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir, channelId, taskId) {
     return join(resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir), encodeChannelPathSegment(channelId), encodeChannelPathSegment(taskId));
 }
-export function resolveChannelContextGatewayAuthPath(stateRootDir, channelId, turnExecutionId) {
-    const filename = turnExecutionId
-        ? `.localhost-gateway-auth.${Buffer.from(turnExecutionId, 'utf8').toString('hex')}.json`
-        : CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME;
-    return join(resolveChannelContextDirectory(stateRootDir, channelId), filename);
+export function resolveChannelGatewayCredentialPath(stateRootDir, channelId) {
+    return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
+}
+export function resolveGatewayCredentialPathFromPayloadPath(payloadPath) {
+    return join(dirname(payloadPath), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
 }
-export function resolveGatewayAuthPathFromPayloadPath(payloadPath) {
-    return join(dirname(payloadPath), CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME);
+/**
+ * Every basename a gateway credential can carry in a channel context directory, including the ones
+ * this host no longer writes. The directory holds at most one live credential — the token is
+ * reissued every turn — and this sweep is the only thing that ever unlinks the others, so a name
+ * dropped from this list leaves a 0600 file behind that still looks live.
+ */
+const GATEWAY_CREDENTIAL_SIDECAR_BASENAME_PREFIXES = [
+    '.borgee-agent-gateway.',
+    '.borgee-agent-bootstrap.',
+    '.localhost-gateway-auth.',
+];
+export function isGatewayCredentialSidecarBasename(basename) {
+    return basename.endsWith('.json')
+        && GATEWAY_CREDENTIAL_SIDECAR_BASENAME_PREFIXES.some((prefix) => basename.startsWith(prefix));
 }
-const LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX = '.localhost-gateway-auth.';
-async function pruneLegacyGatewayAuthSidecars(fileSystem, directoryPath) {
+async function pruneGatewayCredentialSidecars(fileSystem, directoryPath, keepBasename) {
     let entries;
     try {
         entries = await fileSystem.readdir(directoryPath);
@@ -167,8 +183,7 @@ async function pruneLegacyGatewayAuthSidecars(fileSystem, directoryPath) {
         throw error;
     }
     await Promise.all(entries
-        .filter((entry) => entry.startsWith(LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX)
-        && entry.endsWith('.json'))
+        .filter((entry) => isGatewayCredentialSidecarBasename(entry) && entry !== keepBasename)
         .map(async (entry) => {
         await fileSystem.unlink(join(directoryPath, entry)).catch((error) => {
             if (error.code !== 'ENOENT') {
@@ -196,8 +211,8 @@ export async function resolveBorgeeAgentSkillRuntimeAssets(moduleUrl, fileSystem
     const packageRootPath = await resolvePackageRootFromModuleUrl(moduleUrl, fileSystem);
     const skillDirectoryPath = join(packageRootPath, 'skills', BORGEE_AGENT_SKILL_DIRNAME);
     const skillMarkdownPath = join(skillDirectoryPath, 'SKILL.md');
-    const nodeCliPath = join(skillDirectoryPath, 'borgee-agent.mjs');
-    const pythonCliPath = join(skillDirectoryPath, 'borgee-agent.py');
+    const nodeCliPath = join(skillDirectoryPath, 'scripts', 'borgee-agent.mjs');
+    const pythonCliPath = join(skillDirectoryPath, 'scripts', 'borgee-agent.py');
     await Promise.all([
         fileSystem.access(skillDirectoryPath),
         fileSystem.access(skillMarkdownPath),
@@ -249,7 +264,7 @@ export class FileChannelContextStore {
         const auxiliaryCollaborationEnabled = collaborationCommandsEnabled && collaborationRoutesAllowedForTurnMode;
         const directoryPath = resolveChannelContextDirectory(this.stateRootDir, input.channelId);
         const payloadPath = resolveChannelContextPayloadPath(this.stateRootDir, input.channelId);
-        const gatewayAuthPath = resolveGatewayAuthPathFromPayloadPath(payloadPath);
+        const gatewayCredentialPath = resolveGatewayCredentialPathFromPayloadPath(payloadPath);
         const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(payloadPath, this.fileSystem);
         const skillRuntime = this.skillRuntimeEnabled
             ? await this.resolveSkillRuntimeBestEffort()
@@ -292,15 +307,15 @@ export class FileChannelContextStore {
                 ...(taskWorkspace ? { taskWorkspace } : {}),
             }
             : undefined);
-        const gatewayAuthPayload = buildLocalhostGatewayAuthPayload(input.channelId, issuedLocalhostGateway);
+        const gatewayCredential = buildBorgeeAgentGatewayCredential(input.channelId, issuedLocalhostGateway);
         let taskWorkspaceMaterialized = false;
         let payloadWritten = false;
-        let gatewayAuthWritten = false;
+        let gatewayCredentialWritten = false;
         const preparedContext = {
             directoryPath,
             payload,
             payloadPath,
-            gatewayAuthPath: gatewayAuthPayload ? gatewayAuthPath : undefined,
+            gatewayCredentialPath: gatewayCredential ? gatewayCredentialPath : undefined,
             skillRuntime,
             localhostGateway,
             taskWorkspace,
@@ -311,19 +326,20 @@ export class FileChannelContextStore {
                 await this.fileSystem.mkdir(taskWorkspace.rootPath, { recursive: true, mode: 0o700 });
                 taskWorkspaceMaterialized = true;
             }
-            await pruneLegacyGatewayAuthSidecars(this.fileSystem, directoryPath);
+            await pruneGatewayCredentialSidecars(this.fileSystem, directoryPath, gatewayCredential ? CHANNEL_GATEWAY_CREDENTIAL_FILENAME : undefined);
             await this.fileSystem.writeFile(payloadPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
             payloadWritten = true;
-            if (gatewayAuthPayload) {
-                await this.fileSystem.writeFile(gatewayAuthPath, `${JSON.stringify(gatewayAuthPayload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-                gatewayAuthWritten = true;
+            if (gatewayCredential) {
+                // Replaced atomically: a CLI invocation left over from an earlier turn must read either
+                // the old credential or the new one, never a missing or half-written file, because the
+                // documented correction for a rotated token is a 401 and not a usage error. The staging
+                // name is itself a credential sidecar, so a crashed run's leftover is swept above.
+                const stagingCredentialPath = join(directoryPath, `.borgee-agent-gateway.${randomUUID()}.json`);
+                await this.fileSystem.writeFile(stagingCredentialPath, `${JSON.stringify(gatewayCredential, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+                await this.fileSystem.rename(stagingCredentialPath, gatewayCredentialPath);
+                gatewayCredentialWritten = true;
             }
             else {
-                await this.fileSystem.unlink(gatewayAuthPath).catch((error) => {
-                    if (error.code !== 'ENOENT') {
-                        throw error;
-                    }
-                });
                 this.localhostGateway?.clearChannel(input.channelId);
             }
             if (issuedLocalhostGateway) {
@@ -336,7 +352,7 @@ export class FileChannelContextStore {
                 directoryPath,
                 payload,
                 payloadPath: payloadWritten ? payloadPath : undefined,
-                gatewayAuthPath: gatewayAuthWritten ? gatewayAuthPath : undefined,
+                gatewayCredentialPath: gatewayCredentialWritten ? gatewayCredentialPath : undefined,
                 skillRuntime: payloadWritten ? skillRuntime : undefined,
                 localhostGateway: payloadWritten ? localhostGateway : undefined,
                 taskWorkspace: taskWorkspaceMaterialized ? taskWorkspace : undefined,

package/dist/context/main-session-delegation.d.ts

@@ -0,0 +1 @@
+export declare const MAIN_SESSION_DELEGATION_LINES: readonly string[];

package/dist/context/main-session-delegation.js

@@ -0,0 +1,6 @@
+export const MAIN_SESSION_DELEGATION_LINES = [
+    'This session is your coordination surface: read the channel, answer the human, break work down, and keep task state current here.',
+    'Delegate the actual work to subagents — research, code edits, long builds and test runs, and broad repository sweeps belong in a delegated worker instead of running inline here.',
+    'Delegation changes who executes, not who owns: the work still belongs to this thread, and you still report the result here yourself.',
+    'Stay responsive while delegated work runs, so a new incoming message never waits behind a long local operation.',
+];

package/dist/context/prompt.js

@@ -2,6 +2,8 @@ import { AWAITING_USER_CONTROL_PREFIX } from '../providers/awaiting-user.js';
 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') {
@@ -12,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>"]`);
-    }
-    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>"]`);
+    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;
 }
@@ -76,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.');
@@ -84,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) {
@@ -221,6 +210,7 @@ export function buildPrompt(params) {
         '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.',
+        ...MAIN_SESSION_DELEGATION_LINES,
         ...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}`,
@@ -245,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,