AbstractRuntime 0.7.3__tar.gz → 0.8.1__tar.gz

{abstractruntime-0.7.3 → abstractruntime-0.8.1}/.github/workflows/ci.yml

@@ -56,7 +56,17 @@ jobs:
             tests/test_budget_law_no_unrequested_caps.py \
             tests/test_discovery_voice_openai_api_key.py \
             tests/test_voice_openai_api_key_path.py \
-            tests/test_discovery_tts_unavailable_reason.py
+            tests/test_discovery_tts_unavailable_reason.py \
+            tests/test_abstractcore_comms_facade.py \
+            tests/test_abstractcore_discovery_facade.py \
+            tests/test_automation_definition.py \
+            tests/test_automation_tool_approval.py \
+            tests/test_default_tools_comms_gating.py \
+            tests/test_every_path_bearing_tool_is_walled.py \
+            tests/test_packaging_extras.py \
+            tests/test_tool_catalog.py \
+            tests/test_trigger_registry.py \
+            tests/test_workspace_read_only.py
 
   build:
     name: Build distributions

{abstractruntime-0.7.3 → abstractruntime-0.8.1}/CHANGELOG.md

@@ -7,6 +7,150 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-09-30
+
+Email automations never trigger themselves, speech and images work without a buildable text model,
+and a chat's mail to its owner runs without asking. Requires AbstractCore 2.20.2.
+
+### Added
+- Mail sent by an automation run (controller, occurrence, any run it starts, the send-email action)
+  is automatic mail: the run's `EmailContext` gets `automation_marker =
+  "automation:<automation id>/run:<run id>"`, so every send carries `Auto-Submitted` and
+  `X-AbstractFramework-Automation`. `automation_marker_for(vars, run_id)` is exported from
+  `abstractruntime.email.binding`. Chats and discussions send ordinary mail.
+- `email.received@1` config `auto_submitted`: `"skip"` (default) never admits a message whose
+  `Auto-Submitted` header is present and not `no`; `"admit"` lets it reach the filters. Stored
+  configs without the key behave like `"skip"`.
+- `EmailInboxFeeder(..., is_own_sent=callable)` and `PollReport.own_automatic`: the account's own
+  automatic mail (the framework marker from its own address, or a Message-ID the host recorded as
+  sent) never enters the event inbox.
+- `abstractruntime.integrations.abstractcore.run_facade.inline_run_active(run_id)`: true while the
+  run facade executes a child run in this process; host runners skip such runs.
+- `ToolApprovalPolicy.default_require_approval_tools`: the names on the require list only because
+  no list was given (the default caution list).
+
+### Changed
+- The pooled local client runs media-only requests (image, video, voice, music, transcription, no
+  tools) and streaming TTS on AbstractCore's capability host instead of building the default text
+  client: text-to-speech no longer fails when the text default cannot be built (for example an
+  MLX route on an install without MLX), and no text model is loaded for a media request.
+- Without a per-run tool policy, the `send_email_recipient@v2` refiner now also lowers a name that
+  is on the executor's default caution list (`send_email` under `ToolApprovalPolicy()`): a chat
+  run's send to its owner's own address runs without an approval wait. An explicitly passed
+  require list and a per-run policy's still win; email-triggered runs under `approval: "ask"` are
+  unchanged.
+
+### Dependencies
+- `abstractcore>=2.20.2` (also `[apple]` and `[gpu]`).
+
+## [0.8.0] - 2026-09-30
+
+### Added
+
+- **Email for each user** (see `docs/email.md`). A run acts for one account: its non-secret binding
+  `_runtime.email_account = {account_ref, address}` is resolved at the moment a tool needs it through the host's
+  per-runtime resolver (`Runtime.set_email_context_resolver(fn)`), so credentials never enter run vars, the ledger,
+  tool arguments or results. `Runtime.set_email_binding(...)` binds automation occurrences; hosts set root runs with
+  `bind_email_account(...)` after `strip_client_email_keys(...)`. Child runs inherit the binding and the
+  pre-authorised recipients (the parent's value wins). Once a runtime has a resolver, AbstractCore's email tools in
+  that process never fall back to the local AbstractCore settings.
+- **`send_email_recipient@v2` approval refiner.** A `send_email` runs without an approval wait only when every
+  recipient is the registered address (`_runtime.operator_email`) or is listed in `_runtime.email_allowed_recipients`;
+  `reply_email`, unknown argument keys and anything unproven ask. The account's recipient policy and send limits
+  (AbstractCore `guarded_send`) still apply to every send.
+- **Durable event inbox and mail feeder** (`abstractruntime.email`): `JsonFileEventInbox` / `InMemoryEventInbox`
+  (append-only, unique event ids, per-stream dedupe keys and state, crash-repaired index), attached with
+  `Runtime.set_event_inbox(...)`; `EmailInboxFeeder.poll(ctx)` appends each new message whole, advances its
+  UIDVALIDITY + UID cursor only after a durable append, resynchronises after a folder rebuild without loss or
+  duplicates, passes a message that fails three polls, and reports connection failures as typed
+  `{code, cause, fix, retryable}` with a capped backoff (60 s to 15 min). `email_trigger_consumers(...)` and
+  `wake_email_automations(...)` serve the host's watcher.
+- **`email.received@1` trigger source.** Typed filters (`from_in`, `from_domain_in`, `to_in`, `subject_contains`,
+  `has_attachment`), batches no more often than `every` (default `1h` for automations that run a model, `60s`
+  otherwise; at least `60s`), up to `max_batch` messages, each message at most once per automation across restarts
+  and folder rebuilds. Occurrences receive the messages as `input_data.trigger` marked `content_trust: "untrusted"`
+  and, for a string `prompt`, inside a fixed untrusted frame whose markers carry a boundary token drawn at random
+  for each occurrence (a body cannot fake the end of its email). The messages and the framed prompt are stored as
+  artifacts at admission: `automation.admitted`, `pending_occurrence` and the dispatch effect carry refs, metadata and
+  event ids, never bodies, and the occurrence run resolves the refs when it starts. Creating this trigger on a
+  runtime without an artifact store is refused (`unsupported_feature`).
+- **Send-email action** (`abstractframework.email-actions@1.0.0:send_email`, `register_email_action_workflow`,
+  `email_action_target`): automations without a model send templated mail (fixed placeholders, `each` or `digest`
+  mode) through an ordinary `send_email` tool call, under the same approval rule, policy and limits.
+- **Automation definition schema v2**: `policy.email_allowed_recipients` (`"self"` and exact addresses, default
+  `["self"]`, frozen into each occurrence) and `notify.channels` (`["console"]` or `["console", "email"]`), which
+  attention items carry as `channels`. Stored v1 definitions read with the defaults.
+- **Email tools follow the host's decision**: `email_enabled=` on `get_default_toolsets`, `get_default_tools`,
+  `list_default_tool_specs`, `build_default_tool_map` and `list_tool_catalog`; the email kind adds `reply_email`,
+  `search_emails`, `get_email_attachment` and the read-only `list_email_folders`.
+- **Oversized mail never blocks the feeder**: a message over AbstractCore's reading limit is appended with its headers,
+  attachment list and typed `body_skipped` record (bodies `null`, never cut), listed in `PollReport.body_skipped`,
+  passed to occurrences in `input_data.trigger.emails[].body_skipped` and shown as `Body (not fetched)` in the frame.
+- **The resolver learns who is sending** (`use="agent_tool"` or `use="action"`), so a host applies its users'
+  "agent email tools" choice to agent tools only; the send-email action is identified by its node function.
+- **`email_facade`** (`abstractruntime.integrations.abstractcore.email_facade`): AbstractCore's mail library for hosts.
+- **Event-inbox retention**: `EventInboxRetention` (default 90 days and 10,000 events), `inbox.prune(...)` and
+  `prune_email_inbox(runtime, retention=...)`, which never removes an event an active email automation has not read.
+- **`policy.untrusted_input_tools`**: tools named one by one that an email-triggered occurrence may run without asking
+  although "allow all tools" does not cover them there; message-sending tools are never granted this way.
+- **`START_SUBWORKFLOW` `payload.resolve_vars`**: top-level vars whose artifact refs are resolved for the child only
+  (strict: a missing artifact fails the start), so the parent's ledger and node traces keep the refs.
+- **Tool facts for untrusted input** (`tool_effects`): `TOOL_NETWORK_REACH` (`none`, `configured`, `open`, `send`) and
+  `TOOL_WRITE_SCOPE` (`workspace`, `workspace_only_mode`, `host`, and for the memory tools `run` and `memory`) for
+  every tool the runtime exposes, with `untrusted_input_grantable(...)`.
+- `list_tool_catalog(email_off_reason=...)` names why email is off (`not_connected`, `admin_disabled`,
+  `not_available` — the administrator has not made agent email tools available to this user — and `agent_tools_off`).
+
+### Changed
+
+- **Requires AbstractCore 2.20.0 or newer** (`abstractcore.comms.email`, the email tools on a per-run resolver).
+- **Email-triggered automations act only within the user's mission** (operator decision 2026-09-30). Under
+  "allow all tools", an automation triggered by `email.received@1` grants by kind, decided on tool facts and never on
+  names: only tools with no network egress beyond configured services, no code or command execution, no message
+  sending, no writes outside the run's workspace and no delegation run unattended (file reads, workspace-confined
+  file writes, mailbox reads, `get_email_attachment`, `recall_memory` and `update_plan`). `fetch_url`,
+  `browser_probe`, `skim_url`, `skim_websearch`, `web_search`, `execute_command`, `shell_exec`, `execute_python`,
+  `delegate_agent`, `channel_fs_write`, `agora_post_message`, `agora_send_dm`, the camera tools, the memory-writing
+  tools (`remember`, `remember_note` including `scope: "global"`, `compact_memory`: they write the user's lasting
+  memory, outside the run's workspace, so a stranger's email cannot plant a note later runs obey), MCP tools and
+  every other tool ask, unless the user named them one by one in `policy.untrusted_input_tools`; message-sending
+  tools (`send_email`, `reply_email`, `agora_post_message`, `agora_send_dm`, WhatsApp and Telegram sends) are never
+  granted, named or not. Schedule and manual automations keep the full grant. `reply_email` is withheld like
+  `send_email` everywhere.
+- **Email-triggered automations under "ask" run nothing unasked** (re-gate 2026-09-30). Their occurrences always carry
+  a per-run tool policy: under `policy.tool_approval: "ask"` it auto-approves only the tools the user named in
+  `policy.untrusted_input_tools` (sending tools never) and requires approval for every other tool, so neither the
+  executor's static defaults (which auto-run `skim_url`, `web_search`, the agora posts and the Telegram sends) nor a
+  per-call refiner decide there. The policy replaces any `tool_policy` the target inputs carried
+  (`replaced_target_policy: true`) and is marked `untrusted_input: true`, beside the run flag
+  `_runtime.untrusted_input`. Child runs inherit both, the parent's value winning over the child's own. Defence in
+  depth: for a run with that flag the approval executor never consults its static policy or a tier ceiling, runs a
+  listed tool unasked only when the user named it or (under "auto") its facts pass `untrusted_input_allow_all`,
+  never runs a sending tool unasked, and applies the per-call refiners only under "auto".
+- `send_email` / `reply_email` `attachments` and `get_email_attachment`'s `output_dir` are confined to the run's
+  workspace in every workspace access mode (ignored paths and the host's protection still apply);
+  `get_email_attachment` is a `write` tool.
+- A run policy that only withholds tools (`tool_policy.withheld_tools`) is applied like any other run policy, so the
+  per-call refiners run for it.
+- The per-call refiners (`send_email_recipient@v2`) also run when a run carries no `_runtime.tool_policy`, on top of
+  the executor's static policy (its `require_approval_tools` still wins), and decide per call: one `send_email` that
+  needs a person makes the batch wait.
+- No environment variable enables the email tools: `ABSTRACT_ENABLE_EMAIL_TOOLS` is gone and
+  `ABSTRACT_ENABLE_COMMS_TOOLS` enables WhatsApp and Telegram only; pass `email_enabled=True`.
+- The untrusted frame tells the agent not to follow links or instructions contained in the emails and to act only
+  on the automation's mission.
+- After a folder rebuild with nothing to resynchronise, the feeder stores the new baseline AbstractCore returns
+  (`reset` and `baseline`) instead of fetching one itself.
+- Large structured tool outputs (for example a `read_email` with a big HTML body) are offloaded to session
+  attachments under the same inline limit as text outputs; the result carries artifact references.
+- The process-local email helpers (`list_email_accounts`, `list_emails`, `read_email`, `send_email`) are no longer
+  exported from `abstractruntime.integrations.abstractcore`; they remain on the host facade for single-user installs.
+
+### Removed
+
+- `emails.config.example.yaml` (environment-variable email setup) is no longer shipped; email is configured through
+  the host's per-user settings.
+
 ## [0.7.3] - 2026-09-29
 
 ### Security

{abstractruntime-0.7.3 → abstractruntime-0.8.1}/CONTRIBUTING.md

@@ -27,6 +27,30 @@ Inside the AbstractFramework workspace, prefer `python -P -m pytest tests -q`: `
 
 If you cloned **only** this repo (without the AbstractFramework workspace), make sure the sibling packages above are importable (install them or clone them next to this repo) before running the full test suite.
 
+### Live email tests (opt-in)
+
+`tests/live_email/` runs the email integration against a **real test mailbox** (framework backlog 0992 WP2): an
+`email.received@1` automation admits one uniquely tagged self-sent message exactly once (not again on a second poll,
+a later wake or a restarted runtime), and a `send_email` tool call to the account's own address runs unattended while
+one to another address parks on a `tool_approval` wait and is never sent. The tests carry the `live_email` marker, are
+not `basic` (CI never selects them), and are skipped unless every variable below is set.
+
+The test harness reads the mailbox from environment variables (the tests' input only; the runtime still gets its
+account from the host resolver): `AF_TEST_EMAIL_IMAP_HOST`, `AF_TEST_EMAIL_IMAP_PORT`, `AF_TEST_EMAIL_IMAP_SECURITY`,
+`AF_TEST_EMAIL_SMTP_HOST`, `AF_TEST_EMAIL_SMTP_PORT`, `AF_TEST_EMAIL_SMTP_SECURITY`, `AF_TEST_EMAIL_USERNAME`,
+`AF_TEST_EMAIL_ADDRESS`, `AF_TEST_EMAIL_PASSWORD`. Keep them in a private file (mode 0600) and load it into the test
+process only:
+
+```bash
+set -a; . ~/.config/abstractframework-test/email.env; set +a; \
+  python -P -m pytest tests/live_email -m live_email -s --durations=0
+```
+
+No credential value is printed (redacting objects, scrubbed failure reports), mail only goes to the test account's
+own address (a guard refuses any other recipient before `MAIL FROM`), and messages are small and tagged
+`[af-live-test]`: the mailbox is read-only, so nothing can be cleaned up. Use a dedicated test mailbox. AbstractCore's
+`tests/email/live/` covers the mail library itself.
+
 ## Repo map (source of truth)
 
 - Public exports: `src/abstractruntime/__init__.py` (keep this consistent with `docs/api.md`)

