@ricsam/r5dctl 0.0.107 → 0.0.108

package/README.md

@@ -87,7 +87,7 @@ r5dctl conversation move-head <session-id> <node-id>     # rewind or replay the
 r5dctl conversation fork <session-id> <node-id>          # copy the branch up to a node into a new session
 r5dctl conversation fork <session-id> <node-id> --name "Retry with tests"
 r5dctl session prompt --worker <label> --mode plan --model max <session-id> "..."
-r5dctl session prompt --worker <label> --mode agent --model max --delivery queue <session-id> "..."   # after the current turn
+r5dctl session prompt --worker <label> --mode agent --model max --delivery queue <session-id> "After you finish your current task, review the release notes"   # deliberately deferred work
 r5dctl -s <session-id> answer-questions --worker <label> --mode plan --model max -a1 "Recipe Collection" -a2 "Both Manual & AI"
 r5dctl -s <session-id> answer-env-request --worker <label> --mode agent --model max -e KEY=value --context "Generate the remaining salts"
 
@@ -95,7 +95,7 @@ r5dctl -p <project> session start --worker <label> --worktree main --model max "
 r5dctl -p <project> session start --worker <label> --new-worktree fix/tests --source worktree:main --model max -f "Fix the failing tests"
 r5dctl -p <project> session start --worker <label> --new-worktree fix/tests --source worktree:main --working-tree clean --model max "Fix the failing tests from main's committed state"
 r5dctl session status <session-id>
-r5dctl session prompt --worker <label> --mode agent --model max <session-id> "Also check the migration"
+r5dctl session prompt --worker <label> --mode agent --model max --delivery steer <session-id> "Also check the migration"
 r5dctl session prompt --worker <label> --mode agent --model max --delivery force <session-id> "Stop that and fix the build first"
 r5dctl session stop <session-id>
 r5dctl session process-log <run-id> --tail 200
@@ -135,6 +135,12 @@ pull requests.
 
 `session prompt` works on any project session you can access, including one created in the web UI. `--delivery` decides how the prompt reaches a session whose agent is busy: `steer` (the default) lands inside the current turn right after the agent's next tool result, `queue` waits until the agent finishes the whole turn, and `force` aborts the agent's current round of tool calls and continues from the prompt instead. An idle session starts a new generation whatever the delivery, and a steer queued while the session was idle with an unfinished turn is still heard by the generation that resumes it. The response's `Prompt:` line reports `started`, `steered`, `queued`, or `forced`. `session stop` returns as soon as the agent run is stopped; the stopped worktree's workspace Git synchronization finishes asynchronously behind the response.
 
+Use the optional `--sender "Authentication review"` flag to display a title above the usual message bubble. Agent shells expose `R5D_SESSION_NAME`, refreshed at each command start from the session name (or its ID until named), so agents can pass `--sender "$R5D_SESSION_NAME"`. The sender is a caller-supplied label; omitting the flag sends no title and leaves the message body unchanged.
+
+For messages to an active session, explicitly use `--delivery steer` for coordination such as merge notices, requests to pause or avoid files, blockers, corrections, and handoff or resume notices. Use `--delivery force` when its current tool round must be interrupted. Reserve `--delivery queue` for work intentionally deferred until the entire current turn ends; even an FYI needs steering when it affects current work. These rules apply equally to peers, parents, and children.
+
+Delivery is not acknowledgment. If a merge or shared-checkout change depends on another session pausing edits, send the pause request separately, wait for its explicit reply, and recheck the working tree before proceeding. `Prompt: queued` cannot establish that coordination, and even `steered` or `forced` does not prove the agent has read or acted on the request. Reply to coordination requests and send resume notices with `--delivery steer`.
+
 `get sessions` lists a project's sessions, newest first, and appends each session's live state (`running`, `stopping`, `paused`, `provisioning`, `queued`, or `idle`) and how long ago its conversation last advanced (`running, last active 12s ago`). Several sessions can work in the same branch checkout at once (task chips, shared-mode sub-agents, sessions the user starts), so run it with `--branch` before relying on a working tree or reviewing what changed in it. A server that predates the fields prints the id, branch, and name only.
 
 `session stop` also stops every sub-agent session the stopped session started, directly or through its own children, and `session status` prints `Child sessions: <active> active of <total>` for a session that launched sub-agents.

package/dist/cjs/cli.cjs

