@stigmer/cli 3.0.8

package/src/resources/documents.ts

@@ -0,0 +1,102 @@
+// Shared YAML document loading for the file-based verbs (validate, diff, apply).
+//
+// One loader, two strictness modes (the S-strict decision):
+//   - lenient (default) — tolerates malformed YAML the same way Wave-1 validate
+//     did; `toJS()` best-effort, no error surfacing.
+//   - strict — rejects any document with YAML parse errors. Used by `apply`,
+//     where silently applying a half-parsed document would be dangerous.
+//
+// Each loaded document carries its parsed JSON value (for kind detection and
+// schema work) and its raw text (for `diff`, which compares the user's authored
+// bytes against the rendered remote state).
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import type { JsonValue } from "@bufbuild/protobuf";
+import { parseAllDocuments } from "yaml";
+import { UsageError } from "../errors/index.js";
+
+export interface LoadedDocument {
+  readonly kind: string;
+  readonly document: JsonValue;
+  /** Raw YAML text of this document (whole file when single-document). */
+  readonly raw: string;
+}
+
+export interface LoadOptions {
+  /** Reject documents with YAML parse errors (apply); off mirrors Wave-1 validate. */
+  readonly strict?: boolean;
+}
+
+/** Expand a path into the YAML files it covers (single file, or dir walk). */
+export function resolveYamlFiles(path: string): string[] {
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(path);
+  } catch (err) {
+    // A path the user typed that doesn't exist is a bad argument, not an
+    // unexpected I/O failure — surface it as a usage error.
+    throw new UsageError(`cannot access ${path}: ${(err as Error).message}`);
+  }
+  if (!stat.isDirectory()) return [path];
+
+  const files: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (isYaml(full)) {
+        files.push(full);
+      }
+    }
+  };
+  walk(path);
+  return files;
+}
+
+/** Parse a file's YAML documents, detecting each document's `kind`. */
+export function loadDocuments(file: string, options: LoadOptions = {}): LoadedDocument[] {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (err) {
+    throw new Error(`cannot read ${file}: ${(err as Error).message}`);
+  }
+
+  const docs = parseAllDocuments(text);
+  const singleDocument = docs.length === 1;
+  const results: LoadedDocument[] = [];
+
+  for (const doc of docs) {
+    if (options.strict === true && doc.errors.length > 0) {
+      throw new UsageError(`invalid YAML in ${file}: ${doc.errors[0].message}`);
+    }
+    const value = doc.toJS() as unknown;
+    if (value === null || value === undefined) continue;
+    if (typeof value !== "object") {
+      throw new UsageError(`invalid YAML document in ${file}`);
+    }
+    const kind = (value as Record<string, unknown>).kind;
+    if (typeof kind !== "string" || kind === "") {
+      throw new UsageError(`missing 'kind' field in ${file}`);
+    }
+    results.push({ kind, document: value as JsonValue, raw: rawText(text, doc, singleDocument) });
+  }
+  return results;
+}
+
+// The `yaml` Document exposes a [valueStart, valueEnd, nodeEnd] range into the
+// source. For multi-document files we slice per document; a single document is
+// just the whole file (matching Go's RawContent for the common case).
+function rawText(source: string, doc: { range?: readonly [number, number, number] | null }, single: boolean): string {
+  if (single) return source;
+  const range = doc.range;
+  if (range === undefined || range === null) return source;
+  return source.slice(range[0], range[2]);
+}
+
+function isYaml(file: string): boolean {
+  const ext = extname(file).toLowerCase();
+  return ext === ".yaml" || ext === ".yml";
+}

package/src/resources/download.ts

