@lotics/cli 0.318.29 → 0.318.31

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.
@@ -12,5 +12,6 @@ Open the one page for the job. Pages are read with the `docs` tool (`docs path="
12
12
  - **Enter data, count, answer a question:** `docs path="working_in_a_workspace"`. The right tool for each job; the value each field takes is `field_values`, choosing rows is `filters`.
13
13
  - **Reach a connected service, or do what a button cannot:** `docs path="workflows"`. Triggers, steps and expressions; each service step is in `workflow_steps`.
14
14
  - **Share an app:** `docs path="first_build"`, § 3. `set_access`, and which app each person gets.
15
+ - **Who can reach what, or why something was refused:** `docs path="permissions"`.
15
16
 
16
17
  Which apps a business needs is `first_build`, § 3 (a worked split: `app_architecture`); how each record is drawn is `design`; every key is in `reference`; each screen in a complete workspace is `examples`.
@@ -33,7 +33,7 @@ coarse, restate a term the heading was carrying.
33
33
 
34
34
  A new doc is **owned by you and private**. `set_access` shares it: `resources[]` with `resource_type` `knowledge_doc`, and `principals[]` (a
35
35
  member, a member group, or `organization` for everyone), each with a `role` of `user` or `manager`; a principal without a `role` has
36
- its access taken away. A doc reaches an agent only when the member can `use` it, an organization admin included.
36
+ its access taken away. A doc reaches an agent when the member can `use` it. An organization admin can use any doc, and their agent searches what they list unless it passes `all: true`.
37
37
 
38
38
  ## How an agent uses a doc
39
39
 
@@ -0,0 +1,74 @@
1
+ # Permissions
2
+
3
+ Who can reach what, what runs under whose access, and what a refusal means.
4
+
5
+ ## Who an agent is
6
+
7
+ An agent over MCP, or a terminal signed in with `lotics auth login`, acts as the member who approved it: it reaches
8
+ what that member reaches, and no more. An `ltk_` key set to **Only selected ones** is its own narrow member: it reaches
9
+ the apps and tables named on it, and a share to the whole organization does not reach it. A key set to **All apps and
10
+ tables** reaches the organization. `get_workspace` lists what the caller can use.
11
+
12
+ ## Ownership and sharing
13
+
14
+ Every table, app, knowledge doc, document template, skill, automation, notification workflow and connection has one
15
+ owner. Everything starts private, and sharing is the only way to widen it. `set_access` gives a member, a group or the
16
+ whole organization a role on a resource (`working_in_a_workspace`). Several shares add up, the highest role wins, and
17
+ there is no deny.
18
+
19
+ **Lists are shorter than reach.** A listing shows your own work and what is shared with you. An admin's listing says what it left out (`not_listed`), and `all: true` on `get_workspace` lists it: apps, knowledge docs and templates. An admin's agent lists every table, automation and connection without it. A doc search covers what is listed, so a member's private doc enters an admin's answers only with `all: true`. By id, an admin reaches anything. Sharing an item with yourself through `set_access` lists it from then on.
20
+
21
+ | Role | Reaches |
22
+ |---|---|
23
+ | Organization owner, admin | Every resource |
24
+ | Member | What they own and what is shared with them |
25
+
26
+ ## Two doors to data
27
+
28
+ - **A table share.** Viewer reads, editor reads and writes. The table's `read_scope` can narrow which rows a member
29
+ opens; it does not narrow an admin or the table's owner.
30
+ - **An app share.** The app runs as its owner and shows what it declares, so a person needs no table access. The app's
31
+ `rows` state which rows each person gets (`reference/read-scope`). What an app does not show, no one reads through it.
32
+
33
+ Hiding a column in a view is layout, not access: to keep a column from someone, give them an app that does not show it.
34
+
35
+ ## Links
36
+
37
+ A link grants nothing: a linked table needs its own share. Someone who can open the linking table and not the target
38
+ sees the link's title and any lookup, both stored on the row by the table's author, and cannot open the linked row.
39
+
40
+ | Action through a link | Result |
41
+ |---|---|
42
+ | A filter crossing into a table the reader cannot open | `403`, on that query or saved view only |
43
+ | A filter crossing into a table the reader opens under a row rule | Answered, matching only through rows they can see |
44
+ | A write or a change request stating a new link | Needs the writer to read that row; a default or a copied row is not judged |
45
+ | A table clone with rows | Needs a whole read of the source; a reader a rule narrows clones the structure |
46
+
47
+ When people who open a table cannot open a table its links reach, `set_tables` and `set_access` say so and name them,
48
+ and a person who owns the target or an admin can share it with them as viewer.
49
+
50
+ ## What runs, runs as its owner
51
+
52
+ A workflow, app, automation and notification workflow uses its owner's current permissions. Pressing a button, answering
53
+ a card or filling a form only triggers it. If the owner loses access, the run fails. Only the owner or an admin writes a
54
+ body, and that includes a notification workflow and naming it on a card; it still runs as its owner.
55
+
56
+ Saving a body needs its owner to be able to use every connection, template and knowledge doc it names. To inspect what a member would get, an admin passes `as_member` with a read or a dry run.
57
+
58
+ ## Connections
59
+
60
+ A connection belongs to the company. Only an admin connects one, in Lotics under Settings → Connections. Admins and
61
+ whoever it is shared with can act through it, and it passes to an admin when its owner leaves. An app handed from one admin
62
+ to another keeps its shares; any other handover clears them.
63
+
64
+ A workflow step's `connected_account_id` is a literal, a constant bound to one, or a choice among them, so every possible
65
+ value is judged at save; one read from an input, a record or a call is refused at save and at run. A document template
66
+ may come from data, and a run refuses one its owner cannot use. No tool calls a service directly
67
+ (`workflows/reaching-a-connected-service`).
68
+
69
+ An automation that reads a mailbox stops and tells its owner when the connection is gone or they can no longer use it.
70
+
71
+ ## Reading a refusal
72
+
73
+ A refusal states what is missing and never shows the content it refused. Nothing shares on its own: a `403` means a
74
+ person who owns the resource, or an admin, has to grant access.
@@ -4,8 +4,10 @@
4
4
 
5
5
  The steps only a workflow body runs: a connection's (an invoice issuer, a mailbox, …) and the platform's own. Each is
6
6
  called as `await <step>({ ...inputs })` (see `workflows`); a step's inputs and answer are its entry here. A connection
7
- step takes the `connected_account_id` that `get_workspace` lists under kind `connection`, and the app's owner and
8
- whoever saves the body must both be able to use that connection.
7
+ step takes the `connected_account_id` that `get_workspace` lists under kind `connection`, and the app's owner must be
8
+ able to use that connection. A step's `connected_account_id` is a literal, a
9
+ constant bound to one, or a choice among them: every possible value is judged at save, and one read from an input, a
10
+ record or a call is refused. A template may come from data; a run refuses one its owner cannot use.
9
11
 
10
12
  **How a step fails.** A step that is refused — an input the schema rejects, a connection the workspace lacks, an
11
13
  answer the provider refuses — ends the run, and the run's error reads `[<step>] <reason>`. Inside `try { … } catch
@@ -3165,10 +3167,10 @@ above. A provider's refusal carries the provider's own words.
3165
3167
 
3166
3168
  ### request_locked_record_change (workflow step)
3167
3169
 
3168
- - Submit one approval request to change locked field values on a record.
3170
+ - Submit one change request to change locked field values on a record.
3169
3171
  - Include every blocked field in the same call — the approver accepts or rejects the change set as a whole.
3170
3172
  - Values are NOT changed immediately; an approver must accept the request first.
3171
- - Returns `{ approval_request_id, status }`.
3173
+ - Returns `{ request_id, status }`.
3172
3174
 
3173
3175
  **Inputs**
3174
3176
 
@@ -3183,7 +3185,7 @@ above. A provider's refusal carries the provider's own words.
3183
3185
 
3184
3186
  | Name | Type | Required | What it is |
3185
3187
  | --- | --- | --- | --- |
3186
- | `approval_request_id` | string | yes | |
3188
+ | `request_id` | string | yes | |
3187
3189
  | `status` | "pending" | yes | |
3188
3190
 
3189
3191
  ## save
@@ -3249,7 +3251,8 @@ above. A provider's refusal carries the provider's own words.
3249
3251
  - Notify workspace members.
3250
3252
  - Lotics shows it to each recipient and emails it to their own address, through no connection; a member who signs in with an identifier an admin issued has no mailbox and sees it in Lotics alone.
3251
3253
  - A member is named by the member_id get_workspace kind member lists. (chat, MCP, CLI)
3252
- - In a workflow body, every member is { type: "organization", id: runtime.organization_id } and the member who started the run { type: "member", id: runtime.triggered_by_member_id }; a run a schedule, a webhook or an email starts was started by no member.
3254
+ - In a workflow body, every member is { type: "organization", id: runtime.organization_id } and the member who started the run { type: "member", id: runtime.triggered_by_member_id }; a run a schedule, a webhook or an email starts was started by no member. blocks draw under the message: text, stat, chart, fields, link, and record (table_id and record_id; the card shows the record's own title, read as the sender can read it). actions are buttons: each runs workflow_id under its owner's access when pressed, and its owner or an admin may name it.
3255
+ - A workflow a card can run declares notification inputs. inputs are the values the sender fixes; asks are the values the presser answers, each ask key an input of the workflow that inputs does not fix; every required input of the workflow is fixed or asked as required. decision is "any" (one decision for all recipients: the first press decides it) or "each" (every recipient decides alone); it is required with actions and refused without.
3253
3256
 
3254
3257
  **Inputs**
3255
3258
 
@@ -3258,7 +3261,16 @@ above. A provider's refusal carries the provider's own words.
3258
3261
  | `recipients` | any[] | yes | List of recipients. Each entry is a principal: { type: 'member', id } \| { type: 'member_group', id } \| { type: 'organization', id } |
3259
3262
  | `title` | string | yes | |
3260
3263
  | `body` | string | yes | |
3261
- | `level` | "urgent" \\| "warning" \\| "info" \\| "success" | | Notification level: urgent, warning, info, success |
3264
+ | `blocks` | any[] | | |
3265
+ | `actions` | object[] | | |
3266
+ | `actions[].key` | string | yes | |
3267
+ | `actions[].label` | string | yes | |
3268
+ | `actions[].confirm` | string | | |
3269
+ | `actions[].outcome` | "negative" | | Pressing it declines what the card asks: the button is drawn after the others, and the decided card ends with a cross rather than a check |
3270
+ | `actions[].asks` | any[] | | |
3271
+ | `actions[].workflow_id` | string | yes | |
3272
+ | `actions[].inputs` | object | yes | |
3273
+ | `decision` | "any" \\| "each" | | |
3262
3274
 
3263
3275
  **Answer**
3264
3276
 
package/docs/workflows.md CHANGED
@@ -26,6 +26,7 @@ ones that follow or name them.
26
26
  | table | `on({ type: "create" \| "update" \| "delete", table: "<alias>", changed?: ["<alias>", ...], when?: "<expression>" })` |
27
27
  | automation | `on({ type: "recurring_schedule", cron_expression })`, `receive_webhook`, `receive_gmail_email` or `receive_outlook_email` — see **Automations** |
28
28
  | app | `on({ type: "app", app_id, alias, inputs?, outputs? })` — `inputs` and `outputs` only for a custom-code app |
29
+ | notification | `on({ type: "notification", inputs: { ... } })` — what a card's action hands the body |
29
30
 
30
31
  What starts a workflow is fixed once it is made: its kind, a table workflow's trigger type and table, an automation's
31
32
  trigger type, an app workflow's app and alias. To change either, delete the workflow and make another. A replace states the whole trigger, so a key the
@@ -41,6 +42,8 @@ not supply is refused, naming the ones it takes. A rehearsal needs write scope:
41
42
  a step it drops included. `even_if_invoked` and `acknowledge_breaking_api_change` belong to an app workflow and are
42
43
  refused for another kind.
43
44
 
45
+ A notification workflow is run by the action of a notification card under its owner's access; the press only triggers it. It declares `inputs` as an app workflow does, reads them as `inputs.<name>` (or `trigger.notification_action.inputs.<name>`), cannot `wait` or `wait_for_event`, and is bound to no table, automation, button or app. Its owner or an admin reads, replaces and deletes it and puts it on a card, and it still runs as its owner; it has one owner for life and is archived with them when they leave (its open cards close), never handed on. Its writes are judged and attributed as its owner. Its runs are read by its owner and admins, and are never retried: pressing the card again is the retry. A step that sends a card names each action's `workflow_id` as a literal. Only a workflow sends a card; an `agent` step writes the title and body it sends.
46
+
44
47
  An app workflow reads its call as `trigger.app_workflow.inputs.<name>`, or `inputs.<name>`, which is the same read. A Workflow node receives the inputs it declares;
45
48
  an Act's `workflow` receives `record_id` (`record_ids` on an act over several rows) and what the Act asks.
46
49
 
@@ -80,20 +83,22 @@ All three carry `trigger.trigger_id`.
80
83
  | for | `for (const <name> of <expr>) { ... }` |
81
84
  | wait | `await wait({ duration_in_minutes: 5 });` |
82
85
  | wait for an event | `await wait_for_event({ event_type: "webhook", event_ref: <expr>, timeout_in_minutes: 60 });` |
83
- | wait for an approval | `await wait_for_approval({ approvers: <expr>, prompt: <expr> });` — see **Waiting for an approval** |
84
86
  | return | `return({ status: "success" \| "error", message: <expr>, field_errors: { ... }?, data: { ... }? });` — `data` holds the outputs a Workflow node declares — a return of `error` undoes no write a step before it made, so every refusal stands before the body's first write |
85
87
  | validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |
86
88
 
87
89
  A delayed run is never cancelled from a workflow: after a `wait`, it reads the row's state and acts only if it still holds.
88
90
 
89
91
  A tool's inputs and answer are in its own description; the steps only a body runs — a connection's, a mail's — are each
90
- an entry of `workflow_steps`. A person connects a service in Lotics under Settings → Connections; a step names that
92
+ an entry of `workflow_steps`. An admin connects a service in Lotics under Settings → Connections; a step names that
91
93
  connection by its `connected_account_id`, which `get_workspace` with `kind: "connection"` lists for the connections the
92
- caller can use. The app's owner and whoever saves the body must both be able to use that connection.
94
+ caller can use. The app's owner must be able to use that connection, so a
95
+ `connected_account_id` is a literal, a constant bound to one, or a choice among them: every possible value is judged at
96
+ save, and one read from an input, a record or a call is refused. A template may come from data; a run refuses one its
97
+ owner cannot use.
93
98
 
94
99
  In a workflow, email reaches a member of the workspace through the step `send_notification`: Lotics shows it to them and
95
100
  mails it to their own address, with no connection. Its recipients are members by `member_id` (`get_workspace` with
96
- `kind: "member"` lists them), member groups or the whole organization. Mail to anyone else goes from a person's
101
+ `kind: "member"` lists them), member groups or the whole organization. Mail to anyone else goes from a
97
102
  connected Gmail or Outlook (`gmail_send_email`, `outlook_send_email`), which leaves an unsent draft unless `draft` is
98
103
  `false`.
99
104
 
@@ -117,31 +122,6 @@ blocks may reuse a name and an inner block may shadow an outer one. A local may
117
122
  (`const size = 3;`), but calling `size(...)` while it is in scope is refused. The names of the tools a
118
123
  workflow calls, the reserved roots, `linked` and `_s` followed by digits cannot be bound.
119
124
 
120
- ### Waiting for an approval
121
-
122
- `wait_for_approval` is the wait worth binding — `wait` and `wait_for_event` carry nothing to read.
123
- Bind it to branch on the decision:
124
-
125
- ```
126
- const approval = await wait_for_approval({
127
- approvers: trigger.app_workflow.inputs.approvers,
128
- prompt: `Approve this quote?`,
129
- });
130
-
131
- if (approval.status == "approved") {
132
- // the approved path
133
- } else {
134
- // the rejected or timed-out path; approval.decision_comment says why
135
- }
136
- ```
137
-
138
- It resolves to `{ status: "approved" | "rejected" | "timed_out", decided_by: MemberId | null,
139
- decided_at: ISO string, decision_comment: string | null }`.
140
-
141
- `approvers` takes a bare member id (`"mbr_…"`), a bare group id (`"grp_…"`) or a full principal
142
- (`{ type: "member_group", id: "grp_x" }`), alone or in a list — so a member field's value passes as it
143
- is.
144
-
145
125
  ### An agent step
146
126
 
147
127
  `const x = await agent({ instructions, input, model, output });` runs a model as one step — read a paper, classify,
@@ -280,7 +260,7 @@ on the innermost loop; labels and `for-in` are refused.
280
260
  **`let`.** `let x = <expr>;` declares a block-scoped variable; the initializer is required
281
261
  (`let x = null;`). Reassign with `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `??=`, `++` and `--`. Re-declaring in
282
262
  the same block is refused; shadowing in a nested block is allowed. A `let` keeps its value across a
283
- `wait`, `wait_for_event` or `wait_for_approval`.
263
+ `wait` or `wait_for_event`.
284
264
 
285
265
  **Refused, each because a save must know what runs and a run must give the same answer twice:** regex
286
266
  (unbounded matching: use the string methods), `Math.random`, `Date.now()` and `new Date()` (use `now()` and
@@ -879,8 +859,7 @@ automation or its table, and for an app's workflow the app's owner or an admin,
879
859
  - **Find.** `query_workflow_executions` lists one workflow's runs (`workflow_id`), every run started for one row
880
860
  (`record_id`) — a table workflow's written row, a pressed button's row, an app run's `record_id` input — or both, newest
881
861
  first, a page at a time (`next_cursor`). Each run names its workflow and kind, what started it, its row and how it ended:
882
- for a failure, the step that threw, its tool and the error; for a waiting run, when it wakes, or the approval and the
883
- approvers it waits on, or the payment. A run started before runs recorded their row carries no `record_id`.
862
+ for a failure, the step that threw, its tool and the error; for a waiting run, when it wakes, or the payment. A run started before runs recorded their row carries no `record_id`.
884
863
  - **Read.** `get_workflow_execution` gives one run's steps in order with each one's tool, input, output and error, what it
885
864
  returned, how many rows it wrote (a row's own history is in `query_audit_logs`) and the runs its writes started. Ninety days
886
865
  after a run starts, its trigger and its steps' input and output are pruned; the read says so and gives the rest.
@@ -893,7 +872,7 @@ automation or its table, and for an app's workflow the app's owner or an admin,
893
872
  the call waits. An app's call is checked again against the workflow's current inputs. A pruned run, a run of a workflow
894
873
  that is off, a reviewed act's run (call the act again) and a recording's filing (the recording retries its delivery)
895
874
  are not run again.
896
- - **Stop.** `set_workflow_execution` with `action: "cancel"` stops a waiting run and withdraws its pending approvals. Both answer
875
+ - **Stop.** `set_workflow_execution` with `action: "cancel"` stops a waiting run. Both answer
897
876
  `execution_id`, `action`, `status`, `retry_of`, `error` and, for a retry, `original_wrote`: the rows and the irreversible
898
877
  calls the first run wrote, which the retry makes again.
899
878
 
@@ -21,11 +21,11 @@ Find the means in this order: `get_workspace` maps the workspace; `search` it by
21
21
 
22
22
  ## People
23
23
 
24
- `get_workspace` with kind `member` lists every member's name and id; an admin also sees each one's email, role, `managed` and `sign_in_name`, and a `unavailable` list (kind `knowledge` or `template`) of the docs and templates the admin cannot open, while usable ones carry `access`. An admin also reads the credit limits there.
24
+ `get_workspace` with kind `member` lists every member's name and id; an admin also sees each one's email, role, `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.
25
25
 
26
26
  `set_members` is an admin'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 the name of a group to create. In `members`, an email no member holds invites that person (`role` is `member` or `admin`; the invitation email goes out), a current member's entry sets `name` and `role`, a removed member's entry restores them and takes only `name`, and `null` removes a member or cancels the invitation pending to that address. Sign-in names are compared in lowercase. A person adds a managed member and sets its password in Settings → Members. The organization keeps at least one admin: the last one cannot be demoted or removed. 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, and the caller's own step-down last. A member's tool list does not carry `set_members` or `set_workspace`.
27
27
 
28
- `set_access` gives members, groups or the whole organization a role on resources. Role `owner`, on one member, hands every resource listed to that member, 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 over 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).
28
+ `set_access` gives members, groups or the whole organization a role on resources. Role `owner`, on one member, hands every resource listed to that member, 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
 
