xitto-kernel 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.3.0
+
+把底座的「能力」與「體驗」補到接近 Claude Code，並擴充領域 pack 與評測。
+
+### 新增
+
+- **完整 Ink TUI**（`--tui`）：持久底部狀態列（model/cwd/git/權限/sandbox/plan/ctx）、`Static` 捲動轉錄、即時串流重繪、Esc 中斷、markdown/程式碼語法高亮、Select 式權限詢問；非真實終端自動退回 readline CLI
+- **新領域 pack**：`deep-research`（多源檢索→深讀→綜整）、`devops`
+- **agent loop 內建化**：把 xitto-code 的 agent loop 移植進 `runTurn`（自帶、用 pi-ai streamFn）
+- **真實 sandbox 接入守衛鏈第 5 格**：macOS Seatbelt（sandbox-exec）OS 層隔離
+- **server app PoC**：把 kernel 包成 HTTP 服務（`/v1/run`、`/v1/stream` SSE、bearer 驗證、per-session workdir）
+- **評測框架**：scorers（answerMatch/stateCheck/toolCalled/allOf）+ SWE-bench mini 與真實 SWE-bench Verified adapter；各 pack eval 套件
+- 套件匯出補上 `./packs/general`、`./packs/deep-research`、`./packs/devops`
+
+### 驗證
+
+- 真實 SWE-bench Verified：coding pack（MiniMax）可重現解出 flask-5014、requests-1142 等
+- 測試 116/116 通過（含 Ink TUI 煙霧測試）
+
 ## 0.2.0
 
 第一個功能完整版 —— 從 0.1.0（基礎 kernel + CLI + 腳手架）補齊近乎 xitto-code 等價的能力，

package/README.md

@@ -50,6 +50,22 @@ xitto-kernel --pack general --yes --goal "抓取 example.com 摘要成繁中寫
 ```
 `general` pack（檔案/shell/web_fetch）+ kernel 的 **goal loop**（反覆 runTurn + LLM 自我驗收，直到達成/無進展/上限）。互動模式用 `/goal <目標>`。
 
+## 當成服務跑（不只 CLI）
+
+kernel 是 UI 無關的，CLI 只是其中一個 app。`src/app/server.js` 是把它包成 **HTTP 服務**的 PoC
+（零依賴 `node:http`）—— 證明「個人工具 → 可服務化底座」：
+
+```bash
+XITTO_SERVER_TOKEN=secret npm run serve     # http://localhost:8787
+curl -s localhost:8787/health
+curl -s -XPOST localhost:8787/v1/run -H "Authorization: Bearer secret" \
+  -H content-type:application/json -d '{"pack":"general","sessionId":"s1","input":"..."}'
+```
+
+特性：bearer token 認證、**per-session 隔離工作目錄 + 歷史**（多輪記得上文）、沙箱（Seatbelt）、
+結構化 JSON 日誌（審計/觀測）、6 個 pack 可選、JSON 或 SSE（`/v1/stream`）串流。
+「個人 vs 生產」是 **app 層**的事 —— 同一個 kernel，CLI 與 server 是兩個 app。
+
 ## 做你自己的領域 agent（不固化）
 
 kernel 是**被依賴的套件**，不是被 clone 的範本。你的 agent 是獨立小專案：
@@ -101,7 +117,9 @@ xitto-kernel/
 │       ├── coding/               ✅ 參考 pack（read/ls/write/edit/bash/git）
 │       ├── data-query/           ✅ 第二領域（證明正交）
 │       ├── notes/                ✅ 第三領域（知識庫）
-│       └── general/              ✅ 通用自主 agent（檔案/shell/web_fetch + goal loop）
+│       ├── general/              ✅ 通用自主 agent（檔案/shell/web/http + goal loop）
+│       ├── deep-research/        ✅ 深度研究（多來源搜尋→查證→有引用結論）
+│       └── devops/               ✅ 維運/SRE（shell + bash_bg + 設定 + 日誌 + 健康檢查）
 ├── bin/xitto-kernel.js           ✅ CLI 進入點（run / new-agent）
 ├── test/                         ✅ 41 測試全綠（runTurn + Seatbelt 隔離 + 腳手架 + …）
 └── examples/
@@ -138,6 +156,23 @@ xitto-kernel/
 
 **設計取向**：沿用 Node ESM + pi-ai provider 抽象；不重寫 xitto-code（kernel 是抽象，xitto-code 仍可獨立存在）。
 
+## 評估（能力可量化）
+
+每個 pack 配一個 EvalSuite（`eval/`，共用 `eval/framework.js`，不進 npm 包）。
+範式：**新領域 agent = 新 pack（會什麼）+ 新 EvalSuite（怎麼打分）**。
+
+| Suite | 對標 | 評分方式 | 跑法 | 參考結果* |
+|------|------|------|------|------|
+| coding | SWE-bench Verified | 隱藏測試 fail→pass（Docker）| `eval/swebench-generate.js` + 官方 harness | 3/8 resolved（真實子集）|
+| coding（迷你）| SWE-bench 風格 | 隱藏測試（免 Docker）| `npm run eval` | 4/4 |
+| general | GAIA 風格 | 答案比對 / 狀態檢查 | `node eval/general-run.js` | 4/4 |
+| data-query | Spider/BIRD 風格 | 真實 SQLite + 答案比對 | `node eval/data-query-run.js` | 4/4 |
+| deep-research | GAIA/研究 | 事實正確 + 真的查證（allOf）| `node eval/deep-research-run.js` | 3/3 |
+| devops | Terminal-Bench 風格 | 狀態檢查（系統/檔案達標）| `node eval/devops-run.js` | 4/4 |
+| 工具呼叫 | BFCL 風格 | 軌跡檢查（呼叫對工具/參數）| `node eval/tool-calling-run.js` | 6/6 |
+
+\* 用 MiniMax-M2.7 跑的參考數字（小樣本）；換模型/擴樣本見 `eval/README.md`。scorer 型：`answerMatch` / `stateCheck` / `toolCalled`。
+
 ## 貢獻
 
 見 [CONTRIBUTING.md](CONTRIBUTING.md)。核心原則：kernel 必須領域無關（安全行為靠工具 metadata，不寫死領域名單）；新領域 = 新增一個 pack，kernel 零改動。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [
@@ -40,6 +40,8 @@
   "scripts": {
     "test": "node --test",
     "demo": "node examples/demo.js",
+    "eval": "node eval/run.js",
+    "serve": "node src/app/server.js",
     "start": "node bin/xitto-kernel.js"
   },
   "exports": {
@@ -47,10 +49,21 @@
     "./app": "./src/app/index.js",
     "./packs/coding": "./src/packs/coding/index.js",
     "./packs/data-query": "./src/packs/data-query/index.js",
-    "./packs/notes": "./src/packs/notes/index.js"
+    "./packs/notes": "./src/packs/notes/index.js",
+    "./packs/general": "./src/packs/general/index.js",
+    "./packs/deep-research": "./src/packs/deep-research/index.js",
+    "./packs/devops": "./src/packs/devops/index.js"
   },
   "dependencies": {
     "@mariozechner/pi-ai": "^0.70.6",
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cli-highlight": "^2.1.11",
+    "ink": "^5.2.1",
+    "marked": "^12.0.2",
+    "marked-terminal": "^7.3.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "ink-testing-library": "^4.0.0"
   }
 }

package/src/app/cli.js

@@ -41,6 +41,26 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   let history = [];
   let currentAgent = null;
   let streaming = false;
+  const turnUsage = { input: 0, output: 0 }; // 本輪 token 累計（顯示頁腳）
+
+  // 等待 LLM 時的 spinner（首個可見輸出出現即停）
+  const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let spinTimer = null;
+  const startSpin = () => {
+    if (!process.stdout.isTTY) return; // 非互動（管線）不顯示 spinner，避免 \r 雜訊
+    let i = 0; const t0 = Date.now();
+    spinTimer = setInterval(() => { process.stdout.write(`\r\x1b[2m${FRAMES[i++ % FRAMES.length]} 思考中… ${Math.round((Date.now() - t0) / 1000)}s\x1b[0m\x1b[K`); }, 100);
+  };
+  const stopSpin = () => { if (spinTimer) { clearInterval(spinTimer); spinTimer = null; process.stdout.write('\r\x1b[K'); } };
+
+  // 目前模式標記（提示列前綴，讓使用者隨時看到狀態）
+  const modeTag = () => {
+    const t = [];
+    if (planMode) t.push('plan');
+    if (sandboxOn) t.push('🔒');
+    if (autoApprove) t.push('⚡');
+    return t.length ? c.gray('[' + t.join(' ') + '] ') : '';
+  };
 
   // 互動權限確認：守衛鏈第 5 格對 mutating/危險工具呼叫此函數。autoApprove → 一律放行。
   // 回 'yes'（允許一次）/ 'always'（此工具全部）/ 'no'（拒絕）。
@@ -88,13 +108,15 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   };
 
   const onEvent = (ev) => {
+    if (ev.type === 'message_end' && ev.message?.usage) { turnUsage.input += ev.message.usage.input || 0; turnUsage.output += ev.message.usage.output || 0; }
     switch (ev.type) {
       case 'message_update': {
         const a = ev.assistantMessageEvent;
-        if (a?.type === 'text_delta' && a.delta) { md.push(a.delta); streaming = true; }
+        if (a?.type === 'text_delta' && a.delta) { stopSpin(); md.push(a.delta); streaming = true; }
         break;
       }
       case 'tool_execution_start':
+        stopSpin();
         endStream();
         if (ev.toolName === 'todo_write' && Array.isArray(ev.args?.todos)) {
           out(c.cyan('☑ 待辦更新\n'));
@@ -202,7 +224,14 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     }
   };
 
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: c.blue('› ') });
+  // 斜線指令 tab 補全
+  const SLASH = ['/help', '/goal ', '/sandbox', '/auto', '/plan', '/undo', '/tools', '/memory', '/sessions', '/resume', '/clear', '/exit'];
+  const completer = (line) => {
+    if (!line.startsWith('/')) return [[], line];
+    const hits = SLASH.filter((s) => s.startsWith(line));
+    return [hits.length ? hits : SLASH, line];
+  };
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: c.blue('› '), completer, historySize: 200 });
   let closed = false;
   const cleanup = () => { try { rl.close(); } catch { /* 略 */ } try { onExit?.(); } catch { /* 略 */ } };
   const finish = () => { cleanup(); process.exit(0); };
@@ -210,13 +239,13 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
 
   // Ctrl+C：執行中→中斷該輪；閒置→離開
   process.on('SIGINT', () => {
-    if (currentAgent) { currentAgent.abort(); out(c.yellow('\n⏹ 已中斷本輪\n')); }
+    if (currentAgent) { stopSpin(); currentAgent.abort(); out(c.yellow('\n⏹ 已中斷本輪\n')); }
     else { out(c.gray('\n再見。\n')); cleanup(); process.exit(0); }
   });
 
   // 橫幅
   out('\n' + c.cyan('✻ ') + c.bold('xitto-kernel') + c.gray(`  ·  ${pack.name} pack  ·  ${model.id}`) + '\n');
-  out(c.gray(`  沙箱 ${sandboxOn ? '開' : '關'}${seatbeltAvailable() ? '（Seatbelt 可用）' : ''}  ·  /help 看指令  ·  Ctrl+C 中斷/離開`) + '\n');
+  out(c.gray(`  沙箱 ${sandboxOn ? '開' : '關'}${seatbeltAvailable() ? '（Seatbelt 可用）' : ''}  ·  /help · Tab 補全 · ↑↓ 歷史 · Ctrl+C 中斷/離開`) + '\n');
   if (resumedNote) out(c.gray('  ' + resumedNote) + '\n');
   out('\n');
 
@@ -224,7 +253,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     if (closed) return finish();
     let q;
     try { q = rl.question.bind(rl); } catch { return finish(); }
-    q(c.blue('› '), async (raw) => {
+    q(modeTag() + c.blue('› '), async (raw) => {
       const input = (raw || '').trim();
       if (!input) return loop();
       // /goal <目標>：目標驅動自主循環（在此 await，避免與下一個提示交錯）
@@ -233,13 +262,16 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
         if (!goal) { out(c.gray('用法 /goal <目標>\n')); return loop(); }
         try {
           out(c.cyan('🎯 目標：') + goal + '\n');
+          turnUsage.input = 0; turnUsage.output = 0;
+          const t0 = Date.now();
           const r = await kernel.runGoal(goal, {
             history,
-            onRound: ({ round, maxRounds }) => out(c.yellow(`\n🔁 第 ${round}/${maxRounds} 輪\n`)),
-            onCheck: ({ done, remaining }) => out(done ? c.green('  ✓ 驗收：已達成\n') : c.gray(`  ↻ ${remaining}\n`)),
+            onRound: ({ round, maxRounds }) => { stopSpin(); out(c.yellow(`\n🔁 第 ${round}/${maxRounds} 輪 `)); startSpin(); },
+            onCheck: ({ done, remaining }) => { stopSpin(); out(done ? c.green('  ✓ 驗收：已達成\n') : c.gray(`  ↻ ${remaining}\n`)); },
             onEvent, onAgent: (a) => { currentAgent = a; },
           });
-          endStream(); history = r.history; persist();
+          stopSpin(); endStream(); history = r.history; persist();
+          out(c.gray(`↳ ${((Date.now() - t0) / 1000).toFixed(1)}s · ${turnUsage.input + turnUsage.output} tokens · ${r.rounds} 輪`) + '\n');
           const why = r.stalled ? '無進展' : r.aborted ? '中斷' : r.verifyBroken ? '驗收持續失敗' : '到上限';
           out('\n' + (r.done ? c.green(`✅ 目標達成（${r.rounds} 輪）`) : c.yellow(`⚠ 未達成（${why}，${r.rounds} 輪）`)) + '\n');
         } catch (err) { endStream(); out(c.red('錯誤：' + err.message) + '\n'); }
@@ -251,13 +283,19 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
         const text = planMode
           ? `[計劃模式：只制定計劃，列出你打算做的步驟與會改動的檔案，不要實際寫檔或執行命令]\n\n${input}`
           : input;
+        turnUsage.input = 0; turnUsage.output = 0;
+        const t0 = Date.now();
+        startSpin();
         const r = await kernel.runTurn(text, {
           history, onEvent, onAgent: (a) => { currentAgent = a; },
         });
+        stopSpin();
         endStream();
         history = r.messages;
         persist();                 // 每輪結束自動存檔（可 /resume 續接）
+        out(c.gray(`↳ ${((Date.now() - t0) / 1000).toFixed(1)}s · ${turnUsage.input + turnUsage.output} tokens`) + '\n');
       } catch (err) {
+        stopSpin();
         endStream();
         out(c.red('錯誤：' + err.message) + '\n');
       } finally {

package/src/app/index.js

@@ -1,5 +1,6 @@
 // app 子路徑公開 API（xitto-kernel/app）：外部 agent 專案 import 這些來啟動，不需改 kernel。
 export { runCli } from './cli.js';
+export { createServerApp, startServer } from './server.js';
 export { loadModel, loadProvidersConfig, buildModel } from './providers.js';
 export { newAgent } from './scaffold.js';
 export { main } from './main.js';

package/src/app/main.js

@@ -3,6 +3,7 @@
 import { join } from 'node:path';
 import { loadModel } from './providers.js';
 import { runCli } from './cli.js';
+import { runTui } from './tui-run.js';
 import { newAgent } from './scaffold.js';
 import { createKernel } from '../kernel/index.js';
 import { loadMcpTools } from '../kernel/mcp.js';
@@ -10,6 +11,8 @@ import { createCodingPack } from '../packs/coding/index.js';
 import { createDataQueryPack } from '../packs/data-query/index.js';
 import { createNotesPack } from '../packs/notes/index.js';
 import { createGeneralPack } from '../packs/general/index.js';
+import { createDeepResearchPack } from '../packs/deep-research/index.js';
+import { createDevopsPack } from '../packs/devops/index.js';
 
 const e = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
 const green = e(32); const gray = e(90); const red = e(31); const cyan = e(36); const yellow = e(33);
@@ -19,6 +22,8 @@ const PACKS = {
   'data-query': createDataQueryPack,
   notes: createNotesPack,
   general: createGeneralPack,
+  'deep-research': createDeepResearchPack,
+  devops: createDevopsPack,
 };
 
 export async function main(argv = process.argv.slice(2)) {
@@ -73,6 +78,12 @@ export async function main(argv = process.argv.slice(2)) {
     process.exit(res.done ? 0 : 1);
   }
 
+  if (opts.tui && process.stdin.isTTY) {
+    runTui({ pack: make({ cwd }), model, getApiKey, sandbox: opts.sandbox, resume: opts.resume });
+    return;
+  }
+  if (opts.tui) console.error(gray('（--tui 需要真實終端，退回一般 CLI）'));
+
   runCli({
     pack: make({ cwd }), model, getApiKey,
     sandbox: opts.sandbox, resume: opts.resume, auto: opts.yes,
@@ -89,6 +100,7 @@ function parse(argv) {
     else if (a === '--model') o.model = argv[++i];
     else if (a === '--sandbox') o.sandbox = true;
     else if (a === '--yes' || a === '-y') o.yes = true;
+    else if (a === '--tui') o.tui = true;
     else if (a === '--goal') o.goal = argv[++i];
     else if (a === '--resume') { const nxt = argv[i + 1]; if (nxt && !nxt.startsWith('--')) { o.resume = nxt; i++; } else o.resume = true; }
   }
@@ -104,10 +116,13 @@ function printHelp() {
     '  xitto-kernel --pack general --goal "..." [--yes]         目標驅動自主循環（headless）',
     '  xitto-kernel new-agent <name>                            產出依賴 kernel 的獨立 agent 專案',
     '',
-    '  --pack <name>   選擇內建 DomainPack（coding | data-query | notes | general；預設 coding）',
+    '  --pack <name>   選擇內建 DomainPack（coding | data-query | notes | general | deep-research | devops；預設 coding）',
     '  --goal "..."    給目標，agent 自主反覆做到完成（建議搭配 --pack general）',
     '  --model <id>    指定 model（預設用 providers.json 的 defaultModel）',
     '  --sandbox       啟動即開啟沙箱（macOS=Seatbelt 真隔離）',
+    '  --tui           完整 Ink TUI（持久狀態列、串流轉錄、Esc 中斷；需真實終端）',
+    '  --resume [id]   接續上次 session（不給 id 接最近一次）',
+    '  --yes, -y       自動核准 mutating 工具（headless / 自主循環常用）',
     '  --help          顯示說明',
     '',
     '需要 ~/.xitto-code/providers.json（與 xitto-code 共用）。',

package/src/app/md-render.js

@@ -0,0 +1,95 @@
+// Markdown → 終端 ANSI 渲染（對標 Claude Code 的回覆排版）
+// 用 marked 解析、marked-terminal 轉 ANSI（標題、粗體、列表、表格、程式碼區塊語法高亮）。
+// Claude Code 的做法：每來一個 token 就把「目前累積的整段 markdown」重新解析重繪，
+// 半截的 **粗體 / 未閉合的 ``` 會在下一幀補齊後自動修正。本檔提供純函式 md()，
+// 重繪由 Ink 的 re-render 負責（見 tui.js）。
+import { Marked } from 'marked';
+import { markedTerminal } from 'marked-terminal';
+import { highlight as hl } from 'cli-highlight';
+
+// 終端寬度（隨視窗；最小 40 避免表格擠壞）
+function termWidth() {
+  const w = process.stdout?.columns || 80;
+  return Math.max(40, Math.min(w, 120));
+}
+
+// ANSI 樣式小工具（marked-terminal 的樣式選項接受 (str)=>str 函式）
+const a = (open, close) => (s) => `\x1b[${open}m${s}\x1b[${close}m`;
+const bold = a(1, 22);
+const cyan = a(36, 39);
+const yellow = a(33, 39);
+const gray = a(90, 39);
+
+// 程式碼區塊本體：語法高亮 + 左側豎線邊框（+ 可選語言標籤）。不含前後空行，方便外部逐塊拼接。
+// withHeader=false 用於「同一個 code block 的延續塊」（串流逐行提交時避免重複 ┌─ lang 標頭）。
+export function codeChunk(text, lang, withHeader = true) {
+  let body;
+  try { body = hl(text, { language: lang || 'plaintext', ignoreIllegals: true }); }
+  catch { body = text; }
+  const bar = gray('│') + ' ';
+  const label = (withHeader && lang) ? gray(`┌─ ${lang}`) + '\n' : '';
+  return label + body.replace(/\n$/, '').split('\n').map((l) => bar + l).join('\n');
+}
+
+// 程式碼區塊（marked renderer 用）：前後補空行與內文隔開
+function codeBlock(text, lang) {
+  return '\n' + codeChunk(text, lang, true) + '\n';
+}
+
+// 依寬度快取 Marked 實例：終端 resize 後寬度改變 → 換一個實例，markdown 自動以新寬度重排。
+// 上限保護：resize 反覆拖動會堆積不同寬度的實例，超過上限即淘汰最舊的(LRU 近似)。
+const cache = new Map();
+const MAX_CACHE = 32;
+function renderer(width) {
+  let m = cache.get(width);
+  if (!m) {
+    m = new Marked();
+    m.use(
+      markedTerminal({
+        width,
+        reflowText: true,
+        tab: 2,
+        showSectionPrefix: false,          // 不顯示標題的 # 記號（對標 Claude Code）
+        firstHeading: (s) => bold(cyan(s)), // 一級標題：粗體青
+        heading: (s) => bold(s),            // 其餘標題：粗體
+        strong: (s) => bold(s),
+        codespan: (s) => yellow(s),
+        blockquote: (s) => gray(s),
+        listitem: (s) => s,
+      }),
+    );
+    // 覆寫 code 渲染：加左側邊框（marked-terminal 內建無邊框）
+    m.use({
+      renderer: {
+        code(token, infostring) {
+          const text = typeof token === 'object' ? token.text : token;
+          const lang = (typeof token === 'object' ? token.lang : infostring) || '';
+          return codeBlock(text, lang);
+        },
+      },
+    });
+    if (cache.size >= MAX_CACHE) cache.delete(cache.keys().next().value); // 淘汰最舊
+    cache.set(width, m);
+  }
+  return m;
+}
+
+// 用 marked 的 block lexer 把 markdown 切成頂層區塊 token（含 .raw，串接即原文）。
+// 串流增量提交用：提交「除最後一塊外」的完整區塊，最後一塊（可能還沒打完）留在動態區。
+const lexMarked = new Marked();
+export function lexBlocks(text) {
+  try { return lexMarked.lexer(text); }
+  catch { return [{ type: 'paragraph', raw: text }]; }
+}
+
+// 把 markdown 字串渲染成帶 ANSI 的終端字串。容錯：解析失敗就回原文。
+export function md(text) {
+  if (!text) return '';
+  try {
+    const out = renderer(termWidth()).parse(text);
+    // 無序列表符號 * → •（marked-terminal 的 BULLET_POINT 寫死為 '* '）
+    return (typeof out === 'string' ? out : String(out)).replace(/\n+$/, '').replace(/^(\s*)\* /gm, '$1• ');
+  } catch {
+    return text;
+  }
+}

package/src/app/server.js

@@ -0,0 +1,102 @@
+// Server app（PoC）— 把 kernel 包成 HTTP 服務（零依賴 node:http）。
+// 證明 kernel 能脫離 CLI 跑成服務：bearer token 認證、per-session 隔離工作目錄、沙箱、結構化日誌、
+// JSON 或 SSE 串流。這是「另一個 app 消費同一組 kernel 事件」—— 不動 kernel 核心。
+import { createServer } from 'node:http';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createKernel } from '../kernel/index.js';
+import { loadModel } from './providers.js';
+import { createCodingPack } from '../packs/coding/index.js';
+import { createDataQueryPack } from '../packs/data-query/index.js';
+import { createNotesPack } from '../packs/notes/index.js';
+import { createGeneralPack } from '../packs/general/index.js';
+import { createDeepResearchPack } from '../packs/deep-research/index.js';
+import { createDevopsPack } from '../packs/devops/index.js';
+
+const PACKS = {
+  coding: createCodingPack, 'data-query': createDataQueryPack, notes: createNotesPack,
+  general: createGeneralPack, 'deep-research': createDeepResearchPack, devops: createDevopsPack,
+};
+
+const lastText = (history) => ([...(history || [])].reverse().find((m) => m.role === 'assistant')?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('');
+const newId = () => 's' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+
+/**
+ * @param {Object} o
+ * @param {object} o.model
+ * @param {Function} o.getApiKey
+ * @param {string} [o.token]        bearer token（未設＝不驗證，僅 PoC）
+ * @param {string} [o.baseDir]      每個 session 的隔離工作目錄根
+ * @param {boolean} [o.sandbox]     是否沙箱（預設 true：服務端跑 agent 應隔離）
+ * @returns {import('node:http').Server}
+ */
+export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-server', sandbox = true } = {}) {
+  const sessions = new Map(); // sessionId -> { pack, history }
+  mkdirSync(baseDir, { recursive: true });
+
+  const json = (res, code, obj) => { res.writeHead(code, { 'content-type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(obj)); };
+  const authed = (req) => !token || (req.headers.authorization === `Bearer ${token}`);
+  const log = (o) => console.log(JSON.stringify({ ts: new Date().toISOString(), ...o }));
+  const readBody = (req) => new Promise((resolve) => { let b = ''; req.on('data', (c) => { b += c; if (b.length > 1e6) req.destroy(); }); req.on('end', () => { try { resolve(JSON.parse(b || '{}')); } catch { resolve({}); } }); });
+
+  return createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    if (req.method === 'GET' && url.pathname === '/health') return json(res, 200, { ok: true, packs: Object.keys(PACKS), model: model.id });
+    if (!authed(req)) return json(res, 401, { error: 'unauthorized（帶 Authorization: Bearer <token>）' });
+
+    if (req.method === 'POST' && (url.pathname === '/v1/run' || url.pathname === '/v1/stream')) {
+      const body = await readBody(req);
+      const make = PACKS[body.pack || 'general'];
+      if (!make) return json(res, 400, { error: `未知 pack「${body.pack}」，可用：${Object.keys(PACKS).join(', ')}` });
+      const sessionId = body.sessionId || newId();
+      const sess = sessions.get(sessionId) || { pack: body.pack || 'general', history: [] };
+      const workdir = join(baseDir, sessionId); mkdirSync(workdir, { recursive: true });
+      const kernel = createKernel(make({ cwd: workdir }), { cwd: workdir, model, getApiKey, sandbox: { enabled: sandbox }, getSandbox: () => sandbox, confirm: async () => 'yes' });
+
+      const usage = { input: 0, output: 0 };
+      const streaming = url.pathname === '/v1/stream';
+      if (streaming) res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      const sse = (o) => res.write(`data: ${JSON.stringify(o)}\n\n`);
+      const onEvent = (ev) => {
+        if (ev.type === 'message_end' && ev.message?.usage) { usage.input += ev.message.usage.input || 0; usage.output += ev.message.usage.output || 0; }
+        if (!streaming) return;
+        if (ev.type === 'tool_execution_start') sse({ type: 'tool', name: ev.toolName, args: ev.args });
+        else if (ev.type === 'message_update' && ev.assistantMessageEvent?.type === 'text_delta') sse({ type: 'text', delta: ev.assistantMessageEvent.delta });
+      };
+
+      const t0 = Date.now();
+      try {
+        const r = (body.mode === 'goal')
+          ? await kernel.runGoal(body.goal || body.input || '', { history: sess.history, onEvent })
+          : await kernel.runTurn(body.input || '', { history: sess.history, onEvent });
+        sess.history = r.messages || r.history || []; sessions.set(sessionId, sess);
+        const text = r.text ?? lastText(sess.history);
+        log({ pack: sess.pack, session: sessionId, mode: body.mode || 'turn', tokens: usage.input + usage.output, rounds: r.rounds, ms: Date.now() - t0 });
+        const payload = { sessionId, text, usage, rounds: r.rounds, done: r.done };
+        if (streaming) { sse({ type: 'done', ...payload }); res.end(); }
+        else json(res, 200, payload);
+      } catch (e) {
+        log({ pack: sess.pack, session: sessionId, error: e.message });
+        if (streaming) { sse({ type: 'error', error: e.message }); res.end(); } else json(res, 500, { error: e.message });
+      }
+      return;
+    }
+    json(res, 404, { error: 'not found' });
+  });
+}
+
+export function startServer() {
+  const port = Number(process.env.PORT || 8787);
+  const token = process.env.XITTO_SERVER_TOKEN || 'dev-token';
+  const sandbox = process.env.XITTO_SERVER_SANDBOX !== 'off';
+  const { model, getApiKey } = loadModel(process.env.XITTO_MODEL);
+  const server = createServerApp({ model, getApiKey, token, sandbox });
+  server.listen(port, () => {
+    console.log(`xitto-kernel server · http://localhost:${port} · model ${model.id} · 沙箱 ${sandbox ? '開' : '關'}`);
+    console.log(`token: ${token === 'dev-token' ? 'dev-token（請設 XITTO_SERVER_TOKEN）' : '(已設定)'}`);
+  });
+  return server;
+}
+
+if (process.argv[1] && process.argv[1] === fileURLToPath(import.meta.url)) startServer();