@ricsam/r5dctl 0.0.106 → 0.0.108

package/README.md

@@ -87,6 +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 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"
 
@@ -94,7 +95,8 @@ 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
 r5dctl session process-log <run-id> --grep "error|failed"
@@ -129,7 +131,15 @@ pull requests.
 
 `get branches` lists every branch the project knows about, including managed branches without sessions. A worker whose workspace sync found a configured branch's checkout directory missing, or present but not a linked worktree of the project, skips that branch and reports it; the listing then shows `checkout=missing on <worker>` or `checkout=not_a_worktree on <worker>`, and `workspace status` prints a `Missing checkouts on <worker>` line. Recover either by deleting the branch with `delete branch <branch> --confirm` or by reconnecting that worker, which recreates the checkout without snapshotting the project's other checkouts.
 
-`session start` creates an ordinary agent-mode chat on an explicitly selected existing worktree, or creates a named linked worktree from an explicit `worktree:<branch>` source. A new worktree is cut from the source branch's current commit; `--working-tree carry` (the default, `git switch -c` semantics) also copies the source checkout's uncommitted changes into it, while `--working-tree clean` checks out that commit only. The new session's first message states which mode applies, and the start output prints `Source` and `Working tree` lines. A clean request fails with a clear error when the selected worker predates the option, because such a worker would silently carry instead. It requires project, worker, model, and prompt and never infers them from the current shell. Start returns a durable `provisioning` handle immediately; workspace synchronization, linked-worktree creation, and prompt enqueue continue in the background and are visible through `session status`. Idempotent request retries return the same handle. Prompts return after durable enqueue. Task specialization belongs in the prompt; there are no predefined debug, explore, research, or test agents. `session stop` returns as soon as the agent run is stopped; the stopped worktree's workspace Git synchronization finishes asynchronously behind the response.
+`session start` creates an ordinary agent-mode chat on an explicitly selected existing worktree, or creates a named linked worktree from an explicit `worktree:<branch>` source. A new worktree is cut from the source branch's current commit; `--working-tree carry` (the default, `git switch -c` semantics) also copies the source checkout's uncommitted changes into it, while `--working-tree clean` checks out that commit only. The new session's first message states which mode applies, and the start output prints `Source` and `Working tree` lines. A clean request fails with a clear error when the selected worker predates the option, because such a worker would silently carry instead. It requires project, worker, model, and prompt and never infers them from the current shell. Start returns a durable `provisioning` handle immediately; workspace synchronization, linked-worktree creation, and prompt enqueue continue in the background and are visible through `session status`. Idempotent request retries return the same handle. Prompts return after durable enqueue. Task specialization belongs in the prompt; there are no predefined debug, explore, research, or test agents.
+
+`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.
 

package/dist/cjs/cli.cjs

@@ -113,6 +113,8 @@ var import_r5d_api = require("@ricsam/r5d-api");
 var import_shell = require("./shell.cjs");
 const CHAT_MODES = /* @__PURE__ */ new Set(["plan", "agent", "large_diff_remediation"]);
 const R5DCTL_SESSION_MODES = /* @__PURE__ */ new Set(["plan", "agent"]);
+const R5DCTL_PROMPT_DELIVERIES = /* @__PURE__ */ new Set(["queue", "steer", "force"]);
+const R5DCTL_PROMPT_DEFAULT_DELIVERY = "steer";
 const MODEL_TIERS = /* @__PURE__ */ new Set(["low", "medium", "high", "max"]);
 const R5DCTL_PACKAGE_NAME = "@ricsam/r5dctl";
 const CLI_GLOBAL_OPTION_HELP = [
@@ -175,11 +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> <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.",
@@ -309,8 +316,8 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: 'session prompt --worker <label> --mode <mode> --model <tier> <session-id> "<prompt>"',
-    description: "Queue a prompt or start a new session 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",
@@ -603,6 +610,14 @@ function requireSessionMode(value) {
   }
   return mode;
 }
+function parsePromptDelivery(value) {
+  if (value === void 0) return R5DCTL_PROMPT_DEFAULT_DELIVERY;
+  const delivery = value.trim();
+  if (!R5DCTL_PROMPT_DELIVERIES.has(delivery)) {
+    throw new Error("Invalid --delivery. Expected one of: queue, steer, force");
+  }
+  return delivery;
+}
 function parseBranchCreateArgs(args) {
   const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--source", "--working-tree", "--worker"]), /* @__PURE__ */ new Map(), "create branch", 1);
   if (parsed.positionals.length > 0) throw new Error(`Unexpected create branch argument: ${parsed.positionals[0]}`);
@@ -802,17 +817,27 @@ function parseSessionRunCommand(options, args) {
     return { kind: subcommand, sessionId };
   }
   if (subcommand === "prompt") {
-    const parsed = parseCommandOperands(commandArgs, /* @__PURE__ */ new Set(["--worker", "--mode", "--model"]), /* @__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"))
+      model: requireModel(parsed.values.get("--model")),
+      delivery: parsePromptDelivery(parsed.values.get("--delivery"))
     };
   }
   throw new Error(`Unknown session command: ${subcommand}`);
@@ -2172,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")}
@@ -2208,7 +2233,9 @@ async function dispatchSessionRunCommand(client, command) {
       worker: command.worker,
       mode: command.mode,
       model: command.model,
-      requestId: (0, import_node_crypto.randomUUID)()
+      requestId: (0, import_node_crypto.randomUUID)(),
+      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.106",
+  "version": "0.0.108",
   "type": "commonjs"
 }

package/dist/mjs/cli.mjs

@@ -13,6 +13,8 @@ import {
 import { runR5dctlShell } from "./shell.mjs";
 const CHAT_MODES = /* @__PURE__ */ new Set(["plan", "agent", "large_diff_remediation"]);
 const R5DCTL_SESSION_MODES = /* @__PURE__ */ new Set(["plan", "agent"]);
+const R5DCTL_PROMPT_DELIVERIES = /* @__PURE__ */ new Set(["queue", "steer", "force"]);
+const R5DCTL_PROMPT_DEFAULT_DELIVERY = "steer";
 const MODEL_TIERS = /* @__PURE__ */ new Set(["low", "medium", "high", "max"]);
 const R5DCTL_PACKAGE_NAME = "@ricsam/r5dctl";
 const CLI_GLOBAL_OPTION_HELP = [
@@ -75,11 +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> <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.",
@@ -209,8 +216,8 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: 'session prompt --worker <label> --mode <mode> --model <tier> <session-id> "<prompt>"',
-    description: "Queue a prompt or start a new session 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",
@@ -503,6 +510,14 @@ function requireSessionMode(value) {
   }
   return mode;
 }
+function parsePromptDelivery(value) {
+  if (value === void 0) return R5DCTL_PROMPT_DEFAULT_DELIVERY;
+  const delivery = value.trim();
+  if (!R5DCTL_PROMPT_DELIVERIES.has(delivery)) {
+    throw new Error("Invalid --delivery. Expected one of: queue, steer, force");
+  }
+  return delivery;
+}
 function parseBranchCreateArgs(args) {
   const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--source", "--working-tree", "--worker"]), /* @__PURE__ */ new Map(), "create branch", 1);
   if (parsed.positionals.length > 0) throw new Error(`Unexpected create branch argument: ${parsed.positionals[0]}`);
@@ -702,17 +717,27 @@ function parseSessionRunCommand(options, args) {
     return { kind: subcommand, sessionId };
   }
   if (subcommand === "prompt") {
-    const parsed = parseCommandOperands(commandArgs, /* @__PURE__ */ new Set(["--worker", "--mode", "--model"]), /* @__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"))
+      model: requireModel(parsed.values.get("--model")),
+      delivery: parsePromptDelivery(parsed.values.get("--delivery"))
     };
   }
   throw new Error(`Unknown session command: ${subcommand}`);
@@ -2072,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")}
@@ -2108,7 +2133,9 @@ async function dispatchSessionRunCommand(client, command) {
       worker: command.worker,
       mode: command.mode,
       model: command.model,
-      requestId: randomUUID()
+      requestId: randomUUID(),
+      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.106",
+  "version": "0.0.108",
   "type": "module"
 }

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { R5dctlApiError, R5dctlClient, type R5dctlConversationForkResponse, type R5dctlConversationHeadResponse, type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessLog, type R5dctlProcessRun, type R5dctlBranch, type R5dctlBranchDeleteResponse, type R5dctlBranchDescription, type R5dctlBranchOperation, type R5dctlSessionSummary, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorkingTreeMode, type R5dctlWorktreeSource, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { R5dctlApiError, R5dctlClient, type R5dctlConversationForkResponse, type R5dctlConversationHeadResponse, type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessLog, type R5dctlProcessRun, type R5dctlBranch, type R5dctlBranchDeleteResponse, type R5dctlBranchDescription, type R5dctlBranchOperation, type R5dctlSessionSummary, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorkingTreeMode, type R5dctlWorktreeSource, type R5dctlPromptDelivery, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -73,8 +73,10 @@ export type R5dctlSessionRunCommand = R5dctlSessionStartCommand | {
     worker: string;
     sessionId: string;
     prompt: string;
+    sender?: string;
     mode: R5dctlSessionMode;
     model: ModelTier;
+    delivery: R5dctlPromptDelivery;
 } | {
     kind: "stop";
     sessionId: string;
@@ -305,6 +307,7 @@ export type R5dctlSessionRunClient = {
             mode: R5dctlSessionMode;
             model: ModelTier;
             requestId: string;
+            delivery?: R5dctlPromptDelivery;
         }) => Promise<R5dctlCommandResponse>;
         stop: (sessionId: string) => Promise<R5dctlCommandResponse>;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.106",
+  "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.106",
+    "@ricsam/r5d-api": "^0.0.108",
     "dotenv": "^17",
     "qrcode": "^1.5.4",
     "ws": "^8.18.3"