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

package/dist/data/openrouter-sync.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runtime sync of the OpenRouter model catalog.
+ *
+ * Fetches openrouter.ai/api/v1/models and replaces the bundled snapshot
+ * in memory for the rest of the process. Used by the /sync-models slash
+ * command. To persist a sync across restarts, re-run the build (which
+ * re-runs scripts/sync-models.ts).
+ */
+import { getOpenRouterSnapshot } from "./openrouter-models.js";
+export interface SyncResult {
+    ok: boolean;
+    count: number;
+    error?: string;
+}
+export declare function syncOpenRouterCatalog(timeoutMs?: number): Promise<SyncResult>;
+export { getOpenRouterSnapshot };

package/dist/data/openrouter-sync.js

@@ -0,0 +1,53 @@
+/**
+ * Runtime sync of the OpenRouter model catalog.
+ *
+ * Fetches openrouter.ai/api/v1/models and replaces the bundled snapshot
+ * in memory for the rest of the process. Used by the /sync-models slash
+ * command. To persist a sync across restarts, re-run the build (which
+ * re-runs scripts/sync-models.ts).
+ */
+import { setOpenRouterSnapshot, getOpenRouterSnapshot, } from "./openrouter-models.js";
+const ENDPOINT = "https://openrouter.ai/api/v1/models";
+function priceToPerMillion(raw) {
+    if (!raw)
+        return 0;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n * 1_000_000 : 0;
+}
+function slim(m) {
+    return {
+        id: m.id,
+        name: m.name ?? m.id,
+        created: m.created ?? 0,
+        contextLength: m.top_provider?.context_length ?? m.context_length ?? 0,
+        maxOutputTokens: m.top_provider?.max_completion_tokens ?? 0,
+        inputPricePerMillion: priceToPerMillion(m.pricing?.prompt),
+        outputPricePerMillion: priceToPerMillion(m.pricing?.completion),
+        modalities: m.architecture?.input_modalities ?? [],
+    };
+}
+export async function syncOpenRouterCatalog(timeoutMs = 15_000) {
+    try {
+        const res = await fetch(ENDPOINT, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            return { ok: false, count: 0, error: `HTTP ${res.status} ${res.statusText}` };
+        }
+        const payload = (await res.json());
+        const raw = payload.data ?? [];
+        const models = raw.map(slim).sort((a, b) => b.created - a.created);
+        setOpenRouterSnapshot({
+            fetchedAt: new Date().toISOString(),
+            source: ENDPOINT,
+            count: models.length,
+            models,
+        });
+        return { ok: true, count: models.length };
+    }
+    catch (err) {
+        return { ok: false, count: 0, error: err.message };
+    }
+}
+export { getOpenRouterSnapshot };

package/dist/data/static-catalogs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hand-maintained static model catalogs for providers whose /v1/models
+ * endpoint returns only ids — no context window, max output, or pricing.
+ *
+ * At runtime we still call the live /models endpoint to discover ids
+ * (so newly-released models work without a code update), then left-join
+ * this table on `id` to fill in metadata. Edit the JSONs in src/data/
+ * when a vendor ships a new model.
+ *
+ * OpenRouter is NOT here — its catalog is generated at build time by
+ * scripts/sync-models.ts because OpenRouter exposes full metadata.
+ */
+import type { ProviderKindName } from "../llm/provider-kinds.js";
+export interface StaticModel {
+    id: string;
+    name: string;
+    contextLength: number;
+    maxOutputTokens: number;
+    inputPricePerMillion: number;
+    outputPricePerMillion: number;
+    modalities: string[];
+    thinking?: boolean;
+}
+export declare function listStaticModels(kind: ProviderKindName): StaticModel[];
+export declare function hasStaticCatalog(kind: ProviderKindName): boolean;

package/dist/data/static-catalogs.js

@@ -0,0 +1,26 @@
+/**
+ * Hand-maintained static model catalogs for providers whose /v1/models
+ * endpoint returns only ids — no context window, max output, or pricing.
+ *
+ * At runtime we still call the live /models endpoint to discover ids
+ * (so newly-released models work without a code update), then left-join
+ * this table on `id` to fill in metadata. Edit the JSONs in src/data/
+ * when a vendor ships a new model.
+ *
+ * OpenRouter is NOT here — its catalog is generated at build time by
+ * scripts/sync-models.ts because OpenRouter exposes full metadata.
+ */
+import { createRequire } from "node:module";
+const requireJson = createRequire(import.meta.url);
+const TABLES = {
+    deepseek: requireJson("./deepseek-models.json"),
+    zai: requireJson("./zai-models.json"),
+    openai: requireJson("./openai-models.json"),
+    google: requireJson("./gemini-models.json"),
+};
+export function listStaticModels(kind) {
+    return TABLES[kind]?.models ?? [];
+}
+export function hasStaticCatalog(kind) {
+    return TABLES[kind] !== undefined;
+}

