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

package/dist/llm/strip-vision.d.ts

@@ -0,0 +1,32 @@
+/**
+ * History-image stripping for non-vision models.
+ *
+ * Why this exists: the vision gate in `Engine.run` only rejects *new* image
+ * attachments on the current turn. But a conversation can accumulate image
+ * content blocks while a vision-capable model is active, then the user
+ * switches to a non-vision model (e.g. DeepSeek) mid-session. Those
+ * *historical* image blocks are still in the transcript and get re-serialized
+ * on every subsequent request — OpenAI-compat backends 400 with
+ * `unknown variant 'image_url', expected 'text'`, which then falls back out
+ * of streaming and degrades the turn.
+ *
+ * Fix: when the active model has `supportsVision: false`, replace each
+ * message's image blocks with a single text placeholder before the request
+ * is built. The transcript/store is untouched — only the outgoing copy is
+ * sanitized — so switching back to a vision model still sees the images.
+ *
+ * Pure function, no I/O. Tested in `strip-vision.test.ts`.
+ */
+import type { Message } from "../types.js";
+/** Text we substitute for an elided image block. Surfaced to the model so it
+ *  knows an image *was* here (vs silently vanishing the context). */
+export declare const VISION_PLACEHOLDER = "[\u56FE\u7247\u5DF2\u7701\u7565:\u5F53\u524D\u6A21\u578B\u4E0D\u652F\u6301\u89C6\u89C9\u8F93\u5165]";
+/**
+ * Return a copy of `messages` with image content blocks replaced by a text
+ * placeholder, but only when `supportsVision` is false.
+ *
+ * Identity-preserving: when vision is supported, or no message carries an
+ * image, the original array (and untouched message objects) are returned as-is
+ * so callers pay nothing on the common path.
+ */
+export declare function stripVisionFromHistory(messages: Message[], supportsVision: boolean): Message[];

package/dist/llm/strip-vision.js

@@ -0,0 +1,94 @@
+/**
+ * History-image stripping for non-vision models.
+ *
+ * Why this exists: the vision gate in `Engine.run` only rejects *new* image
+ * attachments on the current turn. But a conversation can accumulate image
+ * content blocks while a vision-capable model is active, then the user
+ * switches to a non-vision model (e.g. DeepSeek) mid-session. Those
+ * *historical* image blocks are still in the transcript and get re-serialized
+ * on every subsequent request — OpenAI-compat backends 400 with
+ * `unknown variant 'image_url', expected 'text'`, which then falls back out
+ * of streaming and degrades the turn.
+ *
+ * Fix: when the active model has `supportsVision: false`, replace each
+ * message's image blocks with a single text placeholder before the request
+ * is built. The transcript/store is untouched — only the outgoing copy is
+ * sanitized — so switching back to a vision model still sees the images.
+ *
+ * Pure function, no I/O. Tested in `strip-vision.test.ts`.
+ */
+/** Text we substitute for an elided image block. Surfaced to the model so it
+ *  knows an image *was* here (vs silently vanishing the context). */
+export const VISION_PLACEHOLDER = "[图片已省略:当前模型不支持视觉输入]";
+/**
+ * Return a copy of `messages` with image content blocks replaced by a text
+ * placeholder, but only when `supportsVision` is false.
+ *
+ * Identity-preserving: when vision is supported, or no message carries an
+ * image, the original array (and untouched message objects) are returned as-is
+ * so callers pay nothing on the common path.
+ */
+export function stripVisionFromHistory(messages, supportsVision) {
+    if (supportsVision)
+        return messages;
+    let changed = false;
+    const out = messages.map((msg) => {
+        if (typeof msg.content === "string")
+            return msg;
+        // Need to process if there's a top-level image, OR a tool_result whose
+        // own content array carries a nested image (view_image-produced screenshots
+        // live in `tool_result.content: ContentBlock[]`).
+        if (!msg.content.some(needsStrip))
+            return msg;
+        changed = true;
+        const rebuilt = [];
+        let placeholderInserted = false;
+        for (const block of msg.content) {
+            if (block.type === "image") {
+                // Collapse runs of images into a single placeholder per message —
+                // five screenshots don't need five identical notes.
+                if (!placeholderInserted) {
+                    rebuilt.push({ type: "text", text: VISION_PLACEHOLDER });
+                    placeholderInserted = true;
+                }
+                continue;
+            }
+            if (block.type === "tool_result" &&
+                Array.isArray(block.content) &&
+                block.content.some((b) => b.type === "image")) {
+                rebuilt.push({ ...block, content: stripImageBlocks(block.content) });
+                continue;
+            }
+            rebuilt.push(block);
+        }
+        return { ...msg, content: rebuilt };
+    });
+    return changed ? out : messages;
+}
+/** True if this block holds an image we must elide — either it *is* an image,
+ *  or it's a tool_result whose nested content array contains one. */
+function needsStrip(block) {
+    if (block.type === "image")
+        return true;
+    return (block.type === "tool_result" &&
+        Array.isArray(block.content) &&
+        block.content.some((b) => b.type === "image"));
+}
+/** Replace image blocks in a ContentBlock[] with a single text placeholder
+ *  (consecutive/multiple images collapse to one), preserving other blocks.
+ *  Used for both the message top level and nested tool_result.content. */
+function stripImageBlocks(blocks) {
+    const rebuilt = [];
+    let placeholderInserted = false;
+    for (const block of blocks) {
+        if (block.type === "image") {
+            if (!placeholderInserted) {
+                rebuilt.push({ type: "text", text: VISION_PLACEHOLDER });
+                placeholderInserted = true;
+            }
+            continue;
+        }
+        rebuilt.push(block);
+    }
+    return rebuilt;
+}

