@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/protocol/chat-session.js

@@ -1,4 +1,5 @@
 import { isAbortError } from "../llm/client-base.js";
+import { isSameGoalInstance } from "../goal/lifecycle.js";
 /**
  * One ChatSession per UI chat tab. Owns a single Engine, an AbortController
  * for the active turn, and a FIFO queue so a fast second send waits for the
@@ -8,16 +9,16 @@ export class ChatSession {
     id;
     engine;
     /**
-     * Per-session approval callbacks indexed by tool-call requestId.
+     * Per-session approval callbacks and resolver-free metadata indexed by requestId.
      * `readonly` guards the Map reference (preventing reassignment); the
      * contents are mutated by `.set()` / `.delete()` as approvals come and go.
-     * Task 10 will register entries here when the Engine raises an approval
-     * request and clean them up on response.
+     * The resolver stays process-local; only metadata is eligible for Pet snapshots.
      */
     pendingApprovals = new Map();
     lastActivityAt = Date.now();
     queue = [];
     active = null;
+    exclusiveOperation = false;
     controller = null;
     defaultOnStream;
     /**
@@ -44,6 +45,8 @@ export class ChatSession {
      * (the user is engaging again) so normal wakeups resume working afterward.
      */
     cancelledSinceLastTurn = false;
+    settlePromise = Promise.resolve();
+    resolveSettled = null;
     constructor(opts) {
         this.id = opts.id;
         this.engine = opts.engine;
@@ -60,6 +63,36 @@ export class ChatSession {
             this.pump();
         });
     }
+    /**
+     * Run session maintenance (for example context-package summarization) under
+     * the same per-session mutex as turns. Existing activity fails fast; turns
+     * arriving after the lock is acquired remain queued until maintenance has
+     * persisted its final usage/state update.
+     */
+    async runExclusive(operation) {
+        if (this.active || this.exclusiveOperation || this.queue.length > 0) {
+            throw new Error("source session is still producing or has queued turns");
+        }
+        this.lastActivityAt = Date.now();
+        this.exclusiveOperation = true;
+        this.settlePromise = new Promise((resolve) => {
+            this.resolveSettled = resolve;
+        });
+        this.controller = new AbortController();
+        try {
+            return await operation(this.controller.signal);
+        }
+        finally {
+            this.lastActivityAt = Date.now();
+            this.resolveSettled?.();
+            this.resolveSettled = null;
+            this.controller = null;
+            this.exclusiveOperation = false;
+            this.applyPendingModelSwitchAtRunBoundary();
+            if (this.queue.length > 0)
+                void this.pump();
+        }
+    }
     /**
      * True when the user hit Stop and hasn't started a new turn since. The server
      * consults this before auto-waking an idle session on a background-job
@@ -92,7 +125,11 @@ export class ChatSession {
         }
     }
     isBusy() {
-        return this.active !== null;
+        return this.active !== null || this.exclusiveOperation;
+    }
+    /** Resolves after the active engine.run() has completed its pump finally. */
+    get settled() {
+        return this.settlePromise;
     }
     /**
      * Extend the in-flight goal run's turn/budget ceilings (TODO 3.1). Delegates
@@ -104,7 +141,7 @@ export class ChatSession {
         return this.engine.extendGoalRun(opts);
     }
     /**
-     * Read this session's persisted active goal (state.activeGoal), or undefined
+     * Read this session's persisted active goal (state.goalLifecycle), or undefined
      * when none. Cheap — reads only state.json. The host calls this on session
      * load to re-surface the goal block + Cancel button after a reload.
      */
