@stigmer/cli 3.0.8

package/src/resources/stream/tool-state.ts

@@ -0,0 +1,142 @@
+// Tool-call state-transition tracking for the snapshot differ.
+//
+// Ports the Go CLI's trackToolCallStates (run_stream_events.go:597-695). Each
+// snapshot carries the full tool-call list; this tracker diffs it against the
+// last-known per-tool status/result to emit only the *transitions* (running,
+// completed, waiting-approval, streaming delta). One tracker instance per scope:
+// the top-level execution gets one, each sub-agent gets its own (matching Go's
+// per-sub-agent tracker maps).
+
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { convertToolCall, isTerminalToolStatus, mapToolCallStatus } from "./convert.js";
+import type { StreamEvent } from "./events.js";
+
+/**
+ * Stateful tracker that converts successive tool-call snapshots into discrete
+ * lifecycle events. The state (last status + last streamed result per tool ID)
+ * persists across calls, so only genuine transitions produce events.
+ */
+export class ToolStateTracker {
+  // toolCallID -> last known status string.
+  private readonly states = new Map<string, string>();
+  // toolCallID -> last known result content, for streaming-delta detection.
+  private readonly results = new Map<string, string>();
+
+  /**
+   * Diff `toolCalls` against tracked state and return the resulting events.
+   * `subAgentId` scopes the events for nested rendering ("" for top-level).
+   * Mirrors Go's trackToolCallStates branch-for-branch.
+   */
+  track(toolCalls: readonly ToolCall[], subAgentId: string): StreamEvent[] {
+    const pending: StreamEvent[] = [];
+
+    for (const tc of toolCalls) {
+      if (tc.id === "") continue;
+
+      const current = mapToolCallStatus(tc.status);
+      const seen = this.states.has(tc.id);
+      const prev = this.states.get(tc.id);
+
+      // First sight, already running: open a running block.
+      if (!seen && current === "running") {
+        pending.push(this.running(tc, subAgentId));
+        this.states.set(tc.id, current);
+        this.results.set(tc.id, tc.result);
+        continue;
+      }
+
+      // First sight, awaiting approval: open a waiting block.
+      if (!seen && current === "waiting_approval") {
+        pending.push(this.waiting(tc, subAgentId));
+        this.states.set(tc.id, current);
+        continue;
+      }
+
+      // First sight, already terminal (e.g. re-attach): synthesize completion so
+      // the block exists — otherwise its MESSAGE_TOOL is suppressed and it vanishes.
+      if (!seen && isTerminalToolStatus(current)) {
+        pending.push(this.completed(tc, subAgentId));
+        this.states.set(tc.id, current);
+        continue;
+      }
+
+      // running/waiting -> terminal: close the block.
+      if (seen && (prev === "running" || prev === "waiting_approval") && isTerminalToolStatus(current)) {
+        pending.push(this.completed(tc, subAgentId));
+        this.states.set(tc.id, current);
+        this.results.delete(tc.id);
+        continue;
+      }
+
+      // Any other status change: open running/waiting as appropriate.
+      if (current !== prev) {
+        if (current === "running") {
+          pending.push(this.running(tc, subAgentId));
+          this.results.set(tc.id, tc.result);
+        } else if (current === "waiting_approval") {
+          pending.push(this.waiting(tc, subAgentId));
+        }
+        this.states.set(tc.id, current);
+        continue;
+      }
+
+      // Streaming content changed on a running tool: emit a delta.
+      if (current === "running" && tc.isStreaming && tc.result !== this.results.get(tc.id)) {
+        pending.push({
+          kind: "toolStreamDelta",
+          toolCallId: tc.id,
+          toolCall: convertToolCall(tc),
+          content: tc.result,
+          subAgentId,
+        });
+        this.results.set(tc.id, tc.result);
+      }
+    }
+
+    return pending;
+  }
+
+  /**
+   * True if `id` has a tracked state, i.e. a stateful block already exists for
+   * it. Used to suppress a duplicate ToolResultEvent for a MESSAGE_TOOL the
+   * tracker already owns. Mirrors the membership check in Go's isTrackedToolMessage.
+   */
+  has(id: string): boolean {
+    return this.states.has(id);
+  }
+
+  private running(tc: ToolCall, subAgentId: string): StreamEvent {
+    return { kind: "toolRunning", toolCallId: tc.id, toolCall: convertToolCall(tc), subAgentId };
+  }
+
+  private waiting(tc: ToolCall, subAgentId: string): StreamEvent {
+    return { kind: "toolWaitingApproval", toolCallId: tc.id, toolCall: convertToolCall(tc), subAgentId };
+  }
+
+  private completed(tc: ToolCall, subAgentId: string): StreamEvent {
+    return { kind: "toolCompleted", toolCallId: tc.id, toolCall: convertToolCall(tc), subAgentId };
+  }
+}
+
+/** The tool-call ID carried by a tool-lifecycle event, or "" otherwise. Mirrors Go's toolEventID. */
+export function toolEventId(event: StreamEvent): string {
+  switch (event.kind) {
+    case "toolRunning":
+    case "toolCompleted":
+    case "toolWaitingApproval":
+    case "toolStreamDelta":
+      return event.toolCallId;
+    default:
+      return "";
+  }
+}
+
+/** Index tool events by tool-call ID for chronological interleaving. Mirrors Go's buildToolEventMap. */
+export function buildToolEventMap(events: readonly StreamEvent[]): Map<string, StreamEvent> {
+  const m = new Map<string, StreamEvent>();
+  for (const ev of events) {
+    const id = toolEventId(ev);
+    if (id !== "") m.set(id, ev);
+  }
+  return m;
+}

package/src/resources/stream/tty.ts

@@ -0,0 +1,14 @@
+// Terminal-capability gate for renderer selection.
+//
+// Deliberately free of any React/Ink imports so the command can decide whether
+// to take the interactive path *before* paying the dynamic-import cost of
+// ink.tsx (DD-001 lazy boundary). Mirrors Go's termctl.IsSupported.
+
+/**
+ * Whether the terminal can host the interactive Ink renderer: stdout must be a
+ * TTY and TERM must not be "dumb". When false, the command uses plaintext.
+ */
+export function isInkSupported(stream: { isTTY?: boolean } = process.stdout): boolean {
+  if (stream.isTTY !== true) return false;
+  return process.env.TERM !== "dumb";
+}

package/src/resources/stream/workflow-event-view.test.ts

@@ -0,0 +1,116 @@
+import { create } from "@bufbuild/protobuf";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  ApprovalRequestedPayloadSchema,
+  ApprovalResolvedPayloadSchema,
+  BudgetCheckpointPayloadSchema,
+  ExecutionFailedPayloadSchema,
+  TaskFailedPayloadSchema,
+  TaskRetryingPayloadSchema,
+  WorkflowExecutionEventSchema,
+  WorkflowEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { describe, expect, it } from "vitest";
+import { toWorkflowEventView, workflowEventTypeName } from "./workflow-event-view.js";
+
+describe("workflowEventTypeName", () => {
+  it("returns the canonical proto name for the type", () => {
+    expect(workflowEventTypeName(WorkflowEventType.execution_started)).toBe("execution_started");
+    expect(workflowEventTypeName(WorkflowEventType.approval_requested)).toBe("approval_requested");
+  });
+});
+
+describe("toWorkflowEventView", () => {
+  it("formats the HH:MM:SS slice of occurred_at", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      eventType: WorkflowEventType.execution_started,
+      occurredAt: "2026-06-12T13:45:09.123Z",
+      payload: { case: "executionStarted", value: {} as never },
+    });
+    expect(toWorkflowEventView(event).time).toBe("13:45:09");
+  });
+
+  it("falls back to dashes when occurred_at is empty", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      eventType: WorkflowEventType.execution_started,
+      payload: { case: "executionStarted", value: {} as never },
+    });
+    expect(toWorkflowEventView(event).time).toBe("--------");
+  });
+
+  it("marks execution_completed/failed/cancelled/terminated as terminal", () => {
+    for (const c of ["executionCompleted", "executionCancelled", "executionTerminated"] as const) {
+      const event = create(WorkflowExecutionEventSchema, { payload: { case: c, value: {} as never } });
+      expect(toWorkflowEventView(event).terminal).toBe(true);
+    }
+    const failed = create(WorkflowExecutionEventSchema, {
+      payload: { case: "executionFailed", value: create(ExecutionFailedPayloadSchema, { error: "boom" }) },
+    });
+    const view = toWorkflowEventView(failed);
+    expect(view.terminal).toBe(true);
+    expect(view.tone).toBe("error");
+    expect(view.text).toBe("execution failed: boom");
+  });
+
+  it("does not mark task/lifecycle non-terminal events as terminal", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      taskName: "validate",
+      payload: { case: "taskStarted", value: {} as never },
+    });
+    const view = toWorkflowEventView(event);
+    expect(view.terminal).toBe(false);
+    expect(view.text).toBe("task started: validate");
+  });
+
+  it("extracts the error and task name for task_failed", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      taskName: "send",
+      payload: { case: "taskFailed", value: create(TaskFailedPayloadSchema, { error: "timeout" }) },
+    });
+    expect(toWorkflowEventView(event).text).toBe("task failed: send — timeout");
+  });
+
+  it("includes the next attempt for task_retrying", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      taskName: "send",
+      payload: { case: "taskRetrying", value: create(TaskRetryingPayloadSchema, { nextAttempt: 3 }) },
+    });
+    expect(toWorkflowEventView(event).text).toBe("task retrying: send (attempt 3)");
+  });
+
+  it("renders the prompt for approval_requested", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      taskName: "review",
+      payload: { case: "approvalRequested", value: create(ApprovalRequestedPayloadSchema, { prompt: "ok?" }) },
+    });
+    expect(toWorkflowEventView(event).text).toBe("approval requested: review — ok?");
+  });
+
+  it("renders the action and resolver for approval_resolved", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      taskName: "review",
+      payload: {
+        case: "approvalResolved",
+        value: create(ApprovalResolvedPayloadSchema, { action: ApprovalAction.APPROVE, resolvedBy: "alice" }),
+      },
+    });
+    expect(toWorkflowEventView(event).text).toBe("approval resolved: review — approve by alice");
+  });
+
+  it("converts micros to a dollar amount for budget_checkpoint", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      payload: { case: "budgetCheckpoint", value: create(BudgetCheckpointPayloadSchema, { costConsumedMicros: 1_234_500n }) },
+    });
+    expect(toWorkflowEventView(event).text).toBe("budget: $1.2345 spent");
+  });
+
+  it("falls back to a generic line for events without a dedicated view", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      eventType: WorkflowEventType.signal_received,
+      payload: { case: "signalReceived", value: {} as never },
+    });
+    const view = toWorkflowEventView(event);
+    expect(view.glyph).toBe("");
+    expect(view.text).toBe("event: signal_received");
+  });
+});

package/src/resources/stream/workflow-event-view.ts

@@ -0,0 +1,111 @@
+// Canonical WorkflowExecutionEvent → display mapping.
+//
+// This is the single source of truth for how a workflow event is presented,
+// shared by `run workflow` (live stream) and `execution logs` (historical +
+// follow). It is a pure transform with no I/O: a renderer (plaintext or NDJSON)
+// decides where bytes go; this module decides *what* each event means.
+//
+// Why an event view at all: WorkflowExecution exposes a canonical, sequenced
+// event stream (subscribeEvents) with a rich WorkflowEventType taxonomy. Rather
+// than invent a CLI-private vocabulary, every CLI surface renders the server's
+// events directly, so the CLI, the web execution viewer, and the SDK all agree
+// on what happened. Ports Go's execution.renderWorkflowEvent switch
+// (internal/cli/execution/logs_workflow.go), preserving its glyphs and wording.
+
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  type WorkflowExecutionEvent,
+  WorkflowEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+
+/** Color intent for an event line; the renderer maps this to ANSI (or nothing). */
+export type EventTone = "success" | "error" | "warning" | "info" | "muted";
+
+/** A renderer-agnostic view of one workflow event. */
+export interface WorkflowEventView {
+  /** HH:MM:SS slice of occurred_at, or "--------" when absent. */
+  readonly time: string;
+  /** Leading glyph (▶ ✓ ✗ → …); empty for the generic fallback line. */
+  readonly glyph: string;
+  /** Tone applied to the glyph. */
+  readonly tone: EventTone;
+  /** Human sentence describing the event. */
+  readonly text: string;
+  /** True when this event marks a terminal execution phase. */
+  readonly terminal: boolean;
+}
+
+/** Canonical WorkflowEventType name (e.g. "execution_started") for NDJSON `type`. */
+export function workflowEventTypeName(type: WorkflowEventType): string {
+  return WorkflowEventType[type] ?? "workflow_event_type_unspecified";
+}
+
+/** Map a workflow event to its display view. Switches on the typed oneof payload. */
+export function toWorkflowEventView(event: WorkflowExecutionEvent): WorkflowEventView {
+  const time = formatEventTime(event.occurredAt);
+  const taskName = event.taskName;
+  const view = (glyph: string, tone: EventTone, text: string, terminal = false): WorkflowEventView => ({
+    time,
+    glyph,
+    tone,
+    text,
+    terminal,
+  });
+
+  switch (event.payload.case) {
+    case "executionStarted":
+      return view("▶", "success", "execution started");
+    case "executionCompleted":
+      return view("✓", "success", "execution completed", true);
+    case "executionFailed":
+      return view("✗", "error", `execution failed: ${event.payload.value.error}`, true);
+    case "executionPaused":
+      return view("⏸", "warning", "execution paused");
+    case "executionResumed":
+      return view("▶", "success", "execution resumed");
+    case "executionCancelled":
+      return view("⊘", "warning", "execution cancelled", true);
+    case "executionTerminated":
+      return view("⊘", "error", "execution terminated", true);
+    case "taskStarted":
+      return view("→", "info", `task started: ${taskName}`);
+    case "taskCompleted":
+      return view("✓", "success", `task completed: ${taskName}`);
+    case "taskFailed":
+      return view("✗", "error", `task failed: ${taskName} — ${event.payload.value.error}`);
+    case "taskSkipped":
+      return view("⊘", "muted", `task skipped: ${taskName}`);
+    case "taskRetrying":
+      return view("↻", "warning", `task retrying: ${taskName} (attempt ${event.payload.value.nextAttempt})`);
+    case "agentCallStarted":
+      return view("⚡", "info", `agent call started: ${taskName}`);
+    case "agentCallCompleted":
+      return view("⚡", "success", `agent call completed: ${taskName}`);
+    case "approvalRequested":
+      return view("⏳", "warning", `approval requested: ${taskName} — ${event.payload.value.prompt}`);
+    case "approvalResolved": {
+      const { action, resolvedBy } = event.payload.value;
+      return view("✓", "success", `approval resolved: ${taskName} — ${approvalActionLabel(action)} by ${resolvedBy}`);
+    }
+    case "budgetCheckpoint": {
+      const costUsd = Number(event.payload.value.costConsumedMicros) / 1_000_000;
+      return view("$", "muted", `budget: $${costUsd.toFixed(4)} spent`);
+    }
+    default:
+      // Events with no dedicated line (agent_call_progress, signal_received,
+      // event_emitted, artifact_created, unspecified): a generic fallback,
+      // mirroring Go's default branch.
+      return view("", "muted", `event: ${workflowEventTypeName(event.eventType)}`);
+  }
+}
+
+// HH:MM:SS slice of an ISO 8601 timestamp; mirrors Go's formatEventTimestamp.
+function formatEventTime(occurredAt: string): string {
+  if (occurredAt.length > 19) return occurredAt.slice(11, 19);
+  if (occurredAt === "") return "--------";
+  return occurredAt;
+}
+
+function approvalActionLabel(action: ApprovalAction): string {
+  return (ApprovalAction[action] ?? "unspecified").toLowerCase();
+}

