AbstractRuntime 0.5.1__tar.gz → 0.7.0__tar.gz

{abstractruntime-0.5.1 → abstractruntime-0.7.0}/.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Install
         run: |
           python -m pip install -U pip
-          python -m pip install -e ".[abstractcore,mcp-worker,test]"
+          python -m pip install -e ".[test]"
       - name: Pytest basic suite
         run: python -m pytest -q -m basic
       - name: Pytest focused runtime suite
@@ -47,7 +47,16 @@ jobs:
             tests/test_visual_multi_entry_loop_overrides.py \
             tests/test_control_adapter_while.py \
             tests/test_jsonl_ledger_recovery.py \
-            tests/test_llm_client_media_artifacts.py
+            tests/test_llm_client_media_artifacts.py \
+            tests/test_session_history.py \
+            tests/test_entity_history_window.py \
+            tests/test_automation_discussion_isolation.py \
+            tests/test_automation_growing_context.py \
+            tests/test_automation_session_turns.py \
+            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
 
   build:
     name: Build distributions

{abstractruntime-0.5.1 → abstractruntime-0.7.0}/.github/workflows/release.yml

@@ -44,7 +44,7 @@ jobs:
       - name: Install
         run: |
           python -m pip install -U pip
-          python -m pip install -e ".[abstractcore,mcp-worker,test]"
+          python -m pip install -e ".[test]"
       - name: Pytest basic suite
         run: python -m pytest -q -m basic
       - name: Pytest focused runtime suite
@@ -62,7 +62,16 @@ jobs:
             tests/test_visual_multi_entry_loop_overrides.py \
             tests/test_control_adapter_while.py \
             tests/test_jsonl_ledger_recovery.py \
-            tests/test_llm_client_media_artifacts.py
+            tests/test_llm_client_media_artifacts.py \
+            tests/test_session_history.py \
+            tests/test_entity_history_window.py \
+            tests/test_automation_discussion_isolation.py \
+            tests/test_automation_growing_context.py \
+            tests/test_automation_session_turns.py \
+            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
 
   docs:
     name: Build docs

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

@@ -5,6 +5,230 @@ 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.7.0] - 2026-09-28
+
+Replayed session history is one window: the most recent 50,000 tokens of whole turns, recorded in the run.
+Library callers of `session_chat_messages` and `automation_timeline_messages` should read the **Breaking** note.
+
+### Changed
+
+- The base install and the `apple` / `gpu` profiles require AbstractCore 2.18.0 or newer. Its voice extra brings
+  AbstractVoice 0.13.0, the first release that honours the `voice_openai_api_key` setting described below.
+
+- **Session history replay is one window: the most recent 50,000 tokens.** `session_chat_messages` keeps the newest
+  turns that fit `HISTORY_REPLAY_MAX_TOKENS` (50,000) estimated tokens, as whole messages, newest first. The window has
+  no gaps, and a total of exactly 50,000 tokens fits. The 40-message cap, the 24,000-character total budget and the
+  8,000-character cut per message are removed, so no replayed message is ever cut. When the newest turn alone is larger
+  than the window, it is kept whole and the report says so (`oversize_turn_kept`). Tokens are counted with the existing
+  estimator, `memory.token_budget.estimate_message_tokens`. This window applies to automation growing mode (it
+  replaces the 40-message / 24,000-character limit of contract D), to discussion seeds (`automation_timeline_messages`)
+  and to host session seeding. The window is the only limit on replayed history; the model can use the rest of its
+  context window (operator ruling 2026-09-28, ADR-0026 §3: budgets are met by choosing whole turns, never by cutting
+  content).
+- **Library API:** `session_chat_messages` still accepts `max_messages`, `max_chars_per_message` and
+  `max_total_chars` (keyword-only, default `None`) but IGNORES them: they no longer limit anything. Hosts built against
+  0.6 (AbstractGateway 0.6.0 passes `max_messages=40, max_total_chars=24000` and treats any error as "no history") keep
+  replaying their sessions under the window. Passing any of them logs one warning and names them in
+  `report["ignored_inputs"]`. Pass `max_tokens` (a positive int) to use a different window.
+- **Breaking (library API):** `automation_timeline_messages` takes `max_tokens` instead of `max_messages` /
+  `max_chars_per_message` / `max_total_chars`. `GROWING_MAX_MESSAGES` and `GROWING_MAX_TOTAL_CHARS` are removed from
+  `abstractruntime.automations.models`.
+- **The entity chat driver and the entity visit workflow use the same window.** They used to keep only the last 10
+  turns in the prompt, without saying so. Now every turn is kept, and each prompt carries the most recent 50,000 tokens
+  of whole turns, with the `[#TRUNCATION: ...]` line when older turns were dropped. The visit records the window's
+  report in `vars._runtime.session_history`; `ChatSession` puts it on `TurnReport.history_window` (and
+  `ChatSession.history_window`).
+- **The react visit arm (the one AbstractGateway uses) sends the window too.** Its transcript is the durable
+  `context.messages`, sent by the AbstractAgent react loop on every call; before, nothing bounded it (after 12 turns of
+  ~10k tokens a request was ~117k tokens, and a poisoned tool result rode every later turn). BRIDGE now sets
+  `_runtime.history_window_tokens` (50,000); the adapter sends `window_transcript(context.messages)` on every call —
+  a tool result stays with its turn, so a 495k-character tool result drops out of the request once a newer turn
+  exists — and records the report in `vars._runtime.session_history`. The stored transcript stays whole. BRIDGE also
+  records `_runtime.history_window_turn_start` (the visitor's message), and the window keeps the turn in progress whole
+  from there (`window_transcript(..., current_turn_start=)`): an `ask_user` answer or operator guidance inside the turn
+  no longer splits off the turn's own question and tool results; a turn larger than the window is kept whole and
+  reported as `oversize_turn_kept`. HARVEST
+  keeps a turn whose adapter recorded no window (AbstractAgent older than 0.3.17 sends the whole transcript) but
+  logs a warning ("abstractagent < 0.3.17 does not apply the history window; upgrade abstractagent") and records
+  `{"window_applied": false, "reason": "agent_too_old", ...}` in `vars._runtime.session_history` (counting the messages
+  the last request carried, not the reply stored after it); a windowed turn
+  records `window_applied: true`. **The window on the react arm needs AbstractAgent 0.3.17 or newer.**
+- The `[#TRUNCATION: ...]` line is written after a stamped message's own `<runtime_metadata>` envelope, which stays at
+  the head (written in front, it made the payload boundary stack a second envelope).
+- **Breaking (library API):** the `history_turns` parameter of `build_visit_workflow` and `ChatSession` is removed,
+  with `DEFAULT_HISTORY_TURNS` (no caller in the framework passed it). The entity visit no longer sets the
+  per-message character limits `_limits.max_tool_message_chars` (32,000) and `_limits.max_message_chars` (80,000) on
+  re-sent history, and `VISIT_HISTORY_TOOL_RESULT_CAP_CHARS` / `VISIT_HISTORY_MESSAGE_CAP_CHARS` are removed. A
+  single oversized tool result is still limited by AbstractAgent's own guard for oversized messages (200,000 characters).
+- `trim_messages_to_max_input_tokens` (used only when a caller sets a positive `max_input_tokens`) keeps each tool
+  result together with the assistant tool call before it. It used to drop the call and keep the result, which
+  OpenAI-style APIs reject.
+
+- **The context mode decides whether an automation's target reads history.** At admission the runtime sets
+  `use_context` (and `include_context` when present) to `true` for growing occurrences and `false` for independent
+  ones, and to `true` for discussion forks. A `use_context: false` frozen in an older definition no longer makes a
+  growing automation or a discussion replay nothing (basic-agent's `use_context` pin defaults to `false`). The run
+  records `_runtime.automation_context = {mode, use_context, target_use_context}`. Occurrences that were already
+  admitted before the upgrade keep their frozen inputs.
+
+### Added
+
+- Voice discovery (`local_get_voice_catalog`, `local_list_tts_models`, `local_list_stt_models`) accepts a
+  host-supplied `voice_openai_api_key` and passes it to AbstractVoice as the plugin setting of the same name (the
+  OpenAI credential for its `openai` engines; AbstractVoice reads no environment variable for it). The discovery
+  facade and the local clients accept and forward it (`AbstractCoreDiscoveryFacade.get_voice_catalog` /
+  `list_tts_models` / `list_stt_models(voice_openai_api_key=...)`); the remote client accepts it and never sends it.
+  In `llm_kwargs` it reaches the voice plugin through the provider's `config` and changes no text request; tests
+  prove this on real OpenAI, LM Studio, Ollama and MLX provider classes, with the network refused.
+- **The window is recorded.** `session_chat_messages` and `automation_timeline_messages` return a `ReplayedHistory`
+  (a list of messages) with a `.report`: `policy`, `max_tokens`, `token_estimator`, `replayed_messages`,
+  `replayed_tokens`, `dropped_messages`, `dropped_tokens`, `dropped_counts_complete`, `oversize_turn_kept`. A growing
+  occurrence records it in `vars._runtime.session_history`, so the `automation.admitted` record's frozen inputs carry
+  it too. A discussion root records its seed window the same way. When older turns are dropped, the oldest replayed
+  message starts with a `[#TRUNCATION: ...]` line that gives the number of dropped messages and tokens and the window.
+  New exports at the package root: `HISTORY_REPLAY_MAX_TOKENS`, `ReplayedHistory`, `fold_history_window`,
+  `announce_dropped` (writes that `[#TRUNCATION: ...]` line after a host's own `fold_history_window` call, for example
+  on client-sent history; `session_history._announce_dropped` stays as an alias) and `window_transcript` (the window
+  over a transcript the caller already holds).
+- `local_list_tts_models` reports why a provider cannot be listed: when the listing is unavailable, `error` carries
+  AbstractVoice's `unavailable_reason` (for example "no OpenAI API key is configured ..." or an unknown provider id).
+  It used to return `available: false, error: null`.
+- Replay reads turns newest-first in batches that double in size, and stops once the window is full. A long session
+  therefore costs about as much as its window holds.
+
+### Tests and CI
+
+- CI installs the extras that exist (`.[test]`) and runs the history-window, entity window, automation timeline,
+  input-trim and voice-key tests. The five tests that need the sibling `abstractflow/` checkout or the
+  `abstractagent` package skip when those are absent (a standalone checkout or an sdist).
+
+## [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.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.5.1
+Version: 0.7.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,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[audio,music,remote,tools,vision,voice]>=2.16.0
+Requires-Dist: abstractcore[audio,music,remote,tools,vision,voice]>=2.18.0
 Requires-Dist: abstractmemory>=0.3.0
 Requires-Dist: abstractsemantics>=0.0.5
 Requires-Dist: anyio<5.0.0,>=4.12.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[all-apple]>=2.16.0; extra == 'apple'
+Requires-Dist: abstractcore[all-apple]>=2.18.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[all-gpu]>=2.16.0; extra == 'gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.18.0; extra == 'gpu'
 Requires-Dist: setuptools<82.0.0,>=77.0.3; extra == 'gpu'
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == 'test'
@@ -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.7.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -82,7 +82,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.16.0 or newer with remote provider,
+The base install includes AbstractCore 2.18.0 or newer with remote provider,
 tool, 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 +146,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.5.1)
+## What’s included (v0.7.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.7.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.7.0 • **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.16.0 or newer with remote provider,
+The base install includes AbstractCore 2.18.0 or newer with remote provider,
 tool, 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.5.1)
