@gondoai/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,118 +1,48 @@
 # Gondo CLI
 
-Give a coding agent access to [Gondo](https://www.gondo.ai) to create employees, build and test their jobs, and inspect results. The CLI calls Gondo's HTTP API and loads its current authoring guide from the service.
+Use Gondo Admin capabilities from a coding agent or terminal. Requires Node.js 22.12+, a Gondo account with Pro access, and an API key created by an account admin.
 
-Requires **Node.js 22.12 or later** and a Gondo API key. API access requires Pro, an active Pro trial, or complimentary Pro. Installing the CLI does not enable API access.
+## Start
 
-## Get started
+Save `GONDO_API_KEY=…` in a private `gondo.env` file outside source control, then run:
 
-1. In Gondo, open **Account → API keys** and create a key. This requires an account admin. The key is all your agent needs.
-2. Save the key in a local file called `gondo.env`, outside your source repository:
-
-   ```dotenv
-   GONDO_API_KEY=your-api-key
-   ```
-
-3. From any directory, read the guide:
-
-   ```bash
-   npx --yes @gondoai/cli --env-file /absolute/path/to/gondo.env guide
-   ```
-
-No Gondo app checkout is needed. To install a persistent `gondo` command instead:
-
-```bash
-npm install --global @gondoai/cli
-gondo --env-file /absolute/path/to/gondo.env guide
+```sh
+npx --yes @gondoai/cli@0.2.0 --env-file /absolute/path/gondo.env guide
 ```
 
-`--env-file` accepts dotenv syntax, including quoted values. Existing environment variables take precedence over the file. If `GONDO_API_KEY` is already set in your agent's environment, omit the flag. The CLI never loads an env file implicitly. It connects to `https://runtime.gondo.ai` and discovers the account belonging to your key automatically. For development, set `GONDO_API_URL` to another runtime; `GONDO_ACCOUNT_ID` remains an optional override for existing setups. Overrides do not change which account a key can access.
-
-Keep the key out of prompts, source control, and shared logs. Give your agent the local env-file path, not the key text. Connect required integrations using the setup commands below or in Gondo; enable Public browsing for public websites.
-
-## Give this to your agent
+The key identifies its account automatically. Optional `GONDO_API_URL` and `GONDO_ACCOUNT_ID` overrides support development. Environment variables override the explicitly selected env file. Never paste credentials into prompts or command arguments.
 
-Use a coding agent with terminal access, such as Codex or Claude Code. Replace the task and local file path:
+## Shared capabilities
 
-> Use Gondo to build an employee that **[describe the task]**. Your credentials are in **[/absolute/path/to/gondo.env]**; do not print them. Start by running `npx --yes @gondoai/cli --env-file /absolute/path/to/gondo.env guide`. Read the workflow and node guides as directed, then inspect the available integrations. Create a new employee and job, validate it, test with **[agreed inputs]**, and inspect the actual run output. Publish the new job while leaving it disabled for my review. Do not change existing jobs or send messages unless my task explicitly requires it. Report the employee and job IDs and the test results.
-
-Commands shown as `gondo …` in the served guide can all be run as `npx --yes @gondoai/cli --env-file /absolute/path/to/gondo.env …`. If an older guide mentions `pnpm gondo` or the app checkout, use this npm command instead.
-
-## Useful commands
-
-After a global install, with credentials in `gondo.env`:
-
-```bash
-gondo --env-file ./gondo.env guide --topic workflows
-gondo --env-file ./gondo.env guide --topic nodes
-gondo --env-file ./gondo.env list /integrations
-gondo --env-file ./gondo.env employees list
-gondo --env-file ./gondo.env workflows list
-gondo --help
-gondo --version
+```sh
+npx --yes @gondoai/cli@0.2.0 --env-file /absolute/path/gondo.env tools list
+npx --yes @gondoai/cli@0.2.0 --env-file /absolute/path/gondo.env tools describe gondo_upsert_workflow_node
+npx --yes @gondoai/cli@0.2.0 --env-file /absolute/path/gondo.env call gondo_upsert_workflow_node --file arguments.json
+npx --yes @gondoai/cli@0.2.0 --env-file /absolute/path/gondo.env call load_skill --file skill.json --session os_existing
+npx --yes @gondoai/cli@0.2.0 --env-file /absolute/path/gondo.env workflows get <id> --source active --format json
+npx --yes @gondoai/cli@0.2.0 --help
 ```
 
-The command name remains `workflows`; Gondo calls them jobs in the app. The guide documents authoring, execution, file upload/download, resumable workspaces, browser login handoffs, and run inspection. Human approvals are completed by a signed-in person in Gondo.
+The server supplies Admin's existing guides, tool names, descriptions and schemas. The CLI contains no separate authoring manual. `guide --topic workflows` returns the authoritative workflow bundle. Convenience commands adapt to the same operations. Workflow reads return one definition; use `--editor-state` explicitly for the complete editor state.
 
-API responses are JSON. Exit codes: **0** success, **1** failure, **2** user action required. Tests and investigation code execute real actions through your connected integrations. The CLI does not retry mutations automatically; inspect the run or execution after a timeout before trying again.
+Use the host's native web search, delegation and authorization. The catalog preserves Admin's `requireConfirmation` flag; the host applies its authorization policy before invocation, including authorization already given by the user. Required workflow human reviews and login stay in signed-in Gondo; interactive calls return action links. File tools return session artifacts; download inspection images and view them in the host before making visual claims.
 
-## Development and publishing
+Integration management requires `integrations:manage`. Creation follows Admin defaults. Change availability explicitly with `integrations enable|disable <id>`. Submit credentials using `integrations credentials <id> --file <private-file>` or stdin. Credential replacement never implicitly enables a connection. Custom API, custom-tool and browser management are available through the shared catalog.
 
-The service must support `GET /api/operator/me` before publishing this key-only CLI release. That endpoint authenticates the key and returns its account; the Pro requirements still apply.
+Responses are JSON. Exit codes: **0** success, **1** failure, **2** action required. Mutations are never automatically retried. After an uncertain write, inspect its run or execution before proceeding. Existing session, binary transfer, private webhook output and attempt download commands remain available through `--help`.
 
-This repository owns the standalone CLI. Workflow schemas, authoring guides, and authorization remain in the Gondo service. The initial client was extracted from the app's existing operator CLI; it has one runtime dependency and no build step.
+## Development and release
 
-```bash
+```sh
 npm ci
 npm test
-```
-
-Tests exercise the packed npm artifact installed in a separate temporary directory, including its executable, env-file loading, HTTP authentication, and YAML requests. No Gondo credentials or live account are required.
-
-To publish the prepared `@gondoai/cli@0.1.0` release, sign in with an npm account that can publish to the `gondoai` organisation:
-
-```bash
-npm login
-npm whoami
 npm pack --dry-run
-npm publish --access public
-```
-
-Publishing runs the tests again. Complete npm's authentication/2FA prompt when requested. Then verify the registry install from any other directory:
-
-```bash
-npx --yes @gondoai/cli@0.1.0 --version
-npx --yes @gondoai/cli@0.1.0 --env-file /absolute/path/to/gondo.env guide
 ```
 
-`0.1.0` is prepared for its first publication; it is not published by creating or pushing this repository. The npm package is `@gondoai/cli`; its installed executable is `gondo`. Future releases need a new version number. The package is public with no open-source license grant (`UNLICENSED`).
-
-## Connection setup and API-key scopes
-
-All keys have `operator` access. In Account → API keys, admins can additionally select **Manage integrations** (`integrations:manage`) when creating a key. Existing keys do not gain this permission automatically; create a replacement and revoke the old key to change permissions. Ordinary keys can already use connected APIs, including writes; this additional scope controls connection setup, not provider API permissions. Keys cannot grant scopes or approve human reviews.
-
-```sh
-gondo integrations providers
-gondo integrations provider clio
-gondo integrations create --provider clio --name "Demo Clio"
-gondo integrations credentials <id> --file ./private-credentials.json --variant <variant>
-gondo integrations test <id>
-gondo integrations enable <id>
-```
-
-Only prebuilt providers with supplied credentials are supported. Credential JSON/YAML must match the displayed schema; `--file -` reads stdin. Do not pass secret values as arguments. Connections start disabled, and enablement is explicit. Replacement credentials are validated separately before an atomic switch; failed checks leave live credentials untouched. Concurrent replacements return a conflict rather than overwriting each other. `checked: false` means no provider check was available. Use `integrations list|get <id>`, `disable <id>`, or `update <id> --file settings.json` (fields: `label`, `maxScope`, `enabledToolsets`, `disabledTools`). Provider metadata lists valid tool names; `maxScope` accepts `read`, `write`, `admin`. These settings govern named tools, not direct API code.
-
-## Webhooks and workflow documents
-
-```sh
-gondo workflows webhook get <workflow-id>
-gondo workflows webhook configure <workflow-id> --output ./private-webhook.json
-gondo attempts files list <attempt-id>
-gondo attempts files download <attempt-id> <artifact-id> --output-dir ./outputs
-```
+Tests include an installed packed artifact, authenticated HTTP transport, server capability-version checks, private credential files and binary downloads.
 
-Webhook configuration requires a new private output file and never prints its secret. Repeating `configure` preserves existing credentials; explicitly use `rotate-secret` with another output file to replace a lost secret. Trigger the returned URL with curl using its `headerName` and `secret`, then inspect runs. No mutations are automatically retried.
+**Deploy the paired app release exposing capability protocol version 2 before publishing CLI 0.2.0.** This release requires `/operator/tools` and the shared `/operator/guide`; discovery on an older server fails clearly without falling back to stale instructions. This is the initial supported CLI contract; older CLI releases are not supported.
 
-Workflow downloads target an attempt, not a CLI workspace session. Downloads refuse unsafe filenames or overwrites, remove partial files, verify available size/checksum metadata and cap files without size metadata at 512 MiB. Storage requests never carry the Gondo API key.
+The [shared implementation brief](https://github.com/commandable/commandable-app-v1/blob/main/docs/unified-authoring.md) documents the paired app change and verification.
 
-Deploy the backend API-key scope migration and matching runtime before releasing this CLI. No SharePoint file-transfer changes are part of this release.
+After that deployment, an authorized npm maintainer can publish with `npm publish --access public`. Creating or merging these PRs does not itself publish the npm package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gondoai/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Let coding agents build, test, and manage employees and jobs on Gondo.",
   "type": "module",
   "license": "UNLICENSED",

package/src/cli.mjs

@@ -6,7 +6,7 @@ import { Readable, Transform } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 import { parseArgs, parseEnv } from 'node:util'
 import packageJson from '../package.json' with { type: 'json' }
-import { parseDocument } from 'yaml'
+import { parseDocument, stringify } from 'yaml'
 
 export const HELP = `Gondo account operator CLI
 
@@ -16,11 +16,14 @@ Load a local env file with: gondo --env-file ./gondo.env guide
 Use gondo --version to show the installed CLI version.
 Account admins create keys in Account Settings. Never put a key in source code.
 
-gondo guide [--topic overview|workflows|nodes]
+gondo guide [--topic overview|workflows]
+gondo tools list|describe <existing-admin-tool-name>
+gondo call <existing-admin-tool-name> --file arguments.json [--session <id>] [--output-dir <dir>]
+Tool names, descriptions and argument schemas come from the server. Host and interactive tools return required actions.
 gondo list [namespace-path] [--limit 25]
 gondo read <namespace-path>
 gondo employees list|get <id>|create --file employee.yaml|update <id> --file changes.json|delete <id>
-gondo workflows list|get <id>|create --employee <id> --name <name>
+gondo workflows list|get <id> [--source active|draft|published] [--format json|yaml] [--editor-state]|create --employee <id> --name <name>
 gondo workflows save-draft <id> --file workflow.yaml
 gondo workflows validate <id> [--file workflow.yaml] [--source draft|published]
 gondo workflows export <id> [--source active|draft|published] [--output workflow.yaml]
@@ -29,7 +32,7 @@ gondo workflows rename <id> --name <name>
 gondo runs list|get|attempts|events|definition|cancel <run-id>
 gondo attempts get|events|definition|cancel <attempt-id>
 gondo runs test|start <workflow-id> [--input input.json]
-gondo exec --file investigate.js --integrations ref_one,ref_two [--session <id>] [--attach <path> ...] [--output-dir <dir>]
+gondo exec --file investigate.js --integrations ref_one,ref_two [--channels ref_one,ref_two] [--session <id>] [--attach <path> ...] [--output-dir <dir>]
 gondo sessions create|list|get <id>|close <id>
 gondo files list <session-id>|upload <session-id> --file <path>
 gondo files download <file-id> --session <id> --output-dir <dir>
@@ -45,7 +48,7 @@ gondo attempts files list <attempt-id>
 gondo attempts files download <attempt-id> <artifact-id> --output-dir <dir>
 
 Keys have operator access; integration changes also require integrations:manage.
-New integrations are disabled. Save credentials, inspect the check result, then enable explicitly.
+New integrations follow Admin defaults (enabled). Saving credentials never re-enables an existing connection.
 Webhook configure/rotate-secret require --output; secrets never appear on stdout. Configure never rotates an existing secret.
 
 Requires Pro, including active Pro trials. Responses are JSON. Exit 0: success; 1: failure; 2: user action required.
@@ -72,6 +75,9 @@ const options = {
   'name': { type: 'string' },
   'integrations': { type: 'string' },
   'source': { type: 'string' },
+  'format': { type: 'string' },
+  'editor-state': { type: 'boolean' },
+  'channels': { type: 'string' },
   'topic': { type: 'string' },
   'limit': { type: 'string' },
   'help': { type: 'boolean', short: 'h' },
@@ -93,6 +99,15 @@ function segment(value, label = 'ID') {
   return encodeURIComponent(result)
 }
 
+function positiveInteger(value, label) {
+  const text = value.trim()
+  const number = Number(text)
+  if (!/^\d+$/.test(text) || !Number.isSafeInteger(number) || number <= 0)
+    throw new Error(`${label} must be a positive safe integer`)
+
+  return number
+}
+
 async function readStructured(file, stdin = process.stdin) {
   required(file, '--file or --input')
   let source
@@ -140,18 +155,37 @@ export async function buildRequest(argv, { stdin = process.stdin } = {}) {
 
   const request = { method: 'GET', path: '', query: {}, body: undefined, output: values.output, ...(values['env-file'] ? { envFile: values['env-file'] } : {}) }
 
+  // Convenience commands are argument adapters to the shared Admin operations.
+  const call = (name, args, presentation) => {
+    request.path = `/operator/tools/${name}/call`
+    request.method = 'POST'
+    request.query = {}
+    request.body = { arguments: args, ...(values.session ? { sessionId: values.session } : {}), ...(presentation ? { presentation } : {}) }
+    request.requiresCapabilities = 2
+  }
+
   if (command === 'guide') {
     request.path = '/operator/guide'
 
     request.query.topic = values.topic ?? 'overview'
+    request.requiresCapabilities = 2
+  }
+  else if (command === 'tools') {
+    if (action === 'list')
+      request.path = '/operator/tools'
+    else if (action === 'describe')
+      request.path = `/operator/tools/${segment(id, 'tool name')}`
+    request.requiresCapabilities = 2
+  }
+  else if (command === 'call') {
+    call(segment(action, 'tool name'), await readStructured(values.file, stdin))
+    request.outputDir = values['output-dir']
   }
   else if (command === 'list' || command === 'read') {
-    request.path = '/operator/resources'
-
-    request.query = { action: command, path: command === 'read' ? required(action, 'namespace path') : action ?? '/' }
-
-    if (values.limit)
-      request.query.limit = values.limit
+    call(command === 'list' ? 'gondo_list' : 'gondo_read', {
+      path: command === 'read' ? required(action, 'namespace path') : action ?? '/',
+      ...(command === 'list' && values.limit !== undefined ? { limit: positiveInteger(values.limit, '--limit') } : {}),
+    })
   }
   else if (command === 'exec') {
     request.path = '/code/execute'
@@ -160,6 +194,7 @@ export async function buildRequest(argv, { stdin = process.stdin } = {}) {
 
     request.body = {
       code: await readFile(required(values.file, '--file'), 'utf8'),
+      channels: values.channels?.split(',').map(ref => ref.trim()).filter(Boolean) ?? [],
       integrations: values.integrations?.split(',').map(ref => ref.trim()).filter(Boolean) ?? [],
       ...(values.session ? { sessionId: values.session } : {}),
     }
@@ -205,23 +240,19 @@ export async function buildRequest(argv, { stdin = process.stdin } = {}) {
     request.body = { integration: required(values.integration, '--integration') }
   }
   else if (command === 'employees') {
-    if (action === 'list') {
+    if (action === 'list')
       request.path = '/employees'
-    }
-    else if (action === 'create') {
-      request.path = '/employees'
-
-      request.method = 'POST'
-
-      request.body = await readStructured(values.file)
-    }
-    else if (['get', 'update', 'delete'].includes(action)) {
+    else if (action === 'get')
       request.path = `/employees/${segment(id)}`
-
-      request.method = { get: 'GET', update: 'PATCH', delete: 'DELETE' }[action]
-
-      if (action === 'update')
-        request.body = await readStructured(values.file)
+    else if (['create', 'update', 'delete'].includes(action)) {
+      const body = action === 'delete' ? {} : await readStructured(values.file)
+      const { allowedIntegrationRefs, allowedChannelRefs, ...rest } = body
+      call(`${action}_employee`, {
+        ...rest,
+        ...(action !== 'create' ? { employee_id: required(id, 'employee ID') } : {}),
+        ...(allowedIntegrationRefs !== undefined ? { allowed_integration_refs: allowedIntegrationRefs ?? [] } : {}),
+        ...(allowedChannelRefs !== undefined ? { allowed_channel_refs: allowedChannelRefs ?? [] } : {}),
+      })
     }
   }
   else if (command === 'integrations') {
@@ -233,10 +264,13 @@ export async function buildRequest(argv, { stdin = process.stdin } = {}) {
     else if (action === 'list')
       request.path = base
     else if (action === 'create') {
-      request.path = base
-      request.method = 'POST'
-      request.body = { providerKey: required(values.provider, '--provider'), label: required(values.name, '--name'), ...(values.reference ? { referenceId: values.reference } : {}) }
+      call('gondo_add_prebuilt_api_integration', {
+        type: required(values.provider, '--provider'), label: required(values.name, '--name'),
+        ...(values.reference ? { reference_id: values.reference } : {}),
+      })
     }
+    else if (action === 'enable' || action === 'disable')
+      call('gondo_set_integration_enabled', { integration_id: required(id, 'integration ID'), enabled: action === 'enable' })
     else if (action === 'get')
       request.path = `${base}/${segment(id)}`
     else if (action === 'update') {
@@ -244,7 +278,7 @@ export async function buildRequest(argv, { stdin = process.stdin } = {}) {
       request.method = 'PATCH'
       request.body = await readStructured(values.file)
     }
-    else if (['credentials', 'test', 'enable', 'disable'].includes(action)) {
+    else if (['credentials', 'test'].includes(action)) {
       request.path = `${base}/${segment(id)}/${action}`
       request.method = 'POST'
       if (action === 'credentials') {
@@ -280,56 +314,45 @@ export async function buildRequest(argv, { stdin = process.stdin } = {}) {
     }
   }
   else if (command === 'workflows') {
-    if (action === 'list') {
-      request.path = '/workflows'
-    }
-    else if (action === 'create') {
+    if (action === 'list')
       request.path = '/workflows'
-
-      request.method = 'POST'
-
-      request.body = { employeeId: required(values.employee, '--employee'), name: required(values.name, '--name') }
-    }
+    else if (action === 'create')
+      call('create_new_workflow', { employee_id: required(values.employee, '--employee'), suggested_name: required(values.name, '--name') })
     else {
-      const base = `/workflows/${segment(id)}`
-
-      const routes = {
-        'get': ['GET', '/editor'],
-        'save-draft': ['PUT', '/draft'],
-        'discard-draft': ['DELETE', '/draft'],
-        'validate': ['POST', '/validate'],
-        'export': ['POST', '/yaml'],
-        'publish': ['POST', '/publish'],
-        'enable': ['PATCH', ''],
-        'disable': ['PATCH', ''],
-        'rename': ['PATCH', ''],
-        'delete': ['DELETE', ''],
+      const workflowId = required(id, 'workflow ID')
+      const base = `/workflows/${segment(workflowId)}`
+      if (action === 'get')
+        call('gondo_read', { path: base }, { source: values.source ?? 'active', format: values.format ?? 'json', editorState: values['editor-state'] ?? false })
+      else if (action === 'save-draft') {
+        const body = await definitionBody(values.file)
+        call('gondo_put_workflow', { op: 'replace', workflow_id: workflowId, definition_yaml: body.definitionYaml ?? stringify(body.definition) })
       }
-
-      const route = routes[action]
-
-      if (route) {
-        request.method = route[0]
-
-        request.path = `${base}${route[1]}`
-
-        if (action === 'save-draft')
-          request.body = await definitionBody(values.file)
-
-        if (action === 'validate')
-          request.body = { source: values.source ?? 'draft', ...(values.file ? await definitionBody(values.file) : {}) }
-
-        if (action === 'export')
-          request.body = { source: values.source ?? 'active' }
-
-        if (action === 'publish')
-          request.body = {}
-
-        if (action === 'enable' || action === 'disable')
-          request.body = { enabled: action === 'enable' }
-
-        if (action === 'rename')
-          request.body = { name: required(values.name, '--name') }
+      else if (action === 'publish')
+        call('gondo_publish_workflow', { workflow_id: workflowId })
+      else if (action === 'rename')
+        call('gondo_update_workflow_settings', { workflow_id: workflowId, name: required(values.name, '--name') })
+      else if (action === 'validate' && !values.file && !values.source)
+        call('gondo_validate_workflow', { workflow_id: workflowId })
+      else {
+        const routes = {
+          'discard-draft': ['DELETE', '/draft'],
+          'validate': ['POST', '/validate'],
+          'export': ['POST', '/yaml'],
+          'enable': ['PATCH', ''],
+          'disable': ['PATCH', ''],
+          'delete': ['DELETE', ''],
+        }
+        const route = routes[action]
+        if (route) {
+          request.method = route[0]
+          request.path = `${base}${route[1]}`
+          if (action === 'validate')
+            request.body = { source: values.source ?? 'draft', ...(values.file ? await definitionBody(values.file) : {}) }
+          if (action === 'export')
+            request.body = { source: values.source ?? 'active' }
+          if (action === 'enable' || action === 'disable')
+            request.body = { enabled: action === 'enable' }
+        }
       }
     }
   }
@@ -337,8 +360,8 @@ export async function buildRequest(argv, { stdin = process.stdin } = {}) {
     if (action === 'list') {
       request.path = '/runs'
 
-      if (values.limit)
-        request.query.limit = values.limit
+      if (values.limit !== undefined)
+        request.query.limit = positiveInteger(values.limit, '--limit')
     }
     else if (action === 'test' || action === 'start') {
       request.path = '/runs'
@@ -371,7 +394,7 @@ export async function buildRequest(argv, { stdin = process.stdin } = {}) {
   if (!request.path)
     throw new Error('Unknown command. Use --help for supported commands.')
 
-  const maxPositionals = command === 'integrations' && ['providers', 'list', 'create'].includes(action) ? 2 : command === 'workflows' && action === 'webhook' ? 4 : command === 'attempts' && action === 'files' ? (id === 'download' ? 5 : 4) : ['guide', 'exec'].includes(command) ? 1 : ['list', 'read'].includes(command) ? 2 : 3
+  const maxPositionals = command === 'call' ? 2 : command === 'tools' && action === 'list' ? 2 : command === 'integrations' && ['providers', 'list', 'create'].includes(action) ? 2 : command === 'workflows' && action === 'webhook' ? 4 : command === 'attempts' && action === 'files' ? (id === 'download' ? 5 : 4) : ['guide', 'exec'].includes(command) ? 1 : ['list', 'read'].includes(command) ? 2 : 3
 
   if (positionals.length > maxPositionals)
     throw new Error('Unexpected positional argument. Use --help for command syntax.')
@@ -426,6 +449,7 @@ export async function runCli(argv, { env = process.env, fetchImpl = fetch, stdou
   let request
   let secretHandle
   let secretWritten = false
+  let toolCallStarted = false
   try {
     request = await buildRequest(argv, { stdin })
 
@@ -480,12 +504,14 @@ export async function runCli(argv, { env = process.env, fetchImpl = fetch, stdou
       let response
 
       try {
+        if (next.path.startsWith('/operator/tools/') && next.path.endsWith('/call'))
+          toolCallStarted = true
         response = await fetchImpl(url, {
           method: next.method,
           headers: { 'Authorization': `Bearer ${key}`, 'Content-Type': 'application/json', ...uploadHeaders },
           ...(uploadStream ? { body: uploadStream, duplex: 'half' } : next.body !== undefined ? { body: JSON.stringify(next.body) } : {}),
           redirect: 'error',
-          signal: AbortSignal.timeout(120000),
+          signal: AbortSignal.timeout(next.path === '/code/execute' || next.path?.endsWith('/call') ? 420000 : 120000),
         })
       }
       finally {
@@ -495,6 +521,9 @@ export async function runCli(argv, { env = process.env, fetchImpl = fetch, stdou
       if (next.binary && response.ok)
         return { response }
 
+      if (next.requiresCapabilities && [404, 405].includes(response.status))
+        throw new Error('This Gondo server does not support CLI 0.2.0 shared capabilities. Deploy the matching app release before using this command.')
+
       const text = await response.text()
       let result
 
@@ -505,6 +534,8 @@ export async function runCli(argv, { env = process.env, fetchImpl = fetch, stdou
         throw new Error(`Runtime returned non-JSON (HTTP ${response.status}). Check GONDO_API_URL points to the runtime.`)
       }
 
+      if (next.requiresCapabilities && response.ok && result?.version !== next.requiresCapabilities)
+        throw new Error('This Gondo server has an incompatible capability version. Deploy the app release supporting CLI 0.2.0.')
       return { response, result }
     }
 
@@ -621,7 +652,7 @@ export async function runCli(argv, { env = process.env, fetchImpl = fetch, stdou
     }
 
     let received = await send(request)
-    if (request.path === '/code/execute')
+    if (request.path === '/code/execute' || received.result?.executionId)
       recovery = { sessionId: received.result?.sessionId, executionId: received.result?.executionId }
 
     if (request.outputDir && received.result?.files?.length) {
@@ -717,7 +748,7 @@ export async function runCli(argv, { env = process.env, fetchImpl = fetch, stdou
     if (request?.secretOutput && secretHandle && !secretWritten)
       message += ' Webhook state may have changed; inspect it before explicitly rotating again. No automatic retry was performed.'
 
-    stderr.write(`${JSON.stringify({ error: message, ...(request?.path === '/code/execute' ? { sessionId: request.body?.sessionId, ...recovery, recovery: 'Inspect the session and execution before continuing; do not repeat this execution automatically.' } : {}) })}\n`)
+    stderr.write(`${JSON.stringify({ error: message, ...(toolCallStarted || request?.path === '/code/execute' || request?.body?.sessionId || recovery ? { sessionId: request.body?.sessionId, ...recovery, recovery: toolCallStarted ? 'The tool call may have changed state. Inspect the affected resources and any session or execution before continuing; do not repeat this call automatically.' : 'Inspect the session and execution before continuing; do not repeat this execution automatically.' } : {}) })}\n`)
 
     return 1
   }