@cjhyy/code-shell-core 0.5.0-rc.0 → 0.5.0-rc.2

package/dist/engine/engine.d.ts

@@ -1,22 +1,44 @@
 /**
  * Engine — the main facade that wires all components together.
  */
-import type { LLMConfig, StreamCallback, TerminalReason, TokenUsage } from "../types.js";
+import type { ClientDefaults, LLMConfig, SessionOrigin, StreamCallback, TerminalReason, TokenUsage } from "../types.js";
 import { ToolRegistry } from "../tool-system/registry.js";
+import { type BuiltinToolFn } from "../tool-system/builtin/index.js";
 import { type ApprovalBackend } from "../tool-system/permission.js";
 import { HookRegistry } from "../hooks/registry.js";
 import type { HookEventName } from "../hooks/events.js";
 import type { HookHandler } from "../hooks/registry.js";
+import { type GoalConfig } from "./goal.js";
 import { SessionManager } from "../session/session-manager.js";
 import type { CostStateStore } from "./cost-store.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
+import { type SettingsScope } from "../settings/manager.js";
+import type { CapabilityOverride } from "../settings/schema.js";
 import type { ToolContext } from "../tool-system/context.js";
 import { type SandboxConfig } from "../tool-system/sandbox/index.js";
 import { type AgentPresetName } from "../preset/index.js";
 import { ModelPool, type ModelEntry } from "../llm/model-pool.js";
