c0de-agent 0.0.0 → 1.0.0

package/dist/core/metrics.js

@@ -0,0 +1,94 @@
+import { and, eq } from 'drizzle-orm';
+import { toolMetrics } from '../db/schema.js';
+/** 非 edit 工具的占位模式（这些工具只有一种实现，无需选择）。 */
+export const DEFAULT_TOOL_MODE = 'default';
+/** edit 工具在数据不足或历史不达标时使用的保守默认（spec §16.5）。 */
+export const DEFAULT_EDIT_MODE = 'diff';
+/** 推断某次工具调用使用的模式。
+ *  - edit：入参含 `patch` → hashline；否则 diff（search/replace）。
+ *  - 其他工具：固定 default（单实现，不参与模式选择）。 */
+export function inferToolMode(tool, input) {
+    if (tool === 'edit') {
+        if (input !== null && typeof input === 'object' && 'patch' in input)
+            return 'hashline';
+        return 'diff';
+    }
+    return DEFAULT_TOOL_MODE;
+}
+/** DB 行（Date 时间戳）→ 共享 ModelToolMetrics（number 时间戳）。 */
+function rowToMetrics(row) {
+    const lastUsed = row.lastUsed instanceof Date ? row.lastUsed.getTime() : new Date(row.lastUsed).getTime();
+    return {
+        model: row.model,
+        tool: row.tool,
+        mode: row.mode,
+        attempts: row.attempts,
+        successes: row.successes,
+        failures: row.failures,
+        avgLatencyMs: row.avgLatencyMs,
+        lastUsed,
+    };
+}
+/** 查某 (model, tool) 所有已记录模式的 metrics。 */
+export async function getToolMetrics(handle, model, tool) {
+    const rows = await handle.db
+        .select()
+        .from(toolMetrics)
+        .where(and(eq(toolMetrics.model, model), eq(toolMetrics.tool, tool)));
+    return rows.map(rowToMetrics);
+}
+/**
+ * 记录一次工具调用的结果（upsert）。avgLatencyMs 用增量滚动平均更新。
+ * PGLite 单进程，select-then-update 无并发竞争。
+ */
+export async function recordToolMetrics(handle, model, tool, mode, success, latencyMs) {
+    const whereMode = and(eq(toolMetrics.model, model), eq(toolMetrics.tool, tool), eq(toolMetrics.mode, mode));
+    const existing = await handle.db.select().from(toolMetrics).where(whereMode).limit(1);
+    if (existing.length === 0) {
+        await handle.db.insert(toolMetrics).values({
+            model,
+            tool,
+            mode,
+            attempts: 1,
+            successes: success ? 1 : 0,
+            failures: success ? 0 : 1,
+            avgLatencyMs: latencyMs,
+            lastUsed: new Date(),
+        });
+        return;
+    }
+    const row = existing[0];
+    if (!row)
+        return;
+    const attempts = row.attempts + 1;
+    const successes = row.successes + (success ? 1 : 0);
+    const failures = row.failures + (success ? 0 : 1);
+    // 滚动平均：新均值 = 旧均值 + (新值 - 旧均值) / n
+    const avgLatencyMs = row.avgLatencyMs + (latencyMs - row.avgLatencyMs) / attempts;
+    await handle.db
+        .update(toolMetrics)
+        .set({ attempts, successes, failures, avgLatencyMs, lastUsed: new Date() })
+        .where(whereMode);
+}
+/**
+ * 根据历史成功率选择最优工具模式（spec §16.5）。
+ * - 样本不足（attempts < minSamples）→ defaultMode
+ * - 成功率 >= threshold 的模式中取成功率最高（并列取样本最多者）
+ * - 无达标模式 → defaultMode
+ */
+export function selectBestMode(metrics, defaultMode, opts = {}) {
+    const threshold = opts.threshold ?? 0.8;
+    const minSamples = opts.minSamples ?? 5;
+    const eligible = metrics.filter((x) => x.attempts >= minSamples);
+    if (eligible.length === 0)
+        return defaultMode;
+    const good = eligible.filter((x) => x.successes / x.attempts >= threshold);
+    if (good.length === 0)
+        return defaultMode;
+    good.sort((a, b) => {
+        const ra = a.successes / a.attempts;
+        const rb = b.successes / b.attempts;
+        return rb - ra || b.attempts - a.attempts;
+    });
+    return good[0]?.mode ?? defaultMode;
+}

