@stigmer/cli 3.0.8

package/src/resources/execution-logs.ts

@@ -0,0 +1,176 @@
+// `execution logs` — event/message stream for an execution (agent or workflow).
+//
+// Mirrors Go's execution.WorkflowLogs + AgentLogs (logs_workflow.go /
+// logs_agent.go). The two execution families consume different primitives, and
+// that asymmetry is intentional:
+//
+//   - Workflows have a canonical, sequenced event log. Non-follow reads it via
+//     getEventLog (paginated); follow tails it via subscribeEvents. Both render
+//     through the shared workflow event renderer, so `logs` and `run workflow`
+//     speak the same vocabulary.
+//   - Agents have no event stream — only status snapshots (subscribe). So agent
+//     follow diffs the message list across snapshots (lastMsgCount) and stops on
+//     a terminal phase, exactly as Go does; non-follow prints the message list
+//     from a single Get.
+//
+// Ctrl-C ends a follow cleanly: the SIGINT aborts the subscription and we treat
+// the abort as a normal exit (no stack trace).
+
+import { create } from "@bufbuild/protobuf";
+import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  GetEventLogRequestSchema,
+  SubscribeEventsRequestSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { shouldColorize, styler } from "../output/style.js";
+import { formatAgentPhase, isTerminalAgentPhase, resolveExecutionType } from "./execution.js";
+import { type LineSink, renderWorkflowEventPlaintext } from "./stream/workflow-render-plaintext.js";
+
+const EVENT_LOG_PAGE_SIZE = 50;
+const MAX_AGENT_MESSAGE_LEN = 200;
+
+export interface LogsOptions {
+  readonly executionId: string;
+  readonly follow: boolean;
+  /** Workflow-only: filter events by task name. */
+  readonly task?: string;
+}
+
+/** A line sink + a signal that the caller can abort (SIGINT). */
+export interface LogsStreams {
+  readonly out: LineSink;
+  readonly colorize: boolean;
+}
+
+/** Stream or print logs for an execution. `signal` aborts a follow cleanly. */
+export async function streamExecutionLogs(
+  client: Stigmer,
+  opts: LogsOptions,
+  signal: AbortSignal,
+  streams: LogsStreams = defaultStreams(),
+): Promise<void> {
+  const type = resolveExecutionType(opts.executionId);
+  if (type === "workflow") {
+    await (opts.follow ? followWorkflowLogs(client, opts, signal, streams) : printWorkflowLog(client, opts, streams));
+    return;
+  }
+  await (opts.follow ? followAgentLogs(client, opts, signal, streams) : printAgentMessages(client, opts, streams));
+}
+
+async function printWorkflowLog(client: Stigmer, opts: LogsOptions, streams: LogsStreams): Promise<void> {
+  const resp = await client.workflowExecution.getEventLog(
+    create(GetEventLogRequestSchema, {
+      executionId: opts.executionId,
+      pageSize: EVENT_LOG_PAGE_SIZE,
+      ...(opts.task ? { taskName: opts.task } : {}),
+    }),
+  );
+  if (resp.events.length === 0) {
+    streams.out.write("No events recorded for this execution.\n");
+    return;
+  }
+  for (const event of resp.events) renderWorkflowEventPlaintext(event, streams.out, streams.colorize);
+  if (resp.hasMore) {
+    streams.out.write(`\n... more events available (showing first ${resp.events.length})\n`);
+  }
+}
+
+async function followWorkflowLogs(
+  client: Stigmer,
+  opts: LogsOptions,
+  signal: AbortSignal,
+  streams: LogsStreams,
+): Promise<void> {
+  const stream = client.workflowExecution.subscribeEvents(
+    create(SubscribeEventsRequestSchema, { executionId: opts.executionId }),
+    signal,
+  );
+  try {
+    for await (const event of stream) {
+      // Client-side task filter, matching Go's streamWorkflowEvents.
+      if (opts.task !== undefined && opts.task !== "" && event.taskName !== opts.task) continue;
+      renderWorkflowEventPlaintext(event, streams.out, streams.colorize);
+    }
+    streams.out.write("\n--- stream ended ---\n");
+  } catch (error) {
+    if (signal.aborted) return;
+    throw error;
+  }
+}
+
+async function printAgentMessages(client: Stigmer, opts: LogsOptions, streams: LogsStreams): Promise<void> {
+  const exec = await client.agentExecution.get(opts.executionId);
+  const messages = exec.status?.messages ?? [];
+  if (messages.length === 0) {
+    streams.out.write("No messages recorded for this execution.\n");
+    return;
+  }
+  for (const message of messages) renderAgentMessage(message, streams);
+}
+
+async function followAgentLogs(
+  client: Stigmer,
+  opts: LogsOptions,
+  signal: AbortSignal,
+  streams: LogsStreams,
+): Promise<void> {
+  let lastMsgCount = 0;
+  try {
+    for await (const exec of client.agentExecution.subscribe(opts.executionId, signal)) {
+      const messages = exec.status?.messages ?? [];
+      for (let i = lastMsgCount; i < messages.length; i++) renderAgentMessage(messages[i], streams);
+      lastMsgCount = messages.length;
+
+      const phase = exec.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+      if (isTerminalAgentPhase(phase)) {
+        const style = styler(streams.colorize);
+        streams.out.write(`\n${style.dim("[end]")} execution ${formatAgentPhase(phase)}\n`);
+        return;
+      }
+    }
+    streams.out.write("\n--- stream ended ---\n");
+  } catch (error) {
+    if (signal.aborted) return;
+    throw error;
+  }
+}
+
+// Port of Go's renderAgentMessage: a colored type label + truncated content.
+function renderAgentMessage(message: AgentMessage, streams: LogsStreams): void {
+  const style = styler(streams.colorize);
+  const { label, tint } = agentMessageLabel(message.type, style);
+  const content = truncate(message.content, MAX_AGENT_MESSAGE_LEN);
+  streams.out.write(`[${tint(label)}] ${content}\n`);
+}
+
+function agentMessageLabel(
+  type: MessageType,
+  style: ReturnType<typeof styler>,
+): { label: string; tint: (text: string) => string } {
+  switch (type) {
+    case MessageType.MESSAGE_HUMAN:
+      return { label: "human", tint: style.cyan };
+    case MessageType.MESSAGE_AI:
+      return { label: "ai", tint: style.green };
+    case MessageType.MESSAGE_TOOL:
+      return { label: "tool", tint: style.cyan };
+    case MessageType.MESSAGE_SYSTEM:
+      return { label: "system", tint: style.yellow };
+    default:
+      return { label: "unknown", tint: style.dim };
+  }
+}
+
+// Mirrors Go's 200-char content cap (197 + "...").
+function truncate(value: string, maxLen: number): string {
+  return value.length > maxLen ? `${value.slice(0, maxLen - 3)}...` : value;
+}
+
+function defaultStreams(): LogsStreams {
+  return {
+    out: { write: (line: string) => void process.stdout.write(line) },
+    colorize: shouldColorize(process.stdout),
+  };
+}

