@ricsam/r5dctl 0.0.27 → 0.0.28

package/README.md

@@ -63,6 +63,10 @@ r5dctl -s <session-id> conversation --raw              # raw JSON message/tool p
 r5dctl -s <session-id> conversation --tools            # include provider-shaped tool definitions
 r5dctl -s <session-id> conversation --system           # include system prompt messages
 r5dctl -s <session-id> conversation --raw --tools --system  # exact raw agent request transcript
+r5dctl conversation overview <session-id>               # dialogue/thinking with tool work omitted
+r5dctl conversation inspect-work <session-id> <work-id> # compact call list for one omitted turn
+r5dctl conversation inspect-work <session-id> <work-id> --summary
+r5dctl conversation inspect-work <session-id> <work-id> --full
 r5dctl -s <session-id> prompt --mode plan --model max "..."
 r5dctl -s <session-id> answer-questions -a1 "Recipe Collection" -a2 "Both Manual & AI"
 r5dctl -s <session-id> apply-required-envs -e KEY=value
@@ -86,6 +90,8 @@ Conversation output is human-readable by default and excludes both the system pr
 
 When available, conversation rendering uses the newest complete persisted model-request snapshot on the active conversation branch, so its mode, tier, model, thinking mode, tools, and messages reflect the request that actually ran. Legacy or empty sessions without snapshots fall back to reconstruction from the latest conversation context.
 
+`conversation overview` is a deterministic active-branch projection for continuing work in another session. It keeps user messages, injected context, assistant thinking/commentary/final responses, and user decisions, while replacing each turn's tool batches with a stable work ID and numbered call ranges. Use `conversation inspect-work` with that session and work ID to inspect the omitted calls. Inspection is compact by default; `--summary` adds bounded targets/outcomes and `--full` renders persisted inputs and results with the normal tool renderers. The explicit `--compact`, `--summary`, and `--full` flags are mutually exclusive. Compact and summary output are designed to be narrowed with `grep`, `head`, `tail`, `sed`, or `cat -n`.
+
 Project mode is derived from the persisted `backwardsCompatible` project setting:
 
 - `greenfield`: agent can make breaking/reset-style changes

package/dist/cjs/cli.cjs

@@ -34,6 +34,7 @@ __export(cli_exports, {
   main: () => main,
   parseAnswerFlags: () => parseAnswerFlags,
   parseConversationRenderArgs: () => parseConversationRenderArgs,
+  parseConversationWorkDetailArgs: () => parseConversationWorkDetailArgs,
   parseEnvFlags: () => parseEnvFlags,
   parseGlobalArgs: () => parseGlobalArgs,
   parsePromptArgs: () => parsePromptArgs,
@@ -41,7 +42,9 @@ __export(cli_exports, {
   parseSetEnvArgs: () => parseSetEnvArgs,
   parseShellArgs: () => parseShellArgs,
   readDotenvFile: () => readDotenvFile,
+  renderConversationOverviewResponse: () => renderConversationOverviewResponse,
   renderConversationResponse: () => renderConversationResponse,
+  renderConversationWorkResponse: () => renderConversationWorkResponse,
   renderProcessList: () => renderProcessList,
   resolveCommandExecution: () => resolveCommandExecution,
   runR5dctlCli: () => runR5dctlCli,
@@ -163,6 +166,16 @@ const SHARED_HELP_ENTRIES = [
     usage: "-s <session-id> conversation [--raw] [--tools] [--system]",
     description: "Read the agent request transcript in human-readable form."
   },
+  {
+    section: "sessions",
+    usage: "conversation overview <session-id>",
+    description: "Read dialogue and thinking while replacing tool work with inspectable ranges."
+  },
+  {
+    section: "sessions",
+    usage: "conversation inspect-work <session-id> <work-id> [--compact|--summary|--full]",
+    description: "Inspect one turn's omitted tool work at the selected detail."
+  },
   {
     section: "sessions",
     usage: '-s <session-id> prompt --mode <mode> --model <tier> "<message>"',
@@ -316,10 +329,12 @@ function renderCliOnlyCommandHelp(entry) {
 `;
 }
 function renderSharedCommandHelp(pathSegments) {
-  const entry = SHARED_HELP_ENTRIES.find((candidate) => {
-    const usageSegments = candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
-    return usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index]);
-  });
+  const entry = SHARED_HELP_ENTRIES.map((candidate) => ({
+    candidate,
+    usageSegments: candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["))
+  })).filter(
+    ({ usageSegments }) => usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index])
+  ).sort((left, right) => right.usageSegments.length - left.usageSegments.length)[0]?.candidate;
   if (!entry) {
     return void 0;
   }
@@ -1206,6 +1221,30 @@ function renderConversationResponse(read) {
   return read.agentText.endsWith("\n") ? read.agentText : `${read.agentText}
 `;
 }
+function parseConversationWorkDetailArgs(args) {
+  let detail = "compact";
+  let selected = false;
+  for (const arg of args) {
+    const candidate = arg === "--compact" ? "compact" : arg === "--summary" ? "summary" : arg === "--full" ? "full" : void 0;
+    if (!candidate) {
+      throw new Error(`Unknown inspect-work argument: ${arg}`);
+    }
+    if (selected) {
+      throw new Error("Use only one of --compact, --summary, or --full");
+    }
+    detail = candidate;
+    selected = true;
+  }
+  return detail;
+}
+function renderConversationOverviewResponse(read) {
+  return read.overviewText.endsWith("\n") ? read.overviewText : `${read.overviewText}
+`;
+}
+function renderConversationWorkResponse(read) {
+  return read.workText.endsWith("\n") ? read.workText : `${read.workText}
+`;
+}
 async function executeR5dctlCommand(client, json, args) {
   const write = (data, human) => writeDataOutput(json, data, human);
   const [first, second, third] = args;
@@ -1394,6 +1433,22 @@ ${result.message}
     write(result, "Session deleted.\n");
     return;
   }
+  if (first === "conversation" && second === "overview") {
+    if (args.length > 3) {
+      throw new Error(`Unexpected conversation overview argument: ${args[3]}`);
+    }
+    const read = await client.sessions.conversationOverview(requireValue(args[2], "Missing session id"));
+    write(read, renderConversationOverviewResponse(read));
+    return;
+  }
+  if (first === "conversation" && second === "inspect-work") {
+    const sessionId = requireValue(args[2], "Missing session id");
+    const workId = requireValue(args[3], "Missing work id");
+    const detail = parseConversationWorkDetailArgs(args.slice(4));
+    const read = await client.sessions.inspectConversationWork(sessionId, workId, { detail });
+    write(read, renderConversationWorkResponse(read));
+    return;
+  }
   if (first === "sessions" && second === "conversation" || first === "conversation") {
     const offset = first === "conversation" ? 1 : 2;
     const renderOptions = parseConversationRenderArgs(args.slice(offset + 1));
@@ -1716,6 +1771,33 @@ function resolveCommandExecution(options, rest) {
     throw new Error("Unknown delete command");
   }
   if (command === "conversation") {
+    const subcommand = commandArgs[0];
+    if (subcommand === "overview") {
+      const sessionId2 = options.session ?? commandArgs[1];
+      if (!sessionId2) {
+        throw new Error("Session id is required for `conversation overview`");
+      }
+      const remainingArgs = options.session ? commandArgs.slice(1) : commandArgs.slice(2);
+      return {
+        kind: "plugin",
+        pluginArgs: ["conversation", "overview", sessionId2, ...remainingArgs]
+      };
+    }
+    if (subcommand === "inspect-work") {
+      const sessionId2 = options.session ?? commandArgs[1];
+      if (!sessionId2) {
+        throw new Error("Session id is required for `conversation inspect-work`");
+      }
+      const workId = options.session ? commandArgs[1] : commandArgs[2];
+      if (!workId) {
+        throw new Error("Work id is required for `conversation inspect-work`");
+      }
+      const remainingArgs = options.session ? commandArgs.slice(2) : commandArgs.slice(3);
+      return {
+        kind: "plugin",
+        pluginArgs: ["conversation", "inspect-work", sessionId2, workId, ...remainingArgs]
+      };
+    }
     const sessionId = options.session;
     if (!sessionId) {
       throw new Error("--session/-s is required for `conversation`");
@@ -1938,6 +2020,7 @@ async function main(argv = process.argv.slice(2)) {
   main,
   parseAnswerFlags,
   parseConversationRenderArgs,
+  parseConversationWorkDetailArgs,
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
@@ -1945,7 +2028,9 @@ async function main(argv = process.argv.slice(2)) {
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
+  renderConversationOverviewResponse,
   renderConversationResponse,
+  renderConversationWorkResponse,
   renderProcessList,
   resolveCommandExecution,
   runR5dctlCli,

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -116,6 +116,16 @@ const SHARED_HELP_ENTRIES = [
     usage: "-s <session-id> conversation [--raw] [--tools] [--system]",
     description: "Read the agent request transcript in human-readable form."
   },
+  {
+    section: "sessions",
+    usage: "conversation overview <session-id>",
+    description: "Read dialogue and thinking while replacing tool work with inspectable ranges."
+  },
+  {
+    section: "sessions",
+    usage: "conversation inspect-work <session-id> <work-id> [--compact|--summary|--full]",
+    description: "Inspect one turn's omitted tool work at the selected detail."
+  },
   {
     section: "sessions",
     usage: '-s <session-id> prompt --mode <mode> --model <tier> "<message>"',
@@ -269,10 +279,12 @@ function renderCliOnlyCommandHelp(entry) {
 `;
 }
 function renderSharedCommandHelp(pathSegments) {
-  const entry = SHARED_HELP_ENTRIES.find((candidate) => {
-    const usageSegments = candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
-    return usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index]);
-  });
+  const entry = SHARED_HELP_ENTRIES.map((candidate) => ({
+    candidate,
+    usageSegments: candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["))
+  })).filter(
+    ({ usageSegments }) => usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index])
+  ).sort((left, right) => right.usageSegments.length - left.usageSegments.length)[0]?.candidate;
   if (!entry) {
     return void 0;
   }
@@ -1159,6 +1171,30 @@ function renderConversationResponse(read) {
   return read.agentText.endsWith("\n") ? read.agentText : `${read.agentText}
 `;
 }
+function parseConversationWorkDetailArgs(args) {
+  let detail = "compact";
+  let selected = false;
+  for (const arg of args) {
+    const candidate = arg === "--compact" ? "compact" : arg === "--summary" ? "summary" : arg === "--full" ? "full" : void 0;
+    if (!candidate) {
+      throw new Error(`Unknown inspect-work argument: ${arg}`);
+    }
+    if (selected) {
+      throw new Error("Use only one of --compact, --summary, or --full");
+    }
+    detail = candidate;
+    selected = true;
+  }
+  return detail;
+}
+function renderConversationOverviewResponse(read) {
+  return read.overviewText.endsWith("\n") ? read.overviewText : `${read.overviewText}
+`;
+}
+function renderConversationWorkResponse(read) {
+  return read.workText.endsWith("\n") ? read.workText : `${read.workText}
+`;
+}
 async function executeR5dctlCommand(client, json, args) {
   const write = (data, human) => writeDataOutput(json, data, human);
   const [first, second, third] = args;
@@ -1347,6 +1383,22 @@ ${result.message}
     write(result, "Session deleted.\n");
     return;
   }
+  if (first === "conversation" && second === "overview") {
+    if (args.length > 3) {
+      throw new Error(`Unexpected conversation overview argument: ${args[3]}`);
+    }
+    const read = await client.sessions.conversationOverview(requireValue(args[2], "Missing session id"));
+    write(read, renderConversationOverviewResponse(read));
+    return;
+  }
+  if (first === "conversation" && second === "inspect-work") {
+    const sessionId = requireValue(args[2], "Missing session id");
+    const workId = requireValue(args[3], "Missing work id");
+    const detail = parseConversationWorkDetailArgs(args.slice(4));
+    const read = await client.sessions.inspectConversationWork(sessionId, workId, { detail });
+    write(read, renderConversationWorkResponse(read));
+    return;
+  }
   if (first === "sessions" && second === "conversation" || first === "conversation") {
     const offset = first === "conversation" ? 1 : 2;
     const renderOptions = parseConversationRenderArgs(args.slice(offset + 1));
@@ -1669,6 +1721,33 @@ function resolveCommandExecution(options, rest) {
     throw new Error("Unknown delete command");
   }
   if (command === "conversation") {
+    const subcommand = commandArgs[0];
+    if (subcommand === "overview") {
+      const sessionId2 = options.session ?? commandArgs[1];
+      if (!sessionId2) {
+        throw new Error("Session id is required for `conversation overview`");
+      }
+      const remainingArgs = options.session ? commandArgs.slice(1) : commandArgs.slice(2);
+      return {
+        kind: "plugin",
+        pluginArgs: ["conversation", "overview", sessionId2, ...remainingArgs]
+      };
+    }
+    if (subcommand === "inspect-work") {
+      const sessionId2 = options.session ?? commandArgs[1];
+      if (!sessionId2) {
+        throw new Error("Session id is required for `conversation inspect-work`");
+      }
+      const workId = options.session ? commandArgs[1] : commandArgs[2];
+      if (!workId) {
+        throw new Error("Work id is required for `conversation inspect-work`");
+      }
+      const remainingArgs = options.session ? commandArgs.slice(2) : commandArgs.slice(3);
+      return {
+        kind: "plugin",
+        pluginArgs: ["conversation", "inspect-work", sessionId2, workId, ...remainingArgs]
+      };
+    }
     const sessionId = options.session;
     if (!sessionId) {
       throw new Error("--session/-s is required for `conversation`");
@@ -1890,6 +1969,7 @@ export {
   main,
   parseAnswerFlags,
   parseConversationRenderArgs,
+  parseConversationWorkDetailArgs,
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
@@ -1897,7 +1977,9 @@ export {
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
+  renderConversationOverviewResponse,
   renderConversationResponse,
+  renderConversationWorkResponse,
   renderProcessList,
   resolveCommandExecution,
   runR5dctlCli,

package/dist/mjs/package.json

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

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlEnvData, type R5dctlProcessListInput, type R5dctlProcessRun, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlProcessListInput, type R5dctlProcessRun, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -71,6 +71,9 @@ export type EnvSummaryData = Record<string, {
 export declare function summarizeEnvData(data: R5dctlEnvData): EnvSummaryData;
 export declare function parseConversationRenderArgs(args: string[]): ConversationRenderOptions;
 export declare function renderConversationResponse(read: R5dctlConversationResponse): string;
+export declare function parseConversationWorkDetailArgs(args: string[]): R5dctlConversationWorkDetail;
+export declare function renderConversationOverviewResponse(read: R5dctlConversationOverviewResponse): string;
+export declare function renderConversationWorkResponse(read: R5dctlConversationWorkResponse): string;
 export declare function resolveCommandExecution(options: GlobalOptions, rest: string[]): CommandExecutionPlan;
 export declare function runR5dctlCli(argv: string[]): Promise<number>;
 export declare function main(argv?: string[]): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "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.27",
+    "@ricsam/r5d-api": "^0.0.28",
     "dotenv": "^17",
     "ws": "^8.18.3"
   },