package/dist/core/prompt-registry.d.ts

@@ -0,0 +1,21 @@
+import type { PromptBuildContext, PromptRegistry, PromptSection } from './types.js';
+declare const ROLE_DESCRIPTION = "You are c0de-agent, an open-source AI coding assistant the team trusts with load-bearing changes. You help developers write, debug, and understand code across multiple languages and frameworks.\n\nYou operate autonomously: assume the user wants real changes and carry work through to completion end-to-end. Do not stop at analysis or partial fixes. The only times to pause and confirm are: before destructive git operations (commit, reset --hard, amend), before deleting code you did not write, and when a request is genuinely ambiguous between materially different approaches.\n\nPrioritize technical accuracy and truthfulness over validating the user's beliefs. Investigate before confirming; disagree respectfully when necessary. Objective guidance is more valuable than false agreement.";
+declare const ENGINEERING_PRINCIPLES = "# Engineering Principles\n- Optimize for correctness first, then for the next maintainer six months out.\n- You have agency and taste: delete code that isn't pulling its weight, refuse unnecessary abstractions, prefer boring when it's called for.\n- Consider what code compiles to. Never allocate avoidably; no needless copies or computation.\n- You are not alone in this repo. Treat unexpected changes as the user's work and adapt \u2014 never revert edits you did not make unless explicitly asked.";
+declare const TOOL_USAGE = "# Tool Usage\nYou have dedicated tools \u2014 prefer them over shell commands for file operations:\n- Reading a file or listing a directory \u2192 `read` (NOT `cat`, `head`, `tail`).\n- Finding files by name or pattern \u2192 `glob` (NOT `find`, `ls -R`).\n- Searching file contents \u2192 `grep` (NOT shell `grep`/`rg`/`ack`, NOT `awk`/`sed`).\n- Modifying files \u2192 `edit`/`write` (NOT `sed`, `echo >`, heredocs).\n\nReserve `bash` for genuine command execution: builds, tests, git, or short pipelines that compute a fact (`wc -l`, `git status`, `diff`, a checksum). Never explore a codebase with `find`/`ls`/`cat` when `read`/`glob`/`grep` can.\n\nBatch independent tool calls in a single response \u2014 parallelize file reads and independent lookups. Only sequence when one call's result informs the next.\n\nWhen referencing code, use the `file_path:line_number` pattern so the user can navigate directly.";
+declare const CODEBASE = "# Working with the Codebase\nBefore changing files, understand the existing conventions. Mimic code style, reuse existing utilities, and follow established patterns.\n- NEVER assume a library is available, even if well known. Check package.json (or equivalent) and neighboring files first.\n- When creating a new component, look at existing ones first for naming, typing, and framework conventions.\n- When editing, read the surrounding context (especially imports) to make the change idiomatic. Never introduce code that exposes or logs secrets.";
+declare const EXECUTION_WORKFLOW = "# Execution Workflow\n1. Scope \u2014 plan before touching files; research existing code and conventions.\n2. Research \u2014 read sections, not snippets. Reuse existing patterns; a second convention beside an existing one is prohibited.\n3. Decompose \u2014 break multi-step work into steps and track them; skip for trivial requests. Plan only what makes the request work.\n4. Implement \u2014 fix problems at the source. Remove obsolete code \u2014 no leftover comments, aliases, or re-exports. Prefer editing existing files over new ones.\n5. Verify \u2014 never yield non-trivial work without proof: run the relevant tests. Prefer testing behavior, not plumbing. Don't test defaults.\n6. Cleanup \u2014 changelog, tests, docs, and removing scaffolding are the LAST phase, gated on the request demonstrably working. Never pre-plan cleanup before the request works.";
+declare const VERIFICATION = "# Verification & Evidence\n- Never yield non-trivial work without proof: tests, builds, or QA.\n- Run lint and typecheck after changes if the project provides them.\n- Every claim about code, tools, or tests must be grounded. Mark anything not directly observed as [INFERENCE].\n- Verification claims must match what was actually exercised. A passing typecheck does not prove an integration.";
+declare const DELIVERY_CONTRACT = "# Delivery Contract\n- \"Done\" means the deliverable behaves as specified end-to-end \u2014 not that a scaffold compiles.\n- Never yield unless complete. A phase boundary is never a yield point.\n- Never suppress tests to make code pass. Never fabricate outputs.\n- Never substitute an easier problem: don't infer extra scope, don't treat the symptom unless asked.\n- Never ship stubs, placeholders, mocks, no-ops, or fake fallbacks as finished work.\n- Default to clean cutover: migrate every caller; leave no shims or aliases.";
+declare const GIT_SAFETY = "# Git & Safety\n- NEVER commit unless the user explicitly asks. Committing is too proactive.\n- NEVER use `git reset --hard` or `git checkout --` unless explicitly approved.\n- Do not amend a commit unless asked.\n- You may be in a dirty worktree. NEVER revert changes you did not make; if unrelated changes conflict with your task, stop and ask.";
+declare const TONE = "# Tone & Output\n- Be concise and direct. Lead with the conclusion, then the evidence.\n- No preamble or postamble (\"The answer is\u2026\", \"Here is what I'll do next\u2026\").\n- Use GitHub-flavored markdown. Only use emojis if explicitly asked.\n- Don't hide uncertainty: state it at the specific claim, name the tradeoff.\n- For a simple question, a one-liner is best.";
+export { CODEBASE, DELIVERY_CONTRACT, ENGINEERING_PRINCIPLES, EXECUTION_WORKFLOW, GIT_SAFETY, ROLE_DESCRIPTION, TONE, TOOL_USAGE, VERIFICATION, };
+/** Built-in section ids in priority order. */
+export declare const BUILTIN_SECTION_IDS: readonly ["role", "systemPrompt", "engineering", "tool-usage", "codebase", "constraints", "execution-workflow", "verification", "delivery-contract", "git-safety", "tone", "project", "skills", "agents", "slash-commands"];
+/** Create a registry pre-loaded with the built-in sections. */
+declare function createPromptRegistry(): PromptRegistry;
+/** Register a section. A later registration with the same id overrides the earlier
+ *  one (lets plugins replace builtins). */
+declare function registerPromptSection(registry: PromptRegistry, section: PromptSection): void;
+/** Assemble the system prompt: filter by condition, sort by priority, render. */
+declare function buildDynamicPrompt(registry: PromptRegistry, ctx: PromptBuildContext): string;
+export { buildDynamicPrompt, createPromptRegistry, registerPromptSection };

