From a07f6264841b2412b6ac526619ab1ce9bad072cf Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 06:08:48 +0000 Subject: [PATCH 1/2] feat(notifications): tell targets when a routine's run fails or leaves graph changes to review Two new events, routine.failed and routine.proposed, sent through Matterbridge, signed webhooks, Slack and Discord to each namespace a routine runs over. Default events for new targets stay as they were. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AnPBc76gCvHKeWvSLd1L7h --- CHANGELOG.md | 5 + README.md | 3 +- docs/notifications.md | 10 +- docs/processing.md | 4 +- docs/requirements.md | 1 + fastapi_backend/app/domain/notify.py | 93 +++++++++++++++++-- fastapi_backend/app/schemas/notifications.py | 12 ++- .../tests/api/test_notifications.py | 59 ++++++++++++ .../app/openapi-client/types.gen.ts | 10 +- nextjs-frontend/openapi.json | 16 +++- 10 files changed, 194 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0cedf013e..6503a1b38 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version ## Unreleased +- **Routine run alerts.** A routine's run that fails (all its actions, some of them, or one that stops without + finishing) or leaves graph changes to review can now be sent through Matterbridge, to a signed webhook, or to Slack + and Discord: pick the new `routine.failed` and `routine.proposed` events for a namespace's notification target. Each + namespace the routine runs over gets its own message, linking the routine or the run's changes; new targets' default + events are unchanged ([Notifications](docs/notifications.md#events)). - **The upgrade agent starts the code sandbox's gateway.** Settings → Code sandbox → Run the gateway on this machine now works on installs with an upgrade agent: the agent knows the `sandbox` profile and starts or stops its three containers, as it does the MCP runner, the browser and monitoring. An older agent still says to run the line by hand diff --git a/README.md b/README.md index 04f55891d..a51d89e62 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,8 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p [evidence PDFs](docs/api.md#evidence-pdfs), [published feeds](docs/feeds.md); [checks](docs/requirements.md#learn-from-it)) - **Automate it.** Pipelines and workflows on a canvas, routines on a schedule, batch runs over a collection, and - notifications to webhooks, Slack, Discord and Matterbridge. Everything that happens in Lens (new assets, emails, + notifications to webhooks, Slack, Discord and Matterbridge, including when a routine's run fails or leaves graph + changes to review. Everything that happens in Lens (new assets, emails, calendar events, files, feed posts, what people say to Lens, sensor readings, notes, graph changes, runs, budget warnings) is kept as a stream of activities in W3C Activity Streams form, which agents read through the API, MCP and the assistant, and people review on the Timeline page (and Latest on Home), marking what they've seen. Automations act diff --git a/docs/notifications.md b/docs/notifications.md index 5fedca759..176669690 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -1,7 +1,7 @@ # Notifications Lens can tell a chat room or another app when something happens in a namespace: a run finishes or fails, a batch -run finishes, something is added. Each namespace's owners choose where its notifications go (its **targets**) and +run finishes, something is added, a routine's run fails or leaves graph changes to review. Each namespace's owners choose where its notifications go (its **targets**) and which events each target gets, on the namespace's page under **Notifications**. ## Targets @@ -93,14 +93,16 @@ check that the timestamp is recent too, to refuse replays. | `recording.added` | an asset (a recording, document, image or web page) was added, however it came | `recording`, `title`, `source`, `created_at` | | `lens.release` | a new Lens release is out, once per release ([Updates](updates.md)) | `tag`, `name`, `current`, `published_at`, `notes_url` | | `approval.waiting` | an automation's action waits for its person's pick ([Approvals](automations.md#approvals)); one decided before the notifier saw it isn't sent | `approval`, `automation`, `automation_name`, `summary`, `action`, `effect`, `expires_at`, `created_at` | +| `routine.failed` | a [routine](processing.md#routines)'s run failed: all its actions, some of them (`text` says how many), or it stopped without finishing; each namespace the routine runs over gets it | `routine`, `routine_name`, `run`, `trigger`, `status` (`error` or `partly`), `failed` (each failed action's `action` number, `type` and `error`), `actions`, `error`, `started_at`, `finished_at` | +| `routine.proposed` | a routine's run left graph changes to accept or dismiss, counted in each namespace they touch; one whose changes were all decided before the notifier saw it isn't sent | `routine`, `routine_name`, `run`, `trigger`, `status`, `proposed`, `kinds` (`merge`, `link`), `started_at`, `finished_at` | New targets get `job.failed` and `batch.finished`. A batch run's own runs aren't sent one by one: the batch run is, when it finishes. More than five things added to a namespace at once (a watched folder's new files, an import) are one message (`data.recordings`, `data.count`). -`text` is the message chat targets get, and `url` links to the run, batch run, asset or approval in the web app. What -an approval would do holds text its run read from outside Lens, so web addresses in its `text` are broken up -(`hxxps://evil[.]example`), except the web app's own. +`text` is the message chat targets get, and `url` links to the run, batch run, asset, approval, routine or a routine +run's graph changes in the web app. What an approval would do, and a routine's errors, can hold text read from outside +Lens, so web addresses in their `text` are broken up (`hxxps://evil[.]example`), except the web app's own. ## How it's sent diff --git a/docs/processing.md b/docs/processing.md index b9f469e35..cd11ba425 100644 --- a/docs/processing.md +++ b/docs/processing.md @@ -747,7 +747,9 @@ The schedule is a five-field cron expression (minute hour day-of-month month day `@hourly`, `@daily`, `@weekly`, `@monthly`, in a time zone; without one a routine runs only when someone presses Run now. Every 30 seconds, `lens worker` checks (and so does the API process when it runs background work, and `lens watch`); a routine is never started twice at once, and one started in two processes runs once. Each run keeps what every action did and a -log. +log. A run that fails, or leaves graph changes to review, can be sent to a chat room through +Matterbridge or to a webhook: pick `routine.failed` or `routine.proposed` for a namespace's target +([Notifications](notifications.md#events)). ### Organising the graph diff --git a/docs/requirements.md b/docs/requirements.md index 7a4214b31..a7a3e693a 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -181,6 +181,7 @@ request, to another check that proves the same thing; loosening a requirement or | Routines on a schedule | [test_routines.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_routines.py) `test_routines_are_checked_and_run_when_due`, `test_schedules`; [journeys.mjs](https://github.com/adeelahmad/lense/blob/main/ci/clicks/journeys.mjs) `routine-create`; [baseline.json](https://github.com/adeelahmad/lense/blob/main/ci/clicks/baseline.json) `routine-create` ≤ 2 clicks | | Batch runs over a collection | [test_batches.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_batches.py) `test_collections_and_batches` | | Notifications to webhooks, Slack, Discord and Matterbridge | [test_notifications.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notifications.py) `test_owners_manage_targets_and_a_test_is_signed`, `test_runs_that_end_are_sent_once_to_matterbridge` | +| A routine's run that fails or leaves graph changes to review is told through Matterbridge and webhooks, to each namespace it runs over | [test_notifications.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notifications.py) `test_routine_runs_that_fail_or_leave_changes_to_review_are_told` | | Everything that happens is kept as W3C Activity Streams activities, read by agents through the API, MCP and the assistant | [test_events.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_events.py) `test_activities_have_one_shape`; [test_activities.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_activities.py) `test_the_timeline_lists_new_assets_newest_first`, `test_agents_read_the_timeline_too`; [test_news_feed_source.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_news_feed_source.py) `test_a_news_feed_as_a_source` | | The Timeline page and Latest on Home, marking what you've seen | [test_timeline_marks.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_timeline_marks.py) `test_marks_are_set_cleared_and_filter_the_timeline`; [timeline-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/timeline-ui.test.tsx) `Home's Latest card lists what you haven't reviewed` | | Automations act on the stream, on a schedule, at a time or when their own webhook is called | [test_automation_runs.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_runs.py) `test_each_new_activity_runs_each_automation_it_matches_once`, `test_a_schedule_runs_its_automation_when_its_timer_fires`, `test_a_call_to_a_webhook_runs_its_automation`; [test_timer_triggers.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_timer_triggers.py) `test_an_at_trigger_fires_once_then_reads_done` | diff --git a/fastapi_backend/app/domain/notify.py b/fastapi_backend/app/domain/notify.py index 2a4f9311c..252bddd0f 100644 --- a/fastapi_backend/app/domain/notify.py +++ b/fastapi_backend/app/domain/notify.py @@ -10,8 +10,9 @@ {"content"} for Discord). Nothing in the rest of the app calls in here when something happens. A notifier thread in every process that runs -background work (the API's, `lens worker`) reads what changed since it last looked: runs that ended (job.finished_at) -and recordings added (recording.created_at). Each event is claimed once across every process (notify_event:, which only one CREATE wins, in the same transaction that queues it per target in notify_delivery), then sent, with retries. Each source is read in (time, id) order from where the last look stopped, a page at a time; once caught up, a look also reads the last minute again, so a row written just as it looked isn't missed, and the claims @@ -50,6 +51,8 @@ "recording.added": "Something was added", "lens.release": "A new Lens release is out", "approval.waiting": "An automation's action waits for someone's approval", + "routine.failed": "A routine's run failed", + "routine.proposed": "A routine's run left graph changes to review", } DEFAULT_EVENTS = ["job.failed", "batch.finished"] KINDS = { @@ -569,14 +572,23 @@ def _event(kind, key, space, ns, text, url, data): JOB_FIELDS = "recording, space, batch, steps, step_index, status, error, finished_at" REC_FIELDS = "space, title, source, created_at" APPROVAL_FIELDS = "space, summary, automation, origin, intent.action AS action, intent.effect AS effect, expires_at, created_at" +RUN_FIELDS = "routine, trigger, status, results, error, started_at, finished_at" SOURCES = { # source: (table, its time column, the fields read, more to match) - "jobs": ("job", "finished_at", JOB_FIELDS, "AND status IN ['succeeded', 'failed', 'cancelled']"), - "recordings": ("recording", "created_at", REC_FIELDS, ""), - "approvals": ("approval", "created_at", APPROVAL_FIELDS, "AND intent != NONE AND status = 'pending'"), # automations' (approvals.py) + "jobs": ("job", "finished_at", JOB_FIELDS, "AND space IN $sp AND status IN ['succeeded', 'failed', 'cancelled']"), + "recordings": ("recording", "created_at", REC_FIELDS, "AND space IN $sp"), + # automations' (approvals.py) + "approvals": ("approval", "created_at", APPROVAL_FIELDS, "AND space IN $sp AND intent != NONE AND status = 'pending'"), + # routines' (routines.py), which run over namespaces rather than in one: _routine_events says which + "routines": ("routine_run", "finished_at", RUN_FIELDS, "AND (status IN ['error', 'partly'] OR changes.proposed > 0)"), } JOB_EVENTS = {"job.succeeded", "job.failed", "job.cancelled", "batch.finished"} -SOURCE_EVENTS = {"jobs": JOB_EVENTS, "recordings": {"recording.added"}, "approvals": {"approval.waiting"}} +SOURCE_EVENTS = { + "jobs": JOB_EVENTS, + "recordings": {"recording.added"}, + "approvals": {"approval.waiting"}, + "routines": {"routine.failed", "routine.proposed"}, +} def _rows(db, source, pos, floor, spaces, since): @@ -584,7 +596,7 @@ def _rows(db, source, pos, floor, spaces, since): A page that isn't full has caught up, so the rows of the last LOOKBACK seconds (`since`) are read again too, for one written as the last look ran; their claims keep them from being sent twice.""" table, col, fields, more = SOURCES[source] - head = f"SELECT id AS key, record::id(id) AS id, {fields} FROM {table} WHERE {col} > $f AND space IN $sp {more}" + head = f"SELECT id AS key, record::id(id) AS id, {fields} FROM {table} WHERE {col} > $f {more}" page = db.rows( f"{head} AND ({col} > $t OR ({col} = $t AND id > $i)) ORDER BY {col}, key LIMIT {PAGE}", f=floor, @@ -710,6 +722,71 @@ def _approval_events(cfg, rows, names): return out +def _plural(n, one, many): + return f"{n} {one if n == 1 else many}" + + +def _routine_events(db, cfg, rows, spaces, names): + """routine.failed (a routine's run whose actions all or partly failed, or that stopped without finishing) and + routine.proposed (one that left graph changes for someone to accept or dismiss), told to each namespace with + targets that the routine runs over (every one, for a routine over all of them). Changes are counted per namespace + they touch, as they stand now: a run whose proposals were all decided before the notifier saw it isn't sent. Its + errors can hold what the run read from outside Lens, so web addresses in the message are broken up, but Lens's own.""" + from . import untrusted + + owners = { + r["id"]: r + for r in db.rows( + "SELECT record::id(id) AS id, name, namespaces FROM routine WHERE id IN $ids", + ids=[R("routine", i) for i in {r["routine"] for r in rows if isinstance(r.get("routine"), int)}], + ) + } + waiting: dict = {} # run: {space: {kind: proposed changes}} + for c in db.rows("SELECT run, kind, spaces FROM graph_change WHERE run IN $ids AND status = 'proposed'", ids=[r["id"] for r in rows]): + for s in c.get("spaces") or []: + kinds = waiting.setdefault(c["run"], {}).setdefault(s, {}) + kinds[c["kind"]] = kinds.get(c["kind"], 0) + 1 + out = [] + for r in rows: + ro = owners.get(r.get("routine")) + if not ro: + continue # deleted with its runs as the notifier looked + name, over = ro.get("name") or f"Routine {ro['id']}", spaces if ro.get("namespaces") is None else ro["namespaces"] + results = r.get("results") or [] + bad = [ + {"action": k, "type": a.get("type"), "error": a.get("error")} for k, a in enumerate(results, 1) if a.get("status") == "error" + ] + base = { + "routine": ro["id"], + "routine_name": name, + "run": r["id"], + "trigger": r.get("trigger"), + "status": r["status"], + "started_at": r.get("started_at"), + "finished_at": r["finished_at"], + } + for sp in sorted(set(over) & set(spaces)): + ns = names.get(sp) + if r["status"] in ("error", "partly"): + why = "; ".join(f"{b['type']}: {b['error']}" for b in bad[:3]) or r.get("error") or "no reason given" + if r["status"] == "partly": + head = f"{len(bad)} of {_plural(len(results), 'action', 'actions')} of routine “{name}” failed in {ns}" + else: + head = f"Routine “{name}” failed in {ns}" + key = f"routine_run-{r['id']}-{sp}-failed" + data = {**base, "failed": bad, "actions": len(results), "error": r.get("error")} + text = untrusted.defang(f"{head}: {why}", own=[app_url(cfg)]) + out.append(([key], _event("routine.failed", key, sp, ns, text, _link(cfg, f"/routines/{ro['id']}"), data))) + kinds = (waiting.get(r["id"]) or {}).get(sp) + if kinds: + n = sum(kinds.values()) + key = f"routine_run-{r['id']}-{sp}-proposed" + data = {**base, "proposed": n, "kinds": kinds} + text = f"Routine “{name}” left {_plural(n, 'graph change', 'graph changes')} to review in {ns}." + out.append(([key], _event("routine.proposed", key, sp, ns, text, _link(cfg, f"/routines/changes?run={r['id']}"), data))) + return out + + _CLAIMED: dict[str, None] = {} # keys this process knows are claimed, so it doesn't ask the database again _CL = threading.Lock() @@ -810,6 +887,8 @@ def scan(db, cfg): events += _batch_events(db, cfg, bids, spaces, names) elif source == "approvals": events = _approval_events(cfg, rows, names) + elif source == "routines": + events = _routine_events(db, cfg, rows, spaces, names) if rows else [] else: fresh = _unclaimed(db, [f"recording-{r['id']}-added" for r in rows]) events = _added_events(cfg, [r for r in rows if f"recording-{r['id']}-added" in fresh], names) diff --git a/fastapi_backend/app/schemas/notifications.py b/fastapi_backend/app/schemas/notifications.py index e9de93071..9d0a5132b 100644 --- a/fastapi_backend/app/schemas/notifications.py +++ b/fastapi_backend/app/schemas/notifications.py @@ -9,7 +9,17 @@ from app.schemas.common import RequestModel, ResponseModel TargetKind = Literal["webhook", "matterbridge", "slack", "discord"] -EventType = Literal["job.succeeded", "job.failed", "job.cancelled", "batch.finished", "recording.added", "lens.release", "approval.waiting"] +EventType = Literal[ + "job.succeeded", + "job.failed", + "job.cancelled", + "batch.finished", + "recording.added", + "lens.release", + "approval.waiting", + "routine.failed", + "routine.proposed", +] class LastSend(ResponseModel): diff --git a/fastapi_backend/tests/api/test_notifications.py b/fastapi_backend/tests/api/test_notifications.py index b858493f8..2dd7961a7 100644 --- a/fastapi_backend/tests/api/test_notifications.py +++ b/fastapi_backend/tests/api/test_notifications.py @@ -332,3 +332,62 @@ def trickle(): took = time.monotonic() - t0 assert 1 <= took < trickle_for / 2, took srv.close() + + +def test_routine_runs_that_fail_or_leave_changes_to_review_are_told(client, db, env, inbox, monkeypatch): + """A routine's run that fails, or leaves graph changes to review, is told to each namespace it runs over that + has a target for it; changes are counted in the namespaces they touch.""" + from app.domain import organize, routines, workflows + + cfg, pods, calls = env["cfg"], env["pods"], store.ns_id(db, "calls") + events = ["routine.failed", "routine.proposed"] + client.post( + URL, json={"name": "Chat", "kind": "matterbridge", "url": inbox.url, "gateway": "lens", "events": events}, headers=env["ho"] + ) + hook, secret = notify.create(db, cfg, calls, "Ops", "webhook", inbox.url + "/ops", events=["routine.failed"]) + good = workflows.create(db, "Tidy names", organize.DEFAULT_GRAPH, None, "test", "graph") + bad = workflows.create(db, "Judge names", organize.DEFAULT_GRAPH, None, "test", "graph") + + def fake(db_, cfg_, wid, spaces, version, say, origin, propose_only): + if wid == bad: + raise organize.llm.LLMError("500 the model fell over, see https://evil.example/x") + for sp in ([pods], [pods], [pods, calls]): # two merges in pods, a link across pods and calls + cid = db_.next_id("graph_change") + kind = "link" if len(sp) > 1 else "merge" + db_.q("CREATE $r CONTENT $d", r=R("graph_change", cid), d={"kind": kind, "spaces": sp, "status": "proposed", **origin}) + return {}, {"applied": 0, "proposed": 3, "skipped": 0} + + monkeypatch.setattr(organize, "run", fake) + begin(db, cfg) + everywhere = routines.create(db, "Nightly", [{"type": "workflow", "workflow": good}, {"type": "workflow", "workflow": bad}]) + only_pods = routines.create(db, "Pods only", [{"type": "workflow", "workflow": bad}], namespaces=[pods]) + tidy = routines.create(db, "Tidy pods", [{"type": "workflow", "workflow": good}], namespaces=[pods]) + quiet = routines.create(db, "Quiet", [{"type": "workflow", "workflow": good}], namespaces=[pods]) + runs = {rid: routines.run(db, cfg, rid) for rid in (everywhere, only_pods, tidy, quiet)} + db.q("UPDATE graph_change SET status = 'dismissed' WHERE run = $r", r=runs[quiet]) # decided before the notifier looked + + # Nightly: failed and proposed in pods, failed in calls; Pods only: failed in pods; Tidy pods: proposed in pods + assert notify.scan(db, cfg) == 5 + assert notify.scan(db, cfg) == 0 # claimed once + assert notify.deliver_due(db, cfg) == 5 + chat = sorted(inbox.json(i)["text"] for i, g in enumerate(inbox.got) if g["path"] == "/api/message") + assert chat == [ + "1 of 2 actions of routine “Nightly” failed in pods: workflow: LLMError: 500 the model fell over, see hxxps://evil[.]example/x", + "Routine “Nightly” left 3 graph changes to review in pods.", + "Routine “Pods only” failed in pods: workflow: LLMError: 500 the model fell over, see hxxps://evil[.]example/x", + "Routine “Tidy pods” left 3 graph changes to review in pods.", + ] + ops = [g for g in inbox.got if g["path"] == "/ops"] + assert len(ops) == 1 and verify(secret, ops[0]["headers"], ops[0]["body"]) + e = json.loads(ops[0]["body"]) + assert e["type"] == "routine.failed" and e["namespace"] == "calls" and e["data"]["routine_name"] == "Nightly" + assert e["data"]["status"] == "partly" and e["data"]["actions"] == 2 and e["data"]["run"] == runs[everywhere] + assert e["data"]["failed"] == [ + {"action": 2, "type": "workflow", "error": "LLMError: 500 the model fell over, see https://evil.example/x"} + ] + sent = notify.deliveries(db, hook["id"]) + assert [d["event"] for d in sent] == ["routine.failed"] and sent[0]["status"] == "sent" + proposed = next( + json.loads(d["payload"]) for d in db.rows("SELECT payload FROM notify_delivery") if '"routine.proposed"' in d["payload"] + ) + assert proposed["data"]["kinds"] in ({"merge": 2, "link": 1}, {"link": 1, "merge": 2}) and proposed["url"] is None diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 51de46f24..47e1d5c06 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -6697,7 +6697,9 @@ export type EventInfo = { | "batch.finished" | "recording.added" | "lens.release" - | "approval.waiting"; + | "approval.waiting" + | "routine.failed" + | "routine.proposed"; /** * Label */ @@ -14404,6 +14406,8 @@ export type NotifyTarget = { | "recording.added" | "lens.release" | "approval.waiting" + | "routine.failed" + | "routine.proposed" >; /** * Enabled @@ -14487,6 +14491,8 @@ export type NotifyTargetCreate = { | "recording.added" | "lens.release" | "approval.waiting" + | "routine.failed" + | "routine.proposed" > | null; /** * Enabled @@ -14551,6 +14557,8 @@ export type NotifyTargetUpdate = { | "recording.added" | "lens.release" | "approval.waiting" + | "routine.failed" + | "routine.proposed" > | null; /** * Enabled diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index dcfb349c5..d331fb5e3 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -44070,7 +44070,9 @@ "batch.finished", "recording.added", "lens.release", - "approval.waiting" + "approval.waiting", + "routine.failed", + "routine.proposed" ], "title": "Type" }, @@ -57475,7 +57477,9 @@ "batch.finished", "recording.added", "lens.release", - "approval.waiting" + "approval.waiting", + "routine.failed", + "routine.proposed" ] }, "type": "array", @@ -57625,7 +57629,9 @@ "batch.finished", "recording.added", "lens.release", - "approval.waiting" + "approval.waiting", + "routine.failed", + "routine.proposed" ] }, "type": "array" @@ -57756,7 +57762,9 @@ "batch.finished", "recording.added", "lens.release", - "approval.waiting" + "approval.waiting", + "routine.failed", + "routine.proposed" ] }, "type": "array" From b42e3e0e250197ba2d4ed6a0139a9f359d022059 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 07:30:50 +0000 Subject: [PATCH 2/2] docs(readme): list the assistant's answers about Lens itself as built, now that #400 is released Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AnPBc76gCvHKeWvSLd1L7h --- README.md | 6 +++--- docs/requirements.md | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2b3d705fb..74608ada4 100644 --- a/README.md +++ b/README.md @@ -88,11 +88,13 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p cost), opened from its header. It reads answers aloud with a speech provider, macOS `say` or StyleTTS2 on this machine (opt-in), any message in one click. Long conversations are summarised before they fill the model's context, and `/clear` and `/compact` start afresh or summarise now. Conversations title themselves after their first answer, unless - you name them. Each namespace can have its own assistant with + you name them. It answers questions about Lens itself from its docs and this server's own settings, citing the + pages. Each namespace can have its own assistant with its own name, instructions and memory, answering in Telegram and Slack (built in, with voice notes and files), in Discord, Matrix, WhatsApp and other chat rooms through Matterbridge, and by email at an address of its own that you email or forward things to. ([Chat](docs/assistant.md), [web search](docs/assistant.md#web-search-and-reading-pages), [mail, calendars and files](docs/assistant.md#mail-calendars-and-files), [code sandbox](docs/assistant.md#code-sandbox), [answer records](docs/assistant.md#what-each-answer-records), + [questions about Lens](docs/assistant.md#questions-about-lens-itself), [chat rooms](docs/chat-rooms.md), [email](docs/assistant-email.md), [speech providers](docs/speech-providers.md); [checks](docs/requirements.md#ask-and-get-cited-answers)) - **Extend the assistant.** Add tools (a prompt, a web request, a graph drawn on the canvas, or sandboxed Python), @@ -237,8 +239,6 @@ still loading. ([Components](docs/components.md), These are open pull requests, not yet part of Lens: -- **The assistant** answering questions about Lens itself, from its docs and this server - ([#400](https://github.com/adeelahmad/lense/pull/400)). - **Chat:** a conversation exported as Markdown, PDF or JSON ([#474](https://github.com/adeelahmad/lense/pull/474)). - **Pictures:** low-quality images enhanced before they're read ([#479](https://github.com/adeelahmad/lense/pull/479)). - **Web clipper:** signing in, or using your API token, not only an import webhook's diff --git a/docs/requirements.md b/docs/requirements.md index 89ffd8d84..065b45960 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -75,6 +75,7 @@ request, to another check that proves the same thing; loosening a requirement or | Requirement | Checks | |---|---| | A chat assistant on every page | [test_chats.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_chats.py) `test_asking_from_a_page`; [page-chat.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/page-chat.test.tsx); [ask-place.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/ask-place.test.tsx) | +| It answers questions about Lens itself from its docs and this server, for people and agents | [test_lens_help.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_lens_help.py) `test_the_assistant_answers_about_lens_itself`, `test_admins_see_where_each_setting_is`, `test_agents_ask_lens_over_mcp` | | By voice | [assistant-mode.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/assistant-mode.test.tsx) `starts a voice chat from the mic`; [test_voice.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_voice.py) `test_what_is_said_comes_back_as_text` | | It searches by words, and by meaning once search by meaning is set up | [test_chats.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_chats.py) `test_tools_approvals_and_checking`; [test_semantic.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_semantic.py) `test_chat_retrieval_by_meaning`, `test_off_or_unconfigured` | | Answers cite their sources, and only what the person may read | [test_chats.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_chats.py) `test_chat_cites_only_what_you_can_read`; [chat.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/chat.test.tsx) `splits [n], [n, m] and [n][m]` |