@cjhyy/code-shell-core 0.7.0-beta.1 → 0.7.1

package/dist/engine/engine.d.ts

@@ -4,10 +4,11 @@
 import type { LLMConfig, StreamCallback } from "../types.js";
 import { ToolRegistry } from "../tool-system/registry.js";
 import { type BuiltinToolFn } from "../tool-system/builtin/index.js";
+import { type ApprovalRouter } from "../tool-system/permission.js";
 import { HookRegistry } from "../hooks/registry.js";
 import { type GoalConfig, type GoalExtension } from "./goal.js";
 import { type CompactStrategy } from "../context/manager.js";
-import { SessionManager } from "../session/session-manager.js";
+import { SessionManager, type ForkSessionOptions, type ForkSessionResult } from "../session/session-manager.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
 import type { CapabilityOverride } from "../settings/schema.js";
 import { type FeatureFlagName } from "../settings/feature-flags.js";
@@ -34,6 +35,38 @@ export interface EnqueueSteerResult {
     accepted: boolean;
     id: string;
 }
+interface EngineRunOptions {
+    cwd?: string;
+    onStream?: StreamCallback;
+    signal?: AbortSignal;
+    sessionId?: string;
+    /** Immutable permission context for this run only. Omitted uses Engine config. */
+    permissionMode?: NonNullable<EngineConfig["permissionMode"]>;
+    /** Immutable plan context for this run only. Omitted follows permissionMode. */
+    planMode?: boolean;
+    /** Protocol connection's approval owner router for this run. */
+    approvalRouter?: ApprovalRouter;
+    /**
+     * Goal mode for this run: the engine registers a GoalStopHook so the
+     * turn loop runs until the session model judges this goal met. Falls
+     * back to config.goal. Orthogonal to permissionMode. Accepts a raw
+     * string or a full GoalConfig; normalized once at the run boundary.
+     */
+    goal?: string | GoalConfig;
+    /**
+     * Marks this turn's task as a SYNTHETIC system-reminder injection (e.g. a
+     * background-job completion notification the server re-injects to wake an
+     * idle session) rather than the user's own input. The task is still sent
+     * to the model as a `role:"user"` message, but it is persisted with an
+     * `injected` flag so the disk reader skips rendering it as a user bubble
+     * on replay (matching the live UI, which shows only the assistant reply).
+     */
+    injected?: boolean;
+    /** Stable id for this user-intent, used to make duplicate submits idempotent. */
+    clientMessageId?: string;
+    /** Structured input attachments. Legacy `<codeshell-image>` blocks remain supported. */
+    attachments?: InputAttachmentMeta[];
+}
 export { diskDefaultsFrom, type DiskDefaultPatch } from "../settings/disk-defaults.js";
 /**
  * Resolve the LLM config for a spawned child Engine.
@@ -122,6 +155,8 @@ export declare class Engine {
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     readonly runtime: EngineRuntime | null;
     private readonly sandboxCache;
+    private readonly interactiveBackends;
+    private activeApprovalRouter;
     /** Active permission mode for this Engine instance. */
     permissionMode: NonNullable<EngineConfig["permissionMode"]>;
     /** True when permissionMode === "plan". */
