@lotics/cli 0.289.0 → 0.290.0

package/dist/src/client.js

@@ -62,6 +62,9 @@ async function uploadParts(options) {
 var CLI_CAPABILITIES_HEADER = "x-lotics-cli-capabilities";
 var CLI_CAPABILITIES = ["docs-fallback"];
 
+// ../shared/src/proxy_upload_limit.ts
+var PROXY_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
+
 // src/client.ts
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -126,6 +129,7 @@ function getMimeType(filename) {
   return MIME_MAP[ext] ?? "application/octet-stream";
 }
 var MULTIPART_THRESHOLD_BYTES = 8 * 1024 * 1024;
+var PROXY_BATCH_MAX_BYTES = PROXY_UPLOAD_MAX_BYTES / 2;
 var LoticsRequestError = class extends Error {
   constructor(message, status, body) {
     super(message);
@@ -578,25 +582,37 @@ var LoticsClient = class {
     );
   }
   async uploadFiles(filePaths, options) {
-    const small = [];
+    const files = [];
+    const errors = [];
     const large = [];
+    let batch = [];
+    let batchBytes = 0;
+    const sendBatch = async () => {
+      const sent = batch;
+      batch = [];
+      batchBytes = 0;
+      try {
+        const result = await this.uploadFileBytes(sent);
+        files.push(...result.files);
+        errors.push(...result.errors);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(...sent.map((item) => ({ filename: item.filename, error: message })));
+      }
+    };
     for (let i = 0; i < filePaths.length; i++) {
       const absolutePath = path.resolve(filePaths[i]);
       const filename = options?.filenames?.[i] ?? path.basename(absolutePath);
       const { size } = await fs.promises.stat(absolutePath);
       if (size >= MULTIPART_THRESHOLD_BYTES) {
         large.push({ absolutePath, filename, size });
-      } else {
-        small.push({ bytes: await fs.promises.readFile(absolutePath), filename });
+        continue;
       }
+      if (batch.length > 0 && batchBytes + size > PROXY_BATCH_MAX_BYTES) await sendBatch();
+      batch.push({ bytes: await fs.promises.readFile(absolutePath), filename });
+      batchBytes += size;
     }
-    const files = [];
-    const errors = [];
-    if (small.length > 0) {
-      const result = await this.uploadFileBytes(small);
-      files.push(...result.files);
-      errors.push(...result.errors);
-    }
+    if (batch.length > 0) await sendBatch();
     for (const item of large) {
       try {
         files.push(await this.uploadLargeFile(item));

package/docs/cli_reference.md

@@ -31,7 +31,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | — | **The exit code reports the WORK, not just the call — for the two tools that RUN one.** `run_app_workflow` and `run_app_agent` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`) 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. |
 | `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. |
 | `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. |
-| `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` in one request, and several such files go in the same one; 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. |
+| `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. |
 | `lotics file download <file_id> [<path>]` · `-o <dir>` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` → fetch the presigned URL and write it where you asked. **The two spellings mean two different things, and neither is read by shape: the positional `<path>` is the FILE to write, `-o <dir>` is the DIRECTORY to save into.** That is `cp` and `curl -o`, so nothing here consults an extension. A named file is written as named, its parent created, overwriting what is there — the point of naming it is that the next command opens that exact path. A directory is created if missing and written into under the stored filename (the response's `Content-Disposition`), taking a free spelling beside a file of that name already there so a repeat download never clobbers the first; with no destination at all, that filename lands in cwd. Give the destination once — a positional and `-o` together is refused, as is a positional that names an existing directory or ends in a separator (`a directory goes in -o`). The first argument is a **file id**, so a path in that slot is refused rather than sent as an id. The written path goes to **stdout** (under `--json`, `{file_id, path, filename, stored_filename}`) and the narration to stderr, so a download pipes into whatever opens it. `lotics file download record <record_id> <field_key> [-o <dir>]` spreads every file on a record's file field over a DIRECTORY — there is no single file for N files to be. |
 | `lotics file list [--limit <n>] [--cursor <token>]` | The workspace's files, newest first — id, upload time, bytes, MIME type, filename on stdout, one per line (`--json` for the object). `GET /v1/files` with no `file_ids`. A file holding the content of a knowledge doc or template you cannot use is left out. **A page, not a dump**: the store only ever grows, so the last line prints the command for the next page and `next_cursor` is null on the last one. The cursor is opaque and keyset — pass it back as given — so an upload landing mid-sweep cannot make a walk skip or repeat a row. Every other file verb takes an id, so this is the only answer to "what is in here" short of reading Postgres. |
 | `lotics file delete <file_id>` | Archive a stored file, over the `delete_file` tool. **Refused while a record cell, a comment, a knowledge doc, a document template or a voice session still references it** — the refusal names the referents, so this is safe to try. The bytes are left in object storage; the row no longer serves them, which is what "deleted" means here. There is no `lotics delete`: the verb needs its noun. |

package/docs/workflows.md

@@ -6,9 +6,10 @@ Only the forms below are accepted; anything else is refused at save with the lin
 what to write instead. A save that succeeds may still return `warnings` — advisory hints such as a
 loop that may never end. Read them.
 
-The same grammar serves an automation, a table's lifecycle workflow and an app's workflow. Only an
-automation's source opens with a trigger declaration; a lifecycle workflow takes its trigger from its
-table and event, an app workflow from the app that calls it.
+The same grammar serves an automation, a table's lifecycle workflow and an app's workflow, and the
+expressions of a table check. Only an automation's source opens with a trigger declaration; a
+lifecycle workflow takes its trigger from its table and event, an app workflow from the app that calls
+it.
 
 ## Triggers
 
@@ -63,10 +64,10 @@ await send_email({
 | return | `return({ status: "success" \| "error", message: <expr>, field_errors: { ... }? });` |
 | validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |
 
-`return` is a call, not a JavaScript `return` statement. `validate` refuses the write when a check's
-`fail_when` is truthy; the check's `field_key` names the control its message lands on — a field of the
-trigger table in a lifecycle workflow; in an app workflow a declared input, or the `fld_` key of a
-field on a table the body names; in an automation it is not checked.
+`return` is a call, not a JavaScript `return` statement. `validate` ends the workflow with an error
+when a check's `fail_when` is truthy; the check's `field_key` names the control its message lands on —
+in an app workflow a declared input, or the `fld_` key of a field on a table the body names; a field of
+the trigger table in a lifecycle workflow; in an automation it is not checked.
 
 The name in `const x = await tool({...})` is the step's id; later expressions read its output as
 `x.records`, `x.id` and so on. A `// id: my_step` comment directly above a statement sets an explicit
@@ -122,8 +123,7 @@ step — summarize a record, classify, draft text.
 - `output` — `{ mode: "text" }` resolves to a string; `{ mode: "object", schema }` to a typed object.
 
 Only `x` comes back: in text mode `x` is the string itself, in object mode `x.field` reads a field the
-`schema` declares. The agent's own tool calls are not readable. An agent step cannot give a
-synchronous verdict, so a `before_*` lifecycle workflow refuses it.
+`schema` declares. The agent's own tool calls are not readable.
 
 ## Keys, not names
 
@@ -264,25 +264,6 @@ field when there is none. Use `coalesce(x, fallback)` only for a real fallback v
 
 ## Examples
 
-Refuse a duplicate before it is created (a `before_create` lifecycle workflow; the keys come from
-`get_table`):
-
-```
-const dup = await query_records({
-  table_id: "tbl_orders",
-  filters: { node_type: "group", logic: "and", children: [
-    { node_type: "condition", field_key: "fld_ref", operator: "equals", value: record["fld_ref"] },
-    { node_type: "condition", field_key: "fld_closed_at", operator: "is_empty" },
-  ]},
-});
-
-validate({ checks: [{
-  fail_when: size(dup.records) > 0,
-  field_key: "fld_ref",
-  message: "An open order already has this reference.",
-}]});
-```
-
 Compare a link by id. Display text is not unique, and a link reads as a list of ids — `==` against a
 string is a type error:
 
@@ -302,16 +283,14 @@ if (customer && includes(record["fld_customer"], customer.id)) {
 
 A lifecycle workflow is bound to one table and one event, and its source has no `on({...})` line:
 
-- `before_create` / `after_create` — a create, and a draft's submit (the moment it becomes a record).
-- `before_update` / `after_update` — every field edit, a draft's included: a `before_update` check
-  runs while someone fills in a draft, not only once it is submitted.
-- `before_delete` / `after_delete`.
+- `after_create` — a create, and a draft's submit (the moment it becomes a record).
+- `after_update` — every field edit, a draft's included.
+- `after_delete`.
 
-A `before_*` workflow runs before the write commits and may refuse it, with `validate` or
-`return({ status: "error", ... })`; its errors come back as field errors on the write. It cannot
-`wait`, `wait_for_event`, `wait_for_approval` or run an `agent` step. An `after_*` workflow runs after
-the commit, with every step; its errors are logged and never fail the write. An `after_update`
-workflow that writes its own table saves with a `loop_potential` warning: its write fires it again.
+A lifecycle workflow runs after the write commits, with every step; its errors are logged and never
+fail the write. What refuses a write before it lands is a table check (see **Table
+checks**). An `after_update` workflow that writes its own table saves with a `loop_potential`
+warning: its write fires it again.
 
 | reads | on |
 |---|---|
@@ -334,3 +313,63 @@ that cares about some events only skips the rest:
 
 In `if_source`, `runtime.change_origin` is the origin of the write that fired it; in the body, it is
 the workflow's own.
+
+## Table checks
+
+A table check is one condition its table's record writes must not meet, declared beside the table's
+`unique`. It is not a workflow: it reads the write and a few lookups and answers yes or no, so it
+cannot change data. It runs inside the write, on every create, update or delete it is `on`, whichever
+surface makes it — a person, the API, the CLI, an agent, a workflow. A refusal writes nothing and
+answers with the check's message, under its field when the check names one, and names the check.
+
+On the CLI or in chat, `set_table_check` creates one, or changes one when given its `table_check_id`
+and only the parts that change, and `remove_table_check` removes one. `get_table` lists a table's
+checks in the source they are written in.
+
+| part | what it holds |
+|---|---|
+| `on` | the writes it checks: any of `create`, `update`, `delete` |
+| `when` | optional expression; the check runs only on a write where it is truthy. It cannot read lookups. |
+| `lookups` | optional, by name, the rows to read: `{ table_id, filter, limit }`, the filter as `query_records` takes it, `limit` from 1 to 50 (50 when left out). A filter value may read the record. |
+| `fail_when` | expression; truthy refuses the write |
+| `message` | expression for the refusal's text — a fixed text is a quoted string |
+| `field_key` | optional; the field the refusal is shown under |
+
+Every expression is written in the grammar above and reads:
+
+- `record` — the record as it will be stored; on a delete, the record being deleted.
+- `prev_record` — on an update or a delete, the record before.
+- `changes` — on an update, the fields it changes.
+- `lookups.<name>` — in `fail_when` and `message`, the rows that lookup read.
+- `runtime.timezone`, `runtime.workspace_id`, `runtime.organization_id`, `runtime.change_origin` (the
+  write's origin), `runtime.triggered_by_member_id` (the member writing; null for a write no member
+  made), and `now()`.
+
+A check on several operations reads only what all of them carry, so one on creates and updates reads
+neither `prev_record` nor `changes`.
+
+A lookup reads with the access of the member who last saved the check, so saving one requires reading
+every table its lookups read. It reads committed rows: two writes at the same moment can each pass a
+check the other would fail, so values no two rows may share are the table's `unique`, not a check.
+
+A `when`, a lookup or a `fail_when` that cannot decide — it fails, or the write's time runs out —
+refuses the write. A draft is checked when it is submitted, as a create; its edits before that are
+not. A restored record is checked as a create. Cloning a table copies its checks to the member who
+clones it, and is refused when that member cannot read a table a check's lookup reads.
+
+One open order per reference, a row never counting against itself:
+
+```
+{
+  "table_id": "tbl_orders",
+  "name": "One open order per reference",
+  "on": ["create", "update"],
+  "when": "isNull(record[\"fld_closed_at\"])",
+  "lookups": {
+    "same_ref": "{ table_id: \"tbl_orders\", filter: { node_type: \"group\", logic: \"and\", children: [ { field_key: \"fld_ref\", operator: \"equals\", value: record[\"fld_ref\"] }, { field_key: \"fld_closed_at\", operator: \"is_empty\" } ] }, limit: 2 }"
+  },
+  "fail_when": "some(lookups.same_ref, (r) => r.id != record.id)",
+  "message": "\"An open order already has this reference.\"",
+  "field_key": "fld_ref"
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.289.0",
+  "version": "0.290.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {