@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/engine/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Public Engine configuration & result types.
+ *
+ * Extracted out of engine/engine.ts so consumers (protocol server, run
+ * factory, product layer, settings/disk-defaults, SDK index) can import the
+ * Engine's *types* without importing the 3000-line Engine *implementation* —
+ * which would pull the whole engine module (and its transitive deps) into a
+ * type-only consumer and make engine.ts a "type water tower". engine.ts
+ * re-exports these names, so existing `import { EngineConfig } from
+ * "../engine/engine.js"` callers keep working; new callers should prefer
+ * `engine/types.js`.
+ */
+import type { ClientDefaults, LLMConfig, SessionOrigin, TerminalReason, TokenUsage } from "../types.js";
+import type { AgentPresetName } from "../preset/index.js";
+import type { GoalConfig } from "./goal.js";
+import type { ApprovalBackend } from "../tool-system/permission.js";
+import type { SandboxConfig } from "../tool-system/sandbox/index.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 { EngineRuntime } from "./runtime.js";
+import type { HookEventName } from "../hooks/events.js";
+import type { HookHandler } from "../hooks/registry.js";
+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;
+    /**
+     * Override the goal-mode consecutive-stop-block cap (TODO 3.1). Falls back to
+     * goal.maxStopBlocks, then GOAL_DEFAULT_MAX_STOP_BLOCKS. See resolveMaxStopBlocks.
+     */
+    maxStopBlocks?: number;
+    maxToolCallsPerTurn?: number;
+    permissionMode?: "default" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "auto" | "plan";
+    preset?: AgentPresetName;
+    enabledBuiltinTools?: string[];
+    disabledBuiltinTools?: string[];
+    /**
+     * When false, `Bash(run_in_background=true)` is rejected and the
+     * background-shell tools are disabled (design §5.5). Set false by
+     * unattended automation/cron hosts — no one is there to reap a long-lived
+     * dev server. Defaults to true (interactive sessions allow it).
+     */
+    allowBackgroundShells?: boolean;
+    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;
+    hooks?: EngineHookConfig[];
+    askUser?: AskUserFn;
+    /** Browser automation bridge (browser_* tools). Wired by the host (desktop)
+     *  after construction via setBrowserBridge. Undefined → tools degrade. */
+    browserBridge?: import("../tool-system/browser-bridge.js").BrowserBridge;
+    /** Inject a cookie credential into the built-in browser (InjectCredential
+     *  tool). Wired by the host after construction via setInjectCredential.
+     *  Undefined → the tool degrades with a clear "no browser" error. */
+    injectCredentialToBrowser?: import("../tool-system/context.js").InjectCredentialFn;
+    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;
+    /**
+     * 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
+     * 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;
+    /**
+     * Hard skill isolation for a sub-agent. When set, this Engine only lists
+     * and invokes skills in this allowlist (applied on top of disabledSkills).
+     * Set by the spawn() closure from the role definition's `skills:`
+     * frontmatter. Undefined → inherit the parent's full skill pool.
+     */
+    skillAllowlist?: string[];
+    /**
+     * 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
+     * of constructing its own. Existing callers that omit this field continue to
+     * 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;
+    /**
+     * Workspace trust for the project directory (`cwd`). When explicitly `false`,
+     * dangerous fields committed into the project's own
+     * `.code-shell/settings.{json,local.json}` (permissions / env / hooks /
+     * mcpServers / localEnvironment) are stripped before merge, so a cloned
+     * malicious repo can't self-authorize permission rules, inject env
+     * (BASH_ENV/LD_PRELOAD), register hooks, or auto-connect MCP servers. Safe
+     * fields still apply. The user/managed layers are never gated.
+     *
+     * Undefined / true keeps the pre-trust behavior (fully trusted) so embedders
+     * that don't wire a trust store are unaffected. Host terminals (desktop) pass
+     * the real decision from their per-directory trust store; when it's "unknown"
+     * they should pass `false` (fail-closed) until the user grants trust.
+     */
+    projectTrusted?: boolean;
+}
+export interface EngineHookConfig {
+    event: HookEventName;
+    handler: HookHandler;
+    priority?: number;
+    name?: string;
+}
+export interface EngineResult {
+    text: string;
+    reason: TerminalReason;
+    sessionId: string;
+    turnCount: number;
+    usage: TokenUsage;
+}