@@ -0,0 +1,151 @@
+// `download execution`: stream an execution's artifacts to disk via short-lived
+// presigned URLs. Partial-failure tolerant — a failed artifact is reported and
+// skipped, never aborting the batch (mirrors Go's downloadExecutionArtifacts).
+
+import { createWriteStream, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { ReadableStream as NodeReadableStream } from "node:stream/web";
+import { create } from "@bufbuild/protobuf";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { GetArtifactDownloadUrlRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { CliExitError, ExitCode } from "../errors/index.js";
+import { formatBytes } from "./skill.js";
+
+export interface DownloadParams {
+  readonly artifactName: string;
+  readonly outputDir: string;
+}
+
+export interface DownloadOutcome {
+  readonly total: number;
+  readonly downloaded: number;
+  readonly noArtifacts: boolean;
+  /** Set when the execution is not yet terminal (a soft warning, not an error). */
+  readonly incompletePhase?: string;
+}
+
+/** A sink for human progress/warning lines (download is not byte-parity output). */
+export type ProgressSink = (line: string) => void;
+
+const TERMINAL_PHASES: ReadonlySet<ExecutionPhase> = new Set([
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+export async function downloadExecutionArtifacts(
+  client: Stigmer,
+  executionId: string,
+  params: DownloadParams,
+  progress?: ProgressSink,
+): Promise<DownloadOutcome> {
+  const execution = await client.agentExecution.get(executionId);
+  const phase = execution.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+  const incompletePhase = TERMINAL_PHASES.has(phase) ? undefined : formatDownloadPhase(phase);
+  if (incompletePhase !== undefined) {
+    progress?.(`Execution is still ${incompletePhase}. Artifacts may not be complete until execution finishes.`);
+  }
+
+  let artifacts = execution.status?.artifacts ?? [];
+  if (artifacts.length === 0) {
+    return { total: 0, downloaded: 0, noArtifacts: true, incompletePhase };
+  }
+
+  if (params.artifactName !== "") {
+    artifacts = artifacts.filter((a) => a.name === params.artifactName);
+    if (artifacts.length === 0) {
+      throw new CliExitError(
+        `artifact not found: ${params.artifactName}\n\n` +
+          `Use 'stigmer get execution ${executionId}' to see available artifacts`,
+        ExitCode.General,
+      );
+    }
+  }
+
+  mkdirSync(params.outputDir, { recursive: true });
+
+  let downloaded = 0;
+  for (const artifact of artifacts) {
+    try {
+      const written = await downloadSingle(client, executionId, artifact, params.outputDir, progress);
+      progress?.(`  Downloaded ${artifact.name} (${formatBytes(written)})`);
+      downloaded++;
+    } catch (err) {
+      progress?.(`  Failed to download ${artifact.name}: ${(err as Error).message}`);
+    }
+  }
+
+  return { total: artifacts.length, downloaded, noArtifacts: false, incompletePhase };
+}
+
+async function downloadSingle(
+  client: Stigmer,
+  executionId: string,
+  artifact: ExecutionArtifact,
+  outputDir: string,
+  progress?: ProgressSink,
+): Promise<number> {
+  const url = await resolveDownloadUrl(client, executionId, artifact);
+  const destPath = join(outputDir, artifact.name);
+  mkdirSync(dirname(destPath), { recursive: true });
+
+  progress?.(`  Downloading ${artifact.name} (${formatBytes(Number(artifact.sizeBytes))})...`);
+
+  const response = await fetch(url);
+  if (!response.ok || response.body === null) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+
+  let written = 0;
+  const counter = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      written += chunk.byteLength;
+      controller.enqueue(chunk);
+    },
+  });
+  // The CLI compiles with the `dom` lib (for in-process Ink/React), so `fetch`'s
+  // body types as the DOM ReadableStream. `Readable.fromWeb` wants Node's
+  // stream/web variant; they are structurally identical at runtime, so we bridge
+  // the two type worlds at this single boundary.
+  const counted = response.body.pipeThrough(counter) as unknown as NodeReadableStream<Uint8Array>;
+  await pipeline(Readable.fromWeb(counted), createWriteStream(destPath));
+  return written;
+}
+
+/**
+ * Get a fresh presigned URL, falling back to the artifact's cached URL when the
+ * refresh RPC fails (matching Go: prefer fresh, tolerate transient gRPC errors).
+ */
+async function resolveDownloadUrl(client: Stigmer, executionId: string, artifact: ExecutionArtifact): Promise<string> {
+  try {
+    const response = await client.agentExecution.getArtifactDownloadUrl(
+      create(GetArtifactDownloadUrlRequestSchema, { executionId, storageKey: artifact.storageKey }),
+    );
+    if (response.downloadUrl !== "") return response.downloadUrl;
+  } catch {
+    // Fall through to the cached URL below.
+  }
+  if (artifact.downloadUrl !== "") return artifact.downloadUrl;
+  throw new Error("failed to get download URL");
+}
+
+// Human-readable non-terminal phase label (matches Go's formatPhaseForDownload).
+function formatDownloadPhase(phase: ExecutionPhase): string {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_PENDING:
+      return "pending";
+    case ExecutionPhase.EXECUTION_IN_PROGRESS:
+      return "in progress";
+    case ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL:
+      return "waiting for approval";
+    case ExecutionPhase.EXECUTION_PAUSED:
+      return "paused";
+    default:
+      return "unknown";
+  }
+}