package/src/resources/stream/workflow-render-ndjson.ts

@@ -0,0 +1,61 @@
+// NDJSON renderer for workflow events (`run workflow --json`).
+//
+// Emits one `{type, ts, payload}` envelope per event, where `type` is the
+// canonical WorkflowEventType name (e.g. "execution_started") — the server's
+// own vocabulary, not a CLI invention. This is the machine-readable workflow
+// stream that the Go CLI never produced (defect D-WF-1): Go's
+// `run workflow --json` flag was silently ignored.
+//
+// The payload carries the always-present envelope fields plus the salient,
+// event-specific fields extracted from the typed oneof. Empty/nil fields are
+// stripped by ndjsonEnvelope, matching the agent run --json wire shape.
+
+import { ndjsonEnvelope, type NdjsonEnvelope } from "../../output/ndjson.js";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { WorkflowExecutionEvent } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { workflowEventTypeName } from "./workflow-event-view.js";
+
+/** Build the NDJSON envelope for a workflow event. `now` is injectable for tests. */
+export function workflowEventToNdjson(event: WorkflowExecutionEvent, now?: () => string): NdjsonEnvelope {
+  return ndjsonEnvelope(
+    workflowEventTypeName(event.eventType),
+    {
+      sequence: Number(event.sequenceNumber),
+      task: event.taskName,
+      ...eventPayloadFields(event),
+    },
+    now ?? (() => event.occurredAt),
+  );
+}
+
+// Salient fields per event kind. Kept deliberately small and stable — the same
+// keys the plaintext line surfaces — so consumers get a predictable shape.
+function eventPayloadFields(event: WorkflowExecutionEvent): Record<string, unknown> {
+  switch (event.payload.case) {
+    case "executionFailed":
+      return { error: event.payload.value.error };
+    case "executionCompleted":
+      return {
+        durationMs: Number(event.payload.value.durationMs),
+        costMicros: Number(event.payload.value.totalCostMicros),
+      };
+    case "executionCancelled":
+    case "executionTerminated":
+      return { reason: event.payload.value.reason };
+    case "taskFailed":
+      return { error: event.payload.value.error };
+    case "taskRetrying":
+      return { nextAttempt: event.payload.value.nextAttempt };
+    case "approvalRequested":
+      return { prompt: event.payload.value.prompt, toolCallId: event.payload.value.toolCallId };
+    case "approvalResolved":
+      return {
+        action: (ApprovalAction[event.payload.value.action] ?? "unspecified").toLowerCase(),
+        resolvedBy: event.payload.value.resolvedBy,
+      };
+    case "budgetCheckpoint":
+      return { costMicros: Number(event.payload.value.costConsumedMicros) };
+    default:
+      return {};
+  }
+}

