xitto-kernel 0.3.0 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.3.3
+
+- **背景任務 + 完成通知（非同步交互）**：server 新增「派任務→通知」形態，把 agent 當同事用。
+  - `POST /v1/tasks`：立刻回 `202 + taskId`，後台跑，完成 POST 結果到 `webhook`
+  - `GET /v1/tasks`、`GET /v1/tasks/:id`：列表 / 狀態 + 結果
+  - `GET /v1/tasks/:id/events`：附掛事件流（SSE，replay 緩衝 + 即時）
+  - 限流並發 `XITTO_SERVER_CONCURRENCY`（預設 2）
+  - 抽出 `createTaskStore`（純記憶體、可測）與 `mapEvent`；`/v1/run`/`/v1/stream` 共用 `runKernel`
+  - 5 個任務佇列測試（狀態轉移 / 限流 / 事件緩衝 / 完成回呼 / 訂閱）
+
+## 0.3.2
+
+- **沒設定就啟動 → 直接進導引**：偵測到沒有 providers.json 且在真實終端時，
+  不再只印提示，而是直接帶進 `init` 設定流程，完成後接續啟動該 pack（非 TTY 仍只給提示）。
+
+## 0.3.1
+
+首次使用導引 —— 不再假設使用者已有 xitto-code。
+
+### 新增
+
+- **`xitto-kernel init`**：互動式設定導引，產生 `~/.xitto-code/providers.json`
+  - 內建 provider 範本（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂）
+  - 引導選 provider → 填 model → 處理 API key（環境變數參照 `${NAME}` 不落地，或內嵌）
+  - 既有設定不覆寫；`--force` 合併新 provider
+  - pipe-safe 逐行讀取（可 `echo answers | xitto-kernel init` 腳本化）
+- **沒設定就啟動**：改丟明確提示，引導跑 `xitto-kernel init`（不再叫人去找 xitto-code 的範例檔）
+- README 快速開始改為 安裝 → `init` → 啟動 三步
+
 ## 0.3.0
 
 把底座的「能力」與「體驗」補到接近 Claude Code，並擴充領域 pack 與評測。

package/README.md

@@ -23,20 +23,26 @@ xitto-code 經掃描後，約 **8 成已是領域無關的 kernel**；真正跟
 
 ## 快速開始
 
-**前置需求**
-- Node.js ≥ 20
-- `~/.xitto-code/providers.json` —— LLM provider 設定（與 xitto-code 共用，內含 API key）。
-  沒有的話，複製一份填入 key 即可（格式見 xitto-code 的 `providers.example.json`）。
+**前置需求**：Node.js ≥ 20
 
-**安裝**（已發佈 npm）
+**1. 安裝**（已發佈 npm）
 ```bash
 npm install -g xitto-kernel    # 全域命令 xitto-kernel
 ```
 > 開發本倉庫：`cd xitto-kernel && npm install && npm link`。
 
-**跑內建 pack（互動 CLI）**
+**2. 首次設定**（互動導引，產生 `~/.xitto-code/providers.json`）
+```bash
+xitto-kernel init
+```
+引導你選 provider（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂）→ 填 model →
+設定 API key（建議用環境變數參照 `${NAME}`，金鑰不落地）。已是 xitto-code 使用者可直接共用既有設定、跳過此步。
+（沒設定就啟動會提示你跑 `init`；既有設定不會被覆寫，`--force` 才會合併新 provider。）
+
+**3. 跑內建 pack（互動 CLI）**
 ```bash
 xitto-kernel                  # coding agent（讀寫檔案、跑命令）
+xitto-kernel --tui            # 完整 Ink TUI（持久狀態列、串流、Esc 中斷；需真實終端）
 xitto-kernel --pack notes     # 筆記 / 知識庫 agent
 xitto-kernel --pack data-query
 xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱
@@ -66,6 +72,20 @@ curl -s -XPOST localhost:8787/v1/run -H "Authorization: Bearer secret" \
 結構化 JSON 日誌（審計/觀測）、6 個 pack 可選、JSON 或 SSE（`/v1/stream`）串流。
 「個人 vs 生產」是 **app 層**的事 —— 同一個 kernel，CLI 與 server 是兩個 app。
 
+**背景任務 + 完成通知（非同步交互）** —— 派任務出去、立刻拿到 `taskId`、做完回呼 webhook，不用一直盯著：
+```bash
+# 派任務（立刻回 202 + taskId），完成時 POST 結果到 webhook
+curl -s -XPOST localhost:8787/v1/tasks -H "Authorization: Bearer secret" \
+  -H content-type:application/json \
+  -d '{"pack":"general","mode":"goal","goal":"...","webhook":"https://你的服務/done"}'
+
+curl -s localhost:8787/v1/tasks            -H "Authorization: Bearer secret"   # 列表
+curl -s localhost:8787/v1/tasks/<id>       -H "Authorization: Bearer secret"   # 狀態 + 結果
+curl -sN localhost:8787/v1/tasks/<id>/events -H "Authorization: Bearer secret" # 附掛事件流（SSE，replay+即時）
+```
+限流並發 `XITTO_SERVER_CONCURRENCY`（預設 2）；webhook 完成時收到 `{taskId,status,text,usage,rounds,done}`。
+這把「即時盯著看」延伸到「派任務→通知」的非同步形態（像把 agent 當同事）。
+
 ## 做你自己的領域 agent（不固化）
 
 kernel 是**被依賴的套件**，不是被 clone 的範本。你的 agent 是獨立小專案：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [

package/src/app/init.js

@@ -0,0 +1,134 @@
+// 首次啟動導引：互動式產生 ~/.xitto-code/providers.json。
+// 內建常見 provider 範本（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂），
+// 引導選 provider → 填 model → 處理 API key（環境變數或內嵌），寫檔不覆寫既有設定。
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const e = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
+const green = e(32); const gray = e(90); const cyan = e(36); const yellow = e(33); const bold = e(1); const red = e(31);
+
+// provider 範本（沿用實測可用的格式；baseUrl/api/model 皆可在引導中改）
+const PRESETS = {
+  minimax: { label: 'MiniMax（M2.7，anthropic 相容）', api: 'anthropic-messages', baseUrl: 'https://api.minimaxi.com/anthropic', env: 'MINIMAX_API_KEY', model: { id: 'MiniMax-M2.7', name: 'MiniMax M2.7', contextWindow: 1000192, maxTokens: 131072 } },
+  anthropic: { label: 'Anthropic Claude', api: 'anthropic-messages', baseUrl: 'https://api.anthropic.com', env: 'ANTHROPIC_API_KEY', model: { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6', contextWindow: 200000, maxTokens: 64000 } },
+  openai: { label: 'OpenAI', api: 'openai-completions', baseUrl: 'https://api.openai.com/v1', env: 'OPENAI_API_KEY', model: { id: 'gpt-4o', name: 'GPT-4o', contextWindow: 128000, maxTokens: 16384 } },
+  deepseek: { label: 'DeepSeek', api: 'openai-completions', baseUrl: 'https://api.deepseek.com', env: 'DEEPSEEK_API_KEY', model: { id: 'deepseek-chat', name: 'DeepSeek Chat', contextWindow: 64000, maxTokens: 8192 } },
+  custom: { label: '自訂（手動填全部）', api: 'openai-completions', baseUrl: '', env: 'LLM_API_KEY', model: { id: '', name: '', contextWindow: 32000, maxTokens: 4096 } },
+};
+
+const PATH = () => process.env.XITTO_CODE_CONFIG || join(homedir(), '.xitto-code', 'providers.json');
+
+export { PRESETS };
+
+// 純函數：把答案組成 providers.json 結構（合併既有 providers）。互動殼與測試共用。
+export function buildConfig(a, existing) {
+  const cfg = existing && existing.providers ? existing : { defaultModel: a.modelId, providers: {} };
+  cfg.providers = cfg.providers || {};
+  cfg.providers[a.providerName] = {
+    baseUrl: a.baseUrl, apiKey: a.apiKey, api: a.api,
+    models: [{ id: a.modelId, name: a.modelName || a.modelId, contextWindow: a.contextWindow, maxTokens: a.maxTokens }],
+  };
+  cfg.defaultModel = a.modelId;
+  return cfg;
+}
+
+// pipe-safe 逐行讀取：把 'line' 事件排入佇列，即使管線一次送進整批輸入也能依序消費
+// （readline/promises 的 question() 在非 TTY 管線下會丟失已緩衝的行）。
+function makeAsker() {
+  const rl = createInterface({ input: process.stdin });
+  const queue = []; const waiters = []; let closed = false;
+  rl.on('line', (l) => { const w = waiters.shift(); if (w) w(l); else queue.push(l); });
+  rl.on('close', () => { closed = true; while (waiters.length) waiters.shift()(null); });
+  const nextLine = () => new Promise((res) => { if (queue.length) res(queue.shift()); else if (closed) res(null); else waiters.push(res); });
+  return {
+    close: () => rl.close(),
+    ask: async (q, def) => {
+      process.stdout.write(gray(q + (def ? ` [${def}]` : '') + ' '));
+      const line = await nextLine();
+      return ((line == null ? '' : line).trim()) || def || '';
+    },
+  };
+}
+
+export async function runInit(argv = []) {
+  const force = argv.includes('--force');
+  const path = PATH();
+  const io = makeAsker();
+  const rl = { close: io.close };
+  const ask = io.ask;
+
+  try {
+    console.log('\n' + bold('🚀 xitto-kernel 首次設定') + gray('  —— 建立 LLM provider 設定'));
+    console.log(gray(`設定檔：${path}\n`));
+
+    // 既有檔保護
+    if (existsSync(path) && !force) {
+      console.log(yellow(`已存在設定檔。`) + gray(' 用 `xitto-kernel init --force` 覆寫，或直接編輯該檔。'));
+      let cfg; try { cfg = JSON.parse(readFileSync(path, 'utf8')); } catch { /* 壞檔忽略 */ }
+      if (cfg) {
+        const names = Object.keys(cfg.providers || {});
+        console.log(gray(`  目前 provider：${names.join(', ') || '(無)'}　預設 model：${cfg.defaultModel || '(未設)'}`));
+      }
+      rl.close();
+      return;
+    }
+
+    // 1) 選 provider
+    const keys = Object.keys(PRESETS);
+    console.log(bold('1) 選 LLM provider：'));
+    keys.forEach((k, i) => console.log(`   ${cyan(String(i + 1))}. ${PRESETS[k].label}`));
+    const pick = await ask('輸入編號', '1');
+    const presetKey = keys[(parseInt(pick, 10) || 1) - 1] || 'minimax';
+    const preset = PRESETS[presetKey];
+    console.log(green(`   → ${preset.label}\n`));
+
+    // 2) 連線 / model
+    console.log(bold('2) 連線與 model：'));
+    const providerName = await ask('provider 名稱（providers.json 的鍵）', presetKey);
+    const baseUrl = await ask('baseUrl', preset.baseUrl);
+    const api = await ask('api 型別（anthropic-messages | openai-completions）', preset.api);
+    const modelId = await ask('model id', preset.model.id);
+    const modelName = await ask('model 顯示名', preset.model.name || modelId);
+    const contextWindow = parseInt(await ask('contextWindow', String(preset.model.contextWindow)), 10) || preset.model.contextWindow;
+    const maxTokens = parseInt(await ask('maxTokens', String(preset.model.maxTokens)), 10) || preset.model.maxTokens;
+    if (!modelId) { console.log(red('\nmodel id 不可空，已取消。')); rl.close(); return; }
+
+    // 3) API key：環境變數（建議）或內嵌
+    console.log('\n' + bold('3) API key：'));
+    console.log(gray('   a) 用環境變數參照（建議，金鑰不落地在設定檔）'));
+    console.log(gray('   b) 現在貼上金鑰（直接存進設定檔，檔案在你家目錄）'));
+    const mode = (await ask('選 a 或 b', 'a')).toLowerCase();
+    let apiKey; let envHint = '';
+    if (mode === 'b') {
+      const k = await ask('貼上 API key', '');
+      apiKey = k;
+      if (!k) console.log(yellow('   （未填，稍後請手動補上 apiKey）'));
+    } else {
+      const envName = await ask('環境變數名', preset.env);
+      apiKey = '${' + envName + '}';
+      envHint = envName;
+    }
+
+    // 組設定（保留既有 providers，--force 時合併）
+    let existing; if (existsSync(path)) { try { existing = JSON.parse(readFileSync(path, 'utf8')); } catch { /* 壞檔重建 */ } }
+    const cfg = buildConfig({ providerName, baseUrl, api, modelId, modelName, contextWindow, maxTokens, apiKey }, existing);
+
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+
+    console.log('\n' + green('✓ 已寫入 ') + path);
+    if (envHint) {
+      console.log('\n' + bold('下一步：設定環境變數（金鑰）'));
+      console.log(gray(`  export ${envHint}="你的金鑰"   # 加進 ~/.zshrc 永久生效`));
+    }
+    console.log('\n' + bold('啟動：'));
+    console.log(green('  xitto-kernel') + gray('               # coding pack，互動對話'));
+    console.log(green('  xitto-kernel --tui') + gray('         # 完整 Ink TUI（真實終端）'));
+    console.log(green('  xitto-kernel --pack general') + gray(' # 通用 agent'));
+    console.log('');
+  } finally {
+    rl.close();
+  }
+}

