From 7334b3f2a4852d4c72dd4f301c9d34789a769164 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 22:58:39 +0000 Subject: [PATCH] feat(automations): run automations on new activities, with limits, budgets and runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A thread follows the stream for the kinds switched-on automations listen for and runs each one a new activity matches, once, as the person who made it. A run checks that person still may act where it works, its If, its cooldown and hourly limit and the global per-minute limit, and its budgets (held for the person's pick, as routines are), then runs its event workflow and keeps a run with its trace, log and intents. Runs show in the stream as automation.ran; chains stop at max_depth. The API tries an automation (saved or a draft) without keeping anything, runs one now, pages its runs, lists what an activity caused and decides a held run. Settings → Automations switches them off and sets the limits and how long runs are kept. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01VCAZ9NEmBJNovqdzxvK3qi --- CHANGELOG.md | 6 + docs/activity.md | 1 + docs/api.md | 16 +- docs/automations.md | 106 +- docs/budgets.md | 27 +- docs/configuration.md | 13 +- docs/telemetry.md | 2 +- .../app/api/v1/routes/automations.py | 141 +- fastapi_backend/app/api/v1/routes/budgets.py | 2 +- fastapi_backend/app/cli.py | 2 + fastapi_backend/app/core/runtime.py | 4 +- fastapi_backend/app/domain/activity.py | 6 +- fastapi_backend/app/domain/approvals.py | 3 +- fastapi_backend/app/domain/automations.py | 807 ++- fastapi_backend/app/domain/budgets.py | 16 +- fastapi_backend/app/domain/events.py | 1 + .../app/domain/events_automations.py | 192 + fastapi_backend/app/domain/events_content.py | 6 +- fastapi_backend/app/domain/settings.py | 61 +- fastapi_backend/app/domain/store.py | 24 +- fastapi_backend/app/domain/telemetry.py | 1 + fastapi_backend/app/schemas/automations.py | 89 + fastapi_backend/tests/api/test_automations.py | 84 +- .../tests/domain/test_automation_runs.py | 384 + .../tests/domain/test_timer_triggers.py | 4 +- .../__tests__/settings-find.test.tsx | 8 +- nextjs-frontend/app/openapi-client/index.ts | 49 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 173 +- .../app/openapi-client/types.gen.ts | 745 +- .../components/settings/bodies.tsx | 10 +- nextjs-frontend/components/settings/model.ts | 69 +- nextjs-frontend/openapi.json | 6407 ++++++++++------- threat-model.json | 28 +- threat-model.md | 3 + threat-model.yaml | 27 +- 35 files changed, 6806 insertions(+), 2711 deletions(-) create mode 100644 fastapi_backend/app/domain/events_automations.py create mode 100644 fastapi_backend/tests/domain/test_automation_runs.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 416188f00..e7ed31529 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version ## Unreleased +- **Automations run.** An automation saved over the API (`/api/v1/automations`) now reacts to new assets in its + namespaces: when its If passes, it runs its workflow as the person who made it, within its limits and budgets, and + each run shows what its actions did. Try one on an activity without keeping or sending anything, or run it now; + Settings → Automations switches them all off and sets how far they may go + ([Running automations](docs/automations.md#running-automations)). + ## 0.13.0 October 16, 2026 {id="0.13.0"} - **Updating Lens in a microsandbox on a Mac gets past "Building Lens".** An update after a build that stopped diff --git a/docs/activity.md b/docs/activity.md index c79f3c679..cd95fe9dd 100644 --- a/docs/activity.md +++ b/docs/activity.md @@ -11,6 +11,7 @@ Each row names every resource it counts for, as `table:id`: | Resource | Example | | --- | --- | | A routine and one of its runs | `routine:3`, `routine_run:12` | +| An automation and one of its runs | `automation:4`, `automation_run:51` | | A job, its asset, namespace and pipeline | `job:40`, `recording:7`, `space:1`, `pipeline:2` | | A workflow | `workflow:4` | | A chat | `chat:9` | diff --git a/docs/api.md b/docs/api.md index 67386dad0..c61293e9c 100644 --- a/docs/api.md +++ b/docs/api.md @@ -192,13 +192,27 @@ DELETE /api/v1/automations/{id} POST /api/v1/automations/{id}/restore POST /api/v1/automations/{id}/enable POST /api/v1/automations/{id}/policy +POST /api/v1/automations/{id}/test +POST /api/v1/automations/test +POST /api/v1/automations/{id}/run +GET /api/v1/automations/{id}/runs +GET /api/v1/automations/{id}/upcoming +GET /api/v1/automations/runs +GET /api/v1/automations/runs/{run} +POST /api/v1/automations/runs/{run}/decide ``` Automations act for the person who made them in namespaces they can edit ([Saving automations](automations.md#saving-automations)). Admins see and change all of them; anyone else the ones that work only in namespaces they can edit (`?removed=true` lists deleted ones, to restore). A save answers `{id, hooks}`. `/policy` lets an action node run without asking (`auto`) only from a signed-in session in the web app. -`/actions` lists what action nodes can do. +`/actions` lists what action nodes can do. The list adds each one's actions waiting (`waiting`) and cost this month +(`cost_month`). `/test` tries a saved automation, and `POST /automations/test {"draft": ...}` an unsaved one, on an +activity (`activity`) or a kind's sample (`kind`) without keeping or sending anything; `/run` runs it now (on +`activity`, else the newest one its triggers listen for). `/runs` pages its runs (`before`, `limit`; `next` for the +page after), `/runs?activity=` lists the runs an activity started, `/runs/{run}` gives one with its trace, log and +intents, and `/runs/{run}/decide {"run": true}` runs a run held over budget, or skips it ([Running +automations](automations.md#running-automations)). ## activities diff --git a/docs/automations.md b/docs/automations.md index 28a1fd4b0..cca197ee1 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -32,7 +32,7 @@ merged is called built. | Calling a web address: the `http_request` action, with credentials in headers kept sealed | built | | Running Lens work: the `run_workflow`, `run_pipeline` and `run_routine` actions | built | | Changing assets and writing notes: the `set_field`, `add_to_collection` and `write_note` actions | built | -| Settings → Automations: how often followers look, how long the event log is kept, and how late a timer may fire | built | +| Settings → Automations: whether automations run, their limits, how long runs are kept and how late a timer may fire; how often followers look and how long the event log is kept | built | | A webhook address per automation trigger, and calls to it as `webhook.received` ([Webhook trigger](#webhook-trigger)) | built | | Timers that outlast a restart and fire once across the API and the worker (`app/domain/timers.py`, [Time](#time)) | built | | The timers behind schedule, `at` and `relative` triggers, the `clock.tick` kind and what's coming ([Time](#time)), set when an automation is saved | built | @@ -44,7 +44,8 @@ merged is called built. | Agents' approval tools: `approvals` and `decline_approval` over MCP and in the assistant, and no way for an agent to approve | built | | The Approvals page (`/approvals`), its badge in the top bar and nav, and Home's Needs attention row | built | | Saving automations: checks, namespaces, switching on and off, delete and restore, the policy, the API (`app/domain/automations.py`) | built | -| Running automations, joins, the studio | planned | +| Running automations: following the stream, limits, budgets, runs as `automation.ran`, trying and running now, the API (`app/domain/automations.py`) | built | +| Joins, the studio | planned | ## Contract @@ -269,6 +270,11 @@ A kind belongs to the source named in its `source`, and a source may list more i nothing and gives the first id, so a retry never doubles an activity. Inside `with events.caused_by({"automation": 4, "run": 51, "depth": 1}):` what is emitted carries that cause. It is read by `(logged_at, id)` and paged by `published`, and its rows are kept for `events.keep_days` (30; Settings → Automations). +- `automations` (`app/domain/events_automations.py`) reads `automation_run` by `finished_at`, the id breaking ties, + as `automation.ran`: a run that ran its graph (done, partly, failed or waiting), with the automation as its actor + (`Application`, `lens:automation/`), the run and what its actions did as its object, and what started it as its + `lens.cause` when that was another automation's run. An automation over a limit is logged as `automation.limited`, + at most once an hour each. ### Following the stream @@ -340,8 +346,8 @@ tree, `path` (when given) is the part of the value the tree tests. Graphs saved ### Automations: triggers and joins -Built as shapes with checks (`app/domain/automation_spec.py`), and saved ([Saving automations](#saving-automations)); -running them is planned. Each check gives a cleaned copy, or a ValueError naming the first problem. +Built as shapes with checks (`app/domain/automation_spec.py`), saved ([Saving automations](#saving-automations)) and +run ([Running automations](#running-automations)) for triggers on `event` and `manual` and the join `any`. Each check gives a cleaned copy, or a ValueError naming the first problem. ```json {"name": "School emails", "enabled": true, "spaces": [3], "run_as": 1, @@ -537,9 +543,9 @@ whatever the run read. The approvals are the person's (`GET /api/v1/approvals`), (`{automation, run, node}`); the output lists their ids, so a later node can tell you what waits. `ask_agent` saves the exchange as one of your conversations, titled ": ", with the -activity's page as what it was asked from, so you can open it, approve what it proposed there and carry on. Model calls -count in the activity ledger under the run, and stop once a budget they count for (the namespace's, or everything's) -is used up. +activity's page as what it was asked from, so you can open it, approve what it proposed there and carry on. Model +calls count in the activity ledger under the run, and stop once a budget they count for (the automation's, its +namespaces', or everything's) is used up. Params marked `"format": "prompt"` in an action's schema (`ask_model`'s `prompt`, `ask_agent`'s `instructions`) are prompts: they are rendered with `variables.prompt` ([Variables and templates](#prompts)), which marks as data @@ -709,7 +715,8 @@ def _(db, cfg, payload): ... # payload + late (true ### Schedule, at and relative triggers -Built as timers; automations set them once they are stored. Each trigger checks as +Built as timers: saving an automation sets them, and when they fire they start a run +([Running automations](#running-automations)). Each trigger checks as [Automations: triggers and joins](#automations-triggers-and-joins) says. ```python @@ -742,7 +749,7 @@ timers.clock_state(db, automation) # each schedule and at trigger: wai ### Actions that wait -Built as timers; the automation's run hands them over once automations are stored. An action node with a `delay` +Built as timers; the automation's run hands them over. An action node with a `delay` (`2h`) or a `when` (a time, or a template giving one) makes an intent with that time and status `scheduled`, and `timers.later(db, intent)` keeps it as the timer `intent-` (its run and node, like `intent-51-n7`), giving back `{timer, at}` to keep with the intent. The run's page shows it as "scheduled for 18:22". @@ -759,8 +766,8 @@ was when the run made the intent: A routine one is carried out through `actions.perform` as the automation (its person's permissions as they are then), inside its run's cause (what it makes carries `lens.cause`, for the loop guard) and its ledger scope -(`automation:`, `automation_run:`). One that should ask becomes an approval (`approvals.ask`, once approvals -are built; until then it waits, saying why). The run hears of each step through `automations.update_intent`: done +(`automation:`, `automation_run:`). One that should ask becomes an approval +([`approvals.ask`](#approvals)). The run hears of each step through `automations.update_intent`: done with what it gave back, failed with why, waiting, or expired when the automation was switched off or removed first, the timer was cancelled, or Lens was off past the catch-up window. @@ -925,7 +932,7 @@ Agents have the `automation_variables` and `preview_template` MCP tools. ## Saving automations -Built (`app/domain/automations.py`, `POST /api/v1/automations`); running them is planned. An automation acts for the +Built (`app/domain/automations.py`, `POST /api/v1/automations`). An automation acts for the person who made it (`run_as`), with their permissions, in namespaces they can edit: ```json @@ -951,14 +958,15 @@ person who made it (`run_as`), with their permissions, in namespaces they can ed the graph, the namespaces, `limits` (`cooldown`, like `10m`, default `0s`; `max_per_hour`, 1 to 3600, default 60) and the policy. Joins other than `any` are refused as coming soon until joins are built. Saving sets the timers of its `schedule` and `at` triggers ([Schedule, at and relative triggers](#schedule-at-and-relative-triggers)), and - switching it off or deleting it calls them off; they start runs once running automations is built. + switching it off or deleting it calls them off. - **Webhook triggers** get their address when the automation is saved ([Webhook trigger](#webhook-trigger)): the answer's `hooks` gives each new one's `url` and signing `secret`, shown this once, and the trigger keeps the hook's id. Saving it again keeps its address; a webhook trigger dropped (or changed to another kind) loses it at once. - **Switching** (`POST /automations/{id}/enable {"on": true}`) records when it was last switched on (`enabled_at`): - running it (planned) reacts only to what happens after that, so switching one on never replays old activity. New - automations are on unless `enabled: false`. -- **Deleting** switches it off and hides it; `POST /automations/{id}/restore` brings it back, switched off. + it reacts only to what happens after that, so switching one on never replays old activity. New automations are on + unless `enabled: false`. +- **Deleting** switches it off and hides it; `POST /automations/{id}/restore` brings it back, switched off. After 30 + days a deleted automation is removed for good, with its runs and its workflow (unless another automation runs it). - **The policy** (`{action node id: ask or auto}`): a node whose action reaches outside Lens or other people, or changes something in Lens other than the event's own object, asks first. Only the person, signed in to the web app, lets a node run on its own (`POST /automations/{id}/policy {"node": "a", "value": @@ -970,6 +978,64 @@ person who made it (`run_as`), with their permissions, in namespaces they can ed `GET /api/v1/automations/actions` lists what an action node can do: each action's params (a JSON Schema), its effect and what it gives back. +## Running automations + +Built (`app/domain/automations.py`). A thread named `automations` runs where the notifier and routines do (the API's +background work and `lens worker`). It follows the stream ([Following the stream](#following-the-stream)) for the +kinds that switched-on automations' triggers listen for, every `events.poll_seconds` and at once when something is +emitted or an automation is saved. With no automation switched on (or automations switched off in Settings), it only +moves its place to now, so nothing replays when one is switched on. + +Each new activity is checked against each trigger that listens for its kind (a webhook trigger listens for +`webhook.received` calls to its own hook), and skipped when: + +- it happened before the automation was last switched on (`enabled_at`); +- an automation made it, unless the trigger says `from_automations`; +- it is the end of a chain of automations setting each other off as long as `automations.max_depth` (3); +- it isn't in one of the automation's namespaces, or the automation's person may not see it; +- the trigger's `where` doesn't match it. + +Then it is claimed (for the automation, trigger and activity together), so it runs each automation once, even with the +API and a worker both following. **`automations.fire(db, cfg, automation_id, alias, activity, events=None, dry=False)`** +is the one way every trigger starts a run (the stream with its webhook calls, run now, and later the clock, timers and +joins); it gives the run's id, or none when nothing ran. A run goes: + +1. **Its person**: if the person it acts for lost their account, their admin role (for one that works everywhere) or + the right to edit one of its namespaces, the run fails saying so, and the automation is switched off. +2. **The If**, on the [run context](#run-context). When it is false the run stops there: it counts in + `counters.skipped`, uses up no limit and makes no run and no activity. +3. **Limits**: the automation's `cooldown` (the wait between runs) and `max_per_hour`, then every automation's runs + together this minute (`automations.max_runs_per_minute`, 60). Over one, nothing runs: it counts in + `counters.limited` and says so in the stream (`automation.limited`) at most once an hour. +4. **Budgets** on the automation, its workflow and its namespaces ([Budgets](budgets.md)): over one, the run is held + for your pick (status `held`, one at a time; later ones add to its `hold.missed`) or skipped, as its budget says. +5. **The graph** runs as its person, counted for `automation:` and its run in the [activity ledger](activity.md): + graph changes are marked as made by the automation, and activities it makes carry the run as their cause. + Routine actions are done; ones that ask first wait for the person's pick and ones with a time wait for it (until + approvals and timers are built, they stay waiting). +6. **It finishes** `done`, `partly` (some actions failed), `failed` or `waiting` (actions wait), with its cost and + tokens, what each node did (`trace`), its log (at most 500 lines) and an `automation.` row in the activity + ledger; and it appears in the stream as `automation.ran`. When a waiting action is decided or its time comes, its + status changes (`automations.update_intent`) and the run's follows. + +Runs are kept for `automations.keep_runs_days` (30); each automation keeps its last 20 however old they are, and a +held run until you pick. + +**Over the API** (`/api/v1/automations`; admins see every automation, anyone else the ones in namespaces they edit): + +- `GET /automations` lists them with their counters, last run, actions waiting and cost this month. +- `GET /automations/{id}/runs?before=` pages its runs, newest first; `GET /automations/runs/{run}` gives one with + its trace, log and what its actions did (`intents`); `GET /automations/runs?activity=` the runs an activity + started. +- `POST /automations/{id}/test` tries a saved one, and `POST /automations/test {"draft": {...}}` one you haven't saved, + on an activity (`"activity": ""`) or a kind's sample (`"kind"`, default its first trigger's): whether its If + passes and what each action would do. Nothing is kept, sent or counted, and limits and budgets aren't checked. +- `POST /automations/{id}/run` runs it now, on an activity you name (in its namespaces, one its person can see), else + the newest one its triggers listen for, else as started by hand. Limits, budgets and asking first apply. +- `POST /automations/runs/{run}/decide {"run": true}` runs a held run now, once, whatever its budgets say; + `{"run": false}` skips it. +- `GET /automations/{id}/upcoming` lists when it runs next (empty until schedules are built). + ## Refine later - More operators: `in`, `matches` (bounded regular expressions), `between`, times against now, `changed`. @@ -978,7 +1044,6 @@ and what it gives back. - A `?format=as2` JSON-LD view and per-actor outboxes for ActivityPub; SurrealDB `DEFINE EVENT` for Update verbs that no row records; pushing instead of polling. - People given only some collections of a namespace see that namespace's activities about those collections. -- Name an automation actor by its automation's name once automations are stored. - A timeline page filtered to one child of `asset.added` (only emails, say) reads every new asset and keeps those of that kind, up to five source pages; narrow it in the query (path, `remote`, `web`) if that proves slow. - Moves of Google Calendar and iCal events only: events in a calendar file on storage are read as new files. An @@ -1011,7 +1076,7 @@ and what it gives back. uses it; matching on variables in triggers and the If (M5). - The model and the agent: per-node model picks in the studio; streaming an agent's steps into the run's log as they happen; a namespace assistant's memory for automations (`remember` is left out today); approving an agent's - proposals from the chat app it told you in; count the automation's own budget once budgets take `automation:`. + proposals from the chat app it told you in. - Calling a web address: secrets in the address itself (a Slack or Discord webhook URL) sealed like headers; PATCH and DELETE (DELETE would count as deleting); OAuth sign-in for an API; form-encoded bodies; retries with backoff; networks allowed for automations apart from notifications. @@ -1045,3 +1110,8 @@ and what it gives back. card for many alike ("approve all 12"); trying a failed one again; expiring an automation's approvals when it is removed; on the page, keys for decline and edit, live updates instead of reading again each minute, and the assistant's proposals shown with their estimates. +- Limits count in fixed hours and minutes; a sliding window would spread a burst at the turn of the hour. +- Tell the person when a run is held over budget or an automation goes over a limit (today it shows in its runs, its + last status and the stream). +- Automations that listen for every kind (or hundreds of automations): an index of triggers by kind and `where`, so a + look reads each activity once whatever the number of automations. diff --git a/docs/budgets.md b/docs/budgets.md index a552369e2..ae6e7a97a 100644 --- a/docs/budgets.md +++ b/docs/budgets.md @@ -1,6 +1,6 @@ # Budgets -A budget caps what a routine, pipeline, workflow or namespace may cost. Budgets are off unless an admin sets one. +A budget caps what a routine, automation, pipeline, workflow or namespace may cost. Budgets are off unless an admin sets one. What has been spent comes from the [activity ledger](activity.md), so a budget counts everything done for that resource: a namespace's budget counts every job in it, and a routine's counts its runs and the jobs it queued. @@ -44,17 +44,20 @@ PUT /api/v1/setup/budget ## Before a run -Before a routine runs and before a job's first step, Lens looks at the budgets of everything the run counts for: the -routine, the pipelines and workflows its actions name and its namespaces; a job's pipeline, namespace and the routine -that queued it. It estimates the next run from the average of that resource's runs in the last 30 days (always an -estimate, shown with ≈). A run goes ahead unless a budget is used up, or would be once the estimated run is done -(for a `run` budget, unless the estimate alone passes the cap). Then `on_over` decides: - -- `ask` (default): the run is held. A routine gets a run with status `held`, a job the status `held`, each with - `hold.why` saying where the budget stands. Someone picks: run it now, once, whatever the budget says - (`POST /api/v1/routines/runs/{run}/decide {"run": true}`, `POST /api/v1/jobs/{jid}/release {"run": true}`), or skip - it (`{"run": false}`). Doing nothing changes nothing: a held run stays held, and a routine that comes due again adds - to the one held run (`hold.missed`) rather than piling up. +Before a routine runs, an automation runs and a job's first step, Lens looks at the budgets of everything the run +counts for: the routine, the pipelines and workflows its actions name and its namespaces; the automation, its workflow +and its namespaces; a job's pipeline, namespace and the routine that queued it. It estimates the next run from the +average of that resource's runs in the last 30 days (always an estimate, shown with ≈). A run goes ahead unless a +budget is used up, or would be once the estimated run is done (for a `run` budget, unless the estimate alone passes +the cap). Then `on_over` decides: + +- `ask` (default): the run is held. A routine or an automation gets a run with status `held`, a job the status + `held`, each with `hold.why` saying where the budget stands. Someone picks: run it now, once, whatever the budget + says, or skip it (`{"run": false}`): + `POST /api/v1/routines/runs/{run}/decide {"run": true}`, + `POST /api/v1/automations/runs/{run}/decide {"run": true}`, + `POST /api/v1/jobs/{jid}/release {"run": true}`. Doing nothing changes nothing: a held run stays held, and a routine + or automation that comes due again adds to the one held run (`hold.missed`) rather than piling up. - `skip`: the run is skipped, and says why. - `assistant`: the decision model (Settings › AI assistant, decisions) weighs it, with where the budget stands and the estimate. It runs only when the model is sure (`decisions.act_above`); otherwise it's held as with `ask`. diff --git a/docs/configuration.md b/docs/configuration.md index ff77af5f2..2c57e7d95 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -463,15 +463,20 @@ Where namespaces may send notifications ([Notifications](notifications.md)). Set ## Automations -The stream of activities automations follow ([Automations](automations.md#contract)), their timers, and -how long their [approvals](automations.md#approvals) wait. Settings → Automations: +How automations run ([Running automations](automations.md#running-automations)), the stream of activities they +follow ([Automations](automations.md#contract)), their timers, and how long their +[approvals](automations.md#approvals) wait. Settings → Automations: | Setting | Default | | |---|---|---| +| `automations.enabled` | true | off: no automation runs and nothing is lost; back on, they react to what happens from then on | +| `automations.max_depth` | 3 | how long a chain of automations setting each other off may get, 1–10 | +| `automations.max_runs_per_minute` | 60 | runs a minute, all automations together, 1–6000 | +| `automations.keep_runs_days` | 30 | how long runs are kept, 1–3650 days; each automation keeps its last 20 whatever their age | +| `automations.catch_up` | `1h` | how late a timer (a schedule, an action that waits) may still fire after Lens was off, `0s` to `7d`; older ones are missed ([Time](automations.md#time)) | +| `automations.approval_days` | 7 | how long an automation's action waits for your pick before it expires and nothing runs, 1–365 days | | `events.poll_seconds` | 5 | how often followers look for new activities when nothing wakes them, 1–3600 | | `events.keep_days` | 30 | how long activities with no row of their own (the event log) are kept, 1–3650 days | -| `automations.approval_days` | 7 | how long an automation's action waits for your pick before it expires and nothing runs, 1–365 days | -| `automations.catch_up` | `1h` | how late a timer (a schedule, an action that waits) may still fire after Lens was off, `0s` to `7d`; older ones are missed ([Time](automations.md#time)) | ## Trusted proxies diff --git a/docs/telemetry.md b/docs/telemetry.md index f68cf0c5b..83df21b34 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -46,7 +46,7 @@ In Docker, `localhost` is the container itself: point the endpoint at a collecto | Trace | each call to the model server (`chat llama3.1`) | model, server host, temperature, tokens in and out, estimated cost | | Metric | `http.server.request.duration` | method, route, status code | | Metric | `lens.job.step.duration`, `lens.jobs` | step type, outcome | -| Metric | `lens.routine.runs`, `lens.workflow.runs` | outcome | +| Metric | `lens.routine.runs`, `lens.automation.runs`, `lens.workflow.runs` | outcome | | Metric | `gen_ai.client.operation.duration`, `gen_ai.client.token.usage` | model, token type | | Metric | `lens.llm.cost` (USD) | model | diff --git a/fastapi_backend/app/api/v1/routes/automations.py b/fastapi_backend/app/api/v1/routes/automations.py index 0a9cfe9bb..58059b03b 100644 --- a/fastapi_backend/app/api/v1/routes/automations.py +++ b/fastapi_backend/app/api/v1/routes/automations.py @@ -6,21 +6,31 @@ from typing import Any -from fastapi import APIRouter, HTTPException +from fastapi import APIRouter, HTTPException, Query from app.api.deps import Acl, Cfg, CurrentUser, Db, Principal, Writer, domain_errors -from app.domain import actions, auth, automations, store +from app.domain import actions, auth, automations, events, store from app.schemas.automations import ( ActionInfo, Automation, AutomationCatalog, AutomationCreate, + AutomationDraftTry, AutomationPolicy, + AutomationRun, + AutomationRunDetail, + AutomationRunNow, + AutomationRuns, AutomationSaved, + AutomationStarted, AutomationSwitch, + AutomationTried, + AutomationTry, + AutomationUpcoming, AutomationUpdate, ) from app.schemas.common import Ok +from app.schemas.routines import HeldRunDecision router = APIRouter(prefix="/automations", tags=["automations"]) @@ -49,7 +59,8 @@ def list_automations(user: CurrentUser, acl: Acl, db: Db, removed: bool = False) """Your automations: every one for an admin, else those that work only in namespaces you can edit. `removed` lists the deleted ones instead, to restore.""" spaces = None if user.admin else acl.editable() - return AutomationCatalog(automations=automations.list_automations(db, spaces, removed)) + rows = automations.list_automations(db, spaces, removed) + return AutomationCatalog(automations=automations.extras(db, rows)) @router.get("/actions") @@ -132,3 +143,127 @@ def set_policy(aid: int, body: AutomationPolicy, user: Writer, acl: Acl, db: Db) got = automations.set_policy(db, aid, body.node, body.value, user.email) auth.audit(db, user.as_audit(), "automation.policy", f"automation:{aid}", {"node": body.node, "value": body.value}) return got + + +def _run_of(db: Any, user: Principal, acl: Any, run_id: int) -> dict[str, Any]: + """A run of an automation this person manages (404 otherwise), with its trace, log and intents.""" + try: + r = automations.get_run(db, run_id) + except KeyError: + raise HTTPException(404, "not found") from None + for removed in (False, True): + try: + a = automations.get(db, r["automation"], removed) + except KeyError: + continue + if automations.manages(a, _editable(db, user, acl), user.admin): + return r + raise HTTPException(404, "not found") + + +def _activity(db: Any, cfg: Any, user: Principal, acl: Any, activity_id: str | None, kind: str | None) -> dict[str, Any] | None: + """The activity to try or run it on: one you may see, by id, or a kind's sample; None for the default.""" + if activity_id: + a = events.get(db, cfg, activity_id, events.viewer(user.id, acl.readable(), user.admin)) + if a is None: + raise HTTPException(404, "no such activity") + return a + if kind: + try: + a = events.kind_info(kind)["sample"] + except KeyError: + raise HTTPException(400, f"no kind {kind}; GET /api/v1/activities/kinds lists them") from None + if a is None: + raise HTTPException(400, f"{kind} has no sample to try it on; give an activity") + return a + return None + + +@router.get("/runs") +def runs_caused(user: CurrentUser, acl: Acl, db: Db, activity: str = Query(description="an activity's id")) -> list[AutomationRun]: + """What an activity caused: the runs of your automations it started (it was their event, or one of a join's).""" + editable = _editable(db, user, acl) + out = [] + for r in automations.caused(db, activity): + try: + a = automations.get(db, r["automation"]) + except KeyError: + continue + if automations.manages(a, editable, user.admin): + out.append(AutomationRun(**r)) + return out + + +@router.get("/runs/{run:int}") +def get_run(run: int, user: CurrentUser, acl: Acl, db: Db) -> AutomationRunDetail: + """One run: what each node did (trace), its log, and what its actions did, asked or wait to do (intents).""" + return AutomationRunDetail(**_run_of(db, user, acl, run)) + + +@router.post("/runs/{run:int}/decide") +def decide_held_run(run: int, body: HeldRunDecision, user: Writer, acl: Acl, db: Db, cfg: Cfg) -> AutomationStarted: + """Pick for a run held over a budget: run it now, once, whatever its budgets say, or skip it.""" + r = _run_of(db, user, acl, run) + with domain_errors(): + got = automations.decide_held(db, cfg, run, body.run, user.email) + auth.audit(db, user.as_audit(), "automation.release" if body.run else "automation.skip", f"automation:{r['automation']}", {"run": run}) + return AutomationStarted(run=got, status=None if got is None else automations.get_run(db, got)["status"]) + + +@router.post("/test") +def test_draft(body: AutomationDraftTry, user: CurrentUser, acl: Acl, db: Db, cfg: Cfg) -> AutomationTried: + """Try an automation before you save it: a dry run on an activity, or on a kind's sample (default: its first + trigger's kind). Says whether its If passes and what each action would do; keeps, sends and counts nothing.""" + a = _activity(db, cfg, user, acl, body.activity, body.kind) + draft = body.draft.model_dump(exclude_unset=True, by_alias=True) + with domain_errors(): + got = automations.test(db, cfg, draft=draft, activity=a, alias=body.as_, user=_who(user)) + return AutomationTried(**got) + + +@router.post("/{aid:int}/test") +def test_automation(aid: int, user: CurrentUser, acl: Acl, db: Db, cfg: Cfg, body: AutomationTry | None = None) -> AutomationTried: + """Try a saved automation: a dry run on an activity, or on a kind's sample (default: its first trigger's kind). + Keeps, sends and counts nothing.""" + body = body or AutomationTry() + _mine(db, user, acl, aid) + a = _activity(db, cfg, user, acl, body.activity, body.kind) + with domain_errors(): + got = automations.test(db, cfg, aid, activity=a, alias=body.as_) + return AutomationTried(**got) + + +@router.post("/{aid:int}/run") +def run_automation(aid: int, user: Writer, acl: Acl, db: Db, cfg: Cfg, body: AutomationRunNow | None = None) -> AutomationStarted: + """Run it now: on an activity, else the newest one its triggers listen for, else as started by hand. It acts as it + would on its own: limits and budgets apply, and actions that ask first wait for your pick.""" + body = body or AutomationRunNow() + _mine(db, user, acl, aid) + a = _activity(db, cfg, user, acl, body.activity, None) + with domain_errors(): + got = automations.run_now(db, cfg, aid, _who(user), activity=a, alias=body.as_) + auth.audit(db, user.as_audit(), "automation.run", f"automation:{aid}", {"run": got["run"]}) + return AutomationStarted(**got) + + +@router.get("/{aid:int}/runs") +def list_runs( + aid: int, + user: CurrentUser, + acl: Acl, + db: Db, + before: int | None = Query(None, description="a run id: the runs before it"), + limit: int = Query(20, ge=1, le=100), +) -> AutomationRuns: + """Its runs, newest first; `next` pages on.""" + _mine(db, user, acl, aid, removed=False) + rows = automations.runs(db, aid, before, limit) + return AutomationRuns(runs=[AutomationRun(**r) for r in rows], next=rows[-1]["id"] if len(rows) == limit else None) + + +@router.get("/{aid:int}/upcoming") +def upcoming(aid: int, user: CurrentUser, acl: Acl, db: Db, n: int = Query(10, ge=1, le=100)) -> AutomationUpcoming: + """When it runs next, from its schedules and timers (coming soon: empty until schedules are built).""" + _mine(db, user, acl, aid) + with domain_errors(): + return AutomationUpcoming(times=automations.upcoming(db, aid, n)) diff --git a/fastapi_backend/app/api/v1/routes/budgets.py b/fastapi_backend/app/api/v1/routes/budgets.py index 42f3759ad..c425b6631 100644 --- a/fastapi_backend/app/api/v1/routes/budgets.py +++ b/fastapi_backend/app/api/v1/routes/budgets.py @@ -13,7 +13,7 @@ from app.schemas.common import Ok router = APIRouter(tags=["budgets"]) -RESOURCE = Query(description="all (everything Lens spends), routine:, pipeline:, workflow: or space:") +RESOURCE = Query(description="all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space:") @router.get("/budgets") diff --git a/fastapi_backend/app/cli.py b/fastapi_backend/app/cli.py index 1c80f8822..ea587354a 100644 --- a/fastapi_backend/app/cli.py +++ b/fastapi_backend/app/cli.py @@ -264,6 +264,7 @@ def platform_main(argv, config): from .domain import ( auth, + automations, channels, https, jobs, @@ -386,6 +387,7 @@ def password(): notify.start(db, C, stop, name=wk.name, log=say) # sends notifications too (docs/notifications.md) if not (a.steps or a.no_schedule): # and scans watched folders and runs routines, as `lens watch` does routines.start(db, C, stop, log=say) + automations.start(db, C, stop, log=say) # and automations, following the stream sensors.start(db, C, stop, log=say, name=wk.name) # and the sensor hub, while sensors are on smb_share.start(db, C, stop, name=wk.name, log=say) # and the SMB share of the file tree, while it's on shares.start(db, C, stop, log=say, name=wk.name) # and the file shares (S3, WebDAV), while they're on diff --git a/fastapi_backend/app/core/runtime.py b/fastapi_backend/app/core/runtime.py index 9ecc02f6b..315806073 100644 --- a/fastapi_backend/app/core/runtime.py +++ b/fastapi_backend/app/core/runtime.py @@ -13,6 +13,7 @@ from app.domain import ( activity, auth, + automations, channels, components, content_types, @@ -85,7 +86,7 @@ def prepare(self) -> None: ) def start_background(self) -> None: - """Inline workers, the watched-folder poller, the notifier, the routine scheduler, the sensor hub (idle while + """Inline workers, the watched-folder poller, the notifier, the routine scheduler, automations, the sensor hub (idle while sensors are off) and the chat channels (each idle while it's off). Production runs these as separate processes (`lens worker`).""" for i in range(max(0, int(self.current()["workers"]["inline"]))): w = jobs.Worker(self.db, self.current, name=f"api-{os.getpid()}-{i}", log=log.info) @@ -93,6 +94,7 @@ def start_background(self) -> None: notify.start(self.db, self.current, self.stop, name=f"api-{os.getpid()}", log=log.warning) routines.start(self.db, self.current, self.stop, log=log.info) + automations.start(self.db, self.current, self.stop, log=log.info) sensors.start(self.db, self.current, self.stop, log=log.info, name=f"api-{os.getpid()}") channels.start_all(self.db, self.current, self.stop, lambda: self.base, name=f"api-{os.getpid()}", log_fn=log.warning) tunnel.start(self.db, self.current, self.stop, name=f"api-{os.getpid()}", log=log.info) diff --git a/fastapi_backend/app/domain/activity.py b/fastapi_backend/app/domain/activity.py index 026bbb99e..c09c9a053 100644 --- a/fastapi_backend/app/domain/activity.py +++ b/fastapi_backend/app/domain/activity.py @@ -41,6 +41,7 @@ "recordings": "recording", "resources": "recording", "routines": "routine", + "automations": "automation", "runs": "routine_run", "pipelines": "pipeline", "workflows": "workflow", @@ -123,9 +124,12 @@ def current(): def _table(parts, i): - """The table a key after path segment i names: /api/v1/notes/{id} are note pages, a recording's notes/{id} its notes.""" + """The table a key after path segment i names: /api/v1/notes/{id} are note pages, a recording's notes/{id} its + notes, /api/v1/automations/runs/{id} an automation's runs.""" if parts[i] == "notes" and i and parts[i - 1] == "v1": return "note_page" + if parts[i] == "runs" and i and parts[i - 1] == "automations": + return "automation_run" return TABLES.get(parts[i]) diff --git a/fastapi_backend/app/domain/approvals.py b/fastapi_backend/app/domain/approvals.py index c52e4846d..fc3cd61a1 100644 --- a/fastapi_backend/app/domain/approvals.py +++ b/fastapi_backend/app/domain/approvals.py @@ -83,7 +83,8 @@ def _event_of(db, cfg, intent): if intent.get("run") is None: return None try: - ids = (db.one("SELECT events FROM $r", r=R("automation_run", int(intent["run"]))) or {}).get("events") or [] + row = db.one("SELECT event, event_ids FROM $r", r=R("automation_run", int(intent["run"]))) or {} + ids = row.get("event_ids") or ([row["event"]] if row.get("event") else []) except Exception: # noqa: BLE001 - runs aren't stored yet return None if not ids: diff --git a/fastapi_backend/app/domain/automations.py b/fastapi_backend/app/domain/automations.py index 0d4a4aa5c..56d1536a0 100644 --- a/fastapi_backend/app/domain/automations.py +++ b/fastapi_backend/app/domain/automations.py @@ -20,13 +20,33 @@ from __future__ import annotations -from . import actions_web, auth, automation_spec, keyring, store, workflows +import contextlib +import datetime as dt +import threading +import time + +from . import ( + actions_web, + auth, + automation_nodes, + automation_spec, + budgets, + events, + flow, + graph_history, + keyring, + match, + store, + telemetry, + workflows, +) +from . import activity as activity_mod from .automation_nodes import provided R = store.R FIELDS = ( "record::id(id) AS id, name, description, enabled, enabled_at, spaces, run_as, triggers, join, condition, workflow, " - "version, policy, limits, created_by, created_at, updated_at, last_run_at, last_status, counters, removed_at" + "version, policy, limits, created_by, created_at, updated_at, last_run_at, last_status, last_run, counters, removed_at" ) LIMITS = {"cooldown": "0s", "max_per_hour": 60} MAX_PER_HOUR = 3600 @@ -410,3 +430,786 @@ def manages(row, editable_spaces, admin=False): if admin: return True return row.get("spaces") is not None and set(row["spaces"]) <= set(editable_spaces) + + +# ---------- running ---------- +CONSUMER = "automations" # the stream follower's name (events.follow) +STREAM = ("event", "relative", "webhook") # triggers the stream feeds +DEFAULTS = {"enabled": True, "max_depth": 3, "max_runs_per_minute": 60, "keep_runs_days": 30} +LOG_MAX = 500 +KEEP_LAST = 20 # runs each automation keeps however old they are +REMOVED_DAYS = 30 # a deleted automation is kept this long, to restore, then removed with its runs +SWEEP_SECONDS = 3600 +FINISHED = ("done", "partly", "failed", "waiting") +RUN_FIELDS = ( + "record::id(id) AS id, automation, name, version, trigger, trigger_on, event, event_ids, status, by, started_at, finished_at, " + "counts, cost_usd, tokens, cost_estimate, error, why, hold, cause_depth, space, dry" +) +INTENT_FIELDS = "key, action, params, effect, risk, untrusted, spaces, run_as, node, automation, run, when, status, path, result, error, created_at, updated_at" +_swept = {"at": 0.0} + + +def section(cfg): + """Settings → Automations (store.DEFAULTS["automations"]).""" + return {**DEFAULTS, **((cfg or {}).get("automations") or {})} + + +def _now(): + return dt.datetime.now(dt.timezone.utc) + + +def _iso(t): + return t.astimezone(dt.timezone.utc).isoformat(timespec="seconds") + + +def refs(row): + """What an automation's runs count for, for its budgets: it, its workflow and its namespaces.""" + out = [f"automation:{row['id']}"] if row.get("id") is not None else [] + if row.get("workflow") is not None: + out.append(f"workflow:{int(row['workflow'])}") + return out + [f"space:{s}" for s in row.get("spaces") or []] + + +def _lost(db, row, account): + """Why the automation's person may no longer act where it works, or None.""" + if not account: + return "the person it acts for has no account any more" + who = account.get("name") or account.get("email") + if row.get("spaces") is None: + return None if account.get("admin") else f"{who} is no longer an admin, and it works in every namespace" + can = editable(db, account) + gone = [s for s in row["spaces"] if s not in can] + if gone: + return f"{who} can no longer edit namespace {store.space_names(db).get(gone[0]) or gone[0]}" + return None + + +def _count(db, key, now): + """One more in a counter row (made at its first count); the count.""" + got = db.one("UPSERT $r SET n += 1, at = $t RETURN AFTER", r=R("automation_limit", key), t=_iso(now)) + return int((got or {}).get("n") or 0) + + +def _limited(db, cfg, row, now): + """Why this run would go over a limit (and so doesn't happen), or None: the automation's cooldown, its runs this + hour, then every automation's runs this minute.""" + lim = {**LIMITS, **(row.get("limits") or {})} + cool = automation_spec.check_duration(lim["cooldown"], what="the cooldown") + if cool: + got = db.q( + "UPDATE $r SET fired_at = $t WHERE fired_at = NONE OR fired_at <= $c RETURN AFTER", + r=R("automation", row["id"]), + t=_iso(now), + c=_iso(now - dt.timedelta(seconds=cool)), + ) + if not got: + return f"it waits {lim['cooldown']} between runs" + if _count(db, f"a{row['id']}-{now:%Y%m%d%H}", now) > int(lim["max_per_hour"]): + return f"it ran {lim['max_per_hour']} times this hour, the most it may" + most = int(section(cfg)["max_runs_per_minute"]) + if _count(db, f"all-{now:%Y%m%d%H%M}", now) > most: + return f"automations ran {most} times this minute, the most they may (Settings → Automations)" + return None + + +def _over(db, row, why, now): + """Count a run that went over a limit, and say so in the stream at most once an hour per automation.""" + db.q("UPDATE $r SET counters.limited += 1", r=R("automation", row["id"])) + try: + events.emit( + db, + "automation.limited", + actor=dict(events.LENS), + obj={"type": "Application", "id": f"lens:automation/{row['id']}", "name": row["name"], "why": why}, + space=(row.get("spaces") or [None])[0], + summary=f"{row['name']} is over its limit: {why}", + key=f"limited-{row['id']}-{now:%Y%m%d%H}", + ) + except Exception: # noqa: BLE001 - saying so is best effort; the count is kept + pass + + +def _held(db, cfg, row, alias, activity, evs, by, now): + """A run over a budget (budgets.py) is held for the person's pick, or skipped, as a run row that says why; one + held run waits per automation, and later ones add to it. The run, or None when it may go ahead.""" + try: + verdict = budgets.check(db, cfg, refs(row), now) + except Exception: # noqa: BLE001 - a budget that can't be read doesn't stop the work + return None + if verdict["go"]: + return None + held = verdict["action"] != "skip" + status = "held" if held else "skipped" + waiting = db.values("SELECT VALUE record::id(id) FROM automation_run WHERE automation = $a AND status = 'held'", a=row["id"]) + if held and waiting: + db.q("UPDATE $r SET hold.missed += 1, hold.why = $w", r=R("automation_run", waiting[0]), w=verdict["why"]) + return {"run": waiting[0], "status": "held", "why": verdict["why"]} + run_id = db.next_id("automation_run") + db.q( + "CREATE $r CONTENT $d", + r=R("automation_run", run_id), + d=store.clean( + { + "automation": row["id"], + "name": row["name"], + "trigger": alias, + "event": (activity or {}).get("id"), + "event_ids": _ids(evs), + "status": status, + "by": by, + "started_at": _iso(now), + "finished_at": None if held else _iso(now), + "why": verdict["why"], + "hold": { + "why": verdict["why"], + "resource": verdict["resource"], + "action": verdict["action"], + "missed": 0, + "activity": activity, + "events": evs, + }, + } + ), + ) + db.q("UPDATE $r SET last_status = $s, last_run = $i", r=R("automation", row["id"]), s=status, i=run_id) + activity_mod.record( + "run", + f"automation.{status}", + [f"automation:{row['id']}", f"automation_run:{run_id}"], + cfg, + db, + ok=held, + error=None if held else "OverBudget", + detail={"budget": verdict["resource"], "trigger": alias}, + ) + return {"run": run_id, "status": status, "why": verdict["why"]} + + +def _ids(evs): + out = [] + for v in (evs or {}).values(): + for a in v if isinstance(v, list) else [v]: + if isinstance(a, dict) and isinstance(a.get("id"), str): + out.append(a["id"]) + return list(dict.fromkeys(out)) + + +def _keep_intent(db, intent, extra): + t = store.now() + row = store.clean( + {**intent, "path": extra.get("path"), "result": extra.get("result"), "error": extra.get("error"), "created_at": t, "updated_at": t} + ) + db.q("UPSERT $r CONTENT $d", r=R("automation_intent", intent["key"]), d=row) + + +def _hand_off(db, cfg, intent, depth=1, event=None): + """A waiting intent goes to the approvals inbox, a scheduled one to timers (docs/automations.md, Approvals and + Actions that wait); what to keep with it: its approval, or its timer and time. Without those modules they stay + waiting and scheduled on the run.""" + if intent["status"] == "scheduled": + later = provided("timers", "later") + if later is not None: + return later(db, intent, depth=depth) + elif intent["status"] == "waiting": + ask = provided("approvals", "ask") + if ask is not None: + return {"approval": ask(db, cfg, intent, event=event)} + return None + + +def _status(counts, error): + if counts.get("failed") or error: + return "partly" if counts.get("done") else "failed" + if counts.get("waiting") or counts.get("scheduled"): + return "waiting" + return "done" + + +def _counts(intents): + out = dict.fromkeys(("done", "waiting", "scheduled", "failed"), 0) + for i in intents: + s = i.get("status") + if s in out: + out[s] += 1 + return out + + +def fire(db, cfg, automation_id, alias, activity, events=None, dry=False, by=None, over_budget=False): + """Run an automation for one trigger (`alias`) and the activity that fired it (`events`: each trigger's activity, + by its name, for a join), the one way every trigger starts a run: the stream, the clock, timers, joins, webhooks + and run now. The run's id, or None when nothing ran (it's off, over a limit, or its If was false).""" + return run(db, cfg, automation_id, alias, activity, events, dry=dry, by=by, over_budget=over_budget)["run"] + + +def run(db, cfg, aid, alias, activity, evs=None, dry=False, by=None, over_budget=False, row=None, graph=None, now=None): + """`fire`, saying what happened: {run, status, why, trace, log, intents, error, steps}. With `dry`, nothing is + kept, sent or counted, and each action says what it would do. `row` and `graph` run a draft that isn't saved.""" + now = now or _now() + sec = section(cfg) + out = {"run": None, "status": None, "why": None, "trace": {}, "log": [], "intents": [], "error": None, "steps": 0} + if row is None: + try: + row = _row(db, aid) + except KeyError: + return {**out, "status": "missing", "why": "there's no such automation"} + if not dry and not sec["enabled"]: + return {**out, "status": "off", "why": "automations are switched off (Settings → Automations)"} + trig = next((t for t in row["triggers"] if t["as"] == alias), None) or {"as": alias or "manual", "on": "manual"} + activity = activity if isinstance(activity, dict) else {} + evs = dict(evs) if evs else {trig["as"]: activity} + account = _account(db, row.get("run_as")) + lost = _lost(db, row, account) + if lost: + if dry or row.get("id") is None: + return {**out, "status": "failed", "why": lost} + return {**out, **_failed(db, cfg, row, trig["as"], activity, evs, by, now, lost)} + cause = (activity.get("lens") or {}).get("cause") or {} + depth = int(cause.get("depth") or 0) + 1 + if graph is None: + w = workflows.get(db, row["workflow"], row.get("version")) + graph, version = w["graph"], w["version"] + else: + version = None + run_id = None if dry else db.next_id("automation_run") + person = auth.public(account) + auto = {"id": row.get("id"), "name": row["name"], "version": version, "spaces": row.get("spaces")} + trigger = {"as": trig["as"], "on": trig["on"], "timezone": trig.get("timezone")} + ctx = automation_nodes.context(db, cfg, auto, {"id": run_id, "dry": dry}, trigger, activity, evs, person) + # the If first: a run it stops uses up no limit, holds no budget and makes no row + if row.get("condition") and not match.test(row["condition"], ctx): + if not dry: + db.q("UPDATE $r SET counters.skipped += 1", r=R("automation", row["id"])) + return {**out, "status": "skipped", "why": "its If was false"} + if not dry: + why = _limited(db, cfg, row, now) + if why: + _over(db, row, why, now) + return {**out, "status": "limited", "why": why} + if not over_budget: + held = _held(db, cfg, row, trig["as"], activity, evs, by, now) + if held: + return {**out, **held} + lines: list[str] = [] + + def say(msg): + lines.append(f"{store.now()[11:19]} {msg}") + del lines[:-LOG_MAX] + + space = (ctx.get("namespace") or {}).get("id") + if not dry: + db.q( + "CREATE $r CONTENT $d", + r=R("automation_run", run_id), + d=store.clean( + { + "automation": row["id"], + "name": row["name"], + "version": version, + "trigger": trig["as"], + "trigger_on": trig["on"], + "event": activity.get("id"), + "event_ids": _ids(evs), + "cause_depth": depth, + "cause": {"automation": row["id"], "run": run_id, "depth": depth}, + "status": "running", + "by": by, + "space": space, + "started_at": _iso(now), + } + ), + ) + box = automation_nodes.Intents( + db, + cfg, + user=person, + policy=row.get("policy"), + automation=row.get("id"), + run=run_id, + spaces=row.get("spaces"), + dry=dry, + keep=lambda i, x: _keep_intent(db, i, x), + hand_off=lambda i: _hand_off(db, cfg, i, depth, activity or None), + ) + who = f"automation:{row['id']}" if row.get("id") is not None else None + r = flow.Run( + db, cfg, workflows.KITS["event"], ctx, say, dry=dry, user=who, origin={"automation": row.get("id"), "run": run_id}, intents=box + ) + run_refs = [x for x in (who, f"automation_run:{run_id}" if run_id else None) if x] + error = None + with contextlib.ExitStack() as stack: + stack.enter_context(activity_mod.scope(db, *run_refs, cfg=cfg)) + stack.enter_context( + telemetry.span("automation", {"lens.automation.id": str(row.get("id")), "lens.automation.trigger": trig["as"], "lens.dry": dry}) + ) + if not dry: + stack.enter_context(events.caused_by({"automation": row["id"], "run": run_id, "depth": depth})) + stack.enter_context(graph_history.acting(actor=who, via=who, automation=row["id"], automation_run=run_id)) + try: + flow.run_graph(r, graph) + except Exception as e: # noqa: BLE001 - recorded on the run, on the node that failed + error = str(e)[:500] or type(e).__name__ + say(f"failed: {error}") + counts = _counts(box.items) + status = _status(counts, error) + trace = automation_nodes.finish(r.trace, box) + got = {**out, "run": run_id, "status": status, "trace": trace, "log": lines, "intents": box.items, "error": error, "steps": r.steps} + if dry: + return got + usd, tokens, rough = activity_mod.run_total(db, f"automation_run:{run_id}") + t = store.now() + db.q( + "UPDATE $r MERGE $d", + r=R("automation_run", run_id), + d=store.clean( + { + "status": status, + "finished_at": t, + "counts": counts, + "trace": trace, + "log": lines, + "error": error, + "cost_usd": usd, + "tokens": tokens, + "cost_estimate": rough or None, + "steps": r.steps, + } + ), + ) + db.q( + "UPDATE $r SET last_run_at = $t, last_status = $s, last_run = $i, counters.runs += 1", + r=R("automation", row["id"]), + t=t, + s=status, + i=run_id, + ) + activity_mod.record( + "run", + f"automation.{status}", + run_refs, + cfg, + db, + cost_usd=usd, + tokens_in=tokens, + ok=status != "failed", + detail=store.clean({"trigger": trig["as"], "estimate": rough or None, **counts}), + ) + telemetry.record("lens.automation.runs", 1, {"lens.outcome": status}) + events.wake() + return got + + +def _failed(db, cfg, row, alias, activity, evs, by, now, why): + """A run that can't happen because its person lost access: failed, saying why, and the automation switched off.""" + run_id = db.next_id("automation_run") + t = _iso(now) + db.q( + "CREATE $r CONTENT $d", + r=R("automation_run", run_id), + d=store.clean( + { + "automation": row["id"], + "name": row["name"], + "trigger": alias, + "event": activity.get("id"), + "event_ids": _ids(evs), + "status": "failed", + "by": by, + "started_at": t, + "finished_at": t, + "error": f"{why}, so it was switched off", + "counts": _counts([]), + } + ), + ) + _set(db, row["id"], {"enabled": False, "last_run_at": t, "last_status": "failed", "last_run": run_id, "updated_at": t}) + _arm(db, cfg, row["id"]) + activity_mod.record( + "run", "automation.failed", [f"automation:{row['id']}", f"automation_run:{run_id}"], cfg, db, ok=False, error="NoAccess" + ) + return {"run": run_id, "status": "failed", "why": why} + + +def update_intent(db, run_id, key, status, result=None): + """What became of an intent that waited (an approval decided it, its time came): its status and what it gave + back. The run's status follows: done, partly or failed once nothing waits.""" + if status not in automation_spec.STATUSES: + raise ValueError(f"an intent's status is one of {', '.join(automation_spec.STATUSES)}") + row = db.one("SELECT run, status FROM $r", r=R("automation_intent", str(key))) + if not row or row.get("run") != int(run_id): + raise KeyError(key) + sets = {"status": status, "updated_at": store.now(), **({"result": result} if result is not None else {})} + db.q("UPDATE $r MERGE $d", r=R("automation_intent", str(key)), d=sets) + _settle(db, int(run_id)) + + +def _settle(db, run_id): + run_row = db.one("SELECT automation, status, error FROM $r", r=R("automation_run", run_id)) + if not run_row or run_row.get("status") not in FINISHED: + return + counts = _counts(db.rows("SELECT status FROM automation_intent WHERE run = $r", r=run_id)) + status = _status(counts, run_row.get("error")) + db.q("UPDATE $r SET counts = $c, status = $s", r=R("automation_run", run_id), c=counts, s=status) + db.q("UPDATE $r SET last_status = $s WHERE last_run = $i", r=R("automation", run_row["automation"]), s=status, i=run_id) + + +def decide_held(db, cfg, run_id, run_it=True, by=None): + """The person's pick for a run held over budget: run it now (once, whatever its budgets say) or skip it.""" + row = db.one("SELECT automation, trigger, status, hold FROM $r", r=R("automation_run", int(run_id))) + if not row: + raise KeyError(run_id) + if row["status"] != "held": + raise ValueError(f"this run isn't waiting on a budget (it's {row['status']})") + t = store.now() + db.q( + "UPDATE $r SET status = $s, finished_at = $t, hold.decided = $d WHERE status = 'held'", + r=R("automation_run", int(run_id)), + s="released" if run_it else "skipped", + t=t, + d={"run": run_it, "by": by, "at": t}, + ) + if run_it: + hold = row.get("hold") or {} + return fire(db, cfg, row["automation"], row.get("trigger"), hold.get("activity"), hold.get("events"), by=by, over_budget=True) + return None + + +# ---------- following the stream ---------- +def _stream_index(db, rows): + """{kind: [(automation, trigger)]} for the triggers the stream feeds.""" + index: dict = {} + for a in rows: + for t in a["triggers"]: + if t["on"] in ("event", "relative"): + try: + kinds = events.expand(t.get("kinds") or []) + except ValueError: + continue + elif t["on"] == "webhook": + kinds = {"webhook.received"} & {k["name"] for k in events.kinds()} + else: + continue + for k in kinds or (): + index.setdefault(k, []).append((a, t)) + return index + + +def _enabled(db): + return [ + view(db, r) + for r in db.rows(f"SELECT {FIELDS} FROM automation WHERE enabled = true ORDER BY id") + if not r.get("removed_at") and any(t["on"] in STREAM for t in r.get("triggers") or []) + ] + + +def _viewer(db, account): + if account.get("admin"): + return events.viewer(account["id"], None, admin=True) + return events.viewer(account["id"], set(auth.roles(db, account))) + + +def _after(t, since): + try: + return events._parse(t) >= events._parse(since) + except (TypeError, ValueError): + return False + + +def _route(db, cfg, a, t, act, who, sec): + """One activity against one trigger: the guards, a claim so it's handled once, then on to its run (or a join, or + a timer). How many runs it started.""" + if not a.get("enabled_at") or not _after(act.get("published"), a["enabled_at"]): + return 0 + actor = act.get("actor") or {} + if str(actor.get("id") or "").startswith("lens:automation/") and not t.get("from_automations"): + return 0 + cause = (act.get("lens") or {}).get("cause") or {} + if int(cause.get("depth") or 0) >= int(sec["max_depth"]): + return 0 + if a.get("spaces") is not None and not any(s in a["spaces"] for s in events.spaces_of(act)): + return 0 + if who is None or not events.visible(act, who): + return 0 + if t["on"] == "webhook" and (act.get("object") or {}).get("hook") != t.get("hook"): + return 0 + if t.get("where") and not match.test(t["where"], act): + return 0 + if not events.claim(db, CONSUMER, f"{a['id']}|{t['as']}|{act['id']}"): + return 0 + if t["on"] == "relative": + rel = provided("timers", "relative") + if rel is not None: + rel(db, a, t["as"], act, t["field"], t.get("offset") or "0s") + return 0 + if a["join"]["mode"] != "any": + step = provided("match", "join_step") + done = step(db, cfg, a, t["as"], act) if step is not None else [] + return sum(1 for c in done if fire(db, cfg, a["id"], t["as"], c.get("event") or act, c.get("events")) is not None) + return 1 if fire(db, cfg, a["id"], t["as"], act, {t["as"]: act}) is not None else 0 + + +def dispatch(db, cfg, log=None): + """One look at the stream for every switched-on automation that a stream trigger feeds: each new activity runs + each automation it matches, once. With none (or automations off), the follower only moves to now, so nothing + that happened meanwhile replays when one is switched on. How many runs it started.""" + sec = section(cfg) + rows = _enabled(db) if sec["enabled"] else [] + if not rows: + events.idle(db, CONSUMER) + return 0 + index = _stream_index(db, rows) + if not index: + events.idle(db, CONSUMER) + return 0 + spaces = None if any(a.get("spaces") is None for a in rows) else {s for a in rows for s in a["spaces"]} + acts, commit = events.follow(db, cfg, CONSUMER, kinds=sorted(index), spaces=spaces) + viewers: dict = {} + started = 0 + for act in acts: + for a, t in index.get(act.get("kind"), []): + try: + if a["run_as"] not in viewers: + account = _account(db, a["run_as"]) + viewers[a["run_as"]] = _viewer(db, account) if account else None + started += _route(db, cfg, a, t, act, viewers[a["run_as"]], sec) + except Exception as e: # noqa: BLE001 - one automation failing never stops the others + if log: + log(f"automation {a['id']} ({t['as']}) on {act.get('id')}: {type(e).__name__}: {e}") + commit() + return started + + +def start(db, cfg_fn, stop, log=None): + """The automations thread, until `stop` is set: a look at the stream every events.poll_seconds, and at once when + something is emitted or an automation is saved (events.wake); and the tidy, once an hour. Run where the + notifier and routines run (the API's background work and `lens worker`); claims keep two processes from running + one activity twice.""" + + def loop(): + while not stop.is_set(): + g = events.generation() + cfg = cfg_fn() + try: + dispatch(db, cfg, log) + tidy(db, cfg) + except Exception as e: # noqa: BLE001 - keep following + if log: + log(f"automations: {type(e).__name__}: {e}") + events.wait(events.poll_seconds(cfg), stop, since=g) + + th = threading.Thread(target=loop, daemon=True, name="automations") + th.start() + return th + + +def tidy(db, cfg, now=None): + """Runs past automations.keep_runs_days (each automation keeps its last KEEP_LAST whatever their age), automations + deleted REMOVED_DAYS ago with their runs, and spent limit counters; at most once an hour per process. The + cut-off for runs, or None when it didn't look.""" + t = time.monotonic() + if now is None and _swept["at"] and t - _swept["at"] < SWEEP_SECONDS: + return None + _swept["at"] = t + now = now or _now() + cut = _iso(now - dt.timedelta(days=int(section(cfg)["keep_runs_days"] or 30))) + gone = _iso(now - dt.timedelta(days=REMOVED_DAYS)) + for a in db.rows("SELECT record::id(id) AS id, removed_at, workflow FROM automation"): + if a.get("removed_at") and a["removed_at"] <= gone: + _purge(db, a) + continue + keep = [ + r["n"] + for r in db.rows( + "SELECT id, record::id(id) AS n FROM automation_run WHERE automation = $a ORDER BY id DESC LIMIT $k", a=a["id"], k=KEEP_LAST + ) + ] + old = db.values( + "SELECT VALUE record::id(id) FROM automation_run WHERE automation = $a AND started_at < $c " + "AND record::id(id) NOT IN $k AND status != 'held'", + a=a["id"], + c=cut, + k=keep, + ) + if old: + db.q("DELETE automation_intent WHERE run IN $o", o=old) + db.q("DELETE automation_run WHERE id IN $o", o=[R("automation_run", i) for i in old]) + db.q("DELETE automation_limit WHERE at < $c", c=_iso(now - dt.timedelta(hours=2))) + return cut + + +def _purge(db, a): + cancel = provided("timers", "cancel_for") + if cancel is not None: + cancel(db, a["id"]) + revoke = provided("automation_hooks", "revoke") + row = db.one("SELECT triggers FROM $r", r=R("automation", a["id"])) or {} + for t in row.get("triggers") or []: + if t.get("on") == "webhook" and t.get("hook") is not None and revoke is not None: + revoke(db, t["hook"]) + db.q("DELETE automation_intent WHERE automation = $a", a=a["id"]) + db.q("DELETE automation_run WHERE automation = $a", a=a["id"]) + db.q("DELETE $r", r=R("automation", a["id"])) + wid = a.get("workflow") + if wid is not None and not db.values("SELECT VALUE id FROM automation WHERE workflow = $w", w=wid): + db.q("DELETE workflow_version WHERE workflow = $w", w=wid) + db.q("DELETE $r", r=R("workflow", wid)) + + +# ---------- runs ---------- +def runs(db, aid, before=None, limit=20): + """An automation's runs, newest first: `before` a run id for the page after.""" + p = {"a": int(aid), "n": max(1, min(int(limit), 100))} + where = "automation = $a" + if before is not None: + where += " AND id < $b" + p["b"] = R("automation_run", int(before)) + return [_run_row(r) for r in db.rows(f"SELECT {RUN_FIELDS} FROM automation_run WHERE {where} ORDER BY id DESC LIMIT $n", **p)] + + +def _run_row(r): + """A run as lists show it: a held or skipped run has no counts, trace or log yet.""" + r["counts"] = r.get("counts") or _counts([]) + r["event_ids"] = r.get("event_ids") or [] + return r + + +def get_run(db, run_id): + """One run with its trace, log and intents (KeyError when there's none).""" + row = db.one(f"SELECT {RUN_FIELDS}, trace, log FROM $r", r=R("automation_run", int(run_id))) + if not row: + raise KeyError(run_id) + row = _run_row(row) + row["trace"], row["log"] = row.get("trace") or {}, row.get("log") or [] + row["intents"] = db.rows(f"SELECT {INTENT_FIELDS} FROM automation_intent WHERE run = $r ORDER BY created_at, key", r=int(run_id)) + return row + + +def caused(db, activity_id, limit=50): + """The runs an activity started (it was their event, or one of a join's).""" + return [ + _run_row(r) + for r in db.rows( + f"SELECT {RUN_FIELDS} FROM automation_run WHERE event_ids CONTAINS $e ORDER BY id DESC LIMIT $n", + e=str(activity_id), + n=int(limit), + ) + ] + + +def upcoming(db, aid, n=10): + """When it runs next, from its schedules and timers, once timers are built; [] until then.""" + row = _row(db, aid) + fn = provided("timers", "upcoming") + return list(fn(db, view(db, row), n)) if fn is not None else [] + + +def sample(kinds): + """A sample activity of the first kind that has one, to try an automation on.""" + for k in kinds: + try: + got = events.kind_info(k)["sample"] + except KeyError: + continue + if got: + return got + return None + + +def test(db, cfg, aid=None, draft=None, activity=None, alias=None, user=None): + """A dry run of a saved automation (`aid`) or a draft (the body a save takes) on an activity, or its first + trigger's kind's sample: what its If said, and what each action would do. Keeps, sends and counts nothing.""" + graph = None + if draft is not None: + account = _account(db, (user or {}).get("id")) + if not account: + raise ValueError("an automation acts for a person; sign in") + fields, graph = _check(db, dict(draft), None, account) + if graph is None: + graph = workflows.get(db, fields["workflow"], fields.get("version"))["graph"] + row = {"id": None, "run_as": account["id"], "policy": {}, **fields} + else: + row = _row(db, aid) + trig = next((t for t in row["triggers"] if t["as"] == alias), None) if alias else None + trig = trig or next((t for t in row["triggers"] if t.get("kinds")), None) or row["triggers"][0] + if activity is None: + activity = sample(trig.get("kinds") or ["asset.added"]) + if activity is None: + raise ValueError("there's no sample to try it on; give an activity") + return run(db, cfg, row.get("id"), trig["as"], activity, dry=True, row=row, graph=graph) + + +def latest(db, cfg, row, account): + """The newest activity its triggers listen for that its person may see, to run it now on; None when there's none.""" + kinds = sorted({k for t in row["triggers"] for k in t.get("kinds") or []}) + if not kinds or not account: + return None + flt = {"kinds": kinds, **({"spaces": row["spaces"]} if row.get("spaces") is not None else {})} + got = events.page(db, cfg, _viewer(db, account), flt=flt, limit=1)["items"] + return got[0] if got else None + + +def manual(row, account): + """What a run started by hand sees as its event when no activity starts it.""" + who = account.get("name") or account.get("email") + return { + "id": None, + "kind": None, + "type": "Create", + "published": events.stamp(_now()), + "actor": {"type": "Person", "id": f"lens:account/{account['id']}", "name": who}, + "object": {"type": "Application", "id": f"lens:automation/{row['id']}", "name": row["name"]}, + "summary": f"{who} ran {row['name']} by hand", + "space": (row.get("spaces") or [None])[0], + "tag": [], + "lens": {"source": "manual", "pos": [None, None], "untrusted": [], "cause": None}, + } + + +def run_now(db, cfg, aid, user, activity=None, alias=None): + """Run it now for `user` (who must manage it): on an activity, else the newest one its triggers listen for, else + as started by hand. Limits and budgets apply as to any run. {run, status, why}.""" + row = _row(db, aid) + account = _account(db, (user or {}).get("id")) + if not account: + raise ValueError("sign in to run an automation") + owner = _account(db, row.get("run_as")) + if activity is not None and row.get("spaces") is not None and not set(events.spaces_of(activity)) & set(row["spaces"]): + raise ValueError("that activity isn't in a namespace it works in") + if activity is not None and owner and not events.visible(activity, _viewer(db, owner)): + raise ValueError("the person it acts for can't see that activity, so it can't run on it") + if activity is None: + activity = latest(db, cfg, row, owner) + if activity is None: + trig = next((t for t in row["triggers"] if t["on"] == "manual"), None) + if trig is None and any(t.get("kinds") for t in row["triggers"]): + raise ValueError("nothing it listens for has happened yet; give an activity to run it on") + activity, alias = manual(row, account), (trig or {}).get("as") or alias + if alias is None: + kind = activity.get("kind") + alias = next( + (t["as"] for t in row["triggers"] if kind and kind in (events.expand(t.get("kinds") or []) or set())), + row["triggers"][0]["as"], + ) + got = run(db, cfg, aid, alias, activity, by=account["email"]) + return {"run": got["run"], "status": got["status"], "why": got["why"]} + + +def extras(db, rows): + """What lists show next to each automation: its intents waiting for a pick or a time, and what it cost this + month (an estimate when some calls had no price).""" + if not rows: + return rows + ids = [r["id"] for r in rows] + waiting: dict = {} + for i in db.rows( + "SELECT automation, count() AS n FROM automation_intent WHERE automation IN $a AND status IN ['waiting', 'scheduled'] " + "GROUP BY automation", + a=ids, + ): + waiting[i["automation"]] = i["n"] + month = _now().replace(day=1, hour=0, minute=0, second=0, microsecond=0) + costs = activity_mod.costs(db, [f"automation:{i}" for i in ids], _iso(month)) + for r in rows: + c = costs.get(f"automation:{r['id']}") or {} + r["waiting"] = int(waiting.get(r["id"]) or 0) + r["cost_month"] = {"cost_usd": c.get("cost_usd") or 0.0, "estimate": bool(c.get("estimate"))} + return rows diff --git a/fastapi_backend/app/domain/budgets.py b/fastapi_backend/app/domain/budgets.py index b29cc46f8..aed4fc047 100644 --- a/fastapi_backend/app/domain/budgets.py +++ b/fastapi_backend/app/domain/budgets.py @@ -1,4 +1,4 @@ -"""Budgets (docs/budgets.md): a cap on what a routine, pipeline, workflow or namespace may cost, checked before it runs. +"""Budgets (docs/budgets.md): a cap on what a routine, automation, pipeline, workflow or namespace may cost, checked before it runs. A budget is off unless someone sets one. It caps cost in USD, tokens, or both, per run, day, week (from Monday) or month (UTC), with what was spent read from the activity ledger (activity.py). Before a routine run or a job, Lens @@ -32,8 +32,8 @@ R = store.R PERIODS = ("run", "day", "week", "month") ON_OVER = ("ask", "skip", "assistant") -TABLES = ("routine", "pipeline", "workflow", "space") -REF = re.compile(r"^(?:(routine|pipeline|workflow|space):(\d+)|all)$") +TABLES = ("routine", "automation", "pipeline", "workflow", "space") +REF = re.compile(r"^(?:(routine|automation|pipeline|workflow|space):(\d+)|all)$") ALL = "all" # everything Lens spends (set in setup); the meter measures all of Lens against it HARD_SECONDS = 30 # how long hard_stop trusts what it last found FIELDS = "resource, usd, tokens, period, on_over, warn_at, note, by, updated_at, alert" @@ -48,7 +48,7 @@ def _key(resource): def check_ref(resource): if not isinstance(resource, str) or not REF.match(resource): - raise ValueError("a budget is for all, routine:, pipeline:, workflow: or space:") + raise ValueError("a budget is for all, routine:, automation:, pipeline:, workflow: or space:") return resource @@ -123,16 +123,20 @@ def _spent(db, resource, since): def _runs(db, resource, since): - """How many runs this resource had since a time: a routine's runs, or the jobs of a pipeline, workflow or namespace.""" + """How many runs this resource had since a time: a routine's or an automation's runs, or the jobs of a pipeline, + workflow or namespace.""" m = REF.match(resource) if resource == ALL: routine_runs = len(db.values("SELECT VALUE id FROM routine_run WHERE started_at >= $s", s=since)) + automation_runs = len(db.values("SELECT VALUE id FROM automation_run WHERE started_at >= $s", s=since)) job_runs = db.values( "SELECT VALUE id FROM activity WHERE kind = 'run' AND at >= $s AND string::starts_with(action, 'job.')", s=since ) - return routine_runs + len(job_runs) + return routine_runs + automation_runs + len(job_runs) if m and m.group(1) == "routine": return len(db.values("SELECT VALUE id FROM routine_run WHERE routine = $r AND started_at >= $s", r=int(m.group(2)), s=since)) + if m and m.group(1) == "automation": + return len(db.values("SELECT VALUE id FROM automation_run WHERE automation = $r AND started_at >= $s", r=int(m.group(2)), s=since)) return len( db.values( "SELECT VALUE id FROM activity WHERE kind = 'run' AND resources CONTAINS $res AND at >= $s AND string::starts_with(action, 'job.')", diff --git a/fastapi_backend/app/domain/events.py b/fastapi_backend/app/domain/events.py index 85d19235b..b62ade470 100644 --- a/fastapi_backend/app/domain/events.py +++ b/fastapi_backend/app/domain/events.py @@ -1124,3 +1124,4 @@ def tidy(db, cfg, now=None): from . import events_content # noqa: E402, F401 - the recordings source, registered with the stream once it is loaded from . import events_streams # noqa: E402, F401 - sensors, chat, webhooks and system kinds, the same way from . import events_approvals # noqa: E402, F401 - approvals waiting and decided, after the content sources it reuses +from . import events_automations # noqa: E402, F401 - automations' runs, and the automation kinds diff --git a/fastapi_backend/app/domain/events_automations.py b/fastapi_backend/app/domain/events_automations.py new file mode 100644 index 000000000..fe9b0e829 --- /dev/null +++ b/fastapi_backend/app/domain/events_automations.py @@ -0,0 +1,192 @@ +"""Automations as activities (docs/automations.md, Runs): the `automations` source reads the runs automations kept +(the `automation_run` table) as `automation.ran` activities, by `finished_at` with the id breaking ties, so nothing is +stored twice; and `automation.limited`, emitted at most once an hour when an automation is over one of its limits. + +A run's activity id is `ran-automation_run-`; its actor is the automation (Application `lens:automation/`, +by its name), its object the run with its status and what its actions did, and its `lens.cause` what started it +when that was an automation's run too, so a chain of automations can be followed back. +""" + +from __future__ import annotations + +import re + +from . import events, store + +R = store.R +STATUSES = ["done", "partly", "failed", "waiting"] # a run that ran its graph (held, skipped or running ones didn't) +FIELDS = "id AS rid, record::id(id) AS id, automation, name, status, counts, space, finished_at, started_at, trigger, event, cause" +RAN = { + "type": "object", + "properties": { + "type": {"type": "string", "title": "Object type", "enum": ["Activity"]}, + "id": {"type": "string", "title": "Run"}, + "name": {"type": "string", "title": "Run"}, + "url": {"type": "string", "title": "Link"}, + "status": {"type": "string", "title": "Status", "enum": STATUSES}, + "trigger": {"type": "string", "title": "Trigger"}, + "event": {"type": "string", "title": "What started it"}, + "counts": { + "type": "object", + "title": "What its actions did", + "properties": {s: {"type": "integer", "title": s.title()} for s in ("done", "waiting", "scheduled", "failed")}, + }, + }, +} +ACTOR = { + "type": "object", + "properties": { + "type": {"type": "string", "title": "Actor type", "enum": ["Application"]}, + "id": {"type": "string", "title": "Automation"}, + "name": {"type": "string", "title": "Automation's name"}, + }, +} + +events.kind( + "automation.ran", + label="Automation ran", + source="automations", + as_type="Announce", + object_type="Activity", + fields={"object": RAN, "actor": ACTOR}, + sample={ + "id": "ran-automation_run-51", + "type": "Announce", + "kind": "automation.ran", + "published": "2026-10-15T16:22:01.000Z", + "actor": {"type": "Application", "id": "lens:automation/4", "name": "School emails"}, + "object": { + "type": "Activity", + "id": "lens:automation_run/51", + "name": "School emails run 51", + "url": "/automations/4?run=51", + "status": "waiting", + "trigger": "mail", + "event": "create-recording-7", + "counts": {"done": 1, "waiting": 1, "scheduled": 0, "failed": 0}, + }, + "target": None, + "tag": [], + "summary": "School emails ran: 1 done, 1 waiting for your pick", + "space": 3, + "lens": {"source": "automations", "pos": ["2026-10-15T16:22:01+00:00", 51], "untrusted": [], "cause": None}, + }, +) +events.kind( + "automation.limited", + label="Automation over its limit", + source="log", + as_type="Reject", + object_type="Application", + fields={ + "object": { + "type": "object", + "properties": { + "type": {"type": "string", "title": "Object type", "enum": ["Application"]}, + "id": {"type": "string", "title": "Automation"}, + "name": {"type": "string", "title": "Automation's name"}, + "why": {"type": "string", "title": "Which limit"}, + }, + } + }, +) + + +def actor(aid, name): + return {"type": "Application", "id": f"lens:automation/{int(aid)}", "name": (name or "").strip() or f"Automation {aid}"} + + +def _summary(r): + c = r.get("counts") or {} + name = (r.get("name") or "").strip() or f"Automation {r['automation']}" + if r["status"] == "failed" and not any(c.values()): + return f"{name} failed" + parts = [ + f"{c[k]} {w}" + for k, w in (("done", "done"), ("waiting", "waiting for your pick"), ("scheduled", "scheduled"), ("failed", "failed")) + if c.get(k) + ] + return f"{name} ran" + (": " + ", ".join(parts) if parts else "") + + +def _activities(rows): + out = [] + for r in rows: + try: + published = events.stamp(r["finished_at"]) + except (TypeError, ValueError): + continue + cause = r.get("cause") + if not (isinstance(cause, dict) and all(isinstance(cause.get(k), int) for k in ("automation", "run", "depth"))): + cause = None + obj = store.clean( + { + "type": "Activity", + "id": f"lens:automation_run/{r['id']}", + "name": f"{(r.get('name') or '').strip() or 'Automation ' + str(r['automation'])} run {r['id']}", + "url": f"/automations/{r['automation']}?run={r['id']}", + "status": r["status"], + "trigger": r.get("trigger") if isinstance(r.get("trigger"), str) else None, + "event": r.get("event") if isinstance(r.get("event"), str) else None, + "counts": {k: int((r.get("counts") or {}).get(k) or 0) for k in ("done", "waiting", "scheduled", "failed")}, + } + ) + out.append( + events.build( + f"ran-automation_run-{r['id']}", + "automation.ran", + actor=actor(r["automation"], r.get("name")), + obj=obj, + summary=_summary(r), + space=r.get("space"), + source="automations", + pos=[r["finished_at"], r["id"]], + published=published, + cause=cause, + ) + ) + return out + + +class AutomationsSource(events.Source): + """automation_run rows that ran their graph, as automation.ran, read by (finished_at, id).""" + + name = "automations" + kinds = ("automation.ran",) + + def read(self, db, cfg, pos, spaces, limit, hint=None): + p: dict = {"st": STATUSES} + where = ( + f"status IN $st AND finished_at != NONE AND {events.after_sql('finished_at', pos, p, table='automation_run')} " + f"AND {events.space_sql(spaces, p)}" + ) + rows = db.rows(f"SELECT {FIELDS} FROM automation_run WHERE {where} ORDER BY finished_at, rid LIMIT {int(limit)}", **p) + return _activities(rows) + + def page(self, db, cfg, before, who, flt, limit): + p: dict = {"st": STATUSES} + where = [ + "status IN $st", + "finished_at != NONE", + events.space_sql(None if who.get("admin") else (who.get("spaces") or set()), p), + ] + if before is not None: + where.append(events.after_sql("finished_at", before, p, "<", table="automation_run")) + rows = db.rows( + f"SELECT {FIELDS} FROM automation_run WHERE {' AND '.join(where)} ORDER BY finished_at DESC, rid DESC LIMIT {int(limit)}", + **p, + ) + return _activities(rows) + + def get(self, db, cfg, activity_id): + m = re.match(r"^ran-automation_run-(\d+)$", activity_id) + if not m: + return None + r = db.one(f"SELECT {FIELDS} FROM $r", r=R("automation_run", int(m.group(1)))) + if not r or r.get("status") not in STATUSES: + return None + got = _activities([r]) + return got[0] if got else None + + +events.register_source(AutomationsSource()) diff --git a/fastapi_backend/app/domain/events_content.py b/fastapi_backend/app/domain/events_content.py index a4874407f..9aac0d970 100644 --- a/fastapi_backend/app/domain/events_content.py +++ b/fastapi_backend/app/domain/events_content.py @@ -113,6 +113,7 @@ def actors(db, labels): "watch": set(), "source": set(), "routine": set(), + "automation": set(), "hook": set(), "name": set(), } @@ -130,6 +131,7 @@ def actors(db, labels): "source": "source", "sensor": "source", "routine": "routine", + "automation": "automation", "import_hook": "hook", } if table in key: @@ -144,6 +146,7 @@ def actors(db, labels): accounts = _lookup(db, "account", want["account"], "name, email") people = _lookup(db, "account", want["email"], "name", by="email") routines = _lookup(db, "routine", want["routine"]) + automations = _lookup(db, "automation", want["automation"]) hooks = _lookup(db, "import_hook", want["hook"], "name, space") named: dict = {} if want["name"]: @@ -163,7 +166,8 @@ def one(label, space): if m: table, n = m.group(1), int(m.group(2)) if table == "automation": - return {"type": "Application", "id": f"lens:automation/{n}", "name": f"Automation {n}"} + name = (automations.get(n) or {}).get("name") or f"Automation {n}" + return {"type": "Application", "id": f"lens:automation/{n}", "name": name} if table == "account": return one(n, space) if table == "watch": diff --git a/fastapi_backend/app/domain/settings.py b/fastapi_backend/app/domain/settings.py index cc4712753..72573411b 100644 --- a/fastapi_backend/app/domain/settings.py +++ b/fastapi_backend/app/domain/settings.py @@ -1020,38 +1020,53 @@ def _activity_setting(key, value): raise ValueError(f"unknown setting activity.{key}") -def _events_setting(key, value): - """The stream of activities automations follow (docs/automations.md).""" - limits = {"keep_days": (1, 3650, "a whole number of days"), "poll_seconds": (1, 3600, "a whole number of seconds")} - if key not in limits: - raise ValueError(f"unknown setting events.{key}") - lo, hi, what = limits[key] - if not (isinstance(value, int) and not isinstance(value, bool) and lo <= value <= hi): - raise ValueError(f"events.{key} is {what} from {lo} to {hi}") - return value - - CATCH_UP_MAX = 7 * 86400 def _automations_setting(key, value): - """Automations (docs/automations.md): approval_days, how long an automation's action waits for the person's pick, - 1 to 365 days; catch_up, a duration like 1h, from 0s (a timer missed while Lens was off is missed) to 7d.""" - from . import automation_spec - + """How automations run (docs/automations.md, Limits); catch_up is a duration like 1h, from 0s (a timer missed + while Lens was off is missed) to 7d (docs/automations.md, Time); approval_days, how long an automation's action + waits for the person's pick, 1 to 365 days (docs/automations.md, Approvals).""" if key == "approval_days": if not (isinstance(value, int) and not isinstance(value, bool) and 1 <= value <= 365): raise ValueError("automations.approval_days is a whole number of days from 1 to 365") return value - if key != "catch_up": + if key == "catch_up": + from . import automation_spec + + try: + n = automation_spec.check_duration(value, what="automations.catch_up") + except ValueError: + n = -1 + if not 0 <= n <= CATCH_UP_MAX: + raise ValueError("automations.catch_up is a duration from 0s to 7d, like 1h") + return value.strip() + if key == "enabled": + if not isinstance(value, bool): + raise ValueError("automations.enabled is true or false") + return value + limits = { + "max_depth": (1, 10, "a whole number of automations"), + "max_runs_per_minute": (1, 6000, "a whole number of runs"), + "keep_runs_days": (1, 3650, "a whole number of days"), + } + if key not in limits: raise ValueError(f"unknown setting automations.{key}") - try: - n = automation_spec.check_duration(value, what="automations.catch_up") - except ValueError: - n = -1 - if not 0 <= n <= CATCH_UP_MAX: - raise ValueError("automations.catch_up is a duration from 0s to 7d, like 1h") - return value.strip() + lo, hi, what = limits[key] + if not (isinstance(value, int) and not isinstance(value, bool) and lo <= value <= hi): + raise ValueError(f"automations.{key} is {what} from {lo} to {hi}") + return value + + +def _events_setting(key, value): + """The stream of activities automations follow (docs/automations.md).""" + limits = {"keep_days": (1, 3650, "a whole number of days"), "poll_seconds": (1, 3600, "a whole number of seconds")} + if key not in limits: + raise ValueError(f"unknown setting events.{key}") + lo, hi, what = limits[key] + if not (isinstance(value, int) and not isinstance(value, bool) and lo <= value <= hi): + raise ValueError(f"events.{key} is {what} from {lo} to {hi}") + return value def _backup_setting(key, value): diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index 6efa91809..8608aa685 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -622,10 +622,19 @@ def labels(): # the stream of activities automations follow (docs/automations.md): keep_days: how long activities with no row # of their own (the event log) are kept; poll_seconds: how often followers look when nothing wakes them "events": {"keep_days": 30, "poll_seconds": 5}, - # automations (docs/automations.md): approval_days: how long an automation's action waits for your pick before it + # automations (domain/automations.py): enabled false stops every run and keeps everything; max_depth is how many + # automations may follow one another (one's run starting the next); runs past keep_runs_days are dropped, each + # automation keeping its last 20; approval_days: how long an automation's action waits for your pick before it # expires and nothing runs; catch_up: how late a timer (a schedule, a waiting action) may still fire after Lens - # was off; older ones are missed - "automations": {"approval_days": 7, "catch_up": "1h"}, + # was off, older ones being missed + "automations": { + "enabled": True, + "max_depth": 3, + "max_runs_per_minute": 60, + "keep_runs_days": 30, + "approval_days": 7, + "catch_up": "1h", + }, # database backups (docs/database.md, Backups): schedule is a cron expression in timezone, or none (the default) # for none; the newest `keep` scheduled backups are kept. connection: a storage connection (sources.py) every new # backup is also copied to, under folder, encrypted with a key from secret.key first (none: kept here only) @@ -1280,6 +1289,15 @@ def close(self): # automations (domain/automations.py, docs/automations.md): automation: "DEFINE TABLE IF NOT EXISTS automation SCHEMALESS", "DEFINE INDEX IF NOT EXISTS automation_enabled ON automation FIELDS enabled", + # its runs (automation_run:), what their action nodes meant to do (automation_intent:-) and the + # counters its limits are kept with (automation_limit:-) + "DEFINE TABLE IF NOT EXISTS automation_run SCHEMALESS", + "DEFINE INDEX IF NOT EXISTS automation_run_a ON automation_run FIELDS automation", + "DEFINE INDEX IF NOT EXISTS automation_run_finished ON automation_run FIELDS finished_at", + "DEFINE TABLE IF NOT EXISTS automation_intent SCHEMALESS", + "DEFINE INDEX IF NOT EXISTS automation_intent_run ON automation_intent FIELDS run", + "DEFINE INDEX IF NOT EXISTS automation_intent_a ON automation_intent FIELDS automation, status", + "DEFINE TABLE IF NOT EXISTS automation_limit SCHEMALESS", "DEFINE INDEX IF NOT EXISTS upload_recording ON upload FIELDS recording", # automations' saved variables (domain/variables.py, docs/automations.md, Saved variables): an automation's own or # its namespace's, automation_var: (the id keeps the name unique) diff --git a/fastapi_backend/app/domain/telemetry.py b/fastapi_backend/app/domain/telemetry.py index 830c8e2b1..3a07fcf3e 100644 --- a/fastapi_backend/app/domain/telemetry.py +++ b/fastapi_backend/app/domain/telemetry.py @@ -323,6 +323,7 @@ def _instrument(kind, name, unit, description): "lens.job.step.duration": ("histogram", "s", "How long a job's step took"), "lens.jobs": ("counter", "{job}", "Job runs, by how they ended"), "lens.routine.runs": ("counter", "{run}", "Routine runs, by how they ended"), + "lens.automation.runs": ("counter", "{run}", "Automation runs, by how they ended"), "lens.workflow.runs": ("counter", "{run}", "Workflow runs, by how they ended"), "gen_ai.client.operation.duration": ("histogram", "s", "Model call duration"), "gen_ai.client.token.usage": ("histogram", "{token}", "Tokens per model call"), diff --git a/fastapi_backend/app/schemas/automations.py b/fastapi_backend/app/schemas/automations.py index d2db45cba..9d0cbbed7 100644 --- a/fastapi_backend/app/schemas/automations.py +++ b/fastapi_backend/app/schemas/automations.py @@ -45,6 +45,11 @@ class Automation(ResponseModel): created_at: str | None = None updated_at: str | None = None removed_at: str | None = Field(None, description="when it was deleted (restore brings it back)") + waiting: int | None = Field(None, description="in lists: its actions waiting for your pick or for their time") + cost_month: dict[str, Any] | None = Field( + None, description="in lists: what it cost this month {cost_usd, estimate (true when some calls had no price)}" + ) + next_at: str | None = Field(None, description="in lists: when it runs next, from its schedules (coming soon)") class AutomationCatalog(ResponseModel): @@ -117,3 +122,87 @@ class ActionInfo(ResponseModel): "first unless you let it run on its own; depends: worked out from its params" ) output: dict[str, Any] | None = Field(None, description="a JSON Schema of what it gives back, for later nodes (steps.)") + + +class AutomationRun(ResponseModel): + model_config = ConfigDict(extra="allow") + + id: int + automation: int + name: str | None = None + version: int | None = Field(None, description="the workflow version it ran") + trigger: str | None = Field(None, description="the trigger (its `as`) that started it") + trigger_on: str | None = None + event: str | None = Field(None, description="the activity that started it (an id)") + event_ids: list[str] = Field(default_factory=list, description="every activity it ran on (a join's are several)") + status: str = Field( + description="running, done, partly (some actions failed), failed, waiting (actions wait for your pick or their " + "time), held (over a budget: decide), released or skipped (your pick on a held run)" + ) + by: str | None = Field(None, description="who started it by hand") + started_at: str | None = None + finished_at: str | None = None + counts: dict[str, int] = Field(default_factory=dict, description="its actions: {done, waiting, scheduled, failed}") + cost_usd: float | None = None + tokens: int | None = None + cost_estimate: bool | None = Field(None, description="true when some calls had no price, so the cost is a floor") + error: str | None = None + why: str | None = Field(None, description="why it was held") + hold: dict[str, Any] | None = Field(None, description="a held run: the budget it is over and how many runs it missed") + cause_depth: int | None = Field(None, description="how many automations' runs led to this one") + space: int | None = None + dry: bool | None = None + + +class AutomationRunDetail(AutomationRun): + trace: dict[str, Any] = Field(default_factory=dict, description="by node id: what each node took in and passed on") + log: list[str] = Field(default_factory=list) + intents: list[dict[str, Any]] = Field( + default_factory=list, description="what its actions did, asked or wait to do: action, params, effect, risk, status, result" + ) + + +class AutomationRuns(ResponseModel): + runs: list[AutomationRun] + next: int | None = Field(None, description="for the page after: pass it as `before`") + + +class AutomationRunNow(RequestModel): + model_config = ConfigDict(extra="forbid", populate_by_name=True) + + activity: str | None = Field(None, description="an activity's id to run it on (GET /api/v1/activities)") + as_: str | None = Field(None, alias="as", description="which trigger it runs as (its `as`); default: the first that fits") + + +class AutomationTry(AutomationRunNow): + kind: str | None = Field(None, description="else a kind of activity, to run it on that kind's sample") + + +class AutomationDraftTry(AutomationTry): + draft: AutomationCreate = Field(description="the automation as you would save it") + + +class AutomationTried(ResponseModel): + model_config = ConfigDict(extra="allow") + + status: str | None = Field( + None, + description="done, waiting, partly or failed as it would end; skipped when its If is false (limits and " + "budgets aren't checked: a try costs no run)", + ) + why: str | None = None + trace: dict[str, Any] = Field(default_factory=dict) + log: list[str] = Field(default_factory=list) + intents: list[dict[str, Any]] = Field(default_factory=list, description="what each action would do (nothing is done)") + error: str | None = None + steps: int = 0 + + +class AutomationStarted(ResponseModel): + run: int | None = Field(None, description="the run's id (GET /automations/runs/{run}); none when nothing ran") + status: str | None = None + why: str | None = Field(None, description="why it didn't run, or was held") + + +class AutomationUpcoming(ResponseModel): + times: list[Any] = Field(default_factory=list, description="when it runs next, from its schedules and timers (coming soon)") diff --git a/fastapi_backend/tests/api/test_automations.py b/fastapi_backend/tests/api/test_automations.py index 60df01594..9e45a2110 100644 --- a/fastapi_backend/tests/api/test_automations.py +++ b/fastapi_backend/tests/api/test_automations.py @@ -8,7 +8,7 @@ import pytest -from app.domain import automations, keyring, store, workflows +from app.domain import activity, auth, automations, budgets, ingest, keyring, store, workflows from tests.helpers import login, make_user, without URL = "/api/v1/automations" @@ -257,3 +257,85 @@ def test_schedules_and_webhooks_are_armed_once_their_modules_are_there(client, d assert calls[-1] == ("cancel", aid) two = [*NEW, {"as": "now", "on": "manual"}] assert client.post(URL, headers=hr, json=body(triggers=two, join={"mode": "all", "within": "1h"})).status_code == 200 + + +def test_runs_are_started_listed_and_read_by_who_manages_them(client, db, cfg, env): + he, hv, hr = env["he"], env["hv"], env["hr"] + aid = client.post(URL, headers=he, json=body()).json()["id"] + rec = ingest.import_text(db, cfg, "pods", "Sam: Hello.", title="Courier") + one = f"create-recording-{rec}" + # run now on an activity, and with none: the newest one its triggers listen for + r = client.post(f"{URL}/{aid}/run", headers=he, json={"activity": one}) + assert r.status_code == 200, r.text + first = r.json() + assert first["status"] == "done" and first["run"] + again = client.post(f"{URL}/{aid}/run", headers=he).json() + assert again["status"] == "done" and again["run"] != first["run"] + page = client.get(f"{URL}/{aid}/runs", headers=he, params={"limit": 1}).json() + assert [x["id"] for x in page["runs"]] == [again["run"]] and page["next"] == again["run"] + rest = client.get(f"{URL}/{aid}/runs", headers=he, params={"before": page["next"]}).json() + assert [x["id"] for x in rest["runs"]] == [first["run"]] and rest["next"] is None + run = client.get(f"{URL}/runs/{first['run']}", headers=he).json() + assert run["event"] == one and run["by"] == "ed@x.io" and run["counts"]["done"] == 1 + assert run["intents"][0]["result"]["line"] == "New: Courier" and run["trace"]["a"]["status"] == "done" and run["log"] + assert {x["id"] for x in client.get(f"{URL}/runs", headers=he, params={"activity": one}).json()} == {first["run"], again["run"]} + # lists show what waits and what it cost this month + [listed] = client.get(URL, headers=he).json()["automations"] + assert listed["waiting"] == 0 and listed["cost_month"] == {"cost_usd": 0.0, "estimate": False} and listed["last_run"] == again["run"] + # an admin sees them; someone who doesn't manage it sees nothing + assert client.get(f"{URL}/runs/{first['run']}", headers=hr).status_code == 200 + assert client.get(f"{URL}/runs/{first['run']}", headers=hv).status_code == 404 + assert client.get(f"{URL}/runs", headers=hv, params={"activity": one}).json() == [] + assert client.post(f"{URL}/{aid}/run", headers=hv).status_code == 404 + assert client.get(f"{URL}/{aid}/upcoming", headers=he).json() == {"times": []} + # nor on an activity outside its namespaces, or one its person can't see + calls = ingest.import_text(db, cfg, "calls", "Sam: Hi.", title="Call") + r = client.post(f"{URL}/{aid}/run", headers=hr, json={"activity": f"create-recording-{calls}"}) + assert r.status_code == 400 and "isn't in a namespace it works in" in r.json()["detail"] + other = ingest.import_text(db, cfg, "other", "Sam: Hi.", title="Other") + root = client.post(URL, headers=hr, json=body(name="Root")).json()["id"] + db.q("UPDATE $r SET run_as = $a", r=store.R("automation", root), a=auth.find_account(db, "ed@x.io")["id"]) + r = client.post(f"{URL}/{root}/run", headers=hr, json={"activity": f"create-recording-{other}"}) + assert r.status_code == 400 and "can't see that activity" in r.json()["detail"] + assert client.post(f"{URL}/{aid}/run", headers=he, json={"activity": "create-recording-999"}).status_code == 404 + + +def test_automations_are_tried_saved_or_as_a_draft(client, db, env, monkeypatch): + without(monkeypatch, "timers") + he = env["he"] + aid = client.post(URL, headers=he, json=body()).json()["id"] + # on its first trigger's kind's sample, keeping nothing + t = client.post(f"{URL}/{aid}/test", headers=he).json() + assert t["status"] == "done" and t["intents"][0]["status"] == "done" and t["intents"][0]["result"]["line"].startswith("New: ") + assert db.rows("SELECT id FROM automation_run") == [] and client.get(f"{URL}/{aid}", headers=he).json()["counters"]["runs"] == 0 + # a draft, with an If that's false on this sample + draft = body(**{"if": {"all": [{"path": "event.object.name", "op": "equals", "value": "nothing like it"}]}}) + t = client.post(f"{URL}/test", headers=he, json={"draft": draft, "kind": "asset.added"}) + assert t.status_code == 200, t.text + t = t.json() + assert t["status"] == "skipped" and t["intents"] == [] + t = client.post(f"{URL}/test", headers=he, json={"draft": body()}).json() + assert t["status"] == "done" and t["intents"][0]["action"] == "log_line" + assert problem(client, he, {"draft": body(), "kind": "no.such"}, f"{URL}/test").startswith("no kind no.such") + assert "coming soon" in problem( + client, he, {"draft": body(triggers=[{"as": "t", "on": "schedule", "cron": "0 7 * * *"}])}, f"{URL}/test" + ) + assert client.post(f"{URL}/test", headers=he, json={"draft": body(), "activity": "create-recording-999"}).status_code == 404 + assert db.rows("SELECT id FROM automation") and len(db.rows("SELECT id FROM automation")) == 1 + + +def test_a_run_held_over_budget_waits_for_the_persons_pick(client, db, cfg, env): + he = env["he"] + aid = client.post(URL, headers=he, json=body()).json()["id"] + activity.record("out", "model.chat", [f"automation:{aid}"], db=db, model="m", cost_usd=0.6) + budgets.put(db, f"automation:{aid}", usd=0.5) + assert "nothing it listens for has happened yet" in problem(client, he, None, f"{URL}/{aid}/run") + rec = ingest.import_text(db, cfg, "pods", "Sam: Hello.", title="Courier") + held = client.post(f"{URL}/{aid}/run", headers=he, json={"activity": f"create-recording-{rec}"}).json() + assert held["status"] == "held" and "$0.6 of $0.5 this month" in held["why"] + assert client.post(f"{URL}/runs/{held['run']}/decide", headers=env["hv"], json={"run": True}).status_code == 404 + got = client.post(f"{URL}/runs/{held['run']}/decide", headers=he, json={"run": True}).json() + assert got["run"] != held["run"] and got["status"] == "done" + assert client.get(f"{URL}/runs/{held['run']}", headers=he).json()["status"] == "released" + r = client.post(f"{URL}/runs/{held['run']}/decide", headers=he, json={"run": False}) + assert r.status_code == 400 and "isn't waiting on a budget" in r.json()["detail"] diff --git a/fastapi_backend/tests/domain/test_automation_runs.py b/fastapi_backend/tests/domain/test_automation_runs.py new file mode 100644 index 000000000..2da0e100e --- /dev/null +++ b/fastapi_backend/tests/domain/test_automation_runs.py @@ -0,0 +1,384 @@ +"""Running automations (docs/automations.md, Runs): each new activity runs each automation it matches once, even +with two followers; the guards (switched on after, made by an automation, too deep, other namespaces, where); the If; +limits and budgets; intents done, waiting (handed to approvals) and scheduled (handed to timers), and settled later; +dry runs keep nothing; a person who lost access stops their automation; runs as automation.ran in the stream; tidy.""" + +from __future__ import annotations + +import datetime as dt +import time + +import pytest + +from app.domain import actions, activity, auth, automation_hooks, automations, budgets, events, ingest, store, variables, workflows +from app.domain.actions import ActionSpec +from tests.helpers import make_user + +SAMPLE = events.kind_info("asset.added")["sample"] + + +def node(nid, t, **config): + return {"id": nid, "type": t, "config": config} + + +def edge(a, b): + return {"source": a, "target": b} + + +SAY = { + "nodes": [node("i", "input"), node("a", "action", action="log_line", params={"text": "New: {{ event.object.name }}"})], + "edges": [edge("i", "a")], +} +NEW = [{"as": "new", "on": "event", "kinds": ["asset.added"]}] + + +@pytest.fixture +def env(db, cfg): + events._seen.clear() + events._claimed.clear() + automations._swept["at"] = 0.0 + pods, calls = store.ns_id(db, "pods"), store.ns_id(db, "calls") + make_user(db, "root@x.io", "root password 1", admin=True) + make_user(db, "ed@x.io", "editor password 1", roles={"pods": "editor"}) + root, ed = auth.find_account(db, "root@x.io"), auth.find_account(db, "ed@x.io") + done = [] + + def perform(db, cfg, intent, user, dry): + done.append((intent["action"], intent["params"], actions.person(db, intent, user)["email"], dry)) + if intent["action"] == "shout": + events.emit( + db, "automation.limited", actor=dict(events.LENS), obj={"type": "Application", "name": "x"}, space=None, summary="shouted" + ) + return {"ok": True} + + specs = [ + ActionSpec( + name="tag", + label="Tag an asset", + group="Lens", + params={"type": "object", "properties": {"object": {"type": "string"}}}, + required=("object",), + effect="lens", + perform=perform, + ), + ActionSpec(name="shout", label="Shout", group="Run", params={"type": "object", "properties": {}}, effect="read", perform=perform), + ] + for s in specs: + actions.register(s) + yield { + "pods": pods, + "calls": calls, + "root": {**root, "admin": True}, + "ed": {**ed, "admin": False}, + "done": done, + } + for s in specs: + actions._ACTIONS.pop(s.name, None) + + +def make(db, cfg, who, **over): + return automations.create(db, cfg, {"name": "Say new assets", "triggers": NEW, "graph": SAY, **over}, who)["id"] + + +def tick(): + """Wait for the next second, as store.now() counts them.""" + start = store.now() + while store.now() == start: + time.sleep(0.05) + + +def add(db, cfg, ns, title): + return f"create-recording-{ingest.import_text(db, cfg, ns, f'Sam: {title}.', title=title)}" + + +def test_each_new_activity_runs_each_automation_it_matches_once(db, cfg, env): + trip = make( + db, + cfg, + env["root"], + name="Trips", + triggers=[{**NEW[0], "where": {"all": [{"path": "object.name", "op": "contains", "value": "trip"}]}}], + ) + pods = make(db, cfg, env["ed"], name="Pods") + assert automations.dispatch(db, cfg) == 0 # the first look marks where the follower starts + tick() + a1, a2, a3 = add(db, cfg, "pods", "School trip"), add(db, cfg, "pods", "Courier"), add(db, cfg, "calls", "Trip call") + assert automations.dispatch(db, cfg) == 4 + events._seen.clear() # the other process: nothing seen or claimed in its memory + events._claimed.clear() + assert automations.dispatch(db, cfg) == 0 + got = {(r["automation"], r["event"]) for r in db.rows("SELECT automation, event FROM automation_run")} + assert got == {(trip, a1), (trip, a3), (pods, a1), (pods, a2)} + [r] = automations.runs(db, pods, limit=1) + run = automations.get_run(db, r["id"]) + assert run["status"] == "done" and run["counts"] == {"done": 1, "waiting": 0, "scheduled": 0, "failed": 0} + assert run["trigger"] == "new" and run["cause_depth"] == 1 and run["space"] == env["pods"] + assert run["intents"][0]["result"]["line"] == "New: Courier" and run["intents"][0]["status"] == "done" + assert any("Write “New: Courier” to the run log" in line for line in run["log"]) and run["trace"]["a"]["status"] == "done" + a = automations.get(db, pods) + assert a["counters"]["runs"] == 2 and a["last_status"] == "done" and a["last_run"] == run["id"] + assert [x["id"] for x in automations.caused(db, a1)] and {x["automation"] for x in automations.caused(db, a1)} == {trip, pods} + # each run is in the stream, by its automation + ran = events.get(db, cfg, f"ran-automation_run-{run['id']}", events.viewer(1, None, admin=True)) + assert ran["kind"] == "automation.ran" and ran["actor"]["name"] == "Pods" and ran["summary"] == "Pods ran: 1 done" + assert ran["lens"]["cause"] == {"automation": pods, "run": run["id"], "depth": 1} and ran["space"] == env["pods"] + + +def test_a_saved_variable_counts_across_runs(db, cfg, env): + count = node("count", "action", action="set_variable", params={"name": "seen", "op": "increment"}) + say = node("say", "action", action="log_line", params={"text": "{{ event.object.name }} is number {{ steps.count.value }}"}) + aid = make( + db, + cfg, + env["ed"], + name="Count", + graph={"nodes": [node("i", "input"), count, say], "edges": [edge("i", "count"), edge("count", "say")]}, + ) + assert automations.dispatch(db, cfg) == 0 + tick() + add(db, cfg, "pods", "One") + add(db, cfg, "pods", "Two") + assert automations.dispatch(db, cfg) == 2 + [seen] = variables.list_vars(db, automation=aid) + assert seen["name"] == "seen" and seen["value"] == 2 and seen["updated_by"] == f"automation:{aid}" + lines = { + i["result"]["line"] + for r in automations.runs(db, aid) + for i in automations.get_run(db, r["id"])["intents"] + if i["action"] == "log_line" + } + assert lines == {"One is number 1", "Two is number 2"} + + +def test_a_call_to_a_webhook_runs_its_automation(db, cfg, env): + say = {"nodes": [node("i", "input"), node("a", "action", action="log_line", params={"text": "Door: {{ event.object.payload.door }}"})]} + say["edges"] = [edge("i", "a")] + triggers = [{"as": "ping", "on": "webhook"}] + made = automations.create(db, cfg, {"name": "Door", "triggers": triggers, "graph": say, "spaces": [env["pods"]]}, env["ed"]) + other = make(db, cfg, env["ed"], name="Other door", triggers=triggers) + aid, (hook,) = made["id"], made["hooks"] + assert automations.dispatch(db, cfg) == 0 + tick() + token = hook["url"].rsplit("/", 1)[1] + automation_hooks.receive(db, cfg, token, b'{"door": "open"}', "application/json") + # only the automation whose hook was called runs, with what was sent marked as outside text + assert automations.dispatch(db, cfg) == 1 + assert [r["automation"] for r in db.rows("SELECT automation FROM automation_run")] == [aid] and other != aid + [r] = automations.runs(db, aid, limit=1) + run = automations.get_run(db, r["id"]) + assert run["trigger"] == "ping" and run["intents"][0]["result"]["line"] == "Door: open" and run["intents"][0]["untrusted"] + + +def test_a_schedule_runs_its_automation_when_its_timer_fires(db, cfg, env): + from app.domain import timers + + say = {"nodes": [node("i", "input"), node("a", "action", action="log_line", params={"text": "It is {{ event.object.local }}"})]} + say["edges"] = [edge("i", "a")] + morning = [{"as": "m", "on": "schedule", "cron": "0 7 * * *"}] + aid = automations.create(db, cfg, {"name": "Mornings", "triggers": morning, "graph": say, "spaces": [env["pods"]]}, env["ed"])["id"] + at = dt.datetime.fromisoformat(timers.get(db, f"sched-{aid}-m")["at"]) + timers._idle["until"] = 0.0 + assert timers.due(db, cfg, now=at + dt.timedelta(seconds=3)) == 1 + [r] = automations.runs(db, aid, limit=1) + run = automations.get_run(db, r["id"]) + assert run["trigger"] == "m" and run["status"] == "done" and run["intents"][0]["result"]["line"].startswith("It is ") + assert run["space"] == env["pods"] + # it waits for the next morning, and switching the automation off calls that off + assert dt.datetime.fromisoformat(timers.get(db, f"sched-{aid}-m")["at"]) == at + dt.timedelta(days=1) + automations.enable(db, cfg, aid, False, env["ed"]) + assert timers.get(db, f"sched-{aid}-m")["status"] == "cancelled" + + +def test_the_guards_leave_activities_out(db, cfg, env): + aid = make(db, cfg, env["ed"], triggers=[{**NEW[0], "where": {"all": [{"path": "object.media", "op": "equals", "value": "audio"}]}}]) + a = automations.get(db, aid) + who = automations._viewer(db, auth.get_account(db, env["ed"]["id"])) + sec = automations.section(cfg) + later = events.stamp(dt.datetime.now(dt.UTC) + dt.timedelta(seconds=5)) + + def act(n, **over): + return {**SAMPLE, "id": f"create-recording-{900 + n}", "published": later, "space": env["pods"], **over} + + assert automations._route(db, cfg, a, a["triggers"][0], act(1), who, sec) == 1 + assert automations._route(db, cfg, a, a["triggers"][0], act(1), who, sec) == 0 # claimed: once + assert automations._route(db, cfg, a, a["triggers"][0], act(2, published="2020-01-01T00:00:00.000Z"), who, sec) == 0 + bot = {"type": "Application", "id": "lens:automation/9", "name": "Another"} + assert automations._route(db, cfg, a, a["triggers"][0], act(3, actor=bot), who, sec) == 0 + deep = {**SAMPLE["lens"], "cause": {"automation": 9, "run": 1, "depth": 3}} + assert automations._route(db, cfg, a, a["triggers"][0], act(4, lens=deep), who, sec) == 0 + assert automations._route(db, cfg, a, a["triggers"][0], act(5, space=env["calls"]), who, sec) == 0 + assert automations._route(db, cfg, a, a["triggers"][0], act(6, object={**SAMPLE["object"], "media": "video"}), who, sec) == 0 + mine = {**SAMPLE["lens"], "audience": "owner", "owner": env["root"]["id"]} + assert automations._route(db, cfg, a, a["triggers"][0], act(7, lens=mine), who, sec) == 0 + let = {**a["triggers"][0], "from_automations": True} + assert automations._route(db, cfg, a, let, act(8, actor=bot), who, sec) == 1 + + +def test_the_if_limits_and_dry_runs(db, cfg, env): + aid = make(db, cfg, env["root"], **{"if": {"all": [{"path": "event.object.media", "op": "equals", "value": "audio"}]}}) + assert automations.fire(db, cfg, aid, "new", {**SAMPLE, "object": {**SAMPLE["object"], "media": "video"}}) is None + assert automations.get(db, aid)["counters"]["skipped"] == 1 and not db.rows("SELECT id FROM automation_run") + # a dry run (a test) keeps, sends and counts nothing, and says what it would do + got = automations.test(db, cfg, aid) + assert got["status"] == "done" and got["run"] is None and got["intents"][0]["result"]["line"] == "New: Call with the school" + assert not db.rows("SELECT id FROM automation_run") and not db.rows("SELECT id FROM automation_intent") + assert ( + automations.test(db, cfg, aid, activity={**SAMPLE, "object": {**SAMPLE["object"], "media": "image"}})["why"] == "its If was false" + ) + draft = automations.test(db, cfg, draft={"name": "x", "triggers": NEW, "graph": SAY}, user=env["ed"]) + assert draft["status"] == "done" and draft["intents"][0]["params"]["text"] == "New: Call with the school" + # limits: per hour, cooldown, and every automation's per minute + automations.update(db, cfg, aid, {"if": None, "limits": {"max_per_hour": 2}}) + runs = [automations.fire(db, cfg, aid, "new", SAMPLE) for _ in range(4)] + assert runs[0] and runs[1] and runs[2:] == [None, None] + a = automations.get(db, aid) + assert a["counters"]["limited"] == 2 and a["counters"]["runs"] == 2 + said = db.rows("SELECT summary FROM event_log WHERE kind = 'automation.limited'") + assert len(said) == 1 and "the most it may" in said[0]["summary"] # once an hour + cool = make(db, cfg, env["root"], name="Cool", limits={"cooldown": "1h"}) + assert automations.fire(db, cfg, cool, "new", SAMPLE) and automations.fire(db, cfg, cool, "new", SAMPLE) is None + cfg["automations"] = {**automations.DEFAULTS, "max_runs_per_minute": 1} + other = make(db, cfg, env["root"], name="Other") + assert automations.fire(db, cfg, other, "new", SAMPLE) is None # this minute's runs are spent + cfg["automations"] = {**automations.DEFAULTS, "enabled": False} + assert automations.run(db, cfg, other, "new", SAMPLE)["status"] == "off" + + +def test_a_run_over_budget_is_held_for_the_persons_pick(db, cfg, env): + aid = make(db, cfg, env["root"]) + res = f"automation:{aid}" + activity.record("out", "model.chat", [res], db=db, model="m", cost_usd=0.6) + budgets.put(db, res, usd=0.5) + held = automations.run(db, cfg, aid, "new", SAMPLE) + assert held["status"] == "held" and "$0.6 of $0.5 this month" in held["why"] + assert automations.run(db, cfg, aid, "new", SAMPLE)["run"] == held["run"] # one held run waits; later ones add to it + row = automations.get_run(db, held["run"]) + assert row["hold"]["missed"] == 1 and automations.get(db, aid)["last_status"] == "held" + ran = automations.decide_held(db, cfg, held["run"], True, "root@x.io") + assert automations.get_run(db, ran)["status"] == "done" and automations.get_run(db, held["run"])["status"] == "released" + with pytest.raises(ValueError, match="isn't waiting on a budget"): + automations.decide_held(db, cfg, held["run"], False) + + +def test_intents_wait_for_a_pick_or_a_time_and_settle_later(db, cfg, env, monkeypatch): + asked, later = [], [] + fake = { + ("approvals", "ask"): lambda db, cfg, intent, event=None: asked.append((intent, event)) or 77, + ("timers", "later"): lambda db, intent, depth=1: later.append((intent, depth)) or {"timer": "t1", "at": intent["when"]}, + } + monkeypatch.setattr(automations, "provided", lambda m, fn: fake.get((m, fn))) + monkeypatch.setattr("app.domain.automation_nodes._timers", lambda: fake[("timers", "later")]) + g = { + "nodes": [ + node("i", "input"), + node("t", "action", action="tag", params={"object": "lens:recording/99"}), + node("s", "action", action="log_line", params={"text": "after the tag"}), + node("w", "action", action="log_line", params={"text": "in an hour"}, delay="1h"), + ], + "edges": [edge("i", "t"), edge("t", "s"), edge("i", "w")], + } + aid = make(db, cfg, env["ed"], graph=g) + run_id = automations.fire(db, cfg, aid, "new", {**SAMPLE, "space": env["pods"]}) + run = automations.get_run(db, run_id) + assert run["status"] == "waiting" and run["counts"] == {"done": 0, "waiting": 1, "scheduled": 1, "failed": 0} + assert run["trace"]["s"]["status"] == "skipped" and any("waiting for your pick" in line for line in run["log"]) + by = {i["node"]: i for i in run["intents"]} + assert by["t"]["status"] == "waiting" and by["t"]["result"] == {"approval": 77} and asked[0][0]["key"] == by["t"]["key"] + assert asked[0][1]["id"] == SAMPLE["id"] # the approval says which activity it's about + assert by["w"]["status"] == "scheduled" and later[0][0]["key"] == by["w"]["key"] and later[0][1] == 1 + assert by["w"]["result"] == {"timer": "t1", "at": by["w"]["when"]} + assert env["done"] == [] # nothing was done that should wait + # approvals and timers report back + automations.update_intent(db, run_id, by["t"]["key"], "done", {"ok": True}) + assert automations.get_run(db, run_id)["status"] == "waiting" + automations.update_intent(db, run_id, by["w"]["key"], "failed", {"error": "gone"}) + assert automations.get_run(db, run_id)["status"] == "partly" and automations.get(db, aid)["last_status"] == "partly" + with pytest.raises(KeyError): + automations.update_intent(db, run_id + 1, by["t"]["key"], "done") + with pytest.raises(ValueError): + automations.update_intent(db, run_id, by["t"]["key"], "maybe") + + +def test_an_intent_is_approved_in_the_inbox_or_carried_out_at_its_time(db, cfg, env): + from app.domain import approvals, timers + + g = { + "nodes": [ + node("i", "input"), + node("t", "action", action="tag", params={"object": "lens:recording/99"}), + node("w", "action", action="shout", params={}, delay="1h"), + ], + "edges": [edge("i", "t"), edge("i", "w")], + } + aid = make(db, cfg, env["ed"], graph=g) + act = events.get(db, cfg, add(db, cfg, "pods", "Field trip"), events.viewer(admin=True)) + run_id = automations.fire(db, cfg, aid, "new", act) + by = {i["node"]: i for i in automations.get_run(db, run_id)["intents"]} + # the tag on another object asks: an approval, for the person, about the activity + approval = approvals.get(db, by["t"]["result"]["approval"]) + assert approval["status"] == "pending" and approval["origin"] == {"automation": aid, "run": run_id, "node": "t"} + assert approval["why"]["activity"] == act["id"] and approvals._event_of(db, cfg, by["t"])["id"] == act["id"] + got = approvals.decide(db, cfg, approval, {**env["ed"], "admin": False}, "approve") + assert got["status"] == "done" and env["done"][0][0] == "tag" and env["done"][0][2] == "ed@x.io" + # the shout waits an hour as a timer, then runs on its own (a read), and the run is done + timer = timers.get(db, by["w"]["result"]["timer"]) + assert timer["status"] == "waiting" and by["w"]["result"]["at"] == timer["at"] + assert automations.get_run(db, run_id)["status"] == "waiting" + timers._idle["until"] = 0.0 + assert timers.due(db, cfg, now=dt.datetime.fromisoformat(timer["at"]) + dt.timedelta(seconds=3)) == 1 + run = automations.get_run(db, run_id) + assert [x[0] for x in env["done"]] == ["tag", "shout"] and run["status"] == "done" + assert {i["node"]: i["status"] for i in run["intents"]} == {"t": "done", "w": "done"} + + +def test_what_a_run_does_is_caused_by_it_and_acts_for_its_person(db, cfg, env): + g = {"nodes": [node("i", "input"), node("s", "action", action="shout", params={})], "edges": [edge("i", "s")]} + aid = make(db, cfg, env["ed"], graph=g) + run_id = automations.fire(db, cfg, aid, "new", {**SAMPLE, "space": env["pods"]}) + assert env["done"] == [("shout", {}, "ed@x.io", False)] + [row] = db.rows("SELECT cause FROM event_log WHERE summary = 'shouted'") + assert row["cause"] == {"automation": aid, "run": run_id, "depth": 1} + assert activity.costs(db, [f"automation_run:{run_id}"]) # its calls count for the run + + +def test_a_person_who_lost_access_stops_their_automation(db, cfg, env): + aid = make(db, cfg, env["ed"]) + auth.set_role(db, env["ed"]["id"], env["pods"], "viewer") + got = automations.run(db, cfg, aid, "new", {**SAMPLE, "space": env["pods"]}) + assert got["status"] == "failed" and "can no longer edit namespace pods" in got["why"] + a = automations.get(db, aid) + assert not a["enabled"] and a["last_status"] == "failed" + assert "switched off" in automations.get_run(db, got["run"])["error"] + + +def test_tidy_keeps_recent_runs_and_removes_deleted_automations(db, cfg, env): + aid = make(db, cfg, env["root"], limits={"max_per_hour": 100}) + ids = [automations.fire(db, cfg, aid, "new", SAMPLE) for _ in range(23)] + old = "2020-01-01T00:00:00+00:00" + db.q("UPDATE automation_run SET started_at = $o", o=old) + keep = sorted(ids)[-automations.KEEP_LAST :] + automations.tidy(db, cfg) + assert sorted(r["id"] for r in automations.runs(db, aid, limit=100)) == keep + assert {i["run"] for i in db.rows("SELECT run FROM automation_intent")} == set(keep) + assert automations.tidy(db, cfg) is None # once an hour + gone = make(db, cfg, env["root"], name="Gone") + wid = automations.get(db, gone)["workflow"] + automations.remove(db, cfg, gone) + db.q("UPDATE $r SET removed_at = $o", r=store.R("automation", gone), o=old) + automations.tidy(db, cfg, now=dt.datetime.now(dt.UTC)) + assert not db.rows("SELECT id FROM $r", r=store.R("automation", gone)) + with pytest.raises(KeyError): + workflows.get(db, wid) + assert automations.get(db, aid) + + +def test_a_switched_off_follower_replays_nothing(db, cfg, env): + assert automations.dispatch(db, cfg) == 0 # nothing switched on: the follower stays at now + tick() + add(db, cfg, "pods", "Before") + tick() + aid = make(db, cfg, env["root"]) + assert automations.dispatch(db, cfg) == 0 # what happened before it was switched on isn't replayed + tick() + add(db, cfg, "pods", "After") + assert automations.dispatch(db, cfg) == 1 and automations.get(db, aid)["counters"]["runs"] == 1 diff --git a/fastapi_backend/tests/domain/test_timer_triggers.py b/fastapi_backend/tests/domain/test_timer_triggers.py index 086ba9471..8818c0033 100644 --- a/fastapi_backend/tests/domain/test_timer_triggers.py +++ b/fastapi_backend/tests/domain/test_timer_triggers.py @@ -164,7 +164,9 @@ def test_upcoming_says_what_is_coming(db, cfg, fired): assert len(timers.upcoming(db, 4, n=1, now=noon)) == 1 and timers.upcoming(db, 5) == [] -def test_before_automations_are_stored_a_schedule_still_re_arms(db, cfg): +def test_before_automations_are_stored_a_schedule_still_re_arms(db, cfg, monkeypatch): + real = timers._provided + monkeypatch.setattr(timers, "_provided", lambda module, fn: None if module == "automations" else real(module, fn)) timers._idle["until"] = 0.0 timers.schedule_automation(db, auto(MORNING), now=t("2026-10-15T12:00:00")) assert timers.due(db, cfg, now=t("2026-10-16T06:00:00")) == 1 diff --git a/nextjs-frontend/__tests__/settings-find.test.tsx b/nextjs-frontend/__tests__/settings-find.test.tsx index 52f344c30..5d39750f6 100644 --- a/nextjs-frontend/__tests__/settings-find.test.tsx +++ b/nextjs-frontend/__tests__/settings-find.test.tsx @@ -79,10 +79,14 @@ describe("finding a setting", () => { const auto = hits.find((h) => h.section === "automations")!; expect(auto.group).toBe("System"); expect(fieldsOf("automations").map((f) => fieldId(f))).toEqual([ + "automations.enabled", + "automations.max_depth", + "automations.max_runs_per_minute", + "automations.keep_runs_days", + "automations.catch_up", + "automations.approval_days", "events.poll_seconds", "events.keep_days", - "automations.approval_days", - "automations.catch_up", ]); expect(findSettings("missed", true).some((h) => h.section === "automations")).toBe(true); }); diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index 0149b5c1b..d734dd408 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -186,9 +186,18 @@ export type { Automation, AutomationCatalog, AutomationCreate, + AutomationDraftTry, AutomationPolicy, + AutomationRun, + AutomationRunDetail, + AutomationRunNow, + AutomationRuns, AutomationSaved, + AutomationStarted, AutomationSwitch, + AutomationTried, + AutomationTry, + AutomationUpcoming, AutomationUpdate, AutomationVar, AutomationVars, @@ -633,6 +642,11 @@ export type { DecideApprovalErrors, DecideApprovalResponse, DecideApprovalResponses, + DecideHeldRun2Data, + DecideHeldRun2Error, + DecideHeldRun2Errors, + DecideHeldRun2Response, + DecideHeldRun2Responses, DecideHeldRunData, DecideHeldRunError, DecideHeldRunErrors, @@ -1333,6 +1347,11 @@ export type { GetRoutineErrors, GetRoutineResponse, GetRoutineResponses, + GetRun2Data, + GetRun2Error, + GetRun2Errors, + GetRun2Response, + GetRun2Responses, GetRunData, GetRunError, GetRunErrors, @@ -1913,6 +1932,11 @@ export type { ListRoutinesData, ListRoutinesResponse, ListRoutinesResponses, + ListRuns2Data, + ListRuns2Error, + ListRuns2Errors, + ListRuns2Response, + ListRuns2Responses, ListRunsData, ListRunsError, ListRunsErrors, @@ -2723,6 +2747,11 @@ export type { RoutineRun, RoutineRunRequest, RoutineUpdate, + RunAutomationData, + RunAutomationError, + RunAutomationErrors, + RunAutomationResponse, + RunAutomationResponses, RunData, RunError, RunErrors, @@ -2738,6 +2767,11 @@ export type { RunRoutineErrors, RunRoutineResponse, RunRoutineResponses, + RunsCausedData, + RunsCausedError, + RunsCausedErrors, + RunsCausedResponse, + RunsCausedResponses, RunWorkflowData, RunWorkflowError, RunWorkflowErrors, @@ -3106,6 +3140,11 @@ export type { TestAnalyticsData, TestAnalyticsResponse, TestAnalyticsResponses, + TestAutomationData, + TestAutomationError, + TestAutomationErrors, + TestAutomationResponse, + TestAutomationResponses, TestBridgeData, TestBridgeResponse, TestBridgeResponses, @@ -3115,6 +3154,11 @@ export type { TestDecisionsData, TestDecisionsResponse, TestDecisionsResponses, + TestDraftData, + TestDraftError, + TestDraftErrors, + TestDraftResponse, + TestDraftResponses, TestEmbeddingsData, TestEmbeddingsResponse, TestEmbeddingsResponses, @@ -3280,6 +3324,11 @@ export type { UnsealVaultErrors, UnsealVaultResponse, UnsealVaultResponses, + UpcomingData, + UpcomingError, + UpcomingErrors, + UpcomingResponse, + UpcomingResponses, UpdateAssistantMemoryData, UpdateAssistantMemoryError, UpdateAssistantMemoryErrors, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 6a61d72e2..b93cd1e5b 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -273,6 +273,9 @@ import type { DecideApprovalData, DecideApprovalErrors, DecideApprovalResponses, + DecideHeldRun2Data, + DecideHeldRun2Errors, + DecideHeldRun2Responses, DecideHeldRunData, DecideHeldRunErrors, DecideHeldRunResponses, @@ -653,6 +656,9 @@ import type { GetRoutineData, GetRoutineErrors, GetRoutineResponses, + GetRun2Data, + GetRun2Errors, + GetRun2Responses, GetRunData, GetRunErrors, GetRunResponses, @@ -964,6 +970,9 @@ import type { ListRolesResponses, ListRoutinesData, ListRoutinesResponses, + ListRuns2Data, + ListRuns2Errors, + ListRuns2Responses, ListRunsData, ListRunsErrors, ListRunsResponses, @@ -1320,6 +1329,9 @@ import type { RotateNotifySecretData, RotateNotifySecretErrors, RotateNotifySecretResponses, + RunAutomationData, + RunAutomationErrors, + RunAutomationResponses, RunData, RunErrors, RunPipelineData, @@ -1329,6 +1341,9 @@ import type { RunRoutineData, RunRoutineErrors, RunRoutineResponses, + RunsCausedData, + RunsCausedErrors, + RunsCausedResponses, RunWorkflowData, RunWorkflowErrors, RunWorkflowResponses, @@ -1483,12 +1498,18 @@ import type { TelemetryStatusResponses, TestAnalyticsData, TestAnalyticsResponses, + TestAutomationData, + TestAutomationErrors, + TestAutomationResponses, TestBridgeData, TestBridgeResponses, TestConversionNodeData, TestConversionNodeResponses, TestDecisionsData, TestDecisionsResponses, + TestDraftData, + TestDraftErrors, + TestDraftResponses, TestEmbeddingsData, TestEmbeddingsResponses, TestExtensionData, @@ -1576,6 +1597,9 @@ import type { UnsealVaultData, UnsealVaultErrors, UnsealVaultResponses, + UpcomingData, + UpcomingErrors, + UpcomingResponses, UpdateAssistantMemoryData, UpdateAssistantMemoryErrors, UpdateAssistantMemoryResponses, @@ -4113,6 +4137,137 @@ export class Automations { }, }); } + + /** + * Runs Caused + * + * What an activity caused: the runs of your automations it started (it was their event, or one of a join's). + */ + public static runsCaused( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/automations/runs", + ...options, + }); + } + + /** + * Get Run + * + * One run: what each node did (trace), its log, and what its actions did, asked or wait to do (intents). + */ + public static getRun( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/automations/runs/{run}", + ...options, + }); + } + + /** + * Decide Held Run + * + * Pick for a run held over a budget: run it now, once, whatever its budgets say, or skip it. + */ + public static decideHeldRun( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/automations/runs/{run}/decide", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Test Draft + * + * Try an automation before you save it: a dry run on an activity, or on a kind's sample (default: its first + * trigger's kind). Says whether its If passes and what each action would do; keeps, sends and counts nothing. + */ + public static testDraft( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/automations/test", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Test Automation + * + * Try a saved automation: a dry run on an activity, or on a kind's sample (default: its first trigger's kind). + * Keeps, sends and counts nothing. + */ + public static testAutomation( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/automations/{aid}/test", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Run Automation + * + * Run it now: on an activity, else the newest one its triggers listen for, else as started by hand. It acts as it + * would on its own: limits and budgets apply, and actions that ask first wait for your pick. + */ + public static runAutomation( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/automations/{aid}/run", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * List Runs + * + * Its runs, newest first; `next` pages on. + */ + public static listRuns( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/automations/{aid}/runs", + ...options, + }); + } + + /** + * Upcoming + * + * When it runs next, from its schedules and timers (coming soon: empty until schedules are built). + */ + public static upcoming( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/automations/{aid}/upcoming", + ...options, + }); + } } export class Budgets { @@ -10622,9 +10777,9 @@ export class Routines { * Pick for a run held over a budget: run it now, once, whatever its budgets say, or skip it. */ public static decideHeldRun( - options: Options, - ): RequestResult { - return (options.client ?? client).post({ + options: Options, + ): RequestResult { + return (options.client ?? client).post({ url: "/api/v1/routines/runs/{run_id}/decide", ...options, headers: { @@ -10638,9 +10793,9 @@ export class Routines { * List Runs */ public static listRuns( - options: Options, - ): RequestResult { - return (options.client ?? client).get({ + options: Options, + ): RequestResult { + return (options.client ?? client).get({ url: "/api/v1/routines/{rid}/runs", ...options, }); @@ -10650,9 +10805,9 @@ export class Routines { * Get Run */ public static getRun( - options: Options, - ): RequestResult { - return (options.client ?? client).get({ + options: Options, + ): RequestResult { + return (options.client ?? client).get({ url: "/api/v1/routine-runs/{run_id}", ...options, }); diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index ac19e0598..9f85dbefc 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -1558,6 +1558,26 @@ export type Automation = { * when it was deleted (restore brings it back) */ removed_at?: string | null; + /** + * Waiting + * + * in lists: its actions waiting for your pick or for their time + */ + waiting?: number | null; + /** + * Cost Month + * + * in lists: what it cost this month {cost_usd, estimate (true when some calls had no price)} + */ + cost_month?: { + [key: string]: unknown; + } | null; + /** + * Next At + * + * in lists: when it runs next, from its schedules (coming soon) + */ + next_at?: string | null; [key: string]: unknown; }; @@ -1658,6 +1678,34 @@ export type AutomationCreate = { } | null; }; +/** + * AutomationDraftTry + */ +export type AutomationDraftTry = { + /** + * Activity + * + * an activity's id to run it on (GET /api/v1/activities) + */ + activity?: string | null; + /** + * As + * + * which trigger it runs as (its `as`); default: the first that fits + */ + as?: string | null; + /** + * Kind + * + * else a kind of activity, to run it on that kind's sample + */ + kind?: string | null; + /** + * the automation as you would save it + */ + draft: AutomationCreate; +}; + /** * AutomationPolicy */ @@ -1676,6 +1724,303 @@ export type AutomationPolicy = { value: "ask" | "auto"; }; +/** + * AutomationRun + */ +export type AutomationRun = { + /** + * Id + */ + id: number; + /** + * Automation + */ + automation: number; + /** + * Name + */ + name?: string | null; + /** + * Version + * + * the workflow version it ran + */ + version?: number | null; + /** + * Trigger + * + * the trigger (its `as`) that started it + */ + trigger?: string | null; + /** + * Trigger On + */ + trigger_on?: string | null; + /** + * Event + * + * the activity that started it (an id) + */ + event?: string | null; + /** + * Event Ids + * + * every activity it ran on (a join's are several) + */ + event_ids?: Array; + /** + * Status + * + * running, done, partly (some actions failed), failed, waiting (actions wait for your pick or their time), held (over a budget: decide), released or skipped (your pick on a held run) + */ + status: string; + /** + * By + * + * who started it by hand + */ + by?: string | null; + /** + * Started At + */ + started_at?: string | null; + /** + * Finished At + */ + finished_at?: string | null; + /** + * Counts + * + * its actions: {done, waiting, scheduled, failed} + */ + counts?: { + [key: string]: number; + }; + /** + * Cost Usd + */ + cost_usd?: number | null; + /** + * Tokens + */ + tokens?: number | null; + /** + * Cost Estimate + * + * true when some calls had no price, so the cost is a floor + */ + cost_estimate?: boolean | null; + /** + * Error + */ + error?: string | null; + /** + * Why + * + * why it was held + */ + why?: string | null; + /** + * Hold + * + * a held run: the budget it is over and how many runs it missed + */ + hold?: { + [key: string]: unknown; + } | null; + /** + * Cause Depth + * + * how many automations' runs led to this one + */ + cause_depth?: number | null; + /** + * Space + */ + space?: number | null; + /** + * Dry + */ + dry?: boolean | null; + [key: string]: unknown; +}; + +/** + * AutomationRunDetail + */ +export type AutomationRunDetail = { + /** + * Id + */ + id: number; + /** + * Automation + */ + automation: number; + /** + * Name + */ + name?: string | null; + /** + * Version + * + * the workflow version it ran + */ + version?: number | null; + /** + * Trigger + * + * the trigger (its `as`) that started it + */ + trigger?: string | null; + /** + * Trigger On + */ + trigger_on?: string | null; + /** + * Event + * + * the activity that started it (an id) + */ + event?: string | null; + /** + * Event Ids + * + * every activity it ran on (a join's are several) + */ + event_ids?: Array; + /** + * Status + * + * running, done, partly (some actions failed), failed, waiting (actions wait for your pick or their time), held (over a budget: decide), released or skipped (your pick on a held run) + */ + status: string; + /** + * By + * + * who started it by hand + */ + by?: string | null; + /** + * Started At + */ + started_at?: string | null; + /** + * Finished At + */ + finished_at?: string | null; + /** + * Counts + * + * its actions: {done, waiting, scheduled, failed} + */ + counts?: { + [key: string]: number; + }; + /** + * Cost Usd + */ + cost_usd?: number | null; + /** + * Tokens + */ + tokens?: number | null; + /** + * Cost Estimate + * + * true when some calls had no price, so the cost is a floor + */ + cost_estimate?: boolean | null; + /** + * Error + */ + error?: string | null; + /** + * Why + * + * why it was held + */ + why?: string | null; + /** + * Hold + * + * a held run: the budget it is over and how many runs it missed + */ + hold?: { + [key: string]: unknown; + } | null; + /** + * Cause Depth + * + * how many automations' runs led to this one + */ + cause_depth?: number | null; + /** + * Space + */ + space?: number | null; + /** + * Dry + */ + dry?: boolean | null; + /** + * Trace + * + * by node id: what each node took in and passed on + */ + trace?: { + [key: string]: unknown; + }; + /** + * Log + */ + log?: Array; + /** + * Intents + * + * what its actions did, asked or wait to do: action, params, effect, risk, status, result + */ + intents?: Array<{ + [key: string]: unknown; + }>; + [key: string]: unknown; +}; + +/** + * AutomationRunNow + */ +export type AutomationRunNow = { + /** + * Activity + * + * an activity's id to run it on (GET /api/v1/activities) + */ + activity?: string | null; + /** + * As + * + * which trigger it runs as (its `as`); default: the first that fits + */ + as?: string | null; +}; + +/** + * AutomationRuns + */ +export type AutomationRuns = { + /** + * Runs + */ + runs: Array; + /** + * Next + * + * for the page after: pass it as `before` + */ + next?: number | null; + [key: string]: unknown; +}; + /** * AutomationSaved */ @@ -1695,6 +2040,29 @@ export type AutomationSaved = { [key: string]: unknown; }; +/** + * AutomationStarted + */ +export type AutomationStarted = { + /** + * Run + * + * the run's id (GET /automations/runs/{run}); none when nothing ran + */ + run?: number | null; + /** + * Status + */ + status?: string | null; + /** + * Why + * + * why it didn't run, or was held + */ + why?: string | null; + [key: string]: unknown; +}; + /** * AutomationSwitch */ @@ -1705,6 +2073,86 @@ export type AutomationSwitch = { on?: boolean; }; +/** + * AutomationTried + */ +export type AutomationTried = { + /** + * Status + * + * done, waiting, partly or failed as it would end; skipped when its If is false (limits and budgets aren't checked: a try costs no run) + */ + status?: string | null; + /** + * Why + */ + why?: string | null; + /** + * Trace + */ + trace?: { + [key: string]: unknown; + }; + /** + * Log + */ + log?: Array; + /** + * Intents + * + * what each action would do (nothing is done) + */ + intents?: Array<{ + [key: string]: unknown; + }>; + /** + * Error + */ + error?: string | null; + /** + * Steps + */ + steps?: number; + [key: string]: unknown; +}; + +/** + * AutomationTry + */ +export type AutomationTry = { + /** + * Activity + * + * an activity's id to run it on (GET /api/v1/activities) + */ + activity?: string | null; + /** + * As + * + * which trigger it runs as (its `as`); default: the first that fits + */ + as?: string | null; + /** + * Kind + * + * else a kind of activity, to run it on that kind's sample + */ + kind?: string | null; +}; + +/** + * AutomationUpcoming + */ +export type AutomationUpcoming = { + /** + * Times + * + * when it runs next, from its schedules and timers (coming soon) + */ + times?: Array; + [key: string]: unknown; +}; + /** * AutomationUpdate */ @@ -26266,6 +26714,267 @@ export type SetPolicyResponses = { export type SetPolicyResponse = SetPolicyResponses[keyof SetPolicyResponses]; +export type RunsCausedData = { + body?: never; + path?: never; + query: { + /** + * Activity + * + * an activity's id + */ + activity: string; + }; + url: "/api/v1/automations/runs"; +}; + +export type RunsCausedErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type RunsCausedError = RunsCausedErrors[keyof RunsCausedErrors]; + +export type RunsCausedResponses = { + /** + * Response Automations-Runs Caused + * + * Successful Response + */ + 200: Array; +}; + +export type RunsCausedResponse = RunsCausedResponses[keyof RunsCausedResponses]; + +export type GetRunData = { + body?: never; + path: { + /** + * Run + */ + run: number; + }; + query?: never; + url: "/api/v1/automations/runs/{run}"; +}; + +export type GetRunErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type GetRunError = GetRunErrors[keyof GetRunErrors]; + +export type GetRunResponses = { + /** + * Successful Response + */ + 200: AutomationRunDetail; +}; + +export type GetRunResponse = GetRunResponses[keyof GetRunResponses]; + +export type DecideHeldRunData = { + body: HeldRunDecision; + path: { + /** + * Run + */ + run: number; + }; + query?: never; + url: "/api/v1/automations/runs/{run}/decide"; +}; + +export type DecideHeldRunErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type DecideHeldRunError = DecideHeldRunErrors[keyof DecideHeldRunErrors]; + +export type DecideHeldRunResponses = { + /** + * Successful Response + */ + 200: AutomationStarted; +}; + +export type DecideHeldRunResponse = DecideHeldRunResponses[keyof DecideHeldRunResponses]; + +export type TestDraftData = { + body: AutomationDraftTry; + path?: never; + query?: never; + url: "/api/v1/automations/test"; +}; + +export type TestDraftErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type TestDraftError = TestDraftErrors[keyof TestDraftErrors]; + +export type TestDraftResponses = { + /** + * Successful Response + */ + 200: AutomationTried; +}; + +export type TestDraftResponse = TestDraftResponses[keyof TestDraftResponses]; + +export type TestAutomationData = { + /** + * Body + */ + body?: AutomationTry | null; + path: { + /** + * Aid + */ + aid: number; + }; + query?: never; + url: "/api/v1/automations/{aid}/test"; +}; + +export type TestAutomationErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type TestAutomationError = TestAutomationErrors[keyof TestAutomationErrors]; + +export type TestAutomationResponses = { + /** + * Successful Response + */ + 200: AutomationTried; +}; + +export type TestAutomationResponse = TestAutomationResponses[keyof TestAutomationResponses]; + +export type RunAutomationData = { + /** + * Body + */ + body?: AutomationRunNow | null; + path: { + /** + * Aid + */ + aid: number; + }; + query?: never; + url: "/api/v1/automations/{aid}/run"; +}; + +export type RunAutomationErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type RunAutomationError = RunAutomationErrors[keyof RunAutomationErrors]; + +export type RunAutomationResponses = { + /** + * Successful Response + */ + 200: AutomationStarted; +}; + +export type RunAutomationResponse = RunAutomationResponses[keyof RunAutomationResponses]; + +export type ListRunsData = { + body?: never; + path: { + /** + * Aid + */ + aid: number; + }; + query?: { + /** + * Before + * + * a run id: the runs before it + */ + before?: number | null; + /** + * Limit + */ + limit?: number; + }; + url: "/api/v1/automations/{aid}/runs"; +}; + +export type ListRunsErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type ListRunsError = ListRunsErrors[keyof ListRunsErrors]; + +export type ListRunsResponses = { + /** + * Successful Response + */ + 200: AutomationRuns; +}; + +export type ListRunsResponse = ListRunsResponses[keyof ListRunsResponses]; + +export type UpcomingData = { + body?: never; + path: { + /** + * Aid + */ + aid: number; + }; + query?: { + /** + * N + */ + n?: number; + }; + url: "/api/v1/automations/{aid}/upcoming"; +}; + +export type UpcomingErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type UpcomingError = UpcomingErrors[keyof UpcomingErrors]; + +export type UpcomingResponses = { + /** + * Successful Response + */ + 200: AutomationUpcoming; +}; + +export type UpcomingResponse = UpcomingResponses[keyof UpcomingResponses]; + export type RemoveBudgetData = { body?: never; path?: never; @@ -26273,7 +26982,7 @@ export type RemoveBudgetData = { /** * Resource * - * all (everything Lens spends), routine:, pipeline:, workflow: or space: + * all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space: */ resource: string; }; @@ -26323,7 +27032,7 @@ export type SetBudgetData = { /** * Resource * - * all (everything Lens spends), routine:, pipeline:, workflow: or space: + * all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space: */ resource: string; }; @@ -26399,7 +27108,7 @@ export type BudgetStatusData = { /** * Resource * - * all (everything Lens spends), routine:, pipeline:, workflow: or space: + * all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space: */ resource: string; }; @@ -39049,7 +39758,7 @@ export type RunRoutineResponses = { export type RunRoutineResponse = RunRoutineResponses[keyof RunRoutineResponses]; -export type DecideHeldRunData = { +export type DecideHeldRun2Data = { body: HeldRunDecision; path: { /** @@ -39061,25 +39770,25 @@ export type DecideHeldRunData = { url: "/api/v1/routines/runs/{run_id}/decide"; }; -export type DecideHeldRunErrors = { +export type DecideHeldRun2Errors = { /** * Validation Error */ 422: HttpValidationError; }; -export type DecideHeldRunError = DecideHeldRunErrors[keyof DecideHeldRunErrors]; +export type DecideHeldRun2Error = DecideHeldRun2Errors[keyof DecideHeldRun2Errors]; -export type DecideHeldRunResponses = { +export type DecideHeldRun2Responses = { /** * Successful Response */ 200: Ok; }; -export type DecideHeldRunResponse = DecideHeldRunResponses[keyof DecideHeldRunResponses]; +export type DecideHeldRun2Response = DecideHeldRun2Responses[keyof DecideHeldRun2Responses]; -export type ListRunsData = { +export type ListRuns2Data = { body?: never; path: { /** @@ -39096,16 +39805,16 @@ export type ListRunsData = { url: "/api/v1/routines/{rid}/runs"; }; -export type ListRunsErrors = { +export type ListRuns2Errors = { /** * Validation Error */ 422: HttpValidationError; }; -export type ListRunsError = ListRunsErrors[keyof ListRunsErrors]; +export type ListRuns2Error = ListRuns2Errors[keyof ListRuns2Errors]; -export type ListRunsResponses = { +export type ListRuns2Responses = { /** * Response Routines-List Runs * @@ -39114,9 +39823,9 @@ export type ListRunsResponses = { 200: Array; }; -export type ListRunsResponse = ListRunsResponses[keyof ListRunsResponses]; +export type ListRuns2Response = ListRuns2Responses[keyof ListRuns2Responses]; -export type GetRunData = { +export type GetRun2Data = { body?: never; path: { /** @@ -39128,23 +39837,23 @@ export type GetRunData = { url: "/api/v1/routine-runs/{run_id}"; }; -export type GetRunErrors = { +export type GetRun2Errors = { /** * Validation Error */ 422: HttpValidationError; }; -export type GetRunError = GetRunErrors[keyof GetRunErrors]; +export type GetRun2Error = GetRun2Errors[keyof GetRun2Errors]; -export type GetRunResponses = { +export type GetRun2Responses = { /** * Successful Response */ 200: RoutineRun; }; -export type GetRunResponse = GetRunResponses[keyof GetRunResponses]; +export type GetRun2Response = GetRun2Responses[keyof GetRun2Responses]; export type UndoRunData = { body?: never; diff --git a/nextjs-frontend/components/settings/bodies.tsx b/nextjs-frontend/components/settings/bodies.tsx index e8c8522bd..9f2b7f1f9 100644 --- a/nextjs-frontend/components/settings/bodies.tsx +++ b/nextjs-frontend/components/settings/bodies.tsx @@ -472,6 +472,13 @@ export function SectionBody({ ctx }: { ctx: BodyCtx }) { case "automations": return ( <> + +
+ + + +
+ The stream of activities
@@ -479,7 +486,8 @@ export function SectionBody({ ctx }: { ctx: BodyCtx }) {

- Agents read the same stream with the timeline tool (MCP and the assistant) or GET /api/v1/activities. + Agents read the same stream with the timeline tool (MCP and the assistant) or GET /api/v1/activities, and + manage automations over /api/v1/automations.

); diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts index bb8302df6..05684aa54 100644 --- a/nextjs-frontend/components/settings/model.ts +++ b/nextjs-frontend/components/settings/model.ts @@ -393,9 +393,9 @@ export const SECTIONS: SectionSpec[] = [ { id: "automations", label: "Automations", - backend: ["events", "automations"], + backend: ["automations", "events"], description: - "The stream of activities automations follow (new assets and what else happens in Lens): how often followers look for new ones, how long activities with no row of their own are kept, how long an automation’s action waits for your pick, and how late a timer may still fire after Lens was off.", + "Whether automations run, how far one automation may set off another, how many runs a minute they may make together, how long runs are kept, how late a timer may still fire after Lens was off, how long an automation’s action waits for your pick; and the stream of activities they follow (new assets and what else happens in Lens).", }, { id: "startup", @@ -2678,33 +2678,40 @@ export const FIELDS: FieldSpec[] = [ max: 20, hint: "A failed send waits 30 seconds, then four times longer each time, up to 6 hours", }, - // Automations (the stream of activities) + // Automations { - section: "events", - key: "poll_seconds", - label: "Look for new activities every (seconds)", + section: "automations", + key: "enabled", + label: "Run automations", + kind: "switch", + hint: "Off: no automation runs and nothing is lost; switched back on, they react to what happens from then on", + }, + { + section: "automations", + key: "max_depth", + label: "Automations one run may set off", kind: "int", min: 1, - max: 3600, - hint: "New assets wake followers on this server at once; this is how often they look anyway", + max: 10, + hint: "How long a chain of automations setting each other off may get, so two can't loop forever", }, { - section: "events", - key: "keep_days", - label: "Keep logged activities (days)", + section: "automations", + key: "max_runs_per_minute", + label: "Runs a minute, all automations together", kind: "int", min: 1, - max: 3650, - hint: "Activities with no row of their own, such as an automation’s; new assets and other rows stay as long as they do", + max: 6000, + hint: "Each automation also has its own most runs an hour and wait between runs", }, { section: "automations", - key: "approval_days", - label: "An automation’s action waits for your pick (days)", + key: "keep_runs_days", + label: "Keep runs (days)", kind: "int", min: 1, - max: 365, - hint: "Then it expires and nothing runs; you decide in Approvals", + max: 3650, + hint: "Each automation keeps its last 20 runs however old they are", }, { section: "automations", @@ -2722,6 +2729,34 @@ export const FIELDS: FieldSpec[] = [ ], hint: "Schedules and actions that wait; one that missed several times runs once, and older ones count as missed", }, + { + section: "automations", + key: "approval_days", + label: "An automation’s action waits for your pick (days)", + kind: "int", + min: 1, + max: 365, + hint: "Then it expires and nothing runs; you decide in Approvals", + }, + // The stream of activities automations follow + { + section: "events", + key: "poll_seconds", + label: "Look for new activities every (seconds)", + kind: "int", + min: 1, + max: 3600, + hint: "New assets wake followers on this server at once; this is how often they look anyway", + }, + { + section: "events", + key: "keep_days", + label: "Keep logged activities (days)", + kind: "int", + min: 1, + max: 3650, + hint: "Activities with no row of their own, such as an automation’s; new assets and other rows stay as long as they do", + }, // Usage analytics (Google Analytics opt-in) { section: "analytics", diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 14784682b..7eacbd785 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -5958,14 +5958,27 @@ } } }, - "/api/v1/budgets": { + "/api/v1/automations/runs": { "get": { "tags": [ - "budgets" + "automations" + ], + "summary": "Runs Caused", + "description": "What an activity caused: the runs of your automations it started (it was their event, or one of a join's).", + "operationId": "runs_caused", + "parameters": [ + { + "name": "activity", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "an activity's id", + "title": "Activity" + }, + "description": "an activity's id" + } ], - "summary": "List Budgets", - "description": "Every budget, with where it stands now.", - "operationId": "list_budgets", "responses": { "200": { "description": "Successful Response", @@ -5974,51 +5987,52 @@ "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/BudgetStatus" + "$ref": "#/components/schemas/AutomationRun" }, - "title": "Response Budgets-List Budgets" + "title": "Response Automations-Runs Caused" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" } } } } } - }, - "put": { + } + }, + "/api/v1/automations/runs/{run}": { + "get": { "tags": [ - "budgets" + "automations" ], - "summary": "Set Budget", - "operationId": "set_budget", + "summary": "Get Run", + "description": "One run: what each node did (trace), its log, and what its actions did, asked or wait to do (intents).", + "operationId": "get_run", "parameters": [ { - "name": "resource", - "in": "query", + "name": "run", + "in": "path", "required": true, "schema": { - "type": "string", - "description": "all (everything Lens spends), routine:, pipeline:, workflow: or space:", - "title": "Resource" - }, - "description": "all (everything Lens spends), routine:, pipeline:, workflow: or space:" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BudgetSet" - } + "type": "integer", + "title": "Run" } } - }, + ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetStatus" + "$ref": "#/components/schemas/AutomationRunDetail" } } } @@ -6034,33 +6048,44 @@ } } } - }, - "delete": { + } + }, + "/api/v1/automations/runs/{run}/decide": { + "post": { "tags": [ - "budgets" + "automations" ], - "summary": "Remove Budget", - "operationId": "remove_budget", + "summary": "Decide Held Run", + "description": "Pick for a run held over a budget: run it now, once, whatever its budgets say, or skip it.", + "operationId": "decide_held_run", "parameters": [ { - "name": "resource", - "in": "query", + "name": "run", + "in": "path", "required": true, "schema": { - "type": "string", - "description": "all (everything Lens spends), routine:, pipeline:, workflow: or space:", - "title": "Resource" - }, - "description": "all (everything Lens spends), routine:, pipeline:, workflow: or space:" + "type": "integer", + "title": "Run" + } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HeldRunDecision" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Ok" + "$ref": "#/components/schemas/AutomationStarted" } } } @@ -6078,76 +6103,31 @@ } } }, - "/api/v1/budgets/meter": { - "get": { + "/api/v1/automations/test": { + "post": { "tags": [ - "budgets" + "automations" ], - "summary": "Budget Meter", - "description": "What a namespace (or all of Lens) spent this day, week or month, against its budget when it has one: the top\nbar's meter, and with `detail` the costs page. Anyone who can read a namespace sees its meter; admins see all of\nLens's.", - "operationId": "budget_meter", - "parameters": [ - { - "name": "ns", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "a namespace; none for all of Lens (admins)", - "title": "Ns" - }, - "description": "a namespace; none for all of Lens (admins)" - }, - { - "name": "period", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "enum": [ - "day", - "week", - "month" - ], - "type": "string" - }, - { - "type": "null" - } - ], - "description": "none: the budget's own period, else month", - "title": "Period" - }, - "description": "none: the budget's own period, else month" + "summary": "Test Draft", + "description": "Try an automation before you save it: a dry run on an activity, or on a kind's sample (default: its first\ntrigger's kind). Says whether its If passes and what each action would do; keeps, sends and counts nothing.", + "operationId": "test_draft", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AutomationDraftTry" + } + } }, - { - "name": "detail", - "in": "query", - "required": false, - "schema": { - "type": "boolean", - "description": "also by day, by model and what cost most", - "default": false, - "title": "Detail" - }, - "description": "also by day, by model and what cost most" - } - ], + "required": true + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetMeter" + "$ref": "#/components/schemas/AutomationTried" } } } @@ -6165,34 +6145,49 @@ } } }, - "/api/v1/budgets/status": { - "get": { + "/api/v1/automations/{aid}/test": { + "post": { "tags": [ - "budgets" + "automations" ], - "summary": "Budget Status", - "description": "Where a resource's budget stands, and what its next run will likely cost (also without a budget).", - "operationId": "budget_status", + "summary": "Test Automation", + "description": "Try a saved automation: a dry run on an activity, or on a kind's sample (default: its first trigger's kind).\nKeeps, sends and counts nothing.", + "operationId": "test_automation", "parameters": [ { - "name": "resource", - "in": "query", + "name": "aid", + "in": "path", "required": true, "schema": { - "type": "string", - "description": "all (everything Lens spends), routine:, pipeline:, workflow: or space:", - "title": "Resource" - }, - "description": "all (everything Lens spends), routine:, pipeline:, workflow: or space:" + "type": "integer", + "title": "Aid" + } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/AutomationTry" + }, + { + "type": "null" + } + ], + "title": "Body" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetStatus" + "$ref": "#/components/schemas/AutomationTried" } } } @@ -6210,42 +6205,59 @@ } } }, - "/api/v1/admin/fedora": { - "get": { + "/api/v1/automations/{aid}/run": { + "post": { "tags": [ - "fedora" + "automations" ], - "summary": "Get Fedora Status", - "operationId": "get_fedora_status", + "summary": "Run Automation", + "description": "Run it now: on an activity, else the newest one its triggers listen for, else as started by hand. It acts as it\nwould on its own: limits and budgets apply, and actions that ask first wait for your pick.", + "operationId": "run_automation", + "parameters": [ + { + "name": "aid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Aid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/AutomationRunNow" + }, + { + "type": "null" + } + ], + "title": "Body" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FedoraStatus" + "$ref": "#/components/schemas/AutomationStarted" } } } - } - } - } - }, - "/api/v1/admin/fedora/sync": { - "post": { - "tags": [ - "fedora" - ], - "summary": "Sync Fedora", - "description": "Compare everything with Fedora now and send what differs (the background sync does this every fedora.full_hours).", - "operationId": "sync_fedora", - "responses": { - "200": { - "description": "Successful Response", + }, + "422": { + "description": "Validation Error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FedoraSyncResult" + "$ref": "#/components/schemas/HTTPValidationError" } } } @@ -6253,53 +6265,62 @@ } } }, - "/api/v1/setup": { + "/api/v1/automations/{aid}/runs": { "get": { "tags": [ - "setup" + "automations" ], - "summary": "Get Setup", - "description": "What is set already, and which fields .env or archive.yaml locks.", - "operationId": "get_setup", - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SetupView" + "summary": "List Runs", + "description": "Its runs, newest first; `next` pages on.", + "operationId": "list_runs", + "parameters": [ + { + "name": "aid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Aid" + } + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" } - } + ], + "description": "a run id: the runs before it", + "title": "Before" + }, + "description": "a run id: the runs before it" + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 100, + "minimum": 1, + "default": 20, + "title": "Limit" } } - } - } - }, - "/api/v1/setup/namespace": { - "post": { - "tags": [ - "setup" ], - "summary": "Save Namespace", - "description": "Create the first namespace (or set the graph mode of one that exists).", - "operationId": "save_namespace", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SetupNamespace" - } - } - }, - "required": true - }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SetupSaved" + "$ref": "#/components/schemas/AutomationRuns" } } } @@ -6317,31 +6338,44 @@ } } }, - "/api/v1/setup/llm": { - "put": { + "/api/v1/automations/{aid}/upcoming": { + "get": { "tags": [ - "setup" + "automations" ], - "summary": "Save Llm", - "description": "The model provider: an OpenAI-compatible server's address, the model, and its key (empty: unchanged).", - "operationId": "save_llm", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SetupLlm" - } + "summary": "Upcoming", + "description": "When it runs next, from its schedules and timers (coming soon: empty until schedules are built).", + "operationId": "upcoming", + "parameters": [ + { + "name": "aid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Aid" } }, - "required": true - }, + { + "name": "n", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 100, + "minimum": 1, + "default": 10, + "title": "N" + } + } + ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SetupSaved" + "$ref": "#/components/schemas/AutomationUpcoming" } } } @@ -6359,117 +6393,59 @@ } } }, - "/api/v1/setup/llm/detect": { + "/api/v1/budgets": { "get": { "tags": [ - "setup" + "budgets" ], - "summary": "Detect Llm", - "description": "Model servers running on this machine or the Docker host (Ollama, LM Studio, llama.cpp, vLLM, LocalAI), with\ntheir models, so the wizard can offer one instead of asking for an address.", - "operationId": "detect_llm", + "summary": "List Budgets", + "description": "Every budget, with where it stands now.", + "operationId": "list_budgets", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "items": { - "$ref": "#/components/schemas/LocalModelServer" - }, "type": "array", - "title": "Response Setup-Detect Llm" - } - } - } - } - } - } - }, - "/api/v1/setup/llm/providers": { - "get": { - "tags": [ - "setup" - ], - "summary": "Llm Providers", - "description": "Cloud providers with an OpenAI-compatible API (OpenAI, Anthropic, Gemini, ...), each with its address and a\nmodel, so picking one leaves only the API key to paste.", - "operationId": "llm_providers", - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { "items": { - "$ref": "#/components/schemas/CloudModelProvider" + "$ref": "#/components/schemas/BudgetStatus" }, - "type": "array", - "title": "Response Setup-Llm Providers" + "title": "Response Budgets-List Budgets" } } } } } - } - }, - "/api/v1/setup/storage": { + }, "put": { "tags": [ - "setup" + "budgets" ], - "summary": "Save Storage", - "description": "The upload limit, and optionally a folder on this machine (inside sources.local_roots) to watch.", - "operationId": "save_storage", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SetupStorage" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SetupSaved" - } - } - } - }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } - } + "summary": "Set Budget", + "operationId": "set_budget", + "parameters": [ + { + "name": "resource", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space:", + "title": "Resource" + }, + "description": "all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space:" } - } - } - }, - "/api/v1/setup/telemetry": { - "put": { - "tags": [ - "setup" ], - "summary": "Save Telemetry", - "description": "Opt in to telemetry: traces and metrics sent only to this endpoint (an OTLP collector), and usage statistics\nto your own Google Analytics property when `analytics` is true. Each is off unless chosen.", - "operationId": "save_telemetry", "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SetupTelemetry" + "$ref": "#/components/schemas/BudgetSet" } } - }, - "required": true + } }, "responses": { "200": { @@ -6477,7 +6453,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SetupSaved" + "$ref": "#/components/schemas/BudgetStatus" } } } @@ -6493,33 +6469,33 @@ } } } - } - }, - "/api/v1/setup/budget": { - "put": { + }, + "delete": { "tags": [ - "setup" + "budgets" + ], + "summary": "Remove Budget", + "operationId": "remove_budget", + "parameters": [ + { + "name": "resource", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space:", + "title": "Resource" + }, + "description": "all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space:" + } ], - "summary": "Save Budget", - "description": "The overall AI budget: a soft limit that warns and a hard limit where runs wait and paid model calls stop\n(docs/budgets.md#one-budget-for-everything), with the chat model's price so its spending is counted. No hard\nlimit: no budget.", - "operationId": "save_budget", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SetupBudget" - } - } - }, - "required": true - }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SetupSaved" + "$ref": "#/components/schemas/Ok" } } } @@ -6537,31 +6513,76 @@ } } }, - "/api/v1/setup/oauth": { - "put": { + "/api/v1/budgets/meter": { + "get": { "tags": [ - "setup" + "budgets" ], - "summary": "Save Oauth", - "description": "Let apps and AI assistants (MCP clients such as Claude or Cursor) sign people in with their Lens account, or\nnot, and how long their tokens last (docs/authentication.md#oauth). On unless turned off.", - "operationId": "save_oauth", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SetupOAuth" - } - } + "summary": "Budget Meter", + "description": "What a namespace (or all of Lens) spent this day, week or month, against its budget when it has one: the top\nbar's meter, and with `detail` the costs page. Anyone who can read a namespace sees its meter; admins see all of\nLens's.", + "operationId": "budget_meter", + "parameters": [ + { + "name": "ns", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "a namespace; none for all of Lens (admins)", + "title": "Ns" + }, + "description": "a namespace; none for all of Lens (admins)" }, - "required": true - }, + { + "name": "period", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "enum": [ + "day", + "week", + "month" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "description": "none: the budget's own period, else month", + "title": "Period" + }, + "description": "none: the budget's own period, else month" + }, + { + "name": "detail", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "description": "also by day, by model and what cost most", + "default": false, + "title": "Detail" + }, + "description": "also by day, by model and what cost most" + } + ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SetupSaved" + "$ref": "#/components/schemas/BudgetMeter" } } } @@ -6579,31 +6600,34 @@ } } }, - "/api/v1/setup/finish": { - "post": { + "/api/v1/budgets/status": { + "get": { "tags": [ - "setup" + "budgets" + ], + "summary": "Budget Status", + "description": "Where a resource's budget stands, and what its next run will likely cost (also without a budget).", + "operationId": "budget_status", + "parameters": [ + { + "name": "resource", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space:", + "title": "Resource" + }, + "description": "all (everything Lens spends), routine:, automation:, pipeline:, workflow: or space:" + } ], - "summary": "Finish", - "description": "Finish (or skip) the wizard; the web app stops showing it. Everything stays changeable in Settings. With no\nnamespace yet, the default one is made (saved: [\"namespace\"]).", - "operationId": "finish", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SetupFinish" - } - } - }, - "required": true - }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SetupSaved" + "$ref": "#/components/schemas/BudgetStatus" } } } @@ -6621,42 +6645,84 @@ } } }, - "/api/v1/namespaces": { + "/api/v1/admin/fedora": { "get": { "tags": [ - "namespaces" + "fedora" ], - "summary": "List Namespaces", - "description": "The namespaces you have a role in, with their counts, and those you see only some collections of (`partial`,\nno `role`): counted over those collections, without the namespace-wide people and word cloud.", - "operationId": "list_namespaces", + "summary": "Get Fedora Status", + "operationId": "get_fedora_status", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "items": { - "$ref": "#/components/schemas/Namespace" - }, - "type": "array", - "title": "Response Namespaces-List Namespaces" + "$ref": "#/components/schemas/FedoraStatus" } } } } } - }, + } + }, + "/api/v1/admin/fedora/sync": { "post": { "tags": [ - "namespaces" + "fedora" ], - "summary": "Create Namespace", - "operationId": "create_namespace", + "summary": "Sync Fedora", + "description": "Compare everything with Fedora now and send what differs (the background sync does this every fedora.full_hours).", + "operationId": "sync_fedora", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FedoraSyncResult" + } + } + } + } + } + } + }, + "/api/v1/setup": { + "get": { + "tags": [ + "setup" + ], + "summary": "Get Setup", + "description": "What is set already, and which fields .env or archive.yaml locks.", + "operationId": "get_setup", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupView" + } + } + } + } + } + } + }, + "/api/v1/setup/namespace": { + "post": { + "tags": [ + "setup" + ], + "summary": "Save Namespace", + "description": "Create the first namespace (or set the graph mode of one that exists).", + "operationId": "save_namespace", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceCreate" + "$ref": "#/components/schemas/SetupNamespace" } } }, @@ -6668,7 +6734,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Created" + "$ref": "#/components/schemas/SetupSaved" } } } @@ -6686,34 +6752,23 @@ } } }, - "/api/v1/namespaces/{name}": { - "patch": { + "/api/v1/setup/llm": { + "put": { "tags": [ - "namespaces" - ], - "summary": "Update Namespace", - "description": "Owners: the graph mode (shared or isolated), the default pipeline (null for the built-in one) and a pipeline per\ncontent type.", - "operationId": "update_namespace", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" - } - } + "setup" ], + "summary": "Save Llm", + "description": "The model provider: an OpenAI-compatible server's address, the model, and its key (empty: unchanged).", + "operationId": "save_llm", "requestBody": { - "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceUpdate" + "$ref": "#/components/schemas/SetupLlm" } } - } + }, + "required": true }, "responses": { "200": { @@ -6721,7 +6776,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Ok" + "$ref": "#/components/schemas/SetupSaved" } } } @@ -6739,75 +6794,75 @@ } } }, - "/api/v1/namespaces/{name}/nsfw": { + "/api/v1/setup/llm/detect": { "get": { "tags": [ - "namespaces" - ], - "summary": "Get Namespace Nsfw", - "description": "NSFW classification here (docs/nsfw.md): whether it's on, the threshold and how flagged resources show, what the\nnamespace chose for itself and the archive's settings, and how many resources are classified and flagged.", - "operationId": "get_namespace_nsfw", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" - } - } + "setup" ], + "summary": "Detect Llm", + "description": "Model servers running on this machine or the Docker host (Ollama, LM Studio, llama.cpp, vLLM, LocalAI), with\ntheir models, so the wizard can offer one instead of asking for an address.", + "operationId": "detect_llm", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceNsfw" - } - } - } - }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" + "items": { + "$ref": "#/components/schemas/LocalModelServer" + }, + "type": "array", + "title": "Response Setup-Detect Llm" } } } } } - }, - "put": { + } + }, + "/api/v1/setup/llm/providers": { + "get": { "tags": [ - "namespaces" + "setup" ], - "summary": "Update Namespace Nsfw", - "description": "Owners: turn NSFW classification on or off for this namespace, or give it its own threshold or display; null\nfollows the archive's setting again. A new threshold re-flags what's classified at once. `classify` also queues the\nnsfw step for its videos, documents and images not classified yet. Audited as `namespace.nsfw`.", - "operationId": "update_namespace_nsfw", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" + "summary": "Llm Providers", + "description": "Cloud providers with an OpenAI-compatible API (OpenAI, Anthropic, Gemini, ...), each with its address and a\nmodel, so picking one leaves only the API key to paste.", + "operationId": "llm_providers", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/CloudModelProvider" + }, + "type": "array", + "title": "Response Setup-Llm Providers" + } + } } } + } + } + }, + "/api/v1/setup/storage": { + "put": { + "tags": [ + "setup" ], + "summary": "Save Storage", + "description": "The upload limit, and optionally a folder on this machine (inside sources.local_roots) to watch.", + "operationId": "save_storage", "requestBody": { - "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceNsfwUpdate" + "$ref": "#/components/schemas/SetupStorage" } } - } + }, + "required": true }, "responses": { "200": { @@ -6815,7 +6870,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceNsfw" + "$ref": "#/components/schemas/SetupSaved" } } } @@ -6833,32 +6888,31 @@ } } }, - "/api/v1/namespaces/{name}/nsfw/classify": { - "post": { + "/api/v1/setup/telemetry": { + "put": { "tags": [ - "namespaces" + "setup" ], - "summary": "Classify Namespace Nsfw", - "description": "Editors: queue the nsfw step for the namespace's videos, documents and images not classified yet (those added\nwhile it's on are classified by their pipeline). 409 where classification is off.", - "operationId": "classify_namespace_nsfw", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" + "summary": "Save Telemetry", + "description": "Opt in to telemetry: traces and metrics sent only to this endpoint (an OTLP collector), and usage statistics\nto your own Google Analytics property when `analytics` is true. Each is off unless chosen.", + "operationId": "save_telemetry", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupTelemetry" + } } - } - ], + }, + "required": true + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/JobsQueued" + "$ref": "#/components/schemas/SetupSaved" } } } @@ -6876,30 +6930,33 @@ } } }, - "/api/v1/namespaces/{name}/wordcloud.svg": { - "get": { + "/api/v1/setup/budget": { + "put": { "tags": [ - "namespaces" + "setup" ], - "summary": "Get Namespace Wordcloud", - "description": "The namespace's word cloud. Accepts a bearer token or the signed link from the namespace list.", - "operationId": "get_namespace_wordcloud", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" + "summary": "Save Budget", + "description": "The overall AI budget: a soft limit that warns and a hard limit where runs wait and paid model calls stop\n(docs/budgets.md#one-budget-for-everything), with the chat model's price so its spending is counted. No hard\nlimit: no budget.", + "operationId": "save_budget", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupBudget" + } } - } - ], + }, + "required": true + }, "responses": { "200": { "description": "Successful Response", "content": { - "image/svg+xml": {} + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupSaved" + } + } } }, "422": { @@ -6915,84 +6972,31 @@ } } }, - "/api/v1/namespaces/{name}/stats": { - "get": { + "/api/v1/setup/oauth": { + "put": { "tags": [ - "namespaces" + "setup" ], - "summary": "Get Namespace Stats", - "description": "The namespace's numbers for the assets made in a range of days (the Reports overview): how many and how long,\nwho was heard and for how long, and the same per month. Without a range, every asset.", - "operationId": "get_namespace_stats", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" + "summary": "Save Oauth", + "description": "Let apps and AI assistants (MCP clients such as Claude or Cursor) sign people in with their Lens account, or\nnot, and how long their tokens last (docs/authentication.md#oauth). On unless turned off.", + "operationId": "save_oauth", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupOAuth" + } } }, - { - "name": "from", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "type": "string", - "format": "date" - }, - { - "type": "null" - } - ], - "description": "dated on or after this day", - "title": "From" - }, - "description": "dated on or after this day" - }, - { - "name": "to", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "type": "string", - "format": "date" - }, - { - "type": "null" - } - ], - "description": "dated on or before this day", - "title": "To" - }, - "description": "dated on or before this day" - }, - { - "name": "top", - "in": "query", - "required": false, - "schema": { - "type": "integer", - "maximum": 50, - "minimum": 1, - "description": "how many people in `top_speakers`", - "default": 5, - "title": "Top" - }, - "description": "how many people in `top_speakers`" - } - ], + "required": true + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceStats" + "$ref": "#/components/schemas/SetupSaved" } } } @@ -7010,32 +7014,31 @@ } } }, - "/api/v1/namespaces/{name}/ip-groups": { - "get": { + "/api/v1/setup/finish": { + "post": { "tags": [ - "namespaces" + "setup" ], - "summary": "List Ip Groups", - "description": "The namespace's IP groups (owners), and your address as the server sees it, to check the ranges against.", - "operationId": "list_ip_groups", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" + "summary": "Finish", + "description": "Finish (or skip) the wizard; the web app stops showing it. Everything stays changeable in Settings. With no\nnamespace yet, the default one is made (saved: [\"namespace\"]).", + "operationId": "finish", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupFinish" + } } - } - ], + }, + "required": true + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IpGroups" + "$ref": "#/components/schemas/SetupSaved" } } } @@ -7051,34 +7054,48 @@ } } } + } + }, + "/api/v1/namespaces": { + "get": { + "tags": [ + "namespaces" + ], + "summary": "List Namespaces", + "description": "The namespaces you have a role in, with their counts, and those you see only some collections of (`partial`,\nno `role`): counted over those collections, without the namespace-wide people and word cloud.", + "operationId": "list_namespaces", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/Namespace" + }, + "type": "array", + "title": "Response Namespaces-List Namespaces" + } + } + } + } + } }, "post": { "tags": [ "namespaces" ], - "summary": "Create Ip Group", - "description": "Add an IP group (owners): visitors from its addresses see all of every asset in the namespace\n(everything), or of the assets chosen on each. Answers with all of the namespace's groups.", - "operationId": "create_ip_group", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" - } - } - ], + "summary": "Create Namespace", + "operationId": "create_namespace", "requestBody": { - "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IpGroupCreate" + "$ref": "#/components/schemas/NamespaceCreate" } } - } + }, + "required": true }, "responses": { "200": { @@ -7086,7 +7103,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IpGroups" + "$ref": "#/components/schemas/Created" } } } @@ -7104,14 +7121,14 @@ } } }, - "/api/v1/namespaces/{name}/ip-groups/{gid}": { + "/api/v1/namespaces/{name}": { "patch": { "tags": [ "namespaces" ], - "summary": "Update Ip Group", - "description": "Rename an IP group, change its ranges or what it opens (owners). Choosing assets again after opening\neverything brings back the ones chosen before.", - "operationId": "update_ip_group", + "summary": "Update Namespace", + "description": "Owners: the graph mode (shared or isolated), the default pipeline (null for the built-in one) and a pipeline per\ncontent type.", + "operationId": "update_namespace", "parameters": [ { "name": "name", @@ -7121,15 +7138,6 @@ "type": "string", "title": "Name" } - }, - { - "name": "gid", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "title": "Gid" - } } ], "requestBody": { @@ -7137,7 +7145,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IpGroupUpdate" + "$ref": "#/components/schemas/NamespaceUpdate" } } } @@ -7148,7 +7156,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IpGroups" + "$ref": "#/components/schemas/Ok" } } } @@ -7164,14 +7172,16 @@ } } } - }, - "delete": { + } + }, + "/api/v1/namespaces/{name}/nsfw": { + "get": { "tags": [ "namespaces" ], - "summary": "Delete Ip Group", - "description": "Delete an IP group (owners): its visitors lose what it opened. Answers with the groups left.", - "operationId": "delete_ip_group", + "summary": "Get Namespace Nsfw", + "description": "NSFW classification here (docs/nsfw.md): whether it's on, the threshold and how flagged resources show, what the\nnamespace chose for itself and the archive's settings, and how many resources are classified and flagged.", + "operationId": "get_namespace_nsfw", "parameters": [ { "name": "name", @@ -7181,24 +7191,66 @@ "type": "string", "title": "Name" } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NamespaceNsfw" + } + } + } }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "put": { + "tags": [ + "namespaces" + ], + "summary": "Update Namespace Nsfw", + "description": "Owners: turn NSFW classification on or off for this namespace, or give it its own threshold or display; null\nfollows the archive's setting again. A new threshold re-flags what's classified at once. `classify` also queues the\nnsfw step for its videos, documents and images not classified yet. Audited as `namespace.nsfw`.", + "operationId": "update_namespace_nsfw", + "parameters": [ { - "name": "gid", + "name": "name", "in": "path", "required": true, "schema": { - "type": "integer", - "title": "Gid" + "type": "string", + "title": "Name" } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NamespaceNsfwUpdate" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IpGroups" + "$ref": "#/components/schemas/NamespaceNsfw" } } } @@ -7216,14 +7268,14 @@ } } }, - "/api/v1/namespaces/{name}/assistant": { - "get": { + "/api/v1/namespaces/{name}/nsfw/classify": { + "post": { "tags": [ "namespaces" ], - "summary": "Get Namespace Assistant", - "description": "The namespace's assistant: whether it's on, its name and instructions, and how much it remembers.", - "operationId": "get_namespace_assistant", + "summary": "Classify Namespace Nsfw", + "description": "Editors: queue the nsfw step for the namespace's videos, documents and images not classified yet (those added\nwhile it's on are classified by their pipeline). 409 where classification is off.", + "operationId": "classify_namespace_nsfw", "parameters": [ { "name": "name", @@ -7241,7 +7293,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceAssistant" + "$ref": "#/components/schemas/JobsQueued" } } } @@ -7257,14 +7309,16 @@ } } } - }, - "patch": { + } + }, + "/api/v1/namespaces/{name}/wordcloud.svg": { + "get": { "tags": [ "namespaces" ], - "summary": "Update Namespace Assistant", - "description": "Owners: turn the assistant on or off, name it, or change its instructions.", - "operationId": "update_namespace_assistant", + "summary": "Get Namespace Wordcloud", + "description": "The namespace's word cloud. Accepts a bearer token or the signed link from the namespace list.", + "operationId": "get_namespace_wordcloud", "parameters": [ { "name": "name", @@ -7276,25 +7330,11 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NamespaceAssistantUpdate" - } - } - } - }, "responses": { "200": { "description": "Successful Response", "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NamespaceAssistant" - } - } + "image/svg+xml": {} } }, "422": { @@ -7310,14 +7350,14 @@ } } }, - "/api/v1/namespaces/{name}/assistant/memories": { + "/api/v1/namespaces/{name}/stats": { "get": { "tags": [ "namespaces" ], - "summary": "List Assistant Memories", - "description": "What the namespace's assistant remembers: pinned first, then newest first (or by `q`).", - "operationId": "list_assistant_memories", + "summary": "Get Namespace Stats", + "description": "The namespace's numbers for the assets made in a range of days (the Reports overview): how many and how long,\nwho was heard and for how long, and the same per month. Without a range, every asset.", + "operationId": "get_namespace_stats", "parameters": [ { "name": "name", @@ -7329,22 +7369,56 @@ } }, { - "name": "q", + "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { - "type": "string" + "type": "string", + "format": "date" }, { "type": "null" } ], - "description": "only memories with these words, best first", - "title": "Q" + "description": "dated on or after this day", + "title": "From" }, - "description": "only memories with these words, best first" + "description": "dated on or after this day" + }, + { + "name": "to", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date" + }, + { + "type": "null" + } + ], + "description": "dated on or before this day", + "title": "To" + }, + "description": "dated on or before this day" + }, + { + "name": "top", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 50, + "minimum": 1, + "description": "how many people in `top_speakers`", + "default": 5, + "title": "Top" + }, + "description": "how many people in `top_speakers`" } ], "responses": { @@ -7353,11 +7427,7 @@ "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AssistantMemory" - }, - "title": "Response Namespaces-List Assistant Memories" + "$ref": "#/components/schemas/NamespaceStats" } } } @@ -7373,14 +7443,16 @@ } } } - }, - "post": { + } + }, + "/api/v1/namespaces/{name}/ip-groups": { + "get": { "tags": [ "namespaces" ], - "summary": "Add Assistant Memory", - "description": "Editors: tell the assistant something to remember.", - "operationId": "add_assistant_memory", + "summary": "List Ip Groups", + "description": "The namespace's IP groups (owners), and your address as the server sees it, to check the ranges against.", + "operationId": "list_ip_groups", "parameters": [ { "name": "name", @@ -7392,23 +7464,13 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AssistantMemoryCreate" - } - } - } - }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Created" + "$ref": "#/components/schemas/IpGroups" } } } @@ -7425,13 +7487,13 @@ } } }, - "delete": { + "post": { "tags": [ "namespaces" ], - "summary": "Forget All Assistant Memories", - "description": "Owners: forget everything the assistant remembers.", - "operationId": "forget_all_assistant_memories", + "summary": "Create Ip Group", + "description": "Add an IP group (owners): visitors from its addresses see all of every asset in the namespace\n(everything), or of the assets chosen on each. Answers with all of the namespace's groups.", + "operationId": "create_ip_group", "parameters": [ { "name": "name", @@ -7443,13 +7505,23 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IpGroupCreate" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Ok" + "$ref": "#/components/schemas/IpGroups" } } } @@ -7467,16 +7539,16 @@ } } }, - "/api/v1/namespaces/{name}/assistant/memories/{mid}": { + "/api/v1/namespaces/{name}/ip-groups/{gid}": { "patch": { "tags": [ "namespaces" ], - "summary": "Update Assistant Memory", - "description": "Editors: correct a memory, or pin it so it's read with every question.", - "operationId": "update_assistant_memory", - "parameters": [ - { + "summary": "Update Ip Group", + "description": "Rename an IP group, change its ranges or what it opens (owners). Choosing assets again after opening\neverything brings back the ones chosen before.", + "operationId": "update_ip_group", + "parameters": [ + { "name": "name", "in": "path", "required": true, @@ -7486,12 +7558,12 @@ } }, { - "name": "mid", + "name": "gid", "in": "path", "required": true, "schema": { "type": "integer", - "title": "Mid" + "title": "Gid" } } ], @@ -7500,7 +7572,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AssistantMemoryUpdate" + "$ref": "#/components/schemas/IpGroupUpdate" } } } @@ -7511,7 +7583,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AssistantMemory" + "$ref": "#/components/schemas/IpGroups" } } } @@ -7532,9 +7604,9 @@ "tags": [ "namespaces" ], - "summary": "Forget Assistant Memory", - "description": "Editors: forget one memory.", - "operationId": "forget_assistant_memory", + "summary": "Delete Ip Group", + "description": "Delete an IP group (owners): its visitors lose what it opened. Answers with the groups left.", + "operationId": "delete_ip_group", "parameters": [ { "name": "name", @@ -7546,12 +7618,12 @@ } }, { - "name": "mid", + "name": "gid", "in": "path", "required": true, "schema": { "type": "integer", - "title": "Mid" + "title": "Gid" } } ], @@ -7561,7 +7633,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Ok" + "$ref": "#/components/schemas/IpGroups" } } } @@ -7579,14 +7651,14 @@ } } }, - "/api/v1/namespaces/{name}/integrations": { + "/api/v1/namespaces/{name}/assistant": { "get": { "tags": [ "namespaces" ], - "summary": "Get Namespace Integrations", - "description": "Whether the namespace's own MCP server and chat completions are on, their addresses, and the tools offered.", - "operationId": "get_namespace_integrations", + "summary": "Get Namespace Assistant", + "description": "The namespace's assistant: whether it's on, its name and instructions, and how much it remembers.", + "operationId": "get_namespace_assistant", "parameters": [ { "name": "name", @@ -7604,7 +7676,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceIntegrations" + "$ref": "#/components/schemas/NamespaceAssistant" } } } @@ -7625,9 +7697,9 @@ "tags": [ "namespaces" ], - "summary": "Update Namespace Integrations", - "description": "Owners: turn the namespace's own MCP server or chat completions on or off, or pick the read tools the model may\nuse in its chat completions. Off, each answers 403; apps keep their access to the rest of Lens as before.", - "operationId": "update_namespace_integrations", + "summary": "Update Namespace Assistant", + "description": "Owners: turn the assistant on or off, name it, or change its instructions.", + "operationId": "update_namespace_assistant", "parameters": [ { "name": "name", @@ -7644,7 +7716,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceIntegrationsUpdate" + "$ref": "#/components/schemas/NamespaceAssistantUpdate" } } } @@ -7655,7 +7727,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NamespaceIntegrations" + "$ref": "#/components/schemas/NamespaceAssistant" } } } @@ -7673,14 +7745,14 @@ } } }, - "/api/v1/namespaces/{name}/models": { + "/api/v1/namespaces/{name}/assistant/memories": { "get": { "tags": [ - "chat completions" + "namespaces" ], - "summary": "List Completion Models", - "description": "OpenAI's model list for the namespace's chat completions: lens (the configured model) and the models people may\npick in Lens's chat.", - "operationId": "list_completion_models", + "summary": "List Assistant Memories", + "description": "What the namespace's assistant remembers: pinned first, then newest first (or by `q`).", + "operationId": "list_assistant_memories", "parameters": [ { "name": "name", @@ -7690,6 +7762,24 @@ "type": "string", "title": "Name" } + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "only memories with these words, best first", + "title": "Q" + }, + "description": "only memories with these words, best first" } ], "responses": { @@ -7698,29 +7788,15 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CompletionModels" + "type": "array", + "items": { + "$ref": "#/components/schemas/AssistantMemory" + }, + "title": "Response Namespaces-List Assistant Memories" } } } }, - "400": { - "description": "OpenAI's error shape: {error: {message, type, code}}" - }, - "401": { - "description": "no token, or one that doesn't open this namespace" - }, - "403": { - "description": "the namespace's chat completions are off" - }, - "404": { - "description": "no such namespace, or not one you can read" - }, - "429": { - "description": "a budget is used up" - }, - "502": { - "description": "the model server failed" - }, "422": { "description": "Validation Error", "content": { @@ -7732,16 +7808,14 @@ } } } - } - }, - "/api/v1/namespaces/{name}/chat/completions": { + }, "post": { "tags": [ - "chat completions" + "namespaces" ], - "summary": "Create Chat Completion", - "description": "OpenAI's chat completions, answered from this namespace alone: the last user message is the question, the\nmessages before it the conversation and system messages the app's instructions. The answer cites what it read as\n[n], with a Sources list after it, `citations` (the n-th link for [n]) and `lens.sources`. With `stream`, it comes\nas OpenAI's chunks (server-sent events) ending in `data: [DONE]`. Off until an owner of the namespace turns it on;\nread-only tokens are enough. 429 when the namespace's budget or Lens's overall one is used up.", - "operationId": "create_chat_completion", + "summary": "Add Assistant Memory", + "description": "Editors: tell the assistant something to remember.", + "operationId": "add_assistant_memory", "parameters": [ { "name": "name", @@ -7758,7 +7832,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatCompletionRequest" + "$ref": "#/components/schemas/AssistantMemoryCreate" } } } @@ -7769,29 +7843,11 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatCompletion" + "$ref": "#/components/schemas/Created" } } } }, - "400": { - "description": "OpenAI's error shape: {error: {message, type, code}}" - }, - "401": { - "description": "no token, or one that doesn't open this namespace" - }, - "403": { - "description": "the namespace's chat completions are off" - }, - "404": { - "description": "no such namespace, or not one you can read" - }, - "429": { - "description": "a budget is used up" - }, - "502": { - "description": "the model server failed" - }, "422": { "description": "Validation Error", "content": { @@ -7803,16 +7859,14 @@ } } } - } - }, - "/api/v1/namespaces/{name}/collections": { - "get": { + }, + "delete": { "tags": [ "namespaces" ], - "summary": "List Namespace Collections", - "description": "The namespace's collections, depth first and by name, each with its place in the tree, how many assets it\nholds (with and without the collections inside it), and what you may do with it. Someone who sees only some\ncollections of the namespace gets those, starting from the ones they were given.", - "operationId": "list_namespace_collections", + "summary": "Forget All Assistant Memories", + "description": "Owners: forget everything the assistant remembers.", + "operationId": "forget_all_assistant_memories", "parameters": [ { "name": "name", @@ -7830,11 +7884,7 @@ "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CollectionNode" - }, - "title": "Response Namespaces-List Namespace Collections" + "$ref": "#/components/schemas/Ok" } } } @@ -7850,14 +7900,16 @@ } } } - }, - "post": { + } + }, + "/api/v1/namespaces/{name}/assistant/memories/{mid}": { + "patch": { "tags": [ "namespaces" ], - "summary": "Create Namespace Collection", - "description": "Make a collection at the top of the namespace (its editors) or inside `parent` (them, or an admin of `parent`).\nIts name is unique among the collections next to it, ignoring case; collections go at most 8 deep. Audited as\n`collection.create`.", - "operationId": "create_namespace_collection", + "summary": "Update Assistant Memory", + "description": "Editors: correct a memory, or pin it so it's read with every question.", + "operationId": "update_assistant_memory", "parameters": [ { "name": "name", @@ -7867,6 +7919,15 @@ "type": "string", "title": "Name" } + }, + { + "name": "mid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Mid" + } } ], "requestBody": { @@ -7874,7 +7935,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CollectionNodeCreate" + "$ref": "#/components/schemas/AssistantMemoryUpdate" } } } @@ -7885,7 +7946,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CollectionNode" + "$ref": "#/components/schemas/AssistantMemory" } } } @@ -7901,15 +7962,14 @@ } } } - } - }, - "/api/v1/namespaces/{name}/collections/{cid}": { - "get": { + }, + "delete": { "tags": [ "namespaces" ], - "summary": "Get Namespace Collection", - "operationId": "get_namespace_collection", + "summary": "Forget Assistant Memory", + "description": "Editors: forget one memory.", + "operationId": "forget_assistant_memory", "parameters": [ { "name": "name", @@ -7921,12 +7981,12 @@ } }, { - "name": "cid", + "name": "mid", "in": "path", "required": true, "schema": { "type": "integer", - "title": "Cid" + "title": "Mid" } } ], @@ -7936,7 +7996,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CollectionNode" + "$ref": "#/components/schemas/Ok" } } } @@ -7952,14 +8012,16 @@ } } } - }, - "patch": { + } + }, + "/api/v1/namespaces/{name}/integrations": { + "get": { "tags": [ "namespaces" ], - "summary": "Update Namespace Collection", - "description": "Rename it, describe it, move it inside another collection of the namespace (`parent`; null: to the top) or make\nit the default. Editors of the namespace may do all of that; an admin of the collection all but moving it to the\ntop or making it the default, and only into a collection they're an admin of. The assets and collections\ninside it go with it. Audited as `collection.update`.", - "operationId": "update_namespace_collection", + "summary": "Get Namespace Integrations", + "description": "Whether the namespace's own MCP server and chat completions are on, their addresses, and the tools offered.", + "operationId": "get_namespace_integrations", "parameters": [ { "name": "name", @@ -7969,34 +8031,15 @@ "type": "string", "title": "Name" } - }, - { - "name": "cid", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "title": "Cid" - } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CollectionNodeUpdate" - } - } - } - }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CollectionNode" + "$ref": "#/components/schemas/NamespaceIntegrations" } } } @@ -8013,13 +8056,13 @@ } } }, - "delete": { + "patch": { "tags": [ "namespaces" ], - "summary": "Delete Namespace Collection", - "description": "Delete an empty collection (editors of the namespace, or an admin of it), with the roles given on it: 409 while\nit holds assets or collections, or is the namespace's default. Audited as `collection.delete`.", - "operationId": "delete_namespace_collection", + "summary": "Update Namespace Integrations", + "description": "Owners: turn the namespace's own MCP server or chat completions on or off, or pick the read tools the model may\nuse in its chat completions. Off, each answers 403; apps keep their access to the rest of Lens as before.", + "operationId": "update_namespace_integrations", "parameters": [ { "name": "name", @@ -8029,24 +8072,25 @@ "type": "string", "title": "Name" } - }, - { - "name": "cid", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "title": "Cid" - } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NamespaceIntegrationsUpdate" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Ok" + "$ref": "#/components/schemas/NamespaceIntegrations" } } } @@ -8064,14 +8108,14 @@ } } }, - "/api/v1/namespaces/{name}/collections/{cid}/members": { + "/api/v1/namespaces/{name}/models": { "get": { "tags": [ - "namespaces" + "chat completions" ], - "summary": "List Collection Members", - "description": "Who was given a role on the collection, then who has one through a collection it's inside (owners of the\nnamespace, and admins of the collection). People with a role in the namespace aren't listed: theirs holds in\nevery collection.", - "operationId": "list_collection_members", + "summary": "List Completion Models", + "description": "OpenAI's model list for the namespace's chat completions: lens (the configured model) and the models people may\npick in Lens's chat.", + "operationId": "list_completion_models", "parameters": [ { "name": "name", @@ -8081,32 +8125,108 @@ "type": "string", "title": "Name" } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompletionModels" + } + } + } + }, + "400": { + "description": "OpenAI's error shape: {error: {message, type, code}}" + }, + "401": { + "description": "no token, or one that doesn't open this namespace" + }, + "403": { + "description": "the namespace's chat completions are off" + }, + "404": { + "description": "no such namespace, or not one you can read" + }, + "429": { + "description": "a budget is used up" + }, + "502": { + "description": "the model server failed" }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/namespaces/{name}/chat/completions": { + "post": { + "tags": [ + "chat completions" + ], + "summary": "Create Chat Completion", + "description": "OpenAI's chat completions, answered from this namespace alone: the last user message is the question, the\nmessages before it the conversation and system messages the app's instructions. The answer cites what it read as\n[n], with a Sources list after it, `citations` (the n-th link for [n]) and `lens.sources`. With `stream`, it comes\nas OpenAI's chunks (server-sent events) ending in `data: [DONE]`. Off until an owner of the namespace turns it on;\nread-only tokens are enough. 429 when the namespace's budget or Lens's overall one is used up.", + "operationId": "create_chat_completion", + "parameters": [ { - "name": "cid", + "name": "name", "in": "path", "required": true, "schema": { - "type": "integer", - "title": "Cid" + "type": "string", + "title": "Name" } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatCompletionRequest" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CollectionMember" - }, - "title": "Response Namespaces-List Collection Members" + "$ref": "#/components/schemas/ChatCompletion" } } } }, + "400": { + "description": "OpenAI's error shape: {error: {message, type, code}}" + }, + "401": { + "description": "no token, or one that doesn't open this namespace" + }, + "403": { + "description": "the namespace's chat completions are off" + }, + "404": { + "description": "no such namespace, or not one you can read" + }, + "429": { + "description": "a budget is used up" + }, + "502": { + "description": "the model server failed" + }, "422": { "description": "Validation Error", "content": { @@ -8118,14 +8238,16 @@ } } } - }, - "put": { + } + }, + "/api/v1/namespaces/{name}/collections": { + "get": { "tags": [ "namespaces" ], - "summary": "Set Collection Member", - "description": "Give someone a role on the collection (and the collections inside it), change it, or (role null) take it away.\nThey needn't have a role in the namespace: then they see just this collection. Owners of the namespace and admins\nof the collection. Answers with the members; audited as `collection.member`.", - "operationId": "set_collection_member", + "summary": "List Namespace Collections", + "description": "The namespace's collections, depth first and by name, each with its place in the tree, how many assets it\nholds (with and without the collections inside it), and what you may do with it. Someone who sees only some\ncollections of the namespace gets those, starting from the ones they were given.", + "operationId": "list_namespace_collections", "parameters": [ { "name": "name", @@ -8135,14 +8257,50 @@ "type": "string", "title": "Name" } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionNode" + }, + "title": "Response Namespaces-List Namespace Collections" + } + } + } }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "namespaces" + ], + "summary": "Create Namespace Collection", + "description": "Make a collection at the top of the namespace (its editors) or inside `parent` (them, or an admin of `parent`).\nIts name is unique among the collections next to it, ignoring case; collections go at most 8 deep. Audited as\n`collection.create`.", + "operationId": "create_namespace_collection", + "parameters": [ { - "name": "cid", + "name": "name", "in": "path", "required": true, "schema": { - "type": "integer", - "title": "Cid" + "type": "string", + "title": "Name" } } ], @@ -8151,7 +8309,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CollectionMemberSet" + "$ref": "#/components/schemas/CollectionNodeCreate" } } } @@ -8162,11 +8320,7 @@ "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CollectionMember" - }, - "title": "Response Namespaces-Set Collection Member" + "$ref": "#/components/schemas/CollectionNode" } } } @@ -8184,191 +8338,472 @@ } } }, - "/api/v1/resources": { + "/api/v1/namespaces/{name}/collections/{cid}": { "get": { "tags": [ - "resources" + "namespaces" ], - "summary": "List Recordings", - "description": "Assets you can read, newest first by default: those of the namespaces you have a role in, and of the\ncollections you were given a role on. Filters combine with AND; the ``X-Total-Count`` header says how many match in\nall, so pages can be counted. Each row has your `role` on it.", - "operationId": "list_recordings", + "summary": "Get Namespace Collection", + "operationId": "get_namespace_collection", "parameters": [ { - "name": "ns", - "in": "query", - "required": false, + "name": "name", + "in": "path", + "required": true, "schema": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "one namespace (default: every namespace you can read)", - "title": "Ns" - }, - "description": "one namespace (default: every namespace you can read)" + "type": "string", + "title": "Name" + } }, { - "name": "q", - "in": "query", - "required": false, + "name": "cid", + "in": "path", + "required": true, "schema": { - "anyOf": [ - { - "type": "string", - "maxLength": 200 - }, - { - "type": "null" + "type": "integer", + "title": "Cid" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollectionNode" } - ], - "description": "words that must all appear in the title, the namespace or a person's name", - "title": "Q" - }, - "description": "words that must all appear in the title, the namespace or a person's name" + } + } }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "patch": { + "tags": [ + "namespaces" + ], + "summary": "Update Namespace Collection", + "description": "Rename it, describe it, move it inside another collection of the namespace (`parent`; null: to the top) or make\nit the default. Editors of the namespace may do all of that; an admin of the collection all but moving it to the\ntop or making it the default, and only into a collection they're an admin of. The assets and collections\ninside it go with it. Audited as `collection.update`.", + "operationId": "update_namespace_collection", + "parameters": [ { - "name": "status", - "in": "query", - "required": false, + "name": "name", + "in": "path", + "required": true, "schema": { - "anyOf": [ - { - "type": "array", - "items": { - "enum": [ - "new", - "transcribed", - "diarized", - "analyzed", - "error", - "processing", - "failed" - ], - "type": "string" - } - }, - { - "type": "null" - } - ], - "description": "asset statuses, or processing (a job is queued or running) and failed (the latest job failed); repeat for several (any of them matches)", - "title": "Status" - }, - "description": "asset statuses, or processing (a job is queued or running) and failed (the latest job failed); repeat for several (any of them matches)" + "type": "string", + "title": "Name" + } }, { - "name": "attention", - "in": "query", - "required": false, + "name": "cid", + "in": "path", + "required": true, "schema": { - "type": "boolean", - "description": "only assets that need attention: errored, latest job failed, or a person match to review", - "default": false, - "title": "Attention" - }, - "description": "only assets that need attention: errored, latest job failed, or a person match to review" + "type": "integer", + "title": "Cid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollectionNodeUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollectionNode" + } + } + } }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "namespaces" + ], + "summary": "Delete Namespace Collection", + "description": "Delete an empty collection (editors of the namespace, or an admin of it), with the roles given on it: 409 while\nit holds assets or collections, or is the namespace's default. Audited as `collection.delete`.", + "operationId": "delete_namespace_collection", + "parameters": [ { - "name": "processing", - "in": "query", - "required": false, + "name": "name", + "in": "path", + "required": true, "schema": { - "type": "boolean", - "description": "only assets with a job queued or running", - "default": false, - "title": "Processing" - }, - "description": "only assets with a job queued or running" + "type": "string", + "title": "Name" + } }, { - "name": "speaker", - "in": "query", - "required": false, + "name": "cid", + "in": "path", + "required": true, "schema": { - "anyOf": [ - { - "type": "array", - "items": { - "type": "integer" - } - }, - { - "type": "null" + "type": "integer", + "title": "Cid" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" } - ], - "description": "person ids; repeat for several (any of them matches)", - "title": "Speaker" - }, - "description": "person ids; repeat for several (any of them matches)" + } + } }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/namespaces/{name}/collections/{cid}/members": { + "get": { + "tags": [ + "namespaces" + ], + "summary": "List Collection Members", + "description": "Who was given a role on the collection, then who has one through a collection it's inside (owners of the\nnamespace, and admins of the collection). People with a role in the namespace aren't listed: theirs holds in\nevery collection.", + "operationId": "list_collection_members", + "parameters": [ { - "name": "from", - "in": "query", - "required": false, + "name": "name", + "in": "path", + "required": true, "schema": { - "anyOf": [ - { - "type": "string", - "format": "date" - }, - { - "type": "null" - } - ], - "description": "recorded on or after this day", - "title": "From" - }, - "description": "recorded on or after this day" + "type": "string", + "title": "Name" + } }, { - "name": "to", - "in": "query", - "required": false, + "name": "cid", + "in": "path", + "required": true, "schema": { - "anyOf": [ - { - "type": "string", - "format": "date" - }, - { - "type": "null" + "type": "integer", + "title": "Cid" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionMember" + }, + "title": "Response Namespaces-List Collection Members" } - ], - "description": "recorded on or before this day", - "title": "To" - }, - "description": "recorded on or before this day" + } + } }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "put": { + "tags": [ + "namespaces" + ], + "summary": "Set Collection Member", + "description": "Give someone a role on the collection (and the collections inside it), change it, or (role null) take it away.\nThey needn't have a role in the namespace: then they see just this collection. Owners of the namespace and admins\nof the collection. Answers with the members; audited as `collection.member`.", + "operationId": "set_collection_member", + "parameters": [ { - "name": "min_duration", - "in": "query", - "required": false, + "name": "name", + "in": "path", + "required": true, "schema": { - "anyOf": [ - { - "type": "integer", - "minimum": 0 - }, - { - "type": "null" - } - ], - "description": "at least this many seconds long", - "title": "Min Duration" - }, - "description": "at least this many seconds long" + "type": "string", + "title": "Name" + } }, { - "name": "max_duration", - "in": "query", - "required": false, + "name": "cid", + "in": "path", + "required": true, "schema": { - "anyOf": [ - { + "type": "integer", + "title": "Cid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollectionMemberSet" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionMember" + }, + "title": "Response Namespaces-Set Collection Member" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/resources": { + "get": { + "tags": [ + "resources" + ], + "summary": "List Recordings", + "description": "Assets you can read, newest first by default: those of the namespaces you have a role in, and of the\ncollections you were given a role on. Filters combine with AND; the ``X-Total-Count`` header says how many match in\nall, so pages can be counted. Each row has your `role` on it.", + "operationId": "list_recordings", + "parameters": [ + { + "name": "ns", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "one namespace (default: every namespace you can read)", + "title": "Ns" + }, + "description": "one namespace (default: every namespace you can read)" + }, + { + "name": "q", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "maxLength": 200 + }, + { + "type": "null" + } + ], + "description": "words that must all appear in the title, the namespace or a person's name", + "title": "Q" + }, + "description": "words that must all appear in the title, the namespace or a person's name" + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "array", + "items": { + "enum": [ + "new", + "transcribed", + "diarized", + "analyzed", + "error", + "processing", + "failed" + ], + "type": "string" + } + }, + { + "type": "null" + } + ], + "description": "asset statuses, or processing (a job is queued or running) and failed (the latest job failed); repeat for several (any of them matches)", + "title": "Status" + }, + "description": "asset statuses, or processing (a job is queued or running) and failed (the latest job failed); repeat for several (any of them matches)" + }, + { + "name": "attention", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "description": "only assets that need attention: errored, latest job failed, or a person match to review", + "default": false, + "title": "Attention" + }, + "description": "only assets that need attention: errored, latest job failed, or a person match to review" + }, + { + "name": "processing", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "description": "only assets with a job queued or running", + "default": false, + "title": "Processing" + }, + "description": "only assets with a job queued or running" + }, + { + "name": "speaker", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "array", + "items": { + "type": "integer" + } + }, + { + "type": "null" + } + ], + "description": "person ids; repeat for several (any of them matches)", + "title": "Speaker" + }, + "description": "person ids; repeat for several (any of them matches)" + }, + { + "name": "from", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date" + }, + { + "type": "null" + } + ], + "description": "recorded on or after this day", + "title": "From" + }, + "description": "recorded on or after this day" + }, + { + "name": "to", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date" + }, + { + "type": "null" + } + ], + "description": "recorded on or before this day", + "title": "To" + }, + "description": "recorded on or before this day" + }, + { + "name": "min_duration", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "integer", + "minimum": 0 + }, + { + "type": "null" + } + ], + "description": "at least this many seconds long", + "title": "Min Duration" + }, + "description": "at least this many seconds long" + }, + { + "name": "max_duration", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { "type": "integer", "minimum": 1 }, @@ -29671,101 +30106,1158 @@ } } }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } - } + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "AccessRequest": { + "properties": { + "recording": { + "type": "integer", + "title": "Recording" + }, + "title": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Title" + }, + "namespace": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Namespace" + }, + "account": { + "type": "integer", + "title": "Account" + }, + "email": { + "type": "string", + "title": "Email" + }, + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Name" + }, + "message": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Message" + }, + "at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "At" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "approved", + "declined" + ], + "title": "Status" + }, + "decided_by": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Decided By" + }, + "decided_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Decided At" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "recording", + "account", + "email", + "status" + ], + "title": "AccessRequest", + "description": "Someone asking for permission on an asset (docs/access.md)." + }, + "AccountToken": { + "properties": { + "id": { + "type": "integer", + "title": "Id" + }, + "name": { + "type": "string", + "title": "Name" + }, + "scope": { + "type": "string", + "enum": [ + "read", + "write" + ], + "title": "Scope" + }, + "prefix": { + "type": "string", + "title": "Prefix" + }, + "created_at": { + "type": "string", + "title": "Created At" + }, + "expires_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Expires At" + }, + "last_used_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Used At" + }, + "namespace": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Namespace", + "description": "the one namespace it opens (its own servers alone), when it was made for one" + }, + "account": { + "type": "integer", + "title": "Account" + }, + "email": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Email" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "name", + "scope", + "prefix", + "created_at", + "account" + ], + "title": "AccountToken", + "description": "Anyone's key, for admins." + }, + "ActionInfo": { + "properties": { + "name": { + "type": "string", + "title": "Name" + }, + "label": { + "type": "string", + "title": "Label" + }, + "group": { + "type": "string", + "title": "Group" + }, + "description": { + "type": "string", + "title": "Description", + "default": "" + }, + "params": { + "additionalProperties": true, + "type": "object", + "title": "Params", + "description": "a JSON Schema (type object) of its params; a string holding {{ }} stands for any type" + }, + "required": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Required" + }, + "effect": { + "type": "string", + "enum": [ + "read", + "self", + "lens", + "out", + "depends" + ], + "title": "Effect", + "description": "what it reaches: read and self run at once; lens asks unless it changes the event's own object; out asks first unless you let it run on its own; depends: worked out from its params" + }, + "output": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Output", + "description": "a JSON Schema of what it gives back, for later nodes (steps.)" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "name", + "label", + "group", + "params", + "effect" + ], + "title": "ActionInfo" + }, + "ActivityActor": { + "properties": { + "type": { + "type": "string", + "enum": [ + "Service", + "Person", + "Application" + ], + "title": "Type" + }, + "id": { + "type": "string", + "title": "Id", + "description": "a Lens reference, like lens:account/1 or lens:automation/4" + }, + "name": { + "type": "string", + "title": "Name" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "type", + "id", + "name" + ], + "title": "ActivityActor" + }, + "ActivityCosts": { + "properties": { + "period": { + "type": "string", + "title": "Period" + }, + "since": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Since" + }, + "costs": { + "additionalProperties": { + "$ref": "#/components/schemas/ResourceSpend" + }, + "type": "object", + "title": "Costs", + "description": "by resource; ones you can't see are left out" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "period", + "costs" + ], + "title": "ActivityCosts" + }, + "ActivityEntry": { + "properties": { + "id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Id", + "description": "the ledger row's id; none for an audit log entry" + }, + "at": { + "type": "string", + "title": "At" + }, + "kind": { + "type": "string", + "enum": [ + "in", + "out", + "run", + "change" + ], + "title": "Kind", + "description": "in: an API request; out: a call Lens made (a model, embeddings, the decision model, a webhook, a web tool); run: a job or routine run ended; change: an audit log entry, or a change to the entity graph (action `graph.`)" + }, + "action": { + "type": "string", + "title": "Action", + "description": "what it was: `POST /api/v1/routines/{rid}/run`, `model.chat`, `job.succeeded`, `routine.update`" + }, + "resources": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Resources", + "description": "every resource it counts for, as table:id" + }, + "actor": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Actor", + "description": "the account that made it, when a person did" + }, + "email": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Email" + }, + "model": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Model" + }, + "tokens_in": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tokens In" + }, + "tokens_out": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Tokens Out" + }, + "cost_usd": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Cost Usd", + "description": "estimated from the prices in Settings; none when the model has no price" + }, + "ms": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Ms" + }, + "ok": { + "type": "boolean", + "title": "Ok", + "default": true + }, + "error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Error", + "description": "the error's type or HTTP status; never its message" + }, + "detail": { + "title": "Detail" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "at", + "kind", + "action" + ], + "title": "ActivityEntry" + }, + "ActivityKind": { + "properties": { + "name": { + "type": "string", + "title": "Name" + }, + "label": { + "type": "string", + "title": "Label" + }, + "source": { + "type": "string", + "title": "Source" + }, + "type": { + "type": "string", + "title": "Type", + "description": "the Activity Streams verb its activities have" + }, + "object_type": { + "type": "string", + "title": "Object Type" + }, + "parent": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Parent" + }, + "children": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Children" + }, + "fields": { + "additionalProperties": true, + "type": "object", + "title": "Fields", + "description": "JSON Schemas of its own object, actor or target fields" + }, + "schema": { + "additionalProperties": true, + "type": "object", + "title": "Schema", + "description": "a JSON Schema of its activities, with every field" + }, + "untrusted": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Untrusted" + }, + "noisy": { + "type": "boolean", + "title": "Noisy", + "description": "left out of the timeline unless named", + "default": false + }, + "sample": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Sample" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "name", + "label", + "source", + "type", + "object_type", + "schema" + ], + "title": "ActivityKind" + }, + "ActivityLens": { + "properties": { + "source": { + "type": "string", + "title": "Source", + "description": "the source that made it, like recordings or log" + }, + "pos": { + "items": {}, + "type": "array", + "title": "Pos", + "description": "the source's position, [time, id]; for the stream machinery" + }, + "untrusted": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Untrusted", + "description": "dotted paths holding text from outside Lens" + }, + "cause": { + "anyOf": [ + { + "additionalProperties": { + "type": "integer" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Cause", + "description": "{automation, run, depth} when an automation caused it" + }, + "spaces": { + "anyOf": [ + { + "items": { + "type": "integer" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Spaces", + "description": "every namespace it belongs to, when there are several" + }, + "audience": { + "anyOf": [ + { + "type": "string", + "enum": [ + "space", + "owner", + "admins" + ] + }, + { + "type": "null" + } + ], + "title": "Audience", + "description": "who may see it (default: space)" + }, + "owner": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Owner", + "description": "the account that alone sees it, with audience owner" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "source", + "pos" + ], + "title": "ActivityLens" + }, + "ActivityMark": { + "properties": { + "reviewed": { + "type": "boolean", + "title": "Reviewed", + "default": false + }, + "important": { + "type": "boolean", + "title": "Important", + "default": false + }, + "hidden": { + "type": "boolean", + "title": "Hidden", + "default": false + }, + "at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "At", + "description": "when you last marked it" + } + }, + "additionalProperties": true, + "type": "object", + "title": "ActivityMark", + "description": "Your own review marks on an activity; nobody else sees them." + }, + "ActivityObject": { + "properties": { + "type": { + "type": "string", + "title": "Type" + }, + "id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Id", + "description": "a Lens reference, like lens:recording/7" + }, + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Name" + }, + "url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Url", + "description": "its page in the web app, relative to it" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "type" + ], + "title": "ActivityObject", + "description": "What the activity is about; each kind adds its own fields (GET /activities/kinds has its schema)." + }, + "ActivityPage": { + "properties": { + "items": { + "items": { + "$ref": "#/components/schemas/StreamActivity" + }, + "type": "array", + "title": "Items", + "description": "newest first" + }, + "next": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next", + "description": "give it as before for the page after; null at the end" + }, + "namespaces": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Namespaces", + "description": "the names of the namespaces in items, by id" + }, + "marks": { + "additionalProperties": { + "$ref": "#/components/schemas/ActivityMark" + }, + "type": "object", + "title": "Marks", + "description": "your marks on items, by id (those you marked)" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "items" + ], + "title": "ActivityPage" + }, + "ActivityTop": { + "properties": { + "period": { + "type": "string", + "title": "Period" + }, + "since": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Since" + }, + "resources": { + "items": { + "$ref": "#/components/schemas/ResourceCost" + }, + "type": "array", + "title": "Resources" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "period", + "resources" + ], + "title": "ActivityTop" + }, + "ActivityTotals": { + "properties": { + "resource": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Resource" + }, + "period": { + "type": "string", + "title": "Period" + }, + "since": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Since" + }, + "calls": { + "type": "integer", + "title": "Calls" + }, + "failed": { + "type": "integer", + "title": "Failed" + }, + "tokens_in": { + "type": "integer", + "title": "Tokens In" + }, + "tokens_out": { + "type": "integer", + "title": "Tokens Out" + }, + "cost_usd": { + "type": "number", + "title": "Cost Usd", + "description": "what its calls cost (run rows repeat their calls' cost and aren't added again)" + }, + "ms": { + "type": "integer", + "title": "Ms" + }, + "unpriced": { + "type": "integer", + "title": "Unpriced", + "description": "calls that cost something but have no figure (a model with no price, a reply without token counts)", + "default": 0 + }, + "estimate": { + "type": "boolean", + "title": "Estimate", + "description": "true when unpriced calls make cost_usd a floor rather than exact", + "default": false + }, + "by_kind": { + "additionalProperties": { + "$ref": "#/components/schemas/KindTotals" + }, + "type": "object", + "title": "By Kind" } - } - } - } - }, - "components": { - "schemas": { - "AccessRequest": { + }, + "additionalProperties": true, + "type": "object", + "required": [ + "period", + "calls", + "failed", + "tokens_in", + "tokens_out", + "cost_usd", + "ms", + "by_kind" + ], + "title": "ActivityTotals" + }, + "AnalyticsChurn": { "properties": { - "recording": { + "previous_active": { "type": "integer", - "title": "Recording" + "title": "Previous Active" }, - "title": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Title" + "retained": { + "type": "integer", + "title": "Retained" }, - "namespace": { + "churned": { + "type": "integer", + "title": "Churned" + }, + "rate": { "anyOf": [ { - "type": "string" + "type": "number" }, { "type": "null" } ], - "title": "Namespace" + "title": "Rate" }, - "account": { + "returning": { "type": "integer", - "title": "Account" + "title": "Returning" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "previous_active", + "retained", + "churned", + "returning" + ], + "title": "AnalyticsChurn" + }, + "AnalyticsCohort": { + "properties": { + "week": { + "type": "string", + "title": "Week" }, - "email": { + "users": { + "type": "integer", + "title": "Users" + }, + "retention": { + "items": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ] + }, + "type": "array", + "title": "Retention" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "week", + "users", + "retention" + ], + "title": "AnalyticsCohort" + }, + "AnalyticsDay": { + "properties": { + "day": { "type": "string", - "title": "Email" + "title": "Day" + }, + "active_users": { + "type": "integer", + "title": "Active Users" }, + "actions": { + "type": "integer", + "title": "Actions" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "day", + "active_users", + "actions" + ], + "title": "AnalyticsDay" + }, + "AnalyticsEvent": { + "properties": { "name": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], + "type": "string", "title": "Name" }, - "message": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Message" + "description": { + "type": "string", + "title": "Description" }, - "at": { + "on": { + "type": "boolean", + "title": "On" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "name", + "description", + "on" + ], + "title": "AnalyticsEvent" + }, + "AnalyticsFeature": { + "properties": { + "feature": { + "type": "string", + "title": "Feature" + }, + "actions": { + "type": "integer", + "title": "Actions" + }, + "users": { + "type": "integer", + "title": "Users" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "feature", + "actions", + "users" + ], + "title": "AnalyticsFeature" + }, + "AnalyticsMetrics": { + "properties": { + "days": { + "type": "integer", + "title": "Days" + }, + "since": { + "type": "string", + "title": "Since" + }, + "until": { + "type": "string", + "title": "Until" + }, + "daily": { + "items": { + "$ref": "#/components/schemas/AnalyticsDay" + }, + "type": "array", + "title": "Daily" + }, + "dau": { + "type": "integer", + "title": "Dau" + }, + "wau": { + "type": "integer", + "title": "Wau" + }, + "mau": { + "type": "integer", + "title": "Mau" + }, + "stickiness": { "anyOf": [ { - "type": "string" + "type": "number" }, { "type": "null" } ], - "title": "At" + "title": "Stickiness" + }, + "accounts": { + "type": "integer", + "title": "Accounts" + }, + "active_users": { + "type": "integer", + "title": "Active Users" + }, + "new_users": { + "type": "integer", + "title": "New Users" + }, + "churn": { + "$ref": "#/components/schemas/AnalyticsChurn" }, - "status": { - "type": "string", - "enum": [ - "pending", - "approved", - "declined" - ], - "title": "Status" + "retention": { + "items": { + "$ref": "#/components/schemas/AnalyticsCohort" + }, + "type": "array", + "title": "Retention" }, - "decided_by": { + "features": { + "items": { + "$ref": "#/components/schemas/AnalyticsFeature" + }, + "type": "array", + "title": "Features" + }, + "last_active_day": { "anyOf": [ { "type": "string" @@ -29774,58 +31266,51 @@ "type": "null" } ], - "title": "Decided By" + "title": "Last Active Day" }, - "decided_at": { + "days_since_active": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Decided At" + "title": "Days Since Active" } }, "additionalProperties": true, "type": "object", "required": [ - "recording", - "account", - "email", - "status" + "days", + "since", + "until", + "daily", + "dau", + "wau", + "mau", + "accounts", + "active_users", + "new_users", + "churn", + "retention", + "features" ], - "title": "AccessRequest", - "description": "Someone asking for permission on an asset (docs/access.md)." + "title": "AnalyticsMetrics", + "description": "Active people, churn, retention and feature use, worked out on this machine from the activity ledger and\nsign-ins (docs/analytics.md#the-numbers)." }, - "AccountToken": { + "AnalyticsStatus": { "properties": { - "id": { - "type": "integer", - "title": "Id" - }, - "name": { - "type": "string", - "title": "Name" - }, - "scope": { - "type": "string", - "enum": [ - "read", - "write" - ], - "title": "Scope" - }, - "prefix": { - "type": "string", - "title": "Prefix" + "enabled": { + "type": "boolean", + "title": "Enabled" }, - "created_at": { - "type": "string", - "title": "Created At" + "configured": { + "type": "boolean", + "title": "Configured" }, - "expires_at": { + "measurement_id": { "anyOf": [ { "type": "string" @@ -29834,9 +31319,9 @@ "type": "null" } ], - "title": "Expires At" + "title": "Measurement Id" }, - "last_used_at": { + "client_id": { "anyOf": [ { "type": "string" @@ -29845,9 +31330,9 @@ "type": "null" } ], - "title": "Last Used At" + "title": "Client Id" }, - "namespace": { + "last_sent_at": { "anyOf": [ { "type": "string" @@ -29856,14 +31341,17 @@ "type": "null" } ], - "title": "Namespace", - "description": "the one namespace it opens (its own servers alone), when it was made for one" + "title": "Last Sent At" }, - "account": { - "type": "integer", - "title": "Account" + "last_sent": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Last Sent", + "default": [] }, - "email": { + "last_error": { "anyOf": [ { "type": "string" @@ -29872,210 +31360,135 @@ "type": "null" } ], - "title": "Email" + "title": "Last Error" + }, + "events": { + "items": { + "$ref": "#/components/schemas/AnalyticsEvent" + }, + "type": "array", + "title": "Events" } }, "additionalProperties": true, "type": "object", "required": [ - "id", - "name", - "scope", - "prefix", - "created_at", - "account" + "enabled", + "configured", + "events" ], - "title": "AccountToken", - "description": "Anyone's key, for admins." + "title": "AnalyticsStatus", + "description": "Whether usage statistics go to Google Analytics, and how the last send went (docs/analytics.md)." }, - "ActionInfo": { + "AnalyticsTestResult": { "properties": { - "name": { - "type": "string", - "title": "Name" - }, - "label": { - "type": "string", - "title": "Label" - }, - "group": { - "type": "string", - "title": "Group" - }, - "description": { - "type": "string", - "title": "Description", - "default": "" - }, - "params": { - "additionalProperties": true, - "type": "object", - "title": "Params", - "description": "a JSON Schema (type object) of its params; a string holding {{ }} stands for any type" - }, - "required": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Required" - }, - "effect": { - "type": "string", - "enum": [ - "read", - "self", - "lens", - "out", - "depends" - ], - "title": "Effect", - "description": "what it reaches: read and self run at once; lens asks unless it changes the event's own object; out asks first unless you let it run on its own; depends: worked out from its params" + "ok": { + "type": "boolean", + "title": "Ok" }, - "output": { + "error": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "Output", - "description": "a JSON Schema of what it gives back, for later nodes (steps.)" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "name", - "label", - "group", - "params", - "effect" - ], - "title": "ActionInfo" - }, - "ActivityActor": { - "properties": { - "type": { - "type": "string", - "enum": [ - "Service", - "Person", - "Application" - ], - "title": "Type" - }, - "id": { - "type": "string", - "title": "Id", - "description": "a Lens reference, like lens:account/1 or lens:automation/4" + "title": "Error" }, - "name": { - "type": "string", - "title": "Name" + "messages": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Messages", + "default": [] } }, "additionalProperties": true, "type": "object", "required": [ - "type", - "id", - "name" + "ok" ], - "title": "ActivityActor" + "title": "AnalyticsTestResult" }, - "ActivityCosts": { + "AnswerCheck": { "properties": { - "period": { - "type": "string", - "title": "Period" + "claims": { + "type": "integer", + "title": "Claims", + "description": "sentences that cite a source" }, - "since": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Since" + "supported": { + "type": "integer", + "title": "Supported", + "description": "claims the cited excerpts support" + }, + "verdicts": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array", + "title": "Verdicts", + "default": [] }, - "costs": { - "additionalProperties": { - "$ref": "#/components/schemas/ResourceSpend" + "uncited": { + "items": { + "type": "string" }, - "type": "object", - "title": "Costs", - "description": "by resource; ones you can't see are left out" + "type": "array", + "title": "Uncited", + "default": [] } }, "additionalProperties": true, "type": "object", "required": [ - "period", - "costs" + "claims", + "supported" ], - "title": "ActivityCosts" + "title": "AnswerCheck" }, - "ActivityEntry": { + "ApiToken": { "properties": { "id": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Id", - "description": "the ledger row's id; none for an audit log entry" + "type": "integer", + "title": "Id" }, - "at": { + "name": { "type": "string", - "title": "At" + "title": "Name" }, - "kind": { + "scope": { "type": "string", "enum": [ - "in", - "out", - "run", - "change" + "read", + "write" ], - "title": "Kind", - "description": "in: an API request; out: a call Lens made (a model, embeddings, the decision model, a webhook, a web tool); run: a job or routine run ended; change: an audit log entry, or a change to the entity graph (action `graph.`)" + "title": "Scope" }, - "action": { + "prefix": { "type": "string", - "title": "Action", - "description": "what it was: `POST /api/v1/routines/{rid}/run`, `model.chat`, `job.succeeded`, `routine.update`" + "title": "Prefix" }, - "resources": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Resources", - "description": "every resource it counts for, as table:id" + "created_at": { + "type": "string", + "title": "Created At" }, - "actor": { + "expires_at": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Actor", - "description": "the account that made it, when a person did" + "title": "Expires At" }, - "email": { + "last_used_at": { "anyOf": [ { "type": "string" @@ -30084,9 +31497,9 @@ "type": "null" } ], - "title": "Email" + "title": "Last Used At" }, - "model": { + "namespace": { "anyOf": [ { "type": "string" @@ -30095,59 +31508,149 @@ "type": "null" } ], - "title": "Model" + "title": "Namespace", + "description": "the one namespace it opens (its own servers alone), when it was made for one" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "name", + "scope", + "prefix", + "created_at" + ], + "title": "ApiToken" + }, + "ApiTokenCreate": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "default": "token" }, - "tokens_in": { + "scope": { + "type": "string", + "enum": [ + "read", + "write" + ], + "title": "Scope", + "default": "read" + }, + "namespace": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Tokens In" + "title": "Namespace", + "description": "a namespace you can read: the key opens that namespace's own MCP server and chat completions alone, and nothing else in Lens; none: whatever you can reach" }, - "tokens_out": { + "days": { "anyOf": [ { - "type": "integer" + "type": "integer", + "maximum": 3650.0, + "minimum": 0.0 }, { "type": "null" } ], - "title": "Tokens Out" + "title": "Days", + "description": "how long it lasts; default: tokens.default_days; 0: never expires, when tokens.never_expire allows" + } + }, + "additionalProperties": false, + "type": "object", + "title": "ApiTokenCreate" + }, + "ApiTokenCreated": { + "properties": { + "id": { + "type": "integer", + "title": "Id" }, - "cost_usd": { + "token": { + "type": "string", + "title": "Token" + }, + "note": { + "type": "string", + "title": "Note", + "default": "copy it now; it won't be shown again" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "token" + ], + "title": "ApiTokenCreated" + }, + "ApiTokenRename": { + "properties": { + "name": { + "type": "string", + "maxLength": 80, + "minLength": 1, + "title": "Name" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ], + "title": "ApiTokenRename" + }, + "Approval": { + "properties": { + "id": { + "type": "integer", + "title": "Id" + }, + "chat": { "anyOf": [ { - "type": "number" + "type": "integer" }, { "type": "null" } ], - "title": "Cost Usd", - "description": "estimated from the prices in Settings; none when the model has no price" + "title": "Chat" }, - "ms": { + "tool": { + "type": "string", + "title": "Tool" + }, + "summary": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Ms" + "title": "Summary" }, - "ok": { - "type": "boolean", - "title": "Ok", - "default": true + "estimate": { + "title": "Estimate" }, - "error": { + "status": { + "type": "string", + "title": "Status", + "description": "pending (waiting), running, done, failed, declined or expired" + }, + "created_at": { "anyOf": [ { "type": "string" @@ -30156,244 +31659,243 @@ "type": "null" } ], - "title": "Error", - "description": "the error's type or HTTP status; never its message" - }, - "detail": { - "title": "Detail" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "at", - "kind", - "action" - ], - "title": "ActivityEntry" - }, - "ActivityKind": { - "properties": { - "name": { - "type": "string", - "title": "Name" - }, - "label": { - "type": "string", - "title": "Label" - }, - "source": { - "type": "string", - "title": "Source" + "title": "Created At" }, - "type": { - "type": "string", - "title": "Type", - "description": "the Activity Streams verb its activities have" + "result": { + "title": "Result" }, - "object_type": { - "type": "string", - "title": "Object Type" + "error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Error" }, - "parent": { + "origin": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/ApprovalOrigin" }, { "type": "null" } ], - "title": "Parent" - }, - "children": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Children" - }, - "fields": { - "additionalProperties": true, - "type": "object", - "title": "Fields", - "description": "JSON Schemas of its own object, actor or target fields" - }, - "schema": { - "additionalProperties": true, - "type": "object", - "title": "Schema", - "description": "a JSON Schema of its activities, with every field" - }, - "untrusted": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Untrusted" + "description": "the automation run that asked, when one did" }, - "noisy": { - "type": "boolean", - "title": "Noisy", - "description": "left out of the timeline unless named", - "default": false + "intent": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalIntent" + }, + { + "type": "null" + } + ], + "description": "an automation's action: what it would do" }, - "sample": { + "automation": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "Sample" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "name", - "label", - "source", - "type", - "object_type", - "schema" - ], - "title": "ActivityKind" - }, - "ActivityLens": { - "properties": { - "source": { - "type": "string", - "title": "Source", - "description": "the source that made it, like recordings or log" + "title": "Automation", + "description": "the automation's name" }, - "pos": { - "items": {}, - "type": "array", - "title": "Pos", - "description": "the source's position, [time, id]; for the stream machinery" + "space": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Space" }, - "untrusted": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Untrusted", - "description": "dotted paths holding text from outside Lens" + "why": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalWhy" + }, + { + "type": "null" + } + ] }, - "cause": { + "expires_at": { "anyOf": [ { - "additionalProperties": { - "type": "integer" - }, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "Cause", - "description": "{automation, run, depth} when an automation caused it" + "title": "Expires At", + "description": "when it expires and nothing runs (automations only)" }, - "spaces": { + "decided_by": { "anyOf": [ { - "items": { - "type": "integer" - }, - "type": "array" + "type": "string" }, { "type": "null" } ], - "title": "Spaces", - "description": "every namespace it belongs to, when there are several" + "title": "Decided By" }, - "audience": { + "decided_at": { "anyOf": [ { - "type": "string", - "enum": [ - "space", - "owner", - "admins" - ] + "type": "string" }, { "type": "null" } ], - "title": "Audience", - "description": "who may see it (default: space)" + "title": "Decided At" }, - "owner": { + "told": { + "items": { + "$ref": "#/components/schemas/ApprovalTold" + }, + "type": "array", + "title": "Told", + "description": "the chats you were told in" + }, + "can": { "anyOf": [ { - "type": "integer" + "$ref": "#/components/schemas/ApprovalCan" }, { "type": "null" } - ], - "title": "Owner", - "description": "the account that alone sees it, with audience owner" + ] } }, "additionalProperties": true, "type": "object", "required": [ - "source", - "pos" + "id", + "tool", + "status" ], - "title": "ActivityLens" + "title": "Approval" }, - "ActivityMark": { + "ApprovalCan": { "properties": { - "reviewed": { + "approve": { "type": "boolean", - "title": "Reviewed", + "title": "Approve", "default": false }, - "important": { + "decline": { "type": "boolean", - "title": "Important", + "title": "Decline", "default": false }, - "hidden": { + "edit": { "type": "boolean", - "title": "Hidden", + "title": "Edit", "default": false }, - "at": { + "always": { + "type": "boolean", + "title": "Always", + "default": false + } + }, + "additionalProperties": true, + "type": "object", + "title": "ApprovalCan", + "description": "What you can do with it from where you asked: approving an automation's action is yours, signed in or in the\nchat it told you in; an API key, an app or an agent can only decline it." + }, + "ApprovalCount": { + "properties": { + "waiting": { + "type": "integer", + "title": "Waiting" + }, + "automations": { + "type": "integer", + "title": "Automations", + "description": "of them, waiting for an automation" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "waiting", + "automations" + ], + "title": "ApprovalCount" + }, + "ApprovalDecision": { + "properties": { + "decision": { + "type": "string", + "enum": [ + "approve", + "sample", + "decline", + "edit", + "always" + ], + "title": "Decision", + "description": "sample: a batch run on 3 assets first; edit: an automation's action with `params` changed, then carried out; always: carried out, and that action node of the automation runs without asking from now on (signed in only)", + "default": "approve" + }, + "params": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "At", - "description": "when you last marked it" + "title": "Params", + "description": "edit: the params to change (null leaves one out)" } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", - "title": "ActivityMark", - "description": "Your own review marks on an activity; nobody else sees them." + "title": "ApprovalDecision" }, - "ActivityObject": { + "ApprovalIntent": { "properties": { - "type": { + "action": { "type": "string", - "title": "Type" + "title": "Action" + }, + "params": { + "additionalProperties": true, + "type": "object", + "title": "Params" + }, + "effect": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Effect" }, - "id": { + "risk": { "anyOf": [ { "type": "string" @@ -30402,21 +31904,21 @@ "type": "null" } ], - "title": "Id", - "description": "a Lens reference, like lens:recording/7" + "title": "Risk" }, - "name": { + "untrusted": { "anyOf": [ { - "type": "string" + "type": "boolean" }, { "type": "null" } ], - "title": "Name" + "title": "Untrusted", + "description": "its run read text from outside Lens" }, - "url": { + "node": { "anyOf": [ { "type": "string" @@ -30425,29 +31927,9 @@ "type": "null" } ], - "title": "Url", - "description": "its page in the web app, relative to it" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "type" - ], - "title": "ActivityObject", - "description": "What the activity is about; each kind adds its own fields (GET /activities/kinds has its schema)." - }, - "ActivityPage": { - "properties": { - "items": { - "items": { - "$ref": "#/components/schemas/StreamActivity" - }, - "type": "array", - "title": "Items", - "description": "newest first" + "title": "Node" }, - "next": { + "status": { "anyOf": [ { "type": "string" @@ -30456,373 +31938,190 @@ "type": "null" } ], - "title": "Next", - "description": "give it as before for the page after; null at the end" - }, - "namespaces": { - "additionalProperties": { - "type": "string" - }, - "type": "object", - "title": "Namespaces", - "description": "the names of the namespaces in items, by id" - }, - "marks": { - "additionalProperties": { - "$ref": "#/components/schemas/ActivityMark" - }, - "type": "object", - "title": "Marks", - "description": "your marks on items, by id (those you marked)" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "items" - ], - "title": "ActivityPage" - }, - "ActivityTop": { - "properties": { - "period": { - "type": "string", - "title": "Period" + "title": "Status" }, - "since": { + "spaces": { "anyOf": [ { - "type": "string" + "items": { + "type": "integer" + }, + "type": "array" }, { "type": "null" } ], - "title": "Since" - }, - "resources": { - "items": { - "$ref": "#/components/schemas/ResourceCost" - }, - "type": "array", - "title": "Resources" + "title": "Spaces" } }, "additionalProperties": true, "type": "object", "required": [ - "period", - "resources" + "action" ], - "title": "ActivityTop" + "title": "ApprovalIntent", + "description": "What an automation's action would do, as the inbox shows it (credential headers hidden)." }, - "ActivityTotals": { + "ApprovalOrigin": { "properties": { - "resource": { + "automation": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Resource" - }, - "period": { - "type": "string", - "title": "Period" + "title": "Automation" }, - "since": { + "run": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Since" - }, - "calls": { - "type": "integer", - "title": "Calls" - }, - "failed": { - "type": "integer", - "title": "Failed" - }, - "tokens_in": { - "type": "integer", - "title": "Tokens In" - }, - "tokens_out": { - "type": "integer", - "title": "Tokens Out" - }, - "cost_usd": { - "type": "number", - "title": "Cost Usd", - "description": "what its calls cost (run rows repeat their calls' cost and aren't added again)" - }, - "ms": { - "type": "integer", - "title": "Ms" - }, - "unpriced": { - "type": "integer", - "title": "Unpriced", - "description": "calls that cost something but have no figure (a model with no price, a reply without token counts)", - "default": 0 - }, - "estimate": { - "type": "boolean", - "title": "Estimate", - "description": "true when unpriced calls make cost_usd a floor rather than exact", - "default": false - }, - "by_kind": { - "additionalProperties": { - "$ref": "#/components/schemas/KindTotals" - }, - "type": "object", - "title": "By Kind" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "period", - "calls", - "failed", - "tokens_in", - "tokens_out", - "cost_usd", - "ms", - "by_kind" - ], - "title": "ActivityTotals" - }, - "AnalyticsChurn": { - "properties": { - "previous_active": { - "type": "integer", - "title": "Previous Active" - }, - "retained": { - "type": "integer", - "title": "Retained" - }, - "churned": { - "type": "integer", - "title": "Churned" + "title": "Run" }, - "rate": { + "node": { "anyOf": [ { - "type": "number" + "type": "string" }, { "type": "null" - } - ], - "title": "Rate" - }, - "returning": { - "type": "integer", - "title": "Returning" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "previous_active", - "retained", - "churned", - "returning" - ], - "title": "AnalyticsChurn" - }, - "AnalyticsCohort": { - "properties": { - "week": { - "type": "string", - "title": "Week" - }, - "users": { - "type": "integer", - "title": "Users" - }, - "retention": { - "items": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] - }, - "type": "array", - "title": "Retention" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "week", - "users", - "retention" - ], - "title": "AnalyticsCohort" - }, - "AnalyticsDay": { - "properties": { - "day": { - "type": "string", - "title": "Day" - }, - "active_users": { - "type": "integer", - "title": "Active Users" - }, - "actions": { - "type": "integer", - "title": "Actions" + } + ], + "title": "Node" } }, "additionalProperties": true, "type": "object", - "required": [ - "day", - "active_users", - "actions" - ], - "title": "AnalyticsDay" + "title": "ApprovalOrigin" }, - "AnalyticsEvent": { + "ApprovalOutcome": { "properties": { - "name": { + "status": { "type": "string", - "title": "Name" + "title": "Status" }, - "description": { - "type": "string", - "title": "Description" + "batch": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Batch", + "description": "the batch run started, for run_template" }, - "on": { - "type": "boolean", - "title": "On" + "error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Error", + "description": "why an automation's action failed" + }, + "result": { + "title": "Result", + "description": "what an automation's action gave back" + }, + "always": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Always", + "description": "that node runs without asking from now on" } }, "additionalProperties": true, "type": "object", "required": [ - "name", - "description", - "on" + "status" ], - "title": "AnalyticsEvent" + "title": "ApprovalOutcome" }, - "AnalyticsFeature": { + "ApprovalTold": { "properties": { - "feature": { + "channel": { "type": "string", - "title": "Feature" + "title": "Channel" }, - "actions": { - "type": "integer", - "title": "Actions" + "label": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Label" }, - "users": { - "type": "integer", - "title": "Users" + "chat": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Chat" } }, "additionalProperties": true, "type": "object", "required": [ - "feature", - "actions", - "users" + "channel" ], - "title": "AnalyticsFeature" + "title": "ApprovalTold" }, - "AnalyticsMetrics": { + "ApprovalWhy": { "properties": { - "days": { - "type": "integer", - "title": "Days" - }, - "since": { - "type": "string", - "title": "Since" - }, - "until": { + "activity": { "type": "string", - "title": "Until" - }, - "daily": { - "items": { - "$ref": "#/components/schemas/AnalyticsDay" - }, - "type": "array", - "title": "Daily" - }, - "dau": { - "type": "integer", - "title": "Dau" - }, - "wau": { - "type": "integer", - "title": "Wau" - }, - "mau": { - "type": "integer", - "title": "Mau" + "title": "Activity" }, - "stickiness": { + "kind": { "anyOf": [ { - "type": "number" + "type": "string" }, { "type": "null" } ], - "title": "Stickiness" - }, - "accounts": { - "type": "integer", - "title": "Accounts" - }, - "active_users": { - "type": "integer", - "title": "Active Users" - }, - "new_users": { - "type": "integer", - "title": "New Users" - }, - "churn": { - "$ref": "#/components/schemas/AnalyticsChurn" - }, - "retention": { - "items": { - "$ref": "#/components/schemas/AnalyticsCohort" - }, - "type": "array", - "title": "Retention" + "title": "Kind" }, - "features": { - "items": { - "$ref": "#/components/schemas/AnalyticsFeature" - }, - "type": "array", - "title": "Features" + "summary": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Summary" }, - "last_active_day": { + "published": { "anyOf": [ { "type": "string" @@ -30831,51 +32130,66 @@ "type": "null" } ], - "title": "Last Active Day" + "title": "Published" }, - "days_since_active": { + "url": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Days Since Active" + "title": "Url" } }, "additionalProperties": true, "type": "object", "required": [ - "days", - "since", - "until", - "daily", - "dau", - "wau", - "mau", - "accounts", - "active_users", - "new_users", - "churn", - "retention", - "features" + "activity" ], - "title": "AnalyticsMetrics", - "description": "Active people, churn, retention and feature use, worked out on this machine from the activity ledger and\nsign-ins (docs/analytics.md#the-numbers)." + "title": "ApprovalWhy", + "description": "The activity that caused it, as it was when it asked." }, - "AnalyticsStatus": { + "AssistantMemory": { "properties": { - "enabled": { - "type": "boolean", - "title": "Enabled" + "id": { + "type": "integer", + "title": "Id" }, - "configured": { - "type": "boolean", - "title": "Configured" + "text": { + "type": "string", + "title": "Text" }, - "measurement_id": { + "recording": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Recording", + "description": "the asset it came from" + }, + "t0": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "T0", + "description": "the moment in that asset (ms)" + }, + "title": { "anyOf": [ { "type": "string" @@ -30884,9 +32198,10 @@ "type": "null" } ], - "title": "Measurement Id" + "title": "Title", + "description": "that asset's title" }, - "client_id": { + "time": { "anyOf": [ { "type": "string" @@ -30895,28 +32210,33 @@ "type": "null" } ], - "title": "Client Id" + "title": "Time", + "description": "that moment as \"12:34\"" }, - "last_sent_at": { + "chat": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Last Sent At" + "title": "Chat", + "description": "the conversation it was told in" }, - "last_sent": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Last Sent", - "default": [] + "author": { + "type": "string", + "title": "Author", + "description": "assistant (kept from a conversation) or person (written here)" }, - "last_error": { + "pinned": { + "type": "boolean", + "title": "Pinned", + "description": "always read with every question", + "default": false + }, + "created_at": { "anyOf": [ { "type": "string" @@ -30925,33 +32245,9 @@ "type": "null" } ], - "title": "Last Error" - }, - "events": { - "items": { - "$ref": "#/components/schemas/AnalyticsEvent" - }, - "type": "array", - "title": "Events" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "enabled", - "configured", - "events" - ], - "title": "AnalyticsStatus", - "description": "Whether usage statistics go to Google Analytics, and how the last send went (docs/analytics.md)." - }, - "AnalyticsTestResult": { - "properties": { - "ok": { - "type": "boolean", - "title": "Ok" + "title": "Created At" }, - "error": { + "updated_at": { "anyOf": [ { "type": "string" @@ -30960,111 +32256,86 @@ "type": "null" } ], - "title": "Error" - }, - "messages": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Messages", - "default": [] + "title": "Updated At" } }, "additionalProperties": true, "type": "object", "required": [ - "ok" + "id", + "text", + "author" ], - "title": "AnalyticsTestResult" + "title": "AssistantMemory" }, - "AnswerCheck": { + "AssistantMemoryCreate": { "properties": { - "claims": { - "type": "integer", - "title": "Claims", - "description": "sentences that cite a source" - }, - "supported": { - "type": "integer", - "title": "Supported", - "description": "claims the cited excerpts support" - }, - "verdicts": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "type": "array", - "title": "Verdicts", - "default": [] + "text": { + "type": "string", + "maxLength": 500, + "title": "Text" }, - "uncited": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Uncited", - "default": [] + "pinned": { + "type": "boolean", + "title": "Pinned", + "default": false } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", "required": [ - "claims", - "supported" + "text" ], - "title": "AnswerCheck" + "title": "AssistantMemoryCreate" }, - "ApiToken": { + "AssistantMemoryUpdate": { "properties": { - "id": { - "type": "integer", - "title": "Id" - }, - "name": { - "type": "string", - "title": "Name" - }, - "scope": { - "type": "string", - "enum": [ - "read", - "write" + "text": { + "anyOf": [ + { + "type": "string", + "maxLength": 500 + }, + { + "type": "null" + } ], - "title": "Scope" - }, - "prefix": { - "type": "string", - "title": "Prefix" - }, - "created_at": { - "type": "string", - "title": "Created At" + "title": "Text" }, - "expires_at": { + "pinned": { "anyOf": [ { - "type": "string" + "type": "boolean" }, { "type": "null" } ], - "title": "Expires At" + "title": "Pinned" + } + }, + "additionalProperties": false, + "type": "object", + "title": "AssistantMemoryUpdate" + }, + "AttachedTo": { + "properties": { + "resource": { + "type": "integer", + "title": "Resource" }, - "last_used_at": { + "file": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Last Used At" + "title": "File" }, - "namespace": { + "title": { "anyOf": [ { "type": "string" @@ -31073,130 +32344,148 @@ "type": "null" } ], - "title": "Namespace", - "description": "the one namespace it opens (its own servers alone), when it was made for one" + "title": "Title" } }, "additionalProperties": true, "type": "object", "required": [ - "id", - "name", - "scope", - "prefix", - "created_at" + "resource" ], - "title": "ApiToken" + "title": "AttachedTo", + "description": "The email a resource was attached to (it's one of that email's files too)." }, - "ApiTokenCreate": { + "Attachment": { "properties": { - "name": { + "id": { "type": "string", - "title": "Name", - "default": "token" + "title": "Id", + "description": "the upload" }, - "scope": { + "filename": { "type": "string", - "enum": [ - "read", - "write" - ], - "title": "Scope", - "default": "read" + "title": "Filename" }, - "namespace": { + "size": { + "type": "integer", + "title": "Size" + }, + "recording": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Namespace", - "description": "a namespace you can read: the key opens that namespace's own MCP server and chat completions alone, and nothing else in Lens; none: whatever you can reach" + "title": "Recording", + "description": "the asset it became, once imported" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "filename", + "size" + ], + "title": "Attachment" + }, + "AuditEntry": { + "properties": { + "at": { + "type": "string", + "title": "At" }, - "days": { + "email": { "anyOf": [ { - "type": "integer", - "maximum": 3650.0, - "minimum": 0.0 + "type": "string" }, { "type": "null" } ], - "title": "Days", - "description": "how long it lasts; default: tokens.default_days; 0: never expires, when tokens.never_expire allows" - } - }, - "additionalProperties": false, - "type": "object", - "title": "ApiTokenCreate" - }, - "ApiTokenCreated": { - "properties": { - "id": { - "type": "integer", - "title": "Id" - }, - "token": { - "type": "string", - "title": "Token" + "title": "Email" }, - "note": { + "action": { "type": "string", - "title": "Note", - "default": "copy it now; it won't be shown again" + "title": "Action" + }, + "target": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Target" + }, + "detail": { + "title": "Detail" } }, "additionalProperties": true, "type": "object", "required": [ - "id", - "token" + "at", + "action" ], - "title": "ApiTokenCreated" + "title": "AuditEntry" }, - "ApiTokenRename": { + "AuthStatus": { "properties": { - "name": { - "type": "string", - "maxLength": 80, - "minLength": 1, - "title": "Name" + "setup_required": { + "type": "boolean", + "title": "Setup Required" + }, + "wizard_pending": { + "type": "boolean", + "title": "Wizard Pending", + "default": false + }, + "passwords": { + "type": "boolean", + "title": "Passwords", + "default": false } }, - "additionalProperties": false, + "additionalProperties": true, "type": "object", "required": [ - "name" + "setup_required" ], - "title": "ApiTokenRename" + "title": "AuthStatus" }, - "Approval": { + "Automation": { "properties": { "id": { "type": "integer", "title": "Id" }, - "chat": { + "name": { + "type": "string", + "title": "Name" + }, + "description": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Chat" + "title": "Description" }, - "tool": { - "type": "string", - "title": "Tool" + "enabled": { + "type": "boolean", + "title": "Enabled" }, - "summary": { + "enabled_at": { "anyOf": [ { "type": "string" @@ -31205,64 +32494,147 @@ "type": "null" } ], - "title": "Summary" + "title": "Enabled At", + "description": "when it was last switched on: it reacts only to what happens after" }, - "estimate": { - "title": "Estimate" + "spaces": { + "anyOf": [ + { + "items": { + "type": "integer" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Spaces", + "description": "the namespaces it works in; none for every one (admins)" }, - "status": { - "type": "string", - "title": "Status", - "description": "pending (waiting), running, done, failed, declined or expired" + "namespace_names": { + "anyOf": [ + { + "items": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Namespace Names" }, - "created_at": { + "run_as": { + "type": "integer", + "title": "Run As", + "description": "the account it acts for, with that person's permissions: its maker" + }, + "triggers": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array", + "title": "Triggers", + "description": "each {as, on, ...}: {as, on: event, kinds, where?, from_automations?}, {as, on: manual}; on schedule, at, relative and webhook are coming soon (docs/automations.md, Triggers)" + }, + "join": { + "additionalProperties": true, + "type": "object", + "title": "Join", + "description": "how several triggers make one run: {mode: any} (each on its own)" + }, + "if": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Created At" + "title": "If", + "description": "a match tree over the run context, tested before the Then runs, like {all: [{path, op, value}]}" }, - "result": { - "title": "Result" + "workflow": { + "type": "integer", + "title": "Workflow", + "description": "its workflow (scope event)" }, - "error": { + "version": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Error" + "title": "Version", + "description": "the workflow version it runs; none follows the published one" }, - "origin": { + "runs_version": { "anyOf": [ { - "$ref": "#/components/schemas/ApprovalOrigin" + "type": "integer" }, { "type": "null" } ], - "description": "the automation run that asked, when one did" + "title": "Runs Version", + "description": "the version it runs now" }, - "intent": { + "graph": { "anyOf": [ { - "$ref": "#/components/schemas/ApprovalIntent" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "description": "an automation's action: what it would do" + "title": "Graph", + "description": "the Then: a workflow graph of scope event (an input node, then action nodes and the flow primitives)" }, - "automation": { + "policy": { + "additionalProperties": { + "type": "string", + "enum": [ + "ask", + "auto" + ] + }, + "type": "object", + "title": "Policy", + "description": "{action node id: ask or auto}" + }, + "limits": { + "additionalProperties": true, + "type": "object", + "title": "Limits", + "description": "{cooldown (like 10m), max_per_hour}" + }, + "counters": { + "additionalProperties": { + "type": "integer" + }, + "type": "object", + "title": "Counters", + "description": "{runs, skipped (its If was false), limited (over a limit), missed}" + }, + "last_run_at": { "anyOf": [ { "type": "string" @@ -31271,31 +32643,31 @@ "type": "null" } ], - "title": "Automation", - "description": "the automation's name" + "title": "Last Run At" }, - "space": { + "last_status": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Space" + "title": "Last Status" }, - "why": { + "created_by": { "anyOf": [ { - "$ref": "#/components/schemas/ApprovalWhy" + "type": "string" }, { "type": "null" } - ] + ], + "title": "Created By" }, - "expires_at": { + "created_at": { "anyOf": [ { "type": "string" @@ -31304,10 +32676,9 @@ "type": "null" } ], - "title": "Expires At", - "description": "when it expires and nothing runs (automations only)" + "title": "Created At" }, - "decided_by": { + "updated_at": { "anyOf": [ { "type": "string" @@ -31316,9 +32687,9 @@ "type": "null" } ], - "title": "Decided By" + "title": "Updated At" }, - "decided_at": { + "removed_at": { "anyOf": [ { "type": "string" @@ -31327,232 +32698,254 @@ "type": "null" } ], - "title": "Decided At" + "title": "Removed At", + "description": "when it was deleted (restore brings it back)" }, - "told": { - "items": { - "$ref": "#/components/schemas/ApprovalTold" - }, - "type": "array", - "title": "Told", - "description": "the chats you were told in" + "waiting": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Waiting", + "description": "in lists: its actions waiting for your pick or for their time" }, - "can": { + "cost_month": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Cost Month", + "description": "in lists: what it cost this month {cost_usd, estimate (true when some calls had no price)}" + }, + "next_at": { "anyOf": [ { - "$ref": "#/components/schemas/ApprovalCan" + "type": "string" }, { "type": "null" } - ] + ], + "title": "Next At", + "description": "in lists: when it runs next, from its schedules (coming soon)" } }, "additionalProperties": true, "type": "object", "required": [ "id", - "tool", - "status" + "name", + "enabled", + "run_as", + "triggers", + "join", + "workflow", + "limits", + "counters" ], - "title": "Approval" - }, - "ApprovalCan": { - "properties": { - "approve": { - "type": "boolean", - "title": "Approve", - "default": false - }, - "decline": { - "type": "boolean", - "title": "Decline", - "default": false - }, - "edit": { - "type": "boolean", - "title": "Edit", - "default": false - }, - "always": { - "type": "boolean", - "title": "Always", - "default": false - } - }, - "additionalProperties": true, - "type": "object", - "title": "ApprovalCan", - "description": "What you can do with it from where you asked: approving an automation's action is yours, signed in or in the\nchat it told you in; an API key, an app or an agent can only decline it." + "title": "Automation" }, - "ApprovalCount": { + "AutomationCatalog": { "properties": { - "waiting": { - "type": "integer", - "title": "Waiting" - }, "automations": { - "type": "integer", - "title": "Automations", - "description": "of them, waiting for an automation" + "items": { + "$ref": "#/components/schemas/Automation" + }, + "type": "array", + "title": "Automations" } }, "additionalProperties": true, "type": "object", "required": [ - "waiting", "automations" ], - "title": "ApprovalCount" + "title": "AutomationCatalog" }, - "ApprovalDecision": { + "AutomationCreate": { "properties": { - "decision": { + "name": { "type": "string", - "enum": [ - "approve", - "sample", - "decline", - "edit", - "always" + "title": "Name" + }, + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } ], - "title": "Decision", - "description": "sample: a batch run on 3 assets first; edit: an automation's action with `params` changed, then carried out; always: carried out, and that action node of the automation runs without asking from now on (signed in only)", - "default": "approve" + "title": "Description" }, - "params": { + "enabled": { + "type": "boolean", + "title": "Enabled", + "description": "switched on, it reacts to what happens from now on", + "default": true + }, + "spaces": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "items": { + "type": "integer" + }, + "type": "array" }, { "type": "null" } ], - "title": "Params", - "description": "edit: the params to change (null leaves one out)" - } - }, - "additionalProperties": false, - "type": "object", - "title": "ApprovalDecision" - }, - "ApprovalIntent": { - "properties": { - "action": { - "type": "string", - "title": "Action" + "title": "Spaces", + "description": "namespace ids you can edit; default: each one you can edit (every one, for admins)" }, - "params": { - "additionalProperties": true, - "type": "object", - "title": "Params" + "triggers": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array", + "title": "Triggers", + "description": "each {as, on, ...}: {as, on: event, kinds, where?, from_automations?}, {as, on: manual}; on schedule, at, relative and webhook are coming soon (docs/automations.md, Triggers)" }, - "effect": { + "join": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Effect" + "title": "Join", + "description": "default {mode: any}: each trigger starts a run of its own" }, - "risk": { + "if": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Risk" + "title": "If", + "description": "a match tree over the run context, tested before the Then runs, like {all: [{path, op, value}]}" }, - "untrusted": { + "graph": { "anyOf": [ { - "type": "boolean" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Untrusted", - "description": "its run read text from outside Lens" + "title": "Graph", + "description": "the Then: a workflow graph of scope event (an input node, then action nodes and the flow primitives); or name a saved one in workflow" }, - "node": { + "workflow": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Node" + "title": "Workflow", + "description": "a saved workflow of scope event, instead of a graph" }, - "status": { + "version": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Status" + "title": "Version", + "description": "with workflow: the version to run; none follows the published one" }, - "spaces": { + "policy": { "anyOf": [ { - "items": { - "type": "integer" + "additionalProperties": { + "type": "string", + "const": "ask" }, - "type": "array" + "type": "object" }, { "type": "null" } ], - "title": "Spaces" + "title": "Policy", + "description": "{action node id: ask}; only you, signed in, let a node run on its own (POST /automations/{id}/policy)" + }, + "limits": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Limits", + "description": "{cooldown: 0s, max_per_hour: 60}" } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", "required": [ - "action" + "name", + "triggers" ], - "title": "ApprovalIntent", - "description": "What an automation's action would do, as the inbox shows it (credential headers hidden)." + "title": "AutomationCreate" }, - "ApprovalOrigin": { + "AutomationDraftTry": { "properties": { - "automation": { + "activity": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Automation" + "title": "Activity", + "description": "an activity's id to run it on (GET /api/v1/activities)" }, - "run": { + "as": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Run" + "title": "As", + "description": "which trigger it runs as (its `as`); default: the first that fits" }, - "node": { + "kind": { "anyOf": [ { "type": "string" @@ -31561,32 +32954,57 @@ "type": "null" } ], - "title": "Node" + "title": "Kind", + "description": "else a kind of activity, to run it on that kind's sample" + }, + "draft": { + "$ref": "#/components/schemas/AutomationCreate", + "description": "the automation as you would save it" } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", - "title": "ApprovalOrigin" + "required": [ + "draft" + ], + "title": "AutomationDraftTry" }, - "ApprovalOutcome": { + "AutomationPolicy": { "properties": { - "status": { + "node": { "type": "string", - "title": "Status" + "title": "Node", + "description": "an action node's id" }, - "batch": { - "anyOf": [ - { - "type": "integer" - }, - { - "type": "null" - } + "value": { + "type": "string", + "enum": [ + "ask", + "auto" ], - "title": "Batch", - "description": "the batch run started, for run_template" + "title": "Value", + "description": "ask: it asks you first; auto: it runs on its own" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "node", + "value" + ], + "title": "AutomationPolicy" + }, + "AutomationRun": { + "properties": { + "id": { + "type": "integer", + "title": "Id" }, - "error": { + "automation": { + "type": "integer", + "title": "Automation" + }, + "name": { "anyOf": [ { "type": "string" @@ -31595,40 +33013,21 @@ "type": "null" } ], - "title": "Error", - "description": "why an automation's action failed" - }, - "result": { - "title": "Result", - "description": "what an automation's action gave back" + "title": "Name" }, - "always": { + "version": { "anyOf": [ { - "type": "boolean" + "type": "integer" }, { "type": "null" } ], - "title": "Always", - "description": "that node runs without asking from now on" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "status" - ], - "title": "ApprovalOutcome" - }, - "ApprovalTold": { - "properties": { - "channel": { - "type": "string", - "title": "Channel" + "title": "Version", + "description": "the workflow version it ran" }, - "label": { + "trigger": { "anyOf": [ { "type": "string" @@ -31637,9 +33036,10 @@ "type": "null" } ], - "title": "Label" + "title": "Trigger", + "description": "the trigger (its `as`) that started it" }, - "chat": { + "trigger_on": { "anyOf": [ { "type": "string" @@ -31648,23 +33048,9 @@ "type": "null" } ], - "title": "Chat" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "channel" - ], - "title": "ApprovalTold" - }, - "ApprovalWhy": { - "properties": { - "activity": { - "type": "string", - "title": "Activity" + "title": "Trigger On" }, - "kind": { + "event": { "anyOf": [ { "type": "string" @@ -31673,9 +33059,23 @@ "type": "null" } ], - "title": "Kind" + "title": "Event", + "description": "the activity that started it (an id)" }, - "summary": { + "event_ids": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Event Ids", + "description": "every activity it ran on (a join's are several)" + }, + "status": { + "type": "string", + "title": "Status", + "description": "running, done, partly (some actions failed), failed, waiting (actions wait for your pick or their time), held (over a budget: decide), released or skipped (your pick on a held run)" + }, + "by": { "anyOf": [ { "type": "string" @@ -31684,9 +33084,10 @@ "type": "null" } ], - "title": "Summary" + "title": "By", + "description": "who started it by hand" }, - "published": { + "started_at": { "anyOf": [ { "type": "string" @@ -31695,9 +33096,9 @@ "type": "null" } ], - "title": "Published" + "title": "Started At" }, - "url": { + "finished_at": { "anyOf": [ { "type": "string" @@ -31706,67 +33107,51 @@ "type": "null" } ], - "title": "Url" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "activity" - ], - "title": "ApprovalWhy", - "description": "The activity that caused it, as it was when it asked." - }, - "AssistantMemory": { - "properties": { - "id": { - "type": "integer", - "title": "Id" + "title": "Finished At" }, - "text": { - "type": "string", - "title": "Text" + "counts": { + "additionalProperties": { + "type": "integer" + }, + "type": "object", + "title": "Counts", + "description": "its actions: {done, waiting, scheduled, failed}" }, - "recording": { + "cost_usd": { "anyOf": [ { - "type": "integer" + "type": "number" }, { "type": "null" } ], - "title": "Recording", - "description": "the asset it came from" + "title": "Cost Usd" }, - "t0": { + "tokens": { "anyOf": [ { "type": "integer" }, - { - "type": "number" - }, { "type": "null" } ], - "title": "T0", - "description": "the moment in that asset (ms)" + "title": "Tokens" }, - "title": { + "cost_estimate": { "anyOf": [ { - "type": "string" + "type": "boolean" }, { "type": "null" } ], - "title": "Title", - "description": "that asset's title" + "title": "Cost Estimate", + "description": "true when some calls had no price, so the cost is a floor" }, - "time": { + "error": { "anyOf": [ { "type": "string" @@ -31775,99 +33160,57 @@ "type": "null" } ], - "title": "Time", - "description": "that moment as \"12:34\"" + "title": "Error" }, - "chat": { + "why": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Chat", - "description": "the conversation it was told in" - }, - "author": { - "type": "string", - "title": "Author", - "description": "assistant (kept from a conversation) or person (written here)" - }, - "pinned": { - "type": "boolean", - "title": "Pinned", - "description": "always read with every question", - "default": false + "title": "Why", + "description": "why it was held" }, - "created_at": { + "hold": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Created At" + "title": "Hold", + "description": "a held run: the budget it is over and how many runs it missed" }, - "updated_at": { + "cause_depth": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Updated At" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "id", - "text", - "author" - ], - "title": "AssistantMemory" - }, - "AssistantMemoryCreate": { - "properties": { - "text": { - "type": "string", - "maxLength": 500, - "title": "Text" + "title": "Cause Depth", + "description": "how many automations' runs led to this one" }, - "pinned": { - "type": "boolean", - "title": "Pinned", - "default": false - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "text" - ], - "title": "AssistantMemoryCreate" - }, - "AssistantMemoryUpdate": { - "properties": { - "text": { + "space": { "anyOf": [ { - "type": "string", - "maxLength": 500 + "type": "integer" }, { "type": "null" } ], - "title": "Text" + "title": "Space" }, - "pinned": { + "dry": { "anyOf": [ { "type": "boolean" @@ -31876,94 +33219,64 @@ "type": "null" } ], - "title": "Pinned" + "title": "Dry" } }, - "additionalProperties": false, + "additionalProperties": true, "type": "object", - "title": "AssistantMemoryUpdate" + "required": [ + "id", + "automation", + "status" + ], + "title": "AutomationRun" }, - "AttachedTo": { + "AutomationRunDetail": { "properties": { - "resource": { + "id": { "type": "integer", - "title": "Resource" + "title": "Id" }, - "file": { + "automation": { + "type": "integer", + "title": "Automation" + }, + "name": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "File" + "title": "Name" }, - "title": { + "version": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } - ], - "title": "Title" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "resource" - ], - "title": "AttachedTo", - "description": "The email a resource was attached to (it's one of that email's files too)." - }, - "Attachment": { - "properties": { - "id": { - "type": "string", - "title": "Id", - "description": "the upload" - }, - "filename": { - "type": "string", - "title": "Filename" - }, - "size": { - "type": "integer", - "title": "Size" + ], + "title": "Version", + "description": "the workflow version it ran" }, - "recording": { + "trigger": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Recording", - "description": "the asset it became, once imported" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "id", - "filename", - "size" - ], - "title": "Attachment" - }, - "AuditEntry": { - "properties": { - "at": { - "type": "string", - "title": "At" + "title": "Trigger", + "description": "the trigger (its `as`) that started it" }, - "email": { + "trigger_on": { "anyOf": [ { "type": "string" @@ -31972,13 +33285,9 @@ "type": "null" } ], - "title": "Email" - }, - "action": { - "type": "string", - "title": "Action" + "title": "Trigger On" }, - "target": { + "event": { "anyOf": [ { "type": "string" @@ -31987,55 +33296,23 @@ "type": "null" } ], - "title": "Target" - }, - "detail": { - "title": "Detail" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "at", - "action" - ], - "title": "AuditEntry" - }, - "AuthStatus": { - "properties": { - "setup_required": { - "type": "boolean", - "title": "Setup Required" - }, - "wizard_pending": { - "type": "boolean", - "title": "Wizard Pending", - "default": false + "title": "Event", + "description": "the activity that started it (an id)" }, - "passwords": { - "type": "boolean", - "title": "Passwords", - "default": false - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "setup_required" - ], - "title": "AuthStatus" - }, - "Automation": { - "properties": { - "id": { - "type": "integer", - "title": "Id" + "event_ids": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Event Ids", + "description": "every activity it ran on (a join's are several)" }, - "name": { + "status": { "type": "string", - "title": "Name" + "title": "Status", + "description": "running, done, partly (some actions failed), failed, waiting (actions wait for your pick or their time), held (over a budget: decide), released or skipped (your pick on a held run)" }, - "description": { + "by": { "anyOf": [ { "type": "string" @@ -32044,13 +33321,10 @@ "type": "null" } ], - "title": "Description" - }, - "enabled": { - "type": "boolean", - "title": "Enabled" + "title": "By", + "description": "who started it by hand" }, - "enabled_at": { + "started_at": { "anyOf": [ { "type": "string" @@ -32059,108 +33333,85 @@ "type": "null" } ], - "title": "Enabled At", - "description": "when it was last switched on: it reacts only to what happens after" + "title": "Started At" }, - "spaces": { + "finished_at": { "anyOf": [ { - "items": { - "type": "integer" - }, - "type": "array" + "type": "string" }, { "type": "null" } ], - "title": "Spaces", - "description": "the namespaces it works in; none for every one (admins)" + "title": "Finished At" }, - "namespace_names": { + "counts": { + "additionalProperties": { + "type": "integer" + }, + "type": "object", + "title": "Counts", + "description": "its actions: {done, waiting, scheduled, failed}" + }, + "cost_usd": { "anyOf": [ { - "items": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "type": "array" + "type": "number" }, { "type": "null" } ], - "title": "Namespace Names" - }, - "run_as": { - "type": "integer", - "title": "Run As", - "description": "the account it acts for, with that person's permissions: its maker" - }, - "triggers": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "type": "array", - "title": "Triggers", - "description": "each {as, on, ...}: {as, on: event, kinds, where?, from_automations?}, {as, on: manual}; on schedule, at, relative and webhook are coming soon (docs/automations.md, Triggers)" - }, - "join": { - "additionalProperties": true, - "type": "object", - "title": "Join", - "description": "how several triggers make one run: {mode: any} (each on its own)" + "title": "Cost Usd" }, - "if": { + "tokens": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "type": "integer" }, { "type": "null" } ], - "title": "If", - "description": "a match tree over the run context, tested before the Then runs, like {all: [{path, op, value}]}" + "title": "Tokens" }, - "workflow": { - "type": "integer", - "title": "Workflow", - "description": "its workflow (scope event)" + "cost_estimate": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Cost Estimate", + "description": "true when some calls had no price, so the cost is a floor" }, - "version": { + "error": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Version", - "description": "the workflow version it runs; none follows the published one" + "title": "Error" }, - "runs_version": { + "why": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Runs Version", - "description": "the version it runs now" + "title": "Why", + "description": "why it was held" }, - "graph": { + "hold": { "anyOf": [ { "additionalProperties": true, @@ -32170,69 +33421,78 @@ "type": "null" } ], - "title": "Graph", - "description": "the Then: a workflow graph of scope event (an input node, then action nodes and the flow primitives)" - }, - "policy": { - "additionalProperties": { - "type": "string", - "enum": [ - "ask", - "auto" - ] - }, - "type": "object", - "title": "Policy", - "description": "{action node id: ask or auto}" - }, - "limits": { - "additionalProperties": true, - "type": "object", - "title": "Limits", - "description": "{cooldown (like 10m), max_per_hour}" - }, - "counters": { - "additionalProperties": { - "type": "integer" - }, - "type": "object", - "title": "Counters", - "description": "{runs, skipped (its If was false), limited (over a limit), missed}" + "title": "Hold", + "description": "a held run: the budget it is over and how many runs it missed" }, - "last_run_at": { + "cause_depth": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Last Run At" + "title": "Cause Depth", + "description": "how many automations' runs led to this one" }, - "last_status": { + "space": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Last Status" + "title": "Space" }, - "created_by": { + "dry": { "anyOf": [ { - "type": "string" + "type": "boolean" }, { "type": "null" } ], - "title": "Created By" + "title": "Dry" }, - "created_at": { + "trace": { + "additionalProperties": true, + "type": "object", + "title": "Trace", + "description": "by node id: what each node took in and passed on" + }, + "log": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Log" + }, + "intents": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array", + "title": "Intents", + "description": "what its actions did, asked or wait to do: action, params, effect, risk, status, result" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "automation", + "status" + ], + "title": "AutomationRunDetail" + }, + "AutomationRunNow": { + "properties": { + "activity": { "anyOf": [ { "type": "string" @@ -32241,9 +33501,10 @@ "type": "null" } ], - "title": "Created At" + "title": "Activity", + "description": "an activity's id to run it on (GET /api/v1/activities)" }, - "updated_at": { + "as": { "anyOf": [ { "type": "string" @@ -32252,262 +33513,244 @@ "type": "null" } ], - "title": "Updated At" + "title": "As", + "description": "which trigger it runs as (its `as`); default: the first that fits" + } + }, + "additionalProperties": false, + "type": "object", + "title": "AutomationRunNow" + }, + "AutomationRuns": { + "properties": { + "runs": { + "items": { + "$ref": "#/components/schemas/AutomationRun" + }, + "type": "array", + "title": "Runs" }, - "removed_at": { + "next": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Removed At", - "description": "when it was deleted (restore brings it back)" + "title": "Next", + "description": "for the page after: pass it as `before`" } }, "additionalProperties": true, "type": "object", "required": [ - "id", - "name", - "enabled", - "run_as", - "triggers", - "join", - "workflow", - "limits", - "counters" + "runs" ], - "title": "Automation" + "title": "AutomationRuns" }, - "AutomationCatalog": { + "AutomationSaved": { "properties": { - "automations": { + "id": { + "type": "integer", + "title": "Id" + }, + "hooks": { "items": { - "$ref": "#/components/schemas/Automation" + "additionalProperties": { + "type": "string" + }, + "type": "object" }, "type": "array", - "title": "Automations" + "title": "Hooks", + "description": "new webhook triggers' addresses and signing secrets {as, url, secret}, shown this once" } }, "additionalProperties": true, "type": "object", "required": [ - "automations" + "id" ], - "title": "AutomationCatalog" + "title": "AutomationSaved" }, - "AutomationCreate": { + "AutomationStarted": { "properties": { - "name": { - "type": "string", - "title": "Name" - }, - "description": { + "run": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Description" - }, - "enabled": { - "type": "boolean", - "title": "Enabled", - "description": "switched on, it reacts to what happens from now on", - "default": true + "title": "Run", + "description": "the run's id (GET /automations/runs/{run}); none when nothing ran" }, - "spaces": { + "status": { "anyOf": [ { - "items": { - "type": "integer" - }, - "type": "array" + "type": "string" }, { "type": "null" } ], - "title": "Spaces", - "description": "namespace ids you can edit; default: each one you can edit (every one, for admins)" - }, - "triggers": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "type": "array", - "title": "Triggers", - "description": "each {as, on, ...}: {as, on: event, kinds, where?, from_automations?}, {as, on: manual}; on schedule, at, relative and webhook are coming soon (docs/automations.md, Triggers)" + "title": "Status" }, - "join": { + "why": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "Join", - "description": "default {mode: any}: each trigger starts a run of its own" - }, - "if": { + "title": "Why", + "description": "why it didn't run, or was held" + } + }, + "additionalProperties": true, + "type": "object", + "title": "AutomationStarted" + }, + "AutomationSwitch": { + "properties": { + "on": { + "type": "boolean", + "title": "On", + "default": true + } + }, + "additionalProperties": false, + "type": "object", + "title": "AutomationSwitch" + }, + "AutomationTried": { + "properties": { + "status": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "If", - "description": "a match tree over the run context, tested before the Then runs, like {all: [{path, op, value}]}" + "title": "Status", + "description": "done, waiting, partly or failed as it would end; skipped when its If is false (limits and budgets aren't checked: a try costs no run)" }, - "graph": { + "why": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "Graph", - "description": "the Then: a workflow graph of scope event (an input node, then action nodes and the flow primitives); or name a saved one in workflow" + "title": "Why" }, - "workflow": { + "trace": { + "additionalProperties": true, + "type": "object", + "title": "Trace" + }, + "log": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Log" + }, + "intents": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array", + "title": "Intents", + "description": "what each action would do (nothing is done)" + }, + "error": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Workflow", - "description": "a saved workflow of scope event, instead of a graph" + "title": "Error" }, - "version": { + "steps": { + "type": "integer", + "title": "Steps", + "default": 0 + } + }, + "additionalProperties": true, + "type": "object", + "title": "AutomationTried" + }, + "AutomationTry": { + "properties": { + "activity": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Version", - "description": "with workflow: the version to run; none follows the published one" + "title": "Activity", + "description": "an activity's id to run it on (GET /api/v1/activities)" }, - "policy": { + "as": { "anyOf": [ { - "additionalProperties": { - "type": "string", - "const": "ask" - }, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "Policy", - "description": "{action node id: ask}; only you, signed in, let a node run on its own (POST /automations/{id}/policy)" + "title": "As", + "description": "which trigger it runs as (its `as`); default: the first that fits" }, - "limits": { + "kind": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "Limits", - "description": "{cooldown: 0s, max_per_hour: 60}" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "name", - "triggers" - ], - "title": "AutomationCreate" - }, - "AutomationPolicy": { - "properties": { - "node": { - "type": "string", - "title": "Node", - "description": "an action node's id" - }, - "value": { - "type": "string", - "enum": [ - "ask", - "auto" - ], - "title": "Value", - "description": "ask: it asks you first; auto: it runs on its own" + "title": "Kind", + "description": "else a kind of activity, to run it on that kind's sample" } }, "additionalProperties": false, "type": "object", - "required": [ - "node", - "value" - ], - "title": "AutomationPolicy" + "title": "AutomationTry" }, - "AutomationSaved": { + "AutomationUpcoming": { "properties": { - "id": { - "type": "integer", - "title": "Id" - }, - "hooks": { - "items": { - "additionalProperties": { - "type": "string" - }, - "type": "object" - }, + "times": { + "items": {}, "type": "array", - "title": "Hooks", - "description": "new webhook triggers' addresses and signing secrets {as, url, secret}, shown this once" + "title": "Times", + "description": "when it runs next, from its schedules and timers (coming soon)" } }, "additionalProperties": true, "type": "object", - "required": [ - "id" - ], - "title": "AutomationSaved" - }, - "AutomationSwitch": { - "properties": { - "on": { - "type": "boolean", - "title": "On", - "default": true - } - }, - "additionalProperties": false, - "type": "object", - "title": "AutomationSwitch" + "title": "AutomationUpcoming" }, "AutomationUpdate": { "properties": { diff --git a/threat-model.json b/threat-model.json index bd35eea72..b2f8ae08a 100644 --- a/threat-model.json +++ b/threat-model.json @@ -118,7 +118,8 @@ "chat, /graph/ask, MCP tools", "extensions (prompt, graph and http tools, hooks), custom nodes including template nodes", "Python code tools, shipped and admin-created templates, workflows, pipelines, routines", - "Lens extension side panel" + "Lens extension side panel", + "automations" ], "touches": [ "network", @@ -579,6 +580,15 @@ "provenance": "documented", "source": "docs/mcp.md \"curate entities and topics as an editor does\"" }, + { + "entry_point": "automations", + "parameter": "/api/v1/automations (save, try, run now, decide): triggers, where and If match trees, the event workflow graph (action params are Jinja templates), policy, limits, an activity id; the text of the activities an automation runs on", + "attacker_controllable": "yes", + "component": "assistant", + "caller_must_enforce": "none — it runs as its maker with their permissions at run time (P-AUTOMATION-ACTOR); actions reaching outside Lens ask first; outside text marks intents untrusted and breaks up links (P-INJECTION-EGRESS); chains and bursts are bounded (P-AUTOMATION-LOOP)", + "provenance": "documented", + "source": "docs/automations.md \"Running automations\"" + }, { "entry_point": "microsandbox program requests", "parameter": "ask/NAME.want in /data/.lens/programs: a program's name", @@ -1221,6 +1231,22 @@ "provenance": "documented", "source": "domain/flow.py docstring \"Graphs never loop back\"" }, + { + "property": "P-AUTOMATION-ACTOR", + "violation_symptom": "integrity-bypass", + "severity_tier": "security", + "conditions": "an automation acts only for its maker (run_as), with their permissions when it runs, in namespaces they edit, on activities they may see published after it was switched on; a maker who lost access fails its next run and switches it off; actions reaching outside Lens or other people ask first unless the person, signed in to the web app, set the node to auto (API keys, apps, agents and drafts cannot)", + "provenance": "documented", + "source": "docs/automations.md \"Running automations\"" + }, + { + "property": "P-AUTOMATION-LOOP", + "violation_symptom": "x-cap-exceeded", + "severity_tier": "correctness", + "conditions": "activities an automation made start another only with from_automations; a chain stops at automations.max_depth runs (3); each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all (60); a run over a limit does nothing, is counted and logged at most hourly", + "provenance": "documented", + "source": "docs/automations.md \"Running automations\"" + }, { "property": "P-BROWSER", "violation_symptom": "integrity-bypass", diff --git a/threat-model.md b/threat-model.md index 201beb8d0..d6e985692 100644 --- a/threat-model.md +++ b/threat-model.md @@ -305,6 +305,7 @@ classified by gate only *(inferred, Q8)*; unread modules are listed in Q34. | `.lens-control/inbox/upgrade` (host upgrade agent), `/metrics`, `.lens-control/prometheus-token` | `ref` (release tag or this install's branch; empty: the version running), with `https=`, `public=` (`0`/`1`) and `target=` (`full`/`lean`); `action=services` with `monitoring=on`/`off`; the scrape token | the inbox is writable by the containers (and local users); `/metrics` by anyone reaching the web app | x-env-config, credential | the agent installs only a release tag or the install's branch, changes only the HTTPS ports, the web app's network reach and the edition (any other value is dropped) and only toggles the `monitoring` profile, nothing else from the file, so a writer of the inbox can at most restart Lens with those choices or open it to the network; `/metrics` answers only the scrape token (constant-time compare); the token file is world-readable on the host and grants metrics only, which carry no personal content | *(documented, docs/updates.md, docs/prometheus.md "Privacy")* | | `PUT /api/v1/admin/install`, `POST /api/v1/settings/https/ports`, MCP `set_install_settings` | `public`, `target`, `open` | admin only (MCP: with the write scope) | x-env-config | admin is trusted; audited (`lens.install`, `https.ports`); the change reaches the machine only as an inbox request, which the agent checks again | *(documented, docs/updates.md "Setting the machine up again")* | | MCP `edit_entity`, `edit_topic`, `merge_topics`, `delete_topic`, `undo_topic_change`, `undo_graph_change`; assistant `propose_topic_change` | entity and topic ids, names, labels, definitions | yes, an agent with an editor's write-scope token; indirectly through content the model reads | data, x-prompt-injection | the curate permission in each namespace touched and a write-capable principal (the same route functions as the web app); the assistant's changes wait for the person's approval; merges and deletes are kept to undo, and audited | *(documented, docs/mcp.md "curate entities and topics as an editor does")* | +| `/api/v1/automations` (save, try, run now, decide); the activities an automation runs on | triggers, `where` and If match trees, the event workflow graph (action params are Jinja templates), `policy`, `limits`, an activity id; the text of the activities themselves | yes: any editor, for automations in namespaces they edit; indirectly through activity text (mail, titles, chat) that reaches action params | callback/code (declarative), data, x-prompt-injection | none; it runs as its maker with their permissions at run time (P-AUTOMATION-ACTOR), actions reaching outside Lens ask first, outside text marks intents untrusted and breaks up links (P-INJECTION-EGRESS), and chains and bursts are bounded (P-AUTOMATION-LOOP) | *(documented, docs/automations.md "Running automations")* | | `ask/NAME.want` in a microsandbox's `/data/.lens/programs` (LibreOffice and Chromium on first use) | a program's name | writable by the Lens user inside the sandbox | x-env-config | the start script, as root, installs only `libreoffice` or `chromium`, each a fixed list of signed Debian packages, and answers in `got/`, which only root writes; it reads nothing from the file but its name, and only deletes any other name or link | *(documented, docs/microsandbox.md "LibreOffice and Chromium")* | **Stateful postconditions.** A refused or failed one-time secret check consumes nothing; a used one is deleted before @@ -539,6 +540,8 @@ Paths in the Voided by column are relative to `fastapi_backend/app/`. Searches c | P-NOTIFY | Each notification event is claimed once across processes and retried with backoff. | wrong-output | correctness-only | *(documented, docs/notifications.md "claimed once")* | Voided by: none identified (not required for this symptom; no exhaustive search) | | P-HIERARCHY | Collections nest at most 8 deep, without cycles, 5000 per namespace. | bad-data-accepted | correctness-only | *(documented, docs/api.md "at most 8 deep")* | Voided by: Checks only in `_check_parent` — `domain/hierarchy.py:132`, `:142-143`. `grep -rln '"parent"\]' fastapi_backend/app/domain` — only `domain/hierarchy.py` writes it (Q34 covers unread movers). | | P-FLOW | Flow and tool graphs never loop back and run within a step budget. | hang | correctness-only | *(documented, domain/flow.py docstring "Graphs never loop back")* | Voided by: none identified (not required for this symptom; no exhaustive search) | +| P-AUTOMATION-ACTOR | An automation acts only for the person who made it (`run_as`), with that person's permissions as they are when it runs, in namespaces they can edit: it reacts only to activities that person may see in those namespaces, published after it was last switched on. If the person loses their account, their admin role (for one that works everywhere) or the right to edit one of its namespaces, its next run fails saying so and it is switched off. Actions that reach outside Lens or other people, or change something in Lens other than the event's own object, ask the person first unless the person, signed in to the web app, set that node to run on its own; API keys, apps, agents and drafts cannot. | integrity-bypass | security-critical | *(documented, docs/automations.md "Running automations")* | Voided by: an admin manages every automation and can run one now on any activity in its namespaces that its person may see — `api/v1/routes/automations.py`; a node the person set to `auto` acts on outside text without asking (P-INJECTION-EGRESS still applies). | +| P-AUTOMATION-LOOP | Automations cannot set each other off without end: activities an automation made start another only when its trigger says `from_automations`, a chain stops at `automations.max_depth` runs (3), and each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all of them (60). A run over a limit does nothing, is counted, and is logged at most once an hour. | x-cap-exceeded | correctness-only | *(documented, docs/automations.md "Running automations")* | Voided by: limits count in fixed hours and minutes, so up to twice a limit can run across the turn of one; an admin can raise `max_depth` to 10 and `max_runs_per_minute` to 6000 (Settings → Automations). | | P-BROWSER | The assistant uses a person's browser only from that person's own conversations and API calls, while their own Lens side panel is connected (seen in the last 20 seconds, not closed). Only that person sees the session's actions and answers them, once each. `ai.browser` off refuses new sessions and offers no browser tools. | integrity-bypass | security-critical | *(documented, docs/browser-assistant.md "Only you")* | Voided by: The side panel carries out what it's asked: which sites it acts on, and what it asks the person first, is the extension's (docs/browser-assistant.md); an agent holding the person's write token can ask too — `api/v1/routes/browser.py`. | | P-BROWSER-GUARD | The Lens extension's side panel reads and acts only on sites the person allowed in it (and the browser granted), and opens an address only on such a site. It asks the person before a click, submit or Enter that the model marks consequential or whose control's words or posting form look so, and, once the answer has read text from outside Lens (`ai.untrusted_asks`), before opening or downloading an address or typing text the person's own message doesn't contain. It never types into password, card or file fields, never reports their values, and shows each action as it happens. | integrity-bypass | security-critical | *(documented, docs/browser-assistant.md "Letting it use your browser")* | Voided by: The consequential check is the model's flag plus a word list (`extensions/browser/src/core/act.js`): a control with no telling words that a misled model doesn't mark runs without asking; synthetic events reach only the page's own handlers. Removing a site from the options stops the side panel acting there, but leaves the browser's access to it for the clipper. Lens sends the ask (`confirm`) and the extension honours it: an extension older than this doesn't ask. | diff --git a/threat-model.yaml b/threat-model.yaml index 003f22ef3..751e8b18b 100644 --- a/threat-model.yaml +++ b/threat-model.yaml @@ -2,7 +2,7 @@ # Authority order: prose > yaml > json. Regenerate whenever the prose changes. schema: threat-model-sidecar/v2 project: lens -prose_version: "threat-model.md@sha256:49093c03f4301d948103da23445851585e4b6b88d299a048558e1195df560aa8" +prose_version: "threat-model.md@sha256:e22b2868ef9a7b23de3a120f94f97f1723f395751605532b7e86e4f0172a46d4" model_status: under-review triage_policy: strict confidence: {documented: 201, maintainer: 46, inferred: 91, assumption: 8} @@ -523,6 +523,15 @@ entry_points: control_kinds: [data, x-prompt-injection] caller_must_enforce: "none — the curate permission in each namespace touched and a write-capable principal (the web app's own route functions); the assistant's changes wait for the person's approval; merges and deletes are kept to undo, and audited" provenance: {kind: documented, source: 'docs/mcp.md "curate entities and topics as an editor does"'} + - id: "automations" + component: assistant + parameters: + - name: "/api/v1/automations (save, try, run now, decide): triggers, where and If match trees, the event workflow graph (action params are Jinja templates), policy, limits, an activity id; the text of the activities an automation runs on" + attacker_controllable: true + x-condition: "any editor, for automations in namespaces they edit; indirectly through activity text (mail, titles, chat) that reaches action params" + control_kinds: [callback/code, data, x-prompt-injection] + caller_must_enforce: "none — it runs as its maker with their permissions at run time (P-AUTOMATION-ACTOR); actions reaching outside Lens ask first; outside text marks intents untrusted and breaks up links (P-INJECTION-EGRESS); chains and bursts are bounded (P-AUTOMATION-LOOP)" + provenance: {kind: documented, source: 'docs/automations.md "Running automations"'} - id: "microsandbox program requests" component: authz parameters: @@ -1655,6 +1664,22 @@ properties_claimed: violation_symptoms: [hang] x-voided-by: "none identified (not required for this symptom; no exhaustive search)" provenance: {kind: documented, source: 'domain/flow.py docstring "Graphs never loop back"'} + - id: P-AUTOMATION-ACTOR + kind: integrity + components: [assistant, authz] + tier: security-critical + conditions: "an automation acts only for its maker (run_as), with their permissions when it runs, in namespaces they edit, on activities they may see published after it was switched on; a maker who lost access fails its next run and switches it off; actions reaching outside Lens or other people ask first unless the person, signed in to the web app, set the node to auto (API keys, apps, agents and drafts cannot)" + violation_symptoms: [integrity-bypass] + x-voided-by: "an admin manages every automation and can run one now on any activity in its namespaces its person may see (api/v1/routes/automations.py); a node set to auto acts on outside text without asking (P-INJECTION-EGRESS still applies)" + provenance: {kind: documented, source: 'docs/automations.md "Running automations"'} + - id: P-AUTOMATION-LOOP + kind: correctness + components: [assistant] + tier: correctness-only + conditions: "activities an automation made start another only with from_automations; a chain stops at automations.max_depth runs (3); each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all (60); a run over a limit does nothing, is counted and logged at most hourly" + violation_symptoms: [x-cap-exceeded] + x-voided-by: "fixed hour and minute windows let up to twice a limit run across the turn of one; an admin can raise max_depth to 10 and max_runs_per_minute to 6000" + provenance: {kind: documented, source: 'docs/automations.md "Running automations"'} - id: P-BROWSER kind: integrity components: [assistant]