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

package/dist/cli/agent-server-tcp.js

@@ -23,6 +23,7 @@ import { ChatSessionManager } from "../protocol/chat-session-manager.js";
 import { AgentServer } from "../protocol/server.js";
 import { listenTcp } from "../protocol/tcp-transport.js";
 import { SettingsManager } from "../settings/manager.js";
+import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
 import { personalizationFrom } from "../settings/personalization.js";
 import { MCPManager } from "../tool-system/mcp-manager.js";
 import { mergePluginMcpServers } from "../plugins/installer/loadPluginMcp.js";
@@ -31,18 +32,24 @@ import { HeadlessApprovalBackend } from "../tool-system/permission.js";
 import { createRunManager } from "../run/factory.js";
 import { startAutomation } from "../automation/index.js";
 import { CronStore, defaultCronStorePath } from "../automation/store.js";
+import { resolveLLMConfigForTag } from "../engine/resolve-llm-config.js";
 const cwd = process.env.AGENT_CWD ?? process.cwd();
 const port = Number(process.env.AGENT_TCP_PORT ?? "4321");
 const host = process.env.AGENT_TCP_HOST ?? "127.0.0.1";
 const settingsManager = new SettingsManager(cwd, "full");
+// Read once at startup and reuse for every session (see engineFactory below).
+// This is intentional for the TCP host: it's a headless long-running server,
+// so config changes — including `mcpServers` — take effect on restart, not
+// mid-session. (The stdio host re-reads per session via freshSettings(); the
+// difference is by design, not a bug. Assessment §4.8.)
 const settings = settingsManager.get();
-const llmConfig = {
-    provider: settings.model.provider,
-    model: settings.model.name,
-    apiKey: settings.model.apiKey ?? "",
-    baseUrl: settings.model.baseUrl,
-    maxTokens: settings.model.maxTokens,
-};
+const seedLlm = resolveLLMConfigForTag(settings, "text", settings.defaults?.text);
+if (!seedLlm) {
+    console.error(`[agent-server] 没有可用的文本模型连接(defaults.text=${settings.defaults?.text ?? "未设置"})。` +
+        `请在「连接」页添加并填写凭证。`);
+    process.exit(1);
+}
+const llmConfig = seedLlm;
 // ── Shared runtime (same bootstrap as stdio) ─────────────────────
 const seedEngine = new Engine({ llm: llmConfig, cwd, settingsScope: "full" });
 const modelPool = seedEngine.getModelPool();
@@ -60,25 +67,32 @@ const runtime = new EngineRuntime({
 });
 const chatManager = new ChatSessionManager({
     runtime,
-    engineFactory: (slice) => new Engine({
-        llm: runtime.modelPool.resolveLLMConfig() ?? resolvedLlmConfig,
-        clientDefaults: resolvedClientDefaults,
-        cwd,
-        runtime,
-        settingsScope: "full",
-        mcpServers: mergePluginMcpServers(settings.mcpServers ?? {}, settings.disabledPlugins ?? []),
-        permissionMode: slice.permissionMode,
-        preset: slice.preset,
-        customSystemPrompt: slice.customSystemPrompt,
-        appendSystemPrompt: slice.appendSystemPrompt,
-        // Personalization + instruction compat come from disk settings only
-        // (not per-request slice overrides) — same disk-only contract as the
-        // stdio host. Shared helper keeps the three fields wired identically.
-        ...personalizationFrom(settings.agent),
-        maxTurns: slice.maxTurns,
-        maxContextTokens: slice.maxContextTokens,
-        ...(slice.cwd ? { cwd: slice.cwd } : {}),
-    }),
+    engineFactory: (slice) => {
+        // Fold project capabilityOverrides over the global disabledPlugins for
+        // the MCP merge (能力总览 project "on" must override global off) — same
+        // contract as the stdio host's factory.
+        const sessionCwd = slice.cwd ?? cwd;
+        const { disabledPlugins } = computeEffectiveDisabledLists(new SettingsManager(sessionCwd, "full"), sessionCwd);
+        return new Engine({
+            llm: runtime.modelPool.resolveLLMConfig() ?? resolvedLlmConfig,
+            clientDefaults: resolvedClientDefaults,
+            cwd,
+            runtime,
+            settingsScope: "full",
+            mcpServers: mergePluginMcpServers(settings.mcpServers ?? {}, disabledPlugins, settings.mcpServerOverrides ?? {}),
+            permissionMode: slice.permissionMode,
+            preset: slice.preset,
+            customSystemPrompt: slice.customSystemPrompt,
+            appendSystemPrompt: slice.appendSystemPrompt,
+            // Personalization + instruction compat come from disk settings only
+            // (not per-request slice overrides) — same disk-only contract as the
+            // stdio host. Shared helper keeps the three fields wired identically.
+            ...personalizationFrom(settings.agent),
+            maxTurns: slice.maxTurns,
+            maxContextTokens: slice.maxContextTokens,
+            ...(slice.cwd ? { cwd: slice.cwd } : {}),
+        });
+    },
     maxSessions: 16,
     idleTtlMs: 30 * 60 * 1000,
 });

package/dist/context/compaction.d.ts

@@ -16,6 +16,25 @@ import type { Message } from "../types.js";
  * Uses per-block-type estimation with 33% overhead padding.
  */
 export declare function estimateTokens(messages: Message[]): number;
+/**
+ * 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 declare function clampContextRatios(input: {
+    compactAtRatio?: number;
+    summarizeAtRatio?: number;
+    microcompactFloorRatio?: number;
+}): {
+    compactAtRatio?: number;
+    summarizeAtRatio?: number;
+    microcompactFloorRatio?: number;
+};
 /**
  * Expand a slice start-index backwards so that every tool_result in the
  * kept range has its corresponding tool_use in the kept range too.
@@ -74,6 +93,43 @@ export interface MicrocompactOptions {
  *    forced into blind re-Reads (which then trip the Investigation guard).
  */
 export declare function microcompact(messages: Message[], options?: MicrocompactOptions): Message[];
+export interface DedupeFileReadsResult {
+    messages: Message[];
+    /** How many stale Read results were cleared. */
+    clearedCount: number;
+}
+/**
+ * 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 declare function dedupeFileReads(messages: Message[]): DedupeFileReadsResult;
+/**
+ * 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 declare function maskOldObservations(messages: Message[]): {
+    messages: Message[];
+    maskedCount: number;
+};
 /**
  * Apply aggregate per-message tool result budget.
  * When total tool_result content in a single message exceeds maxTotalChars,

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,

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 = {
@@ -127,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.
@@ -341,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;
     }

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 [];
+    }
+}