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

package/dist/context/compaction.js

@@ -18,6 +18,30 @@ import { estimateMessagesTokens } from "./token-counter.js";
 export function estimateTokens(messages) {
     return Math.ceil(estimateMessagesTokens(messages) * (4 / 3));
 }
+/**
+ * Reconcile user-supplied compaction ratios into a safe ordering.
+ *
+ * The three tiers must satisfy `floor < compact < summarize` or the manager
+ * fires them in the wrong order (e.g. an emergency window-compact before the
+ * cheaper summary). Users edit these freely in settings.json, so we clamp
+ * rather than trust: summarize is pulled up to at least compact, floor is
+ * pushed down to at most compact. Absent fields are left undefined so the
+ * ContextManager keeps its own default for them.
+ */
+export function clampContextRatios(input) {
+    const compact = input.compactAtRatio;
+    const summarize = input.summarizeAtRatio !== undefined && compact !== undefined
+        ? Math.max(input.summarizeAtRatio, compact)
+        : input.summarizeAtRatio;
+    const floor = input.microcompactFloorRatio !== undefined && compact !== undefined
+        ? Math.min(input.microcompactFloorRatio, compact)
+        : input.microcompactFloorRatio;
+    return {
+        compactAtRatio: compact,
+        summarizeAtRatio: summarize,
+        microcompactFloorRatio: floor,
+    };
+}
 // ─── Tool Use / Result Pair Protection ──────────────────────────────
 /**
  * Expand a slice start-index backwards so that every tool_result in the
@@ -275,6 +299,168 @@ export function microcompact(messages, options = {}) {
     }
     return result;
 }
+/** Tools whose result is the content of a single file, keyed by path. */
+const FILE_READ_TOOLS = new Set(["Read"]);
+/**
+ * Content-aware dedup: when the SAME file is Read more than once, every Read
+ * result except the most recent is stale — the file's current state is in the
+ * latest read. Clear the older ones (replace with a fingerprint pointing at
+ * the newer read) regardless of the recency window or pressure floor, because
+ * this is pure waste removal, not lossy compaction: the model never needs two
+ * copies of the same file.
+ *
+ * Distinct from microcompact (which is recency-gated and pressure-gated): a
+ * file Read 3 times in the last 3 turns keeps 3 full copies under microcompact
+ * but only the newest under this pass. Zero-cost and always safe to run, so the
+ * ContextManager calls it as an early tier.
+ *
+ * Only `Read` is deduped (its result is exactly the file content). Edit/Write
+ * results are diffs/confirmations, not full snapshots, so they're left alone.
+ */
+export function dedupeFileReads(messages) {
+    const idToName = buildToolUseIdToNameMap(messages);
+    const idToInput = new Map();
+    for (const msg of messages) {
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type === "tool_use" && block.id)
+                idToInput.set(block.id, block.input);
+        }
+    }
+    // Resolve a Read tool_use_id to its file_path arg (the dedup key).
+    const pathOf = (toolUseId) => {
+        const input = idToInput.get(toolUseId);
+        const p = input?.file_path ?? input?.path;
+        return typeof p === "string" && p.length > 0 ? p : undefined;
+    };
+    // Collect, per file path, the message indices + block positions of every
+    // non-cleared Read result. Walk forward so "last" is the newest.
+    const byPath = new Map();
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type !== "tool_result" || !block.tool_use_id)
+                continue;
+            if (!FILE_READ_TOOLS.has(idToName.get(block.tool_use_id) ?? ""))
+                continue;
+            if (typeof block.content !== "string")
+                continue;
+            if (block.content.startsWith("[Old tool result cleared"))
+                continue;
+            const path = pathOf(block.tool_use_id);
+            if (!path)
+                continue;
+            const list = byPath.get(path) ?? [];
+            list.push({ msgIdx: i, toolUseId: block.tool_use_id });
+            byPath.set(path, list);
+        }
+    }
+    // For each path read more than once, mark all-but-last for clearing.
+    const clearIds = new Set();
+    for (const [, reads] of byPath) {
+        if (reads.length < 2)
+            continue;
+        for (let k = 0; k < reads.length - 1; k++)
+            clearIds.add(reads[k].toolUseId);
+    }
+    if (clearIds.size === 0)
+        return { messages, clearedCount: 0 };
+    let clearedCount = 0;
+    const result = messages.map((msg) => {
+        if (!Array.isArray(msg.content))
+            return msg;
+        return {
+            ...msg,
+            content: msg.content.map((block) => {
+                if (block.type !== "tool_result" || !block.tool_use_id)
+                    return block;
+                if (!clearIds.has(block.tool_use_id))
+                    return block;
+                const argsSummary = summarizeToolCallArgs("Read", idToInput.get(block.tool_use_id));
+                clearedCount++;
+                return {
+                    ...block,
+                    content: `[Old tool result cleared — superseded by a newer Read${argsSummary ? ` of ${argsSummary}` : ""}]`,
+                };
+            }),
+        };
+    });
+    return { messages: result, clearedCount };
+}
+/** Build id → true for tool_use blocks that are a browser snapshot observation,
+ *  i.e. `browser_observe` with mode "snapshot" (the default when mode omitted).
+ *  Only snapshots produce large, supersede-able element lists worth masking. */
+function buildSnapshotObserveIdSet(messages) {
+    const ids = new Set();
+    for (const msg of messages) {
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type !== "tool_use" || !block.id || block.name !== "browser_observe")
+                continue;
+            const mode = block.input?.mode;
+            if (mode === undefined || mode === "snapshot")
+                ids.add(block.id);
+        }
+    }
+    return ids;
+}
+const OLD_SNAPSHOT_PLACEHOLDER = "[Old browser snapshot collapsed — superseded by a newer browser_observe(snapshot). " +
+    "Re-run browser_observe for the current page's elements.]";
+/**
+ * Observation masking for browser_observe(snapshot) results (the research's
+ * highest-leverage browser-token saving: a page snapshot is large and only the
+ * LATEST one matters for the next decision; older ones are stale element lists).
+ * Keep the most recent snapshot result verbatim; replace every earlier one with
+ * a one-line placeholder. Deterministic — no LLM summarization needed.
+ *
+ * Keyed on the snapshot OBSERVATION (browser_observe with mode snapshot) — read/
+ * extract observations and act results are left untouched. Renamed from
+ * maskOldBrowserSnapshots when the 9 browser_* tools collapsed into 3.
+ */
+export function maskOldObservations(messages) {
+    const snapshotIds = buildSnapshotObserveIdSet(messages);
+    const snapResults = [];
+    for (const msg of messages) {
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type !== "tool_result" || !block.tool_use_id)
+                continue;
+            if (!snapshotIds.has(block.tool_use_id))
+                continue;
+            if (typeof block.content !== "string")
+                continue;
+            if (block.content.startsWith("[Old browser snapshot collapsed"))
+                continue;
+            snapResults.push(block.tool_use_id);
+        }
+    }
+    if (snapResults.length < 2)
+        return { messages, maskedCount: 0 };
+    // Mask all but the last (newest walked-forward).
+    const maskIds = new Set(snapResults.slice(0, -1));
+    let maskedCount = 0;
+    const result = messages.map((msg) => {
+        if (!Array.isArray(msg.content))
+            return msg;
+        return {
+            ...msg,
+            content: msg.content.map((block) => {
+                if (block.type !== "tool_result" || !block.tool_use_id)
+                    return block;
+                if (!maskIds.has(block.tool_use_id))
+                    return block;
+                maskedCount++;
+                return { ...block, content: OLD_SNAPSHOT_PLACEHOLDER };
+            }),
+        };
+    });
+    return { messages: result, maskedCount };
+}
 /**
  * Apply aggregate per-message tool result budget.
  * When total tool_result content in a single message exceeds maxTotalChars,
@@ -299,28 +485,36 @@ export function applyToolResultBudget(messages, maxTotalChars = 100_000) {
             return msg;
         // Sort by size descending — truncate largest first
         resultBlocks.sort((a, b) => b.size - a.size);
+        // Build the exact replacement for a block, so the running budget uses the
+        // real post-truncation length (the old code assumed a flat ~200 chars,
+        // but the replacement is ~150 boilerplate + up to 500 preview ≈ 650+,
+        // which under-truncated and could even leave the message LARGER).
+        const truncate = (content) => {
+            const preview = content.slice(0, 500);
+            const sizeKb = (content.length / 1000).toFixed(0);
+            return (`Output too large (${sizeKb}KB) — truncated to fit the per-message budget. ` +
+                `Re-run the originating tool if you need the full output.\n\n` +
+                `Preview (first 500 chars):\n${preview}`);
+        };
         let remaining = totalSize;
-        const toTruncate = new Set();
+        const replacements = new Map();
         for (const rb of resultBlocks) {
             if (remaining <= maxTotalChars)
                 break;
-            toTruncate.add(rb.index);
-            remaining -= rb.size;
-            remaining += 200; // truncated replacement is ~200 chars
+            const original = msg.content[rb.index].content;
+            const replaced = truncate(original);
+            // Only truncate if it actually shrinks the block; otherwise skip it
+            // (truncating a barely-oversized block would grow the message).
+            if (replaced.length >= rb.size)
+                continue;
+            replacements.set(rb.index, replaced);
+            remaining -= rb.size - replaced.length;
         }
-        if (toTruncate.size === 0)
+        if (replacements.size === 0)
             return msg;
         const newContent = msg.content.map((block, i) => {
-            if (!toTruncate.has(i))
-                return block;
-            const preview = typeof block.content === "string" ? block.content.slice(0, 500) : "";
-            const sizeKb = (block.content.length / 1000).toFixed(0);
-            return {
-                ...block,
-                content: `Output too large (${sizeKb}KB) — truncated to fit the per-message budget. ` +
-                    `Re-run the originating tool if you need the full output.\n\n` +
-                    `Preview (first 500 chars):\n${preview}`,
-            };
+            const replaced = replacements.get(i);
+            return replaced === undefined ? block : { ...block, content: replaced };
         });
         return { ...msg, content: newContent };
     });

package/dist/context/manager.d.ts

@@ -39,7 +39,6 @@ export type OnCompactFn = (info: {
 }) => void;
 export declare class ContextManager {
     private config;
-    private toolCallHashes;
     private summarizeFn;
     private consecutiveSummaryFailures;
     private lastSummary;
@@ -123,23 +122,4 @@ export declare class ContextManager {
         needsCompact: boolean;
         needsEmergency: boolean;
     };
-    /**
-     * Deduplicate tool calls by hashing arguments.
-     */
-    deduplicateToolCalls(calls: Array<{
-        toolName: string;
-        args: Record<string, unknown>;
-    }>): {
-        toExecute: typeof calls;
-        cached: Array<{
-            toolName: string;
-            args: Record<string, unknown>;
-            result: string;
-        }>;
-    };
-    /**
-     * Record a tool call result for dedup tracking.
-     */
-    recordToolResult(toolName: string, args: Record<string, unknown>, result: string): void;
-    private hashCall;
 }

