Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
two, before or after a time or within a duration, falls on certain days or times of day, and whether a value changed
since the last activity. Each value is checked when it's saved, and patterns that could tie up the worker are refused
([Operators](docs/automations.md#operators)).
- **Automations look back.** An automation's If can ask whether something like this happened before: activities of
some kinds within a time, from the same sender or about the same thing, at least or at most so many times, looked for
only in the automation's namespaces and only as its person may see them. `changed` in a trigger's where or an If
compares each activity with the last one, and trying an automation keeps nothing
([Looking back](docs/automations.md#looking-back)).
- **Specs from transcripts.** Turn a voice session or a meeting into a technical spec, saved as a note linked to it:
the model writes the spec, then lists every named decision, every "no" and "not that, this", every constraint and
every gap the speaker left to decide later, each with its quote and a link to the moment it was said; a quote the
Expand Down Expand Up @@ -79,6 +84,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
- **Agents follow news feeds.** `subscribe_feed` (MCP and the assistant, admins) follows a feed into a namespace in one
step, checked before it's kept; `news_feeds` lists them and `unsubscribe_feed` stops one
([News feeds](docs/processing.md#news-feeds-rss-and-atom)).
- **Fixed: Lens could freeze after an answer.** When a browser left a streaming answer early, the cleanup of that
stream could wait for a database connection its own thread already held, and every request after it waited too.
A query made inside another on the same thread now runs on that connection
([Concurrency](docs/database.md#concurrency)).

## 0.14.0 <small>October 17, 2026</small> {id="0.14.0"}

Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,8 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
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
on that stream, on a schedule, at a time or when their own webhook is called: they test conditions (text, patterns,
numbers, lists, times, days and whether a value changed), then tell you in
numbers, lists, times, days, whether a value changed and whether something like it happened before in their
namespaces), then tell you in
your own chat app, ask the model or the agent, use a tool, call a web address (its credentials kept sealed), run a
workflow, pipeline or routine, or change assets and notes. A Classify node in a workflow sorts an asset into labels,
content types or topics, acting only on a sure answer. Anything that reaches outside Lens or changes more than what
Expand Down
32 changes: 29 additions & 3 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ merged is called built.
| --- | --- |
| Match trees: one condition language for triggers, an automation's If and workflow nodes | built |
| Operators for times, lists, text patterns and changes (`in`, `matches`, `within`, `changed`...) | built |
| Looking back over the stream in an automation's If (`seen`) | built |
| Activities, the kinds catalog, the event log, following the stream, timeline reads (`app/domain/events.py`) | built |
| New assets as `asset.added` (the `recordings` source) | built |
| New assets by kind: emails received, calendar events, files from storage, uploads, pages saved from the web, imports | built |
Expand Down Expand Up @@ -381,6 +382,27 @@ its items does (as `contains` does), and `not_in` passes when none does. A value
that the oldest go and are counted (`match.dropped(db, automation)`). A `last` value is kept 30 days after it was
last seen; `match.tidy` drops expired rows once an hour, from the routine schedule.

#### Looking back

Built (`match.seen`). An automation's If (and only its If, so testing a trigger's `where` on each new activity stays
cheap) can ask whether something happened before: a `seen` stands where a test would.

```json
{"seen": {"kinds": ["email.received"], "within": "2d", "same": "object.from",
"where": {"path": "object.subject", "op": "matches", "value": "trip|outing"},
"count": {"at_least": 1}}}
```

- It finds activities of `kinds` (and the kinds under them) published in the last `within` before now, passing its
own `where`, and, with `same`, holding the same value at that path as the activity that started the run (the run
context's `event`). That activity itself doesn't count.
- `count` is `{"at_least": n}` (1 when not given), `{"at_most": n}` or both, up to 100: `{"at_most": 0}` reads
"if nothing like it came", as in "if I haven't replied within 2 days".
- It reads at most 200 activities, of the automation's namespaces (`env["spaces"]`) and as the automation's person
(`env["viewer"]`, or `env["account"]`) may see them; `env["db"]` and `env["cfg"]` give the database. Without a database it finds
nothing. Its `where` is tested with the same `env` (so its clock too) and can't test `changed`.
- In words: `at least one of “Email received” in the last 2 days, with the same sender`.

In a workflow, a condition, filter or switch case takes either one test, as before, or a tree in `match`; with a
tree, `path` (when given) is the part of the value the tree tests. Graphs saved before keep running unchanged.

Expand Down Expand Up @@ -1072,7 +1094,8 @@ Each new activity is checked against each trigger that listens for its kind (a w
- an automation made it, unless the trigger says `from_automations`;
- it is the end of a chain of automations setting each other off as long as `automations.max_depth` (3);
- it isn't in one of the automation's namespaces, or the automation's person may not see it;
- the trigger's `where` doesn't match it.
- the trigger's `where` doesn't match it (in the trigger's time zone; a `changed` in it compares with the last
activity the trigger saw).

Then it is claimed (for the automation, trigger and activity together), so it runs each automation once, even with the
API and a worker both following. **`automations.fire(db, cfg, automation_id, alias, activity, events=None, dry=False)`**
Expand All @@ -1081,8 +1104,11 @@ joins); it gives the run's id, or none when nothing ran. A run goes:

1. **Its person**: if the person it acts for lost their account, their admin role (for one that works everywhere) or
the right to edit one of its namespaces, the run fails saying so, and the automation is switched off.
2. **The If**, on the [run context](#run-context). When it is false the run stops there: it counts in
`counters.skipped`, uses up no limit and makes no run and no activity.
2. **The If**, on the [run context](#run-context), with the run's clock and time zone: a `seen` in it looks back in
the automation's namespaces as its person may see, and `changed` compares with what the automation saw last
([Operators](#operators)). The If and the graph's condition, filter and switch nodes share one State a run, so a
node testing what the If tested agrees with it; a dry run keeps nothing. When it is false the run stops there: it
counts in `counters.skipped`, uses up no limit and makes no run and no activity.
3. **Limits**: the automation's `cooldown` (the wait between runs) and `max_per_hour`, then every automation's runs
together this minute (`automations.max_runs_per_minute`, 60). Over one, nothing runs: it counts in
`counters.limited` and says so in the stream (`automation.limited`) at most once an hour.
Expand Down
4 changes: 3 additions & 1 deletion docs/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,9 @@ are in `.upgrade-check/` (on GitHub, the run's `upgrade-check` artifact).
## Concurrency

The handle (`store.DB`) is thread-safe. Against a server it keeps a small pool of connections; the embedded engine has
one connection that queries take turns on. SurrealDB transactions are optimistic: when two touch the same record at
one connection that queries take turns on, which a query made on a thread already inside one (Python closing an
abandoned generator in the middle of a query, say) shares rather than waits for; against a server such a query takes
another connection. SurrealDB transactions are optimistic: when two touch the same record at
once, one fails with a retryable write conflict. The handle retries those automatically, with jittered backoff, for
single statements and for `run()` transactions (which roll back as a whole, so retrying is safe).

Expand Down
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,7 @@ request, to another check that proves the same thing; loosening a requirement or
| They test conditions, then tell you, ask the model or the agent, use a tool, call a web address with sealed credentials, run Lens work, or change assets and notes | [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_actions_messages.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_messages.py) `test_notify_tells_me_in_my_chat_app`; [test_actions_ai.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_ai.py) `test_ask_model_answers_in_text_or_as_the_fields_a_schema_names`, `test_ask_agent_works_on_what_happened_and_saves_the_conversation`, `test_call_tool_reads_as_the_person_and_changes_only_by_asking_them`; [test_actions_web.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_web.py) `test_credentials_in_headers_are_sealed_to_the_automation_and_the_host_and_never_shown`; [test_actions_run.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_run.py) `test_run_workflow_queues_it_on_the_asset_as_the_automation`, `test_run_pipeline_processes_the_asset_again`; [test_actions_lens.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_lens.py) `test_set_field_is_kept_in_the_assets_history_by_the_automation`, `test_write_note_writes_a_page_adds_to_a_things_page_or_notes_an_asset` |
| What reaches outside Lens, or changes more than what set it off, asks first: on the Approvals page or with a yes in chat; agents decline but never approve | [test_automation_spec.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_spec.py) `test_risk_follows_the_effect`; [test_approvals.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_approvals.py) `test_approve_carries_the_action_out_and_the_run_records_it`, `test_agents_over_mcp_list_and_decline_but_never_approve`; [test_approvals_chat.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_approvals_chat.py) `test_a_yes_in_my_chat_decides_an_action_inside_lens`; [approvals-page.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/approvals-page.test.tsx) `groups what waits, puts the first in focus, and Enter approves it` |
| Conditions test text, patterns, numbers, lists, times, days and whether a value changed, checked as they're saved and read in words | [test_match_ops.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_ops.py) `test_each_test_passes_what_it_should`, `test_checks_refuse_values_a_test_cant_use`, `test_a_pattern_reads_a_long_value_only_so_far_and_gives_up_when_slow`, `test_changed_compares_with_the_last_value_seen`, `test_the_added_tests_read_in_words` |
| Conditions look back over what happened in the automation's namespaces, as its person may see it, and compare each activity with the last one; a dry run keeps nothing | [test_match_seen.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_seen.py) `test_seen_finds_what_happened_in_the_window`, `test_an_if_looks_back_and_reads_the_context`, `test_seen_is_only_for_an_automations_if`; [test_automation_conditions.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_conditions.py) `test_the_if_looks_back_in_the_automations_namespaces`, `test_changed_in_a_where_compares_with_the_last_activity`, `test_the_if_and_a_condition_node_agree_and_dry_runs_keep_nothing` |
| 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` |

Expand Down
5 changes: 3 additions & 2 deletions fastapi_backend/app/domain/automation_spec.py
Original file line number Diff line number Diff line change
Expand Up @@ -271,10 +271,11 @@ def check_join(j, aliases=None):

# ---------- If, policy ----------
def check_if(tree):
"""An automation's If, cleaned: a match tree over the run context, whose paths start with one of its keys."""
"""An automation's If, cleaned: a match tree over the run context, whose paths start with one of its keys. It
may look back over what happened (match.py, seen)."""
if tree is None:
return None
out = match.check(tree, "the If")
out = match.check(tree, "the If", lookback=True)
keys = {c[0] for c in CONTEXT}
for p in match.paths(out):
if p.split(".")[0] not in keys:
Expand Down
37 changes: 34 additions & 3 deletions fastapi_backend/app/domain/automations.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
match,
store,
telemetry,
variables,
workflows,
)
from . import activity as activity_mod
Expand Down Expand Up @@ -682,8 +683,9 @@ def run(db, cfg, aid, alias, activity, evs=None, dry=False, by=None, over_budget
auto = {"id": row.get("id"), "name": row["name"], "version": version, "spaces": row.get("spaces")}
trigger = {"as": trig["as"], "on": trig["on"], "timezone": trig.get("timezone")}
ctx = automation_nodes.context(db, cfg, auto, {"id": run_id, "dry": dry}, trigger, activity, evs, person)
env = _env(db, cfg, row, trig["as"], ctx, account, dry)
# the If first: a run it stops uses up no limit, holds no budget and makes no row
if row.get("condition") and not match.test(row["condition"], ctx):
if row.get("condition") and not match.test(row["condition"], ctx, env):
if not dry:
db.q("UPDATE $r SET counters.skipped += 1", r=R("automation", row["id"]))
return {**out, "status": "skipped", "why": "its If was false"}
Expand Down Expand Up @@ -739,7 +741,16 @@ def say(msg):
)
who = f"automation:{row['id']}" if row.get("id") is not None else None
r = flow.Run(
db, cfg, workflows.KITS["event"], ctx, say, dry=dry, user=who, origin={"automation": row.get("id"), "run": run_id}, intents=box
db,
cfg,
workflows.KITS["event"],
ctx,
say,
dry=dry,
user=who,
origin={"automation": row.get("id"), "run": run_id},
intents=box,
env=env,
)
run_refs = [x for x in (who, f"automation_run:{run_id}" if run_id else None) if x]
error = None
Expand Down Expand Up @@ -805,6 +816,21 @@ def say(msg):
return got


def _env(db, cfg, row, alias, ctx, account, dry):
"""What a run's If and its graph's conditions test with (match.test's env): the run's clock and time zone, one
State for `changed` (so the If and a node testing the same thing agree), and its namespaces and person for
looking back (`seen`)."""
return {
"db": db,
"cfg": cfg,
"now": ctx.get("now"),
"timezone": ctx.get("timezone"),
"spaces": row.get("spaces"),
"viewer": _viewer(db, account) if account else None,
"state": match.State(db, row.get("id"), alias, dry=dry or row.get("id") is None),
}


def _failed(db, cfg, row, alias, activity, evs, by, now, why):
"""A run that can't happen because its person lost access: failed, saying why, and the automation switched off."""
run_id = db.next_id("automation_run")
Expand Down Expand Up @@ -921,6 +947,11 @@ def _after(t, since):
return False


def _where_env(db, a, t):
"""What a trigger's where tests with: the trigger's time zone and its own State for `changed`."""
return {"timezone": variables.timezone_of(a, t), "state": match.State(db, a["id"], t["as"])}


def _route(db, cfg, a, t, act, who, sec):
"""One activity against one trigger: the guards, a claim so it's handled once, then on to its run (or a join, or
a timer). How many runs it started."""
Expand All @@ -938,7 +969,7 @@ def _route(db, cfg, a, t, act, who, sec):
return 0
if t["on"] == "webhook" and (act.get("object") or {}).get("hook") != t.get("hook"):
return 0
if t.get("where") and not match.test(t["where"], act):
if t.get("where") and not match.test(t["where"], act, _where_env(db, a, t)):
return 0
if not events.claim(db, CONSUMER, f"{a['id']}|{t['as']}|{act['id']}"):
return 0
Expand Down
Loading
Loading