package/dist/core/prompt-registry.js

@@ -0,0 +1,200 @@
+import { builtinCommands } from './slash.js';
+// ── Static section bodies (shared with the legacy buildSystemPrompt) ──
+const ROLE_DESCRIPTION = `You are c0de-agent, an open-source AI coding assistant the team trusts with load-bearing changes. You help developers write, debug, and understand code across multiple languages and frameworks.
+
+You operate autonomously: assume the user wants real changes and carry work through to completion end-to-end. Do not stop at analysis or partial fixes. The only times to pause and confirm are: before destructive git operations (commit, reset --hard, amend), before deleting code you did not write, and when a request is genuinely ambiguous between materially different approaches.
+
+Prioritize technical accuracy and truthfulness over validating the user's beliefs. Investigate before confirming; disagree respectfully when necessary. Objective guidance is more valuable than false agreement.`;
+const ENGINEERING_PRINCIPLES = `# Engineering Principles
+- Optimize for correctness first, then for the next maintainer six months out.
+- You have agency and taste: delete code that isn't pulling its weight, refuse unnecessary abstractions, prefer boring when it's called for.
+- Consider what code compiles to. Never allocate avoidably; no needless copies or computation.
+- You are not alone in this repo. Treat unexpected changes as the user's work and adapt — never revert edits you did not make unless explicitly asked.`;
+const TOOL_USAGE = `# Tool Usage
+You have dedicated tools — prefer them over shell commands for file operations:
+- Reading a file or listing a directory → \`read\` (NOT \`cat\`, \`head\`, \`tail\`).
+- Finding files by name or pattern → \`glob\` (NOT \`find\`, \`ls -R\`).
+- Searching file contents → \`grep\` (NOT shell \`grep\`/\`rg\`/\`ack\`, NOT \`awk\`/\`sed\`).
+- Modifying files → \`edit\`/\`write\` (NOT \`sed\`, \`echo >\`, heredocs).
+
+Reserve \`bash\` for genuine command execution: builds, tests, git, or short pipelines that compute a fact (\`wc -l\`, \`git status\`, \`diff\`, a checksum). Never explore a codebase with \`find\`/\`ls\`/\`cat\` when \`read\`/\`glob\`/\`grep\` can.
+
+Batch independent tool calls in a single response — parallelize file reads and independent lookups. Only sequence when one call's result informs the next.
+
+When referencing code, use the \`file_path:line_number\` pattern so the user can navigate directly.`;
+const CODEBASE = `# Working with the Codebase
+Before changing files, understand the existing conventions. Mimic code style, reuse existing utilities, and follow established patterns.
+- NEVER assume a library is available, even if well known. Check package.json (or equivalent) and neighboring files first.
+- When creating a new component, look at existing ones first for naming, typing, and framework conventions.
+- When editing, read the surrounding context (especially imports) to make the change idiomatic. Never introduce code that exposes or logs secrets.`;
+const PARADIGM_CONSTRAINTS = `# Coding Paradigm
+This project follows a strict data + functions paradigm:
+- Use \`type\` (not \`interface\`) for type definitions.
+- Use discriminated unions with \`_tag\` fields for variant types.
+- Use plain functions \`export function foo(ctx, ...)\` with context-first argument.
+- No classes; prefer factory functions and pure data transformation.
+- Prefer \`import type\` for type-only imports.`;
+const EXECUTION_WORKFLOW = `# Execution Workflow
+1. Scope — plan before touching files; research existing code and conventions.
+2. Research — read sections, not snippets. Reuse existing patterns; a second convention beside an existing one is prohibited.
+3. Decompose — break multi-step work into steps and track them; skip for trivial requests. Plan only what makes the request work.
+4. Implement — fix problems at the source. Remove obsolete code — no leftover comments, aliases, or re-exports. Prefer editing existing files over new ones.
+5. Verify — never yield non-trivial work without proof: run the relevant tests. Prefer testing behavior, not plumbing. Don't test defaults.
+6. Cleanup — changelog, tests, docs, and removing scaffolding are the LAST phase, gated on the request demonstrably working. Never pre-plan cleanup before the request works.`;
+const VERIFICATION = `# Verification & Evidence
+- Never yield non-trivial work without proof: tests, builds, or QA.
+- Run lint and typecheck after changes if the project provides them.
+- Every claim about code, tools, or tests must be grounded. Mark anything not directly observed as [INFERENCE].
+- Verification claims must match what was actually exercised. A passing typecheck does not prove an integration.`;
+const DELIVERY_CONTRACT = `# Delivery Contract
+- "Done" means the deliverable behaves as specified end-to-end — not that a scaffold compiles.
+- Never yield unless complete. A phase boundary is never a yield point.
+- Never suppress tests to make code pass. Never fabricate outputs.
+- Never substitute an easier problem: don't infer extra scope, don't treat the symptom unless asked.
+- Never ship stubs, placeholders, mocks, no-ops, or fake fallbacks as finished work.
+- Default to clean cutover: migrate every caller; leave no shims or aliases.`;
+const GIT_SAFETY = `# Git & Safety
+- NEVER commit unless the user explicitly asks. Committing is too proactive.
+- NEVER use \`git reset --hard\` or \`git checkout --\` unless explicitly approved.
+- Do not amend a commit unless asked.
+- You may be in a dirty worktree. NEVER revert changes you did not make; if unrelated changes conflict with your task, stop and ask.`;
+const TONE = `# Tone & Output
+- Be concise and direct. Lead with the conclusion, then the evidence.
+- No preamble or postamble ("The answer is…", "Here is what I'll do next…").
+- Use GitHub-flavored markdown. Only use emojis if explicitly asked.
+- Don't hide uncertainty: state it at the specific claim, name the tradeoff.
+- For a simple question, a one-liner is best.`;
+export { CODEBASE, DELIVERY_CONTRACT, ENGINEERING_PRINCIPLES, EXECUTION_WORKFLOW, GIT_SAFETY, ROLE_DESCRIPTION, TONE, TOOL_USAGE, VERIFICATION, };
+// ── Registry ──────────────────────────────────────────────
+/** Built-in section ids in priority order. */
+export const BUILTIN_SECTION_IDS = [
+    'role',
+    'systemPrompt',
+    'engineering',
+    'tool-usage',
+    'codebase',
+    'constraints',
+    'execution-workflow',
+    'verification',
+    'delivery-contract',
+    'git-safety',
+    'tone',
+    'project',
+    'skills',
+    'agents',
+    'slash-commands',
+];
+/** Built-in sections. Dynamic bodies (tool list, project info, skills) use `render`. */
+function builtinSections() {
+    return [
+        { id: 'role', content: ROLE_DESCRIPTION, priority: 0 },
+        {
+            id: 'systemPrompt',
+            content: '',
+            priority: 5,
+            condition: (c) => Boolean(c.config.systemPrompt),
+            render: (c) => c.config.systemPrompt ?? '',
+        },
+        { id: 'engineering', content: ENGINEERING_PRINCIPLES, priority: 10 },
+        {
+            id: 'tool-usage',
+            content: '',
+            priority: 20,
+            condition: (c) => c.tools.length > 0,
+            render: (c) => {
+                const lines = ['## Available Tools'];
+                for (const tool of c.tools)
+                    lines.push(`- **${tool.name}**: ${tool.description}`);
+                lines.push(TOOL_USAGE);
+                return lines.join('\n');
+            },
+        },
+        { id: 'codebase', content: CODEBASE, priority: 30 },
+        { id: 'constraints', content: PARADIGM_CONSTRAINTS, priority: 40 },
+        { id: 'execution-workflow', content: EXECUTION_WORKFLOW, priority: 50 },
+        { id: 'verification', content: VERIFICATION, priority: 60 },
+        { id: 'delivery-contract', content: DELIVERY_CONTRACT, priority: 70 },
+        { id: 'git-safety', content: GIT_SAFETY, priority: 80 },
+        { id: 'tone', content: TONE, priority: 90 },
+        {
+            id: 'project',
+            content: '',
+            priority: 100,
+            render: (c) => {
+                const lines = ['## Project Context'];
+                lines.push(`- Name: ${c.projectInfo.name}`);
+                lines.push(`- Language: ${c.projectInfo.language}`);
+                if (c.projectInfo.framework)
+                    lines.push(`- Framework: ${c.projectInfo.framework}`);
+                lines.push(`- Root: ${c.projectInfo.rootDir}`);
+                if (c.projectInfo.gitBranch)
+                    lines.push(`- Git Branch: ${c.projectInfo.gitBranch}`);
+                return lines.join('\n');
+            },
+        },
+        {
+            id: 'skills',
+            content: '',
+            priority: 110,
+            condition: (c) => Boolean(c.skills && c.skills.length > 0),
+            render: (c) => {
+                const lines = ['## Loaded Skills'];
+                for (const skill of c.skills ?? [])
+                    lines.push(`- ${skill}`);
+                return lines.join('\n');
+            },
+        },
+        // spec §17.2：有子 agent 时列出可委托 agent（插件/配置注入）。
+        {
+            id: 'agents',
+            content: '',
+            priority: 115,
+            condition: (c) => Boolean(c.agents && c.agents.length > 0),
+            render: (c) => {
+                const lines = ['## Available Agents'];
+                for (const agent of c.agents ?? [])
+                    lines.push(`- ${agent}`);
+                return lines.join('\n');
+            },
+        },
+        // spec §17.2：始终列出可用 slash 命令，让模型知道可调用哪些命令。
+        {
+            id: 'slash-commands',
+            content: '',
+            priority: 120,
+            render: () => {
+                const lines = ['## Slash Commands'];
+                for (const cmd of builtinCommands)
+                    lines.push(`- /${cmd.name}: ${cmd.description}`);
+                return lines.join('\n');
+            },
+        },
+    ];
+}
+/** Create a registry pre-loaded with the built-in sections. */
+function createPromptRegistry() {
+    const registry = { sections: new Map() };
+    for (const section of builtinSections()) {
+        registry.sections.set(section.id, section);
+    }
+    return registry;
+}
+/** Register a section. A later registration with the same id overrides the earlier
+ *  one (lets plugins replace builtins). */
+function registerPromptSection(registry, section) {
+    registry.sections.set(section.id, section);
+}
+/** Assemble the system prompt: filter by condition, sort by priority, render. */
+function buildDynamicPrompt(registry, ctx) {
+    const sections = Array.from(registry.sections.values())
+        .filter((s) => !s.condition || s.condition(ctx))
+        .sort((a, b) => a.priority - b.priority);
+    const parts = [];
+    for (const section of sections) {
+        const body = section.render ? section.render(ctx) : section.content;
+        if (body.length > 0)
+            parts.push(body);
+    }
+    return parts.join('\n\n');
+}
+export { buildDynamicPrompt, createPromptRegistry, registerPromptSection };

