From 5b9f4b79d6e09eb58b9aa0a520bd06b20a011358 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Fri, 16 Oct 2026 00:00:46 +0000 Subject: [PATCH 1/2] feat(automations): an automation's action that asks first waits as an approval approvals.ask keeps an intent that asks first as an approval of the automation's person, tells them once in their chat app, caps 100 waiting per automation and expires undecided ones after automations.approval_days (Settings > Automations, default 7) with nothing run. Approving performs the intent as the automation; decline, edit (params checked against the action's schema) and always (the node runs on its own from now on) are the other picks. Only the person approves, signed in: an API key or an app can list and decline. GET /api/v1/approvals gains filters and paging, with /approvals/count and /approvals/{aid}. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01VF3LK1DBx3dXX2b8c5T3cQ --- docs/api.md | 10 + docs/automations.md | 54 +- docs/configuration.md | 4 +- fastapi_backend/app/api/v1/routes/chats.py | 77 ++- fastapi_backend/app/domain/ai_tools.py | 15 +- fastapi_backend/app/domain/approvals.py | 409 ++++++++++++ fastapi_backend/app/domain/ops_tools.py | 1 + fastapi_backend/app/domain/routines.py | 7 + fastapi_backend/app/domain/settings.py | 14 + fastapi_backend/app/domain/store.py | 7 + fastapi_backend/app/schemas/chats.py | 74 ++- fastapi_backend/tests/api/test_approvals.py | 326 ++++++++++ .../__tests__/settings-find.test.tsx | 6 +- nextjs-frontend/app/openapi-client/index.ts | 14 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 42 +- .../app/openapi-client/types.gen.ts | 299 ++++++++- .../components/settings/bodies.tsx | 1 + nextjs-frontend/components/settings/model.ts | 13 +- nextjs-frontend/openapi.json | 597 +++++++++++++++++- threat-model.md | 1 + 20 files changed, 1939 insertions(+), 32 deletions(-) create mode 100644 fastapi_backend/app/domain/approvals.py create mode 100644 fastapi_backend/tests/api/test_approvals.py diff --git a/docs/api.md b/docs/api.md index 9dd651a6b..bd8958605 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1357,9 +1357,19 @@ POST /api/v1/chats/{cid}/messages POST /api/v1/chats/{cid}/stop POST /api/v1/chats/{cid}/messages/{mid}/check GET /api/v1/approvals +GET /api/v1/approvals/count +GET /api/v1/approvals/{aid} POST /api/v1/approvals/{aid} ``` +`GET /approvals` lists what waits for your pick and what became of it, newest first: the assistant's proposals and +automations' actions ([Approvals](automations.md#approvals)); filter by `status`, `origin` (`automation` or `chat`), +`automation` or `chat_id`, and page with `before` (the last id of the page before) and `limit`. `/approvals/count` +gives `{waiting, automations}`. `POST /approvals/{aid} {decision, params?}` decides one: `approve`, `sample` (a batch +run on 3 assets first), `decline`, `edit` (an automation's action with `params` changed) or `always` (approved, and +that node runs without asking from now on). Approving, editing and `always` on an automation's action need a signed-in +session (403 for an API key or an app); each approval's `can` says what you may do with it. + `GET /chats/capabilities` tells anyone signed in whether a language model is set up (`configured`), which (`model`), whether it uses tools (`tools`, `max_steps`), whether answers can be checked (`check`) and the `models` people may pick (the configured one first; `llm.chat_models`, else the server's list); never the model server's address or key. A diff --git a/docs/automations.md b/docs/automations.md index 75cfbc92b..b2b37b468 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -27,7 +27,9 @@ merged is called built. | Changing assets and writing notes: the `set_field`, `add_to_collection` and `write_note` actions | built | | Settings → Automations: how often followers look and how long the event log is kept | built | | The Timeline page with filters, grouping, review keys and new items, and Home's Latest card ([Timeline](timeline.md)) | built | -| Storing and running automations, schedules and timers, joins, approvals, variables, the studio | planned | +| Approvals: an automation's action that asks first waits for your pick (approve, decline, edit, allow from now on), told once in your chat app, capped and expiring (`app/domain/approvals.py`) | built | +| The Approvals page and its badge, a yes in your chat app, approval activities and notifications, agents' approval tools | planned | +| Storing and running automations, schedules and timers, joins, variables, the studio | planned | ## Contract @@ -413,6 +415,53 @@ everyone who reads the asset sees. Calendar events aren't written: Lens signs in to Google Calendar read-only, and writing needs a new consent. Meanwhile the agent can draft an event as a note. +## Approvals + +Built: everything that waits for your pick is an approval in one table (`app/domain/approvals.py`): the assistant's +proposals in a conversation, as before, and an automation's actions that ask first. When an action node's intent asks +(its effect is `out`, or `lens` on anything but the event's own object), the engine hands it to +`approvals.ask(db, cfg, intent, event=None)`, which keeps: + +| Field | | +| --- | --- | +| `origin` | `{automation, run, node}`: the run that asked (null for the assistant's own approvals) | +| `intent` | the intent, with the params as the run filled them in | +| `summary`, `automation`, `why` | what it would do (the action's `describe`), the automation's name, and the activity that caused it (`{activity, kind, summary, published, url}`) | +| `account`, `space` | the automation's person, whose pick it is, and the namespace it is about | +| `expires_at` | when it expires: `automations.approval_days` (7) after it asked | +| `told` | the chats you were told in | +| `status` | `pending` (waiting), `running`, `done`, `failed`, `declined` or `expired`; `decided_by`, `decided_at`, `result`, `error` | + +You are told once, in your own chat app when one is linked ([Telling a person](#telling-a-person)): "School emails +wants to post in the Matterbridge gateway family: “Trip on Friday”. Open to decide." The link opens the approval +in Lens. Handing the same intent over again gives the same approval. At most 100 wait for one automation: past that its +intents are dropped, and the run says so, so a flood of activities can't bury your inbox or your chat. + +Deciding (`POST /api/v1/approvals/{aid}`): + +- `approve` carries the intent out through `actions.perform`, for its person and as the automation (what it writes is + by `automation:`, model calls count in the activity ledger under the run, and what it causes carries the run as + its cause). Its outcome, `done` with what it gave back or `failed` with why, goes on the approval and on the run. +- `decline` does nothing, and the run says it was declined. +- `edit` with `params` changes them first (a param given as null is left out), checked against the action's schema; + what the run filled in from a template stays as it is now. A credential header shows as `••••`, and given back as + `••••` it keeps its sealed value. +- `always` approves it, then lets that action node run without asking from now on (the automation's policy, `auto`). + Only an action that reaches outside Lens or other people asks each time, so only those can be allowed. + +Approving, editing and `always` are yours: signed in to Lens, on the approval's card. An API key, an app, MCP and the +assistant can list and decline approvals, never approve them, since approving is the person's pick; each approval's +`can` says what the caller may do with it. This is the one place where an agent can't do what you can. The +assistant's own approvals in a conversation are decided as before. + +Undecided approvals expire after `automations.approval_days` (Settings → Automations, 1–365, default 7): a sweep +called from the scheduler once an hour marks them `expired`, nothing runs, and the run says so. The assistant's own +approvals don't expire. + +The inbox reads `GET /api/v1/approvals` (newest first; `status`, `origin=automation|chat`, `automation`, `chat_id`, +and `before` with `limit` to page), `GET /api/v1/approvals/{aid}` and `GET /api/v1/approvals/count` (`{waiting, +automations}`, for a badge). + ## Refine later - More operators: `in`, `matches` (bounded regular expressions), `between`, times against now, `changed`. @@ -454,3 +503,6 @@ the agent can draft an event as a note. - Changing assets: asking first instead of failing when a move would show an asset to new people (risk that reads the database); fields on collections and files; tags; roles on collections counting for `edit`. - Writing calendar events (a new Google consent, so it changes existing installs). +- Approvals: a cost estimate on actions that ask (a run on another asset could say what it would cost); buttons in + Telegram and Slack; approvals that need two people; one card for many alike ("approve all 12"); trying a failed one + again; expiring an automation's approvals when it is removed. diff --git a/docs/configuration.md b/docs/configuration.md index 50e1ab71f..898d6a47f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -463,12 +463,14 @@ Where namespaces may send notifications ([Notifications](notifications.md)). Set ## Automations -The stream of activities automations follow ([Automations](automations.md#contract)). Settings → Automations: +The stream of activities automations follow ([Automations](automations.md#contract)) and how long their +[approvals](automations.md#approvals) wait. Settings → Automations: | Setting | Default | | |---|---|---| | `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 | ## Trusted proxies diff --git a/fastapi_backend/app/api/v1/routes/chats.py b/fastapi_backend/app/api/v1/routes/chats.py index 9207483cf..aadedbd19 100644 --- a/fastapi_backend/app/api/v1/routes/chats.py +++ b/fastapi_backend/app/api/v1/routes/chats.py @@ -10,20 +10,21 @@ import json import logging from collections.abc import Iterator -from typing import Any +from typing import Any, Literal -from fastapi import APIRouter, HTTPException, Request +from fastapi import APIRouter, HTTPException, Query, Request from fastapi.responses import StreamingResponse from starlette.concurrency import run_in_threadpool from app.api.deps import Access, Acl, Cfg, CurrentUser, Db, Principal, Writer from app.api.media import sign_urls from app.api.v1.routes.collections import own_collection -from app.domain import ai_tools, auth, auto_scope, browser, chat, llm, store, uploads +from app.domain import ai_tools, approvals, auth, auto_scope, browser, chat, llm, store, uploads from app.domain.store import DB from app.schemas.chats import ( AnswerCheck, Approval, + ApprovalCount, ApprovalDecision, ApprovalOutcome, Chat, @@ -397,29 +398,75 @@ def check_message(cid: int, mid: int, user: Writer, db: Db, cfg: Cfg) -> AnswerC return out +def _via(user: Principal) -> str: + """Where a pick is made: web for a signed-in session, else token (an API key) or oauth (an app).""" + return "web" if user.via == "access" else user.via + + +def approval_view(a: dict, via: str = "web") -> Any: + """An approval as the API shows it: an automation's intent with credentials hidden, and what `via` can do.""" + return {**a, "intent": approvals.shown(a.get("intent")), "told": a.get("told") or [], "can": approvals.can(a, via)} + + @router.get("/approvals") -def list_approvals(user: CurrentUser, db: Db, chat_id: int | None = None) -> list[Approval]: - """Work the assistant proposed for you to approve (and what became of it), newest first.""" - return db.rows( - "SELECT record::id(id) AS id, chat, tool, summary, estimate, status, created_at, result FROM approval WHERE account = $a" - + (" AND chat = $c" if chat_id else "") - + " ORDER BY created_at DESC LIMIT 100", - a=user.id, - c=chat_id, - ) +def list_approvals( + user: CurrentUser, + db: Db, + chat_id: int | None = None, + status: Literal["pending", "running", "done", "failed", "declined", "expired"] | None = None, + origin: Literal["automation", "chat"] | None = None, + automation: int | None = None, + before: int | None = Query(default=None, description="ids below this one: the last id of the page before"), + limit: int = Query(default=100, ge=1, le=200), +) -> list[Approval]: + """What waits for your pick (and what became of it), newest first: the assistant's proposals and automations' + actions. Filter by `status` (pending is waiting), `origin` (automation or chat), one `automation` or one chat + (`chat_id`); page with `before`.""" + rows = approvals.listing(db, user.id, status, origin, automation, chat_id, before, limit) + return [approval_view(a, _via(user)) for a in rows] + + +@router.get("/approvals/count") +def count_approvals(user: CurrentUser, db: Db) -> ApprovalCount: + """How many approvals wait for you, for the badge in the top bar.""" + return approvals.count(db, user.id) + + +@router.get("/approvals/{aid}") +def get_approval(aid: int, user: CurrentUser, db: Db) -> Approval: + """One of your approvals.""" + a = approvals.get(db, aid) + if not a or a["account"] != user.id: + raise HTTPException(404, "not found") + return approval_view(a, _via(user)) @router.post("/approvals/{aid}") def decide_approval(aid: int, body: ApprovalDecision, user: Writer, acl: Acl, db: Db, cfg: Cfg, request: Request) -> ApprovalOutcome: - """Approve (or run a sample of, or decline) something the assistant proposed. Each approval is decided once.""" + """Approve (or run a sample of, or decline) something the assistant proposed or an automation's action. Each + approval is decided once. An automation's action can also be edited (`params`) and then carried out, or allowed + from now on for that automation (`always`); approving one needs you signed in, since it's your pick: an API key + or an app can only decline it.""" a = db.one("SELECT account FROM $r", r=R("approval", aid)) if not a or a["account"] != user.id: raise HTTPException(404, "not found") try: out = ai_tools.approve( - db, cfg, aid, user.as_audit(), set(acl.editable()), body.decision, request.app.state.archive.base, user.admin, set(acl.roles) + db, + cfg, + aid, + user.as_audit(), + set(acl.editable()), + body.decision, + request.app.state.archive.base, + user.admin, + set(acl.roles), + params=body.params, + via=_via(user), ) - except (ValueError, PermissionError, KeyError) as e: + except PermissionError as e: + raise HTTPException(403, str(e)) from None + except (ValueError, KeyError) as e: raise HTTPException(400, str(e)) from None auth.audit(db, user.as_audit(), "assistant.approval", f"approval:{aid}", {"decision": body.decision, **out}) request.app.state.graph_cache.clear() # an approved entity or topic change shows in the graph at once diff --git a/fastapi_backend/app/domain/ai_tools.py b/fastapi_backend/app/domain/ai_tools.py index 5c907186d..24d1a5173 100644 --- a/fastapi_backend/app/domain/ai_tools.py +++ b/fastapi_backend/app/domain/ai_tools.py @@ -1436,12 +1436,21 @@ def cited(self, text): return [{**r, "used": r["n"] in used} for r in self.refs if r["n"] in used] -def approve(db, cfg, aid, user, editable, decision="approve", base=None, admin=False, readable=None): +def approve(db, cfg, aid, user, editable, decision="approve", base=None, admin=False, readable=None, params=None, via="web"): """Carry out an approved action: a batch run (or a sample of it), an entity change, a note an automation's agent - proposed, or a change to the server (ops_tools.py: settings, a namespace, importing attached files or web pages).""" - a = db.one("SELECT record::id(id) AS id, chat, account, tool, args, status FROM $r", r=R("approval", int(aid))) + proposed, or a change to the server (ops_tools.py: settings, a namespace, importing attached files or web pages). + An automation's action (an approval with an intent) is decided by approvals.decide: `params` are an edit's, `via` + where the pick was made (web, chat, token, oauth or agent; only the person, signed in or in their own chat, + approves it).""" + from . import approvals # it carries actions out, and actions load the assistant's tools + + a = approvals.get(db, aid) if not a or a["status"] != "pending": raise ValueError("nothing to approve") + if a.get("intent"): + return approvals.decide(db, cfg, a, user, decision, params, via) + if decision in ("edit", "always"): + raise ValueError("only an automation's action can be edited or allowed from now on") if decision == "decline": db.q( "UPDATE $r SET status = 'declined', decided_at = $t, decided_by = $u", r=R("approval", a["id"]), t=store.now(), u=user["email"] diff --git a/fastapi_backend/app/domain/approvals.py b/fastapi_backend/app/domain/approvals.py new file mode 100644 index 000000000..e0b70edf7 --- /dev/null +++ b/fastapi_backend/app/domain/approvals.py @@ -0,0 +1,409 @@ +"""Approvals (docs/automations.md, Approvals): everything that waits for the person's pick, in one table and one inbox. + +The `approval` table holds two kinds, told apart by `origin` and `intent`: + +- the assistant's (`chat` set, `tool` and `args`): a change it proposed in a conversation, or that an automation's + agent proposed while it ran (`origin` set too), carried out by `ai_tools.approve` as they always were; +- an automation's (`origin` {automation, run, node} and `intent`, `tool` "action"): an action node whose intent asks + first, which the engine hands to `ask`. Approving it performs the intent through `actions.perform`, as the + automation and for its person, and records the outcome on the run (`automations.update_intent`). + +An automation's approval is the person's pick: approving it (or editing its params, or allowing that node from now on) +needs them signed in to Lens, or a yes in the chat it was told in (bridge.decide_in_room). An API key, an app, MCP and +the assistant can list and decline approvals, never approve them. Undecided ones expire after +`automations.approval_days` (default 7) and nothing runs; the assistant's own approvals never expire, as before. + +Statuses: pending (waiting), running (being carried out), done, failed, declined, expired. +""" + +from __future__ import annotations + +import datetime as dt +import importlib +import logging +import time + +from . import actions, activity, channels, events, graph_history, store +from . import automation_spec as spec_ +from .store import R + +log = logging.getLogger("lens.automations") +CAP = 100 # waiting approvals per automation; past that its intents are dropped +SWEEP_SECONDS = 3600 +STUCK_SECONDS = 3600 # an approval still running after this was cut short (the server stopped while it ran) +STATUSES = ("pending", "running", "done", "failed", "declined", "expired") +DECISIONS = ("approve", "sample", "decline", "edit", "always") +DROPPED = f"dropped: {CAP} approvals already wait for this automation; decide some in Approvals" +FIELDS = ( + "record::id(id) AS id, chat, account, tool, args, summary, estimate, status, created_at, result, error, origin, " + "intent, space, expires_at, decided_by, decided_at, told, why, automation" +) +_swept = {"at": 0.0} + + +def _studio(fn): + """`fn` of the automations module (update_intent, set_policy) once it is there, else None: until stored + automations land, the approval itself keeps the outcome.""" + try: + mod = importlib.import_module(f"{__package__}.automations") + except ModuleNotFoundError as e: + if e.name != f"{__package__}.automations": + raise + return None + return getattr(mod, fn, None) + + +def days(cfg): + return int((cfg.get("automations") or {}).get("approval_days") or 7) + + +def _iso(t): + return t.astimezone(dt.timezone.utc).isoformat(timespec="seconds") + + +def _record(db, intent, status, result=None): + """The intent's outcome on its run (M6's update_intent), when runs are stored.""" + update = _studio("update_intent") + if update is None or intent.get("run") is None: + return + try: + update(db, intent["run"], intent["key"], status, result) + except Exception: # noqa: BLE001 - the approval keeps the outcome either way + log.warning("automation run %s: couldn't record %s as %s", intent.get("run"), intent.get("key"), status, exc_info=True) + + +def waiting(db, automation): + """How many approvals wait for one automation.""" + row = db.one("SELECT count() AS n FROM approval WHERE origin.automation = $a AND status = 'pending' GROUP ALL", a=int(automation)) + return int((row or {}).get("n") or 0) + + +def _event_of(db, cfg, intent): + """The activity that fired the intent's run: the last of the run's events, when runs are stored.""" + 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 [] + except Exception: # noqa: BLE001 - runs aren't stored yet + return None + if not ids: + return None + last = ids[-1] + return events.get(db, cfg, last if isinstance(last, str) else (last or {}).get("id"), events.viewer(admin=True)) + + +def _why(event): + """What the activity that caused it said, kept with the approval (it stays readable if the activity goes).""" + if not isinstance(event, dict) or not event.get("id"): + return None + return store.clean( + { + "activity": event["id"], + "kind": event.get("kind"), + "summary": event.get("summary"), + "published": event.get("published"), + "url": (event.get("object") or {}).get("url"), + } + ) + + +def _space(intent, event): + spaces = intent.get("spaces") or [] + s = (event or {}).get("space") + if s is not None and (not spaces or s in spaces): + return s + return spaces[0] if spaces else None + + +def link(cfg, db, aid): + """Where the person decides: the approval in the inbox, on the address they open the web app at.""" + from app.email import app_url + + return f"{app_url(cfg, db)}/approvals?id={aid}" + + +def message(name, what, url): + """What the person is told when an automation's action waits for them.""" + said = what[:1].lower() + what[1:] if what else "do something" + return f"{name} wants to {said}. Open {url} to decide." + + +def ask(db, cfg, intent, event=None): + """An approval for an intent that asks first (the engine's hand-off): the row, for the automation's person, with + what it would do, the activity that caused it (`event`, else the run's last) and when it expires; then the person + is told once in their own chat app, when they have one linked (channels.tell). Its id; the same id when the intent + was handed over before; None when CAP approvals already wait for the automation (the intent is dropped, said on + the run). ValueError for an intent that doesn't check or acts for nobody.""" + i = spec_.check_intent(intent) + if i["automation"] is None or i["run"] is None: + raise ValueError("only a run of a saved automation asks: a dry run never does") + person = actions.person(db, i) + same = db.one( + "SELECT VALUE record::id(id) FROM approval WHERE origin.automation = $a AND origin.run = $r AND intent.key = $k LIMIT 1", + a=i["automation"], + r=i["run"], + k=i["key"], + ) + if same is not None: + return same + if waiting(db, i["automation"]) >= CAP: + _record(db, i, "failed", {"error": DROPPED}) + log.warning("automation %s: %s", i["automation"], DROPPED) + return None + event = event if event is not None else _event_of(db, cfg, i) + name = actions.actor(db, i)["name"] + what = actions.describe(i["action"], i["params"]) + now = dt.datetime.now(dt.timezone.utc) + aid = db.next_id("approval") + db.q( + "CREATE $r CONTENT $d", + r=R("approval", aid), + d=store.clean( + { + "account": person["id"], + "origin": {"automation": i["automation"], "run": i["run"], "node": i["node"]}, + "tool": "action", + "intent": {**i, "status": "waiting"}, + "automation": name, + "summary": what, + "why": _why(event), + "space": _space(i, event), + "status": "pending", + "created_at": _iso(now), + "expires_at": _iso(now + dt.timedelta(days=days(cfg))), + } + ), + ) + told = tell(db, cfg, person, aid, name, what) + if told: + db.q("UPDATE $r SET told = $t", r=R("approval", aid), t=told) + return aid + + +def tell(db, cfg, person, aid, name, what): + """Tell the person once, in their own chat apps, that something waits: the chats it went to.""" + url = link(cfg, db, aid) + try: + got = channels.tell(db, cfg, person, message(name, what, url), links=(url,)) + except Exception: # noqa: BLE001 - the approval waits in the inbox either way + log.warning("approval %s: couldn't tell %s", aid, person.get("email"), exc_info=True) + return [] + return [store.clean({k: s.get(k) for k in ("channel", "label", "chat", "conversation")}) for s in got.get("sent") or []] + + +# ---------- deciding ---------- +def get(db, aid): + return db.one(f"SELECT {FIELDS} FROM $r", r=R("approval", int(aid))) + + +def _secret_headers(action, params): + if action != "http_request" or not isinstance(params.get("headers"), dict): + return set() + from . import actions_web + + return {k for k in params["headers"] if actions_web.secret(k)} + + +def shown(intent): + """An intent as the inbox shows it: credential headers hidden (actions_web.HIDDEN), as the action describes them.""" + if not isinstance(intent, dict): + return None + params = dict(intent.get("params") or {}) + hide = _secret_headers(intent.get("action"), params) + if hide: + from . import actions_web + + params["headers"] = {k: actions_web.HIDDEN if k in hide else v for k, v in params["headers"].items()} + return {k: intent.get(k) for k in ("action", "effect", "risk", "untrusted", "node", "status", "spaces")} | {"params": params} + + +def edited(intent, new): + """The intent's params with the person's edits on top (a param given as null is left out), checked against the + action's schema. A hidden credential header given back as shown keeps its sealed value. ValueError naming the + problem.""" + if not isinstance(new, dict): + raise ValueError("give the params to change as an object") + spec = actions.get(intent["action"]) + old = dict(intent.get("params") or {}) + params = {k: v for k, v in {**old, **new}.items() if v is not None} + hide = _secret_headers(intent["action"], old) + if hide and isinstance(params.get("headers"), dict): + from . import actions_web + + params["headers"] = {k: old["headers"][k] if k in hide and v == actions_web.HIDDEN else v for k, v in params["headers"].items()} + out = actions.check_params(spec, params) + props = spec.params.get("properties") or {} + for k, v in out.items(): # a template isn't filled in any more: it stands for itself + want = (props.get(k) or {}).get("type") + if want and want != "string" and isinstance(v, str): + raise ValueError(f"{spec.name}: {k} is {'an' if want[0] in 'aeiou' else 'a'} {want}") + return out + + +def can(row, via="web"): + """What the person can do with a waiting approval from where they are (`via`: web for a signed-in session, chat for + their own chat app, token or oauth for an API key or an app, agent for MCP and the assistant).""" + pending = row.get("status") == "pending" + intent = row.get("intent") + if not intent: + return {"approve": pending, "decline": pending, "edit": False, "always": False} + person = via in ("web", "chat") + return { + "approve": pending and person, + "decline": pending, + "edit": pending and via == "web", + "always": pending and via == "web" and intent.get("effect") == "out" and _studio("set_policy") is not None, + } + + +def _take(db, aid, status, user): + """Claim a waiting approval for one decision (two at once can't both carry it out): True when this one won.""" + return bool( + db.rows( + "UPDATE $r SET status = $s, decided_at = $t, decided_by = $u WHERE status = 'pending' RETURN id", + r=R("approval", int(aid)), + s=status, + t=store.now(), + u=user.get("email"), + ) + ) + + +def _depth(db, intent): + try: + d = (db.one("SELECT cause_depth FROM $r", r=R("automation_run", int(intent["run"]))) or {}).get("cause_depth") + except Exception: # noqa: BLE001 - runs aren't stored yet + d = None + return (d if isinstance(d, int) else 0) + 1 + + +def decide(db, cfg, row, user, decision="approve", params=None, via="web"): + """Decide an automation's approval: approve (perform its intent), decline, edit (new params, then perform) or + always (perform, then let that node run on its own from now on). `user` is who decided; the intent acts for its + person, as the automation. {status, result or error}; PermissionError when `via` can't make that pick, ValueError + when it isn't waiting or the edit doesn't check.""" + if decision not in DECISIONS or decision == "sample": + raise ValueError("an automation's action is approved, declined, edited or allowed from now on") + allowed = can(row, via) + if row.get("status") != "pending": + raise ValueError("nothing to approve") + if decision == "decline": + if not _take(db, row["id"], "declined", user): + raise ValueError("nothing to approve") + db.q("UPDATE $r SET intent.status = 'declined'", r=R("approval", row["id"])) + _record(db, row["intent"], "declined") + return {"status": "declined"} + if not allowed[decision]: + if decision == "always" and row["intent"].get("effect") != "out": + raise ValueError("only an action that reaches outside Lens or other people can be allowed from now on") + if decision == "always" and _studio("set_policy") is None: + raise ValueError("allowing an action from now on comes with saved automations: approve it this once") + raise PermissionError( + "approve an automation's action yourself: signed in to Lens, or with a yes in the chat it told you in" + if via not in ("web", "chat") + else "edit or allow an action from now on in Lens, on its card" + ) + intent = dict(row["intent"]) + if decision == "edit": + if params is None: + raise ValueError("give the params to change") + intent["params"] = edited(intent, params) + intent["effect"] = actions.effect_of(actions.get(intent["action"]), intent["params"]) + person = actions.person(db, intent) + if not _take(db, row["id"], "running", user): + raise ValueError("nothing to approve") + result, error = None, None + try: + who = actions.actor(db, intent) + cause = {"automation": intent["automation"], "run": intent["run"], "depth": _depth(db, intent)} + with ( + activity.scope(db, f"automation:{intent['automation']}", f"automation_run:{intent['run']}", cfg=cfg), + events.caused_by(cause), + graph_history.acting(actor=who["email"], via=who["id"], why=f"approved by {user.get('email')}", approval=row["id"]), + ): + result = actions.perform(db, cfg, {**intent, "status": "waiting"}, person) + except Exception as e: # noqa: BLE001 - recorded on the approval and the run + error = f"{type(e).__name__}: {e}"[:500] if not isinstance(e, ValueError) else str(e)[:500] + status = "failed" if error else "done" + db.q( + "UPDATE $r SET status = $s, result = $res, error = $e, intent = $i", + r=R("approval", row["id"]), + s=status, + res=result, + e=error, + i={**intent, "status": status}, + ) + _record(db, intent, status, result if not error else {"error": error}) + out = {"status": status, **({"error": error} if error else {"result": result})} + if decision == "always" and not error: + o = row.get("origin") or {} + try: + _studio("set_policy")(db, o["automation"], o["node"], "auto", user.get("email")) + out["always"] = True + except Exception as e: # noqa: BLE001 - it was carried out; the node keeps asking + out["always"], out["error"] = False, f"carried out, but it will still ask next time: {e}"[:500] + return out + + +# ---------- the inbox ---------- +def listing(db, account, status=None, origin=None, automation=None, chat=None, before=None, limit=50): + """The person's approvals, newest first, `limit` at a time before the id `before`: those with `status`, from + automations or chats (`origin`), from one automation, or asked in one chat.""" + where, v = ["account = $a"], {"a": account, "limit": max(1, min(int(limit or 50), 200))} + if status: + where.append("status = $s") + v["s"] = status + if origin == "automation": + where.append("origin != NONE AND origin != NULL") + elif origin == "chat": + where.append("(origin = NONE OR origin = NULL)") + if automation is not None: + where.append("origin.automation = $au") + v["au"] = int(automation) + if chat is not None: + where.append("chat = $c") + v["c"] = int(chat) + if before is not None: + where.append("id < $b") + v["b"] = R("approval", int(before)) + return db.rows(f"SELECT {FIELDS} FROM approval WHERE {' AND '.join(where)} ORDER BY id DESC LIMIT $limit", **v) + + +def count(db, account): + """How many approvals wait for the person: all of them, and those from automations.""" + rows = db.rows( + "SELECT (origin != NONE AND origin != NULL) AS auto, count() AS n FROM approval " + "WHERE account = $a AND status = 'pending' GROUP BY auto", + a=account, + ) + auto = sum(int(r["n"]) for r in rows if r.get("auto")) + return {"waiting": sum(int(r["n"]) for r in rows), "automations": auto} + + +# ---------- expiry ---------- +def sweep(db, cfg, now=None): + """Automation approvals past their expires_at become expired (nothing runs; the run says so), and one still running + an hour on failed; at most once an hour per process (routines.run_due calls it every 30 seconds). How many expired, + 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 dt.datetime.now(dt.timezone.utc) + gone = db.rows( + "UPDATE approval SET status = 'expired', decided_at = $n, intent.status = 'expired' " + "WHERE status = 'pending' AND expires_at != NONE AND expires_at < $n RETURN record::id(id) AS id, intent", + n=_iso(now), + ) + for a in gone: + if a.get("intent"): + _record(db, a["intent"], "expired") + stuck = db.rows( + "UPDATE approval SET status = 'failed', error = 'the server stopped while it was carried out' " + "WHERE status = 'running' AND decided_at < $c RETURN record::id(id) AS id, intent", + c=_iso(now - dt.timedelta(seconds=STUCK_SECONDS)), + ) + for a in stuck: + if a.get("intent"): + _record(db, a["intent"], "failed", {"error": "the server stopped while it was carried out"}) + return len(gone) diff --git a/fastapi_backend/app/domain/ops_tools.py b/fastapi_backend/app/domain/ops_tools.py index 982a47e71..098bea380 100644 --- a/fastapi_backend/app/domain/ops_tools.py +++ b/fastapi_backend/app/domain/ops_tools.py @@ -33,6 +33,7 @@ "reports", "notifications", "events", + "automations", "workers", "decisions", "voice", diff --git a/fastapi_backend/app/domain/routines.py b/fastapi_backend/app/domain/routines.py index 397b5d81b..382c61450 100644 --- a/fastapi_backend/app/domain/routines.py +++ b/fastapi_backend/app/domain/routines.py @@ -609,6 +609,13 @@ def run_due(db, cfg, log=print, now=None): except Exception as e: # noqa: BLE001 - the schedule carries on if log: log(f"events: {type(e).__name__}: {e}") + try: + from . import approvals # it loads the actions, and an action runs routines + + approvals.sweep(db, cfg) # automations' approvals past automations.approval_days expire, once an hour + except Exception as e: # noqa: BLE001 - the schedule carries on + if log: + log(f"approvals: {type(e).__name__}: {e}") try: analytics.tick(db, cfg, now) # once a day, while Google Analytics is on (docs/analytics.md) except Exception as e: # noqa: BLE001 - the schedule carries on diff --git a/fastapi_backend/app/domain/settings.py b/fastapi_backend/app/domain/settings.py index 16270ea6f..08351c2ca 100644 --- a/fastapi_backend/app/domain/settings.py +++ b/fastapi_backend/app/domain/settings.py @@ -56,6 +56,7 @@ "updates": ("check", "check_hours", "auto_install", "email"), "activity": None, "events": None, + "automations": None, "backups": None, "encryption": None, "fedora": None, @@ -479,6 +480,8 @@ def _check(section, key, value, default): return _activity_setting(key, value) if section == "events": return _events_setting(key, value) + if section == "automations": + return _automations_setting(key, value) if section == "backups": return _backup_setting(key, value) if section == "fedora": @@ -1028,6 +1031,17 @@ def _events_setting(key, value): return value +def _automations_setting(key, value): + """Automations (docs/automations.md): how long an automation's action waits for the person's pick.""" + limits = {"approval_days": (1, 365, "a whole number of days")} + if key not in limits: + raise ValueError(f"unknown setting automations.{key}") + 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 _backup_setting(key, value): from . import schedule diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index c1500e0db..32f2ae4ce 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -622,6 +622,9 @@ 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 + # expires and nothing runs + "automations": {"approval_days": 7}, # 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) @@ -1480,6 +1483,10 @@ def close(self): "DEFINE INDEX IF NOT EXISTS job_batch ON job FIELDS batch", "DEFINE TABLE IF NOT EXISTS approval SCHEMALESS", "DEFINE INDEX IF NOT EXISTS approval_chat ON approval FIELDS chat", + # the inbox (approvals.py): a person's waiting approvals, an automation's (capped), and the expiry sweep + "DEFINE INDEX IF NOT EXISTS approval_waiting ON approval FIELDS account, status", + "DEFINE INDEX IF NOT EXISTS approval_automation ON approval FIELDS origin.automation", + "DEFINE INDEX IF NOT EXISTS approval_expires ON approval FIELDS expires_at", # the scheduled backup (domain/backups.py): backup_schedule:next holds when it's next due and how the last went "DEFINE TABLE IF NOT EXISTS backup_schedule SCHEMALESS", # backup_remote:last: how copying the last backup to backups.connection went diff --git a/fastapi_backend/app/schemas/chats.py b/fastapi_backend/app/schemas/chats.py index 8ca5a392e..2cf82c334 100644 --- a/fastapi_backend/app/schemas/chats.py +++ b/fastapi_backend/app/schemas/chats.py @@ -174,21 +174,91 @@ class MessageCreate(RequestModel): ) +class ApprovalOrigin(ResponseModel): + automation: int | None = None + run: int | None = None + node: str | None = None + + +class ApprovalIntent(ResponseModel): + """What an automation's action would do, as the inbox shows it (credential headers hidden).""" + + action: str + params: dict[str, Any] = Field(default_factory=dict) + effect: str | None = None + risk: str | None = None + untrusted: bool | None = Field(default=None, description="its run read text from outside Lens") + node: str | None = None + status: str | None = None + spaces: list[int] | None = None + + +class ApprovalWhy(ResponseModel): + """The activity that caused it, as it was when it asked.""" + + activity: str + kind: str | None = None + summary: str | None = None + published: str | None = None + url: str | None = None + + +class ApprovalTold(ResponseModel): + channel: str + label: str | None = None + chat: str | None = None + + +class ApprovalCan(ResponseModel): + """What you can do with it from where you asked: approving an automation's action is yours, signed in or in the + chat it told you in; an API key, an app or an agent can only decline it.""" + + approve: bool = False + decline: bool = False + edit: bool = False + always: bool = False + + class Approval(ResponseModel): id: int chat: int | None = None tool: str summary: str | None = None estimate: Any = None - status: str + status: str = Field(description="pending (waiting), running, done, failed, declined or expired") created_at: str | None = None result: Any = None + error: str | None = None + origin: ApprovalOrigin | None = Field(default=None, description="the automation run that asked, when one did") + intent: ApprovalIntent | None = Field(default=None, description="an automation's action: what it would do") + automation: str | None = Field(default=None, description="the automation's name") + space: int | None = None + why: ApprovalWhy | None = None + expires_at: str | None = Field(default=None, description="when it expires and nothing runs (automations only)") + decided_by: str | None = None + decided_at: str | None = None + told: list[ApprovalTold] = Field(default_factory=list, description="the chats you were told in") + can: ApprovalCan | None = None + + +class ApprovalCount(ResponseModel): + waiting: int + automations: int = Field(description="of them, waiting for an automation") class ApprovalDecision(RequestModel): - decision: Literal["approve", "sample", "decline"] = "approve" + decision: Literal["approve", "sample", "decline", "edit", "always"] = Field( + "approve", + 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)", + ) + params: dict[str, Any] | None = Field(default=None, description="edit: the params to change (null leaves one out)") class ApprovalOutcome(ResponseModel): status: str batch: int | None = Field(default=None, description="the batch run started, for run_template") + error: str | None = Field(default=None, description="why an automation's action failed") + result: Any = Field(default=None, description="what an automation's action gave back") + always: bool | None = Field(default=None, description="that node runs without asking from now on") diff --git a/fastapi_backend/tests/api/test_approvals.py b/fastapi_backend/tests/api/test_approvals.py new file mode 100644 index 000000000..51ebe5243 --- /dev/null +++ b/fastapi_backend/tests/api/test_approvals.py @@ -0,0 +1,326 @@ +"""The approvals inbox (docs/automations.md, Approvals): an automation's action that asks first waits as an approval +the person decides (approve, decline, edit, always), told once in their chat app, capped, expiring, and only the +person approves it: an API key, an app or an agent can only decline.""" + +from __future__ import annotations + +import datetime as dt + +import pytest +from fastapi.testclient import TestClient + +from app.domain import actions, ai_tools, approvals, auth, channels, store, telegram +from tests import fake_telegram +from tests.helpers import login, make_user, seed + +update = fake_telegram.update + + +@pytest.fixture +def tg(): + srv, url = fake_telegram.start() + telegram._BOTS.clear() + yield fake_telegram.Handler, url + srv.shutdown() + + +@pytest.fixture +def people(app, db, cfg, folder): + seed(db, cfg, folder) + return { + "me": make_user(db, "me@x.io", "my password 1", roles={"pods": "editor"}), + "other": make_user(db, "other@x.io", "other password 1", roles={"pods": "editor"}), + "pods": store.ns_id(db, "pods"), + } + + +@pytest.fixture +def posted(): + """A test action that reaches other people (effect out) and keeps what it was asked to post.""" + sent = [] + + def perform(db, cfg, intent, user, dry): + if intent["params"]["text"] == "boom": + raise ValueError("the room is gone") + if not dry: + sent.append({"text": intent["params"]["text"], "room": intent["params"]["room"], "as": user["email"]}) + return {"posted": intent["params"]["text"]} + + actions.register( + actions.ActionSpec( + name="test_post", + label="Post in a room", + group="Messages", + params={ + "type": "object", + "properties": { + "room": {"type": "string", "title": "Room", "default": "family"}, + "text": {"type": "string", "title": "Text", "maxLength": 200}, + "times": {"type": "integer", "title": "Times", "default": 1}, + }, + }, + required=("text",), + effect="out", + perform=perform, + describe=lambda p: f"Post “{p.get('text')}” to the {p.get('room', 'family')} room", + ) + ) + yield sent + actions._ACTIONS.pop("test_post", None) + + +@pytest.fixture +def studio(monkeypatch): + """Stored automations' update_intent and set_policy (the engine's), recording what they were told.""" + calls = {"intents": [], "policy": []} + fns = { + "update_intent": lambda db, run, key, status, result=None: calls["intents"].append((run, key, status, result)), + "set_policy": lambda db, aid, node, value, by: calls["policy"].append((aid, node, value, by)), + } + monkeypatch.setattr(approvals, "_studio", fns.get) + return calls + + +def intent(people, n=7, run=51, automation=4, **kw): + return { + "key": f"{run}-n{n}", + "action": "test_post", + "params": {"text": "Trip on Friday, bring a packed lunch", "room": "family"}, + "effect": "out", + "risk": "ask", + "untrusted": True, + "spaces": [people["pods"]], + "run_as": people["me"], + "node": f"n{n}", + "automation": automation, + "run": run, + "when": None, + "status": "waiting", + **kw, + } + + +EVENT = { + "id": "create-recording-7", + "kind": "email.received", + "summary": "Work Gmail received “School trip on Friday”", + "published": "2026-10-15T16:21:58Z", + "space": None, + "object": {"id": "lens:recording/7", "url": "/resources/7"}, +} + + +def test_an_automation_action_waits_as_an_approval_and_the_person_is_told_once(db, cfg, people, posted, tg): + h, url = tg + cfg["telegram"] = { + **cfg["telegram"], + "enabled": True, + "api_url": url, + "token": fake_telegram.TOKEN, + "account": "me@x.io", + "users": ["alice"], + } + h.updates = [update("hi")] # alice, privately: where me@x.io is told things + channels.tick(db, cfg, cfg, "api-1", telegram.TELEGRAM) + h.sent = [] + aid = approvals.ask(db, cfg, intent(people), {**EVENT, "space": people["pods"]}) + a = approvals.get(db, aid) + assert a["status"] == "pending" and a["account"] == people["me"] and a["tool"] == "action" + assert a["origin"] == {"automation": 4, "run": 51, "node": "n7"} and a["space"] == people["pods"] + assert a["summary"] == "Post “Trip on Friday, bring a packed lunch” to the family room" + assert a["automation"] == "Automation 4" and a["why"]["activity"] == "create-recording-7" and a["why"]["url"] == "/resources/7" + made = dt.datetime.fromisoformat(a["created_at"]) + assert dt.datetime.fromisoformat(a["expires_at"]) - made == dt.timedelta(days=7) + assert not posted # nothing happens until the person picks + text = h.sent[-1]["text"] + assert text.startswith("Automation 4 wants to post “Trip on Friday, bring a packed lunch” to the family room. Open ") + assert text.endswith(f"/approvals?id={aid} to decide.") + assert [t["channel"] for t in a["told"]] == ["telegram"] and a["told"][0]["conversation"] + # handed over again (the engine tried twice): the same approval, nobody told twice + assert approvals.ask(db, cfg, intent(people)) == aid and len(h.sent) == 1 + # a dry run never asks; nobody to act for is refused + with pytest.raises(ValueError): + approvals.ask(db, cfg, intent(people, run=None)) + with pytest.raises(ValueError): + approvals.ask(db, cfg, intent(people, run_as=999)) + + +def test_with_no_chat_app_it_waits_in_the_inbox(db, cfg, people, posted): + aid = approvals.ask(db, cfg, intent(people)) + assert approvals.get(db, aid)["told"] is None and approvals.count(db, people["me"]) == {"waiting": 1, "automations": 1} + + +def test_approve_carries_the_action_out_and_the_run_records_it(app, client, db, cfg, people, posted, studio): + h = login(client, "me@x.io", "my password 1") + aid = approvals.ask(db, cfg, intent(people)) + got = client.get(f"/api/v1/approvals/{aid}", headers=h).json() + assert got["intent"]["action"] == "test_post" and got["can"] == {"approve": True, "decline": True, "edit": True, "always": True} + ho = login(TestClient(app, base_url="http://127.0.0.1"), "other@x.io", "other password 1") + assert client.post(f"/api/v1/approvals/{aid}", headers=ho, json={"decision": "approve"}).status_code == 404 # not theirs + out = client.post(f"/api/v1/approvals/{aid}", headers=h, json={"decision": "approve"}).json() + assert out["status"] == "done" and out["result"] == {"posted": "Trip on Friday, bring a packed lunch"} + assert posted == [{"text": "Trip on Friday, bring a packed lunch", "room": "family", "as": "me@x.io"}] # for its person + assert studio["intents"] == [(51, "51-n7", "done", {"posted": "Trip on Friday, bring a packed lunch"})] + a = approvals.get(db, aid) + assert a["status"] == "done" and a["decided_by"] == "me@x.io" and a["intent"]["status"] == "done" + assert client.post(f"/api/v1/approvals/{aid}", headers=h, json={"decision": "approve"}).status_code == 400 # only once + assert len(posted) == 1 + # one that fails is failed, said on the run, and not tried again + bad = approvals.ask(db, cfg, intent(people, n=8, params={"text": "boom"})) + out = client.post(f"/api/v1/approvals/{bad}", headers=h, json={"decision": "approve"}).json() + assert out == {"status": "failed", "error": "the room is gone", "batch": None, "result": None, "always": None} + assert studio["intents"][-1] == (51, "51-n8", "failed", {"error": "the room is gone"}) + + +def test_decline_and_edit(client, db, cfg, people, posted, studio): + h = login(client, "me@x.io", "my password 1") + aid = approvals.ask(db, cfg, intent(people)) + assert client.post(f"/api/v1/approvals/{aid}", headers=h, json={"decision": "decline"}).json()["status"] == "declined" + assert not posted and studio["intents"] == [(51, "51-n7", "declined", None)] + assert approvals.get(db, aid)["status"] == "declined" + aid = approvals.ask(db, cfg, intent(people, n=8)) + for bad, why in ( + ({"times": "twice"}, "times is an integer"), + ({"times": "{{ steps.n3.count }}"}, "times is an integer"), # a template isn't filled in any more + ({"colour": "red"}, "no param colour"), + ({"text": "x" * 201}, "at most 200"), + ): + r = client.post(f"/api/v1/approvals/{aid}", headers=h, json={"decision": "edit", "params": bad}) + assert r.status_code == 400 and why in r.json()["detail"], (bad, r.text) + assert client.post(f"/api/v1/approvals/{aid}", headers=h, json={"decision": "edit"}).status_code == 400 # no params + assert approvals.get(db, aid)["status"] == "pending" and not posted + out = client.post( + f"/api/v1/approvals/{aid}", headers=h, json={"decision": "edit", "params": {"text": "Trip on Friday", "room": "school"}} + ) + assert out.json()["status"] == "done" + assert posted == [{"text": "Trip on Friday", "room": "school", "as": "me@x.io"}] + assert approvals.get(db, aid)["intent"]["params"] == {"text": "Trip on Friday", "room": "school", "times": 1} + + +def test_always_lets_the_node_run_on_its_own_and_only_signed_in(app, client, db, cfg, people, posted, studio): + h = login(client, "me@x.io", "my password 1") + _, key = auth.create_token(db, people["me"], "script", scope="write") + hk = {"Authorization": f"Bearer {key}"} + aid = approvals.ask(db, cfg, intent(people)) + got = client.get(f"/api/v1/approvals/{aid}", headers=hk).json() + assert got["can"] == {"approve": False, "decline": True, "edit": False, "always": False} # an API key only declines + for decision in ("always", "approve", "edit"): + r = client.post(f"/api/v1/approvals/{aid}", headers=hk, json={"decision": decision, "params": {"text": "x"}}) + assert r.status_code == 403, decision + assert not posted and not studio["policy"] + out = client.post(f"/api/v1/approvals/{aid}", headers=h, json={"decision": "always"}).json() + assert out["status"] == "done" and out["always"] is True and len(posted) == 1 + assert studio["policy"] == [(4, "n7", "auto", "me@x.io")] + # only an action that reaches outside Lens is ever allowed from now on + lens = approvals.ask(db, cfg, intent(people, n=8, effect="lens")) + r = client.post(f"/api/v1/approvals/{lens}", headers=h, json={"decision": "always"}) + assert r.status_code == 400 and "outside Lens" in r.json()["detail"] + # an API key still declines + assert client.post(f"/api/v1/approvals/{lens}", headers=hk, json={"decision": "decline"}).json()["status"] == "declined" + + +def test_always_waits_for_saved_automations(client, db, cfg, people, posted): + h = login(client, "me@x.io", "my password 1") + aid = approvals.ask(db, cfg, intent(people)) + assert client.get(f"/api/v1/approvals/{aid}", headers=h).json()["can"]["always"] is False + r = client.post(f"/api/v1/approvals/{aid}", headers=h, json={"decision": "always"}) + assert r.status_code == 400 and "this once" in r.json()["detail"] and not posted + # and the outcome stays on the approval itself meanwhile + assert client.post(f"/api/v1/approvals/{aid}", headers=h, json={"decision": "approve"}).json()["status"] == "done" + assert approvals.get(db, aid)["intent"]["status"] == "done" + + +def test_undecided_approvals_expire_and_nothing_runs(db, cfg, people, posted, studio): + cfg["automations"]["approval_days"] = 2 + aid = approvals.ask(db, cfg, intent(people)) + a = approvals.get(db, aid) + assert dt.datetime.fromisoformat(a["expires_at"]) - dt.datetime.fromisoformat(a["created_at"]) == dt.timedelta(days=2) + chat_one = db.next_id("approval") # the assistant's own approvals never expire + db.q( + "CREATE $r CONTENT $d", + r=store.R("approval", chat_one), + d={"account": people["me"], "tool": "run_template", "status": "pending", "created_at": "2020-01-01T00:00:00+00:00"}, + ) + now = dt.datetime.now(dt.UTC) + assert approvals.sweep(db, cfg, now + dt.timedelta(days=1)) == 0 + assert approvals.sweep(db, cfg, now + dt.timedelta(days=3)) == 1 + a = approvals.get(db, aid) + assert a["status"] == "expired" and a["intent"]["status"] == "expired" and not posted + assert studio["intents"] == [(51, "51-n7", "expired", None)] + assert approvals.get(db, chat_one)["status"] == "pending" + with pytest.raises(ValueError): + ai_tools.approve(db, cfg, aid, {"id": people["me"], "email": "me@x.io"}, {people["pods"]}) + # throttled to once an hour when called on schedule + approvals._swept["at"] = 0.0 + assert approvals.sweep(db, cfg) == 0 + assert approvals.sweep(db, cfg) is None + + +def test_a_flood_of_approvals_is_capped_per_automation(db, cfg, people, posted, studio, monkeypatch): + monkeypatch.setattr(approvals, "CAP", 3) + ids = [approvals.ask(db, cfg, intent(people, n=n)) for n in range(1, 4)] + assert all(ids) and approvals.waiting(db, 4) == 3 + assert approvals.ask(db, cfg, intent(people, n=9)) is None # dropped, said on the run + run, key, status, result = studio["intents"][-1] + assert (run, key, status) == (51, "51-n9", "failed") and result["error"].startswith("dropped") + assert approvals.ask(db, cfg, intent(people, n=9, automation=5)) is not None # another automation's still ask + ai_tools.approve(db, cfg, ids[0], {"id": people["me"], "email": "me@x.io"}, set(), "decline") + assert approvals.ask(db, cfg, intent(people, n=10)) is not None # room again once one is decided + + +def test_the_inbox_lists_both_kinds_with_filters_paging_and_a_count(client, db, cfg, people, posted): + h = login(client, "me@x.io", "my password 1") + chat_one = db.next_id("approval") + db.q( + "CREATE $r CONTENT $d", + r=store.R("approval", chat_one), + d={ + "chat": 3, + "account": people["me"], + "tool": "run_template", + "summary": "Run Meeting notes", + "status": "pending", + "created_at": store.now(), + }, + ) + a1 = approvals.ask(db, cfg, intent(people, n=1)) + a2 = approvals.ask(db, cfg, intent(people, n=2, automation=5)) + approvals.ask(db, cfg, intent(people, n=3, run_as=people["other"])) # someone else's + ai_tools.approve(db, cfg, a1, {"id": people["me"], "email": "me@x.io"}, set(), "decline") + + def ids(**q): + return [a["id"] for a in client.get("/api/v1/approvals", headers=h, params=q).json()] + + assert ids() == [a2, a1, chat_one] + assert ids(status="pending") == [a2, chat_one] + assert ids(origin="automation") == [a2, a1] and ids(origin="chat") == [chat_one] + assert ids(automation=5) == [a2] and ids(chat_id=3) == [chat_one] + assert ids(limit=1) == [a2] and ids(limit=1, before=a2) == [a1] and ids(before=chat_one) == [] + assert client.get("/api/v1/approvals/count", headers=h).json() == {"waiting": 2, "automations": 1} + one = client.get(f"/api/v1/approvals/{chat_one}", headers=h).json() + assert one["can"] == {"approve": True, "decline": True, "edit": False, "always": False} and one["intent"] is None + assert client.get(f"/api/v1/approvals/{a2 + 1}", headers=h).status_code == 404 # someone else's + assert client.post(f"/api/v1/approvals/{chat_one}", headers=h, json={"decision": "edit", "params": {}}).status_code == 400 + + +def test_credential_headers_stay_hidden_and_sealed_through_an_edit(db, cfg, people): + sealed = "lens:sealed:abc" + i = intent( + people, + action="http_request", + params={"method": "POST", "url": "https://api.example.com/x", "headers": {"Authorization": sealed, "Accept": "a"}}, + ) + shown = approvals.shown(i) + assert shown["params"]["headers"] == {"Authorization": "••••", "Accept": "a"} + got = approvals.edited(i, {"headers": {"Authorization": "••••", "Accept": "b"}}) + assert got["headers"] == {"Authorization": sealed, "Accept": "b"} + + +def test_how_long_approvals_wait_is_a_setting(app, client, db): + make_user(db, "root@x.io", "root password 1", admin=True) + h = login(client, "root@x.io", "root password 1") + assert client.get("/api/v1/settings", headers=h).json()["automations"]["values"] == {"approval_days": 7} + assert client.put("/api/v1/settings/automations", json={"approval_days": 14}, headers=h).status_code == 200 + assert approvals.days(app.state.settings.current()) == 14 + for bad in ({"approval_days": 0}, {"approval_days": 366}, {"approval_days": "7"}, {"approval_days": True}, {"days": 1}): + assert client.put("/api/v1/settings/automations", json=bad, headers=h).status_code == 400, bad diff --git a/nextjs-frontend/__tests__/settings-find.test.tsx b/nextjs-frontend/__tests__/settings-find.test.tsx index 5260cc263..9eb8ec711 100644 --- a/nextjs-frontend/__tests__/settings-find.test.tsx +++ b/nextjs-frontend/__tests__/settings-find.test.tsx @@ -78,7 +78,11 @@ describe("finding a setting", () => { const hits = findSettings("activities", true); const auto = hits.find((h) => h.section === "automations")!; expect(auto.group).toBe("System"); - expect(fieldsOf("automations").map((f) => fieldId(f))).toEqual(["events.poll_seconds", "events.keep_days"]); + expect(fieldsOf("automations").map((f) => fieldId(f))).toEqual([ + "events.poll_seconds", + "events.keep_days", + "automations.approval_days", + ]); }); it("finds only People for people who aren't admins", () => { diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index 0186a7826..333081e48 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -156,8 +156,14 @@ export type { ApplySuggestionResponse, ApplySuggestionResponses, Approval, + ApprovalCan, + ApprovalCount, ApprovalDecision, + ApprovalIntent, + ApprovalOrigin, ApprovalOutcome, + ApprovalTold, + ApprovalWhy, ApproveAccessRequestData, ApproveAccessRequestError, ApproveAccessRequestErrors, @@ -386,6 +392,9 @@ export type { ConversionNodeTestResult, Converters, CopyWork, + CountApprovalsData, + CountApprovalsResponse, + CountApprovalsResponses, CreateBatchData, CreateBatchError, CreateBatchErrors, @@ -1022,6 +1031,11 @@ export type { GetActivityErrors, GetActivityResponse, GetActivityResponses, + GetApprovalData, + GetApprovalError, + GetApprovalErrors, + GetApprovalResponse, + GetApprovalResponses, GetAudioData, GetAudioError, GetAudioErrors, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 5fb6a616a..dab828b3c 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -139,6 +139,8 @@ import type { ControlWorkerData, ControlWorkerErrors, ControlWorkerResponses, + CountApprovalsData, + CountApprovalsResponses, CreateBatchData, CreateBatchErrors, CreateBatchResponses, @@ -474,6 +476,9 @@ import type { GetActivityData, GetActivityErrors, GetActivityResponses, + GetApprovalData, + GetApprovalErrors, + GetApprovalResponses, GetAudioData, GetAudioErrors, GetAudioResponses, @@ -9529,7 +9534,9 @@ export class Chats { /** * List Approvals * - * Work the assistant proposed for you to approve (and what became of it), newest first. + * What waits for your pick (and what became of it), newest first: the assistant's proposals and automations' + * actions. Filter by `status` (pending is waiting), `origin` (automation or chat), one `automation` or one chat + * (`chat_id`); page with `before`. */ public static listApprovals( options?: Options, @@ -9540,10 +9547,41 @@ export class Chats { }); } + /** + * Count Approvals + * + * How many approvals wait for you, for the badge in the top bar. + */ + public static countApprovals( + options?: Options, + ): RequestResult { + return (options?.client ?? client).get({ + url: "/api/v1/approvals/count", + ...options, + }); + } + + /** + * Get Approval + * + * One of your approvals. + */ + public static getApproval( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/approvals/{aid}", + ...options, + }); + } + /** * Decide Approval * - * Approve (or run a sample of, or decline) something the assistant proposed. Each approval is decided once. + * Approve (or run a sample of, or decline) something the assistant proposed or an automation's action. Each + * approval is decided once. An automation's action can also be edited (`params`) and then carried out, or allowed + * from now on for that automation (`always`); approving one needs you signed in, since it's your pick: an API key + * or an app can only decline it. */ public static decideApproval( options: Options, diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index b34bf9c89..2391e2bd2 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -911,6 +911,8 @@ export type Approval = { estimate?: unknown; /** * Status + * + * pending (waiting), running, done, failed, declined or expired */ status: string; /** @@ -921,6 +923,93 @@ export type Approval = { * Result */ result?: unknown; + /** + * Error + */ + error?: string | null; + /** + * the automation run that asked, when one did + */ + origin?: ApprovalOrigin | null; + /** + * an automation's action: what it would do + */ + intent?: ApprovalIntent | null; + /** + * Automation + * + * the automation's name + */ + automation?: string | null; + /** + * Space + */ + space?: number | null; + why?: ApprovalWhy | null; + /** + * Expires At + * + * when it expires and nothing runs (automations only) + */ + expires_at?: string | null; + /** + * Decided By + */ + decided_by?: string | null; + /** + * Decided At + */ + decided_at?: string | null; + /** + * Told + * + * the chats you were told in + */ + told?: Array; + can?: ApprovalCan | null; + [key: string]: unknown; +}; + +/** + * ApprovalCan + * + * What you can do with it from where you asked: approving an automation's action is yours, signed in or in the + * chat it told you in; an API key, an app or an agent can only decline it. + */ +export type ApprovalCan = { + /** + * Approve + */ + approve?: boolean; + /** + * Decline + */ + decline?: boolean; + /** + * Edit + */ + edit?: boolean; + /** + * Always + */ + always?: boolean; + [key: string]: unknown; +}; + +/** + * ApprovalCount + */ +export type ApprovalCount = { + /** + * Waiting + */ + waiting: number; + /** + * Automations + * + * of them, waiting for an automation + */ + automations: number; [key: string]: unknown; }; @@ -930,8 +1019,82 @@ export type Approval = { export type ApprovalDecision = { /** * Decision + * + * 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) + */ + decision?: "approve" | "sample" | "decline" | "edit" | "always"; + /** + * Params + * + * edit: the params to change (null leaves one out) + */ + params?: { + [key: string]: unknown; + } | null; +}; + +/** + * ApprovalIntent + * + * What an automation's action would do, as the inbox shows it (credential headers hidden). + */ +export type ApprovalIntent = { + /** + * Action + */ + action: string; + /** + * Params + */ + params?: { + [key: string]: unknown; + }; + /** + * Effect + */ + effect?: string | null; + /** + * Risk + */ + risk?: string | null; + /** + * Untrusted + * + * its run read text from outside Lens + */ + untrusted?: boolean | null; + /** + * Node + */ + node?: string | null; + /** + * Status + */ + status?: string | null; + /** + * Spaces + */ + spaces?: Array | null; + [key: string]: unknown; +}; + +/** + * ApprovalOrigin + */ +export type ApprovalOrigin = { + /** + * Automation + */ + automation?: number | null; + /** + * Run */ - decision?: "approve" | "sample" | "decline"; + run?: number | null; + /** + * Node + */ + node?: string | null; + [key: string]: unknown; }; /** @@ -948,6 +1111,72 @@ export type ApprovalOutcome = { * the batch run started, for run_template */ batch?: number | null; + /** + * Error + * + * why an automation's action failed + */ + error?: string | null; + /** + * Result + * + * what an automation's action gave back + */ + result?: unknown; + /** + * Always + * + * that node runs without asking from now on + */ + always?: boolean | null; + [key: string]: unknown; +}; + +/** + * ApprovalTold + */ +export type ApprovalTold = { + /** + * Channel + */ + channel: string; + /** + * Label + */ + label?: string | null; + /** + * Chat + */ + chat?: string | null; + [key: string]: unknown; +}; + +/** + * ApprovalWhy + * + * The activity that caused it, as it was when it asked. + */ +export type ApprovalWhy = { + /** + * Activity + */ + activity: string; + /** + * Kind + */ + kind?: string | null; + /** + * Summary + */ + summary?: string | null; + /** + * Published + */ + published?: string | null; + /** + * Url + */ + url?: string | null; [key: string]: unknown; }; @@ -36196,6 +36425,28 @@ export type ListApprovalsData = { * Chat Id */ chat_id?: number | null; + /** + * Status + */ + status?: "pending" | "running" | "done" | "failed" | "declined" | "expired" | null; + /** + * Origin + */ + origin?: "automation" | "chat" | null; + /** + * Automation + */ + automation?: number | null; + /** + * Before + * + * ids below this one: the last id of the page before + */ + before?: number | null; + /** + * Limit + */ + limit?: number; }; url: "/api/v1/approvals"; }; @@ -36220,6 +36471,52 @@ export type ListApprovalsResponses = { export type ListApprovalsResponse = ListApprovalsResponses[keyof ListApprovalsResponses]; +export type CountApprovalsData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/approvals/count"; +}; + +export type CountApprovalsResponses = { + /** + * Successful Response + */ + 200: ApprovalCount; +}; + +export type CountApprovalsResponse = CountApprovalsResponses[keyof CountApprovalsResponses]; + +export type GetApprovalData = { + body?: never; + path: { + /** + * Aid + */ + aid: number; + }; + query?: never; + url: "/api/v1/approvals/{aid}"; +}; + +export type GetApprovalErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type GetApprovalError = GetApprovalErrors[keyof GetApprovalErrors]; + +export type GetApprovalResponses = { + /** + * Successful Response + */ + 200: Approval; +}; + +export type GetApprovalResponse = GetApprovalResponses[keyof GetApprovalResponses]; + export type DecideApprovalData = { body: ApprovalDecision; path: { diff --git a/nextjs-frontend/components/settings/bodies.tsx b/nextjs-frontend/components/settings/bodies.tsx index 292d93185..c2294ce56 100644 --- a/nextjs-frontend/components/settings/bodies.tsx +++ b/nextjs-frontend/components/settings/bodies.tsx @@ -475,6 +475,7 @@ export function SectionBody({ ctx }: { ctx: BodyCtx }) {
+

Agents read the same stream with the timeline tool (MCP and the assistant) or GET /api/v1/activities. diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts index 44342f563..1fafb3e41 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"], + backend: ["events", "automations"], description: - "The stream of activities automations follow (new assets and what else happens in Lens): how often followers look for new ones, and how long activities with no row of their own are kept.", + "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, and how long an automation’s action waits for your pick.", }, { id: "startup", @@ -2697,6 +2697,15 @@ export const FIELDS: FieldSpec[] = [ 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", }, + { + 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", + }, // Usage analytics (Google Analytics opt-in) { section: "analytics", diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index b74989d6f..2b61e1766 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -23835,7 +23835,7 @@ "chats" ], "summary": "List Approvals", - "description": "Work the assistant proposed for you to approve (and what became of it), newest first.", + "description": "What waits for your pick (and what became of it), newest first: the assistant's proposals and automations'\nactions. Filter by `status` (pending is waiting), `origin` (automation or chat), one `automation` or one chat\n(`chat_id`); page with `before`.", "operationId": "list_approvals", "parameters": [ { @@ -23853,6 +23853,96 @@ ], "title": "Chat Id" } + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "enum": [ + "pending", + "running", + "done", + "failed", + "declined", + "expired" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Status" + } + }, + { + "name": "origin", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "enum": [ + "automation", + "chat" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Origin" + } + }, + { + "name": "automation", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Automation" + } + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "ids below this one: the last id of the page before", + "title": "Before" + }, + "description": "ids below this one: the last id of the page before" + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 200, + "minimum": 1, + "default": 100, + "title": "Limit" + } } ], "responses": { @@ -23883,13 +23973,76 @@ } } }, + "/api/v1/approvals/count": { + "get": { + "tags": [ + "chats" + ], + "summary": "Count Approvals", + "description": "How many approvals wait for you, for the badge in the top bar.", + "operationId": "count_approvals", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApprovalCount" + } + } + } + } + } + } + }, "/api/v1/approvals/{aid}": { + "get": { + "tags": [ + "chats" + ], + "summary": "Get Approval", + "description": "One of your approvals.", + "operationId": "get_approval", + "parameters": [ + { + "name": "aid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Aid" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Approval" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, "post": { "tags": [ "chats" ], "summary": "Decide Approval", - "description": "Approve (or run a sample of, or decline) something the assistant proposed. Each approval is decided once.", + "description": "Approve (or run a sample of, or decline) something the assistant proposed or an automation's action. Each\napproval is decided once. An automation's action can also be edited (`params`) and then carried out, or allowed\nfrom now on for that automation (`always`); approving one needs you signed in, since it's your pick: an API key\nor an app can only decline it.", "operationId": "decide_approval", "parameters": [ { @@ -30200,7 +30353,8 @@ }, "status": { "type": "string", - "title": "Status" + "title": "Status", + "description": "pending (waiting), running, done, failed, declined or expired" }, "created_at": { "anyOf": [ @@ -30215,6 +30369,124 @@ }, "result": { "title": "Result" + }, + "error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Error" + }, + "origin": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalOrigin" + }, + { + "type": "null" + } + ], + "description": "the automation run that asked, when one did" + }, + "intent": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalIntent" + }, + { + "type": "null" + } + ], + "description": "an automation's action: what it would do" + }, + "automation": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Automation", + "description": "the automation's name" + }, + "space": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Space" + }, + "why": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalWhy" + }, + { + "type": "null" + } + ] + }, + "expires_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Expires At", + "description": "when it expires and nothing runs (automations only)" + }, + "decided_by": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Decided By" + }, + "decided_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Decided At" + }, + "told": { + "items": { + "$ref": "#/components/schemas/ApprovalTold" + }, + "type": "array", + "title": "Told", + "description": "the chats you were told in" + }, + "can": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalCan" + }, + { + "type": "null" + } + ] } }, "additionalProperties": true, @@ -30226,6 +30498,54 @@ ], "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." + }, + "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": { @@ -30233,16 +30553,162 @@ "enum": [ "approve", "sample", - "decline" + "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": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "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" + }, + "params": { + "additionalProperties": true, + "type": "object", + "title": "Params" + }, + "effect": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Effect" + }, + "risk": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Risk" + }, + "untrusted": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Untrusted", + "description": "its run read text from outside Lens" + }, + "node": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Node" + }, + "status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Status" + }, + "spaces": { + "anyOf": [ + { + "items": { + "type": "integer" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Spaces" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "action" + ], + "title": "ApprovalIntent", + "description": "What an automation's action would do, as the inbox shows it (credential headers hidden)." + }, + "ApprovalOrigin": { + "properties": { + "automation": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Automation" + }, + "run": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Run" + }, + "node": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Node" + } + }, + "additionalProperties": true, + "type": "object", + "title": "ApprovalOrigin" + }, "ApprovalOutcome": { "properties": { "status": { @@ -30260,6 +30726,34 @@ ], "title": "Batch", "description": "the batch run started, for run_template" + }, + "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, @@ -30269,6 +30763,101 @@ ], "title": "ApprovalOutcome" }, + "ApprovalTold": { + "properties": { + "channel": { + "type": "string", + "title": "Channel" + }, + "label": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Label" + }, + "chat": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Chat" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "channel" + ], + "title": "ApprovalTold" + }, + "ApprovalWhy": { + "properties": { + "activity": { + "type": "string", + "title": "Activity" + }, + "kind": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Kind" + }, + "summary": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Summary" + }, + "published": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Published" + }, + "url": { + "anyOf": [ + { + "type": "string" + }, + { + "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": { diff --git a/threat-model.md b/threat-model.md index faae1de06..61aa35c41 100644 --- a/threat-model.md +++ b/threat-model.md @@ -390,6 +390,7 @@ Every row is claimed, disclaimed, N/A with a reason, or unresolved. Family short | Query | Resource complexity | unresolved | SPARQL has a row cap only; the Cypher regex guard is heuristic | Q16, Q25 | *(inferred, Q25)* | | Assistant | Numeric domain | claimed | tool loop capped by `ai.max_steps` and `ai.max_transcript_reads` | P-RETRIEVAL | *(documented, docs/assistant.md "capped by")* | | Assistant | Failure atomicity | claimed | change tools become approval cards; approval re-checks the role; notes and setup excepted | P-APPROVAL | *(documented, docs/assistant.md "Approvals")* | +| P-AUTOMATION-APPROVAL | An automation's action that asks first (effect `out`, or `lens` beyond the event's own object) waits as an approval of the automation's person, and nothing runs until they pick. Approving, editing or allowing a node from now on (`always`) needs them signed in to Lens; API keys, apps, MCP and the assistant can only list and decline. A decision is claimed once (two at once can't both carry it out). At most 100 wait per automation and each tells the person once, so a flood of activities can't bury the inbox or their chat; undecided ones expire after `automations.approval_days` and nothing runs. | integrity-bypass | security-critical | *(documented, docs/automations.md "Approvals")* | Voided by: the person setting a node to `auto` (`always`, or the builder's toggle) — that node then runs without asking; an admin raising `automations.approval_days`. The summary and the message the person is told hold text the run read from outside Lens: links in it are broken up (P-INJECTION-EGRESS), and what runs is the intent the card shows. | | Assistant | Recursive / cyclic topology | claimed | flow graphs never loop back; step budget | P-FLOW | *(documented, domain/flow.py docstring "Graphs never loop back")* | | Assistant | Callback / collaborator execution | claimed | tools see only the person's reads; Python tools from admins only | P-RETRIEVAL, P-NO-CODE | *(documented, docs/assistant.md "limited to what the person can read")* | | Assistant | Serialization / reconstruction | claimed | manifests checked; Python refused for non-admins | P-NO-CODE | *(documented, domain/extensions.py docstring "Only admins write Python")* | From d06c6ce972651c78d58d9106db33c7087d8cccb6 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Fri, 16 Oct 2026 00:35:54 +0000 Subject: [PATCH 2/2] test: read each automations setting on its own now that there are two Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01VF3LK1DBx3dXX2b8c5T3cQ --- fastapi_backend/tests/api/test_approvals.py | 2 +- fastapi_backend/tests/domain/test_timers.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fastapi_backend/tests/api/test_approvals.py b/fastapi_backend/tests/api/test_approvals.py index 51ebe5243..28eebd525 100644 --- a/fastapi_backend/tests/api/test_approvals.py +++ b/fastapi_backend/tests/api/test_approvals.py @@ -319,7 +319,7 @@ def test_credential_headers_stay_hidden_and_sealed_through_an_edit(db, cfg, peop def test_how_long_approvals_wait_is_a_setting(app, client, db): make_user(db, "root@x.io", "root password 1", admin=True) h = login(client, "root@x.io", "root password 1") - assert client.get("/api/v1/settings", headers=h).json()["automations"]["values"] == {"approval_days": 7} + assert client.get("/api/v1/settings", headers=h).json()["automations"]["values"]["approval_days"] == 7 assert client.put("/api/v1/settings/automations", json={"approval_days": 14}, headers=h).status_code == 200 assert approvals.days(app.state.settings.current()) == 14 for bad in ({"approval_days": 0}, {"approval_days": 366}, {"approval_days": "7"}, {"approval_days": True}, {"days": 1}): diff --git a/fastapi_backend/tests/domain/test_timers.py b/fastapi_backend/tests/domain/test_timers.py index 818e9bd3a..9d31b7022 100644 --- a/fastapi_backend/tests/domain/test_timers.py +++ b/fastapi_backend/tests/domain/test_timers.py @@ -213,6 +213,6 @@ def test_catch_up_is_a_setting(app, client, db): assert timers.catch_up(app.state.settings.current()) == 3600 assert client.put("/api/v1/settings/automations", json={"catch_up": "15m"}, headers=h).status_code == 200 assert timers.catch_up(app.state.settings.current()) == 900 - assert client.get("/api/v1/settings", headers=h).json()["automations"]["values"] == {"catch_up": "15m"} + assert client.get("/api/v1/settings", headers=h).json()["automations"]["values"]["catch_up"] == "15m" for bad in ({"catch_up": "8d"}, {"catch_up": 60}, {"catch_up": "-1h"}, {"catch_up": "soon"}, {"grace": "1h"}): assert client.put("/api/v1/settings/automations", json=bad, headers=h).status_code == 400, bad