{abstractruntime-0.7.3 → abstractruntime-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.7.3
+Version: 0.8.1
 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,7 +20,7 @@ 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.19.2
+Requires-Dist: abstractcore>=2.20.2
 Requires-Dist: abstractmemory>=0.3.0
 Requires-Dist: abstractsemantics>=0.0.5
 Requires-Dist: anyio<5.0.0,>=4.12.1
@@ -35,16 +35,17 @@ 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.19.2; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.20.2; 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.19.2; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.20.2; 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'
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
@@ -54,7 +55,7 @@ Description-Content-Type: text/markdown
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.7.3 • **Python:** 3.10+
+**Version:** 0.8.1 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -82,7 +83,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.19.2 or newer (its light install:
+The base install includes AbstractCore 2.20.2 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
@@ -146,7 +147,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.7.3)
+## What’s included (v0.8.1)
 
 Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -158,7 +159,7 @@ 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) 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), 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`)
 - 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:
@@ -239,6 +240,7 @@ sr = create_scheduled_runtime(
 | [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 |
 | [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.7.3 → abstractruntime-0.8.1}/README.md

@@ -4,7 +4,7 @@
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.7.3 • **Python:** 3.10+
+**Version:** 0.8.1 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -32,7 +32,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.19.2 or newer (its light install:
+The base install includes AbstractCore 2.20.2 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
@@ -96,7 +96,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.7.3)
+## What’s included (v0.8.1)
 
 Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -108,7 +108,7 @@ 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) 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), 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`)
 - 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:
