@stigmer/cli 3.0.8

package/src/resources/usage.test.ts

@@ -0,0 +1,94 @@
+import { create, toJson } from "@bufbuild/protobuf";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  GetAgentUsageReportOutputSchema,
+  GetOrgUsageReportOutputSchema,
+  GetSessionUsageReportOutputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { describe, expect, it } from "vitest";
+import { renderAgentUsage, renderOrgUsage, renderSessionUsage } from "./usage.js";
+
+const sessionReport = create(GetSessionUsageReportOutputSchema, {
+  sessionId: "ses_1",
+  executionCount: 1,
+  firstExecutionAt: "2026-03-01T10:00:00Z",
+  lastExecutionAt: "2026-03-01T11:00:00Z",
+  totalUsage: { inputTokens: 12500n, cacheReadInputTokens: 5000n },
+  modelBreakdown: [
+    { model: "claude-sonnet-4", inputTokens: 12500n, outputTokens: 1800n, cacheReadInputTokens: 5000n, billableCostMicros: 74000n },
+  ],
+  executions: [
+    {
+      startedAt: "2026-03-01T10:00:00Z",
+      inputTokens: 12500n,
+      outputTokens: 1800n,
+      billableCostMicros: 74000n,
+      primaryModel: "claude-sonnet-4",
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+    },
+  ],
+});
+
+describe("renderSessionUsage", () => {
+  it("emits protojson for json (DD-005 divergence: not Go's encoding/json)", () => {
+    const json = JSON.parse(renderSessionUsage(sessionReport, "json"));
+    expect(json).toEqual(toJson(GetSessionUsageReportOutputSchema, sessionReport, { useProtoFieldName: true }));
+  });
+
+  it("renders a human table with cost, token, model, and cache detail", () => {
+    const out = renderSessionUsage(sessionReport, "table");
+    expect(out).toContain("Session: ses_1");
+    expect(out).toContain("$0.074"); // sub-dollar → 3 decimals
+    expect(out).toContain("12.5K"); // compact token count
+    expect(out).toContain("claude-sonnet-4");
+    expect(out).toContain("40% cached"); // 5000 / 12500
+    expect(out).toContain("completed");
+  });
+});
+
+const agentReport = create(GetAgentUsageReportOutputSchema, {
+  agentId: "agt_1",
+  agentName: "Reviewer",
+  totalSessions: 2,
+  totalExecutions: 4,
+  totalBillableCostMicros: 4_000_000n,
+  modelBreakdown: [{ model: "claude-sonnet-4", inputTokens: 1000n, outputTokens: 200n, billableCostMicros: 4_000_000n }],
+  sessions: [{ sessionId: "ses_1", executionCount: 4, billableCostMicros: 4_000_000n, firstExecutionAt: "2026-03-01T10:00:00Z", lastExecutionAt: "2026-03-02T10:00:00Z" }],
+});
+
+describe("renderAgentUsage", () => {
+  it("emits protojson for yaml", () => {
+    const out = renderAgentUsage(agentReport, { from: "", to: "" }, "yaml");
+    expect(out).toContain("agent_id: agt_1");
+  });
+
+  it("renders summary stats with an average per execution", () => {
+    const out = renderAgentUsage(agentReport, { from: "2026-03-01", to: "2026-03-13" }, "table");
+    expect(out).toContain("Agent:  Reviewer");
+    expect(out).toContain("Period: 2026-03-01 to 2026-03-13");
+    expect(out).toContain("$4.00"); // total cost, dollar+ → 2 decimals
+    expect(out).toContain("$1.00"); // avg/exec = 4.00 / 4
+    expect(out).toContain("100.0%"); // single model = 100% share
+  });
+});
+
+const orgReport = create(GetOrgUsageReportOutputSchema, {
+  totalAgents: 3,
+  totalSessions: 5,
+  totalExecutions: 10,
+  totalBillableCostMicros: 10_000_000n,
+  modelBreakdown: [{ model: "claude-sonnet-4", inputTokens: 1000n, billableCostMicros: 10_000_000n }],
+  topAgentsByCost: [{ agentId: "agt_1", agentName: "Reviewer", executionCount: 6, billableCostMicros: 6_000_000n }],
+  dailyCosts: [{ date: "2026-03-01", executionCount: 4, billableCostMicros: 4_000_000n }],
+});
+
+describe("renderOrgUsage", () => {
+  it("renders org summary, top agents, and daily trend", () => {
+    const out = renderOrgUsage(orgReport, { from: "2026-03-01", to: "2026-03-31" }, "table");
+    expect(out).toContain("Organization Usage Report");
+    expect(out).toContain("Agents:       3");
+    expect(out).toContain("Reviewer");
+    expect(out).toContain("2026-03-01");
+    expect(out).toContain("60.0%"); // 6M of 10M total
+  });
+});

