cueme 0.1.4 → 0.1.7

package/README.md

@@ -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.4",
+  "version": "0.1.7",
   "description": "Cue command protocol adapter (stdin/stdout JSON)",
   "license": "Apache-2.0",
   "files": [
     "bin/",
     "src/",
+    "docs/",
     "protocol.md",
     "README.md",
     "LICENSE"

package/protocol.md

@@ -2,22 +2,26 @@
 
 你与用户的协作交互通过命令行工具 `cueme` 完成。
 
+- 首次连接 / 无 agent_id：先执行 `join()` 获取 agent_id，再执行 `cue()`。
+
+- 重连 / 已有 agent_id（例如网络波动导致 cue 中断但对话仍在继续）：用户再次发送 `cue` 时，优先直接用已有 agent_id 执行 `cue()`；仅当无法确认 agent_id 时才重新 `join()`。
+
 当用户接受 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)
 
+cueme 命令不可放在后台运行.All cueme commands must run in blocking/foreground mode to ensure proper interaction flow.
+
 ### join() -> message
 
 Command:
@@ -26,7 +30,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`:
 
@@ -34,29 +38,30 @@ Returns (plain text):
 - Format: lowercase, `_` only.
 - Examples: `windsurf`, `cursor`, `vscode`, `claude_code`, `terminal`, `codex`, `kiro`, `opencode`.
 
-### recall(hints: str) -> message
+### cue(agent_id: str, stdin: {prompt: str!, payload?: object | null}) -> text
 
-Command:
-
-- `cueme recall <hints>`
+Command (requires stdin):
 
-Returns (plain text):
+`cueme cue <agent_id> -`
 
-- a short message (includes `agent_id=...`)
+Provide via stdin (tag-block envelope, MUST NOT be empty; bash/zsh use heredoc; PowerShell use here-string):
 
-### cue(prompt: str, agent_id: str, payload?: object | null) -> text
+<cueme_prompt>
+Your actual prompt text here
+</cueme_prompt>
 
-Command:
+<cueme_payload>
+{"type":"confirm","text":"Continue?"}
+</cueme_payload>
 
-`cueme cue <agent_id> -`
+Rules:
 
-stdin JSON envelope:
-{
-  "prompt": NonEmptyString,          // REQUIRED, must be non-empty after trim
-  "payload"?: object | null          // OPTIONAL, may be omitted or null
-}
+- `<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.
 
-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> -`.
+Tip: when you need clearer structured interaction, prefer `payload` (choice/confirm/form) over encoding structure in `prompt`.
 
 Returns:
 
@@ -69,24 +74,16 @@ Payload protocol (payload object):
 - 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> | -]`
 
-- `cueme pause <agent_id> <prompt|->`
+stdin envelope (when `-` is used): tag blocks (prompt only; tags must be alone on their line):
 
-`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.
+<cueme_prompt>
+...raw prompt text...
+</cueme_prompt>
 
 Returns:
-
 - plain text (stdout)

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,17 +95,32 @@ 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> -',
         '  cueme pause <agent_id> [prompt|-]',
-        '  cueme migrate',
         '',
-        'Cue stdin JSON envelope:',
-        '  {"prompt":"...","payload":{...}}',
+        '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)',
+        '  - join/cue/pause: plain text (stdout)',
       ].join('\n') + '\n'
     );
     return;
@@ -78,8 +132,8 @@ async function main() {
     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');
+  if (parsed.agent_id != null || parsed.prompt != null) {
+    process.stderr.write('error: --agent_id/--prompt flags are not supported; use positional args\n');
     process.exitCode = 2;
     return;
   }
@@ -94,14 +148,57 @@ async function main() {
     parsed.agent_runtime = String(agentRuntime);
   }
 
-  if (sub === 'recall') {
-    const hints = pos[0];
-    if (!hints) {
-      process.stderr.write('error: missing <hints>\n');
+  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;
     }
-    parsed.hints = String(hints);
   }
 
   if (sub === 'cue') {
@@ -113,7 +210,7 @@ async function main() {
     }
 
     if (parsed.payload != null) {
-      process.stderr.write('error: --payload is not supported for cue. Use stdin JSON envelope.\n');
+      process.stderr.write('error: --payload is not supported for cue. Use stdin tag-blocks envelope.\n');
       process.exitCode = 2;
       return;
     }
@@ -122,42 +219,19 @@ async function main() {
 
     const promptPos = pos[1];
     if (promptPos !== '-') {
-      process.stderr.write('error: cue requires stdin JSON. Usage: cueme cue <agent_id> -\n');
+      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 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.stderr.write('error: cue only accepts <agent_id> - and stdin tag-blocks envelope.\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);
+    const ok = await parseStdinTagBlocksOrExit({ parsed, allow_payload: true });
+    if (!ok) return;
   }
 
   if (sub === 'pause') {
@@ -167,14 +241,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,95 @@
+function parseTagBlocksEnvelope(raw, opts = {}) {
+  const allowPayload = opts.allow_payload !== false;
+  const text = String(raw == null ? '' : raw);
+  const trimmed = text.trim();
+  if (!trimmed) {
+    // Fallback: use default prompt based on command type
+    // allowPayload === true means cue command, false means pause command
+    const defaultPrompt = allowPayload ? 'hi' : 'pause';
+    return { ok: true, prompt: defaultPrompt, payload: null };
+  }
+
+  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 };