package/dist/engine/types.js

@@ -0,0 +1,13 @@
+/**
+ * Public Engine configuration & result types.
+ *
+ * Extracted out of engine/engine.ts so consumers (protocol server, run
+ * factory, product layer, settings/disk-defaults, SDK index) can import the
+ * Engine's *types* without importing the 3000-line Engine *implementation* —
+ * which would pull the whole engine module (and its transitive deps) into a
+ * type-only consumer and make engine.ts a "type water tower". engine.ts
+ * re-exports these names, so existing `import { EngineConfig } from
+ * "../engine/engine.js"` callers keep working; new callers should prefer
+ * `engine/types.js`.
+ */
+export {};

package/dist/external-agents/config.d.ts

@@ -0,0 +1,2 @@
+import type { ExternalAgentsSettings, ResolvedExternalAgentsConfig } from "./types.js";
+export declare function resolveExternalAgentConfig(settings: ExternalAgentsSettings | undefined): ResolvedExternalAgentsConfig;

package/dist/external-agents/config.js

@@ -0,0 +1,15 @@
+export function resolveExternalAgentConfig(settings) {
+    return {
+        claudeCode: {
+            command: settings?.claudeCode?.command ?? "claude",
+            defaultMode: settings?.claudeCode?.defaultMode ?? "safe",
+            dangerousArgs: settings?.claudeCode?.dangerousArgs ?? [],
+            trustedWorkspaces: settings?.claudeCode?.trustedWorkspaces ?? [],
+            autoStartInTrustedWorkspaces: settings?.claudeCode?.autoStartInTrustedWorkspaces ?? false,
+        },
+        codex: {
+            command: settings?.codex?.command ?? "codex",
+            args: settings?.codex?.args ?? [],
+        },
+    };
+}

package/dist/external-agents/types.d.ts

@@ -0,0 +1,31 @@
+export type ExternalAgentMode = "safe" | "dangerous";
+export interface ClaudeCodeSettings {
+    command?: string;
+    defaultMode?: ExternalAgentMode;
+    dangerousArgs?: string[];
+    trustedWorkspaces?: string[];
+    autoStartInTrustedWorkspaces?: boolean;
+}
+export interface CodexSettings {
+    command?: string;
+    args?: string[];
+}
+export interface ExternalAgentsSettings {
+    claudeCode?: ClaudeCodeSettings;
+    codex?: CodexSettings;
+}
+export interface ResolvedClaudeCodeSettings {
+    command: string;
+    defaultMode: ExternalAgentMode;
+    dangerousArgs: string[];
+    trustedWorkspaces: string[];
+    autoStartInTrustedWorkspaces: boolean;
+}
+export interface ResolvedCodexSettings {
+    command: string;
+    args: string[];
+}
+export interface ResolvedExternalAgentsConfig {
+    claudeCode: ResolvedClaudeCodeSettings;
+    codex: ResolvedCodexSettings;
+}

package/dist/external-agents/types.js

@@ -0,0 +1 @@
+export {};

package/dist/git/parse-log.d.ts

@@ -0,0 +1,13 @@
+export interface GitLogEntry {
+    hash: string;
+    message: string;
+    author: string;
+    date: string;
+}
+/**
+ * Parse `git log --format=%H|%s|%an|%ci` output into entries. Tolerates
+ * malformed/short lines (missing `|` separators) by defaulting absent fields
+ * to "" rather than destructuring `undefined` and crashing on `.slice`
+ * (review-2026-05-30). Blank lines are skipped.
+ */
+export declare function parseGitLog(raw: string): GitLogEntry[];