package/src/app/main.js

@@ -5,6 +5,7 @@ import { loadModel } from './providers.js';
 import { runCli } from './cli.js';
 import { runTui } from './tui-run.js';
 import { newAgent } from './scaffold.js';
+import { runInit } from './init.js';
 import { createKernel } from '../kernel/index.js';
 import { loadMcpTools } from '../kernel/mcp.js';
 import { createCodingPack } from '../packs/coding/index.js';
@@ -27,6 +28,9 @@ const PACKS = {
 };
 
 export async function main(argv = process.argv.slice(2)) {
+  // 子指令：init —— 首次設定導引，產生 providers.json
+  if (argv[0] === 'init') { await runInit(argv.slice(1)); return; }
+
   // 子指令：new-agent <name> —— 產出獨立 agent 專案（不碰 kernel）
   if (argv[0] === 'new-agent') {
     const name = argv.find((a, i) => i >= 1 && !a.startsWith('--'));
@@ -50,7 +54,26 @@ export async function main(argv = process.argv.slice(2)) {
 
   let model, getApiKey;
   try { ({ model, getApiKey } = loadModel(opts.model)); }
-  catch (err) { console.error('\x1b[31m' + err.message + '\x1b[0m'); process.exit(1); }
+  catch (err) {
+    // 沒設定 + 真實終端：直接帶進設定導引，完成後續跑；非 TTY 才只給提示
+    if (err.noConfig && process.stdin.isTTY) {
+      console.log(cyan('首次使用，沒找到 providers.json —— 進入設定導引。') + gray('（按 Ctrl+C 取消）'));
+      await runInit([]);
+      try { ({ model, getApiKey } = loadModel(opts.model)); }
+      catch (err2) {
+        console.error(red(err2.message));
+        console.error(gray(err2.noConfig ? '（未完成設定，已取消）' : '（設定好像缺東西，可編輯該檔或重跑 `xitto-kernel init`）'));
+        process.exit(1);
+      }
+    } else {
+      console.error(red(err.message));
+      if (err.noConfig) {
+        console.error('\n' + cyan('首次使用？') + ' 跑一次設定導引：');
+        console.error(green('  xitto-kernel init') + gray('   # 選 provider、填 model、設定 API key'));
+      }
+      process.exit(1);
+    }
+  }
 
   // MCP：啟動時連 .xitto-kernel/<pack>/mcp.json 的 server，工具以 extraTools 注入
   const cwd = process.cwd();
@@ -112,6 +135,7 @@ function printHelp() {
     'xitto-kernel — 領域無關 agent 底座',
     '',
     '用法:',
+    '  xitto-kernel init                                        首次設定導引（產生 providers.json）',
     '  xitto-kernel [--pack <name>] [--model <id>] [--sandbox] [--resume [id]] [--yes]   互動跑內建 pack',
     '  xitto-kernel --pack general --goal "..." [--yes]         目標驅動自主循環（headless）',
     '  xitto-kernel new-agent <name>                            產出依賴 kernel 的獨立 agent 專案',
@@ -125,7 +149,7 @@ function printHelp() {
     '  --yes, -y       自動核准 mutating 工具（headless / 自主循環常用）',
     '  --help          顯示說明',
     '',
-    '需要 ~/.xitto-code/providers.json（與 xitto-code 共用）。',
+    '首次使用先跑 `xitto-kernel init` 建立 ~/.xitto-code/providers.json（已是 xitto-code 使用者可直接共用）。',
     'new-agent 產出的是獨立專案，import xitto-kernel 而非修改它——升級不固化。',
   ].join('\n'));
 }

package/src/app/providers.js

@@ -7,7 +7,7 @@ import { join } from 'node:path';
 const DEFAULT_PATH = () => process.env.XITTO_CODE_CONFIG || join(homedir(), '.xitto-code', 'providers.json');
 
 export function loadProvidersConfig(path = DEFAULT_PATH()) {
-  if (!existsSync(path)) throw new Error(`找不到 providers.json：${path}\n（可複用 xitto-code 的 ~/.xitto-code/providers.json）`);
+  if (!existsSync(path)) { const err = new Error(`找不到 providers.json：${path}`); err.noConfig = true; throw err; }
   return { ...JSON.parse(readFileSync(path, 'utf8')), path };
 }
 

package/src/app/server.js

@@ -1,6 +1,7 @@
 // Server app（PoC）— 把 kernel 包成 HTTP 服務（零依賴 node:http）。
 // 證明 kernel 能脫離 CLI 跑成服務：bearer token 認證、per-session 隔離工作目錄、沙箱、結構化日誌、
-// JSON 或 SSE 串流。這是「另一個 app 消費同一組 kernel 事件」—— 不動 kernel 核心。
+// JSON 或 SSE 串流，以及「背景任務 + 完成通知（webhook）」—— 派任務出去、做完回呼，不用一直盯著。
+// 這是「另一個 app 消費同一組 kernel 事件」—— 不動 kernel 核心。
 import { createServer } from 'node:http';
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
@@ -20,7 +21,75 @@ const PACKS = {
 };
 
 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);
+const newId = (p = 's') => p + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+
+// 把原始 kernel 事件壓成精簡的對外事件（串流端與背景任務共用，避免重複映射）
+export const mapEvent = (ev) => {
+  if (ev.type === 'tool_execution_start') return { type: 'tool', name: ev.toolName, args: ev.args };
+  if (ev.type === 'tool_execution_end') return { type: 'tool_end', name: ev.toolName, isError: !!ev.isError };
+  if (ev.type === 'message_update' && ev.assistantMessageEvent?.type === 'text_delta') return { type: 'text', delta: ev.assistantMessageEvent.delta };
+  return null;
+};
+
+/**
+ * 背景任務佇列（純記憶體、可測，與 HTTP 無關）。
+ * 派任務 → 限流跑 → 緩衝事件供事後附掛 → 完成回呼（webhook）。
+ * @param {Object} o
+ * @param {(spec:object, emit:(ev:object)=>void)=>Promise<any>} o.runJob  實際執行（回傳值＝任務結果）
+ * @param {number} [o.concurrency]   同時跑幾個（預設 2）
+ * @param {(task:object)=>void} [o.onFinish]  每個任務 settle 後呼叫（拿來發 webhook）
+ * @param {number} [o.maxEvents]     每任務保留最近幾筆事件（預設 500）
+ */
+export function createTaskStore({ runJob, concurrency = 2, onFinish, maxEvents = 500 } = {}) {
+  const tasks = new Map();   // id -> task
+  const queue = [];          // 等待中的 task
+  const subs = new Map();    // id -> Set<(ev)=>void>
+  let active = 0;
+
+  const view = (t) => ({ taskId: t.id, status: t.status, pack: t.spec.pack || 'general', mode: t.spec.mode || 'turn', sessionId: t.result?.sessionId || t.spec.sessionId || null, createdAt: t.createdAt, startedAt: t.startedAt, finishedAt: t.finishedAt, error: t.error });
+
+  const emit = (t, ev) => {
+    t.events.push(ev);
+    if (t.events.length > maxEvents) t.events.shift();
+    const s = subs.get(t.id); if (s) for (const fn of s) { try { fn(ev); } catch { /* 訂閱端錯不影響任務 */ } }
+  };
+
+  function pump() {
+    while (active < concurrency && queue.length) {
+      const t = queue.shift();
+      active++;
+      t.status = 'running'; t.startedAt = new Date().toISOString();
+      emit(t, { type: 'status', status: 'running' });
+      Promise.resolve()
+        .then(() => runJob(t.spec, (ev) => emit(t, ev)))
+        .then((result) => { t.status = 'done'; t.result = result; })
+        .catch((e) => { t.status = 'error'; t.error = e.message || String(e); })
+        .finally(() => {
+          t.finishedAt = new Date().toISOString();
+          emit(t, { type: 'end', status: t.status, result: t.result, error: t.error });
+          active--;
+          try { onFinish?.(t); } catch { /* webhook 錯不影響佇列 */ }
+          pump();
+        });
+    }
+  }
+
+  return {
+    enqueue(spec) {
+      const t = { id: newId('t'), status: 'queued', spec: spec || {}, events: [], result: null, error: null, createdAt: new Date().toISOString(), startedAt: null, finishedAt: null };
+      tasks.set(t.id, t);
+      queue.push(t);
+      pump();
+      return t;
+    },
+    get: (id) => tasks.get(id),
+    view: (id) => { const t = tasks.get(id); return t ? view(t) : null; },
+    result: (id) => { const t = tasks.get(id); return t ? { ...view(t), result: t.result } : null; },
+    list: () => [...tasks.values()].map(view),
+    subscribe(id, fn) { let s = subs.get(id); if (!s) { s = new Set(); subs.set(id, s); } s.add(fn); return () => s.delete(fn); },
+    stats: () => ({ active, queued: queue.length, total: tasks.size }),
+  };
+}
 
 /**
  * @param {Object} o
@@ -29,9 +98,10 @@ const newId = () => 's' + Date.now().toString(36) + Math.random().toString(36).s
  * @param {string} [o.token]        bearer token（未設＝不驗證，僅 PoC）
  * @param {string} [o.baseDir]      每個 session 的隔離工作目錄根
  * @param {boolean} [o.sandbox]     是否沙箱（預設 true：服務端跑 agent 應隔離）
+ * @param {number} [o.concurrency]  背景任務同時數（預設 2）
  * @returns {import('node:http').Server}
  */
-export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-server', sandbox = true } = {}) {
+export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-server', sandbox = true, concurrency = 2 } = {}) {
   const sessions = new Map(); // sessionId -> { pack, history }
   mkdirSync(baseDir, { recursive: true });
 
@@ -39,49 +109,93 @@ export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-ser
   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({}); } }); });