package/dist/llm/types.d.ts

@@ -20,13 +20,12 @@ export interface CreateMessageOptions {
      */
     recordUsage?: boolean;
     /**
-     * DeepSeek V4 thinking-mode switch. "enabled" is the endpoint default;
-     * "disabled" turns reasoning off (faster, cheaper, no `reasoning_content`
-     * on the reply). Ignored by every provider except DeepSeek V4 — the OpenAI
-     * SDK forwards unknown top-level fields verbatim, so it's harmless on
-     * other compatible endpoints.
+     * Reasoning/thinking setting for this call. Overrides LLMConfig.reasoning.
+     * Rich shape ({mode:"off"|"on"} | {mode:"effort",effort} |
+     * {mode:"budget",budgetTokens}) — translated to the per-vendor wire form by
+     * the client's capability layer.
      */
-    thinking?: "enabled" | "disabled";
+    reasoning?: import("./reasoning-setting.js").ReasoningSetting;
 }
 export interface LLMUsageTracker {
     records: TokenUsage[];

package/dist/logging/logger.js

@@ -25,6 +25,7 @@ import { appendFileSync, mkdirSync, existsSync, readdirSync, unlinkSync, readFil
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { redactSecrets } from "./sanitize-messages.js";
 const LEVEL_ORDER = {
     debug: 0,
     info: 1,
@@ -246,7 +247,14 @@ class Logger {
     recordError(msg, data) {
         if (inMemoryErrors.length >= MAX_IN_MEMORY_ERRORS)
             inMemoryErrors.shift();
-        inMemoryErrors.push({ msg, t: new Date().toISOString(), data });
+        // Scrub secrets out of msg + data before parking the entry in the in-
+        // memory ring. The ring is exposed via diagnostics endpoints, so
+        // anything that survives here is reachable by protocol clients.
+        inMemoryErrors.push({
+            msg: redactSecrets(msg),
+            t: new Date().toISOString(),
+            data: data ? redactSecrets(data) : undefined,
+        });
     }
     write(level, msg, data) {
         if (!this.enabled)
@@ -262,7 +270,13 @@ class Logger {
                 return;
         }
         const t = new Date().toISOString();
-        const entry = { t, l: level, msg, ...this.context };
+        // Scrub msg + data before the entry is built. msg is a plain string so
+        // only bearer-tokens / URL secret query params can hide there; data is
+        // arbitrary so it gets the full recursive walk. Done at the boundary so
+        // every level/category sink shares the same redaction rules.
+        const safeMsg = redactSecrets(msg);
+        const safeData = data ? redactSecrets(data) : undefined;
+        const entry = { t, l: level, msg: safeMsg, ...this.context };
         if (cat && !entry.cat)
             entry.cat = cat;
         // Stamp the current process-wide session id unless this logger's
@@ -270,8 +284,8 @@ class Logger {
         // children created before Engine.run() still pick up the real sid.
         if (entry.sid === undefined)
             entry.sid = getCurrentSid();
-        if (data)
-            entry.d = data;
+        if (safeData)
+            entry.d = safeData;
         const line = JSON.stringify(entry) + "\n";
         if (this.stderrEcho) {
             process.stderr.write(line);

package/dist/logging/sanitize-messages.d.ts

@@ -32,6 +32,16 @@ export declare function sanitizeContent(content: Message["content"]): Message["c
  * path for the overwhelmingly common pure-text case).
  */
 export declare function sanitizeMessages(messages: readonly Message[]): Message[];
+/**
+ * Recursively walk a value and return a *new* value with secret-looking
+ * fields replaced by "[redacted]". Used by the logger (so anything ending up
+ * in `entry.d` is scrubbed) and by diagnostics / in-memory error capture.
+ *
+ * Pure / no I/O. Does not mutate the input — important because the same
+ * object may also be on its way to a transcript or UI stream where the
+ * unredacted form is correct.
+ */
+export declare function redactSecrets<T>(value: T, depth?: number): T;
 /**
  * Sanitize a free-form task string before logging.
  *

package/dist/logging/sanitize-messages.js

@@ -129,6 +129,96 @@ export function sanitizeMessages(messages) {
     }
     return touched ? out : messages;
 }
+// ─────────────────────────────────────────────────────────────────────
+// Secret redaction
+// ─────────────────────────────────────────────────────────────────────
+//
+// Beyond image payloads, log/diagnostics entries can carry API keys,
+// authorization headers, provider tokens, and similar secrets via
+// `data` blobs (settings dumps, provider configs, error responses, …).
+// These walkers redact secrets *in place on a deep clone* so the caller
+// can still log "useful shape, scrubbed values".
+const SECRET_KEY_RE = /(^|[._-])(api[_-]?key|authorization|x[_-]api[_-]key|bearer[_-]?token|access[_-]?token|refresh[_-]?token|session[_-]?token|token|secret|password|client[_-]?secret|cookie)($|[._-])/i;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._\-+/=~]{8,}/g;
+// URL query parameters that look like credentials. Conservative — only
+// trigger on a small named set so a normal `?id=…&q=…` URL passes through.
+const URL_SECRET_QS_RE = /([?&](?:key|api_key|apikey|access_token|token|auth|sig|signature)=)[^&#\s]+/gi;
+const REDACTED = "[redacted]";
+const MAX_DEPTH = 10;
+function isSecretKey(key) {
+    return SECRET_KEY_RE.test(key);
+}
+/** Scrub bare `Bearer <token>` and credential-looking URL query params from a string. */
+function redactSecretsInString(s) {
+    let out = s;
+    if (BEARER_RE.test(out))
+        out = out.replace(BEARER_RE, "Bearer [redacted]");
+    if (URL_SECRET_QS_RE.test(out))
+        out = out.replace(URL_SECRET_QS_RE, "$1[redacted]");
+    return out;
+}
+/**
+ * Recursively walk a value and return a *new* value with secret-looking
+ * fields replaced by "[redacted]". Used by the logger (so anything ending up
+ * in `entry.d` is scrubbed) and by diagnostics / in-memory error capture.
+ *
+ * Pure / no I/O. Does not mutate the input — important because the same
+ * object may also be on its way to a transcript or UI stream where the
+ * unredacted form is correct.
+ */
+export function redactSecrets(value, depth = 0) {
+    if (value === null || value === undefined)
+        return value;
+    if (depth > MAX_DEPTH)
+        return value;
+    const t = typeof value;
+    if (t === "string")
+        return redactSecretsInString(value);
+    if (t === "number" || t === "boolean" || t === "bigint" || t === "symbol")
+        return value;
+    if (t === "function")
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((v) => redactSecrets(v, depth + 1));
+    }
+    // Error objects: preserve name/message/stack shape but redact within.
+    if (value instanceof Error) {
+        const clone = {
+            name: value.name,
+            message: redactSecretsInString(value.message),
+            ...(value.stack ? { stack: redactSecretsInString(value.stack) } : {}),
+        };
+        // Some libraries attach extra properties (`.response`, `.config`, …) —
+        // walk them as well.
+        for (const key of Object.keys(value)) {
+            if (key === "name" || key === "message" || key === "stack")
+                continue;
+            const v = value[key];
+            clone[key] = isSecretKey(key) ? REDACTED : redactSecrets(v, depth + 1);
+        }
+        return clone;
+    }
+    if (t === "object") {
+        const obj = value;
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (isSecretKey(k)) {
+                // Preserve presence (null/undefined stay as-is so consumers can
+                // still distinguish "key present" vs "key absent"; non-empty values
+                // collapse to [redacted]).
+                if (v === null || v === undefined || v === "")
+                    out[k] = v;
+                else
+                    out[k] = REDACTED;
+            }
+            else {
+                out[k] = redactSecrets(v, depth + 1);
+            }
+        }
+        return out;
+    }
+    return value;
+}
 /**
  * Sanitize a free-form task string before logging.
  *

package/dist/lsp/client.js

@@ -10,7 +10,12 @@ export class LSPClient extends EventEmitter {
     process;
     nextId = 1;
     pending = new Map();
-    buffer = "";
+    // The LSP framing uses byte-counted Content-Length, so we buffer bytes,
+    // not characters. Joining chunks as strings (`data.toString()` + string
+    // concat) can split a multibyte UTF-8 codepoint across chunks and de-
+    // synchronize against Content-Length. Stay in Buffer-land until we've
+    // sliced out exactly the right body length.
+    buffer = Buffer.alloc(0);
     contentLength = -1;
     initialized = false;
     constructor(command, args = [], cwd) {
@@ -24,7 +29,7 @@ export class LSPClient extends EventEmitter {
             cwd: this.cwd,
             stdio: ["pipe", "pipe", "pipe"],
         });
-        this.process.stdout?.on("data", (data) => this.handleData(data.toString()));
+        this.process.stdout?.on("data", (data) => this.handleData(data));
         this.process.stderr?.on("data", (_data) => {
             // LSP servers often log to stderr — ignore
         });
@@ -116,26 +121,41 @@ export class LSPClient extends EventEmitter {
         return this.process !== undefined && !this.process.killed;
     }
     handleData(data) {
-        this.buffer += data;
+        // Append the new chunk as bytes. Buffer.concat avoids the UTF-8
+        // boundary corruption that string concatenation produces — a
+        // multibyte codepoint split across two TCP/pipe chunks decodes to
+        // U+FFFD, mangles the buffer length count, and breaks framing.
+        this.buffer = Buffer.concat([this.buffer, data]);
         while (true) {
             if (this.contentLength < 0) {
+                // Search for the header terminator in bytes, not chars.
                 const headerEnd = this.buffer.indexOf("\r\n\r\n");
                 if (headerEnd < 0)
                     break;
-                const header = this.buffer.slice(0, headerEnd);
+                // Headers are ASCII per spec, so toString("ascii") is safe and
+                // avoids paying for a UTF-8 decode on the framing band.
+                const header = this.buffer.slice(0, headerEnd).toString("ascii");
                 const match = header.match(/Content-Length:\s*(\d+)/i);
                 if (!match) {
-                    this.buffer = this.buffer.slice(headerEnd + 4);
+                    this.buffer = this.buffer.subarray(headerEnd + 4);
                     continue;
                 }
                 this.contentLength = parseInt(match[1], 10);
-                this.buffer = this.buffer.slice(headerEnd + 4);
+                this.buffer = this.buffer.subarray(headerEnd + 4);
             }
+            // Content-Length is a BYTE count — compare against the buffer's
+            // byte length, not its character length. Pre-fix this compared
+            // string lengths; with multibyte responses (e.g. CJK identifiers,
+            // emoji in diagnostics) we'd block waiting for bytes that had
+            // already arrived.
             if (this.buffer.length < this.contentLength)
                 break;
-            const content = this.buffer.slice(0, this.contentLength);
-            this.buffer = this.buffer.slice(this.contentLength);
+            const bodyBytes = this.buffer.subarray(0, this.contentLength);
+            this.buffer = this.buffer.subarray(this.contentLength);
             this.contentLength = -1;
+            // Decode the full body in one shot — at this point we have the
+            // exact byte count, so the UTF-8 boundary issue is fully gone.
+            const content = bodyBytes.toString("utf8");
             try {
                 const message = JSON.parse(content);
                 if ("id" in message && this.pending.has(message.id)) {

package/dist/lsp/manager.js

@@ -6,6 +6,7 @@ import { LSPClient } from "./client.js";
 import { BUILTIN_LSP_SERVERS } from "./servers.js";
 import { execSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
+import { rootUriToPath } from "./root-path.js";
 export class LSPServerManager {
     servers = new Map();
     rootUri;
@@ -49,7 +50,7 @@ export class LSPServerManager {
         }
         managed.state = "starting";
         try {
-            const client = new LSPClient(managed.config.command, managed.config.args, this.rootUri.replace("file://", ""));
+            const client = new LSPClient(managed.config.command, managed.config.args, rootUriToPath(this.rootUri));
             await client.start();
             await client.initialize(this.rootUri);
             managed.client = client;

package/dist/lsp/root-path.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Convert a `file://` root URI to a platform filesystem path.
+ *
+ * The LSP manager used `rootUri.replace("file://", "")`, which only strips the
+ * first occurrence and leaves percent-encoding intact, and on Windows turns
+ * `file:///C:/x` into the invalid `/C:/x`. fileURLToPath does the proper
+ * platform conversion (drive letters, percent-decoding, UNC).
+ */
+export declare function rootUriToPath(rootUri: string): string;

package/dist/lsp/root-path.js

@@ -0,0 +1,12 @@
+import { fileURLToPath } from "node:url";
+/**
+ * Convert a `file://` root URI to a platform filesystem path.
+ *
+ * The LSP manager used `rootUri.replace("file://", "")`, which only strips the
+ * first occurrence and leaves percent-encoding intact, and on Windows turns
+ * `file:///C:/x` into the invalid `/C:/x`. fileURLToPath does the proper
+ * platform conversion (drive letters, percent-decoding, UNC).
+ */
+export function rootUriToPath(rootUri) {
+    return fileURLToPath(rootUri);
+}

package/dist/onboarding.js

@@ -4,9 +4,9 @@
  * (see src/ui/components/OnboardingPrompt.tsx); this module only exposes
  * pure(-ish) helpers it consumes, so there's a single input stack.
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { userHome } from "./settings/manager.js";
 import { getOpenRouterModels } from "./data/openrouter-models.js";
 import { sanitizeApiKey } from "./llm/api-key-sanitize.js";
 export const PROVIDERS = [
@@ -257,8 +257,13 @@ export function resolveApiKey(optionsApiKey, settingsApiKey) {
         if (!p.envKey)
             continue;
         const v = process.env[p.envKey];
-        if (v && v.trim())
-            return v.trim();
+        if (!v)
+            continue;
+        // Same sanitization boundary as detectEnvKeys — env-sourced keys carry
+        // CRLF/BOM/zero-width/control chars; .trim() alone misses interior ones.
+        const cleaned = sanitizeApiKey(v).value;
+        if (cleaned)
+            return cleaned;
     }
     return undefined;
 }
@@ -272,7 +277,7 @@ export function resolveApiKey(optionsApiKey, settingsApiKey) {
  * then settings.model (legacy top-level). undefined when nothing matches.
  */
 export function findSavedKeyForProvider(provider) {
-    const file = join(homedir(), ".code-shell", "settings.json");
+    const file = join(userHome(), ".code-shell", "settings.json");
     if (!existsSync(file))
         return undefined;
     let data;
@@ -304,7 +309,7 @@ export function findSavedKeyForProvider(provider) {
  * just the provider's first model.
  */
 export function loadSavedModelsForProvider(provider) {
-    const file = join(homedir(), ".code-shell", "settings.json");
+    const file = join(userHome(), ".code-shell", "settings.json");
     if (!existsSync(file))
         return [];
     let data;
@@ -334,7 +339,7 @@ export function hasApiKey() {
     // /logout look like a no-op when the others still held credentials.
     // Reads ~/.code-shell/ only — ~/.claude/ compat was dropped because Claude
     // Code's settings schema diverges and merging broke boot.
-    const p = join(homedir(), ".code-shell", "settings.json");
+    const p = join(userHome(), ".code-shell", "settings.json");
     if (existsSync(p)) {
         try {
             const data = JSON.parse(readFileSync(p, "utf-8"));
@@ -501,7 +506,7 @@ export function modelDisplayName(model) {
     return base.charAt(0).toUpperCase() + base.slice(1);
 }
 export function saveSettings(result, providerDef, poolModels) {
-    const dir = join(homedir(), ".code-shell");
+    const dir = join(userHome(), ".code-shell");
     const file = join(dir, "settings.json");
     mkdirSync(dir, { recursive: true });
     let existing = {};
@@ -551,7 +556,7 @@ export function saveSettings(result, providerDef, poolModels) {
  * Writes atomically via tmp+rename.
  */
 export function appendOnboardingResult(opts) {
-    const dir = join(homedir(), ".code-shell");
+    const dir = join(userHome(), ".code-shell");
     const file = join(dir, "settings.json");
     mkdirSync(dir, { recursive: true });
     let existing = {};
@@ -602,13 +607,15 @@ export function appendOnboardingResult(opts) {
         renameSync(tmp, file);
     }
     catch {
-        // Fallback: best-effort direct write if rename fails (e.g. cross-device).
+        // Fallback: best-effort direct write if rename fails (e.g. cross-device),
+        // then remove the orphaned temp file the failed rename left behind.
         writeFileSync(file, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+        rmSync(tmp, { force: true });
     }
 }
 // saveArenaSettings removed — replaced by saveArenaSettingsByKeys
 export function saveArenaSettingsByKeys(keys) {
-    const dir = join(homedir(), ".code-shell");
+    const dir = join(userHome(), ".code-shell");
     const file = join(dir, "settings.json");
     let existing = {};
     if (existsSync(file)) {

package/dist/plugins/gitOps.d.ts

@@ -21,9 +21,43 @@ export type GitResult = {
     ok: false;
     error: string;
 };
+/**
+ * Force git to never prompt interactively. gitOps runs in headless contexts
+ * (the Electron main process, the agent worker) that have no TTY, so a
+ * private/auth-required clone or an unknown SSH host key would otherwise make
+ * git BLOCK on a credential/host-key prompt — the operation appears to hang
+ * until the safeSpawn timeout (or an off-screen askpass dialog). With these
+ * set, git fails fast with an auth error instead.
+ *
+ * - GIT_TERMINAL_PROMPT=0 — git's own username/password prompt becomes an error.
+ * - GIT_SSH_COMMAND BatchMode=yes — ssh never asks for a password/passphrase;
+ *   accept-new auto-trusts a first-seen host key (instead of the y/n prompt)
+ *   but still rejects a changed key. Not overridden if the caller already
+ *   provides GIT_SSH_COMMAND (e.g. a custom identity file).
+ */
+export declare function nonInteractiveGitEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Clone a marketplace repo cheaply. These repos can bundle hundreds of plugins
+ * (thousands of files), but adding a marketplace only needs its manifest — the
+ * individual plugin trees are pulled on demand at install time
+ * ({@link gitSparseCheckoutAdd}). So we do a blobless, no-checkout clone and
+ * then sparse-check out only the manifest directories.
+ *
+ * `sparsePaths` defaults to the two manifest locations we support
+ * (.claude-plugin and .agents/plugins). On any failure of the sparse setup we
+ * fall back to checking out the full tree, so correctness never depends on
+ * sparse support being present.
+ */
 export declare function gitClone(url: string, destDir: string, options?: {
     ref?: string;
+    sparsePaths?: string[];
 }): Promise<GitResult>;
+/**
+ * Expand a sparse-checkout to include an additional path (a plugin subdir),
+ * materializing its blobs. Best-effort: if the repo isn't sparse this errors
+ * harmlessly and the caller proceeds (the files are already present).
+ */
+export declare function gitSparseCheckoutAdd(repoDir: string, relPath: string): Promise<GitResult>;
 export declare function gitRevParseHead(repoDir: string): Promise<GitResult>;
 export declare function gitFetchAndReset(repoDir: string, ref?: string): Promise<GitResult>;
 /**

package/dist/plugins/gitOps.js

@@ -15,10 +15,31 @@
  * classification. See docs/architecture/17 for the trust framing.
  */
 import { safeSpawn } from "../runtime/safe-spawn.js";
+/**
+ * Force git to never prompt interactively. gitOps runs in headless contexts
+ * (the Electron main process, the agent worker) that have no TTY, so a
+ * private/auth-required clone or an unknown SSH host key would otherwise make
+ * git BLOCK on a credential/host-key prompt — the operation appears to hang
+ * until the safeSpawn timeout (or an off-screen askpass dialog). With these
+ * set, git fails fast with an auth error instead.
+ *
+ * - GIT_TERMINAL_PROMPT=0 — git's own username/password prompt becomes an error.
+ * - GIT_SSH_COMMAND BatchMode=yes — ssh never asks for a password/passphrase;
+ *   accept-new auto-trusts a first-seen host key (instead of the y/n prompt)
+ *   but still rejects a changed key. Not overridden if the caller already
+ *   provides GIT_SSH_COMMAND (e.g. a custom identity file).
+ */
+export function nonInteractiveGitEnv(base) {
+    return {
+        ...base,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_SSH_COMMAND: base.GIT_SSH_COMMAND ?? "ssh -oBatchMode=yes -oStrictHostKeyChecking=accept-new",
+    };
+}
 async function runGit(args, cwd, timeoutMs = 60_000) {
     const r = await safeSpawn("git", args, {
         cwd: cwd ?? process.cwd(),
-        env: process.env,
+        env: nonInteractiveGitEnv(process.env),
         timeoutMs,
     });
     if (r.spawnFailed) {
@@ -35,12 +56,47 @@ async function runGit(args, cwd, timeoutMs = 60_000) {
         error: `git ${args.join(" ")} exited ${r.exitCode}: ${r.stderr.trim() || "unknown error"}`,
     };
 }
+/**
+ * Clone a marketplace repo cheaply. These repos can bundle hundreds of plugins
+ * (thousands of files), but adding a marketplace only needs its manifest — the
+ * individual plugin trees are pulled on demand at install time
+ * ({@link gitSparseCheckoutAdd}). So we do a blobless, no-checkout clone and
+ * then sparse-check out only the manifest directories.
+ *
+ * `sparsePaths` defaults to the two manifest locations we support
+ * (.claude-plugin and .agents/plugins). On any failure of the sparse setup we
+ * fall back to checking out the full tree, so correctness never depends on
+ * sparse support being present.
+ */
 export async function gitClone(url, destDir, options) {
-    const args = ["clone", "--depth", "1"];
+    const sparsePaths = options?.sparsePaths ?? [".claude-plugin", ".agents/plugins"];
+    const args = ["clone", "--depth", "1", "--filter=blob:none", "--no-checkout"];
     if (options?.ref)
         args.push("--branch", options.ref);
     args.push("--", url, destDir);
-    return runGit(args);
+    const cloned = await runGit(args);
+    if (!cloned.ok)
+        return cloned;
+    // Restrict the working tree to the manifest dirs, then check out. Use
+    // non-cone mode so nested paths like ".agents/plugins" match exactly.
+    const init = await runGit(["sparse-checkout", "set", "--no-cone", ...sparsePaths], destDir);
+    if (!init.ok) {
+        // Sparse unsupported/failed — fall back to a normal full checkout so the
+        // manifest is still present.
+        return runGit(["checkout"], destDir);
+    }
+    const checkout = await runGit(["checkout"], destDir);
+    if (!checkout.ok)
+        return checkout;
+    return cloned;
+}
+/**
+ * Expand a sparse-checkout to include an additional path (a plugin subdir),
+ * materializing its blobs. Best-effort: if the repo isn't sparse this errors
+ * harmlessly and the caller proceeds (the files are already present).
+ */
+export async function gitSparseCheckoutAdd(repoDir, relPath) {
+    return runGit(["sparse-checkout", "add", relPath], repoDir);
 }
 export async function gitRevParseHead(repoDir) {
     return runGit(["rev-parse", "HEAD"], repoDir);

package/dist/plugins/installer/codex/convertAgents.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert one Codex agent TOML into a CC agent Markdown string.
+ * Real CC fields: name, description, model, body(=developer_instructions).
+ * Every other field is preserved with a `codex_` prefix (v1 inert; see spec §7.1).
+ * `mcp_servers` values are rewritten to `<plugin>:<server>` to match the MCP merge key.
+ */
+export declare function convertCodexAgentToml(toml: string, sourceName: string, pluginName: string): string;