package/dist/git/parse-log.js

@@ -0,0 +1,21 @@
+/**
+ * Parse `git log --format=%H|%s|%an|%ci` output into entries. Tolerates
+ * malformed/short lines (missing `|` separators) by defaulting absent fields
+ * to "" rather than destructuring `undefined` and crashing on `.slice`
+ * (review-2026-05-30). Blank lines are skipped.
+ */
+export function parseGitLog(raw) {
+    return raw
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => {
+        const parts = line.split("|");
+        const hash = parts[0] ?? "";
+        return {
+            hash: hash.slice(0, 8),
+            message: parts[1] ?? "",
+            author: parts[2] ?? "",
+            date: parts[3] ?? "",
+        };
+    });
+}

package/dist/git/utils.d.ts

@@ -1,16 +1,18 @@
 /**
  * Git utility functions for the git workflow commands.
+ *
+ * Every call goes through execFileSync with an argv array — no command
+ * strings, no shell interpolation. Even arguments that look "safe" (already
+ * quoted, hard-coded) are passed as separate argv tokens so a future caller
+ * can't accidentally widen the attack surface by interpolating user input
+ * into the string form.
  */
+import { type GitLogEntry } from "./parse-log.js";
 export interface GitStatusEntry {
     status: string;
     path: string;
 }
-export interface GitLogEntry {
-    hash: string;
-    message: string;
-    author: string;
-    date: string;
-}
+export type { GitLogEntry };
 export declare function isGitRepo(cwd: string): boolean;
 export declare function getCurrentBranch(cwd: string): string;
 export declare function getGitStatus(cwd: string): GitStatusEntry[];

package/dist/git/utils.js

