@stigmer/cli 3.0.8

package/src/resources/run/env.ts

@@ -0,0 +1,167 @@
+// Runtime-environment assembly for agent execution.
+//
+// Ports the Go CLI's `internal/cli/envfile` package (parser.go + merge.go): it
+// parses `--env`/`--secret` flags and `--env-file`/`--secret-file` files into a
+// single merged map of runtime values, each tagged secret or plaintext.
+//
+// Precedence is load-order, lowest to highest (mirrors LoadAndMergeWithSecrets):
+//   env-files (in order) < secret-files (in order) < --env flags < --secret flags
+// so a later source overrides an earlier one on key collision, and a secret
+// source overriding a plaintext source flips the value to secret. This exact
+// ordering is a wire-parity contract with the Go CLI.
+
+import { readFileSync } from "node:fs";
+import type { EnvVarInput } from "@stigmer/sdk";
+import { UsageError } from "../../errors/index.js";
+
+/** A merged runtime environment: variable name -> value + secret flag. */
+export type RuntimeEnv = Record<string, EnvVarInput>;
+
+/** The four raw env sources collected from CLI flags, in precedence groups. */
+export interface EnvSources {
+  readonly envFlags: readonly string[];
+  readonly secretFlags: readonly string[];
+  readonly envFiles: readonly string[];
+  readonly secretFiles: readonly string[];
+}
+
+/**
+ * Load and merge every env source into one map. Mirrors Go's
+ * LoadAndMergeWithSecrets: files are processed before flags, and within each
+ * tier secrets are layered after plaintext, so the precedence is
+ * env-files < secret-files < --env < --secret (later wins).
+ */
+export function loadAndMergeEnv(sources: EnvSources): RuntimeEnv {
+  const layers: RuntimeEnv[] = [];
+  for (const path of sources.envFiles) layers.push(parseEnvFile(path, false));
+  for (const path of sources.secretFiles) layers.push(parseEnvFile(path, true));
+  if (sources.envFlags.length > 0) layers.push(parseEnvFlags(sources.envFlags, false));
+  if (sources.secretFlags.length > 0) layers.push(parseEnvFlags(sources.secretFlags, true));
+  return mergeEnv(layers);
+}
+
+// Later layers override earlier ones; mirrors Go's MergeEnvSources.
+function mergeEnv(layers: readonly RuntimeEnv[]): RuntimeEnv {
+  const result: RuntimeEnv = {};
+  for (const layer of layers) {
+    for (const [key, value] of Object.entries(layer)) result[key] = value;
+  }
+  return result;
+}
+
+// Parse a dotenv-style file: comments (#), blank lines, optional `export `
+// prefix, and quoted values with escapes. Every value carries the file's
+// secret tag. Mirrors Go's parseFileWithSecretFlag.
+function parseEnvFile(path: string, isSecret: boolean): RuntimeEnv {
+  let contents: string;
+  try {
+    contents = readFileSync(path, "utf8");
+  } catch (err) {
+    throw new UsageError(`failed to open environment file ${path}: ${(err as Error).message}`);
+  }
+
+  const result: RuntimeEnv = {};
+  const lines = contents.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const parsed = parseLine(lines[i]);
+    if (parsed === null) continue; // comment or blank
+    if (parsed instanceof Error) {
+      throw new UsageError(`${path}:${i + 1}: ${parsed.message}`);
+    }
+    result[parsed.key] = { value: parsed.value, isSecret };
+  }
+  return result;
+}
+
+// Parse repeated `KEY=VALUE` flag values. Unlike file parsing, a comment/blank
+// flag value is an error (the user explicitly passed it). Mirrors Go's
+// parseFlagsWithSecretFlag.
+function parseEnvFlags(vars: readonly string[], isSecret: boolean): RuntimeEnv {
+  const result: RuntimeEnv = {};
+  for (const raw of vars) {
+    const parsed = parseLine(raw);
+    if (parsed === null) {
+      throw new UsageError(`invalid environment variable "${raw}": empty or comment`);
+    }
+    if (parsed instanceof Error) {
+      throw new UsageError(`invalid environment variable "${raw}": ${parsed.message}`);
+    }
+    result[parsed.key] = { value: parsed.value, isSecret };
+  }
+  return result;
+}
+
+interface ParsedEntry {
+  readonly key: string;
+  readonly value: string;
+}
+
+// Parse one `KEY=VALUE` line. Returns null for comments/blanks, an Error for a
+// malformed entry, or the parsed pair. Mirrors Go's ParseLine.
+function parseLine(line: string): ParsedEntry | Error | null {
+  let trimmed = line.trim();
+  if (trimmed === "" || trimmed.startsWith("#")) return null;
+
+  if (trimmed.startsWith("export ")) trimmed = trimmed.slice("export ".length);
+
+  const eq = trimmed.indexOf("=");
+  if (eq === -1) return new Error("invalid format: missing '=' separator");
+
+  const key = trimmed.slice(0, eq).trim();
+  if (key === "") return new Error("empty key");
+  if (!isValidEnvKey(key)) {
+    return new Error(`invalid key "${key}": must contain only letters, numbers, and underscores`);
+  }
+
+  return { key, value: parseValue(trimmed.slice(eq + 1)) };
+}
+
+// First char a letter or underscore, rest alphanumeric/underscore. Mirrors Go's
+// isValidEnvKey (notably: a leading digit is rejected).
+function isValidEnvKey(key: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}
+
+// Trim, then strip matching single/double quotes and unescape. Mirrors Go's
+// parseValue + unescapeValue.
+function parseValue(raw: string): string {
+  const value = raw.trim();
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return unescapeValue(value.slice(1, -1));
+    }
+  }
+  return value;
+}
+
+// Escape map for the single-pass scan below.
+const ESCAPES: Readonly<Record<string, string>> = {
+  "\\": "\\",
+  '"': '"',
+  "'": "'",
+  n: "\n",
+  t: "\t",
+  r: "\r",
+};
+
+// Single-pass unescape, matching Go's strings.NewReplacer semantics: each `\x`
+// is consumed at most once (a chained string-replace would double-process, e.g.
+// turning a literal "\\n" into a newline). An unrecognized `\x` is left verbatim.
+function unescapeValue(value: string): string {
+  let out = "";
+  for (let i = 0; i < value.length; i++) {
+    if (value[i] === "\\" && i + 1 < value.length) {
+      const next = value[i + 1];
+      const mapped = ESCAPES[next];
+      if (mapped !== undefined) {
+        out += mapped;
+        i++;
+        continue;
+      }
+    }
+    out += value[i];
+  }
+  return out;
+}