package/dist/data/zai-models.json

@@ -0,0 +1,56 @@
+{
+  "fetchedAt": "2026-05-14",
+  "source": "https://docs.z.ai/guides/llm/glm-5.1 + https://docs.z.ai/guides/overview/pricing",
+  "count": 5,
+  "models": [
+    {
+      "id": "glm-5.1",
+      "name": "GLM-5.1",
+      "contextLength": 200000,
+      "maxOutputTokens": 128000,
+      "inputPricePerMillion": 1.4,
+      "outputPricePerMillion": 4.4,
+      "modalities": ["text"],
+      "thinking": true
+    },
+    {
+      "id": "glm-4.6",
+      "name": "GLM-4.6",
+      "contextLength": 200000,
+      "maxOutputTokens": 128000,
+      "inputPricePerMillion": 0.6,
+      "outputPricePerMillion": 2.2,
+      "modalities": ["text"],
+      "thinking": true
+    },
+    {
+      "id": "glm-4.5",
+      "name": "GLM-4.5",
+      "contextLength": 128000,
+      "maxOutputTokens": 96000,
+      "inputPricePerMillion": 0.6,
+      "outputPricePerMillion": 2.2,
+      "modalities": ["text"],
+      "thinking": true
+    },
+    {
+      "id": "glm-4.5-air",
+      "name": "GLM-4.5 Air",
+      "contextLength": 128000,
+      "maxOutputTokens": 96000,
+      "inputPricePerMillion": 0.2,
+      "outputPricePerMillion": 1.1,
+      "modalities": ["text"],
+      "thinking": true
+    },
+    {
+      "id": "glm-4.5-flash",
+      "name": "GLM-4.5 Flash (free tier)",
+      "contextLength": 128000,
+      "maxOutputTokens": 96000,
+      "inputPricePerMillion": 0,
+      "outputPricePerMillion": 0,
+      "modalities": ["text"]
+    }
+  ]
+}

package/dist/engine/cost-store.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CostStateStore — an opaque snapshot/restore hook that Engine uses to
+ * persist session-level cost state across `run({ sessionId })` calls.
+ *
+ * Engine itself doesn't compute prices or format summaries; it just hands
+ * the state blob to whatever store was injected. The CLI's `costTracker`
+ * is one concrete implementation; a SaaS backend might implement this
+ * against a database instead.
+ *
+ * Default: no store is injected, and cost state is not persisted. Engine
+ * continues to report per-run token usage via `EngineResult.usage` and
+ * `LLMClientBase.getUsage()` — this hook is only for the
+ * "resume-and-keep-counting" scenario.
+ */
+/** Arbitrary serializable snapshot — opaque to Engine. */
+export type CostStateSnapshot = unknown;
+export interface CostStateStore {
+    /** Serialize current cost state for persistence. */
+    serialize(): CostStateSnapshot;
+    /** Restore previously-serialized cost state. */
+    restore(state: CostStateSnapshot): void;
+}

package/dist/engine/cost-store.js

@@ -0,0 +1,15 @@
+/**
+ * CostStateStore — an opaque snapshot/restore hook that Engine uses to
+ * persist session-level cost state across `run({ sessionId })` calls.
+ *
+ * Engine itself doesn't compute prices or format summaries; it just hands
+ * the state blob to whatever store was injected. The CLI's `costTracker`
+ * is one concrete implementation; a SaaS backend might implement this
+ * against a database instead.
+ *
+ * Default: no store is injected, and cost state is not persisted. Engine
+ * continues to report per-run token usage via `EngineResult.usage` and
+ * `LLMClientBase.getUsage()` — this hook is only for the
+ * "resume-and-keep-counting" scenario.
+ */
+export {};