+  const sseHead = (res) => res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive' });
+
+  // 共用：跑一輪/一目標，回傳 { sessionId, text, usage, rounds, done }；onEvent 收原始 kernel 事件
+  async function runKernel(spec, onEvent) {
+    const make = PACKS[spec.pack || 'general'];
+    if (!make) throw new Error(`未知 pack「${spec.pack}」，可用：${Object.keys(PACKS).join(', ')}`);
+    const sessionId = spec.sessionId || newId();
+    const sess = sessions.get(sessionId) || { pack: spec.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 wrapped = (ev) => { if (ev.type === 'message_end' && ev.message?.usage) { usage.input += ev.message.usage.input || 0; usage.output += ev.message.usage.output || 0; } onEvent?.(ev); };
+    const r = (spec.mode === 'goal')
+      ? await kernel.runGoal(spec.goal || spec.input || '', { history: sess.history, onEvent: wrapped })
+      : await kernel.runTurn(spec.input || '', { history: sess.history, onEvent: wrapped });
+    sess.history = r.messages || r.history || []; sessions.set(sessionId, sess);
+    return { sessionId, text: r.text ?? lastText(sess.history), usage, rounds: r.rounds, done: r.done };
+  }
+
+  // 完成通知：POST 結果到 spec.webhook（http/https），單次嘗試、失敗記日誌不重試（PoC）
+  async function fireWebhook(task) {
+    const url = task.spec.webhook; if (!url || !/^https?:\/\//.test(url)) return;
+    const r = task.result || {};
+    const body = JSON.stringify({ taskId: task.id, status: task.status, error: task.error, sessionId: r.sessionId, text: r.text, usage: r.usage, rounds: r.rounds, done: r.done, finishedAt: task.finishedAt });
+    try { const resp = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body }); log({ webhook: url, task: task.id, status: task.status, code: resp.status }); }
+    catch (e) { log({ webhook: url, task: task.id, error: e.message }); }
+  }
+
+  const tasks = createTaskStore({
+    concurrency,
+    runJob: (spec, emit) => runKernel(spec, (ev) => { const m = mapEvent(ev); if (m) emit(m); }),
+    onFinish: (task) => { log({ task: task.id, pack: task.spec.pack, mode: task.spec.mode || 'turn', status: task.status, ms: task.startedAt ? Date.parse(task.finishedAt) - Date.parse(task.startedAt) : 0 }); fireWebhook(task); },
+  });
 
   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 });
