xitto-kernel 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 0.5.0
+
+- **持久工作空間（許願台成品間的關係）**：每個成品仍是獨立對話,但共用一個持久工作空間。
+  - server workdir 改綁 `workspace`（`.xitto-server/ws/<workspace>`,預設 `default`）而非每 job 丟棄式 sessionId
+  - 效果:① 檔案留存,後續任務能接續前面成果;② **五層沉澱跨成品累積**(偏好/技能/經驗/信任)——越用越懂你
+  - history 仍每 job 獨立（不續接,避免 context 暴脹）;`workspace` 可在 POST 指定（多使用者隔離）
+  - 交付檔案端點與 webhook 改用 workspace 解析；result 帶 `workspace`
+- **待辦打勾**：`todo_write` 的清單進 `progress.todos`,UI 顯示 ☐/◐/☑（把「未知時長」變「可見剩餘步數」,對標 Claude Code）
+- **可中斷（取消鈕）**：`POST /v1/tasks/:id/cancel` → abort 進行中 agent / 移除排隊 / 解除待答；UI「停止」鈕;狀態 `cancelled`
+- 5 個新測試（取消 running/queued/已結束/待答 + todo 進度）+ 真實 server 端到端
+  （Job2 接續 Job1 的檔案與記憶、todo 打勾、長任務中途取消）
+- 緣由:對標 Claude Code 處理「等待焦慮」——liveness(心跳)+ transparency(進度/待辦)+ control(可中斷)
+
+## 0.4.6
+
+- **許願台「活著的證明」**：解決「只顯示進行中、不知道是否真的在跑」。
+  - **每秒心跳時鐘**「已進行 Ns」：UI 端 1 秒 ticker（不靠 poll）,即使沒有新事件也持續跳動 → 看得到它活著
+  - **思考文字可見**：progress 新增 `thinking`——累積 agent 當下串流的文字,在「思考中」階段顯示 💭 它在想什麼
+    （tool/round 後清空；不存進 view 的 buffer 用 `t._textbuf`）
+  - phase 新增 `thinking`；poll 由 1500ms 縮到 1200ms
+  - 真實 live 驗證:時鐘 0→16s 連續跳動,階段 starting→thinking(💭)→acting(建檔→讀檔)→done
+  - 1 個新測試（text 事件累積 thinking、tool/round 清空）。測試 166/166。
+
+## 0.4.5
+
+- **修：CLI 澄清提問被 spinner 蓋住，導致回答疑似沒被採用**。
+  - `askUserQuestion` / `askConfirm` 提問前先 `stopSpin()`——否則「思考中…」spinner 每 100ms 覆蓋掉
+    `❓ 問題` 與你的輸入列,使用者根本看不到 agent 在問,打的字也對不上 → 看起來像回答被忽略
+  - ask_user 提問加上「agent 想問你：」更醒目
+  - `ask_user` 工具結果改為自帶 `{ question, answer, note }`：把回答標為權威依據,長對話也不脫鉤
+  - 驗證:kernel/server 的回答鏈本來就正確（單輪 + 多輪 live 測試:round-1 回答在 round-2 仍被採用）;
+    本修針對互動 CLI 的顯示遮蔽問題
+
+## 0.4.4
+
+- **即時進度（許願台不再只顯示「進行中」）**：讓非技術使用者看得到 agent 在做什麼。
+  - 任務 view 新增 `progress`：`{ phase, round, steps, recent[] }`——從事件流累積（排除 text 雜訊）
+  - `mapEvent` 補 `round` / `verify`→`phase` 事件；goal 模式 wire `onRound` → 進度有輪數
+  - 網頁把工具動作翻成人話（讀取檔案/執行指令/搜尋網路…）+ 第幾輪 + 動作數 + 動畫指示,取代靜態轉圈
+  - `recent` 只留最近 6 個動作避免膨脹
+  - 3 個測試（mapEvent 新事件 + progress 累積/上限）+ 真實端到端（進度快照逐步演進）
+
+## 0.4.3
+
+- **許願台網頁（結果導向第三刀）**：給非技術使用者的瀏覽器介面,以結果為中心、不是聊天。
+  - server 服務 `GET /` → 單一 HTML（`src/app/web/index.html`,零依賴 vanilla,polling 不靠 SSE）
+  - 介面:許願(送目標)→ 進行中狀態 → needs-input 時跳問題+回答框 → 收成品(摘要+產出檔案)→ 歷史清單
+  - 新增 `GET /v1/tasks/:id/file?path=`：取交付檔案內容（點檔名看成品）；`resolveArtifact` 防路徑穿越
+  - 任務 view 補 `goal`（顯示願望）；token 注入頁面供同源呼叫（本地自用零設定,正式部署需前置認證）
+  - 2 個測試（resolveArtifact 穿越防護 + GET / 服務頁面/token 注入/API 仍需 auth）+ 真實端到端
+    （許願→交付 hello.txt→點開看內容→穿越攻擊擋下）
+  - 「許願→交付」三刀完成:交付抽象 + 澄清通道 + Job 介面
+
+## 0.4.2
+
+- **澄清通道（結果導向第二刀）**：agent 只在非問不可時暫停提問,而非盲猜或頻繁打擾。
+  - 新增 `ask_user` 工具（app 提供 `config.askUser` 才注入；readOnly）；prompt 引導節制使用(能合理推斷就別問)
+  - **CLI**：`askUser` 內嵌提問,使用者打字回答,agent 續跑
+  - **背景任務 pause/resume**：`createTaskStore` 的 `runJob` 多收 `ask`；呼叫即轉 `needs-input` 並掛起問題;
+    新增 `POST /v1/tasks/:id/answer` 回答後解除暫停、續跑（完全非同步,可隔很久才答）
+  - 任務 view 帶 `pending`（待答問題）；事件流發 `needs_input` / `answered`
+  - 4 個測試（工具有無/回空提示 + 佇列 pause/answer/resume + 無待答回 false）+ 真實 server 端到端
+    （under-spec 目標 → agent 暫停問檔名/內容 → 答完交付正確檔案）
+
+## 0.4.1
+
+- **結果導向：交付物為一等公民（「對話只是過程」）**：第一刀朝非技術使用者的「許願→交付」模型。
+  - 新增 `api.runOutcome(goal, opts)`：跑 goal loop,回傳**交付物** `{ done, summary, artifacts:{created,modified}, rounds, history }`
+  - 交付物偵測：掃工作目錄前後 diff（pack 無關,連 bash 寫的檔也抓；排除 .xitto-kernel/node_modules/.git）
+  - `--goal` 改印交付物（📦 產出/改動檔案 + 📝 摘要),不再只報達成輪數
+  - server `POST /v1/tasks`（mode=goal）回 `artifacts`；背景任務 webhook payload 也帶 `artifacts`
+  - 3 個測試（created/modified/無變動 + 內部沉澱檔不算交付物）+ 真實 model 端到端（產出 greet.js/example.js）
+  - 後續規劃:澄清通道（ask_user 暫停/續跑）、Job 介面（成品歷史）
+
 ## 0.4.0
 
 **「執行中沉澱經驗」五層完整**（反射 / 事實 / 程序 / 情節 / 結晶）——里程碑。

package/README.md

@@ -78,6 +78,38 @@ xitto-kernel --pack general --yes --goal "抓取 example.com 摘要成繁中寫
 ```
 `general` pack（檔案/shell/web_fetch）+ kernel 的 **goal loop**（反覆 runTurn + LLM 自我驗收，直到達成/無進展/上限）。互動模式用 `/goal <目標>`。
 
+**結果導向：對話只是過程，交付物才是產品**
+
+對非技術使用者,真正要的不是「跟 AI 聊天」,是「把事做完、給我結果」。`api.runOutcome(goal)` 跑 goal loop,回傳的不是對話而是**交付物**：
+```js
+const o = await kernel.runOutcome('建立 greet.js 並寫個範例驗證');
+// → { done, summary（做了什麼）, artifacts: { created:[...], modified:[...] }, rounds }
+```
+`--goal` 與 server 的 `POST /v1/tasks`（mode=goal）都會回交付物——**產出/改動的檔案**(掃工作目錄前後 diff,連 bash 寫的也抓)+ 摘要 + 是否達成。對話被降格成過程,結果(檔案/達成)被擺到最前面。背景任務的 webhook 也帶 `artifacts`。
+
+**澄清通道（只在非問不可時才打斷你）**：自主交付的風險是「自主走錯」。`ask_user` 工具讓 agent 在**缺少關鍵資訊、無法合理推斷**時暫停提問——而非盲猜或頻繁打擾(prompt 明確引導:能用合理預設就別問)。由 app 注入 `config.askUser` 決定「問」的形態：
+- **CLI**：內嵌提問,你打字回答,agent 續跑
+- **背景任務**：任務轉 `needs-input` 狀態並掛起問題 → 你 `POST /v1/tasks/:id/answer` 回答 → 解除暫停、續跑(可隔數小時才答,完全非同步)
+
+實測:給「建個設定檔但檔名/內容我還沒決定」→ agent 不亂猜,暫停問你檔名與內容 → 答完才交付正確的 `app.config.json`。這讓「許願→交付」既自主又不失控。
+
+**🪄 許願台網頁（給非技術使用者：瀏覽器打開就用）**
+```bash
+XITTO_SERVER_TOKEN=secret npm run serve   # 然後瀏覽器開 http://localhost:8787/
+```
+不用終端機、不用碰金鑰(伺服器端管)。介面以**結果**為中心,不是聊天:
+- **許願**:打一句「你想完成什麼」→ 交辦(背景跑 goal loop)
+- **進行中**:**即時進度 + 活著的證明**——每秒跳動的「已進行 Ns」心跳時鐘、目前階段(思考中/執行中/驗收中)、agent 當下的**思考文字**(💭)、工具動作翻成人話、第幾輪 + 動作數。看得到它在想什麼、做什麼
+- **待辦打勾**:agent 用 `todo_write` 規劃多步任務時,顯示 ☐/◐/☑ 清單,把「未知時長」變成「看得到的剩餘步數」(對標 Claude Code)
+- **隨時可停**:每個進行中任務有「停止」鈕 → `POST /v1/tasks/:id/cancel`(abort 正在跑的 agent)。控制權在使用者手上,降低「啟動了控制不了的東西」的焦慮
+- **需要你回答**:agent 暫停提問時,跳出問題 + 回答框(澄清通道)
+- **收成品**:完成後顯示摘要 + **產出的檔案**,點檔名可直接看內容(`GET /v1/tasks/:id/file`,防路徑穿越)
+- **歷史成品**:過往交辦的清單(願望 + 狀態),不是聊天串
+
+**持久工作空間(成品間的關係)**:每個成品是**獨立的對話**(不續接前一個,避免 context 暴脹),但**共用一個持久工作空間**(`.xitto-server/ws/<workspace>`,預設 `default`)——所以 ① **檔案留存**,後面的任務能接續前面的成果(「把我上次做的 plan.md 翻成英文」);② **五層沉澱跨成品累積**(偏好/技能/經驗/信任)——它**越用越懂你**,不再是每次都從零開始的陌生人。`workspace` 可在 POST 時指定(多使用者各自一個)。
+
+零依賴單一 HTML(`src/app/web/index.html`),polling 不靠 SSE。token 注入頁面供同源呼叫——本地自用零設定;**正式部署請前置真實認證**。
+
 ## 當成服務跑（不只 CLI）
 
 kernel 是 UI 無關的，CLI 只是其中一個 app。`src/app/server.js` 是把它包成 **HTTP 服務**的 PoC

package/package.json

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

package/src/app/cli.js

@@ -37,6 +37,8 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     getPlanMode: () => planMode,            // 計劃模式：守衛擋 mutating 工具
     autoExtractMemory: true,                // 事實層：每輪後自動萃取持久事實進記憶（非阻塞）
     confirm: askConfirm,                    // 互動權限確認（mutating/危險工具執行前）
+    askUser: askUserQuestion,               // 澄清通道：agent 非問不可時向使用者提問並等待
+
     onTrusted: ({ name, signature, scope }) => {            // 漸進放權：自動放行時標示「已信任」（維持可理解）
       endStream();
       out(c.gray(`  ✓ 已信任 ${scope === 'command' ? `「${signature}」類` : name}，自動放行\n`));
@@ -71,6 +73,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   // 回 'yes'（允許一次）/ 'command'（信任此命令簽章類,跨 session）/ 'always'（信任此工具全部）/ 'no'（拒絕）。
   async function askConfirm(name, args, danger, meta = {}) {
     if (autoApprove && !danger) return 'yes';   // 自動模式仍對危險命令把關
+    stopSpin();                                 // 停 spinner,否則它每 100ms 蓋掉提問/輸入列
     endStream();
     const sig = meta.signature; // 有簽章（bash 類）才提供細粒度「信任這類命令」
     return new Promise((res) => {
@@ -92,6 +95,17 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     });
   }
 
+  // 澄清通道：agent 呼叫 ask_user 時,內嵌問使用者並等待回答（自由文字；options 只當提示）
+  async function askUserQuestion({ question, options }) {
+    stopSpin();                                 // 關鍵：停 spinner,否則它會蓋掉問題與你的輸入,讓你看不到 agent 在問
+    endStream();
+    out('\n' + c.cyan('  ❓ agent 想問你：') + c.bold(String(question || '')) + '\n');
+    if (Array.isArray(options) && options.length) out(c.gray('     選項：' + options.map((o, i) => `${i + 1}) ${o}`).join('   ')) + '\n');
+    return new Promise((res) => {
+      try { rl.question(c.cyan('  你的回答 › '), (ans) => res((ans || '').trim())); } catch { res(''); }
+    });
+  }
+
   // session：續接（--resume [id]）或開新；每輪結束自動存檔
   let sessionId = kernel.session.newId();
   let resumedNote = '';

package/src/app/main.js

@@ -87,7 +87,7 @@ export async function main(argv = process.argv.slice(2)) {
       confirm: opts.yes ? (async () => 'yes') : undefined, // headless：--yes 才自動核准 mutating
     });
     console.log(cyan('🎯 目標：') + opts.goal + gray(`  ·  ${opts.pack} pack · ${model.id}`));
-    const res = await kernel.runGoal(opts.goal, {
+    const res = await kernel.runOutcome(opts.goal, {
       onRound: ({ round, maxRounds }) => console.log(yellow(`\n🔁 第 ${round}/${maxRounds} 輪`)),
       onCheck: ({ done, remaining }) => console.log(done ? green('  ✓ 驗收：已達成') : gray(`  ↻ 驗收：${remaining}`)),
       onEvent: (ev) => {
@@ -95,8 +95,16 @@ export async function main(argv = process.argv.slice(2)) {
         if (ev.type === 'tool_execution_end') console.log(ev.isError ? red('    ⎿ ✗') : gray('    ⎿ ✓'));
       },
     });
-    const why = res.stalled ? '無進展停止' : res.aborted ? '中斷' : res.verifyBroken ? '驗收持續失敗' : '到上限';
-    console.log('\n' + (res.done ? green(`✅ 目標達成（${res.rounds} 輪）`) : yellow(`⚠ 未達成（${why}，${res.rounds} 輪）`)));
+    // 交付物（對話只是過程，這才是產品）
+    const why = res.stalled ? '無進展停止' : res.aborted ? '中斷' : '到上限';
+    console.log('\n' + (res.done ? green(`✅ 已交付（${res.rounds} 輪）`) : yellow(`⚠ 未完成（${why}，${res.rounds} 輪）`)));
+    const { created, modified } = res.artifacts;
+    if (created.length || modified.length) {
+      console.log(cyan('📦 產出檔案：'));
+      created.forEach((f) => console.log(green(`   + ${f}`)));
+      modified.forEach((f) => console.log(yellow(`   ~ ${f}`)));
+    } else console.log(gray('   （沒有檔案變動）'));
+    if (res.summary) console.log(cyan('📝 摘要：') + gray(res.summary.slice(0, 400)));
     try { await mcp.close(); } catch { /* 略 */ }
     process.exit(res.done ? 0 : 1);
   }

package/src/app/server.js

@@ -3,8 +3,8 @@
 // JSON 或 SSE 串流，以及「背景任務 + 完成通知（webhook）」—— 派任務出去、做完回呼，不用一直盯著。
 // 這是「另一個 app 消費同一組 kernel 事件」—— 不動 kernel 核心。
 import { createServer } from 'node:http';
-import { mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, dirname, isAbsolute, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createKernel } from '../kernel/index.js';
 import { loadModel } from './providers.js';
@@ -23,11 +23,25 @@ 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 = (p = 's') => p + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
 
+// 交付檔案路徑解析（防穿越）：rel 必須是 workdir 內的相對路徑,否則回 null。
+export function resolveArtifact(workdir, rel) {
+  if (typeof rel !== 'string' || !rel || isAbsolute(rel)) return null;
+  const full = join(workdir, rel);
+  const r = relative(workdir, full);
+  return (r.startsWith('..') || isAbsolute(r)) ? null : full;
+}
+
+let _webHtml;
+const webHtml = () => (_webHtml ??= readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'web', 'index.html'), 'utf8'));
+
 // 把原始 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 };
+  if (ev.type === 'round') return { type: 'round', round: ev.round, maxRounds: ev.maxRounds };
+  if (ev.type === 'verify_start') return { type: 'phase', phase: 'verifying' };
+  if (ev.type === 'verify_end') return { type: 'phase', phase: ev.ok ? 'verified' : 'fixing' };
   return null;
 };
 
@@ -46,14 +60,31 @@ export function createTaskStore({ runJob, concurrency = 2, onFinish, maxEvents =
   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 view = (t) => ({ taskId: t.id, status: t.status, pack: t.spec.pack || 'general', mode: t.spec.mode || 'turn', goal: t.spec.goal || t.spec.input || '', sessionId: t.result?.sessionId || t.spec.sessionId || null, createdAt: t.createdAt, startedAt: t.startedAt, finishedAt: t.finishedAt, error: t.error, pending: t.pending || null, progress: t.progress || null });
 
   const emit = (t, ev) => {
     t.events.push(ev);
     if (t.events.length > maxEvents) t.events.shift();
+    // 進度追蹤（給 UI 顯示「正在做什麼」,不要只顯示進行中；排除 text 雜訊）
+    const p = (t.progress ||= { steps: 0, round: 0, maxRounds: 0, recent: [], phase: 'starting', thinking: '', todos: [] });
+    if (ev.type === 'tool' && ev.name === 'todo_write') { if (Array.isArray(ev.args?.todos)) p.todos = ev.args.todos; } // 待辦清單（給 UI 打勾）
+    else if (ev.type === 'tool') { p.steps++; p.phase = 'acting'; p.thinking = ''; t._textbuf = ''; p.recent.push({ name: ev.name, args: ev.args }); if (p.recent.length > 6) p.recent.shift(); }
+    else if (ev.type === 'text') { p.phase = 'thinking'; t._textbuf = ((t._textbuf || '') + (ev.delta || '')).slice(-400); p.thinking = t._textbuf.replace(/\s+/g, ' ').trim().slice(-150); }
+    else if (ev.type === 'round') { p.round = ev.round; if (ev.maxRounds) p.maxRounds = ev.maxRounds; p.thinking = ''; t._textbuf = ''; }
+    else if (ev.type === 'phase') p.phase = ev.phase;
+    else if (ev.type === 'needs_input') p.phase = 'needs-input';
+    else if (ev.type === 'answered') p.phase = 'acting';
+    else if (ev.type === 'end') p.phase = ev.status;
     const s = subs.get(t.id); if (s) for (const fn of s) { try { fn(ev); } catch { /* 訂閱端錯不影響任務 */ } }
   };
 
+  // 澄清通道：job 呼叫 ask({question,options}) → 任務轉 needs-input、暫停,直到有人 answer()
+  const makeAsk = (t) => ({ question, options }) => {
+    t.status = 'needs-input'; t.pending = { question: String(question || ''), options: options || null };
+    emit(t, { type: 'needs_input', question: t.pending.question, options: t.pending.options });
+    return new Promise((resolve) => { t._answer = resolve; });
+  };
+
   function pump() {
     while (active < concurrency && queue.length) {
       const t = queue.shift();
@@ -61,10 +92,11 @@ export function createTaskStore({ runJob, concurrency = 2, onFinish, maxEvents =
       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(() => runJob(t.spec, (ev) => emit(t, ev), makeAsk(t), (agent) => { t._agent = agent; }))
         .then((result) => { t.status = 'done'; t.result = result; })
         .catch((e) => { t.status = 'error'; t.error = e.message || String(e); })
         .finally(() => {
+          if (t._cancelling && t.status !== 'error') t.status = 'cancelled'; // 使用者中斷
           t.finishedAt = new Date().toISOString();
           emit(t, { type: 'end', status: t.status, result: t.result, error: t.error });
           active--;
@@ -87,6 +119,31 @@ export function createTaskStore({ runJob, concurrency = 2, onFinish, maxEvents =
     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); },
+    // 中斷任務（取消鈕）：排隊中 → 直接移除；進行中 → abort agent；待答中 → 解除阻塞後 abort。
+    cancel(id) {
+      const t = tasks.get(id);
+      if (!t || ['done', 'error', 'cancelled'].includes(t.status)) return false;
+      t._cancelling = true;
+      if (t.status === 'queued') {
+        const i = queue.indexOf(t); if (i >= 0) queue.splice(i, 1);
+        t.status = 'cancelled'; t.finishedAt = new Date().toISOString();
+        emit(t, { type: 'end', status: 'cancelled' });
+        return true;
+      }
+      if (typeof t._answer === 'function') { const r = t._answer; t._answer = null; t.pending = null; r(''); } // 解除待答阻塞
+      if (t._agent && typeof t._agent.abort === 'function') { try { t._agent.abort(); } catch { /* 略 */ } }
+      emit(t, { type: 'cancelling' });
+      return true;
+    },
+    // 回答一個待答任務 → 解除暫停、續跑。回 true 表示有對應的待答問題。
+    answer(id, text) {
+      const t = tasks.get(id);
+      if (!t || typeof t._answer !== 'function') return false;
+      const resolve = t._answer; t._answer = null; t.pending = null; t.status = 'running';
+      emit(t, { type: 'answered', answer: String(text ?? '') });
+      resolve(String(text ?? ''));
+      return true;
+    },
     stats: () => ({ active, queued: queue.length, total: tasks.size }),
   };
 }
@@ -111,35 +168,43 @@ export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-ser
   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) {
+  // 共用：跑一輪/一目標，回傳 { sessionId, text, usage, rounds, done }；onEvent 收原始 kernel 事件；
+  // ask（可選）= 澄清通道,讓 agent 在背景任務中暫停問使用者。
+  async function runKernel(spec, onEvent, ask, onAgent) {
     const make = PACKS[spec.pack || 'general'];
     if (!make) throw new Error(`未知 pack「${spec.pack}」，可用：${Object.keys(PACKS).join(', ')}`);
+    // 持久工作空間（B 模型）：workdir 綁 workspace（非 sessionId）→ 檔案留存 + 五層沉澱跨成品累積。
+    const workspace = (spec.workspace || 'default').replace(/[^a-zA-Z0-9_-]/g, '') || 'default';
+    const workdir = join(baseDir, 'ws', workspace); mkdirSync(workdir, { recursive: true });
+    // history 仍綁 sessionId（每個成品獨立對話：無 sessionId → 全新,不續接,避免 context 暴脹/混淆）
     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 sess = sessions.get(sessionId) || { history: [] };
+    const kernel = createKernel(make({ cwd: workdir }), { cwd: workdir, model, getApiKey, sandbox: { enabled: sandbox }, getSandbox: () => sandbox, confirm: async () => 'yes', autoExtractMemory: true, ...(ask ? { askUser: ask } : {}) });
     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 });
+    if (spec.mode === 'goal') {
+      // 結果導向：回傳交付物（做了什麼 + 產出的檔案 + 是否達成），對話只是過程
+      const o = await kernel.runOutcome(spec.goal || spec.input || '', { history: sess.history, onEvent: wrapped, onAgent, onRound: (i) => wrapped({ type: 'round', round: i.round, maxRounds: i.maxRounds }) });
+      sess.history = o.history || []; sessions.set(sessionId, sess);
+      return { sessionId, workspace, text: o.summary || lastText(sess.history), usage, rounds: o.rounds, done: o.done, aborted: o.aborted, artifacts: o.artifacts };
+    }
+    const r = await kernel.runTurn(spec.input || '', { history: sess.history, onEvent: wrapped, onAgent });
     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 };
+    return { sessionId, workspace, 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 });
+    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, artifacts: r.artifacts, 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); }),
+    runJob: (spec, emit, ask, onAgent) => runKernel(spec, (ev) => { const m = mapEvent(ev); if (m) emit(m); }, ask, onAgent),
     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); },
   });
 
@@ -147,6 +212,14 @@ export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-ser
     const url = new URL(req.url, 'http://localhost');
     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() });
+
+    // 「許願台」網頁（公開可載入；token 注入頁面供同源 API 呼叫——PoC/本地自用,正式部署請前置真實認證）
+    if (req.method === 'GET' && (path === '/' || path === '/index.html')) {
+      let html; try { html = webHtml(); } catch { return json(res, 500, { error: 'web UI 未找到' }); }
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      return res.end(html.replace(/__SERVER_TOKEN__/g, token || '').replace(/__PACKS__/g, JSON.stringify(Object.keys(PACKS))));
+    }
+
     if (!authed(req)) return json(res, 401, { error: 'unauthorized（帶 Authorization: Bearer <token>）' });
 
     // 同步：跑完才回（JSON 或 SSE 串流）
@@ -182,6 +255,38 @@ export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-ser
     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' }); }
 
+    // 回答待答任務（澄清通道）：背景任務問了問題,使用者把答案送回 → 解除暫停、續跑
+    const mAns = path.match(/^\/v1\/tasks\/([^/]+)\/answer$/);
+    if (req.method === 'POST' && mAns) {
+      const body = await readBody(req);
+      const t = tasks.get(mAns[1]);
+      if (!t) return json(res, 404, { error: 'task not found' });
+      if (t.status !== 'needs-input') return json(res, 409, { error: '此任務目前沒有待答問題', status: t.status });
+      tasks.answer(mAns[1], body.answer);
+      log({ task: mAns[1], action: 'answer' });
+      return json(res, 200, { ok: true, taskId: mAns[1], status: 'running' });
+    }
+
+    // 中斷任務（取消鈕）：控制權在使用者手上,降低「啟動了控制不了的東西」的焦慮
+    const mCancel = path.match(/^\/v1\/tasks\/([^/]+)\/cancel$/);
+    if (req.method === 'POST' && mCancel) {
+      const ok = tasks.cancel(mCancel[1]);
+      log({ task: mCancel[1], action: 'cancel', ok });
+      return ok ? json(res, 200, { ok: true, taskId: mCancel[1] }) : json(res, 409, { error: '無法中斷（任務不存在或已結束）' });
+    }
+
+    // 取交付物檔案內容（讓「成品」可被瀏覽/下載）
+    const mFile = path.match(/^\/v1\/tasks\/([^/]+)\/file$/);
+    if (req.method === 'GET' && mFile) {
+      const t = tasks.get(mFile[1]); const ws = t?.result?.workspace;
+      if (!ws) return json(res, 404, { error: '無交付物（任務尚未完成?）' });
+      const full = resolveArtifact(join(baseDir, 'ws', ws), url.searchParams.get('path'));
+      if (!full) return json(res, 400, { error: 'path 不合法' });
+      if (!existsSync(full)) return json(res, 404, { error: '檔案不存在' });
+      try { res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' }); return res.end(readFileSync(full)); }
+      catch (e) { return json(res, 500, { error: e.message }); }
+    }
+
     // 附掛背景任務的事件流（replay 緩衝 + 即時；已結束則回放後關閉）
     const mEv = path.match(/^\/v1\/tasks\/([^/]+)\/events$/);
     if (req.method === 'GET' && mEv) {
@@ -208,9 +313,10 @@ export function startServer() {
   const { model, getApiKey } = loadModel(process.env.XITTO_MODEL);
   const server = createServerApp({ model, getApiKey, token, sandbox, concurrency });
   server.listen(port, () => {
-    console.log(`xitto-kernel server · http://localhost:${port} · model ${model.id} · 沙箱 ${sandbox ? '開' : '關'} · 背景並發 ${concurrency}`);
+    console.log(`🪄 許願台：http://localhost:${port}/  （瀏覽器打開即用——說出目標、交付成品）`);
+    console.log(`xitto-kernel server · 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');
+    console.log('API：POST /v1/run · /v1/stream · /v1/tasks · /v1/tasks/:id/{answer,cancel}｜GET /v1/tasks[/:id[/events|/file]] · /health');
   });
   return server;
 }

package/src/app/web/index.html

@@ -0,0 +1,180 @@
+<!doctype html>
+<html lang="zh-Hant">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>xitto · 許願台</title>
+<style>
+  :root { --bg:#0f1115; --card:#181b22; --line:#272b34; --fg:#e7e9ee; --dim:#8b919e; --accent:#6ea8fe; --ok:#5fd38a; --warn:#f0c674; --me:#222630; }
+  * { box-sizing:border-box; }
+  body { margin:0; font:15px/1.6 -apple-system,"PingFang TC","Microsoft JhengHei",system-ui,sans-serif; background:var(--bg); color:var(--fg); }
+  .wrap { max-width:760px; margin:0 auto; padding:28px 18px 80px; }
+  header { display:flex; align-items:baseline; gap:10px; margin-bottom:6px; }
+  header h1 { font-size:22px; margin:0; }
+  header .sub { color:var(--dim); font-size:13px; }
+  .ask { background:var(--card); border:1px solid var(--line); border-radius:14px; padding:14px; margin:18px 0; }
+  .ask textarea { width:100%; background:#0c0e12; color:var(--fg); border:1px solid var(--line); border-radius:10px; padding:12px; font:inherit; resize:vertical; min-height:64px; }
+  .row { display:flex; gap:10px; align-items:center; margin-top:10px; }
+  select, button { font:inherit; }
+  select { background:#0c0e12; color:var(--fg); border:1px solid var(--line); border-radius:8px; padding:8px; }
+  button { background:var(--accent); color:#08101f; border:0; border-radius:8px; padding:9px 16px; font-weight:600; cursor:pointer; }
+  button.ghost { background:transparent; color:var(--dim); border:1px solid var(--line); }
+  button:disabled { opacity:.5; cursor:default; }
+  .spacer { flex:1; }
+  .card { background:var(--card); border:1px solid var(--line); border-radius:14px; padding:16px; margin:14px 0; }
+  .goal { font-weight:600; margin-bottom:8px; }
+  .status { display:inline-block; font-size:12px; padding:2px 10px; border-radius:20px; border:1px solid var(--line); color:var(--dim); }
+  .status.running { color:var(--accent); border-color:var(--accent); }
+  .status.needs { color:var(--warn); border-color:var(--warn); }
+  .status.done { color:var(--ok); border-color:var(--ok); }
+  .status.error { color:#f08a8a; border-color:#f08a8a; }
+  .activity { color:var(--dim); font-size:13px; margin-top:8px; min-height:20px; }
+  .phase { color:var(--accent); font-size:13px; margin-bottom:5px; }
+  .step { font-size:13px; color:var(--dim); padding:1px 0; }
+  .step.cur { color:var(--fg); }
+  .step.think { color:var(--warn); font-style:italic; }
+  .todos { margin-top:10px; padding-top:8px; border-top:1px solid var(--line); }
+  .todo { font-size:13px; padding:2px 0; color:var(--dim); }
+  .todo.in_progress { color:var(--accent); font-weight:600; }
+  .todo.completed { color:var(--ok); }
+  button.cancel { margin-left:10px; padding:3px 12px; font-size:12px; background:transparent; color:#f08a8a; border:1px solid #5b3030; }
+  button.cancel:hover { background:#2a1818; }
+  .dots::after { content:""; animation:dots 1.4s steps(4,end) infinite; }
+  @keyframes dots { 0%{content:""} 25%{content:"·"} 50%{content:"··"} 75%{content:"···"} }
+  .summary { margin-top:10px; white-space:pre-wrap; }
+  .files { margin-top:10px; }
+  .file { display:inline-block; margin:3px 6px 0 0; padding:4px 10px; background:#0c0e12; border:1px solid var(--line); border-radius:8px; font-size:13px; cursor:pointer; color:var(--accent); }
+  .file.mod { color:var(--warn); }
+  .qbox { margin-top:12px; padding:12px; background:#1d1c12; border:1px solid var(--warn); border-radius:10px; }
+  .qbox .q { color:var(--warn); margin-bottom:8px; }
+  .qbox input { width:100%; background:#0c0e12; color:var(--fg); border:1px solid var(--line); border-radius:8px; padding:9px; font:inherit; }
+  h3 { color:var(--dim); font-size:13px; font-weight:600; text-transform:uppercase; letter-spacing:.05em; margin:28px 0 8px; }
+  .hist { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:11px 14px; margin:8px 0; cursor:pointer; }
+  .hist:hover { border-color:var(--accent); }
+  .hist .g { font-size:14px; } .hist .m { color:var(--dim); font-size:12px; }
+  pre.viewer { background:#0c0e12; border:1px solid var(--line); border-radius:10px; padding:12px; overflow:auto; max-height:360px; white-space:pre-wrap; font:13px/1.5 ui-monospace,Menlo,monospace; }
+  .empty { color:var(--dim); font-size:13px; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <h1>🪄 xitto 許願台</h1>
+    <span class="sub">說出你想完成的事，交給它去做、做完給你成品</span>
+  </header>
+
+  <div class="ask">
+    <textarea id="goal" placeholder="例如：把這個資料夾的 .md 檔整理成一份目錄 index.md；或：抓 example.com 的標題寫進 title.txt"></textarea>
+    <div class="row">
+      <select id="pack" title="領域"></select>
+      <span class="spacer"></span>
+      <button id="go">交辦 →</button>
+    </div>
+  </div>
+
+  <div id="current"></div>
+
+  <h3>歷史成品</h3>
+  <div id="history"><div class="empty">還沒有任何任務。上面交辦一件事試試。</div></div>
+</div>
+
+<script>
+const TOKEN = "__SERVER_TOKEN__";
+const PACKS = __PACKS__;
+const $ = (s) => document.querySelector(s);
+const api = (p, opts={}) => fetch(p, { ...opts, headers: { authorization:"Bearer "+TOKEN, "content-type":"application/json", ...(opts.headers||{}) } });
+const esc = (s) => String(s==null?"":s).replace(/[&<>]/g, c=>({"&":"&amp;","<":"&lt;",">":"&gt;"}[c]));
+
+// 把工具動作翻成人話,讓「進行中」變成看得懂的進度
+const TOOL_ZH = { read:"讀取檔案", ls:"查看目錄", glob:"尋找檔案", grep:"搜尋內容", write:"建立檔案", edit:"修改檔案", bash:"執行指令", web_search:"搜尋網路", web_fetch:"讀取網頁", http:"呼叫 API", read_image:"看圖片", skill:"載入技能", skill_save:"記錄技能", skills_check:"複查技能", playbook_update:"記下做法", episode_record:"記下經驗", episode_recall:"回想經驗", memory_save:"記住重點", todo_write:"規劃步驟", spawn_agent:"派出子助手", ask_user:"來問你" };
+const PHASE_ZH = { starting:"啟動中", thinking:"思考中", acting:"執行中", verifying:"驗收中", verified:"驗收通過", fixing:"修正中", "needs-input":"等你回答" };
+const friendlyStep = (a) => { const z = TOOL_ZH[a.name] || a.name; const d = a.args && (a.args.command||a.args.path||a.args.query||a.args.url||a.args.topic||a.args.name) || ""; return z + (d ? ` ${String(d).slice(0,44)}` : ""); };
+const elapsedOf = (t) => t.startedAt ? Math.max(0, Math.round((Date.now() - new Date(t.startedAt).getTime())/1000)) : 0;
+function progressHtml(t) {
+  const p = t.progress || {};
+  const head = `${PHASE_ZH[p.phase]||"進行中"}${p.round?` · 第 ${p.round} 輪`:""}${p.steps?` · ${p.steps} 個動作`:""} · 已進行 <span id="elapsed">${elapsedOf(t)}s</span>`;
+  const think = p.thinking ? `<div class="step think">💭 ${esc(p.thinking)}…</div>` : "";
+  const steps = (p.recent||[]).slice().reverse().map((a,i)=>`<div class="step ${i===0?"cur":""}">${i===0?"▸":"·"} ${esc(friendlyStep(a))}</div>`).join("");
+  return `<div class="activity"><div class="phase dots">${head}</div>${think}${steps}</div>`;
+}
+// 心跳：每秒更新「已進行 Ns」,即使沒有新事件也讓使用者看到它活著
+let liveTask = null;
+setInterval(() => { if (liveTask && (liveTask.status==="running"||liveTask.status==="queued")) { const el=document.getElementById("elapsed"); if (el) el.textContent = elapsedOf(liveTask)+"s"; } }, 1000);
+
+// 領域選單（非技術使用者預設「通用」）
+const LABELS = { general:"通用", coding:"程式", "data-query":"查資料", notes:"筆記", "deep-research":"研究", devops:"維運" };
+$("#pack").innerHTML = PACKS.map(p=>`<option value="${p}" ${p==="general"?"selected":""}>${LABELS[p]||p}</option>`).join("");
+
+let activeId = null, polling = null;
+
+$("#go").onclick = async () => {
+  const goal = $("#goal").value.trim(); if (!goal) return;
+  $("#go").disabled = true;
+  const r = await api("/v1/tasks", { method:"POST", body: JSON.stringify({ pack:$("#pack").value, mode:"goal", goal }) }).then(r=>r.json());
+  $("#go").disabled = false;
+  if (r.error) { alert(r.error); return; }
+  $("#goal").value = "";
+  activeId = r.taskId;
+  poll();
+};
+
+function statusClass(s){ return s==="running"?"running":s==="needs-input"?"needs":s==="done"?"done":(s==="error"||s==="cancelled")?"error":""; }
+function statusText(s){ return ({queued:"排隊中",running:"進行中…","needs-input":"需要你回答",done:"已完成",error:"失敗",cancelled:"已中斷"})[s]||s; }
+const CANCELLABLE = ["queued","running","needs-input"];
+function todosHtml(p){ if(!p||!(p.todos||[]).length) return ""; const ic=s=>s==="completed"?"☑":s==="in_progress"?"◐":"☐"; return `<div class="todos">${p.todos.map(td=>`<div class="todo ${td.status}">${ic(td.status)} ${esc(td.content)}</div>`).join("")}</div>`; }
+async function cancelTask(id){ await api("/v1/tasks/"+id+"/cancel",{method:"POST"}); for(let i=0;i<10;i++){ await new Promise(r=>setTimeout(r,600)); const t=await api("/v1/tasks/"+id).then(r=>r.json()); liveTask=t; renderCurrent(t); if(["done","error","cancelled"].includes(t.status)){loadHistory();break;} } }
+
+async function poll() {
+  clearTimeout(polling);
+  const t = await api("/v1/tasks/"+activeId).then(r=>r.json());
+  liveTask = t;
+  renderCurrent(t);
+  if (t.status==="done" || t.status==="error") { loadHistory(); return; }
+  if (t.status==="needs-input") return; // 等使用者回答
+  polling = setTimeout(poll, 1200);
+}
+
+function renderCurrent(t) {
+  const a = t.result?.artifacts, files = a ? [...(a.created||[]).map(f=>[f,"new"]), ...(a.modified||[]).map(f=>[f,"mod"])] : [];
+  $("#current").innerHTML = `<div class="card">
+    <div class="goal">${esc(t.goal||"任務")}</div>
+    <span class="status ${statusClass(t.status)}">${statusText(t.status)}${t.rounds?` · ${t.rounds} 輪`:""}</span>
+    ${CANCELLABLE.includes(t.status)?`<button class="cancel" onclick="cancelTask('${t.taskId}')">停止</button>`:""}
+    ${t.status==="running"||t.status==="queued"?progressHtml(t):""}
+    ${todosHtml(t.progress)}
+    ${t.status==="needs-input"?`<div class="qbox"><div class="q">❓ ${esc(t.pending?.question)}</div>
+      <input id="ans" placeholder="輸入你的回答，按 Enter 送出"></div>`:""}
+    ${t.status==="done"?`<div class="summary">${esc(t.result?.text||"")}</div>`:""}
+    ${t.status==="error"?`<div class="summary">⚠ ${esc(t.error)}</div>`:""}
+    ${files.length?`<div class="files">📦 成品：${files.map(([f,k])=>`<span class="file ${k==="mod"?"mod":""}" onclick="viewFile('${t.taskId}','${esc(f)}')">${k==="mod"?"~":"+"} ${esc(f)}</span>`).join("")}</div>`:""}
+    <pre class="viewer" id="fview" style="display:none"></pre>
+  </div>`;
+  if (t.status==="needs-input") {
+    const inp = $("#ans"); inp.focus();
+    inp.onkeydown = async (e) => { if (e.key==="Enter" && inp.value.trim()) {
+      const ans = inp.value.trim(); inp.disabled = true;
+      await api("/v1/tasks/"+t.taskId+"/answer", { method:"POST", body: JSON.stringify({ answer: ans }) });
+      poll();
+    }};
+  }
+}
+
+async function viewFile(id, path) {
+  const v = $("#fview"); v.style.display="block"; v.textContent="載入中…";
+  const r = await api("/v1/tasks/"+id+"/file?path="+encodeURIComponent(path));
+  v.textContent = r.ok ? await r.text() : "（無法讀取）";
+}
+
+async function loadHistory() {
+  const r = await api("/v1/tasks").then(r=>r.json());
+  const list = (r.tasks||[]).filter(t=>t.mode==="goal").reverse();
+  $("#history").innerHTML = list.length ? list.map(t=>`<div class="hist" onclick="openTask('${t.taskId}')">
+    <div class="g">${esc(t.goal||t.taskId)} <span class="status ${statusClass(t.status)}">${statusText(t.status)}</span></div>
+    <div class="m">${esc(t.createdAt)}</div></div>`).join("") : `<div class="empty">還沒有任何任務。</div>`;
+}
+async function openTask(id){ activeId=id; const t=await api("/v1/tasks/"+id).then(r=>r.json()); liveTask=t; renderCurrent(t); if(t.status==="running"||t.status==="queued"){poll();} window.scrollTo({top:0,behavior:"smooth"}); }
+
+loadHistory();
+</script>
+</body>
+</html>

package/src/kernel/index.js

@@ -2,8 +2,8 @@
 // 確定性那半部：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 { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, isAbsolute, relative } from 'node:path';
 import { loadPack } from './pack-loader.js';
 import { createToolRegistry, deriveMutatingTools, isSandboxable } from './tool-registry.js';
 import { composeGuards } from './guard-chain.js';
@@ -44,6 +44,25 @@ function loadContextFiles(cwd, names) {
     found.map((f) => `## ${f.name}\n${f.text.trim()}`).join('\n\n');
 }
 
+// 交付物偵測：掃工作目錄前後快照,diff 出「產出/改動的檔案」（pack 無關,連 bash 寫的也抓得到）。
+const SKIP_SCAN = new Set(['.xitto-kernel', 'node_modules', '.git', '.swebench-repos', '.xitto-server']);
+function scanWorkdir(dir, base = dir, acc = new Map(), depth = 0) {
+  if (depth > 8 || acc.size > 5000) return acc;
+  let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
+  for (const e of entries) {
+    if (SKIP_SCAN.has(e.name)) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) scanWorkdir(full, base, acc, depth + 1);
+    else if (e.isFile()) { try { const s = statSync(full); acc.set(relative(base, full), `${s.mtimeMs}:${s.size}`); } catch { /* 略 */ } }
+  }
+  return acc;
+}
+function diffWorkdir(before, after) {
+  const created = [], modified = [];
+  for (const [rel, sig] of after) { if (!before.has(rel)) created.push(rel); else if (before.get(rel) !== sig) modified.push(rel); }
+  return { created: created.sort(), modified: modified.sort() };
+}
+
 const DEFAULT_MEMORY_GUIDE =
   '遇到值得跨 session 記住的事實（使用者偏好、踩過的坑、專案決策）時，當下就存一條。';
 
@@ -153,6 +172,19 @@ export function createKernel(pack, config = {}) {
   };
   const skills = createSkills(join(dataDir, 'skills'), { verifyRunner: runVerify }); // 漸進揭露 + 結晶（須驗證）
 
+  // 澄清通道：app 提供 askUser 才有 ask_user 工具（結果導向:自主完成,只在非問不可時才打斷使用者）。
+  const askUserTool = typeof config.askUser === 'function' ? {
+    name: 'ask_user', label: '詢問使用者', readOnly: true,
+    description: '只在「缺少關鍵資訊、無法合理推斷、或決策會明顯改變結果」時,才向使用者提問並等待回答。能自己判斷、能用合理預設就別問——盡量自主完成,把打斷降到最低。回傳使用者的回答。',
+    parameters: { type: 'object', properties: { question: { type: 'string', description: '簡短、具體的問題' }, options: { type: 'array', items: { type: 'string' }, description: '可選:提供幾個選項供使用者挑' } }, required: ['question'] },
+    execute: async (_id, { question, options }) => {
+      let answer; try { answer = await config.askUser({ question, options }); } catch { answer = null; }
+      const text = (answer == null || answer === '') ? '(使用者未回答；請用合理預設繼續，不要再追問)' : String(answer);
+      // 同時回傳 question + 明確指示，讓模型把回答當權威依據（即使對話很長也不會脫鉤）
+      return { content: [{ type: 'text', text: JSON.stringify({ question: String(question || ''), answer: text, note: '這是使用者對你提問的回答，請以此為準繼續，不要忽略或再問同一件事。' }) }] };
+    },
+  } : null;
+
   // 工具：pack 工具（sandboxable 包 Seatbelt、mutating+path 加 undo 快照）+ kernel 內建記憶工具 + spawn_agent。
   const undoStack = [];
   const baseTools = [
@@ -160,6 +192,7 @@ export function createKernel(pack, config = {}) {
     ...memory.tools,
     ...playbook.tools,
     ...episodes.tools,
+    ...(askUserTool ? [askUserTool] : []),
     todo.tool,
     ...skills.tools,
     ...(config.extraTools || []),  // 外部注入（MCP 工具等）：由 app 層先 async 載入再傳入
@@ -190,6 +223,7 @@ export function createKernel(pack, config = {}) {
     '\n\n# 記憶與專案手冊\n' + (pack.memoryGuide || DEFAULT_MEMORY_GUIDE) + '\n' + DEFAULT_PLAYBOOK_GUIDE + '\n' + DEFAULT_EPISODE_GUIDE +
     (memText ? `\n\n# 已記住的事實（跨 session）\n${memText}` : '') +
     (pbText ? `\n\n# 專案手冊（這個專案怎麼做事，跨 session 累積）\n${pbText}` : '') +
+    (askUserTool ? '\n\n# 詢問\n盡量自主完成目標。只在缺少關鍵資訊、無法合理推斷、或決策會明顯改變結果時，才用 ask_user 問使用者；能用合理預設就別問。' : '') +
     skills.promptSection();
 
   const getPlanMode = config.getPlanMode || (() => false);
@@ -415,6 +449,22 @@ export function createKernel(pack, config = {}) {
       }
       return { done: false, maxedOut: true, rounds: maxRounds, history };
     },
+
+    /**
+     * 結果導向：給目標 → 跑 goal loop → 回「交付物」（做了什麼 + 產出/改動的檔案 + 是否達成）。
+     * 對非技術使用者:對話只是過程,這回傳的才是產品。
+     * @param {string} goal
+     * @param {object} [opts] 同 runGoal
+     * @returns {Promise<{ goal, done, rounds, aborted, stalled, summary, artifacts: {created:string[], modified:string[]}, history }>}
+     */
+    runOutcome: async (goal, opts = {}) => {
+      const before = scanWorkdir(cwd);
+      const g = await api.runGoal(goal, opts);
+      const artifacts = diffWorkdir(before, scanWorkdir(cwd));
+      const lastAssistant = [...(g.history || [])].reverse().find((m) => m.role === 'assistant');
+      const summary = (lastAssistant?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('').trim();
+      return { goal, done: !!g.done, rounds: g.rounds, aborted: !!g.aborted, stalled: !!g.stalled, summary, artifacts, history: g.history };
+    },
   };
   return api;
 }