xitto-kernel 0.1.0

package/src/kernel/index.js

@@ -0,0 +1,291 @@
+// Kernel 組裝 — 把一個 DomainPack 接上領域無關的執行期。
+// 確定性那半部：pack 載入、工具註冊、mutatingTools 推導、固定順序守衛鏈、systemPrompt 組裝、
+// 單一工具呼叫（runTool）。LLM 那半部：runTurn 驅動移植自 xitto-code 的 Agent loop
+// （串流 + 多步工具循環 + 守衛接線）。壓縮/TUI 仍為後續接縫。
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join, dirname, isAbsolute } from 'node:path';
+import { loadPack } from './pack-loader.js';
+import { createToolRegistry, deriveMutatingTools, isSandboxable } from './tool-registry.js';
+import { composeGuards } from './guard-chain.js';
+import { createPermissionStep } from './security/permission-step.js';
+import { normalizeSandbox, wrapWithSeatbelt } from './security/sandbox.js';
+import { createMemory } from './memory.js';
+import { createSpawnTool } from './subagent.js';
+import { createSkills } from './skills.js';
+import { loadHooks, runPreToolHooks, runPostToolHooks } from './hooks.js';
+import { maybeCompact, resolveCompactionSettings } from './compaction.js';
+import { newSessionId, saveSession, loadSession, listSessions, latestSession } from './session.js';
+
+// 載入 pack.contextFiles：從 cwd 逐層往上找每個檔名，找到就讀入並注入 system prompt（領域規範）。
+// 對標 xitto-code 的 CLAUDE.md/AGENTS.md 載入；但檔名由 pack 決定（kernel 不認識具體檔名）。
+function loadContextFiles(cwd, names) {
+  if (!Array.isArray(names) || !names.length) return '';
+  const found = [];
+  for (const name of names) {
+    let dir = cwd;
+    for (;;) {
+      const p = join(dir, name);
+      if (existsSync(p)) { try { found.push({ name, text: readFileSync(p, 'utf8') }); } catch { /* 略 */ } break; }
+      const parent = dirname(dir);
+      if (parent === dir) break; // 到根目錄
+      dir = parent;
+    }
+  }
+  if (!found.length) return '';
+  return '\n\n# 專案規範（讀自下列檔案，請遵守）\n' +
+    found.map((f) => `## ${f.name}\n${f.text.trim()}`).join('\n\n');
+}
+
+const DEFAULT_MEMORY_GUIDE =
+  '遇到值得跨 session 記住的事實（使用者偏好、建置/測試指令、踩過的坑、專案決策）時，當下就存一條。';
+
+// 把 sandboxable 工具的命令在執行期包進 Seatbelt（macOS OS 級隔離）。
+// 非 macOS / 沙箱關閉 / 無 command → wrapWithSeatbelt 回 null，跑原命令（仍受第 5 格靜態策略保護）。
+function wrapSandboxable(tool, { cwd, getSandbox, getSandboxConfig }) {
+  if (!isSandboxable(tool) || typeof tool.execute !== 'function') return tool;
+  const orig = tool.execute.bind(tool);
+  return {
+    ...tool,
+    execute: (id, params, ...rest) => {
+      if (getSandbox?.() && params?.command) {
+        const wrapped = wrapWithSeatbelt(params.command, { cwd, cfg: getSandboxConfig?.() });
+        if (wrapped) params = { ...params, command: wrapped };
+      }
+      return orig(id, params, ...rest);
+    },
+  };
+}
+
+// undo 快照：mutating 且帶 args.path 的工具（檔案編輯類），執行前記錄檔案原狀，供 kernel.undo() 還原。
+// 「以 path 指涉被改檔案」是常見約定；非檔案型 mutating 工具（bash/sql_exec 無 path）不受影響。
+function wrapUndo(tool, { cwd, undoStack }) {
+  if (tool.mutating !== true || typeof tool.execute !== 'function') return tool;
+  const orig = tool.execute.bind(tool);
+  return {
+    ...tool,
+    execute: (id, params, ...rest) => {
+      if (params?.path) {
+        const p = isAbsolute(params.path) ? params.path : join(cwd, params.path);
+        try {
+          undoStack.push({ path: p, rel: params.path, before: existsSync(p) ? readFileSync(p, 'utf8') : null });
+          if (undoStack.length > 50) undoStack.shift();
+        } catch { /* 略 */ }
+      }
+      return orig(id, params, ...rest);
+    },
+  };
+}
+
+/**
+ * 建立 kernel 執行期。
+ * @param {import('../types.js').DomainPack} pack
+ * @param {Object} [config]
+ * @param {string} [config.cwd]
+ * @param {() => boolean} [config.getPlanMode]                 計劃模式狀態（預設關）
+ * @param {(ctx: object) => import('../types.js').PolicyDecision} [config.circuitBreaker] 上下文熔斷（預設不熔斷）
+ * @param {(ctx: object) => import('../types.js').PolicyDecision} [config.preToolHooks]   使用者 PreToolUse hooks（預設無）
+ * @param {(name: string, args: object) => Promise<'yes'|'no'>} [config.confirm]          mutating 工具的確認（預設放行）
+ * @param {Partial<import('../types.js').KernelServices>} [config.services]
+ * @param {object} [config.model]                              LLM model 物件（runTurn 需要）
+ * @param {(provider: string) => string|Promise<string>} [config.getApiKey]               取 API key（runTurn 需要）
+ * @param {Function} [config.streamFn]                         注入串流（測試用 fake provider）；預設用 pi-ai
+ * @param {'off'|'low'|'medium'|'high'} [config.thinkingLevel] 推理強度（預設依 model.reasoning）
+ */
+export function createKernel(pack, config = {}) {
+  loadPack(pack);
+  const cwd = config.cwd || process.cwd();
+
+  // 每個 pack 在 cwd 下有獨立資料夾（記憶、session 分領域存放，互不混）
+  const dataDir = join(cwd, '.xitto-kernel', pack.name);
+  const memory = createMemory(join(dataDir, 'memory.md'));
+  const sessionsDir = join(dataDir, 'sessions');
+  const hooks = loadHooks(join(dataDir, 'settings.json')); // PreToolUse/PostToolUse
+  const skills = createSkills(join(dataDir, 'skills'));     // 漸進揭露技能
+
+  // 沙箱策略：config.sandbox > pack.permissionPolicy.sandbox > 預設（關）。
+  const sandboxCfg = normalizeSandbox(config.sandbox ?? pack.permissionPolicy?.sandbox);
+  const getSandbox = config.getSandbox || (() => !!sandboxCfg.enabled);
+  const getSandboxConfig = () => sandboxCfg;
+
+  // 工具：pack 工具（sandboxable 包 Seatbelt、mutating+path 加 undo 快照）+ kernel 內建記憶工具 + spawn_agent。
+  const undoStack = [];
+  const baseTools = [
+    ...pack.tools().map((t) => wrapUndo(wrapSandboxable(t, { cwd, getSandbox, getSandboxConfig }), { cwd, undoStack })),
+    ...memory.tools,
+    ...(skills.tool ? [skills.tool] : []),
+    ...(config.extraTools || []),  // 外部注入（MCP 工具等）：由 app 層先 async 載入再傳入
+  ];
+  // spawn_agent：派唯讀子 agent。其可用工具 = 所有唯讀工具（不含 spawn_agent 自己，避免遞迴）。
+  let allTools = baseTools;
+  const spawnTool = createSpawnTool({
+    getModel: () => config.model,
+    getApiKey: config.getApiKey,
+    getReadOnlyTools: () => allTools.filter((t) => t.readOnly === true && t.name !== 'spawn_agent'),
+  });
+  const tools = [...baseTools, spawnTool];
+  allTools = tools;
+  const registry = createToolRegistry(tools);
+  const mutatingTools = new Set(deriveMutatingTools(pack, tools));
+  const services = {
+    cwd,
+    memory: { save: memory.save, list: memory.list },
+    sandbox: { isOn: () => getSandbox(), config: () => getSandboxConfig() },
+    ...(config.services || {}),
+  };
+
+  const memText = memory.load();
+  const systemPrompt =
+    pack.systemPrompt +
+    loadContextFiles(cwd, pack.contextFiles) +          // 注入領域規範檔（CLAUDE.md 等）
+    '\n\n# 記憶\n' + (pack.memoryGuide || DEFAULT_MEMORY_GUIDE) +
+    (memText ? `\n\n# 已記住的事實（跨 session）\n${memText}` : '') +
+    skills.promptSection();
+
+  const getPlanMode = config.getPlanMode || (() => false);
+
+  // 守衛鏈第 5 格：真實權限/沙箱（A 半部：靜態策略 deny/網路/提權/越界寫入 + 危險命令）。
+  const permission = createPermissionStep({
+    registry, getSandbox, getSandboxConfig,
+    deny: pack.permissionPolicy?.deny || [],
+    confirm: config.confirm,
+  });
+
+  const guard = composeGuards({
+    planGuard: (ctx) => (getPlanMode() && mutatingTools.has(ctx.name)
+      ? { block: true, reason: '計劃模式：只能規劃不能執行。請描述你打算怎麼做。' }
+      : undefined),
+    circuitBreaker: config.circuitBreaker || (() => undefined),
+    packPreTool: pack.preToolPolicy,
+    preToolHooks: config.preToolHooks || ((ctx) => runPreToolHooks(hooks, ctx.name, cwd)), // 第 4 格：PreToolUse
+    permission,
+    services,
+  });
+
+  return {
+    pack,
+    registry,
+    mutatingTools,
+    systemPrompt,
+    services,
+    permissionPolicy: pack.permissionPolicy || {},
+    sandbox: { isOn: () => getSandbox(), config: () => getSandboxConfig() },
+    memory,
+    /** 撤銷上一次檔案改動（write/edit）：還原內容，新建的檔則刪除。 */
+    undo: () => {
+      const snap = undoStack.pop();
+      if (!snap) return { undone: false, reason: '沒有可撤銷的改動' };
+      try {
+        if (snap.before === null) { if (existsSync(snap.path)) unlinkSync(snap.path); }
+        else writeFileSync(snap.path, snap.before, 'utf8');
+        return { undone: true, path: snap.rel, created: snap.before === null };
+      } catch (e) { return { undone: false, reason: e.message }; }
+    },
+    // session 持久化 / resume（按 pack 分目錄）。CLI 用它存檔與續接。
+    session: {
+      dir: sessionsDir,
+      newId: () => newSessionId(),
+      save: (id, messages) => saveSession(sessionsDir, id, { messages, model: config.model }),
+      load: (id) => loadSession(sessionsDir, id),
+      list: () => listSessions(sessionsDir),
+      latest: () => latestSession(sessionsDir),
+    },
+    /** 對一次工具呼叫跑守衛鏈，回傳決策（不執行）。 */
+    guardToolCall: (toolCall) => guard(toolCall),
+    /**
+     * 跑守衛鏈，通過才執行工具。回 { blocked, reason } 或 { result }。
+     * 這是 agent loop 中「一次工具呼叫」的確定性切片，可不靠 LLM 測試/示範。
+     */
+    runTool: async (name, args = {}, extra = {}) => {
+      const ctx = { name, args, ...extra };
+      const decision = await guard(ctx);
+      if (decision?.block) return { blocked: true, reason: decision.reason };
+      const tool = registry.get(name);
+      const result = await tool.execute(`call-${name}`, args, extra.signal, extra.onUpdate, services);
+      return { result };
+    },
+    /**
+     * 跑一輪：把使用者輸入交給 LLM，驅動「串流 → 工具呼叫（過守衛鏈）→ 回灌 → 再串流」多步循環，
+     * 直到模型不再呼叫工具。移植自 xitto-code 的 Agent loop；守衛鏈接到 Agent.beforeToolCall。
+     * @param {string} input
+     * @param {{ onEvent?: (e: object) => void, onAgent?: (agent: object) => void, history?: object[] }} [opts]
+     *        onAgent：建立 Agent 後、prompt 前同步回呼（讓 CLI 拿到 agent 以便 Ctrl+C abort）。
+     *        history：延續上一輪的 messages（多輪對話）。
+     * @returns {Promise<{ text: string, messages: object[], agent: object, aborted: boolean }>}
+     */
+    runTurn: async (input, opts = {}) => {
+      if (!config.model) throw new Error('runTurn 需要 config.model（LLM model 物件）。');
+      if (!config.getApiKey) throw new Error('runTurn 需要 config.getApiKey。');
+      const { Agent } = await import('./agent-loop.js');
+      const streamFn = config.streamFn || (await import('./provider.js')).defaultStreamFn();
+      const model = config.model;
+
+      const agent = new Agent({
+        initialState: {
+          systemPrompt,
+          model,
+          tools: registry.all(),
+          messages: opts.history || [],   // 多輪對話：延續歷史
+          thinkingLevel: config.thinkingLevel || (model.reasoning ? 'medium' : 'off'),
+        },
+        getApiKey: config.getApiKey,
+        streamFn,
+        // 守衛鏈接線：Agent 的 ctx 形狀 → kernel guard 的 { name, args }
+        beforeToolCall: async (ctx) => guard({
+          name: ctx.toolCall?.name,
+          args: ctx.args,
+          assistantMessage: ctx.assistantMessage,
+        }),
+        // 回合內壓縮：每次串流前若逼近視窗，就地摘要較舊對話、保留最近，繼續同回合
+        maybeCompactInTurn: async () => {
+          const s = resolveCompactionSettings(config.compaction, model.contextWindow);
+          if (!s.enabled) return null;
+          let apiKey; try { apiKey = await config.getApiKey(model.provider); } catch { return null; }
+          const info = await maybeCompact(agent, model, apiKey, s);
+          if (info && !info.error) opts.onEvent?.({ type: 'compact', ...info });
+          return info;
+        },
+        toolExecution: 'sequential',
+      });
+      // 追蹤本輪改動 + PostToolUse hooks（成功工具後跑命令，失敗回灌讓 agent 修正）
+      let turnModified = false;
+      agent.subscribe((e) => {
+        if (e.type !== 'tool_execution_end' || e.isError) return;
+        if (mutatingTools.has(e.toolName)) turnModified = true;
+        for (const f of runPostToolHooks(hooks, e.toolName, cwd)) {
+          opts.onEvent?.({ type: 'hook_fail', command: f.command, output: f.output });
+          agent.steer({ role: 'user', content: `[PostToolUse] \`${f.command}\` 失敗：\n${(f.output || '').slice(0, 2000)}\n請修正後再繼續。` });
+        }
+      });
+      if (opts.onEvent) agent.subscribe((e) => opts.onEvent(e));
+      opts.onAgent?.(agent); // 讓呼叫端拿到 agent（Ctrl+C → agent.abort()）
+
+      await agent.prompt(input);
+      const wasAborted = () => [...agent.state.messages].reverse().find((m) => m.role === 'assistant')?.stopReason === 'aborted';
+
+      // 收尾自我驗收（pack.verify）：失敗則把輸出回灌讓 agent 修正，最多 maxRounds 輪。
+      // 對標 xitto-code 的 runAutoVerify；機制在 kernel、「跑什麼/何時跑」由 pack 決定。
+      if (pack.verify && !wasAborted()) {
+        const maxRounds = Number.isInteger(pack.verify.maxRounds) ? pack.verify.maxRounds : 2;
+        for (let round = 0; round < maxRounds; round++) {
+          const vctx = { turnModified, cwd };
+          const shouldRun = pack.verify.shouldRun ? pack.verify.shouldRun(vctx) : turnModified;
+          if (!shouldRun) break;
+          opts.onEvent?.({ type: 'verify_start' });
+          let v;
+          try { v = await pack.verify.run(vctx); } catch (e) { v = { ok: false, output: e?.message || String(e) }; }
+          opts.onEvent?.({ type: 'verify_end', ok: !!v?.ok, output: v?.output });
+          if (v?.ok) break;
+          turnModified = false;
+          await agent.prompt(`[自動驗收] 驗證失敗，輸出如下：\n${String(v?.output || '').slice(0, 4000)}\n請修正使其通過。`);
+          if (wasAborted() || !turnModified) break; // 中斷或 agent 沒再改 → 停止避免空轉
+        }
+      }
+
+      const messages = agent.state.messages;
+      const lastAssistant = [...messages].reverse().find((m) => m.role === 'assistant');
+      const text = (lastAssistant?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('');
+      const aborted = lastAssistant?.stopReason === 'aborted';
+      return { text, messages, agent, aborted };
+    },
+  };
+}

package/src/kernel/mcp.js

@@ -0,0 +1,54 @@
+// MCP 工具接入 — kernel 內建。.xitto-kernel/<pack>/mcp.json 連 MCP server（stdio），
+// 把 server 的工具以 mcp__<server>__<tool> 注入。連線失敗的 server 自動略過。
+// 非同步（連線需 await），故由 app 層在啟動時載入後以 config.extraTools 傳入 createKernel。
+import { existsSync, readFileSync } from 'node:fs';
+
+const noop = { tools: [], close: async () => {} };
+
+/**
+ * @param {string} mcpConfigPath  .xitto-kernel/<pack>/mcp.json
+ * @param {(msg: string) => void} [onLog]
+ * @returns {Promise<{ tools: import('../types.js').Tool[], close: () => Promise<void> }>}
+ */
+export async function loadMcpTools(mcpConfigPath, onLog = () => {}) {
+  if (!existsSync(mcpConfigPath)) return noop;
+  let cfg;
+  try { cfg = JSON.parse(readFileSync(mcpConfigPath, 'utf8')); } catch { onLog('mcp.json 解析失敗，略過'); return noop; }
+  const servers = cfg.mcpServers || {};
+  if (!Object.keys(servers).length) return noop;
+
+  let Client, StdioClientTransport;
+  try {
+    ({ Client } = await import('@modelcontextprotocol/sdk/client/index.js'));
+    ({ StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js'));
+  } catch { onLog('未安裝 @modelcontextprotocol/sdk，略過 MCP'); return noop; }
+
+  const clients = [];
+  const tools = [];
+  for (const [name, sc] of Object.entries(servers)) {
+    if (!sc || typeof sc.command !== 'string') continue;
+    try {
+      const transport = new StdioClientTransport({ command: sc.command, args: sc.args || [], env: { ...process.env, ...(sc.env || {}) } });
+      const client = new Client({ name: 'xitto-kernel', version: '0.0.1' }, { capabilities: {} });
+      await client.connect(transport);
+      const { tools: mcpTools } = await client.listTools();
+      for (const t of mcpTools) {
+        tools.push({
+          name: `mcp__${name}__${t.name}`, label: `${name}:${t.name}`,
+          mutating: true, // 外部工具保守視為有副作用：走權限確認、計劃模式擋下
+          description: t.description || `MCP ${name} 的 ${t.name}`,
+          parameters: t.inputSchema || { type: 'object', properties: {} },
+          execute: async (_id, args) => {
+            try {
+              const r = await client.callTool({ name: t.name, arguments: args || {} });
+              return { content: r.content || [{ type: 'text', text: JSON.stringify(r) }] };
+            } catch (e) { return { content: [{ type: 'text', text: JSON.stringify({ error: e?.message || String(e) }) }] }; }
+          },
+        });
+      }
+      clients.push(client);
+      onLog(`MCP ${name}：載入 ${mcpTools.length} 個工具`);
+    } catch (e) { onLog(`MCP ${name} 連線失敗，略過：${e?.message || e}`); }
+  }
+  return { tools, close: async () => { for (const c of clients) { try { await c.close(); } catch { /* 略 */ } } } };
+}

package/src/kernel/memory.js

@@ -0,0 +1,45 @@
+// 跨 session 持久記憶 — kernel 內建能力（任何 pack 都自動獲得 memory_save / memory_list）。
+// 存成 markdown 一行一條，啟動時載入注入 system prompt。對標 xitto-code memory.js，但領域無關。
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
+
+/**
+ * @param {string} file  記憶檔路徑（如 <cwd>/.xitto-kernel/<pack>/memory.md）
+ */
+export function createMemory(file) {
+  const readLines = () => (existsSync(file)
+    ? readFileSync(file, 'utf8').split('\n').map((l) => l.replace(/^-\s*/, '').trim()).filter(Boolean)
+    : []);
+
+  const load = () => (existsSync(file) ? readFileSync(file, 'utf8').trim() : '');
+  const list = () => readLines();
+  const save = (value) => {
+    const v = String(value || '').trim();
+    if (!v) return { error: 'value 不可為空' };
+    const lines = readLines();
+    if (lines.includes(v)) return { skipped: true };
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, lines.concat(v).map((l) => `- ${l}`).join('\n') + '\n');
+    return { saved: v };
+  };
+
+  // memory_save/list 只動 kernel 自己的記憶檔（agent 簿記），標 readOnly → 守衛鏈自動放行
+  const tools = [
+    {
+      name: 'memory_save', label: '存記憶', readOnly: true,
+      description: '把值得跨 session 記住的事實存起來（使用者偏好、建置/測試指令、踩過的坑、決策）。一句、自給自足。',
+      parameters: { type: 'object', properties: { value: { type: 'string' } }, required: ['value'] },
+      execute: async (_id, { value }) => txt(save(value)),
+    },
+    {
+      name: 'memory_list', label: '讀記憶', readOnly: true,
+      description: '列出已記住的事實（回憶過往偏好/決策時用）。',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => txt({ memories: list() }),
+    },
+  ];
+
+  return { load, list, save, tools };
+}

package/src/kernel/pack-loader.js

@@ -0,0 +1,45 @@
+// DomainPack 載入與驗證 — kernel 對 pack 的入口契約。
+// 必填：name / tools / systemPrompt。選填欄位若提供則檢查型別。
+// 對應 docs/02-domain-pack-spec.md 的「必填/選填總表」。
+
+/**
+ * 驗證一個 DomainPack，回傳錯誤訊息陣列（空陣列 = 合法）。
+ * @param {import('../types.js').DomainPack} pack
+ * @returns {string[]}
+ */
+export function validatePack(pack) {
+  if (!pack || typeof pack !== 'object') return ['pack 必須是物件'];
+  const errors = [];
+
+  // ── 必填 ──
+  if (typeof pack.name !== 'string' || !pack.name.trim()) errors.push('name：必填，需為非空字串');
+  if (typeof pack.tools !== 'function') errors.push('tools：必填，需為函數 () => Tool[]');
+  if (typeof pack.systemPrompt !== 'string' || !pack.systemPrompt.trim()) errors.push('systemPrompt：必填，需為非空字串');
+
+  // ── 選填（提供才檢查型別）──
+  if (pack.contextFiles !== undefined && !isStringArray(pack.contextFiles)) errors.push('contextFiles：需為字串陣列');
+  if (pack.mutatingTools !== undefined && !isStringArray(pack.mutatingTools)) errors.push('mutatingTools：需為字串陣列');
+  if (pack.verify !== undefined && typeof pack.verify?.run !== 'function') errors.push('verify.run：需為函數');
+  if (pack.preToolPolicy !== undefined && typeof pack.preToolPolicy?.check !== 'function') errors.push('preToolPolicy.check：需為函數');
+  if (pack.permissionPolicy !== undefined && (typeof pack.permissionPolicy !== 'object' || pack.permissionPolicy === null)) errors.push('permissionPolicy：需為物件');
+  if (pack.memoryGuide !== undefined && typeof pack.memoryGuide !== 'string') errors.push('memoryGuide：需為字串');
+
+  return errors;
+}
+
+/**
+ * 載入並驗證 pack；不合法則丟出聚合錯誤。回傳原 pack（不變更）。
+ * @param {import('../types.js').DomainPack} pack
+ * @returns {import('../types.js').DomainPack}
+ */
+export function loadPack(pack) {
+  const errors = validatePack(pack);
+  if (errors.length) {
+    throw new Error(`DomainPack「${pack?.name ?? '?'}」不合法：\n- ${errors.join('\n- ')}`);
+  }
+  return pack;
+}
+
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}

package/src/kernel/provider.js

@@ -0,0 +1,20 @@
+// Provider 呼叫適配 — kernel 怎麼正確地調用 LLM provider（與「provider 設定」不同，後者屬 app）。
+// 預設 streamFn 包 pi-ai 的 streamSimple，並處理 anthropic 相容端點的 prompt caching 相容性。
+import { streamSimple } from '@mariozechner/pi-ai';
+
+// 該 model 是否該關掉 prompt caching：'none' = 關閉。
+// pi-ai 對所有 anthropic-messages provider 預設加 cache_control，但只有「真正的 Anthropic」端點支援；
+// MiniMax 等 anthropic 相容端點會因此回 500，需關閉。（沿用 xitto-code config.cacheRetentionFor）
+export function cacheRetentionFor(model) {
+  if (!model) return undefined;
+  if (model.cache === false) return 'none';
+  if (model.cache === true) return undefined;
+  if (model.api !== 'anthropic-messages') return undefined;
+  return /(^|\/\/|\.)anthropic\.com/.test(model.baseUrl || '') ? undefined : 'none';
+}
+
+// 預設 streamFn：Agent loop 用它串流一次 assistant 回應。
+export function defaultStreamFn() {
+  return (model, ctx, opts) =>
+    streamSimple(model, ctx, { ...opts, cacheRetention: cacheRetentionFor(model) || opts.cacheRetention });
+}

package/src/kernel/security/allow.js

@@ -0,0 +1,41 @@
+// 細粒度權限：bash 命令「簽章」與 allow.json 的解析/序列化（向後相容舊格式）。
+// 對標 Claude Code 的 Bash(npm test) 規則 —— 放行某類命令而非整個 bash 工具。
+
+// 帶子命令的工具：簽章取前兩詞（npm test、git status、docker compose），其餘取首詞（ls、cat）。
+// 這讓「允許 npm test」只放行 npm test 系列，npm install / npm run build 仍需確認。
+const SUBCMD = new Set([
+  'npm', 'pnpm', 'yarn', 'npx', 'bun', 'deno',
+  'git', 'cargo', 'go', 'docker', 'make', 'kubectl',
+  'python', 'python3', 'pip', 'pip3', 'node', 'dotnet', 'mvn', 'gradle',
+]);
+
+export function commandSignature(cmd) {
+  if (typeof cmd !== 'string') return '';
+  const t = cmd.trim().split(/\s+/).filter(Boolean);
+  if (!t.length) return '';
+  // env 前綴（VAR=val cmd）跳過
+  let i = 0;
+  while (i < t.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(t[i])) i++;
+  const head = t.slice(i);
+  if (!head.length) return '';
+  if (head.length >= 2 && SUBCMD.has(head[0])) return `${head[0]} ${head[1]}`;
+  return head[0];
+}
+
+// 解析 allow.json：向後相容。
+//   舊格式：工具名字串陣列 ["bash","write"]
+//   新格式：{ tools: ["write"], bash: ["npm test","git status"] }
+export function parseAllowFile(raw) {
+  if (Array.isArray(raw)) return { tools: raw.filter((x) => typeof x === 'string'), bash: [] };
+  if (raw && typeof raw === 'object') {
+    return {
+      tools: Array.isArray(raw.tools) ? raw.tools.filter((x) => typeof x === 'string') : [],
+      bash: Array.isArray(raw.bash) ? raw.bash.filter((x) => typeof x === 'string') : [],
+    };
+  }
+  return { tools: [], bash: [] };
+}
+
+export function serializeAllow(tools, bash) {
+  return JSON.stringify({ tools: [...tools], bash: [...bash] }, null, 2);
+}

package/src/kernel/security/danger.js

@@ -0,0 +1,37 @@
+// 危險 bash 命令偵測 — 即使使用者對 bash 選了「本次全部允許」，命中這些高破壞性模式時
+// 仍強制二次確認（且不因「always」而永久放行）。高精準、低誤報為原則：只攔真正不可逆/系統級操作。
+// 回傳一句中文原因字串，安全則回傳 null。
+
+const RULES = [
+  // rm 遞迴 + 強制刪除（-rf / -fr / -r -f 任意組合）
+  [(c) => /\brm\b/.test(c) && /-\w*r/.test(c) && /-\w*f/.test(c), 'rm 遞迴強制刪除（不可復原）'],
+  // 刪到根目錄 / 家目錄 / 萬用字元根
+  [(c) => /\brm\b[\s\S]*\s(-\w+\s+)*(\/|~|\$home|\/\*)(\s|$)/.test(c), 'rm 目標為根/家目錄'],
+  // 下載內容直接交給 shell 執行（curl|sh、wget|bash、… | python）
+  [(c) => /\b(curl|wget|fetch)\b[\s\S]*\|\s*(sudo\s+)?(sh|bash|zsh|dash|python\d?|node|perl|ruby)\b/.test(c), '下載內容直接管道給 shell 執行'],
+  // fork bomb :(){ :|:& };:
+  [(c, raw) => /:\(\)\s*\{[\s\S]*\|[\s\S]*&[\s\S]*\}/.test(raw) || /:\(\)\{:\|:&\};:/.test(raw.replace(/\s/g, '')), 'fork bomb'],
+  // 格式化檔案系統
+  [(c) => /\bmkfs(\.\w+)?\b/.test(c), '格式化檔案系統（mkfs）'],
+  // dd 寫入裝置
+  [(c) => /\bdd\b[\s\S]*\bof=\/dev\//.test(c), 'dd 直接寫入裝置'],
+  // 重導向覆寫區塊裝置
+  [(c) => />\s*\/dev\/(sd|nvme|disk|hd|mmcblk)/.test(c), '覆寫區塊裝置'],
+  // 對根遞迴改權限/擁有者
+  [(c) => /\b(chmod|chown)\b[\s\S]*-\w*r[\s\S]*\s\/(\s|$)/.test(c), '對根目錄遞迴 chmod/chown'],
+  // 關機 / 重啟
+  [(c) => /\b(shutdown|reboot|halt|poweroff|init\s+0)\b/.test(c), '關機/重啟'],
+  // 清空磁碟 via /dev/zero|null 寫整顆盤
+  [(c) => /\b(cat|cp)\b[\s\S]*\/dev\/(zero|random|urandom)[\s\S]*>\s*\/dev\//.test(c), '寫入裝置（清空磁碟）'],
+];
+
+export function dangerousReason(cmd) {
+  if (typeof cmd !== 'string') return null;
+  const raw = cmd;
+  const c = cmd.toLowerCase();
+  if (!c.trim()) return null;
+  for (const [test, reason] of RULES) {
+    try { if (test(c, raw)) return reason; } catch { /* 規則出錯不阻塞 */ }
+  }
+  return null;
+}

package/src/kernel/security/permission-step.js

@@ -0,0 +1,63 @@
+// 守衛鏈第 5 格：真實權限/沙箱（領域無關，metadata 驅動）。
+// 對標 xitto-code permissions.js，但不寫死 READ_ONLY/SHELL_TOOLS 名單——
+// 「唯讀」「可沙箱」皆由工具自帶 metadata 決定，故任何領域通用。
+// 檢查順序：deny → 沙箱靜態策略違規 → 危險命令 → 命令簽章白名單 / 確認。
+import { sandboxViolation } from './sandbox.js';
+import { dangerousReason } from './danger.js';
+import { commandSignature } from './allow.js';
+
+/**
+ * @param {Object} o
+ * @param {{ get: (name: string) => object }} o.registry
+ * @param {() => boolean} [o.getSandbox]                沙箱是否開啟
+ * @param {() => object} [o.getSandboxConfig]           沙箱策略（blockNetwork/allowWritePrefixes）
+ * @param {string[]} [o.deny]                           禁止的工具名 / "bash:<簽章>"
+ * @param {(name: string, args: object, danger: string|null) => Promise<'yes'|'no'|'always'|'command'>} [o.confirm]
+ *        互動確認；不提供（headless）時：危險命令一律擋、其餘放行（沙箱靜態違規仍先擋）。
+ * @returns {(ctx: { name: string, args: object }) => Promise<import('../../types.js').PolicyDecision>}
+ */
+export function createPermissionStep({ registry, getSandbox, getSandboxConfig, deny = [], confirm }) {
+  const denySet = new Set(deny);
+  const allowedSignatures = new Set(); // session 內「允許此命令簽章全部」
+  const alwaysTools = new Set();       // session 內「允許此工具全部」（使用者選 always）
+
+  return async function permission(ctx) {
+    const name = ctx.name;
+    const tool = registry.get(name);
+    if (!tool) return { block: true, reason: `未知工具：${name}` };
+    if (tool.readOnly === true) return undefined; // metadata 驅動：唯讀自動放行
+
+    const cmd = ctx.args?.command || ctx.args?.cmd || '';
+    const isShell = tool.sandboxable === true || typeof cmd === 'string' && cmd.length > 0;
+    const sig = isShell ? commandSignature(cmd) : null;
+
+    // 1) deny 規則優先於一切
+    if (denySet.has(name) || (sig && denySet.has(`bash:${sig}`))) {
+      return { block: true, reason: `${name}${sig ? `（${sig}）` : ''} 已被 deny 規則禁止。` };
+    }
+
+    // 2) 沙箱靜態策略：違規（網路/提權/越界寫入）直接擋，不執行也不詢問
+    if (isShell && getSandbox?.()) {
+      const v = sandboxViolation(cmd, getSandboxConfig?.() || {});
+      if (v) return { block: true, reason: `${v}。可關閉沙箱或調整策略。` };
+    }
+
+    // 3) 危險命令：即使 always-allow / 無 confirm 也強制把關（headless 直接擋）
+    const danger = isShell ? dangerousReason(cmd) : null;
+
+    // 4) 非危險：本工具/命令簽章已 always-allow → 直接過；headless（無 confirm）→ 放行
+    if (!danger) {
+      if (alwaysTools.has(name) || (sig && allowedSignatures.has(sig))) return undefined;
+      if (!confirm) return undefined;
+    } else if (!confirm) {
+      return { block: true, reason: `偵測到危險命令（${danger}），headless 模式下拒絕執行。` };
+    }
+
+    // 5) 互動確認（危險命令即使選 always 也只放行這次，不永久放行）
+    const decision = await confirm(name, ctx.args, danger);
+    if (decision === 'always' && !danger) { alwaysTools.add(name); return undefined; }
+    if (decision === 'command' && sig && !danger) { allowedSignatures.add(sig); return undefined; }
+    if (decision === 'yes') return undefined;
+    return { block: true, reason: `使用者拒絕執行 ${name}。` };
+  };
+}