@@ -1,10 +1,30 @@
 /**
  * Git utility functions for the git workflow commands.
+ *
+ * Every call goes through execFileSync with an argv array — no command
+ * strings, no shell interpolation. Even arguments that look "safe" (already
+ * quoted, hard-coded) are passed as separate argv tokens so a future caller
+ * can't accidentally widen the attack surface by interpolating user input
+ * into the string form.
  */
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import { parseGitLog } from "./parse-log.js";
+import { resolveExecutable } from "../utils/exec.js";
+// Resolve git/gh through PATH×PATHEXT on Windows so a .cmd/.exe shim is found
+// (bare execFile doesn't walk PATHEXT). No-op on POSIX. See utils/exec.ts.
+const GIT_BIN = resolveExecutable("git");
+const GH_BIN = resolveExecutable("gh");
+/** Run git with an argv array and return its trimmed stdout. */
+function git(cwd, args, timeoutMs = 10000) {
+    return execFileSync(GIT_BIN, args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+}
+/** Run gh with an argv array and return its trimmed stdout. */
+function gh(cwd, args, timeoutMs = 10000) {
+    return execFileSync(GH_BIN, args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+}
 export function isGitRepo(cwd) {
     try {
-        execSync("git rev-parse --is-inside-work-tree", { cwd, encoding: "utf-8", timeout: 5000 });
+        git(cwd, ["rev-parse", "--is-inside-work-tree"], 5000);
         return true;
     }
     catch {
@@ -12,10 +32,10 @@ export function isGitRepo(cwd) {
     }
 }
 export function getCurrentBranch(cwd) {
-    return execSync("git branch --show-current", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+    return git(cwd, ["branch", "--show-current"], 5000);
 }
 export function getGitStatus(cwd) {
-    const raw = execSync("git status --porcelain", { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+    const raw = git(cwd, ["status", "--porcelain"], 10000);
     if (!raw)
         return [];
     return raw.split("\n").map((line) => ({
@@ -24,51 +44,58 @@ export function getGitStatus(cwd) {
     }));
 }
 export function getGitDiff(cwd, opts) {
-    const args = ["git", "diff", "--no-color"];
+    const args = ["diff", "--no-color"];
     if (opts?.staged)
         args.push("--staged");
+    // `--` terminates option parsing so a file path starting with `-` can't
+    // be re-interpreted as a flag.
     if (opts?.file)
         args.push("--", opts.file);
-    return execSync(args.join(" "), { cwd, encoding: "utf-8", timeout: 30000 }).trim();
+    return git(cwd, args, 30000);
 }
 export function getGitDiffStat(cwd, opts) {
-    const args = ["git", "diff", "--stat", "--no-color"];
+    const args = ["diff", "--stat", "--no-color"];
     if (opts?.staged)
         args.push("--staged");
     if (opts?.file)
         args.push("--", opts.file);
-    return execSync(args.join(" "), { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+    return git(cwd, args, 10000);
 }
 export function getGitLog(cwd, n = 10) {
-    const raw = execSync(`git log --oneline --format="%H|%s|%an|%ci" -${n}`, { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+    // `n` is numeric — coerce/validate to keep the argv clean even if a caller
+    // hands us a string.
+    const count = Number.isFinite(n) && n > 0 ? Math.floor(n) : 10;
+    const raw = git(cwd, ["log", "--oneline", "--format=%H|%s|%an|%ci", `-${count}`], 10000);
     if (!raw)
         return [];
-    return raw.split("\n").map((line) => {
-        const [hash, message, author, date] = line.split("|");
-        return { hash: hash.slice(0, 8), message, author, date };
-    });
+    return parseGitLog(raw);
 }
 export function getRemoteUrl(cwd) {
     try {
-        return execSync("git remote get-url origin", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+        return git(cwd, ["remote", "get-url", "origin"], 5000);
     }
     catch {
         return undefined;
     }
 }
 export function gitAdd(cwd, files = ["."]) {
-    const fileArgs = files.map((f) => `"${f}"`).join(" ");
-    execSync(`git add ${fileArgs}`, { cwd, timeout: 10000 });
+    // `--` ensures a path starting with `-` cannot be parsed as a flag.
+    // Each file is its own argv token, so spaces / quotes / non-ASCII pass
+    // through verbatim with no shell parsing.
+    execFileSync(GIT_BIN, ["add", "--", ...files], { cwd, timeout: 10000 });
 }
 export function gitCommit(cwd, message) {
-    return execSync(`git commit -m ${JSON.stringify(message)}`, {
+    // Pre-fix this used `JSON.stringify(message)` which only happened to be
+    // safe because JSON.stringify covers most shell metacharacters — but it's
+    // not real escaping. The argv form is.
+    return execFileSync(GIT_BIN, ["commit", "-m", message], {
         cwd,
         encoding: "utf-8",
         timeout: 30000,
     }).trim();
 }
 export function gitListBranches(cwd) {
-    const raw = execSync("git branch --no-color", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+    const raw = git(cwd, ["branch", "--no-color"], 5000);
     if (!raw)
         return [];
     return raw.split("\n").map((line) => ({
@@ -77,12 +104,22 @@ export function gitListBranches(cwd) {
     }));
 }
 export function gitCheckout(cwd, branch, create = false) {
-    const flag = create ? "-b" : "";
-    execSync(`git checkout ${flag} ${branch}`, { cwd, timeout: 10000 });
+    // argv form defeats shell injection. We additionally reject branch names
+    // that start with `-` so a value like `--orphan` can't slip through git's
+    // own option parser (the trailing `--` trick doesn't help on checkout:
+    // git interprets it as the option's value, not as an option terminator).
+    if (typeof branch !== "string" || branch.length === 0) {
+        throw new Error("branch must be a non-empty string");
+    }
+    if (branch.startsWith("-")) {
+        throw new Error(`refusing branch name that starts with '-': ${branch}`);
+    }
+    const args = create ? ["checkout", "-b", branch] : ["checkout", branch];
+    execFileSync(GIT_BIN, args, { cwd, timeout: 10000 });
 }
 export function ghAvailable() {
     try {
-        execSync("gh --version", { encoding: "utf-8", timeout: 5000 });
+        execFileSync(GH_BIN, ["--version"], { encoding: "utf-8", timeout: 5000 });
         return true;
     }
     catch {
@@ -90,9 +127,8 @@ export function ghAvailable() {
     }
 }
 export function ghPrComments(cwd, prUrl) {
-    return execSync(`gh pr view ${prUrl} --comments --json comments -q ".comments[].body"`, {
-        cwd,
-        encoding: "utf-8",
-        timeout: 30000,
-    }).trim();
+    // Pre-fix `gh pr view ${prUrl}` interpolated the URL directly. argv form
+    // means even a value like "$(rm -rf ~)" is sent to gh as a literal
+    // positional argument (which gh will then reject as a bad PR URL).
+    return gh(cwd, ["pr", "view", prUrl, "--comments", "--json", "comments", "-q", ".comments[].body"], 30000);
 }

package/dist/git/worktree.d.ts

@@ -1,6 +1,7 @@
 /**
  * Git worktree management — create/remove isolated worktrees for agents.
  */
+import type { SandboxBackend } from "../tool-system/sandbox/index.js";
 export interface WorktreeSession {
     originalCwd: string;
     worktreePath: string;
@@ -10,6 +11,21 @@ export interface WorktreeSession {
     sessionId: string;
     createdAt: number;
 }
+/** Per-platform setup/cleanup scripts (a project's localEnvironment). */
+export interface PlatformScripts {
+    default?: string;
+    macos?: string;
+    linux?: string;
+    windows?: string;
+}
+/**
+ * Pick the setup/cleanup script for the running platform, falling back to
+ * `default`. Empty/whitespace-only scripts are treated as absent so a project
+ * can leave a platform key blank without spawning an empty shell. `platform`
+ * defaults to `process.platform` so callers usually omit it; tests pass a
+ * fixed value.
+ */
+export declare function selectPlatformScript(scripts: PlatformScripts | undefined, platform?: NodeJS.Platform): string | undefined;
 /**
  * Validate worktree slug to prevent path traversal attacks.
  */
@@ -22,6 +38,38 @@ export declare function findGitRoot(cwd: string): string;
  * Create an isolated git worktree for an agent session.
  */
 export declare function createWorktree(cwd: string, slug: string, sessionId: string): WorktreeSession;
+export interface WorktreeSetupResult {
+    /** True if no setup script was configured for this platform (nothing ran). */
+    skipped: boolean;
+    /** True if a script ran and exited 0. */
+    ok: boolean;
+    /** Combined stdout/stderr, for surfacing to the user on failure. */
+    output: string;
+    /** Exit code when a script ran; undefined when skipped. */
+    exitCode?: number | null;
+}
+/**
+ * Run a project's `localEnvironment.setupScripts` once, in the freshly-created
+ * worktree's root, right after `git worktree add`. This mirrors Codex's
+ * local-environment semantics: setup belongs to the *worktree* lifecycle, not
+ * the conversation — it runs when the isolated copy is born so e.g. `bun
+ * install` or `cp .env.example .env` happens before the agent works there.
+ *
+ * Failure is non-fatal by design (Beta decision 2026-06-08, "警告但继续"): a
+ * broken setup script shouldn't strand the agent outside a worktree it already
+ * created. The caller surfaces `output` as a warning and proceeds. cleanup
+ * scripts are intentionally NOT auto-run on exit (same decision).
+ *
+ * Reuses the same sandbox + env primitives as the Bash tool so the setup
+ * command sees the project's `localEnvironment.env` and runs under the same
+ * isolation the agent's later commands will.
+ */
+export declare function runWorktreeSetup(worktreePath: string, script: string | undefined, opts?: {
+    sandbox?: SandboxBackend;
+    shellEnv?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<WorktreeSetupResult>;
 /**
  * Remove a worktree and optionally its branch.
  */