@stigmer/cli 3.0.8

package/src/commands/draft.ts

@@ -0,0 +1,128 @@
+// `stigmer draft <skill|agent|mcp-server>` — AI-assisted resource creation. Each
+// subcommand invokes a system agent (skill-creator/agent-creator/mcp-server-
+// creator) that lives in the "stigmer" org, reusing the full run stack. Mirrors
+// Go's draft.go + draft_handler.go.
+//
+// Draft differs from run only at the edges: the agent is fixed (a system agent),
+// --message is required, and artifacts download to -o/--output (or the CWD)
+// unless detached or a local workspace is in play.
+
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import { addAgentExecFlags, type AgentExecOptions, toAgentExecFlags } from "./agent-exec-flags.js";
+import { globalOrg } from "./shared.js";
+
+// The org that owns the system agent blueprints (installed by the seedpack),
+// regardless of which org the user operates in. Mirrors Go's systemAgentOrg.
+const SYSTEM_AGENT_ORG = "stigmer";
+
+interface DraftFlags extends AgentExecOptions {
+  output?: string;
+  json?: boolean;
+}
+
+interface DraftConfig {
+  /** Subcommand name + system agent slug. */
+  readonly name: string;
+  /** User-facing resource label. */
+  readonly resourceType: string;
+  readonly summary: string;
+}
+
+const CONFIGS: readonly DraftConfig[] = [
+  { name: "skill", resourceType: "Skill", summary: "create a skill with AI assistance" },
+  { name: "agent", resourceType: "Agent", summary: "create an agent with AI assistance" },
+  { name: "mcp-server", resourceType: "McpServer", summary: "create an MCP server config with AI assistance" },
+];
+
+// System agent slug per subcommand (Go's draftConfig.AgentName: "<type>-creator").
+function agentSlug(name: string): string {
+  return `${name}-creator`;
+}
+
+export function registerDraft(program: Command): void {
+  const draft = program.command("draft").description("create resource configurations with AI assistance");
+  for (const config of CONFIGS) {
+    const sub = draft.command(config.name).description(config.summary);
+    addAgentExecFlags(sub, true)
+      .option("-o, --output <dir>", "directory to save generated artifacts (default: current directory)")
+      .option("--json", "stream events as newline-delimited JSON")
+      .action((options: DraftFlags, command: Command) => runDraft(config, options, command));
+  }
+}
+
+async function runDraft(config: DraftConfig, options: DraftFlags, command: Command): Promise<void> {
+  const { connectBackend } = await import("../backend.js");
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+  if (org === "") {
+    throw new UsageError(
+      "organization not set\n\nSet it with:\n  stigmer config context set --org <org>\n  stigmer draft --org <org> ...",
+    );
+  }
+
+  const [{ prepareAgentExec }, { executeResolvedAgent }, { resolveAgentRef }, { localWorkspaceRoots }] =
+    await Promise.all([
+      import("../resources/run/prepare.js"),
+      import("../resources/run/agent-exec.js"),
+      import("../resources/run/resolve.js"),
+      import("../resources/run/workspace.js"),
+    ]);
+
+  const agent = await resolveDraftAgent(resolveAgentRef, client.stigmer, config);
+
+  const prepared = await prepareAgentExec(toAgentExecFlags(options), client.stigmer, org, stderrProgress());
+
+  if (prepared.attachments.length + prepared.workspaceFileRefs.length > 0) {
+    process.stderr.write(`Attached ${prepared.attachments.length + prepared.workspaceFileRefs.length} file(s) as context\n`);
+  }
+
+  await executeResolvedAgent({
+    agent,
+    prepared,
+    org,
+    downloadDir: resolveDownloadDir(options.output ?? "", prepared.detach, localWorkspaceRoots(prepared.workspaceEntries)),
+    outputMode: options.json === true ? "json" : "inline",
+    client,
+  });
+}
+
+// Resolve the system agent in the "stigmer" org, with seedpack-recovery guidance
+// on failure (Go's displayDraftAgentNotFoundError).
+async function resolveDraftAgent(
+  resolveAgentRef: typeof import("../resources/run/resolve.js").resolveAgentRef,
+  client: import("@stigmer/sdk").Stigmer,
+  config: DraftConfig,
+): Promise<import("@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb").Agent> {
+  const slug = agentSlug(config.name);
+  try {
+    return await resolveAgentRef(client, `${SYSTEM_AGENT_ORG}/${slug}`, SYSTEM_AGENT_ORG);
+  } catch {
+    throw new UsageError(
+      `${slug} agent not found in organization "${SYSTEM_AGENT_ORG}"\n\n` +
+        `System agents are installed by the seedpack in the "${SYSTEM_AGENT_ORG}" organization.\n\n` +
+        "Troubleshooting:\n" +
+        `  1. Verify agents exist:  stigmer list agents --org ${SYSTEM_AGENT_ORG}\n` +
+        "  2. Re-apply seedpack:    stigmer apply -f seedpack/",
+    );
+  }
+}
+
+// Download-target resolution (Go's executeDraft switch):
+//   detach          → no download (execution is backgrounded)
+//   explicit -o     → that directory
+//   local workspace → skip (the agent writes directly to disk)
+//   otherwise       → current directory
+function resolveDownloadDir(output: string, detach: boolean, localRoots: readonly string[]): string {
+  if (detach) return "";
+  if (output !== "") return output;
+  if (localRoots.length > 0) return "";
+  return ".";
+}
+
+function stderrProgress(): (line: string) => void {
+  if (process.stderr.isTTY !== true) return () => {};
+  return (line) => void process.stderr.write(`${line}\n`);
+}

