feat: add --session-id and JSON output support in exec mode

Author: qorzj

packages/cli/src/cli-args.ts

@@ -8,22 +8,19 @@ import Yargs from "yargs";
 import { getCliVersion } from "./utils/version";
 import { writeStderrLine } from "./utils/stdio-helpers";
 import { hideBin } from "yargs/helpers";
+import { isValidSessionId } from "@vegamo/deepcode-core";
 
-// UUID v4 regex pattern for validation
-const SESSION_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
-/**
- * Validates if a string is a valid session ID format.
- */
-export function isValidSessionId(value: string): boolean {
-  return SESSION_ID_REGEX.test(value);
-}
+export { isValidSessionId };
 
 export interface ParsedCliArgs {
   /** Prompt text from -p / --prompt */
   prompt: string | undefined;
   /** Run one prompt without starting the interactive TUI. */
   exec: boolean;
+  /** UUID to use when creating a new session in exec mode. */
+  sessionId: string | undefined;
+  /** Output the final assistant message as a single JSON object. */
+  json: boolean;
   /**
    * Resume session identifier:
    *   - `undefined` — --resume was not used
@@ -100,6 +97,16 @@ async function configureYargs(argv?: string[]) {
           type: "string",
           describe: "Resume a specific session by its ID. Use without an ID to show session picker.",
         })
+        .option("session-id", {
+          type: "string",
+          requiresArg: true,
+          describe: "Adopt the persisted Session with this id",
+        })
+        .option("json", {
+          type: "boolean",
+          default: false,
+          describe: "Output a single JSON object instead of human-readable text.",
+        })
         .option("fork", {
           alias: "f",
           type: "string",
@@ -116,6 +123,18 @@ async function configureYargs(argv?: string[]) {
           const hasPositionalQuery = Array.isArray(query) ? query.length > 0 : !!query;
           const prompt = argv["prompt"] as string | undefined;
           const exec = argv["exec"] === true;
+          const sessionId = argv["session-id"] as string | undefined;
+
+          if (sessionId !== undefined) {
+            if (!exec) return "--session-id requires --exec / -x.";
+            if (argv["resume"] !== undefined || argv["fork"] !== undefined || argv["last"] === true) {
+              return "Cannot use --session-id together with --resume, --fork, or --last.";
+            }
+            if (!isValidSessionId(sessionId)) {
+              return `Invalid session ID: "${sessionId}". Must be a valid UUID.`;
+            }
+          }
+          if (argv["json"] === true && !exec) return "--json requires --exec / -x.";
 
           if (prompt && hasPositionalQuery) {
             return "Cannot use both a positional prompt and the --prompt (-p) flag together";
@@ -212,6 +231,8 @@ export async function parseArguments(argv?: string[]): Promise<ParsedCliArgs> {
   return {
     prompt: parsed.prompt as string | undefined,
     exec: parsed.exec === true,
+    sessionId: (parsed["session-id"] as string | undefined)?.toLowerCase(),
+    json: parsed.json === true,
     resume,
     fork,
     version: parsed.version === true,

packages/cli/src/cli.tsx

@@ -74,6 +74,8 @@ async function main(): Promise<void> {
     process.exitCode = await runExecMode({
       prompt: parsed.prompt!,
       projectRoot,
+      sessionId: parsed.sessionId,
+      json: parsed.json,
       resumeSessionId: typeof resumeSessionId === "string" ? resumeSessionId : undefined,
       forkSessionId: typeof forkSessionId === "string" ? forkSessionId : undefined,
     });

packages/cli/src/exec-runner.ts

@@ -6,9 +6,11 @@ import {
   type AskPermissionScope,
   type PermissionSettings,
   type SessionManagerOptions,
+  type SessionMessage,
 } from "@vegamo/deepcode-core";
 import { buildExecPrompt, type ExecInputStream } from "./exec-input";
 import { writeStderrLine, writeStdoutLine } from "./utils/stdio-helpers";
+import { formatSessionMessageJson } from "./session-message-json";
 
 type ExecSessionManager = Pick<
   SessionManager,
@@ -30,6 +32,8 @@ interface SignalTarget {
 export interface ExecRunnerOptions {
   prompt: string;
   projectRoot: string;
+  sessionId?: string;
+  json?: boolean;
   resumeSessionId?: string;
   forkSessionId?: string;
   input?: ExecInputStream;
@@ -61,6 +65,7 @@ export async function runExecMode(
   const deps = { ...defaultDependencies, ...dependencies };
   let manager: ExecSessionManager | null = null;
   let interrupted = false;
+  const result: { message?: SessionMessage } = {};
 
   const handleSigint = (): void => {
     interrupted = true;
@@ -76,7 +81,10 @@ export async function runExecMode(
       getResolvedSettings: () => deps.resolveSettings(options.projectRoot),
       renderMarkdown: (text) => text,
       nonInteractive: true,
-      onAssistantMessage: () => {},
+      onAssistantMessage: (message, shouldConnect) => {
+        // Ignore transient notices and tool messages; retain model responses.
+        if (shouldConnect && message.role === "assistant") result.message = message;
+      },
     });
 
     await manager.initMcpServers(settings.mcpServers);
@@ -108,7 +116,7 @@ export async function runExecMode(
       manager.setActiveSessionId(options.resumeSessionId);
     }
 
-    await manager.handleUserPrompt({ text: prompt });
+    await manager.handleUserPrompt({ text: prompt }, { sessionId: options.sessionId });
     const sessionId = manager.getActiveSessionId();
     const session = sessionId ? manager.getSession(sessionId) : null;
 
@@ -137,7 +145,15 @@ export async function runExecMode(
       return 1;
     }
 
-    deps.writeStdoutLine(session.assistantReply ?? "");
+    if (options.json) {
+      if (!result.message || result.message.sessionId !== sessionId) {
+        deps.writeStderrLine("Execution completed without a final assistant message.");
+        return 1;
+      }
+      deps.writeStdoutLine(formatSessionMessageJson(result.message));
+    } else {
+      deps.writeStdoutLine(session.assistantReply ?? "");
+    }
     return 0;
   } catch (error) {
     if (interrupted) {

packages/cli/src/session-message-json.ts

@@ -0,0 +1,20 @@
+import type { SessionMessage } from "@vegamo/deepcode-core";
+
+export function formatSessionMessageJson(message: SessionMessage): string {
+  return JSON.stringify(omitEmptyValues(message));
+}
+
+function omitEmptyValues(value: unknown): unknown {
+  if (value === null || value === undefined || value === "") return undefined;
+  if (Array.isArray(value)) {
+    const items = value.map(omitEmptyValues).filter((item) => item !== undefined);
+    return items.length ? items : undefined;
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value)
+      .map(([key, item]) => [key, omitEmptyValues(item)] as const)
+      .filter(([, item]) => item !== undefined);
+    return entries.length ? Object.fromEntries(entries) : undefined;
+  }
+  return value;
+}

packages/cli/src/tests/cli-args.test.ts

@@ -21,7 +21,63 @@ test("parseArguments returns prompt after -p", async () => {
   assert.ok(!("message" in r));
   assert.equal(r.prompt, "hello world");
   assert.equal(r.exec, false);
-});
+  assert.equal(r.sessionId, undefined);
+  assert.equal(r.json, false);
+});
+
+test("parseArguments accepts a custom UUID and JSON output in exec mode", async () => {
+  const id = "0A5CB7A5-C39D-4C39-A11B-05F8B22B8DF6";
+  const parsed = await parseArguments(["--exec", "--prompt", "hello", "--session-id", id, "--json"]);
+  assert.equal(parsed.sessionId, id.toLowerCase());
+  assert.equal(parsed.json, true);
+});
+
+test("isValidSessionId accepts standard UUID versions and rejects invalid variants", () => {
+  for (let version = 1; version <= 8; version++) {
+    assert.ok(isValidSessionId(`0a5cb7a5-c39d-${version}c39-a11b-05f8b22b8df6`));
+  }
+  assert.ok(isValidSessionId("00000000-0000-0000-0000-000000000000"));
+  assert.ok(isValidSessionId("ffffffff-ffff-ffff-ffff-ffffffffffff"));
+  assert.ok(!isValidSessionId("0a5cb7a5-c39d-4c39-711b-05f8b22b8df6"));
+  assert.ok(!isValidSessionId("0a5cb7a5-c39d-9c39-a11b-05f8b22b8df6"));
+});
+
+for (const flags of [
+  ["--resume", "0a5cb7a5-c39d-4c39-a11b-05f8b22b8df6"],
+  ["--fork", "0a5cb7a5-c39d-4c39-a11b-05f8b22b8df6"],
+  ["--fork"],
+  ["--last"],
+]) {
+  test(`parseArguments accepts --json with exec and ${flags.join(" ")}`, async () => {
+    const parsed = await parseArguments(["-x", "-p", "hello", "--json", ...flags]);
+    assert.equal(parsed.json, true);
+  });
+}
+
+for (const args of [
+  ["--session-id", "0a5cb7a5-c39d-4c39-a11b-05f8b22b8df6"],
+  ["--json"],
+  ["-x", "-p", "hello", "--session-id"],
+  ["-x", "-p", "hello", "--session-id", ""],
+  ["-x", "-p", "hello", "--session-id", "not-a-uuid"],
+  ["-x", "--json"],
+  ["-x", "--session-id", "0a5cb7a5-c39d-4c39-a11b-05f8b22b8df6"],
+  ...["-r", "--resume", "-f", "--fork", "-l", "--last"].map((flag) => [
+    "-x",
+    "-p",
+    "hello",
+    "--session-id",
+    "0a5cb7a5-c39d-4c39-a11b-05f8b22b8df6",
+    flag,
+  ]),
+]) {
+  test(`parseArguments rejects ${args.join(" ")}`, async () => {
+    await withMockedExit(async (exitSpy) => {
+      await assert.rejects(parseArguments(args), /process.exit\(1\)/);
+      assert.ok(exitSpy.calls.includes(1));
+    });
+  });
+}
 
 test("parseArguments enables exec mode with -x", async () => {
   const r = await parseArguments(["-x", "-p", "hello world"]);

packages/cli/src/tests/exec-runner.test.ts

@@ -5,6 +5,7 @@ import type {
   ResolvedDeepcodingSettings,
   SessionEntry,
   SessionManagerOptions,
+  SessionMessage,
   SessionStatus,
   UserPromptContent,
 } from "@vegamo/deepcode-core";
@@ -84,6 +85,7 @@ function pipedInput(content: string): ExecInputStream {
 type ManagerScenario = {
   finalStatus?: SessionStatus;
   finalReply?: string | null;
+  finalMessageParams?: unknown;
   failReason?: string | null;
   resumeExists?: boolean;
   throwFromPrompt?: Error;
@@ -127,10 +129,10 @@ function createHarness(scenario: ManagerScenario = {}) {
           entry = createEntry(activeId, "completed");
           return activeId;
         },
-        handleUserPrompt: async (prompt) => {
+        handleUserPrompt: async (prompt, promptOptions) => {
           submitted.push(prompt);
           if (scenario.throwFromPrompt) throw scenario.throwFromPrompt;
-          activeId ??= "new-session";
+          activeId ??= promptOptions?.sessionId ?? "new-session";
           options.onSessionEntryUpdated?.(createEntry(activeId, "processing"));
           options.onAssistantMessage(
             {
@@ -154,6 +156,21 @@ function createHarness(scenario: ManagerScenario = {}) {
             failReason: scenario.failReason ?? null,
             askPermissions: scenario.askPermissions,
           });
+          const finalMessage: SessionMessage = {
+            id: "final-message",
+            sessionId: activeId,
+            role: "assistant",
+            content: entry.assistantReply,
+            contentParams: null,
+            messageParams: scenario.finalMessageParams ?? null,
+            compacted: false,
+            visible: Boolean(entry.assistantReply),
+            createTime: entry.createTime,
+            updateTime: entry.updateTime,
+          };
+          options.onAssistantMessage(finalMessage, true);
+          options.onAssistantMessage({ ...finalMessage, id: "notice", content: "diagnostic" }, false);
+          options.onAssistantMessage({ ...finalMessage, id: "tool", role: "tool", content: "tool output" }, true);
           options.onSessionEntryUpdated?.(entry);
         },
         initMcpServers: async (servers) => {
@@ -224,6 +241,76 @@ test("runExecMode submits piped stdin in the persisted user prompt", async () =>
   assert.deepEqual(harness.stderr, []);
 });
 
+for (const sessionOptions of [
+  { sessionId: RESUME_ID },
+  { resumeSessionId: RESUME_ID },
+  { forkSessionId: RESUME_ID },
+  {},
+]) {
+  test(`runExecMode outputs only the final message as JSON with ${JSON.stringify(sessionOptions)}`, async () => {
+    const harness = createHarness({ resumeExists: true, finalMessageParams: { reasoning_content: "thoughts" } });
+    const code = await runExecMode(
+      { prompt: "task", projectRoot: "/tmp/project", input: ttyInput(), json: true, ...sessionOptions },
+      harness.dependencies
+    );
+    assert.equal(code, 0);
+    assert.equal(harness.stdout.length, 1);
+    assert.deepEqual(JSON.parse(harness.stdout[0]), {
+      id: "final-message",
+      sessionId: sessionOptions.forkSessionId
+        ? "forked-session"
+        : (sessionOptions.sessionId ?? sessionOptions.resumeSessionId ?? "new-session"),
+      role: "assistant",
+      content: "final answer",
+      messageParams: { reasoning_content: "thoughts" },
+      compacted: false,
+      visible: true,
+      createTime: "2026-01-01T00:00:00.000Z",
+      updateTime: "2026-01-01T00:00:00.000Z",
+    });
+    assert.deepEqual(harness.stderr, []);
+    assert.equal(harness.disposed, 1);
+  });
+}
+
+test("runExecMode outputs JSON even when the final message has no text", async () => {
+  const harness = createHarness({ finalReply: null });
+  const code = await runExecMode(
+    { prompt: "task", projectRoot: "/tmp/project", input: ttyInput(), json: true },
+    harness.dependencies
+  );
+  assert.equal(code, 0);
+  const message = JSON.parse(harness.stdout[0]);
+  assert.equal(message.id, "final-message");
+  assert.equal(message.visible, false);
+  assert.equal("content" in message, false);
+});
+
+for (const finalStatus of ["failed", "ask_permission", "waiting_for_user", "interrupted"] as const) {
+  test(`runExecMode keeps stderr diagnostics and exit status in JSON mode for ${finalStatus}`, async () => {
+    const harness = createHarness({ finalStatus });
+    const code = await runExecMode(
+      { prompt: "task", projectRoot: "/tmp/project", input: ttyInput(), json: true },
+      harness.dependencies
+    );
+    assert.equal(code, 1);
+    assert.deepEqual(harness.stdout, []);
+    assert.equal(harness.stderr.length, 1);
+    assert.equal(harness.disposed, 1);
+  });
+}
+
+test("runExecMode keeps stdout empty on SIGINT in JSON mode", async () => {
+  const harness = createHarness({ duringPrompt: () => harness.emitSigint() });
+  const code = await runExecMode(
+    { prompt: "task", projectRoot: "/tmp/project", input: ttyInput(), json: true },
+    harness.dependencies
+  );
+  assert.equal(code, 130);
+  assert.deepEqual(harness.stdout, []);
+  assert.equal(harness.disposed, 1);
+});
+
 test("runExecMode resumes a validated session before submitting", async () => {
   const harness = createHarness({ resumeExists: true, finalReply: "continued" });
   const code = await runExecMode(