@zocomputer/cli 0.1.1 → 0.2.0

package/README.md

@@ -6,25 +6,26 @@ see [runtime requirements](../README.md#set-up).
 
 ## Install or upgrade
 
-After publication, install the versioned package:
+Install the latest published version from npm:
 
 ```sh
-npm install --global @zocomputer/cli@0.1.1
+npm install --global @zocomputer/cli@latest
 zo --version
 zo login
 ```
 
-Use the same install command with the desired version to upgrade. The CLI
+Run the same install command again to upgrade. The CLI
 installs its matching public SDK dependency. It performs no update check when
 you run a command.
 
-To test unpublished artifacts, install both tarballs together:
+To try the CLI without installing it globally:
 
 ```sh
-npm install --global ./zocomputer-system-api-0.1.1.tgz ./zocomputer-cli-0.1.1.tgz
-zo --version
+npx -y @zocomputer/cli@latest --help
 ```
 
+Replace `--help` with a command such as `login` or `--version`.
+
 ## Develop locally
 
 Install the independent client workspace, then build the CLI:
@@ -50,8 +51,10 @@ node dist/main.js auth status
 ```
 
 Use `node dist/main.js` while working in this repository. The repository's
-internal operator CLI is `./zocli/zo` from the repository root. Run `type -a zo`
-to diagnose a PATH collision; the two clients store separate sign-ins.
+internal operator CLI is `zd` (`./zocli/zd` from the repository root).
+If an old internal `zo` symlink is still on PATH, run `./zocli/zd setup` from
+your main checkout and refresh your shell's command cache. Run `type -a zd zo`
+to check both commands; the two clients store separate sign-ins.
 
 ## Accounts and workspaces
 
@@ -78,13 +81,26 @@ workspaces, a terminal prompts for a selection; scripts must supply
 person separately from the effective subject in the selected workspace.
 `context list`, `context use` and status refresh that view from the server.
 
-`login` prints the authorization URL on its own line on stderr, opens your
-browser, and waits for sign-in to finish. You can copy the URL into another
-browser window. The message is dim on interactive terminals and plain when
-redirected, with `--json`, or when `NO_COLOR` is set.
+`login` uses the OAuth device authorization grant (RFC 8628). It prints a
+sign-in URL and a code on stderr, opens your browser, and polls the token
+endpoint until you approve or deny. Approve only if the page shows the same
+code. Nothing connects back to the CLI's machine, so the URL works from any
+browser or device. The request expires after 10 minutes; Ctrl-C cancels it
+(exit 130). Denial exits 4 with `access_denied`; expiry exits 3 with
+`login_timeout`.
+
+Over SSH (`SSH_CONNECTION` or `SSH_TTY` set), or with no `DISPLAY` or
+`WAYLAND_DISPLAY` outside macOS, login doesn't open a browser and asks you to
+visit the URL on any device. `login --no-browser` does the same anywhere.
+
+After approval, login lists every approved workspace with the identity the CLI
+acts as there (`as you` or `as service account <id>`), even when there is only
+one. A workspace you don't recognize means someone else approved your sign-in
+link; run `logout` to revoke it.
 
-`login --no-browser` prints the same URL and waits without opening a browser.
-It is not a device-code login. The browser must reach the CLI's localhost callback.
+Each poll waits up to 20 seconds. After a timeout or network error the CLI
+retries once at once, inside the issuer's 30-second redemption window, then
+resumes polling every `interval` seconds; `slow_down` and a 429 add 5 seconds.
 
 ## Tokens and logout
 
@@ -131,7 +147,9 @@ Before sending, the CLI durably marks the outcome uncertain. If syncing that
 marker fails after replacement, it attempts to restore the original ready
 credential and reports the storage error; no exchange was sent. A lost response
 may be retried once under the lock within the server's 30-second recovery
-window. Saving the received successor clears the marker. A crash, failure to
+window. A 429 comes only from the rate limiter, before any exchange, so the
+CLI restores the ready state, does not retry, and asks you to try again
+shortly; a 429 on that retry leaves the marker in place. Saving the received successor clears the marker. A crash, failure to
 replace the credential file, or unresolved second request leaves the marker
 in place and requires login;
 later processes cannot unknowingly replay that refresh token.

package/dist/auth.d.ts

@@ -12,6 +12,7 @@ export interface AuthOptions {
     environment?: Binding;
     env?: NodeJS.ProcessEnv;
     now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     signal?: AbortSignal;
 }
 export declare class AuthClient {
@@ -22,6 +23,7 @@ export declare class AuthClient {
     private readonly fetcher;
     private readonly env;
     private readonly now;
+    private readonly sleep;
     private readonly signal?;
     constructor(profile: Profile, directory: string, options?: AuthOptions);
     private locked;
@@ -31,6 +33,8 @@ export declare class AuthClient {
     session(): Promise<Session>;
     private revoke;
     private cleanup;
+    /** RFC 8628 section 3.4 polling until approval, denial or expiry. */
+    private poll;
     login(options?: LoginOptions): Promise<{
         cleanupPending: boolean;
     }>;

package/dist/auth.js

@@ -1,10 +1,13 @@
 import { join } from "node:path";
 import { CliError, record, throwIfInterrupted } from "./errors.js";
 import { requestJson, RequestFailure } from "./http.js";
-import { loginCode } from "./login.js";
+import { browserAvailable, DEVICE_CODE_GRANT, deviceAuthorization, openBrowser, pause, } from "./login.js";
 import { environments, profileName } from "./profiles.js";
 import { parseSession } from "./session.js";
 import { privateDirectory, PrivateWriteDurabilityError, readPrivate, removePrivate, withLock, writePrivate, } from "./storage.js";
+// Longer than requestJson's 8-second default, and short enough that a retry
+// after a lost approval lands inside the issuer's 30-second redemption window.
+const DEVICE_POLL_TIMEOUT_MS = 20_000;
 function tokens(raw, now) {
     if (!record(raw) ||
         raw.error !== undefined ||
@@ -36,6 +39,7 @@ export class AuthClient {
     fetcher;
     env;
     now;
+    sleep;
     signal;
     constructor(profile, directory, options = {}) {
         this.profile = profile;
@@ -45,6 +49,7 @@ export class AuthClient {
         this.fetcher = options.fetch ?? fetch;
         this.env = options.env ?? process.env;
         this.now = options.now ?? Date.now;
+        this.sleep = options.sleep ?? pause;
         this.signal = options.signal;
     }
     async locked(work, signal = this.signal) {
@@ -97,7 +102,7 @@ export class AuthClient {
             refreshState: raw.refreshState,
         };
     }
-    async tokenRequest(form, signal = this.signal) {
+    async tokenRequest(form, signal = this.signal, timeoutMs) {
         const issuedAt = this.now();
         return tokens(await requestJson(`${this.binding.issuer}/zo-system-api/oauth/token`, {
             method: "POST",
@@ -107,7 +112,7 @@ export class AuthClient {
                 client_id: this.binding.clientId,
                 resource: this.binding.audience,
             }),
-        }, this.fetcher), issuedAt);
+        }, this.fetcher, timeoutMs === undefined ? {} : { timeoutMs }), issuedAt);
     }
     async accessToken() {
         throwIfInterrupted(this.signal);
@@ -150,6 +155,13 @@ export class AuthClient {
             }
             catch (error) {
                 throwIfInterrupted(this.signal);
+                if (error instanceof RequestFailure && error.status === 429) {
+                    // Only the rate limiter answers 429, before any exchange, so the
+                    // refresh token is unused. Retrying now would hit the same limit.
+                    credential.refreshState = "ready";
+                    await writePrivate(this.path, credential);
+                    throw new CliError("Too many sign-in requests right now. Try again shortly.", 5, "rate_limited");
+                }
                 // Two eight-second requests fit the issuer's thirty-second recovery
                 // window. Wall time also catches suspension of the monotonic clock.
                 const elapsed = this.now() - startedAt;
@@ -208,6 +220,61 @@ export class AuthClient {
             throwIfInterrupted(signal);
         }
     }
+    /** RFC 8628 section 3.4 polling until approval, denial or expiry. */
+    async poll(device, signal) {
+        const deadline = this.now() + device.expiresInMs;
+        const form = {
+            grant_type: DEVICE_CODE_GRANT,
+            device_code: device.deviceCode,
+        };
+        const expired = () => new CliError("Login timed out. Run zo login to try again.", 3, "login_timeout");
+        let interval = device.intervalMs;
+        let retryNow = false;
+        for (;;) {
+            if (!retryNow)
+                await this.sleep(interval, signal);
+            throwIfInterrupted(signal);
+            if (this.now() >= deadline)
+                throw expired();
+            const retry = retryNow;
+            retryNow = false;
+            try {
+                return await this.tokenRequest(form, signal, DEVICE_POLL_TIMEOUT_MS);
+            }
+            catch (error) {
+                throwIfInterrupted(signal);
+                if (!(error instanceof RequestFailure))
+                    throw error;
+                if (error.status === 400) {
+                    if (error.code === "authorization_pending")
+                        continue;
+                    if (error.code === "slow_down") {
+                        interval += 5_000;
+                        continue;
+                    }
+                    if (error.code === "access_denied")
+                        throw new CliError("Authorization was denied. Run zo login to try again.", 4, "access_denied");
+                    if (error.code === "expired_token")
+                        throw expired();
+                    if (error.code === "invalid_grant")
+                        throw new CliError("This sign-in request can no longer be completed. Run zo login again.", 3, "invalid_grant");
+                    throw error;
+                }
+                // The rate limiter answered before the issuer saw the poll.
+                if (error.status === 429) {
+                    interval += 5_000;
+                    continue;
+                }
+                // A timeout, network error or 5xx may have lost an approval the issuer
+                // already redeemed. One immediate retry gets the same refresh token.
+                if (error.ambiguous) {
+                    retryNow = !retry;
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
     async login(options = {}) {
         const signal = this.signal && options.signal
             ? AbortSignal.any([this.signal, options.signal])
@@ -218,13 +285,18 @@ export class AuthClient {
         return this.locked(async () => {
             const previous = await this.read();
             throwIfInterrupted(signal);
-            const code = await loginCode(this.binding.issuer, this.binding.audience, this.binding.clientId, { ...options, signal });
-            const active = await this.tokenRequest({
-                grant_type: "authorization_code",
-                code: code.code,
-                code_verifier: code.verifier,
-                redirect_uri: code.redirectUri,
-            }, signal);
+            const device = await deviceAuthorization(this.binding.issuer, this.binding.audience, this.binding.clientId, this.fetcher, signal);
+            const browser = !options.noBrowser &&
+                browserAvailable(this.env, options.platform ?? process.platform);
+            options.announce?.({
+                url: device.url,
+                userCode: device.userCode,
+                browser,
+            });
+            // The printed URL is the fallback when the opener fails.
+            if (browser)
+                void (options.openBrowser ?? openBrowser)(device.url).catch(() => { });
+            const active = await this.poll(device, signal);
             const credential = {
                 version: 1,
                 binding: this.binding,

package/dist/generated/commands.js

@@ -1,6 +1,6 @@
 // Generated by scripts/generate-commands.mjs. Do not edit.
 export const commandManifest = {
-    schemaDigest: "sha256:eaaf7ee560e0c39788aab1da5335e7717fc7244b9868589282dadfb6a9ea205d",
+    schemaDigest: "sha256:8f3267de41a6d06b71c959bca7eae3d05a1bda6e63304a51a9bbfa315ef0af31",
     commands: [
         {
             action: "zo.activity.list",
@@ -33,8 +33,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Create an Agent in a workspace. A zo.native Agent requires the workspace to be on Metronome billing.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"},"implementation":{"const":"zo.native","title":"Implementation","type":"string"},"configuration":{"$ref":"#/$defs/NativeConfiguration"}},"required":["workspace_id","display_name","implementation","configuration"],"title":"AgentCreateInput","type":"object","$defs":{"NativeConfiguration":{"additionalProperties":false,"description":"The ``zo.native`` configuration. Unknown fields are rejected.","properties":{"model":{"description":"Model identifier the runner calls.","maxLength":200,"minLength":1,"title":"Model","type":"string"},"system_prompt":{"anyOf":[{"maxLength":50000,"type":"string"},{"type":"null"}],"default":null,"description":"The Agent\'s instructions.","title":"System Prompt"},"instructions_file":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Knowledge file ID, such as an AGENTS.md, appended to the instructions each turn.","title":"Instructions File"},"skill_files":{"default":[],"description":"Knowledge file IDs of skills, each a Markdown file with Agent Skills frontmatter, indexed in the instructions.","items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":32,"title":"Skill Files","type":"array"}},"required":["model"],"title":"NativeConfiguration","type":"object"}}}',
+                    description: "Create an Agent in a workspace. A zo.native Agent requires the workspace to be on Metronome billing. Describe what this Agent is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this Agent is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"},"implementation":{"const":"zo.native","title":"Implementation","type":"string"},"configuration":{"$ref":"#/$defs/NativeConfiguration"}},"required":["workspace_id","display_name","implementation","configuration"],"title":"AgentCreateInput","type":"object","$defs":{"NativeConfiguration":{"additionalProperties":false,"description":"The ``zo.native`` configuration. Unknown fields are rejected.","properties":{"model":{"description":"Model identifier the runner calls.","maxLength":200,"minLength":1,"title":"Model","type":"string"},"system_prompt":{"anyOf":[{"maxLength":50000,"type":"string"},{"type":"null"}],"default":null,"description":"The Agent\'s instructions.","title":"System Prompt"},"instructions_file":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Knowledge file ID, such as an AGENTS.md, appended to the instructions each turn.","title":"Instructions File"},"skill_files":{"default":[],"description":"Knowledge file IDs of skills, each a Markdown file with Agent Skills frontmatter, indexed in the instructions.","items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":32,"title":"Skill Files","type":"array"}},"required":["model"],"title":"NativeConfiguration","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -108,7 +108,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Rename an Agent or replace its configuration. Changes apply from each session's next turn.",
-                    inputJson: '{"additionalProperties":false,"description":"Omitted fields keep their value; ``configuration`` replaces the whole configuration.","properties":{"agent_id":{"maxLength":200,"minLength":1,"title":"Agent Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":120,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"configuration":{"anyOf":[{"$ref":"#/$defs/NativeConfiguration"},{"type":"null"}],"default":null}},"required":["agent_id","expected_revision"],"title":"AgentUpdateInput","type":"object","$defs":{"NativeConfiguration":{"additionalProperties":false,"description":"The ``zo.native`` configuration. Unknown fields are rejected.","properties":{"model":{"description":"Model identifier the runner calls.","maxLength":200,"minLength":1,"title":"Model","type":"string"},"system_prompt":{"anyOf":[{"maxLength":50000,"type":"string"},{"type":"null"}],"default":null,"description":"The Agent\'s instructions.","title":"System Prompt"},"instructions_file":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Knowledge file ID, such as an AGENTS.md, appended to the instructions each turn.","title":"Instructions File"},"skill_files":{"default":[],"description":"Knowledge file IDs of skills, each a Markdown file with Agent Skills frontmatter, indexed in the instructions.","items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":32,"title":"Skill Files","type":"array"}},"required":["model"],"title":"NativeConfiguration","type":"object"}}}',
+                    inputJson: '{"additionalProperties":false,"description":"Omitted fields keep their value; ``configuration`` replaces the whole configuration.","properties":{"agent_id":{"maxLength":200,"minLength":1,"title":"Agent Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":120,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Describe what this Agent is for in the user\'s terms.","title":"Description"},"configuration":{"anyOf":[{"$ref":"#/$defs/NativeConfiguration"},{"type":"null"}],"default":null}},"required":["agent_id","expected_revision"],"title":"AgentUpdateInput","type":"object","$defs":{"NativeConfiguration":{"additionalProperties":false,"description":"The ``zo.native`` configuration. Unknown fields are rejected.","properties":{"model":{"description":"Model identifier the runner calls.","maxLength":200,"minLength":1,"title":"Model","type":"string"},"system_prompt":{"anyOf":[{"maxLength":50000,"type":"string"},{"type":"null"}],"default":null,"description":"The Agent\'s instructions.","title":"System Prompt"},"instructions_file":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Knowledge file ID, such as an AGENTS.md, appended to the instructions each turn.","title":"Instructions File"},"skill_files":{"default":[],"description":"Knowledge file IDs of skills, each a Markdown file with Agent Skills frontmatter, indexed in the instructions.","items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":32,"title":"Skill Files","type":"array"}},"required":["model"],"title":"NativeConfiguration","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -182,8 +182,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Create a connection from a published definition. A protected connection is reachable only by its owner and the principals they grant.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"definition_id":{"maxLength":200,"minLength":1,"title":"Definition Id","type":"string"},"definition_version":{"exclusiveMinimum":0,"maximum":2147483647,"title":"Definition Version","type":"integer"},"display_name":{"maxLength":256,"minLength":1,"title":"Display Name","type":"string"},"configuration":{"additionalProperties":{"x-zo-json-value":true},"title":"Configuration","type":"object"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","definition_id","definition_version","display_name","configuration"],"title":"ConnectionCreateInput","type":"object"}',
+                    description: "Create a connection from a published definition, or from named values on a private definition Zo publishes for it. A protected connection is reachable only by its owner and the principals they grant. Describe what this connection is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"definition_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"The published definition to connect to. Give it, or `values`, not both.","title":"Definition Id"},"definition_version":{"anyOf":[{"exclusiveMinimum":0,"maximum":2147483647,"type":"integer"},{"type":"null"}],"default":null,"description":"The version of `definition_id` to connect to; required with it.","title":"Definition Version"},"display_name":{"maxLength":256,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this connection is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"configuration":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"The connection\'s configuration; required with `definition_id`.","title":"Configuration"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"},"values":{"anyOf":[{"additionalProperties":{"description":"Secret: the value. Stored sealed and never returned.","maxLength":16384,"minLength":1,"type":"string"},"maxProperties":100,"minProperties":1,"type":"object"},{"type":"null"}],"default":null,"description":"Named values to store, in place of a definition: Zo publishes a private definition named after `display_name`, with one required key credential per name delivered as the environment variable of that name, creates the connection and stores every value. A definition name already taken in the workspace returns `conflict`. A name Zo refuses as an environment variable returns `invalid_input` with the `invalid_environment` violation.","title":"Values"},"environment":{"additionalProperties":{"maxLength":4096,"type":"string"},"default":{},"description":"Environment variables delivered, exactly as written, to machines that list this connection, beside its credential and the variables its definition sets. Plain strings, not secrets: put a secret in the vault. Names are upper-case letters, digits and underscores; at most 64 variables of at most 4096 characters each.","maxProperties":64,"title":"Environment","type":"object"}},"required":["workspace_id","display_name"],"title":"ConnectionCreateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -279,8 +279,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Replace a connection's configuration, rename it, or both; a field left out keeps its current value.",
-                    inputJson: '{"additionalProperties":false,"properties":{"connection_id":{"maxLength":200,"minLength":1,"title":"Connection Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"configuration":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"The configuration that replaces the stored one; omit it to keep the stored configuration, which reads never return.","title":"Configuration"},"display_name":{"anyOf":[{"maxLength":256,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"A new name for the connection; omit it to keep the current name.","title":"Display Name"}},"required":["connection_id","expected_revision"],"title":"ConnectionUpdateInput","type":"object"}',
+                    description: "Replace a connection's configuration or environment, rename it, move it to another version of its definition, or set and remove its named values; a field left out keeps its current value.",
+                    inputJson: '{"additionalProperties":false,"properties":{"connection_id":{"maxLength":200,"minLength":1,"title":"Connection Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"configuration":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"The configuration that replaces the stored one; omit it to keep the stored configuration, which reads never return.","title":"Configuration"},"display_name":{"anyOf":[{"maxLength":256,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"A new name for the connection; omit it to keep the current name.","title":"Display Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Describe what this connection is for in the user\'s terms.","title":"Description"},"definition_version":{"anyOf":[{"exclusiveMinimum":0,"maximum":2147483647,"type":"integer"},{"type":"null"}],"default":null,"description":"Move the connection to this version of its definition, keeping its id and grants. Credentials in both versions keep their values, credentials only the current version has are erased, and credentials only the new version has start empty. Omit it to stay on the current version.","title":"Definition Version"},"values":{"anyOf":[{"additionalProperties":{"anyOf":[{"description":"Secret: the value. Stored sealed and never returned.","maxLength":16384,"minLength":1,"type":"string"},{"type":"null"}]},"maxProperties":100,"minProperties":1,"type":"object"},{"type":"null"}],"default":null,"description":"Named values to set, or `null` to remove a name, on a connection whose definition is private to its workspace and holds only single-value key credentials, as one created from `values` does. Changing a value replaces that credential. Adding or removing a name publishes the definition\'s next version from the connection\'s own version and moves the connection to it, keeping its id and grants; other connections to the definition stay on their versions. A connection keeps at least one name. Any other connection returns `invalid_input`.","title":"Values"},"environment":{"anyOf":[{"additionalProperties":{"maxLength":4096,"type":"string"},"maxProperties":64,"type":"object"},{"type":"null"}],"default":null,"description":"The environment that replaces the stored one; omit it to keep the stored environment. Environment variables delivered, exactly as written, to machines that list this connection, beside its credential and the variables its definition sets. Plain strings, not secrets: put a secret in the vault. Names are upper-case letters, digits and underscores; at most 64 variables of at most 4096 characters each.","title":"Environment"}},"required":["connection_id","expected_revision"],"title":"ConnectionUpdateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -558,8 +558,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Create a workspace-owned function.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name"],"title":"FunctionCreateInput","type":"object"}',
+                    description: "Create a workspace-owned function. Describe what this function is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this function is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name"],"title":"FunctionCreateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -680,8 +680,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Create a managed machine from a machine image and return its current view.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"source":{"$ref":"#/$defs/MachineSourceInput"},"resources":{"$ref":"#/$defs/MachineResourcesInput"},"lifecycle":{"$ref":"#/$defs/MachineLifecycleInput"},"region":{"default":"us","pattern":"^[a-z0-9][a-z0-9-]{0,31}$","title":"Region","type":"string"},"init":{"default":"none","description":"Which process runs first at boot. `none` (default): nothing; the machine waits for exec. `image`: the init system inside the machine\'s image (systemd, OpenRC) becomes PID 1 and starts the services enabled on its disk. This does not choose the image; `source.machine_image_id` does. Debian and Ubuntu images need `systemd systemd-sysv` installed first. A unit restarts after a crash only when it sets `Restart=`.","enum":["none","image"],"title":"Init","type":"string"},"command":{"anyOf":[{"items":{"minLength":1,"type":"string"},"maxItems":64,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Run these arguments as the main process on every boot, without a shell. Use [\\"sh\\", \\"-c\\", ...] for shell syntax. Find ENTRYPOINT and CMD on the image\'s registry page; Zo does not return them. Pass ENTRYPOINT then CMD. With `init: image`, the command must wait for services it needs. The machine stops when it exits; resume runs it again. It may run more than once after a lost create or resume response, so make it safe to rerun. Each argument is at most 4,096 UTF-8 bytes and all arguments total at most 65,536 bytes. A running command is not activity: set `idle_timeout_seconds` at least as long as the job. The maximum is published by `zo.machine.list_configurations` (3,600 s today); a longer job needs Zo exec or file calls, or HTTP through a tunnel or connect token. After exit, `get` may show `running` for a few minutes until the stop is recorded. Zo reports no exit reason or code. Write a job\'s result to disk. A resume runs the command again, so to read it, clear the command, resume, then use `zo.machine.read_bytes`. With `init: image` and a command, a missing `/sbin/init` ends the generation as an exit stop, without `incompatible_image`.","title":"Command"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see and use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","idempotency_key","display_name","source","resources","lifecycle"],"title":"MachineCreateInput","type":"object","$defs":{"MachineLifecycleInput":{"additionalProperties":false,"properties":{"idle_timeout_seconds":{"default":900,"maximum":86400,"minimum":1,"title":"Idle Timeout Seconds","type":"integer"},"max_run_seconds":{"maximum":86400,"minimum":1,"title":"Max Run Seconds","type":"integer"}},"required":["max_run_seconds"],"title":"MachineLifecycleInput","type":"object"},"MachineResourcesInput":{"additionalProperties":false,"properties":{"vcpus":{"description":"Whole vCPUs of CPU capacity; each is half a Modal physical core. A quarter is reserved; the full allocation can burst when capacity allows. Guest logical CPU count is separate.","maximum":2147483647,"minimum":1,"title":"Vcpus","type":"integer"},"memory_mib":{"maximum":2147483647,"minimum":1,"title":"Memory Mib","type":"integer"}},"required":["vcpus","memory_mib"],"title":"MachineResourcesInput","type":"object"},"MachineSourceInput":{"additionalProperties":false,"properties":{"machine_image_id":{"description":"The machine image to boot (from `zo.machine_image.import`). Separate from `init`, which only chooses what runs first at boot.","minLength":1,"title":"Machine Image Id","type":"string"}},"required":["machine_image_id"],"title":"MachineSourceInput","type":"object"}}}',
+                    description: "Create a managed machine from a machine image and return its current view. Describe what this machine is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this machine is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"source":{"$ref":"#/$defs/MachineSourceInput"},"resources":{"$ref":"#/$defs/MachineResourcesInput"},"lifecycle":{"$ref":"#/$defs/MachineLifecycleInput"},"region":{"default":"us","pattern":"^[a-z0-9][a-z0-9-]{0,31}$","title":"Region","type":"string"},"init":{"default":"none","description":"Which process runs first at boot. `none` (default): nothing; the machine waits for exec. `image`: the init system inside the machine\'s image (systemd, OpenRC) becomes PID 1 and starts the services enabled on its disk. This does not choose the image; `source.machine_image_id` does. Debian and Ubuntu images need `systemd systemd-sysv` installed first. A unit restarts after a crash only when it sets `Restart=`. GPU machines require `none`.","enum":["none","image"],"title":"Init","type":"string"},"command":{"anyOf":[{"items":{"minLength":1,"type":"string"},"maxItems":64,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Run these arguments as the main process on every boot, without a shell. Use [\\"sh\\", \\"-c\\", ...] for shell syntax. Find ENTRYPOINT and CMD on the image\'s registry page; Zo does not return them. Pass ENTRYPOINT then CMD. With `init: image`, the command must wait for services it needs. The machine stops when it exits; resume runs it again. It may run more than once after a lost create or resume response, so make it safe to rerun. Each argument is at most 4,096 UTF-8 bytes and all arguments total at most 65,536 bytes. A running command is not activity: set `idle_timeout_seconds` at least as long as the job. The maximum is published by `zo.machine.list_configurations`: 3,600 s for CPU machines and 86,400 s for GPU machines. Longer CPU jobs need Zo exec or file calls, or HTTP through a tunnel or connect token. After exit, `get` may show `running` for a few minutes until the stop is recorded. Zo reports no exit reason or code. Write a job\'s result to disk. A resume runs the command again, so to read it, clear the command, resume, then use `zo.machine.read_bytes`. With `init: image` and a command, a missing `/sbin/init` ends the generation as an exit stop, without `incompatible_image`.","title":"Command"},"environment":{"additionalProperties":{"maxLength":4096,"type":"string"},"default":{},"description":"Environment variables set, exactly as written, in the boot process and every command run on the machine. Plain strings, not secrets: they are part of the machine\'s configuration, which anyone who can read the machine sees. Names are upper-case letters, digits and underscores, and reserved names such as `PATH` or ones starting with `ZO_` are refused; at most 64 variables of at most 4096 characters each. A variable here wins over a connection in `credentials` that sets the same name.","maxProperties":64,"title":"Environment","type":"object"},"credentials":{"default":[],"description":"Connection IDs whose credentials the machine receives as environment variables, in the boot process and every command. Each slot of a listed connection sets the variable its definition names, with the variables the slot and the connection declare. The machine also needs a use grant on each connection (`zo.grant.create` with the machine as assignee); a listed connection without one delivers nothing. When two listed connections set the same variable, the later one in the list wins. At most 100 connections, each listed once.","items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":100,"title":"Credentials","type":"array"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see and use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","idempotency_key","display_name","source","resources","lifecycle"],"title":"MachineCreateInput","type":"object","$defs":{"GpuType":{"enum":["T4","L4","A10","L40S","A100","A100-40GB","A100-80GB","RTX-PRO-6000","H100","H100!","H200","B200","B200+","B300"],"type":"string"},"MachineGpu":{"additionalProperties":false,"properties":{"type":{"$ref":"#/$defs/GpuType"},"count":{"maximum":8,"minimum":1,"title":"Count","type":"integer"}},"required":["type","count"],"title":"MachineGpu","type":"object"},"MachineLifecycleInput":{"additionalProperties":false,"properties":{"idle_timeout_seconds":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Omit for 900 seconds on CPU. For GPU, the default is the smaller of 300 seconds and max_run_seconds. An explicit GPU idle timeout must not exceed max_run_seconds.","title":"Idle Timeout Seconds"},"max_run_seconds":{"maximum":86400,"minimum":1,"title":"Max Run Seconds","type":"integer"}},"required":["max_run_seconds"],"title":"MachineLifecycleInput","type":"object"},"MachineResourcesInput":{"additionalProperties":false,"properties":{"vcpus":{"description":"Whole vCPUs of CPU capacity; each is half a Modal physical core. A quarter is reserved; the full allocation can burst when capacity allows. Guest logical CPU count is separate.","maximum":2147483647,"minimum":1,"title":"Vcpus","type":"integer"},"memory_mib":{"maximum":2147483647,"minimum":1,"title":"Memory Mib","type":"integer"},"gpu":{"anyOf":[{"$ref":"#/$defs/MachineGpu"},{"type":"null"}],"default":null}},"required":["vcpus","memory_mib"],"title":"MachineResourcesInput","type":"object"},"MachineSourceInput":{"additionalProperties":false,"properties":{"machine_image_id":{"description":"The machine image to boot (from `zo.machine_image.import`). Separate from `init`, which only chooses what runs first at boot.","minLength":1,"title":"Machine Image Id","type":"string"}},"required":["machine_image_id"],"title":"MachineSourceInput","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -741,7 +741,7 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "List independent whole-vCPU and whole-MiB ranges, regions, timeout bounds and per-second unit prices.",
+                    description: "List independent CPU/RAM bounds, GPU allocations, runtime capabilities, timers and per-second unit prices.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"MachineListConfigurationsInput","type":"object"}',
                     resultKind: "inline",
                 },
@@ -790,8 +790,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Save a running managed machine's filesystem as a ready image. Destination options live under image. Image visibility defaults to the source; choose workspace or protected explicitly to override it. Finish filesystem writes first. Processes and credentials are not rebound from the source. User-written secrets remain in captured files. Never automatically retry an uncertain result.",
-                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"image":{"$ref":"#/$defs/MachineImageCreateOptions"},"timeout_seconds":{"default":60,"description":"Maximum seconds for filesystem capture, including provider lookup. The remaining request deadline can shorten this budget.","maximum":180,"minimum":1,"title":"Timeout Seconds","type":"integer"}},"required":["machine_id","expected_revision","image"],"title":"MachineSnapshotInput","type":"object","$defs":{"MachineImageCreateOptions":{"additionalProperties":false,"properties":{"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"visibility":{"anyOf":[{"enum":["workspace","protected"],"type":"string"},{"type":"null"}],"default":null,"description":"Image visibility. Omit or pass null to use the creating operation\'s default. Protected images use ordinary verified-human creator ownership.","title":"Visibility"}},"required":["display_name"],"title":"MachineImageCreateOptions","type":"object"}}}',
+                    description: "Save a running managed machine's filesystem as a ready image. Destination options live under image. Image visibility defaults to the source; choose workspace or protected explicitly to override it. Finish filesystem writes first. Processes and credentials are not rebound from the source. User-written secrets remain in captured files. Never automatically retry an uncertain result. Describe what this machine image is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"image":{"$ref":"#/$defs/MachineImageCreateOptions"},"timeout_seconds":{"default":60,"description":"Maximum seconds for filesystem capture, including provider lookup. The remaining request deadline can shorten this budget.","maximum":180,"minimum":1,"title":"Timeout Seconds","type":"integer"}},"required":["machine_id","expected_revision","image"],"title":"MachineSnapshotInput","type":"object","$defs":{"MachineImageCreateOptions":{"additionalProperties":false,"properties":{"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this machine image is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"anyOf":[{"enum":["workspace","protected"],"type":"string"},{"type":"null"}],"default":null,"description":"Image visibility. Omit or pass null to use the creating operation\'s default. Protected images use ordinary verified-human creator ownership.","title":"Visibility"}},"required":["display_name"],"title":"MachineImageCreateOptions","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -827,7 +827,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Change a managed machine's name, timers or next-boot settings against its current revision.",
-                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":120,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"lifecycle":{"anyOf":[{"$ref":"#/$defs/MachineLifecycleUpdate"},{"type":"null"}],"default":null},"init":{"anyOf":[{"enum":["none","image"],"type":"string"},{"type":"null"}],"default":null,"description":"Which process runs first at boot. `none` (default): nothing; the machine waits for exec. `image`: the image\'s init system (systemd, OpenRC) becomes PID 1 and starts enabled services. `source.machine_image_id` chooses the image. Debian and Ubuntu need `systemd systemd-sysv`. Setting `image` needs exec permission; approval-gated exec is denied. Write access to boot files can run code as root at next boot.","title":"Init"},"command":{"anyOf":[{"items":{"minLength":1,"type":"string"},"maxItems":64,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Set the main process for the next resume. Arguments run without a shell; use [\\"sh\\", \\"-c\\", ...] for shell syntax. Find ENTRYPOINT and CMD on the image\'s registry page; Zo does not return them. Pass ENTRYPOINT then CMD. With `init: image`, wait for needed services. The machine stops when the command exits; resume runs it again. It may run more than once after a lost create or resume response, so make it safe to rerun. Each argument is at most 4,096 UTF-8 bytes and all arguments total at most 65,536 bytes. A running command is not activity: set `idle_timeout_seconds` at least as long as the job. The maximum is published by `zo.machine.list_configurations` (3,600 s today); a longer job needs Zo exec or file calls, or HTTP through a tunnel or connect token. After exit, `get` may show `running` for a few minutes. Zo reports no exit reason or code. Write a job\'s result to disk. A resume runs the command again, so to read it, clear the command, resume, then use `zo.machine.read_bytes`. With `init: image` and a command, a missing `/sbin/init` ends the generation as an exit stop, without `incompatible_image`. Changing the command needs exec permission; approval-gated exec is denied. Write access to its script can run code as root at next boot.","title":"Command"},"clear_command":{"default":false,"description":"Remove the main process on the next resume. Requires manage permission only.","title":"Clear Command","type":"boolean"}},"required":["machine_id","expected_revision"],"title":"MachineUpdateInput","type":"object","$defs":{"MachineLifecycleUpdate":{"additionalProperties":false,"description":"The timers a caller may change after create. Modal fixes them at\\nsandbox create, so a change takes effect at the next resume.","properties":{"idle_timeout_seconds":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Idle Timeout Seconds"},"max_run_seconds":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Run Seconds"}},"title":"MachineLifecycleUpdate","type":"object","required":[]}}}',
+                    inputJson: '{"additionalProperties":false,"properties":{"machine_id":{"title":"Machine Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":120,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Describe what this machine is for in the user\'s terms.","title":"Description"},"lifecycle":{"anyOf":[{"$ref":"#/$defs/MachineLifecycleUpdate"},{"type":"null"}],"default":null},"init":{"anyOf":[{"enum":["none","image"],"type":"string"},{"type":"null"}],"default":null,"description":"Which process runs first at boot. `none` (default): nothing; the machine waits for exec. `image`: the image\'s init system (systemd, OpenRC) becomes PID 1 and starts enabled services. `source.machine_image_id` chooses the image. Debian and Ubuntu need `systemd systemd-sysv`. Write access to boot files can run code as root at next boot.","title":"Init"},"command":{"anyOf":[{"items":{"minLength":1,"type":"string"},"maxItems":64,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Set the main process for the next resume. Arguments run without a shell; use [\\"sh\\", \\"-c\\", ...] for shell syntax. Find ENTRYPOINT and CMD on the image\'s registry page; Zo does not return them. Pass ENTRYPOINT then CMD. With `init: image`, wait for needed services. The machine stops when the command exits; resume runs it again. It may run more than once after a lost create or resume response, so make it safe to rerun. Each argument is at most 4,096 UTF-8 bytes and all arguments total at most 65,536 bytes. A running command is not activity: set `idle_timeout_seconds` at least as long as the job. The maximum is published by `zo.machine.list_configurations`: 3,600 s for CPU machines and 86,400 s for GPU machines. Longer CPU jobs need Zo exec or file calls, or HTTP through a tunnel or connect token. After exit, `get` may show `running` for a few minutes. Zo reports no exit reason or code. Write a job\'s result to disk. A resume runs the command again, so to read it, clear the command, resume, then use `zo.machine.read_bytes`. With `init: image` and a command, a missing `/sbin/init` ends the generation as an exit stop, without `incompatible_image`. Write access to its script can run code as root at next boot.","title":"Command"},"clear_command":{"default":false,"description":"Remove the main process on the next resume.","title":"Clear Command","type":"boolean"},"environment":{"anyOf":[{"additionalProperties":{"maxLength":4096,"type":"string"},"maxProperties":64,"type":"object"},{"type":"null"}],"default":null,"description":"The environment that replaces the stored one; omit it to keep it. Environment variables set, exactly as written, in the boot process and every command run on the machine. Plain strings, not secrets: they are part of the machine\'s configuration, which anyone who can read the machine sees. Names are upper-case letters, digits and underscores, and reserved names such as `PATH` or ones starting with `ZO_` are refused; at most 64 variables of at most 4096 characters each. A variable here wins over a connection in `credentials` that sets the same name.","title":"Environment"},"credentials":{"anyOf":[{"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":100,"type":"array"},{"type":"null"}],"default":null,"description":"The list that replaces the stored one; omit it to keep it. Connection IDs whose credentials the machine receives as environment variables, in the boot process and every command. Each slot of a listed connection sets the variable its definition names, with the variables the slot and the connection declare. The machine also needs a use grant on each connection (`zo.grant.create` with the machine as assignee); a listed connection without one delivers nothing. When two listed connections set the same variable, the later one in the list wins. At most 100 connections, each listed once.","title":"Credentials"}},"required":["machine_id","expected_revision"],"title":"MachineUpdateInput","type":"object","$defs":{"MachineLifecycleUpdate":{"additionalProperties":false,"description":"The timers a caller may change after create. Modal fixes them at\\nsandbox create, so a change takes effect at the next resume.","properties":{"idle_timeout_seconds":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Idle Timeout Seconds"},"max_run_seconds":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Run Seconds"}},"title":"MachineLifecycleUpdate","type":"object","required":[]}}}',
                     resultKind: "inline",
                 },
             ],
@@ -874,8 +874,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Import a registry image, pinned to its manifest digest, and return the image view.",
-                    inputJson: '{"additionalProperties":false,"properties":{"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see and use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"source":{"$ref":"#/$defs/RegistrySourceInput"}},"required":["display_name","workspace_id","idempotency_key","source"],"title":"MachineImageImportInput","type":"object","$defs":{"RegistrySourceInput":{"additionalProperties":false,"properties":{"kind":{"const":"registry","title":"Kind","type":"string"},"ref":{"maxLength":1024,"minLength":1,"pattern":"^(?:[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[0-9]{1,5})?/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[0-9a-f]{64})?$","title":"Ref","type":"string"},"platform":{"const":"linux/amd64","default":"linux/amd64","title":"Platform","type":"string"}},"required":["kind","ref"],"title":"RegistrySourceInput","type":"object"}}}',
+                    description: "Import a registry image, pinned to its manifest digest, and return the image view. Describe what this machine image is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this machine image is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can see and use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"source":{"$ref":"#/$defs/RegistrySourceInput"}},"required":["display_name","workspace_id","idempotency_key","source"],"title":"MachineImageImportInput","type":"object","$defs":{"RegistrySourceInput":{"additionalProperties":false,"properties":{"kind":{"const":"registry","title":"Kind","type":"string"},"ref":{"maxLength":1024,"minLength":1,"pattern":"^(?:[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[0-9]{1,5})?/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[0-9a-f]{64})?$","title":"Ref","type":"string"},"platform":{"const":"linux/amd64","default":"linux/amd64","title":"Platform","type":"string"}},"required":["kind","ref"],"title":"RegistrySourceInput","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -972,8 +972,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Create a schedule.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"rrule":{"maxLength":1000,"minLength":1,"title":"Rrule","type":"string"},"start_at":{"title":"Start At","type":"string"},"timezone":{"title":"Timezone","type":"string"},"data":{"additionalProperties":{"x-zo-json-value":true},"default":{},"title":"Data","type":"object"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name","rrule","start_at","timezone"],"title":"ScheduleCreateInput","type":"object"}',
+                    description: "Create a schedule. Describe what this schedule is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this schedule is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"rrule":{"maxLength":1000,"minLength":1,"title":"Rrule","type":"string"},"start_at":{"title":"Start At","type":"string"},"timezone":{"title":"Timezone","type":"string"},"data":{"additionalProperties":{"x-zo-json-value":true},"default":{},"title":"Data","type":"object"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name","rrule","start_at","timezone"],"title":"ScheduleCreateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -1022,7 +1022,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Update a schedule.",
-                    inputJson: '{"additionalProperties":false,"properties":{"schedule_id":{"maxLength":200,"minLength":1,"title":"Schedule Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"rrule":{"maxLength":1000,"minLength":1,"title":"Rrule","type":"string"},"start_at":{"title":"Start At","type":"string"},"timezone":{"title":"Timezone","type":"string"},"data":{"additionalProperties":{"x-zo-json-value":true},"title":"Data","type":"object"},"lifecycle":{"enum":["active","paused"],"title":"Lifecycle","type":"string"}},"required":["schedule_id","expected_revision","display_name","rrule","start_at","timezone","data","lifecycle"],"title":"ScheduleUpdateInput","type":"object"}',
+                    inputJson: '{"additionalProperties":false,"properties":{"schedule_id":{"maxLength":200,"minLength":1,"title":"Schedule Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Describe what this schedule is for in the user\'s terms.","title":"Description"},"rrule":{"maxLength":1000,"minLength":1,"title":"Rrule","type":"string"},"start_at":{"title":"Start At","type":"string"},"timezone":{"title":"Timezone","type":"string"},"data":{"additionalProperties":{"x-zo-json-value":true},"title":"Data","type":"object"},"lifecycle":{"enum":["active","paused"],"title":"Lifecycle","type":"string"}},"required":["schedule_id","expected_revision","display_name","rrule","start_at","timezone","data","lifecycle"],"title":"ScheduleUpdateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -1075,8 +1075,8 @@ export const commandManifest = {
                 },
                 {
                     version: 2,
-                    description: "Bind an event definition to a function entrypoint or a workflow's start run as a non-human execution principal, or to an Agent whose sessions receive each occurrence.",
-                    inputJson: '{"additionalProperties":false,"description":"Bind an event definition to a handler. ``handler_resource_type`` is\\n``function``, ``workflow`` or ``agent``. A Function target names\\n``handler_resource_id``, ``handler_entrypoint``, ``input_contract_version``,\\n``input_contract_kind`` and the ``execution_principal_id`` service account it\\nruns as. A workflow target names ``workflow_id`` and the same fields but\\n``handler_resource_id``: ``handler_entrypoint`` is ``start``, which begins a\\nnew run per occurrence with the envelope as its ``event`` input, and\\n``input_contract_version`` is 1, the contract of that input. An Agent\\ntarget names ``agent_id``, the ``agent_priority`` an occurrence enters a turn\\nwith (``queue``, ``steer`` or ``interrupt``), the ``agent_session_policy``\\nthat picks its session (``new``; ``fixed``, with ``agent_session_id``; or\\n``per_conversation``, for an event with a ``conversation_path``, keyed in\\n``agent_session_scope``, the event\'s ``<publisher>/<name>`` when omitted)\\nand optional ``agent_instructions`` shown with every occurrence. Fields of\\nthe other handler type are refused. Omit ``filter`` to receive every\\noccurrence.","properties":{"workspace_id":{"title":"Workspace Id","type":"string"},"event_id":{"title":"Event Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"filter":{"anyOf":[{"discriminator":{"mapping":{"all":"#/$defs/All1","any":"#/$defs/Any1","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All1"},{"$ref":"#/$defs/Any1"}]},{"type":"null"}],"default":null,"title":"Filter"},"handler_resource_type":{"enum":["function","workflow","agent"],"title":"Handler Resource Type","type":"string"},"handler_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Handler Resource Id"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Workflow Id"},"handler_entrypoint":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Handler Entrypoint"},"input_contract_version":{"anyOf":[{"exclusiveMinimum":0,"maximum":2147483647,"type":"integer"},{"type":"null"}],"default":null,"title":"Input Contract Version"},"input_contract_kind":{"anyOf":[{"$ref":"#/$defs/InputContractKind"},{"type":"null"}],"default":null},"execution_principal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Execution Principal Id"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Id"},"agent_priority":{"default":"queue","enum":["queue","steer","interrupt"],"title":"Agent Priority","type":"string"},"agent_session_policy":{"default":"new","enum":["new","fixed","per_conversation"],"title":"Agent Session Policy","type":"string"},"agent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Session Id"},"agent_session_scope":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Agent Session Scope"},"agent_instructions":{"anyOf":[{"maxLength":4096,"type":"string"},{"type":"null"}],"default":null,"title":"Agent Instructions"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","event_id","display_name","handler_resource_type"],"title":"SubscriptionCreateInputV2","type":"object","$defs":{"All1":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All2","any":"#/$defs/Any2","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All2"},{"$ref":"#/$defs/Any2"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All1","type":"object"},"All2":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All3","any":"#/$defs/Any3","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All3"},{"$ref":"#/$defs/Any3"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All2","type":"object"},"All3":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All3","type":"object"},"Any1":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All2","any":"#/$defs/Any2","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All2"},{"$ref":"#/$defs/Any2"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any1","type":"object"},"Any2":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All3","any":"#/$defs/Any3","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All3"},{"$ref":"#/$defs/Any3"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any2","type":"object"},"Any3":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any3","type":"object"},"EqFilter":{"additionalProperties":false,"properties":{"op":{"const":"eq","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"},"value":{"x-zo-json-value":true}},"required":["op","path","value"],"title":"EqFilter","type":"object"},"ExistsFilter":{"additionalProperties":false,"properties":{"op":{"const":"exists","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"}},"required":["op","path"],"title":"ExistsFilter","type":"object"},"InFilter":{"additionalProperties":false,"properties":{"op":{"const":"in","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"},"values":{"items":{"x-zo-json-value":true},"maxItems":32,"minItems":1,"title":"Values","type":"array"}},"required":["op","path","values"],"title":"InFilter","type":"object"},"InputContractKind":{"enum":["exact_event","generic_envelope"],"type":"string"}}}',
+                    description: "Bind an event definition to a function entrypoint or a workflow's start run as a non-human execution principal, or to an Agent whose sessions receive each occurrence. Describe what this subscription is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"description":"Bind an event definition to a handler. ``handler_resource_type`` is\\n``function``, ``workflow`` or ``agent``. A Function target names\\n``handler_resource_id``, ``handler_entrypoint``, ``input_contract_version``,\\n``input_contract_kind`` and the ``execution_principal_id`` service account it\\nruns as. A workflow target names ``workflow_id`` and the same fields but\\n``handler_resource_id``: ``handler_entrypoint`` is ``start``, which begins a\\nnew run per occurrence with the envelope as its ``event`` input, and\\n``input_contract_version`` is 1, the contract of that input. An Agent\\ntarget names ``agent_id``, the ``agent_priority`` an occurrence enters a turn\\nwith (``queue``, ``steer`` or ``interrupt``), the ``agent_session_policy``\\nthat picks its session (``new``; ``fixed``, with ``agent_session_id``; or\\n``per_conversation``, for an event with a ``conversation_path``, keyed in\\n``agent_session_scope``, the event\'s ``<publisher>/<name>`` when omitted)\\nand optional ``agent_instructions`` shown with every occurrence. Fields of\\nthe other handler type are refused. Omit ``filter`` to receive every\\noccurrence.","properties":{"workspace_id":{"title":"Workspace Id","type":"string"},"event_id":{"title":"Event Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this subscription is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"filter":{"anyOf":[{"discriminator":{"mapping":{"all":"#/$defs/All1","any":"#/$defs/Any1","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All1"},{"$ref":"#/$defs/Any1"}]},{"type":"null"}],"default":null,"title":"Filter"},"handler_resource_type":{"enum":["function","workflow","agent"],"title":"Handler Resource Type","type":"string"},"handler_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Handler Resource Id"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Workflow Id"},"handler_entrypoint":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Handler Entrypoint"},"input_contract_version":{"anyOf":[{"exclusiveMinimum":0,"maximum":2147483647,"type":"integer"},{"type":"null"}],"default":null,"title":"Input Contract Version"},"input_contract_kind":{"anyOf":[{"$ref":"#/$defs/InputContractKind"},{"type":"null"}],"default":null},"execution_principal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Execution Principal Id"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Id"},"agent_priority":{"default":"queue","enum":["queue","steer","interrupt"],"title":"Agent Priority","type":"string"},"agent_session_policy":{"default":"new","enum":["new","fixed","per_conversation"],"title":"Agent Session Policy","type":"string"},"agent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Session Id"},"agent_session_scope":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Agent Session Scope"},"agent_instructions":{"anyOf":[{"maxLength":4096,"type":"string"},{"type":"null"}],"default":null,"title":"Agent Instructions"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","event_id","display_name","handler_resource_type"],"title":"SubscriptionCreateInputV2","type":"object","$defs":{"All1":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All2","any":"#/$defs/Any2","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All2"},{"$ref":"#/$defs/Any2"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All1","type":"object"},"All2":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All3","any":"#/$defs/Any3","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All3"},{"$ref":"#/$defs/Any3"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All2","type":"object"},"All3":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All3","type":"object"},"Any1":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All2","any":"#/$defs/Any2","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All2"},{"$ref":"#/$defs/Any2"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any1","type":"object"},"Any2":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All3","any":"#/$defs/Any3","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All3"},{"$ref":"#/$defs/Any3"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any2","type":"object"},"Any3":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any3","type":"object"},"EqFilter":{"additionalProperties":false,"properties":{"op":{"const":"eq","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"},"value":{"x-zo-json-value":true}},"required":["op","path","value"],"title":"EqFilter","type":"object"},"ExistsFilter":{"additionalProperties":false,"properties":{"op":{"const":"exists","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"}},"required":["op","path"],"title":"ExistsFilter","type":"object"},"InFilter":{"additionalProperties":false,"properties":{"op":{"const":"in","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"},"values":{"items":{"x-zo-json-value":true},"maxItems":32,"minItems":1,"title":"Values","type":"array"}},"required":["op","path","values"],"title":"InFilter","type":"object"},"InputContractKind":{"enum":["exact_event","generic_envelope"],"type":"string"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1144,7 +1144,7 @@ export const commandManifest = {
                 {
                     version: 2,
                     description: "Replace a subscription's configuration and lifecycle at the expected revision.",
-                    inputJson: '{"additionalProperties":false,"description":"Full replacement of every create field but the workspace and the event (a new\\ndefinition or version is a new subscription), plus ``lifecycle``: ``active``\\nresumes a paused or suspended subscription, ``paused`` pauses it;\\n``zo.subscription.delete`` retires. ``handler_resource_type`` must be the\\nsubscription\'s own: a different handler type is a new subscription.","properties":{"subscription_id":{"title":"Subscription Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"filter":{"anyOf":[{"discriminator":{"mapping":{"all":"#/$defs/All1","any":"#/$defs/Any1","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All1"},{"$ref":"#/$defs/Any1"}]},{"type":"null"}],"default":null,"title":"Filter"},"handler_resource_type":{"enum":["function","workflow","agent"],"title":"Handler Resource Type","type":"string"},"handler_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Handler Resource Id"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Workflow Id"},"handler_entrypoint":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Handler Entrypoint"},"input_contract_version":{"anyOf":[{"exclusiveMinimum":0,"maximum":2147483647,"type":"integer"},{"type":"null"}],"default":null,"title":"Input Contract Version"},"input_contract_kind":{"anyOf":[{"$ref":"#/$defs/InputContractKind"},{"type":"null"}],"default":null},"execution_principal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Execution Principal Id"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Id"},"agent_priority":{"default":"queue","enum":["queue","steer","interrupt"],"title":"Agent Priority","type":"string"},"agent_session_policy":{"default":"new","enum":["new","fixed","per_conversation"],"title":"Agent Session Policy","type":"string"},"agent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Session Id"},"agent_session_scope":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Agent Session Scope"},"agent_instructions":{"anyOf":[{"maxLength":4096,"type":"string"},{"type":"null"}],"default":null,"title":"Agent Instructions"},"lifecycle":{"enum":["active","paused"],"title":"Lifecycle","type":"string"}},"required":["subscription_id","expected_revision","display_name","handler_resource_type","lifecycle"],"title":"SubscriptionUpdateInputV2","type":"object","$defs":{"All1":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All2","any":"#/$defs/Any2","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All2"},{"$ref":"#/$defs/Any2"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All1","type":"object"},"All2":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All3","any":"#/$defs/Any3","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All3"},{"$ref":"#/$defs/Any3"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All2","type":"object"},"All3":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All3","type":"object"},"Any1":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All2","any":"#/$defs/Any2","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All2"},{"$ref":"#/$defs/Any2"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any1","type":"object"},"Any2":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All3","any":"#/$defs/Any3","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All3"},{"$ref":"#/$defs/Any3"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any2","type":"object"},"Any3":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any3","type":"object"},"EqFilter":{"additionalProperties":false,"properties":{"op":{"const":"eq","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"},"value":{"x-zo-json-value":true}},"required":["op","path","value"],"title":"EqFilter","type":"object"},"ExistsFilter":{"additionalProperties":false,"properties":{"op":{"const":"exists","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"}},"required":["op","path"],"title":"ExistsFilter","type":"object"},"InFilter":{"additionalProperties":false,"properties":{"op":{"const":"in","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"},"values":{"items":{"x-zo-json-value":true},"maxItems":32,"minItems":1,"title":"Values","type":"array"}},"required":["op","path","values"],"title":"InFilter","type":"object"},"InputContractKind":{"enum":["exact_event","generic_envelope"],"type":"string"}}}',
+                    inputJson: '{"additionalProperties":false,"description":"Replace create fields except workspace, event and optional description.\\nA new event definition or version requires a new subscription.\\nOmitted or null description keeps its value. ``lifecycle``: ``active``\\nresumes a paused or suspended subscription, ``paused`` pauses it;\\n``zo.subscription.delete`` retires. ``handler_resource_type`` must be the\\nsubscription\'s own: a different handler type is a new subscription.","properties":{"subscription_id":{"title":"Subscription Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Describe what this subscription is for in the user\'s terms.","title":"Description"},"filter":{"anyOf":[{"discriminator":{"mapping":{"all":"#/$defs/All1","any":"#/$defs/Any1","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All1"},{"$ref":"#/$defs/Any1"}]},{"type":"null"}],"default":null,"title":"Filter"},"handler_resource_type":{"enum":["function","workflow","agent"],"title":"Handler Resource Type","type":"string"},"handler_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Handler Resource Id"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Workflow Id"},"handler_entrypoint":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Handler Entrypoint"},"input_contract_version":{"anyOf":[{"exclusiveMinimum":0,"maximum":2147483647,"type":"integer"},{"type":"null"}],"default":null,"title":"Input Contract Version"},"input_contract_kind":{"anyOf":[{"$ref":"#/$defs/InputContractKind"},{"type":"null"}],"default":null},"execution_principal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Execution Principal Id"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Id"},"agent_priority":{"default":"queue","enum":["queue","steer","interrupt"],"title":"Agent Priority","type":"string"},"agent_session_policy":{"default":"new","enum":["new","fixed","per_conversation"],"title":"Agent Session Policy","type":"string"},"agent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Session Id"},"agent_session_scope":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Agent Session Scope"},"agent_instructions":{"anyOf":[{"maxLength":4096,"type":"string"},{"type":"null"}],"default":null,"title":"Agent Instructions"},"lifecycle":{"enum":["active","paused"],"title":"Lifecycle","type":"string"}},"required":["subscription_id","expected_revision","display_name","handler_resource_type","lifecycle"],"title":"SubscriptionUpdateInputV2","type":"object","$defs":{"All1":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All2","any":"#/$defs/Any2","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All2"},{"$ref":"#/$defs/Any2"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All1","type":"object"},"All2":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All3","any":"#/$defs/Any3","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All3"},{"$ref":"#/$defs/Any3"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All2","type":"object"},"All3":{"additionalProperties":false,"properties":{"op":{"const":"all","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"All3","type":"object"},"Any1":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All2","any":"#/$defs/Any2","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All2"},{"$ref":"#/$defs/Any2"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any1","type":"object"},"Any2":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"all":"#/$defs/All3","any":"#/$defs/Any3","eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"},{"$ref":"#/$defs/All3"},{"$ref":"#/$defs/Any3"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any2","type":"object"},"Any3":{"additionalProperties":false,"properties":{"op":{"const":"any","title":"Op","type":"string"},"filters":{"items":{"discriminator":{"mapping":{"eq":"#/$defs/EqFilter","exists":"#/$defs/ExistsFilter","in":"#/$defs/InFilter"},"propertyName":"op"},"oneOf":[{"$ref":"#/$defs/EqFilter"},{"$ref":"#/$defs/InFilter"},{"$ref":"#/$defs/ExistsFilter"}]},"maxItems":32,"minItems":1,"title":"Filters","type":"array"}},"required":["op","filters"],"title":"Any3","type":"object"},"EqFilter":{"additionalProperties":false,"properties":{"op":{"const":"eq","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"},"value":{"x-zo-json-value":true}},"required":["op","path","value"],"title":"EqFilter","type":"object"},"ExistsFilter":{"additionalProperties":false,"properties":{"op":{"const":"exists","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"}},"required":["op","path"],"title":"ExistsFilter","type":"object"},"InFilter":{"additionalProperties":false,"properties":{"op":{"const":"in","title":"Op","type":"string"},"path":{"maxLength":256,"minLength":1,"pattern":"^(?:/[^/]*)+$","title":"Path","type":"string"},"values":{"items":{"x-zo-json-value":true},"maxItems":32,"minItems":1,"title":"Values","type":"array"}},"required":["op","path","values"],"title":"InFilter","type":"object"},"InputContractKind":{"enum":["exact_event","generic_envelope"],"type":"string"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1448,8 +1448,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Create a Website address in a workspace.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"slug":{"pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$","title":"Slug","type":"string"},"display_name":{"maxLength":200,"minLength":1,"title":"Display Name","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","slug","display_name"],"title":"WebsiteCreateInput","type":"object"}',
+                    description: "Create a Website address in a workspace. Describe what this Website is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"slug":{"pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$","title":"Slug","type":"string"},"display_name":{"maxLength":200,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this Website is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","slug","display_name"],"title":"WebsiteCreateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -1498,7 +1498,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Update a Website display name or custom hostname.",
-                    inputJson: '{"additionalProperties":false,"properties":{"website_id":{"maxLength":200,"minLength":1,"title":"Website Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"custom_hostname":{"anyOf":[{"$ref":"#/$defs/CustomHostnameChange"},{"type":"null"}],"default":null}},"required":["website_id","expected_revision"],"title":"WebsiteUpdateInput","type":"object","$defs":{"CustomHostnameChange":{"additionalProperties":false,"properties":{"hostname":{"anyOf":[{"maxLength":253,"minLength":4,"type":"string"},{"type":"null"}],"title":"Hostname"}},"required":["hostname"],"title":"CustomHostnameChange","type":"object"}}}',
+                    inputJson: '{"additionalProperties":false,"properties":{"website_id":{"maxLength":200,"minLength":1,"title":"Website Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Describe what this Website is for in the user\'s terms.","title":"Description"},"custom_hostname":{"anyOf":[{"$ref":"#/$defs/CustomHostnameChange"},{"type":"null"}],"default":null}},"required":["website_id","expected_revision"],"title":"WebsiteUpdateInput","type":"object","$defs":{"CustomHostnameChange":{"additionalProperties":false,"properties":{"hostname":{"anyOf":[{"maxLength":253,"minLength":4,"type":"string"},{"type":"null"}],"title":"Hostname"}},"required":["hostname"],"title":"CustomHostnameChange","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1618,8 +1618,8 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Create a workflow in a workspace.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name"],"title":"WorkflowCreateInput","type":"object"}',
+                    description: "Create a workflow in a workspace. Describe what this workflow is for in the user's terms.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"},"display_name":{"maxLength":120,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this workflow is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name"],"title":"WorkflowCreateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],

package/dist/http.d.ts

@@ -3,7 +3,11 @@ import { CliError } from "./errors.ts";
 export declare function systemApiFailure(response: Response, raw: string | Uint8Array, operation: string): SystemAPIError;
 export declare class RequestFailure extends CliError {
     readonly ambiguous: boolean;
-    constructor(ambiguous: boolean, code?: string, exitCode?: number);
+    /** The HTTP status when the server answered; absent for transport failures. */
+    readonly status?: number | undefined;
+    constructor(ambiguous: boolean, code?: string, exitCode?: number, 
+    /** The HTTP status when the server answered; absent for transport failures. */
+    status?: number | undefined);
 }
 export declare function requestJson(url: string, init?: RequestInit, fetcher?: typeof fetch, options?: {
     timeoutMs?: number;

package/dist/http.js

@@ -46,11 +46,15 @@ export function systemApiFailure(response, raw, operation) {
 }
 export class RequestFailure extends CliError {
     ambiguous;
-    constructor(ambiguous, code = "transport_error", exitCode = 5) {
+    status;
+    constructor(ambiguous, code = "transport_error", exitCode = 5, 
+    /** The HTTP status when the server answered; absent for transport failures. */
+    status) {
         super(code === "invalid_grant"
             ? "Your sign-in ended. Run zo login."
             : "The authentication request failed. Try again or run zo login.", exitCode, code);
         this.ambiguous = ambiguous;
+        this.status = status;
     }
 }
 export async function requestJson(url, init = {}, fetcher = fetch, options = {}) {
@@ -106,6 +110,10 @@ export async function requestJson(url, init = {}, fetcher = fetch, options = {})
         body = JSON.parse(raw);
     }
     catch {
+        // Cloudflare's edge rate limits answer 429 with a non-JSON page before the
+        // worker runs; the status alone says the request was not processed.
+        if (response.status === 429)
+            throw new RequestFailure(true, "temporarily_unavailable", 5, 429);
         throw new RequestFailure(false, "invalid_response");
     }
     if (!response.ok) {
@@ -118,7 +126,7 @@ export async function requestJson(url, init = {}, fetcher = fetch, options = {})
             ? 3
             : response.status === 403
                 ? 4
-                : 5);
+                : 5, response.status);
     }
     return body;
 }

package/dist/login.d.ts

@@ -1,14 +1,30 @@
+export declare const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export interface LoginPrompt {
+    url: string;
+    userCode: string;
+    /** False when the CLI won't open a browser: --no-browser, SSH or no display. */
+    browser: boolean;
+}
 export interface LoginOptions {
     noBrowser?: boolean;
-    timeoutMs?: number;
     signal?: AbortSignal;
-    announce?: (url: string) => void;
+    platform?: NodeJS.Platform;
+    announce?: (prompt: LoginPrompt) => void;
     openBrowser?: (url: string) => Promise<void>;
 }
-export interface LoginCode {
-    code: string;
-    verifier: string;
-    redirectUri: string;
+export interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    url: string;
+    expiresInMs: number;
+    intervalMs: number;
 }
 export declare function openBrowser(url: string): Promise<void>;
-export declare function loginCode(issuer: string, audience: string, clientId: string, options?: LoginOptions): Promise<LoginCode>;
+/**
+ * A browser opened over SSH, or with no display, lands on the wrong machine or
+ * nowhere. xdg-open needs a display on every system other than macOS.
+ */
+export declare function browserAvailable(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+export declare function pause(ms: number, signal?: AbortSignal | null): Promise<void>;
+export declare function parseDeviceAuthorization(raw: unknown, issuer: string): DeviceAuthorization;
+export declare function deviceAuthorization(issuer: string, audience: string, clientId: string, fetcher: typeof fetch, signal?: AbortSignal): Promise<DeviceAuthorization>;

package/dist/login.js

@@ -1,102 +1,93 @@
-import { createHash, randomBytes } from "node:crypto";
-import { createServer } from "node:http";
 import { spawn } from "node:child_process";
-import { CliError } from "./errors.js";
+import { CliError, record, throwIfInterrupted } from "./errors.js";
+import { requestJson, RequestFailure } from "./http.js";
+export const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 export async function openBrowser(url) {
     await new Promise((resolve, reject) => {
         const child = spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { stdio: "ignore", detached: true });
         child.unref();
-        child.once("error", () => reject(new CliError("Could not open a browser. Retry with --no-browser.")));
-        child.once("exit", (status) => status === 0
-            ? resolve()
-            : reject(new CliError("Could not open a browser. Retry with --no-browser.")));
+        child.once("error", reject);
+        child.once("exit", (status) => status === 0 ? resolve() : reject(new Error("Browser opener failed.")));
     });
 }
-export async function loginCode(issuer, audience, clientId, options = {}) {
-    const state = randomBytes(32).toString("base64url");
-    const verifier = randomBytes(32).toString("base64url");
-    let complete = () => { };
-    let fail = () => { };
-    const received = new Promise((resolve, reject) => {
-        complete = resolve;
-        fail = reject;
-    });
-    // The callback may arrive while the browser opener is still running.
-    void received.catch(() => { });
-    let accepted = false;
-    const server = createServer((request, response) => {
-        let url;
-        try {
-            url = new URL(request.url ?? "/", "http://127.0.0.1");
-        }
-        catch {
-            response.writeHead(400).end("Invalid callback.");
-            return;
-        }
-        const params = url.searchParams;
-        const keys = [...params.keys()];
-        const valid = !accepted &&
-            request.method === "GET" &&
-            url.pathname === "/callback" &&
-            keys.length === new Set(keys).size &&
-            params.get("state") === state &&
-            params.get("iss") === issuer &&
-            params.has("code") !== params.has("error");
-        response.setHeader("Content-Type", "text/plain; charset=utf-8");
-        response.setHeader("Cache-Control", "no-store");
-        if (!valid) {
-            response.writeHead(400).end("Invalid callback.");
-            return;
-        }
-        accepted = true;
-        response.end("You may close this window and return to Zo.");
-        if (params.has("error"))
-            fail(new CliError("Authorization was denied. Run zo login to try again.", 4, "access_denied"));
-        else {
-            const code = params.get("code");
-            if (code)
-                complete(code);
-            else
-                fail(new CliError("Authorization returned an empty code.", 3, "invalid_response"));
-        }
-    });
-    server.requestTimeout = 5_000;
-    server.headersTimeout = 5_000;
-    await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(0, "127.0.0.1", resolve);
+/**
+ * A browser opened over SSH, or with no display, lands on the wrong machine or
+ * nowhere. xdg-open needs a display on every system other than macOS.
+ */
+export function browserAvailable(env, platform = process.platform) {
+    if (env.SSH_CONNECTION || env.SSH_TTY)
+        return false;
+    return platform === "darwin" || !!env.DISPLAY || !!env.WAYLAND_DISPLAY;
+}
+export function pause(ms, signal) {
+    throwIfInterrupted(signal);
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(new CliError("Interrupted.", 130, "interrupted"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", abort, { once: true });
     });
-    const address = server.address();
-    if (!address || typeof address === "string")
-        throw new CliError("Could not bind the login callback.");
-    const redirectUri = `http://127.0.0.1:${address.port}/callback`;
-    const authorize = new URL("/zo-system-api/oauth/authorize", issuer);
-    authorize.search = new URLSearchParams({
-        response_type: "code",
-        client_id: clientId,
-        redirect_uri: redirectUri,
-        resource: audience,
-        code_challenge: createHash("sha256").update(verifier).digest("base64url"),
-        code_challenge_method: "S256",
-        state,
-    }).toString();
-    const timer = setTimeout(() => fail(new CliError("Login timed out. Run zo login to try again.", 3, "login_timeout")), options.timeoutMs ?? 300_000);
-    const abort = () => fail(new CliError("Login interrupted.", 130, "interrupted"));
-    options.signal?.addEventListener("abort", abort, { once: true });
+}
+function seconds(value, maximum) {
+    return typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value > 0 &&
+        value <= maximum
+        ? value
+        : undefined;
+}
+export function parseDeviceAuthorization(raw, issuer) {
+    const invalid = () => new CliError("The sign-in service returned an invalid response.", 5, "invalid_response");
+    if (!record(raw) ||
+        typeof raw.device_code !== "string" ||
+        !/^[A-Za-z0-9._~-]{1,512}$/.test(raw.device_code) ||
+        typeof raw.user_code !== "string" ||
+        !/^[A-Z0-9]{1,8}(?:-[A-Z0-9]{1,8}){0,3}$/.test(raw.user_code) ||
+        typeof raw.verification_uri_complete !== "string")
+        throw invalid();
+    const expiresIn = seconds(raw.expires_in, 3_600);
+    const interval = raw.interval === undefined ? 2 : seconds(raw.interval, 60);
+    if (expiresIn === undefined || interval === undefined)
+        throw invalid();
+    let url;
+    try {
+        url = new URL(raw.verification_uri_complete);
+    }
+    catch {
+        throw invalid();
+    }
+    // The URL goes to the system opener; only the issuer's own scheme is safe.
+    // Production is https; the local test issuer is http.
+    if (url.protocol !== new URL(issuer).protocol || url.username || url.password)
+        throw invalid();
+    return {
+        deviceCode: raw.device_code,
+        userCode: raw.user_code,
+        url: url.href,
+        expiresInMs: expiresIn * 1000,
+        intervalMs: interval * 1000,
+    };
+}
+export async function deviceAuthorization(issuer, audience, clientId, fetcher, signal) {
+    let raw;
     try {
-        if (options.signal?.aborted)
-            abort();
-        else {
-            options.announce?.(authorize.href);
-            if (!options.noBrowser)
-                void (options.openBrowser ?? openBrowser)(authorize.href).catch(fail);
-        }
-        return { code: await received, verifier, redirectUri };
+        raw = await requestJson(`${issuer}/zo-system-api/oauth/device_authorization`, {
+            method: "POST",
+            signal,
+            body: new URLSearchParams({ client_id: clientId, resource: audience }),
+        }, fetcher);
     }
-    finally {
-        clearTimeout(timer);
-        options.signal?.removeEventListener("abort", abort);
-        server.closeAllConnections();
-        await new Promise((resolve) => server.close(() => resolve()));
+    catch (error) {
+        if (error instanceof RequestFailure && error.status === 429)
+            throw new CliError("Too many sign-in attempts from this network. Wait a minute, then run zo login again.", 5, "rate_limited");
+        if (error instanceof RequestFailure && error.code === "unauthorized_client")
+            throw new CliError("This environment does not allow Zo CLI sign-in yet.", 5, "unauthorized_client");
+        throw error;
     }
+    return parseDeviceAuthorization(raw, issuer);
 }

package/dist/main.js

@@ -26,7 +26,7 @@ Use --profile to keep separate sign-ins. New profiles use production.
 ZO_SYSTEM_API_ACCESS_TOKEN overrides saved credentials; ZO_WORKSPACE_ID selects a workspace.
 `;
 const localHelp = {
-    login: "Usage: zo login [--profile <name>] [--workspace <id>] [--no-browser]\nPrint the sign-in URL, open your browser, and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--no-browser skips opening the browser and still waits for the localhost callback.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
+    login: "Usage: zo login [--profile <name>] [--workspace <id>] [--no-browser]\nPrint a sign-in URL and code, open your browser, and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--no-browser prints the URL without opening a browser; approve it on any device.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
     logout: "Usage: zo logout [--profile <name>] [--local-only]\nRevoke the saved sign-in and pending replaced sign-ins. --local-only removes local credentials without revoking server access.\n",
     auth: "Usage: zo auth status | token [--headers]\nStatus shows the current identity; token explicitly prints an access token.\n",
     "auth status": "Usage: zo auth status [--profile <name>] [--workspace <id>] [--json]\nShow the approving person, sign-in expiry and effective identity in the selected workspace.\n",
@@ -41,6 +41,16 @@ const localHelp = {
     rpc: "Usage: zo rpc <action> [--input <json> | --input-file <path|->] [--version <integer>]\n  --query <json>            Declared list-query options; one page per call\n  --idempotency-key <key>   Envelope key where the action supports it\n  --preview                Print the request without invoking\n  --envelope               Print the complete success envelope\n  --json                   Print exact result JSON\n  --profile <name> --workspace <id>\nThe live catalog supplies the default version. RPC preserves supplied inputs. Invocations are never retried.\n",
     completion: "Usage: zo completion bash|zsh|fish\nPrint completion from installed metadata without credentials or network requests.\n",
 };
+function identity(session, workspace) {
+    const { type, id } = workspace.subject;
+    if (type === "user" &&
+        session.approving_subject?.type === "user" &&
+        session.approving_subject.id === id)
+        return "as you";
+    if (type === "service_account")
+        return `as service account ${safeText(id)}`;
+    return `as ${type} ${safeText(id)}`;
+}
 async function showHelp(args, stdout) {
     if (!args.length) {
         stdout.write(help);
@@ -121,19 +131,17 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
             const login = await auth.login({
                 noBrowser: parsed.flags.has("no-browser"),
                 signal,
-                announce: (url) => {
-                    const message = `Open this URL to sign in:\n${url}\n`;
-                    const dim = stderr.isTTY &&
-                        !options.json &&
-                        env.NO_COLOR === undefined &&
-                        env.TERM !== "dumb";
-                    stderr.write(dim ? `\u001b[2m${message}\u001b[22m` : message);
-                },
+                announce: ({ url, userCode, browser }) => stderr.write(`${browser
+                    ? "Opening your browser to sign in. If it doesn't open, visit:"
+                    : "To sign in, visit this URL on any device:"}\n\n  ${url}\n\nCode: ${userCode}. Approve only if your browser shows the same code.\nWaiting for approval… (Ctrl-C to cancel)\n`),
             });
-            stderr.write(`Sign-in saved for profile ${profile.name}.\n`);
+            stderr.write(`\nApproved in the browser. Sign-in saved for profile ${profile.name}.\n`);
             if (login.cleanupPending)
                 stderr.write("A previous sign-in could not be revoked. Cleanup remains saved for the next login; the current sign-in is active. You can revoke the previous sign-in in Authorized apps.\n");
             const session = await auth.session();
+            // Always list the approved workspaces, so a sign-in someone else
+            // approved shows up as workspaces or identities you don't recognize.
+            session.workspaces.forEach((workspace, index) => stderr.write(`${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id}), ${identity(session, workspace)}\n`));
             const desired = options.workspace ?? env.ZO_WORKSPACE_ID ?? profile.workspaceId;
             let chosen;
             if (options.workspace !== undefined)
@@ -152,7 +160,6 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
                 process.stdin.isTTY &&
                 stderr.isTTY &&
                 session.workspaces.length > 0) {
-                session.workspaces.forEach((workspace, index) => stderr.write(`${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id})\n`));
                 const input = createInterface({
                     input: process.stdin,
                     output: process.stderr,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zocomputer/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Public Zo command line client",
   "bin": {
@@ -14,7 +14,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.13.0"
   },
   "dependencies": {
-    "@zocomputer/system-api": "0.1.1"
+    "@zocomputer/system-api": "0.1.2"
   },
   "publishConfig": {
     "access": "public",