unfazed 0.5.0 → 0.6.0

package/README.md

@@ -18,6 +18,10 @@ SDK:  one script. Three requests. You read the four lines you cared about.
 ```
 
 - Zero runtime dependencies. Installing `unfazed` installs exactly one package.
+  (The optional [`unfazed/workflow`](#durable-workflows-unfazedworkflow) subpath
+  uses Workflow SDK packages your app installs; the root entry never loads them.)
+- `npx workflow inspect runs --backend unfazed`: Workflow SDK's CLI and web UI
+  read your app's runs through the platform ([details](#inspect-runs-from-your-terminal)).
 - Strict TypeScript, generated from the platform's own GraphQL schema.
 - Bun-first, runs unchanged on Node >= 20 and Deno.
 
@@ -413,6 +417,319 @@ So an agent working inside a run can create workspaces, deploy, and read logs
 through this same SDK with zero configuration and no credential ever written
 into the prompt.
 
+## Durable workflows: `unfazed/workflow`
+
+[Workflow SDK](https://workflow-sdk.dev) runs durable functions: a
+`"use workflow"` function orchestrates `"use step"` functions, survives
+crashes and redeploys, sleeps for minutes or months and waits for webhooks.
+`unfazed/workflow` is the **World** that runs it on unfazed:
+
+- run storage, streams and `await run.returnValue` are the upstream
+  `@workflow/world-postgres` code over **the app's own Postgres** (its
+  migrations are applied for you; the upstream graphile-worker queue is never
+  started);
+- the **queue is the platform's**: every wake-up (`sleep()`, a retry, the next
+  step, a resumed hook) is a delivery the unfazed worker makes to the app's flow
+  route, cold-starting an `on_demand` VM when it is asleep. Nothing needs a warm
+  process, so the default `on_demand` lifecycle is the right one.
+
+```sh
+bun add unfazed workflow @workflow/world-postgres nitro hono
+```
+
+`workflow`, `@workflow/core`, `@workflow/world`, `@workflow/world-postgres`,
+`pg`, `drizzle-orm` and `nitro` are **optional peer dependencies**: code-mode
+users of `unfazed` install none of them. `@workflow/core` arrives with
+`workflow`, and `@workflow/world`, `pg` and `drizzle-orm` with
+`@workflow/world-postgres`, under npm and Bun; with pnpm or Yarn PnP add them
+to the app as well.
+
+### With Nitro (the recipe)
+
+```ts
+// nitro.config.ts
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  modules: ["workflow/nitro", "unfazed/workflow/nitro"],
+  routes: { "/**": "./src/app.ts" },   // a Hono app; not named server.ts (Nitro claims that name)
+});
+```
+
+```json
+// unfazed.json — package.json has "build": "nitro build"
+{ "kind": "SERVICE", "runtime": "BUN", "install": "bun install", "build": "bun run build", "entry": "unfazed-entry.ts" }
+```
+
+```ts
+// unfazed-entry.ts
+export { default } from "./.output/server/index.mjs";
+```
+
+Then bind a Postgres or Neon integration to the app and deploy. In a
+production build the module:
+
+- installs the World with `setWorld(createWorld())` from a server plugin, which
+  Nitro runs before the first request (a bundle without `node_modules` cannot
+  load a World through `WORKFLOW_TARGET_WORLD`);
+- embeds the SQL migrations of **the app's own** `@workflow/world-postgres`, so
+  the schema always matches the storage code in the bundle;
+- answers anything that reaches `/.well-known/workflow/v1/flow` without the
+  platform's queue token with **401** (including the SDK's `?__health` probe).
+  Public ingress strips that header, so only the platform can deliver. The
+  webhook route stays public: its unguessable token is its authorization;
+- mounts the **inspection route** the unfazed dashboard and MCP read runs
+  through (below), with the build's workflow list and Workflow SDK version;
+- sets `noExternals: true` and builds Nitro's `standard` output (`export
+  default { fetch }`), which is what unfazed serves, whenever no preset was
+  chosen, whatever Nitro detected on the build machine: `bun` under Bun (as on
+  the unfazed build VM), `node-server` under Node, `deno-server` under Deno.
+  Their own outputs start a server of their own (under Bun with a 10 s idle
+  timeout that cuts every quiet workflow stream). A preset chosen explicitly
+  (`preset` in nitro.config.ts or .nitrorc, `NITRO_PRESET`, `SERVER_PRESET`)
+  other than `standard` **fails the build** with a message saying so; leave it
+  out, or set `preset: "standard"`.
+- serves public assets only when `serveStatic: "inline"` embeds them in the
+  bundle (a service VM has nothing next to it to read from disk). That is how
+  one service ships an API and its UI (`publicAssets: [{ dir: "dist" }]`
+  after a `vite build`).
+
+`nitro dev` is left alone and keeps the SDK's Local World.
+
+A complete app — steps, a retried step, `sleep`, a webhook (plain
+`createWebhook()` and `webhook.url`), a progress stream — is in
+[`examples/workflow-nitro`](./examples/workflow-nitro). Once it is deployed,
+`UNFZ_APP=<alias> npx workflow inspect runs --backend unfazed` lists its runs
+([Inspect runs from your terminal](#inspect-runs-from-your-terminal)).
+
+### Without Nitro
+
+Install the World in your framework's start-up hook, before it serves:
+
+```ts
+import { setWorld } from "workflow/runtime";
+import { createWorld } from "unfazed/workflow";
+
+setWorld(createWorld());   // Next.js: instrumentation.ts register(); SvelteKit: hooks.server.ts init
+```
+
+`createWorld()` is synchronous and opens nothing. Without the Nitro module the
+World applies the migrations embedded in this package (built from the
+`@workflow/world-postgres` version in its devDependencies), so keep the app's
+`@workflow/world-postgres` on that version.
+
+Mount the inspection route yourself, as a catch-all under its base path:
+
+```ts
+// e.g. Next.js: app/.well-known/workflow/v1/unfazed/inspect/v1/[op]/route.ts
+import { createInspectHandler } from "unfazed/workflow";
+
+const inspect = createInspectHandler({ workflowVersion: "5.2.2" });   // optional: workflows: [...names]
+export const GET = inspect;
+export const POST = inspect;
+```
+
+### Inspecting runs from the dashboard and MCP
+
+The app answers the platform's questions about its runs itself, on
+`/.well-known/workflow/v1/unfazed/inspect/v1/<op>` (unfazed
+`docs/workflow-inspect.md`, guest contract v1): `info`, `runs`, `run`, `steps`,
+`step`, `events`, `event` and `stream` read through the app's own World
+(`getWorld()`), so an `on_demand` app cold-starts for the request and holds no
+database connection afterwards; `wake` and `cancel` are Workflow SDK's own
+`getRun(id).wakeUp()` and `.cancel()`.
+
+- Only the platform can call it: anything without `X-Unfz-Queue-Token` equal to
+  `UNFZ_STATE_TOKEN` (compared in constant time) gets 401, and public ingress
+  strips that header. A World that failed to start answers 503
+  `world_unavailable` with its start error, which the owner sees.
+- Payloads (inputs, outputs, errors, event data, stream chunks) are hydrated
+  with `workflow/observability` on top of the SDK's common revivers and sent as
+  display text, cut at the contract's caps (16 KiB per input or output, 64 KiB
+  per event payload, 8 KiB per chunk); every answer stays under 1 MiB, a page
+  coming back shorter (with the World's cursor for the rest) when it must.
+- Hook tokens and webhook URLs never leave: hooks are shown by ID, kind and
+  state; every `token` key is dropped from event info and event data; every
+  occurrence of the run's hook tokens in an event's data reads `[redacted]`;
+  and every Workflow SDK webhook URL in any text the route returns (run and
+  step inputs and outputs, errors, event info and data, stream chunks,
+  attributes) has its token segment replaced, as
+  `https://app.example/.well-known/workflow/v1/webhook/[redacted]?answer=yes`,
+  also when percent-encoded inside another URL or written with JSON-escaped
+  slashes. That happens before any cap, so a cut never leaves part of a token.
+  Everything else the app writes is shown as written, as in its logs.
+- A step's input shows as its arguments: Workflow SDK stores it as
+  `{ args, closureVars, thisVal }`, and the route answers `args`, or
+  `{ args, closureVars?, thisVal? }` with only the parts that hold something
+  (any other stored shape is shown as it is).
+- A run page carries at most the latest 500 sleeps and 500 hooks
+  (`waits_truncated` / `hooks_truncated` say when there were more); a list
+  page may hold fewer items than `limit`, so callers page on `has_more`.
+
+### Inspect runs from your terminal
+
+Workflow SDK's own CLI reads an app's runs through the platform, the way
+`--backend vercel` reads a Vercel project. From the app's project (where
+`unfazed` is installed; the CLI loads `createWorld()` from it):
+
+```sh
+export UNFZ_API_TOKEN=...          # a token from https://unfazed.dev/auth.md
+UNFZ_APP=birthday-card npx workflow inspect runs --backend unfazed
+```
+
+```
+runId                            workflowName          status     startedAt                completedAt
+-------------------------------  --------------------  ---------  -----------------------  -----------------------
+wrun_01KPBDAY00000000000000RN01  generateBirthdayCard  running    2026-10-15 09:30:01.000
+wrun_01KPBDAY00000000000000RN02  generateBirthdayCard  completed  2026-10-15 09:10:01.000  2026-10-15 09:12:00.000
+wrun_01KPBDAY00000000000000RN03  generateBirthdayCard  failed     2026-10-15 09:05:01.000  2026-10-15 09:06:00.000
+```
+
+```sh
+npx workflow inspect run <run-id> --backend unfazed               # input, output, error
+npx workflow inspect steps --runId <run-id> --backend unfazed     # also: events, hooks, sleeps, streams
+npx workflow inspect step <step-id> --runId <run-id> --backend unfazed
+npx workflow inspect stream <stream-id> --runId <run-id> --backend unfazed   # follows it while the run writes
+npx workflow cancel <run-id> --backend unfazed
+npx workflow web --backend unfazed                                # the local web UI: trace, events, streams,
+                                                                  # Wake Up Sleep and Cancel
+```
+
+The usual options work (`--json`, `--limit`, `--cursor`, `--all`, `--status`,
+`--workflowName`, `--interactive`); the exceptions are below.
+`export WORKFLOW_TARGET_WORLD=unfazed` saves typing `--backend`.
+
+- **Which app:** `UNFZ_APP` (its alias, the `<alias>` of
+  `https://<alias>.unfz.to`); without it, the `alias` in `./unfazed.json`, or
+  its only `apps[]` entry. `UNFZ_API_URL` points at another control plane.
+- **The token** needs `unfz:read`; cancel and Wake Up Sleep need `unfz:deploy`
+  too, and the caller must be allowed to restart the app (owner, team member,
+  operator).
+- **Every command is one platform call relayed to the app**, through the same
+  inspection route the dashboard reads; an `on_demand` app cold-starts for it,
+  as for a visitor.
+
+What differs from `--backend vercel`:
+
+- **Payloads are the inspection route's display data**: hydrated inside the
+  app and cut at its caps (16 KiB per run or step input and output, 64 KiB
+  per event payload, 8 KiB per stream chunk). A cut value is a string ending
+  in `… [truncated by unfazed inspection: N bytes in full]`. Values are JSON:
+  a `Date` reads as its ISO string, a `Map`, `Set`, bytes or `Error` as
+  `{"$map": …}`, `{"$set": …}`, `{"$bytes": n}`, `{"$error": …}`. A payload the
+  app could not read is `[unreadable payload: <why>]`. Run data on unfazed is
+  not encrypted, so `--decrypt` has nothing to do.
+- **Hook tokens never leave the app**: hooks show `token: "[redacted]"`, and
+  the web UI cannot resume a hook.
+- **List views carry no payloads**, so `--withData` (deprecated by the CLI for
+  lists) shows none; `inspect run <id>` and `inspect step <id>` do. Listed
+  events carry their metadata, `inspect event <id>` its payload.
+- **No analytics read path**: `--attribute`, `--since`/`--until` and `inspect
+  attributes` need one, and the CLI says it is ignored or unavailable.
+- **Runs list newest first only** (`--sort asc` is refused). A run's steps
+  newest first (the CLI's default) are read whole, up to 2 000, and paged
+  locally.
+- **Hooks are found through their run**: `inspect hooks` without `--runId`,
+  and `inspect hook <id>`, look through the app's running and pending runs.
+- **A run page reads at most 10 000 events**, the latest 500 sleeps and 500
+  hooks, and 50 streams (the route's limits).
+- **Writes**: cancel (`workflow cancel`, bulk cancel, the web UI) and wake-up
+  (the web UI) go through the platform. Everything else (replay, re-enqueue,
+  resuming a hook, starting a run) is refused: this backend is read-only, and
+  an app's own World is `unfazed/workflow`. Setting
+  `WORKFLOW_TARGET_WORLD=unfazed` inside an app fails loudly for the same
+  reason.
+
+### How it behaves
+
+- **Start-up is lazy and cheap.** The first World call of a process applies the
+  migrations (one query when the database is current) and probes the platform
+  queue; every call waits for that, so a request arriving during a cold start
+  waits instead of failing. Active runs are then re-enqueued in the background
+  with the key `reenqueue:<runId>:<deploymentId>`, which the platform drops as
+  a duplicate while that message is stored and for an hour after it settles,
+  so a run asleep for days is not re-enqueued on every cold start.
+  `world.start()` does the same and lets you await it.
+- **No warm process, no lingering connections.** Postgres connections,
+  including the `LISTEN` ones behind stream readers and
+  `waitForTerminalStatus`, are held only while a World call or a stream reader
+  is open (plus 2 s); idle pool connections close after 5 s. A reaped VM leaves
+  nothing behind on the database.
+- **Deliveries** carry `X-Unfz-Queue-*` headers; the handler checks the token
+  in constant time against `UNFZ_STATE_TOKEN`, maps the rest to the SDK's
+  message metadata, and reports the delivery deadline (15 minutes from the
+  moment the VM was ready, so a cold start does not shorten it) through
+  `getRuntimeDeadline()`, so the SDK sizes its inline work to fit. Every answer
+  is a complete JSON body and never a redirect (the platform follows none, and
+  retries a 3xx or a broken 2xx body).
+- **Concurrency:** at most 32 deliveries per app are open at once. Set it per
+  app in `unfazed.json` with `"workflow": {"concurrency": N}` (1 to 256;
+  `workflow_concurrency` on `create_service_deployment` for an app deployed
+  from a workspace). A step that awaits a child run holds one delivery for the
+  child's whole run, so keep the concurrency above the number of such waits.
+  When the VM stops on its own under deliveries (out of memory, a crash), the
+  platform halves the app's concurrency for 5 minutes and records a
+  `service.workflow_throttled` event.
+- **Routes for other queue consumers:** `world.registerRoute(prefix, path)` is
+  stored on the platform. `registerHandler()` is not offered: the platform
+  delivers over HTTP, never inside a process.
+- **Webhook URLs need no code.** `createWebhook().url` (and
+  `getWorkflowMetadata().url`) are built on the app's public address. Workflow
+  SDK 5.x reads only `VERCEL_URL` for that (`https://${VERCEL_URL}`, else
+  `http://localhost:<port>`), so when `VERCEL_URL` is unset and
+  `UNFZ_PUBLIC_URL` is a bare https host — a custom domain or
+  `https://<alias>.unfz.to` — `createWorld()` sets `VERCEL_URL` to that host in
+  the app's own process. Inside the SDK that variable decides nothing else
+  (it also skips probing for the local port, which is then unneeded). Your own
+  code and libraries see it too, as the public host. Opt out with
+  `createWorld({ publicUrl: false })`; an explicit `VERCEL_URL` is never
+  changed.
+
+  A **path-form** public URL (`https://app.unfazed.dev/<alias>`) cannot be
+  passed that way: the SDK's base path is fixed at build time and Workflow
+  SDK's Nitro integration sets none. Those apps build the URL in a step:
+
+  ```ts
+  async function publicWebhookUrl(token: string) {
+    "use step";
+    return `${process.env.UNFZ_PUBLIC_URL}/.well-known/workflow/v1/webhook/${token}`;
+  }
+  ```
+- **Errors** are `UnfazedWorkflowError` with a `code`: `no_database` (bind a
+  Postgres or Neon integration), `no_platform` (not inside an unfazed service),
+  `queue_not_supported` (the worker has no queue yet), `queue_unavailable`,
+  `quota_exceeded` (its message names the limit: 100 000 pending messages,
+  64 MiB of live messages or 200 000 idempotency keys), `payload_too_large`
+  (over 1 MiB), `unavailable` (503 or network, after 30 s of retries with the
+  same idempotency keys), …
+
+| Read from | Meaning |
+| --- | --- |
+| `WORKFLOW_POSTGRES_URL`, `DATABASE_URL_UNPOOLED`, `DATABASE_URL` | run storage, first one set; `sslmode=require` gets `uselibpqcompat=true` |
+| `WORKFLOW_POSTGRES_MAX_POOL_SIZE` | pool size (default 10) |
+| `UNFZ_STATE_URL`, `UNFZ_STATE_TOKEN` | the platform queue and the delivery token (injected by unfazed) |
+| `UNFZ_DEPLOYMENT_ID` | `getDeploymentId()` |
+| `UNFZ_PUBLIC_URL` | the public address webhook URLs are built on (see above) |
+
+`createWorld({ ... })` takes the same settings as options (`connectionString`,
+`stateUrl`, `stateToken`, `deploymentId`, `maxPoolSize`, `migrations`,
+`publicUrl`, `retryBudgetMs`, `idleReleaseMs`, `env`, `fetch`).
+
+### Testing it
+
+```sh
+bun test                                           # unit tests, incl. a fake platform implementing the wire contract
+export UNFAZED_TEST_DATABASE_URL=postgres://...    # a database whose user may CREATE DATABASE
+bun test test/workflow                             # + the World against Postgres
+WORKFLOW_POSTGRES_URL=$UNFAZED_TEST_DATABASE_URL bun run test:conformance
+                                                   # the SDK's World conformance suite, and every
+                                                   # delivery cold-started in a fresh process
+bun run test:example                               # the example, bundled as unfazed builds it,
+                                                   # one fresh process per delivery and request
+bun run test:cli                                   # Workflow SDK's CLI with --backend unfazed (and --web)
+                                                   # against a fake of the platform's inspection API
+```
+
 ## Development
 
 ```sh
@@ -424,6 +741,10 @@ bun run build
 bun run check        # all of the above, plus a dist smoke test on Bun AND Node
 ```
 
+After bumping the `@workflow/world-postgres` devDependency, run
+`bun run embed-migrations`: `bun run check` fails while
+`src/workflow/migrations.generated.ts` is stale.
+
 ### Regenerating from the schema
 
 `schema/schema.graphqls` is a **vendored copy** of `graph/schema.graphqls` from

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 /** SDK version, sent as the User-Agent. Keep in sync with package.json. */
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";
 /**
  * Default GraphQL endpoint.
  *

package/dist/client.js

@@ -1,6 +1,6 @@
 import { UnfazedAuthError, UnfazedConfigError, UnfazedGraphQLError, UnfazedHTTPError, UnfazedTimeoutError, } from "./errors.js";
 /** SDK version, sent as the User-Agent. Keep in sync with package.json. */
-export const VERSION = "0.5.0";
+export const VERSION = "0.6.0";
 /**
  * Default GraphQL endpoint.
  *

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  UnfazedAuthError,\n  UnfazedConfigError,\n  UnfazedGraphQLError,\n  UnfazedHTTPError,\n  UnfazedTimeoutError,\n  type GraphQLResponseError,\n} from \"./errors.js\";\n\n/** SDK version, sent as the User-Agent. Keep in sync with package.json. */\nexport const VERSION = \"0.5.0\";\n\n/**\n * Default GraphQL endpoint.\n *\n * Note this is the FULL endpoint, not an origin: the platform's own documented\n * convention (`UNFZ_API_URL=\"https://unfazed.dev/query\"`, and cmd/showcase-deploy\n * in the unfazed repo) treats the /query URL as the configurable unit, so the\n * SDK matches it rather than inventing a base-URL convention.\n */\nexport const DEFAULT_ENDPOINT = \"https://unfazed.dev/query\";\n\n/** Platform origin, used to derive the endpoint when only `baseUrl` is given. */\nexport const DEFAULT_BASE_URL = \"https://unfazed.dev\";\n\n/** Path of the GraphQL endpoint under an origin. */\nexport const GRAPHQL_PATH = \"/query\";\n\n/**\n * Environment variable holding the bearer token.\n *\n * This is the platform's documented name (docs/agent-deployments.md,\n * internal/agentdocs/reference.md). It accepts either an operator API token or\n * an agent access token from POST /agents/register — /query takes both as\n * plain bearers.\n */\nexport const TOKEN_ENV_VAR = \"UNFZ_API_TOKEN\";\n\n/** Environment variable holding the full GraphQL endpoint URL. */\nexport const ENDPOINT_ENV_VAR = \"UNFZ_API_URL\";\n\n/** Minimal structural type of the `fetch` the transport needs. */\nexport type FetchLike = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n    body: string;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  text(): Promise<string>;\n}>;\n\nexport interface ClientOptions {\n  /**\n   * Bearer token. Falls back to `UNFZ_API_TOKEN`. Get one from\n   * https://unfazed.dev/auth.md — the same token the MCP server uses.\n   */\n  token?: string;\n  /**\n   * Full GraphQL endpoint URL. Wins over `baseUrl`. Falls back to\n   * `UNFZ_API_URL`, then {@link DEFAULT_ENDPOINT}.\n   */\n  endpoint?: string;\n  /**\n   * Platform origin; `/query` is appended. Convenience for self-hosted or\n   * staging control planes where only the host differs.\n   */\n  baseUrl?: string;\n  /** Extra headers merged into every request. Authorization always wins. */\n  headers?: Record<string, string>;\n  /**\n   * Per-request timeout in ms. Default 60_000. Pass 0 to disable.\n   *\n   * Bounds the WHOLE request — connect, headers and reading the response body —\n   * so a proxy that answers with headers and then stalls still fails on time.\n   */\n  timeoutMs?: number;\n  /** Injection point for tests and instrumented/proxied transports. */\n  fetch?: FetchLike;\n  /** Overrides the default `unfazed-sdk/<version>` User-Agent. */\n  userAgent?: string;\n}\n\n/**\n * A GraphQL document.\n *\n * Structural rather than `string & {...}` on purpose: graphql-codegen emits\n * `TypedDocumentString`, a String SUBCLASS, which is not assignable to the\n * primitive `string`. Requiring only `toString()` plus the optional phantom\n * `__apiType` lets three things through with full inference:\n *\n *  - generated `TypedDocumentString` documents (types inferred),\n *  - documents assembled at runtime, like the batched writeFiles mutation,\n *  - plain template-literal strings a caller wrote by hand.\n */\nexport interface GraphQLDocument<TResult, TVariables> {\n  /** Phantom type carrier. Never called; present only to bind the generics. */\n  __apiType?: (variables: TVariables) => TResult;\n  toString(): string;\n}\n\n/** Result type carried by a typed document. */\nexport type ResultOf<T> = T extends GraphQLDocument<infer R, infer _V> ? R : unknown;\n\n/** Variables type carried by a typed document. */\nexport type VariablesOf<T> = T extends GraphQLDocument<infer _R, infer V> ? V : never;\n\n/** Per-request knobs. */\nexport interface RequestOptions {\n  signal?: AbortSignal;\n  timeoutMs?: number;\n  operationName?: string;\n}\n\n/**\n * Layer 1 — a typed, dependency-free GraphQL transport over `fetch`.\n *\n * This is the SDK's entire networking surface. It understands auth, timeouts\n * and the GraphQL error envelope, and nothing about deployments. The workflow\n * layer ({@link import(\"./unfazed.js\").Unfazed}) is built strictly on top of\n * it, so you can always drop down here for any operation the workflow layer\n * does not wrap — the schema has ~660 fields and the workflow layer\n * deliberately covers only the agent-facing ones.\n *\n * ```ts\n * const client = new UnfazedClient();               // reads UNFZ_API_TOKEN\n * const data = await client.query<{ whoami: { name: string } }, never>(\n *   `query { whoami { name } }`,\n * );\n * ```\n */\nexport class UnfazedClient {\n  /** Resolved GraphQL endpoint URL. */\n  readonly endpoint: string;\n\n  readonly #token: string;\n  readonly #headers: Record<string, string>;\n  readonly #timeoutMs: number;\n  readonly #fetch: FetchLike;\n\n  constructor(options: ClientOptions = {}) {\n    const token = options.token ?? readEnv(TOKEN_ENV_VAR);\n    if (!token) {\n      throw new UnfazedAuthError(\n        `unfazed: no API token. Pass { token } or set ${TOKEN_ENV_VAR}. ` +\n          `Get one at ${DEFAULT_BASE_URL}/auth.md`,\n      );\n    }\n    this.#token = token.trim();\n\n    this.endpoint = resolveEndpoint(options);\n\n    this.#headers = { ...(options.headers ?? {}) };\n    this.#timeoutMs = options.timeoutMs ?? 60_000;\n\n    const injected = options.fetch;\n    if (injected) {\n      this.#fetch = injected;\n    } else {\n      const globalFetch = (globalThis as { fetch?: unknown }).fetch;\n      if (typeof globalFetch !== \"function\") {\n        throw new UnfazedConfigError(\n          \"unfazed: no global fetch. Use Bun, Node >= 20, or pass { fetch } to the client.\",\n        );\n      }\n      this.#fetch = globalFetch.bind(globalThis) as FetchLike;\n    }\n\n    const ua = options.userAgent ?? `unfazed-sdk/${VERSION}`;\n    if (ua) this.#headers[\"User-Agent\"] = ua;\n  }\n\n  /** Runs a query document. Identical wire behaviour to {@link mutate}. */\n  query<TResult, TVariables>(\n    document: GraphQLDocument<TResult, TVariables>,\n    variables?: TVariables,\n    options?: RequestOptions,\n  ): Promise<TResult> {\n    return this.request(document, variables, options);\n  }\n\n  /**\n   * Runs a mutation document. Distinct from {@link query} for call-site\n   * readability only — GraphQL over HTTP POST makes no distinction.\n   */\n  mutate<TResult, TVariables>(\n    document: GraphQLDocument<TResult, TVariables>,\n    variables?: TVariables,\n    options?: RequestOptions,\n  ): Promise<TResult> {\n    return this.request(document, variables, options);\n  }\n\n  /**\n   * The single code path behind {@link query} and {@link mutate}.\n   *\n   * Throws {@link UnfazedHTTPError} on non-2xx, {@link UnfazedGraphQLError}\n   * when the body carries `errors`, {@link UnfazedTimeoutError} on timeout or\n   * abort. Resolves to the `data` object on success.\n   */\n  async request<TResult = unknown>(\n    document: string | { toString(): string },\n    variables?: unknown,\n    options: RequestOptions = {},\n  ): Promise<TResult> {\n    const timeoutMs = options.timeoutMs ?? this.#timeoutMs;\n    const { signal, cleanup, didTimeout } = makeSignal(timeoutMs, options.signal);\n\n    // `document` may be a TypedDocumentString (a String object). JSON.stringify\n    // would serialise that fine, but String(...) keeps the wire body a plain\n    // primitive regardless of how the caller obtained the document.\n    const body = JSON.stringify({\n      query: String(document),\n      ...(variables === undefined ? {} : { variables }),\n      ...(options.operationName ? { operationName: options.operationName } : {}),\n    });\n\n    // The deadline covers BOTH phases — headers AND body. A proxy that answers\n    // with headers and then stalls the body is a real failure mode, and\n    // stopping the clock at the end of `fetch()` would leave `response.text()`\n    // hanging forever. `untilAborted` additionally races the signal itself, so\n    // an injected transport that ignores `signal` still cannot outlive the\n    // timeout.\n    let response: Awaited<ReturnType<FetchLike>>;\n    let text: string;\n    try {\n      response = await untilAborted(\n        this.#fetch(this.endpoint, {\n          method: \"POST\",\n          headers: {\n            ...this.#headers,\n            \"Content-Type\": \"application/json\",\n            Accept: \"application/json\",\n            Authorization: `Bearer ${this.#token}`,\n          },\n          body,\n          ...(signal ? { signal } : {}),\n        }),\n        signal,\n      );\n      text = await untilAborted(response.text(), signal);\n    } catch (cause) {\n      if (didTimeout()) {\n        throw new UnfazedTimeoutError(`unfazed: request timed out after ${timeoutMs}ms`, { cause });\n      }\n      if (isAbort(cause)) {\n        throw new UnfazedTimeoutError(\"unfazed: request aborted\", { cause });\n      }\n      throw cause;\n    } finally {\n      cleanup();\n    }\n\n    if (!response.ok) {\n      throw new UnfazedHTTPError(response.status, text, this.endpoint);\n    }\n\n    let parsed: { data?: TResult; errors?: GraphQLResponseError[] };\n    try {\n      parsed = JSON.parse(text) as typeof parsed;\n    } catch {\n      throw new UnfazedHTTPError(response.status, text, this.endpoint);\n    }\n\n    // A GraphQL 200 can still be a failure, and can be a PARTIAL failure: the\n    // batched writeFiles document resolves each aliased field independently.\n    // Attaching `data` to the error is what lets a caller see which writes\n    // landed before the failing one.\n    if (parsed.errors?.length) {\n      throw new UnfazedGraphQLError(parsed.errors, parsed.data);\n    }\n    if (parsed.data === undefined || parsed.data === null) {\n      throw new UnfazedGraphQLError(\n        [{ message: \"response contained neither data nor errors\" }],\n        undefined,\n      );\n    }\n    return parsed.data;\n  }\n}\n\nfunction resolveEndpoint(options: ClientOptions): string {\n  if (options.endpoint) return options.endpoint;\n  if (options.baseUrl) return trimSlash(options.baseUrl) + GRAPHQL_PATH;\n  const env = readEnv(ENDPOINT_ENV_VAR);\n  // UNFZ_API_URL is documented as the full /query URL and is used verbatim.\n  // Tolerate a bare origin anyway, since that is the obvious mistake and\n  // guessing right costs nothing.\n  if (env) {\n    const trimmed = trimSlash(env);\n    return /\\/query$|\\/graphql$/.test(trimmed) ? trimmed : trimmed + GRAPHQL_PATH;\n  }\n  return DEFAULT_ENDPOINT;\n}\n\nfunction readEnv(name: string): string | undefined {\n  // Guarded: the SDK must also work in a browser or worker, where there is no\n  // `process` at all.\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process\n    ?.env;\n  return env?.[name] || undefined;\n}\n\nfunction trimSlash(u: string): string {\n  return u.replace(/\\/+$/, \"\");\n}\n\nfunction isAbort(e: unknown): boolean {\n  return typeof e === \"object\" && e !== null && (e as { name?: string }).name === \"AbortError\";\n}\n\nfunction abortError(): Error {\n  const e = new Error(\"The operation was aborted.\");\n  e.name = \"AbortError\";\n  return e;\n}\n\n/**\n * Settles with `promise`, or rejects the moment `signal` aborts.\n *\n * A global `fetch` honours the signal for headers and body alike, but an\n * injected {@link FetchLike} — a proxy, an instrumented transport, a test\n * double — need not. Racing the signal makes the timeout an upper bound on the\n * whole request regardless of what the transport does with it. The loser's\n * rejection is swallowed by the already-settled promise rather than surfacing\n * as an unhandled rejection.\n */\nfunction untilAborted<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {\n  if (!signal) return promise;\n  if (signal.aborted) return Promise.reject(abortError());\n  return new Promise<T>((resolve, reject) => {\n    const onAbort = () => reject(abortError());\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n    const done = () => signal.removeEventListener(\"abort\", onAbort);\n    promise.then(\n      (value) => {\n        done();\n        resolve(value);\n      },\n      (error: unknown) => {\n        done();\n        reject(error as Error);\n      },\n    );\n  });\n}\n\n/**\n * Combines the request timeout with any caller-supplied signal.\n *\n * `didTimeout` is tracked separately from the abort so a caller's own\n * cancellation is not mislabelled as a timeout in the thrown message.\n */\nfunction makeSignal(\n  timeoutMs: number,\n  external?: AbortSignal,\n): { signal?: AbortSignal; cleanup: () => void; didTimeout: () => boolean } {\n  if (!timeoutMs && !external) return { cleanup: () => {}, didTimeout: () => false };\n  if (typeof AbortController !== \"function\") {\n    return {\n      ...(external ? { signal: external } : {}),\n      cleanup: () => {},\n      didTimeout: () => false,\n    };\n  }\n\n  const controller = new AbortController();\n  let timedOut = false;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  if (timeoutMs > 0) {\n    timer = setTimeout(() => {\n      timedOut = true;\n      controller.abort();\n    }, timeoutMs);\n  }\n\n  const onExternalAbort = () => controller.abort();\n  if (external) {\n    if (external.aborted) controller.abort();\n    else external.addEventListener(\"abort\", onExternalAbort, { once: true });\n  }\n\n  return {\n    signal: controller.signal,\n    cleanup: () => {\n      if (timer !== undefined) clearTimeout(timer);\n      external?.removeEventListener(\"abort\", onExternalAbort);\n    },\n    didTimeout: () => timedOut,\n  };\n}\n"]}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  UnfazedAuthError,\n  UnfazedConfigError,\n  UnfazedGraphQLError,\n  UnfazedHTTPError,\n  UnfazedTimeoutError,\n  type GraphQLResponseError,\n} from \"./errors.js\";\n\n/** SDK version, sent as the User-Agent. Keep in sync with package.json. */\nexport const VERSION = \"0.6.0\";\n\n/**\n * Default GraphQL endpoint.\n *\n * Note this is the FULL endpoint, not an origin: the platform's own documented\n * convention (`UNFZ_API_URL=\"https://unfazed.dev/query\"`, and cmd/showcase-deploy\n * in the unfazed repo) treats the /query URL as the configurable unit, so the\n * SDK matches it rather than inventing a base-URL convention.\n */\nexport const DEFAULT_ENDPOINT = \"https://unfazed.dev/query\";\n\n/** Platform origin, used to derive the endpoint when only `baseUrl` is given. */\nexport const DEFAULT_BASE_URL = \"https://unfazed.dev\";\n\n/** Path of the GraphQL endpoint under an origin. */\nexport const GRAPHQL_PATH = \"/query\";\n\n/**\n * Environment variable holding the bearer token.\n *\n * This is the platform's documented name (docs/agent-deployments.md,\n * internal/agentdocs/reference.md). It accepts either an operator API token or\n * an agent access token from POST /agents/register — /query takes both as\n * plain bearers.\n */\nexport const TOKEN_ENV_VAR = \"UNFZ_API_TOKEN\";\n\n/** Environment variable holding the full GraphQL endpoint URL. */\nexport const ENDPOINT_ENV_VAR = \"UNFZ_API_URL\";\n\n/** Minimal structural type of the `fetch` the transport needs. */\nexport type FetchLike = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n    body: string;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  text(): Promise<string>;\n}>;\n\nexport interface ClientOptions {\n  /**\n   * Bearer token. Falls back to `UNFZ_API_TOKEN`. Get one from\n   * https://unfazed.dev/auth.md — the same token the MCP server uses.\n   */\n  token?: string;\n  /**\n   * Full GraphQL endpoint URL. Wins over `baseUrl`. Falls back to\n   * `UNFZ_API_URL`, then {@link DEFAULT_ENDPOINT}.\n   */\n  endpoint?: string;\n  /**\n   * Platform origin; `/query` is appended. Convenience for self-hosted or\n   * staging control planes where only the host differs.\n   */\n  baseUrl?: string;\n  /** Extra headers merged into every request. Authorization always wins. */\n  headers?: Record<string, string>;\n  /**\n   * Per-request timeout in ms. Default 60_000. Pass 0 to disable.\n   *\n   * Bounds the WHOLE request — connect, headers and reading the response body —\n   * so a proxy that answers with headers and then stalls still fails on time.\n   */\n  timeoutMs?: number;\n  /** Injection point for tests and instrumented/proxied transports. */\n  fetch?: FetchLike;\n  /** Overrides the default `unfazed-sdk/<version>` User-Agent. */\n  userAgent?: string;\n}\n\n/**\n * A GraphQL document.\n *\n * Structural rather than `string & {...}` on purpose: graphql-codegen emits\n * `TypedDocumentString`, a String SUBCLASS, which is not assignable to the\n * primitive `string`. Requiring only `toString()` plus the optional phantom\n * `__apiType` lets three things through with full inference:\n *\n *  - generated `TypedDocumentString` documents (types inferred),\n *  - documents assembled at runtime, like the batched writeFiles mutation,\n *  - plain template-literal strings a caller wrote by hand.\n */\nexport interface GraphQLDocument<TResult, TVariables> {\n  /** Phantom type carrier. Never called; present only to bind the generics. */\n  __apiType?: (variables: TVariables) => TResult;\n  toString(): string;\n}\n\n/** Result type carried by a typed document. */\nexport type ResultOf<T> = T extends GraphQLDocument<infer R, infer _V> ? R : unknown;\n\n/** Variables type carried by a typed document. */\nexport type VariablesOf<T> = T extends GraphQLDocument<infer _R, infer V> ? V : never;\n\n/** Per-request knobs. */\nexport interface RequestOptions {\n  signal?: AbortSignal;\n  timeoutMs?: number;\n  operationName?: string;\n}\n\n/**\n * Layer 1 — a typed, dependency-free GraphQL transport over `fetch`.\n *\n * This is the SDK's entire networking surface. It understands auth, timeouts\n * and the GraphQL error envelope, and nothing about deployments. The workflow\n * layer ({@link import(\"./unfazed.js\").Unfazed}) is built strictly on top of\n * it, so you can always drop down here for any operation the workflow layer\n * does not wrap — the schema has ~660 fields and the workflow layer\n * deliberately covers only the agent-facing ones.\n *\n * ```ts\n * const client = new UnfazedClient();               // reads UNFZ_API_TOKEN\n * const data = await client.query<{ whoami: { name: string } }, never>(\n *   `query { whoami { name } }`,\n * );\n * ```\n */\nexport class UnfazedClient {\n  /** Resolved GraphQL endpoint URL. */\n  readonly endpoint: string;\n\n  readonly #token: string;\n  readonly #headers: Record<string, string>;\n  readonly #timeoutMs: number;\n  readonly #fetch: FetchLike;\n\n  constructor(options: ClientOptions = {}) {\n    const token = options.token ?? readEnv(TOKEN_ENV_VAR);\n    if (!token) {\n      throw new UnfazedAuthError(\n        `unfazed: no API token. Pass { token } or set ${TOKEN_ENV_VAR}. ` +\n          `Get one at ${DEFAULT_BASE_URL}/auth.md`,\n      );\n    }\n    this.#token = token.trim();\n\n    this.endpoint = resolveEndpoint(options);\n\n    this.#headers = { ...(options.headers ?? {}) };\n    this.#timeoutMs = options.timeoutMs ?? 60_000;\n\n    const injected = options.fetch;\n    if (injected) {\n      this.#fetch = injected;\n    } else {\n      const globalFetch = (globalThis as { fetch?: unknown }).fetch;\n      if (typeof globalFetch !== \"function\") {\n        throw new UnfazedConfigError(\n          \"unfazed: no global fetch. Use Bun, Node >= 20, or pass { fetch } to the client.\",\n        );\n      }\n      this.#fetch = globalFetch.bind(globalThis) as FetchLike;\n    }\n\n    const ua = options.userAgent ?? `unfazed-sdk/${VERSION}`;\n    if (ua) this.#headers[\"User-Agent\"] = ua;\n  }\n\n  /** Runs a query document. Identical wire behaviour to {@link mutate}. */\n  query<TResult, TVariables>(\n    document: GraphQLDocument<TResult, TVariables>,\n    variables?: TVariables,\n    options?: RequestOptions,\n  ): Promise<TResult> {\n    return this.request(document, variables, options);\n  }\n\n  /**\n   * Runs a mutation document. Distinct from {@link query} for call-site\n   * readability only — GraphQL over HTTP POST makes no distinction.\n   */\n  mutate<TResult, TVariables>(\n    document: GraphQLDocument<TResult, TVariables>,\n    variables?: TVariables,\n    options?: RequestOptions,\n  ): Promise<TResult> {\n    return this.request(document, variables, options);\n  }\n\n  /**\n   * The single code path behind {@link query} and {@link mutate}.\n   *\n   * Throws {@link UnfazedHTTPError} on non-2xx, {@link UnfazedGraphQLError}\n   * when the body carries `errors`, {@link UnfazedTimeoutError} on timeout or\n   * abort. Resolves to the `data` object on success.\n   */\n  async request<TResult = unknown>(\n    document: string | { toString(): string },\n    variables?: unknown,\n    options: RequestOptions = {},\n  ): Promise<TResult> {\n    const timeoutMs = options.timeoutMs ?? this.#timeoutMs;\n    const { signal, cleanup, didTimeout } = makeSignal(timeoutMs, options.signal);\n\n    // `document` may be a TypedDocumentString (a String object). JSON.stringify\n    // would serialise that fine, but String(...) keeps the wire body a plain\n    // primitive regardless of how the caller obtained the document.\n    const body = JSON.stringify({\n      query: String(document),\n      ...(variables === undefined ? {} : { variables }),\n      ...(options.operationName ? { operationName: options.operationName } : {}),\n    });\n\n    // The deadline covers BOTH phases — headers AND body. A proxy that answers\n    // with headers and then stalls the body is a real failure mode, and\n    // stopping the clock at the end of `fetch()` would leave `response.text()`\n    // hanging forever. `untilAborted` additionally races the signal itself, so\n    // an injected transport that ignores `signal` still cannot outlive the\n    // timeout.\n    let response: Awaited<ReturnType<FetchLike>>;\n    let text: string;\n    try {\n      response = await untilAborted(\n        this.#fetch(this.endpoint, {\n          method: \"POST\",\n          headers: {\n            ...this.#headers,\n            \"Content-Type\": \"application/json\",\n            Accept: \"application/json\",\n            Authorization: `Bearer ${this.#token}`,\n          },\n          body,\n          ...(signal ? { signal } : {}),\n        }),\n        signal,\n      );\n      text = await untilAborted(response.text(), signal);\n    } catch (cause) {\n      if (didTimeout()) {\n        throw new UnfazedTimeoutError(`unfazed: request timed out after ${timeoutMs}ms`, { cause });\n      }\n      if (isAbort(cause)) {\n        throw new UnfazedTimeoutError(\"unfazed: request aborted\", { cause });\n      }\n      throw cause;\n    } finally {\n      cleanup();\n    }\n\n    if (!response.ok) {\n      throw new UnfazedHTTPError(response.status, text, this.endpoint);\n    }\n\n    let parsed: { data?: TResult; errors?: GraphQLResponseError[] };\n    try {\n      parsed = JSON.parse(text) as typeof parsed;\n    } catch {\n      throw new UnfazedHTTPError(response.status, text, this.endpoint);\n    }\n\n    // A GraphQL 200 can still be a failure, and can be a PARTIAL failure: the\n    // batched writeFiles document resolves each aliased field independently.\n    // Attaching `data` to the error is what lets a caller see which writes\n    // landed before the failing one.\n    if (parsed.errors?.length) {\n      throw new UnfazedGraphQLError(parsed.errors, parsed.data);\n    }\n    if (parsed.data === undefined || parsed.data === null) {\n      throw new UnfazedGraphQLError(\n        [{ message: \"response contained neither data nor errors\" }],\n        undefined,\n      );\n    }\n    return parsed.data;\n  }\n}\n\nfunction resolveEndpoint(options: ClientOptions): string {\n  if (options.endpoint) return options.endpoint;\n  if (options.baseUrl) return trimSlash(options.baseUrl) + GRAPHQL_PATH;\n  const env = readEnv(ENDPOINT_ENV_VAR);\n  // UNFZ_API_URL is documented as the full /query URL and is used verbatim.\n  // Tolerate a bare origin anyway, since that is the obvious mistake and\n  // guessing right costs nothing.\n  if (env) {\n    const trimmed = trimSlash(env);\n    return /\\/query$|\\/graphql$/.test(trimmed) ? trimmed : trimmed + GRAPHQL_PATH;\n  }\n  return DEFAULT_ENDPOINT;\n}\n\nfunction readEnv(name: string): string | undefined {\n  // Guarded: the SDK must also work in a browser or worker, where there is no\n  // `process` at all.\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process\n    ?.env;\n  return env?.[name] || undefined;\n}\n\nfunction trimSlash(u: string): string {\n  return u.replace(/\\/+$/, \"\");\n}\n\nfunction isAbort(e: unknown): boolean {\n  return typeof e === \"object\" && e !== null && (e as { name?: string }).name === \"AbortError\";\n}\n\nfunction abortError(): Error {\n  const e = new Error(\"The operation was aborted.\");\n  e.name = \"AbortError\";\n  return e;\n}\n\n/**\n * Settles with `promise`, or rejects the moment `signal` aborts.\n *\n * A global `fetch` honours the signal for headers and body alike, but an\n * injected {@link FetchLike} — a proxy, an instrumented transport, a test\n * double — need not. Racing the signal makes the timeout an upper bound on the\n * whole request regardless of what the transport does with it. The loser's\n * rejection is swallowed by the already-settled promise rather than surfacing\n * as an unhandled rejection.\n */\nfunction untilAborted<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {\n  if (!signal) return promise;\n  if (signal.aborted) return Promise.reject(abortError());\n  return new Promise<T>((resolve, reject) => {\n    const onAbort = () => reject(abortError());\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n    const done = () => signal.removeEventListener(\"abort\", onAbort);\n    promise.then(\n      (value) => {\n        done();\n        resolve(value);\n      },\n      (error: unknown) => {\n        done();\n        reject(error as Error);\n      },\n    );\n  });\n}\n\n/**\n * Combines the request timeout with any caller-supplied signal.\n *\n * `didTimeout` is tracked separately from the abort so a caller's own\n * cancellation is not mislabelled as a timeout in the thrown message.\n */\nfunction makeSignal(\n  timeoutMs: number,\n  external?: AbortSignal,\n): { signal?: AbortSignal; cleanup: () => void; didTimeout: () => boolean } {\n  if (!timeoutMs && !external) return { cleanup: () => {}, didTimeout: () => false };\n  if (typeof AbortController !== \"function\") {\n    return {\n      ...(external ? { signal: external } : {}),\n      cleanup: () => {},\n      didTimeout: () => false,\n    };\n  }\n\n  const controller = new AbortController();\n  let timedOut = false;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  if (timeoutMs > 0) {\n    timer = setTimeout(() => {\n      timedOut = true;\n      controller.abort();\n    }, timeoutMs);\n  }\n\n  const onExternalAbort = () => controller.abort();\n  if (external) {\n    if (external.aborted) controller.abort();\n    else external.addEventListener(\"abort\", onExternalAbort, { once: true });\n  }\n\n  return {\n    signal: controller.signal,\n    cleanup: () => {\n      if (timer !== undefined) clearTimeout(timer);\n      external?.removeEventListener(\"abort\", onExternalAbort);\n    },\n    didTimeout: () => timedOut,\n  };\n}\n"]}

package/dist/errors.d.ts

@@ -97,6 +97,31 @@ export declare class UnfazedConflictError extends UnfazedError {
 /** The requested alias, deployment or release does not exist (or was pruned). */
 export declare class UnfazedNotFoundError extends UnfazedError {
 }
+/**
+ * What the `unfazed` CLI backend's World (`createWorld()`) throws.
+ *
+ * Its `name` is the Workflow SDK error a World would throw in its place
+ * (`WorkflowWorldError`, `WorkflowRunNotFoundError`, `HookNotFoundError`),
+ * because Workflow SDK's CLI and web UI pick their message by `name`,
+ * `status` and `code`: a missing run reads as a 404 there, an argument the
+ * backend cannot serve (`code: "INVALID_ARGUMENT"`) prints as given.
+ * `instanceof UnfazedError` still holds.
+ */
+export declare class UnfazedInspectError extends UnfazedError {
+    /** HTTP-like status: 404 for a missing run, step, event, hook or app; 401/403 for a refused token. */
+    readonly status: number | undefined;
+    /** `INVALID_ARGUMENT`, `READ_ONLY`, or undefined. */
+    readonly code: string | undefined;
+    /** The run, for `WorkflowRunNotFoundError`. */
+    readonly runId: string | undefined;
+    constructor(message: string, options?: {
+        name?: "WorkflowWorldError" | "WorkflowRunNotFoundError" | "HookNotFoundError";
+        status?: number;
+        code?: string;
+        runId?: string;
+        cause?: unknown;
+    });
+}
 /**
  * The server's exact "no such workspace" sentinel.
  *

package/dist/errors.js

@@ -114,6 +114,31 @@ export class UnfazedConflictError extends UnfazedError {
 /** The requested alias, deployment or release does not exist (or was pruned). */
 export class UnfazedNotFoundError extends UnfazedError {
 }
+/**
+ * What the `unfazed` CLI backend's World (`createWorld()`) throws.
+ *
+ * Its `name` is the Workflow SDK error a World would throw in its place
+ * (`WorkflowWorldError`, `WorkflowRunNotFoundError`, `HookNotFoundError`),
+ * because Workflow SDK's CLI and web UI pick their message by `name`,
+ * `status` and `code`: a missing run reads as a 404 there, an argument the
+ * backend cannot serve (`code: "INVALID_ARGUMENT"`) prints as given.
+ * `instanceof UnfazedError` still holds.
+ */
+export class UnfazedInspectError extends UnfazedError {
+    /** HTTP-like status: 404 for a missing run, step, event, hook or app; 401/403 for a refused token. */
+    status;
+    /** `INVALID_ARGUMENT`, `READ_ONLY`, or undefined. */
+    code;
+    /** The run, for `WorkflowRunNotFoundError`. */
+    runId;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = options.name ?? "WorkflowWorldError";
+        this.status = options.status;
+        this.code = options.code;
+        this.runId = options.runId;
+    }
+}
 /**
  * The server's exact "no such workspace" sentinel.
  *

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Error taxonomy.\n *\n * Everything the SDK throws is an {@link UnfazedError}, so a code-mode script\n * can `catch (e) { if (e instanceof UnfazedError) ... }` and still\n * discriminate on the subclass to decide whether to retry.\n */\n\n/** A single entry from a GraphQL response's `errors` array. */\nexport interface GraphQLResponseError {\n  message: string;\n  path?: (string | number)[];\n  extensions?: Record<string, unknown>;\n}\n\n/** Base class for everything this SDK throws. */\nexport class UnfazedError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = new.target.name;\n  }\n}\n\n/** No token was passed and no token environment variable was set. */\nexport class UnfazedAuthError extends UnfazedError {}\n\n/** The runtime has no global `fetch` and none was injected. */\nexport class UnfazedConfigError extends UnfazedError {}\n\n/**\n * The endpoint answered with a non-2xx status. `status` is the HTTP status and\n * `body` the response text, which is where the platform reports non-GraphQL\n * failures such as an expired or wrong-scope bearer token.\n */\nexport class UnfazedHTTPError extends UnfazedError {\n  readonly status: number;\n  readonly body: string;\n\n  constructor(status: number, body: string, url: string) {\n    super(`unfazed: HTTP ${status} from ${url}${body ? `: ${truncate(body)}` : \"\"}`);\n    this.status = status;\n    this.body = body;\n  }\n}\n\n/**\n * The endpoint answered 200 with a GraphQL `errors` array.\n *\n * Partial `data` is preserved deliberately: the batched writeFiles document\n * resolves each aliased field independently, so one path can fail while the\n * others commit, and the caller needs to see which landed.\n */\nexport class UnfazedGraphQLError extends UnfazedError {\n  readonly errors: GraphQLResponseError[];\n  readonly data: unknown;\n\n  constructor(errors: GraphQLResponseError[], data: unknown) {\n    const summary = errors.map((e) => e.message).join(\"; \") || \"unknown GraphQL error\";\n    super(`unfazed: ${summary}`);\n    this.errors = errors;\n    this.data = data;\n  }\n}\n\n/** A request exceeded `timeoutMs`, or the caller's AbortSignal fired. */\nexport class UnfazedTimeoutError extends UnfazedError {}\n\n/**\n * Waiting on a deploy ended badly.\n *\n * `reason` separates the two outcomes because they need different handling:\n * FAILED means the build finished and is broken (read `deployment.error` and\n * fix the source — retrying will not help), TIMEOUT means it is still BUILDING\n * and polling longer may still succeed.\n */\nexport class UnfazedDeployError extends UnfazedError {\n  readonly reason: \"FAILED\" | \"TIMEOUT\";\n  readonly deploymentId: string;\n  /** Last deployment snapshot observed before giving up. */\n  readonly deployment: unknown;\n\n  constructor(\n    reason: \"FAILED\" | \"TIMEOUT\",\n    deploymentId: string,\n    deployment: unknown,\n    message: string,\n  ) {\n    super(message);\n    this.reason = reason;\n    this.deploymentId = deploymentId;\n    this.deployment = deployment;\n  }\n}\n\n/**\n * Waiting on a run timed out.\n *\n * Unlike {@link UnfazedDeployError}, a run's FAILED status is never thrown\n * here: {@link import(\"./unfazed.js\").Unfazed.waitForRun} resolves on\n * SUCCEEDED, FAILED and CANCELLED alike, because a run that executed and\n * exited non-zero is a completed answer — read `run.error`/`run.exitCode` —\n * not a broken build the way a FAILED deployment is. TIMEOUT is the only\n * outcome still worth an exception: the run is, as far as the last poll\n * showed, still QUEUED or RUNNING, and waiting longer may yet succeed.\n */\nexport class UnfazedRunError extends UnfazedError {\n  readonly reason: \"TIMEOUT\";\n  readonly runId: string;\n  /** Last run snapshot observed before giving up. */\n  readonly run: unknown;\n\n  constructor(reason: \"TIMEOUT\", runId: string, run: unknown, message: string) {\n    super(message);\n    this.reason = reason;\n    this.runId = runId;\n    this.run = run;\n  }\n}\n\n/**\n * A rollback's compare-and-swap guard was rejected: the alias moved between\n * reading the current release and swapping it.\n *\n * Recovery is always \"re-list releases and rebuild the guard\" — never \"reuse\n * the old tuple\", because the server checks the holder id, epoch AND opaque\n * revision to close same-id ABA. `Unfazed.rollback` does that re-list for you\n * once by default.\n */\nexport class UnfazedConflictError extends UnfazedError {\n  readonly errors: GraphQLResponseError[];\n\n  constructor(message: string, errors: GraphQLResponseError[]) {\n    super(message);\n    this.errors = errors;\n  }\n}\n\n/** The requested alias, deployment or release does not exist (or was pruned). */\nexport class UnfazedNotFoundError extends UnfazedError {}\n\n/**\n * The server's exact \"no such workspace\" sentinel.\n *\n * A missing workspace and a workspace belonging to another tenant return the\n * SAME message on purpose, so the API cannot be used to probe for someone\n * else's ids. Treat it as \"not yours to see\", not strictly as \"absent\".\n */\nexport const WORKSPACE_NOT_FOUND = \"workspace was not found\";\n\n/** The server's exact \"no such deployment\" sentinel. See {@link WORKSPACE_NOT_FOUND}. */\nexport const DEPLOYMENT_NOT_FOUND = \"deployment was not found\";\n\n/**\n * Does this error carry EXACTLY the given not-found sentinel?\n *\n * Exact equality, deliberately. The tempting version — \"does any message\n * contain 'not found'\" — also swallows `release not found in history`,\n * `integration not found` and every future message that happens to use the\n * phrase, turning real failures into a silent `false` from a delete. These two\n * strings are stable authz sentinels with test coverage on the server side;\n * anything else is a genuine error and must keep throwing.\n */\nexport function isNotFoundSentinel(error: unknown, sentinel: string): boolean {\n  return (\n    error instanceof UnfazedGraphQLError &&\n    error.errors.some((e) => e.message.trim() === sentinel)\n  );\n}\n\n/**\n * Message shape of the server's per-owner duplicate workspace name error:\n * `a workspace named \"x\" already exists; reuse it (id <uuid>) or pick a\n * different name`.\n *\n * Used only to turn a lost `ensureWorkspace` race into a re-read. Requiring\n * both \"workspace\" and \"already exists\" in one clause keeps it off unrelated\n * conflicts (a duplicate ALIAS, say), and a false negative is safe: the\n * caller just gets the server's error verbatim.\n */\nconst DUPLICATE_WORKSPACE_NAME = /\\bworkspace\\b[^.;]{0,80}\\balready exists\\b/i;\n\n/** Did `createWorkspace` fail because the name is already taken by this owner? */\nexport function isDuplicateWorkspaceName(error: unknown): boolean {\n  return (\n    error instanceof UnfazedGraphQLError &&\n    error.errors.some((e) => DUPLICATE_WORKSPACE_NAME.test(e.message))\n  );\n}\n\nfunction truncate(s: string, max = 500): string {\n  return s.length <= max ? s : `${s.slice(0, max)}…`;\n}\n\n/**\n * Message shapes that mean \"the alias moved under you\".\n *\n * The first two are the platform's ACTUAL strings. A rejected rollback guard\n * returns `store.ErrAliasMoved` verbatim — every guard point in the rollback\n * and adopt paths returns that one sentinel unwrapped — and the staged-service\n * rollback wraps the same guard with its own prefix. The rest are defensive:\n * the guard ARGUMENTS named back at you, or the alias-revision concept in any\n * spelling, or `alias` sitting in the same clause as a conflict verb, so a\n * rewording on the server side does not silently disable the retry.\n *\n * Deliberately NOT matched: a bare \"conflict\", \"changed\" or \"stale\" anywhere in\n * any message. Those fire on errors that have nothing to do with the alias\n * compare-and-swap, and a false positive is not free — it spends a pointless\n * re-list AND rewraps an unrelated failure as {@link UnfazedConflictError},\n * whose message would then blame concurrent deploys for, say, a permission\n * problem.\n */\nconst CAS_PATTERNS: RegExp[] = [\n  /alias was repointed by another change/i,\n  /became stale before alias change/i,\n  /expected[\\s_-]*current/i,\n  /alias[\\s_-]*revision/i,\n  /\\balias\\b[^.;]{0,80}\\b(?:moved|repointed|changed|conflicts?|stale|mismatch)\\b/i,\n  /\\b(?:moved|repointed|changed|conflicts?|stale|mismatch)\\b[^.;]{0,80}\\balias\\b/i,\n];\n\n/**\n * Heuristic: does this GraphQL error set look like a rejected compare-and-swap?\n *\n * The server carries no machine-readable code in `extensions` — its error\n * presenter returns gqlgen's default untouched — so this has to match message\n * text. It is used ONLY to decide whether to re-list and retry once: a false\n * negative costs a surfaced error the caller can retry by hand, a false\n * positive costs an extra read and a misleading error class. Neither can\n * promote the wrong release, because the retry rebuilds the guard from a fresh\n * read and the server re-validates it.\n */\nexport function looksLikeCASConflict(errors: GraphQLResponseError[]): boolean {\n  return errors.some((e) => CAS_PATTERNS.some((pattern) => pattern.test(e.message)));\n}\n"]}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Error taxonomy.\n *\n * Everything the SDK throws is an {@link UnfazedError}, so a code-mode script\n * can `catch (e) { if (e instanceof UnfazedError) ... }` and still\n * discriminate on the subclass to decide whether to retry.\n */\n\n/** A single entry from a GraphQL response's `errors` array. */\nexport interface GraphQLResponseError {\n  message: string;\n  path?: (string | number)[];\n  extensions?: Record<string, unknown>;\n}\n\n/** Base class for everything this SDK throws. */\nexport class UnfazedError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = new.target.name;\n  }\n}\n\n/** No token was passed and no token environment variable was set. */\nexport class UnfazedAuthError extends UnfazedError {}\n\n/** The runtime has no global `fetch` and none was injected. */\nexport class UnfazedConfigError extends UnfazedError {}\n\n/**\n * The endpoint answered with a non-2xx status. `status` is the HTTP status and\n * `body` the response text, which is where the platform reports non-GraphQL\n * failures such as an expired or wrong-scope bearer token.\n */\nexport class UnfazedHTTPError extends UnfazedError {\n  readonly status: number;\n  readonly body: string;\n\n  constructor(status: number, body: string, url: string) {\n    super(`unfazed: HTTP ${status} from ${url}${body ? `: ${truncate(body)}` : \"\"}`);\n    this.status = status;\n    this.body = body;\n  }\n}\n\n/**\n * The endpoint answered 200 with a GraphQL `errors` array.\n *\n * Partial `data` is preserved deliberately: the batched writeFiles document\n * resolves each aliased field independently, so one path can fail while the\n * others commit, and the caller needs to see which landed.\n */\nexport class UnfazedGraphQLError extends UnfazedError {\n  readonly errors: GraphQLResponseError[];\n  readonly data: unknown;\n\n  constructor(errors: GraphQLResponseError[], data: unknown) {\n    const summary = errors.map((e) => e.message).join(\"; \") || \"unknown GraphQL error\";\n    super(`unfazed: ${summary}`);\n    this.errors = errors;\n    this.data = data;\n  }\n}\n\n/** A request exceeded `timeoutMs`, or the caller's AbortSignal fired. */\nexport class UnfazedTimeoutError extends UnfazedError {}\n\n/**\n * Waiting on a deploy ended badly.\n *\n * `reason` separates the two outcomes because they need different handling:\n * FAILED means the build finished and is broken (read `deployment.error` and\n * fix the source — retrying will not help), TIMEOUT means it is still BUILDING\n * and polling longer may still succeed.\n */\nexport class UnfazedDeployError extends UnfazedError {\n  readonly reason: \"FAILED\" | \"TIMEOUT\";\n  readonly deploymentId: string;\n  /** Last deployment snapshot observed before giving up. */\n  readonly deployment: unknown;\n\n  constructor(\n    reason: \"FAILED\" | \"TIMEOUT\",\n    deploymentId: string,\n    deployment: unknown,\n    message: string,\n  ) {\n    super(message);\n    this.reason = reason;\n    this.deploymentId = deploymentId;\n    this.deployment = deployment;\n  }\n}\n\n/**\n * Waiting on a run timed out.\n *\n * Unlike {@link UnfazedDeployError}, a run's FAILED status is never thrown\n * here: {@link import(\"./unfazed.js\").Unfazed.waitForRun} resolves on\n * SUCCEEDED, FAILED and CANCELLED alike, because a run that executed and\n * exited non-zero is a completed answer — read `run.error`/`run.exitCode` —\n * not a broken build the way a FAILED deployment is. TIMEOUT is the only\n * outcome still worth an exception: the run is, as far as the last poll\n * showed, still QUEUED or RUNNING, and waiting longer may yet succeed.\n */\nexport class UnfazedRunError extends UnfazedError {\n  readonly reason: \"TIMEOUT\";\n  readonly runId: string;\n  /** Last run snapshot observed before giving up. */\n  readonly run: unknown;\n\n  constructor(reason: \"TIMEOUT\", runId: string, run: unknown, message: string) {\n    super(message);\n    this.reason = reason;\n    this.runId = runId;\n    this.run = run;\n  }\n}\n\n/**\n * A rollback's compare-and-swap guard was rejected: the alias moved between\n * reading the current release and swapping it.\n *\n * Recovery is always \"re-list releases and rebuild the guard\" — never \"reuse\n * the old tuple\", because the server checks the holder id, epoch AND opaque\n * revision to close same-id ABA. `Unfazed.rollback` does that re-list for you\n * once by default.\n */\nexport class UnfazedConflictError extends UnfazedError {\n  readonly errors: GraphQLResponseError[];\n\n  constructor(message: string, errors: GraphQLResponseError[]) {\n    super(message);\n    this.errors = errors;\n  }\n}\n\n/** The requested alias, deployment or release does not exist (or was pruned). */\nexport class UnfazedNotFoundError extends UnfazedError {}\n\n/**\n * What the `unfazed` CLI backend's World (`createWorld()`) throws.\n *\n * Its `name` is the Workflow SDK error a World would throw in its place\n * (`WorkflowWorldError`, `WorkflowRunNotFoundError`, `HookNotFoundError`),\n * because Workflow SDK's CLI and web UI pick their message by `name`,\n * `status` and `code`: a missing run reads as a 404 there, an argument the\n * backend cannot serve (`code: \"INVALID_ARGUMENT\"`) prints as given.\n * `instanceof UnfazedError` still holds.\n */\nexport class UnfazedInspectError extends UnfazedError {\n  /** HTTP-like status: 404 for a missing run, step, event, hook or app; 401/403 for a refused token. */\n  readonly status: number | undefined;\n  /** `INVALID_ARGUMENT`, `READ_ONLY`, or undefined. */\n  readonly code: string | undefined;\n  /** The run, for `WorkflowRunNotFoundError`. */\n  readonly runId: string | undefined;\n\n  constructor(\n    message: string,\n    options: {\n      name?: \"WorkflowWorldError\" | \"WorkflowRunNotFoundError\" | \"HookNotFoundError\";\n      status?: number;\n      code?: string;\n      runId?: string;\n      cause?: unknown;\n    } = {},\n  ) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = options.name ?? \"WorkflowWorldError\";\n    this.status = options.status;\n    this.code = options.code;\n    this.runId = options.runId;\n  }\n}\n\n/**\n * The server's exact \"no such workspace\" sentinel.\n *\n * A missing workspace and a workspace belonging to another tenant return the\n * SAME message on purpose, so the API cannot be used to probe for someone\n * else's ids. Treat it as \"not yours to see\", not strictly as \"absent\".\n */\nexport const WORKSPACE_NOT_FOUND = \"workspace was not found\";\n\n/** The server's exact \"no such deployment\" sentinel. See {@link WORKSPACE_NOT_FOUND}. */\nexport const DEPLOYMENT_NOT_FOUND = \"deployment was not found\";\n\n/**\n * Does this error carry EXACTLY the given not-found sentinel?\n *\n * Exact equality, deliberately. The tempting version — \"does any message\n * contain 'not found'\" — also swallows `release not found in history`,\n * `integration not found` and every future message that happens to use the\n * phrase, turning real failures into a silent `false` from a delete. These two\n * strings are stable authz sentinels with test coverage on the server side;\n * anything else is a genuine error and must keep throwing.\n */\nexport function isNotFoundSentinel(error: unknown, sentinel: string): boolean {\n  return (\n    error instanceof UnfazedGraphQLError &&\n    error.errors.some((e) => e.message.trim() === sentinel)\n  );\n}\n\n/**\n * Message shape of the server's per-owner duplicate workspace name error:\n * `a workspace named \"x\" already exists; reuse it (id <uuid>) or pick a\n * different name`.\n *\n * Used only to turn a lost `ensureWorkspace` race into a re-read. Requiring\n * both \"workspace\" and \"already exists\" in one clause keeps it off unrelated\n * conflicts (a duplicate ALIAS, say), and a false negative is safe: the\n * caller just gets the server's error verbatim.\n */\nconst DUPLICATE_WORKSPACE_NAME = /\\bworkspace\\b[^.;]{0,80}\\balready exists\\b/i;\n\n/** Did `createWorkspace` fail because the name is already taken by this owner? */\nexport function isDuplicateWorkspaceName(error: unknown): boolean {\n  return (\n    error instanceof UnfazedGraphQLError &&\n    error.errors.some((e) => DUPLICATE_WORKSPACE_NAME.test(e.message))\n  );\n}\n\nfunction truncate(s: string, max = 500): string {\n  return s.length <= max ? s : `${s.slice(0, max)}…`;\n}\n\n/**\n * Message shapes that mean \"the alias moved under you\".\n *\n * The first two are the platform's ACTUAL strings. A rejected rollback guard\n * returns `store.ErrAliasMoved` verbatim — every guard point in the rollback\n * and adopt paths returns that one sentinel unwrapped — and the staged-service\n * rollback wraps the same guard with its own prefix. The rest are defensive:\n * the guard ARGUMENTS named back at you, or the alias-revision concept in any\n * spelling, or `alias` sitting in the same clause as a conflict verb, so a\n * rewording on the server side does not silently disable the retry.\n *\n * Deliberately NOT matched: a bare \"conflict\", \"changed\" or \"stale\" anywhere in\n * any message. Those fire on errors that have nothing to do with the alias\n * compare-and-swap, and a false positive is not free — it spends a pointless\n * re-list AND rewraps an unrelated failure as {@link UnfazedConflictError},\n * whose message would then blame concurrent deploys for, say, a permission\n * problem.\n */\nconst CAS_PATTERNS: RegExp[] = [\n  /alias was repointed by another change/i,\n  /became stale before alias change/i,\n  /expected[\\s_-]*current/i,\n  /alias[\\s_-]*revision/i,\n  /\\balias\\b[^.;]{0,80}\\b(?:moved|repointed|changed|conflicts?|stale|mismatch)\\b/i,\n  /\\b(?:moved|repointed|changed|conflicts?|stale|mismatch)\\b[^.;]{0,80}\\balias\\b/i,\n];\n\n/**\n * Heuristic: does this GraphQL error set look like a rejected compare-and-swap?\n *\n * The server carries no machine-readable code in `extensions` — its error\n * presenter returns gqlgen's default untouched — so this has to match message\n * text. It is used ONLY to decide whether to re-list and retry once: a false\n * negative costs a surfaced error the caller can retry by hand, a false\n * positive costs an extra read and a misleading error class. Neither can\n * promote the wrong release, because the retry rebuilds the guard from a fresh\n * read and the server re-validates it.\n */\nexport function looksLikeCASConflict(errors: GraphQLResponseError[]): boolean {\n  return errors.some((e) => CAS_PATTERNS.some((pattern) => pattern.test(e.message)));\n}\n"]}

package/dist/index.d.ts

@@ -21,6 +21,7 @@
  *  - {@link Unfazed} — the workflow layer (deploy + wait, batch writes, one-call rollback).
  *  - {@link UnfazedClient} — the typed GraphQL transport, for anything not wrapped.
  */
+import type { RemoteWorld, RemoteWorldOptions } from "./remote/world.js";
 export { Unfazed } from "./unfazed.js";
 export type { CreateRunOptions, FollowUpRunOptions, DeleteDeploymentOptions, DeleteWorkspaceOptions, Deployment, DeployBoxOptions, DeployOptions, DeployServiceOptions, DeployStaticOptions, EnvVar, FileContent, FilesMap, ListRunsFilter, RollbackOptions, Run, UnfazedOptions, Workspace, WorkspaceFile, WriteFilesOptions, } from "./unfazed.js";
 export { UnfazedClient, DEFAULT_BASE_URL, DEFAULT_ENDPOINT, ENDPOINT_ENV_VAR, GRAPHQL_PATH, TOKEN_ENV_VAR, VERSION, } from "./client.js";
@@ -28,6 +29,26 @@ export type { ClientOptions, FetchLike, GraphQLDocument, RequestOptions, ResultO
 export { DEPLOYMENT_NOT_FOUND, UnfazedAuthError, UnfazedConfigError, UnfazedConflictError, UnfazedDeployError, UnfazedError, UnfazedGraphQLError, UnfazedHTTPError, UnfazedNotFoundError, UnfazedRunError, UnfazedTimeoutError, WORKSPACE_NOT_FOUND, isDuplicateWorkspaceName, isNotFoundSentinel, } from "./errors.js";
 export type { GraphQLResponseError } from "./errors.js";
 export type { WaitOptions } from "./wait.js";
+export { UnfazedInspectError } from "./errors.js";
+export { APP_ENV_VAR } from "./remote/app.js";
+export type { RemoteWorld, RemoteWorldOptions } from "./remote/world.js";
+/**
+ * The `unfazed` backend of Workflow SDK's CLI: a read-mostly World over the
+ * platform's workflow inspection API, for one app.
+ *
+ * ```sh
+ * export UNFZ_API_TOKEN=...                                   # https://unfazed.dev/auth.md
+ * UNFZ_APP=birthday-card npx workflow inspect runs --backend unfazed
+ * ```
+ *
+ * The CLI (and its `--web` UI) resolve `unfazed` from the project and call
+ * this with no arguments. The app is `UNFZ_APP`, else the `alias` (or the
+ * single `apps[]` entry) of `unfazed.json` in the current directory. Reads
+ * and `workflow cancel` work; every other write throws, since an app's own
+ * World is `unfazed/workflow`. The module behind it loads on first call, so
+ * `import "unfazed"` stays as light as before.
+ */
+export declare function createWorld(options?: RemoteWorldOptions): Promise<RemoteWorld>;
 /**
  * Every operation document the workflow layer uses, for callers that want the
  * typed documents but not the wrapper methods.