@@ -189,6 +189,7 @@ sr = create_scheduled_runtime(
 | [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 |
 | [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.7.3 → abstractruntime-0.8.1}/docs/README.md

@@ -28,14 +28,15 @@ 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, 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)
-- `tool-approval.md` — tool risk tiers, the run-policy rank ceiling, and per-call refiners (the `send_email` self-recipient rule)
+- `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
+- `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#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`, `manual@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 or on request as a durable controller run; triggers (`schedule@1`, `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)
 - `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.7.3 → abstractruntime-0.8.1}/docs/api.md

@@ -64,7 +64,7 @@ Implementation: `src/abstractruntime/core/runtime.py`.
 
 - `Runtime.start(workflow, vars=..., actor_id=..., session_id=..., parent_run_id=..., run_id=...) -> run_id`
   - creates and persists a new `RunState`
-  - `run_id` starts the run under an id you choose (`[A-Za-z0-9_-]+`). The run is created only if that id is free; starting it again with the same identity (workflow, session, parent, `vars._meta.occurrence`, `vars._meta.creation_digest`) returns the existing run untouched, and a different identity raises `RunIdentityConflict` (a `ValueError`, `reason_code = "identity_conflict"`). The store must support `create_if_absent` (otherwise `NotImplementedError`). `START_SUBWORKFLOW` accepts the same explicit id as `payload.run_id`
+  - `run_id` starts the run under an id you choose (`[A-Za-z0-9_-]+`). The run is created only if that id is free; starting it again with the same identity (workflow, session, parent, `vars._meta.occurrence`, `vars._meta.creation_digest`) returns the existing run untouched, and a different identity raises `RunIdentityConflict` (a `ValueError`, `reason_code = "identity_conflict"`). The store must support `create_if_absent` (otherwise `NotImplementedError`). `START_SUBWORKFLOW` accepts the same explicit id as `payload.run_id`, and `payload.resolve_vars` (a list of top-level var names) resolves the artifact refs in those vars for the child only, strictly (a missing artifact fails the start), so the parent's records keep the refs
   - a root run that names a session is checked against the session's attribution: in a discussion session it gets the discussion's workspace setup (its own writable workspace and the read-only mount) and provenance, and when the attribution cannot be read (an invalid discussion root, or a store without a run index) the start raises `SessionAttributionError` (see [automations.md](automations.md#discussions))
 - `Runtime.tick(workflow, run_id, max_steps=..., step_gate=None) -> RunState`
   - executes node handlers and effects until the run becomes `WAITING`, `COMPLETED`, `FAILED`, or `CANCELLED`
@@ -241,7 +241,32 @@ from abstractruntime.triggers import get_trigger_adapter, trigger_sources
 - 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)`
 - `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` and `manual@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`, `manual@1` and `email.received@1`, third-party sources through the `abstractruntime.trigger_sources` entry-point group
+- definition v2: `policy.email_allowed_recipients` (default `["self"]`), `policy.untrusted_input_tools` (default `[]`) and `notify.channels` (default `["console"]`); attention items carry `channels`
+
+## Email
+
+Implementation: `src/abstractruntime/email/*`, `src/abstractruntime/triggers/email_received.py`. Deep dive: [email.md](email.md).
+
+```python
+from abstractruntime.email import (
+    EmailBinding, bind_email_account, strip_client_email_keys, binding_of,   # run-scoped binding
+    JsonFileEventInbox, InMemoryEventInbox,                                  # durable event inbox
+    EmailInboxFeeder, PollReport, email_event_id,                            # mailbox -> inbox
+    email_trigger_consumers, wake_email_automations, prune_email_inbox,      # watcher helpers
+    EventInboxRetention,                                                     # inbox retention (90 days / 10,000 events)
+    EMAIL_USE_AGENT_TOOL, EMAIL_USE_ACTION, email_use_for_workflow,          # who is sending
+    email_action_target, register_email_action_workflow, validate_email_action, render_email_template,
+)
+```
+
+- `Runtime.set_email_context_resolver(fn)`: `fn(binding, *, use) -> EmailContext | None` (`use` is `"agent_tool"` or `"action"`; `fn(binding)` also accepted), per runtime, memory only
+- `Runtime.set_email_binding(binding | None)` / `Runtime.email_binding`: the account occurrences are bound to
+- `Runtime.set_event_inbox(inbox)` / `Runtime.event_inbox`: required by `email.received@1`
+- `EmailInboxFeeder(inbox, account_ref=...).poll(ctx, *, now=None, force=False) -> PollReport` and `.status()`
+- toolsets: `get_default_toolsets(..., email_enabled=True)` (also `list_default_tool_specs`, `build_default_tool_map`, `list_tool_catalog`); no env flag; `list_tool_catalog(email_enabled=False, email_off_reason="not_connected" | "admin_disabled" | "not_available" | "agent_tools_off")`
+- mail library for hosts: `abstractruntime.integrations.abstractcore.email_facade` re-exports `abstractcore.comms.email` (its `__all__` plus the `legacy` module; `GATEWAY_NAMES` lists the names hosts use)
+- approval: the `send_email_recipient@v2` refiner ([tool-approval.md](tool-approval.md#per-call-refiners))
 - `adopt_legacy_schedule_projection(run)`: read-only summary of a legacy gateway `scheduled:*` root
 - read-only mounts: `_runtime.workspace_read_only_paths` (absolute folders; file write tools and VisualFlow writers refused inside, reads and command/code tools allowed); helpers `read_only_paths(vars)`, `path_is_read_only(vars, path)` and `READ_ONLY_PATHS_KEY` in `abstractruntime.utils.workspace_paths`
 - read-only workspaces: run vars `workspace_read_only: true` (or `_runtime.workspace_read_only: true`); `abstractruntime.integrations.abstractcore.tool_effects.TOOL_EFFECT_CLASSES` classifies every exposable tool as `read`, `write`, `exec`, `delegate`, `comms` or `memory-write`
@@ -277,7 +302,7 @@ from Core route resolution and persisted from `LLM_CALL` results.
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install abstractruntime` (AbstractCore 2.19.2 or newer is part of the base install).
+Requires: `pip install abstractruntime` (AbstractCore 2.20.2 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -285,9 +310,9 @@ Entry points:
 - `create_local_runtime(...)`, `create_remote_runtime(...)`, `create_hybrid_runtime(...)` (`src/abstractruntime/integrations/abstractcore/factory.py`)
 - public discovery facade: `AbstractCoreDiscoveryFacade`, `get_abstractcore_discovery_facade(...)` (`src/abstractruntime/integrations/abstractcore/discovery_facade.py`)
 - public host facade: `AbstractCoreHostFacade`, `get_abstractcore_host_facade(...)` (`src/abstractruntime/integrations/abstractcore/host_facade.py`)
-- public email comms wrappers: `list_email_accounts(...)`, `list_emails(...)`, `read_email(...)`, `send_email(...)` (`src/abstractruntime/integrations/abstractcore/comms_facade.py`)
+- email facade: `email_facade` (AbstractCore's mail library for hosts; see [Email](#email))
 - public Telegram host wrappers: `TelegramTdlibNotAvailable`, `bootstrap_telegram_auth_from_env(...)`, `get_global_telegram_client(...)`, `stop_global_telegram_client()`, `send_telegram_message(...)` (`src/abstractruntime/integrations/abstractcore/telegram_facade.py`)
-- public durable run facade: `AbstractCoreRunFacade`, `get_abstractcore_run_facade(...)` (`src/abstractruntime/integrations/abstractcore/run_facade.py`)
+- public durable run facade: `AbstractCoreRunFacade`, `get_abstractcore_run_facade(...)` (`src/abstractruntime/integrations/abstractcore/run_facade.py`); `inline_run_active(run_id)` is true while the facade executes a child run in this process (its workflow exists only inside that call), so a host runner that scans `RUNNING` runs skips it
 - effect handler wiring: `build_effect_handlers(...)` (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`)
 - tool executors: `MappingToolExecutor`, `AbstractCoreToolExecutor`, `PassthroughToolExecutor`, `ApprovalToolExecutor`, `ToolApprovalPolicy` (`src/abstractruntime/integrations/abstractcore/tool_executor.py`)
 - 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`)
@@ -298,7 +323,7 @@ Entry points:
 - 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
 - local `list_model_residency` merges AbstractCore's host-wide loaded-model sweep into text-generation listings (sweep-only rows carry `source: "provider_server"` and no `task` label), and residency rows normalize provider size extras to `size_bytes` / `size_vram_bytes` while keeping the originals; local text rows also carry registry-declared `modalities` (omitted on a registry miss), host identity (`host_id` / `host_name`), and runtime-owned lock truth (`locked` / `lockable`, with `pinned` a truthful alias of `locked` — never the default-identity flag, which `default` alone carries), while remote listings keep the Core server's row identity
 - host-local prompt-cache export/import admin also lives on the host facade and client delegation layer (`list_prompt_cache_exports`, `prompt_cache_export`, `prompt_cache_import`) and is intentionally local-only
-- host-facade email helpers delegate to Runtime's host-local comms facade/export layer (`list_email_accounts`, `list_emails`, `read_email`, `send_email`)
+- host-facade email helpers (`list_email_accounts`, `list_emails`, `read_email`, `send_email`) use the process's own AbstractCore account (single-user installs)
 - run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `edit_image`, `upscale_image`, `generate_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
 - task-specific image/video helpers preserve batch and adapter controls such as
   `count`/`n`, `seeds`, ordered `lora_adapters`, and video `flow_shift`; local
@@ -323,6 +348,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
+- 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`)
 - optional local media residency failures complete with `status_hint="warning"` and `degraded=true`; local media warmup that no capability plugin can serve (`image_generation`, `image_upscale`, `video_generation`, `text_to_video`, `image_to_video`, `tts`, `stt`, `music_generation`) reports `requires_long_lived_server=true`, and image/video tasks also report `execution_mode="local_one_shot_subprocess"`

{abstractruntime-0.7.3 → abstractruntime-0.8.1}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
 > Updated: 2026-09-29
-> Version: 0.7.3
+> Version: 0.8.1
 > Scope: this describes **what is implemented in this repository**.
 
 AbstractRuntime is a **durable workflow runtime**: it executes workflow graphs as a persisted state machine with explicit waits (user, time, events, jobs, subworkflows). A run can pause for hours/days and resume **without** keeping Python stacks/coroutines alive.
@@ -332,7 +332,8 @@ 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, manual@1,<br/>entry-point sources"]
+    Triggers["trigger registry<br/>schedule@1, manual@1, email.received@1,<br/>entry-point sources"]
+    Inbox["event inbox<br/>(email/, filled by the host's watcher)"]
     Queries["get_automation / list_occurrences /<br/>list_attention / pending_waits /<br/>list_automations"]
   end
   subgraph Runs["runs"]
@@ -351,6 +352,7 @@ flowchart LR
   Loop --> Controller
   Loop --> Occ
   Controller -->|"prepare / admit / rearm"| Triggers
+  Controller -->|"events after its cursor"| Inbox
   Controller -->|"START_SUBWORKFLOW run_id"| Occ
   Occ --> Desc
   Controller --> RS
@@ -361,6 +363,11 @@ flowchart LR
   Queries --> LS
 ```
 
+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
+resolver at call time. See [email.md](email.md).
+
 Invariants the design rests on:
 
 - **Create-if-absent.** Controllers, occurrences and discussions are created under explicit ids through
@@ -409,6 +416,7 @@ AbstractRuntime includes a compiler and a portable bundle format:
 - `getting-started.md` — first steps
 - `api.md` — public API surface (imports + pointers)
 - `automations.md` — automations: controller, triggers, commands, context, discussions, storage guarantees
+- `email.md` — email accounts per run, the event inbox, the `email.received@1` trigger, the send-email action
 - `limits.md` — `_limits` and RuntimeConfig
 - `snapshots.md` — snapshot/bookmark stores
 - `provenance.md` — hash chain and verification

{abstractruntime-0.7.3 → abstractruntime-0.8.1}/docs/artifacts.md

@@ -105,7 +105,12 @@ Offload applies to:
 - `read_file` content above the inline threshold;
 - `execute_command` `stdout` and `stderr`, regardless of exit code (verbose
   failures are offloaded like verbose successes);
-- any other host tool whose string output exceeds the inline threshold.
+- any other host tool whose string output exceeds the inline threshold;
+- any other host tool whose structured (dict) output exceeds the inline threshold as JSON: its largest string
+  values, at any depth, are stored one by one (largest first) until the output fits, each replaced by
+  `{"$artifact": id, "offloaded": true, "bytes": n, "open": "open_attachment(...)"}`; when many small values make
+  it too large, the whole output is stored as one JSON attachment and replaced by its reference. The result lists
+  the stored ids in `output_offloaded_artifact_ids`, and reading the run back resolves the references.
 
 Thresholds (environment-configurable):