package/src/resources/stream/workflow-render-plaintext.ts

@@ -0,0 +1,43 @@
+// Plaintext renderer for workflow events (human + `execution logs` output).
+//
+// Renders one line per event: `[HH:MM:SS] <glyph> <text>`, with the glyph tinted
+// by the event tone (color auto-disables off a TTY / under NO_COLOR, like the
+// rest of the CLI). Mirrors the layout of Go's renderWorkflowEvent. Output goes
+// to a caller-supplied sink so this composes into both the `run workflow` inline
+// stream and `execution logs`.
+
+import { type Styler, styler } from "../../output/style.js";
+import { type EventTone, type WorkflowEventView, toWorkflowEventView } from "./workflow-event-view.js";
+import type { WorkflowExecutionEvent } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+
+/** A single-line writer (e.g. a wrapper over process.stdout). */
+export interface LineSink {
+  write(line: string): void;
+}
+
+/** Render a workflow event as one tinted line to `sink`. */
+export function renderWorkflowEventPlaintext(event: WorkflowExecutionEvent, sink: LineSink, colorize: boolean): void {
+  const view = toWorkflowEventView(event);
+  sink.write(formatLine(view, styler(colorize)));
+}
+
+function formatLine(view: WorkflowEventView, style: Styler): string {
+  const prefix = style.dim(`[${view.time}]`);
+  const glyph = view.glyph === "" ? "  " : tint(view.glyph, view.tone, style);
+  return `${prefix} ${glyph} ${view.text}\n`;
+}
+
+function tint(glyph: string, tone: EventTone, style: Styler): string {
+  switch (tone) {
+    case "success":
+      return style.green(glyph);
+    case "error":
+      return style.red(glyph);
+    case "warning":
+      return style.yellow(glyph);
+    case "info":
+      return style.cyan(glyph);
+    case "muted":
+      return style.dim(glyph);
+  }
+}

package/src/resources/stream/workflow-render.test.ts