package/dist/context/manager.js

@@ -5,7 +5,7 @@
  * Tier 2: LLM summary (async) — generate summary of older messages via model call
  * Tier 3: window compact (sync, emergency) — aggressive truncation fallback
  */
-import { estimateTokens, microcompact, snipCompact, windowCompact, truncateToolResult, buildSummarizationPrompt, applySummaryCompaction, applyToolResultBudget, extractAnchoredSummary, } from "./compaction.js";
+import { estimateTokens, microcompact, dedupeFileReads, maskOldObservations, snipCompact, windowCompact, truncateToolResult, buildSummarizationPrompt, applySummaryCompaction, applyToolResultBudget, extractAnchoredSummary, } from "./compaction.js";
 import { applyToolResultPersistence, createContentReplacementState, reconstructContentReplacementState, resolveToolResultsDir, } from "./tool-result-storage.js";
 import { logger } from "../logging/logger.js";
 const DEFAULT_CONFIG = {
@@ -39,7 +39,6 @@ function defaultKeepRecent(maxTokens) {
 }
 export class ContextManager {
     config;
-    toolCallHashes = new Map();
     summarizeFn;
     consecutiveSummaryFailures = 0;
     lastSummary;
@@ -128,6 +127,25 @@ export class ContextManager {
         // Tier 0c: Aggregate tool result budget (per-message) — char-level
         // backstop for messages still over the limit after persistence.
         result = applyToolResultBudget(result);
+        // Tier 0d: dedup repeated Reads of the same file — keep only the latest
+        // copy (older ones are stale). Always-on + zero-cost: it's pure waste
+        // removal (the model never needs two snapshots of one file), unlike the
+        // pressure-/recency-gated tiers below. Runs before microcompact so an
+        // already-deduped result isn't double-counted toward the keep-recent window.
+        const dedup = dedupeFileReads(result);
+        if (dedup.clearedCount > 0) {
+            result = dedup.messages;
+            logger.info("context.dedupe_file_reads", { cleared: dedup.clearedCount });
+        }
+        // Tier 0d': browser observation masking — keep only the latest
+        // browser_snapshot, collapse older ones (stale element lists, often large).
+        // Same always-on waste-removal class as dedupeFileReads. The research's
+        // top browser-token lever (folding old observations beats LLM summarizing).
+        const masked = maskOldObservations(result);
+        if (masked.maskedCount > 0) {
+            result = masked.messages;
+            logger.info("context.mask_browser_snapshots", { masked: masked.maskedCount });
+        }
         // Tier 1: microcompact — fingerprint old whitelisted tool_results.
         // Only runs above the floor ratio: under-pressure context keeps full
         // detail so the model isn't forced to re-Read files it just looked at.
@@ -342,20 +360,22 @@ export class ContextManager {
      */
     truncateToolResults(messages) {
         const maxChars = this.config.maxToolResultChars;
-        let modified = false;
         const result = messages.map((msg) => {
             if (!Array.isArray(msg.content))
                 return msg;
+            // Per-message flag: a truncation in an earlier message must not force
+            // later, unchanged messages to be spread-copied.
+            let messageModified = false;
             const newContent = msg.content.map((block) => {
                 if (block.type === "tool_result" && typeof block.content === "string") {
                     if (block.content.length > maxChars) {
-                        modified = true;
+                        messageModified = true;
                         return { ...block, content: truncateToolResult(block.content, maxChars) };
                     }
                 }
                 return block;
             });
-            return modified ? { ...msg, content: newContent } : msg;
+            return messageModified ? { ...msg, content: newContent } : msg;
         });
         return result;
     }
@@ -384,40 +404,4 @@ export class ContextManager {
             needsEmergency: ratio >= this.config.summarizeAtRatio,
         };
     }
-    /**
-     * Deduplicate tool calls by hashing arguments.
-     */
-    deduplicateToolCalls(calls) {
-        const toExecute = [];
-        const cached = [];
-        for (const call of calls) {
-            const hash = this.hashCall(call.toolName, call.args);
-            const existing = this.toolCallHashes.get(hash);
-            if (existing && existing.count >= 2) {
-                cached.push({ ...call, result: existing.lastResult });
-                existing.count++;
-            }
-            else {
-                toExecute.push(call);
-            }
-        }
-        return { toExecute, cached };
-    }
-    /**
-     * Record a tool call result for dedup tracking.
-     */
-    recordToolResult(toolName, args, result) {
-        const hash = this.hashCall(toolName, args);
-        const existing = this.toolCallHashes.get(hash);
-        if (existing) {
-            existing.count++;
-            existing.lastResult = result;
-        }
-        else {
-            this.toolCallHashes.set(hash, { count: 1, lastResult: result });
-        }
-    }
-    hashCall(toolName, args) {
-        return `${toolName}:${JSON.stringify(args)}`;
-    }
 }

package/dist/cost-tracker.js

@@ -3,67 +3,11 @@
  */
 import { NOOP_COLORIZER } from "./colorizer.js";
 import { findOpenRouterModel } from "./data/openrouter-models.js";
-function pricing(input, output) {
-    // Default cache pricing: read = 10% of input, write = 125% of input
-    return { input, output, cacheRead: input * 0.1, cacheWrite: input * 1.25 };
-}
-const MODEL_PRICING = {
-    // Anthropic (per 1M tokens, USD)
-    "claude-opus-4.6": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-    "claude-opus-4-6": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 }, // alias
-    "claude-opus-4.5": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-    "claude-opus-4.1": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-    "claude-opus-4": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-    "claude-sonnet-4.6": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-    "claude-sonnet-4-6": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 }, // alias
-    "claude-sonnet-4.5": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-    "claude-sonnet-4": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-    "claude-3.7-sonnet": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-    "claude-3-7-sonnet": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-    "claude-3.5-haiku": { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
-    "claude-haiku-4.5": { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
-    "claude-haiku-4-5": { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 }, // alias
-    // OpenAI
-    "gpt-5.4": pricing(5, 20),
-    "gpt-5.4-mini": pricing(1.5, 6),
-    "gpt-5.4-pro": pricing(10, 40),
-    "gpt-5": pricing(5, 20),
-    "gpt-4o": pricing(2.5, 10),
-    "gpt-4o-mini": pricing(0.15, 0.6),
-    "gpt-4.1": pricing(2, 8),
-    "gpt-4.1-mini": pricing(0.4, 1.6),
-    "o4-mini": pricing(1.1, 4.4),
-    "o3": pricing(10, 40),
-    "o3-mini": pricing(1.1, 4.4),
-    // Google
-    "gemini-2.5-pro": pricing(1.25, 10),
-    "gemini-2.5-pro-preview": pricing(1.25, 10),
-    "gemini-2.5-flash": pricing(0.15, 0.6),
-    "gemini-3.1-pro-preview": pricing(2, 10),
-    "gemini-3-flash-preview": pricing(0.15, 0.6),
-    "gemini-2.0-flash": pricing(0.1, 0.4),
-    // DeepSeek
-    "deepseek-v4-flash": pricing(0.126, 0.252),
-    "deepseek-v4-pro": pricing(0.5, 2),
-    "deepseek-v3.2": pricing(0.14, 0.28),
-    "deepseek-chat": pricing(0.14, 0.28),
-    "deepseek-r1": pricing(0.55, 2.19),
-    "deepseek-reasoner": pricing(0.55, 2.19),
-    // Qwen
-    "qwen3-coder": pricing(0.3, 0.6),
-    "qwen3-235b-a22b": pricing(0.3, 1.2),
-    "qwen3-30b-a3b": pricing(0.1, 0.3),
-    "qwen3-max": pricing(0.5, 2),
-    // Meta
-    "llama-4-maverick": pricing(0.2, 0.8),
-    "llama-4-scout": pricing(0.15, 0.4),
-    // Mistral
-    "devstral-medium": pricing(0.5, 1.5),
-    "mistral-large": pricing(2, 6),
-    "devstral-small": pricing(0.1, 0.3),
-};
-// Default fallback pricing
-const DEFAULT_PRICING = pricing(3, 15);
+import { MODEL_PRICING, DEFAULT_PRICING, } from "./data/model-metadata.js";
+// Pricing per 1M tokens (USD). The MODEL_PRICING table + DEFAULT_PRICING now
+// live in data/model-metadata.json (loaded by data/model-metadata.ts) so a
+// price change is a data edit, not a code change. cacheRead/cacheWrite are
+// derived there: read = 10% of input, write = 125% of input.
 /** Build a ModelPricing from an OpenRouter snapshot entry. */
 function openRouterPricing(hit) {
     const input = hit.inputPricePerMillion;

package/dist/credentials/cipher.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Credential encryption boundary.
+ *
+ * The core has no business owning a platform encryption key — on the desktop
+ * the only safe key lives behind Electron `safeStorage`, which is in the main
+ * process, not in this worker. So core defines an INTERFACE and the host feeds
+ * an implementation: desktop main injects a safeStorage-backed cipher; the
+ * headless CLI / SDK inject {@link PlaintextCipher}. This keeps `safeStorage`
+ * out of `packages/core` entirely (`grep -R safeStorage packages/core/src`
+ * must stay empty) and puts secret crypto where the key actually is.
+ *
+ * The stored field is a tagged string so a store written by one cipher can be
+ * read (or rejected) by another:
+ *   - `plain:<secret>`        — PlaintextCipher, or any pre-cipher legacy value
+ *                               that has no recognized prefix (treated as plain).
+ *   - `enc:<scheme>:<base64>` — an encrypting cipher; `<scheme>` lets a cipher
+ *                               recognize its own ciphertext via canDecrypt().
+ */
+export interface EncryptionCipher {
+    /** Encrypt a plaintext secret into its stored (tagged) form. */
+    encrypt(plaintext: string): string;
+    /** Decrypt a stored value back to plaintext. Must accept this cipher's own
+     *  output and legacy un-prefixed plaintext; may throw if a value is
+     *  recognizably foreign and undecryptable. */
+    decrypt(stored: string): string;
+    /** True when this cipher can decrypt `stored`. Used by the store to decide
+     *  whether to migrate (re-encrypt on next save) a value written by a
+     *  different cipher / left as legacy plaintext. */
+    canDecrypt?(stored: string): boolean;
+}
+/**
+ * The no-encryption strategy — chosen explicitly, not a no-op. Headless and
+ * SDK hosts have no safe key store, so they keep credentials as owner-only
+ * (0o600) plaintext, exactly as before this boundary existed. Named so the
+ * choice reads honestly in host wiring: `new CredentialStore(cwd, new
+ * PlaintextCipher())` says "plaintext on purpose", not "forgot to encrypt".
+ */
+export declare class PlaintextCipher implements EncryptionCipher {
+    encrypt(plaintext: string): string;
+    decrypt(stored: string): string;
+    canDecrypt(stored: string): boolean;
+}
+/** Reads a value that may be tagged (`plain:`) or legacy bare plaintext. */
+export declare function readPlaintext(stored: string): string;
+/** Host startup hook: install the process-wide credential cipher (desktop main
+ *  passes a safeStorage-backed implementation). Idempotent; last call wins. */
+export declare function setDefaultCredentialCipher(cipher: EncryptionCipher): void;
+/** The current process-default cipher (PlaintextCipher unless a host set one). */
+export declare function getDefaultCredentialCipher(): EncryptionCipher;

package/dist/credentials/cipher.js

@@ -0,0 +1,45 @@
+const PLAIN_PREFIX = "plain:";
+/**
+ * The no-encryption strategy — chosen explicitly, not a no-op. Headless and
+ * SDK hosts have no safe key store, so they keep credentials as owner-only
+ * (0o600) plaintext, exactly as before this boundary existed. Named so the
+ * choice reads honestly in host wiring: `new CredentialStore(cwd, new
+ * PlaintextCipher())` says "plaintext on purpose", not "forgot to encrypt".
+ */
+export class PlaintextCipher {
+    encrypt(plaintext) {
+        return `${PLAIN_PREFIX}${plaintext}`;
+    }
+    decrypt(stored) {
+        // Accept our own tag, and treat any un-tagged legacy value as plaintext.
+        if (stored.startsWith(PLAIN_PREFIX))
+            return stored.slice(PLAIN_PREFIX.length);
+        if (stored.startsWith("enc:")) {
+            throw new Error("PlaintextCipher cannot decrypt an encrypted credential");
+        }
+        return stored;
+    }
+    canDecrypt(stored) {
+        return !stored.startsWith("enc:");
+    }
+}
+/** Reads a value that may be tagged (`plain:`) or legacy bare plaintext. */
+export function readPlaintext(stored) {
+    return stored.startsWith(PLAIN_PREFIX) ? stored.slice(PLAIN_PREFIX.length) : stored;
+}
+// ─── Process-default cipher ──────────────────────────────────────
+// CredentialStore is constructed at ~12 call sites (core + desktop) as
+// `new CredentialStore(cwd)`. Rather than thread a cipher through every one,
+// the host sets the process default ONCE at startup; stores pick it up unless
+// a cipher is passed explicitly. Defaults to PlaintextCipher so any host that
+// never calls the setter behaves exactly as before.
+let defaultCipher = new PlaintextCipher();
+/** Host startup hook: install the process-wide credential cipher (desktop main
+ *  passes a safeStorage-backed implementation). Idempotent; last call wins. */
+export function setDefaultCredentialCipher(cipher) {
+    defaultCipher = cipher;
+}
+/** The current process-default cipher (PlaintextCipher unless a host set one). */
+export function getDefaultCredentialCipher() {
+    return defaultCipher;
+}

package/dist/credentials/cookie-jar.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Cookie jar 工具(凭证模块第二期):core 侧的纯函数,把存进 CredentialStore 的
+ * cookie 凭证(序列化的 jar)转成 yt-dlp/curl/wget/aria2 都吃的 Netscape cookies.txt。
+ *
+ * 形态与 desktop/src/main/credentials-service.ts 的 `formatNetscapeCookies` 一致
+ * (desktop 在拓取那一刻用,core 在取用那一刻用)。core 不能 import desktop,故各持一份
+ * 同语义的纯实现 —— 都无 Electron 依赖、可单测。
+ */
+/** 与 Electron Cookie 对齐的最小子集(jar 里存的就是这个)。 */
+export interface CookieLike {
+    domain?: string;
+    hostOnly?: boolean;
+    path?: string;
+    secure?: boolean;
+    expirationDate?: number;
+    name: string;
+    value: string;
+}
+/** Cookie[] → Netscape cookies.txt 字符串。跳过含 TAB/换行的脏 cookie。 */
+export declare function formatNetscapeCookies(cookies: CookieLike[]): string;
+/**
+ * 解析 cookie 凭证的 `secret`(序列化 jar)。容错:非数组/坏 JSON → 空数组。
+ */
+export declare function parseCookieJar(secret: string | undefined): CookieLike[];

package/dist/credentials/cookie-jar.js

@@ -0,0 +1,40 @@
+/**
+ * Cookie jar 工具(凭证模块第二期):core 侧的纯函数,把存进 CredentialStore 的
+ * cookie 凭证(序列化的 jar)转成 yt-dlp/curl/wget/aria2 都吃的 Netscape cookies.txt。
+ *
+ * 形态与 desktop/src/main/credentials-service.ts 的 `formatNetscapeCookies` 一致
+ * (desktop 在拓取那一刻用,core 在取用那一刻用)。core 不能 import desktop,故各持一份
+ * 同语义的纯实现 —— 都无 Electron 依赖、可单测。
+ */
+function bad(s) {
+    return s.includes("\t") || s.includes("\n") || s.includes("\r");
+}
+/** Cookie[] → Netscape cookies.txt 字符串。跳过含 TAB/换行的脏 cookie。 */
+export function formatNetscapeCookies(cookies) {
+    const lines = ["# Netscape HTTP Cookie File"];
+    for (const c of cookies) {
+        if (bad(c.name) || bad(c.value) || (c.domain && bad(c.domain)))
+            continue;
+        const domain = c.domain ?? "";
+        const includeSub = c.hostOnly === true ? "FALSE" : "TRUE";
+        const path = c.path ?? "/";
+        const secure = c.secure ? "TRUE" : "FALSE";
+        const expiry = typeof c.expirationDate === "number" ? String(Math.floor(c.expirationDate)) : "0";
+        lines.push([domain, includeSub, path, secure, expiry, c.name, c.value].join("\t"));
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * 解析 cookie 凭证的 `secret`(序列化 jar)。容错:非数组/坏 JSON → 空数组。
+ */
+export function parseCookieJar(secret) {
+    if (!secret)
+        return [];
+    try {
+        const parsed = JSON.parse(secret);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/credentials/index.d.ts

@@ -0,0 +1,7 @@
+export { CredentialStore } from "./store.js";
+export type { CredentialScope, MaskedCredential } from "./store.js";
+export { type EncryptionCipher, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./cipher.js";
+export type { Credential, CredentialType, CredentialStoreFile } from "./types.js";
+export { formatNetscapeCookies, parseCookieJar, type CookieLike } from "./cookie-jar.js";
+export { useCredentialToolDef, useCredentialToolDefFor, useCredentialTool, sweepStaleCredentialCookies, } from "./use-credential-tool.js";
+export { credentialUseGate } from "./use-gate.js";

package/dist/credentials/index.js

@@ -0,0 +1,5 @@
+export { CredentialStore } from "./store.js";
+export { PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./cipher.js";
+export { formatNetscapeCookies, parseCookieJar } from "./cookie-jar.js";
+export { useCredentialToolDef, useCredentialToolDefFor, useCredentialTool, sweepStaleCredentialCookies, } from "./use-credential-tool.js";
+export { credentialUseGate } from "./use-gate.js";

package/dist/credentials/inject-credential-tool.d.ts

@@ -0,0 +1,20 @@
+/**
+ * InjectCredential 工具:把一条 cookie 凭证「注入内置浏览器」(恢复登录态),
+ * 让 AI 能以该账号身份在内置浏览器面板做 UI 操作(配 browser_* 工具)。
+ *
+ * 与 UseCredential 的区别:
+ *  - UseCredential 取 cookie 文件路径走 HTTP 请求(curl/yt-dlp),只读、不改浏览器。
+ *  - InjectCredential 改的是内置浏览器的登录态(先清再灌),副作用更大 →
+ *    独立的逐条门 `autoInjectByAI`(不复用 autoUseByAI)。
+ *
+ * 跨进程:实际的 restoreCookiesToBrowser 在 desktop main(core 够不到 Electron
+ * session),经 `ctx.injectCredentialToBrowser` 回调(宿主注入,镜像 askUser)触发。
+ */
+import type { ToolDefinition } from "../types.js";
+import type { ToolContext } from "../tool-system/context.js";
+export declare const injectCredentialToolDef: ToolDefinition;
+/** 该工具仅在有 cookie 凭证 且 宿主接了注入回调时才可见(BUILTIN_TOOL_GUARDS)。 */
+export declare function isInjectCredentialAvailable(cwd: string): boolean;
+export declare function injectCredentialTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+/** 测试钩子:清空会话 allow 集。 */
+export declare function __resetInjectCredentialSessionAllowForTests(): void;