@laburen/delta-cli 0.2.0-canary.11 → 0.2.0-canary.13
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/secret-notice.d.ts +4 -0
- package/dist/commands/secret-notice.js +21 -0
- package/dist/commands/secret-notice.js.map +1 -0
- package/dist/errors.js +42 -0
- package/dist/errors.js.map +1 -1
- package/dist/generated/commands.js +11 -1
- package/dist/generated/commands.js.map +1 -1
- package/dist/generated/schemas.js +5 -0
- package/dist/generated/schemas.js.map +1 -1
- package/dist/operations/tables.js +8 -0
- package/dist/operations/tables.js.map +1 -1
- package/dist/program.js +2 -2
- package/dist/program.js.map +1 -1
- package/docs/SKILL.md +7 -5
- package/docs/references/commands.md +83 -2
- package/docs/references/output-and-errors.md +6 -1
- package/package.json +2 -2
- package/dist/commands/token-notice.d.ts +0 -4
- package/dist/commands/token-notice.js +0 -13
- package/dist/commands/token-notice.js.map +0 -1
package/docs/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: laburen-cli
|
|
3
|
-
description: Use the `laburen` CLI to create, run and operate Laburen agents, skills, MCP connections and API tokens from the terminal, without the dashboard. Use when a task says "create an agent", "run or test an agent", "add a tool", "upload a skill", "connect an MCP", "version or activate an agent", or "create the worker token".
|
|
3
|
+
description: Use the `laburen` CLI to create, run and operate Laburen agents, skills, MCP connections, website chat widgets, threads (conversations) and API tokens from the terminal, without the dashboard. Use when a task says "create an agent", "run or test an agent", "add a tool", "upload a skill", "connect an MCP", "version or activate an agent", "put the agent on a website", "add a chat widget", "create a thread or conversation", "store messages before a turn", or "create the worker token".
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@laburen/delta-cli"
|
|
6
6
|
---
|
|
@@ -12,7 +12,7 @@ metadata:
|
|
|
12
12
|
|
|
13
13
|
## When to use
|
|
14
14
|
|
|
15
|
-
Use this skill when you need to manage Laburen resources from a terminal or from an AI agent: agents and their versions, skills, MCP connections, API tokens, and which organization you are working in.
|
|
15
|
+
Use this skill when you need to manage Laburen resources from a terminal or from an AI agent: agents and their versions, skills, MCP connections, website chat widgets, threads (conversations), API tokens, and which organization you are working in.
|
|
16
16
|
|
|
17
17
|
## How to use
|
|
18
18
|
|
|
@@ -48,6 +48,8 @@ Tool rules the API enforces (the wizard and `--schema` already follow them): eve
|
|
|
48
48
|
- Fields of each tool (`--schema` prints them): `http` takes `url` (required), `method`, `name`, `description`, `headers`, `body`, `query_parameters`, `path_variables` and `with_approval` (`true` = a person must approve each call); `thinking` takes `instructions` and `max_thoughts` (an integer, at least 1); `send_files` and `request_human` take nothing besides `type` and an optional `id`. Any other key fails with `invalid_request` (one issue per unknown key, with its name in `field`). `agents tools add --json` and `agents tools remove --json` print the agent with its new `version` inside.
|
|
49
49
|
- Items of the http tool's `headers`, `body`, `query_parameters` and `path_variables` are `{ "key", "value"?, "description"?, "is_user_provided"?, "required"?, "accepted_values"?, "type"? }` (only `key` is required), for example `{"key":"Authorization","value":"Bearer xyz"}`.
|
|
50
50
|
- `agents tools remove <agent_id> <tool_id>` takes the tool's `id` from `config.tools[]`; read it with `laburen agents versions get <agent_id> <version_id>` (or the latest version). Without a TTY it is required; with a TTY a picker lists the tools.
|
|
51
|
+
- `laburen agents widgets create <agent_id> --name <name>` puts the agent on a website: the response has the snippet ready to paste (`web_widget_script`), an `embed_iframe` and a `standalone_url` to try it. It also returns `identity_secret` **once** (same for `agents widgets rotate`): save it for the site's backend, which signs the visitor identity token with it. Details, flags and identifying visitors: [Commands](references/commands.md#widgets).
|
|
52
|
+
- `laburen threads create --agent-id <agent_id>` opens a conversation before any turn, with metadata, stored messages (`user` or `assistant`) or a link to an existing WhatsApp, CRM or Chatwoot conversation (`--channel`). Storing messages does not run the agent: run it after with `laburen agents run <agent_id> --thread <thread_id> "<message>"`. The response has `created`: `false` when it found the existing conversation of a channel (calling again appends the `messages` again). `threads get` needs `read`, the others `write`; `threads update` without metadata changes nothing. Replies of `agents run` on a channel thread do not go through the channel, and the model sees only the last `config.history.exchanges` exchanges (default 5, max 12). Details and errors: [Commands](references/commands.md#threads).
|
|
51
53
|
- `laburen tokens create` returns the secret once, in `value`. Save it right away. Revoked tokens stay in `tokens list` (there is no `tokens delete`). `tokens update <token_id> --description null` clears the description.
|
|
52
54
|
|
|
53
55
|
### Facts that are easy to get wrong
|
|
@@ -63,7 +65,7 @@ Tool rules the API enforces (the wizard and `--schema` already follow them): eve
|
|
|
63
65
|
|
|
64
66
|
Removing `thinking` first with `agents tools remove` and changing the model after also works, but makes two versions.
|
|
65
67
|
- **`--search <text>`** filters by name (case-insensitive) on `agents list`, `skills list`, `mcp connections list`, `knowledge projects list` and `tokens list`.
|
|
66
|
-
- **Permissions are independent**: `query`, `read`, `write` and `admin` do not include each other. A token with only `admin` cannot read. Deleting agents, skills
|
|
68
|
+
- **Permissions are independent**: `query`, `read`, `write` and `admin` do not include each other. A token with only `admin` cannot read. Deleting agents, skills, MCP connections and widgets needs `admin`; `insufficient_permissions` means the token lacks one.
|
|
67
69
|
- **`resource_in_use`** (deleting a skill or MCP connection that agents still use): `details.agent_versions` lists the blocking agent versions, `[{ agent_id, version_id, is_active }]` (no repeats); `details.agent_ids` lists their agents. Versions are immutable, so they are not edited. Recipe: (1) for an `is_active: true` entry, make the agent stop using the resource: `laburen agents update <agent_id> --skills '[]' --activate` (or `--mcp-connections '[]'`, or the list without that resource); (2) `laburen agents versions delete <agent_id> <version_id>` for each entry with `is_active: false`, and also for the version that was active before step 1 (it is inactive now and still assigns the resource; the new active version cannot be deleted); (3) retry the delete. Or delete the agent. The CLI `next` has one `agents versions delete` per inactive version and an `agents versions get` for the active one (after step 1, delete that one too, then retry).
|
|
68
70
|
- **`mcp_server_unreachable`** (exit 1, API code `400`): the API could not connect to the MCP server when you listed its tools (`details.connection_id` says which connection). Saving an agent `tools` filter with a MCP that is down does not fail: it saves and the response carries a `mcp_tools_unverified` warning. It is not retried automatically: check the URL and headers (`mcp connections versions list <connection_id>` shows the host of each version), then run it again. A run whose agent uses a MCP that is down does not fail with this error.
|
|
69
71
|
- **`issues[].field`** points to the exact place, like `config.tools[3].url`. When the error names a field (`details.field`), `issues[]` has it too.
|
|
@@ -178,10 +180,10 @@ Read the individual reference documents for details.
|
|
|
178
180
|
|
|
179
181
|
## Run an agent
|
|
180
182
|
|
|
181
|
-
`laburen agents run <agent_id> "<message>"` runs one turn. Always pass the message as an argument: without it the CLI reads stdin only if it starts sending within 500 ms (otherwise `missing_required`), and `-` reads stdin until it ends. stdout gets the answer text only; tool calls, sources and the footer go to stderr. Add `--json` to wait for the end and read one JSON object (`text`, `memory.thread`, `cost`, `tool_calls`...) on stdout: use it when you are an AI agent. To continue the conversation, pass `--thread <memory.thread>`. `--instructions`, `--model`, `--reasoning` and `--max-steps` replace the agent's settings for that run and need `write` permission. `laburen agents run --schema` prints the body schema (`<agent_id>` is optional only there). If the turn ends at the step limit without an answer, stderr says `Warning: The run stopped at the step limit (max_steps N) before a final answer.`: raise `--max-steps` or ask for less. Continuing that thread does not bring back the tool results of the cut turn unless the agent keeps tool calls in its history (`config.history.tool_calls.mode`, `off` by default; see [Commands](references/commands.md#run-an-agent)). `contact` in `--data` is not shown to the model. After a handoff to a human, the footer says `handed off to a human; the AI is off in this thread`: that thread cannot be continued (`ai_disabled_for_conversation`); start a new one (the `next` is the same command without `--thread`). A `--thread` belongs to one `--resource`: sending another `memory.resource` with an existing thread fails with `thread_resource_mismatch`; reuse the resource the thread started with. There is no command to list threads or read the messages of a conversation (the history is in the dashboard), and the contacts that `--resource` creates cannot be deleted with the CLI. A run costs credits, and Ctrl+C does not stop the turn on the server. If stdout is closed (`| head -1`), the turn keeps running and the footer and the `continue:` line still go to stderr.
|
|
183
|
+
`laburen agents run <agent_id> "<message>"` runs one turn. Always pass the message as an argument: without it the CLI reads stdin only if it starts sending within 500 ms (otherwise `missing_required`), and `-` reads stdin until it ends. stdout gets the answer text only; tool calls, sources and the footer go to stderr. Add `--json` to wait for the end and read one JSON object (`text`, `memory.thread`, `cost`, `tool_calls`...) on stdout: use it when you are an AI agent. To continue the conversation, pass `--thread <memory.thread>`. `--instructions`, `--model`, `--reasoning` and `--max-steps` replace the agent's settings for that run and need `write` permission. `laburen agents run --schema` prints the body schema (`<agent_id>` is optional only there). If the turn ends at the step limit without an answer, stderr says `Warning: The run stopped at the step limit (max_steps N) before a final answer.`: raise `--max-steps` or ask for less. Continuing that thread does not bring back the tool results of the cut turn unless the agent keeps tool calls in its history (`config.history.tool_calls.mode`, `off` by default; see [Commands](references/commands.md#run-an-agent)). `contact` in `--data` is not shown to the model. After a handoff to a human, the footer says `handed off to a human; the AI is off in this thread`: that thread cannot be continued (`ai_disabled_for_conversation`); start a new one (the `next` is the same command without `--thread`). A `--thread` belongs to one `--resource`: sending another `memory.resource` with an existing thread fails with `thread_resource_mismatch`; reuse the resource the thread started with. There is no command to list threads or read the messages of a conversation (the history is in the dashboard; see the `threads create` bullet above to create or link one), and the contacts that `--resource` creates cannot be deleted with the CLI. A run costs credits, and Ctrl+C does not stop the turn on the server. If stdout is closed (`| head -1`), the turn keeps running and the footer and the `continue:` line still go to stderr.
|
|
182
184
|
|
|
183
185
|
### References
|
|
184
186
|
|
|
185
|
-
- [Commands](references/commands.md) - every command with one example, `agents run`, the confirmation before deleting, picking a missing id and the questions of each `create`.
|
|
187
|
+
- [Commands](references/commands.md) - every command with one example, `agents run`, threads, widgets (install code, `identity_secret`, identifying visitors), the confirmation before deleting, picking a missing id and the questions of each `create`.
|
|
186
188
|
- [Auth and organizations](references/auth-and-organizations.md) - login, `LABUREN_TOKEN`, which organization is used, `link.json`, API URL, separate sessions, testing against a local dashboard.
|
|
187
189
|
- [Output and errors](references/output-and-errors.md) - stdout vs stderr, `--json`, `--paginate`, the error JSON with `next`, exit codes, colors.
|
|
@@ -159,7 +159,7 @@ Things to know when you run turns:
|
|
|
159
159
|
|
|
160
160
|
- `contact` is not shown to the model: it only fills in the profile of the contact that `memory.resource` creates. To give the model data about the user, use `--context`.
|
|
161
161
|
- The `continue:` line does not repeat `--resource`: the thread already knows its resource, and the server uses it.
|
|
162
|
-
- There is no command to list threads or to read the messages of a conversation: the history is seen in the dashboard. Keep the `memory.thread` of each run if you want to continue it.
|
|
162
|
+
- There is no command to list threads or to read the messages of a conversation: the history is seen in the dashboard. Keep the `memory.thread` of each run if you want to continue it. To open a thread yourself (with metadata, stored messages or a channel link), see [Threads](#threads).
|
|
163
163
|
- The contacts that `--resource` (or `memory.resource` with `contact` in `--data`) creates cannot be deleted with the CLI.
|
|
164
164
|
- A turn that stopped at `--max-steps` and is continued with `--thread`: by default the agent keeps no tool calls in its history (`config.history.tool_calls.mode` is `off`), so the results of the tools of the cut turn are not in the history and the model may call those tools again. To keep them, set the mode on the agent: `laburen agents update <agent_id> --config '{"history":{"tool_calls":{"mode":"all"}}}' --activate` (or `{"mode":"recent","turns":<n>}`; `exclude_tools` leaves some tools out). `history` is replaced whole, so send `exchanges` and `reasoning` too if you had changed them.
|
|
165
165
|
- `--version-id` needs only the `query` permission, also for a version that is not active: that is on purpose (the API contract says so), so a token that can only run agents can try a version before it is activated.
|
|
@@ -216,6 +216,87 @@ laburen mcp connections versions compare <connection_id> --from <version_id> --t
|
|
|
216
216
|
|
|
217
217
|
Headers of an MCP connection are an object, name to value: `--headers '{"Authorization":"Bearer x"}'` or `@headers.json` (not the list of `{ key, value }` of the http tool). `mcp connections versions create` without `--headers` keeps the headers of the latest version; `--headers '{}'` removes them. If the server cannot be reached, listing its tools fails with `mcp_server_unreachable` (400); check the URL and headers. Saving an `--mcp-connections` item with `tools` does not fail: it saves and warns with `mcp_tools_unverified`.
|
|
218
218
|
|
|
219
|
+
## Widgets
|
|
220
|
+
|
|
221
|
+
A widget puts an agent on a website as a chat. It belongs to an agent (an agent can have several, for example one per site) and the visitor talks to the agent's **active version**.
|
|
222
|
+
|
|
223
|
+
```sh
|
|
224
|
+
laburen agents widgets create <agent_id> --name "Acme site" --allowed-domains '["acme.com","*.acme.com"]'
|
|
225
|
+
laburen agents widgets list <agent_id> # table: ID, NAME, ENABLED, DOMAINS, ANONYMOUS, UPDATED; newest first
|
|
226
|
+
laburen agents widgets get <agent_id> <widget_id>
|
|
227
|
+
laburen agents widgets update <agent_id> <widget_id> --no-enabled # turn it off; --enabled turns it on
|
|
228
|
+
laburen agents widgets rotate <agent_id> <widget_id> # new identity_secret; the old one stops working
|
|
229
|
+
laburen agents widgets delete <agent_id> <widget_id> # needs admin; the snippet stops working, conversations stay
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Every response carries the code to install it, with the public token and the URL already set: `web_widget_script` (the `<script>` of the chat bubble: paste it in the site's `<head>` or before `</body>`), `embed_iframe` (an `<iframe>` that shows the chat inside a page, 400×600 by default: change `width`/`height`) and `standalone_url` (a chat page of its own; open it to try the widget). Without `--json` the snippet is printed with its line breaks escaped (`\n`), so do not copy it from there: read it with `--json`, for example `laburen agents widgets get <agent_id> <widget_id> --json | jq -r .web_widget_script`. `token` is public (it goes in the snippet).
|
|
233
|
+
|
|
234
|
+
`create` and `rotate` also return `identity_secret`, **only in that response**: without `--json`, stderr says "Save the `identity_secret` now: it will not be shown again." It is what your site's backend uses to sign the visitor's identity token (below); it never goes in the browser. `create` and `rotate` are sent once, never retried (they are not idempotent); `rotate` does not ask for confirmation.
|
|
235
|
+
|
|
236
|
+
Flags of `create` and `update` (`update` changes only what you pass; `--data` takes the whole body):
|
|
237
|
+
|
|
238
|
+
| Flag | Default | What it does |
|
|
239
|
+
|---|---|---|
|
|
240
|
+
| `--name` | (required in `create`) | Name of the widget, 1 to 100 characters |
|
|
241
|
+
| `--enabled` / `--no-enabled` | on | `--no-enabled` turns it off: the chat answers `widget_not_found`, as if it did not exist |
|
|
242
|
+
| `--allowed-domains` | `[]` | JSON list of sites that can embed it (up to 50); empty = any site. Full host (`www.acme.com` does not include `acme.com`), wildcard only at the start (`*.acme.com` covers subdomains, not `acme.com`), optional port (1 to 65535). A wildcard cannot cover a whole public suffix (`*.com`, `*.com.ar`, `*.co.uk`, `*.github.io`: the list is the Public Suffix List) or an IP. Stored in lowercase, without scheme, path or repeats. `localhost` and its subdomains are rejected: use `127.0.0.1`. An invalid one fails with `invalid_request` on `allowed_domains[i]` |
|
|
243
|
+
| `--allows-anonymous` / `--no-allows-anonymous` | on | `--no-allows-anonymous`: a visitor your site did not identify cannot chat (`identity_required`) |
|
|
244
|
+
| `--max-attachments-per-message` | `5` | Files per visitor message, 1 to 10 |
|
|
245
|
+
| `--visitor-rate-limit` | `null` | JSON `{"max_messages":20,"interval_seconds":60}` (up to 100000 messages and 30 days): cap per visitor; `null` removes it |
|
|
246
|
+
| `--limit-reached-message` | `null` | Text the visitor sees at the cap (1 to 500 characters); `--limit-reached-message null` goes back to the default text |
|
|
247
|
+
| `--appearance` | `{}` | JSON with `widget_color` (`#rrggbb`), `welcome_title` (up to 100), `welcome_tagline` (up to 200), `position` (`left`/`right`), `theme` (`light`/`dark`/`auto`), `launcher_icon_url` (https). `update --appearance` replaces the whole object: send every field you want to keep |
|
|
248
|
+
|
|
249
|
+
`allowed_domains` limits who can **embed** the chat (a `Content-Security-Policy: frame-ancestors` header), not who calls the API. Each domain is allowed over `https://`, except `127.0.0.1` and `0.0.0.0`, which use `http://`: a page served over `http` on a public domain (a staging without a certificate) cannot embed the chat.
|
|
250
|
+
|
|
251
|
+
When changes show: the chat reads the widget on every message, so `--no-enabled` or `delete` stops it right away (`widget_not_found`). The widget **page** (`standalone_url` and the iframe's page) keeps the domains for up to 60 seconds, so a new `--allowed-domains`, turning the widget off or deleting it can take up to a minute to show there.
|
|
252
|
+
|
|
253
|
+
The widget answers with the agent's active version. If the agent has none, the widget is created anyway, but every visitor message fails with `invalid_agent_config` ("has no active version") until you activate one (`laburen agents versions activate`).
|
|
254
|
+
|
|
255
|
+
**Identify visitors (optional).** Without it every browser is an anonymous visitor. If the site has its own login, its backend signs an identity token with the `identity_secret` for the logged-in user (for example from an endpoint the page calls with `fetch`), and the page passes it to the widget with `window.$laburen.identify({ token })` (it can run right after the snippet: the snippet queues the call until the widget script loads); the visitor is then linked to a contact of the organization (found or created by `user_id`). The token is a JWT HS256: the key is the UTF-8 bytes of `identity_secret`; `user_id` (non-empty string) and `exp` are required; `email`, `name`, `phone` and `custom_attributes` (an object of strings) are optional. In a Worker or Node backend, `signIdentityToken({ secret, userId, expiresIn? })` from `@laburen/delta-sdk/platform` builds it (see `docs/platform/guide.md` of `@laburen/delta-sdk`, section 14). A bad, expired or incomplete token makes the chat fail with `invalid_identity_token`. The CLI has no command to sign one: signing happens in the site's backend. Other snippet calls: `$laburen.reset()` (on logout), `$laburen.toggle(open?)` and `$laburen.setAttributes(text)` (up to 1000 characters of unverified context sent with the visitor's messages).
|
|
256
|
+
|
|
257
|
+
The CLI and the API do not read or answer the widget's conversations (that is in the dashboard), and the API the chat itself uses in the browser is internal.
|
|
258
|
+
|
|
259
|
+
## Threads
|
|
260
|
+
|
|
261
|
+
A thread is one conversation of an agent. `agents run` creates one for you; `threads` lets you create it first (the response is the thread plus `created` and the stored `messages`; `threads messages create` answers `type: "thread_messages_created"` with its `messages`), with your own data, stored messages, or a link to a customer conversation that already exists in WhatsApp, a CRM or Chatwoot.
|
|
262
|
+
|
|
263
|
+
```sh
|
|
264
|
+
laburen threads create --agent-id <agent_id> --metadata '{"plan":"pro"}' # a thread with metadata
|
|
265
|
+
laburen threads create --agent-id <agent_id> --resource customer-42 \
|
|
266
|
+
--messages '[{"role":"user","parts":[{"type":"text","text":"Hi"}]},{"role":"assistant","parts":[{"type":"text","text":"Hello!"}]}]'
|
|
267
|
+
laburen threads create --agent-id <agent_id> \
|
|
268
|
+
--channel '{"type":"whatsapp","phone_number_id":"<meta phone_number_id>","to":"<wa_id or BSUID>"}'
|
|
269
|
+
laburen threads get <thread_id> # read permission
|
|
270
|
+
laburen threads update <thread_id> --metadata '{"plan":"business","vip":null}'
|
|
271
|
+
laburen threads messages create <thread_id> --messages '[{"role":"assistant","parts":[{"type":"text","text":"Your order shipped."}]}]'
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
- **Permissions.** `threads get` needs `read`; `threads create`, `threads update` and `threads messages create` need `write`. `create` and `messages create` answer with ids and roles, not the content of the messages. A thread linked to WhatsApp does not show the number or the `to`, and `resource` is `null` unless you sent it. `threads update` without `--metadata` (or with `{}`) changes nothing and returns the thread as it is.
|
|
275
|
+
- **Size.** The body of a request is limited to ~1 MB (a bigger one answers 413, without the usual error format): for long histories, send several `threads messages create` batches. The metadata is sent whole in the prompt of every turn: ~600 KB is about 75k input tokens each turn.
|
|
276
|
+
- **History window.** The model sees only the last `config.history.exchanges` exchanges (default 5, max 12): in a longer loaded history the first messages and their files are left out. To raise it, publish a new agent version with a bigger `config.history.exchanges`.
|
|
277
|
+
- **Replies do not go to the channel.** `agents run` on a WhatsApp, CRM or Chatwoot thread does not send the answer through the channel: it comes back only in the API response. The channel delivers when the customer writes.
|
|
278
|
+
- **Messages.** Each one has the shape of the `messages` of `agents run`: `role` is `user` or `assistant` (never `system`) and `parts` are `text` or `file`; a `file` part is accepted only in a `user` message. Validation errors name the field in `issues[].field`: `parts: []` fails on `messages[i].parts`, an empty text on `messages[i]`. Nothing is stored.
|
|
279
|
+
- **Files.** Only `https` urls. They are downloaded and checked when the messages are saved, not when a turn runs: a 404, an `http` url or a `media_type` that does not match the content fails with `invalid_request` and the exact field (`messages[i].parts[j].url` or `.media_type`) in `issues[].field` and `details.field`, and **nothing is stored**: no new thread, no message, no metadata.
|
|
280
|
+
- **Storing messages does not run the agent.** To get an answer, run a turn on that thread: `laburen agents run <agent_id> --thread <thread_id> "<message>"`.
|
|
281
|
+
- **Metadata.** `update` merges by top-level key: the keys you send are set, the others stay, and a key sent as `null` is deleted. A nested object is replaced whole, so a `null` inside it is stored as `null` (it does not delete): `{"a":{"b":null}}` saves `a` as `{"b":null}`. On `create`, a top-level `null` is ignored. The metadata goes to the agent's prompt in every turn, so the model reads it and it costs tokens each time: the key `prompt` is put first as plain text (as JSON if its value is not text), the other keys go as JSON, and `scratchpad` is not shown.
|
|
282
|
+
- **Channel.** `--channel` links the thread to a conversation of a channel, so replies and follow-ups reach the customer. `laburen threads create --help` lists the forms:
|
|
283
|
+
- If the conversation of the channel already exists, `threads create` returns **that** thread (same `id`) instead of creating another: the metadata is merged as in `update` (`null` deletes a key) and the `messages` you send are appended at the end. Parallel calls with the same channel end in one thread. The response has `created`: `true` if this call created the thread, `false` if it found the existing one. **Repeating the call appends the `messages` again** (a template would end up repeated): send them once, or check `created` to decide. Metadata of parallel calls is merged by key; if two write the same key, the last one to reach the server wins. Parallel batches of messages stay contiguous, each in its own order.
|
|
284
|
+
- `whatsapp`: `phone_number_id` is the WhatsApp number of your organization connected to this same agent; `to` is the customer identifier Meta returned when the template was sent (`contacts[0].wa_id`, digits only: no `+` or spaces; or `contacts[0].user_id`, a BSUID in capitals as Meta returns it, like `AR.123456`).
|
|
285
|
+
- `crm`: `account_id` and `conversation_id` as the CRM reports them. The agent must have a CRM connected.
|
|
286
|
+
- `chatwoot`: `conversation_id` as Chatwoot reports it.
|
|
287
|
+
- For `crm` and `chatwoot` the conversation must already exist: send the template through the CRM or Chatwoot first, and take the id from there (it is not the contact id).
|
|
288
|
+
- A malformed `--channel` (a missing field, an unknown `type`) is a validation error: `invalid_request` with the field in `issues[].field`. `details.field` is only for business errors (channel, file, empty message). Channel errors:
|
|
289
|
+
- `invalid_request` with `details.reason` `channel_not_connected`: for `whatsapp`, the agent has no WhatsApp number `<phone_number_id>` connected; for `crm` and `chatwoot`, the agent has no CRM or Chatwoot connected. Connect it from the dashboard; the CLI `next` says so (running it again does not fix it).
|
|
290
|
+
- `invalid_request` with `details.reason` `agent_not_linked_to_channel`: the number belongs to another agent, or the existing conversation belongs to another agent. `details.agent_id` is the owner when there is a single one, and the CLI `next` repeats the command with that `--agent-id`.
|
|
291
|
+
- `channel_conversation_not_found` (404): for `crm` and `chatwoot`, that `conversation_id` does not exist in the account (`details.field` is `channel.conversation_id` and `details.channel_conversation_id` is the id you sent). Check the id there; the `next` says creating another thread will not fix it.
|
|
292
|
+
- `channel_provider_unavailable` (529): the CRM did not answer; retry.
|
|
293
|
+
- `conversation_not_found` (404) is only for the thread itself (`threads get/update/messages create`, or `--thread`); the `next` of the `threads` commands is `laburen threads create --agent-id <agent_id>`.
|
|
294
|
+
- `threads create` accepts `--data` or the flags like any other command; `--agent-id` cannot be an agent in conversational mode (`conversational_mode_not_supported`). `agents get` and the version config do not show that mode: it is set in the dashboard, so if you get that error, use another agent.
|
|
295
|
+
- **Resource and contact.** `--resource` on a thread without owner assigns it (in `threads create` with `--channel`, and in `agents run --resource`); a thread that belongs to another resource fails with `thread_resource_mismatch` (403). `contact` without `resource` is ignored, as in `agents run`; the model does not see `contact`.
|
|
296
|
+
- Deleting an agent deletes its threads: afterwards they give `conversation_not_found`.
|
|
297
|
+
|
|
298
|
+
The CLI and the API do not list threads, read their messages or delete them (a thread is deleted only when its agent is deleted), and threads of other channels (a widget, Instagram, MercadoLibre) give `conversation_not_found`.
|
|
299
|
+
|
|
219
300
|
## Tokens
|
|
220
301
|
|
|
221
302
|
```sh
|
|
@@ -226,7 +307,7 @@ laburen tokens update <token_id> --description null # clears the description
|
|
|
226
307
|
laburen tokens revoke <token_id>
|
|
227
308
|
```
|
|
228
309
|
|
|
229
|
-
`tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again.
|
|
310
|
+
`tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again (`agents widgets create` and `rotate` do the same for `identity_secret`).
|
|
230
311
|
|
|
231
312
|
## Account and organization
|
|
232
313
|
|
|
@@ -71,7 +71,12 @@ CLI reasons: `login_required`, `login_cancelled`, `cancelled`, `missing_argument
|
|
|
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
|
+
- `conversation_not_found`: the `memory.thread` (or the thread of a `threads` command) does not exist or belongs to another organization or agent.
|
|
76
|
+
- `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
|
+
- `channel_provider_unavailable` (529): the CRM did not answer when `threads create` checked the conversation; retry.
|
|
78
|
+
- `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.
|
|
75
80
|
- `thread_resource_mismatch`: `memory.resource` is not the one that owns the `memory.thread`; send the same resource the thread started with.
|
|
76
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.
|
|
77
82
|
- `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`.
|
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.13",
|
|
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.13",
|
|
31
31
|
"@vercel/detect-agent": "1.2.7",
|
|
32
32
|
"commander": "14.0.3",
|
|
33
33
|
"picocolors": "1.1.1"
|
|
@@ -1,4 +0,0 @@
|
|
|
1
|
-
import type { Command } from "commander";
|
|
2
|
-
import type { CliContext } from "../context.js";
|
|
3
|
-
/** Después de `tokens create` (sin --json) avisa en stderr que el `value` no se vuelve a mostrar. */
|
|
4
|
-
export declare function registerTokenNotice(program: Command, _ctx: CliContext): void;
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
import { extendOperation } from "../operations.js";
|
|
2
|
-
import { notice } from "../output.js";
|
|
3
|
-
/** Después de `tokens create` (sin --json) avisa en stderr que el `value` no se vuelve a mostrar. */
|
|
4
|
-
export function registerTokenNotice(program, _ctx) {
|
|
5
|
-
extendOperation(program, ["tokens", "create"], {
|
|
6
|
-
afterResult: (ctx, mode) => {
|
|
7
|
-
if (mode.json)
|
|
8
|
-
return;
|
|
9
|
-
notice(ctx, mode, "Save the token `value` now: it will not be shown again.");
|
|
10
|
-
},
|
|
11
|
-
});
|
|
12
|
-
}
|
|
13
|
-
//# sourceMappingURL=token-notice.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"token-notice.js","sourceRoot":"","sources":["../../src/commands/token-notice.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,qGAAqG;AACrG,MAAM,UAAU,mBAAmB,CAAC,OAAgB,EAAE,IAAgB;IACrE,eAAe,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE;QAC9C,WAAW,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YAC1B,IAAI,IAAI,CAAC,IAAI;gBAAE,OAAO;YACtB,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,yDAAyD,CAAC,CAAC;QAC9E,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}
|