From da9ff45c98d6d20dce22a430001e18e1ffb0b738 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 22:28:02 +0000 Subject: [PATCH 1/2] feat(automations): new assets as emails, calendar events, files, uploads, web pages and imports A new asset is now an activity of the most specific kind its row tells: email.received, calendar_event.added, file.added, upload.added, web_page.saved or import.received, all children of asset.added, each with its own fields (who an email was from and to, an event's times and place, a file's path, type and size, a page's site) and outside text marked untrusted. Actors are named from what Lens writes down (sources, watches, people by account or email, import hooks, routines, sensors, automations) in a few queries per page. Mail addressing and event times are kept on the resource when it is made (recording.mail, recording.event), and an email's attachments and the start of its text once it is read, so nothing is parsed on read. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019nbuG2q5wEXeUxWb8vr5HJ --- docs/automations.md | 47 +- docs/database.md | 4 +- fastapi_backend/app/domain/calendars.py | 25 + fastapi_backend/app/domain/convert.py | 16 +- fastapi_backend/app/domain/events_content.py | 619 ++++++++++++++++-- fastapi_backend/app/domain/feeds.py | 4 +- fastapi_backend/app/domain/gmail.py | 2 +- fastapi_backend/app/domain/sources.py | 48 +- fastapi_backend/tests/api/test_activities.py | 6 +- fastapi_backend/tests/domain/test_events.py | 6 +- .../tests/domain/test_events_content.py | 359 ++++++++++ 11 files changed, 1051 insertions(+), 85 deletions(-) create mode 100644 fastapi_backend/tests/domain/test_events_content.py diff --git a/docs/automations.md b/docs/automations.md index 0186a4a00..271103917 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -12,7 +12,8 @@ merged is called built. | Match trees: one condition language for triggers, an automation's If and workflow nodes | 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 | -| More kinds: emails, files, calendar events, jobs, deletions, comments, notes, graph changes, sensors, chat | planned | +| New assets by kind: emails received, calendar events, files from storage, uploads, pages saved from the web, imports | built | +| More kinds: jobs, deletions, calendar moves, comments, notes, graph changes, sensors, chat | planned | | The timeline API (`GET /api/v1/activities`), the MCP tools `timeline` and `event_kinds`, the assistant's `timeline` | built | | The shapes of triggers, joins, an If, policy and intents, checked (`app/domain/automation_spec.py`) | built | | The action registry with risk from each action's effect, and one action, `log_line` (`app/domain/actions.py`) | built | @@ -71,9 +72,32 @@ registered), and whether it is `noisy` (left out of the timeline unless named). then its own), `events.descendants(name)` the kind and every kind under it, and `events.field_at(kind, path)` the schema of one field, whose `title` names it in words (`match.describe(tree, kind)` says "the title contains “call”"). -| Kind | Parent | Source | Object | -| --- | --- | --- | --- | -| `asset.added` | | `recordings` | `{type: Audio, Video, Image or Document, id: lens:recording/, name: its title, url: /resources/, media: audio, video, image, document or transcript, content_type}` | +Every kind's object has `type`, `id`, `name` and `url`; the table lists what each adds. Its fields' titles, a sample +and the paths holding outside text are in `GET /api/v1/activities/kinds` (`event_kinds` over MCP). + +| Kind | Parent | Source | Object | Example summary | +| --- | --- | --- | --- | --- | +| `asset.added` | | `recordings` | `{type: Audio, Video, Image or Document, id: lens:recording/, name: its title, url: /resources/, media: audio, video, image, document or transcript, content_type}` | Lens added “Scan 12” | +| `email.received` | `asset.added` | `recordings` | `from`, `to`, `cc` (addresses), `subject`, `list`, `mailbox`, `date` (sent), `snippet` (the start of its text), `attachments` (how many) | Work mail received “School trip on Friday” from office@stmarys.org | +| `calendar_event.added` | `asset.added` | `recordings` | `startTime`, `endTime`, `location`, `organizer`, `attendees` (addresses), `calendar` | Family calendar added the event “Parents' evening” on 2026-10-20 | +| `file.added` | `asset.added` | `recordings` | `path` (in its source), `mediaType`, `size` (bytes), `duration` (seconds) | Office share added “Minutes” | +| `upload.added` | `asset.added` | `recordings` | `path` (the file's name), `mediaType`, `size`, `duration` | Sam uploaded “Call with the school” | +| `web_page.saved` | `asset.added` | `recordings` | `href` (the page's address), `site` | Sam saved “Museum opening hours” from museum.example.org | +| `import.received` | `asset.added` | `recordings` | `via`: hook (an import hook), paste (pasted text) or file (a file read as text) | Phone shortcut imported “Shopping list” | + +A new asset is one activity, of the most specific kind its row tells, decided by its content type and where it came +from, never by reading its file: an email (content type email, or from an IMAP or Gmail mailbox), a calendar event +(content type calendar_event, or from an iCal feed or Google Calendar), an import hook's, one saved from the web +(webcapture.py, mediaurl.py), a file from a storage source or Drive, an upload, an import (pasted text, a transcript +imported), else `asset.added`. A file an email or archive held, made a resource of its own, stays `asset.added`: the +email is what arrived. A trigger on `asset.added` matches every one of them. + +Fields come from what the row keeps, so reading them costs nothing on the ingest path. A message's addressing is +kept as it is listed (`recording.mail`: who sent it to whom, its subject, list, mailbox, and Gmail's snippet), an +event's times, place and people as it is imported (`recording.event`), and an email's attachments and the start of +its text once it has been read (`recording.email`). Emails and events imported before these were kept have only the +fields their rows had. Outside text (titles, subjects, addresses, snippets, places, file names, page addresses) is +listed in `lens.untrusted`. ### Sources and the event log @@ -91,9 +115,13 @@ so nothing is stored twice: A kind belongs to the source named in its `source`, and a source may list more in `kinds`. Two are built: - `recordings` (`app/domain/events_content.py`) reads `recording` by `created_at`, the id breaking ties, as - `asset.added`. The actor is whoever added it: an automation (its first job was queued by `automation:`), the - storage source a watched file came from (`Service`, `lens:source/`), the person whose upload it was (`Person`, - `lens:account/`), or Lens (a folder scan). + `asset.added` and its children (Kinds, above). The actor is whoever added it: an automation (its first job was + queued by `automation:`), the storage source or mailbox it came from (`Service`, `lens:source/`), an import + hook (`Service`, `lens:import_hook/`), the person whose upload, clip or import it was (`Person`, + `lens:account/`, or `lens:email/
` for someone who isn't an account), a sensor's digest (`Service`, + `lens:sensor/`), or Lens (a folder scan). `events_content.actors(db, labels)` names them the way Lens writes + them down (an account id, an email, `watch:`, `routine:`, `import_hook:`, `automation:`, ...), + in a few queries for a whole page, and keeps names for 30 seconds. - `log` reads `event_log`: activities no row of their own records (a deletion, a webhook call), written by `events.emit(db, kind, *, actor, obj, space, summary, target=None, tag=None, key=None, published=None, spaces=None, audience=None, owner=None, untrusted=None)`, which gives the id (`log-`). Emitting a `key` again changes @@ -260,3 +288,8 @@ worked out, it counts as `out`. An action's own `risk` function may make it stri no row records; pushing instead of polling. - People given only some collections of a namespace see that namespace's activities about those collections. - Name an automation actor by its automation's name once automations are stored. +- A timeline page filtered to one child of `asset.added` (only emails, say) reads every new asset and keeps those of + that kind, up to five source pages; narrow it in the query (path, `remote`, `web`) if that proves slow. +- Folder scans of a namespace's own folders as `file.added`; uploaded `.ics` files with their event's fields; a + snippet for IMAP messages before they are read (it needs the message body). +- Per-recipient threading of email conversations; entity tags on new assets once extraction runs at ingest. diff --git a/docs/database.md b/docs/database.md index 4382d9bd5..9c85e329e 100644 --- a/docs/database.md +++ b/docs/database.md @@ -73,7 +73,9 @@ kept anyway, such as `recording.created_at`. What no row records goes in `event_ `published`, kept for `events.keep_days`), with the keys it was emitted with in `event_log_key:`. Each consumer of the stream keeps where its next look starts in `event_cursor:` (a position per source), and claims what it handles in `event_claim:`; a claim is a `CREATE` only one process wins, and claims go -after a day. +after a day. So that it can be read without opening files, a resource made from an email keeps the message's +addressing as it was listed (`recording.mail`) and one made from a calendar event its times, place and people +(`recording.event`); both are optional, and older resources simply don't have them. ## Upgrades diff --git a/fastapi_backend/app/domain/calendars.py b/fastapi_backend/app/domain/calendars.py index 8203be6b0..9a249d2aa 100644 --- a/fastapi_backend/app/domain/calendars.py +++ b/fastapi_backend/app/domain/calendars.py @@ -378,6 +378,31 @@ def event_text(event): return "\n".join([f"# {title}", "", *head, *([""] + [desc] if desc else [])]) + "\n" +def _address(value): + return re.sub(r"^mailto:", "", (value or "").strip(), flags=re.I).strip().lower() or None + + +def details(raw, calendar=None): + """What an automation or the timeline reads of a calendar's first event (an event's own .ics), kept on its + resource as `event`: {uid, startTime, endTime, location, organizer, attendees, calendar}; None for no event.""" + events = parse(raw)["events"] + if not events: + return None + ev = events[0] + p, v = first(ev, "DTEND") + _, org = first(ev, "ORGANIZER") + out = { + "uid": key(ev)[:300], + "startTime": iso(start(ev)), + "endTime": iso(when(p, v, ev.get("zones"))), + "location": unescape(first(ev, "LOCATION")[1] or "").strip()[:300] or None, + "organizer": _address(org), + "attendees": [a for a in (_address(v) for _, v in all_of(ev, "ATTENDEE")) if a][:50] or None, + "calendar": (calendar or "")[:200] or None, + } + return {k: v for k, v in out.items() if v is not None} + + def text(raw): """A whole calendar as Markdown, its events in order of when they start (for a .ics file read as a transcript).""" cal = parse(raw) diff --git a/fastapi_backend/app/domain/convert.py b/fastapi_backend/app/domain/convert.py index 2c57850a7..3eaafaedb 100644 --- a/fastapi_backend/app/domain/convert.py +++ b/fastapi_backend/app/domain/convert.py @@ -841,6 +841,19 @@ def _fetch_for(cfg, ext, say): fetch_program(cfg, "chromium", say) +def email_info(e): + """What a resource keeps of an email it was read from (read_eml's shape): its subject, who sent it to whom, when, + how many files were attached, and the start of its text (for the timeline and automations).""" + from .ingest import _html_text + + info = {k: e[k] for k in ("subject", "from", "to", "cc", "date") if e.get(k)} + info["attachments"] = sum(1 for a in e.get("parts") or [] if a.get("attached")) + body = e.get("text") if e.get("text") is not None else _html_text(e.get("html")) + if body and body.strip(): + info["snippet"] = " ".join(body.split())[:300] + return info + + def to_pdf(cfg, src, out, say=None): """Make `out`, the PDF of the document at `src`. Returns what was learnt on the way: {by, title?, email?, attachments?}. Unavailable when the server can't; ValueError when the file can't be read. A program installed @@ -856,8 +869,7 @@ def to_pdf(cfg, src, out, say=None): if ext in (".eml", ".msg"): e = read_msg(path) if ext == ".msg" else read_eml(path) page, attachments = email_page(e) - info = {k: e[k] for k in ("subject", "from", "to", "cc", "date") if e.get(k)} - return {"by": page_pdf(cfg, page, out, via), "title": e["subject"] or None, "email": info, "attachments": attachments} + return {"by": page_pdf(cfg, page, out, via), "title": e["subject"] or None, "email": email_info(e), "attachments": attachments} if ext in store.ARCHIVE_EXT: from . import archives diff --git a/fastapi_backend/app/domain/events_content.py b/fastapi_backend/app/domain/events_content.py index 39e8acbaa..974f2aca9 100644 --- a/fastapi_backend/app/domain/events_content.py +++ b/fastapi_backend/app/domain/events_content.py @@ -1,81 +1,388 @@ -"""Content as activities (docs/automations.md, Sources): the `recordings` source reads the assets Lens keeps (the -`recording` table: audio, video, documents, images, emails, web pages) as `asset.added` activities, by `created_at` -with the id breaking ties, so nothing is stored twice. +"""Content as activities (docs/automations.md, Sources and Kinds): the `recordings` source reads the assets Lens keeps +(the `recording` table: audio, video, documents, images, emails, web pages) by `created_at`, the id breaking ties, so +nothing is stored twice. -Each one's id is `create-recording-`, so it is the same every time it's read. Its actor is whoever added it: an -automation (the asset's first job was queued by `automation:`), the storage source a watched file came from, the -person whose upload it was, or Lens itself (a folder scan). Its object is the asset; its title is outside text. +Each new asset is one activity, `create-recording-`, the same every time it's read, of the most specific kind its +row tells: an email received from a mailbox (`email.received`), a calendar event (`calendar_event.added`), a file +from storage or Drive (`file.added`), an upload (`upload.added`), a page or video saved from the web +(`web_page.saved`), something imported (pasted text, a transcript, an import hook's: `import.received`), else +`asset.added`, their parent. The kind is read from the row's content type, where it came from and who brought it, +never from its file. + +Its actor is whoever brought it: an automation (its first job was queued by `automation:`), the storage source +or mailbox it came from, an import hook, the person whose upload, clip or import it was, or Lens itself (a folder +scan). Labels like `watch:`, a person's email or `routine:` are looked up a page at a time, a few queries for +all of them, and their names kept for NAME_SECONDS (`actors`), so other sources name their actors the same way. + +Mail addressing and an event's times are stored on the recording when it's made (`mail`, `event`: sources.py) and +read from there; an email's own details (`email`: subject, who, a snippet, its attachments) once it's been read. +Older rows without them are read without those fields. """ from __future__ import annotations +import mimetypes +import pathlib import re +import threading +import time +import urllib.parse +import weakref from . import events, store R = store.R -FIELDS = "id AS rid, record::id(id) AS id, space, title, source, media, remote, content_type, created_at" +FIELDS = ( + "id AS rid, record::id(id) AS id, space, title, source, media, remote, content_type, created_at, path, web, engine, " + "created_by, mail, event, email, size, duration_ms, attached_to, sensor, form" +) TYPES = {"audio": "Audio", "video": "Video", "image": "Image", "document": "Document", "transcript": "Document"} AUTOMATION_RX = re.compile(r"^automation:(\d+)$") +LABEL_RX = re.compile(r"^(account|watch|source|routine|import_hook|sensor|automation):(\d+)$") +HOOK_RX = re.compile(r"^import hook: (.{1,80})$") +KEY_RX = re.compile(r"^[A-Za-z0-9_.:@+-]{1,200}$") +UPLOAD_RX = re.compile(r"/uploads/[^/]+/[0-9a-f]{24}/[^/]+$") # uploads.py keeps each upload in // +MAIL_SOURCES = {"imap", "gmail"} +CALENDAR_SOURCES = {"ical", "gcal"} +NAME_SECONDS = 30 # how long a looked-up name is used before it's read again +APPS = { + "assistant": {"type": "Application", "id": "lens:assistant", "name": "Assistant"}, + "mcp": {"type": "Application", "id": "lens:mcp", "name": "An agent (MCP)"}, +} +MOST = {"from": 20, "to": 50, "cc": 50, "attendees": 50} # addresses an activity carries at most -def _sec(t): - """A time as `created_at` is written (store.now(): to the second, +00:00), cut down to the second.""" - return events._parse(t).replace(microsecond=0).isoformat(timespec="seconds") +# ---------- names, a page at a time ---------- +_names: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary() # per database: {(table, key): (when, row)} +_names_lock = threading.Lock() -def _actors(db, rows): - """{recording id: actor} for these rows, in a few queries for all of them.""" - ids = [r["id"] for r in rows] - if not ids: - return {} - first_job: dict = {} - for j in db.rows("SELECT recording, created_by, created_at FROM job WHERE recording IN $ids ORDER BY created_at", ids=ids): - first_job.setdefault(j["recording"], j.get("created_by")) - uploads = {u["recording"]: u for u in db.rows("SELECT recording, account, email FROM upload WHERE recording IN $ids", ids=ids)} - accounts = {u["account"] for u in uploads.values() if isinstance(u.get("account"), int)} - names = { - a["id"]: a.get("name") or a.get("email") - for a in ( - db.rows("SELECT record::id(id) AS id, name, email FROM account WHERE id IN $a", a=[R("account", n) for n in accounts]) - if accounts - else [] - ) - } - srcs = {(r.get("remote") or {}).get("source") for r in rows} - {None} - sources = { - s["id"]: s.get("name") - for s in ( - db.rows("SELECT record::id(id) AS id, name FROM storage_source WHERE id IN $s", s=[R("storage_source", n) for n in srcs]) - if srcs - else [] - ) +def _lookup(db, table, keys, fields="name", by="id"): + """{key: row} for these keys of a table (record ids, or the values of the indexed field `by`), one query for the + ones not looked up in the last NAME_SECONDS.""" + keys = [k for k in dict.fromkeys(keys) if k is not None] + now, out, todo = time.monotonic(), {}, [] + with _names_lock: + mine = _names.setdefault(db, {}) + for k in keys: + hit = mine.get((table, by, k)) + if hit and now - hit[0] < NAME_SECONDS: + if hit[1] is not None: + out[k] = hit[1] + else: + todo.append(k) + if todo: + if by == "id": + rows = db.rows(f"SELECT record::id(id) AS key, {fields} FROM {table} WHERE id IN $k", k=[R(table, k) for k in todo]) + else: + rows = db.rows(f"SELECT record::id(id) AS id, {by} AS key, {fields} FROM {table} WHERE {by} IN $k", k=todo) + got = {r["key"]: r for r in rows} + with _names_lock: + mine = _names.setdefault(db, {}) + if len(mine) > 20000: + mine.clear() + for k in todo: + mine[(table, by, k)] = (now, got.get(k)) + out.update(got) + return out + + +def forget_names(db=None): + """Look every name up again (tests; a rename shows at once).""" + with _names_lock: + if db is None: + _names.clear() + else: + _names.pop(db, None) + + +def _num(v): + return int(v) if isinstance(v, int) and not isinstance(v, bool) else None + + +def actors(db, labels): + """{(label, space): actor} for who did something, as Lens writes it down: an account id, a person's email, + `watch:` and `source:` (a storage source), `routine:`, `import_hook:` or `import hook: ` + (the hook of that namespace), `sensor:`, `automation:`, `assistant` and `mcp`. Anything else, or None, is + Lens. A few queries for all of them.""" + labels = list(dict.fromkeys(labels)) + want: dict[str, set] = { + "account": set(), + "email": set(), + "watch": set(), + "source": set(), + "routine": set(), + "hook": set(), + "name": set(), } - out = {} - for r in rows: - m = AUTOMATION_RX.match(str(first_job.get(r["id"]) or "")) - sid = (r.get("remote") or {}).get("source") - up = uploads.get(r["id"]) + for label, _ in labels: + if _num(label) is not None: + want["account"].add(label) + continue + s = str(label or "") + m = LABEL_RX.match(s) if m: - out[r["id"]] = {"type": "Application", "id": f"lens:automation/{m.group(1)}", "name": f"Automation {m.group(1)}"} - elif sid is not None and re.match(r"^[A-Za-z0-9_.:@+-]{1,200}$", str(sid)): - out[r["id"]] = {"type": "Service", "id": f"lens:source/{sid}", "name": sources.get(sid) or f"Source {sid}"} - elif up and isinstance(up.get("account"), int): - out[r["id"]] = { - "type": "Person", - "id": f"lens:account/{up['account']}", - "name": names.get(up["account"]) or up.get("email") or "Someone", + table, n = m.group(1), int(m.group(2)) + key = { + "account": "account", + "watch": "watch", + "source": "source", + "sensor": "source", + "routine": "routine", + "import_hook": "hook", } - else: - out[r["id"]] = dict(events.LENS) + if table in key: + want[key[table]].add(n) + elif HOOK_RX.match(s): + want["name"].add(HOOK_RX.match(s).group(1)) + elif "@" in s: + want["email"].add(s.strip().lower()) + watches = _lookup(db, "watch_path", want["watch"], "source") + want["source"] |= {w["source"] for w in watches.values() if _num(w.get("source")) is not None} + sources = _lookup(db, "storage_source", want["source"], "name, type") + accounts = _lookup(db, "account", want["account"], "name, email") + people = _lookup(db, "account", want["email"], "name", by="email") + routines = _lookup(db, "routine", want["routine"]) + hooks = _lookup(db, "import_hook", want["hook"], "name, space") + named: dict = {} + if want["name"]: + for h in db.rows("SELECT record::id(id) AS id, name, space FROM import_hook WHERE name IN $n", n=sorted(want["name"])): + named.setdefault(h["name"], []).append(h) + + def service(table, n, name, fallback): + return {"type": "Service", "id": f"lens:{table}/{n}", "name": name or f"{fallback} {n}"} + + def one(label, space): + n = _num(label) + if n is not None: + a = accounts.get(n) + return {"type": "Person", "id": f"lens:account/{n}", "name": (a or {}).get("name") or (a or {}).get("email") or "Someone"} + s = str(label or "").strip() + m = LABEL_RX.match(s) + if m: + table, n = m.group(1), int(m.group(2)) + if table == "automation": + return {"type": "Application", "id": f"lens:automation/{n}", "name": f"Automation {n}"} + if table == "account": + return one(n, space) + if table == "watch": + sid = _num((watches.get(n) or {}).get("source")) + return service("source", sid, (sources.get(sid) or {}).get("name"), "Source") if sid is not None else dict(events.LENS) + if table == "source": + return service("source", n, (sources.get(n) or {}).get("name"), "Source") + if table == "sensor": + return service("sensor", n, (sources.get(n) or {}).get("name"), "Sensor") + if table == "routine": + return {"type": "Application", "id": f"lens:routine/{n}", "name": (routines.get(n) or {}).get("name") or f"Routine {n}"} + return service("import_hook", n, (hooks.get(n) or {}).get("name"), "Import hook") + m = HOOK_RX.match(s) + if m: + found = named.get(m.group(1)) or [] + h = next((h for h in found if h.get("space") == space), found[0] if found else None) + if h: + return service("import_hook", h["id"], h["name"], "Import hook") + return {"type": "Service", "id": "lens:import_hook", "name": m.group(1)} + if s in APPS: + return dict(APPS[s]) + if "@" in s: + p = people.get(s.lower()) + if p: + return {"type": "Person", "id": f"lens:account/{p['id']}", "name": p.get("name") or s} + return {"type": "Person", "id": f"lens:email/{s.lower()}" if KEY_RX.match(s) else "lens:email", "name": s[:200]} + return dict(events.LENS) + + return {(label, space): one(label, space) for label, space in labels} + + +# ---------- what an asset is ---------- +_types: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary() + + +def _content_types(db): + """Every content type (content_types.all_types), kept for NAME_SECONDS.""" + from . import content_types + + now = time.monotonic() + with _names_lock: + hit = _types.get(db) + if hit and now - hit[0] < NAME_SECONDS: + return hit[1] + got = content_types.all_types(db) + with _names_lock: + _types[db] = (now, got) + return got + + +def _content_type(db, r, types): + """The asset's content type key, as content_types.of_recording says it, without a query per asset.""" + from . import content_types + + if r.get("content_type"): + chosen = next((t for t in types if t["key"] == r["content_type"]), None) + if chosen and chosen["base"] == content_types.base_of(r): + return chosen["key"] + t = content_types.recognise(db, r, types) + return t["key"] if t else None + + +def _first_jobs(db, ids): + """{recording: who queued its first job}.""" + out: dict = {} + for j in db.rows("SELECT recording, created_by, created_at FROM job WHERE recording IN $ids ORDER BY created_at", ids=ids): + out.setdefault(j["recording"], j.get("created_by")) return out +def _addresses(v, most): + """Addresses, lowercased, from a list of them or a header's text ("Ann , bob@y.org").""" + import email.utils + + if isinstance(v, str): + v = [a for _, a in email.utils.getaddresses([v])] + out = [str(a).strip().lower() for a in v or [] if isinstance(a, str) and "@" in a] + return list(dict.fromkeys(out))[:most] + + +def _text(v, most=300): + s = " ".join(str(v or "").split()) + return s[:most] or None + + +def _mail(r): + """An email's fields: what its mailbox said when it came (`mail`), else what reading it found (`email`).""" + mail, got = r.get("mail") if isinstance(r.get("mail"), dict) else {}, r.get("email") if isinstance(r.get("email"), dict) else {} + box = mail.get("mailbox") + return store.clean( + { + "from": _addresses(mail.get("from") or got.get("from"), MOST["from"]) or None, + "to": _addresses(mail.get("to") or got.get("to"), MOST["to"]) or None, + "cc": _addresses(mail.get("cc") or got.get("cc"), MOST["cc"]) or None, + "subject": _text(mail.get("subject") or got.get("subject") or r.get("title")), + "list": _text(mail.get("list"), 200), + "mailbox": _text(", ".join(str(b) for b in box) if isinstance(box, list) else box, 200), + "date": got.get("date") or mail.get("date"), + "snippet": _text(mail.get("snippet") or got.get("snippet")), + "attachments": got.get("attachments") if _num(got.get("attachments")) is not None else None, + } + ) + + +def _event(r): + ev = r.get("event") if isinstance(r.get("event"), dict) else {} + return store.clean( + { + "startTime": ev.get("startTime"), + "endTime": ev.get("endTime"), + "location": _text(ev.get("location"), 300), + "organizer": _text(ev.get("organizer"), 200), + "attendees": [str(a)[:200] for a in ev.get("attendees") or []][: MOST["attendees"]] or None, + "calendar": _text(ev.get("calendar"), 200), + } + ) + + +def _file(r, kind): + """A file's fields: its name in its source (or the name it was uploaded with), media type, size and length.""" + remote = r.get("remote") or {} + path = remote.get("path") if kind == "file.added" else pathlib.PurePosixPath(str(r.get("path") or "")).name + media_type = mimetypes.guess_type(str(path or ""))[0] + return store.clean( + { + "path": str(path)[:500] if path else None, + "mediaType": media_type, + "size": _num(r.get("size")), + "duration": round(r["duration_ms"] / 1000, 3) if isinstance(r.get("duration_ms"), (int, float)) and r["duration_ms"] else None, + } + ) + + +def _web(r): + url = str((r.get("web") or {}).get("url") or "") + return store.clean({"href": url[:2000] or None, "site": (urllib.parse.urlsplit(url).hostname or None) if url else None}) + + +def _imported(r, actor): + """How an import came: an import hook, pasted text, or a file read as text.""" + if actor["id"].startswith("lens:import_hook"): + return "hook" + path = str(r.get("path") or "") + return "paste" if path.startswith("paste:") else "file" + + +def _kind(r, ctype, source_type, actor): + """The most specific kind the row tells (module docstring).""" + if r.get("attached_to"): + return "asset.added" # a file an email or archive held: the email is what arrived + if ctype == "email" or source_type in MAIL_SOURCES: + return "email.received" + if ctype == "calendar_event" or source_type in CALENDAR_SOURCES: + return "calendar_event.added" + if actor["id"].startswith("lens:import_hook"): + return "import.received" + if (r.get("web") or {}).get("url"): + return "web_page.saved" + if (r.get("remote") or {}).get("source") is not None: + return "file.added" + if UPLOAD_RX.search(str(r.get("path") or "")): + return "upload.added" + if str(r.get("engine") or "").startswith("import:") or str(r.get("path") or "").startswith(("paste:", "hook:")): + return "import.received" + return "asset.added" + + +def _summary(kind, actor, obj): + who, title = actor["name"], obj["name"][:200] + if kind == "email.received": + sender = (obj.get("from") or [None])[0] + return f"{who} received “{title}”" + (f" from {sender}" if sender else "") + if kind == "calendar_event.added": + start = str(obj.get("startTime") or "") + return f"{who} added the event “{title}”" + (f" on {start[:10]}" if start else "") + if kind == "upload.added": + return f"{who} uploaded “{title}”" + if kind == "web_page.saved": + return f"{who} saved “{title}”" + (f" from {obj['site']}" if obj.get("site") else "") + if kind == "import.received": + return f"{who} imported “{title}”" + return f"{who} added “{title}”" + + +def _label_of(r, first, upload): + """Who brought it, as Lens wrote it down, in the order that says most: an automation, the storage source, whoever + made it (a web clip's person), the upload's account, a sensor, then whoever queued its first job.""" + if AUTOMATION_RX.match(str(first or "")): + return first + sid = (r.get("remote") or {}).get("source") + if _num(sid) is not None: + return f"source:{sid}" + if r.get("created_by"): + return r["created_by"] + if upload and (upload.get("account") is not None or upload.get("email")): + return upload["account"] if upload.get("account") is not None else upload["email"] + if _num(r.get("sensor")) is not None: + return f"sensor:{r['sensor']}" + return first + + def _activities(db, rows): - """The rows as asset.added activities (a row whose created_at isn't a time is skipped).""" + """The rows as activities of their kinds (a row whose created_at isn't a time is skipped).""" from . import render - who = _actors(db, rows) + rows = [r for r in rows if r] + ids = [r["id"] for r in rows] + if not ids: + return [] + first = _first_jobs(db, ids) + uploads = {u["recording"]: u for u in db.rows("SELECT recording, account, email FROM upload WHERE recording IN $ids", ids=ids)} + labels = {r["id"]: (_label_of(r, first.get(r["id"]), uploads.get(r["id"])), r.get("space")) for r in rows} + who = actors(db, labels.values()) + srcs = _lookup( + db, + "storage_source", + [(r.get("remote") or {}).get("source") for r in rows if _num((r.get("remote") or {}).get("source")) is not None], + "name, type", + ) + types = _content_types(db) out = [] for r in rows: try: @@ -84,24 +391,35 @@ def _activities(db, rows): continue media = render.kind(r) title = " ".join(str(r.get("title") or "").split()) or "Untitled" - actor = who[r["id"]] - obj = store.clean( - { - "type": TYPES.get(media, "Document"), - "id": f"lens:recording/{r['id']}", - "name": title, - "url": f"/resources/{r['id']}", - "media": media, - "content_type": r.get("content_type") if isinstance(r.get("content_type"), str) else None, - } - ) + actor = who[labels[r["id"]]] + ctype = _content_type(db, r, types) + kind = _kind(r, ctype, (srcs.get((r.get("remote") or {}).get("source")) or {}).get("type"), actor) + obj = { + "type": TYPES.get(media, "Document"), + "id": f"lens:recording/{r['id']}", + "name": title, + "url": f"/resources/{r['id']}", + "media": media, + "content_type": ctype, + } + if kind == "email.received": + obj.update(_mail(r)) + elif kind == "calendar_event.added": + obj.update(_event(r)) + elif kind in ("file.added", "upload.added"): + obj.update(_file(r, kind)) + elif kind == "web_page.saved": + obj.update(_web(r)) + elif kind == "import.received": + obj["via"] = _imported(r, actor) + obj = store.clean(obj) out.append( events.build( f"create-recording-{r['id']}", - "asset.added", + kind, actor=actor, obj=obj, - summary=f"{actor['name']} added “{title[:200]}”", + summary=_summary(kind, actor, obj), space=r.get("space"), source="recordings", pos=[r["created_at"], r["id"]], @@ -111,8 +429,13 @@ def _activities(db, rows): return out +def _sec(t): + """A time as `created_at` is written (store.now(): to the second, +00:00), cut down to the second.""" + return events._parse(t).replace(microsecond=0).isoformat(timespec="seconds") + + class RecordingsSource(events.Source): - """recording rows as asset.added, read by (created_at, id).""" + """recording rows as asset.added and its children, read by (created_at, id).""" name = "recordings" kinds = ("asset.added",) @@ -152,3 +475,165 @@ def get(self, db, cfg, activity_id): events.register_source(RecordingsSource()) + + +# ---------- the kinds ---------- +def _s(title, typ="string", **more): + return {"type": typ, "title": title, **more} + + +def _addrs(title, item="Address"): + return {"type": "array", "title": title, "items": {"type": "string", "title": item}} + + +def _child(name, label, props, untrusted, sample_actor, sample_obj, summary): + events.kind( + name, + label=label, + source="recordings", + as_type="Create", + object_type="Document", + parent="asset.added", + fields={"object": {"type": "object", "properties": props}}, + untrusted=untrusted, + sample={ + "id": "create-recording-7", + "type": "Create", + "kind": name, + "published": "2026-10-15T16:21:58.000Z", + "actor": sample_actor, + "object": {"id": "lens:recording/7", "url": "/resources/7", **sample_obj}, + "target": None, + "tag": [], + "summary": summary, + "space": 3, + "lens": {"source": "recordings", "pos": ["2026-10-15T16:21:58+00:00", 7], "untrusted": list(untrusted), "cause": None}, + }, + ) + + +FILE_FIELDS = { + "path": _s("File name"), + "mediaType": _s("Media type"), + "size": _s("Size (bytes)", "integer"), + "duration": _s("Length (seconds)", "number"), +} + +_child( + "email.received", + "Email received", + { + "from": _addrs("Sender"), + "to": _addrs("Recipients"), + "cc": _addrs("Copied to"), + "subject": _s("Subject"), + "list": _s("Mailing list"), + "mailbox": _s("Mailbox"), + "date": _s("Sent", format="date-time"), + "snippet": _s("Start of the text"), + "attachments": _s("Attachments", "integer"), + }, + ("object.name", "object.subject", "object.from", "object.to", "object.cc", "object.list", "object.snippet"), + {"type": "Service", "id": "lens:source/12", "name": "Work Gmail"}, + { + "type": "Document", + "name": "School trip on Friday", + "media": "document", + "content_type": "email", + "from": ["office@stmarys.org"], + "to": ["sam@example.org"], + "subject": "School trip on Friday", + "mailbox": "INBOX", + "date": "2026-10-15T16:20:41+00:00", + "snippet": "Dear parents, the trip to the museum leaves at 9 on Friday.", + "attachments": 1, + }, + "Work Gmail received “School trip on Friday” from office@stmarys.org", +) +_child( + "calendar_event.added", + "Calendar event added", + { + "startTime": _s("Starts", format="date-time"), + "endTime": _s("Ends", format="date-time"), + "location": _s("Where"), + "organizer": _s("Organizer"), + "attendees": _addrs("Attendees", "Attendee"), + "calendar": _s("Calendar"), + }, + ("object.name", "object.location", "object.organizer", "object.attendees"), + {"type": "Service", "id": "lens:source/14", "name": "Family calendar"}, + { + "type": "Document", + "name": "Parents' evening", + "media": "transcript", + "content_type": "calendar_event", + "startTime": "2026-10-20T18:00:00+01:00", + "endTime": "2026-10-20T19:30:00+01:00", + "location": "St Mary's School hall", + "organizer": "office@stmarys.org", + "attendees": ["sam@example.org"], + "calendar": "Family calendar", + }, + "Family calendar added the event “Parents' evening” on 2026-10-20", +) +_child( + "file.added", + "File added", + FILE_FIELDS, + ("object.name", "object.path"), + {"type": "Service", "id": "lens:source/9", "name": "Office share"}, + { + "type": "Document", + "name": "Minutes", + "media": "document", + "content_type": "document", + "path": "board/2026-10 minutes.docx", + "mediaType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", + "size": 48213, + }, + "Office share added “Minutes”", +) +_child( + "upload.added", + "Upload added", + FILE_FIELDS, + ("object.name", "object.path"), + {"type": "Person", "id": "lens:account/1", "name": "Sam"}, + { + "type": "Audio", + "name": "Call with the school", + "media": "audio", + "content_type": "meeting_audio", + "path": "Call with the school.m4a", + "mediaType": "audio/mp4", + "size": 5120000, + "duration": 754.2, + }, + "Sam uploaded “Call with the school”", +) +_child( + "web_page.saved", + "Web page saved", + {"href": _s("Page address"), "site": _s("Site")}, + ("object.name", "object.href"), + {"type": "Person", "id": "lens:account/1", "name": "Sam"}, + { + "type": "Document", + "name": "Museum opening hours", + "media": "document", + "content_type": "web_page", + "href": "https://museum.example.org/visit", + "site": "museum.example.org", + }, + "Sam saved “Museum opening hours” from museum.example.org", +) +_child( + "import.received", + "Import received", + {"via": _s("Came as", enum=["hook", "paste", "file"])}, + ("object.name",), + {"type": "Service", "id": "lens:import_hook/2", "name": "Phone shortcut"}, + {"type": "Document", "name": "Shopping list", "media": "transcript", "content_type": "text", "via": "hook"}, + "Phone shortcut imported “Shopping list”", +) diff --git a/fastapi_backend/app/domain/feeds.py b/fastapi_backend/app/domain/feeds.py index 2a595c7c1..bcbef94f9 100644 --- a/fastapi_backend/app/domain/feeds.py +++ b/fastapi_backend/app/domain/feeds.py @@ -305,7 +305,8 @@ def _addresses(h, *names): def _addressing(h, subject, mailbox): """What routing rules (mail_routes.py) look at: who sent it, who it was for (To, Cc, and the address a shared - inbox received it at), its subject, mailing list and mailbox.""" + inbox received it at), its subject, mailing list and mailbox; and who was copied in (Cc) on its own, for the + timeline.""" try: listed = str(h.get("list-id") or "").strip() except (ValueError, TypeError): @@ -313,6 +314,7 @@ def _addressing(h, subject, mailbox): return { "from": _addresses(h, "from"), "to": _addresses(h, "to", "cc", "delivered-to", "x-original-to"), + "cc": _addresses(h, "cc"), "subject": subject, "list": listed, "mailbox": mailbox, diff --git a/fastapi_backend/app/domain/gmail.py b/fastapi_backend/app/domain/gmail.py index 373fbc83e..92859b2f9 100644 --- a/fastapi_backend/app/domain/gmail.py +++ b/fastapi_backend/app/domain/gmail.py @@ -227,7 +227,7 @@ def _entry(m, label, names, mark): sent or arrived, key=f"message-id:{msgid}" if msgid else None, cursor=mark, - mail=feeds._addressing(h, subject, shown), + mail={**feeds._addressing(h, subject, shown), "snippet": " ".join(str(m.get("snippet") or "").split())[:300]}, settled=True, # a message is whole once Gmail lists it: no waiting for it to settle ) diff --git a/fastapi_backend/app/domain/sources.py b/fastapi_backend/app/domain/sources.py index 389d4901a..b7a19b0f3 100644 --- a/fastapi_backend/app/domain/sources.py +++ b/fastapi_backend/app/domain/sources.py @@ -596,10 +596,19 @@ def _ingest(db, cfg, src, f, kind, space, by, steps=None, pipeline=None, collect if feeds.handles(src) and not feeds.immutable(src): _same_resource(db, space, src["id"], f["path"], ingest.fingerprint(local)) rid = ingest.import_transcript(db, cfg, ns, local, title=title, log=lambda *a: None, collection=collection) + event = _event_of(local, f, src) db.q( "UPDATE $r MERGE $d", r=R("recording", rid), - d=store.clean({"path": shown, "remote": {"source": src["id"], "path": f["path"]}, "recorded_at": f.get("when")}), + d=store.clean( + { + "path": shown, + "remote": {"source": src["id"], "path": f["path"]}, + "recorded_at": f.get("when"), + "mail": _mail_of(f), + "event": event, + } + ), ) return rid, jobs.enqueue(db, rid, steps or None, by=by, pipeline=pipeline) if f.get("key"): # the same message in two mailboxes (a Message-ID) is one resource @@ -609,7 +618,7 @@ def _ingest(db, cfg, src, f, kind, space, by, steps=None, pipeline=None, collect known = db.one("SELECT record::id(id) AS id FROM recording WHERE fp_key = $k", k=f"{space}:{fp}") if known: return known["id"], None - rid = db.next_id("recording") + rid, mail = db.next_id("recording"), _mail_of(f) db.q( "CREATE $r CONTENT $d", r=R("recording", rid), @@ -627,11 +636,46 @@ def _ingest(db, cfg, src, f, kind, space, by, steps=None, pipeline=None, collect "size": f["size"], "status": "new", "created_at": store.now(), + **({"mail": mail} if mail else {}), }, ) return rid, jobs.enqueue(db, rid, steps or None, by=by, pipeline=pipeline) +def _mail_of(f): + """What a mailbox said of a message as it was listed (feeds._addressing: who sent it to whom, its subject, list + and mailbox, a snippet where the server gives one), kept small on its resource as `mail`, for automations and the + timeline (events_content.py) to read without opening the message. None for a file that isn't a message.""" + m = f.get("mail") + if not isinstance(m, dict): + return None + box = m.get("mailbox") + out = { + "from": [str(a)[:200] for a in m.get("from") or []][:20], + "to": [str(a)[:200] for a in m.get("to") or []][:50], + "cc": [str(a)[:200] for a in m.get("cc") or []][:50], + "subject": str(m.get("subject") or "")[:300], + "list": str(m.get("list") or "")[:200], + "mailbox": [str(b)[:200] for b in box][:20] if isinstance(box, list) else str(box or "")[:200], + "date": f.get("when"), + "snippet": " ".join(str(m.get("snippet") or "").split())[:300], + } + return {k: v for k, v in out.items() if v} or None + + +def _event_of(local, f, src): + """A calendar event's times, place and people (calendars.details), kept on its resource as `event`; None for a file + that isn't an event, or one that can't be read.""" + if not str(f.get("path") or "").lower().endswith(".ics"): + return None + from . import calendars + + try: + return calendars.details(pathlib.Path(local).read_text(encoding="utf-8-sig", errors="replace"), src.get("name")) + except (OSError, ValueError): + return None + + def _same_resource(db, space, sid, path, fp): """A calendar event that changed is read again into the resource it already is (found by where it came from), not made a second one: that resource takes the new file's fingerprint, which the import then finds.""" diff --git a/fastapi_backend/tests/api/test_activities.py b/fastapi_backend/tests/api/test_activities.py index f017db9a6..feb6bf59e 100644 --- a/fastapi_backend/tests/api/test_activities.py +++ b/fastapi_backend/tests/api/test_activities.py @@ -33,9 +33,11 @@ def test_the_timeline_lists_new_assets_newest_first(client, db, cfg, folder): page = client.get(URL, headers=env["hr"]).json() assert [a["id"] for a in page["items"]] == [call, pods2, pods1] and page["next"] is None first = page["items"][0] - assert first["kind"] == "asset.added" and first["type"] == "Create" and first["actor"] == events.LENS + # transcripts imported from the command line are imports (a child of asset.added), by Lens + assert first["kind"] == "import.received" and first["type"] == "Create" and first["actor"] == events.LENS + assert first["object"]["via"] == "file" and first["object"]["content_type"] == "text" assert first["object"]["id"] == "lens:recording/" + call.split("-")[-1] and first["lens"]["untrusted"] == ["object.name"] - assert first["summary"].startswith("Lens added “") and sorted(page["namespaces"].values()) == ["calls", "pods"] + assert first["summary"].startswith("Lens imported “") and sorted(page["namespaces"].values()) == ["calls", "pods"] # each person sees their namespaces' alone assert [a["id"] for a in client.get(URL, headers=env["hv"]).json()["items"]] == [pods2, pods1] mine = client.get(URL, headers=env["hc"]).json() diff --git a/fastapi_backend/tests/domain/test_events.py b/fastapi_backend/tests/domain/test_events.py index 720d78c82..2f7253d95 100644 --- a/fastapi_backend/tests/domain/test_events.py +++ b/fastapi_backend/tests/domain/test_events.py @@ -112,12 +112,13 @@ def test_the_catalog_knows_each_kind_its_parents_and_fields(): events.kind( "test_mail.flagged", label="Flagged", source="recordings", as_type="Create", object_type="Document", parent="test_mail.received" ) - assert events.descendants("asset.added") == {"asset.added", "test_mail.received", "test_mail.flagged"} + assert events.descendants("test_mail.received") == {"test_mail.received", "test_mail.flagged"} + assert {"asset.added", "email.received", "test_mail.received", "test_mail.flagged"} <= events.descendants("asset.added") assert events.expand(["test_mail.received"]) == {"test_mail.received", "test_mail.flagged"} and events.expand(None) is None with pytest.raises(ValueError, match="no kind test_nope.x"): events.expand(["test_nope.x"]) info = events.kind_info("asset.added") - assert info["children"] == ["test_mail.received"] and info["source"] == "recordings" and info["type"] == "Create" + assert "test_mail.received" in info["children"] and info["source"] == "recordings" and info["type"] == "Create" assert info["untrusted"] == ["object.name"] and info["sample"]["kind"] == "asset.added" # a child's schema has every activity's fields, its parents' and its own assert events.field_at("test_mail.flagged", "object.subject")["title"] == "Subject" @@ -332,6 +333,7 @@ def test_recordings_are_asset_added_by_whoever_added_them(db, cfg, feed): "name": "Parents' evening", "url": "/resources/" + ids["up"].split("-")[-1], "media": "audio", + "content_type": "audio", # its content type as Lens recognises it, when nobody chose one } assert up["type"] == "Create" and up["kind"] == "asset.added" and up["lens"]["untrusted"] == ["object.name"] for a in (up, share, auto): diff --git a/fastapi_backend/tests/domain/test_events_content.py b/fastapi_backend/tests/domain/test_events_content.py new file mode 100644 index 000000000..05d9b9d0e --- /dev/null +++ b/fastapi_backend/tests/domain/test_events_content.py @@ -0,0 +1,359 @@ +"""Content as activities (docs/automations.md, Kinds): every new asset is an activity of the most specific kind its +row tells (an email received, a calendar event, a file from storage, an upload, a page saved from the web, an import), +with the right actor and the kind's own fields, written the way the real code paths write them.""" + +from __future__ import annotations + +import datetime as dt +import time +from email.message import EmailMessage + +import pytest + +from app.domain import convert, events, events_content, feeds, gmail, import_hooks, ingest, sources, store, uploads, webcapture +from tests.helpers import make_user, write_wav + +R = store.R +ADMIN = events.viewer(1, None, admin=True) +ICS = """BEGIN:VCALENDAR\r +VERSION:2.0\r +BEGIN:VEVENT\r +UID:evening-1@stmarys.org\r +DTSTART:20261020T170000Z\r +DTEND:20261020T183000Z\r +SUMMARY:Parents' evening\r +LOCATION:School hall\\, St Mary's\r +ORGANIZER;CN=School office:mailto:Office@StMarys.org\r +ATTENDEE;CN=Sam:mailto:sam@example.org\r +ATTENDEE:mailto:alex@example.org\r +END:VEVENT\r +END:VCALENDAR\r +""" + + +@pytest.fixture(autouse=True) +def fresh(): + """Names are looked up again in every test (each has its own database), and nothing handled carries over.""" + events_content.forget_names() + events._seen.clear() + events._claimed.clear() + yield + events_content.forget_names() + + +def source(db, name, typ, **params): + sid = db.next_id("storage_source") + db.q("CREATE $r CONTENT $d", r=R("storage_source", sid), d={"name": name, "type": typ, "params": params, "created_at": store.now()}) + return sources.get(db, sid) + + +def watch(db, sid, space): + wid = db.next_id("watch_path") + db.q("CREATE $r CONTENT $d", r=R("watch_path", wid), d={"source": sid, "path": "", "space": space}) + return wid + + +def start(db, cfg, consumer="test.content"): + """A follower's first look marks where it starts: what's made in that second isn't seen, so wait for the next.""" + assert events.follow(db, cfg, consumer)[0] == [] + t = store.now() + while store.now() == t: + time.sleep(0.05) + + +def new(db, cfg, consumer="test.content", kinds=None): + """What a follower sees next.""" + got, commit = events.follow(db, cfg, consumer, kinds=kinds) + commit() + return got + + +def one(db, cfg, rid): + a = events.get(db, cfg, f"create-recording-{rid}", ADMIN) + assert a is not None and events.check_activity(a) + return a + + +def test_an_email_from_a_mailbox_is_email_received(db, cfg): + pods = store.ns_id(db, "pods") + src = source(db, "Work mail", "imap", host="imap.example.org") + wid = watch(db, src["id"], pods) + start(db, cfg) + f = { + "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": ["sam@example.org", "alex@example.org"], + "cc": ["alex@example.org"], + "subject": "School trip on Friday", + "list": "", + "mailbox": "INBOX", + }, + } + rid, job = sources._ingest(db, cfg, src, f, "document", pods, f"watch:{wid}") + assert job and db.one("SELECT mail FROM $r", r=R("recording", rid))["mail"]["from"] == ["office@stmarys.org"] + got = new(db, cfg) + assert [a["id"] for a in got] == [f"create-recording-{rid}"] + a = got[0] + assert a["kind"] == "email.received" and a["type"] == "Create" and a["space"] == pods + assert a["actor"] == {"type": "Service", "id": f"lens:source/{src['id']}", "name": "Work mail"} + o = a["object"] + assert o["id"] == f"lens:recording/{rid}" and o["url"] == f"/resources/{rid}" and o["content_type"] == "email" + assert o["from"] == ["office@stmarys.org"] and o["to"] == ["sam@example.org", "alex@example.org"] and o["cc"] == ["alex@example.org"] + assert o["subject"] == "School trip on Friday" and o["mailbox"] == "INBOX" and o["date"] == "2026-10-15T16:20:41+00:00" + assert "list" not in o and "snippet" not in o and "attachments" not in o # not known until it's been read + assert a["summary"] == "Work mail received “School trip on Friday” from office@stmarys.org" + assert set(a["lens"]["untrusted"]) >= {"object.name", "object.subject", "object.from", "object.snippet"} + # once it's read (documents.py keeps convert.email_info as `email`), its text's start and attachments show + db.q( + "UPDATE $r SET email = $e", + r=R("recording", rid), + e={"subject": "School trip on Friday", "from": "Office ", "attachments": 1, "snippet": "Dear parents"}, + ) + a = one(db, cfg, rid) + assert a["object"]["snippet"] == "Dear parents" and a["object"]["attachments"] == 1 and a["id"] == got[0]["id"] + # a trigger on the parent matches it, and the catalog has its fields + assert events.follow(db, cfg, "test.parent", kinds=["asset.added"])[0] == [] + assert events.field_at("email.received", "object.from.0")["title"] == "Address" + assert events.kind_info("email.received")["parent"] == "asset.added" + + +def test_what_reading_an_email_keeps_and_what_a_mailbox_says(tmp_path): + msg = tmp_path / "trip.eml" + msg.write_bytes( + b"From: School office \r\nTo: sam@example.org\r\nCc: alex@example.org\r\nSubject: School trip\r\n" + b"Date: Thu, 15 Oct 2026 16:20:41 +0000\r\nMIME-Version: 1.0\r\nContent-Type: multipart/mixed; boundary=b\r\n\r\n" + b"--b\r\nContent-Type: text/plain\r\n\r\nDear parents,\r\n\r\n the trip leaves at 9.\r\n" + b"--b\r\nContent-Type: application/pdf\r\nContent-Disposition: attachment; filename=form.pdf\r\n\r\n%PDF-1.4\r\n--b--\r\n" + ) + info = convert.email_info(convert.read_eml(msg)) + assert info["subject"] == "School trip" and info["from"] == "School office " and info["cc"] == "alex@example.org" + assert info["attachments"] == 1 and info["snippet"] == "Dear parents, the trip leaves at 9." + # Gmail lists a message with a snippet; Cc is kept apart from To (which routing rules read, Cc included) + entry = gmail._entry( + { + "id": "18c", + "internalDate": "1792080041000", + "sizeEstimate": 900, + "snippet": "Dear parents, the trip", + "payload": { + "headers": [ + {"name": "Subject", "value": "School trip"}, + {"name": "From", "value": "Office "}, + {"name": "To", "value": "sam@example.org"}, + {"name": "Cc", "value": "Alex "}, + ] + }, + }, + "INBOX", + {"INBOX": "Inbox"}, + None, + ) + assert entry["mail"]["snippet"] == "Dear parents, the trip" and entry["mail"]["cc"] == ["alex@example.org"] + assert entry["mail"]["to"] == ["sam@example.org", "alex@example.org"] + assert sources._mail_of(entry) == { + "from": ["office@stmarys.org"], + "to": ["sam@example.org", "alex@example.org"], + "cc": ["alex@example.org"], + "subject": "School trip", + "mailbox": "Inbox", + "date": entry["when"], + "snippet": "Dear parents, the trip", + } + assert sources._mail_of({"path": "a.pdf"}) is None and feeds._addressing(EmailMessage(), "", "INBOX")["cc"] == [] + + +def test_a_calendar_event_is_calendar_event_added_with_its_times(db, cfg, folder): + pods = store.ns_id(db, "pods") + inbox = folder / "inbox" + inbox.mkdir() + (inbox / "evening.ics").write_text(ICS) + src = source(db, "Family calendar", "local") + start(db, cfg) + f = {"path": str(inbox / "evening.ics"), "title": "Parents' evening", "size": len(ICS), "modified": store.now(), "when": None} + rid, _ = sources._ingest(db, cfg, src, f, "transcript", pods, "sam@example.org") + ev = db.one("SELECT event FROM $r", r=R("recording", rid))["event"] + assert ev["uid"] == "evening-1@stmarys.org|" and ev["calendar"] == "Family calendar" + got = new(db, cfg) + a = got[0] + assert [x["id"] for x in got] == [f"create-recording-{rid}"] and a["kind"] == "calendar_event.added" + assert a["actor"]["id"] == f"lens:source/{src['id']}" and a["actor"]["name"] == "Family calendar" + o = a["object"] + assert o["name"] == "Parents' evening" and o["content_type"] == "calendar_event" and o["calendar"] == "Family calendar" + assert o["startTime"] == "2026-10-20T17:00:00+00:00" and o["endTime"] == "2026-10-20T18:30:00+00:00" + assert o["location"] == "School hall, St Mary's" and o["organizer"] == "office@stmarys.org" + assert o["attendees"] == ["sam@example.org", "alex@example.org"] + assert a["summary"] == "Family calendar added the event “Parents' evening” on 2026-10-20" + assert {"object.location", "object.organizer"} <= set(a["lens"]["untrusted"]) + + +def test_a_file_from_storage_is_file_added(db, cfg): + calls = store.ns_id(db, "calls") + src = source(db, "Office share", "s3") + wid = watch(db, src["id"], calls) + f = {"path": "board/minutes.pdf", "size": 48213, "modified": "2026-10-15T09:00:00+00:00"} + rid, _ = sources._ingest(db, cfg, src, f, "document", calls, f"watch:{wid}") + a = one(db, cfg, rid) + assert a["kind"] == "file.added" and a["actor"] == {"type": "Service", "id": f"lens:source/{src['id']}", "name": "Office share"} + o = a["object"] + assert o["name"] == "minutes" and o["path"] == "board/minutes.pdf" and o["mediaType"] == "application/pdf" and o["size"] == 48213 + assert o["type"] == "Document" and o["media"] == "document" and "duration" not in o + assert a["summary"] == "Office share added “minutes”" and set(a["lens"]["untrusted"]) == {"object.name", "object.path"} + + +def test_an_upload_is_upload_added_by_whoever_uploaded_it(db, cfg, folder): + sam = make_user(db, "sam@example.org", "sam password 1", roles={"pods": "editor"}) + db.q("UPDATE $r SET name = 'Sam'", r=R("account", sam)) + wav = folder / "call.wav" + write_wav(wav, seconds=1.5) + up = uploads.take(db, cfg, "pods", wav, "Call with the school.wav", {"id": sam, "email": "sam@example.org"}) + rid = up["recording"] + a = one(db, cfg, rid) + assert a["kind"] == "upload.added" and a["actor"] == {"type": "Person", "id": f"lens:account/{sam}", "name": "Sam"} + o = a["object"] + assert o["path"] == "Call with the school.wav" and o["mediaType"] in ("audio/x-wav", "audio/wav") and o["duration"] == 1.5 + assert o["size"] > 0 and o["type"] == "Audio" and a["summary"] == "Sam uploaded “Call with the school”" + # finished uploads are forgotten after a day; who uploaded it is still known from its first run's queuer + db.q("DELETE upload") + events_content.forget_names() + assert one(db, cfg, rid)["actor"] == a["actor"] and one(db, cfg, rid)["kind"] == "upload.added" + + +def test_a_page_saved_from_the_web_is_web_page_saved(db, cfg): + pods = store.ns_id(db, "pods") + sam = make_user(db, "sam@example.org", "sam password 1") + rid = webcapture.create(db, pods, "https://museum.example.org/visit?lang=en", "Museum opening hours", by="sam@example.org") + a = one(db, cfg, rid) + assert a["kind"] == "web_page.saved" and a["actor"] == {"type": "Person", "id": f"lens:account/{sam}", "name": "sam"} + assert a["object"]["href"] == "https://museum.example.org/visit?lang=en" and a["object"]["site"] == "museum.example.org" + assert a["object"]["url"] == f"/resources/{rid}" and a["summary"] == "sam saved “Museum opening hours” from museum.example.org" + # someone who isn't an account (any more) is still named, by their address + gone = webcapture.create(db, pods, "https://example.org/", "Example", by="old@example.org") + assert one(db, cfg, gone)["actor"] == {"type": "Person", "id": "lens:email/old@example.org", "name": "old@example.org"} + + +def test_imports_are_import_received_by_their_hook_or_person(db, cfg): + pods = store.ns_id(db, "pods") + hook, _ = import_hooks.create(db, pods, "Phone shortcut") + got = import_hooks.accept_text(db, cfg, import_hooks.get(db, hook["id"]), "Milk, eggs, bread", "Shopping list") + a = one(db, cfg, got["recording"]) + assert a["kind"] == "import.received" and a["actor"] == { + "type": "Service", + "id": f"lens:import_hook/{hook['id']}", + "name": "Phone shortcut", + } + assert a["object"]["via"] == "hook" and a["summary"] == "Phone shortcut imported “Shopping list”" + pasted = ingest.import_text(db, cfg, "pods", "[00:00] Sam: Remember the forms.", title="Note to self") + a = one(db, cfg, pasted) + assert a["kind"] == "import.received" and a["object"]["via"] == "paste" and a["actor"] == events.LENS + + +def test_a_hook_upload_is_an_import(db, cfg): + pods = store.ns_id(db, "pods") + hook, _ = import_hooks.create(db, pods, "Recorder") + wav = uploads.incoming(cfg) / "memo-in" + write_wav(wav, seconds=1) + got = import_hooks.accept_file(db, cfg, import_hooks.get(db, hook["id"]), wav, "memo.wav") + a = one(db, cfg, got["recording"]) + assert a["kind"] == "import.received" and a["actor"]["id"] == f"lens:import_hook/{hook['id']}" and a["actor"]["name"] == "Recorder" + db.q("DELETE upload") # once its upload is forgotten, its first run's queuer ("import hook: Recorder") names the hook + events_content.forget_names() + assert one(db, cfg, got["recording"])["actor"]["id"] == f"lens:import_hook/{hook['id']}" + + +def test_actors_name_who_did_it_in_a_few_queries(db, cfg): + pods = store.ns_id(db, "pods") + ann = make_user(db, "ann@example.org", "ann password 1") + src = source(db, "Drive", "drive") + wid = watch(db, src["id"], pods) + rid = db.next_id("routine") + db.q("CREATE $r CONTENT $d", r=R("routine", rid), d={"name": "Morning digest"}) + labels = [ + (ann, None), + ("ANN@example.org", None), + (f"watch:{wid}", None), + (f"routine:{rid}", None), + ("automation:4", None), + ("assistant", None), + ("analysis", None), + (None, None), + ("watch:999", None), + ] + got = events_content.actors(db, labels) + assert got[(ann, None)] == got[("ANN@example.org", None)] == {"type": "Person", "id": f"lens:account/{ann}", "name": "ann"} + assert got[(f"watch:{wid}", None)] == {"type": "Service", "id": f"lens:source/{src['id']}", "name": "Drive"} + assert got[(f"routine:{rid}", None)] == {"type": "Application", "id": f"lens:routine/{rid}", "name": "Morning digest"} + assert got[("automation:4", None)]["id"] == "lens:automation/4" and got[("assistant", None)]["id"] == "lens:assistant" + assert got[("analysis", None)] == got[(None, None)] == got[("watch:999", None)] == events.LENS + # names are kept a little while (looked up again after NAME_SECONDS, or when forgotten) + db.q("UPDATE $r SET name = 'Shared drive'", r=R("storage_source", src["id"])) + assert events_content.actors(db, [(f"watch:{wid}", None)])[(f"watch:{wid}", None)]["name"] == "Drive" + events_content.forget_names(db) + assert events_content.actors(db, [(f"watch:{wid}", None)])[(f"watch:{wid}", None)]["name"] == "Shared drive" + # an automation that queued an asset's first run is its actor, whatever else the row says + rec = db.next_id("recording") + db.q( + "CREATE $r CONTENT $d", + r=R("recording", rec), + d={"space": pods, "title": "Made by a rule", "source": "document", "web": {"url": "https://x.org/"}, "created_at": store.now()}, + ) + db.q("CREATE job CONTENT $d", d={"recording": rec, "created_by": "automation:9", "created_at": store.now()}) + a = one(db, cfg, rec) + assert a["actor"]["id"] == "lens:automation/9" and a["kind"] == "web_page.saved" + + +def test_an_attachment_made_a_resource_is_an_asset_added(db, cfg): + pods = store.ns_id(db, "pods") + rid = db.next_id("recording") + db.q( + "CREATE $r CONTENT $d", + r=R("recording", rid), + d={ + "space": pods, + "title": "form", + "source": "document", + "path": "/data/uploads/pods/attachment-3-1/form.eml", + "attached_to": {"resource": 3, "file": "1"}, + "created_at": store.now(), + }, + ) + assert one(db, cfg, rid)["kind"] == "asset.added" + + +def _rows(db, n, space, when): + for _ in range(n): + rid = db.next_id("recording") + db.q( + "CREATE $r CONTENT $d", r=R("recording", rid), d={"space": space, "title": f"Scan {rid}", "source": "image", "created_at": when} + ) + + +def test_paging_six_hundred_assets_of_one_second(db, cfg): + pods, calls = store.ns_id(db, "pods"), store.ns_id(db, "calls") + start(db, cfg, "test.many") + when = (dt.datetime.now(dt.UTC) + dt.timedelta(seconds=2)).isoformat(timespec="seconds") + _rows(db, 600, pods, when) + _rows(db, 5, calls, when) + ids = sorted(db.values("SELECT VALUE record::id(id) FROM recording WHERE space = $s", s=pods), reverse=True) + seen, before = [], None + member = events.viewer(7, {pods}) + while True: + p = events.page(db, cfg, member, before, {"kinds": ["asset.added"]}, 50) + seen += [a["id"] for a in p["items"]] + if not p["next"]: + break + before = p["next"] + assert seen == [f"create-recording-{i}" for i in ids] # each once, newest first, the id breaking the tie + assert all(events.get(db, cfg, a, member)["space"] == pods for a in seen[:3]) + # following reads them a page at a time, oldest first, each once + first, commit = events.follow(db, cfg, "test.many", limit=500) + commit() + rest, commit = events.follow(db, cfg, "test.many", limit=500) + commit() + got = [a["id"] for a in first + rest] + assert len(first) == 500 and len(got) == 605 and len(set(got)) == 605 From 09bccc4605b4eda4b4c0e44148b0c1dff6caade8 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 22:35:29 +0000 Subject: [PATCH 2/2] fix(automations): describe an email's attachment count and snippet in the API Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019nbuG2q5wEXeUxWb8vr5HJ --- fastapi_backend/app/schemas/recordings.py | 2 ++ fastapi_backend/tests/api/test_conversion.py | 3 ++- .../app/openapi-client/types.gen.ts | 12 ++++++++++ nextjs-frontend/openapi.json | 24 +++++++++++++++++++ 4 files changed, 40 insertions(+), 1 deletion(-) diff --git a/fastapi_backend/app/schemas/recordings.py b/fastapi_backend/app/schemas/recordings.py index e765711d6..81642fe82 100644 --- a/fastapi_backend/app/schemas/recordings.py +++ b/fastapi_backend/app/schemas/recordings.py @@ -178,6 +178,8 @@ class EmailInfo(ResponseModel): to: str | None = None cc: str | None = None date: str | None = Field(None, description="when it was sent (ISO 8601)") + attachments: int | None = Field(None, description="how many files it carried") + snippet: str | None = Field(None, description="the start of its text, at most 300 characters") class Rendition(ResponseModel): diff --git a/fastapi_backend/tests/api/test_conversion.py b/fastapi_backend/tests/api/test_conversion.py index 0b4cab18a..d2b6148dd 100644 --- a/fastapi_backend/tests/api/test_conversion.py +++ b/fastapi_backend/tests/api/test_conversion.py @@ -162,7 +162,8 @@ def test_an_email_becomes_a_document_and_its_attachments_resources(client, env, why = (CHROME, (db.one("SELECT error FROM $r", r=R("recording", rid)) or {}).get("error")) assert (rec["title"], rec["recorded_at"], rec["status"]) == ("Harbour report", "2026-09-29T09:30:00+01:00", "analyzed"), why sent = {"subject": "Harbour report", "from": "Mara Keane ", "to": "tom@example.org", "cc": None} - assert rec["email"] == {**sent, "date": rec["recorded_at"]} + snippet = "The ships arrived at dawn. The lighthouse keeper wrote twice." + assert rec["email"] == {**sent, "date": rec["recorded_at"], "attachments": 4, "snippet": snippet} assert "The lighthouse keeper wrote twice." in _text(db, rid) # its attachments are its files; those Lens reads are resources of their own, which say where they came from diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 8efef6cb2..25643d6a3 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -4267,6 +4267,18 @@ export type EmailInfo = { * when it was sent (ISO 8601) */ date?: string | null; + /** + * Attachments + * + * how many files it carried + */ + attachments?: number | null; + /** + * Snippet + * + * the start of its text, at most 300 characters + */ + snippet?: string | null; [key: string]: unknown; }; diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index d89e96757..f87400176 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -35981,6 +35981,30 @@ ], "title": "Date", "description": "when it was sent (ISO 8601)" + }, + "attachments": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Attachments", + "description": "how many files it carried" + }, + "snippet": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Snippet", + "description": "the start of its text, at most 300 characters" } }, "additionalProperties": true,