@cjhyy/code-shell-capability-coding 0.8.2 → 0.8.4

package/README.md

@@ -2,7 +2,7 @@
 
 Optional coding capability pack for `@cjhyy/code-shell-core`. It owns
 CodeShell's coding policy and implementations: the `terminal-coding` preset,
-coding prompt, Git/worktree behavior, LSP, ApplyPatch, NotebookEdit, Brief,
+coding prompt, Git/worktree behavior, LSP, ApplyPatch, NotebookEdit,
 review/quota helpers, and external coding-agent adapters.
 
 The package is deliberately separate from core. A service building a customer
@@ -52,8 +52,10 @@ import { probeClaudeCli } from "@cjhyy/code-shell-capability-coding/orchestratio
 ```
 
 These are subpaths of the same npm package, not independently versioned
-packages. LSP, ApplyPatch, Brief, NotebookEdit, and other compatibility exports
-remain available from the root.
+packages. LSP, ApplyPatch, NotebookEdit, and other compatibility exports remain
+available from the root. The legacy `briefTool` formatter is also retained as a
+root compatibility export, but it is no longer registered with the default
+coding preset: user-facing Markdown should be returned as normal assistant text.
 
 ## Boundary
 

package/dist/external-runtimes/claude-code/event-translator.d.ts

@@ -34,6 +34,8 @@ export declare class ClaudeEventTranslator {
     /** Accumulates `input_json_delta` per tool block so args land as one object. */
     private readonly toolInput;
     constructor(options: ClaudeEventTranslatorOptions);
+    /** Reset turn-scoped state while preserving the durable Claude session id. */
+    beginTurn(): void;
     /** Claude session id, learned from the `system/init` line. */
     runtimeSessionId?: string;
     /**

package/dist/external-runtimes/claude-code/event-translator.js

@@ -31,6 +31,11 @@ export class ClaudeEventTranslator {
         this.options = options;
         this.codeshellServer = options.codeshellServerName ?? "codeshell_tools";
     }
+    /** Reset turn-scoped state while preserving the durable Claude session id. */
+    beginTurn() {
+        this.terminal = false;
+        this.toolInput.clear();
+    }
     /** Claude session id, learned from the `system/init` line. */
     runtimeSessionId;
     /**
@@ -188,12 +193,32 @@ export class ClaudeEventTranslator {
         if (this.terminal)
             return [];
         this.terminal = true;
-        return [
-            {
-                type: "turn_complete",
-                reason: terminalReasonFor(str(message.subtype), message.is_error === true),
-            },
-        ];
+        const events = [];
+        const usage = asRecord(message.usage);
+        const number = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+        const promptTokens = number(usage?.input_tokens);
+        if (promptTokens !== undefined) {
+            const completionTokens = number(usage?.output_tokens);
+            const cacheReadTokens = number(usage?.cache_read_input_tokens);
+            const cacheCreationTokens = number(usage?.cache_creation_input_tokens);
+            events.push({
+                type: "usage_update",
+                promptTokens,
+                promptTokensSource: "provider_usage",
+                promptTokensConfidence: "high",
+                ...(completionTokens !== undefined ? { completionTokens } : {}),
+                ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+                ...(cacheCreationTokens !== undefined ? { cacheCreationTokens } : {}),
+            });
+        }
+        const reason = terminalReasonFor(str(message.subtype), message.is_error === true);
+        if (reason === "model_error") {
+            const detail = str(message.result) ?? str(message.error);
+            if (detail)
+                events.push({ type: "error", error: detail });
+        }
+        events.push({ type: "turn_complete", reason });
+        return events;
     }
     isCodeshellHostTool(toolName) {
         return toolName.startsWith(`mcp__${this.codeshellServer}__`);

package/dist/external-runtimes/claude-code/runtime.d.ts

@@ -1,5 +1,6 @@
 import type { StreamEvent } from "@cjhyy/code-shell-core/extension";
 import type { McpBridgeHandle } from "../shared/mcp-bridge.js";
+import { type ExternalRuntimeTurnInput } from "../turn-input.js";
 export interface ClaudeRuntimeOptions {
     cwd: string;
     /** CodeShell business session id — the authorization subject. */
@@ -12,6 +13,8 @@ export interface ClaudeRuntimeOptions {
     /** Extra args, inserted before the runtime's own. */
     extraArgs?: readonly string[];
     model?: string;
+    resumeRuntimeSessionId?: string;
+    initialContext?: string;
     serverName?: string;
     log?: (event: string, data: Record<string, unknown>) => void;
 }
@@ -30,6 +33,8 @@ export declare class ClaudeCodeRuntime {
     private child?;
     private claudeSessionId?;
     private closed;
+    private firstTurn;
+    private terminalSeen;
     constructor(options: ClaudeRuntimeOptions, hooks?: ClaudeRuntimeHooks);
     /** Claude session id, once the first turn has reported it. Resume key only. */
     get runtimeSessionId(): string | undefined;
@@ -41,8 +46,9 @@ export declare class ClaudeCodeRuntime {
      * positional prompt after it is swallowed as another config value (measured),
      * and a prompt on the command line would also be visible in `ps`.
      */
-    send(text: string): Promise<ClaudeTurnHandle>;
+    send(input: ExternalRuntimeTurnInput): Promise<ClaudeTurnHandle>;
     private onLine;
+    private emit;
     /**
      * Interrupt the active turn.
      *

package/dist/external-runtimes/claude-code/runtime.js

@@ -19,6 +19,7 @@ import { createInterface } from "node:readline";
 import { ClaudeEventTranslator } from "./event-translator.js";
 import { claudeBridgeArgs, CLAUDE_MCP_SERVER_NAME } from "./mcp-config.js";
 import { buildRuntimeSpawnEnv } from "../shared/spawn-env.js";
+import { textWithAttachmentReferences } from "../turn-input.js";
 export class ClaudeCodeRuntime {
     options;
     hooks;
@@ -28,6 +29,8 @@ export class ClaudeCodeRuntime {
     child;
     claudeSessionId;
     closed = false;
+    firstTurn = true;
+    terminalSeen = false;
     constructor(options, hooks = {}) {
         this.options = options;
         this.hooks = hooks;
@@ -36,6 +39,7 @@ export class ClaudeCodeRuntime {
             sessionId: options.businessSessionId,
             codeshellServerName: options.serverName ?? CLAUDE_MCP_SERVER_NAME,
         });
+        this.claudeSessionId = options.resumeRuntimeSessionId;
     }
     /** Claude session id, once the first turn has reported it. Resume key only. */
     get runtimeSessionId() {
@@ -49,11 +53,13 @@ export class ClaudeCodeRuntime {
      * positional prompt after it is swallowed as another config value (measured),
      * and a prompt on the command line would also be visible in `ps`.
      */
-    async send(text) {
+    async send(input) {
         if (this.closed)
             throw new Error("ClaudeCodeRuntime is closed");
         if (this.child)
             throw new Error("a turn is already running");
+        this.terminalSeen = false;
+        this.translator.beginTurn();
         const wiring = claudeBridgeArgs({
             bridge: this.options.bridge,
             exposedToolNames: this.options.exposedToolNames,
@@ -94,19 +100,34 @@ export class ClaudeCodeRuntime {
             if (trimmed)
                 this.log("claude.stderr", { bytes: trimmed.length });
         });
+        let text = textWithAttachmentReferences(input);
+        if (this.firstTurn && !this.options.resumeRuntimeSessionId && this.options.initialContext) {
+            text = `${this.options.initialContext}\n\n<current_user_request>\n${text}\n</current_user_request>`;
+        }
+        this.firstTurn = false;
         child.stdin.end(text);
         const done = new Promise((resolve) => {
-            const finish = () => {
+            let finished = false;
+            const finish = (code, error) => {
+                if (finished)
+                    return;
+                finished = true;
                 lines.close();
                 // Clean up the config file that carried the bearer token.
                 wiring.cleanup();
                 this.child = undefined;
+                if (!this.terminalSeen) {
+                    const detail = error?.message ??
+                        `Claude Code exited without a terminal result (code ${code ?? "unknown"})`;
+                    this.emit({ type: "error", error: detail });
+                    this.emit({ type: "turn_complete", reason: "model_error" });
+                }
                 resolve();
             };
-            child.once("exit", finish);
+            child.once("exit", (code) => finish(code));
             child.once("error", (error) => {
                 this.log("claude.spawn_failed", { error: error.message.slice(0, 200) });
-                finish();
+                finish(undefined, error);
             });
         });
         return { done };
@@ -124,14 +145,9 @@ export class ClaudeCodeRuntime {
             return;
         }
         for (const event of this.translator.translate(parsed)) {
-            try {
-                this.hooks.onEvent?.(event);
-            }
-            catch (error) {
-                this.log("claude.event_handler_failed", {
-                    error: error instanceof Error ? error.name : "unknown",
-                });
-            }
+            if (event.type === "turn_complete")
+                this.terminalSeen = true;
+            this.emit(event);
         }
         if (!this.claudeSessionId && this.translator.runtimeSessionId) {
             this.claudeSessionId = this.translator.runtimeSessionId;
@@ -141,6 +157,16 @@ export class ClaudeCodeRuntime {
             });
         }
     }
+    emit(event) {
+        try {
+            this.hooks.onEvent?.(event);
+        }
+        catch (error) {
+            this.log("claude.event_handler_failed", {
+                error: error instanceof Error ? error.name : "unknown",
+            });
+        }
+    }
     /**
      * Interrupt the active turn.
      *

package/dist/external-runtimes/codex/event-translator.d.ts

@@ -56,6 +56,8 @@ export declare class CodexEventTranslator {
     private onTurnCompleted;
     private onError;
     private onAgentDelta;
+    private onReasoningDelta;
+    private onTokenUsage;
     /**
      * A CodeShell Host Tool call must not produce a card here — `ToolExecutor`
      * already emits one, and two unsynchronised sources for one operation is

package/dist/external-runtimes/codex/event-translator.js

@@ -2,6 +2,18 @@
 const CODESHELL_MCP_SERVER = "codeshell_tools";
 /** Cap on remembered finished turns — a session is long-lived, the set is not. */
 const MAX_TOMBSTONES = 256;
+/** Thread items that represent observable runtime work rather than prose/state. */
+const TOOL_ITEM_TYPES = new Set([
+    "commandExecution",
+    "fileChange",
+    "mcpToolCall",
+    "dynamicToolCall",
+    "collabAgentToolCall",
+    "webSearch",
+    "imageView",
+    "sleep",
+    "imageGeneration",
+]);
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -69,13 +81,17 @@ export class CodexEventTranslator {
                 return this.onError(params);
             case "item/agentMessage/delta":
                 return this.onAgentDelta(params);
+            case "item/reasoning/summaryTextDelta":
+            case "item/reasoning/textDelta":
+                return this.onReasoningDelta(params);
+            case "thread/tokenUsage/updated":
+                return this.onTokenUsage(params);
             case "item/started":
                 return this.onItemStarted(params);
             case "item/completed":
                 return this.onItemCompleted(params);
             default:
-                // Everything else (token usage, rate limits, plan updates, MCP status…)
-                // is either handled elsewhere or deliberately not surfaced.
+                // Rate limits, plan updates and MCP status are not chat events.
                 return [];
         }
     }
@@ -118,7 +134,18 @@ export class CodexEventTranslator {
         if (turnId)
             this.remember(turnId);
         this.activeTurnId = undefined;
-        return [{ type: "turn_complete", reason: terminalReasonFor(str(turn?.status)) }];
+        const reason = terminalReasonFor(str(turn?.status));
+        if (reason === "model_error") {
+            const error = asRecord(turn?.error);
+            const detail = str(error?.message) ?? str(error?.additionalDetails);
+            if (detail) {
+                return [
+                    { type: "error", error: detail },
+                    { type: "turn_complete", reason },
+                ];
+            }
+        }
+        return [{ type: "turn_complete", reason }];
     }
     onError(params) {
         // A retryable error is not terminal. Reporting completion here would close
@@ -132,7 +159,12 @@ export class CodexEventTranslator {
         if (turnId)
             this.remember(turnId);
         this.activeTurnId = undefined;
-        return [{ type: "turn_complete", reason: "model_error" }];
+        const error = asRecord(params.error);
+        const message = str(error?.message) ?? str(error?.additionalDetails) ?? "Codex turn failed";
+        return [
+            { type: "error", error: message },
+            { type: "turn_complete", reason: "model_error" },
+        ];
     }
     onAgentDelta(params) {
         if (this.isStale(str(params.turnId)))
@@ -140,6 +172,50 @@ export class CodexEventTranslator {
         const delta = str(params.delta);
         return delta ? [{ type: "text_delta", text: delta }] : [];
     }
+    onReasoningDelta(params) {
+        if (this.isStale(str(params.turnId)))
+            return [];
+        const delta = str(params.delta);
+        return delta ? [{ type: "thinking_delta", text: delta }] : [];
+    }
+    onTokenUsage(params) {
+        if (this.isStale(str(params.turnId)))
+            return [];
+        const usage = asRecord(params.tokenUsage);
+        const total = asRecord(usage?.total);
+        const last = asRecord(usage?.last);
+        const number = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+        const promptTokens = number(last?.inputTokens);
+        if (promptTokens === undefined)
+            return [];
+        const cacheReadTokens = number(last?.cachedInputTokens);
+        const cumulativePromptTokens = number(total?.inputTokens);
+        const cumulativeCacheReadTokens = number(total?.cachedInputTokens);
+        const cacheCreationTokens = number(last?.cacheWriteInputTokens);
+        const cumulativeCacheCreationTokens = number(total?.cacheWriteInputTokens);
+        const completionTokens = number(last?.outputTokens);
+        const cumulativeCompletionTokens = number(total?.outputTokens);
+        return [
+            {
+                type: "usage_update",
+                promptTokens,
+                promptTokensSource: "provider_usage",
+                promptTokensConfidence: "high",
+                ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+                ...(cacheCreationTokens !== undefined ? { cacheCreationTokens } : {}),
+                singleTurnPromptTokens: promptTokens,
+                ...(cacheReadTokens !== undefined ? { singleTurnCacheReadTokens: cacheReadTokens } : {}),
+                ...(cacheCreationTokens !== undefined
+                    ? { singleTurnCacheCreationTokens: cacheCreationTokens }
+                    : {}),
+                ...(cumulativePromptTokens !== undefined ? { cumulativePromptTokens } : {}),
+                ...(cumulativeCacheReadTokens !== undefined ? { cumulativeCacheReadTokens } : {}),
+                ...(cumulativeCacheCreationTokens !== undefined ? { cumulativeCacheCreationTokens } : {}),
+                ...(completionTokens !== undefined ? { completionTokens } : {}),
+                ...(cumulativeCompletionTokens !== undefined ? { cumulativeCompletionTokens } : {}),
+            },
+        ];
+    }
     /**
      * A CodeShell Host Tool call must not produce a card here — `ToolExecutor`
      * already emits one, and two unsynchronised sources for one operation is
@@ -161,6 +237,8 @@ export class CodexEventTranslator {
         const type = str(item?.type);
         if (!item || !id || !type)
             return [];
+        if (!TOOL_ITEM_TYPES.has(type))
+            return [];
         if (this.isCodeshellHostTool(item))
             return [];
         const { id: _id, type: _type, ...args } = item;
@@ -174,13 +252,33 @@ export class CodexEventTranslator {
         const type = str(item?.type);
         if (!item || !id || !type)
             return [];
+        if (!TOOL_ITEM_TYPES.has(type))
+            return [];
         if (this.isCodeshellHostTool(item))
             return [];
-        const output = str(item.aggregatedOutput) ?? str(item.output) ?? str(item.text) ?? str(item.result);
+        const rawOutput = item.aggregatedOutput ?? item.output ?? item.text ?? item.result ?? item.changes;
+        let output;
+        if (typeof rawOutput === "string")
+            output = rawOutput;
+        else if (rawOutput !== undefined && rawOutput !== null) {
+            try {
+                output = JSON.stringify(rawOutput);
+            }
+            catch {
+                output = String(rawOutput);
+            }
+        }
+        const error = asRecord(item.error);
+        const errorMessage = str(error?.message) ?? str(item.error);
         return [
             {
                 type: "tool_result",
-                result: { id, toolName: type, ...(output !== undefined ? { result: output } : {}) },
+                result: {
+                    id,
+                    toolName: type,
+                    ...(output !== undefined ? { result: output } : {}),
+                    ...(errorMessage ? { error: errorMessage, isError: true } : {}),
+                },
             },
         ];
     }

package/dist/external-runtimes/codex/runtime.d.ts

@@ -18,6 +18,7 @@
 import type { StreamEvent } from "@cjhyy/code-shell-core/extension";
 import { type AppServerClientOptions } from "./app-server-client.js";
 import { type McpBridgeHandle } from "../shared/mcp-bridge.js";
+import { type ExternalRuntimeTurnInput } from "../turn-input.js";
 export interface CodexRuntimeOptions {
     cwd: string;
     /** CodeShell business session id — the authorization subject, never the thread id. */
@@ -31,6 +32,9 @@ export interface CodexRuntimeOptions {
      */
     bridgeServerName?: string;
     model?: string;
+    resumeRuntimeSessionId?: string;
+    initialContext?: string;
+    developerInstructions?: string;
     /** Codex sandbox mode. Kebab-case per protocol (`workspace-write`, …). */
     sandbox?: string;
     /** Codex approval policy. Also kebab-case. */
@@ -59,6 +63,11 @@ export interface CodexRuntimeHooks {
         method: string;
         params: unknown;
     }) => Promise<NativeApprovalDecision> | NativeApprovalDecision;
+    /** Answer Codex's request_user_input tool through the owning CodeShell UI. */
+    onUserInput?: (request: {
+        method: string;
+        params: unknown;
+    }) => Promise<unknown> | unknown;
 }
 export declare class CodexRuntime {
     private readonly options;
@@ -69,6 +78,8 @@ export declare class CodexRuntime {
     private translator?;
     private threadId?;
     private started;
+    private resumed;
+    private firstTurn;
     private activeTurn?;
     constructor(options: CodexRuntimeOptions, hooks?: CodexRuntimeHooks);
     /** Codex thread id, once the thread exists. Protocol routing only — never the
@@ -90,7 +101,7 @@ export declare class CodexRuntime {
      * tombstones are what keep a late `turn/started` from reactivating a session
      * that already reported terminal.
      */
-    send(text: string): Promise<CodexTurnHandle>;
+    send(input: ExternalRuntimeTurnInput): Promise<CodexTurnHandle>;
     /**
      * Interrupt the active turn.
      *

package/dist/external-runtimes/codex/runtime.js

@@ -2,6 +2,7 @@ import { CodexAppServerClient } from "./app-server-client.js";
 import { CodexEventTranslator } from "./event-translator.js";
 import { buildRuntimeSpawnEnv } from "../shared/spawn-env.js";
 import { codexBridgeConfigArgs } from "../shared/mcp-bridge.js";
+import { textWithAttachmentReferences } from "../turn-input.js";
 /** A thread/start or turn/start that hangs is worse than one that fails. */
 const CRITICAL_RPC_TIMEOUT_MS = 60_000;
 /** Interrupt is a fail-safe; an unbounded wait silently defeats it. */
@@ -15,6 +16,8 @@ export class CodexRuntime {
     translator;
     threadId;
     started = false;
+    resumed = false;
+    firstTurn = true;
     activeTurn;
     constructor(options, hooks = {}) {
         this.options = options;
@@ -57,15 +60,41 @@ export class CodexRuntime {
             clientInfo: { name: "codeshell", title: "CodeShell", version: "1" },
             capabilities: { experimentalApi: true },
         }, CRITICAL_RPC_TIMEOUT_MS);
-        const thread = (await this.client.request("thread/start", {
+        let thread;
+        if (this.options.resumeRuntimeSessionId) {
+            try {
+                thread = (await this.client.request("thread/resume", {
+                    threadId: this.options.resumeRuntimeSessionId,
+                    cwd: this.options.cwd,
+                    ...(this.options.model ? { model: this.options.model } : {}),
+                    ...(this.options.sandbox ? { sandbox: this.options.sandbox } : {}),
+                    ...(this.options.approvalPolicy ? { approvalPolicy: this.options.approvalPolicy } : {}),
+                    ...(this.options.developerInstructions
+                        ? { developerInstructions: this.options.developerInstructions }
+                        : {}),
+                }, CRITICAL_RPC_TIMEOUT_MS));
+                this.resumed = true;
+            }
+            catch (error) {
+                this.log("runtime.thread_resume_failed", {
+                    businessSessionId: this.options.businessSessionId,
+                    error: error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200),
+                });
+            }
+        }
+        thread ??= (await this.client.request("thread/start", {
             cwd: this.options.cwd,
             ...(this.options.model ? { model: this.options.model } : {}),
             ...(this.options.sandbox ? { sandbox: this.options.sandbox } : {}),
             ...(this.options.approvalPolicy ? { approvalPolicy: this.options.approvalPolicy } : {}),
+            ...(this.options.developerInstructions
+                ? { developerInstructions: this.options.developerInstructions }
+                : {}),
         }, CRITICAL_RPC_TIMEOUT_MS));
         const threadId = thread?.thread?.id;
-        if (!threadId)
-            throw new Error("thread/start returned no thread id");
+        if (!threadId) {
+            throw new Error(`${this.resumed ? "thread/resume" : "thread/start"} returned no thread id`);
+        }
         this.threadId = threadId;
         this.translator = new CodexEventTranslator({
             threadId,
@@ -74,6 +103,7 @@ export class CodexRuntime {
         this.log("runtime.thread_started", {
             businessSessionId: this.options.businessSessionId,
             threadIdPrefix: threadId.slice(0, 8),
+            resumed: this.resumed,
         });
     }
     /**
@@ -84,16 +114,31 @@ export class CodexRuntime {
      * tombstones are what keep a late `turn/started` from reactivating a session
      * that already reported terminal.
      */
-    async send(text) {
+    async send(input) {
         if (!this.threadId)
             throw new Error("CodexRuntime.send() before start()");
         let resolveDone;
         const done = new Promise((resolve) => (resolveDone = resolve));
         this.activeTurn = { resolve: resolveDone };
+        let text = textWithAttachmentReferences(input);
+        if (this.firstTurn && !this.resumed && this.options.initialContext) {
+            text = `${this.options.initialContext}\n\n<current_user_request>\n${text}\n</current_user_request>`;
+        }
+        this.firstTurn = false;
+        const imageInputs = (input.attachments ?? [])
+            .filter((attachment) => attachment.kind === "image" || attachment.mime?.toLowerCase().startsWith("image/"))
+            .map((attachment) => ({
+            type: "localImage",
+            path: attachment.path,
+            ...(attachment.detail === "low" || attachment.detail === "high"
+                ? { detail: attachment.detail }
+                : {}),
+        }));
         const response = (await this.client.request("turn/start", {
             threadId: this.threadId,
+            ...(input.clientMessageId ? { clientUserMessageId: input.clientMessageId } : {}),
             // `text_elements` is required by the protocol even when empty.
-            input: [{ type: "text", text, text_elements: [] }],
+            input: [{ type: "text", text, text_elements: [] }, ...imageInputs],
         }, CRITICAL_RPC_TIMEOUT_MS));
         const turnId = response?.turn?.id;
         if (this.activeTurn)
@@ -171,6 +216,11 @@ export class CodexRuntime {
         if (method === "mcpServer/elicitation/request") {
             return this.answerMcpElicitation(params);
         }
+        if (method === "item/tool/requestUserInput") {
+            return this.hooks.onUserInput
+                ? await this.hooks.onUserInput({ method, params })
+                : { answers: {} };
+        }
         if (!method.includes("requestApproval")) {
             // Some other server request (user input, …). Leave unhandled so the client
             // answers method-not-found rather than inventing consent.

package/dist/external-runtimes/index.d.ts

@@ -20,6 +20,8 @@ export { SessionContextStore } from "./shared/session-context-store.js";
 export type { ResolveRequest, SessionContextResult, SessionContextMissReason, ToolHostRef, } from "./shared/session-context-store.js";
 export { buildRuntimeSpawnEnv } from "./shared/spawn-env.js";
 export type { RuntimeSpawnEnvOptions } from "./shared/spawn-env.js";
+export { textWithAttachmentReferences } from "./turn-input.js";
+export type { ExternalRuntimeAttachment, ExternalRuntimeTurnInput } from "./turn-input.js";
 export { CodexEventTranslator } from "./codex/event-translator.js";
 export { CodexAppServerClient } from "./codex/app-server-client.js";
 export type { AppServerClientOptions } from "./codex/app-server-client.js";

package/dist/external-runtimes/index.js

@@ -17,6 +17,7 @@
 export { CODEX_MCP_TOKEN_ENV_VAR, codexBridgeConfigArgs, startLoopbackMcpBridge, threadIdFromMeta, } from "./shared/mcp-bridge.js";
 export { SessionContextStore } from "./shared/session-context-store.js";
 export { buildRuntimeSpawnEnv } from "./shared/spawn-env.js";
+export { textWithAttachmentReferences } from "./turn-input.js";
 export { CodexEventTranslator } from "./codex/event-translator.js";
 export { CodexAppServerClient } from "./codex/app-server-client.js";
 export { CodexRuntime } from "./codex/runtime.js";

package/dist/external-runtimes/session-factory.d.ts

@@ -23,6 +23,7 @@ import type { PermissionRule, ToolDefinition } from "@cjhyy/code-shell-core/exte
 import { createSessionToolHost, type ExternalToolExposurePolicy, type ToolVisibilityInputs } from "@cjhyy/code-shell-core/extension";
 import { type CodexRuntimeHooks, type CodexRuntimeOptions } from "./codex/runtime.js";
 import { type ClaudeRuntimeHooks } from "./claude-code/runtime.js";
+import type { ExternalRuntimeTurnInput } from "./turn-input.js";
 export type ExternalRuntimeKind = "codex" | "claude-code";
 /**
  * Everything the host must decide. Deliberately no defaults for the
@@ -52,6 +53,12 @@ export interface ExternalRuntimeSessionOptions {
     contextOverrides?: Parameters<typeof createSessionToolHost>[0]["contextOverrides"];
     settingsScope?: Parameters<typeof createSessionToolHost>[0]["settingsScope"];
     model?: string;
+    /** Runtime thread/session id recovered from durable Desktop state. */
+    resumeRuntimeSessionId?: string;
+    /** Context replayed only when resume is unavailable and a fresh thread starts. */
+    initialContext?: string;
+    /** Stable host guidance applied to new and resumed runtime threads. */
+    developerInstructions?: string;
     /** Codex only. Kebab-case per protocol. */
     sandbox?: string;
     /** Codex only. Kebab-case per protocol. */
@@ -76,7 +83,7 @@ export interface ExternalRuntimeSession {
     readonly runtimeSessionId: string | undefined;
     /** Tools actually exposed, after the allowlist and visibility guards. */
     listTools(): readonly ToolDefinition[];
-    send(text: string): Promise<{
+    send(input: ExternalRuntimeTurnInput): Promise<{
         done: Promise<void>;
     }>;
     interrupt(): Promise<void>;

package/dist/external-runtimes/session-factory.js

@@ -66,6 +66,13 @@ export async function startExternalRuntimeSession(options) {
                 businessSessionId: options.businessSessionId,
                 bridge,
                 ...(options.model ? { model: options.model } : {}),
+                ...(options.resumeRuntimeSessionId
+                    ? { resumeRuntimeSessionId: options.resumeRuntimeSessionId }
+                    : {}),
+                ...(options.initialContext ? { initialContext: options.initialContext } : {}),
+                ...(options.developerInstructions
+                    ? { developerInstructions: options.developerInstructions }
+                    : {}),
                 ...(options.sandbox ? { sandbox: options.sandbox } : {}),
                 ...(options.approvalPolicy ? { approvalPolicy: options.approvalPolicy } : {}),
                 ...(options.codexClient ? { client: options.codexClient } : {}),
@@ -81,6 +88,10 @@ export async function startExternalRuntimeSession(options) {
                 bridge,
                 exposedToolNames,
                 ...(options.model ? { model: options.model } : {}),
+                ...(options.resumeRuntimeSessionId
+                    ? { resumeRuntimeSessionId: options.resumeRuntimeSessionId }
+                    : {}),
+                ...(options.initialContext ? { initialContext: options.initialContext } : {}),
                 ...(options.claudeExtraArgs ? { extraArgs: options.claudeExtraArgs } : {}),
                 ...(options.claudeCommand ? { command: options.claudeCommand } : {}),
                 log,
@@ -103,7 +114,7 @@ export async function startExternalRuntimeSession(options) {
             return activeRuntime.runtimeSessionId;
         },
         listTools: () => activeHost.listTools(),
-        send: (text) => activeRuntime.send(text),
+        send: (input) => activeRuntime.send(input),
         interrupt: () => activeRuntime.interrupt(),
         close,
     };

package/dist/external-runtimes/turn-input.d.ts

@@ -0,0 +1,13 @@
+/** Transport-neutral user input for Codex / Claude Code runtimes. */
+export interface ExternalRuntimeAttachment {
+    path: string;
+    kind?: "image" | "file" | "directory";
+    mime?: string;
+    detail?: "low" | "standard" | "high";
+}
+export interface ExternalRuntimeTurnInput {
+    text: string;
+    clientMessageId?: string;
+    attachments?: readonly ExternalRuntimeAttachment[];
+}
+export declare function textWithAttachmentReferences(input: ExternalRuntimeTurnInput): string;

package/dist/external-runtimes/turn-input.js

@@ -0,0 +1,15 @@
+export function textWithAttachmentReferences(input) {
+    const references = (input.attachments ?? [])
+        .filter((attachment) => attachment.path.trim())
+        .map((attachment) => `- ${attachment.kind ?? "file"}: ${attachment.path}`);
+    if (references.length === 0)
+        return input.text;
+    return [
+        input.text,
+        "",
+        "<codeshell_attachments>",
+        "The user explicitly attached these local paths. Inspect them when relevant:",
+        ...references,
+        "</codeshell_attachments>",
+    ].join("\n");
+}

package/dist/index.capability.js

@@ -1,7 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { BUILTIN_AGENT_PRESETS, BUILTIN_TOOLS, derivePresetExposure, } from "@cjhyy/code-shell-core/extension";
-import { briefTool, briefToolDef } from "./tools/brief.js";
 import { lspTool, lspToolDef } from "./tools/lsp.js";
 import { notebookEditTool, notebookEditToolDef } from "./tools/notebook-edit.js";
 import { applyPatchTool, applyPatchToolDef } from "./tools/apply-patch/index.js";
@@ -16,6 +15,9 @@ function defineTool(definition, execute, exposure) {
     return { definition, execute, exposure };
 }
 export const CODING_TOOLS = [
+    // `briefTool` remains a root compatibility export, but is deliberately not
+    // model-exposed here: its Markdown return value is a tool result, not a
+    // user-facing assistant message (especially important for headless runs).
     defineTool({
         ...driveAgentToolDef,
         source: "builtin",
@@ -92,16 +94,6 @@ export const CODING_TOOLS = [
             },
         },
     }, applyPatchTool, { presetTags: ["terminal-coding"] }),
-    defineTool({
-        ...briefToolDef,
-        source: "builtin",
-        permissionDefault: "allow",
-        isReadOnly: true,
-        isConcurrencySafe: true,
-    }, briefTool, {
-        presetTags: ["terminal-coding"],
-        defaultPermissionRules: [{ tool: "Brief", decision: "allow" }],
-    }),
     defineTool({
         ...notebookEditToolDef,
         source: "builtin",

package/dist/tools/brief.d.ts

@@ -1,6 +1,12 @@
 /**
- * BriefTool — send structured messages with markdown support.
+ * Legacy Brief formatter.
+ *
+ * Kept as a root compatibility export for existing programmatic consumers. It
+ * is intentionally not registered in the default coding capability because a
+ * tool result is not a user-facing assistant message.
  */
 import type { ToolDefinition } from "@cjhyy/code-shell-core/extension";
+/** @deprecated Return user-facing Markdown as normal assistant text instead. */
 export declare const briefToolDef: ToolDefinition;
+/** @deprecated Return user-facing Markdown as normal assistant text instead. */
 export declare function briefTool(args: Record<string, unknown>): Promise<string>;

package/dist/tools/brief.js

@@ -1,6 +1,11 @@
 /**
- * BriefTool — send structured messages with markdown support.
+ * Legacy Brief formatter.
+ *
+ * Kept as a root compatibility export for existing programmatic consumers. It
+ * is intentionally not registered in the default coding capability because a
+ * tool result is not a user-facing assistant message.
  */
+/** @deprecated Return user-facing Markdown as normal assistant text instead. */
 export const briefToolDef = {
     name: "Brief",
     description: "Send a structured brief/summary message. Useful for providing concise status updates, " +
@@ -25,6 +30,7 @@ export const briefToolDef = {
         required: ["content"],
     },
 };
+/** @deprecated Return user-facing Markdown as normal assistant text instead. */
 export async function briefTool(args) {
     const title = args.title;
     const content = args.content;

package/dist/tools/drive-agent.js

@@ -107,6 +107,9 @@ export const driveAgentToolDef = {
         required: ["prompt"],
     },
 };
+function isExternalRuntimeContext(ctx) {
+    return (ctx?.externalRuntime === true);
+}
 const defaultRunner = (opts) => {
     const { adapter, command } = CLI_ADAPTERS[opts.cli];
     return runAgentOnce(adapter, {
@@ -601,7 +604,7 @@ function trackBackgroundRun(params) {
     return { jobId, ...(warning ? { warning } : {}) };
 }
 async function waitForForegroundOrHandoff(run, handoffMs) {
-    if (handoffMs < 0) {
+    if (!Number.isFinite(handoffMs) || handoffMs < 0) {
         return { kind: "completed", result: await run };
     }
     let timer;
@@ -651,9 +654,14 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
             args.permissionMode === "acceptEdits" ||
             args.permissionMode === "bypassPermissions"
             ? args.permissionMode
-            : "bypassPermissions";
+            : isExternalRuntimeContext(ctx)
+                ? "default"
+                : "bypassPermissions";
         const isWritableRun = permissionMode !== "default";
-        const background = args.background !== false;
+        // External runtimes do not participate in the native Engine's wake-up loop.
+        // A detached result would be queued for an Engine that is not driving this
+        // turn, so keep delegation attached to the parent runtime.
+        const background = isExternalRuntimeContext(ctx) ? false : args.background !== false;
         const cliName = cli === "codex" ? "Codex" : "Claude Code";
         if (background && !isValidSessionId(ctx?.sessionId)) {
             return `Error: cannot start a background ${cliName} job without a session — its result notification would be dropped. Retry with background:false, or ensure the tool runs inside a session.`;
@@ -801,7 +809,9 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
             permissionMode,
             imagePaths,
         };
-        const foregroundHandoffMs = options.foregroundHandoffMs ?? DRIVE_AGENT_FOREGROUND_HANDOFF_MS;
+        const foregroundHandoffMs = isExternalRuntimeContext(ctx)
+            ? Number.POSITIVE_INFINITY
+            : (options.foregroundHandoffMs ?? DRIVE_AGENT_FOREGROUND_HANDOFF_MS);
         if (background) {
             // Fail loud on a missing sessionId: a background job whose completion
             // notification can't be routed (enqueue drops invalid/empty sessionId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-capability-coding",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Coding capability pack for the generic code-shell agent core.",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,7 +39,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "dependencies": {
-    "@cjhyy/code-shell-core": "0.8.2"
+    "@cjhyy/code-shell-core": "0.8.4"
   },
   "engines": {
     "node": ">=20.10"