30
30
  ## Comments
31
31
 
@@ -37,7 +37,7 @@ A keyed entry is removed by `null`: a field, check, view, option, instruction, q
37
37
 
38
38
  ## Locking and changing a locked record
39
39
 
40
- `update_records` with `locked: true` locks the targets (write access) and `locked: false` unlocks them (the table's manager). Beside field edits, a record that is locked before and after the call is refused into `blocked`; an unlock lands before the edit and a lock after it. `request_change: { reason }` files one approval request per blocked record instead, carrying the values the call resolves, and lists them in `requested` as `{ record_id, approval_request_id }`; the unlocked targets of the same call are written, and the call and its requests are one transaction, so a request that cannot be filed leaves them unwritten too.
40
+ `update_records` with `locked: true` locks the targets (write access) and `locked: false` unlocks them (the table's manager). Beside field edits, a record that is locked before and after the call is refused into `blocked`; an unlock lands before the edit and a lock after it. `request_change: { reason }` files one change request per blocked record instead, carrying the values the call resolves, and lists them in `requested` as `{ record_id, request_id }`; the unlocked targets of the same call are written, and the call and its requests are one transaction, so a request that cannot be filed leaves them unwritten too.
41
41
 
42
42
  ## Undoing a write
43
43
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.318.29",
3
+ "version": "0.318.31",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {