AbstractRuntime 0.15.3__tar.gz → 0.17.0__tar.gz

abstractruntime-0.17.0/.github/workflows/changelog.yml

@@ -0,0 +1,23 @@
+name: Changelog
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  changelog:
+    # A pull request that changes src/ adds a fragment, changelog.d/<pr-or-slug>.md, instead of
+    # editing CHANGELOG.md (scripts/changelog.py; changelog.d/README.md).
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Fragment present and well formed
+        run: python scripts/changelog.py check --base "origin/${{ github.base_ref }}"

{abstractruntime-0.15.3 → abstractruntime-0.17.0}/CHANGELOG.md

@@ -5,8 +5,139 @@ 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 changes live in [`changelog.d/`](changelog.d/README.md), one file per pull request;
+`python scripts/changelog.py assemble X.Y.Z` writes them here at release.
+
 ## [Unreleased]
 
+## [0.17.0] - 2026-11-03
+
+### Added
+
+- **`EffectInterrupted`: a host stop interrupts an effect, it never fails it** (`core/effect_cancellation.py`,
+  exported as `abstractruntime.EffectInterrupted`; gateway backlog 1103). A host that stops on purpose (a gateway stop
+  or restart, a model-host restart for an update) raises it into the effect in flight. The runtime writes no terminal
+  record and re-raises: the ledger tail stays STARTED, the run stays RUNNING at its last durable step, and the next
+  tick (after the host is back) sends the effect again under the same idempotency key as attempt 1, so no retry is
+  consumed and nothing reaches an automation's outcome. A BaseException like `EffectKilled`, so no `except Exception`
+  on the way turns it into a failure. The interrupted call's live text ends `cancelled` with `detail: "interrupted"`.
+- **Public updates carry their type in replay** (`replay/view.py`). A `public_update` message has
+  `update_kind`: `"finding"` when the actor typed the event `kind: "finding"` (a fact or piece of
+  evidence it established), otherwise `"progress"` (what it is doing), including events written
+  before the field existed. Clients use it as given, for example to list the findings of a
+  conversation. See [docs/replay.md](docs/replay.md#public-conversation-messages).
+- **Hosts tell model errors apart through the discovery facade** (`integrations/abstractcore/discovery_facade.py`):
+  `ModelNotDownloadedError` and `ModelNotFoundError` are AbstractCore's own classes, so a host (the gateway's
+  "model not downloaded" sentence) catches exactly what Core raises and reads `model` / `provider` without importing
+  AbstractCore.
+- **Replayed tool calls keep the model's call id** (`replay/view.py`). An `activities[].tool_calls[]`
+  row keyed by a runtime call id (`id`) also carries `call_id`, the model's own id, which is what a
+  public update's `source_call_ids` cite; a client can now resolve a finding to the results it cites.
+
+### Changed
+
+- **Compare reads text next to a number or true/false exactly** (`visual/builtins.py` `_exact_from_text`, ADR 0049 as
+  amended 2026-11-03: "we must have automatic conversion"). When one side is a number or true/false and the other is
+  text, the text is read as that type by the Flow editor's literal grammar (a decimal number, ASCII, no `_`, finite,
+  a whole number kept exact beyond 2**53; or `true`/`false` in any case), so `5 == "5"` and `"9" < 10` are true. This
+  covers flows saved by AbstractFlow 0.13.0 (a typed value stored as text next to a wired number) and text arriving at
+  run time from a form, an API input or a model, with no re-save. `"1_000"`, `"0x10"`, `"inf"`, `"nan"`, full-width
+  digits and empty text are refused. Text against text is never converted (`"10" > "9"` compares text). The table is
+  `tests/fixtures/visualflow/compare_text_operands.json`.
+- **Compare refuses values it cannot compare instead of answering False** (`visual/builtins.py` `control_compare`,
+  ADR 0049). Text that is not a number next to a number, or not `true`/`false` next to true/false (`5 == "five"`,
+  every operator; text that is a number or true/false is read as one, see "Compare reads text next to a number or true/false exactly" above), and `<`/`<=`/`>`/`>=` between values Python cannot order
+  (`None > 3`, a list and a number), now fail the step with an error naming the node and pins: "Compare 'Is five'
+  (node same) ==: b is text ('five'), not a number; a is a number (5)." Before, these answered False silently.
+  Equality of same-type values and Python's equality across other types (`None == 5`) are unchanged; true/false
+  compares with numbers as Python's booleans do (`True == 1`).
+- **AbstractCore floor 2.33.0** in the base install and the `apple` and `gpu` extras (was 2.32.0).
+
+### Fixed
+
+- **An automation occurrence whose agent completed with `success: false` names the agent's reason**
+  (`automations/attention.py`). The attention item and the `automation_failed` email said "completed" (the run's status
+  word); the reason is now read from the Agent node's `meta.error`, and when there is none it says so plainly.
+
+## [0.16.0] - 2026-11-02
+
+### Added
+
+- A package agent skill documents operating durable workflows, waits, storage and structured execution through the public Python API.
+
+- **`config_facade.model_catalog(..., hub_page=, hub_page_size=)`** (backlog 0864) passes a page of Hugging Face search
+  results through to AbstractCore, which reports it in `hub.search`. It is passed only when asked. An AbstractCore
+  whose catalog has no `hub_page` raises `AbstractCoreTooOld` in words instead of answering page 1.
+  `AbstractCoreTooOld` accepts a `required=` description. `extended=True` (every quant of a row's own GGUF repos,
+  AbstractCore 0865) is passed the same way and refused in words on an AbstractCore without it.
+- **Fit refusals (AbstractCore ADR 0010) reach every surface.** A load refused with `ModelDoesNotFitError` (the model
+  does not fit even after evicting what is not locked) is never retried (a retry would only evict more); its
+  sentence is the effect error, its fields (needed/free bytes, kept models, suggestions) are kept on the ledger
+  record (`result.error_details`, `EffectOutcome.error_details`) and in the residency diagnostics (`refusals`, the
+  last five), and the default pair keeps the sentence instead of the configuration hint.
+- Opt-in public actor updates and explicit human-guidance acceptance messages share durable replay history, with host-origin checks and exact original human words.
+- Conversational ASK_USER policies distinguish indefinite essential questions from 120–300 second clarifications with predeclared safe fallbacks. Fresh question keys, strict server cutoffs, durable outcomes, retained late replies and pause/restart behavior reuse the existing due-wait indexes.
+- Participant-checked live entity-visit corrections use the existing durable sidecar and fresh attributed recall before the next actor reasoning boundary.
+- The package agent skill documents these question and guidance contracts.
+- **A decision is an `LLM_CALL` whose output spec says `modality: "decision"`** (`integrations/abstractcore/llm_client.py`, `effect_handlers.py`). Payload `{"prompt": <state>, "output": {"modality": "decision", "questions": {...}, "truncate"?, "model"?}}`; the result is the usual normalized shape plus `decision` (the System One body: `model`, `answers`, `usage`, `latency_ms`[, `truncated`]) and `answers` (= `decision.answers`), with `content` the answers as JSON, `outputs`/`resources` empty and `provider`/`model` the decision model that answered. No artifact, no store, no `generated_media` tag; the resolved action id is `decision`. Local: the resolved spec (the `output.decision` capability default, or the spec's own route) reaches `generate(prompt, output=[spec])` and core runs it through its decision pool on any text provider; the pooled client serves a decision-only request on the capability host without building the text model. Remote: `POST {core}/v1/decisions` with `model` = `provider/model`, `state`, `questions`, `truncate`; the server's body maps to the same result.
+- **`decide`: a calibrated decision as a durable child run and a VisualFlow node** (`integrations/abstractcore/run_facade.py`, `visualflow_compiler/visual/executor.py`, `visualflow_compiler/compiler.py`). `run_facade.decide(run_id, state=..., questions=..., model=None, truncate=None)` starts a child `LLM_CALL` whose output spec is `{"modality": "decision", "questions": ...}` (plus `truncate` and `model` when given); a `model` written as `provider/model` (`mlx/jaredpalmer/kev-4b`) travels whole and AbstractCore splits it. The `decide` VisualFlow node asks one typed question (inputs `state`, `question`, `question_type` = `choice` | `noul` | `score`, `options` / `levels`, `provider`, `model`, `truncate`) and fills that type's output pins (`answer`, then `choice`/`confidence`/`probabilities`, `noul`/`verdict`, or `score`/`level`/`confidence`/`probabilities`, plus `model`, `success`); a wired `questions` object asks several System One questions at once and fills `answers`. It lowers to the same `LLM_CALL`; the result sync also carries `decision` (the System One body), `content` and `meta` (`abstractflow.decide.v1.meta`).
+- **A local model's loaded context, through the config facade** (`integrations/abstractcore/config_facade.py`).
+  `configured_model_context(provider, model)` and `set_model_context(provider, model, tokens)` read and set the
+  per-model context AbstractCore loads a model with (AbstractCore ADR 0010 point 8: a set context is a pin, loaded
+  as is or refused, never shrunk). The gateway's Resources page "Set context" calls them instead of importing
+  AbstractCore. On a Core without `abstractcore.config.model_contexts` (every release up to 2.31.1) they raise
+  `AbstractCoreTooOld` naming what is missing.
+- Tool approval waits can carry optional `details.public_action` (`text`, `update_id`, `run_id`,
+  `iteration`, `call_ids`) supplied by an actor adapter alongside its proposed effect batch.
+  Runtime validates its owning run and exact call identities, narrows it to the actual gated
+  subset, and withholds mismatched or private-fenced context. The canonical replay preserves
+  this public explanation; approval decisions and policies are unchanged.
+- Hosts can start Core's independently authenticated HTTP listener through a lazy Runtime lifecycle facade; unused server dependencies stay unloaded.
+
+### Changed
+
+- **Changelog entries are fragments** (`changelog.d/`, `scripts/changelog.py`). A pull request adds
+  `changelog.d/<pr-or-slug>.md` instead of editing `CHANGELOG.md`'s `[Unreleased]` section, which conflicted on every
+  merge of main; the release assembles the fragments (`python scripts/changelog.py assemble X.Y.Z`) and CI fails a pull
+  request that changes `src/` without one.
+- **AbstractCore floor `>=2.32.0`** (`pyproject.toml`, `integrations/abstractcore/output_specs.py`): the `decision` output modality (`output.decision` route, `/v1/decisions`, `MultimodalGenerateResponse.decision`, `output_has_generated_media` False for it).
+- **Voice transport is not a conversation attachment** (`history_bundle.py`, `conversation_search.py`). A session turn in
+  a history bundle no longer lists the recording of a spoken question or the read-aloud audio of an answer among its
+  `attachments` and `artifacts`; `is_voice_transport(tags)` recognizes them (`purpose` `voice_playback` or
+  `voice_dictation`, `artifact_space` `voice`, a `voice/` or `client:voice/` path). The bundle's own `artifacts`
+  section still lists every artifact. Clients that showed voice recordings as turn attachments stop doing so.
+
+### Fixed
+
+- **A console change to a non-text default no longer reloads the text model, and a runtime never
+  leaves a dropped copy resident.** Found on the Linux test server (two accounts, a 9B GGUF):
+  changing the embedding default evicted the admin runtime's whole text pool; the boot-warmed copy
+  was dropped, its eject skipped because both accounts' runtimes named the same default, and the
+  copy stayed in memory with no pool holding it ("resident ~5.4 GiB + 8.3 GiB cache ... still in
+  use by runtime client 70a5b844f350, runtime client 70a72f833890; not ejected"), with nothing
+  running. Now: (1) a capability-only refresh keeps every pooled text client and hands it the new
+  routes in place (a move of the `input.text` route itself still rebuilds); (2) a configured default
+  the client has not built is no longer a residency claim (a loaded one is its `pool` claim, one
+  loading is `building`); (3) when another runtime really keeps its own copy, the dropping runtime
+  still unloads its OWN HuggingFace copy (`released_own_copies`; MLX shares weights and is left to
+  the process-wide eject); (4) holders are named in words: `MultiLocalAbstractCoreLLMClient
+  .residency_owner_label` (hosts set it; the gateway: "the runtime of account default/bob"), claims
+  carry `owner_label`, residency records carry `held_by`, and the skip reason reads "the runtime of
+  account default/bob (loaded) still uses it". HuggingFace process rows also carry the loaded
+  `context_length` and `kv_cache_bytes` (AbstractCore 2.31.1).
+- **A standalone `LocalAbstractCoreLLMClient` claims the model it holds** (ROOT backlog 0897): another
+  client's default switch or a server unload no longer ejects weights it still uses (its next call
+  silently reloaded them). A pool unregisters the clients it adopts (its own claims cover them).
+  A dropped HuggingFace copy is never lent to another request again, a copy a call just started on
+  is freed when that call ends, and one waiter per model frees every copy a later switch drops.
+- Conversational answer and retained-reply replay preserves original human whitespace and the actual question generation identity, including after another question has opened.
+- Completed flows with an explicit structured `result` and no prose now retain a final JSON message in replay. Generic agent envelopes are not serialized; internal-bearing results are withheld from the public projection while their technical run output remains available.
+- **A pin expression that is a single bare word explains how to pass text** (`visualflow_compiler/visual/pin_expressions.py`).
+  `hello` is read as a Python name; its `NameError` now says to write `'hello'` with quotes or to set the pin's value
+  instead of an expression.
+- **The residency listing carries the model's slot pool** (`integrations/abstractcore/llm_client.py`, core ADR 0011, OVH 8080 pass four). A GGUF row now carries `slots`, `slots_max`, `active`, `queued`, `copies`, `slot_bytes`, `shared_weights` and `slot_refusal_reason`, folded from Core's process row. Before, only the gateway's `/host/state` showed them, so the Resources table could not say that requests were waiting, or why another slot is not built. A row whose holders share one weights instance no longer says "each a full copy of the weights".
+- Structured generation carries JSON schemas across execution-client boundaries and creates validators where inference runs, preserving nested validation and defaults without serializing Python classes. Remote Core calls forward their structured response format and explicitly refuse Python validator classes that cannot cross HTTP. Local explicit validator classes remain supported. Request serialization failures are not retried, and execution diagnostics include the actual ledger step identity.
+
 ## [0.15.3] - 2026-10-29
 
 ### Fixed

{abstractruntime-0.15.3 → abstractruntime-0.17.0}/CONTRIBUTING.md

@@ -81,7 +81,8 @@ When behavior changes, update:
 - `docs/api.md` (public API surface + imports)
 - `docs/getting-started.md` (onboarding examples)
 - `docs/architecture.md` (semantics/invariants)
-- `CHANGELOG.md` (user-visible changes)
+- a changelog fragment, `changelog.d/<pr-or-slug>.md` (user-visible changes; never an edit of
+  `CHANGELOG.md`: [changelog.d/README.md](changelog.d/README.md), checked by CI)
 
 List every `docs/*.md` page in `docs/README.md`. Keep `llms.txt` (the hand-curated index) and
 `llms-full.txt` in step with the documentation in the same change. `llms-full.txt` is generated:
@@ -92,4 +93,5 @@ is stale). Add a page to the script's `DOCUMENTS` list when it joins the core se
 ## Releases
 
 - Bump `version` in `pyproject.toml`