+    const path = url.pathname;
+    if (req.method === 'GET' && path === '/health') return json(res, 200, { ok: true, packs: Object.keys(PACKS), model: model.id, tasks: tasks.stats() });
     if (!authed(req)) return json(res, 401, { error: 'unauthorized（帶 Authorization: Bearer <token>）' });
 
-    if (req.method === 'POST' && (url.pathname === '/v1/run' || url.pathname === '/v1/stream')) {
+    // 同步：跑完才回（JSON 或 SSE 串流）
+    if (req.method === 'POST' && (path === '/v1/run' || path === '/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 streaming = path === '/v1/stream';
+      if (streaming) sseHead(res);
       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);
+        const r = await runKernel(body, streaming ? (ev) => { const m = mapEvent(ev); if (m) sse(m); } : undefined);
+        log({ pack: body.pack || 'general', session: r.sessionId, mode: body.mode || 'turn', tokens: r.usage.input + r.usage.output, rounds: r.rounds, ms: Date.now() - t0 });
+        if (streaming) { sse({ type: 'done', ...r }); res.end(); } else json(res, 200, r);
       } 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 });
+        log({ pack: body.pack, error: e.message });
+        if (streaming) { sse({ type: 'error', error: e.message }); res.end(); } else json(res, e.message?.startsWith('未知 pack') ? 400 : 500, { error: e.message });
       }
       return;
     }