package/dist/core/prompt.d.ts

@@ -0,0 +1,11 @@
+import type { PromptContext } from './types.js';
+/**
+ * Build the system prompt for an agent run.
+ *
+ * Legacy entry point kept for backward compatibility with `agentLoop` and
+ * existing call sites. Internally assembles via the dynamic prompt registry
+ * (spec §17): a default registry seeded with the built-in sections, so plugins
+ * that register custom sections on the same registry are reflected.
+ */
+declare function buildSystemPrompt(ctx: PromptContext): string;
+export { buildSystemPrompt };

package/dist/core/prompt.js

@@ -0,0 +1,13 @@
+import { buildDynamicPrompt, createPromptRegistry } from './prompt-registry.js';
+/**
+ * Build the system prompt for an agent run.
+ *
+ * Legacy entry point kept for backward compatibility with `agentLoop` and
+ * existing call sites. Internally assembles via the dynamic prompt registry
+ * (spec §17): a default registry seeded with the built-in sections, so plugins
+ * that register custom sections on the same registry are reflected.
+ */
+function buildSystemPrompt(ctx) {
+    return buildDynamicPrompt(createPromptRegistry(), ctx);
+}
+export { buildSystemPrompt };

package/dist/core/secret.d.ts

@@ -0,0 +1,12 @@
+/** 判断存储值是否已加密（带 enc: 前缀）。 */
+export declare function isEncryptedSecret(stored: string): boolean;
+/**
+ * 加密一个敏感值（如 provider apiKey），返回 `enc:` 前缀的 base64 串。
+ * 使用 AES-256-GCM + 随机 IV + 机器绑定密钥（spec §24.2「keyring 或加密文件」）。
+ * 机器绑定意味着密文不可跨机器解密——apiKey 本就该在各机器重新配置。
+ */
+export declare function encryptSecret(plaintext: string): string;
+/**
+ * 解密存储值。带 `enc:` 前缀则解密；否则原样返回（明文兼容，平滑迁移）。
+ */
+export declare function decryptSecret(stored: string): string;

