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

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 = {
@@ -41,6 +41,8 @@ export class ContextManager {
     config;
     summarizeFn;
     consecutiveSummaryFailures = 0;
+    /** Prevents repeated spin-band LLM calls after a summary generated no shrink. */
+    suppressNoOpMicroSummaryUntilCompact = false;
     lastSummary;
     /** Last known actual token count from API usage data. */
     lastActualTokens;
@@ -91,6 +93,64 @@ export class ContextManager {
     setSummarizeFn(fn) {
         this.summarizeFn = fn;
     }
+    async trySummaryCompact(messages, before, logEvent) {
+        if (!this.summarizeFn || this.consecutiveSummaryFailures >= 3) {
+            return { messages, tokens: before, compacted: false, noProgress: false };
+        }
+        try {
+            const keepRecentN = Math.max(8, Math.floor(messages.length * 0.3));
+            const messagesToSummarize = messages.slice(1, -keepRecentN); // skip first (userContext) and recent
+            if (messagesToSummarize.length <= 3) {
+                return { messages, tokens: before, compacted: false, noProgress: false };
+            }
+            // Rolling summary: if a prior summary is already anchored in the
+            // messages (from an earlier compaction in this session or in a resumed
+            // session), feed it back so the LLM merges-updates rather than
+            // re-summarizes from scratch.
+            const priorSummary = extractAnchoredSummary(messages) ?? this.lastSummary;
+            const prompt = buildSummarizationPrompt(messagesToSummarize, priorSummary);
+            const summary = await this.summarizeFn(prompt);
+            if (!summary || summary.length <= 50) {
+                this.consecutiveSummaryFailures++;
+                logger.warn("context.summary_failed", {
+                    failures: this.consecutiveSummaryFailures,
+                    error: "summary was empty or too short",
+                });
+                return { messages, tokens: before, compacted: false, noProgress: true };
+            }
+            const compacted = applySummaryCompaction(messages, summary, keepRecentN, this.transcriptPath);
+            const after = estimateTokens(compacted);
+            if (after >= before) {
+                this.consecutiveSummaryFailures++;
+                logger.warn("context.summary_no_progress", {
+                    failures: this.consecutiveSummaryFailures,
+                    before,
+                    after,
+                    summaryLen: summary.length,
+                    rolling: priorSummary !== undefined,
+                });
+                return { messages, tokens: before, compacted: false, noProgress: true };
+            }
+            this.consecutiveSummaryFailures = 0;
+            this.lastSummary = summary;
+            logger.info(logEvent, {
+                before,
+                after,
+                summaryLen: summary.length,
+                rolling: priorSummary !== undefined,
+            });
+            this.onCompact?.({ strategy: "summary", before, after });
+            return { messages: compacted, tokens: after, compacted: true, noProgress: false };
+        }
+        catch (err) {
+            this.consecutiveSummaryFailures++;
+            logger.warn("context.summary_failed", {
+                failures: this.consecutiveSummaryFailures,
+                error: err.message,
+            });
+            return { messages, tokens: before, compacted: false, noProgress: false };
+        }
+    }
     /**
      * Set the transcript path so compaction can reference it. The
      * tool-results directory lives alongside the transcript file:
@@ -127,6 +187,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.
@@ -221,7 +300,9 @@ export class ContextManager {
         result = applyToolResultBudget(result);
         // Tier 1: microcompact — see manage() for the rationale on the floor.
         const preTier1Tokens = this.estimateTokensHybrid(result);
-        if (preTier1Tokens > this.config.maxTokens * this.config.microcompactFloorRatio) {
+        const microFloorGate = this.config.maxTokens * this.config.microcompactFloorRatio;
+        let microNoOpAtFloor = false;
+        if (preTier1Tokens > microFloorGate) {
             const keepRecentN = this.config.microcompactKeepRecent ?? defaultKeepRecent(this.config.maxTokens);
             // See manage(): onClear fires synchronously before microcompact returns,
             // so defer the token re-estimate until result is reassigned.
@@ -232,63 +313,58 @@ export class ContextManager {
                     clearedInfo = info;
                 },
             });
+            const postTier1Tokens = this.estimateTokensHybrid(result);
+            microNoOpAtFloor = postTier1Tokens === preTier1Tokens;
+            if (postTier1Tokens < preTier1Tokens) {
+                this.suppressNoOpMicroSummaryUntilCompact = false;
+            }
             if (clearedInfo) {
-                const after = this.estimateTokensHybrid(result);
                 logger.info("context.microcompact", {
                     before: preTier1Tokens,
-                    after,
+                    after: postTier1Tokens,
                     keepRecentN,
                     clearedRounds: clearedInfo.clearedRounds,
                     toolNames: clearedInfo.toolNames,
                 });
-                this.onCompact?.({ strategy: "micro", before: preTier1Tokens, after });
+                this.onCompact?.({
+                    strategy: "micro",
+                    before: preTier1Tokens,
+                    after: postTier1Tokens,
+                });
             }
         }
-        const tokens = this.estimateTokensHybrid(result);
+        let tokens = this.estimateTokensHybrid(result);
         const ratio = tokens / this.config.maxTokens;
-        // Tier 2: LLM summary if approaching limit
-        if (ratio >= this.config.compactAtRatio &&
-            this.summarizeFn &&
-            this.consecutiveSummaryFailures < 3) {
-            try {
-                const keepRecentN = Math.max(8, Math.floor(result.length * 0.3));
-                const messagesToSummarize = result.slice(1, -keepRecentN); // skip first (userContext) and recent
-                if (messagesToSummarize.length > 3) {
-                    // Rolling summary: if a prior summary is already anchored in the
-                    // messages (from an earlier compaction in this session or in a
-                    // resumed session), feed it back so the LLM merges-updates rather
-                    // than re-summarizes from scratch — preserves info that would
-                    // otherwise erode across successive compactions.
-                    const priorSummary = extractAnchoredSummary(result) ?? this.lastSummary;
-                    const prompt = buildSummarizationPrompt(messagesToSummarize, priorSummary);
-                    const summary = await this.summarizeFn(prompt);
-                    if (summary && summary.length > 50) {
-                        result = applySummaryCompaction(result, summary, keepRecentN, this.transcriptPath);
-                        this.consecutiveSummaryFailures = 0;
-                        this.lastSummary = summary;
-                        const after = estimateTokens(result);
-                        logger.info("context.summary_compact", {
-                            before: tokens,
-                            after,
-                            summaryLen: summary.length,
-                            rolling: priorSummary !== undefined,
-                        });
-                        this.onCompact?.({ strategy: "summary", before: tokens, after });
-                        return result;
-                    }
-                }
+        if (ratio < this.config.microcompactFloorRatio) {
+            this.suppressNoOpMicroSummaryUntilCompact = false;
+        }
+        const noOpMicroSpinBand = microNoOpAtFloor &&
+            ratio >= this.config.microcompactFloorRatio &&
+            ratio < this.config.compactAtRatio;
+        const shouldEscalateNoOpMicro = noOpMicroSpinBand && !this.suppressNoOpMicroSummaryUntilCompact;
+        // Tier 2: LLM summary if approaching limit, or if micro was the only tier
+        // available in the 0.70-0.85 band and it freed nothing.
+        if (ratio >= this.config.compactAtRatio || shouldEscalateNoOpMicro) {
+            const summarized = await this.trySummaryCompact(result, tokens, "context.summary_compact");
+            result = summarized.messages;
+            tokens = summarized.tokens;
+            if (summarized.compacted) {
+                this.suppressNoOpMicroSummaryUntilCompact = false;
+                return result;
             }
-            catch (err) {
-                this.consecutiveSummaryFailures++;
-                logger.warn("context.summary_failed", {
-                    failures: this.consecutiveSummaryFailures,
-                    error: err.message,
+            if (shouldEscalateNoOpMicro && summarized.noProgress) {
+                this.suppressNoOpMicroSummaryUntilCompact = true;
+                logger.info("context.micro_noop_summary_suppressed", {
+                    tokens,
+                    ratio,
+                    compactAtRatio: this.config.compactAtRatio,
+                    microcompactFloorRatio: this.config.microcompactFloorRatio,
                 });
             }
         }
-        // Reuse the `tokens` we already computed above. We only get here if the
-        // LLM summary path didn't fire (no summarizeFn, too many failures, or it
-        // threw) — fall back to the same severity ladder as manage().
+        // Reuse the `tokens` we already computed above. We only get here if no
+        // summary compacted the prompt (no summarizeFn, too many failures, a
+        // thrown error, or a generated summary that did not shrink anything).
         let live = tokens;
         const snipGate = this.config.maxTokens * this.config.compactAtRatio;
         const windowGate = this.config.maxTokens * (this.config.compactAtRatio + 0.05);
@@ -317,6 +393,61 @@ export class ContextManager {
         }
         return result;
     }
+    /**
+     * Force maximum compaction, ignoring the ratio gates. This is what a manual
+     * `/compact` invokes: the user explicitly asked to shrink NOW, so we don't
+     * wait for the prompt to reach compactAtRatio.
+     *
+     * Order: tier-0 cleanups (persist/truncate/dedupe/mask) + microcompact, then
+     * an unconditional LLM summary of the older messages. If no summarizeFn is
+     * wired (or it fails / yields nothing), fall back to snip → window so the
+     * call still shrinks the conversation rather than no-opping.
+     *
+     * Unlike manage()/manageAsync(), there is NO `ratio >= compactAtRatio` gate:
+     * a long-but-under-threshold text-only conversation (the /compact bug) still
+     * gets summarized here.
+     */
+    async forceSummarize(messages) {
+        let result = messages;
+        // Tier 0: same waste-removal + micro as the automatic path.
+        result = this.persistLargeToolResults(result);
+        result = this.truncateToolResults(result);
+        result = applyToolResultBudget(result);
+        const dedup = dedupeFileReads(result);
+        if (dedup.clearedCount > 0)
+            result = dedup.messages;
+        const masked = maskOldObservations(result);
+        if (masked.maskedCount > 0)
+            result = masked.messages;
+        const keepRecentN = this.config.microcompactKeepRecent ?? defaultKeepRecent(this.config.maxTokens);
+        result = microcompact(result, { keepRecentN });
+        let tokens = this.estimateTokensHybrid(result);
+        // Unconditional LLM summary (no ratio gate).
+        {
+            const summarized = await this.trySummaryCompact(result, tokens, "context.force_summary_compact");
+            result = summarized.messages;
+            tokens = summarized.tokens;
+            if (summarized.compacted)
+                return result;
+        }
+        // Fallback: no summary available — snip, then window, so /compact still
+        // shrinks the conversation instead of no-opping.
+        {
+            const before = tokens;
+            result = snipCompact(result, 3, 8);
+            tokens = this.estimateTokensHybrid(result);
+            if (tokens < before)
+                this.onCompact?.({ strategy: "snip", before, after: tokens });
+        }
+        if (this.estimateTokensHybrid(result) >= this.estimateTokensHybrid(messages)) {
+            const before = tokens;
+            const keepN = Math.max(10, Math.floor(result.length * 0.4));
+            result = windowCompact(result, keepN);
+            tokens = this.estimateTokensHybrid(result);
+            this.onCompact?.({ strategy: "window", before, after: tokens });
+        }
+        return result;
+    }
     /**
      * Persist large tool_result blocks to disk and replace them with a
      * preview + filepath. No-op when transcript path hasn't been set
@@ -341,20 +472,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;
     }

package/dist/context/token-counter.js

@@ -69,11 +69,24 @@ function estimateBlockTokens(block) {
     if (block.content && typeof block.content === "string") {
         tokens += estimateStringTokens(block.content);
     }
+    else if (Array.isArray(block.content)) {
+        for (const nested of block.content) {
+            tokens += estimateBlockTokens(nested);
+        }
+    }
     if (block.input) {
         tokens += estimateStringTokens(JSON.stringify(block.input));
     }
     if (block.name)
         tokens += estimateStringTokens(block.name);
+    if (block.source?.data) {
+        tokens += estimateStringTokens(block.source.media_type);
+        tokens += estimateStringTokens(block.source.data);
+    }
+    const maybeOpenAI = block;
+    if (typeof maybeOpenAI.image_url?.url === "string") {
+        tokens += estimateStringTokens(maybeOpenAI.image_url.url);
+    }
     return tokens;
 }
 export function calculateContextUsage(messages, systemPrompt, maxTokens) {

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;