@laburen/delta-cli 0.2.0-canary.13 → 0.2.0-canary.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/agent-follow-ups/body.d.ts +20 -0
- package/dist/commands/agent-follow-ups/body.js +31 -0
- package/dist/commands/agent-follow-ups/body.js.map +1 -0
- package/dist/commands/agent-follow-ups.d.ts +10 -0
- package/dist/commands/agent-follow-ups.js +129 -0
- package/dist/commands/agent-follow-ups.js.map +1 -0
- package/dist/commands/agent-run/body.d.ts +2 -0
- package/dist/commands/agent-run/body.js +2 -0
- package/dist/commands/agent-run/body.js.map +1 -1
- package/dist/commands/agent-run/render.d.ts +26 -3
- package/dist/commands/agent-run/render.js +47 -6
- package/dist/commands/agent-run/render.js.map +1 -1
- package/dist/commands/agent-run.d.ts +3 -1
- package/dist/commands/agent-run.js +145 -31
- package/dist/commands/agent-run.js.map +1 -1
- package/dist/commands/agent-tools/shared.d.ts +176 -0
- package/dist/commands/agent-tools/shared.js +4 -1
- package/dist/commands/agent-tools/shared.js.map +1 -1
- package/dist/commands/config-sources.d.ts +3 -1
- package/dist/commands/config-sources.js +6 -0
- package/dist/commands/config-sources.js.map +1 -1
- package/dist/commands/config-wizard.js +21 -20
- package/dist/commands/config-wizard.js.map +1 -1
- package/dist/commands/wizards.d.ts +1 -1
- package/dist/commands/wizards.js +9 -1
- package/dist/commands/wizards.js.map +1 -1
- package/dist/errors.d.ts +4 -1
- package/dist/errors.js +517 -44
- package/dist/errors.js.map +1 -1
- package/dist/generated/commands.d.ts +9 -1
- package/dist/generated/commands.js +17 -11
- package/dist/generated/commands.js.map +1 -1
- package/dist/generated/schemas.js +15 -12
- package/dist/generated/schemas.js.map +1 -1
- package/dist/invocation.d.ts +30 -0
- package/dist/invocation.js +130 -33
- package/dist/invocation.js.map +1 -1
- package/dist/operations/file-input.d.ts +5 -0
- package/dist/operations/file-input.js +67 -0
- package/dist/operations/file-input.js.map +1 -0
- package/dist/operations/params.d.ts +3 -1
- package/dist/operations/params.js +35 -6
- package/dist/operations/params.js.map +1 -1
- package/dist/operations/register.d.ts +4 -0
- package/dist/operations/register.js +67 -7
- package/dist/operations/register.js.map +1 -1
- package/dist/operations/run-operation.js +4 -2
- package/dist/operations/run-operation.js.map +1 -1
- package/dist/operations/skeleton.js +13 -5
- package/dist/operations/skeleton.js.map +1 -1
- package/dist/operations/tables.js +11 -2
- package/dist/operations/tables.js.map +1 -1
- package/dist/output.d.ts +2 -0
- package/dist/output.js +30 -5
- package/dist/output.js.map +1 -1
- package/dist/pickers.d.ts +4 -2
- package/dist/pickers.js +29 -15
- package/dist/pickers.js.map +1 -1
- package/dist/program.js +13 -24
- package/dist/program.js.map +1 -1
- package/docs/SKILL.md +20 -13
- package/docs/references/auth-and-organizations.md +2 -0
- package/docs/references/commands.md +149 -22
- package/docs/references/output-and-errors.md +40 -16
- package/package.json +2 -2
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
## stdout and stderr
|
|
4
4
|
|
|
5
|
-
- stdout: the data, and the error JSON (see below).
|
|
6
|
-
- stderr: notices, the login URL, the version notice, and errors for humans. `agents run` without `--json` writes all its errors to stderr (as JSON in non-interactive mode), including usage errors such as a missing `<agent_id>`, so stdout keeps only the text of the turn.
|
|
5
|
+
- stdout: the data, and the error JSON (with `--json` or in non-interactive mode; see below).
|
|
6
|
+
- stderr: notices, the login URL, the version notice, and errors for humans. The exception is a command whose stdout is the content: `agents run` without `--json` writes all its errors to stderr (as JSON in non-interactive mode), including usage errors such as a missing `<agent_id>`, so stdout keeps only the text of the turn; and `agents follow-ups run` without `--json`, when the result has `error`, prints the card on stdout and the error on stderr (with `--json`, stdout has only the `FollowUpRun`, which already carries `error`).
|
|
7
7
|
- `Warning: <message>` on stderr for each item of `warnings` in an API response, read from the top-level `warnings` and from a nested `version.warnings` (as in `agents create` and `agents update`) (also with `--json`, where stdout stays the untouched JSON). Without `--json`, the card on stdout does not repeat those `warnings`: each one is shown once, on stderr; use `--json` to read their other fields (such as `code`).
|
|
8
8
|
|
|
9
|
-
Without `--json`, lists print as a table and single items as `key: value` lines (an empty `changed_fields` shows as `changed_fields: []`; an empty `warnings` list and empty objects are hidden). Lists of agents, versions, skills and the like show a few columns and cut long text to the width of a terminal (the ID column is never cut, and piped output is not cut); `get` or `--json` shows every field. In a `get` card, nested objects are indented under their key; in a table cell they are one-line JSON. Lists of strings appear as `a,b` in a table cell; in a card they go one `- item` per line under their key, also with a single item, so a list never looks like a single value. `versions compare` prints one difference per line with one rule for every resource: a string longer than 120 characters, or a list of only text blocks (the prompt), shows its first 60 characters: `"<first 60 chars>…" (N chars)`; any other list or object is summarized as `<list, N items>` or `<object, N keys>` only when its JSON is longer than 120 characters, and a shorter one is printed whole (`[{"skill_id":"…","strategy":"pin"}] → […"latest"]`). When both values are objects and one of them is that long, the line names the top-level keys that changed instead (`tree: changed SKILL.md; added references/b.md; removed references/a.md`), up to 5 keys per group and then `(+N more)`. When both values are non-empty lists and one of them is that long, the line names the items that changed, were added or were removed (`tools: changed tool_b, tool_d; added tool_x`), with the same limit: each item is named by its `id` (or `skill_id`, `connection_id`, `name`, `type`) when every item has one and none repeats, and by its position otherwise (`changed [1]; added [2]`); same items in another order show as `same items, reordered`. Use `--json` for the full values. `--json` is never changed by any of this. Table columns follow the order in which keys appear, including columns that are `null` in every row. Control characters in values from the server (`\n`, `\t`, `ESC`...) are printed escaped (`\n`, `\x1b`), never raw: in tables, cards, errors, `next` lines and the labels of the questions. An empty list prints `No results.`
|
|
9
|
+
Without `--json`, lists print as a table and single items as `key: value` lines (an empty `changed_fields` shows as `changed_fields: []`; an empty `warnings` list and empty objects are hidden). Lists of agents, versions, skills and the like show a few columns and cut long text to the width of a terminal (the ID column is never cut, and piped output is not cut); `get` or `--json` shows every field. In a `get` card, nested objects are indented under their key; in a table cell they are one-line JSON. Lists of strings appear as `a,b` in a table cell; in a card they go one `- item` per line under their key, also with a single item, so a list never looks like a single value. `agents follow-ups run` prints the `reason`, `reasoning` and `messages` of `decider` and `agent` with their real line breaks, indented under their field (a one-line text stays on the line of its field); control characters and terminal sequences are escaped as everywhere else. `versions compare` prints one difference per line with one rule for every resource: a string longer than 120 characters, or a list of only text blocks (the prompt), shows its first 60 characters: `"<first 60 chars>…" (N chars)`; any other list or object is summarized as `<list, N items>` or `<object, N keys>` only when its JSON is longer than 120 characters, and a shorter one is printed whole (`[{"skill_id":"…","strategy":"pin"}] → […"latest"]`). When both values are objects and one of them is that long, the line names the top-level keys that changed instead (`tree: changed SKILL.md; added references/b.md; removed references/a.md`), up to 5 keys per group and then `(+N more)`. When both values are non-empty lists and one of them is that long, the line names the items that changed, were added or were removed (`tools: changed tool_b, tool_d; added tool_x`), with the same limit: each item is named by its `id` (or `skill_id`, `connection_id`, `name`, `type`) when every item has one and none repeats, and by its position otherwise (`changed [1]; added [2]`); same items in another order show as `same items, reordered`. Use `--json` for the full values. `--json` is never changed by any of this. Table columns follow the order in which keys appear, including columns that are `null` in every row. Control characters in values from the server (`\n`, `\t`, `ESC`...) are printed escaped (`\n`, `\x1b`), never raw: in tables, cards, errors, `next` lines and the labels of the questions. An empty list prints `No results.`
|
|
10
10
|
|
|
11
11
|
If stdout is closed early (for example `laburen agents list | head -2`), the CLI exits quietly. The exception is `agents run`: it keeps going and still writes the footer and the `continue:` line on stderr (a closed stderr also stops it quietly).
|
|
12
12
|
|
|
@@ -47,8 +47,8 @@ With `--json` or in non-interactive mode, the error goes to stdout as JSON:
|
|
|
47
47
|
- `reason`: the API `code` when the API failed, otherwise one of the CLI reasons below. `request_id` is only present for API errors (the key is omitted otherwise).
|
|
48
48
|
- `issues`: a validation error that names a field (`details.field`) has them too, as the API sends them: `[{ "field": "...", "message": "..." }]`. `field` is the exact place, for example `config.tools[3].url`; an unknown key gets one issue per key, with the key's name in `field` (`harness_type`).
|
|
49
49
|
- `choices`: only when an id is missing and the CLI cannot ask: up to 20 `[{ "id": "...", "name": "..." }]`, with one `next` per choice. The current one (the active version, the organization in use) also has `"current": true`.
|
|
50
|
-
- `details`: only when there are any: the API `details`, or for `network_error` the `cause` reported by the SDK.
|
|
51
|
-
- `next`: commands that fix the error, each with `command` and `when`. They are the real command you ran (path, ids and flags) with what is missing added, so you can run them as they are once the placeholders are filled in. A placeholder is a word in angle brackets: `<value>` is a value you type (a required flag that was missing, or a secret that was not copied), and `<id>`, `<version_id>` or `<agent_id>` is an id you get from a `list` or from the user. The value of a secret flag (`--token`, `-t`, `--refresh-token`, `--data`, `--headers`, `--config`, `--tool`, `--files`, `--value`, `--secret`, `--password`) is never copied, in any `next` or notice: it becomes `<value>` (for example `--headers <value>`), so fill it back in before running the command. In `--url` only the user and password and the values of the query and the fragment become `<value>` (`https://u:<value>@host/path?key=<value>#tok=<value>`); the rest stays so the command still points to the right server. When `npx` runs the CLI (`npx @laburen/delta-cli ...`), commands in `next`, and a `run laburen ...` inside `when`, start with `npx @laburen/delta-cli` instead of `laburen`. A `laburen` installed globally keeps `laburen` even when the program that runs it was started with npx. Every suggested command (in `next` and in notices) keeps the global flags you passed (`--org`, `--api-url`, `--global-config`, `--json`) unless it already has them, so it runs against the same API, folder and organization; a `--help` command does not get them, the `Created version <n> (not active)` notice
|
|
50
|
+
- `details`: only when there are any: the API `details`, or for `network_error` the `cause` reported by the SDK. In `agents run` they are the same with or without `--json`: an error in the middle of the live stream carries the same `details` as the JSON error of `--json`.
|
|
51
|
+
- `next`: commands that fix the error, each with `command` and `when`. They are the real command you ran (path, ids and flags) with what is missing added, so you can run them as they are once the placeholders are filled in. A placeholder is a word in angle brackets: `<value>` is a value you type (a required flag that was missing, or a secret that was not copied), and `<id>`, `<version_id>` or `<agent_id>` is an id you get from a `list` or from the user. The value of a secret flag (`--token`, `-t`, `--refresh-token`, `--data`, `--headers`, `--config`, `--tool`, `--files`, `--value`, `--secret`, `--password`) is never copied, in any `next` or notice: it becomes `<value>` (for example `--headers <value>`), so fill it back in before running the command. The exception is a reference to a file (`--data @body.json`, `--config @config.json`): it is copied as you typed it, since the file is not the secret and the command is ready to run (its content is never copied). In `--url` only the user and password and the values of the query and the fragment become `<value>` (`https://u:<value>@host/path?key=<value>#tok=<value>`); the rest stays so the command still points to the right server. When `npx` runs the CLI (`npx @laburen/delta-cli ...`), commands in `next`, and a `run laburen ...` inside `when`, start with `npx @laburen/delta-cli` instead of `laburen`. A `laburen` installed globally keeps `laburen` even when the program that runs it was started with npx. Every suggested command (in `next` and in notices) keeps the global flags you passed (`--org`, `--api-url`, `--global-config`, `--json`) unless it already has them, so it runs against the same API, folder and organization. The ones the CLI adds go right after the CLI name, before the subcommand (`laburen --org org_1 --api-url ... agents list`), which is where the CLI always reads them; the ones you typed in the command stay where you wrote them; a value that starts with `-` goes stuck to its flag (`--instructions=--help`); a `--help` command does not get them, the `Created version <n> (not active)` notice and the `continue:` line of `agents run` leave `--json` out (it only changes how this run printed), and the `next` that reruns a command without `--org` (after `organization_mismatch`) leaves `--org` out on purpose. Two `next` of an error never have the same command: when two ways of fixing the error give the same command (for example with a `--data` from a file, or written on the command line, which is shown as `<value>`), they come as one `next` whose `when` lists the options (`(1) ... (2) ...`).
|
|
52
52
|
|
|
53
53
|
A usage error from the argument parser (`unknown option ...`) never repeats a flag value, secret or not: `--any-flag=x` is shown as `--any-flag=<value>`.
|
|
54
54
|
|
|
@@ -66,40 +66,64 @@ CLI reasons: `login_required`, `login_cancelled`, `cancelled`, `missing_argument
|
|
|
66
66
|
- `agent_has_no_version` (exit 1): `agents tools add` on an agent with no versions; there is no config to add the tool to. `next` is `agents versions create <agent_id> --config @config.json` (a file name to create; the CLI does not mask it as `<value>`).
|
|
67
67
|
- `invalid_link`: `.laburen/link.json` is broken, or `.laburen` exists and is not a folder (in that case no command falls back to the `link.json` of a parent folder).
|
|
68
68
|
- `auth_lock_timeout`: another `laburen` held the credentials lock too long; `next` is `rm "<lock file>"`.
|
|
69
|
-
- `network_error`: the API could not be reached (or did not answer in time). The network timeout is fixed: there is no flag or environment variable to change it. Each request waits 30 seconds per attempt; a GET, or a call that carries an `Idempotency-Key`, is retried up to 2 times. `agents run` waits up to 630 seconds (10.5 minutes) for the API to answer, and without `--json` it also fails if the live stream sends nothing for 45 seconds.
|
|
69
|
+
- `network_error`: the API could not be reached (or did not answer in time), or the connection of an `agents run` stream was cut before the end (`details.cause` says which; then `next` is empty: the turn may still be running on the server, so check the thread before running it again). The network timeout is fixed: there is no flag or environment variable to change it. Each request waits 30 seconds per attempt; a GET, or a call that carries an `Idempotency-Key`, is retried up to 2 times. `agents run` waits up to 630 seconds (10.5 minutes) for the API to answer and `agents follow-ups run` up to 690 seconds, and without `--json` it also fails if the live stream sends nothing for 45 seconds.
|
|
70
70
|
|
|
71
71
|
Other reasons you may meet (API codes):
|
|
72
72
|
|
|
73
73
|
- `invalid_skill`: the skill does not follow the format; `details.reason` is `forbidden_path` (only `SKILL.md` and `references/**`), `invalid_character`, `invalid_frontmatter`, `missing_skill_md` (no `SKILL.md` among the files), `name_mismatch` (frontmatter `name` differs from the skill name), `limit_exceeded` or `no_active_version`.
|
|
74
74
|
- `api_error` with `status 413` ("Error response without the expected format"): the request body is over ~1 MB (Next's default limit). Send less per call, for example `threads messages create` in several batches.
|
|
75
|
-
- `
|
|
75
|
+
- `invalid_request` in `agents follow-ups run --messages`: a `{"type":"file"}` part (only text is accepted) comes with the generic message "The request does not match the expected format." and the reason in `issues[0]` (`field` `messages[0].parts[0]`). A message without text has `details.field` `messages[i]`, and `created_at` on some messages and not on others, or going backwards, has `details.field` `messages[i].created_at`. A `reasons[].description` over 500 characters in a version config is a generic `invalid_request` with the reason in `issues[0]` (`field` `config.follow_up.reasons[i].description`).
|
|
76
|
+
- `conversation_not_found`: the `memory.thread` (or the thread of a `threads` command, or the `--thread` of `agents follow-ups run`) does not exist or belongs to another organization or agent. For `agents follow-ups run` the `next` are the same command with `--messages @messages.json` (a conversation you write) and with another `--thread`; a thread of any channel works there.
|
|
76
77
|
- `channel_conversation_not_found`: `threads create --channel` with a `crm` or `chatwoot` `conversation_id` that does not exist in that account (`details.field` is `channel.conversation_id`, `details.channel_conversation_id` the id you sent); check the id there.
|
|
77
78
|
- `channel_provider_unavailable` (529): the CRM did not answer when `threads create` checked the conversation; retry.
|
|
79
|
+
- `decision_not_found` (404): the `<decision_id>` of `decisions get` does not exist or belongs to another organization; `next` is `laburen decisions list`.
|
|
80
|
+
- `invalid_request` with `details.reason` `unsupported_question_type` (the model does not support that question type, for example `box` with `gemini-decision-1`), `unsupported_state_media_type` (the model does not read that `media_type`) `question_out_of_limits` (a question is outside the limits of the model; `details.field` and `details.model` say which) or `box_needs_image` (a `box` question with no image in `state`; nothing is charged), `image_out_of_limits` (with `jev-1.14.0`, an image with a side outside 280 to 1568 px; `details.field`, `details.width` and `details.height` say which) (`decisions create`): change the model, the question or the image; the CLI does not check these.
|
|
81
|
+
- `evals_not_supported` (400): `decisions create --environment evals` with a model that has no evals account.
|
|
82
|
+
- `model_content_filtered` (400): `decisions create`: the model provider blocked the content; change the state or the question. `invalid_request` with `details.model` and `details.status`: the provider rejected the request (for example, it is over the provider limit); reduce the state. A turn (`agents run`, `agents follow-ups run`) whose request the provider rejects with a 400 gets the same `invalid_request` with `details.status`.
|
|
83
|
+
- `model_context_exceeded` (400, `invalid_request_error`, not retryable; `details.status` is the provider's status and, in follow-ups, `details.stage` the part that failed; `agents run`, `agents follow-ups run` and `decisions create`): the model provider rejected the request because the conversation (history, attachments and instructions) does not fit the context window of the model. In `agents follow-ups run` it also comes from the filter (`--mode decider` or `both`), with `details.stage: "decider"`; in `--mode both` a failure of the agent turn comes inside `error`, with `details.stage: "agent"`, like the other failures of the agent. In `agents run` and `agents follow-ups run` the `next` is `laburen models list`: pick one with a larger `context_window` for the model that did not fit (`follow_up.decider.model` when `details.stage` is `decider`, the model of the agent otherwise), or send a shorter conversation (with `--thread`, start a new one). In `decisions create` the state does not fit the decision model: send a smaller state (decision models are not in `models list`); the failed decision was saved, so the `next` is `laburen decisions get <decision_id>`. It never suggests running the same command again, because it fails the same way.
|
|
78
84
|
- `invalid_request` with `details.reason` `channel_not_connected` or `agent_not_linked_to_channel` (`threads create --channel`): the agent has no such number, CRM or Chatwoot connected, or the number or conversation belongs to another agent (`details.agent_id`). `next` points to the dashboard or to the same command with the owner's `--agent-id`.
|
|
79
|
-
- `conversational_mode_not_supported` and `legacy_agent_not_supported` (400): `threads` works only with agents of the new harness that are not in conversational mode.
|
|
85
|
+
- `conversational_mode_not_supported` and `legacy_agent_not_supported` (400): `threads` works only with agents of the new harness that are not in conversational mode. `agents run` and `agents follow-ups run` also return `legacy_agent_not_supported` for a legacy agent.
|
|
80
86
|
- `thread_resource_mismatch`: `memory.resource` is not the one that owns the `memory.thread`; send the same resource the thread started with.
|
|
81
|
-
- `ai_disabled_for_conversation`: a human took over the conversation, so the turn does not run. `next` is the same command without `--thread`: start a new conversation.
|
|
87
|
+
- `ai_disabled_for_conversation`: a human took over the conversation, so the turn does not run. The first `next` is the same command without `--thread`: start a new conversation. The second is `laburen threads update <thread_id> --ai-enabled`, which turns the AI back on in that thread (not on `chatwoot` or `crm` threads, where the AI state is managed in Chatwoot).
|
|
82
88
|
- `invalid_request`/`invalid_agent_config` on `config.knowledge.project_ids`: a project id does not exist in this organization; `next` is `laburen knowledge projects list`.
|
|
83
89
|
- An attachment that could not be downloaded says the HTTP status or network error and the host; the url must be public and downloadable without logging in.
|
|
84
90
|
- `mcp_server_unreachable` (400): the API could not connect to the MCP server when listing its tools; `details.connection_id` says which connection. Saving an agent `tools` filter with a MCP that is down does not fail with it: it saves and returns a `mcp_tools_unverified` warning. It is not retried automatically; check the URL and headers and run it again. It is raised only by the management API: a turn with a MCP that is down does not fail with it. `next` is `mcp connections versions list <connection_id>` (its HOST column shows where each version points).
|
|
85
91
|
- `resource_in_use`: a skill or MCP connection that agent versions still assign (or pin a version of); `details.agent_versions` lists them as `[{ agent_id, version_id, is_active }]` (no repeats), `details.agent_ids` the agents and `details.versions_count` how many versions. Versions are immutable: update the agent so the active version stops using it, delete the inactive versions that still assign it (never the active one), then retry (recipe in SKILL.md).
|
|
86
|
-
- `idempotency_key_in_progress`: the CLI only gets it on its own retry: the first attempt failed or took too long (a timeout), the CLI retried it with the same key, and the server is still processing that first request, which may finish and apply. The message says so. Do not rerun the command as it is: a rerun sends a new request (a new key) and can duplicate what the first one does. Wait, then check with `list`/`get` that it did not apply, and only then run it again. The `next` is that `list` (for a create or update); `agents run` has none, because the CLI cannot show a turn in progress.
|
|
92
|
+
- `idempotency_key_in_progress`: the CLI only gets it on its own retry: the first attempt failed or took too long (a timeout), the CLI retried it with the same key, and the server is still processing that first request, which may finish and apply. The message says so. Do not rerun the command as it is: a rerun sends a new request (a new key) and can duplicate what the first one does. Wait, then check with `list`/`get` that it did not apply, and only then run it again. The `next` is that `list` (for a create or update); `agents run` has none, because the CLI cannot show a turn in progress. `threads create` has no `list` either: with `--channel` (or `channel` in `--data`) its `next` is the same command, to run again after waiting, because it finds the same thread of that conversation; without a channel there is no `next`, like `agents run` (a rerun is a new request and can create a second thread or repeat `--messages`).
|
|
87
93
|
- `model_provider_auth_failed`: the model provider rejected the platform's credentials, even after the platform tried its fallback models; not retryable and not caused by your request. If it persists, contact support.
|
|
94
|
+
- `evals_not_supported` (400, its own code; `agents run --environment evals` and `agents follow-ups run --environment evals`): the model has no evals route (`details.model` says which, `details.field` is `environment`). Not retryable. The `next` is the same command without `--environment` (it runs on production; it needs only `query` unless the command has `--model`, `--instructions`, `--reasoning` or `--max-steps`, which need `write`) and `laburen models list` (to pick a `--model` with EVALS `yes`). If the command has `--thread` (as a flag, or `memory.thread` in a `--data` written on the command line), the thread is an evals one, so taking out only `--environment` would fail with `environment_mismatch`: the `next` are then the same command with `--model <model_id>` (the same thread, still in evals; if the version has the `thinking` tool, the model also needs THINKING TOOL `yes`), the command without `--thread` and `--environment` (a new conversation on production) and `laburen models list`. With a `--data` from a file or stdin the CLI cannot see the thread, so it uses these same `next`, and the `when` of the second one asks you to take `memory.thread` and `environment` out of that file. Permissions: `models list` needs `read` and `--model` needs `write`. A token with only `query` can use, without a thread, the command without `--environment`, and, with a thread, the command without `--thread` and `--environment` (only if the command has no `--model`, `--instructions`, `--reasoning` or `--max-steps`, which need `write`). In `agents follow-ups run` there is no `--model`: the model of the agent is `follow_up.model` or, without it, the `model` of the version, and which models are checked depends on `--mode` (`agent` and `both` check the one of the agent; `decider` and `both` check `follow_up.decider.model`), so the `next` are different: the same command without `--environment` (production), or, with `--thread` (an evals thread), the same command with `--messages @messages.json` instead of `--thread` and without `--environment`; then `laburen models list` (to pick a model with evals for `follow_up.model` and `follow_up.decider.model`, with `agents update`, or run a version that has them with `--version-id`).
|
|
95
|
+
- `invalid_request` with `details.reason` `environment_mismatch` (`agents run` and `agents follow-ups run`): the `--thread` was created with the other environment (`details.thread_environment` is `evals` or `null`, `details.conversation_id` the thread). The first `next` is the same command with the environment of the thread (`--environment evals`, or without `--environment` for a production thread). The second is the same command without `--thread`, which starts a new conversation (its `when` says in which environment). There is no `threads get` in the `next`: the error already says the environment. In `agents follow-ups run` there is only the first `next` (the same command with the environment of the thread): the second one would leave the command with neither `--thread` nor `--messages`.
|
|
96
|
+
- `invalid_request` with `details.reason` `channel_conversation_is_real` (`threads create --environment evals --channel`): a channel conversation is a real one. The `next` creates it without `--environment`, or without `--channel`.
|
|
97
|
+
- `invalid_request` with `details.reason` of an attachment (`--file`, or a file part in `--data`; `details.field` is the path of the part): `invalid_url` (not a valid URL), `not_https` (the URL must use https), `private_host` (a private or internal address), `too_large` (more than 20 MB), `unreachable` (the API could not download it; `details.status` is the HTTP status when there was a response; the URL must be public and downloadable without logging in) and `media_type_mismatch` (`details.declared` and `details.detected`: the content is of another type than the declared one; the CLI sets the type from the extension, so fix the file or use `--data` with the right `media_type`). A file declared with a type that has a known signature (image, PDF, Office) whose content is an HTML page also gives `media_type_mismatch`, with `details.detected` `text/html`: the URL usually points to a web page, not to the file. The same check applies to the file parts of the `--state` of `decisions create` (`details.field` is `state[i].media_type`). The images of `agents widgets images upload` use `details.field` `file` and `too_large` (more than 1 MB), `unsupported_media_type` (not PNG or JPG) or `media_type_mismatch` (see [Commands](commands.md#widgets)). The `next` is `--help` or the command to correct; none is retryable.
|
|
98
|
+
- `invalid_request` or `invalid_agent_config` with `details.reason` `thinking_tool_conflict` (`details.model`): the `thinking` tool and a model that reasons. `details.field` varies (`model`, `model_settings.reasoning`, `config.tools[i].type`): the CLI reads the `reason`. In a run, `details.field` is `model` when the request sent a `model`, and `model_settings.reasoning` only when the request sent just `--reasoning` and the saved version already had a model that reasons together with the `thinking` tool (a version saved before the current rule). The `next` of a run is, first, the same command without the flag that clashes (`--model`, or `--reasoning`; only if the command has it, as a flag or in a `--data` written on the command line; with a `--data` from a file or stdin the command is the same and the `when` says to take `model` (or `model_settings.reasoning`) out of that file first, then run it; in evals it only works if the model of the version has evals), then `agents versions list <agent_id>` (run a version without the tool with `--version-id`) and `laburen models list` (a `--model` with THINKING TOOL `yes`). When it happens saving, the `next` depends on the command (it has no `--version-id`): `agents tools add` → `laburen models list` only (then `agents update` with that model); when `details.field` is `config.followUp.model` (the model of the follow-up is the one that reasons) the `next` never changes the `model` of the agent: `agents tools add` → `laburen models list` (a model with THINKING TOOL `yes` for `follow_up.model`) and `agents get <agent_id>` (to read the saved `follow_up`, which an update replaces whole), and `agents create`, `agents update` and `agents versions create` → the same command, whose `when` says to set `follow_up.model` to a model with THINKING TOOL `yes` or drop the thinking tool, sending `follow_up` complete; `agents create`, `agents update` and `agents versions create` → the same command (in `agents update` the tool may be in the `--config` or already saved in the version the update starts from, so send `"tools"` in the `--config` without it; in the other two, drop it from the `--config`; or set a model with THINKING TOOL `yes`) and `laburen models list`, and for `agents update` last `agents tools remove <agent_id> <tool_id>` (only if the tool is already in the latest version and you changed just the model; then run the update again); `agents versions restore` → `agents versions list <agent_id>` and `laburen models list`.
|
|
99
|
+
- `invalid_agent_config` with the message "has no active version" (`agents run` and `agents follow-ups run`): the agent has no active version. The `next` are `agents versions list <agent_id>`, `agents versions activate <agent_id> <version_id>` and `agents versions create <agent_id> --config @config.json`. Any other `invalid_agent_config` (a version with a broken config) does not get these.
|
|
100
|
+
- `payment_overdue` (402): the organization has an overdue payment. Reading, deleting and `agents widgets rotate` work; creating, updating, `agents run`, `agents follow-ups run` and `decisions create` fail. Not retryable and there is no `next`: the account owner pays from the Laburen dashboard.
|
|
101
|
+
- `credits_exhausted` (402): the organization has no credits left. Only running fails (`agents run`, `agents follow-ups run` and `decisions create`). Not retryable and there is no `next`: buy credits from the Laburen dashboard.
|
|
102
|
+
- Not found (404, exit 1): `agent_not_found`, `config_version_not_found` (a version of that agent, also `--version-id` in `agents run` and `agents follow-ups run`), `skill_not_found`, `skill_version_not_found`, `mcp_connection_not_found`, `mcp_connection_version_not_found`, `token_not_found`, `widget_not_found` and `decision_not_found`. The resource does not exist, was deleted or belongs to another organization (or, for a version or a widget, to another parent). The `next` is the `list` that shows the ids that do exist (`laburen agents list`, `laburen agents versions list <agent_id>`, `laburen skills list`, `laburen skills versions list <skill_id>`, `laburen mcp connections list`, `laburen mcp connections versions list <connection_id>`, `laburen tokens list`, `laburen agents widgets list <agent_id>`, `laburen decisions list`).
|
|
103
|
+
- `base_version_mismatch` (409): with `--base-version-id`, someone created a version after the one you based your change on; `details.latest_version_id` is the latest. `agents tools add` and `remove` send it on their own and retry once. The `next` is `versions list`: read the latest and run the command again, or leave out `--base-version-id` to skip the check.
|
|
104
|
+
- `version_number_conflict` (409): another version took the same number at the same time and the server ran out of retries. Retryable: run the command again.
|
|
105
|
+
- `model_provider_rate_limited` and `model_provider_unavailable` (529; `agents run`, `agents follow-ups run`, `decisions create`): the model provider limited the rate or did not answer, after the platform tried its fallback models. Retryable: the CLI already retried; wait a little and run it again (a failed turn may not have been saved). A `model_provider_unavailable` with `retryable: false` (in `--json`, no retry by the CLI) means the provider failed with this request: running it again fails the same way; if the conversation is long, shorten it or use a model with a larger context.
|
|
106
|
+
- `model_response_malformed` (500): the model's answer lacked something the call needs (a tool call without a result, a filter answer out of format in `agents follow-ups run`, a decision out of format in `decisions create`). Run it again once; if it keeps failing, try another model and report the `request_id`.
|
|
107
|
+
- `tool_source_failed` (500): a tool source of the agent (an MCP connection, an integration) failed when the turn loaded its tools; `details.source` says which. It is retryable when the original error was. Check the source (`laburen mcp connections tools list <connection_id>`) and run it again.
|
|
108
|
+
- `tool_execution_failed` (400): a tool that calls a customer system got an error or no answer. In a turn this usually goes back to the model as the tool result and the turn goes on; as an error of the command it is rare. Check the tool's URL, headers and that system.
|
|
109
|
+
- `turn_deadline_exceeded` (500): the turn passed the server's time limit (10 minutes) and was cut. Ask for less, lower `--max-steps`, or check slow tools; the turn may have charged credits.
|
|
110
|
+
- `invalid_history` (500): the history built for the model was malformed; it is a server bug. Keep the `request_id` and report it; a new conversation (without `--thread`) works around it.
|
|
111
|
+
- Codes that never reach the CLI: `agent_unavailable`, `identity_required`, `invalid_identity_token` and `rate_limited` are of the browser chat of a widget; `invalid_origin` is of dashboard sessions with a cookie; `delivery_failed` is of the delivery to a channel, which this API does not do. `idempotency_key_reused` and `unsupported_trigger` should not happen through the CLI (it never reuses a key with a different body): if you get one, report it with the `request_id`.
|
|
88
112
|
- `internal_invariant_violation` (500): a bug on the server; keep the `request_id` and report it.
|
|
89
|
-
- In the SDK, an error that arrives inside the `agents.stream` stream carries its HTTP `status` and `
|
|
90
|
-
- `insufficient_permissions`: the token lacks a permission. They are independent (`query`, `read`, `write`, `admin`); deleting agents, skills
|
|
113
|
+
- In the SDK, an error that arrives inside the `agents.stream` stream carries its HTTP `status`, `shouldRetry` and `details`, like any `LaburenApiError`. The CLI error JSON has no HTTP status and no `retryable` (`agents run --json` uses `generate`, not the stream); its `details` are the same with or without `--json`.
|
|
114
|
+
- `insufficient_permissions`: the token lacks a permission. They are independent (`query`, `read`, `write`, `admin`); deleting agents, skills, MCP connections and widgets needs `admin`.
|
|
91
115
|
- `invalid_shell` (CLI, exit 2): `laburen completion` got a shell it does not support; the message lists them.
|
|
92
116
|
|
|
93
|
-
Some API errors come with `next` too: `organization_access_denied` → `laburen orgs list` (without the bad `--org`); `insufficient_permissions` → `laburen whoami` (shows the permissions of the token you used); `idempotency_key_in_progress` → the `list` of the resource the command creates or edits, to check before running again (none for `agents run`); a model or reasoning level the API does not offer (`invalid_request`/`invalid_agent_config` on `model`, `config.model.id` or `reasoning`, with a message that says it is not offered) → `laburen models list`; a run where the version has the `thinking` tool and the model reasons (`
|
|
117
|
+
Some API errors come with `next` too: `organization_access_denied` → `laburen orgs list` (without the bad `--org`); `insufficient_permissions` → `laburen whoami` (shows the permissions of the token you used); `idempotency_key_in_progress` → the `list` of the resource the command creates or edits, to check before running again (none for `agents run`); a model or reasoning level the API does not offer (`invalid_request`/`invalid_agent_config` on `model`, `config.model.id` or `reasoning`, with a message that says it is not offered) → `laburen models list`; a run where the version has the `thinking` tool and the model reasons (`details.reason` `thinking_tool_conflict`) → `laburen agents versions list <agent_id>` (run a version without the tool with `--version-id`) and `laburen models list` (pick a `--model` with THINKING TOOL `yes`); `evals_not_supported`, `environment_mismatch` and `channel_conversation_is_real` → the same command with the environment fixed (see above; with `environment` and `channel` inside `--data` there is no flag to drop: drop them from the `--data`); `idempotency_key_in_progress` of `threads create` with `--channel` → the same command again, after waiting (it finds the same thread); without a channel, none; `skill_name_taken` → `laburen skills list`; `mcp_connection_name_taken` → `laburen mcp connections list --search <name>` (the `--name` you passed); `resource_in_use` → with `details.agent_versions`, one `laburen agents versions delete <agent_id> <version_id>` per inactive version and one `agents versions get` per active one (never a delete of the active version); without it, one `laburen agents versions list <agent_id>` per id in `details.agent_ids`; `*_not_found` → the `list` of that resource (with the parent id filled in); `version_in_use` → `versions activate` of another version; a missing organization header (`invalid_request`) → `laburen orgs list` and the command you ran with `--org <id>`. Any other request the API rejects as invalid (`invalid_request_error`, such as `invalid_agent_config` or `invalid_request` with `issues`) without its own `next` gets the command you ran, with your ids and values (secrets as `<value>`), to fix the fields in `issues` and run again, plus `laburen <command> --schema` when the command has a request body (`--help` when it does not).
|
|
94
118
|
|
|
95
119
|
## Exit codes
|
|
96
120
|
|
|
97
121
|
| Code | Meaning |
|
|
98
122
|
|---|---|
|
|
99
123
|
| `0` | ok (also `--help` and `--version`) |
|
|
100
|
-
| `1` | the API or the network failed, login or a question cancelled, a resource that does not exist (as in the API: `*_not_found` from the API, `tool_not_found`, `organization_not_found`), nothing to pick from (`no_results`), an agent with no version to add a tool to (`agent_has_no_version`) |
|
|
101
|
-
| `2` | wrong usage: missing argument, unknown command, invalid flag value (also an empty `--org`, reason `invalid_flag_value`), `--data` that is not a JSON object or a missing `@file`, a `--dir` with a file that is not UTF-8 text (no request is sent), organization mismatch, broken `link.json` |
|
|
102
|
-
| `130` | Ctrl+C during `agents run` (the turn keeps running on the server) |
|
|
124
|
+
| `1` | the API or the network failed, login or a question cancelled, a resource that does not exist (as in the API: `*_not_found` from the API, `tool_not_found`, `organization_not_found`), nothing to pick from (`no_results`), an agent with no version to add a tool to (`agent_has_no_version`), `agents follow-ups run` whose result has `error` (the turn of the agent failed after the filter decided: the result still goes to stdout) |
|
|
125
|
+
| `2` | wrong usage: missing argument, unknown command, invalid flag value (also an empty `--org`, reason `invalid_flag_value`; a boolean flag of a command together with its `--no-` form, like `--ai-enabled --no-ai-enabled` or `--activate --no-activate` of `agents tools add|remove`, is `invalid_flag_value` too; `--environment` accepts only `evals` or `null`, and `null` is production, like leaving it out, in `agents run` and `threads create`), `--data` that is not a JSON object or a missing `@file`, a `--dir` with a file that is not UTF-8 text (no request is sent), organization mismatch, broken `link.json` |
|
|
126
|
+
| `130` | Ctrl+C during `agents run` (the turn keeps running on the server). With `--json` it ends the process without printing anything |
|
|
103
127
|
|
|
104
128
|
## Non-interactive mode
|
|
105
129
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@laburen/delta-cli",
|
|
3
|
-
"version": "0.2.0-canary.
|
|
3
|
+
"version": "0.2.0-canary.20",
|
|
4
4
|
"description": "Laburen CLI to manage agents from the terminal",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
},
|
|
28
28
|
"dependencies": {
|
|
29
29
|
"@clack/prompts": "1.8.1",
|
|
30
|
-
"@laburen/delta-sdk": "1.5.0-canary.
|
|
30
|
+
"@laburen/delta-sdk": "1.5.0-canary.20",
|
|
31
31
|
"@vercel/detect-agent": "1.2.7",
|
|
32
32
|
"commander": "14.0.3",
|
|
33
33
|
"picocolors": "1.1.1"
|