package/dist/core/secret.js

@@ -0,0 +1,51 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+import { hostname, userInfo } from 'node:os';
+/** 加密值的存储前缀。无此前缀的值视为明文（向后兼容）。 */
+const PREFIX = 'enc:';
+/** 密钥派生盐（固定；机器绑定由 hostname+username 提供）。 */
+const SALT = 'c0de-agent-apikey-v1';
+/** 机器标识，用于派生加密密钥。userInfo 失败时回退到环境变量。 */
+function machineId() {
+    try {
+        return `${hostname()}:${userInfo().username}`;
+    }
+    catch {
+        return `${hostname()}:${process.env.USER ?? 'anonymous'}`;
+    }
+}
+/** 派生 256 位 AES 密钥（机器绑定）。 */
+function deriveKey() {
+    return scryptSync(machineId(), SALT, 32);
+}
+/** 判断存储值是否已加密（带 enc: 前缀）。 */
+export function isEncryptedSecret(stored) {
+    return stored.startsWith(PREFIX);
+}
+/**
+ * 加密一个敏感值（如 provider apiKey），返回 `enc:` 前缀的 base64 串。
+ * 使用 AES-256-GCM + 随机 IV + 机器绑定密钥（spec §24.2「keyring 或加密文件」）。
+ * 机器绑定意味着密文不可跨机器解密——apiKey 本就该在各机器重新配置。
+ */
+export function encryptSecret(plaintext) {
+    const key = deriveKey();
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const enc = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return PREFIX + Buffer.concat([iv, tag, enc]).toString('base64');
+}
+/**
+ * 解密存储值。带 `enc:` 前缀则解密；否则原样返回（明文兼容，平滑迁移）。
+ */
+export function decryptSecret(stored) {
+    if (!stored.startsWith(PREFIX))
+        return stored;
+    const buf = Buffer.from(stored.slice(PREFIX.length), 'base64');
+    const iv = buf.subarray(0, 12);
+    const tag = buf.subarray(12, 28);
+    const enc = buf.subarray(28);
+    const key = deriveKey();
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8');
+}