@@ -177,13 +177,16 @@ const SESSION_RUN_HELP_TEXT = [
   '  r5dctl -p <project> session start --worker <label> --worktree <branch> --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
   '  r5dctl -p <project> session start --worker <label> --new-worktree <branch> --source worktree:<branch> [--working-tree carry|clean] --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
   "  r5dctl session status <session-id>",
-  '  r5dctl session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] <session-id> "<prompt>"',
+  '  r5dctl session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
   "  r5dctl session stop <session-id>",
   "  r5dctl session process-log <run-id> [--tail <n>] [--grep <pattern>]",
   "",
   "Create, inspect, resume, and stop ordinary agent sessions.",
   "prompt reaches a busy session by --delivery: steer (default) lands after the agent's next tool result,",
   "queue waits for the current turn to finish, force replaces the agent's current tool round. An idle session starts a new generation either way.",
+  "Use --delivery steer for active-session coordination, including merge notices, pause requests, blockers, and handoffs.",
+  "Use force when the current tool round must be interrupted; queue is only for work deliberately deferred until the turn ends.",
+  "Prompt delivery is not acknowledgment. If a shared-checkout change depends on a pause, wait for the recipient's reply before proceeding.",
   "A new worktree starts with the source checkout's uncommitted changes (--working-tree carry, the default);",
   "--working-tree clean checks out the source branch's current commit only. Start and status print the mode, never a commit hash.",
   "Use -f/--follow/--watch to attach after a start; Ctrl-C detaches without stopping the session.",
@@ -313,8 +316,8 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: 'session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] <session-id> "<prompt>"',
-    description: "Prompt a session: steer into the current turn after the next tool result (default), queue behind the turn, or force in place of the current tool round; an idle session starts a new generation."
+    usage: 'session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
+    description: "Prompt a session: steer into the current turn after the next tool result (default), queue behind the turn, or force in place of the current tool round; an idle session starts a new generation. Use steer for active-session coordination; queue only deliberately deferred work. --sender adds an optional title above the message."
   },
   {
     section: "sessions",
@@ -814,15 +817,24 @@ function parseSessionRunCommand(options, args) {
     return { kind: subcommand, sessionId };
   }
   if (subcommand === "prompt") {
-    const parsed = parseCommandOperands(commandArgs, /* @__PURE__ */ new Set(["--worker", "--mode", "--model", "--delivery"]), /* @__PURE__ */ new Map(), "session prompt", 1);
+    const parsed = parseCommandOperands(
+      commandArgs,
+      /* @__PURE__ */ new Set(["--worker", "--mode", "--model", "--delivery", "--sender"]),
+      /* @__PURE__ */ new Map(),
+      "session prompt",
+      1
+    );
     const sessionId = requireValue(parsed.positionals[0], "Session id is required for `session prompt`");
     const prompt = parsed.positionals.slice(1).join(" ").trim();
     if (!prompt) throw new Error("Prompt is required for `session prompt`");
+    const sender = parsed.values.get("--sender")?.trim();
+    if (sender !== void 0 && !sender) throw new Error("--sender must not be empty");
     return {
       kind: "prompt",
       worker: requireWorker(parsed.values),
       sessionId,
       prompt,
+      ...sender ? { sender } : {},
       mode: requireSessionMode(parsed.values.get("--mode")),
       model: requireModel(parsed.values.get("--model")),
       delivery: parsePromptDelivery(parsed.values.get("--delivery"))
@@ -2185,7 +2197,7 @@ function renderSessionRunStatus(session) {
   const summary = responseString(session, "summary");
   if (summary) lines.push("", summary);
   const sessionId = responseString(session, "sessionId");
-  if (sessionId && ["provisioning", "queued", "running"].includes(status)) {
+  if (sessionId && ["provisioning", "queued", "running", "waiting"].includes(status)) {
     lines.push("", "Next:", `  r5dctl session status ${sessionId}`, `  r5dctl session stop ${sessionId}`);
   }
   return `${lines.join("\n")}
@@ -2222,7 +2234,8 @@ async function dispatchSessionRunCommand(client, command) {
       mode: command.mode,
       model: command.model,
       requestId: (0, import_node_crypto.randomUUID)(),
-      delivery: command.delivery
+      delivery: command.delivery,
+      ...command.sender ? { sender: command.sender } : {}
     });
     return { data: data2, human: renderSessionRunStatus(data2) };
   }

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "type": "commonjs"
 }

package/dist/mjs/cli.mjs

@@ -77,13 +77,16 @@ const SESSION_RUN_HELP_TEXT = [
   '  r5dctl -p <project> session start --worker <label> --worktree <branch> --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
   '  r5dctl -p <project> session start --worker <label> --new-worktree <branch> --source worktree:<branch> [--working-tree carry|clean] --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
   "  r5dctl session status <session-id>",
-  '  r5dctl session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] <session-id> "<prompt>"',
+  '  r5dctl session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
   "  r5dctl session stop <session-id>",
   "  r5dctl session process-log <run-id> [--tail <n>] [--grep <pattern>]",
   "",
   "Create, inspect, resume, and stop ordinary agent sessions.",
   "prompt reaches a busy session by --delivery: steer (default) lands after the agent's next tool result,",
   "queue waits for the current turn to finish, force replaces the agent's current tool round. An idle session starts a new generation either way.",
+  "Use --delivery steer for active-session coordination, including merge notices, pause requests, blockers, and handoffs.",
+  "Use force when the current tool round must be interrupted; queue is only for work deliberately deferred until the turn ends.",
+  "Prompt delivery is not acknowledgment. If a shared-checkout change depends on a pause, wait for the recipient's reply before proceeding.",
   "A new worktree starts with the source checkout's uncommitted changes (--working-tree carry, the default);",
   "--working-tree clean checks out the source branch's current commit only. Start and status print the mode, never a commit hash.",
   "Use -f/--follow/--watch to attach after a start; Ctrl-C detaches without stopping the session.",
@@ -213,8 +216,8 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: 'session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] <session-id> "<prompt>"',
-    description: "Prompt a session: steer into the current turn after the next tool result (default), queue behind the turn, or force in place of the current tool round; an idle session starts a new generation."
+    usage: 'session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
+    description: "Prompt a session: steer into the current turn after the next tool result (default), queue behind the turn, or force in place of the current tool round; an idle session starts a new generation. Use steer for active-session coordination; queue only deliberately deferred work. --sender adds an optional title above the message."
   },
   {
     section: "sessions",
@@ -714,15 +717,24 @@ function parseSessionRunCommand(options, args) {
     return { kind: subcommand, sessionId };
   }
   if (subcommand === "prompt") {
-    const parsed = parseCommandOperands(commandArgs, /* @__PURE__ */ new Set(["--worker", "--mode", "--model", "--delivery"]), /* @__PURE__ */ new Map(), "session prompt", 1);
+    const parsed = parseCommandOperands(
+      commandArgs,
+      /* @__PURE__ */ new Set(["--worker", "--mode", "--model", "--delivery", "--sender"]),
+      /* @__PURE__ */ new Map(),
+      "session prompt",
+      1
+    );
     const sessionId = requireValue(parsed.positionals[0], "Session id is required for `session prompt`");
     const prompt = parsed.positionals.slice(1).join(" ").trim();
     if (!prompt) throw new Error("Prompt is required for `session prompt`");
+    const sender = parsed.values.get("--sender")?.trim();
+    if (sender !== void 0 && !sender) throw new Error("--sender must not be empty");
     return {
       kind: "prompt",
       worker: requireWorker(parsed.values),
       sessionId,
       prompt,
+      ...sender ? { sender } : {},
       mode: requireSessionMode(parsed.values.get("--mode")),
       model: requireModel(parsed.values.get("--model")),
       delivery: parsePromptDelivery(parsed.values.get("--delivery"))
@@ -2085,7 +2097,7 @@ function renderSessionRunStatus(session) {
   const summary = responseString(session, "summary");
   if (summary) lines.push("", summary);
   const sessionId = responseString(session, "sessionId");
-  if (sessionId && ["provisioning", "queued", "running"].includes(status)) {
+  if (sessionId && ["provisioning", "queued", "running", "waiting"].includes(status)) {
     lines.push("", "Next:", `  r5dctl session status ${sessionId}`, `  r5dctl session stop ${sessionId}`);
   }
   return `${lines.join("\n")}
@@ -2122,7 +2134,8 @@ async function dispatchSessionRunCommand(client, command) {
       mode: command.mode,
       model: command.model,
       requestId: randomUUID(),
-      delivery: command.delivery
+      delivery: command.delivery,
+      ...command.sender ? { sender: command.sender } : {}
     });
     return { data: data2, human: renderSessionRunStatus(data2) };
   }

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "type": "module"
 }

package/dist/types/cli.d.ts

@@ -73,6 +73,7 @@ export type R5dctlSessionRunCommand = R5dctlSessionStartCommand | {
     worker: string;
     sessionId: string;
     prompt: string;
+    sender?: string;
     mode: R5dctlSessionMode;
     model: ModelTier;
     delivery: R5dctlPromptDelivery;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "type": "module",
   "main": "./dist/cjs/cli.cjs",
   "module": "./dist/mjs/cli.mjs",
@@ -26,7 +26,7 @@
     "r5dctl": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.107",
+    "@ricsam/r5d-api": "^0.0.108",
     "dotenv": "^17",
     "qrcode": "^1.5.4",
     "ws": "^8.18.3"