AbstractRuntime 0.5.1__tar.gz → 0.6.0__tar.gz

{abstractruntime-0.5.1 → abstractruntime-0.6.0}/CHANGELOG.md

@@ -5,6 +5,131 @@ 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).
 
+## [0.6.0] - 2026-09-27
+
+Automations v1: run a workflow on a schedule or on request as a durable, crash-safe controller run. Hosts that
+fold root runs into sessions should read the **Changed** notes (occurrences appear as session turns).
+
+### Added
+
+- **Automations** (`abstractruntime.automations`, see `docs/automations.md`): run a workflow on a trigger. An
+  automation is a durable controller run (the packaged bundle `abstractframework.automation-controller@1.0.0`), and
+  each firing (an occurrence) is a child run with a deterministic id, so a crash never loses an occurrence or starts
+  one twice. Every transition is an `automation.*` record in the controller's ledger.
+  - `create_automation(runtime, request, *, actor_id=None)` returns `(automation_id, revision)`; the same request
+    returns the same automation and a reused `request_id` with a different request raises `identity_conflict`.
+    `get_automation`, `list_occurrences` and `drive_automation` (a run loop for hosts without one) complete the
+    service API.
+  - `apply_automation_command` pauses, resumes, runs now, revises, stops the current occurrence or archives. Commands
+    are idempotent per `command_id` (a reused id for a different command is refused with `identity_conflict`), are
+    checked against `expected_revision`, and never interleave with the controller. Pause stops scheduled runs only;
+    resume never fires missed runs; revising `policy` changes only the fields sent.
+  - Context: independent occurrences (the default) start fresh in their own session; in growing mode each occurrence
+    joins the automation's session and receives its previous turns (at most 40 messages / 24,000 characters).
+  - Failed occurrences are retried: 3 attempts by default, 30 s then 60 s apart, capped at 10 minutes. An occurrence's
+    inputs are frozen when it is admitted, so a later revision never changes it.
+  - Automations are quiet unless the output carries `notify: true` or `notify: {title, body}`, or an occurrence still
+    fails after its last retry. `list_attention` pages these items oldest first.
+  - `policy.tool_approval`: `"auto"` (default; creating the automation is the consent, and each occurrence receives a
+    frozen `_runtime.tool_policy.auto_approve_tools` grant) or `"ask"`. Unclassified tools still ask.
+  - `pending_waits` lists occurrence runs waiting on a person as typed waits: `ask_user`, `tool_approval` (with the
+    calls to approve in `details`) or `event` (with `{scope, name}` when known); `ANSWER_PAYLOADS` gives the resume
+    payload for each kind.
+  - `start_discussion(..., workspace_root=...)` forks a separate conversation at occurrence N: a new root run in its
+    own session, seeded once with the automation's whole conversation through N (every occurrence 1..N, in either
+    context mode, oldest dropped first under the history budget), working in its own writable workspace with the
+    automation's workspace mounted read-only alongside, and without the automation's tool grant. Discussion sessions
+    are scoped to their automation.
+  - `get_automation` and `list_automations` summaries carry `next_fire_at` for every active scheduled automation,
+    also while an occurrence runs (the tick the controller will admit next, coalescing included), and
+    `current_occurrence` (`{index, run_id, attempt, status}` of the occurrence in flight), so clients never
+    compute schedules themselves.
+  - `adopt_legacy_schedule_projection(run)` summarizes a legacy gateway `scheduled:*` root read-only.
+  - Limits: `every` is at most `366d`, `count` at most 1,000,000.
+- **Trigger sources** (`abstractruntime.triggers`): `schedule@1` (fixed UTC intervals such as `5m` or `24h` on a grid
+  that does not drift; `start_at`, exclusive `until` and `count`; one-shot when `every` is absent; missed ticks run
+  once, marked `coalesced`) and `manual@1`. Other packages add sources through the `abstractruntime.trigger_sources`
+  entry-point group; a broken third-party source is listed as unavailable, and a missing built-in source is an error.
+- VisualFlow node type `automation` (the controller's nodes, adapters `automation.<node_id>`).
+- `abstractruntime.automation_queries`: `list_automations(store, status=, cursor=, limit=)` (automation summaries,
+  newest first, with a cursor that survives restarts; archived automations stay listed) and
+  `latest_occurrence(store, automation_id)`. `changed_since` is refused with `unsupported_feature`.
+- Explicit run ids: `Runtime.start(..., run_id=...)` and `START_SUBWORKFLOW` `payload.run_id` create a run only if the
+  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; a different identity raises
+  `RunIdentityConflict` (a `ValueError`, `reason_code = "identity_conflict"`). A parent that crashes after starting
+  such a child, but before saving its wait, finds the same child on replay; if the child already finished, the parent
+  receives its result directly.
+- `RunStore.create_if_absent(run) -> (run, created)` on the SQLite, JSON-file, in-memory and offloading stores (the JSON
+  store publishes a fully written temp file with an atomic hard link and never replaces an existing run file).
+  `store_supports_create_if_absent` / `require_create_if_absent` check a store. Recovery after a process crash is
+  covered; power-loss durability is not claimed.
+- `run_mutation_lock(run_id)`: the per-run, per-process lock that `Runtime.tick` holds for the whole tick and
+  `Runtime.resume` for its commit. Hosts take it around their own read-modify-save of a run. v1 supports one writer
+  process per store.
+- Run index attribution: rows carry `automation_id`, `role` (`controller`, `occurrence`, `descendant`, `discussion`,
+  `legacy_schedule` or empty), `occurrence_index` and `session_kind` (`chat`, `automation`, `occurrence`,
+  `discussion`), and `list_run_index` filters on them (`session_kind="chat,discussion"` works). Existing SQLite stores
+  fill the new columns once when opened; the JSON store re-reads each run file once. Every store has
+  `session_kinds(session_id)` and `latest_occurrence_row(automation_id)`.
+- Run index rows carry `workspace_root`: the folder the run executes in (its top-level `vars["workspace_root"]` as
+  stored, stripped, never resolved; `None` when absent), so apps can open a session's folder without loading runs.
+  Existing SQLite stores fill it once when opened; the JSON store re-reads each run file once.
+- `session_attribution(store, session_id)` (`abstractruntime.core.run_attribution`) reports what kind of session an id
+  is (`chat`, `automation`, `occurrence` or `discussion`, with the discussion's validated root, automation and
+  workspace). Every root run started in a discussion session gets the discussion's own workspace, access settings and
+  read-only mounts (the whole-workspace read-only flag only when the discussion carries it) and its provenance,
+  whatever the caller passed; when the session cannot be attributed (an invalid
+  discussion root, or a store without a run index) `Runtime.start` raises `SessionAttributionError`.
+- `select_session_turns(store, session_id, ...)`: the one definition of a session's turns (parent-less runs except
+  automation controllers, plus automation occurrences; never child runs, internal runs, legacy scheduled wrappers or,
+  unless asked, draft-test runs), with `include_occurrences`, `automation_id`, `through_occurrence`, `until_ms`,
+  `include_drafts` and `limit`. `is_draft_lifecycle` is exported too.
+- `session_chat_messages(..., automation_id=None, through_occurrence=None, strict=False)`: bound the replayed turns to
+  one automation or to the history as it stood at occurrence N, however old. In a discussion session the seed is
+  replayed first and dropped first under the budget. `strict=True` raises `SessionHistoryError`
+  (`reason_code = "history_unavailable"`) instead of returning a partial history.
+- Read-only workspaces: a run started with `workspace_read_only: true` (or trusted runtime policy
+  `_runtime.workspace_read_only: true`) can read its workspace but not change it. Tools that write files or run
+  commands or code, and any tool the runtime has not classified, are refused, as are the VisualFlow `write_file`,
+  `write_pdf`, `write_docx`, `write_chart` and `export_artifact` nodes. A read-only workspace folder is never created,
+  a read-only run without one is refused, and child runs and nodes inherit the setting.
+  `tool_effects.TOOL_EFFECT_CLASSES` classifies every exposable tool (`read`, `write`, `exec`, `delegate`, `comms`,
+  `memory-write`).
+- Read-only mounts: `_runtime.workspace_read_only_paths` (absolute folders, symlinks resolved) makes those folders
+  readable but not writable by the file tools (`write_file`, `edit_file`) and the VisualFlow file/export writers,
+  while the run's own workspace stays writable. Commands and code (`execute_command`, `execute_python`, ...) are not
+  restricted by a mount: the shell cannot be sandboxed, so mounts protect the file tools only. Child runs and
+  VisualFlow nodes inherit the mounts and can only add more. Helpers `read_only_paths(vars)` and
+  `path_is_read_only(vars, path)` in `abstractruntime.utils.workspace_paths`.
+- `select_session_turns(..., automation_id=A)` gathers A's occurrences from every session (an independent-mode
+  automation runs each occurrence in its own session), interleaved with the session's own turns.
+- `JsonFileRunStore.warm_session_index()` builds the session and children indexes at host startup.
+
+### Changed
+
+- Session history bundles and session replay include automation occurrences as turns (kind `occurrence`, with
+  `automation_id` and `occurrence_index`); a retried occurrence counts once, as its last attempt. Draft-test runs are
+  left out of a session's history.
+- `list_run_index(root_only=True)` returns turn roots: parent-less runs except automation controllers, plus automation
+  occurrences. Apps that fold root runs into sessions show an automation's session as a chat whose turns are its
+  occurrences.
+- Children of an automation occurrence carry `vars._meta.occurrence` with `role = "descendant"`, and children of a
+  discussion carry its `vars._meta.discussion` (without the seed); a child cannot clear or change either.
+
+### Fixed
+
+- Session lookups on the JSON run store use an index of each session's runs instead of scanning the store (about
+  0.1 ms per new chat turn at 20,000 runs). Several store objects or processes on one run folder see each other's
+  created and deleted runs through a creation journal (`.runs_created.log`).
+- History "through occurrence N" returns the history up to that occurrence in sessions of any length, and raises
+  (`strict`) or returns nothing when the session has no occurrence N.
+- A discussion session's seed is read only from a validated root: every run of the session must name the same root,
+  and that root must belong to the session and carry the seed.
+- The JSON run store removes run temp files left behind by a crash (older than 10 minutes) when it opens.
+- Automation identity metadata (`vars._meta.automation`, `.occurrence`, `.discussion`, `.creation_digest`) always
+  stays inline when a finished run is offloaded.
+
 ## [0.5.1] - 2026-09-26
 
 ### Added