package/dist/core/slash.d.ts

@@ -0,0 +1,15 @@
+import type { SlashCommand } from './types.js';
+declare function parseSlashInput(input: string): {
+    name: string;
+    args: string;
+} | null;
+type SlashRegistry = {
+    has: (name: string) => boolean;
+    get: (name: string) => SlashCommand | undefined;
+    list: () => SlashCommand[];
+    register: (cmd: SlashCommand) => void;
+};
+declare function createSlashRegistry(): SlashRegistry;
+declare const builtinCommands: SlashCommand[];
+export type { SlashRegistry };
+export { builtinCommands, createSlashRegistry, parseSlashInput };

package/dist/core/slash.js

@@ -0,0 +1,114 @@
+function parseSlashInput(input) {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith('/'))
+        return null;
+    const spaceIdx = trimmed.indexOf(' ');
+    if (spaceIdx === -1) {
+        return { name: trimmed.slice(1), args: '' };
+    }
+    return { name: trimmed.slice(1, spaceIdx), args: trimmed.slice(spaceIdx + 1).trim() };
+}
+function createSlashRegistry() {
+    const commands = new Map();
+    for (const cmd of builtinCommands) {
+        commands.set(cmd.name, cmd);
+    }
+    return {
+        has: (name) => commands.has(name),
+        get: (name) => commands.get(name),
+        list: () => Array.from(commands.values()),
+        register: (cmd) => commands.set(cmd.name, cmd),
+    };
+}
+const helpCommand = {
+    name: 'help',
+    description: 'List available slash commands',
+    execute: async () => {
+        const lines = [
+            'Available commands:',
+            '  /compact        Manually trigger context compaction',
+            '  /model <name>   Switch the current session model',
+            '  /clear          Clear session messages',
+            '  /help           Show this help',
+            '  /fork [index]   Fork session from a message',
+            '  /config [k][v]  View or set configuration',
+        ];
+        return { _tag: 'text', text: lines.join('\n') };
+    },
+};
+const compactCommand = {
+    name: 'compact',
+    description: 'Manually trigger context compaction',
+    execute: async () => {
+        return {
+            _tag: 'success',
+            message: 'Compaction queued. Use the agent API to trigger with a summarizer.',
+        };
+    },
+};
+const modelCommand = {
+    name: 'model',
+    description: 'Switch the current session model',
+    argsHint: '<model-name>',
+    execute: async (args) => {
+        if (!args)
+            return { _tag: 'error', message: 'Usage: /model <model-name>' };
+        return { _tag: 'success', message: `Model set to ${args} (takes effect next turn)` };
+    },
+};
+const clearCommand = {
+    name: 'clear',
+    description: 'Clear session messages',
+    execute: async (args, ctx) => {
+        if (!args)
+            return { _tag: 'error', message: 'Usage: /clear <session-id>' };
+        const { deleteEntriesByIds, getEntries } = await import('../session/message.js');
+        const entries = await getEntries(ctx.deps.db, args);
+        const ids = entries.map((e) => ('id' in e ? e.id : '')).filter(Boolean);
+        if (ids.length > 0) {
+            await deleteEntriesByIds(ctx.deps.db, ids);
+        }
+        return { _tag: 'success', message: `Cleared ${ids.length} entries` };
+    },
+};
+const forkCommand = {
+    name: 'fork',
+    description: 'Fork session from a message index',
+    argsHint: '<session-id> [message-index]',
+    execute: async (args, ctx) => {
+        if (!args)
+            return { _tag: 'error', message: 'Usage: /fork <session-id> [message-index]' };
+        const parts = args.split(/\s+/);
+        const sessionId = parts[0] ?? '';
+        const messageIndex = parts[1] !== undefined ? Number.parseInt(parts[1], 10) : 0;
+        const { forkSession } = await import('../session/branch.js');
+        const forked = await forkSession(ctx.deps.db, sessionId, messageIndex);
+        return { _tag: 'success', message: `Forked to new session: ${forked.id}` };
+    },
+};
+const configCommand = {
+    name: 'config',
+    description: 'View or set configuration',
+    argsHint: '[key] [value]',
+    execute: async (args, ctx) => {
+        if (!args) {
+            return { _tag: 'text', text: JSON.stringify(ctx.config, null, 2) };
+        }
+        const parts = args.split(/\s+/);
+        const key = parts[0] ?? '';
+        if (parts.length === 1) {
+            const value = ctx.config[key];
+            return { _tag: 'text', text: `${key}: ${JSON.stringify(value)}` };
+        }
+        return { _tag: 'success', message: 'Config updates are handled via the config API' };
+    },
+};
+const builtinCommands = [
+    helpCommand,
+    compactCommand,
+    modelCommand,
+    clearCommand,
+    forkCommand,
+    configCommand,
+];
+export { builtinCommands, createSlashRegistry, parseSlashInput };