package/src/resources/run/epilogue.ts

@@ -0,0 +1,166 @@
+// The post-stream epilogue, shared by every renderer (Go's streamAgentEpilogue +
+// run_display_summary.go). After the stream ends we fetch the authoritative final
+// execution and a usage report, then print a compact, copy-paste-friendly exit
+// summary to stderr (AI content already went to stdout). A stream that failed
+// before reaching a phase is re-raised as a CLI error.
+
+import { create } from "@bufbuild/protobuf";
+import { ExecutionPhase, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { GetExecutionUsageReportInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { UsageReportAggregate } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { CliExitError, ExitCode } from "../../errors/index.js";
+import { shouldColorize, styler } from "../../output/style.js";
+import { mapPhaseToString } from "../stream/convert.js";
+import type { HeadlessResult } from "../stream/headless.js";
+
+/**
+ * Fetch the final execution + usage and print the exit summary. Returns the
+ * final execution so the caller can act on its artifacts (e.g. --download).
+ */
+export async function runEpilogue(
+  client: Stigmer,
+  sessionId: string,
+  executionId: string,
+  result: HeadlessResult,
+): Promise<AgentExecution> {
+  // A stream error before any phase is a hard failure (Go: epilogue returns it).
+  if (result.error !== "" && result.phase === "") {
+    throw new CliExitError(result.error, ExitCode.General);
+  }
+
+  const exec = await client.agentExecution.get(executionId);
+  const usage = await fetchUsage(client, executionId);
+
+  const write = (line: string): void => void process.stderr.write(`${line}\n`);
+  const s = styler(shouldColorize(process.stderr));
+  write("");
+  if (sessionId !== "") {
+    printSessionExit(write, s, sessionId, exec, usage);
+  } else {
+    printCompletion(write, s, exec);
+  }
+  return exec;
+}
+
+// Best-effort usage fetch; a failure here must not fail the run (Go tolerates a
+// nil usage report and renders without the cost line).
+async function fetchUsage(client: Stigmer, executionId: string): Promise<UsageReportAggregate | undefined> {
+  try {
+    const report = await client.agentExecution.getExecutionUsageReport(
+      create(GetExecutionUsageReportInputSchema, { executionId }),
+    );
+    return report.aggregate;
+  } catch {
+    return undefined;
+  }
+}
+
+type Styler = ReturnType<typeof styler>;
+type Write = (line: string) => void;
+
+// Compact session summary + a copy-paste resume command. Mirrors Go's
+// displaySessionExitLine + sessionResumeVerb.
+function printSessionExit(
+  write: Write,
+  s: Styler,
+  sessionId: string,
+  exec: AgentExecution,
+  usage: UsageReportAggregate | undefined,
+): void {
+  const phase = exec.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+  const duration = formatDuration(exec.status?.startedAt ?? "", exec.status?.completedAt ?? "");
+  const cost = usage !== undefined && usage.billableCostMicros > 0n ? formatCost(usage.billableCostMicros) : "";
+
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_COMPLETED:
+      write(s.green(completedLine(duration, cost)));
+      break;
+    case ExecutionPhase.EXECUTION_FAILED:
+      write(s.red(`✗ Failed: ${resolveFailureError(exec)}`));
+      break;
+    case ExecutionPhase.EXECUTION_CANCELLED:
+      write(s.yellow("Cancelled"));
+      break;
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      write(s.yellow(`Stopped: ${resolveFailureError(exec)}`));
+      break;
+    default:
+      write(s.yellow(`Exited (${mapPhaseToString(phase)})`));
+  }
+
+  write("");
+  write(`  ${resumeVerb(phase)}  stigmer resume ${sessionId}`);
+}
+
+// Non-session completion (rare for run; e.g. a degraded backend). Mirrors the
+// information of Go's displayAgentExecutionComplete without the panel chrome.
+function printCompletion(write: Write, s: Styler, exec: AgentExecution): void {
+  const phase = exec.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+  if (phase === ExecutionPhase.EXECUTION_FAILED) {
+    write(s.red(`✗ Execution failed: ${resolveFailureError(exec)}`));
+    return;
+  }
+  write(s.green(`✓ Execution ${mapPhaseToString(phase)}`));
+}
+
+function completedLine(duration: string, cost: string): string {
+  if (duration !== "" && cost !== "") return `✓ Completed (${duration} · ${cost})`;
+  if (duration !== "") return `✓ Completed (${duration})`;
+  return "✓ Completed";
+}
+
+function resumeVerb(phase: ExecutionPhase): string {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_COMPLETED:
+      return "To continue:";
+    case ExecutionPhase.EXECUTION_FAILED:
+      return "To retry:   ";
+    default:
+      return "To resume:  ";
+  }
+}
+
+// Mirrors Go's resolveFailureError: canonical error, else last system message,
+// else first failed tool call's error, else a generic pointer to the logs.
+function resolveFailureError(exec: AgentExecution): string {
+  const status = exec.status;
+  if (status === undefined) return GENERIC_FAILURE;
+  if (status.error !== "") return status.error;
+
+  for (let i = status.messages.length - 1; i >= 0; i--) {
+    const msg = status.messages[i];
+    if (msg.type === MessageType.MESSAGE_SYSTEM && msg.content !== "") return msg.content;
+  }
+  for (const msg of status.messages) {
+    for (const tc of msg.toolCalls) {
+      if (tc.status === ToolCallStatus.TOOL_CALL_FAILED && tc.error !== "") return tc.error;
+    }
+  }
+  return GENERIC_FAILURE;
+}
+
+const GENERIC_FAILURE = "Execution failed (error details unavailable — check execution logs)";
+
+// "1m23s"/"45s" between two RFC3339 timestamps, or "" when unknown. Mirrors Go's
+// parseDuration + Round(time.Second).
+function formatDuration(startedAt: string, completedAt: string): string {
+  if (startedAt === "" || completedAt === "") return "";
+  const start = Date.parse(startedAt);
+  const end = Date.parse(completedAt);
+  if (Number.isNaN(start) || Number.isNaN(end) || end < start) return "";
+  const totalSeconds = Math.round((end - start) / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return seconds === 0 ? `${minutes}m` : `${minutes}m${seconds}s`;
+}
+
+// USD from micros. Mirrors usage.ts's formatCost precision tiers.
+function formatCost(micros: bigint): string {
+  const usd = Number(micros) / 1_000_000;
+  if (usd === 0) return "$0.00";
+  if (usd < 1) return `$${usd.toFixed(3)}`;
+  return `$${usd.toFixed(2)}`;
+}

package/src/resources/run/header.test.ts

@@ -0,0 +1,61 @@
+import { create } from "@bufbuild/protobuf";
+import {
+  WorkspaceEntrySchema,
+} from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import { describe, expect, it } from "vitest";
+import { renderSessionHeader, workspaceNames } from "./header.js";
+
+function capture(): { out: { write(c: string): void; isTTY: boolean }; text: () => string } {
+  let buf = "";
+  return {
+    out: { write: (c: string) => void (buf += c), isTTY: false },
+    text: () => buf,
+  };
+}
+
+describe("renderSessionHeader", () => {
+  it("omits empty fields and aligns labels", () => {
+    const { out, text } = capture();
+    renderSessionHeader(out, { agentName: "Reviewer", sessionId: "ses_abc", model: "", mode: "", workspaces: [] });
+    expect(text()).toBe("Agent:      Reviewer\nSession:    ses_abc\n\n");
+  });
+
+  it("surfaces plan mode but not agent/default", () => {
+    const plan = capture();
+    renderSessionHeader(plan.out, { agentName: "", sessionId: "", model: "", mode: "plan", workspaces: [] });
+    expect(plan.text()).toContain("Mode:");
+    expect(plan.text()).toContain("Plan (read-only)");
+
+    const agent = capture();
+    renderSessionHeader(agent.out, { agentName: "", sessionId: "s", model: "", mode: "agent", workspaces: [] });
+    expect(agent.text()).not.toContain("Mode:");
+  });
+
+  it("indents extra workspaces under the first", () => {
+    const { out, text } = capture();
+    renderSessionHeader(out, {
+      agentName: "",
+      sessionId: "",
+      model: "",
+      mode: "",
+      workspaces: ["app", "infra"],
+    });
+    expect(text()).toBe("Workspaces: app\n            infra\n\n");
+  });
+
+  it("prints nothing when every field is empty", () => {
+    const { out, text } = capture();
+    renderSessionHeader(out, { agentName: "", sessionId: "", model: "", mode: "", workspaces: [] });
+    expect(text()).toBe("");
+  });
+});
+
+describe("workspaceNames", () => {
+  it("extracts the derived name from each entry", () => {
+    const entries = [
+      create(WorkspaceEntrySchema, { name: "app" }),
+      create(WorkspaceEntrySchema, { name: "infra" }),
+    ];
+    expect(workspaceNames(entries)).toEqual(["app", "infra"]);
+  });
+});

package/src/resources/run/header.ts

@@ -0,0 +1,62 @@
+// The session header shown before a headless stream starts (Go's
+// renderSessionHeader / sessionHeaderInfo in run_display_header.go).
+//
+// Deliberate divergence (clean over chrome): Go renders a lipgloss bordered
+// panel with a side-by-side "recent sessions" column. That panel is TTY
+// eye-candy; the interactive path here is owned by Ink's SessionView, which
+// draws its own header. The only consumers of THIS header are the headless
+// (--json / non-TTY plaintext) paths, where the output target is stderr — a
+// bordered panel there would be noise. So we emit a compact, aligned key/value
+// block carrying the same fields (Agent, Session, Model, Mode, Workspaces).
+
+import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import { shouldColorize, styler } from "../../output/style.js";
+import type { RunMode } from "./prepare.js";
+
+export interface SessionHeaderInfo {
+  readonly agentName: string;
+  readonly sessionId: string;
+  /** Session subject; shown for resumed sessions, empty for fresh runs. */
+  readonly subject?: string;
+  readonly model: string;
+  readonly mode: RunMode;
+  readonly workspaces: readonly string[];
+}
+
+// Fixed label column width; sized to the longest label ("Workspaces") + ": ".
+const LABEL_WIDTH = 12;
+
+/**
+ * Write the session header to `out` (stderr). Empty fields are omitted, exactly
+ * like Go's formatMetadataSection. A header with no populated fields prints
+ * nothing.
+ */
+export function renderSessionHeader(out: { write(chunk: string): unknown; isTTY?: boolean }, info: SessionHeaderInfo): void {
+  const s = styler(shouldColorize(out));
+  const lines: string[] = [];
+
+  if (info.agentName !== "") lines.push(row(s, "Agent", info.agentName));
+  if (info.sessionId !== "") lines.push(row(s, "Session", info.sessionId));
+  if ((info.subject ?? "") !== "") lines.push(row(s, "Subject", info.subject ?? ""));
+  if (info.model !== "") lines.push(row(s, "Model", info.model));
+  // Only "plan" is surfaced; "agent"/"" is the default and stays implicit.
+  if (info.mode === "plan") lines.push(row(s, "Mode", "Plan (read-only)"));
+  if (info.workspaces.length > 0) {
+    lines.push(row(s, "Workspaces", info.workspaces[0]));
+    const indent = " ".repeat(LABEL_WIDTH);
+    for (const ws of info.workspaces.slice(1)) lines.push(`${indent}${ws}`);
+  }
+
+  if (lines.length === 0) return;
+  out.write(`${lines.join("\n")}\n\n`);
+}
+
+function row(s: ReturnType<typeof styler>, label: string, value: string): string {
+  const padded = `${label}:`.padEnd(LABEL_WIDTH, " ");
+  return `${s.dim(padded)}${value}`;
+}
+
+/** Displayable names from workspace entries (Go's workspaceNames). */
+export function workspaceNames(entries: readonly WorkspaceEntry[]): string[] {
+  return entries.map((e) => e.name);
+}

package/src/resources/run/prepare.test.ts

@@ -0,0 +1,92 @@
+// Unit tests for the prelude orchestrator: flag validation helpers and the
+// STIGMER_ORG_ID injection rule. Attachment uploading is covered in
+// attachments.test.ts, so these tests use no attachments.
+
+import { describe, expect, it } from "vitest";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { type AgentExecFlags, parseApprovalAction, prepareAgentExec, validateMode } from "./prepare.js";
+
+describe("parseApprovalAction", () => {
+  it("maps each accepted value (case-insensitive)", () => {
+    expect(parseApprovalAction("")).toBe(ApprovalAction.UNSPECIFIED);
+    expect(parseApprovalAction("approve")).toBe(ApprovalAction.APPROVE);
+    expect(parseApprovalAction("SKIP")).toBe(ApprovalAction.SKIP);
+    expect(parseApprovalAction("reject")).toBe(ApprovalAction.REJECT);
+    expect(parseApprovalAction("approve-all")).toBe(ApprovalAction.APPROVE_ALL);
+    expect(parseApprovalAction("approve_all")).toBe(ApprovalAction.APPROVE_ALL);
+    expect(parseApprovalAction("approveall")).toBe(ApprovalAction.APPROVE_ALL);
+  });
+
+  it("rejects an unknown value", () => {
+    expect(() => parseApprovalAction("maybe")).toThrow(/must be one of/);
+  });
+});
+
+describe("validateMode", () => {
+  it("accepts empty, agent, and plan", () => {
+    expect(() => validateMode("")).not.toThrow();
+    expect(() => validateMode("agent")).not.toThrow();
+    expect(() => validateMode("plan")).not.toThrow();
+  });
+
+  it("rejects anything else", () => {
+    expect(() => validateMode("yolo")).toThrow(/must be "agent" or "plan"/);
+  });
+});
+
+const BASE_FLAGS: AgentExecFlags = {
+  message: "hi",
+  attach: [],
+  approveDefault: "",
+  verbose: false,
+  detach: false,
+  workspace: [],
+  branch: "",
+  commit: "",
+  env: [],
+  envFile: [],
+  secret: [],
+  secretFile: [],
+  model: "",
+  autoApprove: false,
+  mode: "",
+};
+
+// prepareAgentExec only touches client.agentExecution for attachment uploads;
+// with no attachments a bare stub suffices.
+const STUB_CLIENT = { agentExecution: {} } as unknown as Stigmer;
+
+describe("prepareAgentExec env injection", () => {
+  it("injects STIGMER_ORG_ID when absent", async () => {
+    const prepared = await prepareAgentExec(BASE_FLAGS, STUB_CLIENT, "acme");
+    expect(prepared.runtimeEnv.STIGMER_ORG_ID).toEqual({ value: "acme", isSecret: false });
+  });
+
+  it("does not override an explicit STIGMER_ORG_ID", async () => {
+    const prepared = await prepareAgentExec(
+      { ...BASE_FLAGS, env: ["STIGMER_ORG_ID=explicit"] },
+      STUB_CLIENT,
+      "acme",
+    );
+    expect(prepared.runtimeEnv.STIGMER_ORG_ID).toEqual({ value: "explicit", isSecret: false });
+  });
+
+  it("skips injection when org is empty", async () => {
+    const prepared = await prepareAgentExec(BASE_FLAGS, STUB_CLIENT, "");
+    expect(prepared.runtimeEnv.STIGMER_ORG_ID).toBeUndefined();
+  });
+
+  it("carries through scalar flags", async () => {
+    const prepared = await prepareAgentExec(
+      { ...BASE_FLAGS, message: "go", model: "claude", autoApprove: true, detach: true, mode: "plan" },
+      STUB_CLIENT,
+      "acme",
+    );
+    expect(prepared.message).toBe("go");
+    expect(prepared.model).toBe("claude");
+    expect(prepared.autoApproveAll).toBe(true);
+    expect(prepared.detach).toBe(true);
+    expect(prepared.mode).toBe("plan");
+  });
+});

package/src/resources/run/prepare.ts

@@ -0,0 +1,139 @@
+// The agent-execution prelude: validate flags and resolve every input the
+// create step needs. Ports the Go CLI's prepareAgentExec (run_agent_exec.go).
+//
+// Order matters and mirrors Go: validate cheap flags first (mode, approve
+// default), then parse workspaces, then merge env, then process attachments
+// (the only step that hits the network). A failure short-circuits before any
+// upload. STIGMER_ORG_ID is injected into the runtime env when absent so agents
+// can address the caller's org without the user wiring it manually.
+
+import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { UsageError } from "../../errors/index.js";
+import { type ProgressSink, processAttachments } from "./attachments.js";
+import { loadAndMergeEnv, type RuntimeEnv } from "./env.js";
+import { localWorkspaceRoots, parseWorkspaceEntries } from "./workspace.js";
+
+/** The interaction mode requested for the run; "" means the agent default. */
+export type RunMode = "" | "agent" | "plan";
+
+/** Raw agent-execution flags shared by `run` and `draft` (Go's agentExecFlags). */
+export interface AgentExecFlags {
+  readonly message: string;
+  readonly attach: readonly string[];
+  readonly approveDefault: string;
+  readonly verbose: boolean;
+  readonly detach: boolean;
+  readonly workspace: readonly string[];
+  readonly branch: string;
+  readonly commit: string;
+  readonly env: readonly string[];
+  readonly envFile: readonly string[];
+  readonly secret: readonly string[];
+  readonly secretFile: readonly string[];
+  readonly model: string;
+  readonly autoApprove: boolean;
+  readonly mode: RunMode;
+}
+
+/**
+ * The validated, resolved inputs ready for create + stream. Mirrors Go's
+ * preparedAgentExec, minus the client/org which the command already owns.
+ */
+export interface PreparedRun {
+  readonly defaultAction: ApprovalAction;
+  readonly workspaceEntries: WorkspaceEntry[];
+  readonly runtimeEnv: RuntimeEnv;
+  readonly attachments: Attachment[];
+  readonly workspaceFileRefs: string[];
+  readonly message: string;
+  readonly detach: boolean;
+  readonly verbose: boolean;
+  readonly model: string;
+  readonly autoApproveAll: boolean;
+  readonly mode: RunMode;
+}
+
+/**
+ * Validate flags and resolve all execution inputs. The `org` is used to inject
+ * STIGMER_ORG_ID and the `client` to upload non-workspace attachments.
+ */
+export async function prepareAgentExec(
+  flags: AgentExecFlags,
+  client: Stigmer,
+  org: string,
+  progress?: ProgressSink,
+): Promise<PreparedRun> {
+  const defaultAction = parseApprovalAction(flags.approveDefault);
+  validateMode(flags.mode);
+
+  const workspaceEntries = parseWorkspaceEntries(flags.workspace, flags.branch, flags.commit);
+
+  const runtimeEnv = loadAndMergeEnv({
+    envFlags: flags.env,
+    secretFlags: flags.secret,
+    envFiles: flags.envFile,
+    secretFiles: flags.secretFile,
+  });
+  if (runtimeEnv.STIGMER_ORG_ID === undefined && org !== "") {
+    runtimeEnv.STIGMER_ORG_ID = { value: org, isSecret: false };
+  }
+
+  const { attachments, workspaceFileRefs } = await processAttachments(
+    client.agentExecution,
+    flags.attach,
+    localWorkspaceRoots(workspaceEntries),
+    progress,
+  );
+
+  return {
+    defaultAction,
+    workspaceEntries,
+    runtimeEnv,
+    attachments,
+    workspaceFileRefs,
+    message: flags.message,
+    detach: flags.detach,
+    verbose: flags.verbose,
+    model: flags.model,
+    autoApproveAll: flags.autoApprove,
+    mode: flags.mode,
+  };
+}
+
+/**
+ * Parse the `--approve-default` flag to an ApprovalAction. Empty means "no
+ * default" (UNSPECIFIED). Mirrors Go's approval.ParseAction, including the
+ * approve-all aliases and case-insensitivity.
+ */
+export function parseApprovalAction(value: string): ApprovalAction {
+  if (value.trim() === "") return ApprovalAction.UNSPECIFIED;
+  switch (value.trim().toLowerCase()) {
+    case "approve":
+      return ApprovalAction.APPROVE;
+    case "skip":
+      return ApprovalAction.SKIP;
+    case "reject":
+      return ApprovalAction.REJECT;
+    case "approve-all":
+    case "approve_all":
+    case "approveall":
+      return ApprovalAction.APPROVE_ALL;
+    default:
+      throw new UsageError(
+        `invalid --approve-default value "${value}": must be one of: approve, skip, reject, approve-all`,
+      );
+  }
+}
+
+/**
+ * Validate the `--mode` flag. Empty (unset) is valid and means "use default"
+ * (agent). Mirrors Go's validateMode.
+ */
+export function validateMode(mode: string): asserts mode is RunMode {
+  if (mode !== "" && mode !== "agent" && mode !== "plan") {
+    throw new UsageError(`invalid --mode value "${mode}": must be "agent" or "plan"`);
+  }
+}