@zocomputer/cli 0.4.0 → 0.4.1

package/dist/generated/commands.js

@@ -1,6 +1,6 @@
 // Generated by scripts/generate-commands.mjs. Do not edit.
 export const commandManifest = {
-    schemaDigest: "sha256:f3723f93d9d519ebe2517e16cb3db50c99b38e60b9705187006ada3eaeb4e391",
+    schemaDigest: "sha256:5efcff731683bd222f815032f63155a41134ba7ed47b8b63caa7736a2e5950a3",
     commands: [
         {
             action: "zo.activity.list",
@@ -10,7 +10,7 @@ export const commandManifest = {
                     version: 1,
                     description: "List who did what in the workspace, newest first: task, connection, event, membership and other changes, each with its principal, subject, outcome and a one-line summary. You see a row when you did it, when its subject is visible to the workspace, or when you own its protected subject.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"ActivityListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["occurred_at.desc"],"default":"occurred_at.desc"},"filter":{"additionalProperties":false,"properties":{"occurred_after":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only rows after this time.","title":"Occurred After"},"occurred_before":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only rows before this time.","title":"Occurred Before"},"principal":{"anyOf":[{"$ref":"#/$defs/EntityFilter"},{"type":"null"}],"default":null,"description":"Only what this principal did."},"principal_type":{"anyOf":[{"items":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","type":"string"},"maxItems":8,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only rows done by any of these principal types, such as user, agent, function, workflow, service_account or workspace.","title":"Principal Type"},"subject":{"anyOf":[{"$ref":"#/$defs/EntityFilter"},{"type":"null"}],"default":null,"description":"Only what was done to this resource."},"action":{"anyOf":[{"items":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","type":"string"},"maxItems":50,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only rows with any of these actions.","title":"Action"},"outcome":{"anyOf":[{"items":{"enum":["succeeded","failed","cancelled","unknown"],"type":"string"},"maxItems":4,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only rows with any of these outcomes.","title":"Outcome"},"search":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only rows whose summary or principal\'s current name contains this text, ignoring case. Leading and trailing spaces are ignored.","title":"Search"}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"EntityFilter":{"additionalProperties":false,"properties":{"type":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"EntityFilter","type":"object"}}}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["occurred_at.desc"],"default":"occurred_at.desc"},"filter":{"additionalProperties":false,"properties":{"occurred_after":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only rows after this time. A run or turn row\'s time is when it ended.","title":"Occurred After"},"occurred_before":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only rows before this time. A run or turn row\'s time is when it ended.","title":"Occurred Before"},"details":{"anyOf":[{"$ref":"#/$defs/ActivityDetailsFilter"},{"type":"null"}],"default":null,"description":"Match any listed value for each details key; keys combine with AND. Empty is a no-op."},"principal":{"anyOf":[{"$ref":"#/$defs/EntityFilter"},{"type":"null"}],"default":null,"description":"Only what this principal did."},"principal_type":{"anyOf":[{"items":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","type":"string"},"maxItems":8,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only rows done by any of these principal types, such as user, agent, function, workflow, service_account or workspace.","title":"Principal Type"},"subject":{"anyOf":[{"$ref":"#/$defs/EntityFilter"},{"type":"null"}],"default":null,"description":"Only what was done to this resource."},"action":{"anyOf":[{"items":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","type":"string"},"maxItems":50,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only rows with any of these actions.","title":"Action"},"outcome":{"anyOf":[{"items":{"enum":["succeeded","failed","cancelled","unknown"],"type":"string"},"maxItems":4,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only rows with any of these outcomes.","title":"Outcome"},"search":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only rows whose summary or principal\'s current name contains this text, ignoring case. Leading and trailing spaces are ignored.","title":"Search"}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"ActivityDetailsFilter":{"additionalProperties":false,"properties":{"turn_outcome":{"anyOf":[{"items":{"enum":["completed","failed","cancelled","interrupted"],"type":"string"},"maxItems":4,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"system_agent_turn_ended rows carry the runner\'s turn_outcome.","title":"Turn Outcome"},"reason":{"anyOf":[{"items":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"system_agent_turn_ended rows carry reason when the turn has an error reason.","title":"Reason"},"error_code":{"anyOf":[{"items":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"function_run_ended and workflow_run_ended carry error_code on errors. managed_machine_create_failed, managed_machine_resume_failed, machine_image_import_failed and database_create_failed carry error_code, including \\"none\\".","title":"Error Code"},"trigger":{"anyOf":[{"items":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"system_agent_turn_ended rows carry message or event; scheduled_runs_summarized rows carry schedule or event.","title":"Trigger"}},"title":"ActivityDetailsFilter","type":"object","required":[]},"EntityFilter":{"additionalProperties":false,"properties":{"type":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"EntityFilter","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -131,7 +131,7 @@ export const commandManifest = {
             versions: [
                 {
                     version: 1,
-                    description: "Read a session's history: its inputs, the Agent's responses and tool results, newest first, as ACP updates.",
+                    description: "Read a session's history: its inputs, the Agent's responses and tool results, newest first, as ACP updates. The page limit counts context rows, so a page can contain more items than its limit; a turn_ended item follows each finished turn's last item.",
                     inputJson: '{"additionalProperties":false,"properties":{"session_id":{"maxLength":200,"minLength":1,"title":"Session Id","type":"string"}},"required":["session_id"],"title":"AgentSessionHistoryInput","type":"object"}',
                     queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 100; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."}},"required":[]}',
                     resultKind: "inline",
@@ -146,7 +146,7 @@ export const commandManifest = {
                     version: 1,
                     description: "List an Agent's sessions that the caller can read.",
                     inputJson: '{"additionalProperties":false,"properties":{"agent_id":{"maxLength":200,"minLength":1,"title":"Agent Id","type":"string"}},"required":["agent_id"],"title":"AgentSessionListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc","created_at.desc","created_at.asc","display_name.asc","last_activity_at.desc"],"default":"id.asc"}},"required":[]}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc","created_at.desc","created_at.asc","display_name.asc","last_activity_at.desc"],"default":"id.asc"},"filter":{"additionalProperties":false,"properties":{"last_turn_ended_after":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions whose last turn ended after this time, exclusively.","title":"Last Turn Ended After"},"last_turn_ended_before":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions whose last turn ended before this time, exclusively.","title":"Last Turn Ended Before"},"last_turn_outcome":{"anyOf":[{"items":{"enum":["completed","cancelled","interrupted","failed"],"type":"string"},"maxItems":4,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only sessions whose last turn has any of these outcomes.","title":"Last Turn Outcome"}},"type":"object","required":[],"default":{}}},"required":[]}',
                     resultKind: "inline",
                 },
             ],
@@ -159,7 +159,7 @@ export const commandManifest = {
                     version: 1,
                     description: "List the sessions in a workspace that the caller can read, across Agents.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"AgentSessionWorkspaceListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc","created_at.desc","created_at.asc","display_name.asc","last_activity_at.desc"],"default":"id.asc"},"filter":{"additionalProperties":false,"properties":{"agent_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only this Agent\'s sessions.","title":"Agent Id"}},"type":"object","required":[],"default":{}}},"required":[]}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc","created_at.desc","created_at.asc","display_name.asc","last_activity_at.desc"],"default":"id.asc"},"filter":{"additionalProperties":false,"properties":{"last_turn_ended_after":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions whose last turn ended after this time, exclusively.","title":"Last Turn Ended After"},"last_turn_ended_before":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions whose last turn ended before this time, exclusively.","title":"Last Turn Ended Before"},"last_turn_outcome":{"anyOf":[{"items":{"enum":["completed","cancelled","interrupted","failed"],"type":"string"},"maxItems":4,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only sessions whose last turn has any of these outcomes.","title":"Last Turn Outcome"},"agent_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only this Agent\'s sessions.","title":"Agent Id"}},"type":"object","required":[],"default":{}}},"required":[]}',
                     resultKind: "inline",
                 },
             ],
@@ -671,7 +671,7 @@ export const commandManifest = {
                     version: 1,
                     description: "List functions accessible to the caller in a workspace.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"FunctionListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."}},"required":[]}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"connection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Connection Id"}},"type":"object","required":[],"default":{}}},"required":[]}',
                     resultKind: "inline",
                 },
             ],
@@ -684,7 +684,7 @@ export const commandManifest = {
                     version: 1,
                     description: "List the function's runs, newest first.",
                     inputJson: '{"additionalProperties":false,"properties":{"function_id":{"title":"Function Id","type":"string"}},"required":["function_id"],"title":"FunctionListRunsInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."}},"required":[]}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["created_at.desc","created_at.asc"],"default":"created_at.desc"},"filter":{"additionalProperties":false,"properties":{"created_after":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs created after this time.","title":"Created After"},"created_before":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs created before this time.","title":"Created Before"},"state":{"anyOf":[{"items":{"$ref":"#/$defs/RunState"},"maxItems":8,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only runs in any of these states.","title":"State"},"error_code":{"anyOf":[{"items":{"pattern":"^[a-z][a-z0-9_]{0,63}$","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only runs with any of these error codes.","title":"Error Code"},"deployment_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs of this deployment.","title":"Deployment Id"},"entry_kind":{"anyOf":[{"items":{"enum":["direct","connection","http"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only runs with any of these entry kinds.","title":"Entry Kind"},"trigger":{"anyOf":[{"items":{"enum":["direct","http","event","workflow_step","run","agent"],"type":"string"},"maxItems":6,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only runs with any of these trigger kinds.","title":"Trigger"},"subscription_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs delivered by this subscription.","title":"Subscription Id"},"agent_session_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs started by this Agent session.","title":"Agent Session Id"}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"RunState":{"enum":["queued","starting","running","succeeded","failed","cancel_requested","cancelled","unknown"],"type":"string"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -781,7 +781,7 @@ export const commandManifest = {
                     version: 1,
                     description: "List the managed machines the caller can see in a workspace.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"MachineListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc","created_at.desc","created_at.asc","display_name.asc"],"default":"id.asc"}},"required":[]}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc","created_at.desc","created_at.asc","display_name.asc"],"default":"id.asc"},"filter":{"additionalProperties":false,"properties":{"state":{"anyOf":[{"items":{"$ref":"#/$defs/ObservedState"},"maxItems":8,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only machines in any of these states.","title":"State"}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"ObservedState":{"enum":["creating","running","stopping","stopped","resuming","destroying","destroyed","failed"],"type":"string"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -968,6 +968,18 @@ export const commandManifest = {
                 },
             ],
         },
+        {
+            action: "zo.model.generate_text",
+            path: ["model", "generate-text"],
+            versions: [
+                {
+                    version: 1,
+                    description: "Generate text with a model from a prompt or a conversation, or structured data when output is set: an object or a list matching a JSON Schema, one choice from a set, or any JSON. A user message can hold images and text files. One call, with no tools and no memory of earlier calls. Each call is charged to the workspace's credit for the tokens the provider reports and needs V2 billing.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"model":{"description":"A model ID from zo.model.list, such as anthropic/claude-sonnet-5-5.","maxLength":200,"minLength":1,"title":"Model","type":"string"},"prompt":{"anyOf":[{"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"A single user message. Set this or messages.","title":"Prompt"},"messages":{"anyOf":[{"items":{"discriminator":{"mapping":{"assistant":"#/$defs/AssistantMessage","user":"#/$defs/UserMessage"},"propertyName":"role"},"oneOf":[{"$ref":"#/$defs/UserMessage"},{"$ref":"#/$defs/AssistantMessage"}]},"maxItems":500,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"A conversation that ends with a user message. Set this or prompt.","title":"Messages"},"instructions":{"anyOf":[{"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"System instructions.","title":"Instructions"},"output":{"anyOf":[{"discriminator":{"mapping":{"array":"#/$defs/ArrayOutput","choice":"#/$defs/ChoiceOutput","json":"#/$defs/JsonOutput","object":"#/$defs/ObjectOutput"},"propertyName":"type"},"oneOf":[{"$ref":"#/$defs/ObjectOutput"},{"$ref":"#/$defs/ArrayOutput"},{"$ref":"#/$defs/ChoiceOutput"},{"$ref":"#/$defs/JsonOutput"}]},{"type":"null"}],"default":null,"description":"The structured output wanted. Omit for plain text.","title":"Output"},"reasoning":{"anyOf":[{"maxLength":32,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Reasoning effort, one of the model\'s reasoning_levels. Omit for its default.","title":"Reasoning"},"include":{"anyOf":[{"$ref":"#/$defs/Include"},{"type":"null"}],"default":null},"provider_options":{"anyOf":[{"$ref":"#/$defs/ProviderOptions"},{"type":"null"}],"default":null,"description":"Settings for the provider the model runs on, keyed by provider, in snake case. Only the routed provider\'s options are used; an option it doesn\'t take is refused before the call."},"max_output_tokens":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"The most tokens to generate.","title":"Max Output Tokens"},"temperature":{"anyOf":[{"maximum":2,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Temperature"},"top_p":{"anyOf":[{"maximum":1,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Top P"},"top_k":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Top K"},"presence_penalty":{"anyOf":[{"maximum":2,"minimum":-2,"type":"number"},{"type":"null"}],"default":null,"title":"Presence Penalty"},"frequency_penalty":{"anyOf":[{"maximum":2,"minimum":-2,"type":"number"},{"type":"null"}],"default":null,"title":"Frequency Penalty"},"stop_sequences":{"anyOf":[{"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":16,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"title":"Stop Sequences"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Seed"}},"required":["workspace_id","model"],"title":"GenerateTextInput","type":"object","$defs":{"ArrayOutput":{"additionalProperties":false,"properties":{"type":{"const":"array","title":"Type","type":"string"},"element_schema":{"additionalProperties":{"x-zo-json-value":true},"description":"A JSON Schema every element of the result matches.","title":"Element Schema","type":"object"},"name":{"anyOf":[{"maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"anyOf":[{"maxLength":1024,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Description"}},"required":["type","element_schema"],"title":"ArrayOutput","type":"object"},"AssistantMessage":{"additionalProperties":false,"properties":{"role":{"const":"assistant","title":"Role","type":"string"},"content":{"items":{"$ref":"#/$defs/TextPart"},"maxItems":100,"minItems":1,"title":"Content","type":"array"}},"required":["role","content"],"title":"AssistantMessage","type":"object"},"ChoiceOutput":{"additionalProperties":false,"properties":{"type":{"const":"choice","title":"Type","type":"string"},"options":{"description":"The result is exactly one of these.","items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":100,"minItems":2,"title":"Options","type":"array"}},"required":["type","options"],"title":"ChoiceOutput","type":"object"},"FilePart":{"additionalProperties":false,"description":"An image (PNG, JPEG, GIF or WebP, up to 20 MiB) or a text file (up to 1 MiB), as a Knowledge file by ID or\\ninline as base64. A call may name at most 20 distinct Knowledge files. Other types, PDFs and video included, are\\nrefused. Which types a model takes is its `input_media` in `zo.model.list`.","properties":{"type":{"const":"file","title":"Type","type":"string"},"file_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"A Knowledge file the caller can read. Set this or data, not both.","title":"File Id"},"data":{"anyOf":[{"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"The file\'s bytes as base64.","title":"Data"},"media_type":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Required with data, such as image/png or text/plain. Ignored for a Knowledge file, which always uses its stored type.","title":"Media Type"},"filename":{"anyOf":[{"maxLength":255,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Filename"}},"required":["type"],"title":"FilePart","type":"object"},"Include":{"additionalProperties":false,"properties":{"reasoning":{"default":false,"description":"Return the model\'s reasoning text when it provides one.","title":"Reasoning","type":"boolean"}},"title":"Include","type":"object","required":[]},"JsonOutput":{"additionalProperties":false,"properties":{"type":{"const":"json","title":"Type","type":"string"}},"required":["type"],"title":"JsonOutput","type":"object"},"ObjectOutput":{"additionalProperties":false,"properties":{"type":{"const":"object","title":"Type","type":"string"},"schema":{"additionalProperties":{"x-zo-json-value":true},"description":"A JSON Schema whose root type is object. The result matches it.","title":"Schema","type":"object"},"name":{"anyOf":[{"maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"anyOf":[{"maxLength":1024,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Description"}},"required":["type","schema"],"title":"ObjectOutput","type":"object"},"ProviderOptions":{"additionalProperties":false,"description":"Settings for one provider, keyed by provider, passed through to that\\nprovider\'s request as the Vercel AI SDK\'s providerOptions are. Shared by\\nevery model action that takes them.","properties":{"anthropic":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For Anthropic models: thinking, send_reasoning.","title":"Anthropic"},"openai":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For OpenAI models: reasoning_summary, text_verbosity, service_tier, user, logit_bias.","title":"Openai"},"google":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For Google models: thinking_config, safety_settings.","title":"Google"},"xai":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For xAI models. None are accepted yet.","title":"Xai"},"deepseek":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For DeepSeek models. None are accepted yet.","title":"Deepseek"},"moonshot":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For Moonshot models. None are accepted yet.","title":"Moonshot"},"zai":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For Z.ai models. None are accepted yet.","title":"Zai"},"voyage":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For Voyage models: truncation.","title":"Voyage"},"bytedance":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For ByteDance models. None are accepted yet.","title":"Bytedance"},"recraft":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For Recraft models. None are accepted yet.","title":"Recraft"},"assemblyai":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"For AssemblyAI transcription: punctuate, format_text, disfluencies, filter_profanity, word_boost, boost_param.","title":"Assemblyai"}},"title":"ProviderOptions","type":"object","required":[]},"TextPart":{"additionalProperties":false,"properties":{"type":{"const":"text","title":"Type","type":"string"},"text":{"title":"Text","type":"string"}},"required":["type","text"],"title":"TextPart","type":"object"},"UserMessage":{"additionalProperties":false,"properties":{"role":{"const":"user","title":"Role","type":"string"},"content":{"description":"Text and file parts, in order.","items":{"discriminator":{"mapping":{"file":"#/$defs/FilePart","text":"#/$defs/TextPart"},"propertyName":"type"},"oneOf":[{"$ref":"#/$defs/TextPart"},{"$ref":"#/$defs/FilePart"}]},"maxItems":100,"minItems":1,"title":"Content","type":"array"}},"required":["role","content"],"title":"UserMessage","type":"object"}}}',
+                    resultKind: "inline",
+                },
+            ],
+        },
         {
             action: "zo.model.list",
             path: ["model", "list"],
@@ -988,7 +1000,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Register an OAuth app a workspace's connections authorize through.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"provider":{"maxLength":200,"minLength":1,"title":"Provider","type":"string"},"client_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Client Id"},"manager_ref":{"additionalProperties":{"x-zo-json-value":true},"default":{},"title":"Manager Ref","type":"object"},"visibility":{"enum":["private","public"],"title":"Visibility","type":"string"},"requested_scopes":{"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":100,"title":"Requested Scopes","type":"array"},"connection_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Connection Id"},"client_secret":{"anyOf":[{"maxLength":4096,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"The app\'s client secret. Zo seals it in the workspace vault and stores only its `manager_ref.client_secret_id`; it is never returned.","title":"Client Secret"}},"required":["workspace_id","provider","visibility","requested_scopes"],"title":"OAuthAppCreateWithSecretInput","type":"object"}',
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"provider":{"maxLength":200,"minLength":1,"title":"Provider","type":"string"},"client_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Client Id"},"manager_ref":{"additionalProperties":{"x-zo-json-value":true},"default":{},"title":"Manager Ref","type":"object"},"visibility":{"enum":["private","public"],"title":"Visibility","type":"string"},"requested_scopes":{"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":100,"title":"Requested Scopes","type":"array"},"connection_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Connection Id"},"client_secret":{"anyOf":[{"maxLength":4096,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"The app\'s client secret. Zo seals it in the workspace vault and never returns it. A private app needs one. After an update, every connection on the app uses the new secret from its next refresh.","title":"Client Secret"}},"required":["workspace_id","provider","visibility","requested_scopes"],"title":"OAuthAppCreateWithSecretInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -1037,7 +1049,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Replace an OAuth app's client, secret and visibility.",
-                    inputJson: '{"additionalProperties":false,"properties":{"owner":{"$ref":"#/$defs/OAuthAppOwner"},"oauth_app_id":{"maxLength":200,"minLength":1,"title":"Oauth App Id","type":"string"},"expected_state":{"pattern":"^[0-9a-f]{64}$","title":"Expected State","type":"string"},"client_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Client Id"},"manager_ref":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"Omitted: keep the app\'s current `manager_ref` (with a new `client_secret`, only its secret id changes).","title":"Manager Ref"},"visibility":{"enum":["private","public"],"title":"Visibility","type":"string"},"client_secret":{"anyOf":[{"maxLength":4096,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"The app\'s client secret. Zo seals it in the workspace vault and stores only its `manager_ref.client_secret_id`; it is never returned.","title":"Client Secret"}},"required":["owner","oauth_app_id","expected_state","visibility"],"title":"OAuthAppUpdateWithSecretInput","type":"object","$defs":{"OAuthAppOwner":{"additionalProperties":false,"properties":{"type":{"description":"The workspace, or the connection the app is bound to.","enum":["workspace","connection"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"OAuthAppOwner","type":"object"}}}',
+                    inputJson: '{"additionalProperties":false,"properties":{"owner":{"$ref":"#/$defs/OAuthAppOwner"},"oauth_app_id":{"maxLength":200,"minLength":1,"title":"Oauth App Id","type":"string"},"expected_state":{"pattern":"^[0-9a-f]{64}$","title":"Expected State","type":"string"},"client_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Client Id"},"manager_ref":{"anyOf":[{"additionalProperties":{"x-zo-json-value":true},"type":"object"},{"type":"null"}],"default":null,"description":"Omitted: keep the app\'s current `manager_ref`. It can\'t contain `client_secret`, `client_secret_id` or `client_secret_env`.","title":"Manager Ref"},"visibility":{"enum":["private","public"],"title":"Visibility","type":"string"},"client_secret":{"anyOf":[{"maxLength":4096,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"The app\'s client secret. Zo seals it in the workspace vault and never returns it. A private app needs one. After an update, every connection on the app uses the new secret from its next refresh.","title":"Client Secret"}},"required":["owner","oauth_app_id","expected_state","visibility"],"title":"OAuthAppUpdateWithSecretInput","type":"object","$defs":{"OAuthAppOwner":{"additionalProperties":false,"properties":{"type":{"description":"The workspace, or the connection the app is bound to.","enum":["workspace","connection"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"OAuthAppOwner","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1220,14 +1232,14 @@ export const commandManifest = {
                     version: 1,
                     description: "List subscriptions accessible to the caller in a workspace, optionally for one event definition.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"SubscriptionListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":100,"description":"Rows per page, at most 100; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions to this event definition.","title":"Event Id"},"handler":{"anyOf":[{"$ref":"#/$defs/SubscriptionHandlerRef"},{"type":"null"}],"default":null,"description":"Only subscriptions whose handler is this resource: its handler_resource_type and handler_resource_id, such as an Agent."}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"SubscriptionHandlerRef":{"additionalProperties":false,"properties":{"type":{"enum":["function","workflow","agent"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"SubscriptionHandlerRef","type":"object"}}}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":100,"description":"Rows per page, at most 100; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions to this event definition.","title":"Event Id"},"schedule_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions that run for this schedule.","title":"Schedule Id"},"handler":{"anyOf":[{"$ref":"#/$defs/SubscriptionHandlerRef"},{"type":"null"}],"default":null,"description":"Only subscriptions whose handler is this resource: its handler_resource_type and handler_resource_id, such as an Agent."}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"SubscriptionHandlerRef":{"additionalProperties":false,"properties":{"type":{"enum":["function","workflow","agent"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"SubscriptionHandlerRef","type":"object"}}}',
                     resultKind: "inline",
                 },
                 {
                     version: 2,
                     description: "List subscriptions accessible to the caller in a workspace, optionally for one event definition.",
                     inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"SubscriptionListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":100,"description":"Rows per page, at most 100; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions to this event definition.","title":"Event Id"},"handler":{"anyOf":[{"$ref":"#/$defs/SubscriptionHandlerRef"},{"type":"null"}],"default":null,"description":"Only subscriptions whose handler is this resource: its handler_resource_type and handler_resource_id, such as an Agent."}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"SubscriptionHandlerRef":{"additionalProperties":false,"properties":{"type":{"enum":["function","workflow","agent"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"SubscriptionHandlerRef","type":"object"}}}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":100,"description":"Rows per page, at most 100; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"filter":{"additionalProperties":false,"properties":{"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions to this event definition.","title":"Event Id"},"schedule_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions that run for this schedule.","title":"Schedule Id"},"handler":{"anyOf":[{"$ref":"#/$defs/SubscriptionHandlerRef"},{"type":"null"}],"default":null,"description":"Only subscriptions whose handler is this resource: its handler_resource_type and handler_resource_id, such as an Agent."}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"SubscriptionHandlerRef":{"additionalProperties":false,"properties":{"type":{"enum":["function","workflow","agent"],"title":"Type","type":"string"},"id":{"maxLength":200,"minLength":1,"title":"Id","type":"string"}},"required":["type","id"],"title":"SubscriptionHandlerRef","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1745,7 +1757,7 @@ export const commandManifest = {
                     version: 1,
                     description: "List the workflow's runs, newest first.",
                     inputJson: '{"additionalProperties":false,"properties":{"workflow_id":{"title":"Workflow Id","type":"string"}},"required":["workflow_id"],"title":"WorkflowListRunsInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."}},"required":[]}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["created_at.desc","created_at.asc"],"default":"created_at.desc"},"filter":{"additionalProperties":false,"properties":{"created_after":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs created after this time.","title":"Created After"},"created_before":{"anyOf":[{"description":"An ISO 8601 timestamp with a time zone.","maxLength":40,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs created before this time.","title":"Created Before"},"state":{"anyOf":[{"items":{"$ref":"#/$defs/WorkflowRunState"},"maxItems":7,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only runs in any of these states.","title":"State"},"error_code":{"anyOf":[{"items":{"$ref":"#/$defs/WorkflowRunError"},"maxItems":5,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only runs with any of these error codes.","title":"Error Code"},"revision_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs of this revision.","title":"Revision Id"},"trigger":{"anyOf":[{"items":{"enum":["direct","event","run","agent"],"type":"string"},"maxItems":4,"minItems":1,"type":"array"},{"type":"null"}],"default":null,"description":"Only runs with any of these trigger kinds.","title":"Trigger"},"subscription_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs delivered by this subscription.","title":"Subscription Id"},"agent_session_id":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs started by this Agent session.","title":"Agent Session Id"}},"type":"object","required":[],"default":{}}},"required":[],"$defs":{"WorkflowRunError":{"enum":["step_failed","deadline_exceeded","engine_error","engine_rejected","engine_unavailable"],"type":"string"},"WorkflowRunState":{"enum":["queued","running","cancel_requested","succeeded","failed","cancelled","unknown"],"type":"string"}}}',
                     resultKind: "inline",
                 },
             ],

package/dist/help.d.ts

@@ -0,0 +1,7 @@
+import type { Style } from "./style.ts";
+/**
+ * Root help: grouped, aligned, and short enough for one 80-column screen.
+ * People and agents read the same text; `style` only adds bold and dim on a
+ * terminal. `resources` are the first words of the built-in commands.
+ */
+export declare function rootHelp(style: Style, resources: readonly string[]): string;

package/dist/help.js

@@ -0,0 +1,43 @@
+const WIDTH = 80;
+function wrapped(words, indent) {
+    const lines = [];
+    let line = indent;
+    words.forEach((word, index) => {
+        const piece = index === words.length - 1 ? word : `${word},`;
+        if (line !== indent && line.length + 1 + piece.length > WIDTH) {
+            lines.push(line);
+            line = indent;
+        }
+        line += line === indent ? piece : ` ${piece}`;
+    });
+    return line === indent ? lines : [...lines, line];
+}
+/**
+ * Root help: grouped, aligned, and short enough for one 80-column screen.
+ * People and agents read the same text; `style` only adds bold and dim on a
+ * terminal. `resources` are the first words of the built-in commands.
+ */
+export function rootHelp(style, resources) {
+    const row = (command, description) => `  ${command.padEnd(23)}${description}`;
+    return `${[
+        style.bold("Zo public command line client"),
+        `${style.bold("Usage:")} zo <command> [--profile <name>] [--workspace <id>] [--json]`,
+        "",
+        style.bold("Set up"),
+        row("login, logout", "Sign in through your browser, or sign out"),
+        row("auth status|token", "Show your identity, or print an access token"),
+        row("context list|use|show", "List, choose or show the selected workspace"),
+        row("update, --version", "Upgrade the CLI, or print its version"),
+        row("completion <shell>", "Print bash, zsh or fish completion"),
+        "",
+        style.bold("Call the System API"),
+        row("<resource> <action>", "Run a built-in command for one of these:"),
+        ...wrapped(resources, "    "),
+        row("actions list|describe", "Discover callable actions and their schemas"),
+        row("rpc <action>", "Call any action with JSON input"),
+        "",
+        style.bold("Examples"),
+        "  zo machine list --limit 20",
+        `  zo task create --help  ${style.dim("Show any command's options")}`,
+    ].join("\n")}\n`;
+}

package/dist/output.d.ts

@@ -1,17 +1,15 @@
-import { type JsonObject } from "@zocomputer/system-api/json";
+import { type JsonObject, type JsonValue } from "@zocomputer/system-api/json";
 import type { RpcResult } from "./rpc.ts";
+import { type Terminal } from "./style.ts";
 export interface OutputOptions {
     json?: boolean;
     envelope?: boolean;
-    stdout?: {
-        write(text: string): unknown;
-        isTTY?: boolean;
-    };
-    stderr?: {
-        write(text: string): unknown;
-        isTTY?: boolean;
-    };
+    stdout?: Terminal;
+    stderr?: Terminal;
+    /** Read for NO_COLOR. */
+    env?: NodeJS.ProcessEnv;
 }
+export declare function toJson(value: unknown): JsonValue;
 export declare function writeJsonText(text: string, options?: OutputOptions): void;
 export declare function writeJson(value: unknown, options?: OutputOptions): void;
 export declare function writeRpcResult(result: RpcResult, options?: OutputOptions): void;

package/dist/output.js

@@ -1,7 +1,8 @@
 import { SystemAPIError } from "@zocomputer/system-api";
 import { canonicalNumberFromToken, dumpsJson, JsonNumber, loadsJson, } from "@zocomputer/system-api/json";
 import { CliError, record, safeText } from "./errors.js";
-function toJson(value) {
+import { blankLine, styleFor } from "./style.js";
+export function toJson(value) {
     if (value === null ||
         typeof value === "string" ||
         typeof value === "boolean" ||
@@ -206,8 +207,33 @@ export function writeError(error, options = {}) {
     }
     if (options.json)
         stderr.write(`${dumpsJson({ error: failure })}\n`);
+    else if (stderr.isTTY && status === 130) {
+        // The terminal echoed ^C onto this line, after a spinner or prompt if one
+        // was showing.
+        stderr.write(`${blankLine(stderr)}Cancelled.\n`);
+        if (failure.outcome === "unknown") {
+            if (failure.request_id !== undefined)
+                stderr.write(`Request: ${safeText(String(failure.request_id))}\n`);
+            stderr.write("The action may have run; the CLI did not replay it.\n");
+        }
+    }
     else {
-        stderr.write(`${safeText(String(failure.code))}: ${safeText(String(failure.message))}\n`);
+        if (stderr.isTTY) {
+            const style = styleFor(stderr, options.env);
+            // The CLI's own messages put the problem first, then what to do about
+            // it. Server messages stay on one line: their wording isn't ours.
+            const [problem = "", ...steps] = error instanceof CliError
+                ? String(failure.message)
+                    .trimEnd()
+                    .replace(/^(.*?[.?!])[ \t]+(?=\S)/, "$1\n")
+                    .split("\n")
+                : [String(failure.message)];
+            stderr.write(`${style.bold(style.red("Error:"))} ${safeText(problem)} ${style.dim(`(${safeText(String(failure.code))})`)}\n`);
+            for (const step of steps)
+                stderr.write(`${safeText(step)}\n`);
+        }
+        else
+            stderr.write(`${safeText(String(failure.code))}: ${safeText(String(failure.message))}\n`);
         if (failure.request_id !== undefined)
             stderr.write(`Request: ${safeText(String(failure.request_id))}\n`);
         if (failure.details !== undefined)

package/dist/presentation.d.ts

@@ -1,9 +1,13 @@
 import { type OutputOptions } from "./output.ts";
 import type { RpcResult } from "./rpc.ts";
+import { type Style } from "./style.ts";
 export interface PresentationOptions extends OutputOptions {
     workspaceId?: string;
     identity?: string;
     columns?: number;
 }
-export declare function tableResult(action: string, text: string, columns?: number): string | undefined;
+/** A table for a list action's result, or undefined when it should stay JSON. */
+export declare function tableResult(action: string, text: string, columns?: number, style?: Style): string | undefined;
+/** A complete key/value view of an object result, or undefined when it should stay JSON. */
+export declare function detailResult(text: string, style?: Style): string | undefined;
 export declare function writeBuiltinResult(action: string, result: RpcResult, options?: PresentationOptions): void;

package/dist/presentation.js

@@ -1,7 +1,11 @@
-import { dumpsJson, loadsJson, JsonNumber, } from "@zocomputer/system-api/json";
+import { loadsJson } from "@zocomputer/system-api/json";
+import { listSortFields } from "./commands.js";
 import { safeText } from "./errors.js";
 import { schemaObject } from "./flags.js";
 import { writeRpcResult } from "./output.js";
+import { cell, completeResultHint, detailLines, fitsCell, isScalar, jsonHint, tableLines, } from "./render.js";
+import { styleFor, terminalWidth } from "./style.js";
+/** Columns picked by hand for the lists people read most. */
 const tables = {
     "zo.machine.list": {
         field: "machines",
@@ -24,58 +28,98 @@ const tables = {
         columns: ["occurred_at", "action", "outcome", "summary"],
     },
 };
-function cell(value) {
-    if (value === undefined || value === null)
-        return "-";
-    return safeText(typeof value === "string"
-        ? value
-        : value instanceof JsonNumber
-            ? value.text
-            : dumpsJson(value));
-}
-function clipped(text, width) {
-    const characters = Array.from(text);
-    return characters.length <= width
-        ? text.padEnd(width)
-        : `${characters.slice(0, width - 1).join("")}…`;
+const labelFields = [
+    "display_name",
+    "name",
+    "title",
+    "slug",
+    "path",
+    "display",
+];
+const stateFields = ["state", "status", "lifecycle", "outcome"];
+// The same for every row of a page, or bookkeeping.
+const skippedFields = new Set(["workspace_id", "type_version", "revision"]);
+const DERIVED_COLUMNS = 5;
+/**
+ * Columns for a list action with no hand-picked ones: the fields every row
+ * holds as a value one cell can show, ordered ID, name, state, the fields
+ * the action sorts by, then the rest as the rows declare them.
+ */
+function derivedProjection(result, sortFields) {
+    const arrays = Object.entries(result).filter(([, value]) => Array.isArray(value));
+    const [field, rows] = arrays[0] ?? [];
+    // With two lists on a page there is no telling which holds the rows.
+    if (arrays.length !== 1 || field === undefined || !Array.isArray(rows))
+        return undefined;
+    const shown = Object.keys(schemaObject(rows[0]) ?? {}).filter((key) => !skippedFields.has(key) &&
+        rows.every((row) => {
+            const object = schemaObject(row);
+            return object && Object.hasOwn(object, key) && fitsCell(object[key]);
+        }));
+    const ordered = [
+        "id",
+        ...labelFields,
+        ...stateFields,
+        ...sortFields,
+        ...shown.filter((key) => key !== "description"),
+        "description",
+    ];
+    const columns = [...new Set(ordered)]
+        .filter((key) => shown.includes(key))
+        .slice(0, DERIVED_COLUMNS);
+    // Rows with nothing to show in columns are better read as JSON.
+    return rows.length && !columns.length ? undefined : { field, columns };
 }
-export function tableResult(action, text, columns = 100) {
-    const projection = tables[action];
-    if (!projection)
+/** A table for a list action's result, or undefined when it should stay JSON. */
+export function tableResult(action, text, columns = 100, style = styleFor(undefined)) {
+    const picked = Object.hasOwn(tables, action) ? tables[action] : undefined;
+    const sortFields = picked ? undefined : listSortFields(action);
+    if (!picked && !sortFields)
         return undefined;
     const result = schemaObject(loadsJson(text, { maxNodes: null, maxDepth: 256 }));
-    const rows = result?.[projection.field];
-    if (!result || !Array.isArray(rows))
+    if (!result)
+        return undefined;
+    const projection = picked ?? derivedProjection(result, sortFields ?? []);
+    const rows = projection ? result[projection.field] : undefined;
+    if (!projection || !Array.isArray(rows))
         return undefined;
+    // Hand-picked columns hold plain values only: a nested one means the
+    // contract changed under them.
+    const fits = picked ? isScalar : fitsCell;
     if (rows.some((row) => {
         const object = schemaObject(row);
         return (!object ||
-            projection.columns.some((field) => !Object.hasOwn(object, field) ||
-                (object[field] !== null &&
-                    typeof object[field] === "object" &&
-                    !(object[field] instanceof JsonNumber))));
+            projection.columns.some((field) => !Object.hasOwn(object, field) || !fits(object[field])));
     }))
         return undefined;
-    const cells = rows.map((row) => projection.columns.map((field) => cell(schemaObject(row)?.[field])));
-    const width = Math.max(20, Math.floor(columns));
-    const visible = projection.columns.slice(0, Math.max(1, Math.floor((width + 2) / 12)));
-    const budget = Math.floor((width - (visible.length - 1) * 2) / visible.length);
-    const widths = visible.map((column, index) => Math.min(budget, Math.max(column.length, ...cells.map((row) => Array.from(row[index] ?? "").length))));
-    const format = (row) => visible
-        .map((_, index) => clipped(row[index] ?? "", widths[index] ?? budget))
-        .join("  ")
-        .trimEnd();
-    const lines = [
-        format(visible.map((column) => column.toUpperCase())),
-        ...cells.map(format),
-    ];
+    const lines = projection.columns.length
+        ? tableLines(projection.columns.map((column) => safeText(column).toUpperCase()), rows.map((row) => projection.columns.map((field) => cell(schemaObject(row)?.[field]))), columns, style)
+        : [];
     if (!rows.length)
         lines.push("No results.");
+    if (!picked) {
+        // What the page says beside its rows, such as totals.
+        const page = Object.fromEntries(Object.entries(result).filter(([key, value]) => key !== projection.field &&
+            key !== "next_cursor" &&
+            !skippedFields.has(key) &&
+            value !== null));
+        const beside = detailLines(page, style) ?? [];
+        if (beside.length)
+            lines.push("", ...beside);
+    }
     if (result.next_cursor !== undefined && result.next_cursor !== null)
         lines.push(`Next cursor: ${cell(result.next_cursor)}`);
-    lines.push("Use --json for the complete result.");
+    lines.push(style.dim(completeResultHint));
     return `${lines.join("\n")}\n`;
 }
+/** A complete key/value view of an object result, or undefined when it should stay JSON. */
+export function detailResult(text, style = styleFor(undefined)) {
+    const result = schemaObject(loadsJson(text, { maxNodes: null, maxDepth: 256 }));
+    const lines = result && detailLines(result, style);
+    return lines?.length
+        ? `${[...lines, style.dim(jsonHint)].join("\n")}\n`
+        : undefined;
+}
 export function writeBuiltinResult(action, result, options = {}) {
     const stdout = options.stdout ?? process.stdout;
     const stderr = options.stderr ?? process.stderr;
@@ -84,10 +128,15 @@ export function writeBuiltinResult(action, result, options = {}) {
         !options.envelope &&
         result.kind === "success") {
         if (options.workspaceId)
-            stderr.write(`Workspace: ${safeText(options.workspaceId)}${options.identity ? `  Identity: ${safeText(options.identity)}` : ""}\n`);
-        const table = tableResult(action, result.response.resultJson, options.columns ?? process.stdout.columns ?? 100);
-        if (table !== undefined) {
-            stdout.write(table);
+            stderr.write(`${styleFor(stderr, options.env).dim(`Workspace: ${safeText(options.workspaceId)}${options.identity ? `  Identity: ${safeText(options.identity)}` : ""}`)}\n`);
+        const style = styleFor(stdout, options.env);
+        // A list whose rows don't fit its columns stays JSON; it does not become
+        // a key/value view of the page.
+        const view = Object.hasOwn(tables, action) || listSortFields(action)
+            ? tableResult(action, result.response.resultJson, options.columns ?? terminalWidth(stdout, 100), style)
+            : detailResult(result.response.resultJson, style);
+        if (view !== undefined) {
+            stdout.write(view);
             return;
         }
     }

package/dist/render.d.ts

@@ -0,0 +1,26 @@
+import { type JsonObject, type JsonValue } from "@zocomputer/system-api/json";
+import type { Style } from "./style.ts";
+/** Ends a table: it shows a few columns of each row. */
+export declare const completeResultHint = "Use --json for the complete result.";
+/** Ends a key/value view, which leaves nothing out. */
+export declare const jsonHint = "Use --json for JSON.";
+export declare function jsonObject(value: JsonValue | undefined): JsonObject | undefined;
+export declare function isScalar(value: JsonValue | undefined): boolean;
+/** Plain, or a small object of plain values such as `{type, id}`. */
+export declare function fitsCell(value: JsonValue | undefined): boolean;
+/** One value as escaped single-line text. */
+export declare function cell(value: JsonValue | undefined): string;
+/**
+ * Lines of an aligned table no wider than `width`: a header, then one line a
+ * row. Cells must already be escaped. A narrow terminal drops trailing columns
+ * and shortens the widest ones.
+ */
+export declare function tableLines(headers: readonly string[], rows: readonly (readonly string[])[], width: number, style: Style): string[];
+/**
+ * Lines of an aligned key/value view of one object, with nothing left out or
+ * shortened: a person may not be able to run the command again to see the
+ * rest. Nested objects, lists of objects and text with line breaks are
+ * indented under their key. Returns undefined for a shape this layout can't
+ * hold (lists of lists, mixed lists, deep nesting); the caller prints JSON.
+ */
+export declare function detailLines(value: JsonObject, style: Style, depth?: number): string[] | undefined;