From c22336ba65e5e491a6709366098851b7bf055080 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 08:50:53 +0000 Subject: [PATCH 1/3] feat(automations): starter automations, switched off, at GET /automations/starters Five ready-made drafts (school emails, router alerts, a morning digest, no reply in two days, webhook to note) that POST /automations takes as they are. Nothing is stored until someone saves one. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01AjJqXgjj1cNdKGRQbX5frb --- README.md | 6 +- docs/api.md | 1 + docs/automations.md | 19 +++ docs/requirements.md | 1 + fastapi_backend/app/api/v1/router.py | 2 + .../app/api/v1/routes/automation_starters.py | 20 +++ .../app/domain/automation_starters.py | 139 ++++++++++++++++++ .../app/schemas/automation_starters.py | 20 +++ .../tests/api/test_automation_starters.py | 49 ++++++ nextjs-frontend/app/openapi-client/index.ts | 5 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 17 +++ .../app/openapi-client/types.gen.ts | 56 +++++++ nextjs-frontend/openapi.json | 71 +++++++++ 13 files changed, 403 insertions(+), 3 deletions(-) create mode 100644 fastapi_backend/app/api/v1/routes/automation_starters.py create mode 100644 fastapi_backend/app/domain/automation_starters.py create mode 100644 fastapi_backend/app/schemas/automation_starters.py create mode 100644 fastapi_backend/tests/api/test_automation_starters.py diff --git a/README.md b/README.md index 4c9e2594..930f4791 100644 --- a/README.md +++ b/README.md @@ -193,9 +193,9 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p to group under a broader one, making the changes they're sure of and proposing the rest, each one undoable. Anything that reaches outside Lens or changes more than what set it off asks first, until you let it run on its own: on the Approvals page or, for a change inside Lens, with a yes in the chat it told you in; agents can decline an approval but never give one. Each automation has - limits and budgets, and agents make, try and run them over MCP and in the assistant, or draft one from a sentence. An - automation's workflow is drawn and tried on the workflow canvas, with its actions in the palette, and the studio - lists your automations, builds one in When, If and Then (tested on a recent activity before you save it), and shows + limits and budgets, and agents make, try and run them over MCP and in the assistant, draft one from a sentence, or + start from one of five starters that stay off until you turn them on. An automation's workflow is drawn and tried + on the workflow canvas, with its actions in the palette, and the studio lists your automations, builds one in When, If and Then (tested on a recent activity before you save it), and shows its runs, what's coming up, its variables and its costs. ([Processing](docs/processing.md#workflows-and-the-canvas), [converting assets](docs/processing.md#converting-assets), [notifications](docs/notifications.md), diff --git a/docs/api.md b/docs/api.md index 3cc6947c..ad92445e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -187,6 +187,7 @@ GET /api/v1/automations POST /api/v1/automations GET /api/v1/automations/actions POST /api/v1/automations/draft +GET /api/v1/automations/starters GET /api/v1/automations/{id} PATCH /api/v1/automations/{id} DELETE /api/v1/automations/{id} diff --git a/docs/automations.md b/docs/automations.md index 8c626190..bc39f35c 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -53,6 +53,7 @@ merged is called built. | Describing an automation in words: a draft from a sentence (`POST /api/v1/automations/draft`) | built | | The studio: the list at `/automations` and the When, If and Then builder, with a test panel ([The studio](#the-studio)) | built | | An automation's page: its runs, what's coming up, its variables and its costs, in tabs ([An automation's page](#an-automations-page)) | built | +| Starters: five ready-made drafts, switched off, to open, change and save (`GET /api/v1/automations/starters`, [Starters](#starters)) | built | ## The studio @@ -1198,6 +1199,21 @@ Nothing is saved: try the draft (`POST /automations/test`), change it, then save ledger](activity.md) for you and its namespaces, and isn't made once a budget they count for, or everything's, is used up. +### Starters + +Built (`app/domain/automation_starters.py`). `GET /api/v1/automations/starters` lists ready-made drafts, each +`{id, name, description, draft}`, with `draft` what `POST /automations` takes, switched off. Nothing is stored: a +starter is saved only when someone saves it, and runs only once it is turned on. The description says what to change +first, such as the school's address. + +| Starter | What it does | +| --- | --- | +| Tell me about school emails | An email from an address with “school” in it tells you in your chat app; posting it to the `family` Matterbridge room asks you first | +| Router alerts | An alert in a sensor's log whose name has “router” in it tells you, at most once an hour | +| Morning digest | Every weekday at 07:00 (UTC until you change it) the agent sums up yesterday's timeline items you haven't reviewed, then tells you | +| No reply in two days | An email whose start asks something, with no email in your Sent mailbox within two days, reminds you; any email you send in that time calls it off | +| Webhook to note | A call to its webhook writes a note with what was sent | + ### Agents Built. Over [MCP](mcp.md) an agent uses `automations` (list them, read one with its latest runs, or one run), @@ -1353,6 +1369,9 @@ held run until you pick. - Deleted automations kept for a time, then removed with their runs (today they stay until restored). - The studio: dragging actions and rows to reorder them (today the arrows move an action); sharing an automation as a file; a builder laid out for phones first. +- Starters: "No reply in two days" matching the reply to the same conversation (emails carry no thread yet, so any + email you send calls it off); a starter picking its sensor, room or address from what is connected, instead of a + word to change. - Credentials in the headers of a saved event workflow an automation follows (`workflow`) sealed too (today only a graph saved with the automation is; the workflow's are sent as written). - Webhook triggers: a trigger option for a hook that takes only signed calls (`token_for(..., signed=True)`), and a diff --git a/docs/requirements.md b/docs/requirements.md index d0ac41f4..d353688e 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -234,6 +234,7 @@ request, to another check that proves the same thing; loosening a requirement or | Joins wait for an automation's triggers together: all of them, a number of times, one that doesn't come in time, or a batch, on timers that outlast a restart | [test_match_joins.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_joins.py) `test_all_waits_for_every_trigger_within_the_window_on_the_same_key`, `test_count_fires_once_per_crossing_then_counts_again`, `test_absent_waits_with_a_timer_and_the_missing_one_cancels_it`, `test_batch_collects_then_runs_once`, `test_two_writers_at_once_lose_nothing`; [test_automation_conditions.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_conditions.py) `test_an_absent_join_waits_on_a_timer_and_switching_off_drops_it` | | Each automation has limits and budgets | [test_automation_runs.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_runs.py) `test_the_if_limits_and_dry_runs`, `test_a_run_over_budget_is_held_for_the_persons_pick` | | Agents make, try and run automations over MCP and in the assistant, or draft one from a sentence | [test_automation_tools.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_tools.py) `test_agents_save_try_and_run_automations_over_mcp`, `test_the_assistant_saves_at_once_and_asks_to_switch_on_or_run`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_an_automation_is_drafted_from_a_sentence` | +| Starter automations come switched off, each one saving as it is, and changing nothing until someone turns it on | [test_automation_starters.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_starters.py) `test_every_starter_saves_as_it_is_and_stays_off`, `test_the_school_starter_tells_me_at_once_and_asks_before_posting_to_the_family` | | An automation's workflow is drawn and tried on the canvas: its actions in the palette, their settings drawn from each action's params, Decide's ports and the leaf rule | [workflow-canvas.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-canvas.test.ts) `give a decide node a port per option, then unsure`, `keep the leaf rule: nothing after an action that reaches outside Lens or waits`, `say what the backend would reject in their settings`; [automation-nodes-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automation-nodes-ui.test.tsx) `sets an action up from the catalog, its params drawn from its schema`; [schema-form.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/schema-form.test.tsx) `opens the variable picker on {{ and puts the pick in with Enter` | | In the web app, automations are listed with what sets each off in words, and built in When, If and Then with a test on a recent activity, problems next to their fields | [automations-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automations-ui.test.tsx) `the list reads each automation, and Delete is undone from its toast`, `the builder adds a trigger with a condition and an action, then saves it switched off`, `the test panel runs the draft on a recent activity and says what it would do`, `API problems go next to what they are about`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_lists_read_the_triggers_in_words_and_say_when_it_runs_next` | | An automation's page shows its runs a page at a time with each one's log, what's coming up, its variables to edit and its costs | [automation-detail.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automation-detail.test.tsx) `Runs pages back with before, and a run opens to what it did and its log`, `a run held over a budget can run once or be skipped`, `Coming up lists its times, and says why when there are none`, `Variables set from the keyboard, and Clear is undone from its toast` | diff --git a/fastapi_backend/app/api/v1/router.py b/fastapi_backend/app/api/v1/router.py index d0d77468..5f90367c 100644 --- a/fastapi_backend/app/api/v1/router.py +++ b/fastapi_backend/app/api/v1/router.py @@ -8,6 +8,7 @@ admin, auth, automation_hooks, + automation_starters, automation_vars, automations, backups, @@ -100,6 +101,7 @@ activity, activities, automation_hooks, + automation_starters, automation_vars, # before namespaces: /namespaces/{name}/automation-vars automations, budgets, diff --git a/fastapi_backend/app/api/v1/routes/automation_starters.py b/fastapi_backend/app/api/v1/routes/automation_starters.py new file mode 100644 index 00000000..73a70223 --- /dev/null +++ b/fastapi_backend/app/api/v1/routes/automation_starters.py @@ -0,0 +1,20 @@ +"""Starter automations (docs/automations.md, Starters): ready-made drafts, switched off, that the studio opens in its +builder and agents read before saving their own. Nothing is stored until someone saves one. Automation ids use the +int convertor, so this static path never collides with /automations/{id}.""" + +from __future__ import annotations + +from fastapi import APIRouter + +from app.api.deps import CurrentUser +from app.domain import automation_starters +from app.schemas.automation_starters import AutomationStarter, AutomationStarters + +router = APIRouter(prefix="/automations", tags=["automations"]) + + +@router.get("/starters") +def list_starters(user: CurrentUser) -> AutomationStarters: + """Starter automations: each a draft to open, change and save (POST /automations), switched off until you turn + it on.""" + return AutomationStarters(starters=[AutomationStarter(**s) for s in automation_starters.starters()]) diff --git a/fastapi_backend/app/domain/automation_starters.py b/fastapi_backend/app/domain/automation_starters.py new file mode 100644 index 00000000..6e2a4398 --- /dev/null +++ b/fastapi_backend/app/domain/automation_starters.py @@ -0,0 +1,139 @@ +"""Starter automations (docs/automations.md, Starters): ready-made drafts a person opens in the studio, changes and +saves. Nothing is stored or switched on: each is what POST /api/v1/automations takes, with `enabled` false, so picking +one changes nothing that runs until the person saves it and turns it on. Each starter's checks run in the tests, so a +change to the contract that breaks one fails there.""" + +from __future__ import annotations + +import copy +from typing import Any + + +def _node(nid: str, t: str, **config: Any) -> dict[str, Any]: + return {"id": nid, "type": t, "config": config} + + +def _edge(a: str, b: str) -> dict[str, str]: + return {"source": a, "target": b} + + +def _graph(*steps: dict[str, Any], chain: bool = False) -> dict[str, Any]: + """What happened, then each step: in a row when `chain`, else each straight after it.""" + nodes = [_node("in", "input"), *steps] + edges = [_edge(nodes[i].get("id") if chain else "in", s["id"]) for i, s in enumerate(steps)] + return {"nodes": nodes, "edges": edges} + + +def _notify(nid: str, text: str, to: str = "me") -> dict[str, Any]: + return _node(nid, "action", action="notify", params={"to": to, "text": text}) + + +STARTERS: list[dict[str, Any]] = [ + { + "id": "school-emails", + "name": "Tell me about school emails", + "description": "An email from the school's address tells you in your chat app, and posting it to the family " + "room waits for your yes. Change “school” to the school's address.", + "draft": { + "triggers": [ + { + "as": "mail", + "on": "event", + "kinds": ["email.received"], + "where": {"all": [{"path": "object.from.0", "op": "contains", "value": "school"}]}, + } + ], + "graph": _graph( + _notify("tell", "School email: {{ event.object.subject }}"), + _notify("family", "From school: {{ event.object.subject }}", to="gateway:family"), + ), + }, + }, + { + "id": "router-alerts", + "name": "Router alerts", + "description": "An alert in the router's log tells you, at most once an hour. Change “router” to your sensor's name.", + "draft": { + "triggers": [ + { + "as": "alert", + "on": "event", + "kinds": ["sensor.alert"], + "where": {"all": [{"path": "actor.name", "op": "contains", "value": "router"}]}, + } + ], + "limits": {"max_per_hour": 1}, + "graph": _graph(_notify("tell", "{{ event.summary }}")), + }, + }, + { + "id": "morning-digest", + "name": "Morning digest", + "description": "Every weekday at 7:00 the agent sums up yesterday's timeline items you haven't reviewed, and tells you.", + "draft": { + "triggers": [{"as": "morning", "on": "schedule", "cron": "0 7 * * 1-5", "timezone": "UTC"}], + "graph": _graph( + _node( + "digest", + "action", + action="ask_agent", + params={ + "instructions": "Read yesterday's timeline items I haven't reviewed and sum them up in a few " + "short lines, the ones that need me first." + }, + ), + _notify("tell", "Your morning digest:\n{{ steps.digest.answer }}"), + chain=True, + ), + }, + }, + { + "id": "no-reply", + "name": "No reply in two days", + "description": "An email that asks you something, with no email sent from your mailbox within two days, " + "reminds you. Any email you send in that time calls it off.", + "draft": { + "triggers": [ + { + "as": "mail", + "on": "event", + "kinds": ["email.received"], + "where": {"all": [{"path": "object.snippet", "op": "contains", "value": "?"}]}, + }, + { + "as": "sent", + "on": "event", + "kinds": ["email.received"], + "where": {"all": [{"path": "object.mailbox", "op": "contains", "value": "Sent"}]}, + }, + ], + "join": {"mode": "absent", "after": "mail", "missing": "sent", "within": "2d"}, + "graph": _graph(_notify("remind", "No reply yet to {{ event.object.from.0 }}: {{ event.object.subject }}")), + }, + }, + { + "id": "webhook-note", + "name": "Webhook to note", + "description": "A call to its webhook writes a note with what was sent. Its address shows once you save it.", + "draft": { + "triggers": [{"as": "hook", "on": "webhook"}], + "graph": _graph( + _node( + "note", + "action", + action="write_note", + params={"text": "{{ event.object }}", "title": "From the webhook, {{ now_local }}"}, + ) + ), + }, + }, +] + + +def starters() -> list[dict[str, Any]]: + """Every starter, each with its draft named and switched off, as POST /api/v1/automations takes it.""" + out = [] + for s in STARTERS: + draft = {"name": s["name"], "enabled": False, "join": {"mode": "any"}, **copy.deepcopy(s["draft"])} + out.append({"id": s["id"], "name": s["name"], "description": s["description"], "draft": draft}) + return out diff --git a/fastapi_backend/app/schemas/automation_starters.py b/fastapi_backend/app/schemas/automation_starters.py new file mode 100644 index 00000000..d386df5f --- /dev/null +++ b/fastapi_backend/app/schemas/automation_starters.py @@ -0,0 +1,20 @@ +"""Starter automations (docs/automations.md, Starters): drafts to open in the studio, change and save.""" + +from __future__ import annotations + +from typing import Any + +from pydantic import Field + +from app.schemas.common import ResponseModel + + +class AutomationStarter(ResponseModel): + id: str + name: str + description: str = Field(description="what it does, and what to change before turning it on") + draft: dict[str, Any] = Field(description="what POST /automations takes, switched off") + + +class AutomationStarters(ResponseModel): + starters: list[AutomationStarter] diff --git a/fastapi_backend/tests/api/test_automation_starters.py b/fastapi_backend/tests/api/test_automation_starters.py new file mode 100644 index 00000000..566d19e0 --- /dev/null +++ b/fastapi_backend/tests/api/test_automation_starters.py @@ -0,0 +1,49 @@ +"""Starter automations (docs/automations.md, Starters): every starter is a draft the API saves as it is, switched off, +so picking one changes nothing that runs.""" + +from __future__ import annotations + +from app.domain import automation_starters +from tests.helpers import login, make_user + +URL = "/api/v1/automations" + + +def test_every_starter_saves_as_it_is_and_stays_off(client, db): + make_user(db, "root@x.io", "root password 1", admin=True) + h = login(client, "root@x.io", "root password 1") + r = client.get(f"{URL}/starters", headers=h) + assert r.status_code == 200, r.text + got = r.json()["starters"] + assert [s["id"] for s in got] == [s["id"] for s in automation_starters.STARTERS] + assert {s["id"] for s in got} >= {"school-emails", "router-alerts", "morning-digest", "no-reply", "webhook-note"} + for s in got: + assert s["draft"]["enabled"] is False and s["description"] + saved = client.post(URL, headers=h, json=s["draft"]) + assert saved.status_code == 200, (s["id"], saved.text) + a = client.get(f"{URL}/{saved.json()['id']}", headers=h).json() + assert a["enabled"] is False and a["name"] == s["name"] + # nothing was switched on, and a webhook starter got its address once saved + listed = client.get(URL, headers=h).json()["automations"] + assert len(listed) == len(got) and not any(a["enabled"] for a in listed) + + +def test_starters_are_for_people_signed_in(client): + assert client.get(f"{URL}/starters").status_code == 401 + + +def test_starters_are_copies(client): + first = automation_starters.starters() + first[0]["draft"]["triggers"].clear() + assert automation_starters.starters()[0]["draft"]["triggers"] + + +def test_the_school_starter_tells_me_at_once_and_asks_before_posting_to_the_family(client, db): + make_user(db, "root@x.io", "root password 1", admin=True) + h = login(client, "root@x.io", "root password 1") + school = next(s for s in automation_starters.starters() if s["id"] == "school-emails") + r = client.post(f"{URL}/test", headers=h, json={"draft": school["draft"], "kind": "email.received"}) + assert r.status_code == 200, r.text + by = {i["node"]: i for i in r.json()["intents"]} + assert by["tell"]["status"] == "done" and by["tell"]["risk"] == "routine" + assert by["family"]["status"] == "waiting" and by["family"]["risk"] == "ask" diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index 8ca209fb..51c59477 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -215,6 +215,8 @@ export type { AutomationRuns, AutomationSaved, AutomationStarted, + AutomationStarter, + AutomationStarters, AutomationSwitch, AutomationTried, AutomationTry, @@ -2261,6 +2263,9 @@ export type { ListSpeakersErrors, ListSpeakersResponse, ListSpeakersResponses, + ListStartersData, + ListStartersResponse, + ListStartersResponses, ListTagsData, ListTagsError, ListTagsErrors, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 252ede34..38d3c529 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -1141,6 +1141,8 @@ import type { ListSpeakersData, ListSpeakersErrors, ListSpeakersResponses, + ListStartersData, + ListStartersResponses, ListTagsData, ListTagsErrors, ListTagsResponses, @@ -4359,6 +4361,21 @@ export class Automations { }); } + /** + * List Starters + * + * Starter automations: each a draft to open, change and save (POST /automations), switched off until you turn + * it on. + */ + public static listStarters( + options?: Options, + ): RequestResult { + return (options?.client ?? client).get({ + url: "/api/v1/automations/starters", + ...options, + }); + } + /** * Get Automation Vars * diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 4af7ecec..27824060 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -2132,6 +2132,46 @@ export type AutomationStarted = { [key: string]: unknown; }; +/** + * AutomationStarter + */ +export type AutomationStarter = { + /** + * Id + */ + id: string; + /** + * Name + */ + name: string; + /** + * Description + * + * what it does, and what to change before turning it on + */ + description: string; + /** + * Draft + * + * what POST /automations takes, switched off + */ + draft: { + [key: string]: unknown; + }; + [key: string]: unknown; +}; + +/** + * AutomationStarters + */ +export type AutomationStarters = { + /** + * Starters + */ + starters: Array; + [key: string]: unknown; +}; + /** * AutomationSwitch */ @@ -32565,6 +32605,22 @@ export type CallAutomationHookResponses = { export type CallAutomationHookResponse = CallAutomationHookResponses[keyof CallAutomationHookResponses]; +export type ListStartersData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/automations/starters"; +}; + +export type ListStartersResponses = { + /** + * Successful Response + */ + 200: AutomationStarters; +}; + +export type ListStartersResponse = ListStartersResponses[keyof ListStartersResponses]; + export type GetAutomationVarsData = { body?: never; path: { diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 4c76dd25..d1f8aaa0 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -5667,6 +5667,28 @@ } } }, + "/api/v1/automations/starters": { + "get": { + "tags": [ + "automations" + ], + "summary": "List Starters", + "description": "Starter automations: each a draft to open, change and save (POST /automations), switched off until you turn\nit on.", + "operationId": "list_starters", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AutomationStarters" + } + } + } + } + } + } + }, "/api/v1/automations/{aid}/vars": { "get": { "tags": [ @@ -38927,6 +38949,55 @@ "type": "object", "title": "AutomationStarted" }, + "AutomationStarter": { + "properties": { + "id": { + "type": "string", + "title": "Id" + }, + "name": { + "type": "string", + "title": "Name" + }, + "description": { + "type": "string", + "title": "Description", + "description": "what it does, and what to change before turning it on" + }, + "draft": { + "additionalProperties": true, + "type": "object", + "title": "Draft", + "description": "what POST /automations takes, switched off" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "name", + "description", + "draft" + ], + "title": "AutomationStarter" + }, + "AutomationStarters": { + "properties": { + "starters": { + "items": { + "$ref": "#/components/schemas/AutomationStarter" + }, + "type": "array", + "title": "Starters" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "starters" + ], + "title": "AutomationStarters" + }, "AutomationSwitch": { "properties": { "on": { From ee8ec39f823293db226a0d45cb552338ab698cf5 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 09:20:18 +0000 Subject: [PATCH 2/3] test(automations): prove the email-to-approval journey end to end An email from a mailbox watch (sources._ingest) is email.received; an automation saved over the API matches it when the stream is followed; its ask_model step (stand-in model) feeds a notify to me, done at once, and a notify to a Matterbridge gateway, which waits as an approval; approved over the API it is posted; and the timeline lists the email, the run and the decision linked by cause. Only the model, channels.tell and Matterbridge are stand-ins. Runs in the embedded and the server suites. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01AjJqXgjj1cNdKGRQbX5frb --- .../tests/api/test_automation_journey.py | 191 ++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 fastapi_backend/tests/api/test_automation_journey.py diff --git a/fastapi_backend/tests/api/test_automation_journey.py b/fastapi_backend/tests/api/test_automation_journey.py new file mode 100644 index 00000000..8f58eba1 --- /dev/null +++ b/fastapi_backend/tests/api/test_automation_journey.py @@ -0,0 +1,191 @@ +"""The automations journey end to end (docs/automations.md): an email from a mailbox watch is email.received in the +stream; an automation saved over the API whose trigger matches it runs once when the stream is followed; its model +step answers (a stand-in model), telling me happens at once, and posting to a chat room waits as an approval; approved +over the API it is posted; and the timeline lists the email, the run and the decision, each linked to what caused it. +Only the model, my chat app and the chat-room bridge are stand-ins: everything between is the real code.""" + +from __future__ import annotations + +import time + +import pytest + +from app.domain import automations, channels, events, events_content, sources, store +from tests import fake_llm, fake_matterbridge +from tests.api._assist import start_llm +from tests.helpers import login, make_user + +R = store.R +MAIL = { + "path": "INBOX/7-12.eml", + "title": "School trip on Friday", + "size": 2048, + "modified": "2026-10-15T16:21:58+00:00", + "when": "2026-10-15T16:20:41+00:00", + "key": "message-id:trip@stmarys.org", + "mail": {"from": ["office@stmarys.org"], "to": ["me@x.io"], "subject": "School trip on Friday", "mailbox": "INBOX"}, +} + + +def node(nid, t, **config): + return {"id": nid, "type": t, "config": config} + + +def edge(a, b): + return {"source": a, "target": b} + + +SCHOOL = { + "name": "School emails", + "triggers": [ + { + "as": "mail", + "on": "event", + "kinds": ["email.received"], + "where": {"all": [{"path": "object.from.0", "op": "ends_with", "value": "@stmarys.org"}]}, + } + ], + "graph": { + "nodes": [ + node("i", "input"), + node("ask", "action", action="ask_model", params={"prompt": "Sum up for a parent: {{ event.object.subject }}"}), + node("me", "action", action="notify", params={"to": "me", "text": "School: {{ steps.ask.text }}"}), + node("room", "action", action="notify", params={"to": "gateway:family", "text": "From school: {{ steps.ask.text }}"}), + ], + "edges": [edge("i", "ask"), edge("ask", "me"), edge("ask", "room")], # nothing after an action that reaches out + }, +} + + +@pytest.fixture +def llm(cfg): + srv = start_llm(cfg) + yield fake_llm.Handler + fake_llm.Handler.usage = None + srv.shutdown() + + +@pytest.fixture +def room(): + """Matterbridge's API, keeping what is posted to its gateways.""" + srv, url = fake_matterbridge.start() + fake_matterbridge.Handler.posted = [] + yield fake_matterbridge.Handler, url + srv.shutdown() + + +@pytest.fixture +def app(cfg, db, llm, room): + """The app with the chat-room bridge on, answering as me@x.io (set before the app first reads its settings).""" + from app.main import create_app + + cfg["bridge"] = {**cfg["bridge"], "enabled": True, "url": room[1], "token": "mb-token", "account": "me@x.io"} + return create_app(cfg, db, background=False) + + +@pytest.fixture +def told(monkeypatch): + """My chat app: what channels.tell would send me, kept rather than sent.""" + got = [] + + def tell(db, cfg, account, text, links=()): + got.append({"account": account["id"], "text": text if isinstance(text, str) else text("telegram", {}, {})}) + return {"sent": [{"channel": "telegram", "label": "Telegram", "chat": "private chat with me"}], "failed": [], "error": None} + + monkeypatch.setattr(channels, "tell", tell) + return got + + +@pytest.fixture(autouse=True) +def fresh(): + """Nothing seen, claimed or named in an earlier test carries over.""" + events_content.forget_names() + events._seen.clear() + events._claimed.clear() + automations._swept["at"] = 0.0 + yield + events_content.forget_names() + + +def tick(): + """Wait for the next second, as store.now() counts them: a follower doesn't read the second it started in.""" + start = store.now() + while store.now() == start: + time.sleep(0.05) + + +def mailbox(db, space): + """An IMAP account watched into namespace `space`: (the source, the watch's id).""" + sid = db.next_id("storage_source") + db.q( + "CREATE $r CONTENT $d", r=R("storage_source", sid), d={"name": "Work mail", "type": "imap", "params": {}, "created_at": store.now()} + ) + wid = db.next_id("watch_path") + db.q("CREATE $r CONTENT $d", r=R("watch_path", wid), d={"source": sid, "path": "", "space": space}) + return sources.get(db, sid), wid + + +def test_an_email_runs_an_automation_that_tells_me_asks_before_posting_and_shows_on_the_timeline(client, db, cfg, llm, room, told): + pods = store.ns_id(db, "pods") + me = make_user(db, "me@x.io", "my password 1", roles={"pods": "editor"}) + h = login(client, "me@x.io", "my password 1") + # saved over the API, on from the start, in the namespace I edit + r = client.post("/api/v1/automations", headers=h, json=SCHOOL) + assert r.status_code == 200, r.text + aid = r.json()["id"] + saved = client.get(f"/api/v1/automations/{aid}", headers=h).json() + assert saved["enabled"] and saved["spaces"] == [pods] and saved["run_as"] == me + assert automations.dispatch(db, cfg) == 0 # the first look marks where the follower starts + tick() + + # an email arrives from the mailbox watch: email.received, by the mailbox, in its namespace + src, wid = mailbox(db, pods) + rid, job = sources._ingest(db, cfg, src, MAIL, "document", pods, f"watch:{wid}") + assert job + email = f"create-recording-{rid}" + got = client.get(f"/api/v1/activities/{email}", headers=h).json() + assert got["kind"] == "email.received" and got["space"] == pods and got["actor"]["id"] == f"lens:source/{src['id']}" + assert got["object"]["from"] == ["office@stmarys.org"] and got["object"]["subject"] == "School trip on Friday" + + # following the stream runs the automation once, on that email + assert automations.dispatch(db, cfg) == 1 + [listed] = client.get("/api/v1/automations/runs", headers=h, params={"activity": email}).json() + assert listed["automation"] == aid and listed["event"] == email and listed["trigger"] == "mail" + run = client.get(f"/api/v1/automations/runs/{listed['id']}", headers=h).json() + assert run["status"] == "waiting" and run["counts"] == {"done": 2, "waiting": 1, "scheduled": 0, "failed": 0} + ask, tell, post = run["intents"] + # the model step answered (the stand-in model), with the email's text marked as outside text + assert ask["action"] == "ask_model" and ask["status"] == "done" and ask["result"] == {"text": "OK"} and ask["untrusted"] + assert "School trip on Friday" in ask["params"]["prompt"] and " Date: Sun, 18 Oct 2026 09:25:10 +0000 Subject: [PATCH 3/3] docs(requirements): name the automation journey test Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01AjJqXgjj1cNdKGRQbX5frb --- docs/requirements.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.md b/docs/requirements.md index d353688e..87a3dc45 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -235,6 +235,7 @@ request, to another check that proves the same thing; loosening a requirement or | Each automation has limits and budgets | [test_automation_runs.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_runs.py) `test_the_if_limits_and_dry_runs`, `test_a_run_over_budget_is_held_for_the_persons_pick` | | Agents make, try and run automations over MCP and in the assistant, or draft one from a sentence | [test_automation_tools.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_tools.py) `test_agents_save_try_and_run_automations_over_mcp`, `test_the_assistant_saves_at_once_and_asks_to_switch_on_or_run`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_an_automation_is_drafted_from_a_sentence` | | Starter automations come switched off, each one saving as it is, and changing nothing until someone turns it on | [test_automation_starters.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_starters.py) `test_every_starter_saves_as_it_is_and_stays_off`, `test_the_school_starter_tells_me_at_once_and_asks_before_posting_to_the_family` | +| From an email to a yes: an automation tells you at once, asks before posting to the family, carries the post out on approval, and its run shows on the timeline | [test_automation_journey.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_journey.py) `test_an_email_runs_an_automation_that_tells_me_asks_before_posting_and_shows_on_the_timeline` | | An automation's workflow is drawn and tried on the canvas: its actions in the palette, their settings drawn from each action's params, Decide's ports and the leaf rule | [workflow-canvas.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-canvas.test.ts) `give a decide node a port per option, then unsure`, `keep the leaf rule: nothing after an action that reaches outside Lens or waits`, `say what the backend would reject in their settings`; [automation-nodes-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automation-nodes-ui.test.tsx) `sets an action up from the catalog, its params drawn from its schema`; [schema-form.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/schema-form.test.tsx) `opens the variable picker on {{ and puts the pick in with Enter` | | In the web app, automations are listed with what sets each off in words, and built in When, If and Then with a test on a recent activity, problems next to their fields | [automations-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automations-ui.test.tsx) `the list reads each automation, and Delete is undone from its toast`, `the builder adds a trigger with a condition and an action, then saves it switched off`, `the test panel runs the draft on a recent activity and says what it would do`, `API problems go next to what they are about`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_lists_read_the_triggers_in_words_and_say_when_it_runs_next` | | An automation's page shows its runs a page at a time with each one's log, what's coming up, its variables to edit and its costs | [automation-detail.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automation-detail.test.tsx) `Runs pages back with before, and a run opens to what it did and its log`, `a run held over a budget can run once or be skipped`, `Coming up lists its times, and says why when there are none`, `Variables set from the keyboard, and Clear is undone from its toast` |