package/src/resources/execution-approve.test.ts

@@ -0,0 +1,50 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { classify, ExitCode } from "../errors/index.js";
+import { readFormData } from "./execution-approve.js";
+
+const dirs: string[] = [];
+
+async function tempFile(name: string, contents: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "stigmer-approve-"));
+  dirs.push(dir);
+  const path = join(dir, name);
+  await writeFile(path, contents, "utf8");
+  return path;
+}
+
+afterAll(() => {
+  // mkdtemp dirs are small and OS-cleaned; nothing to do but keep the ref alive.
+  void dirs;
+});
+
+describe("readFormData", () => {
+  it("returns undefined when no path is given", async () => {
+    expect(await readFormData(undefined)).toBeUndefined();
+    expect(await readFormData("")).toBeUndefined();
+  });
+
+  it("parses a JSON object", async () => {
+    const path = await tempFile("form.json", JSON.stringify({ approved: true, note: "ok" }));
+    expect(await readFormData(path)).toEqual({ approved: true, note: "ok" });
+  });
+
+  it("rejects a missing file with a usage error", async () => {
+    const err = await readFormData("/no/such/file.json").catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+
+  it("rejects malformed JSON with a usage error", async () => {
+    const path = await tempFile("bad.json", "{ not valid");
+    const err = await readFormData(path).catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+
+  it("rejects a non-object JSON value with a usage error", async () => {
+    const path = await tempFile("array.json", "[1, 2, 3]");
+    const err = await readFormData(path).catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+});

package/src/resources/execution-approve.ts

@@ -0,0 +1,94 @@
+// `execution approve` — submit an approval decision for a waiting execution.
+//
+// Mirrors Go's execution.ApproveWorkflow / ApproveAgent (approve.go), with two
+// deliberate corrections over the Go behavior:
+//
+//   - D-EX-1 (fixed here): the agent `--comment` is carried onto
+//     SubmitApprovalInput.comment. The field exists on the proto; Go accepted the
+//     flag then dropped it. We thread it through.
+//   - D-EX-2 (match Go, backend follow-up): the workflow `reviewer` field is left
+//     unset by the client. Reviewer is an audit identity and must be attributed
+//     server-side from the authenticated principal — a client-supplied identity
+//     is spoofable. The backend follow-up is to populate it from the token.
+
+import { readFile } from "node:fs/promises";
+import { type JsonObject } from "@bufbuild/protobuf";
+import { create } from "@bufbuild/protobuf";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SubmitApprovalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { SubmitWorkflowTaskApprovalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { UsageError } from "../errors/index.js";
+
+export interface ApproveWorkflowOptions {
+  readonly executionId: string;
+  readonly taskName: string;
+  readonly outcome: string;
+  readonly comment: string;
+  readonly formData?: JsonObject;
+}
+
+/** Submit a workflow task approval. `reviewer` stays unset (server-attributed). */
+export async function approveWorkflowTask(client: Stigmer, opts: ApproveWorkflowOptions): Promise<void> {
+  await client.workflowExecution.submitWorkflowTaskApproval(
+    create(SubmitWorkflowTaskApprovalInputSchema, {
+      executionId: opts.executionId,
+      taskName: opts.taskName,
+      outcome: opts.outcome,
+      comment: opts.comment,
+      ...(opts.formData ? { formData: opts.formData } : {}),
+    }),
+  );
+}
+
+export interface ApproveAgentOptions {
+  readonly executionId: string;
+  readonly toolCallId: string;
+  readonly action: string;
+  readonly comment: string;
+}
+
+/** Submit an agent tool-call approval. `--comment` is carried through (D-EX-1). */
+export async function approveAgentToolCall(client: Stigmer, opts: ApproveAgentOptions): Promise<void> {
+  await client.agentExecution.submitApproval(
+    create(SubmitApprovalInputSchema, {
+      agentExecutionId: opts.executionId,
+      toolCallId: opts.toolCallId,
+      action: resolveApprovalAction(opts.action),
+      comment: opts.comment,
+    }),
+  );
+}
+
+// Mirrors Go's mapping: "deny"/"reject" → REJECT, everything else → APPROVE.
+function resolveApprovalAction(action: string): ApprovalAction {
+  return action === "deny" || action === "reject" ? ApprovalAction.REJECT : ApprovalAction.APPROVE;
+}
+
+/**
+ * Read and parse a `--data-file` JSON object for workflow form data. A missing
+ * path returns undefined; an unreadable file or non-object/invalid JSON is a
+ * usage error (bad input), mirroring Go's os.ReadFile + json.Unmarshal guards.
+ */
+export async function readFormData(path: string | undefined): Promise<JsonObject | undefined> {
+  if (path === undefined || path === "") return undefined;
+
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    throw new UsageError(`failed to read data file '${path}': ${(error as Error).message}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new UsageError(`failed to parse JSON in '${path}': ${(error as Error).message}`);
+  }
+
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new UsageError(`data file '${path}' must contain a JSON object`);
+  }
+  return parsed as JsonObject;
+}

package/src/resources/execution-control.ts

@@ -0,0 +1,78 @@
+// Lifecycle control for executions (cancel / terminate / pause / resume).
+//
+// Mirrors Go's execution.Cancel/Terminate/Pause/Resume (cancel.go + pause.go):
+// each verb auto-detects agent vs workflow from the ID prefix, issues the
+// matching controller RPC, and returns the resulting phase as a human label.
+// The phase is read back from the RPC response so the success line reports the
+// authoritative post-mutation state, exactly as the Go CLI does.
+//
+// These return a plain `{ type, phase }` rather than a CommandResult so the
+// command layer owns presentation (single source of the success wording).
+
+import { create } from "@bufbuild/protobuf";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  CancelAgentExecutionInputSchema,
+  PauseAgentExecutionInputSchema,
+  ResumeAgentExecutionInputSchema,
+  TerminateAgentExecutionInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { ExecutionPhase as WorkflowExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import {
+  CancelWorkflowExecutionInputSchema,
+  PauseWorkflowExecutionInputSchema,
+  ResumeWorkflowExecutionInputSchema,
+  TerminateWorkflowExecutionInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { type ExecutionType, formatAgentPhase, formatWorkflowPhase, resolveExecutionType } from "./execution.js";
+
+/** Outcome of a control verb: the resolved type and the post-mutation phase. */
+export interface ControlResult {
+  readonly type: ExecutionType;
+  readonly phase: string;
+}
+
+/** Gracefully cancel an execution (agent or workflow). Mirrors Go execution.Cancel. */
+export async function cancelExecution(client: Stigmer, id: string, reason: string): Promise<ControlResult> {
+  const type = resolveExecutionType(id);
+  if (type === "agent") {
+    const result = await client.agentExecution.cancel(create(CancelAgentExecutionInputSchema, { id, reason }));
+    return { type, phase: formatAgentPhase(result.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) };
+  }
+  const result = await client.workflowExecution.cancel(create(CancelWorkflowExecutionInputSchema, { id, reason }));
+  return { type, phase: formatWorkflowPhase(result.status?.phase ?? WorkflowExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) };
+}
+
+/** Force-stop an execution immediately (agent or workflow). Mirrors Go execution.Terminate. */
+export async function terminateExecution(client: Stigmer, id: string, reason: string): Promise<ControlResult> {
+  const type = resolveExecutionType(id);
+  if (type === "agent") {
+    const result = await client.agentExecution.terminate(create(TerminateAgentExecutionInputSchema, { id, reason }));
+    return { type, phase: formatAgentPhase(result.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) };
+  }
+  const result = await client.workflowExecution.terminate(create(TerminateWorkflowExecutionInputSchema, { id, reason }));
+  return { type, phase: formatWorkflowPhase(result.status?.phase ?? WorkflowExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) };
+}
+
+/** Pause a running execution (agent or workflow). Mirrors Go execution.Pause. */
+export async function pauseExecution(client: Stigmer, id: string, reason: string): Promise<ControlResult> {
+  const type = resolveExecutionType(id);
+  if (type === "agent") {
+    const result = await client.agentExecution.pause(create(PauseAgentExecutionInputSchema, { id, reason }));
+    return { type, phase: formatAgentPhase(result.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) };
+  }
+  const result = await client.workflowExecution.pause(create(PauseWorkflowExecutionInputSchema, { id, reason }));
+  return { type, phase: formatWorkflowPhase(result.status?.phase ?? WorkflowExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) };
+}
+
+/** Resume a paused execution (agent or workflow). Mirrors Go execution.Resume (no reason). */
+export async function resumeExecution(client: Stigmer, id: string): Promise<ControlResult> {
+  const type = resolveExecutionType(id);
+  if (type === "agent") {
+    const result = await client.agentExecution.resume(create(ResumeAgentExecutionInputSchema, { id }));
+    return { type, phase: formatAgentPhase(result.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) };
+  }
+  const result = await client.workflowExecution.resume(create(ResumeWorkflowExecutionInputSchema, { id }));
+  return { type, phase: formatWorkflowPhase(result.status?.phase ?? WorkflowExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) };
+}

package/src/resources/execution-format.test.ts

@@ -0,0 +1,48 @@
+import { WorkflowTaskType } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { describe, expect, it } from "vitest";
+import { calculateDuration, formatWorkflowTaskType, truncateWithEllipsis } from "./execution-format.js";
+
+describe("calculateDuration", () => {
+  it("returns '-' when a bound is missing or unparseable", () => {
+    expect(calculateDuration("", "2026-01-01T00:00:01Z")).toBe("-");
+    expect(calculateDuration("2026-01-01T00:00:00Z", "")).toBe("-");
+    expect(calculateDuration("not-a-date", "2026-01-01T00:00:01Z")).toBe("-");
+  });
+
+  it("formats sub-minute durations in seconds", () => {
+    expect(calculateDuration("2026-01-01T00:00:00Z", "2026-01-01T00:00:42Z")).toBe("42s");
+  });
+
+  it("formats sub-hour durations as minutes and seconds", () => {
+    expect(calculateDuration("2026-01-01T00:00:00Z", "2026-01-01T00:05:09Z")).toBe("5m 9s");
+  });
+
+  it("formats hour-plus durations as hours and minutes", () => {
+    expect(calculateDuration("2026-01-01T00:00:00Z", "2026-01-01T02:30:00Z")).toBe("2h 30m");
+  });
+});
+
+describe("truncateWithEllipsis", () => {
+  it("leaves short strings untouched", () => {
+    expect(truncateWithEllipsis("short", 10)).toBe("short");
+  });
+
+  it("truncates and appends an ellipsis", () => {
+    expect(truncateWithEllipsis("abcdefghij", 8)).toBe("abcde...");
+  });
+});
+
+describe("formatWorkflowTaskType", () => {
+  it.each([
+    [WorkflowTaskType.WORKFLOW_TASK_AGENT_INVOCATION, "agent"],
+    [WorkflowTaskType.WORKFLOW_TASK_APPROVAL, "approval"],
+    [WorkflowTaskType.WORKFLOW_TASK_API_CALL, "api_call"],
+    [WorkflowTaskType.WORKFLOW_TASK_CONDITIONAL, "condition"],
+    [WorkflowTaskType.WORKFLOW_TASK_PARALLEL, "parallel"],
+    [WorkflowTaskType.WORKFLOW_TASK_TRANSFORM, "transform"],
+    [WorkflowTaskType.WORKFLOW_TASK_CUSTOM, "custom"],
+    [WorkflowTaskType.WORKFLOW_TASK_TYPE_UNSPECIFIED, "unknown"],
+  ])("%s -> %s", (type, expected) => {
+    expect(formatWorkflowTaskType(type)).toBe(expected);
+  });
+});

package/src/resources/execution-format.ts

@@ -0,0 +1,54 @@
+// Shared, presentation-only formatters for execution output.
+//
+// These mirror helpers in Go's pkg/display + internal/cli/execution (duration
+// math, ellipsis truncation, workflow task-type labels). They live here, away
+// from any RPC code, so both `execution trace` and the `run workflow` epilogue
+// format durations and task types identically without duplicating the logic.
+
+import { WorkflowTaskType } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+
+/**
+ * Human duration between two ISO 8601 timestamps. Mirrors Go's calculateDuration:
+ * "-" when either bound is missing/unparseable, "<n>s" under a minute,
+ * "<m>m <s>s" under an hour, "<h>h <m>m" otherwise.
+ */
+export function calculateDuration(start: string, end: string): string {
+  if (start === "" || end === "") return "-";
+  const startMs = Date.parse(start);
+  const endMs = Date.parse(end);
+  if (Number.isNaN(startMs) || Number.isNaN(endMs)) return "-";
+
+  const totalSeconds = Math.floor((endMs - startMs) / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  if (totalSeconds < 3600) return `${Math.floor(totalSeconds / 60)}m ${totalSeconds % 60}s`;
+  return `${Math.floor(totalSeconds / 3600)}h ${Math.floor((totalSeconds % 3600) / 60)}m`;
+}
+
+/** Truncate to `maxLen`, appending "..." when cut. Mirrors Go's display.TruncateWithEllipsis. */
+export function truncateWithEllipsis(value: string, maxLen: number): string {
+  if (value.length <= maxLen) return value;
+  if (maxLen <= 3) return value.slice(0, maxLen);
+  return `${value.slice(0, maxLen - 3)}...`;
+}
+
+/** Short workflow task-type label. Mirrors Go's formatWorkflowTaskType. */
+export function formatWorkflowTaskType(type: WorkflowTaskType): string {
+  switch (type) {
+    case WorkflowTaskType.WORKFLOW_TASK_AGENT_INVOCATION:
+      return "agent";
+    case WorkflowTaskType.WORKFLOW_TASK_APPROVAL:
+      return "approval";
+    case WorkflowTaskType.WORKFLOW_TASK_API_CALL:
+      return "api_call";
+    case WorkflowTaskType.WORKFLOW_TASK_CONDITIONAL:
+      return "condition";
+    case WorkflowTaskType.WORKFLOW_TASK_PARALLEL:
+      return "parallel";
+    case WorkflowTaskType.WORKFLOW_TASK_TRANSFORM:
+      return "transform";
+    case WorkflowTaskType.WORKFLOW_TASK_CUSTOM:
+      return "custom";
+    default:
+      return "unknown";
+  }
+}