@@ -0,0 +1,81 @@
+import { create } from "@bufbuild/protobuf";
+import {
+  ApprovalRequestedPayloadSchema,
+  ExecutionFailedPayloadSchema,
+  WorkflowExecutionEventSchema,
+  WorkflowEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { describe, expect, it } from "vitest";
+import { renderWorkflowEventPlaintext } from "./workflow-render-plaintext.js";
+import { workflowEventToNdjson } from "./workflow-render-ndjson.js";
+
+function collect(): { sink: { write(line: string): void }; lines: string[] } {
+  const lines: string[] = [];
+  return { sink: { write: (line) => lines.push(line) }, lines };
+}
+
+describe("renderWorkflowEventPlaintext", () => {
+  it("renders a single uncolored line with timestamp, glyph, and text", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      eventType: WorkflowEventType.task_started,
+      occurredAt: "2026-06-12T13:45:09Z",
+      taskName: "validate",
+      payload: { case: "taskStarted", value: {} as never },
+    });
+    const { sink, lines } = collect();
+    renderWorkflowEventPlaintext(event, sink, false);
+    expect(lines).toEqual(["[13:45:09] → task started: validate\n"]);
+  });
+
+  it("pads the glyph column for the generic fallback line", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      eventType: WorkflowEventType.signal_received,
+      occurredAt: "2026-06-12T13:45:09Z",
+      payload: { case: "signalReceived", value: {} as never },
+    });
+    const { sink, lines } = collect();
+    renderWorkflowEventPlaintext(event, sink, false);
+    expect(lines).toEqual(["[13:45:09]    event: signal_received\n"]);
+  });
+});
+
+describe("workflowEventToNdjson", () => {
+  it("uses the canonical event type as `type` and carries the occurred_at ts", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      eventType: WorkflowEventType.execution_started,
+      occurredAt: "2026-06-12T13:45:09Z",
+      sequenceNumber: 1n,
+      payload: { case: "executionStarted", value: {} as never },
+    });
+    const env = workflowEventToNdjson(event);
+    expect(env.type).toBe("execution_started");
+    expect(env.ts).toBe("2026-06-12T13:45:09Z");
+    expect(env.payload).toEqual({ sequence: 1 });
+  });
+
+  it("surfaces salient fields and strips empty ones", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      eventType: WorkflowEventType.execution_failed,
+      occurredAt: "2026-06-12T13:45:10Z",
+      sequenceNumber: 7n,
+      payload: { case: "executionFailed", value: create(ExecutionFailedPayloadSchema, { error: "boom" }) },
+    });
+    const env = workflowEventToNdjson(event);
+    expect(env.payload).toEqual({ sequence: 7, error: "boom" });
+  });
+
+  it("includes the tool call id on approval_requested (drives interactive approval)", () => {
+    const event = create(WorkflowExecutionEventSchema, {
+      eventType: WorkflowEventType.approval_requested,
+      occurredAt: "2026-06-12T13:45:11Z",
+      sequenceNumber: 9n,
+      taskName: "review",
+      payload: {
+        case: "approvalRequested",
+        value: create(ApprovalRequestedPayloadSchema, { prompt: "ok?", toolCallId: "tc_1" }),
+      },
+    });
+    const env = workflowEventToNdjson(event);
+    expect(env.payload).toMatchObject({ task: "review", prompt: "ok?", toolCallId: "tc_1" });
+  });
+});

package/src/resources/tag.ts

@@ -0,0 +1,50 @@
+// `tag` dispatch: assign a tag to a versioned resource. Tags are mutable
+// pointers — reassigning a tag moves it to the named version. Only workflows are
+// versioned/taggable today, matching the Go CLI's tag command.
+//
+// This is an id-shaped mutation, so it rides the high-level workflow sub-client
+// (resolve the workflow by reference, then tagVersion) rather than a raw
+// controller.
+
+import { create } from "@bufbuild/protobuf";
+import { TagWorkflowVersionInputSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { UsageError } from "../errors/index.js";
+import { CommandResult } from "../output/index.js";
+
+export async function tagVersion(
+  client: Stigmer,
+  typeArg: string,
+  ref: string,
+  hash: string,
+  tag: string,
+  org: string,
+): Promise<CommandResult> {
+  const normalized = typeArg.trim().toLowerCase();
+  if (normalized !== "workflow" && normalized !== "wf") {
+    throw new UsageError(`tagging is not supported for resource type "${typeArg}"\n\nSupported types: workflow`);
+  }
+
+  const [refOrg, slug] = parseOrgSlug(ref, org);
+  const workflow = await client.workflow.getByReference({ org: refOrg, slug });
+  const workflowId = workflow.metadata?.id ?? "";
+
+  await client.workflow.tagVersion(create(TagWorkflowVersionInputSchema, { workflowId, versionHash: hash, tag }));
+
+  return CommandResult.success(`Tagged version ${truncateHash(hash)} as '${tag}'`);
+}
+
+// "org/slug" → [org, slug]; a bare token uses the resolved org context.
+function parseOrgSlug(ref: string, defaultOrg: string): [string, string] {
+  const slash = ref.indexOf("/");
+  if (slash > 0) {
+    return [ref.slice(0, slash), ref.slice(slash + 1)];
+  }
+  return [defaultOrg, ref];
+}
+
+// The backend addresses versions by their full content hash; the CLI echoes a
+// 12-char prefix for readability, matching Go's truncateHash.
+function truncateHash(hash: string): string {
+  return hash.length > 12 ? hash.slice(0, 12) : hash;
+}