-- Add a dated section to `CHANGELOG.md` (Keep a Changelog format)
+- Assemble the changelog: `python scripts/changelog.py assemble X.Y.Z` (the dated section from
+  `changelog.d/`, fragments deleted)

{abstractruntime-0.15.3 → abstractruntime-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.15.3
+Version: 0.17.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>=2.30.0
+Requires-Dist: abstractcore>=2.33.0
 Requires-Dist: abstractmemory>=0.4.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[apple]>=2.30.0; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.33.0; extra == 'apple'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'apple'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
 Provides-Extra: gpu
-Requires-Dist: abstractcore[gpu]>=2.30.0; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.33.0; extra == 'gpu'
 Requires-Dist: setuptools<82.0.0,>=77.0.3; extra == 'gpu'
 Provides-Extra: test
 Requires-Dist: aiosmtpd<2.0.0,>=1.4.4; extra == 'test'
@@ -55,10 +55,43 @@ 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.15.3 • **Python:** 3.10+
+**Version:** 0.17.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.17.0
+
+- **A host stop suspends a run, it never fails it**: a host that stops on purpose raises `EffectInterrupted` into
+  the effect in flight; the runtime writes no terminal record, the run stays running at its last durable step, and
+  the next tick sends the call again as attempt 1 (no retry used, no automation outcome, nothing notified).
+- **Public updates are typed**: a `public_update` in the replay view carries `update_kind`, `"finding"` (a fact or
+  piece of evidence the actor established) or `"progress"` (what it is doing), so a client can list a conversation's
+  findings. See [docs/replay.md](docs/replay.md#public-conversation-messages).
+- **Replayed tool calls keep the model's call id**: an `activities[].tool_calls[]` row also carries `call_id`, the id
+  a public update's `source_call_ids` cite, so a finding resolves to the results it cites.
+- **Compare reads text next to a number or true/false exactly**: `5 == "5"` and `"9" < 10` are true, text it
+  cannot read as that type (`"five"`, `"0x10"`, empty) fails the step with an error naming the node and pins, and
+  text against text is never converted.
+- **An automation occurrence says why it failed**: when the agent finished without success, the attention item and
+  the notification carry the agent's own error, never "completed". Full list: [CHANGELOG.md](CHANGELOG.md).
+
+## What's new in 0.16.0
+
+- **Calibrated decisions**: an `LLM_CALL` whose output says `modality: "decision"` returns typed answers
+  (`answers`, `decision`) from a decision model instead of generated text; `run_facade.decide(...)` runs one as a
+  durable child run and the `decide` VisualFlow node asks a choice, yes/no or score question. Requires AbstractCore
+  2.32.0 or newer (AbstractRuntime 0.17.0 requires 2.33.0). See [docs/integrations/abstractcore.md](docs/integrations/abstractcore.md).
+- **Conversational questions and guidance**: `ASK_USER` can ask an essential question (waits indefinitely) or a timed
+  clarification with a declared fallback; `Runtime.steer(..., display_text=)` records human guidance in its exact
+  words; opt-in public updates and tool-approval `public_action` context appear in the replay view.
+- **Model residency in words**: fit refusals are never retried and keep their typed fields on the ledger, residency
+  rows carry the slot pool (`slots`, `active`, `queued`, ...) and name who holds a model, and the config facade reads
+  and sets a local model's loaded context (`configured_model_context`, `set_model_context`).
+- **Structured output across process boundaries**: JSON schemas travel as data and validators are built where
+  inference runs, for local, remote and hybrid clients alike.
+- **Voice transport is not a turn attachment** in history bundles and conversation search. Full list:
+  [CHANGELOG.md](CHANGELOG.md#0160---2026-11-02).
+
 ## What's new in 0.15.3
 
 - **A run-store index build no longer announces its journal replay as changes**: a plain read (`list_run_index`,
@@ -128,8 +161,8 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.30.0 or newer (its light install:
-remote providers, tools, vision, voice, audio, and music integration), plus the
+The base install includes AbstractCore 2.33.0 or newer (its light install:
+remote providers, tools, vision, voice, audio, music, and decision 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
 sentence-transformer embeddings are not selected unless you choose a hardware
@@ -238,7 +271,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Runtime-owned integrations:
-- AbstractCore (LLM + tools, `MODEL_RESIDENCY` with residency locks and context estimates, public discovery/host/run facades, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, local-only prompt-cache export/import admin, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/video/voice/music outputs with progress events, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY` with residency locks and context estimates, public discovery/host/run facades, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, local-only prompt-cache export/import admin, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/video/voice/music outputs with progress events, calibrated decisions (`decide`), host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
 - AbstractCore models and engines for hosts: `config_facade` passes through the host profile, local-engine status and installs, the model catalog with fit verdicts, installed models, deletes, host jobs (with who-cancelled attribution) and the embeddable console screens: `docs/integrations/abstractcore.md#models-engines-and-host-jobs-config-facade`
 - For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers and the standalone email comms facade remain host-local and nondurable.
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
@@ -274,6 +307,14 @@ sr = create_scheduled_runtime(
 )
 ```
 
+## For AI agents
+
+Register and use the [`abstractruntime` agent skill](https://github.com/lpalbou/AbstractRuntime/tree/main/skills/abstractruntime)
+to operate durable workflows, waits, storage and AbstractCore integration. Copy
+`skills/abstractruntime/` from the checkout matching your package version into
+your agent's skills directory. Start with its install verification, then use the
+linked documentation for the installed version.
+
 ## Documentation
 
 | Document | Description |

{abstractruntime-0.15.3 → abstractruntime-0.17.0}/README.md

@@ -4,10 +4,43 @@
 
 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.15.3 • **Python:** 3.10+
+**Version:** 0.17.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.17.0
+
+- **A host stop suspends a run, it never fails it**: a host that stops on purpose raises `EffectInterrupted` into
+  the effect in flight; the runtime writes no terminal record, the run stays running at its last durable step, and
+  the next tick sends the call again as attempt 1 (no retry used, no automation outcome, nothing notified).
+- **Public updates are typed**: a `public_update` in the replay view carries `update_kind`, `"finding"` (a fact or
+  piece of evidence the actor established) or `"progress"` (what it is doing), so a client can list a conversation's
+  findings. See [docs/replay.md](docs/replay.md#public-conversation-messages).
+- **Replayed tool calls keep the model's call id**: an `activities[].tool_calls[]` row also carries `call_id`, the id
+  a public update's `source_call_ids` cite, so a finding resolves to the results it cites.
+- **Compare reads text next to a number or true/false exactly**: `5 == "5"` and `"9" < 10` are true, text it
+  cannot read as that type (`"five"`, `"0x10"`, empty) fails the step with an error naming the node and pins, and
+  text against text is never converted.
+- **An automation occurrence says why it failed**: when the agent finished without success, the attention item and
+  the notification carry the agent's own error, never "completed". Full list: [CHANGELOG.md](CHANGELOG.md).
+
+## What's new in 0.16.0
+
+- **Calibrated decisions**: an `LLM_CALL` whose output says `modality: "decision"` returns typed answers
+  (`answers`, `decision`) from a decision model instead of generated text; `run_facade.decide(...)` runs one as a
+  durable child run and the `decide` VisualFlow node asks a choice, yes/no or score question. Requires AbstractCore
+  2.32.0 or newer (AbstractRuntime 0.17.0 requires 2.33.0). See [docs/integrations/abstractcore.md](docs/integrations/abstractcore.md).
+- **Conversational questions and guidance**: `ASK_USER` can ask an essential question (waits indefinitely) or a timed
+  clarification with a declared fallback; `Runtime.steer(..., display_text=)` records human guidance in its exact
+  words; opt-in public updates and tool-approval `public_action` context appear in the replay view.
+- **Model residency in words**: fit refusals are never retried and keep their typed fields on the ledger, residency
+  rows carry the slot pool (`slots`, `active`, `queued`, ...) and name who holds a model, and the config facade reads
+  and sets a local model's loaded context (`configured_model_context`, `set_model_context`).
+- **Structured output across process boundaries**: JSON schemas travel as data and validators are built where
+  inference runs, for local, remote and hybrid clients alike.
+- **Voice transport is not a turn attachment** in history bundles and conversation search. Full list:
+  [CHANGELOG.md](CHANGELOG.md#0160---2026-11-02).
+
 ## What's new in 0.15.3
 
 - **A run-store index build no longer announces its journal replay as changes**: a plain read (`list_run_index`,
@@ -77,8 +110,8 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.30.0 or newer (its light install:
-remote providers, tools, vision, voice, audio, and music integration), plus the
+The base install includes AbstractCore 2.33.0 or newer (its light install:
+remote providers, tools, vision, voice, audio, music, and decision 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
 sentence-transformer embeddings are not selected unless you choose a hardware
@@ -187,7 +220,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Runtime-owned integrations:
-- AbstractCore (LLM + tools, `MODEL_RESIDENCY` with residency locks and context estimates, public discovery/host/run facades, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, local-only prompt-cache export/import admin, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/video/voice/music outputs with progress events, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY` with residency locks and context estimates, public discovery/host/run facades, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, local-only prompt-cache export/import admin, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/video/voice/music outputs with progress events, calibrated decisions (`decide`), host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
 - AbstractCore models and engines for hosts: `config_facade` passes through the host profile, local-engine status and installs, the model catalog with fit verdicts, installed models, deletes, host jobs (with who-cancelled attribution) and the embeddable console screens: `docs/integrations/abstractcore.md#models-engines-and-host-jobs-config-facade`
 - For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers and the standalone email comms facade remain host-local and nondurable.
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
@@ -223,6 +256,14 @@ sr = create_scheduled_runtime(
 )
 ```
 
+## For AI agents
+
+Register and use the [`abstractruntime` agent skill](https://github.com/lpalbou/AbstractRuntime/tree/main/skills/abstractruntime)
+to operate durable workflows, waits, storage and AbstractCore integration. Copy
+`skills/abstractruntime/` from the checkout matching your package version into
+your agent's skills directory. Start with its install verification, then use the
+linked documentation for the installed version.
+
 ## Documentation
 
 | Document | Description |

abstractruntime-0.17.0/changelog.d/README.md

@@ -0,0 +1,21 @@
+# Changelog fragments
+
+Each pull request that changes `src/` adds ONE file here instead of editing `CHANGELOG.md`:
+`changelog.d/<pr-number-or-slug>.md` (for example `changelog.d/123.md` or `changelog.d/a-short-slug.md`). A new file never
+conflicts with another branch; the `[Unreleased]` section did on every merge.
+
+A fragment is Keep a Changelog markdown: one or more of `### Added`, `### Changed`, `### Deprecated`,
+`### Removed`, `### Fixed`, `### Security`, each followed by its entries, written as before:
+
+```markdown
+### Fixed
+
+- **A stop signal is what a reader needs** (`module.py`). What was wrong, what is true now,
+  and how to use it ...
+```
+
+- CI (`changelog` job): a pull request that changes `src/` without adding a fragment fails, and so does a
+  malformed fragment. `python scripts/changelog.py check` runs the same check locally.
+- `python scripts/changelog.py preview` prints what the next release section will say.
+- Release: `python scripts/changelog.py assemble X.Y.Z` writes `## [X.Y.Z] - <date>` from every fragment
+  (sections in Keep a Changelog order) and deletes the fragments; commit that with the version bump.

{abstractruntime-0.15.3 → abstractruntime-0.17.0}/docs/README.md

@@ -23,10 +23,14 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 
 ## Guides
 
+- [AbstractRuntime agent skill](../skills/abstractruntime/SKILL.md) — a self-contained operating guide for agents using workflows, durable waits, stores and AbstractCore execution
+- [Structured responses](integrations/abstractcore.md#structured-responses) — JSON schemas across execution boundaries, local and remote validation, and streaming behavior
+- [Host-managed serving](integrations/abstractcore.md#host-managed-serving) — optional Core-owned HTTP lifecycle and host-admitted ASGI requests
+
 - `faq.md` — common questions (recommended)
 - `manual_testing.md` — manual smoke tests and how to run the test suite
 - `artifacts.md` — Runtime artifact identity, descriptors, provenance, catalog search, and access stats
-- `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS`, the `config_facade` models/engines/host-jobs passthroughs for hosts, the `structured_facade` response_format check for hosts, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, model-residency listings, locks and model switching, live token streaming, workspace-scoped tools, durable bloc prompt-cache control, media inputs, generated media outputs, video progress events, and tool approval waits via AbstractCore
+- `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS`, the `config_facade` models/engines/host-jobs passthroughs for hosts, the `structured_facade` response_format check for hosts, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, model-residency listings, locks and model switching, live token streaming, workspace-scoped tools, durable bloc prompt-cache control, media inputs, generated media outputs, calibrated decisions (`output.modality: "decision"`, `run_facade.decide`, the `decide` node), video progress events, and tool approval waits via AbstractCore
 - `integrations/abstractmemory.md` — the AbstractMemory memory facade (ADR 0011): open a mind, stamp provenance from the step context, reconstruct a source from the ledger (`get_record`), history and revisions, and the `MEMORY_REVISE` effect / `memory_revise` node
 - `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
 - `email.md` — email for each user: run-scoped account binding and the host resolver, sending without asking (self and pre-authorised recipients), the durable event inbox and mail feeder, the `email.received@1` trigger on the primary or any other mailbox of the user, mail verbs for flows (changes and sends only on a Read and write mailbox: `email_mailbox_read_only`, `email_mailbox_cannot_send`), and the send-email action

{abstractruntime-0.15.3 → abstractruntime-0.17.0}/docs/adr/0002_execution_modes_local_remote_hybrid.md

@@ -30,6 +30,7 @@ effect payloads, client construction arguments, or Runtime-owned environment var
 - Thin-mode clients can run the workflow logic while delegating inference to a server.
 - Remote mode supports AbstractCore per-request `base_url` routing (dynamic endpoint selection).
 - Tool execution can be gated by trust/sandbox policy outside the router.
+- In every mode, a host stop interrupts an effect (`EffectInterrupted`: no terminal record, re-issued on the next tick); only a failure the effect itself met is recorded as failed.
 
 ### See Also
 - Implementation: [`backlog/completed/005_abstractcore_integration.md`](../backlog/completed/005_abstractcore_integration.md)