{abstractruntime-0.5.1 → abstractruntime-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.5.1
+Version: 0.6.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
@@ -54,7 +54,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.5.1 • **Python:** 3.10+
+**Version:** 0.6.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -146,7 +146,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.5.1)
+## What’s included (v0.6.0)
 
 Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -158,6 +158,8 @@ 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`)
+- 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/*`)
@@ -236,6 +238,7 @@ 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 |
 | [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.5.1 → abstractruntime-0.6.0}/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.5.1 • **Python:** 3.10+
+**Version:** 0.6.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -96,7 +96,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.5.1)
+## What’s included (v0.6.0)
 
 Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -108,6 +108,8 @@ 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`)
+- 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/*`)
@@ -186,6 +188,7 @@ 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 |
 | [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.5.1 → abstractruntime-0.6.0}/docs/README.md

@@ -34,6 +34,7 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 
 ## 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)
 - `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.5.1 → abstractruntime-0.6.0}/docs/api.md

@@ -62,8 +62,10 @@ Durability invariant: `RunState.vars` must remain JSON-serializable (`src/abstra
 
 Implementation: `src/abstractruntime/core/runtime.py`.
 
-- `Runtime.start(workflow, vars=..., actor_id=..., session_id=...) -> run_id`
+- `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`
+  - 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`
   - optional `step_gate()` is consulted at every step boundary; when it returns `False` the tick returns the persisted state and the run stays `RUNNING` (a later tick continues where it stopped)
@@ -71,6 +73,7 @@ Implementation: `src/abstractruntime/core/runtime.py`.
   - validates the `wait_key`, writes `payload` to `WaitState.result_key` (if set), and continues from `WaitState.resume_to_node`
   - a wait is resumed at most once: a resume of a run that is no longer waiting, or that waits on another key, raises `StaleResumeError` (a `ValueError`), for example when another caller resumed it first
   - the check and the commit run under a per-run lock, and tools approved with `{"approved": true}` execute while that lock is held, so a long tool delays a competing resume of the same run, which is then refused
+- `run_mutation_lock(run_id)` (package root): the per-run, per-process, re-entrant lock that `tick` holds for the whole tick and `resume` for its commit; take it around your own read-modify-save of a run so a tick cannot overwrite your change
 - `Runtime.get_state(run_id) -> RunState` and `Runtime.get_ledger(run_id) -> list[dict]`
   - host-facing read APIs for checkpoints and the append-only ledger
 - `Runtime.cancel_run(run_id, reason=None, cancelled_by="api") -> RunState`
@@ -117,6 +120,12 @@ Notes:
   - `from abstractruntime import SqliteRunStore, SqliteLedgerStore`, or
   - `from abstractruntime.storage.sqlite import SqliteRunStore, SqliteLedgerStore`
 
+Run index and creation (all built-in run stores, including the offloading wrapper):
+- `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
+- `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
+
 Common decorators:
 - `ObservableLedgerStore` for subscriptions (`src/abstractruntime/storage/observable.py`)
 - `HashChainedLedgerStore` + `verify_ledger_chain(...)` for tamper-evidence (`src/abstractruntime/storage/ledger_chain.py`)
@@ -205,6 +214,49 @@ Public bundle APIs are exported from `src/abstractruntime/workflow_bundle/__init
 
 Docs: `workflow-bundles.md`.
 
