cueme 0.1.3 → 0.1.4

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueme",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Cue command protocol adapter (stdin/stdout JSON)",
   "license": "Apache-2.0",
   "files": [

package/protocol.md

@@ -4,6 +4,18 @@
 
 当用户接受 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
@@ -32,46 +44,25 @@ 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 JSON envelope:
+{
+  "prompt": NonEmptyString,          // REQUIRED, must be non-empty after trim
+  "payload"?: object | null          // OPTIONAL, may be omitted or null
+}
 
-- Do not pass rich prompt via positional `prompt` argument. Use stdin here-doc/here-string.
-
-Examples (stdin):
-
-- `bash/zsh` (here-doc)
-
-  `cueme cue <agent_id> - <<'EOF'
-  <your prompt here>
-  EOF`
-
-- `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`. bash/zsh use heredoc; PowerShell use here-string and pipe the JSON into `cueme cue <agent_id> -`.
 
 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}
@@ -99,12 +90,3 @@ Command:
 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

@@ -58,10 +58,13 @@ async function main() {
         'Usage:',
         '  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 JSON envelope:',
+        '  {"prompt":"...","payload":{...}}',
+        '',
         'Output:',
         '  - join/recall/cue/pause: plain text (stdout)',
       ].join('\n') + '\n'
@@ -108,16 +111,53 @@ async function main() {
       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 === '-') {
-      parsed.prompt = await readAllStdin();
-    } else if (promptPos != null) {
-      parsed.prompt = String(promptPos);
-    } else {
-      parsed.prompt = '';
+    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') {