@@ -115,8 +152,56 @@ export class ChatSession {
      * Clear this session's persisted active goal (CC /goal clear). Works idle or
      * mid-run. Returns true if a goal was actually cleared.
      */
-    clearGoal() {
-        return this.engine.clearGoal(this.id);
+    clearGoal(expected) {
+        return this.engine.clearGoal(this.id, expected);
+    }
+    /** Edit or pause/resume this session's persistent goal. */
+    updateGoal(patch) {
+        return this.engine.updateGoal(this.id, patch);
+    }
+    /** Whether a paused Goal can reuse this run's already Goal-capable prompt/tools. */
+    canResumeGoalInPlace() {
+        return this.engine.canResumeGoalInPlace(this.id);
+    }
+    /**
+     * Queue the synthetic turn which actually drives an idle/dormant Goal after
+     * Resume. The version guard is checked at queue head, so a later edit/delete
+     * cannot leave a stale "resume" turn behind another user turn.
+     */
+    enqueueGoalResumeTurn(goal, opts = {}) {
+        this.lastActivityAt = Date.now();
+        this.cancelledSinceLastTurn = false;
+        return new Promise((resolve, reject) => {
+            // Resume is level-triggered, not an instruction that should accumulate.
+            // While another turn owns the session, pause -> resume can otherwise
+            // leave multiple continuation turns for the same Goal instance queued.
+            // Supersede only pending entries; an already-active resume is governed by
+            // the live TurnLoop control path.
+            if (goal.goalId) {
+                for (let index = this.queue.length - 1; index >= 0; index--) {
+                    const pending = this.queue[index];
+                    if (pending?.goalResumeId !== goal.goalId)
+                        continue;
+                    this.queue.splice(index, 1);
+                    pending.onSkipped?.();
+                }
+            }
+            this.queue.push({
+                task: "<system-reminder>\n用户已恢复持久目标。请读取当前持久目标并继续执行。\n</system-reminder>",
+                opts: { ...opts, injected: true },
+                ...(goal.goalId ? { goalResumeId: goal.goalId } : {}),
+                guard: () => {
+                    const current = this.engine.getGoal(this.id);
+                    // Edits retain the same user-owned goalId and should update the
+                    // queued resume, not cancel it. Pause/delete/replacement must skip.
+                    return current?.paused !== true && isSameGoalInstance(current, goal);
+                },
+                onSkipped: () => resolve(false),
+                resolve: () => resolve(true),
+                reject,
+            });
+            void this.pump();
+        });
     }
     /**
      * Switch this session's active model (per-session, not worker-global).
@@ -144,20 +229,54 @@ export class ChatSession {
      * path and the deferred run-boundary path.
      */
     applyModelSwitch(key) {
-        const entry = this.engine.switchModel(key);
+        // persist: false — a per-session switch must not become the global boot
+        // default (settings.defaults.text); only explicit default-model changes
+        // (legacy single-engine path, TUI /model) persist.
+        const entry = this.engine.switchModel(key, { persist: false });
         this.engine.resetSessionUsage(this.id);
         return entry;
     }
+    /** Apply and clear a deferred switch before another run may start. */
+    applyPendingModelSwitchAtRunBoundary() {
+        const key = this.pendingModel;
+        this.pendingModel = null;
+        if (key === null)
+            return;
+        try {
+            this.applyModelSwitch(key);
+        }
+        catch {
+            // requestModelSwitch already returned when the switch was queued. A
+            // run-boundary persistence failure must not become an unhandled pump
+            // rejection or prevent the session from settling/continuing.
+        }
+    }
     queueDepth() {
         return this.queue.length;
     }
     async pump() {
-        if (this.active)
+        if (this.active || this.exclusiveOperation)
             return;
-        const next = this.queue.shift();
+        let next;
+        while ((next = this.queue.shift())) {
+            let allowed = true;
+            try {
+                allowed = next.guard?.() ?? true;
+            }
+            catch {
+                allowed = false;
+            }
+            if (allowed)
+                break;
+            next.onSkipped?.();
+            next = undefined;
+        }
         if (!next)
             return;
         this.active = next;
+        this.settlePromise = new Promise((resolve) => {
+            this.resolveSettled = resolve;
+        });
         this.cancelledActive = false;
         this.controller = new AbortController();
         try {
@@ -165,12 +284,23 @@ export class ChatSession {
             const result = await this.engine.run(next.task, {
                 cwd: next.opts.cwd,
                 sessionId: this.id,
+                displayText: next.opts.displayText,
                 signal: this.controller.signal,
                 onStream,
                 goal: next.opts.goal,
                 injected: next.opts.injected,
                 clientMessageId: next.opts.clientMessageId,
                 attachments: next.opts.attachments,
+                permissionMode: next.opts.permissionMode,
+                planMode: next.opts.planMode,
+                behaviorMode: next.opts.behaviorMode,
+                profileParams: next.opts.profileParams,
+                workspaceProfile: next.opts.workspaceProfile,
+                sessionMessageTargets: next.opts.sessionMessageTargets,
+                petRuntimeContext: next.opts.petRuntimeContext,
+                petWorkspaces: next.opts.petWorkspaces,
+                kind: next.opts.kind,
+                approvalRouter: next.opts.approvalRouter,
             });
             this.lastActivityAt = Date.now();
             next.resolve(result);
@@ -195,19 +325,24 @@ export class ChatSession {
             }
         }
         finally {
+            // close() must never be held hostage by run-boundary cleanup. Resolve
+            // before model switching or any other operation that may throw.
+            this.resolveSettled?.();
+            this.resolveSettled = null;
             this.active = null;
             this.controller = null;
             this.cancelledActive = false;
             // Run boundary: apply any model switch that was deferred because it was
             // requested mid-run. Done here (not in pump) so it still applies when
             // no further turn is queued.
-            if (this.pendingModel !== null) {
-                this.applyModelSwitch(this.pendingModel);
-                this.pendingModel = null;
+            this.applyPendingModelSwitchAtRunBoundary();
+            // Drain the next turn even if deferred model switching failed.
+            if (this.queue.length > 0) {
+                // Let the just-settled turn's resolve/reject handlers publish their
+                // terminal lifecycle before a queued turn can synchronously emit its
+                // session_started event. This preserves external QueryGuard ordering.
+                queueMicrotask(() => void this.pump());
             }
-            // Drain the next turn if one is waiting.
-            if (this.queue.length > 0)
-                void this.pump();
         }
     }
 }

package/dist/protocol/client.d.ts

@@ -11,9 +11,11 @@
  *   const result = await client.run("fix the bug");
  */
 import type { Transport } from "./transport.js";
-import { type RunParams, type RunResult, type AgentStreamEventNotification, type ConfigureParams, type QueryParams, type QueryResult, type ApprovalRequestNotification, type ApprovalResolvedNotification } from "./types.js";
-import type { ApprovalRequest, ApprovalResult, PermissionMode, BackgroundAgentCompletedEvent } from "../types.js";
-export type ApprovalRequestMeta = Pick<ApprovalRequestNotification, "sessionId">;
+import { type RunParams, type RunResult, type ForkSessionParams, type ForkSessionResult, type AgentStreamEventNotification, type ConfigureParams, type QueryParams, type QueryResult, type PluginCommandsListResult, type PluginCommandExpandResult, type ApprovalRequestNotification, type ApprovalResolvedNotification } from "./types.js";
+import type { ApprovalRequest, ApprovalResult, PermissionMode, BackgroundAgentCompletedEvent, SessionKind } from "../types.js";
+import type { RunBehaviorMode } from "../engine/run-types.js";
+import type { GoalConfig } from "../goal/lifecycle.js";
+export type ApprovalRequestMeta = Pick<ApprovalRequestNotification, "connectionId" | "sessionId" | "generation">;
 export type ApprovalResolvedEvent = ApprovalResolvedNotification;
 export interface AgentClientEvents {
     /** Multi-session envelope: carries sessionId + event. */
@@ -28,12 +30,16 @@ export interface AgentRunOptions {
     permissionMode?: PermissionMode;
     model?: string;
     planMode?: boolean;
+    behaviorMode?: RunBehaviorMode;
+    kind?: SessionKind;
 }
 export type BackgroundAgentCompletedHandler = (sessionId: string, event: BackgroundAgentCompletedEvent) => void;
 export declare class AgentClient {
     private transport;
     private emitter;
     private pendingRequests;
+    /** Routing tuple captured from approval notifications and echoed on approve. */
+    private approvalRoutes;
     /**
      * Map from a user-supplied `BackgroundAgentCompletedHandler` to the
      * internal envelope-filtering wrapper actually registered on the
@@ -52,7 +58,7 @@ export declare class AgentClient {
      * for multi-session servers) or the legacy string form `(task, sessionId?)`
      * for backward compatibility with createInProcessClient callers.
      */
-    run(taskOrParams: string | RunParams, sessionIdOrOptions?: string | AgentRunOptions): Promise<RunResult>;
+    run(taskOrParams: string | RunParams, sessionIdOrOptions?: string | AgentRunOptions, onTransportResponse?: () => void): Promise<RunResult>;
     /**
      * Respond to an approval request from the server.
      *
@@ -68,11 +74,26 @@ export declare class AgentClient {
      * Legacy form:        cancel(reason?)
      */
     cancel(sessionId?: string, reason?: string): Promise<void>;
+    forkSession(params: ForkSessionParams): Promise<ForkSessionResult>;
     /**
      * Clear a session's persisted active goal (CC `/goal clear`). Returns whether
      * a goal was actually cleared (false = there was none).
      */
     goalClear(sessionId?: string): Promise<boolean>;
+    /** Delete a persisted goal. Kept separate from goalClear for UI semantics. */
+    goalDelete(sessionId: string, expected: {
+        goalId: string;
+        revision: number;
+    }): Promise<boolean>;
+    /** Edit or pause/resume a goal while preserving its goalId. */
+    goalUpdate(sessionId: string, patch: {
+        objective?: string;
+        paused?: boolean;
+        expectedGoalId: string;
+        expectedRevision: number;
+    }): Promise<GoalConfig | null>;
+    /** Read the full persisted goal control state. */
+    goalGetState(sessionId: string): Promise<GoalConfig | null>;
     /**
      * Read a session's persisted active goal objective, or null when there's
      * none. The host calls this on session load to re-surface the goal block +
@@ -106,6 +127,13 @@ export declare class AgentClient {
      * Query server state.
      */
     query(type: QueryParams["type"], arg?: string | Record<string, unknown>, ...extra: unknown[]): Promise<QueryResult>;
+    /** Discover enabled installed plugin commands for one workspace. */
+    listPluginCommands(cwd: string): Promise<PluginCommandsListResult>;
+    /**
+     * Expand one plugin command inside the trusted server. The command source
+     * body and install path never cross the protocol boundary.
+     */
+    expandPluginCommand(cwd: string, name: string, rawArguments?: string): Promise<PluginCommandExpandResult>;
     /**
      * Inject context into the session transcript without triggering a LLM turn.
      * Used to make arena results, tool outputs, etc. visible to subsequent LLM calls.
@@ -136,5 +164,10 @@ export declare class AgentClient {
     private request;
     private handleResponse;
     private handleNotification;
+    /** Subscribe to an extension-owned server notification method. */
+    onExtensionNotification(method: string, handler: (params: Record<string, unknown>) => void): void;
+    offExtensionNotification(method: string, handler: (params: Record<string, unknown>) => void): void;
+    /** Issue a request to an extension-registered protocol method. */
+    requestExtension(method: string, params?: Record<string, unknown>): Promise<unknown>;
     close(): void;
 }

package/dist/protocol/client.js

@@ -10,13 +10,15 @@
  *   client.onApprovalRequest((reqId, request) => { ... });
  *   const result = await client.run("fix the bug");
  */
-import { Methods, createRequest, isResponse, isNotification, } from "./types.js";
+import { Methods, createRequest, isResponse, isNotification, ErrorCodes, } from "./types.js";
 import { EventEmitter } from "node:events";
 import { logger } from "../logging/logger.js";
 export class AgentClient {
     transport;
     emitter = new EventEmitter();
     pendingRequests = new Map();
+    /** Routing tuple captured from approval notifications and echoed on approve. */
+    approvalRoutes = new Map();
     /**
      * Map from a user-supplied `BackgroundAgentCompletedHandler` to the
      * internal envelope-filtering wrapper actually registered on the
@@ -44,7 +46,7 @@ export class AgentClient {
      * for multi-session servers) or the legacy string form `(task, sessionId?)`
      * for backward compatibility with createInProcessClient callers.
      */
-    async run(taskOrParams, sessionIdOrOptions) {
+    async run(taskOrParams, sessionIdOrOptions, onTransportResponse) {
         let params;
         if (typeof taskOrParams === "string") {
             // Form: run(task, sessionId | options?)
@@ -70,7 +72,7 @@ export class AgentClient {
         // first call of a brand-new session, when sessionId is undefined.
         if (params.sessionId)
             logger.setSid(params.sessionId);
-        const result = (await this.request(Methods.Run, params));
+        const result = (await this.request(Methods.Run, params, onTransportResponse));
         if (result.sessionId)
             logger.setSid(result.sessionId);
         return result;
@@ -78,16 +80,24 @@ export class AgentClient {
     approve(...args) {
         if (args.length === 3) {
             const [sessionId, requestId, decision] = args;
+            const route = this.approvalRoutes.get(requestId);
             return this.request(Methods.Approve, {
+                ...route,
                 sessionId,
                 requestId,
                 decision,
+            }).finally(() => {
+                this.approvalRoutes.delete(requestId);
             });
         }
         const [requestId, decision] = args;
+        const route = this.approvalRoutes.get(requestId);
         return this.request(Methods.Approve, {
+            ...route,
             requestId,
             decision,
+        }).finally(() => {
+            this.approvalRoutes.delete(requestId);
         });
     }
     /**
@@ -99,6 +109,9 @@ export class AgentClient {
     async cancel(sessionId, reason) {
         await this.request(Methods.Cancel, { sessionId, reason });
     }
+    async forkSession(params) {
+        return this.request(Methods.ForkSession, params);
+    }
     /**
      * Clear a session's persisted active goal (CC `/goal clear`). Returns whether
      * a goal was actually cleared (false = there was none).
@@ -107,6 +120,51 @@ export class AgentClient {
         const res = (await this.request(Methods.GoalClear, { sessionId }));
         return res?.cleared === true;
     }
+    /** Delete a persisted goal. Kept separate from goalClear for UI semantics. */
+    async goalDelete(sessionId, expected) {
+        try {
+            const res = (await this.request(Methods.GoalDelete, {
+                sessionId,
+                expectedGoalId: expected.goalId,
+                expectedRevision: expected.revision,
+            }));
+            return res?.deleted === true;
+        }
+        catch (err) {
+            // Compatibility only: old servers do not know GoalDelete and expose the
+            // unfenced GoalClear method. Never downgrade on a stale/validation error.
+            if (err.code !== ErrorCodes.MethodNotFound)
+                throw err;
+            return this.goalClear(sessionId);
+        }
+    }
+    /** Edit or pause/resume a goal while preserving its goalId. */
+    async goalUpdate(sessionId, patch) {
+        const res = (await this.request(Methods.GoalUpdate, {
+            sessionId,
+            ...patch,
+        }));
+        if (res?.updated !== true || !res.goal)
+            return null;
+        return {
+            objective: res.goal,
+            ...(res.goalId ? { goalId: res.goalId } : {}),
+            ...(res.revision ? { revision: res.revision } : {}),
+            ...(res.paused === true ? { paused: true } : {}),
+        };
+    }
+    /** Read the full persisted goal control state. */
+    async goalGetState(sessionId) {
+        const res = (await this.request(Methods.GoalGet, { sessionId }));
+        if (!res?.goal)
+            return null;
+        return {
+            objective: res.goal,
+            ...(res.goalId ? { goalId: res.goalId } : {}),
+            ...(res.revision ? { revision: res.revision } : {}),
+            ...(res.paused === true ? { paused: true } : {}),
+        };
+    }
     /**
      * Read a session's persisted active goal objective, or null when there's
      * none. The host calls this on session load to re-surface the goal block +
@@ -186,6 +244,21 @@ export class AgentClient {
         }
         return this.request(Methods.Query, params);
     }
+    /** Discover enabled installed plugin commands for one workspace. */
+    async listPluginCommands(cwd) {
+        return this.request(Methods.PluginCommandsList, { cwd });
+    }
+    /**
+     * Expand one plugin command inside the trusted server. The command source
+     * body and install path never cross the protocol boundary.
+     */
+    async expandPluginCommand(cwd, name, rawArguments = "") {
+        return this.request(Methods.PluginCommandExpand, {
+            cwd,
+            name,
+            rawArguments,
+        });
+    }
     /**
      * Inject context into the session transcript without triggering a LLM turn.
      * Used to make arena results, tool outputs, etc. visible to subsequent LLM calls.
@@ -247,10 +320,10 @@ export class AgentClient {
         this.emitter.off("stream", wrapper);
     }
     // ─── Internals ──────────────────────────────────────────────────
-    request(method, params) {
+    request(method, params, onResponse) {
         return new Promise((resolve, reject) => {
             const req = createRequest(method, params);
-            this.pendingRequests.set(req.id, { resolve, reject });
+            this.pendingRequests.set(req.id, { onResponse, resolve, reject });
             this.transport.send(req);
         });
     }
@@ -259,6 +332,19 @@ export class AgentClient {
         if (!pending)
             return;
         this.pendingRequests.delete(res.id);
+        // Emit before resolving/rejecting: Promise continuations run in a later
+        // microtask, while the transport may synchronously parse the next queued
+        // session_started notification in the same chunk.
+        if (pending.onResponse) {
+            try {
+                pending.onResponse();
+            }
+            catch (error) {
+                logger.warn("client.run_response_handler_failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
         if (res.error) {
             // Attach both message and code so callers can do toMatchObject({ code }).
             const err = new Error(`[${res.error.code}] ${res.error.message}`);
@@ -286,7 +372,14 @@ export class AgentClient {
                 const request = params.request;
                 if (requestId && request) {
                     const sessionId = typeof params.sessionId === "string" ? params.sessionId : undefined;
-                    const meta = sessionId === undefined ? {} : { sessionId };
+                    const connectionId = typeof params.connectionId === "string" ? params.connectionId : undefined;
+                    const generation = typeof params.generation === "number" ? params.generation : undefined;
+                    const meta = {
+                        ...(connectionId === undefined ? {} : { connectionId }),
+                        ...(sessionId === undefined ? {} : { sessionId }),
+                        ...(generation === undefined ? {} : { generation }),
+                    };
+                    this.approvalRoutes.set(requestId, meta);
                     this.emitter.emit("approvalRequest", requestId, request, meta);
                 }
                 break;
@@ -294,6 +387,7 @@ export class AgentClient {
             case Methods.ApprovalResolved: {
                 const requestId = params.requestId;
                 if (requestId) {
+                    this.approvalRoutes.delete(requestId);
                     const sessionId = typeof params.sessionId === "string" ? params.sessionId : undefined;
                     const event = sessionId === undefined ? { requestId } : { sessionId, requestId };
                     this.emitter.emit("approvalResolved", event);
@@ -306,8 +400,26 @@ export class AgentClient {
                 this.emitter.emit("status", status, message);
                 break;
             }
+            default: {
+                // Extension-owned notification methods (e.g. projection deltas pushed
+                // by a ProtocolObserver via host.notify) surface through a generic
+                // per-method channel; core knows nothing about their payloads.
+                this.emitter.emit(`notification:${notif.method}`, params);
+                break;
+            }
         }
     }
+    /** Subscribe to an extension-owned server notification method. */
+    onExtensionNotification(method, handler) {
+        this.emitter.on(`notification:${method}`, handler);
+    }
+    offExtensionNotification(method, handler) {
+        this.emitter.off(`notification:${method}`, handler);
+    }
+    /** Issue a request to an extension-registered protocol method. */
+    async requestExtension(method, params) {
+        return this.request(method, params);
+    }
     close() {
         // Reject all pending requests
         for (const [, pending] of this.pendingRequests) {

package/dist/protocol/index.d.ts

@@ -1,4 +1,4 @@
 export { AgentServer, type AgentServerOptions } from "./server.js";
 export { AgentClient } from "./client.js";
-export { createInProcessTransport, StdioTransport, type Transport, } from "./transport.js";
-export { Methods, ErrorCodes, type RpcMessage, type RunResult } from "./types.js";
+export { createInProcessTransport, StdioTransport, type Transport } from "./transport.js";
+export { Methods, ErrorCodes, type RpcMessage, type RunResult, type PluginCommandsListParams, type PluginCommandsListResult, type ProtocolPluginCommandDescriptor, type PluginCommandExpandParams, type PluginCommandExpandResult, } from "./types.js";

package/dist/protocol/index.js

@@ -1,4 +1,4 @@
 export { AgentServer } from "./server.js";
 export { AgentClient } from "./client.js";
-export { createInProcessTransport, StdioTransport, } from "./transport.js";
-export { Methods, ErrorCodes } from "./types.js";
+export { createInProcessTransport, StdioTransport } from "./transport.js";
+export { Methods, ErrorCodes, } from "./types.js";