@lotics/cli 0.275.0 → 0.277.0

package/docs/workflows.md

@@ -0,0 +1,336 @@
+# Workflows — the steps a workflow runs
+
+A workflow is written as a strict subset of JavaScript. The source is never run as JavaScript: a
+save parses it into steps, type-checks it against what its trigger supplies, and stores the steps.
+Only the forms below are accepted; anything else is refused at save with the line, the column and
+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.
+
+## Triggers
+
+An automation answers an event outside the records: a schedule, a webhook, an inbound email. A
+reaction to a record being created, updated or deleted is a table lifecycle workflow (see
+**Table lifecycle workflows**).
+
+```
+on({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });
+```
+
+Every source below is typed, so a misspelled member is refused at save rather than read as nothing.
+All three carry `trigger.trigger_id`.
+
+| trigger | required config | what the body reads |
+|---|---|---|
+| `recurring_schedule` | `cron_expression` | `runtime.timezone`; the current time is `now()` |
+| `receive_webhook` | `secret`? | `trigger.method`, `trigger.headers[...]`, `trigger.query[...]`, `trigger.body` (any JSON, or raw text when the request is not JSON), `trigger.received_at` |
+| `receive_gmail_email` / `receive_outlook_email` | `connected_account_id`, `filter` | `trigger.email_id`, `trigger.from`, `trigger.to`, `trigger.cc`, `trigger.bcc`, `trigger.subject`, `trigger.date`, `trigger.body` (plain text), `trigger.reply_to`, `trigger.in_reply_to`, `trigger.attachments` (file refs — assign them straight to a files field). One type serves both providers, so `labels`, `thread_id`, `importance` and `conversation_id` are not readable. |
+
+A whole automation:
+
+```
+on({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });
+
+const open = await query_records({
+  table_id: "tbl_tickets",
+  filters: { node_type: "condition", field_key: "fld_status", operator: "has_any_of", value: ["opt_open"] },
+});
+await send_email({
+  to: "team@example.com",
+  subject: "Weekly digest",
+  body: `${size(open.records)} tickets open as of ${formatDate(now(), "YYYY-MM-DD")}.`,
+});
+```
+
+## Steps
+
+| step | syntax |
+|---|---|
+| tool call, kept | `const <id> = await <tool>({ ...inputs });` — also `let x = await …` and `x = await …` |
+| tool call | `await <tool>({ ...inputs });` |
+| agent | `const <id> = await agent({ instructions, input, tools, model, output });` — see **An agent step** |
+| app agent | `const <id> = await app_agent({ alias: "<agent alias>", input: { ... } });` — runs one of the app's declared agents, in an app workflow only, and resolves to its declared outputs or its final text. `wait: false` only starts the run and resolves to `{ run_id }`; the run's failure is then its own, not the workflow's. Refused in a run an agent started. |
+| bind | `const <id> = <expression>;` — evaluated once; later steps read `<id>`. Bind any expression used twice. |
+| if / else | `if (<expr>) { ... } else { ... }` — `else` optional, `else if` chains allowed |
+| switch | `switch (<expr>) { case "X": { ... } default: { ... } }` — string cases only, no fallthrough |
+| for | `for (const <name> of <expr>) { ... }` |
+| wait | `await wait({ duration_in_minutes: 5 });` |
+| wait for an event | `await wait_for_event({ event_type: "webhook", event_ref: <expr>, timeout_in_minutes: 60 });` |
+| wait for an approval | `await wait_for_approval({ approvers: <expr>, prompt: <expr> });` — see **Waiting for an approval** |
+| 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.
+
+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
+id; any other `//` comment there becomes the step's description.
+
+**`await` inside a statement** runs the call as its own step first, then reads its output where it is
+written: `size((await query_records({...})).records)`, an `if` test, a `return` value, a `for-of`
+iterable, a tool input. `const x = c ? await t({...}) : null;` is stored as the `if` it means. An
+`await` that would run on some paths only — inside `&&`, `||`, `??`, `?.`, a nested ternary, a loop
+test, a `validate` check — is refused; write the `if`.
+
+**Names are block-scoped, as in JavaScript** — `const`, `let`, loop items and `catch (e)`: sibling
+blocks may reuse a name and an inner block may shadow an outer one. A local may take a helper's name
+(`const size = 3;`), but calling `size(...)` while it is in scope is refused. Tool names, the reserved
+roots, `linked` and `_s` followed by digits cannot be bound.
+
+### Waiting for an approval
+
+`wait_for_approval` is the wait worth binding — `wait` and `wait_for_event` carry nothing to read.
+Bind it to branch on the decision:
+
+```
+const approval = await wait_for_approval({
+  approvers: record["fld_approvers"],
+  prompt: `Approve the quote for ${record["fld_name"]}?`,
+});
+
+if (approval.status == "approved") {
+  // the approved path
+} else {
+  // the rejected or timed-out path; approval.decision_comment says why
+}
+```
+
+It resolves to `{ status: "approved" | "rejected" | "timed_out", decided_by: MemberId | null,
+decided_at: ISO string, decision_comment: string | null }`.
+
+`approvers` takes a bare member id (`"mbr_…"`), a bare group id (`"grp_…"`) or a full principal
+(`{ type: "member_group", id: "grp_x" }`), alone or in a list — so a member field's value passes as it
+is.
+
+### An agent step
+
+`const x = await agent({ instructions, input, tools, model, output });` runs a model with tools as one
+step — summarize a record, classify, draft text.
+
+- `instructions` — a fixed string.
+- `input` — an object literal; its fields are expressions, evaluated and handed to the model (`{}` for
+  none). It is the ONLY workflow data the agent sees: read `record`, prior steps, `runtime` or the loop
+  item here, never inside `instructions` or `tools`, which are fixed literals and read no binding.
+- `tools` — the names of the tools it may call.
+- `model` — optional; omit it to follow the platform's default model.
+- `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.
+
+## Keys, not names
+
+1. **Fields and options are named by key.** A field reads as `record["fld_status"]`, an option as
+   `"opt_done"`, a linked field as `linked(record["fld_customer"])[0]["fld_name"]`. `get_table` lists
+   each field's `key` and each option's `key`; a display name is refused at save with the key to use.
+2. **`==` against a multi-select means "includes".** `record["fld_tags"] == "opt_urgent"` on a
+   multi-select is stored as `includes(record["fld_tags"], "opt_urgent")`; either spelling works.
+3. **Text renders labels.** Inside a template or a text tool input, a select, member or link value
+   renders its display text: `` `${record["fld_status"]}` `` writes "Done", not `opt_done`.
+
+## What an expression reads
+
+- `record` — the trigger record (on an update, the record as it now stands).
+- `prev_record` — the record before the change, same shape (updates and deletes only).
+- `changes` — the fields an update changed, a PARTIAL map: `changes["fld_x"]?.next_value` and
+  `?.prev_value`, the `?.` required (updates only).
+- `trigger` — what a non-record trigger carries (see **Triggers**). `trigger.data`,
+  `trigger.prev_data` and `trigger.changes` are the same three roots spelled long; a saved body reads
+  back in the short form.
+- a loop's item name, and `index`, the iteration's 0-based index.
+- `<step id>` — an earlier step's output (`dup.records`).
+- `runtime.timezone`, `runtime.workflow_id`, `runtime.execution_id`, `runtime.workspace_id`,
+  `runtime.organization_id`, `runtime.change_origin`, `runtime.triggered_by_member_id`. The current
+  time is `now()`.
+
+## Paths
+
+- `record.fld_x` and `record["fld_x"]` read a field; `[n]` reads a list's n-th item.
+- A path may start at an awaited call: `(await get_record({...})).data["fld_x"]`. It may not start at a
+  helper's result — `first(found.records).id` is refused; bind `first(found.records)`, then read it.
+- A record reads in its declared shape wherever it comes from — the trigger, a tool result, a `let`, a
+  callback parameter: a single select or member as its key or null, a link as its ids. (The record
+  tools called outside a workflow return the stored arrays instead.)
+- `linked(record["fld_link"])[n]["fld_x"]` fetches the n-th linked row and reads a field of it; bare
+  `linked(record["fld_link"])` is every linked row, one fetch per row. Its argument is a path ending on
+  a link field and carries the guard: `linked(record?.["fld_link"])[0]`.
+- `changes["fld_link"]?.next_value` is the same list of ids; `linked()` over a change is refused —
+  read `linked(record["fld_link"])` or `linked(prev_record["fld_link"])`.
+
+## Operators and statements
+
+Operators in JavaScript precedence: `? :`, `||`, `??`, `&&`, `== !=`, `< <= > >=`, `+ -`, `* /`, prefix
+`! -`.
+
+- `??` is `coalesce(left, right)`; `?.` reads through a null (`a?.b`, `a?.[0]`, and `s?.trim()` for the
+  method names listed under **Helpers**). `x?.()` is refused: helpers and tools are not values.
+- Templates use backticks and `${...}`.
+- Destructuring — `const { fld_status, fld_name } = record;` binds each name. Renames
+  (`{ fld_status: s }`), quoted keys (`{ "fld_ref": ref }`), array patterns with holes
+  (`const [first, , third] = xs;`) and defaults (`{ fld_note = "" }`, which apply on null too) work on
+  `const`, `let` and `for (const { id } of rows)`. A tool result destructures directly:
+  `const { records } = await query_records({...});`. `const a = 1, b = 2;` declares both. Nested
+  patterns and rest are refused.
+- Spread — `[...a, b]` and `{ ...a, b: 1 }` (later keys win). Refused inside a tool input: bind the
+  merged value first and pass the binding.
+- Shorthand — `{ table_id }` is `{ table_id: table_id }`.
+- `xs.push(a, b);` appends, also on a key (`o.items.push(v)`); `o.a.b = v;` sets a nested key;
+  `x ??= v`, `x ||= v` and `x &&= v` assign. A `const` may be pushed to or have a key set, as in
+  JavaScript; a loop item is read-only.
+- `undefined` is the same value as `null`. `=== undefined` and `!== undefined` are refused, since they
+  cannot tell a missing key from null: test `isNull(x)`, or `includes(keys(o), "k")` for whether a key
+  was sent.
+- A filter node may leave out `node_type` when its keys say which it is: `field_key` / `operator` /
+  `value` a condition, `logic` / `children` a group, `path` / `condition` a traversal.
+- `function name(p = <default>) { return <expr>; }` — top level only, expanded at every call (a call
+  may come before it). Every parameter needs a default, which gives it its type; the body is one
+  `return <expr>;` reading only its parameters, helpers and the reserved roots — never the caller's
+  names, nor `index`. No recursion; a function never called is refused. A body read back shows the
+  expression at each call, not the `function`.
+
+**try / catch.** `try { ... } catch (e) { ... }` catches a tool error or an expression error inside the
+body; `e` is `{ message, type, step_id?, detail? }`. A failed `validate` and a `return` are not
+errors — they end the workflow — and a step that runs after a wait inside the `try` is outside it.
+`finally` is refused: put always-run steps after the `try`.
+
+**Loops.** `for-of`, `while (cond) { ... }`, `do { ... } while (cond);` and
+`for (let i = 0; i < n; i++) { ... }`, each capped at 10,000 iterations. `break;` and `continue;` act
+on the innermost loop; labels and `for-in` are refused.
+
+**`let`.** `let x = <expr>;` declares a block-scoped variable; the initializer is required
+(`let x = null;`). Reassign with `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `??=`, `++` and `--`. Re-declaring in
+the same block is refused; shadowing in a nested block is allowed. A `let` keeps its value across a
+`wait`, `wait_for_event` or `wait_for_approval`.
+
+**Refused:** regex, `new`, `typeof`, `instanceof`, `in`, `delete`, `void`, rest elements, computed keys,
+classes, `throw`, `import`, `export`, and a function as a value (`const f = (x) => ...`).
+
+## Helpers
+
+Called as `size(arr)`. The method form works only where the name is also a JavaScript method —
+`x.trim()`, `arr.includes(v)`, `arr.at(-1)`, `arr.map(fn)`, `s.split(",")`; `arr.size()` is refused.
+
+- **Null and type**: `isNull`, `isNotNull`, `isEmpty`, `isString`, `isNumber`, `isBoolean`, `isArray`,
+  `isObject`, `coalesce`, `get`, `toNumber`, `toString`, `typeOf`, `parseJson`, `toJson`
+- **Lists**: `size`, `first`, `requireFirst` (the first item, refusing an empty list — after a
+  `validate` on the size it saves an `if`), `last`, `nth`, `at` (`at(arr, -1)` counts from the end),
+  `includes`, `filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `groupBy`, `countBy`, `unique`,
+  `uniqueBy`, `compact` (drops falsy items), `flatten`, `reverse`, `slice`, `concat`, `difference`,
+  `differenceBy`, `intersection`, `intersectionBy`, `list`, `reduce(arr, (acc, x) => ..., initial)`,
+  `range(end)` / `range(start, end)`
+- **Math**: `sum`, `sumBy`, `mean`, `meanBy`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `min`, `max`,
+  `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage`
+- **Text**: `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`,
+  `replaceAll`, `substring`, `length`, `split`, `join`, `padStart(str, length, char)`,
+  `padEnd(str, length, char)`, `formatNumber(x, decimals)` (ungrouped, as `x.toFixed`),
+  `formatDecimal(x, decimals, locale)` (grouped: `formatDecimal(151000, 0, "vi-VN")` is `151.000`),
+  `numberToWords` (an integer in Vietnamese words)
+- **Objects**: `keys`, `values`, `entries`, `nonNullKeys`, `pick`, `omit`, `merge`
+- **Dates**, in the workspace's timezone: `now`, `formatDate`, `parseDate`, `addDays`, `subDays`,
+  `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`,
+  `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,
+  `isSameDay`, `isToday`, `isWithinRange`
+- **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,
+  `randomAlphaNumeric(len)`, `sample(items)` (a random item)
+
+A date helper given a null or empty date returns null, so guard its result before comparing or
+writing it: `differenceInCalendarDays(a, b) ?? 0`.
+
+`filter`, `find`, `some`, `every`, `sortBy`, `pluck`, `sumBy`, `meanBy`, `minBy`, `maxBy`, `groupBy`,
+`countBy`, `uniqueBy`, `differenceBy` and `intersectionBy` take a path string
+(`filter(record.items, "Status", "open")`) or a callback
+(`filter(record.items, x => x.Status == "open" && x.Amount > 100)`); `reduce` takes a callback and an
+initial value. A callback gets `(item, idx)` (`reduce`: `(acc, item, idx)`) and reads `record`,
+`runtime`, the names in scope, loop items and an enclosing callback's parameters. Its body is one
+expression — `(x) => <expr>`, `(x) => { return <expr>; }` or `function (x) { return <expr>; }`;
+several statements, `async` and named function expressions are refused.
+
+## Writing a field: null and undefined
+
+In `update_records`' `set` and `create_records`' `records`:
+
+- `null` clears the field.
+- `undefined`, or leaving the key out, leaves the field as it is.
+
+So passing a read that may be null (`record["fld_x"]`) keeps a value when there is one and clears the
+field when there is none. Use `coalesce(x, fallback)` only for a real fallback value.
+
+## 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:
+
+```
+const found = await query_records({
+  table_id: "tbl_customers",
+  filters: { node_type: "condition", field_key: "fld_name", operator: "equals", value: "ACME Corp" },
+});
+const customer = first(found.records);
+
+if (customer && includes(record["fld_customer"], customer.id)) {
+  // …
+}
+```
+
+## Table lifecycle workflows
+
+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`.
+
+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.
+
+| reads | on |
+|---|---|
+| `record` | every event — the new record on create, the record as it now stands on update, the deleted record on delete |
+| `prev_record` | updates and deletes — the record before |
+| `changes["fld_x"]?.next_value` / `?.prev_value` | updates — the fields that changed |
+
+### Gating with `if_source`
+
+`if_source` is one JavaScript expression, reading what the body reads, tested before the workflow
+runs. When it is falsy the workflow does not run at all — no execution, no log. Use it so a workflow
+that cares about some events only skips the rest:
+
+- a status reaching an option: `changes["fld_status"]?.next_value == "opt_done"`
+- a field cleared: `isNull(record["fld_assignee"])`
+- a direct write, not a workflow's cascade:
+  `includes(["member", "chat_agent", "api_client"], runtime.change_origin.type)` — name every
+  direct-write origin rather than testing for one: `member` is a person in the browser, and the same
+  edit over MCP, the CLI or the API arrives as `api_client`.
+
+In `if_source`, `runtime.change_origin` is the origin of the write that fired it; in the body, it is
+the workflow's own.

package/package.json

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