cueme 0.1.3 → 0.1.6

package/README.md

@@ -24,7 +24,7 @@ A command protocol adapter for Cue, compatible with the existing SQLite mailbox
 
 Note: image sending is currently unavailable (WIP).
 
-## Quick start (2 steps)
+## Quick start (3 steps)
 
 ### Step 1: Install cueme
 
@@ -81,6 +81,24 @@ cueme cue <agent_id> -
 cueme pause <agent_id> -
 ```
 
+You can also provide the prompt as a positional argument:
+
+```bash
+cueme pause <agent_id> "Paused. Click Continue when you are ready."
+```
+
+### proto
+
+Example (macOS + Windsurf):
+
+```bash
+cueme proto apply windsurf
+```
+
+For detailed `proto` usage (config, init, render, markers), see:
+
+- [`docs/proto.md`](./docs/proto.md)
+
 All commands output plain text to stdout.
 
 ---

package/docs/proto.md

@@ -0,0 +1,110 @@
+# cueme proto
+
+This document describes the `cueme proto` command family.
+
+## What it does
+
+`cueme proto` injects the shared `protocol.md` into a specific agent file by composing:
+
+`final_proto = prefix(agent) + "\n\n" + protocol.md`
+
+The injected content is managed between sentinel markers and may be overwritten by `cueme proto apply`.
+
+## Config
+
+Config file path:
+
+`~/.cue/cueme.json`
+
+Required keys:
+
+- `cueme.proto.path`: map of injection target paths by `<platform>.<agent>`
+  - `platform`: `linux` | `macos` | `windows`
+  - supports `~` and `%ENV%` expansions (e.g. `%APPDATA%`, `%USERPROFILE%`)
+- `cueme.proto.prefix`: map of prefix by `<agent>`
+  - can be a string or string array (joined with `\n`)
+- `cueme.proto.protocol_path`: absolute or relative path to the shared `protocol.md`
+  - supports `~` and `%ENV%` expansions
+
+Example:
+
+```json
+{
+  "cueme.proto.path": {
+    "macos.vscode": "~/Library/Application Support/Code/User/prompts/human_proto.md",
+    "macos.windsurf": "~/.codeium/windsurf/memories/global_rules.md",
+
+    "windows.vscode": "%APPDATA%\\Code\\User\\prompts\\human_proto.md",
+    "windows.windsurf": "%USERPROFILE%\\.codeium\\windsurf\\memories\\global_rules.md",
+
+    "linux.vscode": "~/.config/Code/User/prompts/human_proto.md",
+    "linux.windsurf": "~/.codeium/windsurf/memories/global_rules.md"
+  },
+  "cueme.proto.prefix": {
+    "vscode": [
+      "---",
+      "applyTo: '**'",
+      "---"
+    ],
+    "windsurf": []
+  },
+  "cueme.proto.protocol_path": "~/path/to/protocol.md"
+}
+```
+
+## Sentinel markers
+
+Injected content is managed between these markers:
+
+```text
+<!-- HUMAN_AGENT_PROTO_BEGIN -->
+... managed content ...
+<!-- HUMAN_AGENT_PROTO_END -->
+```
+
+Notes:
+
+- Markers are written in the standardized `HUMAN_*` form.
+- Existing files that still use `HUAMN_*` markers are also recognized for replacement.
+
+## Commands
+
+### Render (print to stdout)
+
+```bash
+cueme proto <agent>
+```
+
+Generates and prints `final_proto` to stdout.
+
+### Apply (inject into agent file)
+
+```bash
+cueme proto apply <agent>
+```
+
+Behavior:
+
+- Resolves the target path using `cueme.proto.path["<platform>.<agent>"]`.
+- Writes/updates the managed block in the target file.
+- Preserves the target file's existing EOL style when updating.
+
+### Init (create config)
+
+```bash
+cueme proto init
+```
+
+Creates `~/.cue/cueme.json` if missing (never overwrites).
+
+Auto-detect (current platform only):
+
+- `vscode`: `.vscode/prompts/human_proto.md` (workspace) then platform user path
+- `windsurf`: `.codeium/windsurf/memories/global_rules.md` (workspace) then platform user path
+
+### Helpers
+
+```bash
+cueme proto ls
+cueme proto path <agent>
+```

package/package.json

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

package/protocol.md

@@ -4,6 +4,20 @@
 
 当用户接受 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.
+
+**IMPORTANT: cueme 命令不可放在后台运行。** All cueme commands must run in blocking/foreground mode to ensure proper interaction flow.
+
 ## cueme (command interface)
 
 ### join() -> message
@@ -14,7 +28,7 @@ Command:
 
 Returns (plain text):
 
-- a short message (includes `agent_id=...`, `project_dir=...`, `agent_runtime=...`)
+- a short message (includes `agent_id=...`, `project_dir=...`, `agent_terminal=...`, `agent_runtime=...`)
 
 `agent_runtime`:
 
@@ -32,46 +46,36 @@ Returns (plain text):
 
 - a short message (includes `agent_id=...`)
 
-### cue(prompt: str, agent_id: str, payload?: str) -> text
+### cue(prompt: str, agent_id: str, payload?: object | null) -> text
 
 Command:
 
-- `cueme cue <agent_id> <prompt|-> [--payload "{...}"]`
-
-`prompt`:
-
-- Pass a prompt string as the positional `prompt` argument.
-- If `-` is used, instructions are read from stdin.
+`cueme cue <agent_id> -`
 
-Important:
+stdin envelope (tag blocks; tags must be alone on their line):
 
-- Do not pass rich prompt via positional `prompt` argument. Use stdin here-doc/here-string.
+<cueme_prompt>
+...raw prompt text...
+</cueme_prompt>
 
-Examples (stdin):
+<cueme_payload>
+...JSON object or null...
+</cueme_payload>
 
-- `bash/zsh` (here-doc)
+Rules:
 
-  `cueme cue <agent_id> - <<'EOF'
-  <your prompt here>
-  EOF`
+- `<cueme_prompt>` block required; content must be non-empty after trim.
+- `<cueme_payload>` block optional; if present: JSON object or null. Blank content is treated as null.
+- Only whitespace allowed outside these blocks.
+- Legacy JSON envelope is not supported.
 
-- `PowerShell` (here-string)
-
-  `$prompt = @'
-  <your prompt here>
-  '@
-  $prompt | cueme cue <agent_id> -`
+Tip: when you need clearer structured interaction, prefer `payload` (choice/confirm/form) over encoding structure in `prompt`.
 
 Returns:
 
 - plain text (stdout)
 
-`payload`:
-
-- Optional structured request, encoded as a JSON string.
-- `cueme` does not validate payload; it passes it through.
-
-Payload protocol (JSON string):
+Payload protocol (payload object):
 
 - required: {"type": "choice" | "confirm" | "form"}
 - choice: {"type":"choice","options":["...",...],"allow_multiple":false}
@@ -87,24 +91,13 @@ Minimal examples:
 ### pause(agent_id: str, prompt?: str) -> text
 
 Command:
+- `cueme pause <agent_id> [<prompt> | -]`
 
-- `cueme pause <agent_id> <prompt|->`
-
-`prompt`:
+stdin envelope (when `-` is used): tag blocks (prompt only; tags must be alone on their line):
 
-- 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.
+<cueme_prompt>
+...raw prompt text...
+</cueme_prompt>
 
 Returns:
-
 - plain text (stdout)
-
-### Terminal
-Terminal is non-interactive: MUST NOT rely on live local TTY input. Waiting for remote responses is OK (e.g., cueme cue/pause).
-
-### Tool Use Instructions
-IMPORTANT: When you need to perform actions like reading files, running commands,
-or searching, you MUST use the available tools. Do NOT just describe what you would do -
-actually call the tools to do it. Never respond with suggestions like 'check X' or
-'look at Y' without actually using tools to perform those actions.

package/src/cli.js

@@ -1,5 +1,25 @@
 const { readAllStdin } = require('./io');
 const { handleCommand } = require('./handler');
+const { parseTagBlocksEnvelope } = require('./envelope');
+const { protoApply, protoInit, protoLs, protoPath, protoRender } = require('./proto');
+const pkg = require('../package.json');
+const fs = require('fs');
+const path = require('path');
+
+async function parseStdinTagBlocksOrExit({ parsed, allow_payload }) {
+  const raw = await readAllStdin();
+  const env = parseTagBlocksEnvelope(raw, { allow_payload });
+  if (!env.ok) {
+    process.stderr.write(env.error);
+    process.exitCode = 2;
+    return false;
+  }
+  parsed.prompt = env.prompt;
+  if (allow_payload !== false) {
+    parsed.payload = env.payload == null ? null : JSON.stringify(env.payload);
+  }
+  return true;
+}
 
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -46,6 +66,25 @@ function extractTextFromResult(result) {
 }
 
 async function main() {
+  const first = process.argv[2];
+  if (first === '-v' || first === '--version') {
+    process.stdout.write(String(pkg.version || '') + '\n');
+    return;
+  }
+
+  if (first === '-p' || first === '--protocol') {
+    const protocolPath = path.join(__dirname, '..', 'protocol.md');
+    try {
+      const content = fs.readFileSync(protocolPath, 'utf8');
+      process.stdout.write(String(content || ''));
+      if (!String(content || '').endsWith('\n')) process.stdout.write('\n');
+    } catch {
+      process.stderr.write('error: failed to read protocol.md\n');
+      process.exitCode = 2;
+    }
+    return;
+  }
+
   const parsed = parseArgs(process.argv);
   const sub = parsed._[0];
   const pos = parsed._.slice(1);
@@ -56,11 +95,30 @@ async function main() {
         'cueme',
         '',
         'Usage:',
+        '  cueme -v|--version',
+        '  cueme -p|--protocol',
+        '  cueme proto <agent>',
+        '  cueme proto apply <agent>',
+        '  cueme proto init',
+        '  cueme proto ls',
+        '  cueme proto path <agent>',
         '  cueme join <agent_runtime>',
         '  cueme recall <hints>',
-        '  cueme cue <agent_id> [prompt|-] [--payload "{...}"]',
+        '  cueme cue <agent_id> -',
         '  cueme pause <agent_id> [prompt|-]',
-        '  cueme migrate',
+        '',
+        'Cue stdin envelope (tag blocks; tags must be alone on their line):',
+        '  <cueme_prompt>',
+        '  ...raw prompt text...',
+        '  </cueme_prompt>',
+        '  <cueme_payload>',
+        '  ...JSON object or null...',
+        '  </cueme_payload>',
+        '',
+        'Pause stdin envelope (tag blocks; tags must be alone on their line):',
+        '  <cueme_prompt>',
+        '  ...raw prompt text...',
+        '  </cueme_prompt>',
         '',
         'Output:',
         '  - join/recall/cue/pause: plain text (stdout)',
@@ -101,6 +159,59 @@ async function main() {
     parsed.hints = String(hints);
   }
 
+  if (sub === 'proto') {
+    const action = pos[0];
+    try {
+      if (!action) {
+        process.stderr.write('error: missing <agent>\n');
+        process.exitCode = 2;
+        return;
+      }
+
+      if (action === 'ls') {
+        process.stdout.write(protoLs());
+        return;
+      }
+
+      if (action === 'init') {
+        process.stdout.write(protoInit() + '\n');
+        return;
+      }
+
+      if (action === 'apply') {
+        const agent = pos[1];
+        if (!agent) {
+          process.stderr.write('error: missing <agent>\n');
+          process.exitCode = 2;
+          return;
+        }
+        process.stdout.write(protoApply(String(agent)) + '\n');
+        return;
+      }
+
+      if (action === 'path') {
+        const agent = pos[1];
+        if (!agent) {
+          process.stderr.write('error: missing <agent>\n');
+          process.exitCode = 2;
+          return;
+        }
+        process.stdout.write(protoPath(String(agent)) + '\n');
+        return;
+      }
+
+      const agent = action;
+      const rendered = protoRender(String(agent));
+      process.stdout.write(rendered);
+      if (!String(rendered || '').endsWith('\n')) process.stdout.write('\n');
+      return;
+    } catch (err) {
+      process.stderr.write((err && err.message ? err.message : 'error: proto failed') + '\n');
+      process.exitCode = 2;
+      return;
+    }
+  }
+
   if (sub === 'cue') {
     const agentId = pos[0];
     if (!agentId) {
@@ -108,16 +219,30 @@ async function main() {
       process.exitCode = 2;
       return;
     }
+
+    if (parsed.payload != null) {
+      process.stderr.write('error: --payload is not supported for cue. Use stdin tag-blocks envelope.\n');
+      process.exitCode = 2;
+      return;
+    }
+
     parsed.agent_id = String(agentId);
 
     const promptPos = pos[1];
-    if (promptPos === '-') {
-      parsed.prompt = await readAllStdin();
-    } else if (promptPos != null) {
-      parsed.prompt = String(promptPos);
-    } else {
-      parsed.prompt = '';
+    if (promptPos !== '-') {
+      process.stderr.write('error: cue requires stdin tag-blocks. 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 tag-blocks envelope.\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    const ok = await parseStdinTagBlocksOrExit({ parsed, allow_payload: true });
+    if (!ok) return;
   }
 
   if (sub === 'pause') {
@@ -127,14 +252,25 @@ async function main() {
       process.exitCode = 2;
       return;
     }
+
+    if (parsed.payload != null) {
+      process.stderr.write('error: --payload is not supported for pause. Use tag-blocks stdin or positional prompt.\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;
+      if (pos.length > 2) {
+        process.stderr.write('error: pause only accepts <agent_id> [prompt|-] (tag-blocks stdin when "-" is used).\n');
+        process.exitCode = 2;
+        return;
       }
+
+      const ok = await parseStdinTagBlocksOrExit({ parsed, allow_payload: false });
+      if (!ok) return;
     } else if (promptPos != null) {
       parsed.prompt = String(promptPos);
     }

package/src/envelope.js

@@ -0,0 +1,92 @@
+function parseTagBlocksEnvelope(raw, opts = {}) {
+  const allowPayload = opts.allow_payload !== false;
+  const text = String(raw == null ? '' : raw);
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return { ok: false, error: 'error: stdin must use tag-blocks envelope\n' };
+  }
+
+  if (trimmed.startsWith('{')) {
+    return {
+      ok: false,
+      error:
+        'error: legacy JSON envelope is not supported. Use <cueme_prompt>...</cueme_prompt> and optional <cueme_payload>...</cueme_payload>\n',
+    };
+  }
+
+  const promptOpen = '<cueme_prompt>';
+  const promptClose = '</cueme_prompt>';
+  const payloadOpen = '<cueme_payload>';
+  const payloadClose = '</cueme_payload>';
+
+  function findTagLineIndex(lines, tag) {
+    return lines.findIndex((l) => l.trim() === tag);
+  }
+
+  const normalized = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const lines = normalized.split('\n');
+
+  const pOpenIdx = findTagLineIndex(lines, promptOpen);
+  const pCloseIdx = findTagLineIndex(lines, promptClose);
+  if (pOpenIdx < 0 || pCloseIdx < 0 || pCloseIdx <= pOpenIdx) {
+    return { ok: false, error: 'error: missing <cueme_prompt> block\n' };
+  }
+
+  const pre = lines.slice(0, pOpenIdx).join('\n');
+  if (pre.trim().length > 0) {
+    return { ok: false, error: 'error: only whitespace is allowed outside blocks\n' };
+  }
+
+  const promptText = lines.slice(pOpenIdx + 1, pCloseIdx).join('\n');
+  if (!promptText.trim()) {
+    return { ok: false, error: 'error: <cueme_prompt> content must be non-empty\n' };
+  }
+
+  const remainingLines = lines.slice(pCloseIdx + 1);
+  const remainingText = remainingLines.join('\n');
+
+  const rOpenIdx = findTagLineIndex(remainingLines, payloadOpen);
+  const rCloseIdx = findTagLineIndex(remainingLines, payloadClose);
+
+  let payload = null;
+
+  if (rOpenIdx >= 0 || rCloseIdx >= 0) {
+    if (!allowPayload) {
+      return { ok: false, error: 'error: <cueme_payload> is not supported for pause\n' };
+    }
+
+    if (rOpenIdx < 0 || rCloseIdx < 0 || rCloseIdx <= rOpenIdx) {
+      return { ok: false, error: 'error: invalid <cueme_payload> block\n' };
+    }
+
+    const between = remainingLines.slice(0, rOpenIdx).join('\n');
+    const after = remainingLines.slice(rCloseIdx + 1).join('\n');
+    if (between.trim().length > 0 || after.trim().length > 0) {
+      return { ok: false, error: 'error: only whitespace is allowed outside blocks\n' };
+    }
+
+    const payloadRaw = remainingLines.slice(rOpenIdx + 1, rCloseIdx).join('\n').trim();
+    if (!payloadRaw || payloadRaw === 'null') {
+      payload = null;
+    } else {
+      let parsed;
+      try {
+        parsed = JSON.parse(payloadRaw);
+      } catch {
+        return { ok: false, error: 'error: <cueme_payload> must be JSON object or null\n' };
+      }
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, error: 'error: <cueme_payload> must be JSON object or null\n' };
+      }
+      payload = parsed;
+    }
+  } else {
+    if (remainingText.trim().length > 0) {
+      return { ok: false, error: 'error: only whitespace is allowed outside blocks\n' };
+    }
+  }
+
+  return { ok: true, prompt: promptText, payload };
+}
+
+module.exports = { parseTagBlocksEnvelope };

package/src/handler.js

@@ -1,7 +1,4 @@
 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');
@@ -99,9 +96,48 @@ function normalizeAgentRuntime(raw) {
   return s ? s : 'unknown';
 }
 
+function detectAgentTerminal() {
+  const platform = process.platform;
+  if (platform === 'win32') {
+    const comspec = (process.env.ComSpec ?? '').toString().toLowerCase();
+    const psModulePath = (process.env.PSModulePath ?? '').toString();
+    const shell = (process.env.SHELL ?? '').toString().toLowerCase();
+    const nuVersion = (process.env.NU_VERSION ?? '').toString();
+    const msystem = (process.env.MSYSTEM ?? '').toString().toLowerCase();
+
+    if (
+      shell.includes('powershell') ||
+      shell.includes('pwsh') ||
+      comspec.includes('powershell') ||
+      comspec.includes('pwsh') ||
+      psModulePath
+    ) {
+      return 'powershell';
+    }
+
+    if (nuVersion || shell.includes('nushell') || shell.endsWith('/nu') || shell === 'nu') return 'nushell';
+
+    if (shell.endsWith('/bash') || shell === 'bash' || msystem) return 'bash';
+
+    if (comspec.endsWith('cmd.exe') || comspec.includes('\\cmd.exe') || comspec.includes('/cmd.exe')) return 'cmd';
+    return 'unknown';
+  }
+
+  const isWsl = Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+
+  const shellPath = (process.env.SHELL ?? '').toString().toLowerCase();
+  if (shellPath.endsWith('/zsh') || shellPath === 'zsh') return 'zsh';
+  if (shellPath.endsWith('/bash') || shellPath === 'bash') return 'bash';
+  if (shellPath.endsWith('/fish') || shellPath === 'fish') return 'fish';
+  if (shellPath.endsWith('/nu') || shellPath === 'nu' || shellPath.includes('nushell')) return 'nushell';
+  if (isWsl && (shellPath.endsWith('/bash') || shellPath === 'bash' || !shellPath)) return 'bash';
+  return 'unknown';
+}
+
 async function handleJoin(db, agent_runtime) {
   const agent_id = generateName();
   const project_dir = process.cwd();
+  const agent_terminal = detectAgentTerminal();
   const normalized_runtime = normalizeAgentRuntime(agent_runtime);
   return {
     ok: true,
@@ -110,6 +146,7 @@ async function handleJoin(db, agent_runtime) {
       message:
         `agent_id=${agent_id}\n` +
         `project_dir=${project_dir}\n` +
+        `agent_terminal=${agent_terminal}\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.' +
@@ -314,197 +351,11 @@ 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' && 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') {
@@ -526,10 +377,6 @@ 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,12 +1,69 @@
 function readAllStdin() {
   if (process.stdin.isTTY) return Promise.resolve('');
   return new Promise((resolve, reject) => {
-    let data = '';
-    process.stdin.setEncoding('utf8');
+    const chunks = [];
     process.stdin.on('data', (chunk) => {
-      data += chunk;
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    });
+    process.stdin.on('end', () => {
+      const buf = Buffer.concat(chunks);
+      if (!buf || buf.length === 0) return resolve('');
+
+      // BOM detection
+      if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+        return resolve(buf.slice(3).toString('utf8'));
+      }
+      if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+        return resolve(buf.slice(2).toString('utf16le'));
+      }
+      if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+        // UTF-16BE is rare; decode by swapping bytes.
+        const swapped = Buffer.alloc(buf.length - 2);
+        for (let i = 2; i + 1 < buf.length; i += 2) {
+          swapped[i - 2] = buf[i + 1];
+          swapped[i - 1] = buf[i];
+        }
+        return resolve(swapped.toString('utf16le'));
+      }
+
+      // Heuristic: PowerShell piping to native exe often uses UTF-16LE without BOM.
+      const sampleLen = Math.min(buf.length, 256);
+
+      // For small samples, use odd/even byte distribution (UTF-16LE ASCII often has 0x00 in odd indices).
+      if (sampleLen <= 64) {
+        let oddTotal = 0;
+        let evenTotal = 0;
+        let oddZeros = 0;
+        let evenZeros = 0;
+        for (let i = 0; i < sampleLen; i += 1) {
+          if (i % 2 === 0) {
+            evenTotal += 1;
+            if (buf[i] === 0x00) evenZeros += 1;
+          } else {
+            oddTotal += 1;
+            if (buf[i] === 0x00) oddZeros += 1;
+          }
+        }
+
+        const oddZeroRatio = oddTotal > 0 ? oddZeros / oddTotal : 0;
+        const evenZeroRatio = evenTotal > 0 ? evenZeros / evenTotal : 0;
+
+        if (oddZeroRatio > 0.6 && evenZeroRatio < 0.2) {
+          return resolve(buf.toString('utf16le'));
+        }
+      } else {
+        let zeros = 0;
+        for (let i = 0; i < sampleLen; i += 1) {
+          if (buf[i] === 0x00) zeros += 1;
+        }
+        const zeroRatio = zeros / sampleLen;
+        if (zeroRatio > 0.2) {
+          return resolve(buf.toString('utf16le'));
+        }
+      }
+
+      return resolve(buf.toString('utf8'));
     });
-    process.stdin.on('end', () => resolve(data));
     process.stdin.on('error', reject);
   });
 }

package/src/proto.js

@@ -0,0 +1,384 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const BEGIN_MARKER = '<!-- HUMAN_AGENT_PROTO_BEGIN -->';
+const END_MARKER = '<!-- HUMAN_AGENT_PROTO_END -->';
+
+const BEGIN_MARKER_RE = /<!--\s*(?:HUMAN|HUAMN)_AGENT_PROTO_BEGIN\s*-->/;
+const END_MARKER_RE = /<!--\s*(?:HUMAN|HUAMN)_AGENT_PROTO_END\s*-->/;
+
+function getPlatformKey() {
+  const p = process.platform;
+  if (p === 'win32') return 'windows';
+  if (p === 'darwin') return 'macos';
+  if (p === 'linux') return 'linux';
+  return p;
+}
+
+function configPath() {
+  return path.join(os.homedir(), '.cue', 'cueme.json');
+}
+
+function expandPath(p) {
+  if (typeof p !== 'string') return p;
+  let s = p;
+
+  // Expand leading ~
+  if (s === '~' || s.startsWith('~/') || s.startsWith('~\\')) {
+    s = path.join(os.homedir(), s.slice(2));
+  }
+
+  // Expand %ENV% variables (Windows-style)
+  s = s.replace(/%([A-Za-z0-9_]+)%/g, (_, name) => {
+    const v = process.env[name];
+    return typeof v === 'string' ? v : '';
+  });
+
+  return s;
+}
+
+function pathExists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+function detectVscodeCandidates({ platform }) {
+  const candidates = [];
+  const cwd = process.cwd();
+
+  // Workspace-level (if you want repo-local rules)
+  candidates.push(path.join(cwd, '.vscode', 'prompts', 'human_proto.md'));
+
+  // User-level prompts
+  const home = os.homedir();
+  if (platform === 'macos') {
+    candidates.push(
+      path.join(home, 'Library', 'Application Support', 'Code', 'User', 'prompts', 'human_proto.md')
+    );
+  }
+  if (platform === 'linux') {
+    // User supplied: ~/.config/Code/User/prompts/
+    candidates.push(path.join(home, '.config', 'Code', 'User', 'prompts', 'human_proto.md'));
+  }
+  if (platform === 'windows') {
+    const appData = process.env.APPDATA;
+    if (appData) candidates.push(path.join(appData, 'Code', 'User', 'prompts', 'human_proto.md'));
+  }
+
+  return candidates;
+}
+
+function detectWindsurfCandidates({ platform }) {
+  const candidates = [];
+  const cwd = process.cwd();
+
+  // Workspace-level (repo-local)
+  candidates.push(path.join(cwd, '.codeium', 'windsurf', 'memories', 'global_rules.md'));
+
+  // User-level (standard)
+  const home = os.homedir();
+  const userProfile = process.env.USERPROFILE || home;
+  if (platform === 'macos') candidates.push(path.join(home, '.codeium', 'windsurf', 'memories', 'global_rules.md'));
+  if (platform === 'linux') candidates.push(path.join(home, '.codeium', 'windsurf', 'memories', 'global_rules.md'));
+  if (platform === 'windows') {
+    candidates.push(path.join(userProfile, '.codeium', 'windsurf', 'memories', 'global_rules.md'));
+  }
+
+  return candidates;
+}
+
+function firstExistingPath(candidates) {
+  for (const p of candidates) {
+    if (typeof p === 'string' && p.trim().length > 0 && pathExists(p)) return p;
+  }
+  return '';
+}
+
+function defaultPathMapTemplate() {
+  const out = {};
+
+  const home = os.homedir();
+  const appData = process.env.APPDATA || '';
+  const userProfile = process.env.USERPROFILE || home;
+
+  // VSCode
+  out['macos.vscode'] = path.join(
+    home,
+    'Library',
+    'Application Support',
+    'Code',
+    'User',
+    'prompts',
+    'human_proto.md'
+  );
+  out['windows.vscode'] = appData
+    ? path.join(appData, 'Code', 'User', 'prompts', 'human_proto.md')
+    : path.join(userProfile, 'AppData', 'Roaming', 'Code', 'User', 'prompts', 'human_proto.md');
+  out['linux.vscode'] = path.join(home, '.config', 'Code', 'User', 'prompts', 'human_proto.md');
+
+  // Windsurf
+  out['macos.windsurf'] = path.join(home, '.codeium', 'windsurf', 'memories', 'global_rules.md');
+  out['windows.windsurf'] = path.join(userProfile, '.codeium', 'windsurf', 'memories', 'global_rules.md');
+  out['linux.windsurf'] = path.join(home, '.codeium', 'windsurf', 'memories', 'global_rules.md');
+
+  return out;
+}
+
+function defaultConfigTemplate() {
+  const protocolPath = path.join(__dirname, '..', 'protocol.md');
+  return {
+    'cueme.proto.path': defaultPathMapTemplate(),
+    'cueme.proto.prefix': {
+      windsurf: [],
+      vscode: ['---', 'applyTo: "**"', '---'],
+    },
+    'cueme.proto.protocol_path': protocolPath,
+  };
+}
+
+function detectAndFillTemplatePaths(tpl) {
+  const platform = getPlatformKey();
+  const keyVscode = `${platform}.vscode`;
+  const keyWindsurf = `${platform}.windsurf`;
+
+  const pathMap = tpl['cueme.proto.path'] || {};
+  const detected = { platform, vscode: '', windsurf: '' };
+
+  if (typeof pathMap !== 'object' || Array.isArray(pathMap)) {
+    return { tpl, detected };
+  }
+
+  // If current platform key is empty or missing, try detect.
+  if (typeof pathMap[keyVscode] !== 'string' || pathMap[keyVscode].trim().length === 0) {
+    const p = firstExistingPath(detectVscodeCandidates({ platform }));
+    if (p) {
+      pathMap[keyVscode] = p;
+      detected.vscode = p;
+    }
+  }
+
+  if (typeof pathMap[keyWindsurf] !== 'string' || pathMap[keyWindsurf].trim().length === 0) {
+    const p = firstExistingPath(detectWindsurfCandidates({ platform }));
+    if (p) {
+      pathMap[keyWindsurf] = p;
+      detected.windsurf = p;
+    }
+  }
+
+  tpl['cueme.proto.path'] = pathMap;
+  return { tpl, detected };
+}
+
+function initConfigIfMissing() {
+  const p = configPath();
+  if (fs.existsSync(p)) {
+    return { created: false, path: p, detected: null };
+  }
+  ensureDirForFile(p);
+  const { tpl, detected } = detectAndFillTemplatePaths(defaultConfigTemplate());
+  fs.writeFileSync(p, JSON.stringify(tpl, null, 2) + '\n', 'utf8');
+  return { created: true, path: p, detected };
+}
+
+function readConfigOrThrow({ auto_init } = {}) {
+  const p = configPath();
+  let raw;
+  try {
+    raw = fs.readFileSync(p, 'utf8');
+  } catch {
+    if (auto_init) {
+      initConfigIfMissing();
+      try {
+        raw = fs.readFileSync(p, 'utf8');
+      } catch {
+        throw new Error(`error: cannot read config: ${p}`);
+      }
+    } else {
+      throw new Error(`error: cannot read config: ${p}`);
+    }
+  }
+
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch {
+    throw new Error(`error: config is not valid JSON: ${p}`);
+  }
+
+  if (!cfg || typeof cfg !== 'object') {
+    throw new Error(`error: config must be a JSON object: ${p}`);
+  }
+  return cfg;
+}
+
+function detectEol(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function ensureDirForFile(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function buildFinalProto({ cfg, agent }) {
+  const prefixMap = cfg['cueme.proto.prefix'] || {};
+  const protocolPath = cfg['cueme.proto.protocol_path'];
+
+  const prefixRaw = prefixMap[agent];
+  let prefix;
+  if (typeof prefixRaw === 'string') {
+    prefix = prefixRaw;
+  } else if (Array.isArray(prefixRaw) && prefixRaw.every((x) => typeof x === 'string')) {
+    prefix = prefixRaw.join('\n');
+  } else {
+    throw new Error(`error: prefix not configured: cueme.proto.prefix["${agent}"]`);
+  }
+
+  if (typeof protocolPath !== 'string' || protocolPath.trim().length === 0) {
+    throw new Error('error: cannot read protocol.md');
+  }
+
+  const protocolPathExpanded = expandPath(protocolPath);
+  const resolvedProtocolPath = path.isAbsolute(protocolPathExpanded)
+    ? protocolPathExpanded
+    : path.resolve(process.cwd(), protocolPathExpanded);
+
+  let protocol;
+  try {
+    protocol = fs.readFileSync(resolvedProtocolPath, 'utf8');
+  } catch {
+    throw new Error('error: cannot read protocol.md');
+  }
+
+  return `${prefix}\n\n${protocol}`;
+}
+
+function resolveTargetPath({ cfg, agent }) {
+  const platform = getPlatformKey();
+  const key = `${platform}.${agent}`;
+  const pathMap = cfg['cueme.proto.path'] || {};
+  const p = pathMap[key];
+  if (typeof p !== 'string' || p.trim().length === 0) {
+    throw new Error(`error: target path not configured: cueme.proto.path["${key}"]`);
+  }
+  const expanded = expandPath(p);
+  return path.isAbsolute(expanded) ? expanded : path.resolve(process.cwd(), expanded);
+}
+
+function makeManagedBlock({ finalProto, eol }) {
+  const normalized = String(finalProto || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const protoLines = normalized.split('\n');
+  return [BEGIN_MARKER, ...protoLines, END_MARKER].join(eol) + eol;
+}
+
+function applyManagedBlock({ existing, finalProto }) {
+  const eol = detectEol(existing);
+  const block = makeManagedBlock({ finalProto, eol });
+
+  const beginMatch = existing.match(BEGIN_MARKER_RE);
+  const endMatch = existing.match(END_MARKER_RE);
+  if (beginMatch && endMatch && endMatch.index > beginMatch.index) {
+    const beginIdx = beginMatch.index;
+    const endIdx = endMatch.index;
+    const endLen = endMatch[0].length;
+
+    const before = existing.slice(0, beginIdx);
+    const after = existing.slice(endIdx + endLen);
+
+    const afterTrim = after.startsWith(eol) ? after.slice(eol.length) : after;
+    return before + block + afterTrim;
+  }
+
+  let out = existing;
+  if (!out.endsWith(eol)) out += eol;
+  out += block;
+  return out;
+}
+
+function listAgents({ cfg }) {
+  const prefixMap = cfg['cueme.proto.prefix'] || {};
+  const pathMap = cfg['cueme.proto.path'] || {};
+
+  const agents = new Set();
+  for (const k of Object.keys(prefixMap)) agents.add(k);
+  for (const k of Object.keys(pathMap)) {
+    const parts = String(k).split('.');
+    if (parts.length === 2) agents.add(parts[1]);
+  }
+
+  return Array.from(agents).sort();
+}
+
+function protoRender(agent) {
+  const cfg = readConfigOrThrow({ auto_init: true });
+  return buildFinalProto({ cfg, agent });
+}
+
+function protoPath(agent) {
+  const cfg = readConfigOrThrow({ auto_init: true });
+  return resolveTargetPath({ cfg, agent });
+}
+
+function protoLs() {
+  const cfg = readConfigOrThrow({ auto_init: true });
+  return listAgents({ cfg }).join('\n') + '\n';
+}
+
+function protoApply(agent) {
+  const cfg = readConfigOrThrow({ auto_init: true });
+  const targetPath = resolveTargetPath({ cfg, agent });
+  const finalProto = buildFinalProto({ cfg, agent });
+
+  let existing = '';
+  let exists = false;
+  try {
+    existing = fs.readFileSync(targetPath, 'utf8');
+    exists = true;
+  } catch {
+    existing = '';
+    exists = false;
+  }
+
+  const eol = exists ? detectEol(existing) : os.EOL;
+  const managedBlock = makeManagedBlock({ finalProto, eol });
+
+  let out;
+  if (!exists) {
+    out = managedBlock;
+  } else {
+    out = applyManagedBlock({ existing, finalProto });
+  }
+
+  ensureDirForFile(targetPath);
+  fs.writeFileSync(targetPath, out, 'utf8');
+
+  return `ok: applied to ${targetPath}`;
+}
+
+function protoInit() {
+  const { created, path: p, detected } = initConfigIfMissing();
+  if (!created) return `ok: exists ${p}`;
+  const platform = detected && detected.platform ? detected.platform : getPlatformKey();
+  const keyVscode = `${platform}.vscode`;
+  const keyWindsurf = `${platform}.windsurf`;
+  const vs = detected && detected.vscode ? 'detected' : 'empty';
+  const ws = detected && detected.windsurf ? 'detected' : 'empty';
+  return `ok: initialized ${p} (auto-detect: ${keyVscode}=${vs}, ${keyWindsurf}=${ws})`;
+}
+
+module.exports = {
+  BEGIN_MARKER,
+  END_MARKER,
+  getPlatformKey,
+  protoApply,
+  protoInit,
+  protoLs,
+  protoPath,
+  protoRender,
+};