package/src/resources/usage.ts

@@ -0,0 +1,301 @@
+// `usage` reports: token/cost/model breakdowns at three granularities (session,
+// agent, org). Mirrors Go's internal/cli usage_* renderers, including the cost,
+// token-count, share, and date formatting helpers.
+//
+// DD-005 divergence (S-usage-json): the Go CLI serializes usage reports with the
+// standard library (encoding/json + yaml.v3) directly on the proto messages,
+// which yields a *different* shape (lowerCamel keys, integer enums, numeric
+// int64) than the protojson used by every other command. We deliberately emit
+// protojson here for consistency with the rest of the CLI (string enums/int64,
+// snake_case keys). A Go follow-up should converge the Go side onto protojson.
+
+import { create } from "@bufbuild/protobuf";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  GetAgentUsageReportInputSchema,
+  GetAgentUsageReportOutputSchema,
+  GetOrgUsageReportInputSchema,
+  GetOrgUsageReportOutputSchema,
+  GetSessionUsageReportInputSchema,
+  GetSessionUsageReportOutputSchema,
+  type GetAgentUsageReportOutput,
+  type GetOrgUsageReportOutput,
+  type GetSessionUsageReportOutput,
+} 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 type { OutputFormat } from "../output/index.js";
+import { renderProtoJson, renderProtoYaml, renderTable } from "../output/index.js";
+
+export interface DateRange {
+  readonly from: string;
+  readonly to: string;
+}
+
+// --- Fetch ---
+
+export async function getSessionUsageReport(client: Stigmer, sessionId: string): Promise<GetSessionUsageReportOutput> {
+  return client.agentExecution.getSessionUsageReport(create(GetSessionUsageReportInputSchema, { sessionId }));
+}
+
+export async function getAgentUsageReport(
+  client: Stigmer,
+  agentId: string,
+  range: DateRange,
+): Promise<GetAgentUsageReportOutput> {
+  return client.agentExecution.getAgentUsageReport(
+    create(GetAgentUsageReportInputSchema, { agentId, fromDate: range.from, toDate: range.to }),
+  );
+}
+
+export async function getOrgUsageReport(
+  client: Stigmer,
+  orgId: string,
+  range: DateRange,
+): Promise<GetOrgUsageReportOutput> {
+  return client.agentExecution.getOrgUsageReport(
+    create(GetOrgUsageReportInputSchema, { orgId, fromDate: range.from, toDate: range.to }),
+  );
+}
+
+// --- Render: session ---
+
+export function renderSessionUsage(report: GetSessionUsageReportOutput, format: OutputFormat): string {
+  if (format === "json") return renderProtoJson(GetSessionUsageReportOutputSchema, report);
+  if (format === "yaml") return renderProtoYaml(GetSessionUsageReportOutputSchema, report);
+
+  const lines: string[] = ["", `Session: ${report.sessionId}`];
+  const period = formatDateRange(report.firstExecutionAt, report.lastExecutionAt);
+  if (period !== "") {
+    lines.push(`Period:  ${period} (${report.executionCount} executions)`);
+  } else {
+    lines.push(`Executions: ${report.executionCount}`);
+  }
+  lines.push("");
+
+  if (report.modelBreakdown.length > 0) {
+    let totalInput = 0n;
+    let totalOutput = 0n;
+    let totalCached = 0n;
+    let totalCost = 0n;
+    const rows = report.modelBreakdown.map((m) => {
+      totalInput += m.inputTokens;
+      totalOutput += m.outputTokens;
+      totalCached += m.cacheReadInputTokens;
+      totalCost += m.billableCostMicros;
+      return [
+        m.model,
+        formatTokenCount(m.inputTokens),
+        formatTokenCount(m.outputTokens),
+        formatTokenCount(m.cacheReadInputTokens),
+        formatCost(m.billableCostMicros),
+      ];
+    });
+    if (report.modelBreakdown.length > 1) {
+      rows.push([
+        "Total",
+        formatTokenCount(totalInput),
+        formatTokenCount(totalOutput),
+        formatTokenCount(totalCached),
+        formatCost(totalCost),
+      ]);
+    }
+    lines.push(renderTable(["MODEL", "INPUT", "OUTPUT", "CACHED", "COST"], rows), "");
+  }
+
+  const cacheRate = formatCacheHitRate(report.totalUsage);
+  if (cacheRate !== "") lines.push(`Cache hit rate: ${cacheRate}`);
+
+  if (report.executions.length > 0) {
+    lines.push("");
+    const rows = report.executions.map((exec, i) => [
+      String(i + 1),
+      formatDate(exec.startedAt),
+      formatTokenCount(exec.inputTokens + exec.outputTokens),
+      formatCost(exec.billableCostMicros),
+      exec.primaryModel,
+      mapPhaseToString(exec.phase),
+    ]);
+    lines.push(renderTable(["#", "DATE", "TOKENS", "COST", "MODEL", "STATUS"], rows));
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+// --- Render: agent ---
+
+export function renderAgentUsage(
+  report: GetAgentUsageReportOutput,
+  range: DateRange,
+  format: OutputFormat,
+): string {
+  if (format === "json") return renderProtoJson(GetAgentUsageReportOutputSchema, report);
+  if (format === "yaml") return renderProtoYaml(GetAgentUsageReportOutputSchema, report);
+
+  const name = report.agentName === "" ? report.agentId : report.agentName;
+  const lines: string[] = ["", `Agent:  ${name}`];
+  if (range.from !== "" || range.to !== "") {
+    lines.push(`Period: ${formatInputDateRange(range.from, range.to)}`);
+  }
+  lines.push("");
+  lines.push(`  Sessions:     ${report.totalSessions}`);
+  lines.push(`  Executions:   ${report.totalExecutions}`);
+  lines.push(`  Total cost:   ${formatCost(report.totalBillableCostMicros)}`);
+  if (report.totalExecutions > 0) {
+    const avg = report.totalBillableCostMicros / BigInt(report.totalExecutions);
+    lines.push(`  Avg/exec:     ${formatCost(avg)}`);
+  }
+  lines.push("");
+
+  const totalCost = report.totalBillableCostMicros;
+  if (report.modelBreakdown.length > 0) {
+    const rows = report.modelBreakdown.map((m) => [
+      m.model,
+      formatTokenCount(m.inputTokens + m.outputTokens + m.cacheCreationInputTokens + m.cacheReadInputTokens),
+      formatCost(m.billableCostMicros),
+      formatShare(m.billableCostMicros, totalCost),
+    ]);
+    lines.push(renderTable(["MODEL", "TOKENS", "COST", "SHARE"], rows), "");
+  }
+
+  if (report.sessions.length > 0) {
+    const rows = report.sessions.map((sess, i) => [
+      String(i + 1),
+      formatDateRange(sess.firstExecutionAt, sess.lastExecutionAt),
+      String(sess.executionCount),
+      formatCost(sess.billableCostMicros),
+    ]);
+    lines.push(renderTable(["#", "PERIOD", "EXECUTIONS", "COST"], rows));
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+// --- Render: org ---
+
+export function renderOrgUsage(
+  report: GetOrgUsageReportOutput,
+  range: DateRange,
+  format: OutputFormat,
+): string {
+  if (format === "json") return renderProtoJson(GetOrgUsageReportOutputSchema, report);
+  if (format === "yaml") return renderProtoYaml(GetOrgUsageReportOutputSchema, report);
+
+  const lines: string[] = ["", "Organization Usage Report", `Period: ${formatInputDateRange(range.from, range.to)}`, ""];
+  lines.push(`  Agents:       ${report.totalAgents}`);
+  lines.push(`  Sessions:     ${report.totalSessions}`);
+  lines.push(`  Executions:   ${report.totalExecutions}`);
+  lines.push(`  Total cost:   ${formatCost(report.totalBillableCostMicros)}`);
+  lines.push("");
+
+  const totalCost = report.totalBillableCostMicros;
+  if (report.modelBreakdown.length > 0) {
+    const rows = report.modelBreakdown.map((m) => [
+      m.model,
+      formatTokenCount(m.inputTokens + m.outputTokens + m.cacheCreationInputTokens + m.cacheReadInputTokens),
+      formatCost(m.billableCostMicros),
+      formatShare(m.billableCostMicros, totalCost),
+    ]);
+    lines.push(renderTable(["MODEL", "TOKENS", "COST", "SHARE"], rows), "");
+  }
+
+  if (report.topAgentsByCost.length > 0) {
+    const rows = report.topAgentsByCost.map((a) => [
+      a.agentName === "" ? a.agentId : a.agentName,
+      String(a.executionCount),
+      formatCost(a.billableCostMicros),
+      formatShare(a.billableCostMicros, totalCost),
+    ]);
+    lines.push(renderTable(["AGENT", "EXECUTIONS", "COST", "SHARE"], rows), "");
+  }
+
+  if (report.dailyCosts.length > 0) {
+    const rows = report.dailyCosts.map((day) => [
+      day.date,
+      String(day.executionCount),
+      formatCost(day.billableCostMicros),
+    ]);
+    lines.push(renderTable(["DATE", "EXECUTIONS", "COST"], rows));
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+// --- Formatting helpers (mirror Go's usage_format.go) ---
+
+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)}`;
+}
+
+function formatTokenCount(count: bigint): string {
+  const n = Number(count);
+  if (n < 1000) return String(count);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}K`;
+  return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+function formatShare(part: bigint, total: bigint): string {
+  if (total === 0n) return "0.0%";
+  return `${((Number(part) / Number(total)) * 100).toFixed(1)}%`;
+}
+
+function formatCacheHitRate(usage: UsageReportAggregate | undefined): string {
+  if (usage === undefined || usage.inputTokens === 0n || usage.cacheReadInputTokens === 0n) return "";
+  const rate = (Number(usage.cacheReadInputTokens) / Number(usage.inputTokens)) * 100;
+  return `${Math.round(rate)}% cached`;
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+// "Jan 02" from an ISO 8601 timestamp; raw (≤10 chars) on parse failure.
+function formatDate(iso: string): string {
+  if (iso === "") return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso.length >= 10 ? iso.slice(0, 10) : iso;
+  return `${MONTHS[date.getMonth()]} ${String(date.getDate()).padStart(2, "0")}`;
+}
+
+function formatDateRange(from: string, to: string): string {
+  const f = formatDate(from);
+  const t = formatDate(to);
+  if (f === "" && t === "") return "";
+  if (f === "") return `to ${t}`;
+  if (t === "") return `from ${f}`;
+  return `${f} to ${t}`;
+}
+
+// Plain user-supplied date strings (e.g. "2026-03-01"), shown verbatim.
+function formatInputDateRange(from: string, to: string): string {
+  if (from === "" && to === "") return "";
+  if (from === "") return `to ${to}`;
+  if (to === "") return `from ${from}`;
+  return `${from} to ${to}`;
+}
+
+// Matches Go's mapPhaseToString (snake_case phase labels for the usage table).
+function mapPhaseToString(phase: ExecutionPhase): string {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_PENDING:
+      return "pending";
+    case ExecutionPhase.EXECUTION_IN_PROGRESS:
+      return "in_progress";
+    case ExecutionPhase.EXECUTION_COMPLETED:
+      return "completed";
+    case ExecutionPhase.EXECUTION_FAILED:
+      return "failed";
+    case ExecutionPhase.EXECUTION_CANCELLED:
+      return "cancelled";
+    case ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL:
+      return "waiting_for_approval";
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      return "terminated";
+    default:
+      return "unknown";
+  }
+}

package/src/resources/validate.test.ts

@@ -0,0 +1,54 @@
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { describe, expect, it } from "vitest";
+import { schemaForValidate, validateDocument } from "./validate.js";
+
+describe("schemaForValidate", () => {
+  it("resolves a schema for each file-based kind", () => {
+    expect(schemaForValidate(ApiResourceKind.agent)).toBeDefined();
+    expect(schemaForValidate(ApiResourceKind.workflow)).toBeDefined();
+    expect(schemaForValidate(ApiResourceKind.mcp_server)).toBeDefined();
+    expect(schemaForValidate(ApiResourceKind.project)).toBeDefined();
+  });
+
+  it("returns undefined for non-file-based kinds", () => {
+    expect(schemaForValidate(ApiResourceKind.organization)).toBeUndefined();
+    expect(schemaForValidate(ApiResourceKind.api_key)).toBeUndefined();
+  });
+});
+
+describe("validateDocument", () => {
+  const agentSchema = schemaForValidate(ApiResourceKind.agent);
+  if (agentSchema === undefined) throw new Error("agent schema unavailable");
+
+  it("accepts a structurally valid agent document", () => {
+    expect(() =>
+      validateDocument(agentSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Agent",
+        metadata: { name: "Reviewer", slug: "reviewer", org: "acme" },
+        spec: { description: "reviews code" },
+      }),
+    ).not.toThrow();
+  });
+
+  it("ignores unknown fields for forward compatibility", () => {
+    expect(() =>
+      validateDocument(agentSchema, {
+        kind: "Agent",
+        metadata: { name: "Reviewer" },
+        spec: { description: "reviews code" },
+        somethingNewerServersAdd: true,
+      }),
+    ).not.toThrow();
+  });
+
+  it("rejects a document with a type-mismatched field", () => {
+    expect(() =>
+      validateDocument(agentSchema, {
+        kind: "Agent",
+        // metadata must be an object, not a string.
+        metadata: "not-an-object",
+      }),
+    ).toThrow();
+  });
+});

package/src/resources/validate.ts

@@ -0,0 +1,31 @@
+// Offline resource validation: parse a YAML document into its proto schema.
+//
+// protobuf-es `fromJson` performs structural validation — field types, required
+// shapes, and enum membership — without a server round-trip, mirroring the Go
+// CLI's local load-and-validate. The accepted kinds are the file-based verbs
+// (apply/validate) that carry a YAML representation.
+
+import { type DescMessage, fromJson, type JsonValue } from "@bufbuild/protobuf";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ProjectSchema } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/api_pb";
+
+const VALIDATE_SCHEMAS: ReadonlyMap<ApiResourceKind, DescMessage> = new Map<ApiResourceKind, DescMessage>([
+  [ApiResourceKind.agent, AgentSchema],
+  [ApiResourceKind.workflow, WorkflowSchema],
+  [ApiResourceKind.mcp_server, McpServerSchema],
+  [ApiResourceKind.project, ProjectSchema],
+]);
+
+export function schemaForValidate(kind: ApiResourceKind): DescMessage | undefined {
+  return VALIDATE_SCHEMAS.get(kind);
+}
+
+/** Structurally validate a parsed YAML document against its proto schema. */
+export function validateDocument(schema: DescMessage, document: JsonValue): void {
+  // ignoreUnknownFields mirrors the server's lenient unmarshal: forward-compat
+  // fields a newer server adds should not fail a slightly older CLI.
+  fromJson(schema, document, { ignoreUnknownFields: true });
+}

package/src/resources/version.ts

@@ -0,0 +1,105 @@
+// Workflow version history (`get <workflow> --version-history`) and single
+// version retrieval (`get <workflow> --version <hashOrTag>`). Versioning is a
+// workflow-only feature: applies create immutable, hash-addressed versions that
+// can be tagged and diffed. Mirrors Go's workflow.RunVersionsList /
+// RunVersionsGet, including the table layout and the empty-history guidance.
+
+import { create } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import {
+  GetWorkflowVersionInputSchema,
+  ListWorkflowVersionsInputSchema,
+  type WorkflowVersionEntry,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { CliExitError, ExitCode } from "../errors/index.js";
+
+// Go caps the history view at 50 entries (workflow.getWorkflow → RunVersionsList).
+const VERSION_HISTORY_PAGE_SIZE = 50;
+
+/** Render the workflow's version history table, or empty-history guidance. */
+export async function renderWorkflowVersionHistory(client: Stigmer, org: string, slug: string): Promise<string> {
+  const response = await client.workflow.listVersions(
+    create(ListWorkflowVersionsInputSchema, { org, slug, pageSize: VERSION_HISTORY_PAGE_SIZE }),
+  );
+
+  if (response.versions.length === 0) {
+    return [
+      "",
+      `No version history found for ${org}/${slug}`,
+      "Tip: Apply a workflow to create the first version:",
+      "  stigmer apply -f workflow.yaml",
+      "",
+    ].join("\n");
+  }
+
+  return renderVersionsTable(response.versions, response.totalCount);
+}
+
+/** Fetch the validated YAML for a specific version (by hash or tag). */
+export async function getWorkflowVersionYaml(
+  client: Stigmer,
+  org: string,
+  slug: string,
+  hashOrTag: string,
+): Promise<string> {
+  const workflow = await client.workflow.getByReference({ org, slug });
+  const workflowId = workflow.metadata?.id ?? "";
+
+  const entry = await client.workflow.getVersion(
+    create(GetWorkflowVersionInputSchema, { workflowId, versionHash: hashOrTag }),
+  );
+
+  if (entry.validatedYaml === "") {
+    throw new CliExitError(`version ${truncateHash(hashOrTag)} has no validated YAML`, ExitCode.General);
+  }
+  // Go uses fmt.Print (no added newline) — the YAML carries its own.
+  return entry.validatedYaml;
+}
+
+// --- Rendering (mirrors Go's displayVersionsTable) ---
+
+function renderVersionsTable(entries: readonly WorkflowVersionEntry[], totalCount: number): string {
+  const lines: string[] = [
+    "",
+    `Version History (${totalCount} total)`,
+    "",
+    `  ${pad("HASH", 14)} ${pad("TAG", 10)} ${pad("APPLIED AT", 20)} ${pad("CURRENT", 8)} MESSAGE`,
+    `  ${"─".repeat(14)} ${"─".repeat(10)} ${"─".repeat(20)} ${"─".repeat(8)} ───────`,
+  ];
+
+  for (const entry of entries) {
+    const hash = truncateHash(entry.versionHash);
+    const tag = entry.tag === "" ? "-" : entry.tag;
+    const appliedAt = entry.appliedAt === undefined ? "-" : formatAppliedAt(entry.appliedAt);
+    const current = entry.isCurrent ? "*" : "";
+    const message = truncateMessage(entry.message);
+    lines.push(`  ${pad(hash, 14)} ${pad(tag, 10)} ${pad(appliedAt, 20)} ${pad(current, 8)} ${message}`);
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+function truncateHash(hash: string): string {
+  return hash.length > 12 ? hash.slice(0, 12) : hash;
+}
+
+function truncateMessage(message: string): string {
+  if (message === "") return "-";
+  return message.length > 40 ? `${message.slice(0, 37)}...` : message;
+}
+
+// Matches Go's "2006-01-02 15:04" local-time layout.
+function formatAppliedAt(timestamp: Parameters<typeof timestampDate>[0]): string {
+  const date = timestampDate(timestamp);
+  const pad2 = (n: number): string => String(n).padStart(2, "0");
+  return (
+    `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())} ` +
+    `${pad2(date.getHours())}:${pad2(date.getMinutes())}`
+  );
+}
+
+function pad(value: string, width: number): string {
+  return value.length >= width ? value : value + " ".repeat(width - value.length);
+}

package/src/runtime.ts

@@ -0,0 +1,23 @@
+// Process-global CLI flags that cross-cutting modules (config, errors, logger)
+// read without threading them through every call. Set once by the root
+// preAction hook from the parsed global options. Mirrors the Go CLI's atomic
+// `standalone`/`debug` globals in internal/cli/config and clierr.
+
+let debug = false;
+let standalone = false;
+
+export function setDebug(value: boolean): void {
+  debug = value;
+}
+
+export function isDebug(): boolean {
+  return debug;
+}
+
+export function setStandalone(value: boolean): void {
+  standalone = value;
+}
+
+export function isStandalone(): boolean {
+  return standalone;
+}

package/src/types/marked-terminal.d.ts

@@ -0,0 +1,31 @@
+// Ambient shim for the untyped `marked-terminal` package.
+//
+// The in-process Ink renderer imports @stigmer/ink, which the monorepo resolves
+// to its TypeScript *source* (sdk/ink/package.json "exports": "./src/index.ts").
+// That source uses `marked-terminal`, which ships no types, so @stigmer/ink
+// carries its own ambient declaration — but ambient declarations are scoped to
+// the program that includes them, and this CLI's tsconfig does not reach into
+// the SDK's src/types. We mirror the minimal surface the SDK relies on so the
+// CLI's typecheck sees the same contract. Keep in sync with
+// sdk/ink/src/types/marked-terminal.d.ts; remove if @types/marked-terminal ships
+// or @stigmer/ink is consumed as built declarations.
+
+declare module "marked-terminal" {
+  import type { MarkedExtension } from "marked";
+
+  interface MarkedTerminalOptions {
+    width?: number;
+    reflowText?: boolean;
+    showSectionPrefix?: boolean;
+    tab?: number;
+    unescape?: boolean;
+    emoji?: boolean;
+  }
+
+  export function markedTerminal(
+    options?: MarkedTerminalOptions,
+    highlightOptions?: Record<string, unknown>,
+  ): MarkedExtension;
+
+  export default class Renderer {}
+}