@bastani/atomic 0.9.10-alpha.1 → 0.9.11-alpha.1

package/dist/builtin/workflows/src/durable/dbos-embedded-postgres-root.ts

@@ -0,0 +1,173 @@
+/**
+ * Root-execution support for the embedded DBOS Postgres.
+ *
+ * PostgreSQL categorically refuses to run `initdb`/`postgres` as UID 0, so a
+ * root Atomic process (common in containers, CI sandboxes, and eval harnesses)
+ * cannot provision the embedded cluster directly. On Linux we instead resolve
+ * an unprivileged system account, keep the cluster under a root-safe base
+ * directory (`/root` is mode 0700 and untraversable by that account), and run
+ * every Postgres command with dropped privileges.
+ *
+ * Privilege dropping is strategy-probed at runtime: Node honors the child
+ * process `uid`/`gid` spawn options, but Bun currently ignores them, so we
+ * verify the drop actually happens (`id -u` must report the owner) and fall
+ * back to `setpriv`, `runuser`, or `su` wrappers when it does not.
+ *
+ * The embedded binaries themselves may also live under an untraversable
+ * prefix (for example a root-owned `~/.nvm` global install), so the caller can
+ * probe them as the unprivileged owner and fall back to a one-time copy into
+ * the cluster base directory.
+ */
+
+import { cpSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { runLocalCommand, type LocalCommandResult } from "./local-command.js";
+
+export interface EmbeddedPostgresOwner {
+  readonly uid: number;
+  readonly gid: number;
+  readonly name: string;
+}
+
+export interface EmbeddedPostgresRunContext {
+  /** Directory that holds the cluster, log file, and setup locks. */
+  readonly baseDir: string;
+  /** Present only when commands must drop privileges (Linux root). */
+  readonly owner?: EmbeddedPostgresOwner;
+  /** Runs a command as the owner; identity pass-through when no owner. */
+  readonly runAsOwner: LocalCommandRunner;
+}
+
+export interface EmbeddedPostgresBinaryPaths {
+  readonly pg_ctl: string;
+  readonly initdb: string;
+}
+
+export type LocalCommandRunner = (
+  command: string,
+  args: readonly string[],
+  options?: { readonly uid?: number; readonly gid?: number },
+) => Promise<LocalCommandResult>;
+
+/** Root-safe cluster location: system path, traversable by system accounts. */
+export const ROOT_EMBEDDED_BASE_DIR = "/var/lib/atomic-postgres";
+
+/** Unprivileged accounts tried in order; `postgres` wins when present. */
+const OWNER_CANDIDATES = ["postgres", "nobody", "daemon"] as const;
+
+export function defaultEmbeddedBaseDir(): string {
+  return join(homedir(), ".atomic", "postgres");
+}
+
+/**
+ * Resolve where and as whom the embedded cluster should run. Non-root (and
+ * every non-Linux platform) keeps the historical home-directory layout. Linux
+ * root without a resolvable unprivileged account, or without any working
+ * privilege-drop mechanism, also falls through to the default context so
+ * PostgreSQL's own root refusal surfaces with full detail.
+ */
+export async function resolveEmbeddedRunContext(
+  runner: LocalCommandRunner = runLocalCommand,
+  euid: number | undefined = process.getuid?.(),
+  platform: NodeJS.Platform = process.platform,
+): Promise<EmbeddedPostgresRunContext> {
+  if (platform !== "linux" || euid !== 0) {
+    return { baseDir: defaultEmbeddedBaseDir(), runAsOwner: runner };
+  }
+  for (const name of OWNER_CANDIDATES) {
+    const owner = await lookupOwner(runner, name);
+    if (owner === undefined) continue;
+    const runAsOwner = await resolvePrivilegeDrop(runner, owner);
+    if (runAsOwner === undefined) continue;
+    return { baseDir: ROOT_EMBEDDED_BASE_DIR, owner, runAsOwner };
+  }
+  return { baseDir: defaultEmbeddedBaseDir(), runAsOwner: runner };
+}
+
+/**
+ * Return a runner that verifiably executes commands as the owner, or
+ * `undefined` when no drop mechanism works. Each strategy is validated by
+ * running `id -u` through it and requiring the owner's uid on stdout — the
+ * spawn `uid`/`gid` options in particular are silently ignored by Bun.
+ */
+export async function resolvePrivilegeDrop(
+  runner: LocalCommandRunner,
+  owner: EmbeddedPostgresOwner,
+): Promise<LocalCommandRunner | undefined> {
+  const strategies: readonly LocalCommandRunner[] = [
+    (command, args) => runner(command, args, { uid: owner.uid, gid: owner.gid }),
+    (command, args) => runner("setpriv", [
+      `--reuid=${owner.uid}`, `--regid=${owner.gid}`, "--clear-groups", "--", command, ...args,
+    ]),
+    (command, args) => runner("runuser", ["-u", owner.name, "--", command, ...args]),
+    (command, args) => runner("su", ["-s", "/bin/sh", "-c", shellCommand(command, args), owner.name]),
+  ];
+  for (const strategy of strategies) {
+    const probe = await strategy("id", ["-u"]).catch(() => undefined);
+    if (probe !== undefined && probe.exitCode === 0 && probe.stdout.trim() === String(owner.uid)) {
+      return strategy;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Ensure the embedded binaries are executable by the drop-privilege owner.
+ * Probes `initdb --version` as the owner; on failure (typically an
+ * untraversable ancestor such as `/root`) copies the package's `native` tree
+ * into the cluster base directory once and reuses it afterwards.
+ */
+export async function prepareBinariesForOwner(
+  binaries: EmbeddedPostgresBinaryPaths,
+  context: EmbeddedPostgresRunContext,
+  runner: LocalCommandRunner = runLocalCommand,
+): Promise<EmbeddedPostgresBinaryPaths> {
+  const owner = context.owner;
+  if (owner === undefined) return binaries;
+
+  const probe = await context.runAsOwner(binaries.initdb, ["--version"]).catch(() => undefined);
+  if (probe !== undefined && probe.exitCode === 0) return binaries;
+
+  // `<packageRoot>/native/bin/initdb` → copy the whole `native` tree so the
+  // binaries keep their relative `../lib` runtime library references.
+  const nativeDir = dirname(dirname(binaries.initdb));
+  const copiedNativeDir = join(context.baseDir, "pg-runtime", "native");
+  const copied: EmbeddedPostgresBinaryPaths = {
+    pg_ctl: join(copiedNativeDir, "bin", "pg_ctl"),
+    initdb: join(copiedNativeDir, "bin", "initdb"),
+  };
+  if (!existsSync(copied.initdb)) {
+    cpSync(nativeDir, copiedNativeDir, { recursive: true });
+  }
+  const chown = await runner("chown", ["-R", `${owner.uid}:${owner.gid}`, join(context.baseDir, "pg-runtime")]);
+  if (chown.exitCode !== 0) {
+    throw new Error(
+      `Could not hand the copied embedded Postgres runtime to ${owner.name}: ${chown.stderr.trim() || chown.stdout.trim() || `exit ${chown.exitCode}`}`,
+    );
+  }
+  return copied;
+}
+
+async function lookupOwner(runner: LocalCommandRunner, name: string): Promise<EmbeddedPostgresOwner | undefined> {
+  const uid = await lookupId(runner, ["-u", name]);
+  const gid = await lookupId(runner, ["-g", name]);
+  if (uid === undefined || gid === undefined || uid === 0) return undefined;
+  return { uid, gid, name };
+}
+
+async function lookupId(runner: LocalCommandRunner, args: readonly string[]): Promise<number | undefined> {
+  try {
+    const result = await runner("id", args);
+    if (result.exitCode !== 0) return undefined;
+    const value = Number.parseInt(result.stdout.trim(), 10);
+    return Number.isInteger(value) && value > 0 ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Single-quote a command line for `su -c`; arguments never embed user input. */
+function shellCommand(command: string, args: readonly string[]): string {
+  return [command, ...args].map((part) => `'${part.replaceAll("'", "'\\''")}'`).join(" ");
+}

package/dist/builtin/workflows/src/durable/dbos-embedded-postgres.ts

@@ -10,12 +10,23 @@
  * is started with `pg_ctl`, which daemonizes the server into its own session:
  * it survives Atomic exiting and is shared by every concurrent Atomic session.
  * Atomic never stops it.
+ *
+ * PostgreSQL refuses to run as UID 0, so a root Atomic process (containers,
+ * CI sandboxes, eval harnesses) resolves an unprivileged system account, keeps
+ * the cluster under `/var/lib/atomic-postgres` instead (a root home directory
+ * is untraversable for that account), and runs every Postgres command with
+ * dropped privileges. See dbos-embedded-postgres-root.ts.
  */
 
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { chmodSync, chownSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join, relative } from "node:path";
-import { commandFailureDetail, delay, runLocalCommand, tcpReachable } from "./local-command.js";
+import {
+  prepareBinariesForOwner,
+  resolveEmbeddedRunContext,
+  type EmbeddedPostgresRunContext,
+} from "./dbos-embedded-postgres-root.js";
+import { commandFailureDetail, delay, tcpReachable } from "./local-command.js";
 
 const EMBEDDED_HOST = "127.0.0.1";
 const EMBEDDED_PORT = 5439;
@@ -47,17 +58,20 @@ export function ensureEmbeddedDbosPostgres(): Promise<void> {
 
 async function ensure(): Promise<void> {
   if (await tcpReachable(EMBEDDED_HOST, EMBEDDED_PORT)) return;
-  const binaries = await loadEmbeddedPostgresBinaries();
-  hydrateBinaryLibraryLinks(binaries.pg_ctl);
-  const root = join(homedir(), ".atomic", "postgres");
+  const loaded = await loadEmbeddedPostgresBinaries();
+  hydrateBinaryLibraryLinks(loaded.pg_ctl);
+  const context = await resolveEmbeddedRunContext();
+  const root = context.baseDir;
   const dataDir = join(root, `v${EMBEDDED_PG_MAJOR}`);
   const logFile = join(root, `v${EMBEDDED_PG_MAJOR}.log`);
   mkdirSync(root, { recursive: true, mode: 0o700 });
+  if (context.owner !== undefined) chownSync(root, context.owner.uid, context.owner.gid);
+  const binaries = await prepareBinariesForOwner(loaded, context);
 
   await withSetupLock(join(root, `v${EMBEDDED_PG_MAJOR}.setup-lock`), async () => {
     if (await tcpReachable(EMBEDDED_HOST, EMBEDDED_PORT)) return;
-    if (!existsSync(join(dataDir, "PG_VERSION"))) await initializeCluster(binaries.initdb, dataDir);
-    await startCluster(binaries.pg_ctl, dataDir, logFile);
+    if (!existsSync(join(dataDir, "PG_VERSION"))) await initializeCluster(binaries.initdb, dataDir, context);
+    await startCluster(binaries.pg_ctl, dataDir, logFile, context);
   });
 
   for (let attempt = 0; attempt < READY_ATTEMPTS; attempt += 1) {
@@ -67,11 +81,16 @@ async function ensure(): Promise<void> {
   throw new Error(`Embedded Postgres started but never accepted connections on ${EMBEDDED_HOST}:${EMBEDDED_PORT}; see ${logFile}.`);
 }
 
-async function initializeCluster(initdb: string, dataDir: string): Promise<void> {
+async function initializeCluster(
+  initdb: string,
+  dataDir: string,
+  context: EmbeddedPostgresRunContext,
+): Promise<void> {
   const passwordFile = join(tmpdir(), `atomic-pg-pw-${process.pid}-${crypto.randomUUID().slice(0, 8)}`);
   writeFileSync(passwordFile, `${EMBEDDED_PASSWORD}\n`, { mode: 0o600 });
   try {
-    const result = await runLocalCommand(initdb, [
+    if (context.owner !== undefined) chownSync(passwordFile, context.owner.uid, context.owner.gid);
+    const result = await context.runAsOwner(initdb, [
       "-D", dataDir,
       "-U", EMBEDDED_USER,
       "-A", "password",
@@ -87,8 +106,13 @@ async function initializeCluster(initdb: string, dataDir: string): Promise<void>
   }
 }
 
-async function startCluster(pgCtl: string, dataDir: string, logFile: string): Promise<void> {
-  const result = await runLocalCommand(pgCtl, [
+async function startCluster(
+  pgCtl: string,
+  dataDir: string,
+  logFile: string,
+  context: EmbeddedPostgresRunContext,
+): Promise<void> {
+  const result = await context.runAsOwner(pgCtl, [
     "-D", dataDir,
     "-l", logFile,
     "-o", `-p ${EMBEDDED_PORT} -c listen_addresses=${EMBEDDED_HOST}`,

package/dist/builtin/workflows/src/durable/dbos-lifecycle.ts

@@ -119,10 +119,16 @@ export function getReadyDbosBackendSync(): DbosDurableBackend | undefined {
 
 export async function shutdownDbos(): Promise<void> {
   if (shutdownPromise !== undefined) return await shutdownPromise;
-  if (configured === undefined) return;
+  const configuredPromise = configured;
+  if (configuredPromise === undefined) return;
   shutdownPromise = (async () => {
-    const durability = await configured;
-    if (launchPromise !== undefined) await launchPromise;
+    // A backend that never reached "ready" has nothing to flush or stop.
+    // `configured`/`launchPromise` memoize rejections, so re-awaiting them
+    // unguarded would rethrow the original provisioning failure out of every
+    // session dispose — crashing otherwise-successful runs at process exit.
+    const durability = await configuredPromise.catch(() => undefined);
+    if (durability === undefined) return;
+    if (launchPromise !== undefined) await launchPromise.catch(() => undefined);
     if (state !== "ready") return;
     state = "shutting_down";
     await durability.backend.flush();

package/dist/builtin/workflows/src/durable/factory.ts

@@ -1,4 +1,4 @@
-/** DBOS-only durable backend factory and internal test injection seam. */
+/** DBOS-first durable backend factory with a non-durable last-resort fallback. */
 
 import { InMemoryDurableBackend, type DurableWorkflowBackend } from "./backend.js";
 import {
@@ -9,8 +9,9 @@ import {
 
 let injectedBackend: DurableWorkflowBackend | undefined;
 let initializedBackend: DurableWorkflowBackend | undefined;
+let initializing: Promise<DurableWorkflowBackend> | undefined;
 
-/** Return the injected test backend or the process-wide ready DBOS backend. */
+/** Return the injected test backend or the process-wide initialized backend. */
 export function getDurableBackend(): DurableWorkflowBackend {
   const backend = injectedBackend ?? initializedBackend ?? getReadyDbosBackendSync();
   if (backend === undefined) throw new DbosNotReadyError();
@@ -20,7 +21,10 @@ export function getDurableBackend(): DurableWorkflowBackend {
 /** Internal injection seam. Production initialization uses DBOS. */
 export function setDurableBackend(backend: DurableWorkflowBackend | undefined): void {
   injectedBackend = backend;
-  if (backend === undefined) initializedBackend = undefined;
+  if (backend === undefined) {
+    initializedBackend = undefined;
+    initializing = undefined;
+  }
 }
 
 /** Create an isolated current-interface backend for tests only. */
@@ -28,9 +32,34 @@ export function createInMemoryTestBackend(): InMemoryDurableBackend {
   return new InMemoryDurableBackend();
 }
 
-/** Configure, register, launch, and install the mandatory DBOS backend. */
+/**
+ * Configure, register, launch, and install the DBOS backend.
+ *
+ * When no durable backend can be provisioned (no `DBOS_SYSTEM_DATABASE_URL`,
+ * embedded Postgres unavailable — e.g. running as root without an
+ * unprivileged account — and no Docker), workflows degrade to a process-local
+ * in-memory backend with a loud warning instead of refusing to run at all.
+ * Non-durable runs execute normally but do not survive the process:
+ * `/workflow resume` after exit has nothing to restore.
+ */
 export async function initializeDurableBackend(): Promise<DurableWorkflowBackend> {
   if (injectedBackend !== undefined) return injectedBackend;
-  initializedBackend ??= await getReadyDbosBackend();
-  return initializedBackend;
+  if (initializedBackend !== undefined) return initializedBackend;
+  initializing ??= getReadyDbosBackend()
+    .catch((error: unknown) => degradeToNonDurableBackend(error))
+    .then((backend) => {
+      initializedBackend = backend;
+      return backend;
+    });
+  return await initializing;
+}
+
+function degradeToNonDurableBackend(error: unknown): DurableWorkflowBackend {
+  const detail = error instanceof Error ? error.message : String(error);
+  console.error(
+    "atomic-workflows: durable backend unavailable — continuing NON-DURABLY with an in-memory backend. "
+    + "Workflow runs will execute, but their state will not survive this process and `/workflow resume` "
+    + `after exit will not work. Restore durability by fixing Postgres provisioning: ${detail}`,
+  );
+  return new InMemoryDurableBackend();
 }

package/dist/builtin/workflows/src/durable/local-command.ts

@@ -11,16 +11,25 @@ export interface LocalCommandResult {
 
 const OUTPUT_LIMIT_BYTES = 16_384;
 
+export interface LocalCommandOptions {
+  readonly env?: Readonly<Record<string, string>>;
+  /** POSIX drop-privilege identity for the spawned process (root only). */
+  readonly uid?: number;
+  readonly gid?: number;
+}
+
 export function runLocalCommand(
   command: string,
   args: readonly string[],
-  env?: Readonly<Record<string, string>>,
+  options?: LocalCommandOptions,
 ): Promise<LocalCommandResult> {
   return new Promise((resolve, reject) => {
     const child = spawn(command, [...args], {
       stdio: ["ignore", "pipe", "pipe"],
       windowsHide: true,
-      ...(env !== undefined ? { env: { ...process.env, ...env } } : {}),
+      ...(options?.env !== undefined ? { env: { ...process.env, ...options.env } } : {}),
+      ...(options?.uid !== undefined ? { uid: options.uid } : {}),
+      ...(options?.gid !== undefined ? { gid: options.gid } : {}),
     });
     let stdout = "";
     let stderr = "";

package/dist/builtin/workflows/src/extension/extension-lifecycle.ts

@@ -16,10 +16,22 @@ import { shutdownDbos } from "../durable/dbos-lifecycle.js";
 
 let processShutdownInstalled = false;
 
+/**
+ * Session dispose and process exit must never crash on durability teardown:
+ * a genuine flush/stop failure is diagnostic, not fatal, and an unhandled
+ * rejection here turns an otherwise-successful run into a nonzero exit.
+ */
+function shutdownDbosQuietly(): Promise<void> {
+  return shutdownDbos().catch((error: unknown) => {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.error(`atomic-workflows: DBOS durability shutdown failed: ${detail}`);
+  });
+}
+
 function installDbosProcessShutdown(): void {
   if (processShutdownInstalled) return;
   processShutdownInstalled = true;
-  process.once("beforeExit", () => shutdownDbos());
+  process.once("beforeExit", () => void shutdownDbosQuietly());
 }
 
 export interface WorkflowLifecycleRegistrationDeps {
@@ -123,6 +135,6 @@ export function registerWorkflowLifecycleHandlers(
     deps.storeWidgetRef.current = null;
     runtimeState.resetWorkflowDiscoveryForSession();
     runtimeState.setNotificationsActive(false);
-    await shutdownDbos();
+    await shutdownDbosQuietly();
   });
 }

package/dist/builtin/workflows/src/extension/public-types.ts

@@ -2,6 +2,7 @@ import type {
   CreateAgentSessionOptions,
   DefaultResourceLoaderInheritanceSnapshot,
 } from "@bastani/atomic";
+import type { Api, Model } from "@earendil-works/pi-ai/compat";
 import type { SessionManager } from "../shared/persistence-restore.js";
 import type { StageSessionRuntime } from "../runs/foreground/stage-runner.js";
 import type { RunStatus, StageStatus } from "../shared/store-types.js";
@@ -58,10 +59,7 @@ export interface PiCommandOptions {
   getArgumentCompletions?: (partial: string) => PiArgumentCompletionResult | Promise<PiArgumentCompletionResult>;
 }
 
-export interface PiRuntimeModel {
-  readonly provider: string;
-  readonly id: string;
-}
+export type PiRuntimeModel = Model<Api>;
 
 export interface PiRuntimeModelRegistry {
   getAvailable(): PiRuntimeModel[];
@@ -222,6 +220,7 @@ export interface WorkflowToolArgs {
   workflow?: string;
   inputs?: WorkflowInputValues;
   action?:
+    | "models"
     | "run"
     | "list"
     | "get"

package/dist/builtin/workflows/src/extension/render-call.ts

@@ -11,6 +11,7 @@ export interface WorkflowToolArgs {
   workflow?: string;
   inputs?: WorkflowInputValues;
   action?:
+    | "models"
     | "run"
     | "list"
     | "get"
@@ -106,6 +107,9 @@ export function renderCall(args: WorkflowToolArgs, opts: RenderCallOpts = {}): s
     case "get":
       line = name === undefined ? "workflow: get" : `workflow: get ${quoted(name)}`;
       break;
+    case "models":
+      line = "workflow: list configured models";
+      break;
     default:
       line = name === undefined ? `workflow: ${action}` : `workflow: ${action} ${quoted(name)}`;
       break;

package/dist/builtin/workflows/src/extension/render-result.ts

@@ -149,6 +149,14 @@ type ReloadResult = WorkflowReloadReport & { action: "reload"; status: "ok" | "n
 type InterruptResult = { action: "interrupt"; runId: string; status: string; message: string };
 type QuitResult = { action: "quit"; runId: string; status: string; message: string };
 type ResumeResult = { action: "resume"; runId: string; status: string; message: string };
+export interface ModelCatalogEntry {
+  provider: string;
+  id: string;
+  fullId: string;
+  isCurrent: boolean;
+  availableThinkingLevels?: readonly string[];
+}
+type ModelsResult = { action: "models"; models: ModelCatalogEntry[] };
 
 export type WorkflowToolResult =
   | ListResult
@@ -165,7 +173,8 @@ export type WorkflowToolResult =
   | ReloadResult
   | InterruptResult
   | QuitResult
-  | ResumeResult;
+  | ResumeResult
+  | ModelsResult;
 
 export interface RenderResultOpts {
   isPartial?: boolean;
@@ -432,6 +441,27 @@ export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts
       return renderNotice("WORKFLOW RESUME", `${r.runId}: ${r.message}`, opts, themed);
     }
 
+    case "models": {
+      const r = result as ModelsResult;
+      if (r.models.length === 0) {
+        return renderNotice("WORKFLOW MODELS", "no models in configured catalog — configured-auth snapshot, not proof of credentials, entitlements, OAuth freshness, or live provider access.", opts, themed);
+      }
+      const currentLine = r.models.find((model) => model.isCurrent);
+      const lines = r.models.map((model) => {
+        const levels = model.availableThinkingLevels?.length
+          ? ` [levels: ${model.availableThinkingLevels.join(", ")}]`
+          : "";
+        return `${model.provider}/${model.id}${model.isCurrent ? " (current)" : ""}${levels}`;
+      }).join("; ");
+      const suffix = currentLine !== undefined ? "" : " (no current model)";
+      return renderNotice(
+        "WORKFLOW MODELS",
+        `${lines}${suffix} — configured-auth catalog snapshot, not proof of credentials, entitlements, OAuth freshness, or live provider access.`,
+        opts,
+        themed,
+      );
+    }
+
     default: {
       // Runtime guard — handles values coerced from external sources.
       const fallback = result as { action: string; message?: string };

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -1,12 +1,14 @@
 export const WORKFLOW_TOOL_DESCRIPTION =
   "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; " +
   "when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; " +
-  "discover with list/get/inputs, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
+  "discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
   "send prompt answers or steering, pause/resume/interrupt/quit runs, and reload workflow resources. " +
   "For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
   "For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
   "quote the exact path without rewriting separators (Windows backslashes are valid), " +
-  "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.";
+  "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview. " +
+  "Use action 'models' to inspect models in the configured catalog; the result is a configured-auth snapshot showing what's present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. " +
+  "When authoring a workflow that should dynamically select a model, first call workflow({ action: 'models' }) to inspect the configured catalog, then select from the returned provider/id entries considering the isCurrent marker and available thinking levels.";
 
 export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   `**Workflows**: Treat workflows as the default execution path for any non-trivial task and for any request that has inherent structure plus an objective you can make verifiable. Use the \`workflow\` tool for existing named workflows; when the task needs a graph that is not installed, author a custom TypeScript \`workflow({...})\` inline with normal coding tools, reload workflow resources, and run it.
@@ -30,6 +32,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - When a user asks to create or edit a workflow, clarify only unresolved requirements that materially affect its purpose, inputs, stages, handoffs, validation, success criteria, or starter pattern. Read the workflow docs/examples, implement the TypeScript definition with normal coding tools, reload it, and run representative test inputs before presenting it. Use the create-spec skill when it adds value; it is not mandatory when context is already sufficient.
   - Consult docs/workflows.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done) when designing a stage graph.
   - Treat workflow composition as a first-class authoring option. Before duplicating stages, inspect reusable workflow modules and builtin exports; import their definitions and invoke them with \`ctx.workflow(...)\`, mapping typed inputs and consuming only declared outputs. Nested workflows can themselves import children, so combine small reusable graphs into a richer parent while respecting \`maxDepth\`.
+  - Prefer \`ctx.tool(name, args, fn)\` for workflow-owned TypeScript operations with side effects, such as filesystem writes, network mutations, and external API actions. A completed \`ctx.tool\` call is durably checkpointed with its serializable result, so resume replays that result without rerunning \`fn\`. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately; this rule applies to side effects orchestrated directly by the workflow definition.
   - Pass large stage context through files/artifacts and \`reads\` with an explicit \`Read the file at <path>...\` prompt rather than large \`previous\` payloads or injected session history.
   - Separate implementation/review acceptance from explicitly authorized final actions such as PR/MR/review creation, release tagging, deployment, or publication. Stop implementation loops once acceptance is proven and carry a remaining final action separately.
   - A model stage sees its local prompt, artifacts, tools, and reads, not the graph name or surrounding implementation. State the concrete action, evidence, and success criteria directly.`,

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -9,6 +9,7 @@ export const WorkflowParametersSchema = Type.Object({
     description: "Key/value inputs passed to a named workflow run.",
   })),
   action: Type.Optional(Type.Union([
+    Type.Literal("models"),
     Type.Literal("run"),
     Type.Literal("list"),
     Type.Literal("get"),
@@ -24,7 +25,7 @@ export const WorkflowParametersSchema = Type.Object({
     Type.Literal("resume"),
     Type.Literal("reload"),
   ], {
-    description: "Workflow action: run/list/get/inputs/status, inspect stage metadata, send messages or prompt answers, pause/resume/interrupt/quit runs, or reload workflow resources. 'status' without runId lists every workflow run in the current session with concise per-run summaries (status, timing, active stages, awaiting-input prompts); filter the listing with statusFilter. 'status' with runId returns one run's full detail. For transcript inspection, prefer status/stages/stage first to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.",
+    description: "Workflow action: run/list/get/inputs/models/status, inspect stage metadata, send messages or prompt answers, pause/resume/interrupt/quit runs, inspect the configured model catalog, or reload workflow resources. 'status' without runId lists every workflow run in the current session with concise per-run summaries (status, timing, active stages, awaiting-input prompts); filter the listing with statusFilter. 'status' with runId returns one run's full detail. For transcript inspection, prefer status/stages/stage first to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.",
   })),
   runId: Type.Optional(Type.String({
     description: "Run identifier or unique prefix for status/stages/stage/transcript/send/pause/resume/interrupt/quit. Omit runId with action 'status' to list all session runs and their statuses. Use '--all' or all:true for supported bulk run-control actions.",
@@ -54,7 +55,7 @@ export const WorkflowParametersSchema = Type.Object({
     description: "Filter stages (stages action) or listed runs (status action without runId) by status; 'all' (default) includes everything. For the status listing, run statuses match directly, 'awaiting_input' selects runs with at least one stage awaiting input or pending human prompt, and in-flight runs are listed first.",
   })),
   format: Type.Optional(Type.Union([Type.Literal("text"), Type.Literal("json")], {
-    description: "Agent-visible output format for data-bearing inspection actions (status, stages, stage, transcript); 'json' returns the full structured result.",
+    description: "Agent-visible output format for data-bearing inspection actions (models, status, stages, stage, transcript); 'json' returns the full structured result.",
   })),
   limit: Type.Optional(Type.Integer({
     minimum: 0,

package/dist/builtin/workflows/src/extension/workflow-tool-content.ts

@@ -219,6 +219,7 @@ export function renderWorkflowToolContent(
     case "inputs":
     case "get":
     case "run":
+    case "models":
       return stringifyWorkflowToolResult(result);
   }
 }