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

package/dist/tool-system/builtin/grep.js

@@ -2,9 +2,14 @@
  * Built-in Grep content search tool.
  */
 import { execFile } from "node:child_process";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { promisify } from "node:util";
-import { resolve, sep, isAbsolute } from "node:path";
+import { basename, join, relative, resolve, sep, isAbsolute } from "node:path";
 const execFileAsync = promisify(execFile);
+let execFileForTest = execFileAsync;
+export function _setGrepExecFileForTest(fn) {
+    execFileForTest = fn ?? execFileAsync;
+}
 /**
  * Strip the cwd prefix from each line so results display as relative
  * paths (e.g. "src/ui/App.tsx" instead of an absolute path). Lines that
@@ -76,10 +81,16 @@ export async function grepTool(args, ctx) {
         catch (grepErr) {
             if (isNoMatchExit(grepErr))
                 return "No matches found.";
+            if (isCommandNotFound(rgErr) || isCommandNotFound(grepErr)) {
+                return await runNodeGrep(pattern, searchPath, fileGlob, context, maxResults, outputMode, caseInsensitive);
+            }
             return `Error in search: ${grepErr.message}`;
         }
     }
 }
+function isCommandNotFound(err) {
+    return err?.code === "ENOENT";
+}
 async function runRipgrep(pattern, path, fileGlob, context, maxResults, outputMode, caseInsensitive) {
     const args = ["--color=never"];
     if (caseInsensitive)
@@ -102,7 +113,7 @@ async function runRipgrep(pattern, path, fileGlob, context, maxResults, outputMo
     // Ignore common non-source dirs
     args.push("--glob", "!node_modules", "--glob", "!.git", "--glob", "!dist", "--glob", "!coverage");
     args.push("--", pattern, path);
-    const { stdout } = await execFileAsync("rg", args, {
+    const { stdout } = await execFileForTest("rg", args, {
         maxBuffer: 10 * 1024 * 1024,
         timeout: 30_000,
     });
@@ -139,7 +150,7 @@ async function runGrep(pattern, path, fileGlob, context, maxResults, outputMode,
     args.push("-E", pattern);
     args.push("--exclude-dir=node_modules", "--exclude-dir=.git", "--exclude-dir=dist");
     args.push(path);
-    const { stdout } = await execFileAsync("grep", args, {
+    const { stdout } = await execFileForTest("grep", args, {
         maxBuffer: 10 * 1024 * 1024,
         timeout: 30_000,
     });
@@ -152,3 +163,89 @@ async function runGrep(pattern, path, fileGlob, context, maxResults, outputMode,
     }
     return result;
 }
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "coverage"]);
+async function runNodeGrep(pattern, path, fileGlob, context, maxResults, outputMode, caseInsensitive) {
+    let regex;
+    try {
+        regex = new RegExp(pattern, caseInsensitive ? "i" : "");
+    }
+    catch (err) {
+        return `Error in search: ${err.message}`;
+    }
+    const matches = [];
+    await walkTextFiles(path, fileGlob, async (file) => {
+        if (matches.length >= maxResults)
+            return;
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch {
+            return;
+        }
+        const lines = text.split(/\r?\n/);
+        const matchingLines = [];
+        for (let i = 0; i < lines.length; i++) {
+            regex.lastIndex = 0;
+            if (regex.test(lines[i]))
+                matchingLines.push(i);
+        }
+        if (matchingLines.length === 0)
+            return;
+        const rel = relative(path, file) || basename(file);
+        if (outputMode === "files_with_matches") {
+            matches.push(rel);
+        }
+        else if (outputMode === "count") {
+            matches.push(`${rel}:${matchingLines.length}`);
+        }
+        else {
+            const emitted = new Set();
+            for (const lineIndex of matchingLines) {
+                const start = Math.max(0, lineIndex - context);
+                const end = Math.min(lines.length - 1, lineIndex + context);
+                for (let i = start; i <= end; i++) {
+                    if (emitted.has(i))
+                        continue;
+                    emitted.add(i);
+                    matches.push(`${rel}:${i + 1}:${lines[i]}`);
+                    if (matches.length >= maxResults)
+                        return;
+                }
+            }
+        }
+    });
+    if (matches.length === 0)
+        return "No matches found.";
+    if (matches.length > 200)
+        return matches.slice(0, 200).join("\n") + `\n\n... ${matches.length - 200} more results`;
+    return matches.join("\n");
+}
+async function walkTextFiles(root, fileGlob, visit) {
+    const info = await stat(root).catch(() => null);
+    if (!info)
+        return;
+    if (info.isFile()) {
+        if (!fileGlob || matchesSimpleGlob(basename(root), fileGlob))
+            await visit(root);
+        return;
+    }
+    if (!info.isDirectory())
+        return;
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRS.has(entry.name))
+                continue;
+            await walkTextFiles(join(root, entry.name), fileGlob, visit);
+        }
+        else if (entry.isFile()) {
+            if (!fileGlob || matchesSimpleGlob(entry.name, fileGlob))
+                await visit(join(root, entry.name));
+        }
+    }
+}
+function matchesSimpleGlob(name, glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`).test(name);
+}

package/dist/tool-system/builtin/index.d.ts

@@ -2,6 +2,7 @@
  * Built-in tool registration.
  */
 import type { RegisteredTool } from "../../types.js";
+import type { ToolVisibilityContext } from "../context.js";
 /**
  * Tool executor signature.
  *
@@ -27,6 +28,7 @@ export type BuiltinToolResult = string | {
     sandbox: import("../../types.js").ToolResult["sandbox"];
 };
 export type BuiltinToolFn = (args: Record<string, unknown>, ctx?: import("../context.js").ToolContext) => Promise<BuiltinToolResult>;
+export type BuiltinToolGuard = (ctx: ToolVisibilityContext) => boolean;
 export interface BuiltinTool {
     definition: RegisteredTool;
     execute: BuiltinToolFn;
@@ -38,6 +40,6 @@ export declare const BUILTIN_TOOLS: BuiltinTool[];
  * engine.ts toolDefs assembly). Tools NOT listed here are always visible.
  * Keyed by the tool's `name` (must match the toolDef name).
  */
-export declare const BUILTIN_TOOL_GUARDS: Map<string, (cwd: string) => boolean>;
+export declare const BUILTIN_TOOL_GUARDS: Map<string, BuiltinToolGuard>;
 /** UseCredential is available when the cwd's CredentialStore has ≥1 credential. */
 export declare function isUseCredentialAvailable(cwd: string): boolean;

package/dist/tool-system/builtin/index.js

@@ -711,17 +711,17 @@ export const BUILTIN_TOOLS = [
  * Keyed by the tool's `name` (must match the toolDef name).
  */
 export const BUILTIN_TOOL_GUARDS = new Map([
-    [webSearchToolDef.name, isWebSearchAvailable],
-    [generateImageToolDef.name, isGenerateImageAvailable],
-    [generateVideoToolDef.name, isGenerateVideoAvailable],
+    [webSearchToolDef.name, (ctx) => isWebSearchAvailable(ctx.cwd)],
+    [generateImageToolDef.name, (ctx) => isGenerateImageAvailable(ctx.cwd)],
+    [generateVideoToolDef.name, (ctx) => isGenerateVideoAvailable(ctx.cwd)],
     // UseCredential is hidden until at least one credential exists — keeps it out
     // of the tool list (and the context) for the common no-credentials case,
     // matching the spec's "quiet when empty" intent (true ToolSearch-deferral for
     // builtins isn't wired in the engine).
-    [useCredentialToolDef.name, isUseCredentialAvailable],
+    [useCredentialToolDef.name, (ctx) => isUseCredentialAvailable(ctx.cwd)],
     // InjectCredential hidden until ≥1 cookie credential exists (browser injection
     // is cookie-only). Also degrades at call time if no browser bridge is wired.
-    [injectCredentialToolDef.name, isInjectCredentialAvailable],
+    [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd)],
 ]);
 /** UseCredential is available when the cwd's CredentialStore has ≥1 credential. */
 export function isUseCredentialAvailable(cwd) {

package/dist/tool-system/builtin/powershell.js

@@ -8,7 +8,10 @@
 import { safeSpawn } from "../../runtime/safe-spawn.js";
 export const powershellToolDef = {
     name: "PowerShell",
-    description: "Execute PowerShell commands. Available on Windows and cross-platform where PowerShell Core is installed.",
+    description: "Execute PowerShell commands. Use only when the user explicitly asks for PowerShell " +
+        "or the task requires PowerShell-specific cmdlets, Windows APIs, registry access, " +
+        "or .ps1 behavior. Do NOT use for ordinary file, git, package-manager, test, " +
+        "or POSIX-style shell commands; use Bash for those.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tool-system/builtin/sleep.js

@@ -6,6 +6,11 @@ export const sleepToolDef = {
     description: "Pause execution for a brief, deterministic wait (e.g. letting a just-started service settle for a few seconds). " +
         "Do NOT use Sleep to poll for or wait on background work (background shells, async sub-agents, video generation): " +
         "the system wakes you automatically when that work completes — just end your turn instead of looping Sleep. " +
+        "If you want a safety net in case a background task hangs and never signals completion, do NOT loop Sleep either — " +
+        "instead end your turn and schedule a one-shot self-wakeup with CronCreate " +
+        "({ schedule: '5m', once: true, continueInSession: true, permissionLevel: 'read-only', " +
+        "prompt: 'check whether <that task> finished; if still running, wait again' }). " +
+        "That returns control to you at the interval without burning a turn spinning. " +
         "Maximum duration is 300 seconds (5 minutes).",
     inputSchema: {
         type: "object",

package/dist/tool-system/context.d.ts

@@ -169,6 +169,10 @@ export interface SubAgentSpawner {
  * Optional fields are filled in by Engine.run(); some headless paths may
  * leave them undefined (e.g. running without UI → no askUser).
  */
+export interface ToolVisibilityContext {
+    cwd: string;
+    hasGoal: boolean;
+}
 export interface ToolContext {
     /** Active working directory for this Engine. */
     cwd: string;
@@ -290,6 +294,12 @@ export interface ToolContext {
      * sub-agents and no-cwd contexts (same as readBuiltinOverride).
      */
     disabledBuiltins?: Set<string>;
+    /**
+     * Per-turn context used by builtin availability guards. Engine.run() uses the
+     * same object to hide tools from the model; ToolExecutor reuses it to reject
+     * direct calls to tools that are not available in the current runtime state.
+     */
+    toolVisibility?: ToolVisibilityContext;
     /**
      * MCP servers THIS session's merged config enables (keys of
      * config.mcpServers, enabled!==false). The pool + registry are

package/dist/tool-system/executor.js

@@ -11,6 +11,9 @@ import { validateToolArgs } from "./validation.js";
 import { PLAN_MODE_ALLOWED_TOOLS } from "./plan-mode-allowlist.js";
 import { enforcePathPolicyWithApproval } from "./path-policy.js";
 import { parsePatch } from "./builtin/apply-patch/parser.js";
+import { BUILTIN_TOOL_GUARDS } from "./builtin/index.js";
+import { COMPLETE_GOAL_TOOL_NAME } from "./builtin/complete-goal.js";
+import { CANCEL_GOAL_TOOL_NAME } from "./builtin/cancel-goal.js";
 // A1 hardening: hooks must never promote a non-`allow` classifier
 // decision to `allow`. They may otherwise adjust the decision freely
 // (e.g. tighten `allow` to `deny`/`ask`, or relax `deny` to `ask` to
@@ -119,6 +122,24 @@ export class ToolExecutor {
                 isError: true,
             };
         }
+        if ((call.toolName === COMPLETE_GOAL_TOOL_NAME || call.toolName === CANCEL_GOAL_TOOL_NAME) &&
+            this.toolCtx?.toolVisibility?.hasGoal !== true) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool ${call.toolName} is only available while an active goal is present. Do NOT retry this tool call unless a goal is active.`,
+                isError: true,
+            };
+        }
+        const visibilityGuard = BUILTIN_TOOL_GUARDS.get(call.toolName);
+        if (visibilityGuard && this.toolCtx?.toolVisibility && !visibilityGuard(this.toolCtx.toolVisibility)) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool ${call.toolName} is not available in the current session context. Do NOT retry this tool call unless the relevant context changes.`,
+                isError: true,
+            };
+        }
         // Same gate for MCP tools: the registry is worker-shared, so it can hold
         // tools from servers OTHER sessions enabled. Visibility filtering hides
         // them from this session's tool list; this rejects a direct call anyway.
@@ -274,7 +295,7 @@ export class ToolExecutor {
         // the hook and the user together have decided.
         if (hookResult.decision === "ask") {
             const reason = hookResult.messages?.join("\n") ?? undefined;
-            const approved = await this.permission.handleAsk(call.toolName, call.args, reason);
+            const approved = await this.permission.handleAsk(call.toolName, call.args, reason, { sessionId: this.toolCtx?.sessionId });
             if (!approved) {
                 return {
                     id: call.id,
@@ -347,7 +368,9 @@ export class ToolExecutor {
             }
             if (decision === "ask") {
                 const reason = permHook.messages?.join("\n");
-                const approved = await this.permission.handleAsk(call.toolName, call.args, reason);
+                const approved = await this.permission.handleAsk(call.toolName, call.args, reason, {
+                    sessionId: this.toolCtx?.sessionId,
+                });
                 if (!approved) {
                     return {
                         id: call.id,

package/dist/tool-system/mcp-manager.js

@@ -11,6 +11,7 @@ import { CredentialStore } from "../credentials/index.js";
 import { ENV_ALLOWLIST } from "../runtime/spawn-common.js";
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { diagnoseMcpStdioMissingCommand, previewPath } from "./mcp-stdio-diagnostics.js";
 /**
  * Read a required secret from `process.env` by NAME (Codex-style env-secret
  * handling — the value is never persisted in MCP config). A referenced env var
@@ -393,6 +394,22 @@ export class MCPManager {
             catch {
                 // ignore cleanup errors
             }
+            if (transportType === "stdio" && config.command) {
+                const diagnostic = await diagnoseMcpStdioMissingCommand(config.command, err);
+                if (diagnostic) {
+                    logger.warn("mcp.stdio_command_missing", {
+                        server: name,
+                        command: config.command,
+                        foundPaths: diagnostic.foundPaths,
+                        path: previewPath(),
+                        message: diagnostic.message,
+                    });
+                    const original = err instanceof Error ? err.message : String(err);
+                    const enhanced = new Error(`${original}\n${diagnostic.message}`);
+                    enhanced.cause = err;
+                    throw enhanced;
+                }
+            }
             throw err;
         }
         finally {

package/dist/tool-system/mcp-stdio-diagnostics.d.ts

@@ -0,0 +1,9 @@
+export declare function isBareCommand(command: string): boolean;
+export declare function isMissingCommandError(error: unknown): boolean;
+export declare function probeCommonExecutableLocations(command: string, env?: NodeJS.ProcessEnv): Promise<string[]>;
+export declare function classifyMcpStdioMissingCommand(command: string, foundPaths: readonly string[]): string;
+export declare function diagnoseMcpStdioMissingCommand(command: string, error: unknown, env?: NodeJS.ProcessEnv): Promise<{
+    message: string;
+    foundPaths: string[];
+} | null>;
+export declare function previewPath(env?: NodeJS.ProcessEnv): string;

package/dist/tool-system/mcp-stdio-diagnostics.js

@@ -0,0 +1,93 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { delimiter, isAbsolute, join } from "node:path";
+const COMMON_POSIX_BIN_DIRS = [
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/home/linuxbrew/.linuxbrew/bin",
+    "/usr/bin",
+    "/bin",
+];
+function unique(entries) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of entries) {
+        const trimmed = entry.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
+function commonExecutableDirs(env = process.env) {
+    const home = env.HOME?.trim();
+    return unique([
+        ...COMMON_POSIX_BIN_DIRS,
+        ...(home
+            ? [join(home, ".bun", "bin"), join(home, ".local", "bin"), join(home, ".npm-global", "bin")]
+            : []),
+    ]);
+}
+export function isBareCommand(command) {
+    const trimmed = command.trim();
+    return !!trimmed && !trimmed.includes("/") && !trimmed.includes("\\") && !isAbsolute(trimmed);
+}
+export function isMissingCommandError(error) {
+    const err = error;
+    const message = typeof err.message === "string" ? err.message : String(error);
+    return err.code === "ENOENT" || /\bENOENT\b/i.test(message) || /command not found/i.test(message);
+}
+async function isExecutable(filePath) {
+    try {
+        await access(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function probeCommonExecutableLocations(command, env = process.env) {
+    if (!isBareCommand(command) || process.platform === "win32")
+        return [];
+    const found = [];
+    for (const dir of commonExecutableDirs(env)) {
+        const candidate = join(dir, command);
+        if (await isExecutable(candidate))
+            found.push(candidate);
+    }
+    return found;
+}
+function installGuidance(command) {
+    if (command === "node" || command === "npx")
+        return "Please install Node.js and restart CodeShell.";
+    if (command === "bun" || command === "bunx")
+        return "Please install Bun and restart CodeShell.";
+    return `Please install "${command}" and restart CodeShell.`;
+}
+export function classifyMcpStdioMissingCommand(command, foundPaths) {
+    const trimmed = command.trim();
+    if (foundPaths.length > 0) {
+        return [
+            `MCP stdio command "${trimmed}" failed to start: detected ${trimmed} at ${foundPaths[0]},`,
+            "but that directory was not available on PATH.",
+            "Login-shell PATH injection may have failed; restart CodeShell or configure this MCP command as an absolute path.",
+        ].join(" ");
+    }
+    return [
+        `MCP stdio command "${trimmed}" failed to start: ${trimmed} was not found on PATH or in common install locations.`,
+        installGuidance(trimmed),
+    ].join(" ");
+}
+export async function diagnoseMcpStdioMissingCommand(command, error, env = process.env) {
+    if (!isBareCommand(command) || !isMissingCommandError(error))
+        return null;
+    const foundPaths = await probeCommonExecutableLocations(command, env);
+    return {
+        message: classifyMcpStdioMissingCommand(command, foundPaths),
+        foundPaths,
+    };
+}
+export function previewPath(env = process.env) {
+    return (env.PATH ?? "").split(delimiter).filter(Boolean).join(delimiter);
+}

package/dist/tool-system/permission.d.ts

@@ -130,7 +130,9 @@ export declare class PermissionClassifier {
     reconfigure(mode: PermissionMode, approvalBackend: ApprovalBackend, rules?: PermissionRule[]): void;
     getMode(): PermissionMode;
     classify(toolName: string, args: Record<string, unknown>): PermissionDecision;
-    handleAsk(toolName: string, args: Record<string, unknown>, reason?: string): Promise<boolean>;
+    handleAsk(toolName: string, args: Record<string, unknown>, reason?: string, opts?: {
+        sessionId?: string;
+    }): Promise<boolean>;
     /** Get denial warning message if the model keeps getting denied. */
     getDenialWarning(toolName: string): string | undefined;
     private matchesRule;

package/dist/tool-system/permission.js

@@ -861,7 +861,7 @@ export class PermissionClassifier {
                 return "ask";
         }
     }
-    async handleAsk(toolName, args, reason) {
+    async handleAsk(toolName, args, reason, opts) {
         if (this.defaultMode === "dontAsk") {
             this.log.info("permission.auto_deny", {
                 cat: "permission",
@@ -900,6 +900,7 @@ export class PermissionClassifier {
                 ? `${baseDescription}\n\nReason (from pre_tool_use hook): ${reason}`
                 : baseDescription;
             result = await this.approvalBackend.requestApproval({
+                ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
                 toolName,
                 args,
                 description,

package/dist/tool-system/sandbox/off.js

@@ -1,8 +1,14 @@
+import { resolveShellInvocation } from "../../runtime/spawn-common.js";
 export function createOffBackend() {
     return {
         name: "off",
         wrap(command, opts) {
-            return { file: opts.shell, args: ["-c", command] };
+            // "off" = no sandboxing; just run the command through the shell. Delegate
+            // to resolveShellInvocation for the PLATFORM-CORRECT flag instead of a
+            // hardcoded POSIX `-c`: on Windows cmd.exe needs `/c` (a bare `-c` is taken
+            // as a filename and cmd hangs in interactive mode until timeout — the
+            // "Bash never runs on Windows" beta regression). POSIX still gets `-c`.
+            return resolveShellInvocation(command, opts.shell);
         },
     };
 }

package/dist/types.d.ts

@@ -145,7 +145,19 @@ export interface SessionState {
     startedAt: number;
     model: string;
     provider: string;
+    /**
+     * Legacy/model-scoped usage summary. Some flows reset this accounting window
+     * (for example model switches), so it must not drive whole-session metrics.
+     */
     tokenUsage: TokenUsage;
+    /**
+     * Monotonic prompt-cache counters for the whole session. These only increase
+     * from session start and are separate from the resettable tokenUsage window.
+     * Optional on legacy state.json files; SessionManager normalizes them on load.
+     */
+    cumulativePromptTokens?: number;
+    cumulativeCacheReadTokens?: number;
+    cumulativeCacheCreationTokens?: number;
     turnCount: number;
     /**
      * Conversation-turn counter where ONE user message = one turn (incremented in
@@ -229,6 +241,8 @@ export interface PermissionRule {
     reason?: string;
 }
 export interface ApprovalRequest {
+    /** Originating engine session. Hosts use this only to route the prompt UI. */
+    sessionId?: string;
     toolName: string;
     args: Record<string, unknown>;
     description: string;
@@ -389,7 +403,7 @@ export type StreamEvent = {
     summary: string;
 } | {
     type: "context_compact";
-    strategy: "micro" | "summary" | "window" | "snip" | "emergency";
+    strategy: "micro" | "summary" | "window" | "snip" | "emergency" | "compacted";
     before: number;
     after: number;
     agentId?: string;
@@ -405,6 +419,24 @@ export type StreamEvent = {
      */
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
+    /**
+     * Prompt-cache metrics for the current turn only. These are reset at the
+     * start of each turn-loop iteration and sum every LLM response in that
+     * turn, including max-token continuations.
+     */
+    singleTurnPromptTokens?: number;
+    singleTurnCacheReadTokens?: number;
+    singleTurnCacheCreationTokens?: number;
+    singleTurnCacheHitRate?: number;
+    /**
+     * Whole-session monotonic prompt-cache counters/rate. Unlike the legacy
+     * session* fields below, these are not derived from the resettable
+     * tokenUsage accounting window.
+     */
+    cumulativePromptTokens?: number;
+    cumulativeCacheReadTokens?: number;
+    cumulativeCacheCreationTokens?: number;
+    cumulativeCacheHitRate?: number;
     /**
      * SESSION-CUMULATIVE cache counts (sum across every LLM response this
      * session, across runs and turns), emitted from the engine's turn
@@ -464,6 +496,8 @@ export interface LLMConfig {
     apiKey?: string;
     baseUrl?: string;
     maxTokens?: number;
+    /** Per-model context window size used by hosts to seed Engine.maxContextTokens. */
+    maxContextTokens?: number;
     /**
      * 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

package/dist/utils/exec.d.ts

@@ -38,3 +38,11 @@ export declare function setGitPathOverride(path: string | null | undefined): voi
 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;
+/**
+ * The RESOLVED absolute path of the usable git binary (override path, or git
+ * found on PATH), or null if none. Lets the settings UI auto-fill the git.path
+ * field after a successful detection instead of only reporting available:true
+ * with no path (the "检测到了但没回填 path" complaint). Returns the real path so
+ * the user can see/keep exactly what was found.
+ */
+export declare function resolveGitPath(env?: NodeJS.ProcessEnv): string | null;

package/dist/utils/exec.js

@@ -120,6 +120,16 @@ export function resolveGit(env = process.env) {
 export function isGitAvailable(env = process.env) {
     return findExecutable(gitPathOverride ?? "git", env) !== null;
 }
+/**
+ * The RESOLVED absolute path of the usable git binary (override path, or git
+ * found on PATH), or null if none. Lets the settings UI auto-fill the git.path
+ * field after a successful detection instead of only reporting available:true
+ * with no path (the "检测到了但没回填 path" complaint). Returns the real path so
+ * the user can see/keep exactly what was found.
+ */
+export function resolveGitPath(env = process.env) {
+    return findExecutable(gitPathOverride ?? "git", env);
+}
 function resolveExecutableUncached(trimmed, env) {
     const command = trimmed;
     // Already a path (absolute or relative with a separator): resolve extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.6.0-rc.1",
+  "version": "0.6.0-rc.11",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",