@lotics/cli 0.321.35 → 0.321.37

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.
@@ -33,7 +33,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
33
33
  | — | **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. |
34
34
  | — | **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. |
35
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`. |
36
- | `lotics run set_members '{"members": {"<email or member id>": {"role": "member", "name": "…"}}}'` | Invite to this workspace, rename, set the role in this workspace (`role`: `member` or `admin`; `null` takes the person out of it), set the organization role (`organization_role`: `co_owner` or `member`, the primary owner's), remove from the organization (`remove: true`) or restore members; `groups` keeps the member groups in the same call. An admin of this workspace or an organization owner; a workspace admin acts only on this workspace's people and renames or removes only a person wholly in workspaces they administer. 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
+ | `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. |
37
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. |
38
38
  | `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes — harvested records **only**, never files / external calls / notifications. **Not a rollback**; a rollback is structurally impossible here. A partial cleanup exits non-zero so a script cannot read it as success. |
39
39
  | `lotics file upload <file\|dir...>` (alias `lotics upload`) · `--stdin` · `--base64` · `--url <url>` | Upload files/directories. **The transport is chosen by size and is not a flag**: under 8 MiB the file is POSTed to `/v1/files`, several such files to a request up to half that route's 100 MiB cap; at or above it the CLI takes presigned part URLs and PUTs the bytes straight to object storage, so they never pass through the API. That threshold matches the AWS CLI's own `multipart_threshold`, and the number matters less than there being nothing to choose — one verb, any size, up to the 2 GiB a workspace may store. A large upload reads one part at a time, so memory stays flat regardless of file size, and a failure part-way abandons the parts already sent rather than leaving them billable and invisible. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
package/docs/design.md CHANGED
@@ -198,10 +198,9 @@ or its entity is read-only (`edit: false`); a stepped status never is, since Act
198
198
 
199
199
  Whatever goes wrong on a row and needs a person to act — a line delivered short, a price missing, a customer over their
200
200
  credit limit, a permit about to expire — is an issue its table declares in `records.issues`. A declared issue stands in
201
- every app that draws its row, with no app stating it: first on the row's line (`+N` the others), in the record's
202
- callout, in the List's filter of what needs checking with how many rows hold it, and those rows first. It never makes an
201
+ every app that draws its row, with no app stating it: first on the row's line (`+N` the others), in the record's callout (a count of child rows as pills on those rows), in the List's filter of what needs checking with how many rows hold it, and those rows first. It never makes an
203
202
  app draw a row it did not, and never shows on an `Outside` page. What needs no one's action is no issue: a stage is the
204
- status, a category a select.
203
+ status, a category a select. A record's callout says each issue by its label and what it means: a text issue's own sentence, a yes/no issue's field `description` — give a yes/no issue's field one, or its line shows the name alone.
205
204
 
206
205
  An issue is a promise that someone will act every time it stands: people and their agents see it on every row it holds.
207
206
  Declare one only where the owner confirms each flagged case is a problem; a rule that flags rows nobody fixes trains
@@ -23,7 +23,7 @@ Find the means in this order: `get_workspace` maps the workspace; `search` it by
23
23
 
24
24
  `get_workspace` with kind `member` lists the name and id of each person in this workspace; an organization owner passes `all: true` for everyone in the organization. An admin of the workspace also sees each one's email, organization `role`, `workspace_role` (`admin`, `member`, or null for a person outside it), `managed` and `sign_in_name`, and, on kind `app`, `knowledge` or `template`, `not_listed`: how many more they can reach, which `all: true` lists. Listed docs and templates carry `access`. An admin also reads the credit limits there. With kind `group`, everyone lists the groups of this workspace.
25
25
 
26
- `set_members` is an admin's of this workspace or an organization owner's: `members` is a map keyed by an email address, a member id or a managed member's sign-in name, and `groups` a map keyed by a group id, or by a group's name, which sets the group of that name or creates it (refused where several groups share it: key that entry by id). In `members`, `role` is the person's role in THIS workspace, `member` or `admin`; `role: null` takes them out of it, ending their shares here and passing what they own here to the caller. An email no member holds invites that person to the organization as a member, with `role` as their place here (`member` when omitted; the invitation email goes out). A current member's entry sets `name`, `role`, and `organization_role`: `co_owner` or `member`, which only the primary owner sets; a co-owner made a member passes what they own in workspaces they are not in to the primary owner. A removed member's entry restores them as an organization member in no workspace, and takes only `name`; only an organization owner restores. `remove: true` removes a member from the organization, or cancels the invitation pending to that address; removing a co-owner is the primary owner's. A workspace admin who is not an organization owner acts on this workspace's people only: never on an organization owner; renames or removes from the organization only a person in no workspace they do not administer; adds to this workspace only someone already in a workspace; an address invited elsewhere gets a place here on that invitation; `remove` on an invitation takes it out of this workspace, canceling it when no other workspace holds it. Each result says which changed: `added_to_workspace`, `workspace_role_changed`, `removed_from_workspace`, `organization_role_changed`, `removed`, `restored`. Sign-in names are compared in lowercase. A person adds a managed member and sets its password in Settings → Members. The primary owner is never removed, demoted or given a workspace role. A group belongs to this workspace and holds only its people. In `groups`, an entry sets `name`, `description` and the roster with `member_ids`, or with `add_member_ids` and `remove_member_ids` that leave the rest in place; a roster entry may be a key of `members`, so a person invited in the same call can join; `null` deletes the group. The whole input is checked before anything is written or sent; members are applied before groups, in the order given. A workspace admin's tool list carries `set_workspace` and `set_members`; a member's carries neither.
26
+ `set_members` is an admin's of this workspace or an organization owner's: `members` is a map keyed by an email address, a member id or, for a member who signs in by a name, that name, and `groups` a map keyed by a group id, or by a group's name, which sets the group of that name or creates it (refused where several groups share it: key that entry by id). In `members`, `role` is the person's role in THIS workspace, `member` or `admin`; `role: null` takes them out of it, ending their shares here and passing what they own here to the caller. An email no member holds invites that person into this workspace with `role` (`member` when omitted) and `name`, and the invitation email goes out; an address invited to another workspace gets a place here on that invitation. `role: null` on an address with an invitation pending here takes the invitation out of this workspace, canceling it when no other workspace holds it. A workspace admin who is not an organization owner never changes an organization owner, and adds only someone already in a workspace. Each result says which changed: `invited`, `invitation_canceled`, `added_to_workspace`, `workspace_role_changed`, `removed_from_workspace`. Renaming or removing a person, restoring a removed one, co-ownership, and a member who signs in by a name are a person's in Settings → Members: no tool takes them. The primary owner is never given a workspace role. A group belongs to this workspace and holds only its people. In `groups`, an entry sets `name`, `description` and the roster with `member_ids`, or with `add_member_ids` and `remove_member_ids` that leave the rest in place; a roster entry may be a key of `members`, so a person invited in the same call can join; `null` deletes the group. The whole input is checked before anything is written or sent; members are applied before groups, in the order given. A workspace admin's tool list carries `set_workspace` and `set_members`; a member's carries neither.
27
27
 
28
28
  `set_access` gives members or groups in the workspace, or everyone in it (`organization`), a role on resources. A share with someone outside the workspace, or with a group of another workspace, is refused as outside the workspace; an admin of the workspace adds them first with `set_members` (`role: "member"`), then the share is made again. Role `owner`, on one member, hands every resource listed to that member, who is in the resource's workspace and whom only the resource's owner or an admin may name; a call cannot share an app and hand it over together, an app handed to or from a member loses its sharing, and an automation is turned off until its new owner turns it on. Handovers are applied one resource at a time, and a failure part-way names what was already applied. `set_workspace` takes `credit_limits` (`workspace`, `apps` by app id, `members` by member id; a number is the daily ceiling in credits, `null` removes it and asks for approval).
29
29
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.321.35",
3
+ "version": "0.321.37",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {