@gondoai/cli 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# 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.
+
+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.
+
+## Get started
+
+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
+```
+
+`--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
+
+Use a coding agent with terminal access, such as Codex or Claude Code. Replace the task and local file path:
+
+> 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
+```
+
+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.
+
+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.
+
+## Development and publishing
+
+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.
+
+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.
+
+```bash
+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
+```
+
+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.
+
+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.
+
+Deploy the backend API-key scope migration and matching runtime before releasing this CLI. No SharePoint file-transfer changes are part of this release.

package/bin/gondo.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.mjs'
+
+process.exitCode = await runCli(process.argv.slice(2))

package/gondo.env.example

@@ -0,0 +1 @@
+GONDO_API_KEY=your-api-key

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@gondoai/cli",
+  "version": "0.1.0",
+  "description": "Let coding agents build, test, and manage employees and jobs on Gondo.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "gondo": "bin/gondo.mjs"
+  },
+  "exports": "./src/cli.mjs",
+  "files": [
+    "bin/",
+    "src/",
+    "gondo.env.example"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/commandable/gondo-cli.git"
+  },
+  "homepage": "https://github.com/commandable/gondo-cli#readme",
+  "bugs": {
+    "url": "https://github.com/commandable/gondo-cli/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": ["gondo", "cli", "agents", "workflows"],
+  "dependencies": {
+    "yaml": "^2.8.3"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,731 @@
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { mkdir, open, readFile, stat, unlink, writeFile } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+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'
+
+export const HELP = `Gondo account operator CLI
+
+Set GONDO_API_KEY. The production URL and your key's account are automatic.
+Optional overrides: GONDO_API_URL (development runtime), GONDO_ACCOUNT_ID.
+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 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 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]
+gondo workflows publish|enable|disable|discard-draft|delete <id>
+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 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>
+gondo executions get <execution-id> --session <id>
+gondo browser restart <session-id> --integration <ref>
+gondo integrations providers|provider <provider>|list|get <id>
+gondo integrations create --provider <provider> --name <name> [--reference <ref>]
+gondo integrations credentials <id> --file credentials.json|- [--variant <variant>]
+gondo integrations test|enable|disable <id>
+gondo integrations update <id> --file settings.json
+gondo workflows webhook get|configure|rotate-secret <workflow-id> [--output <private-file>]
+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.
+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.
+Workspaces retain files for 24h inactivity. Browsers expire after 10m idle / 30m total.
+Login links are included in JSON. Login never reruns code. Use exec --session for the next explicit call.
+Tests and code execute real external actions. No mutations are retried automatically.
+Run commands follow the current attempt; attempts commands target a specific execution. A timeout does not imply no writes occurred.
+`
+
+const options = {
+  'env-file': { type: 'string' },
+  'version': { type: 'boolean', short: 'v' },
+  'file': { type: 'string' },
+  'session': { type: 'string' },
+  'attach': { type: 'string', multiple: true },
+  'output-dir': { type: 'string' },
+  'integration': { type: 'string' },
+  'provider': { type: 'string' },
+  'reference': { type: 'string' },
+  'variant': { type: 'string' },
+  'input': { type: 'string' },
+  'output': { type: 'string' },
+  'employee': { type: 'string' },
+  'name': { type: 'string' },
+  'integrations': { type: 'string' },
+  'source': { type: 'string' },
+  'topic': { type: 'string' },
+  'limit': { type: 'string' },
+  'help': { type: 'boolean', short: 'h' },
+}
+
+function required(value, label) {
+  if (typeof value !== 'string' || !value.trim())
+    throw new Error(`${label} is required. Use --help for examples.`)
+
+  return value.trim()
+}
+
+function segment(value, label = 'ID') {
+  const result = required(value, label)
+
+  if (result === '.' || result === '..' || result.includes('/'))
+    throw new Error(`${label} must be a single ID`)
+
+  return encodeURIComponent(result)
+}
+
+async function readStructured(file, stdin = process.stdin) {
+  required(file, '--file or --input')
+  let source
+  if (file === '-') {
+    const chunks = []
+    for await (const chunk of stdin)
+      chunks.push(Buffer.from(chunk))
+    source = Buffer.concat(chunks).toString('utf8')
+  }
+  else {
+    source = await readFile(file, 'utf8')
+  }
+
+  if (file.toLowerCase().endsWith('.json'))
+    return JSON.parse(source)
+
+  const document = parseDocument(source, { uniqueKeys: true, schema: 'core', merge: false })
+
+  if (document.errors.length)
+    throw new Error(document.errors.map(error => error.message).join('\n'))
+
+  return document.toJS({ maxAliasCount: 0 })
+}
+
+async function definitionBody(file) {
+  required(file, '--file')
+
+  if (file.toLowerCase().endsWith('.json'))
+    return { definition: await readStructured(file) }
+
+  // Keep YAML text intact so the server's canonical parser checks it.
+  return { definitionYaml: await readFile(file, 'utf8') }
+}
+
+export async function buildRequest(argv, { stdin = process.stdin } = {}) {
+  const { values, positionals } = parseArgs({ args: argv, options, allowPositionals: true, strict: true })
+
+  if (values.version)
+    return { version: true }
+
+  if (values.help || !positionals.length)
+    return { help: true }
+
+  const [command, action, id] = positionals
+
+  const request = { method: 'GET', path: '', query: {}, body: undefined, output: values.output, ...(values['env-file'] ? { envFile: values['env-file'] } : {}) }
+
+  if (command === 'guide') {
+    request.path = '/operator/guide'
+
+    request.query.topic = values.topic ?? 'overview'
+  }
+  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
+  }
+  else if (command === 'exec') {
+    request.path = '/code/execute'
+
+    request.method = 'POST'
+
+    request.body = {
+      code: await readFile(required(values.file, '--file'), 'utf8'),
+      integrations: values.integrations?.split(',').map(ref => ref.trim()).filter(Boolean) ?? [],
+      ...(values.session ? { sessionId: values.session } : {}),
+    }
+  }
+  else if (command === 'sessions' || command === 'session') {
+    if (action === 'create' || action === 'list') {
+      request.path = '/code/sessions'
+
+      request.method = action === 'create' ? 'POST' : 'GET'
+    }
+    else if (action === 'get' || action === 'close') {
+      request.path = `/code/sessions/${segment(id)}${action === 'close' ? '/close' : ''}`
+
+      request.method = action === 'close' ? 'POST' : 'GET'
+    }
+  }
+  else if (command === 'files') {
+    const sessionId = action === 'download' ? required(values.session, '--session') : required(id, 'session ID')
+
+    request.path = `/code/sessions/${segment(sessionId)}/files`
+
+    if (action === 'upload') {
+      request.method = 'POST'
+      request.upload = required(values.file, '--file')
+    }
+    else if (action === 'download') {
+      request.path += `/${segment(id)}`
+
+      request.download = { sessionId, fileId: id, directory: required(values['output-dir'], '--output-dir') }
+    }
+    else if (action !== 'list') {
+      request.path = ''
+    }
+  }
+  else if (command === 'executions' && action === 'get') {
+    request.path = `/code/sessions/${segment(values.session, '--session')}/executions/${segment(id)}`
+  }
+  else if (command === 'browser' && action === 'restart') {
+    request.path = `/code/sessions/${segment(id)}/browser/restart`
+
+    request.method = 'POST'
+
+    request.body = { integration: required(values.integration, '--integration') }
+  }
+  else if (command === 'employees') {
+    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)) {
+      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 (command === 'integrations') {
+    const base = '/operator/integrations'
+    if (action === 'providers')
+      request.path = `${base}/providers`
+    else if (action === 'provider')
+      request.path = `${base}/providers/${segment(id)}`
+    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 } : {}) }
+    }
+    else if (action === 'get')
+      request.path = `${base}/${segment(id)}`
+    else if (action === 'update') {
+      request.path = `${base}/${segment(id)}`
+      request.method = 'PATCH'
+      request.body = await readStructured(values.file)
+    }
+    else if (['credentials', 'test', 'enable', 'disable'].includes(action)) {
+      request.path = `${base}/${segment(id)}/${action}`
+      request.method = 'POST'
+      if (action === 'credentials') {
+        required(values.file, '--file')
+        try {
+          request.body = { credentials: await readStructured(values.file, stdin), ...(values.variant ? { variantKey: values.variant } : {}) }
+        }
+        catch {
+          throw new Error('Could not read credentials. Provide a valid JSON or YAML object using --file (or --file - for stdin).')
+        }
+      }
+    }
+  }
+  else if (command === 'workflows' && action === 'webhook') {
+    const routes = { get: ['GET', 'connection'], configure: ['POST', 'connection'], 'rotate-secret': ['POST', 'rotate'] }
+    const route = routes[id]
+    if (route) {
+      request.path = `/workflows/${segment(positionals[3], 'workflow ID')}/webhook/${route[1]}`
+      request.method = route[0]
+      if (route[0] === 'POST') {
+        request.secretOutput = required(values.output, '--output')
+        request.output = undefined
+      }
+    }
+  }
+  else if (command === 'attempts' && action === 'files') {
+    if (id === 'list' || id === 'download') {
+      const attemptId = segment(positionals[3], 'attempt ID')
+      request.path = `/run-attempts/${attemptId}`
+      request.artifactList = true
+      if (id === 'download')
+        request.artifactDownload = { attemptId, artifactId: required(positionals[4], 'artifact ID'), directory: required(values['output-dir'], '--output-dir') }
+    }
+  }
+  else if (command === 'workflows') {
+    if (action === 'list') {
+      request.path = '/workflows'
+    }
+    else if (action === 'create') {
+      request.path = '/workflows'
+
+      request.method = 'POST'
+
+      request.body = { employeeId: required(values.employee, '--employee'), 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 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 (command === 'runs') {
+    if (action === 'list') {
+      request.path = '/runs'
+
+      if (values.limit)
+        request.query.limit = values.limit
+    }
+    else if (action === 'test' || action === 'start') {
+      request.path = '/runs'
+
+      request.method = 'POST'
+
+      request.body = {
+        workflowId: required(id, 'workflow ID'),
+        useDraft: action === 'test',
+        startAsync: true,
+        triggerData: values.input ? await readStructured(values.input) : {},
+      }
+    }
+    else if (action === 'get' || action === 'attempts') {
+      request.path = `/runs/${segment(id)}${action === 'get' ? '' : '/attempts'}`
+    }
+    else if (['events', 'definition', 'cancel'].includes(action)) {
+      request.path = `/runs/${segment(id)}`
+
+      request.resolveAttemptAction = action
+    }
+  }
+  else if (command === 'attempts' && ['get', 'events', 'definition', 'cancel'].includes(action)) {
+    request.path = `/run-attempts/${segment(id)}${action === 'get' ? '' : `/${action}`}`
+
+    if (action === 'cancel')
+      request.method = 'POST'
+  }
+
+  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
+
+  if (positionals.length > maxPositionals)
+    throw new Error('Unexpected positional argument. Use --help for command syntax.')
+
+  if (command === 'exec' && values.attach?.length)
+    request.attach = values.attach
+
+  if (command === 'exec' && values['output-dir'])
+    request.outputDir = values['output-dir']
+
+  return request
+}
+
+// Reject separators and control characters before creating any local file.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_DOWNLOAD_NAME = /[\\/\x00-\x1F\x7F]/
+const WINDOWS_FILENAME_CHARS = /[<>:"|?*]/g
+
+export function safeDownloadName(name) {
+  if (typeof name !== 'string' || !name || name === '.' || name === '..' || UNSAFE_DOWNLOAD_NAME.test(name))
+    throw new Error('Unsafe output filename')
+
+  return name.replace(WINDOWS_FILENAME_CHARS, '_')
+}
+
+function credentialStrings(value) {
+  if (typeof value === 'string')
+    return value ? [value] : []
+  if (value && typeof value === 'object')
+    return Object.values(value).flatMap(credentialStrings)
+  return []
+}
+
+function redactString(value, secrets) {
+  for (const secret of [...secrets].sort((a, b) => b.length - a.length))
+    value = value.replaceAll(secret, '[REDACTED]')
+  return value
+}
+
+function redactResponse(value, secrets) {
+  if (typeof value === 'string')
+    return redactString(value, secrets)
+  if (Array.isArray(value))
+    return value.map(item => redactResponse(item, secrets))
+  if (value && typeof value === 'object')
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [redactString(key, secrets), redactResponse(item, secrets)]))
+  return value
+}
+
+export async function runCli(argv, { env = process.env, fetchImpl = fetch, stdout = process.stdout, stderr = process.stderr, stdin = process.stdin } = {}) {
+  let recovery
+  let request
+  let secretHandle
+  let secretWritten = false
+  try {
+    request = await buildRequest(argv, { stdin })
+
+    if (request.version) {
+      stdout.write(`${packageJson.version}\n`)
+
+      return 0
+    }
+
+    if (request.help) {
+      stdout.write(HELP)
+
+      return 0
+    }
+
+    if (request.envFile)
+      env = { ...parseEnv(await readFile(request.envFile, 'utf8')), ...env }
+
+    const base = new URL(env.GONDO_API_URL || 'https://runtime.gondo.ai')
+
+    if (base.protocol !== 'https:' && !(base.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(base.hostname)))
+      throw new Error('GONDO_API_URL must use HTTPS, or HTTP on localhost for development')
+
+    if (base.username || base.password || base.search || base.hash)
+      throw new Error('GONDO_API_URL must not include credentials, a query, or a fragment')
+
+    let account = env.GONDO_ACCOUNT_ID === undefined ? undefined : segment(env.GONDO_ACCOUNT_ID, 'GONDO_ACCOUNT_ID')
+
+    const key = required(env.GONDO_API_KEY, 'GONDO_API_KEY')
+
+    const send = async (next, { accountScoped = true } = {}) => {
+      const url = new URL(accountScoped ? `/api/accounts/${account}${next.path}` : next.path, base)
+
+      for (const [name, value] of Object.entries(next.query ?? {}))
+        url.searchParams.set(name, value)
+
+      let uploadStream
+
+      let uploadHeaders = {}
+
+      if (next.upload) {
+        const size = (await stat(next.upload)).size
+
+        if (!(await stat(next.upload)).isFile())
+          throw new Error('Only regular files can be uploaded')
+
+        uploadStream = createReadStream(next.upload)
+
+        uploadHeaders = { 'Content-Type': 'application/octet-stream', 'Content-Length': String(size), 'X-File-Name': encodeURIComponent(basename(next.upload)) }
+      }
+
+      let response
+
+      try {
+        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),
+        })
+      }
+      finally {
+        uploadStream?.destroy()
+      }
+
+      if (next.binary && response.ok)
+        return { response }
+
+      const text = await response.text()
+      let result
+
+      try {
+        result = text ? redactResponse(JSON.parse(text), [key, ...credentialStrings(request.body?.credentials)]) : null
+      }
+      catch {
+        throw new Error(`Runtime returned non-JSON (HTTP ${response.status}). Check GONDO_API_URL points to the runtime.`)
+      }
+
+      return { response, result }
+    }
+
+    const failed = ({ response, result }) => {
+      if (response.ok && result?.success !== false && result?.ok !== false)
+        return false
+
+      stderr.write(`${JSON.stringify({ status: response.status, ...result })}\n`)
+
+      return true
+    }
+
+    if (request.secretOutput)
+      secretHandle = await open(request.secretOutput, 'wx', 0o600)
+
+    if (!account) {
+      const identity = await send({ path: '/api/operator/me', method: 'GET' }, { accountScoped: false })
+      if (failed(identity))
+        return 1
+      account = segment(identity.result?.accountId, 'API key account ID')
+    }
+
+    const download = async (sessionId, file, directory, fetchFile) => {
+      const declaredSize = file.sizeBytes ?? undefined
+      if (declaredSize !== undefined && (!Number.isSafeInteger(declaredSize) || declaredSize < 0))
+        throw new Error('Invalid file size metadata')
+      const name = safeDownloadName(file.name)
+
+      await mkdir(directory, { recursive: true })
+
+      const target = resolve(directory, name)
+
+      // Exclusive creation also rejects an existing symlink. Never overwrite an earlier output.
+      const handle = await open(target, 'wx', 0o600)
+
+      let done = false
+
+      try {
+        const received = fetchFile ? await fetchFile() : await send({ path: `/code/sessions/${segment(sessionId)}/files/${segment(file.id)}`, method: 'GET', binary: true })
+
+        if (!received.response.ok)
+          throw new Error(`File download failed (HTTP ${received.response.status})`)
+
+        const hash = createHash('sha256')
+
+        let size = 0
+
+        const check = new Transform({ transform(chunk, _encoding, callback) {
+          size += chunk.length
+
+          if (size > (declaredSize ?? 512 * 1024 * 1024))
+            return callback(new Error('Download exceeded its declared size'))
+
+          hash.update(chunk)
+          callback(null, chunk)
+        } })
+
+        await pipeline(Readable.fromWeb(received.response.body), check, handle.createWriteStream())
+
+        if ((declaredSize !== undefined && size !== declaredSize) || (file.sha256 && hash.digest('hex') !== file.sha256))
+          throw new Error('Downloaded file failed integrity verification')
+
+        done = true
+
+        return { fileId: file.id, savedTo: target }
+      }
+      finally {
+        await handle.close()
+        if (!done) {
+          await unlink(target).catch(() => {
+          })
+        }
+      }
+    }
+
+    if (request.download) {
+      const d = request.download
+
+      const listing = await send({ path: `/code/sessions/${segment(d.sessionId)}/files`, method: 'GET' })
+
+      if (failed(listing))
+        return 1
+
+      const file = listing.result.files.find(f => f.id === d.fileId)
+
+      if (!file)
+        throw new Error('File not found in this session')
+
+      stdout.write(`${JSON.stringify(await download(d.sessionId, file, d.directory))}\n`)
+
+      return 0
+    }
+
+    if (request.attach?.length) {
+      if (!request.body.sessionId) {
+        const created = await send({ path: '/code/sessions', method: 'POST' })
+
+        if (failed(created))
+          return 1
+
+        request.body.sessionId = created.result.id
+      }
+
+      request.body.fileIds = []
+
+      for (const file of request.attach) {
+        const uploaded = await send({ path: `/code/sessions/${segment(request.body.sessionId)}/files`, method: 'POST', upload: file })
+
+        if (failed(uploaded))
+          return 1
+
+        request.body.fileIds.push(uploaded.result.id)
+      }
+    }
+
+    let received = await send(request)
+    if (request.path === '/code/execute')
+      recovery = { sessionId: received.result?.sessionId, executionId: received.result?.executionId }
+
+    if (request.outputDir && received.result?.files?.length) {
+      received.result.downloads = []
+
+      for (const file of received.result.files) {
+        if (file.executionId !== received.result.executionId)
+          throw new Error('Runtime returned an output from a different execution')
+
+        received.result.downloads.push(await download(received.result.sessionId, file, request.outputDir))
+      }
+    }
+
+    if (received.result?.requiredAction) {
+      stdout.write(`${JSON.stringify(received.result, null, 2)}\n`)
+
+      return 2
+    }
+
+    if (failed(received))
+      return 1
+
+    if (request.resolveAttemptAction) {
+      // Resolve once, then pin this operation to that execution even if a retry
+      // becomes current in the meantime. Never retry cancellation automatically.
+      const attemptId = segment(received.result?.currentAttemptId, 'current attempt ID')
+
+      received = await send({
+        path: `/run-attempts/${attemptId}/${request.resolveAttemptAction}`,
+        method: request.resolveAttemptAction === 'cancel' ? 'POST' : 'GET',
+      })
+
+      if (failed(received))
+        return 1
+    }
+
+    if (request.secretOutput) {
+      await secretHandle.writeFile(`${JSON.stringify(received.result, null, 2)}\n`, 'utf8')
+      await secretHandle.sync()
+      secretWritten = true
+      stdout.write(`${JSON.stringify({ savedTo: resolve(request.secretOutput), configured: received.result?.configured, secretIssued: Boolean(received.result?.secret) })}\n`)
+      return 0
+    }
+
+    if (request.artifactList) {
+      const files = received.result?.fileArtifacts ?? []
+      if (request.artifactDownload) {
+        const d = request.artifactDownload
+        const file = files.find(item => item.id === d.artifactId)
+        if (!file)
+          throw new Error('File not found in this attempt')
+        const saved = await download(null, file, d.directory, async () => {
+          const signed = await send({ path: `/run-attempts/${d.attemptId}/files/${segment(d.artifactId)}/download-url`, method: 'GET' })
+          if (failed(signed))
+            throw new Error('Could not obtain file download URL')
+          const url = new URL(signed.result?.sasUrl)
+          if (url.protocol !== 'https:' || url.username || url.password || url.hash)
+            throw new Error('Invalid storage download URL')
+          // Storage is a different origin. Never forward the Gondo Authorization header.
+          try {
+            return { response: await fetchImpl(url, { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(120000) }) }
+          }
+          catch {
+            throw new Error('Storage download failed. Retry the download to obtain a fresh URL.')
+          }
+        })
+        stdout.write(`${JSON.stringify(saved)}\n`)
+        return 0
+      }
+      received.result = { files: files.map(({ id, name, mime, sizeBytes, sha256 }) => ({ id, name, mime, sizeBytes, sha256 })) }
+    }
+
+    const { result } = received
+
+    if (request.output) {
+      const content = typeof result?.yaml === 'string' ? result.yaml : `${JSON.stringify(result, null, 2)}\n`
+
+      await writeFile(request.output, content, { encoding: 'utf8', mode: 0o600 })
+
+      stdout.write(`${JSON.stringify({ savedTo: resolve(request.output) })}\n`)
+    }
+    else {
+      stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    }
+
+    return 0
+  }
+  catch (error) {
+    // Do not dump request objects, environment variables, or authorization headers.
+    let message = error instanceof Error ? error.message : 'Command failed'
+    const key = env.GONDO_API_KEY
+    message = redactString(message, [...(key ? [key] : []), ...credentialStrings(request?.body?.credentials)])
+    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`)
+
+    return 1
+  }
+  finally {
+    if (secretHandle) {
+      await secretHandle.close()
+      if (!secretWritten)
+        await unlink(request.secretOutput).catch(() => {})
+    }
+  }
+}