package/src/commands/execution/approve.ts

@@ -0,0 +1,76 @@
+// `stigmer execution approve <execution-id>` — submit an approval decision.
+//
+// Workflow executions (wex_) approve a task: --task (required) + --outcome, with
+// optional --comment and --data-file (form data). Agent executions (aex_) approve
+// a tool call: --tool-call (required) + --action, with optional --comment.
+// Thin handler: validate required flags, delegate to resources/execution-approve.ts.
+// Mirrors Go's execution_approve.go.
+
+import type { Command } from "commander";
+import { ensureAuthenticated } from "../../config/index.js";
+import { UsageError } from "../../errors/index.js";
+import { resolveExecutionType } from "../../resources/execution.js";
+
+interface ApproveFlags {
+  task?: string;
+  outcome?: string;
+  comment?: string;
+  dataFile?: string;
+  toolCall?: string;
+  action?: string;
+}
+
+export function registerExecutionApprove(execution: Command): void {
+  execution
+    .command("approve <execution-id>")
+    .description("submit approval for a waiting execution")
+    .option("--task <name>", "task name to approve (workflow executions)")
+    .option("--outcome <outcome>", "approval outcome (workflow executions)", "approve")
+    .option("--comment <comment>", "approval comment")
+    .option("--data-file <path>", "JSON file with form data (workflow executions)")
+    .option("--tool-call <id>", "tool call ID to approve (agent executions)")
+    .option("--action <action>", "approval action: approve or deny (agent executions)", "approve")
+    .action((executionId: string, options: ApproveFlags) => runApprove(executionId, options));
+}
+
+async function runApprove(executionId: string, options: ApproveFlags): Promise<void> {
+  // Resolve type before any network call so a bad ID fails fast with guidance.
+  const type = resolveExecutionType(executionId);
+
+  const [{ connectBackend }, approve, { CommandResult, renderResult }] = await Promise.all([
+    import("../../backend.js"),
+    import("../../resources/execution-approve.js"),
+    import("../../output/command-result.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  if (type === "workflow") {
+    if (options.task === undefined || options.task === "") {
+      throw new UsageError("--task is required for workflow execution approvals");
+    }
+    const outcome = options.outcome ?? "approve";
+    await approve.approveWorkflowTask(client.stigmer, {
+      executionId,
+      taskName: options.task,
+      outcome,
+      comment: options.comment ?? "",
+      formData: await approve.readFormData(options.dataFile),
+    });
+    renderResult(CommandResult.success(`Approval submitted: task=${options.task} outcome=${outcome}`), "human");
+    return;
+  }
+
+  if (options.toolCall === undefined || options.toolCall === "") {
+    throw new UsageError("--tool-call is required for agent execution approvals");
+  }
+  const action = options.action ?? "approve";
+  await approve.approveAgentToolCall(client.stigmer, {
+    executionId,
+    toolCallId: options.toolCall,
+    action,
+    comment: options.comment ?? "",
+  });
+  renderResult(CommandResult.success(`Approval submitted: tool-call=${options.toolCall} action=${action}`), "human");
+}

package/src/commands/execution/control.ts

@@ -0,0 +1,79 @@
+// `stigmer execution {cancel,terminate,pause,resume} <execution-id>` — lifecycle
+// control verbs. Thin handlers: resolve the client, call the control resource,
+// render the resulting phase. Mirrors Go's execution_cancel.go / execution_pause.go.
+
+import type { Command } from "commander";
+import { ensureAuthenticated } from "../../config/index.js";
+
+interface ReasonFlags {
+  reason?: string;
+}
+
+export function registerExecutionControl(execution: Command): void {
+  execution
+    .command("cancel <execution-id>")
+    .description("gracefully cancel a running execution")
+    .option("--reason <reason>", "reason for cancellation")
+    .action((executionId: string, options: ReasonFlags) => runControl("cancel", executionId, options.reason ?? ""));
+
+  execution
+    .command("terminate <execution-id>")
+    .description("force-stop an execution immediately")
+    .option("--reason <reason>", "reason for termination")
+    .action((executionId: string, options: ReasonFlags) => runControl("terminate", executionId, options.reason ?? ""));
+
+  execution
+    .command("pause <execution-id>")
+    .description("pause a running execution")
+    .option("--reason <reason>", "reason for pausing")
+    .action((executionId: string, options: ReasonFlags) => runControl("pause", executionId, options.reason ?? ""));
+
+  execution
+    .command("resume <execution-id>")
+    .description("resume a paused execution")
+    .action((executionId: string) => runControl("resume", executionId, ""));
+}
+
+type ControlVerb = "cancel" | "terminate" | "pause" | "resume";
+
+// Past-tense success wording per verb, matching Go's climsg.Success lines.
+const PAST_TENSE: Record<ControlVerb, string> = {
+  cancel: "cancelled",
+  terminate: "terminated",
+  pause: "paused",
+  resume: "resumed",
+};
+
+async function runControl(verb: ControlVerb, executionId: string, reason: string): Promise<void> {
+  const [{ connectBackend }, control, { CommandResult, renderResult }] = await Promise.all([
+    import("../../backend.js"),
+    import("../../resources/execution-control.js"),
+    import("../../output/command-result.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  const result = await dispatch(verb, control, client.stigmer, executionId, reason);
+  const message = `Execution ${PAST_TENSE[verb]}: ${executionId} (phase: ${result.phase})`;
+  renderResult(CommandResult.success(message), "human");
+}
+
+function dispatch(
+  verb: ControlVerb,
+  control: typeof import("../../resources/execution-control.js"),
+  client: import("@stigmer/sdk").Stigmer,
+  executionId: string,
+  reason: string,
+): Promise<import("../../resources/execution-control.js").ControlResult> {
+  switch (verb) {
+    case "cancel":
+      return control.cancelExecution(client, executionId, reason);
+    case "terminate":
+      return control.terminateExecution(client, executionId, reason);
+    case "pause":
+      return control.pauseExecution(client, executionId, reason);
+    case "resume":
+      return control.resumeExecution(client, executionId);
+  }
+}

package/src/commands/execution/index.ts

@@ -0,0 +1,24 @@
+// `stigmer execution …` — lifecycle and observability for agent and workflow
+// executions. The execution type is auto-detected from the ID prefix (aex_ vs
+// wex_), so a single command group serves both families.
+//
+// Mirrors Go's NewExecutionCommand (cmd/stigmer/root/execution.go). Each
+// subcommand is a thin handler that resolves the backend client and delegates to
+// a resources/ module; heavy modules load lazily inside the actions (DD-001).
+
+import type { Command } from "commander";
+import { registerExecutionApprove } from "./approve.js";
+import { registerExecutionControl } from "./control.js";
+import { registerExecutionLogs } from "./logs.js";
+import { registerExecutionTrace } from "./trace.js";
+
+export function registerExecution(program: Command): void {
+  const execution = program
+    .command("execution")
+    .description("manage execution lifecycle and observability (agent: aex_, workflow: wex_)");
+
+  registerExecutionControl(execution);
+  registerExecutionLogs(execution);
+  registerExecutionTrace(execution);
+  registerExecutionApprove(execution);
+}

package/src/commands/execution/logs.ts

@@ -0,0 +1,47 @@
+// `stigmer execution logs <execution-id>` — view or stream execution logs.
+// Thin handler: resolve the client, wire Ctrl-C to abort a follow cleanly, and
+// delegate to resources/execution-logs.ts. Mirrors Go's execution_logs.go.
+
+import type { Command } from "commander";
+import { ensureAuthenticated } from "../../config/index.js";
+
+interface LogsFlags {
+  follow?: boolean;
+  task?: string;
+}
+
+export function registerExecutionLogs(execution: Command): void {
+  execution
+    .command("logs <execution-id>")
+    .description("view execution event logs (use --follow to stream)")
+    .option("-f, --follow", "stream live events")
+    .option("--task <name>", "filter events by task name (workflow only)")
+    .action((executionId: string, options: LogsFlags) => runLogs(executionId, options));
+}
+
+async function runLogs(executionId: string, options: LogsFlags): Promise<void> {
+  const [{ connectBackend }, { streamExecutionLogs }] = await Promise.all([
+    import("../../backend.js"),
+    import("../../resources/execution-logs.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  // Ctrl-C aborts the subscription; the resource treats an aborted signal as a
+  // clean exit (Go cancels the stream context on signal).
+  const controller = new AbortController();
+  const onSignal = (): void => controller.abort();
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  try {
+    await streamExecutionLogs(
+      client.stigmer,
+      { executionId, follow: options.follow === true, task: options.task },
+      controller.signal,
+    );
+  } finally {
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+  }
+}

package/src/commands/execution/trace.ts

@@ -0,0 +1,32 @@
+// `stigmer execution trace <execution-id>` — show task/tool structure + timing.
+// Thin handler: resolve the client and format, delegate to
+// resources/execution-trace.ts. Mirrors Go's execution_trace.go.
+
+import type { Command } from "commander";
+import { ensureAuthenticated } from "../../config/index.js";
+import type { OutputFlags } from "../../output/index.js";
+import type { TraceFormat } from "../../resources/execution-trace.js";
+import { addReadFlags, readFormat } from "../shared.js";
+
+export function registerExecutionTrace(execution: Command): void {
+  const trace = execution
+    .command("trace <execution-id>")
+    .description("show execution task structure and timing")
+    .action((executionId: string, options: OutputFlags) => runTrace(executionId, options));
+  addReadFlags(trace);
+}
+
+async function runTrace(executionId: string, options: OutputFlags): Promise<void> {
+  // Read-class format resolves to exactly table | json | yaml — the trace surface.
+  const format = readFormat(options) as TraceFormat;
+
+  const [{ connectBackend }, { traceExecution }] = await Promise.all([
+    import("../../backend.js"),
+    import("../../resources/execution-trace.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  await traceExecution(client.stigmer, executionId, format);
+}

package/src/commands/get.ts

@@ -0,0 +1,99 @@
+// `stigmer get <type> <reference>` — fetch a single resource.
+//
+// Thin handler: route the two non-registry special cases (executions, addressed
+// by `aex_`/`wex_` ID; workflow version history/retrieval) first, then the
+// registry-driven standard path. Heavy modules (backend client, SDK schemas)
+// are dynamically imported inside the action so `--help` stays fast (DD-001).
+
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import type { OutputFlags } from "../output/index.js";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { defaultRegistry, Verb } from "../registry/index.js";
+import { addReadFlags, globalOrg, readFormat } from "./shared.js";
+
+interface GetFlags extends OutputFlags {
+  version?: string;
+  versionHistory?: boolean;
+}
+
+export function registerGet(program: Command): void {
+  const get = program
+    .command("get <type> <reference>")
+    .description("get a resource by type and reference (slug, org/slug, or ID)")
+    .option("--version <hashOrTag>", "fetch a specific version by hash or tag (workflows only)")
+    .option("--version-history", "show the version history timeline (workflows only)")
+    .action((type: string, reference: string, options: GetFlags, command: Command) =>
+      runGet(type, reference, options, command),
+    );
+  addReadFlags(get);
+}
+
+async function runGet(type: string, reference: string, options: GetFlags, command: Command): Promise<void> {
+  const { isExecutionAlias } = await import("../resources/execution.js");
+  if (isExecutionAlias(type)) {
+    await runGetExecution(reference, options, command);
+    return;
+  }
+
+  const info = defaultRegistry().getByAlias(type);
+  if (info === undefined) {
+    throw new UsageError(`unknown resource type: ${type}`);
+  }
+  if (!info.supportedVerbs.has(Verb.Get)) {
+    throw new UsageError(`${info.displayName} does not support 'get'`);
+  }
+
+  const [{ connectBackend }, { parseReference }, { fetchResource }, { renderResource }] = await Promise.all([
+    import("../backend.js"),
+    import("../resources/reference.js"),
+    import("../resources/get.js"),
+    import("../resources/render.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+
+  // Workflow versioning is the only versioned read surface today (Go ignores the
+  // flags for other kinds, returning the current resource).
+  if (info.kind === ApiResourceKind.workflow && (options.versionHistory === true || (options.version ?? "") !== "")) {
+    const [refOrg, slug] = parseOrgSlug(reference, org);
+    const { renderWorkflowVersionHistory, getWorkflowVersionYaml } = await import("../resources/version.js");
+    if (options.versionHistory === true) {
+      process.stdout.write(await renderWorkflowVersionHistory(client.stigmer, refOrg, slug));
+    } else {
+      process.stdout.write(await getWorkflowVersionYaml(client.stigmer, refOrg, slug, options.version ?? ""));
+    }
+    return;
+  }
+
+  const parsed = parseReference(reference, org, info.idPrefix);
+  const { schema, message } = await fetchResource(client.stigmer, info.kind, parsed);
+  process.stdout.write(renderResource(schema, message, readFormat(options)));
+}
+
+async function runGetExecution(reference: string, options: GetFlags, command: Command): Promise<void> {
+  const [{ connectBackend }, { getExecution }, { renderResource }] = await Promise.all([
+    import("../backend.js"),
+    import("../resources/execution.js"),
+    import("../resources/render.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  // Executions are addressed by ID; org context is irrelevant. `getExecution`
+  // resolves agent-vs-workflow by prefix and throws a usage error otherwise.
+  void globalOrg(command);
+
+  const { schema, message } = await getExecution(client.stigmer, reference);
+  process.stdout.write(renderResource(schema, message, readFormat(options)));
+}
+
+// Splits "org/slug" into its parts; a bare token uses the resolved org context.
+function parseOrgSlug(reference: string, org: string): [string, string] {
+  const idx = reference.indexOf("/");
+  if (idx > 0) return [reference.slice(0, idx), reference.slice(idx + 1)];
+  return [org, reference];
+}

package/src/commands/internal-daemon.ts

@@ -0,0 +1,25 @@
+// `stigmer internal-daemon` (hidden) — the long-lived supervised daemon process
+// that `up` re-execs. It is not meant to be invoked directly; it runs the local
+// stack until it receives SIGTERM/SIGINT, then exits with the daemon's code.
+
+import type { Command } from "commander";
+
+export function registerInternalDaemon(program: Command): void {
+  program
+    .command("internal-daemon", { hidden: true })
+    .description("internal: run the supervised local-stack daemon (do not invoke directly)")
+    .action(async () => {
+      const { runInternalDaemon } = await import("../local/daemon/process.js");
+      const code = await runInternalDaemon({ waitForShutdown: waitForShutdownSignal });
+      process.exit(code);
+    });
+}
+
+// Resolve when the first SIGTERM/SIGINT arrives — the daemon's shutdown trigger.
+function waitForShutdownSignal(): Promise<void> {
+  return new Promise((resolve) => {
+    const onSignal = (): void => resolve();
+    process.once("SIGTERM", onSignal);
+    process.once("SIGINT", onSignal);
+  });
+}

package/src/commands/list.ts

@@ -0,0 +1,138 @@
+// `stigmer list <type>` — list resources of a type, or `list types` to show the
+// registry of available types. Thin handler: resolve/route, delegate, render.
+
+import type { Command } from "commander";
+import { stringify as toYaml } from "yaml";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import type { OutputFlags } from "../output/index.js";
+import { renderTable } from "../output/index.js";
+import { ALL_VERBS, defaultRegistry, Verb } from "../registry/index.js";
+import { addReadFlags, globalOrg, readFormat } from "./shared.js";
+
+const DEFAULT_LIMIT = 50;
+
+interface ListFlags extends OutputFlags {
+  limit?: string;
+  verb?: string;
+  type?: string;
+}
+
+export function registerList(program: Command): void {
+  const list = program
+    .command("list <type>")
+    .description("list resources of a type (or 'list types' for available types)")
+    .option("--limit <n>", "maximum number of results", String(DEFAULT_LIMIT))
+    .option("--verb <verb>", "filter to types supporting this verb (only for 'list types')")
+    .option("--type <kind>", "execution type filter: agent or workflow (only for 'list executions')")
+    .action((type: string, options: ListFlags, command: Command) => runList(type, options, command));
+  addReadFlags(list);
+}
+
+async function runList(type: string, options: ListFlags, command: Command): Promise<void> {
+  if (isTypesAlias(type)) {
+    process.stdout.write(renderTypes(options.verb, readFormat(options)));
+    return;
+  }
+
+  const { isExecutionAlias } = await import("../resources/execution.js");
+  const { isSessionAlias } = await import("../resources/session.js");
+  if (isExecutionAlias(type)) {
+    await runListExecutions(options);
+    return;
+  }
+  if (isSessionAlias(type)) {
+    await runListSessions(options);
+    return;
+  }
+
+  const info = defaultRegistry().getByAlias(type);
+  if (info === undefined) {
+    throw new UsageError(`unknown resource type: ${type}`);
+  }
+  if (!info.supportedVerbs.has(Verb.List)) {
+    throw new UsageError(`${info.displayName} does not support 'list'`);
+  }
+
+  const [{ connectBackend }, { listResources }] = await Promise.all([
+    import("../backend.js"),
+    import("../resources/list.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+  const rendered = await listResources(client.stigmer, info.kind, org, parseLimit(options.limit), readFormat(options));
+  process.stdout.write(rendered);
+}
+
+// Executions bypass the registry: they're listed by their own controllers and
+// optionally filtered to agent (default) or workflow by `--type`.
+async function runListExecutions(options: ListFlags): Promise<void> {
+  const [{ connectBackend }, execution] = await Promise.all([
+    import("../backend.js"),
+    import("../resources/execution.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const limit = parseLimit(options.limit);
+  const format = readFormat(options);
+
+  const filter = (options.type ?? "").trim().toLowerCase();
+  if (filter === "workflow" || filter === "wf") {
+    const result = await execution.listWorkflowExecutions(client.stigmer, limit);
+    process.stdout.write(execution.renderExecutionList(result, format, "workflow"));
+    return;
+  }
+  if (filter !== "" && filter !== "agent") {
+    throw new UsageError(`unknown execution type filter: ${options.type}\n\nValid values: agent, workflow`);
+  }
+  const result = await execution.listAgentExecutions(client.stigmer, limit);
+  process.stdout.write(execution.renderExecutionList(result, format, "agent"));
+}
+
+async function runListSessions(options: ListFlags): Promise<void> {
+  const [{ connectBackend }, session] = await Promise.all([
+    import("../backend.js"),
+    import("../resources/session.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const result = await session.listSessions(client.stigmer, parseLimit(options.limit));
+  process.stdout.write(session.renderSessionList(result, readFormat(options)));
+}
+
+function isTypesAlias(type: string): boolean {
+  const normalized = type.trim().toLowerCase();
+  return normalized === "type" || normalized === "types";
+}
+
+function parseLimit(raw: string | undefined): number {
+  if (raw === undefined || raw === "") return DEFAULT_LIMIT;
+  if (!/^\d+$/.test(raw)) throw new UsageError(`invalid --limit value "${raw}"`);
+  return Number.parseInt(raw, 10);
+}
+
+// `list types` reads from the local registry — no backend call.
+function renderTypes(verbFilter: string | undefined, format: string): string {
+  const registry = defaultRegistry();
+  const verb = verbFilter !== undefined && verbFilter !== "" ? (verbFilter.toLowerCase() as Verb) : undefined;
+  if (verb !== undefined && !ALL_VERBS.includes(verb)) {
+    throw new UsageError(`unknown verb: ${verbFilter}`);
+  }
+
+  const types = (verb !== undefined ? registry.typesForVerb(verb) : registry.all()).map((info) => ({
+    name: info.name,
+    display_name: info.displayName,
+    id_prefix: info.idPrefix,
+    aliases: [...info.aliases],
+    verbs: ALL_VERBS.filter((v) => info.supportedVerbs.has(v)),
+  }));
+
+  if (format === "json") return `${JSON.stringify(types, null, 2)}\n`;
+  if (format === "yaml") return toYaml(types);
+  const rows = types.map((t) => [t.name, t.id_prefix, t.verbs.join(", ")]);
+  return `\n${renderTable(["TYPE", "ID PREFIX", "VERBS"], rows)}`;
+}