xitto-kernel 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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 且在真實終端時，

package/README.md

@@ -72,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.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [

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;
 }