+
+    // 背景任務：立刻回 taskId，後台跑，完成發 webhook
+    if (req.method === 'POST' && path === '/v1/tasks') {
+      const body = await readBody(req);
+      if (!PACKS[body.pack || 'general']) return json(res, 400, { error: `未知 pack「${body.pack}」，可用：${Object.keys(PACKS).join(', ')}` });
+      if (body.webhook && !/^https?:\/\//.test(body.webhook)) return json(res, 400, { error: 'webhook 需為 http(s) URL' });
+      const t = tasks.enqueue({ pack: body.pack, mode: body.mode, input: body.input, goal: body.goal, sessionId: body.sessionId, webhook: body.webhook });
+      log({ task: t.id, action: 'enqueue', pack: body.pack || 'general', mode: body.mode || 'turn' });
+      return json(res, 202, { taskId: t.id, status: t.status, ...tasks.stats() });
+    }
+    if (req.method === 'GET' && path === '/v1/tasks') return json(res, 200, { tasks: tasks.list(), ...tasks.stats() });
+
+    // 任務狀態 / 結果
+    const mTask = path.match(/^\/v1\/tasks\/([^/]+)$/);
+    if (req.method === 'GET' && mTask) { const v = tasks.result(mTask[1]); return v ? json(res, 200, v) : json(res, 404, { error: 'task not found' }); }
+
+    // 附掛背景任務的事件流（replay 緩衝 + 即時；已結束則回放後關閉）
+    const mEv = path.match(/^\/v1\/tasks\/([^/]+)\/events$/);
+    if (req.method === 'GET' && mEv) {
+      const task = tasks.get(mEv[1]);
+      if (!task) return json(res, 404, { error: 'task not found' });
+      sseHead(res);
+      const sse = (o) => res.write(`data: ${JSON.stringify(o)}\n\n`);
+      for (const ev of task.events) sse(ev);
+      if (task.status === 'done' || task.status === 'error') { res.end(); return; }
+      const unsub = tasks.subscribe(task.id, (ev) => { sse(ev); if (ev.type === 'end') { try { unsub(); } catch { /* 略 */ } res.end(); } });
+      req.on('close', () => { try { unsub(); } catch { /* 略 */ } });
+      return;
+    }
+
     json(res, 404, { error: 'not found' });
   });
 }
@@ -90,11 +204,13 @@ 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 concurrency = Number(process.env.XITTO_SERVER_CONCURRENCY || 2);
   const { model, getApiKey } = loadModel(process.env.XITTO_MODEL);
-  const server = createServerApp({ model, getApiKey, token, sandbox });
+  const server = createServerApp({ model, getApiKey, token, sandbox, concurrency });
   server.listen(port, () => {
-    console.log(`xitto-kernel server · http://localhost:${port} · model ${model.id} · 沙箱 ${sandbox ? '開' : '關'}`);
+    console.log(`xitto-kernel server · http://localhost:${port} · model ${model.id} · 沙箱 ${sandbox ? '開' : '關'} · 背景並發 ${concurrency}`);
     console.log(`token: ${token === 'dev-token' ? 'dev-token（請設 XITTO_SERVER_TOKEN）' : '(已設定)'}`);
+    console.log('路由：POST /v1/run · /v1/stream · /v1/tasks（背景+webhook）｜GET /v1/tasks[/:id[/events]] · /health');
   });
   return server;
 }