@cjhyy/code-shell-core 0.6.0-rc.8 → 0.7.0-beta.1

package/dist/protocol/types.d.ts

@@ -47,10 +47,43 @@ export declare const ErrorCodes: {
      */
     readonly Cancelled: -32005;
 };
+export type InputAttachmentKind = "image" | "file" | "directory";
+export type InputAttachmentOrigin = "paste" | "os-drop" | "file-panel" | "picker" | "mention" | "generated" | "tool";
+export interface InputAttachmentMeta {
+    id: string;
+    sessionId: string;
+    kind: InputAttachmentKind;
+    origin: InputAttachmentOrigin;
+    path: string;
+    absPath: string;
+    relPath?: string;
+    mime?: string;
+    size: number;
+    sha256: string;
+    originalName?: string;
+    createdAt: number;
+    sourcePath?: string;
+    width?: number;
+    height?: number;
+    vision?: {
+        include: boolean;
+        mediaPath?: string;
+        detail?: "low" | "standard" | "high";
+    };
+    directory?: {
+        treePath?: string;
+        truncated?: boolean;
+        entryCount?: number;
+    };
+}
 /** Start an agent run with a user task. */
 export interface RunParams {
     sessionId: string;
     task: string;
+    /** Structured input attachments. Legacy `<codeshell-image>` task blocks remain supported. */
+    attachments?: InputAttachmentMeta[];
+    /** Stable id for the user's submit intent; duplicate ids are idempotent. */
+    clientMessageId?: string;
     /**
      * Working directory for this run. When omitted, the Engine uses its
      * configured cwd.
@@ -121,6 +154,10 @@ export interface CancelParams {
 export interface CloseSessionParams {
     sessionId: string;
 }
+/** Reset a live session's workspace binding back to main. */
+export interface ReleaseWorkspaceParams {
+    sessionId: string;
+}
 /** Inject context into a session transcript. */
 export interface InjectParams {
     sessionId: string;
@@ -133,6 +170,8 @@ export interface SteerParams {
     /** Stable host-side id for this queued draft. Rides through to the
      *  steer_injected event and is the handle Unsteer uses to revoke it. */
     id?: string;
+    /** Stable submit-intent id, distinct from the queued steer id. */
+    clientMessageId?: string;
 }
 /** Revoke a still-pending steer entry by id (before the loop consumes it). */
 export interface UnsteerParams {
@@ -256,6 +295,12 @@ export interface ApprovalRequestNotification {
     requestId: string;
     request: ApprovalRequest;
 }
+/** Server tells clients a pending approval/ask has been resolved elsewhere. */
+export interface ApprovalResolvedNotification {
+    /** Originating engine session when known. */
+    sessionId?: string;
+    requestId: string;
+}
 /** Server status changed. */
 export interface StatusNotification {
     status: "ready" | "running" | "error" | "shutdown";
@@ -275,6 +320,8 @@ export declare const Methods: {
     readonly Unsteer: "agent/unsteer";
     /** Close (destroy) a session. */
     readonly CloseSession: "agent/closeSession";
+    /** Reset a session's workspace binding to main without closing it. */
+    readonly ReleaseWorkspace: "agent/releaseWorkspace";
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     readonly GoalExtend: "agent/goalExtend";
     /** Clear a session's persisted active goal (CC /goal clear). */
@@ -289,6 +336,10 @@ export declare const Methods: {
     readonly BackgroundWork: "agent/backgroundWork";
     readonly StreamEvent: "agent/streamEvent";
     readonly ApprovalRequest: "agent/approvalRequest";
+    /** Server-initiated resolution of a pending approval/ask (e.g. a goal-mode
+     *  AskUserQuestion that timed out) so every client can dismiss its stale card
+     *  without a user decision. Same envelope the desktop main broadcasts. */
+    readonly ApprovalResolved: "agent/approvalResolved";
     readonly Status: "agent/status";
 };
 export declare function createRequest(method: string, params?: Record<string, unknown>): RpcRequest;

package/dist/protocol/types.js

@@ -41,6 +41,8 @@ export const Methods = {
     Unsteer: "agent/unsteer",
     /** Close (destroy) a session. */
     CloseSession: "agent/closeSession",
+    /** Reset a session's workspace binding to main without closing it. */
+    ReleaseWorkspace: "agent/releaseWorkspace",
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     GoalExtend: "agent/goalExtend",
     /** Clear a session's persisted active goal (CC /goal clear). */
@@ -56,6 +58,10 @@ export const Methods = {
     // Server → Client (notifications, no id)
     StreamEvent: "agent/streamEvent",
     ApprovalRequest: "agent/approvalRequest",
+    /** Server-initiated resolution of a pending approval/ask (e.g. a goal-mode
+     *  AskUserQuestion that timed out) so every client can dismiss its stale card
+     *  without a user decision. Same envelope the desktop main broadcasts. */
+    ApprovalResolved: "agent/approvalResolved",
     Status: "agent/status",
 };
 // ─── Helpers ────────────────────────────────────────────────────────

package/dist/run/FileRunStore.js

@@ -12,6 +12,8 @@
 import { mkdirSync, existsSync, readFileSync, writeFileSync, appendFileSync, readdirSync, renameSync, rmSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { assertSafeRunFileId, assertSafeRunId } from "./ids.js";
 export class FileRunStore {
     runsDir;
     constructor(storageDir) {
@@ -20,6 +22,7 @@ export class FileRunStore {
     }
     // ─── Helpers ───────────────────────────────────────────────────
     runDir(runId) {
+        assertSafeRunId(runId);
         return join(this.runsDir, runId);
     }
     ensureRunDir(runId) {
@@ -31,7 +34,7 @@ export class FileRunStore {
         return dir;
     }
     writeJson(filePath, data) {
-        const tmp = filePath + ".tmp";
+        const tmp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
         try {
             writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
             // Atomic rename — prevents partial writes on crash
@@ -153,6 +156,8 @@ export class FileRunStore {
     }
     // ─── Checkpoints ───────────────────────────────────────────────
     async saveCheckpoint(cp) {
+        assertSafeRunId(cp.runId);
+        assertSafeRunFileId(cp.checkpointId, "checkpoint id");
         const dir = this.runDir(cp.runId);
         this.writeJson(join(dir, "checkpoints", `${cp.checkpointId}.json`), cp);
     }
@@ -175,10 +180,14 @@ export class FileRunStore {
     }
     // ─── Approvals ─────────────────────────────────────────────────
     async saveApproval(approval) {
+        assertSafeRunId(approval.runId);
+        assertSafeRunFileId(approval.approvalId, "approval id");
         const dir = this.runDir(approval.runId);
         this.writeJson(join(dir, "approvals", `${approval.approvalId}.json`), approval);
     }
     async getApproval(runId, approvalId) {
+        assertSafeRunId(runId);
+        assertSafeRunFileId(approvalId, "approval id");
         return this.readJson(join(this.runDir(runId), "approvals", `${approvalId}.json`));
     }
     async getPendingApproval(runId) {

package/dist/run/Heartbeat.js

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { assertSafeRunId } from "./ids.js";
 export class Heartbeat {
     runsDir;
     intervalMs;
@@ -23,6 +24,12 @@ export class Heartbeat {
      * Start heartbeat for a run. Writes immediately, then repeats on interval.
      */
     start(runId) {
+        assertSafeRunId(runId);
+        const existing = this.timers.get(runId);
+        if (existing) {
+            clearInterval(existing);
+            this.timers.delete(runId);
+        }
         // Write first heartbeat immediately
         this.write(runId);
         // Schedule periodic heartbeats
@@ -37,6 +44,7 @@ export class Heartbeat {
      * Stop heartbeat for a run and remove the heartbeat file.
      */
     stop(runId) {
+        assertSafeRunId(runId);
         const timer = this.timers.get(runId);
         if (timer) {
             clearInterval(timer);
@@ -56,6 +64,7 @@ export class Heartbeat {
      * Read the last heartbeat for a run. Returns null if no heartbeat exists.
      */
     read(runId) {
+        assertSafeRunId(runId);
         const filePath = this.filePath(runId);
         if (!existsSync(filePath))
             return null;
@@ -71,6 +80,7 @@ export class Heartbeat {
      * Returns true if stale or missing, false if recent.
      */
     isStale(runId, thresholdMs) {
+        assertSafeRunId(runId);
         const threshold = thresholdMs ?? this.intervalMs * 3;
         const data = this.read(runId);
         if (!data)
@@ -81,6 +91,7 @@ export class Heartbeat {
      * Check if the process that wrote the heartbeat is still alive.
      */
     isProcessAlive(runId) {
+        assertSafeRunId(runId);
         const data = this.read(runId);
         if (!data)
             return false;
@@ -118,6 +129,7 @@ export class Heartbeat {
         }
     }
     filePath(runId) {
+        assertSafeRunId(runId);
         return join(this.runsDir, runId, "heartbeat");
     }
 }

package/dist/run/RunApprovalBackend.d.ts

@@ -16,6 +16,7 @@ import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
 export interface PendingApproval {
     resolve: (result: ApprovalResult) => void;
     request: ApprovalRequest;
+    timer: ReturnType<typeof setTimeout>;
 }
 export interface PendingInput {
     resolve: (answer: string) => void;
@@ -32,6 +33,7 @@ export interface RunLifecycleHooks {
 export declare class RunApprovalBackend implements ApprovalBackend {
     private pendingApproval;
     private hooks;
+    private approvalRequestSeq;
     setHooks(hooks: RunLifecycleHooks): void;
     /** Max time (ms) to wait for approval before auto-rejecting. Default: 24h */
     private timeoutMs;
@@ -42,6 +44,7 @@ export declare class RunApprovalBackend implements ApprovalBackend {
      */
     resolveApproval(result: ApprovalResult): boolean;
     hasPendingApproval(): boolean;
+    private supersedePendingApproval;
 }
 /**
  * Creates an AskUserFn that suspends the run when user input is needed.

package/dist/run/RunApprovalBackend.js

@@ -14,6 +14,7 @@
 export class RunApprovalBackend {
     pendingApproval = null;
     hooks = null;
+    approvalRequestSeq = 0;
     setHooks(hooks) {
         this.hooks = hooks;
     }
@@ -23,7 +24,8 @@ export class RunApprovalBackend {
         this.timeoutMs = ms;
     }
     async requestApproval(request) {
-        if (!this.hooks) {
+        const hooks = this.hooks;
+        if (!hooks) {
             // No hooks wired — fail CLOSED. This backend is the engine's approval
             // path for an interactive run; if a host forgot to setHooks() there is
             // no UI to ask, so auto-approving every tool (the old behavior) silently
@@ -34,11 +36,8 @@ export class RunApprovalBackend {
                 reason: "run approval backend has no lifecycle hooks wired (denied fail-closed)",
             };
         }
-        // Notify RunManager that approval is needed
-        const { approvalId } = await this.hooks.onApprovalNeeded(request);
-        // Suspend execution until resolved (with timeout safety net)
+        const requestSeq = ++this.approvalRequestSeq;
         return new Promise((resolve) => {
-            this.pendingApproval = { resolve, request };
             const timer = setTimeout(() => {
                 if (this.pendingApproval?.resolve === resolve) {
                     this.pendingApproval = null;
@@ -48,6 +47,30 @@ export class RunApprovalBackend {
             if (typeof timer === "object" && "unref" in timer) {
                 timer.unref();
             }
+            this.supersedePendingApproval();
+            this.pendingApproval = { resolve, request, timer };
+            void Promise.resolve()
+                .then(() => hooks.onApprovalNeeded(request))
+                .then(() => {
+                if (requestSeq !== this.approvalRequestSeq &&
+                    this.pendingApproval?.resolve === resolve) {
+                    this.pendingApproval = null;
+                    clearTimeout(timer);
+                    resolve({
+                        approved: false,
+                        reason: "superseded: a newer approval request replaced this one before it was answered",
+                    });
+                }
+            }, (err) => {
+                if (this.pendingApproval?.resolve !== resolve)
+                    return;
+                this.pendingApproval = null;
+                clearTimeout(timer);
+                resolve({
+                    approved: false,
+                    reason: `approval request failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            });
         });
     }
     /**
@@ -56,14 +79,26 @@ export class RunApprovalBackend {
     resolveApproval(result) {
         if (!this.pendingApproval)
             return false;
-        const { resolve } = this.pendingApproval;
+        const { resolve, timer } = this.pendingApproval;
         this.pendingApproval = null;
+        clearTimeout(timer);
         resolve(result);
         return true;
     }
     hasPendingApproval() {
         return this.pendingApproval !== null;
     }
+    supersedePendingApproval() {
+        if (!this.pendingApproval)
+            return;
+        const { resolve, timer } = this.pendingApproval;
+        this.pendingApproval = null;
+        clearTimeout(timer);
+        resolve({
+            approved: false,
+            reason: "superseded: a newer approval request replaced this one before it was answered",
+        });
+    }
 }
 // ─── RunAskUserAdapter ───────────────────────────────────────────
 /**

package/dist/run/RunLock.js

@@ -10,6 +10,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { lock, check, unlock } from "../utils/lockfile.js";
 import { logger } from "../logging/logger.js";
+import { assertSafeRunId } from "./ids.js";
 export class RunLock {
     runsDir;
     staleMs;
@@ -135,6 +136,7 @@ export class RunLock {
         }
     }
     lockTarget(runId) {
+        assertSafeRunId(runId);
         return join(this.runsDir, runId, "run.json");
     }
 }

package/dist/run/RunManager.d.ts

@@ -66,6 +66,7 @@ export declare class RunManager {
     resume(runId: string, input?: ResumeRunInput): Promise<void>;
     private resumeInner;
     cancel(runId: string, reason?: string): Promise<void>;
+    private cancelInner;
     get(runId: string): Promise<RunSnapshot | null>;
     list(query?: ListRunsQuery): Promise<RunSnapshot[]>;
     getEvents(runId: string): Promise<RunEvent[]>;
@@ -90,5 +91,6 @@ export declare class RunManager {
     private transition;
     private emitRunEvent;
     private notifySubscribers;
+    private getPendingApprovalForResume;
     private getOrThrow;
 }

package/dist/run/RunManager.js

@@ -19,7 +19,13 @@ import { ArtifactTracker } from "./ArtifactTracker.js";
 import { RunLock } from "./RunLock.js";
 import { Heartbeat } from "./Heartbeat.js";
 import { NoopEvaluator } from "./Evaluator.js";
+import { assertSafeRunFileId, assertSafeRunId } from "./ids.js";
 import { VALID_TRANSITIONS } from "./types.js";
+function hasOwnString(value, key) {
+    return (value !== undefined &&
+        Object.prototype.hasOwnProperty.call(value, key) &&
+        typeof value[key] === "string");
+}
 export class RunManager {
     store;
     queue;
@@ -69,6 +75,9 @@ export class RunManager {
     async submit(input) {
         const now = Date.now();
         const runId = nanoid(16);
+        if (input.parentRunId !== undefined && input.parentRunId !== null) {
+            assertSafeRunId(input.parentRunId);
+        }
         const snapshot = {
             runId,
             objective: input.objective,
@@ -110,6 +119,7 @@ export class RunManager {
     }
     // ─── Resume ────────────────────────────────────────────────────
     async resume(runId, input) {
+        assertSafeRunId(runId);
         // Serialize resume/cancel decisions per run. Without this, two concurrent
         // resumes (or resume racing cancel) both pass the status check below —
         // status stays `waiting_*` until a later `await transition()` — and both
@@ -139,18 +149,15 @@ export class RunManager {
         if (handle) {
             if (run.status === "waiting_approval" && input?.approvalDecision) {
                 const { approvalId, approved, reason } = input.approvalDecision;
-                // Persist the approval decision
-                const approval = await this.store.getApproval(runId, approvalId);
-                if (approval && approval.status === "pending") {
-                    approval.status = approved ? "approved" : "rejected";
-                    approval.resolvedAt = Date.now();
-                    await this.store.saveApproval(approval);
-                    await this.emitRunEvent(runId, "approval_resolved", {
-                        approvalId,
-                        approved,
-                        reason,
-                    });
-                }
+                const approval = await this.getPendingApprovalForResume(run, approvalId);
+                approval.status = approved ? "approved" : "rejected";
+                approval.resolvedAt = Date.now();
+                await this.store.saveApproval(approval);
+                await this.emitRunEvent(runId, "approval_resolved", {
+                    approvalId,
+                    approved,
+                    reason,
+                });
                 // Transition back to running and resolve the suspended Engine
                 await this.transition(run, "queued");
                 await this.transition(run, "running");
@@ -158,7 +165,7 @@ export class RunManager {
                 handle.resolveApproval(approved, reason);
                 return;
             }
-            if (run.status === "waiting_input" && input?.userInput) {
+            if (run.status === "waiting_input" && hasOwnString(input, "userInput")) {
                 await this.transition(run, "queued");
                 await this.transition(run, "running");
                 await this.emitRunEvent(runId, "run_resumed", { userInput: input.userInput });
@@ -177,17 +184,15 @@ export class RunManager {
         // Re-queue the run for a fresh execution attempt
         if (input?.approvalDecision) {
             const { approvalId, approved, reason } = input.approvalDecision;
-            const approval = await this.store.getApproval(runId, approvalId);
-            if (approval && approval.status === "pending") {
-                approval.status = approved ? "approved" : "rejected";
-                approval.resolvedAt = Date.now();
-                await this.store.saveApproval(approval);
-                await this.emitRunEvent(runId, "approval_resolved", {
-                    approvalId,
-                    approved,
-                    reason,
-                });
-            }
+            const approval = await this.getPendingApprovalForResume(run, approvalId);
+            approval.status = approved ? "approved" : "rejected";
+            approval.resolvedAt = Date.now();
+            await this.store.saveApproval(approval);
+            await this.emitRunEvent(runId, "approval_resolved", {
+                approvalId,
+                approved,
+                reason,
+            });
         }
         await this.transition(run, "queued");
         await this.emitRunEvent(runId, "run_resumed", {
@@ -197,6 +202,19 @@ export class RunManager {
     }
     // ─── Cancel ────────────────────────────────────────────────────
     async cancel(runId, reason) {
+        assertSafeRunId(runId);
+        if (this.resolvingRuns.has(runId)) {
+            throw new Error(`Cannot cancel run ${runId}: another resume/cancel is already in progress`);
+        }
+        this.resolvingRuns.add(runId);
+        try {
+            await this.cancelInner(runId, reason);
+        }
+        finally {
+            this.resolvingRuns.delete(runId);
+        }
+    }
+    async cancelInner(runId, reason) {
         const run = await this.getOrThrow(runId);
         if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
             throw new Error(`Cannot cancel run ${runId}: already in terminal state ${run.status}`);
@@ -225,16 +243,19 @@ export class RunManager {
     }
     // ─── Query ─────────────────────────────────────────────────────
     async get(runId) {
+        assertSafeRunId(runId);
         return this.store.get(runId);
     }
     async list(query) {
         return this.store.list(query);
     }
     async getEvents(runId) {
+        assertSafeRunId(runId);
         return this.store.listEvents(runId);
     }
     // ─── Attach (live stream) ──────────────────────────────────────
     attach(runId, cb) {
+        assertSafeRunId(runId);
         if (!this.subscribers.has(runId)) {
             this.subscribers.set(runId, new Set());
         }
@@ -326,6 +347,7 @@ export class RunManager {
     }
     // ─── Internal: Execute a run ───────────────────────────────────
     async executeRun(runId) {
+        assertSafeRunId(runId);
         const run = await this.getOrThrow(runId);
         // Acquire run lock — prevents concurrent execution by multiple workers
         const lockResult = await this.lock.acquire(runId);
@@ -657,7 +679,25 @@ export class RunManager {
         }
     }
     // ─── Helpers ───────────────────────────────────────────────────
+    async getPendingApprovalForResume(run, approvalId) {
+        assertSafeRunFileId(approvalId, "approval id");
+        if (run.latestApprovalId !== approvalId) {
+            throw new Error(`Cannot resume run ${run.runId}: approval ${approvalId} is not the latest pending approval`);
+        }
+        const approval = await this.store.getApproval(run.runId, approvalId);
+        if (!approval) {
+            throw new Error(`Cannot resume run ${run.runId}: approval ${approvalId} was not found`);
+        }
+        if (approval.runId !== run.runId || approval.approvalId !== approvalId) {
+            throw new Error(`Cannot resume run ${run.runId}: approval ${approvalId} does not match this run`);
+        }
+        if (approval.status !== "pending") {
+            throw new Error(`Cannot resume run ${run.runId}: approval ${approvalId} is ${approval.status}, not pending`);
+        }
+        return approval;
+    }
     async getOrThrow(runId) {
+        assertSafeRunId(runId);
         const run = await this.store.get(runId);
         if (!run)
             throw new Error(`Run not found: ${runId}`);

package/dist/run/ids.d.ts

@@ -0,0 +1,2 @@
+export declare function assertSafeRunId(runId: unknown): asserts runId is string;
+export declare function assertSafeRunFileId(value: unknown, label: string): asserts value is string;

package/dist/run/ids.js

@@ -0,0 +1,23 @@
+function assertSafeRunSegment(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`invalid ${label}: must be a non-empty string`);
+    }
+    if (value.includes("/") || value.includes("\\")) {
+        throw new Error(`invalid ${label}: contains path separator: ${value}`);
+    }
+    if (value === "." || value === ".." || value.includes("..")) {
+        throw new Error(`invalid ${label}: contains parent-dir token: ${value}`);
+    }
+    if (!/^[A-Za-z0-9_.-]+$/.test(value)) {
+        throw new Error(`invalid ${label}: unexpected characters: ${value}`);
+    }
+    if (value.length > 128) {
+        throw new Error(`invalid ${label}: too long (max 128 chars)`);
+    }
+}
+export function assertSafeRunId(runId) {
+    assertSafeRunSegment(runId, "run id");
+}
+export function assertSafeRunFileId(value, label) {
+    assertSafeRunSegment(value, label);
+}

package/dist/runtime/background-shell.d.ts

@@ -103,6 +103,7 @@ export declare class BackgroundShellManager {
     /** Raw retained output (no cleaning) — test/UI helper. */
     readOutputRaw(shellId: string): string | undefined;
     listForSession(sessionId: string): BgShell[];
+    list(): BgShell[];
     /**
      * Read a shell's output. `mode=incremental` (default) returns text since the
      * agent's last read; `mode=all` returns the full retained buffer. Output is