package/src/resources/execution-trace.ts

@@ -0,0 +1,159 @@
+// `execution trace` — task/tool structure and timing for an execution.
+//
+// Mirrors Go's execution.Trace (trace.go + trace_workflow.go + trace_agent.go):
+// auto-detect the type, and for table output render a compact structure view —
+// workflow task rows (status icon, name, duration, type, error) or the agent's
+// tool-call timeline. For yaml/json, defer to the standard proto renderers so
+// `trace -o json` and `get -o json` produce the identical envelope.
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { WorkflowExecution, WorkflowTask } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowTaskStatus } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { renderProtoJson, renderProtoYaml } from "../output/index.js";
+import { type Styler, shouldColorize, styler } from "../output/style.js";
+import { calculateDuration, formatWorkflowTaskType, truncateWithEllipsis } from "./execution-format.js";
+import { formatAgentPhase, formatWorkflowPhase, resolveExecutionType } from "./execution.js";
+
+/** Output format for trace: a compact structure table, or the full proto envelope. */
+export type TraceFormat = "table" | "yaml" | "json";
+
+export interface TraceStreams {
+  write(text: string): void;
+  readonly colorize: boolean;
+}
+
+/** Fetch and render an execution's structure. */
+export async function traceExecution(
+  client: Stigmer,
+  executionId: string,
+  format: TraceFormat,
+  streams: TraceStreams = defaultStreams(),
+): Promise<void> {
+  if (resolveExecutionType(executionId) === "workflow") {
+    const exec = await client.workflowExecution.get(executionId);
+    if (format === "yaml") {
+      streams.write(renderProtoYaml(WorkflowExecutionSchema, exec));
+      return;
+    }
+    if (format === "json") {
+      streams.write(renderProtoJson(WorkflowExecutionSchema, exec));
+      return;
+    }
+    renderWorkflowTrace(exec, streams);
+    return;
+  }
+
+  const exec = await client.agentExecution.get(executionId);
+  if (format === "yaml") {
+    streams.write(renderProtoYaml(AgentExecutionSchema, exec));
+    return;
+  }
+  if (format === "json") {
+    streams.write(renderProtoJson(AgentExecutionSchema, exec));
+    return;
+  }
+  renderAgentTrace(exec, streams);
+}
+
+function renderWorkflowTrace(exec: WorkflowExecution, streams: TraceStreams): void {
+  const style = styler(streams.colorize);
+  const name = exec.metadata?.name || exec.metadata?.id || "";
+  const phase = formatWorkflowPhase(exec.status?.phase ?? 0);
+  const duration = calculateDuration(exec.status?.startedAt ?? "", exec.status?.completedAt ?? "");
+
+  streams.write(`\nWorkflow: ${name} (${phase}, ${duration})\n\n`);
+
+  const tasks = exec.status?.tasks ?? [];
+  if (tasks.length === 0) {
+    streams.write("  (no tasks recorded)\n\n");
+    return;
+  }
+  for (const task of tasks) renderWorkflowTraceTask(task, style, streams);
+  streams.write("\n");
+}
+
+function renderWorkflowTraceTask(task: WorkflowTask, style: Styler, streams: TraceStreams): void {
+  const icon = workflowTaskStatusIcon(task.status, style);
+  const taskName = task.taskName || task.taskId;
+  const duration = calculateDuration(task.startedAt, task.completedAt);
+  const taskType = style.dim(formatWorkflowTaskType(task.taskType));
+
+  streams.write(`  ${icon} ${pad(truncateWithEllipsis(taskName, 25), 25)}  ${pad(duration, 8)}  ${taskType}\n`);
+  if (task.error !== "") {
+    streams.write(`       ${style.red(truncateWithEllipsis(task.error, 70))}\n`);
+  }
+}
+
+function workflowTaskStatusIcon(status: WorkflowTaskStatus, style: Styler): string {
+  switch (status) {
+    case WorkflowTaskStatus.WORKFLOW_TASK_COMPLETED:
+      return style.green("[done]");
+    case WorkflowTaskStatus.WORKFLOW_TASK_IN_PROGRESS:
+      return style.cyan("[run ]");
+    case WorkflowTaskStatus.WORKFLOW_TASK_PENDING:
+      return style.dim("[    ]");
+    case WorkflowTaskStatus.WORKFLOW_TASK_FAILED:
+      return style.red("[fail]");
+    case WorkflowTaskStatus.WORKFLOW_TASK_SKIPPED:
+      return style.dim("[skip]");
+    case WorkflowTaskStatus.WORKFLOW_TASK_WAITING_APPROVAL:
+      return style.yellow("[wait]");
+    default:
+      return "[ ?? ]";
+  }
+}
+
+function renderAgentTrace(exec: AgentExecution, streams: TraceStreams): void {
+  const style = styler(streams.colorize);
+  const name = exec.metadata?.name || exec.metadata?.id || "";
+  const phase = formatAgentPhase(exec.status?.phase ?? 0);
+  const duration = calculateDuration(exec.status?.startedAt ?? "", exec.status?.completedAt ?? "");
+
+  streams.write(`\nAgent: ${name} (${phase}, ${duration})\n\n`);
+
+  const messages = exec.status?.messages ?? [];
+  if (messages.length === 0) {
+    streams.write("  (no messages recorded)\n\n");
+    return;
+  }
+
+  const toolCalls = extractToolCallSummaries(exec);
+  if (toolCalls.length === 0) {
+    streams.write(`  ${messages.length} message(s), no tool calls\n\n`);
+    return;
+  }
+  for (const call of toolCalls) {
+    streams.write(`  ${style.green("[done]")} ${pad(truncateWithEllipsis(call.name, 25), 25)}  ${style.dim(truncateWithEllipsis(call.summary, 40))}\n`);
+  }
+  streams.write("\n");
+}
+
+interface ToolCallSummary {
+  readonly name: string;
+  readonly summary: string;
+}
+
+// Mirrors Go's extractToolCallSummary: tool calls on AI messages, with results
+// truncated to 40 chars.
+function extractToolCallSummaries(exec: AgentExecution): ToolCallSummary[] {
+  const calls: ToolCallSummary[] = [];
+  for (const message of exec.status?.messages ?? []) {
+    if (message.type !== MessageType.MESSAGE_AI) continue;
+    for (const tc of message.toolCalls) {
+      calls.push({ name: tc.name || "tool_call", summary: truncateWithEllipsis(tc.result, 40) });
+    }
+  }
+  return calls;
+}
+
+function pad(value: string, width: number): string {
+  return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+
+function defaultStreams(): TraceStreams {
+  return { write: (text: string) => void process.stdout.write(text), colorize: shouldColorize(process.stdout) };
+}

package/src/resources/execution.integration.test.ts

@@ -0,0 +1,285 @@
+// In-process integration test for the `execution` group resources.
+//
+// Stands up a real Connect backend over h2c serving the agent + workflow
+// execution query and command controllers (including the server-streaming
+// subscribe / subscribeEvents methods), points an SDK node client at it, and
+// drives the resource layer end to end: lifecycle control, approval submission
+// (asserting D-EX-1 comment carry + D-EX-2 reviewer-unset), trace rendering, and
+// log streaming (workflow event stream + agent snapshot diffing).
+
+import { create } from "@bufbuild/protobuf";
+import type { ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
+import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { SubmitApprovalInput } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { ExecutionPhase as WorkflowExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import {
+  GetEventLogResponseSchema,
+  type SubmitWorkflowTaskApprovalInput,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import {
+  WorkflowExecutionEventSchema,
+  WorkflowEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
+import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
+import type { AddressInfo } from "node:net";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { approveAgentToolCall, approveWorkflowTask } from "./execution-approve.js";
+import { cancelExecution, pauseExecution, resumeExecution, terminateExecution } from "./execution-control.js";
+import { streamExecutionLogs } from "./execution-logs.js";
+import { traceExecution } from "./execution-trace.js";
+
+let backend: Http2Server;
+let client: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+// Spies for the command-side calls, reset per test.
+let agentControl: { verb: string; id: string; reason: string }[] = [];
+let workflowControl: { verb: string; id: string; reason: string }[] = [];
+let agentApproval: SubmitApprovalInput[] = [];
+let workflowApproval: SubmitWorkflowTaskApprovalInput[] = [];
+
+beforeEach(() => {
+  agentControl = [];
+  workflowControl = [];
+  agentApproval = [];
+  workflowApproval = [];
+});
+
+// A workflow execution with two tasks (one done, one failed) for the trace view.
+const workflowExec = create(WorkflowExecutionSchema, {
+  metadata: { id: "wex_1", name: "Deploy" },
+  status: {
+    phase: WorkflowExecutionPhase.EXECUTION_COMPLETED,
+    startedAt: "2026-06-12T10:00:00Z",
+    completedAt: "2026-06-12T10:01:30Z",
+    tasks: [
+      { taskName: "build", status: 3, taskType: 1, startedAt: "2026-06-12T10:00:00Z", completedAt: "2026-06-12T10:00:30Z" },
+      { taskName: "ship", status: 4, taskType: 1, error: "registry down" },
+    ],
+  },
+});
+
+// An agent execution carrying two messages for the agent log + trace views.
+const agentExec = create(AgentExecutionSchema, {
+  metadata: { id: "aex_1", name: "Reviewer" },
+  status: {
+    phase: ExecutionPhase.EXECUTION_COMPLETED,
+    startedAt: "2026-06-12T10:00:00Z",
+    completedAt: "2026-06-12T10:00:20Z",
+    messages: [
+      { type: MessageType.MESSAGE_HUMAN, content: "do it" },
+      { type: MessageType.MESSAGE_AI, content: "done", toolCalls: [{ name: "Shell", result: "ok" }] },
+    ],
+  },
+});
+
+function controlResult(phase: ExecutionPhase) {
+  return create(AgentExecutionSchema, { metadata: { id: "aex_1" }, status: { phase } });
+}
+function workflowControlResult(phase: WorkflowExecutionPhase) {
+  return create(WorkflowExecutionSchema, { metadata: { id: "wex_1" }, status: { phase } });
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentExecutionQueryController, {
+      get: () => agentExec,
+      subscribe: async function* () {
+        yield create(AgentExecutionSchema, {
+          metadata: { id: "aex_1" },
+          status: { phase: ExecutionPhase.EXECUTION_IN_PROGRESS, messages: [{ type: MessageType.MESSAGE_AI, content: "thinking" }] },
+        });
+        yield create(AgentExecutionSchema, {
+          metadata: { id: "aex_1" },
+          status: {
+            phase: ExecutionPhase.EXECUTION_COMPLETED,
+            messages: [
+              { type: MessageType.MESSAGE_AI, content: "thinking" },
+              { type: MessageType.MESSAGE_AI, content: "final answer" },
+            ],
+          },
+        });
+      },
+    });
+    router.service(AgentExecutionCommandController, {
+      cancel: (req) => (agentControl.push({ verb: "cancel", id: req.id, reason: req.reason }), controlResult(ExecutionPhase.EXECUTION_CANCELLED)),
+      terminate: (req) => (agentControl.push({ verb: "terminate", id: req.id, reason: req.reason }), controlResult(ExecutionPhase.EXECUTION_TERMINATED)),
+      pause: (req) => (agentControl.push({ verb: "pause", id: req.id, reason: req.reason }), controlResult(ExecutionPhase.EXECUTION_PAUSED)),
+      resume: (req) => (agentControl.push({ verb: "resume", id: req.id, reason: "" }), controlResult(ExecutionPhase.EXECUTION_IN_PROGRESS)),
+      submitApproval: (req) => (agentApproval.push(req), agentExec),
+    });
+
+    router.service(WorkflowExecutionQueryController, {
+      get: () => workflowExec,
+      getEventLog: () =>
+        create(GetEventLogResponseSchema, {
+          hasMore: true,
+          events: [
+            create(WorkflowExecutionEventSchema, {
+              eventType: WorkflowEventType.execution_started,
+              occurredAt: "2026-06-12T10:00:00Z",
+              payload: { case: "executionStarted", value: {} as never },
+            }),
+          ],
+        }),
+      subscribeEvents: async function* () {
+        yield create(WorkflowExecutionEventSchema, {
+          eventType: WorkflowEventType.task_started,
+          occurredAt: "2026-06-12T10:00:01Z",
+          taskName: "build",
+          payload: { case: "taskStarted", value: {} as never },
+        });
+        yield create(WorkflowExecutionEventSchema, {
+          eventType: WorkflowEventType.task_completed,
+          occurredAt: "2026-06-12T10:00:05Z",
+          taskName: "other",
+          payload: { case: "taskCompleted", value: {} as never },
+        });
+      },
+    });
+    router.service(WorkflowExecutionCommandController, {
+      cancel: (req) => (workflowControl.push({ verb: "cancel", id: req.id, reason: req.reason }), workflowControlResult(WorkflowExecutionPhase.EXECUTION_CANCELLED)),
+      terminate: (req) => (workflowControl.push({ verb: "terminate", id: req.id, reason: req.reason }), workflowControlResult(WorkflowExecutionPhase.EXECUTION_TERMINATED)),
+      pause: (req) => (workflowControl.push({ verb: "pause", id: req.id, reason: req.reason }), workflowControlResult(WorkflowExecutionPhase.EXECUTION_PAUSED)),
+      resume: (req) => (workflowControl.push({ verb: "resume", id: req.id, reason: "" }), workflowControlResult(WorkflowExecutionPhase.EXECUTION_IN_PROGRESS)),
+      submitWorkflowTaskApproval: (req) => (workflowApproval.push(req), workflowExec),
+    });
+  };
+
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+  client = createNodeClient({ baseUrl: normalizeEndpoint(`127.0.0.1:${port}`) });
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("lifecycle control", () => {
+  it("cancels an agent execution and reports the phase", async () => {
+    const result = await cancelExecution(client, "aex_1", "no longer needed");
+    expect(result).toEqual({ type: "agent", phase: "cancelled" });
+    expect(agentControl).toEqual([{ verb: "cancel", id: "aex_1", reason: "no longer needed" }]);
+  });
+
+  it("terminates / pauses an agent execution", async () => {
+    expect((await terminateExecution(client, "aex_1", "stuck")).phase).toBe("terminated");
+    expect((await pauseExecution(client, "aex_1", "")).phase).toBe("paused");
+    expect(agentControl.map((c) => c.verb)).toEqual(["terminate", "pause"]);
+  });
+
+  it("cancels / resumes a workflow execution", async () => {
+    expect((await cancelExecution(client, "wex_1", "")).phase).toBe("cancelled");
+    expect((await resumeExecution(client, "wex_1")).phase).toBe("running");
+    expect(workflowControl.map((c) => c.verb)).toEqual(["cancel", "resume"]);
+  });
+});
+
+describe("approval submission", () => {
+  it("carries --comment onto the agent SubmitApprovalInput (D-EX-1)", async () => {
+    await approveAgentToolCall(client, { executionId: "aex_1", toolCallId: "tc_1", action: "deny", comment: "unsafe" });
+    expect(agentApproval).toHaveLength(1);
+    expect(agentApproval[0].comment).toBe("unsafe");
+    expect(agentApproval[0].toolCallId).toBe("tc_1");
+    // "deny" maps to REJECT (3).
+    expect(agentApproval[0].action).toBe(3);
+  });
+
+  it("leaves the workflow reviewer unset (D-EX-2 — server-attributed)", async () => {
+    await approveWorkflowTask(client, { executionId: "wex_1", taskName: "review", outcome: "approve", comment: "lgtm" });
+    expect(workflowApproval).toHaveLength(1);
+    expect(workflowApproval[0].reviewer).toBe("");
+    expect(workflowApproval[0].comment).toBe("lgtm");
+    expect(workflowApproval[0].outcome).toBe("approve");
+  });
+});
+
+describe("trace", () => {
+  function capture() {
+    const chunks: string[] = [];
+    return { streams: { write: (t: string) => chunks.push(t), colorize: false }, text: () => chunks.join("") };
+  }
+
+  it("renders a workflow task table", async () => {
+    const cap = capture();
+    await traceExecution(client, "wex_1", "table", cap.streams);
+    const text = cap.text();
+    expect(text).toContain("Workflow: Deploy (completed, 1m 30s)");
+    expect(text).toContain("[done] build");
+    expect(text).toContain("[fail] ship");
+    expect(text).toContain("registry down");
+  });
+
+  it("renders the agent tool-call timeline", async () => {
+    const cap = capture();
+    await traceExecution(client, "aex_1", "table", cap.streams);
+    expect(cap.text()).toContain("Agent: Reviewer (completed, 20s)");
+    expect(cap.text()).toContain("[done] Shell");
+  });
+
+  it("emits the full proto envelope for json", async () => {
+    const cap = capture();
+    await traceExecution(client, "wex_1", "json", cap.streams);
+    const json = JSON.parse(cap.text());
+    expect(json.metadata.id).toBe("wex_1");
+    expect(json.status.tasks).toHaveLength(2);
+  });
+});
+
+describe("logs", () => {
+  function capture() {
+    const lines: string[] = [];
+    return { streams: { out: { write: (l: string) => lines.push(l) }, colorize: false }, lines };
+  }
+  const never = new AbortController().signal;
+
+  it("prints the workflow event log with a more-available notice", async () => {
+    const cap = capture();
+    await streamExecutionLogs(client, { executionId: "wex_1", follow: false }, never, cap.streams);
+    const text = cap.lines.join("");
+    expect(text).toContain("execution started");
+    expect(text).toContain("more events available");
+  });
+
+  it("drains the workflow event stream on --follow with a task filter", async () => {
+    const cap = capture();
+    await streamExecutionLogs(client, { executionId: "wex_1", follow: true, task: "build" }, never, cap.streams);
+    const text = cap.lines.join("");
+    expect(text).toContain("task started: build");
+    // "other" task is filtered out.
+    expect(text).not.toContain("task completed: other");
+    expect(text).toContain("--- stream ended ---");
+  });
+
+  it("prints agent messages from a single snapshot when not following", async () => {
+    const cap = capture();
+    await streamExecutionLogs(client, { executionId: "aex_1", follow: false }, never, cap.streams);
+    const text = cap.lines.join("");
+    expect(text).toContain("[human] do it");
+    expect(text).toContain("[ai] done");
+  });
+
+  it("diffs agent snapshots on --follow and stops on the terminal phase", async () => {
+    const cap = capture();
+    await streamExecutionLogs(client, { executionId: "aex_1", follow: true }, never, cap.streams);
+    const text = cap.lines.join("");
+    expect(text).toContain("[ai] thinking");
+    expect(text).toContain("[ai] final answer");
+    expect(text).toContain("[end] execution completed");
+  });
+});