+import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { EngineRuntime } from "./runtime.js";
+/**
+ * Build ScanOptions.compatFileNames from the user's instruction compat toggles.
+ * Primary file name stays hard-wired to CODESHELL.md (not exposed). Turning a
+ * compat flag off only drops the same-named .md (CLAUDE.md / AGENTS.md); the
+ * .claude/ subdir, *.local.md and rules/ are intentionally NOT linked.
+ * undefined (instructions omitted) means both stay on — backward compatible.
+ */
+export declare function compatFileNamesFrom(instructions?: {
+    compatClaude?: boolean;
+    compatCodex?: boolean;
+}): string[];
 export interface EngineConfig {
     llm: LLMConfig;
+    /**
+     * Cross-model runtime knobs (temperature/timeout/retryMaxAttempts/imageDetail).
+     * Stays stable across hot model switches — only `llm` rotates. When omitted,
+     * Engine reads settings.json (model.temperature, images.detail) on construction.
+     */
+    clientDefaults?: ClientDefaults;
     cwd?: string;
     maxTurns?: number;
     maxToolCallsPerTurn?: number;
@@ -26,6 +48,23 @@ export interface EngineConfig {
     disabledBuiltinTools?: string[];
     customSystemPrompt?: string;
     appendSystemPrompt?: string;
+    responseLanguage?: string;
+    userProfile?: string;
+    instructions?: {
+        compatClaude?: boolean;
+        compatCodex?: boolean;
+    };
+    /**
+     * Goal mode: when set, the engine registers a GoalStopHook on `on_stop`
+     * so the turn loop runs until the session model judges this goal met
+     * (bounded by maxStopBlocks + maxTurns). Orthogonal to permissionMode —
+     * the desktop UI defaults permission to bypass when a goal is set, but
+     * the engine treats the two independently.
+     *
+     * Accepts a raw string (objective only) or a full GoalConfig (objective +
+     * optional token/time budgets); the run boundary normalizes it once.
+     */
+    goal?: string | GoalConfig;
     sessionStorageDir?: string;
     maxContextTokens?: number;
     approvalBackend?: ApprovalBackend;
@@ -46,6 +85,11 @@ export interface EngineConfig {
      * Defaults to false.
      */
     headless?: boolean;
+    /**
+     * When true, treat like headless for InvestigationGuard soft-mode — a
+     * read-only session should never be hard-blocked for repeated reads.
+     */
+    readOnlySession?: boolean;
     /**
      * Sandbox configuration for shell-tool execution. When omitted, headless
      * runs default to "auto" (Seatbelt on macOS / bwrap on Linux when
@@ -61,6 +105,12 @@ export interface EngineConfig {
      * pool, the runtime check still blocks the call.
      */
     isSubAgent?: boolean;
+    /**
+     * Host/context that created this Engine's sessions — written to state.json's
+     * `origin` so the desktop disk-rebuild can filter the sidebar (desktop +
+     * automation shown; tui hidden). Sub-agents override to "subagent".
+     */
+    origin?: SessionOrigin;
     /**
      * Optional shared EngineRuntime providing pre-constructed shared resources
      * (modelPool, toolRegistry, etc.). When provided, Engine uses these instead
@@ -68,7 +118,18 @@ export interface EngineConfig {
      * work unchanged — T11 will migrate them.
      */
     runtime?: EngineRuntime;
+    /**
+     * Which disk config layers this Engine may read. Defaults to 'project' —
+     * the safe default: a library/SDK embedding never silently inherits the
+     * host user's personal ~/.code-shell config (keys, models, MCP, hooks); it
+     * only reads the project-level ${cwd}/.code-shell that travels with a repo.
+     * Host-terminal entrypoints (TUI/desktop/CLI) pass 'full' to restore the
+     * managed+user+project+local behavior. 'isolated' reads no disk at all.
+     * Subagents inherit the parent Engine's scope. See SettingsScope.
+     */
+    settingsScope?: SettingsScope;
 }
+export { diskDefaultsFrom, type DiskDefaultPatch } from "../settings/disk-defaults.js";
 export interface EngineHookConfig {
     event: HookEventName;
     handler: HookHandler;
@@ -82,21 +143,88 @@ export interface EngineResult {
     turnCount: number;
     usage: TokenUsage;
 }
+/**
+ * Resolve the LLM config for a spawned child Engine.
+ * - `modelKey` set + present in pool → that model's config (pure entry-derived
+ *   identity; the parent's llm is NOT consulted).
+ * - otherwise (no key, no pool, or key miss) → the parent's llm unchanged.
+ * Key miss is a soft fallback, NOT an error: a stale agent definition must not
+ * crash the spawn.
+ *
+ * ClientDefaults (temperature/timeout/etc.) are inherited from the parent
+ * Engine directly via EngineConfig.clientDefaults — they do not flow through
+ * this helper because they're not part of LLMConfig anymore.
+ */
+export declare function resolveChildLlm(modelKey: string | undefined, pool: ModelPool | undefined, parentLlm: LLMConfig): LLMConfig;
+/**
+ * Load reusable sub-agent role definitions, merging:
+ *   1. project-level  <cwd>/.code-shell/agents/*.md   (ships built-ins)
+ *   2. user-level     ~/.code-shell/agents/*.md        (user wins on name)
+ * Names in `disabledAgents` are filtered out so the LLM never sees them.
+ */
+export declare function loadAgentDefinitionsForCwd(cwd: string, disabledAgents?: string[], disabledPlugins?: string[]): AgentDefinitionRegistry;
+/**
+ * #7: apply a project's per-turn builtin capability override to a tool list.
+ * A builtin marked `off` for the current cwd is HIDDEN from the turn's tool
+ * list (matching how skills/plugins/agents `off` apply mid-session). `on` /
+ * `inherit` / absent keep the tool — we can't re-add a tool the ctor-frozen
+ * registry omitted, but `on` for a tool already present is a no-op. Pure +
+ * exported so it's unit-testable without a full run() turn.
+ */
+export declare function applyBuiltinOverrideVisibility<T extends {
+    name: string;
+}>(tools: T[], override: Record<string, CapabilityOverride> | undefined): T[];
+/**
+ * Compute a child Engine's tool scope.
+ * - `allowlist` set → child enabled = allowlist minus nested-agent tools
+ *   (a per-role tool whitelist, e.g. a read-only researcher).
+ * - `allowlist` undefined → inherit parent enabled/disabled, always with the
+ *   nested-agent tools forced into `disabled` (no grandchildren).
+ */
+export declare function resolveChildToolScope(allowlist: string[] | undefined, parentDisabled: string[] | undefined, parentEnabled: string[] | undefined): {
+    enabled?: string[];
+    disabled: string[];
+};
 export declare class Engine {
     private config;
-    private readonly preset;
+    private preset;
     private toolRegistry;
     private hooks;
     private sessionManager;
     private mcpManager;
     private modelPool;
+    /**
+     * Handles for the settings-sourced hook handlers registered by
+     * registerSettingsHooks(), so reloadHooks() can unregister exactly those
+     * (and nothing else — plugin hooks, goal/builtin hooks are untouched) before
+     * re-registering from fresh settings. Without this, a reload would
+     * accumulate duplicate settings-hook handlers that all fire per event.
+     */
+    private settingsHookHandles;
+    /**
+     * Highest config-reload version applied so far. refreshRuntimeConfig drops
+     * any payload whose version is <= this, so out-of-order reload deliveries
+     * (multiple quick settings saves) can't let an older config clobber a newer
+     * one.
+     */
+    private lastAppliedConfigVersion;
+    /** Memoized sub-agent role registry, keyed by the cwd it was loaded from. */
+    private agentDefsCache?;
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     readonly runtime: EngineRuntime | null;
+    private readonly sandboxCache;
     /** Active permission mode for this Engine instance. */
     permissionMode: NonNullable<EngineConfig["permissionMode"]>;
     /** True when permissionMode === "plan". */
     planMode: boolean;
     private settingsManager;
+    /**
+     * Cached auxiliary-task LLM client, keyed by the models[].key it was built
+     * from. Background calls (memory extraction, auto-dream) reuse it across
+     * runs so we don't redo the provider handshake every session. Invalidated
+     * implicitly: a changed auxModelKey produces a different cache key.
+     */
+    private auxClientCache?;
     private lastContextManager;
     private lastMessages;
     private lastSessionId;
@@ -136,6 +264,19 @@ export declare class Engine {
      * should register SDK-side handlers.
      */
     private registerSettingsHooks;
+    /**
+     * Re-apply settings.hooks onto the live HookRegistry after a settings
+     * change (config hot-reload layer 2). Surgical: removes ONLY the
+     * settings-sourced handlers this Engine previously registered (tracked in
+     * settingsHookHandles by identity) and re-runs registerSettingsHooks() from
+     * fresh disk settings. Plugin hooks (registered once at construction at
+     * priority 80) and goal/builtin/SDK-config hooks are never touched.
+     *
+     * The SettingsManager cache is invalidated first so the re-read reflects the
+     * latest settings.json on disk (mirrors freshSettings()'s load() semantics).
+     * Sub-agents never register settings hooks, so this is a no-op for them.
+     */
+    reloadHooks(): void;
     constructor(config: EngineConfig);
     /**
      * Load models[] / providers[] from settings into the active ModelPool and
@@ -160,13 +301,18 @@ export declare class Engine {
      * Register a custom tool (from product adapter) into the tool registry.
      * Must be called before run().
      */
-    registerCustomTool(definition: import("../types.js").RegisteredTool, executor: (args: Record<string, unknown>) => Promise<string>): void;
+    registerCustomTool(definition: import("../types.js").RegisteredTool, executor: BuiltinToolFn): void;
     /**
      * Inject the askUser handler after construction. Used by AgentServer
      * to wire its protocol-backed askUser into an Engine that was created
      * before the server existed (chicken-and-egg: server takes engine in ctor).
      */
     setAskUser(fn: AskUserFn | undefined): void;
+    /**
+     * Whether this engine runs unattended (no interactive human). Used by the
+     * in-process AgentServer to decide whether to wire an interactive askUser.
+     */
+    isHeadless(): boolean;
     /**
      * Run a task from start to finish.
      */
@@ -175,12 +321,28 @@ export declare class Engine {
         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;
     }): Promise<EngineResult>;
     /**
      * Run the end-of-session memory pipeline as a fire-and-forget background
      * task. Extracts durable memories from the transcript, saves a session
      * summary, and conditionally triggers auto-dream consolidation.
      */
+    /**
+     * Resolve the LLM client for background/auxiliary work (memory extraction,
+     * auto-dream). When settings.auxModelKey names a valid pool model, build (and
+     * cache) a dedicated client for it so per-turn book-keeping runs on a cheap
+     * fast model instead of the expensive primary. Falls back to `fallback` (the
+     * active run's client) when unset, unknown, or on any build failure — aux
+     * work is best-effort and must never break a run.
+     */
+    private resolveAuxClient;
     private runMemoryPipeline;
     /**
      * Drive the auto-dream tool-call loop.
@@ -199,14 +361,6 @@ export declare class Engine {
      * bailed before the first LLM call (e.g. registry missing the tools).
      */
     private runDreamLoop;
-    /**
-     * Execute one memory tool call inside the dream loop. Enforces the two
-     * dream-loop invariants the prompt also states:
-     *   - Only the 4 memory tools are dispatchable.
-     *   - Save/Delete in "user" scope is refused (returned as a tool error)
-     *     because dream runs without an interactive permission backend.
-     */
-    private dispatchDreamTool;
     getToolRegistry(): ToolRegistry;
     /**
      * Switch the active model by pool key. Takes effect on the next run() call.
@@ -235,6 +389,44 @@ export declare class Engine {
     getHookRegistry(): HookRegistry;
     getSessionManager(): SessionManager;
     getConfig(): EngineConfig;
+    /**
+     * Config hot-reload "layer 2": merge a disk-default config patch into this
+     * ALREADY-RUNNING session's `this.config`, reload settings hooks, and
+     * incrementally connect any newly-added MCP servers. Applied at the next
+     * turn boundary — an in-flight turn is NOT interrupted: it keeps using the
+     * PromptComposer it was built with, and the next turn rebuilds the composer
+     * from the freshly-merged config (composer is rebuilt per-turn).
+     *
+     * `version` is a monotonic counter from the server: stale (<=last applied)
+     * payloads are dropped so out-of-order reload deliveries can't let an older
+     * config clobber a newer one (Q5).
+     *
+     * MCP: only connects (idempotent — already-connected servers are skipped);
+     * never disconnects, so an in-flight tool call on an existing server is
+     * never severed (Q3). Removed servers are deferred to the next session
+     * rebuild. If mcpManager isn't built yet (no MCP run has happened), the
+     * new servers will be connected on the next run via the existing per-run
+     * connectAll path — so we skip the connect here.
+     *
+     * Preset (#2): a preset hot-reload re-resolves `this.preset` so the next-turn
+     * PromptComposer picks up the new preset's system prompt / behavior — that's
+     * the main user-visible preset effect and it IS hot. The toolRegistry's
+     * builtin tool SET, however, is ctor-frozen (and may be shared via runtime):
+     * it is NOT rebuilt here. So a preset change that alters the builtin tool set
+     * (e.g. general → terminal-coding adds LSP/Brief) only takes effect on the
+     * next session restart; we log a warning when that case is detected.
+     *
+     * disk-default-vs-slice caveat (#8): the patch carries pure DISK-default
+     * values (preset/customSystemPrompt/appendSystemPrompt/responseLanguage/
+     * userProfile — see diskDefaultsFrom). Spreading them here OVERRIDES any
+     * per-request slice override of the same field. This is correct for the
+     * desktop host today (its per-request slice only carries permissionMode+cwd,
+     * which are excluded from the disk patch). A future host that sets
+     * slice.preset (or the other prompt fields) per-request MUST exclude those
+     * from the reload patch — or track per-request overrides separately — or this
+     * reload will clobber them back to disk values.
+     */
+    refreshRuntimeConfig(patch: Partial<EngineConfig>, version: number): void;
     /**
      * Inject context into a session's transcript without triggering a LLM turn.
      * The injected content appears as an assistant message so the LLM can see it
@@ -279,17 +471,65 @@ export declare class Engine {
      * Also syncs permissionMode to keep both fields consistent.
      */
     setPlanMode(value: boolean): void;
+    /**
+     * Block until a background agent's state changes (finishes / its result is
+     * enqueued) or `signal` aborts. Resolves `true` if aborted, `false` on a
+     * change. The caller re-checks `hasRunningForSession` after each wake, so a
+     * spurious wake (another session's agent) just loops again.
+     *
+     * Subscribes to BOTH the registry AND the notification queue — and that's
+     * load-bearing, not belt-and-suspenders. A completing agent calls
+     * `markCompleted` (registry notify) and only THEN `enqueue` (queue notify),
+     * as two separate statements. If we woke on the registry notify alone, the
+     * loop could re-check, see no running agents, and `drainAll` BEFORE the
+     * result was enqueued — silently losing the last agent's output. Waking on
+     * the queue notify guarantees the item is already in the bucket. But a
+     * *cancelled* agent marks-but-never-enqueues (by design), so we also need
+     * the registry notify or a final cancel would hang the wait forever. Hence
+     * both. Subscribe-before-await closes the check/wait race either way.
+     */
+    private waitForBackgroundAgentChange;
+    /**
+     * Sub-agent role registry for the given cwd, memoized per-cwd so the
+     * directory is read once rather than every turn. A new cwd (e.g. via
+     * run({ cwd })) reloads.
+     */
+    private getAgentDefinitions;
+    /**
+     * Read settings.disabledAgents, folded with the project's
+     * capabilityOverrides.agents overlay for `cwd`. Unlike disabledSkills,
+     * sub-agents do NOT skip this — a disabled role must stay invisible
+     * everywhere. The overlay lets a project force-enable a globally-disabled
+     * role or force-disable a globally-enabled one (tri-state); read UNMERGED
+     * (getForScope) so inherit survives. No cwd / no overlay → baseline
+     * unchanged. Mirrors readDisabledLists (skills/plugins).
+     */
+    private readDisabledAgents;
+    /**
+     * Read the project's capabilityOverrides.builtin bucket for `cwd`, read
+     * UNMERGED (getForScope) so tri-state inherit survives. Sub-agents skip the
+     * overlay (minimal surface, same as readDisabledLists) — their builtin lists
+     * are already narrowed by resolveChildToolScope. No cwd / error → undefined,
+     * so the caller's baseline builtin lists pass through unchanged.
+     */
+    private readBuiltinOverride;
     /**
      * Build a base ToolContext for this Engine. Used by run() (which then
      * overlays turn-specific fields like sandbox and subAgentSpawner) and
      * by tests that want a ToolContext without a full run() cycle.
      */
+    private resolveSandboxWithoutRuntime;
     buildToolContext(): ToolContext;
     /**
-     * Read settings.disabledSkills. Sub-agents skip this for the same
-     * reason they skip settings.hooks / plugin hooks (registerSettingsHooks
-     * at ~line 237): they run with a minimal surface area. Defaults to []
-     * so callers don't have to null-check.
+     * Read settings.disabledSkills + settings.disabledPlugins in a single
+     * pass. Sub-agents skip both for the same reason they skip
+     * settings.hooks / plugin hooks (registerSettingsHooks at ~line 237):
+     * they run with a minimal surface area. Defaults to [] for both
+     * fields so callers don't have to null-check.
+     *
+     * Combined read avoids drift if settings change between two separate
+     * reads — the prompt composer and the tool context will always see
+     * the same snapshot.
      */
-    private readDisabledSkills;
+    private readDisabledLists;
 }