package/dist/core/steering.d.ts

@@ -0,0 +1,8 @@
+import type { AgentState } from '../shared/types/agent.js';
+/** Add a steering message to the queue. Takes effect before the next LLM turn. */
+declare function injectSteering(state: AgentState, message: string): void;
+/** Remove and return all queued steering messages (FIFO order). Clears the queue. */
+declare function drainSteering(state: AgentState): string[];
+/** Discard all queued steering messages without returning them. */
+declare function clearSteering(state: AgentState): void;
+export { clearSteering, drainSteering, injectSteering };

package/dist/core/steering.js

@@ -0,0 +1,15 @@
+/** Add a steering message to the queue. Takes effect before the next LLM turn. */
+function injectSteering(state, message) {
+    state.steeringQueue.push(message);
+}
+/** Remove and return all queued steering messages (FIFO order). Clears the queue. */
+function drainSteering(state) {
+    const messages = [...state.steeringQueue];
+    state.steeringQueue.length = 0;
+    return messages;
+}
+/** Discard all queued steering messages without returning them. */
+function clearSteering(state) {
+    state.steeringQueue.length = 0;
+}
+export { clearSteering, drainSteering, injectSteering };

package/dist/core/title.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 会话标题自动生成。
+ *
+ * 设计参考 opencode 的 `ensureTitle`：在第一条用户消息后，用一个 smol/快速
+ * 模型为会话生成简短标题。fire-and-forget，失败仅吞掉，绝不阻塞主对话流。
+ *
+ * 模型解析遵循 chat 路由的同款策略（见 server/routes/chat.ts）：优先
+ * `config.roleRouting.smol`，未配置则回退 `defaultProvider/defaultModel`。
+ * 不走 registry.resolveModelByRole——因为运行时 buildRegistryFromConfig 只
+ * 注册 provider 路由、并未把 roleRouting 绑定到 registry.roles，角色解析会
+ * 直接抛 NoRoute。
+ */
+import type { DB } from '../db/client.js';
+import { chat as defaultChat } from '../llm/provider.js';
+import type { Registry } from '../llm/registry.js';
+import type { Config } from './config.js';
+/** 会话默认占位标题；仍是该值时才有资格自动生成。 */
+declare const DEFAULT_SESSION_TITLE = "New Session";
+/** 注入点：可覆盖的非流式 chat 函数（测试用）。 */
+type ChatFn = typeof defaultChat;
+/** 标题生成所需的最小依赖（AgentDependencies 的结构子集）。 */
+type TitleDeps = {
+    db: DB;
+    llmRegistry: Registry;
+    config: Config;
+    /** 可选注入 chat 实现；默认走真实 llm/provider。 */
+    chatFn?: ChatFn;
+};
+/** 会话标题是否仍是默认占位值。 */
+declare function isDefaultTitle(title: string): boolean;
+/**
+ * 为会话生成标题并持久化。fire-and-forget 语义：任何错误都被吞掉，
+ * 绝不向调用方抛出，绝不覆盖一个已存在的非默认标题。
+ *
+ * @param deps          最小依赖（含可注入的 chatFn）
+ * @param sessionId     目标会话 id
+ * @param firstMessage  第一条用户消息原文
+ * @param chatProvider  会话实际使用的 LLM provider（AgentConfig.provider）
+ * @param chatModel     会话实际使用的 LLM model（AgentConfig.model）
+ */
+declare function generateSessionTitle(deps: TitleDeps, sessionId: string, firstMessage: string, chatProvider: string, chatModel: string): Promise<void>;
+export { DEFAULT_SESSION_TITLE, generateSessionTitle, isDefaultTitle };