package/dist/engine/engine.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Engine — the main facade that wires all components together.
+ */
+import type { LLMConfig, StreamCallback, TerminalReason, TokenUsage } from "../types.js";
+import { ToolRegistry } from "../tool-system/registry.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 { 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 { 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 { EngineRuntime } from "./runtime.js";
+export interface EngineConfig {
+    llm: LLMConfig;
+    cwd?: string;
+    maxTurns?: number;
+    maxToolCallsPerTurn?: number;
+    permissionMode?: "default" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "auto" | "plan";
+    preset?: AgentPresetName;
+    enabledBuiltinTools?: string[];
+    disabledBuiltinTools?: string[];
+    customSystemPrompt?: string;
+    appendSystemPrompt?: string;
+    sessionStorageDir?: string;
+    maxContextTokens?: number;
+    approvalBackend?: ApprovalBackend;
+    hooks?: EngineHookConfig[];
+    askUser?: AskUserFn;
+    mcpServers?: Record<string, import("../types.js").MCPServerConfig>;
+    /**
+     * Optional opaque store for per-session cost/usage state. When provided,
+     * Engine calls `restore()` on session resume and `serialize()` at the end
+     * of each `run()` and stores the blob on the session. Without this the
+     * Engine doesn't persist cost state — it's a UI concern.
+     */
+    costStore?: CostStateStore;
+    /**
+     * True when the Engine runs in a no-UI / one-shot context (e.g. the `run`
+     * command). Currently controls InvestigationGuard soft-mode: in headless
+     * we never hard-block a tool call because there is no human to retry.
+     * Defaults to false.
+     */
+    headless?: boolean;
+    /**
+     * Sandbox configuration for shell-tool execution. When omitted, headless
+     * runs default to "auto" (Seatbelt on macOS / bwrap on Linux when
+     * available) and interactive runs default to "off" because a human is in
+     * the loop to approve commands.
+     */
+    sandbox?: SandboxConfig;
+    /**
+     * True when this Engine is itself a sub-agent (spawned by another
+     * Engine's Agent tool). Threaded into ToolContext so the Agent tool can
+     * refuse re-entry — defense in depth against the tool-list strip in
+     * spawn(): if a tool registry regression ever leaks Agent into a child's
+     * pool, the runtime check still blocks the call.
+     */
+    isSubAgent?: boolean;
+    /**
+     * Optional shared EngineRuntime providing pre-constructed shared resources
+     * (modelPool, toolRegistry, etc.). When provided, Engine uses these instead
+     * of constructing its own. Existing callers that omit this field continue to
+     * work unchanged — T11 will migrate them.
+     */
+    runtime?: EngineRuntime;
+}
+export interface EngineHookConfig {
+    event: HookEventName;
+    handler: HookHandler;
+    priority?: number;
+    name?: string;
+}
+export interface EngineResult {
+    text: string;
+    reason: TerminalReason;
+    sessionId: string;
+    turnCount: number;
+    usage: TokenUsage;
+}
+export declare class Engine {
+    private config;
+    private readonly preset;
+    private toolRegistry;
+    private hooks;
+    private sessionManager;
+    private mcpManager;
+    private modelPool;
+    /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
+    readonly runtime: EngineRuntime | null;
+    /** Active permission mode for this Engine instance. */
+    permissionMode: NonNullable<EngineConfig["permissionMode"]>;
+    /** True when permissionMode === "plan". */
+    planMode: boolean;
+    private settingsManager;
+    private lastContextManager;
+    private lastMessages;
+    private lastSessionId;
+    private compactedMessagesBySession;
+    /**
+     * SIDs whose ctx-bar seed we've already emitted in this process. The seed
+     * is a rough char/4 estimate; only useful before the first real
+     * usage_update arrives (cold start or cross-process resume). On subsequent
+     * turns the UI already shows the previous turn's accurate ctx — re-seeding
+     * would visibly drop the bar on every submit.
+     */
+    private ctxSeedSent;
+    /**
+     * Per-sid cache of "non-messages overhead" (system prompt + tool defs, in
+     * tokens). Survives across turns so each fresh TurnLoop instance can seed
+     * its first pre-llm emit with the right offset — without this the ctx bar
+     * visibly drops on every user submit (e.g. from ~20k → 3k) until the next
+     * LLM response arrives.
+     */
+    private ctxOverheadBySid;
+    private activePermission;
+    /** Public accessor so UI/clients can read the resolved per-model window. */
+    get maxContextTokens(): number;
+    private resolveMaxContextTokens;
+    /**
+     * Emit a lifecycle hook with isSubAgent auto-merged into data so handlers
+     * can skip noisy injections for spawned children. All Engine-side hook
+     * emits should go through this wrapper to keep the context envelope
+     * uniform with TurnLoop.emitHook.
+     */
+    private emitHook;
+    /**
+     * Read settings.hooks and register a shell-runner wrapper handler per
+     * entry. Sub-agents skip shell hooks entirely — spawning child processes
+     * per emit for every sub-agent run would multiply token-side overhead
+     * for marginal value; explicit users who want sub-agent observability
+     * should register SDK-side handlers.
+     */
+    private registerSettingsHooks;
+    constructor(config: EngineConfig);
+    /**
+     * Load models[] / providers[] from settings into the active ModelPool and
+     * resync this.config.llm with the matching entry. Called from the ctor and
+     * from reloadModelPool() (e.g. after onboarding writes new entries to disk).
+     */
+    private populateModelPoolFromSettings;
+    /**
+     * Re-read settings and refresh the model pool. Used after onboarding /login
+     * writes new providers[] / models[] to disk so the running engine picks them
+     * up without a process restart. Existing pool entries are kept (re-registering
+     * the same key overwrites them), so callers don't need to clear first.
+     */
+    reloadModelPool(): void;
+    /**
+     * Auto-populate the model pool when settings.models[] is empty but
+     * the user has configured an API key. Detects the provider from the
+     * key prefix / baseUrl and registers all its known models.
+     */
+    private autoPopulatePool;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Run a task from start to finish.
+     */
+    run(task: string, options?: {
+        cwd?: string;
+        onStream?: StreamCallback;
+        signal?: AbortSignal;
+        sessionId?: string;
+    }): 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.
+     */
+    private runMemoryPipeline;
+    /**
+     * Drive the auto-dream tool-call loop.
+     *
+     * Runs the LLM with a whitelisted subset of memory tools (MemoryList,
+     * MemoryRead, MemorySave, MemoryDelete). The loop is intentionally small
+     * and offline:
+     *   - No streaming, no UI events — runs in the background after a session.
+     *   - No permission prompts — UI isn't attached, so we hard-reject any
+     *     attempt to Save/Delete in the "user" scope before dispatching. Dream
+     *     scope is the LLM's workspace and goes through freely.
+     *   - Capped at MAX_TURNS LLM round-trips and MAX_WRITES total
+     *     mutations to bound damage on misbehavior.
+     *
+     * Returns true if the loop ran (with or without writes); false if we
+     * 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.
+     * Returns the new model entry.
+     *
+     * Persists settings.activeKey (and a legacy settings.model.* mirror) so the
+     * next process startup defaults to the same model — without this, switches
+     * only live in memory and every restart reverts to the previously persisted
+     * activeKey.
+     */
+    switchModel(key: string): ModelEntry;
+    /**
+     * Write the active model selection to ~/.code-shell/settings.json.
+     *
+     * We mirror into the legacy settings.model.* block (provider/name/apiKey/
+     * baseUrl) because boot paths in cli/main.ts, repl.ts, run.ts still read it.
+     * The mirror uses resolved llm values (not raw entry.*) so credentials that
+     * live on settings.providers[] flow through correctly — entry.apiKey is
+     * undefined when the entry resolves via providerCatalog.
+     */
+    private persistActiveModel;
+    /** Get the model pool. */
+    getModelPool(): ModelPool;
+    /** Get the current model name (full path). */
+    getCurrentModel(): string;
+    getHookRegistry(): HookRegistry;
+    getSessionManager(): SessionManager;
+    getConfig(): EngineConfig;
+    /**
+     * 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
+     * in subsequent conversations. The transcript auto-flushes to disk.
+     *
+     * Also updates the in-memory compacted message cache so the next
+     * engine.run() call for this session picks up the injected content
+     * instead of a stale snapshot from the previous run.
+     */
+    injectContext(sessionId: string, content: string): void;
+    /**
+     * Force context compaction on the current session.
+     * Returns token stats before/after.
+     */
+    forceCompact(): {
+        before: number;
+        after: number;
+        strategy: string;
+    };
+    private stripUserContextMessage;
+    private getSettingsManager;
+    /**
+     * Update a config setting at runtime.
+     */
+    updateConfig(key: string, value: unknown): void;
+    /**
+     * Read a settings value by dotted key (e.g. "arena.participants").
+     * Returns undefined if any segment is missing.
+     */
+    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.
+     * Session-only — does not persist to settings.
+     */
+    setPermissionMode(mode: NonNullable<EngineConfig["permissionMode"]>): void;
+    getPermissionMode(): NonNullable<EngineConfig["permissionMode"]>;
+    /**
+     * Toggle plan mode directly. Called by the Plan tool (Task 7) via ToolContext.engine.
+     * Also syncs permissionMode to keep both fields consistent.
+     */
+    setPlanMode(value: boolean): void;
+    /**
+     * 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.
+     */
+    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.
+     */
+    private readDisabledSkills;
+}