@@ -154,6 +189,7 @@ export declare class Engine {
      * LLM response arrives.
      */
     private ctxOverheadBySid;
+    private lastCacheReadBySid;
     /**
      * Step-gap steering queue (per sessionId, in-memory). Host pushes user
      * messages here via enqueueSteer while a run is in flight; the turn loop
@@ -187,6 +223,19 @@ export declare class Engine {
      * Null when idle; set at run start, cleared in run's finally.
      */
     private activeRunSession;
+    /**
+     * Same-instance run guard. Engine owns single-valued live controls and one
+     * HookRegistry, so a second run must not enter until the first has completed
+     * all state persistence and end hooks. This prevents handle contamination and
+     * whole-state saveState overlap only within this Engine instance. It does not
+     * coordinate different Engine instances sharing a sessionId, Workers, or
+     * processes; session-level locking/CAS for those cases is a separate finding.
+     */
+    private runInProgress;
+    /** Permission update requested while runInProgress. Applied in run() finally. */
+    private pendingPermissionMode;
+    /** Plan update paired with pendingPermissionMode for one atomic boundary apply. */
+    private pendingPlanMode;
     /** Public accessor so UI/clients can read the resolved per-model window. */
     get maxContextTokens(): number;
     private resolveMaxContextTokens;
@@ -278,7 +327,7 @@ export declare class Engine {
      * the queued draft) and is the handle `unsteer` uses to revoke a still-pending
      * entry. A blank id is tolerated but means the entry can't be revoked.
      */
-    enqueueSteer(sessionId: string, text: string, id?: string, clientMessageId?: string): EnqueueSteerResult;
+    enqueueSteer(sessionId: string, text: string, id?: string, clientMessageId?: string, attachments?: InputAttachmentMeta[]): EnqueueSteerResult;
     /**
      * Revoke a still-pending steer entry (the 撤回 path). Returns true if it was
      * removed, false if it was already consumed by the turn loop (can't take it
@@ -287,6 +336,8 @@ export declare class Engine {
     unsteer(sessionId: string, id: string): boolean;
     /** Drain + clear the steer queue for a session (turn loop consumes per step). */
     private consumeSteer;
+    /** Put failed steer preparation back ahead of messages queued while it was being prepared. */
+    private restoreSteer;
     /** Wire the cookie→browser injection callback (InjectCredential tool). Same
      *  post-construction injection model as setBrowserBridge. */
     setInjectCredential(fn: import("../tool-system/context.js").InjectCredentialFn | undefined): void;
@@ -303,35 +354,14 @@ export declare class Engine {
      * against a blank session. A stat probe, not a load.
      */
     sessionExistsOnDisk(sessionId: string): boolean;
+    forkSession(sourceSessionId: string, options?: ForkSessionOptions): ForkSessionResult;
     /**
-     * Run a task from start to finish.
-     */
-    run(task: string, options?: {
-        cwd?: string;
-        onStream?: StreamCallback;
-        signal?: AbortSignal;
-        sessionId?: string;
-        /**
-         * Goal mode for this run: the engine registers a GoalStopHook so the
-         * turn loop runs until the session model judges this goal met. Falls
-         * back to config.goal. Orthogonal to permissionMode. Accepts a raw
-         * string or a full GoalConfig; normalized once at the run boundary.
-         */
-        goal?: string | GoalConfig;
-        /**
-         * Marks this turn's task as a SYNTHETIC system-reminder injection (e.g. a
-         * background-job completion notification the server re-injects to wake an
-         * idle session) rather than the user's own input. The task is still sent
-         * to the model as a `role:"user"` message, but it is persisted with an
-         * `injected` flag so the disk reader skips rendering it as a user bubble
-         * on replay (matching the live UI, which shows only the assistant reply).
-         */
-        injected?: boolean;
-        /** Stable id for this user-intent, used to make duplicate submits idempotent. */
-        clientMessageId?: string;
-        /** Structured input attachments. Legacy `<codeshell-image>` blocks remain supported. */
-        attachments?: InputAttachmentMeta[];
-    }): Promise<EngineResult>;
+     * Run a task from start to finish. Rejects immediately when this Engine
+     * instance already has a run in progress; hosts that want queueing own that
+     * policy (for example ChatSession's FIFO queue).
+     */
+    run(task: string, options?: EngineRunOptions): Promise<EngineResult>;
+    private runExclusive;
     /**
      * Run the end-of-session memory pipeline as a fire-and-forget background
      * task. Extracts durable memories from the transcript, saves a session
@@ -482,7 +512,8 @@ export declare class Engine {
         after: number;
         strategy: "none (no active session)" | "no compaction needed" | "compacted" | CompactStrategy;
     }>;
-    private stripUserContextMessage;
+    private stripInjectedContextMessages;
+    private recordCacheReadDiagnostics;
     private getSettingsManager;
     /**
      * Update a config setting at runtime.
@@ -495,12 +526,14 @@ export declare class Engine {
     readSetting(key: string): unknown;
     private buildPermissionConfig;
     /**
-     * Switch permission mode at runtime. Takes effect immediately for any
-     * in-flight ToolExecutor (which holds a reference to the same classifier),
-     * and the new mode is used for any subsequent run() calls.
+     * Switch permission mode at runtime. Idle updates apply immediately; busy
+     * updates are committed atomically when the current run settles, so its
+     * classifier and ToolContext retain the immutable start-of-run snapshot.
      * Session-only — does not persist to settings.
      */
     setPermissionMode(mode: NonNullable<EngineConfig["permissionMode"]>): void;
+    private applyPermissionState;
+    private applyPendingPermissionState;
     getPermissionMode(): NonNullable<EngineConfig["permissionMode"]>;
     /**
      * Extend the in-flight run's turn ceiling and/or goal budgets (TODO 3.1 —