cueme 0.1.2 → 0.1.4

package/README.md

@@ -1,8 +1,30 @@
 # cueme
 
+<div align="center">
+
+<strong><a href="./README.md">English</a></strong>
+ ·
+<strong><a href="./README.zh-CN.md">中文</a></strong>
+
+</div>
+
+---
+
+[![npm](https://img.shields.io/npm/v/cueme?label=cueme&color=0B7285)](https://www.npmjs.com/package/cueme)
+[![npm downloads](https://img.shields.io/npm/dm/cueme?color=0B7285)](https://www.npmjs.com/package/cueme)
+
+[![Repo: cue-stack](https://img.shields.io/badge/repo-cue--stack-111827)](https://github.com/nmhjklnm/cue-stack)
+[![Repo: cue-console](https://img.shields.io/badge/repo-cue--console-111827)](https://github.com/nmhjklnm/cue-console)
+[![Repo: cue-command](https://img.shields.io/badge/repo-cue--command-111827)](https://github.com/nmhjklnm/cue-command)
+![License](https://img.shields.io/badge/license-Apache--2.0-1E40AF)
+
+[Contributing](./CONTRIBUTING.md) · [Trademark](./TRADEMARK.md)
+
 A command protocol adapter for Cue, compatible with the existing SQLite mailbox (`~/.cue/cue.db`).
 
-## Quick start (2 steps)
+Note: image sending is currently unavailable (WIP).
+
+## Quick start (3 steps)
 
 ### Step 1: Install cueme
 
@@ -12,45 +34,59 @@ npm install -g cueme
 
 ### Step 2: Configure the protocol.md as your system prompt
 
-Add the contents of `cue-command/protocol.md` to your tool's system prompt / rules.
+Copy the contents of `protocol.md` into your runtime's system prompt / persistent rules:
+
+- [`protocol.md`](https://github.com/nmhjklnm/cue-command/blob/main/protocol.md)
+
+If you installed via npm, `protocol.md` is also included in the package.
 
 This file defines the Human Agent Protocol (HAP) rules and the `cueme` command interface.
 
+### Step 3: Run the UI and connect
+
+`cueme` speaks to the same SQLite mailbox used by the UI (`~/.cue/cue.db`). Start the UI:
+
+```bash
+npm install -g cue-console
+cue-console start
+```
+
+Open `http://localhost:3000`, then in your runtime chat type:
+
+`cue`
+
 ## Usage
 
 ### join
 
 ```bash
-cueme join
+cueme join <agent_runtime>
 ```
 
 ### recall
 
 ```bash
-cueme recall --hints "refactored login"
+cueme recall <hints>
 ```
 
 ### cue
 
 ```bash
-cueme cue --agent_id "tavilron" --prompt "What should I do next?" --timeout 600
+cueme cue <agent_id> -
 ```
 
 ### pause
 
 ```bash
-cueme pause --agent_id "tavilron" --prompt "Waiting..."
+cueme pause <agent_id> -
 ```
 
 All commands output plain text to stdout.
 
-## Release
-
-Publishing is tag-driven (GitHub Actions). Create a tag `v<version>` that matches `package.json` `version`.
+---
 
-```bash
-git tag v0.1.1
-git push origin v0.1.1
-```
+## QQ Group
 
-The workflow publishes to npm using `NPM_TOKEN` from GitHub repo secrets.
+<p align="center">
+  <img src="./assets/qq.jpg" alt="QQ group QR code" width="25%" />
+</p>

package/README.zh-CN.md

@@ -0,0 +1,92 @@
+# cueme
+
+<div align="center">
+
+<strong><a href="./README.md">English</a></strong>
+ ·
+<strong><a href="./README.zh-CN.md">中文</a></strong>
+
+</div>
+
+---
+
+[![npm](https://img.shields.io/npm/v/cueme?label=cueme&color=0B7285)](https://www.npmjs.com/package/cueme)
+[![npm downloads](https://img.shields.io/npm/dm/cueme?color=0B7285)](https://www.npmjs.com/package/cueme)
+
+[![Repo: cue-stack](https://img.shields.io/badge/repo-cue--stack-111827)](https://github.com/nmhjklnm/cue-stack)
+[![Repo: cue-console](https://img.shields.io/badge/repo-cue--console-111827)](https://github.com/nmhjklnm/cue-console)
+[![Repo: cue-command](https://img.shields.io/badge/repo-cue--command-111827)](https://github.com/nmhjklnm/cue-command)
+![License](https://img.shields.io/badge/license-Apache--2.0-1E40AF)
+
+[Contributing](./CONTRIBUTING.md) · [Trademark](./TRADEMARK.md)
+
+这是 Cue 的命令行协议适配器，兼容现有的 SQLite mailbox（`~/.cue/cue.db`）。
+
+提示：发送图片功能暂不可用（开发中）。
+
+## 快速开始（2 步）
+
+### 第 1 步：安装 cueme
+
+```bash
+npm install -g cueme
+```
+
+### 第 2 步：把 protocol.md 配置到你的系统提示词里
+
+把 `protocol.md` 的内容复制到你正在使用的 runtime 的系统提示词 / 持久规则里：
+
+- [`protocol.md`](https://github.com/nmhjklnm/cue-command/blob/main/protocol.md)
+
+如果你是通过 npm 安装的，`protocol.md` 也会包含在安装包里。
+
+该文件定义了 Human Agent Protocol（HAP）规则，以及 `cueme` 的命令接口。
+
+### 第 3 步：启动 UI 并连接
+
+`cueme` 会与 UI 共用同一个 SQLite mailbox（`~/.cue/cue.db`）。先启动 UI：
+
+```bash
+npm install -g cue-console
+cue-console start
+```
+
+打开 `http://localhost:3000`，然后在你的 runtime 聊天里输入：
+
+`cue`
+
+## 用法
+
+### join
+
+```bash
+cueme join <agent_runtime>
+```
+
+### recall
+
+```bash
+cueme recall <hints>
+```
+
+### cue
+
+```bash
+cueme cue <agent_id> -
+```
+
+### pause
+
+```bash
+cueme pause <agent_id> -
+```
+
+所有命令都以纯文本输出到 stdout。
+
+---
+
+## QQ 群
+
+<p align="center">
+  <img src="./assets/qq.jpg" alt="QQ 群二维码" width="25%" />
+</p>

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "cueme",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Cue command protocol adapter (stdin/stdout JSON)",
   "license": "Apache-2.0",
   "files": [
     "bin/",
     "src/",
+    "protocol.md",
     "README.md",
     "LICENSE"
   ],

package/protocol.md

@@ -0,0 +1,92 @@
+# Human Agent Protocol (HAP)
+
+你与用户的协作交互通过命令行工具 `cueme` 完成。
+
+当用户接受 HAP：你必须在每次阶段性输出或准备结束回复前调用 `cueme cue`（或 `cueme pause`）等待用户继续。
+
+If HAP is accepted: before any phase-summary or final reply, you MUST call `cueme cue` via the terminal/tool.
+A reply is NOT complete unless the last action is a successful cueme call.
+
+- 首次连接 / 无 agent_id：先执行 `join()` 获取 agent_id，再执行 `cue()`。
+
+- 重连 / 已有 agent_id（例如网络波动导致 cue 中断但对话仍在继续）：用户再次发送 `cue` 时，优先直接用已有 agent_id 执行 `cue()`；仅当无法确认 agent_id 时才重新 `join()`。
+
+## No fake tool actions
+
+You MUST NOT claim you called cueme unless you actually executed it and got its stdout.
+If you cannot run tools, say "TOOLS_UNAVAILABLE" and output only the exact `cueme ...` command for the human to run.
+
+## cueme (command interface)
+
+### join() -> message
+
+Command:
+
+- `cueme join <agent_runtime>`
+
+Returns (plain text):
+
+- a short message (includes `agent_id=...`, `project_dir=...`, `agent_runtime=...`)
+
+`agent_runtime`:
+
+- Required positional tag for where the agent is running (IDE/runtime).
+- Format: lowercase, `_` only.
+- Examples: `windsurf`, `cursor`, `vscode`, `claude_code`, `terminal`, `codex`, `kiro`, `opencode`.
+
+### recall(hints: str) -> message
+
+Command:
+
+- `cueme recall <hints>`
+
+Returns (plain text):
+
+- a short message (includes `agent_id=...`)
+
+### cue(prompt: str, agent_id: str, payload?: object | null) -> text
+
+Command:
+
+`cueme cue <agent_id> -`
+
+stdin JSON envelope:
+{
+  "prompt": NonEmptyString,          // REQUIRED, must be non-empty after trim
+  "payload"?: object | null          // OPTIONAL, may be omitted or null
+}
+
+Tip: when you need clearer structured interaction, prefer `payload` (choice/confirm/form) over encoding structure in `prompt`. bash/zsh use heredoc; PowerShell use here-string and pipe the JSON into `cueme cue <agent_id> -`.
+
+Returns:
+
+- plain text (stdout)
+
+Payload protocol (payload object):
+
+- required: {"type": "choice" | "confirm" | "form"}
+- choice: {"type":"choice","options":["...",...],"allow_multiple":false}
+- confirm: {"type":"confirm","text":"...","confirm_label":"Confirm","cancel_label":"Cancel"}
+- form: {"type":"form","fields":[{"label":"...","kind":"text","options":["...",...],"allow_multiple":false}, ...]}
+
+Minimal examples:
+
+- choice: {"type":"choice","options":["Continue","Stop"]}
+- confirm: {"type":"confirm","text":"Continue?"}
+- form: {"type":"form","fields":[{"label":"Env","options":["prod","staging"]}]}
+
+### pause(agent_id: str, prompt?: str) -> text
+
+Command:
+
+- `cueme pause <agent_id> <prompt|->`
+
+`prompt`:
+
+- Pass a prompt string as the positional `prompt` argument.
+- If `-` is used, instructions are read from stdin.
+- If stdin is empty, `pause` will use the default pause prompt.
+
+Returns:
+
+- plain text (stdout)

package/src/cli.js

@@ -1,3 +1,4 @@
+const { readAllStdin } = require('./io');
 const { handleCommand } = require('./handler');
 
 function parseArgs(argv) {
@@ -47,6 +48,7 @@ function extractTextFromResult(result) {
 async function main() {
   const parsed = parseArgs(process.argv);
   const sub = parsed._[0];
+  const pos = parsed._.slice(1);
 
   if (!sub || sub === 'help' || sub === '-h' || sub === '--help') {
     process.stdout.write(
@@ -54,10 +56,14 @@ async function main() {
         'cueme',
         '',
         'Usage:',
-        '  cueme join',
-        '  cueme recall --hints "..."',
-        '  cueme cue --agent_id "..." --prompt "..." [--payload "{...}"] [--timeout 600]',
-        '  cueme pause --agent_id "..." [--prompt "..."]',
+        '  cueme join <agent_runtime>',
+        '  cueme recall <hints>',
+        '  cueme cue <agent_id> -',
+        '  cueme pause <agent_id> [prompt|-]',
+        '  cueme migrate',
+        '',
+        'Cue stdin JSON envelope:',
+        '  {"prompt":"...","payload":{...}}',
         '',
         'Output:',
         '  - join/recall/cue/pause: plain text (stdout)',
@@ -66,6 +72,114 @@ async function main() {
     return;
   }
 
+  if (parsed.timeout != null) {
+    process.stderr.write('error: --timeout is not supported (fixed to 10 minutes)\n');
+    process.exitCode = 2;
+    return;
+  }
+
+  if (parsed.agent_id != null || parsed.prompt != null || parsed.hints != null) {
+    process.stderr.write('error: --agent_id/--prompt/--hints flags are not supported; use positional args\n');
+    process.exitCode = 2;
+    return;
+  }
+
+  if (sub === 'join') {
+    const agentRuntime = pos[0];
+    if (!agentRuntime) {
+      process.stderr.write('error: missing <agent_runtime>\n');
+      process.exitCode = 2;
+      return;
+    }
+    parsed.agent_runtime = String(agentRuntime);
+  }
+
+  if (sub === 'recall') {
+    const hints = pos[0];
+    if (!hints) {
+      process.stderr.write('error: missing <hints>\n');
+      process.exitCode = 2;
+      return;
+    }
+    parsed.hints = String(hints);
+  }
+
+  if (sub === 'cue') {
+    const agentId = pos[0];
+    if (!agentId) {
+      process.stderr.write('error: missing <agent_id>\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    if (parsed.payload != null) {
+      process.stderr.write('error: --payload is not supported for cue. Use stdin JSON envelope.\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    parsed.agent_id = String(agentId);
+
+    const promptPos = pos[1];
+    if (promptPos !== '-') {
+      process.stderr.write('error: cue requires stdin JSON. Usage: cueme cue <agent_id> -\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    if (pos.length > 2) {
+      process.stderr.write('error: cue only accepts <agent_id> - and stdin JSON.\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    const raw = await readAllStdin();
+    let env;
+    try {
+      env = JSON.parse(raw);
+    } catch {
+      process.stderr.write('error: stdin must be valid JSON (envelope: {"prompt": "...", "payload": {...}})\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    if (!env || typeof env !== 'object') {
+      process.stderr.write('error: stdin JSON must be an object\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    const prompt = typeof env.prompt === 'string' ? env.prompt : '';
+    if (!prompt.trim()) {
+      process.stderr.write('error: stdin JSON must include non-empty string field "prompt"\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    parsed.prompt = prompt;
+    parsed.payload = env.payload == null ? null : JSON.stringify(env.payload);
+  }
+
+  if (sub === 'pause') {
+    const agentId = pos[0];
+    if (!agentId) {
+      process.stderr.write('error: missing <agent_id>\n');
+      process.exitCode = 2;
+      return;
+    }
+    parsed.agent_id = String(agentId);
+
+    const promptPos = pos[1];
+    if (promptPos === '-') {
+      const stdinPrompt = await readAllStdin();
+      if (stdinPrompt && stdinPrompt.trim().length > 0) {
+        parsed.prompt = stdinPrompt;
+      }
+    } else if (promptPos != null) {
+      parsed.prompt = String(promptPos);
+    }
+  }
+
   const result = await handleCommand({ subcommand: sub, args: parsed });
   process.stdout.write(extractTextFromResult(result) + '\n');
 }

package/src/db.js

@@ -30,6 +30,16 @@ async function get(db, sql, params = []) {
 }
 
 async function initSchema(db) {
+  await run(
+    db,
+    [
+      'CREATE TABLE IF NOT EXISTS schema_meta (',
+      '  key TEXT PRIMARY KEY,',
+      '  value TEXT NOT NULL',
+      ')',
+    ].join('\n')
+  );
+
   await run(
     db,
     [
@@ -63,6 +73,48 @@ async function initSchema(db) {
   );
 
   await run(db, 'CREATE INDEX IF NOT EXISTS ix_cue_responses_request_id ON cue_responses(request_id)');
+
+  await run(
+    db,
+    [
+      'CREATE TABLE IF NOT EXISTS cue_files (',
+      '  id INTEGER PRIMARY KEY AUTOINCREMENT,',
+      '  sha256 TEXT UNIQUE NOT NULL,',
+      '  file TEXT NOT NULL,',
+      '  mime_type TEXT NOT NULL,',
+      '  size_bytes INTEGER NOT NULL,',
+      '  created_at TEXT',
+      ')',
+    ].join('\n')
+  );
+
+  await run(db, 'CREATE INDEX IF NOT EXISTS ix_cue_files_sha256 ON cue_files(sha256)');
+
+  await run(
+    db,
+    [
+      'CREATE TABLE IF NOT EXISTS cue_response_files (',
+      '  response_id INTEGER NOT NULL,',
+      '  file_id INTEGER NOT NULL,',
+      '  idx INTEGER NOT NULL,',
+      '  PRIMARY KEY (response_id, idx)',
+      ')',
+    ].join('\n')
+  );
+
+  await run(db, 'CREATE INDEX IF NOT EXISTS ix_cue_response_files_response_id ON cue_response_files(response_id)');
+  await run(db, 'CREATE INDEX IF NOT EXISTS ix_cue_response_files_file_id ON cue_response_files(file_id)');
+
+  const versionRow = await get(db, 'SELECT value FROM schema_meta WHERE key = ?', ['schema_version']);
+  if (!versionRow) {
+    const reqCountRow = await get(db, 'SELECT COUNT(*) AS n FROM cue_requests');
+    const respCountRow = await get(db, 'SELECT COUNT(*) AS n FROM cue_responses');
+    const reqCount = reqCountRow ? Number(reqCountRow.n) : 0;
+    const respCount = respCountRow ? Number(respCountRow.n) : 0;
+    if (reqCount === 0 && respCount === 0) {
+      await run(db, 'INSERT INTO schema_meta (key, value) VALUES (?, ?)', ['schema_version', '2']);
+    }
+  }
 }
 
 function nowIso() {

package/src/handler.js

@@ -1,4 +1,7 @@
 const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { sleep } = require('./io');
 const { generateName } = require('./naming');
 const { openDb, initSchema, run, get, nowIso, getDbPath } = require('./db');
@@ -33,34 +36,57 @@ async function waitForResponse(db, requestId, timeoutSeconds) {
 function parseUserResponseJson(responseJson) {
   try {
     const obj = JSON.parse(responseJson);
-    if (!obj || typeof obj !== 'object') return { text: '', images: [] };
+    if (!obj || typeof obj !== 'object') return { text: '' };
     return {
       text: typeof obj.text === 'string' ? obj.text : '',
-      images: Array.isArray(obj.images) ? obj.images : [],
     };
   } catch {
-    return { text: '', images: [] };
+    return { text: '' };
   }
 }
 
+async function getFilesByResponseId(db, responseId) {
+  if (!responseId) return [];
+  const rows = db
+    .prepare(
+      [
+        'SELECT f.file AS file, f.mime_type AS mime_type',
+        'FROM cue_response_files rf',
+        'JOIN cue_files f ON f.id = rf.file_id',
+        'WHERE rf.response_id = ?',
+        'ORDER BY rf.idx ASC',
+      ].join('\n')
+    )
+    .all(responseId);
+  return Array.isArray(rows) ? rows : [];
+}
+
 function buildToolContentsFromUserResponse(userResp) {
   const contents = [];
 
   const text = (userResp.text || '').trim();
-  const images = Array.isArray(userResp.images) ? userResp.images : [];
+  const files = Array.isArray(userResp.files) ? userResp.files : [];
+  const fileLines = files
+    .map((f) => {
+      const file = f && typeof f === 'object' ? String(f.file || '') : '';
+      const mime = f && typeof f === 'object' ? String(f.mime_type || '') : '';
+      if (!file) return '';
+      const clean = file.replace(/^\/+/, '');
+      const pathForAgent = `~/.cue/${clean}`;
+      return `- ${pathForAgent}${mime ? ` (${mime})` : ''}`;
+    })
+    .filter(Boolean);
 
   if (text) {
     contents.push({ type: 'text', text: `用户希望继续，并提供了以下指令：\n\n${text}` });
-  } else if (images.length > 0) {
-    contents.push({ type: 'text', text: '用户希望继续，并附加了图片：' });
+  } else if (files.length > 0) {
+    contents.push({ type: 'text', text: '用户希望继续，并附加了文件：' });
   }
 
-  for (const img of images) {
-    if (!img) continue;
+  if (fileLines.length > 0) {
     contents.push({
-      type: 'image',
-      data: img.base64_data,
-      mimeType: img.mime_type,
+      type: 'text',
+      text: `\n\n附件文件路径如下（图片与其它文件统一为路径）。请你自行读取这些文件内容后再继续：\n${fileLines.join('\n')}`,
     });
   }
 
@@ -68,14 +94,23 @@ function buildToolContentsFromUserResponse(userResp) {
   return contents;
 }
 
-async function handleJoin(db) {
+function normalizeAgentRuntime(raw) {
+  const s = (raw == null ? '' : String(raw)).trim().toLowerCase().replace(/[-\s]+/g, '_');
+  return s ? s : 'unknown';
+}
+
+async function handleJoin(db, agent_runtime) {
   const agent_id = generateName();
+  const project_dir = process.cwd();
+  const normalized_runtime = normalizeAgentRuntime(agent_runtime);
   return {
     ok: true,
     data: {
       agent_id,
       message:
-        `agent_id=${agent_id}\n\n` +
+        `agent_id=${agent_id}\n` +
+        `project_dir=${project_dir}\n` +
+        `agent_runtime=${normalized_runtime}\n\n` +
         'Use this agent_id when calling cue(prompt, agent_id).' +
         ' You must remember this agent_id: when calling cue(), pass it as agent_id so the system knows who you are.' +
         ' Before ending this session, call cue. Please use cue to provide a final summary, ask a question, or make a request.',
@@ -165,7 +200,7 @@ function timeoutContentsForMode(mode) {
     {
       type: 'text',
       text:
-        'Timed out waiting for user response. Call pause(agent_id) to suspend and wait for resume.\n\n',
+        'Timed out waiting for user response. You MUST NOT continue or add any extra output. Immediately call pause(agent_id) and stop output until resumed.\n\n',
     },
   ];
 }
@@ -192,15 +227,16 @@ async function handleCueLike(db, { mode, agent_id, prompt, payload, timeoutSecon
         data: {
           request_id,
           cancelled: true,
-          response: { text: '', images: [] },
+          response: { text: '' },
           contents: cancelledContentsForMode(mode),
         },
       };
     }
 
     const userResp = parseUserResponseJson(respRow.response_json);
+    userResp.files = await getFilesByResponseId(db, respRow.id);
 
-    if (!userResp.text.trim() && (!userResp.images || userResp.images.length === 0)) {
+    if (!userResp.text.trim() && (!userResp.files || userResp.files.length === 0)) {
       if (mode === 'cue') {
         const updated_at = nowIso();
         await run(
@@ -241,7 +277,7 @@ async function handleCueLike(db, { mode, agent_id, prompt, payload, timeoutSecon
 
       const existing = await get(db, 'SELECT id FROM cue_responses WHERE request_id = ?', [request_id]);
       if (!existing) {
-        const cancelledResponse = JSON.stringify({ text: '', images: [] });
+        const cancelledResponse = JSON.stringify({ text: '' });
         await run(
           db,
           'INSERT INTO cue_responses (request_id, response_json, cancelled, created_at) VALUES (?, ?, ?, ?)',
@@ -254,7 +290,7 @@ async function handleCueLike(db, { mode, agent_id, prompt, payload, timeoutSecon
         data: {
           request_id,
           cancelled: true,
-          response: { text: '', images: [] },
+          response: { text: '' },
           contents: timeoutContentsForMode(mode),
         },
       };
@@ -265,7 +301,7 @@ async function handleCueLike(db, { mode, agent_id, prompt, payload, timeoutSecon
 }
 
 async function handlePause(db, { agent_id, prompt }) {
-  const pausePrompt = prompt || 'Waiting for your confirmation. Click Continue when you are ready.';
+  const pausePrompt = prompt || 'Paused. Click Continue when you are ready.';
   const payload =
     '{"type":"confirm","variant":"pause","text":"Paused. Click Continue when you are ready.","confirm_label":"Continue","cancel_label":""}';
 
@@ -278,12 +314,198 @@ async function handlePause(db, { agent_id, prompt }) {
   });
 }
 
+async function ensureSchemaV2OrGuideMigrate(db) {
+  const versionRow = await get(db, 'SELECT value FROM schema_meta WHERE key = ?', ['schema_version']);
+  const version = versionRow && versionRow.value != null ? String(versionRow.value) : '';
+  if (version === '2') return { ok: true };
+
+  const reqCountRow = await get(db, 'SELECT COUNT(*) AS n FROM cue_requests');
+  const respCountRow = await get(db, 'SELECT COUNT(*) AS n FROM cue_responses');
+  const reqCount = reqCountRow ? Number(reqCountRow.n) : 0;
+  const respCount = respCountRow ? Number(respCountRow.n) : 0;
+
+  if (reqCount === 0 && respCount === 0) {
+    return { ok: true };
+  }
+
+  return {
+    ok: false,
+    error:
+      'Database schema is outdated (pre-file storage). Please migrate: cueme migrate\n' +
+      '数据库结构已过期（旧的 base64 存储）。请先执行：cueme migrate',
+  };
+}
+
+function filesRootDir() {
+  return path.join(os.homedir(), '.cue', 'files');
+}
+
+function extFromMime(mime) {
+  const m = (mime || '').toLowerCase().trim();
+  if (m === 'image/png') return 'png';
+  if (m === 'image/jpeg' || m === 'image/jpg') return 'jpg';
+  if (m === 'image/webp') return 'webp';
+  if (m === 'image/gif') return 'gif';
+  return 'bin';
+}
+
+function safeParseJson(s) {
+  try {
+    return { ok: true, value: JSON.parse(s) };
+  } catch (e) {
+    return { ok: false, error: e };
+  }
+}
+
+function decodeBase64(b64) {
+  try {
+    return { ok: true, value: Buffer.from(String(b64 || ''), 'base64') };
+  } catch (e) {
+    return { ok: false, error: e };
+  }
+}
+
+function normalizeUserResponseForV2(parsed) {
+  const obj = parsed && typeof parsed === 'object' ? parsed : {};
+  const text = typeof obj.text === 'string' ? obj.text : '';
+  const mentions = Array.isArray(obj.mentions) ? obj.mentions : undefined;
+  return mentions ? { text, mentions } : { text };
+}
+
+async function handleMigrate(db) {
+  const root = filesRootDir();
+  fs.mkdirSync(root, { recursive: true });
+
+  const versionRow = await get(db, 'SELECT value FROM schema_meta WHERE key = ?', ['schema_version']);
+  const version = versionRow && versionRow.value != null ? String(versionRow.value) : '';
+  if (version === '2') {
+    return { ok: true, data: { message: 'Already migrated (schema_version=2).' } };
+  }
+
+  const rows = db
+    .prepare('SELECT id, request_id, response_json, cancelled FROM cue_responses ORDER BY id ASC')
+    .all();
+
+  const total = Array.isArray(rows) ? rows.length : 0;
+  let processed = 0;
+  let migrated = 0;
+  let deleted = 0;
+
+  const deleteResponseStmt = db.prepare('DELETE FROM cue_responses WHERE id = ?');
+  const cancelRequestStmt = db.prepare('UPDATE cue_requests SET status = ? WHERE request_id = ?');
+  const upsertFileStmt = db.prepare(
+    [
+      'INSERT INTO cue_files (sha256, file, mime_type, size_bytes, created_at)',
+      'VALUES (@sha256, @file, @mime_type, @size_bytes, @created_at)',
+      'ON CONFLICT(sha256) DO UPDATE SET',
+      '  file = excluded.file,',
+      '  mime_type = excluded.mime_type,',
+      '  size_bytes = excluded.size_bytes',
+    ].join('\n')
+  );
+  const getFileIdStmt = db.prepare('SELECT id FROM cue_files WHERE sha256 = ?');
+  const deleteResponseFilesStmt = db.prepare('DELETE FROM cue_response_files WHERE response_id = ?');
+  const insertRespFileStmt = db.prepare(
+    'INSERT INTO cue_response_files (response_id, file_id, idx) VALUES (?, ?, ?)'
+  );
+  const updateResponseJsonStmt = db.prepare('UPDATE cue_responses SET response_json = ? WHERE id = ?');
+
+  const tx = db.transaction((row) => {
+    const parsed = safeParseJson(row.response_json);
+    if (!parsed.ok) {
+      deleteResponseStmt.run(row.id);
+      cancelRequestStmt.run('CANCELLED', row.request_id);
+      return { migrated: false, deleted: true };
+    }
+
+    const images = Array.isArray(parsed.value.images) ? parsed.value.images : [];
+
+    deleteResponseFilesStmt.run(row.id);
+
+    for (let i = 0; i < images.length; i += 1) {
+      const img = images[i];
+      const mime = img && typeof img === 'object' ? String(img.mime_type || '') : '';
+      const b64 = img && typeof img === 'object' ? img.base64_data : '';
+
+      const decoded = decodeBase64(b64);
+      if (!decoded.ok) {
+        deleteResponseStmt.run(row.id);
+        cancelRequestStmt.run('CANCELLED', row.request_id);
+        return { migrated: false, deleted: true };
+      }
+
+      const buf = decoded.value;
+      if (!buf || buf.length === 0) {
+        deleteResponseStmt.run(row.id);
+        cancelRequestStmt.run('CANCELLED', row.request_id);
+        return { migrated: false, deleted: true };
+      }
+
+      const sha256 = crypto.createHash('sha256').update(buf).digest('hex');
+      const ext = extFromMime(mime);
+      const rel = path.join('files', `${sha256}.${ext}`);
+      const abs = path.join(os.homedir(), '.cue', rel);
+
+      if (!fs.existsSync(abs)) {
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, buf);
+      }
+
+      const created_at = nowIso();
+      upsertFileStmt.run({
+        sha256,
+        file: rel,
+        mime_type: mime || 'application/octet-stream',
+        size_bytes: buf.length,
+        created_at,
+      });
+      const fileRow = getFileIdStmt.get(sha256);
+      const fileId = fileRow ? Number(fileRow.id) : null;
+      if (!fileId) {
+        deleteResponseStmt.run(row.id);
+        cancelRequestStmt.run('CANCELLED', row.request_id);
+        return { migrated: false, deleted: true };
+      }
+
+      insertRespFileStmt.run(row.id, fileId, i);
+    }
+
+    const v2 = normalizeUserResponseForV2(parsed.value);
+    updateResponseJsonStmt.run(JSON.stringify(v2), row.id);
+    return { migrated: true, deleted: false };
+  });
+
+  for (const row of rows) {
+    processed += 1;
+    const res = tx(row);
+    if (res.deleted) deleted += 1;
+    if (res.migrated) migrated += 1;
+    if (processed % 50 === 0 || processed === total) {
+      process.stderr.write(`migrate: ${processed}/${total} (migrated=${migrated}, deleted=${deleted})\n`);
+    }
+  }
+
+  await run(db, 'INSERT OR REPLACE INTO schema_meta (key, value) VALUES (?, ?)', ['schema_version', '2']);
+
+  return {
+    ok: true,
+    data: {
+      message: `Migrate completed. total=${total} migrated=${migrated} deleted=${deleted}`,
+    },
+  };
+}
+
 async function handleCommand({ subcommand, args }) {
   const { db, dbPath } = openDb();
   try {
     await initSchema(db);
 
-    if (subcommand === 'join') return await handleJoin(db);
+    if (subcommand !== 'join' && subcommand !== 'migrate') {
+      const schemaCheck = await ensureSchemaV2OrGuideMigrate(db);
+      if (!schemaCheck.ok) return { ok: false, error: schemaCheck.error, data: { db_path: dbPath } };
+    }
+
+    if (subcommand === 'join') return await handleJoin(db, args.agent_runtime);
 
     if (subcommand === 'recall') {
       const hints = (args.hints ?? '').toString();
@@ -304,6 +526,10 @@ async function handleCommand({ subcommand, args }) {
       return await handlePause(db, { agent_id, prompt });
     }
 
+    if (subcommand === 'migrate') {
+      return await handleMigrate(db);
+    }
+
     return { ok: false, error: `unknown subcommand: ${subcommand}`, data: { db_path: dbPath } };
   } finally {
     db.close();

package/src/io.js

@@ -1,4 +1,5 @@
 function readAllStdin() {
+  if (process.stdin.isTTY) return Promise.resolve('');
   return new Promise((resolve, reject) => {
     let data = '';
     process.stdin.setEncoding('utf8');