AbstractRuntime 0.10.5__tar.gz → 0.12.0__tar.gz

{abstractruntime-0.10.5 → abstractruntime-0.12.0}/CHANGELOG.md

@@ -5,6 +5,119 @@ All notable changes to AbstractRuntime will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.12.0] - 2026-10-27
+
+Requires AbstractCore 2.30.0 or newer (`EmailClient` mailbox verbs; Gmail labels on message summaries) and AbstractMemory 0.3.2 or newer.
+
+First published release since 0.10.6: it also ships the 0.11.0 and 0.11.1 sections below.
+
+### Added
+
+- **Mail verbs for flows**: fixed-verb nodes `mail_search`, `mail_get`, `mail_mark`, `mail_label`, `mail_move`, `mail_delete`, `mail_send`, `mail_reply`, `mail_forward` and `mail_attachment` compile to `TOOL_INVOKE` effects (`mail.*`) the runtime runs on the run's mailbox (default: the trigger's, else the primary; `mailbox` names another by id, or by the address of the run's own or the primary mailbox; `ids` / `id` take one id, one Email record or a list), without an approval prompt and never mintable by a model. Built on AbstractCore 2.28.0's `EmailClient` verbs (`search` with a typed query, `get_many`, `mark`, `label`, `move`, `delete`, `download_attachment`, `session(write=...)`) and `EmailContext.send` / `reply` / `forward` (through `guarded_send`): one connection per verb, reads read-only, mailbox changes and sends refused on a read-only mailbox (`email_mailbox_read_only`). See [Mail verbs for flows](docs/email.md#mail-verbs-for-flows).
+- **Publish to channel**: `EffectType.PUBLISH_EVENT` (node type `publish_event`) with `{channel, type?, title, body?, subject?, data?, alert?}`: the runtime validates it and hands it to the host (`Runtime.set_publish_event_handler`, `handler(run, payload, step_id)` with the effect's idempotency key as `step_id`, the same on a replayed step); the host appends a CloudEvents event with the `channel` extension to the user's stream (and an attention item when `alert`) and returns `{event_id, sequence, alerted}`, the node's result. Channels are free names applications subscribe to. See [Publish to channel](docs/automations.md#publish-to-channel).
+- **The Email record**: one message shape for trigger inputs, samples and the mail verbs: `{id, message_id, mailbox, folder, thread_id, from, to, cc, subject, date, body_text, body_html, attachments: [{index, name, size, type, artifact}], seen, flagged, labels}`. `labels` merges the IMAP keywords with the message's Gmail labels (AbstractCore 2.29.0). The trigger's `messages` use it: their `id` is now the message's locator (`"<uidvalidity>:<uid>:<folder>"`) and the Message-ID moves to `message_id`.
+
+- **Publish to channel: `recipient` and `channels`** (framework ADR-0041 follow-up, Notify me's Who / Where). The `PUBLISH_EVENT` payload gains `recipient` (default `"me"`; a name, so another account can be named later; the host decides) and `channels` (a non-empty list from `tray`, `watch`, `phone`, `email`, `console`, deduplicated in that order; absent or `"all"` = every channel; refused without `alert: true`), validated by `validate_publish` / `normalize_channels` (`DELIVERY_CHANNELS`). Defaults are omitted from the payload the host gets, and `handler(run, payload, step_id)` is unchanged, so older hosts keep working. The visual executor and compiler pass both from the node's pins or, else, its `effectConfig` (`publish_config_defaults`: Notify me saves `effectConfig.channels`). Tests: tests/test_publish_event.py (validation, the host receives the set, the compiled workflow passes the saved choice, a compiled Notify me end to end).
+
+- **RSS 1.0 (RDF) feeds** for `feed.item@1`: `parse_feed` reads `<rdf:RDF>` documents with the RSS 1.0 channel and items (namespace `http://purl.org/rss/1.0/`), stdlib only, into the same item record as RSS 2.0 and Atom: `id` = the item's `rdf:about` (else the link), `published` = Dublin Core `dc:date` (else none), `summary` = `description` (else `content:encoded`), `author` = every `dc:creator`, joined with commas; `title` falls back to `dc:title`. The parsed feed's `kind` is `rss1`. An RDF document without an RSS 1.0 channel is refused (`FeedParseError`, so `feed_unreadable` on the connection). The fetcher also accepts `application/rdf+xml`. Nature (`https://www.nature.com/nature.rss`), Science (`https://www.science.org/rss/news_current.xml`, the journal's table of contents) and Deutsche Welle's RDF feed were refused before and now read.
+
+### Changed
+
+- **Dependency floors**: AbstractCore 2.30.0 (the published successor of 2.27-2.29, with the latest
+  AbstractVoice, AbstractVision, AbstractMusic and Abstract3D plugins) and AbstractMemory 0.3.2.
+
+- **Mail verbs refuse in two plain ways.** A mailbox the person keeps Read only (AbstractCore's explicit `EmailAccount.access`, no longer "has SMTP") refuses `mark`, `label`, `move`, `delete`, `send`, `reply` and `forward` with `email_mailbox_read_only`: "This mailbox is read-only: automations only read it." / "In My email, turn on Read and write for <address> to change it or send from it." A Read and write mailbox without an outgoing server refuses `send`, `reply` and `forward` with the new `email_mailbox_cannot_send`: "This mailbox can't send: it has no outgoing server." / "In My email, add the outgoing server (SMTP) for <address>." Both before connecting.
+
+### Fixed
+
+- **A compiled Publish to channel / Notify me node runs.** The visual compiler adds `resume_to_node` (and the effect type under `type`) to every effect payload; `validate_publish` refused it ("invalid publish request: unknown publish field(s): ['resume_to_node']"), so every Publish to channel and Notify me node of a VisualFlow failed its step, and a node's own `type` pin replaced the effect type the compiler reads. The runtime now strips that envelope before validation (`core/publish.strip_visual_envelope`) and the executor carries the `type` pin as `event_type`.
+- **A process that serves no model does not load one.** `MultiLocalAbstractCoreLLMClient` builds its default client at construction (a warm-up that, for a local MLX default, loads the weights: 15 GB for a 27B model) and again on a default switch. The gateway's split API process builds the same runtime as the runner process, so it loaded a second copy at boot. `set_default_model_warmup(False)` (`integrations.abstractcore.llm_client`, process-wide, no environment variable) defers the default client to its first call; `default_model_warmup()` reads it. Default on: nothing changes for a single process. Tests.
+- **Events reach runs parked by another process.** In a split gateway (`serve --no-runner` + `abstractgateway runner` on one folder) the runner process parks a run in WAITING(EVENT) by re-saving a run it already saved as running, which writes no creation-log line, so the API process's event-wait index never heard of it and an event delivered there missed the waiter (same hole for a run that declared `events_mailbox` later). `JsonFileRunStore` now refreshes both indexes from the store's change signal before every lookup: when the creation log or the folder's mtime moved, or at least every 2 s (`EVENT_INDEX_REFRESH_S`), it stats the running and waiting runs and re-files the ones another process changed. Two stats when nothing moved; own saves never re-read; `event_index_stats()`. Tests: a real second process parks a run, an event delivered in this process resumes it (and the mailbox case); the 2 s floor; no pass when nothing moved.
+- **Run listings come from memory (the trusted run index).** `JsonFileRunStore` answers every listing that is not RUNNING/WAITING or session-scoped (no status, a finished status, `role=`, `automation_id=`, `latest_occurrence_row`: about 61 call sites in the gateway) from its in-memory record of every run's listing fields once one complete pass has read the folder, instead of globbing and stat()ing every run file per call (11,500 files: a 0.25 s pass alone, minutes beside a busy thread). Changes reach it through the store's own writes, the creation log (new line `=<run_id>`: a finished run's file changed, written after publication), a re-read of its RUNNING/WAITING entries when the folder moved, and a background reconciliation (at most every 60 s when the folder or the log moved, at least every 10 min) that repairs and logs any difference. `trust_index=True` (default) / `False` (verify: the scan answers and is compared, `run_index_stats()["shadow_mismatches"]` counts differences); `reconcile_run_index()`; `OffloadingRunStore.run_index_stats()`. Memo hygiene on the way: a scan's read never overwrites a newer entry from this store's own save, a parsed file is memoized with the token of the file actually read (fstat), and the prune keeps entries whose file exists (created after the glob). Tests: differential (2,000 runs, two writers, after every step and after reconciliation), idle minute with zero run-file stats, second process through a store and bypassing the log, shadow mode.
+- **Automation listings read the present, not the history.** `pending_waits` reads the run index's WAITING rows
+  attributed to the automation (occurrences and descendants) instead of walking every occurrence tree, and the new
+  `pending_waits_by_automation` answers a whole page from one read. The new `latest_occurrence(runtime, id)` (the
+  row of `list_occurrences(limit=1)`) reads the controller ledger backwards from its end and stops at the newest
+  admission (`automation_records_newest_first`, a lazy newest-first reader of JSONL ledgers);
+  `list_occurrences` resolves prompt artifacts for the returned page only; `list_attention` reads back to the seen
+  floor only. `normalize_occurrence_output(..., lazy=True)` resolves just the values it reads (an agent's output can
+  hold thousands of offloaded values). `list_automations(..., index_rows=...)` takes controller rows a host already
+  holds, and `automation_generation(run_store)` exposes the change counter to key them on. Measured on a copy of the
+  operator's plane (11,500 run files): the gateway's automations list went from 2.4 s to 0.22 s cold.
+- **Ledger change signal.** `ObservableLedgerStore.change_token()` (a counter every append moves) and
+  `changed_run_ids(token)` (the runs whose ledger grew since, from the last 8,192 appends; `None` beyond), so a periodic
+  reader learns which ledgers grew without re-reading them. Process-local, like the subscriptions. The bounded record
+  behind both stores' `changed_run_ids` is `abstractruntime.storage.change_ring.ChangeRing`.
+- **"Did any run change?" is one stat.** New `JsonFileRunStore.change_token()` (creation-log size + active-index counter,
+  moved by every save, create and delete) and `changed_run_ids(token)` (the runs behind the last 8,192 changes, or
+  `None` when unknown). The gateway runner compared a glob + stat of every run file every 0.5 s instead (32 ms on a
+  warm 11,500-run copy, 0.18 s on the operator's folder): the token costs about 1 µs and reads no file.
+- **A session's artifacts without reading the whole catalog.** New `ArtifactStore.list_session_candidates(session_id, owner_run_id=)`:
+  the artifacts a session may see (owned by its memory run, tagged `session_id`, or tagged `shared`), newest first.
+  `FileArtifactStore` answers from three catalog indexes (two new expression indexes over the tags, built by the first
+  lookup in the caller's thread, never when the store opens): 1-7 ms on a 106k-artifact catalog, where reading the
+  catalog to filter in Python took 3.2 s. A catalog error raises; there is no fallback to reading every artifact.
+- **"Who listens?" no longer reads every automation's run file.** `connection_usage`, `stream_consumers` / `wake_stream_consumers`, `email_trigger_consumers` / `wake_email_automations`, `connection_trigger_consumers` / `wake_connection_automations`, `prune_email_inbox` and the feed poll used to list the whole run index and load every controller run on every call: per connection row, per feed poll, per mailbox poll and per wake (measured on the operator's 11,499-run plane: 0.5 s per call quiet, 2.2 s beside a busy thread, 6-9 s for a 3-connection listing; 190% CPU while idle). They now answer from one **active-consumers index** per runtime (`abstractruntime.automations.consumers`: `{automation_id: trigger}` for the ACTIVE automations), in microseconds. It is rebuilt only when something changed, on the run store's automation generation (`invalidate_active_consumers`, keyed by the store's folder or database file): a JSON-file store bumps it on every save whose controller index row (the automation's status and trigger) is new or different, so any path of the process (a command, a decision, a controller failing or cancelled) is seen at once and ordinary controller saves bump nothing; `create_automation`, every applied automation command and any decision or reconciliation whose delta changes the definition or the `paused` / `exhausted` state bump it explicitly for every store; a 30-second TTL catches another process writing the same folder. A rebuild lists only the RUNNING and WAITING controller rows (a JSON-file store answers from its active index) and reads no run file: a controller's index row now carries `automation_consumer: {status, trigger}` (an older scan sidecar's controller rows are re-parsed once). New `connections_usage(runtime, connections)` answers a list from one snapshot. Answers are unchanged.
+- Trigger messages keep their flags: the mail watcher stores each new message with its `flags` (\\Seen, \\Flagged, IMAP keywords) and Gmail `labels` (AbstractCore 2.29's `MessageSummary.labels`, on a Gmail server) as read, so an occurrence's Email record carries `seen`, `flagged` and `labels` like a sample's (they were null). Nothing else in the payload or the cursor changes.
+
+## [0.11.1] - 2026-10-25
+
+Requires AbstractCore 2.27.0 or newer (`EmailClient.session()` / `get_many()`).
+
+### Added
+
+- **The mail watcher reads a burst of new mail on one connection.** `EmailInboxFeeder.poll` lists and reads the new messages inside one `EmailClient.session()` and reads them with `get_many` (one header FETCH per 100, one body FETCH per text section) instead of one connection per message (~10 s each on a remote server). Payloads, the cursor (advanced message by message, only after each durable append), nothing marked read and the per-message failure count are unchanged; a message that breaks the batch read is read alone so only it fails. Needs AbstractCore with `EmailClient.session` / `get_many` (the release after 2.26.4).
+
+- **Named occurrence inputs for flows**: an automation's occurrence receives its trigger's data as flat, named inputs beside `input_data.event`: `scheduled_at` and `occurrence` (schedules), `messages` and `mailbox` (`email.received@1`; `messages` stored as an artifact like the mail bodies), `items` and `feed` (`feed.item@1`), `calls` (`webhook.received@1`); a manual run adds none. Adapters implement `occurrence_inputs(...)`. A stored webhook call now keeps its headers (lower-cased, without the signature and credentials). The input and output contract (`response`, `success`, `notify`) is documented in [Occurrence inputs and outputs](docs/automations.md#occurrence-inputs-and-outputs-the-flow-contract).
+
+- **Sample inputs for testing a triggered flow**: `sample_occurrence_inputs(runtime, source_id, source_version, config, count=100, principal=...)` returns the named inputs and `event` a real occurrence would receive, from real data and read only: the newest matching messages of the bound mailbox (20-second fetch budget, `truncated`), the latest feed items, the last stored webhook calls (or one documented sample call), `scheduled_at` = now for schedules. The event carries the CloudEvents extension `abstracttest: true`. Mail is read on one IMAP connection (`batched_newest_messages`: AbstractCore's `EmailClient.session()`, `search` and `get_many`; a body over 1 MB is skipped with a typed record, never cut; attachments never downloaded; nothing marked read), so 100 messages take a few round trips. See [Testing a triggered flow](docs/automations.md#testing-a-triggered-flow-with-sample-inputs).
+
+### Changed
+
+- **Feed connections are polled only while something listens.** `TriggerConnection` gains `paused` (default false) and `always_listen` (default false), set through `TriggerConnectionStore.create(...)` / `update(...)`; `status` keeps its meaning. `connection_usage(runtime, connection)` derives `{listening: "paused" | "listening" | "idle", used_by: <active automations reading the stream>}`, and `connection.to_dict(usage=...)` adds both fields. `poll_feed_connections` fetches only listening feed connections (an idle one is not fetched and stores nothing; its first poll after an automation binds again is a baseline) and its reports carry `listening` and `used_by`. `append_webhook_event` refuses a paused connection like a disabled one (409 `connection_disabled`); an idle webhook connection still accepts and stores calls (its `runtime=` argument is accepted and unused). See [Trigger connections](docs/automations.md#trigger-connections).
+- `feed.item@1`'s connection fields read in plain language for forms: "Feed address", "Check every" (a number and a unit), "Most new items per check" and "When added" ("Ignore what is already there" / "Also deliver the latest items", `enumNames`); the field names and values are unchanged.
+
+## [0.11.0] - 2026-10-25
+
+### Added
+
+- **`email.received@1` on a further mailbox** (framework backlog 1044): `config.account` accepts a mailbox id of the user (`"self"`, the default, and `"default"` stay the primary mailbox). The automation reads only that mailbox's inbox streams and its occurrences act for it (`_runtime.email_account` from `email_binding_for_trigger`); `message_matches` checks the mail's `account_ref` too. The descriptor's `account` schema is a pattern with default `"self"` (no longer `enum: ["self"]`). See [The email.received@1 trigger](docs/email.md#the-emailreceived1-trigger).
+
+- **A note wake reaches the person** (framework backlog 1045 follow-up): `SCHEDULE_RUN` takes `notify` (default true for a `note`, false for a `task`); a notifying wake's definition carries `notify.always: true` with `notify.title` (the note) and `notify.body` (the note), so its completed occurrence raises an attention item (kind `notify`, body = the answer, else the note) whatever the answer's own `notify` says. `notify.always` / `title` / `body` are new optional fields of every definition's `notify`. The effect result reports `notify`.
+
+- **Wakes: `EffectType.SCHEDULE_RUN`** (framework backlog 1045): a run schedules work for later (`at`, `after_s` or `on` a trigger event) with a `task` or a reminder `note`, as a new turn of its own session by default (`mode: same_session`) or in a fresh one. The runtime plans a one-shot automation (`automations.wakes.plan_schedule_run`): tools at most the caller's ceiling intersected with the request, never `schedule_run` itself, written as the occurrence's explicit `_runtime.allowed_tools`; approval `ask`, the caller's tool policy copied, untrusted callers make untrusted wakes; `origin_run_id` recorded and the occurrence's origin is `agent`. The host creates it through `Runtime.set_schedule_run_handler` (usually with `create_scheduled_run`) and appends `wake.scheduled` / `wake.cancelled` to the user's stream (`wake_scheduled_event`, `wake_cancelled_event`). Creation requests accept `session_id` (where a growing automation's occurrences run; the controller keeps `automation:<id>`), `origin_run_id`, `one_shot` and `untrusted_origin`; an occurrence's `session_kind` may be `chat`. `schedule_run` is classified as a delegation tool. See [Wakes](docs/automations.md#wakes-schedule_run).
+
+- Several mailboxes per user (framework backlog 1044): `email_binding_for_trigger(binding, trigger)` binds an `email.received@1` automation whose `config.account` names a further mailbox of the same user to that mailbox (`<tenant>:<user>:<account_id>`; `self`, `default` or no value keep the runtime's own binding), with `account_ref_with_id` / `account_id_of_ref` (`abstractruntime.email`).
+
+- **Webhook trigger `webhook.received@1`** (framework backlog 1042, runtime half): a webhook connection with a generated, sealed signing secret (`whsec_…`) or the creator's own, an optional `subject_path` and a replay window. `verify_standard_webhook(secret, headers, body, now, tolerance_s)` checks Standard Webhooks signatures (pure; reference vector tested), and `append_webhook_event(inbox, connection, body, headers)` maps one verified HTTP call to one event on the connection's stream (`webhook-id` as `subject`/`dedupekey`, so a replayed id is refused) and returns the status the host's route answers with (202 / 409 / 401 / 413 / 415). See [`webhook.received@1`](docs/automations.md#webhookreceived1).
+
+- **Feed trigger `feed.item@1`** (framework backlog 1043): runs an automation on new items of an RSS 2.0 or Atom feed connection (`{url, every >= 60s, max_items, initial_items: skip|deliver}`). Standard-library parsing, conditional GET, item identity (Atom id / RSS guid / link) as `subject` and `dedupekey` so each item is appended once, the cursor in the connection stream's state, typed failures on the connection with a capped backoff. The host's plane runs the poller: `poll_feed_connections(runtime, store)` polls the due connections and wakes their automations (no thread started here). The items of one poll become one occurrence, with the items in `input_data.event.data.events` and, for a string prompt, in a fixed untrusted frame. A `network` pytest marker for the live test. See [`feed.item@1`](docs/automations.md#feeditem1).
+
+- **CloudEvents trigger envelope** (framework backlog 1039): `TriggerEnvelope` carries the CloudEvents 1.0 attributes (`specversion`, `id`, `type` = `abstract.<source>.v<version>`, `source`, `time`, `subject`, `datacontenttype`) and extensions (`bindingid`, `connectionid`, `dedupekey`, `sequence`, `recordedtime`, `abstracttrust`; `correlationid`, `expirytime`, `traceparent` reserved) beside its original keys, which stay for this release. Every built-in source populates `subject`, `dedupekey` and `abstracttrust`; schedules add `payload.series = {rule, occurrence, scheduled_at, next_at, coalesced}`. Occurrences receive the envelope as `input_data.event` (`to_cloudevent`; `from_cloudevent` is the inverse; `CLOUDEVENT_JSON_SCHEMA`). The prompt header is unchanged. See [Occurrences](docs/automations.md#occurrences).
+
+- **Run origin** (framework backlog 1038): `vars._meta.origin = {kind: person|trigger|agent|system, actor, client, ref}` records who or what started a run. `abstractruntime.core.run_origin.origin_for(...)` builds it for hosts (person and system runs), `stamp_origin` writes it once and `origin_of` reads it (None for older runs). Every automation occurrence now carries one from the controller: `trigger` with `ref {automation_id, occurrence_index, event_id, source}`, or `person` for a manual run now; the actor is the automation's owner (`_meta.automation_owner`, the `"<tenant>:<user>"` of the creation request). See [Run origin](docs/automations.md#run-origin).
+
+- `wake_stream_consumers(runtime, stream)` / `stream_consumers(runtime, stream)` (`abstractruntime.email`, framework backlog 1042/1044): wake the automations that read ONE inbox stream, decided by their binding alone (`automation_reads_stream`): `trigger:<connection_id>` for a connection-bound binding, `email:<tenant>:<user>:<account_id>:<folder>` for an `email.received@1` binding of that mailbox (`config.account`; `self` or unset is the runtime's bound mailbox). `wake_email_automations(runtime, account_id=…)` and `email_trigger_consumers(runtime, account_id=…)` take an optional mailbox; `prune_email_inbox` also keeps the events a connection-bound automation has not read yet.
+
+- `MailboxQueryableRunStore` (backlog 1046): `list_mailbox_runs(names=[…])` returns every running or waiting run
+  that declares one of the names as `events_mailbox`, and `next_wait_deadline()` the earliest wait deadline over
+  every waiting run. The in-memory, file (a lazily built mailbox index maintained on save and delete, every hit
+  re-verified on disk) and SQLite stores implement both; `OffloadingRunStore` forwards them. They let a host fan
+  durable events out and schedule wakes without a window of the newest runs.
+
+- **Trigger connections** (framework backlog 1040): per-user instances of a trigger source, registered once and reused by any automation. `TriggerConnectionStore(plane_dir)` keeps one JSON file per connection (`<plane>/triggers/connections/<id>.json`, atomic writes), listed and changed per principal (`"<tenant>:<user>"`; another principal's connection reads like an unknown one), with secret fields and generated secrets sealed by AbstractCore's `SecretVault` (the mailbox credentials' sealing). Descriptors gain `needs_connection`, `connection_schema` and `connection_provider` (`schedule@1/2`, `manual@1`: none; `email.received@1`: a mailbox of the mail accounts). Each connection has one inbox stream `trigger:<connection_id>`; `test_fire` appends a synthetic `{data: {test: true}}` event to it and `wake_connection_automations` wakes the bound automations. `create_automation` and `automation.revise` refuse a binding whose `config.connection_id` is unknown, another principal's, of another source or disabled (`Runtime.set_trigger_connection_store`). `ConnectionEventAdapter` is the shared adapter of connection-bound sources (one coalesced admission per batch of stream events). See [Trigger connections](docs/automations.md#trigger-connections).
+
+## [0.10.6] - 2026-10-18
+
+### Added
+
+- `abstractruntime.conversation_search.ConversationSearch`: keyword search over a plane's conversations: each turn's question and answer (as the session replay builds them) and its media, the artifacts it generated (kind and generation prompt, attributed to the turn whose run made them) and the attachments it was sent with (kind and file name); read-aloud audio and internal artifacts are not media. A hit on an artifact names it (`artifact`: id, owning run, kind, content type), so a client can show it. Its own SQLite file per plane, an FTS5 `trigram` index over text lowercased and without accents: words and parts of words, every word required, words of one or two letters as whole words, and a fuzzy pass that keeps a turn holding at least 60% of each word's trigrams (a typo still finds it). One hit per session (its best turn, a snippet, the match positions, where it matched: question, artifact or answer). Tool usage, tool outputs and intermediate thinking are not indexed: [backlog 0849](docs/backlog/proposed/0849_conversation_search_tool_usage_outputs_and_thinking.md). `sync(budget_s=…)` indexes what changed since the last call, newest sessions first, and reports what is left. Works with the file and the SQLite run stores; without the `trigram` tokenizer (SQLite < 3.34) it indexes whole words with prefixes.
+
+- Automation definitions accept a named `policy.tool_policy` snapshot for per-tool Auto and Approve choices. The target tool ceiling remains authoritative; unspecified tools ask for approval. Messaging and untrusted-input restrictions remain enforced. See [Tool approval](docs/automations.md#tool-approval).
+- Streamed read-aloud recordings (`_finalize_tts_stream_artifact`, the streamed-voice path of the AbstractCore integration) are stored under the voice namespace: their artifact tags carry `purpose=voice_playback`, `artifact_space=voice`, a `filename` and a logical `path` of `voice/tts-<id>.wav`, so a host can list a user's generated documents and attachments without the playback audio while playback and replay keep the same artifact ref and provenance. Test: `tests/test_streamed_voice_namespace.py`.
+
 ## [0.10.5] - 2026-10-18
 
 ### Changed

{abstractruntime-0.10.5 → abstractruntime-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.10.5
+Version: 0.12.0
 Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
 Project-URL: AbstractCore (website), https://www.abstractcore.ai/
 Project-URL: AbstractRuntime (GitHub), https://github.com/lpalbou/abstractruntime
@@ -20,8 +20,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
-Requires-Dist: abstractcore>=2.26.0
-Requires-Dist: abstractmemory>=0.3.0
+Requires-Dist: abstractcore>=2.30.0
+Requires-Dist: abstractmemory>=0.3.2
 Requires-Dist: abstractsemantics>=0.0.5
 Requires-Dist: anyio<5.0.0,>=4.12.1
 Requires-Dist: httpx<1.0.0,>=0.28.1
@@ -35,14 +35,14 @@ Requires-Dist: reportlab<5.0.0,>=4.0.0
 Requires-Dist: restrictedpython>=7.0
 Requires-Dist: unstructured[docx,odt,pptx,rtf,xlsx]<0.19.0,>=0.18.32
 Provides-Extra: apple
-Requires-Dist: abstractcore[apple]>=2.26.0; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.30.0; extra == 'apple'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'apple'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
 Provides-Extra: gpu
-Requires-Dist: abstractcore[gpu]>=2.26.0; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.30.0; extra == 'gpu'
 Requires-Dist: setuptools<82.0.0,>=77.0.3; extra == 'gpu'
 Provides-Extra: test
 Requires-Dist: aiosmtpd<2.0.0,>=1.4.4; extra == 'test'
@@ -83,7 +83,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.24.0 or newer (its light install:
+The base install includes AbstractCore 2.30.0 or newer (its light install:
 remote providers, tools, vision, voice, audio, and music integration), plus the
 `abstractruntime-mcp-worker` entry point. It keeps inference remote/light by
 default: local engines such as MLX, vLLM, HuggingFace/Torch, Diffusers, and
@@ -159,13 +159,15 @@ Kernel (import-light):
 - Stop that reaches the running effect: `Runtime.cancel_run(...)` signals the in-flight model or tool call, which ends as a `cancelled` ledger record (never retried); a model unload stops the calls using that model first (`docs/api.md`)
 - host pause at step boundaries: `Runtime.tick(..., step_gate=...)`
 - run-tree tool ceiling: an explicit `allowed_tools` list can only narrow across child runs, and approval policy never widens it
-- automations: run a workflow on a schedule (`schedule@1` fixed UTC intervals; `schedule@2` adds daily, weekly and monthly rules at a wall time in an IANA time zone), when mail arrives (`email.received@1`, `docs/email.md`) or on request (`manual@1`) as a durable controller run whose occurrences are deterministic child runs and session turns, with commands, independent or growing context, discussions forked at any occurrence (own workspace, automation workspace mounted read-only), tool approval, typed waits and quiet-by-default notifications (`docs/automations.md`)
+- automations: run a workflow on a schedule (`schedule@1` fixed UTC intervals; `schedule@2` adds daily, weekly and monthly rules at a wall time in an IANA time zone), when mail arrives in one of the user's mailboxes (`email.received@1`, `docs/email.md`), on new feed items (`feed.item@1`), on a signed webhook call (`webhook.received@1`) or on request (`manual@1`) as a durable controller run; per-user trigger connections (feed URLs, webhook endpoints with sealed signing secrets) reused by any automation; every occurrence receives its trigger as a CloudEvents 1.0 event (`input_data.event`) and records who or what started it (`_meta.origin`); runs can schedule work for later with `SCHEDULE_RUN` (a one-shot wake in the same session, at most the caller's tools, reminders that reach the person), whose occurrences are deterministic child runs and session turns, with commands, independent or growing context, discussions forked at any occurrence (own workspace, automation workspace mounted read-only), tool approval, typed waits and quiet-by-default notifications (`docs/automations.md`)
+- flows that act and tell: mail verbs on the run's mailbox (`mail_search`, `mail_get`, `mail_mark`, `mail_label`, `mail_move`, `mail_delete`, `mail_send`, `mail_reply`, `mail_forward`, `mail_attachment`; changes and sends only on a mailbox the person keeps Read and write, `docs/email.md`) and Publish to channel (`PUBLISH_EVENT`: an event on the user's stream, optionally an alert with its `recipient` and `channels`, handed to the host through `Runtime.set_publish_event_handler`, `docs/automations.md`)
 - explicit run ids: `Runtime.start(..., run_id=...)` creates a run only if the id is free (`RunStore.create_if_absent`), and `run_mutation_lock(run_id)` serializes a run's writers in a process
 
 Durability + storage:
 - stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
 - durable command inbox primitives (idempotent, append-only): `CommandStore`, `CommandCursorStore` (`src/abstractruntime/storage/commands.py`, `src/abstractruntime/storage/sqlite.py`)
 - artifacts + offloading (store large payloads by reference)
+- large JSON run folders without scans: an in-memory active index and trusted run index (`trust_index`, `run_index_stats()`, background reconciliation), change tokens on the run store and the ledger (`change_token()`, `changed_run_ids()`), event-wait indexes that see another process's parked runs, and the active-consumers index for "who listens?" (`docs/architecture.md`, `docs/api.md`)
 - snapshots/bookmarks (`docs/snapshots.md`)
 - tamper-evident hash-chained ledger (`docs/provenance.md`)
 
@@ -239,8 +241,8 @@ sr = create_scheduled_runtime(
 | [Architecture](docs/architecture.md) | Component map + diagrams |
 | [Overview](docs/proposal.md) | Design goals, core concepts, and scope |
 | [AbstractCore Integration](docs/integrations/abstractcore.md) | `LLM_CALL` / `TOOL_CALLS`, host facades, models/engines/host jobs |
-| [Automations](docs/automations.md) | Scheduled and on-request workflows: controller, triggers, commands, context, discussions, storage guarantees |
-| [Email](docs/email.md) | Email for each user: run-scoped account binding, sending without asking, the event inbox and mail feeder, the `email.received@1` trigger, the send-email action |
+| [Automations](docs/automations.md) | Scheduled, event-driven and on-request workflows: controller, triggers (schedules, mail, feeds in RSS 2.0/RSS 1.0/Atom, webhooks), trigger connections, the CloudEvents envelope, run origin, wakes (`SCHEDULE_RUN`), Publish to channel (alerts with `recipient` and `channels`), commands, context, discussions, storage guarantees |
+| [Email](docs/email.md) | Email for each user: run-scoped account binding, sending without asking, the event inbox and mail feeder, the `email.received@1` trigger on any of the user's mailboxes, mail verbs for flows (Read only / Read and write), the send-email action |
 | [Artifacts](docs/artifacts.md) | Artifact identity, descriptors, catalog search and access stats |
 | [Tool Approval](docs/tool-approval.md) | Tool risk tiers, run-policy ceiling, per-call refiners |
 | [Comms Toolset](docs/tools-comms.md) | Opt-in email/WhatsApp/Telegram tools |

{abstractruntime-0.10.5 → abstractruntime-0.12.0}/README.md

@@ -32,7 +32,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.24.0 or newer (its light install:
+The base install includes AbstractCore 2.30.0 or newer (its light install:
 remote providers, tools, vision, voice, audio, and music integration), plus the
 `abstractruntime-mcp-worker` entry point. It keeps inference remote/light by
 default: local engines such as MLX, vLLM, HuggingFace/Torch, Diffusers, and
@@ -108,13 +108,15 @@ Kernel (import-light):
 - Stop that reaches the running effect: `Runtime.cancel_run(...)` signals the in-flight model or tool call, which ends as a `cancelled` ledger record (never retried); a model unload stops the calls using that model first (`docs/api.md`)
 - host pause at step boundaries: `Runtime.tick(..., step_gate=...)`
 - run-tree tool ceiling: an explicit `allowed_tools` list can only narrow across child runs, and approval policy never widens it
-- automations: run a workflow on a schedule (`schedule@1` fixed UTC intervals; `schedule@2` adds daily, weekly and monthly rules at a wall time in an IANA time zone), when mail arrives (`email.received@1`, `docs/email.md`) or on request (`manual@1`) as a durable controller run whose occurrences are deterministic child runs and session turns, with commands, independent or growing context, discussions forked at any occurrence (own workspace, automation workspace mounted read-only), tool approval, typed waits and quiet-by-default notifications (`docs/automations.md`)
+- automations: run a workflow on a schedule (`schedule@1` fixed UTC intervals; `schedule@2` adds daily, weekly and monthly rules at a wall time in an IANA time zone), when mail arrives in one of the user's mailboxes (`email.received@1`, `docs/email.md`), on new feed items (`feed.item@1`), on a signed webhook call (`webhook.received@1`) or on request (`manual@1`) as a durable controller run; per-user trigger connections (feed URLs, webhook endpoints with sealed signing secrets) reused by any automation; every occurrence receives its trigger as a CloudEvents 1.0 event (`input_data.event`) and records who or what started it (`_meta.origin`); runs can schedule work for later with `SCHEDULE_RUN` (a one-shot wake in the same session, at most the caller's tools, reminders that reach the person), whose occurrences are deterministic child runs and session turns, with commands, independent or growing context, discussions forked at any occurrence (own workspace, automation workspace mounted read-only), tool approval, typed waits and quiet-by-default notifications (`docs/automations.md`)
+- flows that act and tell: mail verbs on the run's mailbox (`mail_search`, `mail_get`, `mail_mark`, `mail_label`, `mail_move`, `mail_delete`, `mail_send`, `mail_reply`, `mail_forward`, `mail_attachment`; changes and sends only on a mailbox the person keeps Read and write, `docs/email.md`) and Publish to channel (`PUBLISH_EVENT`: an event on the user's stream, optionally an alert with its `recipient` and `channels`, handed to the host through `Runtime.set_publish_event_handler`, `docs/automations.md`)
 - explicit run ids: `Runtime.start(..., run_id=...)` creates a run only if the id is free (`RunStore.create_if_absent`), and `run_mutation_lock(run_id)` serializes a run's writers in a process
 
 Durability + storage:
 - stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
 - durable command inbox primitives (idempotent, append-only): `CommandStore`, `CommandCursorStore` (`src/abstractruntime/storage/commands.py`, `src/abstractruntime/storage/sqlite.py`)
 - artifacts + offloading (store large payloads by reference)
+- large JSON run folders without scans: an in-memory active index and trusted run index (`trust_index`, `run_index_stats()`, background reconciliation), change tokens on the run store and the ledger (`change_token()`, `changed_run_ids()`), event-wait indexes that see another process's parked runs, and the active-consumers index for "who listens?" (`docs/architecture.md`, `docs/api.md`)
 - snapshots/bookmarks (`docs/snapshots.md`)
 - tamper-evident hash-chained ledger (`docs/provenance.md`)
 
@@ -188,8 +190,8 @@ sr = create_scheduled_runtime(
 | [Architecture](docs/architecture.md) | Component map + diagrams |
 | [Overview](docs/proposal.md) | Design goals, core concepts, and scope |
 | [AbstractCore Integration](docs/integrations/abstractcore.md) | `LLM_CALL` / `TOOL_CALLS`, host facades, models/engines/host jobs |
-| [Automations](docs/automations.md) | Scheduled and on-request workflows: controller, triggers, commands, context, discussions, storage guarantees |
-| [Email](docs/email.md) | Email for each user: run-scoped account binding, sending without asking, the event inbox and mail feeder, the `email.received@1` trigger, the send-email action |
+| [Automations](docs/automations.md) | Scheduled, event-driven and on-request workflows: controller, triggers (schedules, mail, feeds in RSS 2.0/RSS 1.0/Atom, webhooks), trigger connections, the CloudEvents envelope, run origin, wakes (`SCHEDULE_RUN`), Publish to channel (alerts with `recipient` and `channels`), commands, context, discussions, storage guarantees |
+| [Email](docs/email.md) | Email for each user: run-scoped account binding, sending without asking, the event inbox and mail feeder, the `email.received@1` trigger on any of the user's mailboxes, mail verbs for flows (Read only / Read and write), the send-email action |
 | [Artifacts](docs/artifacts.md) | Artifact identity, descriptors, catalog search and access stats |
 | [Tool Approval](docs/tool-approval.md) | Tool risk tiers, run-policy ceiling, per-call refiners |
 | [Comms Toolset](docs/tools-comms.md) | Opt-in email/WhatsApp/Telegram tools |

{abstractruntime-0.10.5 → abstractruntime-0.12.0}/docs/README.md

@@ -17,8 +17,8 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `../README.md` — install + quick start
 - `getting-started.md` — first steps (recommended)
 - `api.md` — public API surface (imports + pointers)
-- `architecture.md` — how the runtime is structured (with diagrams)
-- `troubleshooting.md` — symptom-oriented setup, runtime, and integration fixes
+- `architecture.md` — how the runtime is structured (with diagrams), including how a JSON run store reads a large folder without scanning it (run index, change tokens, cross-process refresh)
+- `troubleshooting.md` — symptom-oriented setup, runtime, and integration fixes (waits, automations, webhooks, mail steps, feeds, workspaces)
 - `proposal.md` — design goals and scope boundaries
 
 ## Guides
@@ -28,15 +28,16 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `artifacts.md` — Runtime artifact identity, descriptors, provenance, catalog search, and access stats
 - `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS`, the `config_facade` models/engines/host-jobs passthroughs for hosts, the `structured_facade` response_format check for hosts, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, model-residency listings, locks and model switching, live token streaming, workspace-scoped tools, durable bloc prompt-cache control, media inputs, generated media outputs, video progress events, and tool approval waits via AbstractCore
 - `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
-- `email.md` — email for each user: run-scoped account binding and the host resolver, sending without asking (self and pre-authorised recipients), the durable event inbox and mail feeder, the `email.received@1` trigger, and the send-email action
+- `email.md` — email for each user: run-scoped account binding and the host resolver, sending without asking (self and pre-authorised recipients), the durable event inbox and mail feeder, the `email.received@1` trigger on the primary or any other mailbox of the user, mail verbs for flows (changes and sends only on a Read and write mailbox: `email_mailbox_read_only`, `email_mailbox_cannot_send`), and the send-email action
 - `tool-approval.md` — tool risk tiers, the run-policy rank ceiling, and per-call refiners (the `send_email` recipient rule: self and pre-authorised recipients)
 - `api.md#workflowbundles-flow-and-visualflow-distribution` — VisualFlow compiler APIs, media nodes, and document nodes (`read_pdf` / `write_pdf` / `write_docx`)
 - `api.md#sessions-and-history` — session history replay: one window, the most recent 50,000 tokens of whole turns (`HISTORY_REPLAY_MAX_TOKENS`), returned as a `ReplayedHistory` whose `.report` records what was replayed and dropped
+- `api.md#conversation-search` — keyword search over a plane's conversations (`ConversationSearch`): questions, answers and the turn's artifacts, one SQLite FTS5 trigram index per plane, incremental `sync` with a time budget, exact then fuzzy matching
 - `api.md#run-history-bundle-export-portable-replay-artifact` — run history bundles, including `resolved_actions` summaries for cross-client capability replay
 
 ## Features (reference)
 
-- `automations.md` — automations: a workflow run on a schedule or on request as a durable controller run; triggers (`schedule@1`, `schedule@2` calendar rules in a time zone, `manual@1`, `email.received@1`, entry-point sources), commands, independent or growing context, discussions forked at any occurrence (own writable workspace, the automation's workspace mounted read-only), tool approval, typed waits, notifications and retries, and the storage guarantees (create-if-absent, per-run lock, turn roots, session kinds, one writer process per store)
+- `automations.md` — automations: a workflow run on a schedule, on an event or on request as a durable controller run; triggers (`schedule@1`, `schedule@2` calendar rules in a time zone, `manual@1`, `email.received@1`, `feed.item@1` RSS 2.0 / RSS 1.0 / Atom, `webhook.received@1` Standard Webhooks, entry-point sources), per-user trigger connections, the CloudEvents envelope (`input_data.event`), run origin (`_meta.origin`), wakes (`SCHEDULE_RUN`: work later in the same session, with at most the caller's tools), Publish to channel (`PUBLISH_EVENT`, alerts with `recipient` and `channels`), commands, independent or growing context, discussions forked at any occurrence (own writable workspace, the automation's workspace mounted read-only), tool approval, typed waits, notifications and retries, and the storage guarantees (create-if-absent, per-run lock, turn roots, session kinds, one writer process per store)
 - `entity-runtime.md` — per-entity runtimes for summoned entities: homes, the one-writer lease, act-only diary privacy (`$act_only` refs), durable visit waits with deadlines
 - `evidence.md` — artifact-backed evidence capture for external-boundary tools
 - `mcp-worker.md` — MCP worker CLI (`abstractruntime-mcp-worker`)

{abstractruntime-0.10.5 → abstractruntime-0.12.0}/docs/api.md

@@ -80,6 +80,7 @@ Implementation: `src/abstractruntime/core/runtime.py`.
   - persists `CANCELLED`, then signals every effect of that run (and its in-flight descendants) executing in this process; the running attempt is recorded as `cancelled` (`StepStatus.CANCELLED`, never retried) with `cancelled_by` and `reason`, and no further effect starts
 - `Runtime.set_default_provider_model(provider=..., model=...)`
   - re-points the default provider/model seeded into new runs; pair it with the pooled client's `set_default_provider_model(...)` so both agree
+- `Runtime.set_event_inbox(inbox)`, `Runtime.set_trigger_connection_store(store)` and `Runtime.set_schedule_run_handler(handler)`: the host seams of event-triggered automations, trigger connections and wakes (see [automations.md](automations.md#triggers) and [automations.md](automations.md#wakes-schedule_run))
 - `Runtime.set_live_delta_sink(sink)` where `sink(event: dict) -> None`, or `None` to remove it
   - receives live token deltas (`llm.delta`, `llm.delta_end`) for LLM calls of runs started with `_runtime.stream: true` (a boolean; `start` refuses any other value); nothing is written to the ledger. See [Live token streaming](integrations/abstractcore.md#live-token-streaming)
 
@@ -124,9 +125,13 @@ Run index and creation (all built-in run stores, including the offloading wrappe
 - `create_if_absent(run) -> (run, created)`: creates a run only if its id is free and never overwrites an existing one; `store_supports_create_if_absent(store)` / `require_create_if_absent(store)` check a store first. Process-crash safe; power-loss durability is not claimed
 - `list_run_index(status=, workflow_id=, session_id=, root_only=, limit=, oldest_first=, automation_id=, role=, session_kind=)`: lightweight rows carrying `automation_id`, `role`, `occurrence_index`, `session_kind` and `workspace_root` (the run's top-level `vars["workspace_root"]` as stored, stripped; `None` when absent); the three attribution filters take a value, a comma-separated string or a list; `root_only=True` returns turn roots (parent-less runs except automation controllers, plus automation occurrences)
 - `session_kinds(session_id) -> frozenset` and `latest_occurrence_row(automation_id)`: indexed lookups used by session attribution and automation listings
+- `MailboxQueryableRunStore` (in-memory, file, SQLite and offloading stores): `list_mailbox_runs(names=[...], limit=10_000)` returns every running or waiting run whose `events_mailbox` names one of the names (newest first; the file store keeps a mailbox index maintained on save and delete and re-verifies each hit on disk), and `next_wait_deadline()` the earliest wait deadline over all waiting runs (`WAIT_UNTIL`, or `WAIT_EVENT` with a deadline), or `None`. Hosts use them to fan durable events out and to schedule wakes without reading a window of the newest runs
 - `JsonFileRunStore.warm_session_index()` builds the session and children indexes at host startup. Store objects and processes sharing one JSON run folder see each other's created and deleted runs through the creation journal `.runs_created.log`; v1 supports one writer process per store
 - `JsonFileRunStore` answers `list_runs` / `list_run_index` for `status=running` or `status=waiting` (without `session_id`) from an in-memory **active index**: the set of active run ids, built from one directory scan (at host boot through `warm_session_index()`, else on the first such listing) and kept current by `save`, `create_if_absent`, `delete` and the creation journal. Every candidate is re-verified against its file at listing time, so a run that ended or vanished is never listed. Rows, order (file mtime, then file name, then the final `updated_at` sort), filters and limits are the same as the directory scan's; a listing of a 10,000-run store costs milliseconds instead of a full scan. `JsonFileRunStore(..., use_active_index=False)` keeps the plain scan. `rescan_active_index()` reconciles the index with the directory in the caller's thread; a background rescan runs at most every `JsonFileRunStore.ACTIVE_INDEX_RESCAN_S` (60 s) to pick up writers that bypass the store. `list_due_wait_until` (the scheduler's due-wait poll) takes its candidates from the index too. Other listings (a terminal status, no status, a session scope) scan as before.
-- The creation journal (`.runs_created.log` in the run folder) carries one line per change another store object or process must learn about: `+<run_id>` created, `-<run_id>` deleted, `~<run_id>` became active again (resumed, re-opened, first save after a restart, or saved after another writer touched the file). Lines are written before the file change they announce; readers apply the lines they have not seen at their next lookup, and a line whose file has not landed yet (or does not read active yet) is re-checked until it does. Readers from AbstractRuntime 0.10.0 ignore `~` lines, and writers from 0.10.0 never write them: a re-open made by such a writer reaches other store objects through the periodic rescan.
+- **Trusted run index** (`JsonFileRunStore(..., trust_index=True)`, the default): every listing the active index does not answer (no status or a finished status, no `session_id`: `list_run_index`, `list_runs`, `latest_occurrence_row`) is answered from memory once one complete pass (the active-index build, at host boot through `warm_session_index()`) has read every run file: ranked by file mtime then file name, same filters, rows and limits as the directory scan, with no glob and no stat of a run file (11,500 files: about 1-20 ms instead of a 0.25 s scan that waits for the interpreter lock under contention). It is kept current by the store's own saves, creates and deletes, the creation journal (including `=<run_id>`), and a re-read of its RUNNING/WAITING entries when the folder's mtime moved (another process ticking a run writes no journal line). A background **reconciliation** (the active-index rescan, a daemon thread, never on a caller's path) re-reads the folder at most every `ACTIVE_INDEX_RESCAN_S` (60 s) when the folder or the journal moved, and at least every `RUN_INDEX_FULL_RECONCILE_S` (600 s); a difference it finds (a writer that bypassed the journal) is repaired and logged as a warning. The risk is a stale row until then, never a lost run: `load()` reads disk. `trust_index=False` (**verify**, the shadow mode) answers every such listing with the directory scan, as before, and compares it with the in-memory answer. `run_index_stats()` (forwarded by `OffloadingRunStore`) returns `mode`, `complete`, `entries`, `active_entries`, `trusted_listings`, `scanned_listings`, `shadow_compared`, `shadow_mismatches` (verify mode: stable comparisons whose answers differed; 0 means the index would have answered every listing the same), `shadow_unstable` (a write overlapped the comparison: no verdict), `last_mismatch`, `reconciles`, `reconcile_repairs` and `last_reconcile`; each mismatch and each repair is also logged as a `JsonFileRunStore:` warning. `reconcile_run_index()` runs the reconciliation in the caller's thread. Needs the active index (`use_active_index=False` is the plain scan, without shadow).
+- The creation journal (`.runs_created.log` in the run folder) carries one line per change another store object or process must learn about: `+<run_id>` created, `-<run_id>` deleted, `~<run_id>` became active again (resumed, re-opened, first save after a restart, or saved after another writer touched the file). Lines are written before the file change they announce; readers apply the lines they have not seen at their next lookup, and a line whose file has not landed yet (or does not read active yet) is re-checked until it does. Readers from AbstractRuntime 0.10.0 ignore `~` lines, and writers from 0.10.0 never write them: a re-open made by such a writer reaches other store objects through the periodic rescan. `=<run_id>`: a run that is not active changed its file (it finished, or a finished run was re-saved), written AFTER the file is published; older readers ignore it, and a change made by an older writer reaches the trusted run index through the reconciliation.
+- `JsonFileRunStore` event-wait and mailbox indexes (`list_event_waiters`, `list_event_waiters_by_prefix`, `list_mailbox_runs`) see what another process saved on the same folder (a split gateway: API process + runner process). Before each lookup the store reads its change signal (the creation log's size and the folder's mtime): when either moved, or at least every `EVENT_INDEX_REFRESH_S` (2 s), it stats each running or waiting run and re-reads the ones whose file changed since it last filed them. An idle store pays two stats per lookup; its own saves are never re-read. `event_index_stats()` returns `{refreshes, refiled, tracked}`.
+- `JsonFileRunStore.change_token()` answers "did any run of this folder change?" with one stat: `(creation-log size, active-index counter)`. Every save, create and delete through the store moves the counter; another process's create, delete or became-active line moves the log size. Not seen: another process re-saving a run that stays active (one ticking process per folder); ending a run, or re-saving a finished one, writes `=<run_id>`. `changed_run_ids(token)` names the runs this store changed since `token`, or `None` when that is unknown (the log moved, or more than 8,192 changes ago). `ObservableLedgerStore.change_token()` / `changed_run_ids(token)` do the same for ledger appends (process-local). The gateway runner's scan gate and its mail notification check compare these tokens instead of reading the directory.
 
 Common decorators:
 - `ObservableLedgerStore` for subscriptions (`src/abstractruntime/storage/observable.py`)
@@ -240,10 +245,19 @@ from abstractruntime.triggers import get_trigger_adapter, trigger_sources
 - `create_automation(runtime, request, *, now=None, actor_id=None)`: creates the controller root run (the automation) with a deterministic id; raises `AutomationError` (`invalid_definition`, `unsupported_feature`, `unknown_trigger_source`, `identity_conflict`)
 - `apply_automation_command(runtime, *, automation_id, command_id, type, payload=None, actor=None, expected_revision=None)`: the only writer of automation state; returns `{status: "applied" | "rejected", error?, duplicate}`; idempotent per `command_id`
 - `record_automation_command_result(...)`: records a host-side failure of a command as a rejected result
-- reads: `get_automation(run_store, id)`, `list_occurrences(runtime, id, cursor=, limit=)`, `list_attention(ledger_store, id, after_seq=, cursor=, limit=)`, `pending_waits(run_store, id, limit=)` with typed waits (`ask_user`, `tool_approval`, `event`) and `ANSWER_PAYLOADS`; `list_automations(run_store, status=, cursor=, limit=)`, `automation_summary(run)`, `latest_occurrence(run_store, id)`
+- reads: `get_automation(run_store, id)`, `list_occurrences(runtime, id, cursor=, limit=)`, `list_attention(ledger_store, id, after_seq=, cursor=, limit=)`, `pending_waits(run_store, id, limit=)` with typed waits (`ask_user`, `tool_approval`, `event`) and `ANSWER_PAYLOADS`; `list_automations(run_store, status=, cursor=, limit=, index_rows=)`, `automation_summary(run)`, `latest_occurrence(run_store, id)` (the index row); from `abstractruntime.automations`: `latest_occurrence(runtime, id, user_turn=)` (the newest occurrence row, read from the ledger's end), `pending_waits_by_automation(run_store, limit=)` (one read for a whole listing), `automation_generation(runtime_or_store)` (the change counter a host keys its cached listings on) and the active-consumers index (`active_consumers_index`, `invalidate_active_consumers`; see `automations.md#trigger-connections`)
 - `start_discussion(runtime, *, automation_id, occurrence_index, request_id, prompt, workspace_root, actor_id=None)`: a separate conversation forked at any occurrence N, seeded with the automation's whole timeline 1..N, working in its own writable `workspace_root` with the automation's workspace mounted read-only
 - controller bundle: `register_controller_bundle(registry)`, `controller_workflow_spec()`, `controller_bundle_path()`; `CONTROLLER_WORKFLOW_ID` is `abstractframework.automation-controller@1.0.0:controller`
-- trigger sources: `trigger_sources()`, `get_trigger_adapter(id, version)`, built-ins `schedule@1`, `schedule@2` (daily/weekly/monthly rules in an IANA time zone; `validate_time_zone`, `time_zone_names`), `manual@1` and `email.received@1`, third-party sources through the `abstractruntime.trigger_sources` entry-point group
+- trigger sources: `trigger_sources()`, `get_trigger_adapter(id, version)`, built-ins `schedule@1`, `schedule@2` (daily/weekly/monthly rules in an IANA time zone; `validate_time_zone`, `time_zone_names`), `manual@1`, `email.received@1`, `feed.item@1` and `webhook.received@1`, third-party sources through the `abstractruntime.trigger_sources` entry-point group
+- trigger connections (`abstractruntime.triggers.connections`): `TriggerConnectionStore(plane_dir, *, sealing_key_file=None)` (per-principal CRUD, sealed secrets), `connection_principal(tenant, user)`, `connection_stream(id)` (`trigger:<id>`), `append_connection_event(...)`, `test_fire(store, inbox, id, principal=)`, `validate_binding_connection(principal, binding, store)`, `wake_connection_automations(runtime, id)`, `Runtime.set_trigger_connection_store(store)`; `create_automation(..., principal=)` and `apply_automation_command(..., principal=)` check a binding's `config.connection_id`
+- run origin (`abstractruntime.core.run_origin`): `origin_for(kind, *, actor=, client=, automation_id=, occurrence_index=, event_id=, source=, origin_run_id=, session_id=, bridge=)` builds `_meta.origin` (`person | trigger | agent | system`), `stamp_origin(vars, origin)`, `origin_of(vars)`; occurrences carry it from the controller
+- CloudEvents envelope (`abstractruntime.triggers.cloudevents`): `to_cloudevent(envelope)`, `from_cloudevent(event)`, `with_cloudevent_attributes(...)`, `event_type(source_id, version)`, `CLOUDEVENT_JSON_SCHEMA`; occurrences receive `input_data.event`
+- feed source `feed.item@1` (`abstractruntime.triggers.feed`): `parse_feed(bytes)`, `FeedPoller(store, inbox, fetch=)`, `poll_feed_connections(runtime, store, fetch=None, now=None)` (the host's poll step), `urllib_fetch` (conditional GET)
+- webhook source `webhook.received@1` (`abstractruntime.triggers.webhook`): `verify_standard_webhook(secret, headers, body, now, tolerance_s=300)`, `append_webhook_event(inbox, connection, body, headers, *, secret=None, store=None, now=None)`, `sign_standard_webhook(...)`, `new_webhook_secret()`, `webhook_event_data(...)`
+- wakes (`abstractruntime.automations.wakes`): `EffectType.SCHEDULE_RUN`, `Runtime.set_schedule_run_handler(handler)` (`handler(run, plan) -> {automation_id}`), `plan_schedule_run(run, payload, *, now, run_store=None, request_id=None)`, `create_scheduled_run(runtime, plan, *, target, tenant, user, workspace_root, notify=None)`, `wake_scheduled_event`, `wake_cancelled_event`; creation requests accept `session_id` (growing only), `origin_run_id`, `one_shot`, `untrusted_origin`
+- sample inputs (`abstractruntime.automations.samples`): `sample_occurrence_inputs(runtime, source_id, source_version, config, *, count=100, principal=None, email_context=None, fetch=None)` -> `{inputs, resolve_vars, truncated, source, count}` (the named inputs + `event` with `abstracttest: true`, from real data, read only), `resolved_sample_inputs(sample, artifact_store=)`, `SampleError`
+- mail verbs for flows (`abstractruntime.mail_verbs`): fixed verbs `mail.search`, `mail.get`, `mail.mark`, `mail.label`, `mail.move`, `mail.delete`, `mail.send`, `mail.reply`, `mail.forward`, `mail.attachment` run by the `TOOL_INVOKE` handler (node types `mail_*`); `run_mail_verb(run, name, arguments)`, `mail_verb_outcome(...)`, `MailVerbError`; the Email record `triggers.email_received.email_record(message, mailbox=)`, `email_id`, `parse_email_id`, `thread_id_of`. See [email.md](email.md#mail-verbs-for-flows)
+- publish to channel (`abstractruntime.core.publish`): `EffectType.PUBLISH_EVENT` (node type `publish_event`), payload `{channel, type?, title, body?, subject?, data?, alert?, recipient? = "me", channels? (tray|watch|phone|email|console; absent = all)}`, `validate_publish(payload)`, `normalize_channels(value)`, `strip_visual_envelope(payload)`, `DELIVERY_CHANNELS`, `Runtime.set_publish_event_handler(handler)` with `handler(run, payload, step_id) -> {event_id, sequence, alerted}`. See [automations.md](automations.md#publish-to-channel)
 - definition v2: `policy.email_allowed_recipients` (default `["self"]`), `policy.untrusted_input_tools` (default `[]`) and `notify.channels` (default `["console"]`); attention items carry `channels`
 
 ## Email
@@ -291,6 +305,16 @@ Implementation: `src/abstractruntime/session_turns.py`, `src/abstractruntime/ses
 
 History bundles (`export_run_history_bundle`) and session replay use the same turn selection, so automation occurrences appear as turns (kind `occurrence`, with `automation_id` and `occurrence_index`) in both.
 
+## Conversation search
+
+Implementation: `src/abstractruntime/conversation_search.py`.
+
+- `ConversationSearch(db_path, *, run_store, ledger_store, artifact_store=None, kinds=None)`: the keyword search index of one runtime plane. `db_path` is its own SQLite file in that plane's data folder (one index per plane, so a principal's search can only ever read the plane it was opened on; the file is disposable and is rebuilt when the schema changes). Each turn root (a question and its answer, as the session replay builds them) is one row, together with the turn's media: the artifacts its run generated (image, voice, video, music, by their generation prompt) and the attachments it was sent with (by their file name), each with its kind. Read-aloud audio, media saved without a prompt and internal artifacts are not indexed. `kinds` defaults to `INDEXED_KINDS` (`chat`, `discussion`): automation sessions are not indexed
+- `sync(*, budget_s=3.0) -> SyncReport`: indexes what changed since the last call (turn roots whose `updated_at` moved, re-read by session, newest sessions first) within the time budget. `SyncReport`: `{indexed_turns, reindexed_sessions, pending_sessions, total_turns, seconds, complete, errors}`; `complete` is `False` while older conversations are still waiting, so a first search on a large plane can say it is still indexing
+- `search(query, *, limit=20, sessions=None, exclude=None, session_kinds=None) -> list[SearchHit]`: one hit per session, best first. Text is indexed and queried lowercased and without accents (`normalize`) with the FTS5 `trigram` tokenizer: every query word of three or more characters must appear in the turn, as a word or part of one ("surviv" finds "overall survival"); words of one or two characters are matched as whole words; ranked by bm25, the question weighing more than the answer. When exact matches are fewer than `limit`, a fuzzy pass keeps turns holding at least `FUZZY_MIN` (60%) of each word's trigrams, so a typo still finds its turn (`fuzzy: true` on those hits). `sessions`, `exclude` and `session_kinds` filter inside the query, so a filter never empties a page that had matches further down. `limit` is clamped to 1–100
+- `SearchHit` (`as_dict()`): `session_id`, `run_id` (the best turn), `prompt`, `snippet` (around the first match), `matched_in` (`question`, `answer` or `artifact`), `highlights` (`[start, length]` pairs in the snippet), `score`, `created_at`, `updated_at`, `session_kind`, `fuzzy`, and `artifact` when the match is an artifact: `{artifact_id, run_id, kind, content_type, name, prompt}`, `run_id` being the run that owns it (a host's artifact content route is scoped to that run)
+- Without the `trigram` tokenizer (SQLite before 3.34) the index falls back to whole words with prefix matching. Tool usage, tool outputs and intermediate thinking are not indexed: [backlog 0849](backlog/proposed/0849_conversation_search_tool_usage_outputs_and_thinking.md)
+
 ## Run history bundle export (portable replay artifact)
 
 Implementation: `src/abstractruntime/history_bundle.py`.
@@ -306,7 +330,7 @@ from Core route resolution and persisted from `LLM_CALL` results.
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install abstractruntime` (AbstractCore 2.24.0 or newer is part of the base install).
+Requires: `pip install abstractruntime` (AbstractCore 2.30.0 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -322,6 +346,7 @@ Entry points:
 - discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog`, `list_tts_models`, `list_stt_models`, `list_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`, `list_vision_adapters`)
 - the host's OpenAI credential for AbstractVoice's `openai` engines, `voice_openai_api_key`, travels two ways. For discovery, pass it to `get_voice_catalog`, `list_tts_models` or `list_stt_models`; the local clients hand it to the voice plugin's config, and a remote client never sends it (a remote AbstractCore server uses its own voice configuration). For execution, put it in `create_local_runtime(llm_kwargs={"voice_openai_api_key": ...})`. Constructor kwargs become the provider's `config`, which is also the capability-plugin config. Providers read only the keys they name, so a `voice_*` key changes no text request (tests `tests/test_voice_openai_api_key_path.py`)
 - host-facade client delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, `prompt_cache_prepare_modules`, `upsert_text_bloc`, `get_bloc_record`, `list_blocs`, `get_bloc_kv_manifest`, `ensure_bloc_kv_artifact`, `load_bloc_kv_artifact`, `list_bloc_kv_artifacts`, `delete_bloc_kv_artifact`, `prune_bloc_kv_artifacts`, `delete_bloc`, `get_model_residency_capabilities`, `list_model_residency`, `load_model_residency`, `unload_model_residency`, `get_memory_snapshot`, `list_session_prompt_caches`, `clear_session_prompt_caches`, `lock_model_residency`, `unlock_model_residency`, `get_context_estimate`); the last six are optional in the client contract, and the facade returns `{"ok": false, "supported": false, ...}` when the configured client does not implement one
+- `integrations.abstractcore.llm_client.set_default_model_warmup(enabled)` (process-wide, no environment variable): whether a new `MultiLocalAbstractCoreLLMClient` builds (for a local model: loads) its default model at construction and on a default switch. Default on. A process that serves no model turns it off once at boot (the gateway's `serve --no-runner`); the default client is then built at its first call. `default_model_warmup()` reads the setting (see `integrations/abstractcore.md#unloading-and-switching-models`)
 - switching the default model (`set_default_provider_model` on the pooled client) unloads the previous in-process model unless an owner in the process still uses it; `list_model_residency` diagnostics report `pending_ejects` and `last_switch_ejects`, and `unload_model_residency(runtime_id=...)` accepts any listed `local:<task>:<provider>:<model>` id, including `local:embedding:<provider>:<model>` rows (see `integrations/abstractcore.md#unloading-and-switching-models`)
 - `lock_model_residency`, `unlock_model_residency`, and `get_context_estimate` accept an optional payload mapping and/or keyword arguments (keyword arguments win on conflicts); a lock requires provider-verified residency — locking a non-resident pair refuses with a structured `model_not_resident` payload (load with `lock: true` instead; remotely the Core server's HTTP 409 refusal is converted to the same payload), while unlock never requires residency so a locked-but-evicted pair is always releasable; a locked model refuses `unload_model_residency` with a structured `model_locked` payload — locally as a client-side per-`(provider, model)` lock, remotely by converting the Core server's HTTP 409 refusal — and unloads only with `force=true`, releasing the lock only after the unload succeeds
 - the `MODEL_RESIDENCY` effect supports `list_loaded`, `load`, `unload`, `lock`, and `unlock` operations with the same soft-fail semantics; on `unload`, `force` is forwarded only when authored in the effect payload
@@ -352,6 +377,7 @@ Multimodal support:
 - remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, image edits, image upscaling, text-to-video, image-to-video, speech, music generation, and transcription endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
 - remote transcription requires one audio media item that resolves to a local file path or artifact-backed temporary file
 - generated image/video/voice/music/audio bytes require a runtime `ArtifactStore`; the result contains `artifact_id` / `artifact_ref` instead of inline bytes
+- streamed TTS playback artifacts carry `purpose=voice_playback`, `artifact_space=voice` and a logical `voice/tts-<id>.wav` path in their tags; hosts can separate read-aloud recordings from user attachments while retaining their artifact refs and provenance
 - with the pooled local client (`MultiLocalAbstractCoreLLMClient`), a request whose outputs are all non-text (image, video, voice, music, transcription) and that carries no tools never builds the text client: it runs on AbstractCore's capability host (`CapabilityHostProvider`, no text model), and so does streaming TTS. A text default that cannot be built (an engine not installed) therefore never blocks speech or image generation
 - media-only normalized results expose `runtime_provider` / `runtime_model` separately from `media_provider` / `media_model`
 - local image/video generation runs in a one-shot subprocess (`execution_mode="local_one_shot_subprocess"`) unless every requested media model is resident (explicitly loaded with `load_model_residency`), in which case it runs in-process on the loaded pipeline (`execution_mode="resident_in_process"`, `resident_load_ids`)

{abstractruntime-0.10.5 → abstractruntime-0.12.0}/docs/architecture.md

@@ -286,6 +286,10 @@ Registered in `Runtime._register_builtin_handlers()` (`src/abstractruntime/core/
 
 ### Host-wired effects
 The kernel defines the protocol; concrete integrations provide handlers:
+- `PUBLISH_EVENT` ("Publish to channel"): the kernel validates the payload; the host's
+  `Runtime.set_publish_event_handler(...)` appends the event to the user's stream (see
+  [automations.md](automations.md#publish-to-channel))
+- `SCHEDULE_RUN`: the kernel validates the request and plans a one-shot automation (tools at most the caller's ceiling, never `schedule_run` itself); the host's `Runtime.set_schedule_run_handler(...)` creates it, because only the host knows the target workflow, the owner and the workspace (see [automations.md](automations.md#wakes-schedule_run))
 - `LLM_CALL`, `TOOL_CALLS`, `MODEL_RESIDENCY`: provided by AbstractCore integration (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). The integration supports local/remote/hybrid execution, cached sessions/prompt-cache control with per-session attribution and clearing, host memory snapshots, discovery/catalog snapshots, model residency including host-wide provider-server rows in listings, residency locks with `force`-gated unload and context-estimate relays, durable run-scoped media child runs, media inputs, generated media outputs, provider progress callbacks as ledger events, provider-key header routing for remote servers, passthrough tools, approval-gated local tool execution, and workspace-scoped file and shell tools (run vars `workspace_*`, inherited by child runs; the host's built-in deny prefixes are enforced without being rendered into the model's prompt).
 - `MEMORY_KG_*`: provided by the AbstractMemory bridge (`src/abstractruntime/integrations/abstractmemory/effect_handlers.py`)
 
@@ -307,8 +311,66 @@ Decorators/helpers:
 - `HashChainedLedgerStore` for tamper-evidence (`src/abstractruntime/storage/ledger_chain.py`)
 - `ArtifactStore` + helpers (`src/abstractruntime/storage/artifacts.py`)
 - `OffloadingRunStore` / `OffloadingLedgerStore` to keep checkpoints bounded (`src/abstractruntime/storage/offloading.py`)
+- `MailboxQueryableRunStore` (`list_mailbox_runs`, `next_wait_deadline`) on every built-in run store, for event fan-out and wake scheduling without a recency window
 - snapshots/bookmarks (`src/abstractruntime/storage/snapshots.py`)
 
+### Reading a large run folder without scanning it
+
+A JSON run folder can hold tens of thousands of run files. `JsonFileRunStore` keeps in memory what
+listings and lookups need, so a host polling it never globs or stats every file:
+
+```mermaid
+flowchart LR
+  subgraph Writers["Writers on one run folder"]
+    Own["This store object<br/>(save / create / delete)"]
+    Other["Another process<br/>(a split host's other half)"]
+  end
+  Folder[("Run files<br/>&lt;run_id&gt;.json")]
+  Log[(".runs_created.log<br/>+ - ~ = lines")]
+  subgraph Store["JsonFileRunStore (in memory)"]
+    Active["Active index<br/>RUNNING / WAITING"]
+    Trusted["Trusted run index<br/>every run's listing fields"]
+    Waits["Event-wait and<br/>mailbox indexes"]
+    Token["change_token()<br/>(log size, counter)"]
+  end
+  Recon["Reconciliation<br/>(background, ≤ 60 s when moved, ≥ every 10 min)"]
+  Own --> Folder
+  Own --> Log
+  Own --> Active
+  Own --> Trusted
+  Own --> Token
+  Other --> Folder
+  Other --> Log
+  Log -->|"next lookup"| Active
+  Log -->|"next lookup"| Trusted
+  Log -->|"size moved, or every 2 s"| Waits
+  Folder -.->|"mtime moved"| Waits
+  Folder -.->|"mtime moved: re-read RUNNING / WAITING entries"| Trusted
+  Recon -->|repairs, logs a warning| Trusted
+  Folder -.-> Recon
+```
+
+- **Active index**: `list_runs` / `list_run_index` for RUNNING or WAITING and the scheduler's due-wait
+  poll, re-verified against each file at listing time.
+- **Trusted run index** (`trust_index=True`, the default): every other listing without a session
+  scope is answered from memory; `trust_index=False` (verify) answers with the scan and counts
+  differences (`run_index_stats()`). The background reconciliation repairs what a writer that
+  bypassed the creation journal left out; `load()` always reads disk.
+- **Event-wait and mailbox indexes** see runs another process parked (refreshed before each
+  lookup when the journal or the folder moved, at least every 2 s).
+- **Change tokens**: `JsonFileRunStore.change_token()` and `ObservableLedgerStore.change_token()`
+  (with `changed_run_ids(token)`) let a periodic reader skip a pass when nothing changed and read
+  only what did.
+- **Active-consumers index** (`abstractruntime.automations.consumers`): one snapshot per runtime of
+  which ACTIVE automation reads which trigger, rebuilt on the store's automation generation, so
+  "who listens to this connection or mailbox?" reads no run file.
+- **Artifacts**: `ArtifactStore.list_session_candidates(session_id, owner_run_id=)` answers a
+  session's artifacts through catalog indexes instead of reading the catalog.
+
+Details and the exact counters: [api.md, Storage layer](api.md#storage-layer-durability-backends)
+and [artifacts.md](artifacts.md). One process ticks a folder; see
+[automations.md, Storage guarantees](automations.md#storage-guarantees).
+
 ## Drivers: scheduler
 
 The scheduler is an in-process driver loop that resumes due waits and can deliver external events:
@@ -320,8 +382,9 @@ The scheduler is an in-process driver loop that resumes due waits and can delive
 An automation runs a target workflow on a trigger, and is itself a durable run. The controller is a packaged
 VisualFlow bundle (`abstractframework.automation-controller@1.0.0`) whose nodes are `automation` adapters; it waits on
 one `WAIT_EVENT` with a deadline, starts each occurrence as an asynchronous `START_SUBWORKFLOW` child with a
-deterministic id, and records every transition as an `automation.*` ledger record. No new effect type or driver is
-involved: a host drives a controller like any other run. See [automations.md](automations.md).
+deterministic id, and records every transition as an `automation.*` ledger record. The controller needs no effect type or driver of its
+own: a host drives it like any other run. A run creates a one-shot automation for later through `SCHEDULE_RUN` (a
+wake). See [automations.md](automations.md).
 
 ```mermaid
 flowchart LR
@@ -332,8 +395,10 @@ flowchart LR
   subgraph Automations["automations/ + triggers/"]
     Commands["apply_automation_command"]
     Controller["controller run<br/>(automation-controller@1.0.0)"]
-    Triggers["trigger registry<br/>schedule@1, schedule@2, manual@1,<br/>email.received@1, entry-point sources"]
-    Inbox["event inbox<br/>(email/, filled by the host's watcher)"]
+    Triggers["trigger registry<br/>schedule@1, schedule@2, manual@1,<br/>email.received@1, feed.item@1,<br/>webhook.received@1, entry-point sources"]
+    Conns["trigger connections<br/>(per user: feed URL, webhook secret)"]
+    Inbox["event inbox<br/>(streams email:… and trigger:…,<br/>filled by the host's feeders)"]
+    Wakes["wakes<br/>(SCHEDULE_RUN plans,<br/>the host creates)"]
     Queries["get_automation / list_occurrences /<br/>list_attention / pending_waits /<br/>list_automations"]
   end
   subgraph Runs["runs"]
@@ -353,6 +418,9 @@ flowchart LR
   Loop --> Occ
   Controller -->|"prepare / admit / rearm"| Triggers
   Controller -->|"events after its cursor"| Inbox
+  Commands -.->|"create / revise:<br/>connection_id check"| Conns
+  Occ -->|"SCHEDULE_RUN"| Wakes
+  Wakes -->|"one-shot automation"| Commands
   Controller -->|"START_SUBWORKFLOW run_id"| Occ
   Occ --> Desc
   Controller --> RS
@@ -363,6 +431,33 @@ flowchart LR
   Queries --> LS
 ```
 
+### Events reaching an occurrence
+
+```mermaid
+flowchart LR
+  subgraph Sources["host-side feeders"]
+    Mail["mail watcher<br/>(EmailInboxFeeder.poll)"]
+    Feed["feed poller<br/>(poll_feed_connections)"]
+    Hook["webhook route<br/>(append_webhook_event,<br/>Standard Webhooks check)"]
+    Test["console test-fire<br/>(test_fire)"]
+  end
+  Inbox["EventInbox<br/>stream per mailbox folder / per connection<br/>dedupe on dedupekey"]
+  Ctrl["controller run<br/>admit: adapter batches events<br/>after its cursor"]
+  Occ["occurrence run<br/>prompt: [Trigger …] header (+ untrusted frame)<br/>input_data.event: CloudEvents 1.0<br/>_meta.origin: trigger / person / agent"]
+  Mail --> Inbox
+  Feed --> Inbox
+  Hook --> Inbox
+  Test --> Inbox
+  Sources -.->|"wake the bound controllers"| Ctrl
+  Inbox --> Ctrl
+  Ctrl -->|"START_SUBWORKFLOW"| Occ
+```
+
+Feeders append one event per mail, feed item or webhook call to the inbox stream of a mailbox folder
+(`email:<tenant>:<user>:<mailbox>:<folder>`) or of a trigger connection (`trigger:<connection_id>`), then wake the
+automations bound to it. The controller reads only its own streams, its adapter turns the pending events into one
+admission, and the occurrence receives the envelope as a CloudEvents 1.0 event beside its prompt header.
+
 Email automations read the runtime's durable event inbox: the host's mail watcher appends each new message
 (`abstractruntime.email.feeder`) and wakes the controller, and the `email.received@1` adapter batches the messages
 after the automation's cursor. Tool calls resolve the executing run's email account through the host's per-runtime
@@ -378,6 +473,8 @@ Invariants the design rests on:
   application.
 - **One lock per run.** `run_mutation_lock(run_id)` serializes `tick`, `resume` commits and automation commands in a
   process. v1 supports one writer process per store.
+- **Origin is recorded once.** Every occurrence carries `_meta.origin` (`trigger`, `person` for a run-now, `agent`
+  for a wake) frozen with its inputs; hosts stamp the runs they start with `origin_for(...)`.
 - **Turns are defined once.** `select_session_turns` decides which runs are a session's turns (parent-less runs
   except controllers, plus occurrences). History bundles, session replay, growing context and discussion seeds all
   use it, and `list_run_index(root_only=True)` returns the same turn roots.