@cjhyy/code-shell-core 0.7.0 → 0.7.1

package/dist/session/transcript.js

@@ -10,11 +10,15 @@ export class Transcript {
     events = [];
     filePath;
     currentTurn = 0;
+    writer;
+    dirty = false;
+    lastFlushFailure;
     getFilePath() {
         return this.filePath;
     }
-    constructor(filePath) {
+    constructor(filePath, writer = appendFileSync) {
         this.filePath = filePath;
+        this.writer = writer;
         mkdirSync(dirname(filePath), { recursive: true });
         if (!existsSync(filePath)) {
             writeFileSync(filePath, "", "utf-8");
@@ -179,18 +183,65 @@ export class Transcript {
     get eventCount() {
         return this.events.length;
     }
+    /** True once any event failed both persistence attempts. Sticky by design. */
+    flushFailed() {
+        return this.dirty;
+    }
+    /** Structured details for the most recent unrecoverable flush failure. */
+    getFlushFailure() {
+        return this.lastFlushFailure ? { ...this.lastFlushFailure } : undefined;
+    }
     findMessageByClientId(clientMessageId) {
         return this.events.find((event) => event.type === "message" &&
             event.data.clientMessageId === clientMessageId);
     }
     flush(event) {
+        const line = JSON.stringify(event) + "\n";
         try {
-            appendFileSync(this.filePath, JSON.stringify(event) + "\n", "utf-8");
+            this.writer(this.filePath, line, "utf-8");
+            return true;
         }
-        catch {
-            // Silently fail on flush errors — events are still in memory
+        catch (firstError) {
+            try {
+                this.writer(this.filePath, line, "utf-8");
+                logger.warn("transcript.flush_retry_recovered", {
+                    filePath: this.filePath,
+                    errno: this.errorErrno(firstError),
+                    message: this.errorMessage(firstError),
+                });
+                return true;
+            }
+            catch (retryError) {
+                const err = retryError;
+                const failure = {
+                    errno: this.errorErrno(retryError),
+                    ...(typeof err?.code === "string" ? { code: err.code } : {}),
+                    message: this.errorMessage(retryError),
+                    timestamp: Date.now(),
+                    attempts: 2,
+                    recoverable: false,
+                    filePath: this.filePath,
+                };
+                // Sticky: a later successful append cannot restore an earlier missing
+                // JSONL event, so the transcript remains degraded for this instance.
+                this.dirty = true;
+                this.lastFlushFailure = failure;
+                logger.error("transcript.flush_failed", { ...failure });
+                return false;
+            }
         }
     }
+    errorErrno(error) {
+        const err = error;
+        if (typeof err?.errno === "number" || typeof err?.errno === "string")
+            return err.errno;
+        if (typeof err?.code === "string")
+            return err.code;
+        return "UNKNOWN";
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
     /**
      * Repair tool_result pairing issues:
      * - Orphaned tool_results (no matching tool_use) get removed
@@ -227,6 +278,70 @@ export class Transcript {
             return true;
         });
     }
+    static readEvents(filePath) {
+        let raw;
+        try {
+            raw = readFileSync(filePath, "utf-8");
+        }
+        catch {
+            return { events: [], malformedLineCount: 0 };
+        }
+        const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+        const events = [];
+        let malformedLineCount = 0;
+        for (const line of lines) {
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                malformedLineCount++;
+            }
+        }
+        return { events, malformedLineCount };
+    }
+    static eventsToMessages(events) {
+        const messages = [];
+        for (const event of events) {
+            switch (event.type) {
+                case "message": {
+                    const { role, content } = event.data;
+                    messages.push({ role, content });
+                    break;
+                }
+                case "tool_use":
+                    break;
+                case "tool_result": {
+                    const { toolCallId, result, error, contentBlocks } = event.data;
+                    const block = {
+                        type: "tool_result",
+                        tool_use_id: toolCallId,
+                        content: error
+                            ? `Error: ${error}`
+                            : Array.isArray(contentBlocks) && contentBlocks.length > 0
+                                ? contentBlocks
+                                : (result ?? "(no output)"),
+                    };
+                    const last = messages[messages.length - 1];
+                    if (last?.role === "user" && Array.isArray(last.content)) {
+                        last.content.push(block);
+                    }
+                    else {
+                        messages.push({ role: "user", content: [block] });
+                    }
+                    break;
+                }
+                case "summary": {
+                    const { summary } = event.data;
+                    messages.push({
+                        role: "user",
+                        content: `<system-reminder>Previous conversation was summarized:\n${summary}</system-reminder>`,
+                    });
+                    break;
+                }
+            }
+        }
+        return messages;
+    }
     static loadFromFile(filePath) {
         const transcript = new Transcript(filePath);
         if (!existsSync(filePath))

package/dist/tool-system/builtin/agent.js

@@ -269,7 +269,9 @@ streamOverride) {
     // that no longer exists. The child Engine is a fresh instance; plan-mode
     // isolation between parent and child is enforced via separate Engine
     // instances (finalized in T6).
-    const { text } = await spawner.spawn({ ...opts, streamOverride });
+    const { text, usage } = await spawner.spawn({ ...opts, streamOverride });
+    if (usage)
+        opts.recordBilledUsage?.(usage);
     const finalText = text || `Agent completed but produced no text output.`;
     safeEmit(startEndSink, { type: "agent_end", agentId, name, description, text: finalText, agentType });
     emitSubAgentHook(opts.hooks, "subagent_finish", { agentId, description, text: finalText });
@@ -372,6 +374,7 @@ export async function agentTool(args, ctx) {
             appendSystemPrompt: overrides.appendSystemPrompt,
             readOnlySession: overrides.resolvedType === "researcher" || overrides.resolvedType === "explorer",
             hooks: ctx?.hooks,
+            recordBilledUsage: ctx?.recordBilledUsage,
             signal: controller.signal,
         }, parentStream, // uiStream: agent_start/end → main feed
         transcriptSink)
@@ -581,6 +584,7 @@ async function runSyncSubAgent(args) {
         readOnlySession: overrides.resolvedType === "researcher" || overrides.resolvedType === "explorer",
         resumeSessionId,
         hooks: ctx?.hooks,
+        recordBilledUsage: ctx?.recordBilledUsage,
         signal: syncController.signal,
     });
     // Sentinel that the timer resolves with, so we can tell "agent finished" from

package/dist/tool-system/builtin/arena.js

@@ -390,6 +390,7 @@ export async function arenaTool(args, ctx) {
             signal,
         });
         const result = await arena.run(topic);
+        ctx.recordBilledUsage?.(result.usage);
         // Use session renderer (markdown, no ANSI) for tool results.
         // Terminal renderer (chalk) is only for direct stdout printing.
         const formattedResult = formatArenaResultForSession(result);

package/dist/tool-system/builtin/background-jobs.d.ts

@@ -23,6 +23,7 @@
 type Listener = () => void;
 export type BackgroundJobStatus = "running" | "cancelling" | "completed" | "failed" | "cancelled";
 export type BackgroundJobKind = "drive-agent" | "video" | "job";
+export type ExternalCliKind = "claude" | "codex";
 /** A background job, running or finished. */
 export interface BackgroundJobEntry {
     jobId: string;
@@ -48,11 +49,13 @@ export interface BackgroundJobEntry {
     /** DriveAgent prompt summary, separate from the UI-oriented description. */
     promptSummary?: string;
     /** External CLI kind for DriveAgent jobs. */
-    cli?: string;
+    cli?: ExternalCliKind;
     /** Client message that launched this external job. */
     originClientMessageId?: string;
-    /** Optional cancellation hook for jobs backed by a live process. */
-    abort?: () => void | Promise<void>;
+    /** Optional cancellation hook for jobs backed by a live process. It may
+     *  return a richer terminal outcome when cancellation races with a result
+     *  that must still be retained (for example, a remotely rendered video). */
+    abort?: () => void | BackgroundJobOutcome | Promise<void | BackgroundJobOutcome>;
 }
 /** Outcome passed to finish() to record how a job ended. */
 export interface BackgroundJobOutcome {
@@ -65,9 +68,9 @@ export interface BackgroundJobStartOptions {
     kind?: BackgroundJobKind;
     cwd?: string;
     promptSummary?: string;
-    cli?: string;
+    cli?: ExternalCliKind;
     originClientMessageId?: string;
-    abort?: () => void | Promise<void>;
+    abort?: () => void | BackgroundJobOutcome | Promise<void | BackgroundJobOutcome>;
 }
 declare class BackgroundJobRegistry {
     private jobs;

package/dist/tool-system/builtin/background-jobs.js

@@ -34,16 +34,18 @@ function isActiveStatus(status) {
 async function waitForAbort(abort) {
     let timer;
     try {
-        await Promise.race([
+        const result = await Promise.race([
             Promise.resolve().then(abort),
             new Promise((resolve) => {
-                timer = setTimeout(resolve, CANCEL_WAIT_TIMEOUT_MS);
+                timer = setTimeout(() => resolve(undefined), CANCEL_WAIT_TIMEOUT_MS);
             }),
         ]);
+        return result && typeof result === "object" ? result : undefined;
     }
     catch {
         // Cancellation is best-effort; the terminal state still closes after the
         // abort hook settles or the hard deadline expires.
+        return undefined;
     }
     finally {
         if (timer)
@@ -118,20 +120,22 @@ class BackgroundJobRegistry {
         // process as active until the abort hook confirms exit.
         entry.status = "cancelling";
         this.notify();
-        if (entry.abort)
-            await waitForAbort(entry.abort);
+        const abortOutcome = entry.abort ? await waitForAbort(entry.abort) : undefined;
         // Session teardown/reset may have removed the entry while termination was
         // in flight. Do not resurrect or notify for a closed session.
         if (this.jobs.get(jobId) !== entry || entry.status !== "cancelling")
             return false;
-        entry.status = "cancelled";
+        entry.status = abortOutcome?.status ?? "cancelled";
         entry.finishedAt = Date.now();
-        if (outcome?.finalText !== undefined)
-            entry.finalText = outcome.finalText;
-        if (outcome?.ccSessionId !== undefined)
-            entry.ccSessionId = outcome.ccSessionId;
-        if (outcome?.changedFiles !== undefined)
-            entry.changedFiles = outcome.changedFiles;
+        const finalText = abortOutcome?.finalText ?? outcome?.finalText;
+        const ccSessionId = abortOutcome?.ccSessionId ?? outcome?.ccSessionId;
+        const changedFiles = abortOutcome?.changedFiles ?? outcome?.changedFiles;
+        if (finalText !== undefined)
+            entry.finalText = finalText;
+        if (ccSessionId !== undefined)
+            entry.ccSessionId = ccSessionId;
+        if (changedFiles !== undefined)
+            entry.changedFiles = changedFiles;
         this.evictTerminalOverCap(entry.sessionId);
         this.notify();
         return true;

package/dist/tool-system/builtin/background-work.d.ts

@@ -1,5 +1,5 @@
 import { type AsyncAgentStatus } from "./agent-registry.js";
-import { type BackgroundJobStatus } from "./background-jobs.js";
+import { type BackgroundJobKind, type BackgroundJobStatus, type ExternalCliKind } from "./background-jobs.js";
 import { type BgShell } from "../../runtime/background-shell.js";
 export type BackgroundWorkKind = "subagent" | "job" | "shell";
 export interface BackgroundWorkItem {
@@ -51,6 +51,11 @@ export type BackgroundWorkEntry = WithSource<{
     finalText?: string;
     /** Files an external agent (DriveAgent) changed, parsed from its transcript. */
     changedFiles?: string[];
+    /** Machine-readable job kind and external-session linkage for DriveAgent. */
+    jobKind?: BackgroundJobKind;
+    externalSessionId?: string;
+    cli?: ExternalCliKind;
+    cwd?: string;
 }>;
 /**
  * Every background-work item spawned by `sessionId`, with per-kind detail, for

package/dist/tool-system/builtin/background-work.js

@@ -14,7 +14,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { asyncAgentRegistry } from "./agent-registry.js";
-import { backgroundJobRegistry } from "./background-jobs.js";
+import { backgroundJobRegistry, } from "./background-jobs.js";
 import { backgroundShellManager } from "../../runtime/background-shell.js";
 import { codeShellHome } from "../../session/session-manager.js";
 /** List every still-running background work item spawned by `sessionId`. */
@@ -125,6 +125,10 @@ export function listBackgroundWorkForUI(sessionId, opts = {}) {
             ...(j.finishedAt != null ? { finishedAt: j.finishedAt } : {}),
             ...(j.finalText != null ? { finalText: j.finalText } : {}),
             ...(j.changedFiles && j.changedFiles.length ? { changedFiles: j.changedFiles } : {}),
+            ...(j.kind ? { jobKind: j.kind } : {}),
+            ...(j.ccSessionId ? { externalSessionId: j.ccSessionId } : {}),
+            ...(j.cli === "claude" || j.cli === "codex" ? { cli: j.cli } : {}),
+            ...(j.cwd ? { cwd: j.cwd } : {}),
             sourceSession: sourceSession(sessionId, j.sessionId),
         });
     }

package/dist/tool-system/builtin/bash.d.ts

@@ -16,9 +16,7 @@
  *     Killed by signal, the truncation message, sandbox denial hints).
  */
 import type { ToolContext } from "../context.js";
-import type { ToolDefinition, ToolResult } from "../../types.js";
+import type { ToolDefinition } from "../../types.js";
+import type { ToolExecutionResult } from "./index.js";
 export declare const bashToolDef: ToolDefinition;
-export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | {
-    result: string;
-    sandbox: ToolResult["sandbox"];
-}>;
+export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | ToolExecutionResult>;

package/dist/tool-system/builtin/bash.js

@@ -82,7 +82,8 @@ export async function bashTool(args, ctx) {
     const sandbox = sandboxMark(backend);
     // Tag every textual return below with the sandbox mark so the UI badge
     // shows up whether the command succeeded, failed, timed out, or aborted.
-    const mark = (result) => ({ result, sandbox });
+    const mark = (result) => ({ ok: true, result, sandbox });
+    const fail = (error, details = {}) => ({ ok: false, error, sandbox, ...details });
     // Project localEnvironment.env (ctx.shellEnv) layers on top of either the
     // full passthrough (off) or the hardened allowlist (sandboxed) — see
     // mergeShellEnv. Background mode merges the same way inside the manager.
@@ -93,7 +94,8 @@ export async function bashTool(args, ctx) {
     // blocked, and Engine.run's wait-for-background loop never waits on it
     // (§难点5: that loop only looks at asyncAgentRegistry).
     if (args.run_in_background === true) {
-        return mark(runInBackground(command, ctx));
+        const backgroundResult = runInBackground(command, ctx);
+        return backgroundResult.startsWith("Error:") ? fail(backgroundResult) : mark(backgroundResult);
     }
     // A6: lifecycle (spawn, kill cascade, IO drain, byte cap, abort/timeout)
     // is centralized in safeSpawnShell. We still handle Bash's user-facing
@@ -112,13 +114,13 @@ export async function bashTool(args, ctx) {
         signal: ctx?.signal,
     });
     if (result.aborted) {
-        return mark(wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.");
+        return fail(wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.");
     }
     if (result.timedOut) {
-        return mark(`Command timed out after ${timeout}ms`);
+        return fail(`Command timed out after ${timeout}ms`);
     }
     if (result.spawnFailed) {
-        return mark(`Failed to spawn command: ${result.error ?? "unknown error"}`);
+        return fail(`Failed to spawn command: ${result.error ?? "unknown error"}`);
     }
     let body = "";
     if (result.stdout)
@@ -150,6 +152,9 @@ export async function bashTool(args, ctx) {
     const hint = backend.hintForBlockedOutput?.(result.stderr);
     if (hint)
         output += hint;
+    if ((code !== 0 && code !== null) || (code === null && sig)) {
+        return fail(output, { exitCode: code, signal: sig, stderr: result.stderr });
+    }
     return mark(output);
 }
 /**

package/dist/tool-system/builtin/browser-tools.d.ts

@@ -22,9 +22,9 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
-import type { BuiltinToolResult } from "./index.js";
+import type { BuiltinToolReturn } from "./index.js";
 export declare const browserObserveToolDef: ToolDefinition;
-export declare function browserObserveTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolResult>;
+export declare function browserObserveTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolReturn>;
 export declare const browserActToolDef: ToolDefinition;
 export declare function browserActTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const browserNavigateToolDef: ToolDefinition;

package/dist/tool-system/builtin/edit.d.ts

@@ -3,5 +3,6 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
+import type { ToolFailure } from "./index.js";
 export declare const editToolDef: ToolDefinition;
-export declare function editTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function editTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | ToolFailure>;

package/dist/tool-system/builtin/edit.js

@@ -1,11 +1,12 @@
 /**
  * Built-in Edit file tool — exact string replacement.
  */
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { fileCache } from "./file-cache.js";
 import { detectEol, toLf, applyEol } from "./eol.js";
+import { getFinalWritePathSnapshot, revalidateFinalWritePath, writeFileNoFollow, } from "../path-policy.js";
 export const editToolDef = {
     name: "Edit",
     description: "Perform exact string replacements in a file. " +
@@ -50,7 +51,11 @@ export async function editTool(args, ctx) {
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {
-        const raw = await readFile(filePath, "utf-8");
+        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd);
+        const beforeRead = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        if ("error" in beforeRead)
+            return { ok: false, error: beforeRead.error };
+        const raw = await readFile(beforeRead.resolvedPath, "utf-8");
         // CRLF handling: detect the file's line ending, then match/replace in LF
         // space (the model emits LF, so a CRLF file would never match otherwise),
         // and write back in the ORIGINAL EOL so a CRLF file stays CRLF (no whole-
@@ -72,7 +77,10 @@ export async function editTool(args, ctx) {
         const updatedLf = replaceAll
             ? content.split(oldLf).join(newLf)
             : content.replace(oldLf, newLf);
-        await writeFile(filePath, applyEol(updatedLf, eol), "utf-8");
+        const beforeWrite = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        if ("error" in beforeWrite)
+            return { ok: false, error: beforeWrite.error };
+        await writeFileNoFollow(beforeWrite.resolvedPath, applyEol(updatedLf, eol));
         fileCache.invalidate(filePath);
         const count = replaceAll
             ? (content.split(oldLf).length - 1)
@@ -84,7 +92,7 @@ export async function editTool(args, ctx) {
         return `Successfully edited ${filePath} (${count} replacement${count > 1 ? "s" : ""})\n${diffSummary}`;
     }
     catch (err) {
-        return `Error editing file: ${err.message}`;
+        return { ok: false, error: `Error editing file: ${err.message}` };
     }
 }
 function generateCompactDiff(oldLines, newLines, filePath) {

package/dist/tool-system/builtin/generate-video.d.ts

@@ -32,6 +32,10 @@ export declare function __normalizeImagesForTests(images: string[] | undefined,
     ok: false;
     error: string;
 }>;
+export declare function __setVideoPollingLimitsForTests(limits: {
+    maxPollMs: number;
+    requestTimeoutMs: number;
+} | null): void;
 export declare const generateVideoToolDef: ToolDefinition;
 export declare function __setVideoProviderForTests(p: VideoProvider | null): void;
 export declare function isGenerateVideoAvailable(cwd?: string, nowMs?: number): boolean;