+## Automations
+
+Implementation: `src/abstractruntime/automations/*`, `src/abstractruntime/triggers/*`, `src/abstractruntime/automation_queries.py`.
+Deep dive: [automations.md](automations.md).
+
+```python
+from abstractruntime.automations import (
+    apply_automation_command,   # pause / resume / run_now / revise / stop_current / archive
+    create_automation,          # -> (automation_id, revision)
+    drive_automation,           # standalone run loop
+    get_automation,
+    list_attention,
+    list_occurrences,
+    pending_waits,
+    register_controller_bundle,
+    start_discussion,
+)
+from abstractruntime.automation_queries import latest_occurrence, list_automations
+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)`
+- `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
+- `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`
+
+## Sessions and history
+
+Implementation: `src/abstractruntime/session_turns.py`, `src/abstractruntime/session_history.py`, `src/abstractruntime/core/run_attribution.py`.
+
+- `select_session_turns(run_store, session_id, *, include_occurrences=True, until_ms=None, automation_id=None, through_occurrence=None, include_drafts=False, limit=50)` (package root): a session's turns, oldest first. Turns are parent-less runs except automation controllers, plus automation occurrences (a retried occurrence counts once, as its newest attempt); child runs, runtime-internal runs, legacy scheduled wrappers and draft-test runs are left out
+- `session_chat_messages(run_store=, ledger_store=, artifact_store=, session_id=, max_messages=40, max_total_chars=24000, ..., automation_id=None, through_occurrence=None, strict=False)` (package root): the session's completed turns as user/assistant message pairs, newest kept under the budget; in a discussion session the discussion's seed comes first. `strict=True` raises `SessionHistoryError` (`reason_code = "history_unavailable"`) instead of returning a partial history
+- `session_attribution(run_store, session_id)` (`abstractruntime.core.run_attribution`): `None` or `{"kind": "chat" | "automation" | "occurrence" | "discussion", ...}`; a discussion adds its validated root, automation, occurrence and workspace. Raises `SessionAttributionError` when the lookup cannot be completed
+- `is_draft_lifecycle(run_lifecycle)` (package root): whether a run's lifecycle value marks a draft test run
+
+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.
+
 ## Run history bundle export (portable replay artifact)
 
 Implementation: `src/abstractruntime/history_bundle.py`.

{abstractruntime-0.5.1 → abstractruntime-0.6.0}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-09-26
-> Version: 0.5.1
+> Updated: 2026-09-27
+> Version: 0.6.0
 > 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.
@@ -315,6 +315,71 @@ The scheduler is an in-process driver loop that resumes due waits and can delive
 - `Scheduler` (`src/abstractruntime/scheduler/scheduler.py`) polls `QueryableRunStore.list_due_wait_until(...)`
 - `ScheduledRuntime` + `create_scheduled_runtime()` (`src/abstractruntime/scheduler/convenience.py`) is the "zero-config" wrapper used in `examples/`
 
+## Automations
+
+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).
+
+```mermaid
+flowchart LR
+  subgraph Host["Host (AbstractGateway run loop, or drive_automation)"]
+    Loop["tick due runs /<br/>resume finished subworkflow parents"]
+    API["commands + reads"]
+  end
+  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"]
+    Queries["get_automation / list_occurrences /<br/>list_attention / pending_waits /<br/>list_automations"]
+  end
+  subgraph Runs["runs"]
+    Occ["occurrence run<br/>(session turn)"]
+    Desc["descendant runs"]
+    Disc["discussion run<br/>(own workspace + read-only mount)"]
+  end
+  subgraph Stores["storage/"]
+    RS["RunStore<br/>create_if_absent + run index"]
+    LS["LedgerStore<br/>automation.* records"]
+  end
+
+  API --> Commands
+  API --> Queries
+  Commands -->|"run_mutation_lock,<br/>decision, wake"| Controller
+  Loop --> Controller
+  Loop --> Occ
+  Controller -->|"prepare / admit / rearm"| Triggers
+  Controller -->|"START_SUBWORKFLOW run_id"| Occ
+  Occ --> Desc
+  Controller --> RS
+  Controller --> LS
+  Occ --> RS
+  Disc --> RS
+  Queries --> RS
+  Queries --> LS
+```
+
+Invariants the design rests on:
+
+- **Create-if-absent.** Controllers, occurrences and discussions are created under explicit ids through
+  `RunStore.create_if_absent`, so replaying a creation after a crash finds the same run and never starts a second
+  one (`Runtime.start(..., run_id=...)`, `START_SUBWORKFLOW` `payload.run_id`).
+- **One decision protocol.** Every controller step and command reconciles, looks its decision key up exactly, saves
+  an intent, appends the record and applies it, so a crash at any point yields exactly one record and one
+  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.
+- **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.
+- **Attribution is indexed.** Each run index row carries `automation_id`, `role`, `occurrence_index` and
+  `session_kind`, derived from inline `vars._meta` that the offloading store never moves. `Runtime.start` uses
+  `session_attribution` to anchor every root run in a discussion session to the discussion's validated root and its
+  workspace setup (its own writable workspace plus the automation's workspace as a read-only mount), and refuses the
+  start when the attribution cannot be read.
+
 ## Observability: what you can export
 
 - Ledger (source of truth): `Runtime.get_ledger(run_id)` (`src/abstractruntime/core/runtime.py`)
@@ -343,6 +408,7 @@ AbstractRuntime includes a compiler and a portable bundle format:
 - `../README.md` — install + quick start
 - `getting-started.md` — first steps
 - `api.md` — public API surface (imports + pointers)
+- `automations.md` — automations: controller, triggers, commands, context, discussions, storage guarantees
 - `limits.md` — `_limits` and RuntimeConfig
 - `snapshots.md` — snapshot/bookmark stores
 - `provenance.md` — hash chain and verification