+## What’s included (v0.7.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.7.0}/docs/README.md

@@ -30,10 +30,12 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `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)
 - `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)
 - `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.7.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,54 @@ 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_tokens=HISTORY_REPLAY_MAX_TOKENS, until_ms=None, exclude_run_ids=None, automation_id=None, through_occurrence=None, strict=False)` (package root): the session's completed turns as user/assistant message pairs; in a discussion session the discussion's seed comes first. Returns a `ReplayedHistory` (a list of messages) whose `.report` says what was replayed and dropped. `strict=True` raises `SessionHistoryError` (`reason_code = "history_unavailable"`) instead of returning a partial history. `max_messages`, `max_total_chars` and `max_chars_per_message` (keyword-only, default `None`) are the caps retired in 0.7.0: they are accepted so hosts built against 0.6 (AbstractGateway 0.6.0) still get their history, and ignored. Passing any of them logs one warning and names them in `report["ignored_inputs"]`
+- The history window: `HISTORY_REPLAY_MAX_TOKENS = 50_000` (package root). Replay keeps the most recent turns that fit 50,000 estimated tokens, newest first, as whole messages. There is no message-count cap and no character cap, and no message is ever cut. The fold stops at the first older turn that does not fit, so the window has no gaps. A total of exactly 50,000 tokens fits. One exception: when the newest turn alone is larger than the window, it is kept whole (`oversize_turn_kept: true`), because cutting it would lose content and dropping it would replay nothing. The model can use the rest of its context window; if a turn is too large for the model, the provider reports the error. Tokens are counted with `abstractruntime.memory.token_budget.estimate_message_tokens`. `max_tokens` must be a positive int
+- `ReplayedHistory.report`: `{policy: "most_recent_whole_turns", max_tokens, token_estimator, replayed_messages, replayed_tokens, dropped_messages, dropped_tokens, dropped_counts_complete, oversize_turn_kept}`. Replay stops reading once the window is full, so in a long session `dropped_counts_complete` is `false` and the dropped counts cover only the turns it read. When turns were dropped, the oldest replayed message starts with a `[#TRUNCATION: N earlier message(s) ... were dropped from replay by the history window ...]` line (ADR-0026). Hosts record the report in the run as `vars._runtime.session_history`
+- `fold_history_window(pairs, *, max_tokens=HISTORY_REPLAY_MAX_TOKENS)` (package root): the window itself, applied to chronological turns (lists of whole messages); returns `(kept, report)`
+- `announce_dropped(messages, report, *, stamp_metadata=True)` (package root): writes the window's `[#TRUNCATION: ...]` notice at the start of the oldest kept message, in place, when `report` says turns were dropped. Use it after your own `fold_history_window` call (for example on client-sent history) so the notice matches session replay. `stamp_metadata=True` also adds `metadata.replay_truncated` and `metadata.history_window` to that message; pass `False` for plain role/content messages. `_announce_dropped` is kept as an alias of the pre-0.7.0 private name
+- `window_transcript(messages, *, max_tokens=HISTORY_REPLAY_MAX_TOKENS, current_turn_start=None)` (package root): the same window over a transcript you already hold (a turn is a user message and the messages after it). `current_turn_start` is the index of the message that opened the turn in progress: from there on everything is one turn, the newest, always kept whole (`oversize_turn_kept` when it alone exceeds the window), whatever user-role messages a loop adds inside it; an index out of range raises `ValueError`. Returns a `ReplayedHistory` of copies with the notice written by `announce_dropped(..., stamp_metadata=False)`. The entity chat driver and the entity visit workflow use it for their prompts. The visit records the report in `vars._runtime.session_history`; the chat driver puts it on `TurnReport.history_window`. On the react visit arm, BRIDGE sets `_runtime.history_window_tokens` (50,000) and `_runtime.history_window_turn_start` (the visitor's message) and the AbstractAgent react loop (0.3.17 or newer) sends `window_transcript(context.messages)` on each call and records the report; the stored transcript stays whole. The report carries `window_applied: true`; with an older AbstractAgent that records no window the turn still completes, a warning is logged and the report is `{"window_applied": false, "reason": "agent_too_old", ...}` (the whole transcript was sent). When the oldest kept message carries a `<runtime_metadata>` envelope, the notice is written after it
+- `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`.
@@ -220,7 +277,7 @@ from Core route resolution and persisted from `LLM_CALL` results.
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install abstractruntime` (AbstractCore 2.16.0 or newer is part of the base install).
+Requires: `pip install abstractruntime` (AbstractCore 2.18.0 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -234,6 +291,7 @@ Entry points:
 - 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`)
+- 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
 - 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