@lotics/cli 0.321.90 → 0.321.92

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.
@@ -109,6 +109,17 @@ export interface ToolBreakingChange {
109
109
  message?: string;
110
110
  app_id?: string;
111
111
  }
112
+ /** A refused row of a write of several, named as the caller knows it: by the id it passed, else by its place (`records[3]`). */
113
+ export type ToolRefusedRow = ({
114
+ record_id: string;
115
+ row?: never;
116
+ } | {
117
+ row: string;
118
+ record_id?: never;
119
+ }) & {
120
+ message: string;
121
+ field_key?: string;
122
+ };
112
123
  export interface ToolExecuteResult {
113
124
  result: unknown;
114
125
  model_output?: string;
@@ -124,6 +135,8 @@ export interface ToolExecuteResult {
124
135
  * list from a refusing table check. */
125
136
  field_errors?: Record<string, string> | Record<string, string[]>;
126
137
  breaking_changes?: readonly ToolBreakingChange[];
138
+ /** Every row of the write the table refused, where `error` names a few per reason. */
139
+ refused?: readonly ToolRefusedRow[];
127
140
  }
128
141
  export interface ToolInfo {
129
142
  name: string;
@@ -78,7 +78,7 @@ function telemetryErrorMessage(status, parsed) {
78
78
 
79
79
  // ../shared/src/cli_capabilities.ts
80
80
  var CLI_CAPABILITIES_HEADER = "x-lotics-cli-capabilities";
81
- var CLI_CAPABILITIES = ["docs-fallback"];
81
+ var CLI_CAPABILITIES = ["docs-fallback", "answer-file"];
82
82
 
83
83
  // ../shared/src/proxy_upload_limit.ts
84
84
  var PROXY_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
@@ -7,7 +7,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
7
7
  | `lotics` / `lotics --help` | Show full help: capabilities, the verb list (§ COMMANDS), flags, config. `lotics <verb> --help` prints that verb's entries alone (`lotics app --help`, `lotics file download --help`); `lotics report --help` prints the report frame. |
8
8
  | `lotics auth login` | Sign this terminal in, on a machine holding no key; a person with no account creates one on the page it opens. It takes no argument and sends no mail. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>` — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code, pick the organization and press Confirm. A person with no account creates one there, by email and a password or with Google: the page shows the code beside the button, and one press creates the account and its first workspace and signs the terminal in; creating the account accepts the Terms and Privacy Policy. A signed-in account with no workspace gets one button that creates the workspace and signs the terminal in. On a private instance, whose people arrive by invitation, the page sends a signed-out person to sign in. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `docs` among them — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
9
9
  | — | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |
10
- | — | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: "outcome_unknown"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code` and `request_id` where the error has them. |
10
+ | — | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: "outcome_unknown"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code`, `request_id`, `field_errors`, `breaking_changes` and `refused` where the error has them; `refused` is every row a write of several had refused, where `error` names five per reason: `{record_id, message, field_key?}` for a row named by the id the call passed, `{row, message, field_key?}` (`records[3]`) for one named by its place. |
11
11
  | `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
12
12
  | `lotics auth web` | Send a magic link email to access the web app (requires auth) |
13
13
  | `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key — read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |
@@ -31,6 +31,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
31
31
  | — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `set_workflow`. A command exists only for work that touches a local file: `app apply`, `app create --custom`, `app pull`, `app deploy`. |
32
32
  | — | **An app's queries and workflows take more than their params and inputs** (`lotics docs agent_surface`). `run_app_query '{"app_id","alias","params"}'` also takes `filters` and `sort` over the query's output columns, `fields` (the columns to return), `count` with `count_by` or `count_where`, `aggregate`, `limit` (200 rows at most; 50 where none is stated) and `cursor`, and `runs` — up to 20 reads in one call, each `{"alias", …}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {"key", …narrowing}` instead of the read arguments makes the file an app's Export makes (`lotics docs agent_surface`). `run_app_workflow '{"app_id","alias","inputs"}'` also takes `dry_run: true` — a rehearsal on the real inputs, nothing written or sent; the answer is what the run would return, with the reads it made under `dry_run.reads`, the calls it would make under `dry_run.writes` and the papers it rendered under `dry_run.papers` and the parts of the answer it could not say under `dry_run.unpredicted`; a workflow no dry run is offered of answers `status: "not_previewed"` — and `runs` — up to 50 runs in order, the first refused, failed or not previewed ending the call, an input `{"from_run": <index>, "path": "data.<key>"}` reading an earlier run's answer. |
33
33
  | — | **The exit code reports the WORK, not just the call — for the tool that RUNS one.** `run_app_workflow` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`, or `not_previewed` — a dry run asked for and not given) exit non-zero and print `<tool> → <status>: <message>` to stderr, so `lotics run … && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE — an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` is data, and exits 0. |
34
+ | `lotics run <tool> '<json>'` with `as_file: true` | An answer that names its own file (`_file`) is saved as that file, whole JSON, where the command runs, or in `-o <dir>`; the path prints after the answer (on stderr under `--json`). The same call names the same file, so running it again replaces it. |
34
35
  | `lotics run <tool> '<json>' -o <dir>` | Also save every **signed link** the answer carries — an object with a `url`, a `filename` and the `expires_at` its signature ends at, at any depth, such as `screenshot_app`'s images. Each is fetched into `<dir>` (created if missing) under its `filename`, taking a free spelling beside a file of that name already there, and a link's `snapshot` text is written beside it as `<name>.txt`. The written paths follow the answer on **stdout**, one per line (on stderr under `--json`, whose stdout stays the one object). A link is signed for an hour; one the store no longer serves exits non-zero. A workspace file states no `expires_at` and is left to `lotics file download`. |
35
36
  | `lotics run set_members '{"members": {"<email or member id>": {"role": "member", "name": "…"}}}'` | Invite to this workspace (`name` is the name the invitation carries) or set a person's role in it (`role`: `member` or `admin`; `null` takes the person, or the invitation pending to that address, out of it); `groups` keeps the member groups in the same call. An admin of this workspace or an organization owner. Renaming or removing a person, restoring one, co-ownership and a member who signs in by a name are a person's in Settings → Members, and no tool takes them. The whole input is checked before an email is sent. A member's `lotics tools` lists neither `set_members` nor `set_workspace`. View-as is the web app's preview alone; the CLI acts as the signed-in member. |
36
37
  | `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |
@@ -60,7 +60,7 @@ A stored text is changed by `edits`, never sent whole again: `set_workflow` (wit
60
60
 
61
61
  A long text not stored yet rides a file. `set_workflow` takes `source_file_id` in place of `source`, `set_knowledge` takes `content_file_id` in place of `content`, and `set_template` takes `template_file_id` in place of an html or email `template`: write the text where you work, upload it with `upload_file` (`files`), and pass the `file_id` the upload answers.
62
62
 
63
- Many rows come as a file. Over MCP, `query_records` with `as_file: true` sends the page as an embedded JSON file and lists no rows. The file is the answer whole: `records`, each with `record_id`, `data` and `display` keyed by field alias, so code reads every row. Without a `limit` it takes the page maximum of 1,000 rows; `has_more` and `offset` page past it. On the CLI, `lotics run query_records '<json>' --json` prints the same answer.
63
+ Many rows come as a file. `query_records` with `as_file: true` sends the page as a JSON file and lists no rows: over MCP an embedded file, on the CLI a file `lotics run` saves where it runs (or in `-o <dir>`) and names. The file is the answer whole: `records`, each with `record_id`, `data` and `display` keyed by field alias, so code reads every row. Without a `limit` it takes the page maximum of 1,000 rows; `has_more` and `offset` page past it.
64
64
 
65
65
  Many rows go back as a file too. `create_records` and `update_records` take `rows_file_id`: a JSON file holding the call's per-row keys, in place of stating them. Everything else stays in the call: `table_id`, `dry_run`, `row_op`, `return_fields`.
66
66
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.321.90",
3
+ "version": "0.321.92",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {