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

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Core type definitions for the code-shell orchestration framework.
  */
+import type { GoalConfig } from "./engine/goal.js";
 export interface ContentBlock {
     type: "text" | "tool_use" | "tool_result" | "image" | "reasoning";
     text?: string;
@@ -9,6 +10,12 @@ export interface ContentBlock {
     input?: Record<string, unknown>;
     content?: string | ContentBlock[];
     tool_use_id?: string;
+    /**
+     * 标记 tool_result 为出错,让 provider 据此设置 wire 层错误标志
+     * (Anthropic 的 `is_error: true`)。不设的话,出错的工具只会以普通
+     * content 文字回传,模型可能把超时/中断误当成成功。
+     */
+    is_error?: boolean;
     source?: {
         type: "base64";
         media_type: string;
@@ -37,10 +44,53 @@ export interface ToolResult {
     id: string;
     toolName: string;
     result?: string;
+    /**
+     * 结构化结果块(目前仅图片)。存在时优先于 `result` 用作发给 LLM 的
+     * tool_result content —— view_image 用它把本地图片以 image ContentBlock
+     * 回传,让 vision 模型能「看」自己生成的图。非视觉模型由 provider 的
+     * stripVisionFromHistory 自动剥离,所以这里照常带图也安全。
+     */
+    contentBlocks?: ContentBlock[];
     error?: string;
     isError?: boolean;
+    /**
+     * Set by tools that execute under the sandbox (Bash / background shell /
+     * worktree) so the UI can show whether THIS call was isolated. `backend`
+     * "off" means the command ran un-sandboxed (we surface it explicitly so the
+     * user sees "未隔离" rather than guessing from an absent badge); "seatbelt"
+     * / "bwrap" mean OS-level isolation applied. `network` is the policy that
+     * was in force (absent when off). Tools that don't touch the sandbox leave
+     * this undefined and the UI renders no badge.
+     */
+    sandbox?: {
+        backend: "off" | "seatbelt" | "bwrap";
+        network?: "allow" | "deny";
+    };
 }
 export type ToolSource = "builtin" | "mcp";
+export type ToolPathPolicyOperation = "read" | "write" | {
+    /** Argument whose value decides whether this invocation reads or writes. */
+    fromArg: string;
+    /** Values that classify the operation as a read. */
+    readValues?: string[];
+    /** Values that classify the operation as a write. */
+    writeValues?: string[];
+    /** Fallback when the argument is absent or does not match either list. */
+    default: "read" | "write";
+};
+export type ToolPathPolicy = {
+    kind: "arg";
+    /** Argument containing a file or directory path. */
+    arg: string;
+    operation: ToolPathPolicyOperation;
+    /** Use ctx.cwd when the argument is omitted. Useful for Glob/Grep roots. */
+    defaultToCwd?: boolean;
+} | {
+    kind: "apply_patch";
+    /** Argument containing the V4A patch text. */
+    arg: string;
+    operation: "write";
+};
 export interface RegisteredTool {
     name: string;
     description: string;
@@ -50,6 +100,18 @@ export interface RegisteredTool {
     permissionDefault: PermissionDecision;
     isConcurrencySafe?: boolean;
     isReadOnly?: boolean;
+    /**
+     * Declarative file-path safety metadata. ToolExecutor enforces this before
+     * dispatching the tool, so file access cannot depend on each tool handler
+     * remembering to call path-policy manually.
+     */
+    pathPolicy?: ToolPathPolicy[];
+    /**
+     * Explicitly marks a path-looking tool as intentionally outside the file
+     * policy layer. Used by tests/audits so new file tools fail closed unless
+     * they either declare pathPolicy or document an exemption.
+     */
+    pathPolicyExempt?: boolean;
     /**
      * Override the default tool execution timeout (ms).
      * Falls back to DEFAULT_TOOL_TIMEOUT_MS (120s) if unset.
@@ -57,7 +119,7 @@ export interface RegisteredTool {
      */
     timeoutMs?: number;
 }
-export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "turn_boundary" | "error";
+export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "subagent" | "turn_boundary" | "goal_progress" | "turn_stopped" | "error";
 export interface TranscriptEvent {
     id: string;
     type: TranscriptEventType;
@@ -67,12 +129,16 @@ export interface TranscriptEvent {
 }
 /**
  * Session lifecycle state persisted in state.json. `"active"` means a run is
- * currently in flight (or was, at the moment of the last heartbeat). All other
- * values match the {@link TerminalReason} the last run returned, so callers
- * can distinguish a user-cancelled session (`"aborted_streaming"`) from an
- * actual error (`"model_error"`, `"prompt_too_long"`, ...).
+ * currently in flight (or was, at the moment of the last heartbeat);
+ * `"paused"` is a non-terminal hold (not a {@link TerminalReason}). Every
+ * other value matches the TerminalReason the last run returned, so callers can
+ * distinguish a user-cancelled session (`"aborted_streaming"`) from an actual
+ * error (`"model_error"`, `"prompt_too_long"`, ...).
  */
 export type SessionStatus = "active" | "paused" | TerminalReason;
+/** Which host/context created a session — used by the desktop disk-rebuild to
+ *  filter the sidebar (only `desktop` + `automation` are shown). */
+export type SessionOrigin = "desktop" | "tui" | "automation" | "subagent";
 export interface SessionState {
     sessionId: string;
     cwd: string;
@@ -81,13 +147,49 @@ export interface SessionState {
     provider: string;
     tokenUsage: TokenUsage;
     turnCount: number;
+    /**
+     * Conversation-turn counter where ONE user message = one turn (incremented in
+     * engine.run before the message hits the LLM). Distinct from `turnCount`,
+     * which counts turn-loop iterations (a single user message can span many).
+     * Tags file-history snapshots so turn-level `/undo` can revert exactly what
+     * the last user message changed. Absent on legacy sessions → treated as 0.
+     */
+    turnSeq?: number;
     invokedSkills: string[];
-    parentSessionId?: string;
+    /**
+     * Owning parent session for a sub-agent run; `null` explicitly marks a
+     * top-level session (post-create marker). Absent only on legacy sessions
+     * written before this field existed — the desktop disk-rebuild uses
+     * "key present && null" to tell a new top-level session apart from legacy.
+     */
+    parentSessionId?: string | null;
+    /**
+     * Which host/context created this session. Desktop disk-rebuild shows only
+     * `desktop` + `automation`. Absent on legacy sessions.
+     */
+    origin?: SessionOrigin;
     status: SessionStatus;
     /** Short summary derived from the first user message */
     summary?: string;
+    /**
+     * LLM-generated one-line title (auxModel, after the first turn). Distinct from
+     * `summary` (the raw first-message fallback). Persisted so the sidebar shows
+     * it after a localStorage wipe / disk rebuild — without this it lived only in
+     * the renderer's localStorage index and was lost on reset.
+     */
+    title?: string;
     /** Persisted cost tracking state (survives process restart). */
     costState?: Record<string, unknown>;
+    /**
+     * Active persistent goal (CC `/goal` style). Set once, it survives across
+     * messages AND manual interrupts until the judge says it's met or the user
+     * clears it. Absent → no active goal. When a run supplies a new goal it
+     * REPLACES this (one active goal per session). The judge's `met` verdict and
+     * `agent/goalClear` both clear it. Persisted so it survives resume/refresh;
+     * on resume the objective carries over but the run-scoped turn/token/time
+     * baselines reset (matching CC). See engine.run goal-resolution.
+     */
+    activeGoal?: GoalConfig;
 }
 export interface TokenUsage {
     promptTokens: number;
@@ -140,11 +242,22 @@ export interface ApprovalRequest {
  *               survives restart for the current project. Not committed.
  */
 export type ApprovalScope = "once" | "session" | "project";
+/**
+ * Path granularity for a remembered file-tool grant (Write/Edit). Narrows the
+ * remembered rule so "allow Write src/foo.ts for this session" doesn't become
+ * "allow Write to ANY path".
+ *   "file" — only this exact file
+ *   "dir"  — this file's directory and its subdirectories
+ *   "tool" — every path (the legacy tool-wide behavior)
+ * Omitted → "tool" (back-compat). Ignored for non-file tools.
+ */
+export type ApprovalPathScope = "file" | "dir" | "tool";
 export type ApprovalResult = {
     approved: true;
     permanent?: boolean;
     always?: boolean;
     scope?: ApprovalScope;
+    pathScope?: ApprovalPathScope;
     /** Used by AskUserQuestion to carry the user's free-text answer. */ answer?: string;
 } | {
     approved: false;
@@ -159,7 +272,7 @@ export interface TurnResult {
     status: "completed" | "tool_use" | "error" | "max_turns" | "aborted";
     error?: string;
 }
-export type TerminalReason = "completed" | "stop_hook_prevented" | "hook_stopped" | "prompt_too_long" | "model_error" | "aborted_streaming" | "aborted_tools" | "max_turns" | "image_error";
+export type TerminalReason = "completed" | "stop_hook_prevented" | "hook_stopped" | "prompt_too_long" | "model_error" | "aborted_streaming" | "aborted_tools" | "max_turns" | "goal_budget_exhausted" | "image_error";
 export interface TaskInfo {
     id: string;
     subject: string;
@@ -170,10 +283,18 @@ export type StreamEvent = {
     type: "session_started";
     sessionId: string;
     promptTokens: number;
+} | {
+    type: "session_title";
+    sessionId: string;
+    title: string;
 } | {
     type: "stream_request_start";
     turnNumber: number;
     agentId?: string;
+} | {
+    type: "steer_injected";
+    text: string;
+    id?: string;
 } | {
     type: "text_delta";
     text: string;
@@ -200,6 +321,24 @@ export type StreamEvent = {
     type: "turn_complete";
     reason: TerminalReason;
     agentId?: string;
+} | {
+    type: "goal_progress";
+    status: "not_met" | "met" | "exhausted" | "approaching_limit";
+    round: number;
+    gaps?: string;
+    /** For "approaching_limit": turns left before the maxTurns cap (TODO 3.1). */
+    turnsRemaining?: number;
+    /** For "approaching_limit": consecutive blocks left before maxStopBlocks (TODO 3.1). */
+    stopBlocksRemaining?: number;
+    /** For "approaching_limit": which ceiling is closest — drives UI copy + extend default. */
+    nearest?: "turns" | "stopBlocks";
+    agentId?: string;
+} | {
+    type: "goal_set";
+    objective: string;
+    replaced: boolean;
+} | {
+    type: "goal_cleared";
 } | {
     type: "error";
     error: string;
@@ -210,6 +349,13 @@ export type StreamEvent = {
 } | {
     type: "task_update";
     tasks: TaskInfo[];
+    agentId?: string;
+} | {
+    type: "memory_recalled";
+    name: string;
+    scope: "user" | "dream";
+    location: "global" | "project";
+    agentId?: string;
 } | {
     type: "thinking_delta";
     text: string;
@@ -219,6 +365,13 @@ export type StreamEvent = {
     agentId: string;
     name?: string;
     description: string;
+    agentType?: string;
+} | {
+    type: "agent_backgrounded";
+    agentId: string;
+    name?: string;
+    description: string;
+    agentType?: string;
 } | {
     type: "agent_end";
     agentId: string;
@@ -226,6 +379,11 @@ export type StreamEvent = {
     description: string;
     text?: string;
     error?: string;
+    agentType?: string;
+} | {
+    type: "agent_heartbeat";
+    agentIds: string[];
+    ts: number;
 } | {
     type: "tool_summary";
     summary: string;
@@ -238,6 +396,27 @@ export type StreamEvent = {
 } | {
     type: "usage_update";
     promptTokens: number;
+    /**
+     * Provider-reported prompt-cache counts, forwarded so the UI can show a
+     * cache hit rate in the context-ring tooltip. Present only when the LLM
+     * response carried them (authoritative-usage emits); omitted on the
+     * message-estimate emits that fire between LLM calls. See
+     * docs/todo/prompt-cache-optimization.md.
+     */
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    /**
+     * SESSION-CUMULATIVE cache counts (sum across every LLM response this
+     * session, across runs and turns), emitted from the engine's turn
+     * boundary off the persisted session.state.tokenUsage. Distinct from the
+     * per-response cacheReadTokens/cacheCreationTokens above: those drive the
+     * live context reading, these drive the "本会话累计命中率" tooltip. Reset
+     * to 0 on a model switch. Present only on the cumulative (turn-boundary)
+     * emit; omitted on per-response / estimate emits.
+     */
+    sessionCacheReadTokens?: number;
+    sessionCacheCreationTokens?: number;
+    sessionPromptTokens?: number;
     agentId?: string;
 } | {
     type: "background_agent_completed";
@@ -245,6 +424,15 @@ export type StreamEvent = {
     name?: string;
     description: string;
     status: "completed" | "failed";
+    /**
+     * What kind of background work this was. Lets UIs localize the
+     * completion toast (e.g. a shell shows "命令完成" not the raw English
+     * description, which is written for the agent's wakeup notification).
+     * Absent for legacy sub-agent notifications (treated as "agent").
+     */
+    workKind?: "agent" | "shell" | "video" | "cc";
+    /** For workKind === "shell": the command that ran (for a friendly label). */
+    command?: string;
     /** Final assistant text (status === "completed" only). */
     finalText?: string;
     /** Error message (status === "failed" only). */
@@ -261,22 +449,42 @@ export type BackgroundAgentCompletedEvent = Extract<StreamEvent, {
     type: "background_agent_completed";
 }>;
 export type StreamCallback = (event: StreamEvent) => void | Promise<void>;
+/**
+ * LLMConfig — model identity only. Everything in this object describes
+ * "which model and how to reach it", nothing about user preferences or
+ * client wiring. Hot-switching models replaces this object wholesale.
+ *
+ * For cross-model preferences (temperature, timeouts, image detail) see
+ * ClientDefaults — those live on the Engine and feed every LLMClient
+ * independently of model identity.
+ */
 export interface LLMConfig {
     provider: string;
     model: string;
     apiKey?: string;
     baseUrl?: string;
-    temperature?: number;
-    topP?: number;
     maxTokens?: number;
-    timeout?: number;
-    retryMaxAttempts?: number;
-    enableStreaming?: boolean;
     /**
-     * Default thinking-mode for DeepSeek V4. Per-call `options.thinking`
-     * (e.g. summarize sub-calls) overrides this. Ignored on other providers.
+     * Shell command whose stdout is the auth token (TODO 7.2). Resolved at
+     * client-build time when `apiKey` is absent. The trimmed first line of
+     * stdout becomes the bearer token.
+     */
+    authCommand?: string;
+    /**
+     * Extra HTTP headers for every request to this model's provider (TODO 7.2).
+     * A value `$ENV_VAR` is resolved from the environment at build time.
      */
-    thinking?: "enabled" | "disabled";
+    httpHeaders?: Record<string, string>;
+    /** OpenAI `service_tier` request param, passed through verbatim (TODO 7.2). */
+    serviceTier?: string;
+    /** OpenAI reasoning `summary` control ("auto"|"concise"|"detailed") (TODO 7.2). */
+    reasoningSummary?: string;
+    /**
+     * Default reasoning/thinking setting for this model. Per-call
+     * `options.reasoning` (e.g. summarize sub-calls) overrides this.
+     * Translated to the per-vendor wire form by the client's capability layer.
+     */
+    reasoning?: import("./llm/reasoning-setting.js").ReasoningSetting;
     /**
      * The provider's `kind` (deepseek/openai/zai/openrouter/...). Used by
      * the capability layer to look up per-(kind, model) request-shape rules
@@ -285,6 +493,38 @@ export interface LLMConfig {
      * ("openai" or "anthropic") that picks which client class to use.
      */
     providerKind?: string;
+    /**
+     * Catalog-driven extra request-body fields (temperature/top_p/thinking etc),
+     * already wire-mapped from the connection's paramValues. Merged into the
+     * request body, each key filtered by the model's rejectedParams.
+     */
+    extraBody?: Record<string, unknown>;
+}
+/**
+ * ClientDefaults — runtime knobs that apply regardless of which model is
+ * active. Settings/UI source these once at boot (or when settings change);
+ * model hot-switching never alters them.
+ *
+ * Anything model-specific belongs in LLMConfig instead.
+ */
+export interface ClientDefaults {
+    /** Sampling temperature. Default 0.3. Per-call options.temperature overrides. */
+    temperature?: number;
+    /** HTTP timeout in ms for LLM requests. Default 120_000. */
+    timeout?: number;
+    /** Max retry attempts for transient errors. Default 3. */
+    retryMaxAttempts?: number;
+    /**
+     * Provider-agnostic image clarity level. Drives the renderer-side
+     * downscale (long-edge cap: low→~1024 / standard→~1568 / high→~2576)
+     * so BOTH providers save tokens before send. On the OpenAI path it
+     * also maps to the wire `detail` hint (low→low, standard/high→high);
+     * Anthropic has no such param and saves purely via the downscale.
+     * Defaults to "high" (full fidelity) when unset.
+     *
+     * Legacy "original" values from older settings are migrated to "high".
+     */
+    imageDetail?: "low" | "standard" | "high";
 }
 export interface LLMResponse {
     text: string;
@@ -310,6 +550,51 @@ export interface MCPServerConfig {
     url?: string;
     transport?: MCPTransport;
     headers?: Record<string, string>;
+    /**
+     * (stdio) NAMES of env vars to forward from the parent process to the
+     * spawned server. The value is read from `process.env` at connect time —
+     * the secret itself is never stored in config. Explicit `env` overrides.
+     */
+    envVars?: string[];
+    /**
+     * (HTTP) NAME of an env var whose value is sent as
+     * `Authorization: Bearer <value>`. Read from `process.env` at connect time.
+     */
+    bearerTokenEnvVar?: string;
+    /**
+     * (HTTP) Map of header-name → env-var-NAME. Each header's value is read
+     * from the named env var at connect time, keeping secrets out of config.
+     */
+    envHeaders?: Record<string, string>;
+    /**
+     * (HTTP) id of a stored credential (CredentialStore) to use as the Bearer
+     * token. Resolved at connect time via a resolver passed to buildHttpHeaders;
+     * the secret is never stored in the MCP config. Wins over bearerTokenEnvVar.
+     */
+    credentialRef?: string;
+    /**
+     * Toggle a server off without deleting its config (mirrors Codex's
+     * `enabled` field). Absent or `true` → connected; only the literal
+     * `false` disables it. Filtered in MCPManager.connectAll so the
+     * connection is never attempted; the entry stays in settings so the
+     * UI toggle can flip it back on. See connectAll().
+     */
+    enabled?: boolean;
+}
+/**
+ * User-supplied supplement for a PLUGIN-provided MCP server, keyed by the
+ * server's `<plugin>:<server>` name. Stored globally under
+ * `settings.mcpServerOverrides` and layered onto the plugin's config at merge
+ * time (see mergePluginMcpServers). Only env/credential fields are allowed —
+ * command/args/url/transport stay owned by the plugin manifest so a plugin
+ * update is never shadowed by a stale user copy.
+ */
+export interface MCPServerOverride {
+    env?: Record<string, string>;
+    envVars?: string[];
+    credentialRef?: string;
+    bearerTokenEnvVar?: string;
+    envHeaders?: Record<string, string>;
 }
 /**
  * Shell-hook configuration entry from settings.json. Each entry binds
@@ -354,6 +639,7 @@ export interface Settings {
         maxTokens: number;
         compactAtRatio: number;
         summarizeAtRatio: number;
+        microcompactFloorRatio: number;
     };
     session: {
         storageDir: string;

package/dist/updater.js

@@ -33,6 +33,7 @@ import { dirname, join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { resolveShellInvocation } from "./runtime/spawn-common.js";
 import { gt } from "./utils/semver.js";
 const execFileAsync = promisify(execFile);
 const PACKAGE_NAME = "@cjhyy/code-shell";
@@ -282,7 +283,7 @@ function launchDetachedInstall(version) {
     try {
         // Avoid `mkdirSync recursive` failures if dir exists.
         try {
-            const fs = require("node:fs");
+            const fs = createRequire(import.meta.url ?? __filename)("node:fs");
             fs.mkdirSync(configDir(), { recursive: true });
             fs.writeFileSync(lockPath, String(process.pid), { encoding: "utf8", flag: "wx" });
         }
@@ -290,7 +291,7 @@ function launchDetachedInstall(version) {
             if (errnoCode(err) === "EEXIST") {
                 // Lock held — check freshness; if stale, take over.
                 try {
-                    const fs = require("node:fs");
+                    const fs = createRequire(import.meta.url ?? __filename)("node:fs");
                     const s = fs.statSync(lockPath);
                     if (Date.now() - s.mtimeMs < LOCK_TIMEOUT_MS)
                         return; // fresh — back off
@@ -309,7 +310,7 @@ function launchDetachedInstall(version) {
     catch {
         return;
     }
-    const fs = require("node:fs");
+    const fs = createRequire(import.meta.url ?? __filename)("node:fs");
     const logFd = fs.openSync(getUpdateLogPath(), "a");
     try {
         fs.writeSync(logFd, `\n[${new Date().toISOString()}] code-shell auto-update: installing ${PACKAGE_NAME}@${version} (pid=${process.pid})\n`);
@@ -318,13 +319,23 @@ function launchDetachedInstall(version) {
         // ignore
     }
     // Wrap install + lock cleanup in a tiny shell so the lock file is removed
-    // even if npm fails. `-c` style runs as a single child, detached from us.
-    const cmd = [
-        `npm install -g ${PACKAGE_NAME}@${shellEscape(version)}`,
-        `; rm -f ${shellEscape(lockPath)}`,
-    ].join(" ");
+    // even if npm fails. Cross-platform: POSIX sequences with `; rm -f`, Windows
+    // cmd.exe with `& del /f /q` (no `sh`/`rm` there). resolveShellInvocation
+    // picks the shell binary + flag (/c vs -c) per platform.
+    const isWin = process.platform === "win32";
+    // cmd.exe doesn't understand POSIX single-quote escaping. version is a semver
+    // from npm (no shell metachars) so it needs no quoting on cmd; the lock path
+    // gets double quotes (cmd-native). POSIX keeps shellEscape on both.
+    const installPkg = isWin
+        ? `npm install -g ${PACKAGE_NAME}@${version}`
+        : `npm install -g ${PACKAGE_NAME}@${shellEscape(version)}`;
+    const cleanup = isWin
+        ? `& del /f /q "${lockPath}"`
+        : `; rm -f ${shellEscape(lockPath)}`;
+    const cmd = `${installPkg} ${cleanup}`;
+    const { file: shellFile, args: shellArgs } = resolveShellInvocation(cmd);
     try {
-        const child = spawn("sh", ["-c", cmd], {
+        const child = spawn(shellFile, shellArgs, {
             detached: true,
             stdio: ["ignore", logFd, logFd],
             cwd: homedir(),

package/dist/utils/envUtils.d.ts

@@ -36,16 +36,7 @@ export declare function getDefaultVertexRegion(): string;
  * Check if bash commands should maintain project working directory.
  */
 export declare function shouldMaintainProjectWorkingDir(): boolean;
-/**
- * Check if running on Homespace (ant-internal cloud environment).
- */
-export declare function isRunningOnHomespace(): boolean;
 /**
  * Get the Vertex AI region for a specific model.
  */
 export declare function getVertexRegionForModel(model: string | undefined): string | undefined;
-/**
- * Stub: Check if running inside a protected namespace.
- * Always returns false in Code Shell (Anthropic-internal feature).
- */
-export declare function isInProtectedNamespace(): boolean;

package/dist/utils/envUtils.js

@@ -3,6 +3,7 @@
  */
 import { homedir } from 'os';
 import { join } from 'path';
+import { VERTEX_REGION_OVERRIDES } from '../data/model-metadata.js';
 // Memoize cache for getClaudeConfigHomeDir
 let _configHomeDirCache = null;
 let _configHomeDirCacheKey = undefined;
@@ -93,27 +94,8 @@ export function getDefaultVertexRegion() {
 export function shouldMaintainProjectWorkingDir() {
     return isEnvTruthy(process.env.CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR);
 }
-/**
- * Check if running on Homespace (ant-internal cloud environment).
- */
-export function isRunningOnHomespace() {
-    return (process.env.USER_TYPE === 'ant' &&
-        isEnvTruthy(process.env.COO_RUNNING_ON_HOMESPACE));
-}
-/**
- * Model prefix → env var for Vertex region overrides.
- */
-const VERTEX_REGION_OVERRIDES = [
-    ['claude-haiku-4-5', 'VERTEX_REGION_CLAUDE_HAIKU_4_5'],
-    ['claude-3-5-haiku', 'VERTEX_REGION_CLAUDE_3_5_HAIKU'],
-    ['claude-3-5-sonnet', 'VERTEX_REGION_CLAUDE_3_5_SONNET'],
-    ['claude-3-7-sonnet', 'VERTEX_REGION_CLAUDE_3_7_SONNET'],
-    ['claude-opus-4-1', 'VERTEX_REGION_CLAUDE_4_1_OPUS'],
-    ['claude-opus-4', 'VERTEX_REGION_CLAUDE_4_0_OPUS'],
-    ['claude-sonnet-4-6', 'VERTEX_REGION_CLAUDE_4_6_SONNET'],
-    ['claude-sonnet-4-5', 'VERTEX_REGION_CLAUDE_4_5_SONNET'],
-    ['claude-sonnet-4', 'VERTEX_REGION_CLAUDE_4_0_SONNET'],
-];
+// VERTEX_REGION_OVERRIDES now lives in data/model-metadata.json (imported above)
+// so adding a model's region env var is a data edit, not a code change.
 /**
  * Get the Vertex AI region for a specific model.
  */
@@ -126,10 +108,3 @@ export function getVertexRegionForModel(model) {
     }
     return getDefaultVertexRegion();
 }
-/**
- * Stub: Check if running inside a protected namespace.
- * Always returns false in Code Shell (Anthropic-internal feature).
- */
-export function isInProtectedNamespace() {
-    return false;
-}

package/dist/utils/exec.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cross-platform executable resolution.
+ *
+ * Node's `child_process.spawn`/`execFile` on Windows do NOT walk PATHEXT for a
+ * bare command name unless `shell:true` — so `execFile("git", …)` finds
+ * `git.exe` but NOT a `git.cmd`/`gh.cmd` shim (common for tools installed via
+ * scoop/npm/chocolatey). On POSIX a bare name in PATH works fine.
+ *
+ * `resolveExecutable` does an explicit PATH × PATHEXT lookup on Windows and
+ * returns the first existing match's absolute path; on POSIX (or when nothing
+ * is found) it returns the command unchanged, so callers can always pass the
+ * result straight to execFile/spawn.
+ */
+/**
+ * The names to probe for `command` on the current platform: the bare name on
+ * POSIX (or when it already has an extension), plus each PATHEXT variant
+ * (command.exe / .cmd / .bat …) on Windows.
+ */
+export declare function commandCandidateNames(command: string, env?: NodeJS.ProcessEnv): string[];
+export declare function resolveExecutable(command: string, env?: NodeJS.ProcessEnv): string;
+/** Test seam: drop the resolution cache. */
+export declare function _clearExecutableCache(): void;
+/**
+ * Find `command` as a real, runnable executable. Unlike {@link resolveExecutable}
+ * (which returns the bare name unchanged when nothing is found, so spawn can
+ * surface its own ENOENT), this returns the absolute path if a binary exists or
+ * `null` if it genuinely cannot be found — works on POSIX too (probes PATH).
+ * Use it to *detect* a missing tool up front (e.g. is git installed?).
+ */
+export declare function findExecutable(command: string, env?: NodeJS.ProcessEnv): string | null;
+/** Set (or clear, with null/"") the user-configured git binary path. */
+export declare function setGitPathOverride(path: string | null | undefined): void;
+/**
+ * The git command to spawn: the user override if set, else `git` resolved
+ * through PATH×PATHEXT. Always returns something spawnable (callers still get
+ * a structured spawn-failure if it's wrong).
+ */
+export declare function resolveGit(env?: NodeJS.ProcessEnv): string;
+/** Is a usable git binary available (override path, or git on PATH)? */
+export declare function isGitAvailable(env?: NodeJS.ProcessEnv): boolean;