@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/protocol/types.d.ts

@@ -7,7 +7,24 @@
  *   Server → Client: notifications (stream events, approval requests)
  *   Server → Client: responses (results of requests)
  */
-import type { StreamEvent, TokenUsage, TerminalReason, ApprovalRequest, ApprovalResult, PermissionMode } from "../types.js";
+import type { InputAttachmentMeta, LegacyPetWorkspaceOption, LegacyPetWorkDelegation, StreamEvent, TokenUsage, TerminalReason, ApprovalRequest, ApprovalResult, PermissionMode, SessionForkLineage, SessionKind, SessionWorkspace } from "../types.js";
+import type { RunBehaviorMode } from "../engine/run-types.js";
+import type { SessionMessageTarget } from "../session/session-message.js";
+export type PendingApprovalKind = "tool_approval" | "ask_user" | "internal";
+/** Resolver-free metadata retained beside a pending approval callback. */
+export interface PendingApprovalMetadata {
+    sessionId: string;
+    requestId: string;
+    routeGeneration?: number;
+    workerGeneration: number;
+    kind: PendingApprovalKind;
+    title: string;
+    toolName?: string;
+    riskLevel?: "low" | "medium" | "high";
+    createdAt: number;
+    expiresAt?: number;
+    surfaceable: boolean;
+}
 export interface RpcRequest {
     jsonrpc: "2.0";
     id: string | number;
@@ -47,43 +64,27 @@ 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;
-    };
-}
+export type { InputAttachmentKind, InputAttachmentOrigin, InputAttachmentMeta } from "../types.js";
 /** Start an agent run with a user task. */
 export interface RunParams {
     sessionId: string;
     task: string;
+    /**
+     * Optional user-facing representation of `task`. The model still receives
+     * the full task, while session feeds and transcript replay show this text.
+     * Host-owned surfaces use it to hide transport/context envelopes without
+     * hiding the user's actual input.
+     */
+    displayText?: 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;
+    /**
+     * Host-generated system reminder. Persisted with an injected marker so disk
+     * transcript readers hide it as a user bubble while retaining the assistant reply.
+     */
+    injected?: boolean;
     /**
      * Working directory for this run. When omitted, the Engine uses its
      * configured cwd.
@@ -113,6 +114,39 @@ export interface RunParams {
      * this run; when omitted, the engine keeps its configured default.
      */
     planMode?: boolean;
+    /** Named behavior profile for a product-specific per-run interaction mode. */
+    behaviorMode?: RunBehaviorMode;
+    /**
+     * Generic per-run parameters consumed by the active behavior profile
+     * (delivered as non-durable run context; never appended to the task or
+     * transcript).
+     */
+    profileParams?: Record<string, unknown>;
+    /** Digital human to bind to this Work Session. */
+    workspaceProfile?: string;
+    /**
+     * Standing brief for this Session, injected as a system section on every run
+     * (see SessionState.sessionBrief). Set when a team is summoned; a planned
+     * Session has no engine state yet, so the host resends it each turn until the
+     * Session persists it.
+     */
+    sessionBrief?: string;
+    /** Closed same-project Session catalog available to SendMessageToSession. */
+    sessionMessageTargets?: SessionMessageTarget[];
+    /**
+     * Host-built bounded Pet world JSON for this invocation. It is delivered as
+     * non-durable system context and must never be appended to the user task or
+     * transcript. Valid only for an explicitly durable Pet run.
+     * @deprecated Compat alias for `profileParams.runtimeContext`.
+     */
+    petRuntimeContext?: string;
+    /**
+     * Closed Workspace choices exposed to Mimi's DelegateWork tool.
+     * @deprecated Compat alias for `profileParams.workspaces`.
+     */
+    petWorkspaces?: LegacyPetWorkspaceOption[];
+    /** Durable classification used only when creating a new session. */
+    kind?: SessionKind;
     /**
      * Require the target session to already exist on disk. When true and the
      * session is absent, the run is rejected with `SessionNotFound` instead of
@@ -130,7 +164,7 @@ export interface RunParams {
      * Accepts a bare objective string or a full GoalConfig (objective +
      * optional token/time budgets). Normalized at the engine run boundary.
      */
-    goal?: string | import("../engine/goal.js").GoalConfig;
+    goal?: string | import("../goal/lifecycle.js").GoalConfig;
 }
 export interface RunResult {
     text: string;
@@ -138,10 +172,59 @@ export interface RunResult {
     sessionId: string;
     turnCount: number;
     usage: TokenUsage;
+    /** Structured results reported by the active behavior profile. */
+    extensions?: Record<string, unknown>;
+    petWorkDelegation?: LegacyPetWorkDelegation;
 }
+export interface FullForkSessionParams {
+    sourceSessionId: string;
+    targetSessionId?: string;
+    mode: "full";
+    /** Ephemeral side fork: snapshot only the last completed conversation turn. */
+    forkKind?: "side";
+    /** Inclusive source event cursor; omitted freezes the current tail. */
+    throughEventId?: string;
+    /** Desktop host ownership generation; ignored by protocol-only hosts. */
+    quickChatClaimId?: string;
+}
+export interface SummaryForkSessionParams {
+    sourceSessionId: string;
+    targetSessionId?: string;
+    mode: "summary";
+    /** Inclusive stable source event range. */
+    fromEventId: string;
+    toEventId: string;
+}
+export type ForkSessionParams = FullForkSessionParams | SummaryForkSessionParams;
+export interface FullForkSessionResult {
+    sessionId: string;
+    mode: "full";
+    forkedFrom: SessionForkLineage;
+    workspace: SessionWorkspace;
+    copiedEventCount: number;
+    titleSuggestion?: string;
+}
+export interface SummaryForkSessionResult {
+    sessionId: string;
+    mode: "summary";
+    summary: string;
+    sourceRange: {
+        fromEventId: string;
+        toEventId: string;
+    };
+    estimatedTokens: number;
+    forkedFrom: SessionForkLineage;
+    workspace: SessionWorkspace;
+    titleSuggestion?: string;
+}
+export type ForkSessionResult = FullForkSessionResult | SummaryForkSessionResult;
 /** Respond to an approval request from the server. */
 export interface ApproveParams {
     sessionId: string;
+    /** Connection owner echoed from ApprovalRequestNotification when present. */
+    connectionId?: string;
+    /** Session-owner generation echoed from ApprovalRequestNotification when present. */
+    generation?: number;
     requestId: string;
     decision: ApprovalResult;
 }
@@ -158,6 +241,11 @@ export interface CloseSessionParams {
 export interface ReleaseWorkspaceParams {
     sessionId: string;
 }
+/** Persist and rebase a session workspace through its owning Engine. */
+export interface SetWorkspaceParams {
+    sessionId: string;
+    workspace: SessionWorkspace;
+}
 /** Inject context into a session transcript. */
 export interface InjectParams {
     sessionId: string;
@@ -180,6 +268,36 @@ export interface UnsteerParams {
     sessionId: string;
     id: string;
 }
+/** Discover renderer-safe metadata for enabled installed plugin commands. */
+export interface PluginCommandsListParams {
+    cwd: string;
+}
+export interface ProtocolPluginCommandDescriptor {
+    name: string;
+    pluginName: string;
+    description: string;
+    argumentHint?: string;
+}
+export interface PluginCommandsListResult {
+    commands: ProtocolPluginCommandDescriptor[];
+}
+/** Expand one enabled command inside the trusted host; command bodies stay server-side. */
+export interface PluginCommandExpandParams {
+    cwd: string;
+    name: string;
+    rawArguments?: string;
+}
+export interface PluginCommandExpandResult {
+    prompt: string;
+}
+/** Edit or pause/resume a persisted goal without replacing its identity. */
+export interface GoalUpdateParams {
+    sessionId: string;
+    objective?: string;
+    paused?: boolean;
+    expectedGoalId: string;
+    expectedRevision: number;
+}
 /** Update runtime configuration. */
 export interface ConfigureParams {
     /** When present, configure that specific chat session. Otherwise worker-global. */
@@ -209,7 +327,8 @@ export interface ConfigureParams {
 }
 /** Query server state. */
 export interface QueryParams {
-    type: "sessions" | "tools" | "config" | "session_detail" | "compact" | "config_set" | "config_get" | "permission_set" | "models" | "providers" | "arena_status" | "provider_add" | "provider_refresh" | "provider_delete" | "model_add" | "model_delete";
+    /** Built-in query name or a trusted CapabilityModule query contribution. */
+    type: string;
     sessionId?: string;
     /** Used by config_set / permission_set: dotted key path or mode field */
     key?: string;
@@ -219,6 +338,10 @@ export interface QueryParams {
     provider?: unknown;
     /** Used by model_add: the new model entry */
     model?: unknown;
+    /** Used by archive_range: half-open message-index window start (inclusive). */
+    start?: unknown;
+    /** Used by archive_range: half-open message-index window end (exclusive). */
+    end?: unknown;
 }
 export interface QueryResult {
     type: string;
@@ -294,6 +417,10 @@ export interface AgentStreamEventNotification {
 export interface ApprovalRequestNotification {
     /** Originating engine session when known. */
     sessionId?: string;
+    /** Connection owner required by strict multi-connection hosts. */
+    connectionId?: string;
+    /** Monotonic owner generation required by strict multi-connection hosts. */
+    generation?: number;
     requestId: string;
     request: ApprovalRequest;
 }
@@ -308,8 +435,14 @@ export interface StatusNotification {
     status: "ready" | "running" | "error" | "shutdown";
     message?: string;
 }
+/** Server accepted and queued an agent/run request after synchronous validation. */
+export interface RunAcceptedNotification {
+    requestId: string | number;
+    sessionId: string;
+}
 export declare const Methods: {
     readonly Run: "agent/run";
+    readonly ForkSession: "agent/forkSession";
     readonly Approve: "agent/approve";
     readonly Cancel: "agent/cancel";
     readonly Configure: "agent/configure";
@@ -324,8 +457,14 @@ export declare const Methods: {
     readonly CloseSession: "agent/closeSession";
     /** Reset a session's workspace binding to main without closing it. */
     readonly ReleaseWorkspace: "agent/releaseWorkspace";
+    /** Persist a workspace pointer through the live session owner. */
+    readonly SetWorkspace: "agent/setWorkspace";
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     readonly GoalExtend: "agent/goalExtend";
+    /** Edit or pause/resume a session's persisted goal. */
+    readonly GoalUpdate: "agent/goalUpdate";
+    /** Delete a persisted goal (explicit alias of goalClear). */
+    readonly GoalDelete: "agent/goalDelete";
     /** Clear a session's persisted active goal (CC /goal clear). */
     readonly GoalClear: "agent/goalClear";
     /** Read a session's persisted active goal, to re-surface it on session load. */
@@ -336,12 +475,23 @@ export declare const Methods: {
      *  for the desktop background panel. Output/kill of a shell still goes through
      *  BackgroundShells by shellId; this is list-only across all three kinds. */
     readonly BackgroundWork: "agent/backgroundWork";
+    /** Read-only bounded Pet projection plus the ordered-delta cursor. */
+    readonly GetPetProjectionSnapshot: "agent/getPetProjectionSnapshot";
+    /** Discover enabled plugin slash commands without exposing their source bodies or file paths. */
+    readonly PluginCommandsList: "pluginCommands/list";
+    /** Expand one enabled plugin command into a reviewable prompt draft. */
+    readonly PluginCommandExpand: "pluginCommands/expand";
+    readonly RunAccepted: "agent/runAccepted";
     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";
+    /** A worker-side settings resource changed on disk and mounted clients
+     * should invalidate their cached settings/catalog reads. */
+    readonly SettingsChanged: "agent/settingsChanged";
+    readonly PetProjectionDelta: "agent/petProjectionDelta";
     readonly Status: "agent/status";
 };
 export declare function createRequest(method: string, params?: Record<string, unknown>): RpcRequest;

package/dist/protocol/types.js

@@ -29,6 +29,7 @@ export const ErrorCodes = {
 export const Methods = {
     // Client → Server
     Run: "agent/run",
+    ForkSession: "agent/forkSession",
     Approve: "agent/approve",
     Cancel: "agent/cancel",
     Configure: "agent/configure",
@@ -43,8 +44,14 @@ export const Methods = {
     CloseSession: "agent/closeSession",
     /** Reset a session's workspace binding to main without closing it. */
     ReleaseWorkspace: "agent/releaseWorkspace",
+    /** Persist a workspace pointer through the live session owner. */
+    SetWorkspace: "agent/setWorkspace",
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     GoalExtend: "agent/goalExtend",
+    /** Edit or pause/resume a session's persisted goal. */
+    GoalUpdate: "agent/goalUpdate",
+    /** Delete a persisted goal (explicit alias of goalClear). */
+    GoalDelete: "agent/goalDelete",
     /** Clear a session's persisted active goal (CC /goal clear). */
     GoalClear: "agent/goalClear",
     /** Read a session's persisted active goal, to re-surface it on session load. */
@@ -55,13 +62,24 @@ export const Methods = {
      *  for the desktop background panel. Output/kill of a shell still goes through
      *  BackgroundShells by shellId; this is list-only across all three kinds. */
     BackgroundWork: "agent/backgroundWork",
+    /** Read-only bounded Pet projection plus the ordered-delta cursor. */
+    GetPetProjectionSnapshot: "agent/getPetProjectionSnapshot",
+    /** Discover enabled plugin slash commands without exposing their source bodies or file paths. */
+    PluginCommandsList: "pluginCommands/list",
+    /** Expand one enabled plugin command into a reviewable prompt draft. */
+    PluginCommandExpand: "pluginCommands/expand",
     // Server → Client (notifications, no id)
+    RunAccepted: "agent/runAccepted",
     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",
+    /** A worker-side settings resource changed on disk and mounted clients
+     * should invalidate their cached settings/catalog reads. */
+    SettingsChanged: "agent/settingsChanged",
+    PetProjectionDelta: "agent/petProjectionDelta",
     Status: "agent/status",
 };
 // ─── Helpers ────────────────────────────────────────────────────────

package/dist/run/ArtifactTracker.d.ts

@@ -3,7 +3,8 @@
  *
  * Listens to StreamEvents and identifies:
  *   - Files written or edited (Write / Edit tool results)
- *   - Files created by Bash commands (mkdir, touch, cp, git commit, etc.)
+ *   - Files created by generic Bash redirection/copy commands
+ *   - Domain-specific outputs recognized by capability detectors
  *   - Structured outputs (e.g., generated configs, test results)
  *
  * Design constraint (§14):
@@ -13,14 +14,17 @@
  */
 import type { StreamEvent } from "../types.js";
 import type { RunStore } from "./RunStore.js";
+import type { CapabilityArtifactDetector } from "../capabilities/index.js";
 export interface ArtifactTrackerConfig {
     runId: string;
     store: RunStore;
+    detectors?: readonly CapabilityArtifactDetector[];
 }
 export declare class ArtifactTracker {
     private readonly config;
     private readonly pendingCalls;
     private readonly recordedPaths;
+    private readonly recordedLocators;
     constructor(config: ArtifactTrackerConfig);
     /**
      * Feed a StreamEvent to the tracker.
@@ -30,6 +34,7 @@ export declare class ArtifactTracker {
     getRecordedPaths(): string[];
     private processToolResult;
     private recordFileArtifact;
+    private recordArtifact;
     /**
      * Extract artifact refs from Bash commands.
      * Only track commands that clearly produce files.

package/dist/run/ArtifactTracker.js

@@ -3,7 +3,8 @@
  *
  * Listens to StreamEvents and identifies:
  *   - Files written or edited (Write / Edit tool results)
- *   - Files created by Bash commands (mkdir, touch, cp, git commit, etc.)
+ *   - Files created by generic Bash redirection/copy commands
+ *   - Domain-specific outputs recognized by capability detectors
  *   - Structured outputs (e.g., generated configs, test results)
  *
  * Design constraint (§14):
@@ -17,6 +18,7 @@ export class ArtifactTracker {
     config;
     pendingCalls = new Map();
     recordedPaths = new Set();
+    recordedLocators = new Set();
     constructor(config) {
         this.config = config;
     }
@@ -60,11 +62,16 @@ export class ArtifactTracker {
             case "Bash":
                 await this.extractBashArtifacts(call.args.command, resultText);
                 break;
-            case "NotebookEdit":
-                if (call.args.notebook_path) {
-                    await this.recordFileArtifact(call.args.notebook_path, "output", "document");
-                }
-                break;
+        }
+        for (const detector of this.config.detectors ?? []) {
+            const detected = detector({
+                toolName: call.toolName,
+                args: call.args,
+                resultText,
+            });
+            for (const artifact of detected ? (Array.isArray(detected) ? detected : [detected]) : []) {
+                await this.recordArtifact(artifact);
+            }
         }
     }
     async recordFileArtifact(filePath, role, kind) {
@@ -77,6 +84,7 @@ export class ArtifactTracker {
         if (this.recordedPaths.has(filePath))
             return;
         this.recordedPaths.add(filePath);
+        this.recordedLocators.add(filePath);
         const ref = {
             artifactRefId: nanoid(12),
             runId: this.config.runId,
@@ -89,6 +97,21 @@ export class ArtifactTracker {
         };
         await this.config.store.appendArtifactRef(ref);
     }
+    async recordArtifact(artifact) {
+        if (!artifact.locator || this.recordedLocators.has(artifact.locator))
+            return;
+        this.recordedLocators.add(artifact.locator);
+        await this.config.store.appendArtifactRef({
+            artifactRefId: nanoid(12),
+            runId: this.config.runId,
+            kind: artifact.kind,
+            title: artifact.title,
+            locator: artifact.locator,
+            role: artifact.role,
+            version: null,
+            metadata: artifact.metadata ?? {},
+        });
+    }
     /**
      * Extract artifact refs from Bash commands.
      * Only track commands that clearly produce files.
@@ -97,21 +120,6 @@ export class ArtifactTracker {
         if (!command)
             return;
         const trimmed = command.trim();
-        // git commit — the commit itself is an artifact
-        if (/^git\s+commit\b/.test(trimmed)) {
-            const ref = {
-                artifactRefId: nanoid(12),
-                runId: this.config.runId,
-                kind: "resource",
-                title: "git commit",
-                locator: "git:HEAD",
-                role: "output",
-                version: null,
-                metadata: { command: trimmed.slice(0, 200) },
-            };
-            await this.config.store.appendArtifactRef(ref);
-            return;
-        }
         // Redirect output: command > file or command >> file (quoted-path aware)
         const redirectTarget = parseRedirectTarget(trimmed);
         if (redirectTarget) {

package/dist/run/EngineRunner.d.ts

@@ -13,6 +13,7 @@ import type { ClientDefaults, LLMConfig, RegisteredTool } from "../types.js";
 import type { RunSnapshot, RunExecutionContext, RunExecutionResult } from "./types.js";
 import { type RunLifecycleHooks } from "./RunApprovalBackend.js";
 import type { ApprovalBackend } from "../tool-system/permission.js";
+import type { CapabilityModule } from "../capabilities/index.js";
 /** Unattended runs (those with an injected approval backend) run headless so
  *  the in-process AgentServer does not wire an interactive askUser. Exported
  *  for unit testing the decision rule. */
@@ -72,6 +73,7 @@ export interface EngineRunnerConfig {
     permissionMode?: EngineConfig["permissionMode"];
     enabledBuiltinTools?: string[];
     disabledBuiltinTools?: string[];
+    capabilities?: readonly CapabilityModule[];
     customSystemPrompt?: string;
     appendSystemPrompt?: string;
     mcpServers?: EngineConfig["mcpServers"];

package/dist/run/EngineRunner.js

@@ -85,6 +85,7 @@ export class EngineRunner {
             preset: run.preset,
             enabledBuiltinTools: this.config.enabledBuiltinTools,
             disabledBuiltinTools: this.config.disabledBuiltinTools,
+            capabilities: this.config.capabilities,
             customSystemPrompt: this.config.customSystemPrompt,
             // NOTE: callers must not pass appendSystemPrompt in engineConfigOverrides
             // below, or it will clobber this composed (automation note + host) value.

package/dist/run/RunManager.d.ts

@@ -14,6 +14,7 @@ import type { RunStore } from "./RunStore.js";
 import { type EngineRunnerConfig, type RunExecutor } from "./EngineRunner.js";
 import { type Evaluator } from "./Evaluator.js";
 import type { RunSnapshot, RunEvent, SubmitRunInput, ResumeRunInput, ListRunsQuery, RunStreamCallback, DetachFn } from "./types.js";
+import { type CapabilityModule } from "../capabilities/index.js";
 export interface RunManagerConfig {
     store: RunStore;
     /**
@@ -35,6 +36,8 @@ export interface RunManagerConfig {
     defaultTags?: string[];
     /** Metadata merged into every submitted run. Submit input wins on conflicts. */
     defaultMetadata?: Record<string, unknown>;
+    /** Product/domain capabilities used by the built-in runner and artifact tracker. */
+    capabilities?: readonly CapabilityModule[];
 }
 export declare class RunManager {
     private readonly store;
@@ -42,9 +45,19 @@ export declare class RunManager {
     private readonly runner;
     private readonly lock;
     private readonly heartbeat;
+    /**
+     * Page size for crash-recovery scans (see listAllByStatus).
+     *
+     * Deliberately NOT a constructor option: hosts have no reason to tune it, and
+     * exposing it would invite a caller to re-introduce the UI's 50-row default.
+     * Tests override it to exercise the multi-page loop cheaply.
+     */
+    private recoverPageSize;
     private readonly evaluator;
     private readonly defaultTags;
     private readonly defaultMetadata;
+    private readonly defaultPreset;
+    private readonly artifactDetectors;
     private readonly subscribers;
     private readonly abortControllers;
     /** Active execution handles — used to resolve pending approvals/input while Engine is suspended */
@@ -81,6 +94,19 @@ export declare class RunManager {
      * Returns the IDs of recovered runs.
      */
     recover(): Promise<string[]>;
+    /**
+     * Drain EVERY run with the given status, page by page.
+     *
+     * `store.list()` defaults to `limit: 50` because it backs a UI list. Crash
+     * recovery must not inherit a UI page size: with 55 stale running runs, the
+     * bare `list({ status })` call recovered the first 50 and left the remaining 5
+     * pinned in "running" forever (no later pass would revisit them, because
+     * recovery only runs at startup).
+     *
+     * Pages until a short page arrives. `maxPages` is a runaway guard for a store
+     * that ignores `offset` — without it a buggy store would loop forever.
+     */
+    private listAllByStatus;
     /**
      * Graceful shutdown — stop all heartbeats and release all locks.
      */