AbstractRuntime 0.15.3__tar.gz → 0.16.0__tar.gz

abstractruntime-0.16.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.16.0}/CHANGELOG.md

@@ -5,8 +5,90 @@ 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.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.16.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.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.15.3
+Version: 0.16.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.32.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.32.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.32.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,27 @@ 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.16.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.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. 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 +145,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.32.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 +255,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 +291,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.16.0}/README.md

@@ -4,10 +4,27 @@
 
 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.16.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.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. 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 +94,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.32.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 +204,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 +240,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.16.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.16.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.16.0}/docs/api.md

@@ -71,7 +71,7 @@ Implementation: `src/abstractruntime/core/runtime.py`.
   - 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)
 - `Runtime.resume(workflow, run_id, wait_key, payload, max_steps=...) -> RunState`
   - 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
+  - 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`); replies to recognized conversational questions are instead retained without answering or resuming another question (below)
   - 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]`
@@ -89,6 +89,95 @@ Effect cancellation helpers (`src/abstractruntime/core/effect_cancellation.py`):
 - `request_model_effects_cancel(provider, model, cancelled_by="model_eject")` stops the effects using a model before it is unloaded; local `unload_model_residency` calls it for you
 - `kill_inflight_effect(step_id, killed_by=...)` is an in-process hard stop for a call that ignores its cancel event (it cannot interrupt a thread blocked inside one native call)
 
+### Conversational questions and deadlines
+
+`ASK_USER` retains its indefinite legacy behavior when `payload.question` is absent.
+For a conversational question, add exactly one of these policies alongside the existing
+`prompt`, `choices` and `allow_free_text` fields:
+
+```json
+{"importance": "essential"}
+```
+
+```json
+{"importance": "clarification", "timeout_s": 120, "fallback": "Compare both options before choosing."}
+```
+
+Essential questions have no deadline or fallback. Clarifications require a numeric duration
+from 120 through 300 seconds and a nonempty, predeclared safe fallback. Extra policy fields
+are refused. Time passing never grants tool approval or permission to perform an action.
+Flows may supply the same object through the AskUser `question` input or `effectConfig.question`.
+
+Every logical issuance has a fresh `wait_key` (`question:<id>`). Its persisted
+`waiting.details.question` contains `id`, `purpose: "conversation"`, `importance`,
+`published_at`, `deadline` and `fallback` (the last two are null for essential questions).
+The existing `waiting.prompt` remains the question text. Resume with the exact key and
+`{"response": "the person's words"}`. Empty responses and approval payloads are refused.
+
+The server arbitrates at commit time: a response before the deadline wins; at or after it,
+expiry wins even if the due scan has not run. An answer result carries
+`question: {id, outcome: "answered"}`. Expiry produces
+`{timed_out: true, fallback: "...", question: {id, outcome: "expired"}}` with no `response`.
+Hosts and actors must present this as a host-authored continuation, never as human speech.
+Cancellation records a `cancelled` outcome and does not continue the workflow.
+
+Explicit pause suppresses timeout continuation. The original deadline survives pause and
+restart; after explicit resume, an overdue question resolves before further work. A reply to
+a paused, expired or already resolved recognized question is retained in the ledger, with
+its reason, and does not answer a newer question. The small outcome index retains 64 entries;
+full outcomes and retained replies remain in the ledger. Outcome receipts are authoritative
+across a crash before the following checkpoint save.
+
+Memory, JSON and SQLite run stores index these USER deadlines through their existing due-wait
+queries. The existing scheduler/host runner advances them; Runtime does not install a timer
+service. Resolution uses process-local locks and the existing single-writer authority for
+the store; it is not a distributed multi-writer transaction. Legacy EVENT deadlines and
+tool-approval waits retain their own contracts.
+
+### Public conversation and accepted guidance
+
+An opt-in actor may inherit `_runtime.conversation: {enabled: true}` through native child
+workflows and VisualFlow Agent nodes. This flag does not create an extra inference call.
+Public updates enter replay only through an explicit completed `EMIT_EVENT` named
+`public_update`, with payload `id`, `text`, `run_id`, optional `session_id`, `iteration` and
+`source_call_ids`. The event's owner must match `run_id`; private diary/thinking fences are
+excluded. See [replay.md](replay.md#public-conversation-messages).
+
+Actors may attach `public_action` to a proposed `TOOL_CALLS` payload with `text`,
+`update_id`, `run_id`, positive integer `iteration` and `call_ids`. The text is the
+actor's public stated purpose (nonblank, at most 600 characters), not execution
+proof. The adapter owns its binding to an accepted public update and unchanged
+proposed calls. Runtime checks the owning run and exact effect call IDs, then
+narrows the metadata to the actual calls requiring approval. Mismatched targets,
+unknown or duplicate IDs, malformed metadata and private fences withhold the
+explanation without changing the approval policy. Valid context appears at
+`waiting.details.public_action` and the canonical replay interaction's `details`.
+Clients verify its run and exact pending IDs before presenting it. An absent
+explanation must not be replaced with private reasoning or a guessed purpose.
+Hosts with an earlier approval boundary can share
+`abstractruntime.integrations.abstractcore.effect_handlers.approval_public_action(run, payload, host_calls, waiting_calls)`.
+Pass the original effect payload and host calls plus the exact gated subset. The return
+value is validated narrowed metadata or `None`; compute it before replacing a delegated
+payload's `tool_calls`, and carry only that returned context forward. This helper grants
+no permission and changes no approval policy.
+
+For human input during work, `Runtime.steer(run_id, message, display_text=words, speaker=...)`
+keeps the existing durable guidance path and adds a public acceptance receipt only when
+`display_text` is explicitly supplied. `message` may contain quoted context; `display_text`
+preserves the person's exact original words (nonblank, at most 65,536 characters).
+Operational steering without this field does not become public human history.
+Hosts may supply `client_message_id` for correlation; it is preserved on the reserved
+receipt and replay message, independently of the sidecar sequence and message id.
+An accepted receipt means the words were durably queued; the actor's later response is the
+evidence that it considered or adopted them. It does not undo an action already performed.
+
+If the sidecar append succeeds and the public-receipt append fails, admission still succeeds:
+the exact words remain in the sidecar and the host logs a repair warning. Delivery repairs
+the receipt before acknowledging that source. A terminal run does not promise another actor
+boundary; its retained sidecar remains recoverable rather than being reported as refused.
+Entity visits use the narrower participant-checked visit door and fresh attributed recall,
+described in [entity-runtime.md](entity-runtime.md#live-visit-corrections).
+
 Tool scope: an explicit `allowed_tools` list in `run.vars["_runtime"]`, in a child run's `_runtime`, or in a `TOOL_CALLS` payload is a ceiling intersected across the run tree (`src/abstractruntime/core/tool_scope.py`). Approval policy can remove a prompt but can never grant a tool outside it; a missing key means unrestricted and an empty list denies every tool.
 
 For the execution model (ledger records, effect outcomes, waits), see `architecture.md`.
@@ -187,6 +276,13 @@ Implementation: `src/abstractruntime/core/policy.py`.
 - `EffectPolicy` protocol and implementations: `DefaultEffectPolicy`, `RetryPolicy`, `NoRetryPolicy`
 - `compute_idempotency_key(...)` helper
 
+The AbstractCore runtime factories default to three total LLM attempts and one
+tool attempt, with exponential backoff starting at one second and capped at
+30 seconds. Supply `effect_policy=NoRetryPolicy()` to disable Runtime retries;
+the provider may have its own retry policy. Deterministic structured-request
+and serialization refusals are nonretryable. Inspect a returned run's status
+and error even when `tick(...)` itself returns normally.
+
 Docs: `architecture.md` (reliability section).
 
 ## WorkflowBundles (`.flow`) and VisualFlow distribution
@@ -201,8 +297,8 @@ VisualFlow compiler helpers are available from `abstractruntime.visualflow_compi
 - `compile_visualflow(...)` and `compile_visualflow_tree(...)` compile VisualFlow JSON into executable `WorkflowSpec` objects.
 
 VisualFlow authoring note (media and document nodes):
-- Runtime recognizes first-class VisualFlow media nodes such as `generate_image`, `edit_image`, `image_to_image`, `upscale_image`, `image_upscale`, `generate_video`, `text_to_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, and `listen_voice`.
-- Generated-media and transcription nodes lower to a durable `EffectType.LLM_CALL` with an `output` selector (for example `{"modality":"music","task":"music_generation"}`), while `listen_voice` lowers to `WAIT_EVENT`. Hosts should persist the authoring node type rather than pre-lowering to `llm_call`.
+- Runtime recognizes first-class VisualFlow media nodes such as `generate_image`, `edit_image`, `image_to_image`, `upscale_image`, `image_upscale`, `generate_video`, `text_to_video`, `image_to_video`, `generate_voice`, `generate_music`, `decide`, `transcribe_audio`, and `listen_voice`.
+- Generated-media and transcription nodes lower to a durable `EffectType.LLM_CALL` with an `output` selector (for example `{"modality":"music","task":"music_generation"}`), while `listen_voice` lowers to `WAIT_EVENT`. The `decide` node asks ONE question about a state (inputs `state`, `question`, `question_type` = `choice` | `noul` | `score`, `options` for a choice, `levels` for a score, `provider`, `model`, `truncate`) and fills the typed output pins of that type (`answer` plus `choice`/`confidence`/`probabilities`, `noul`/`verdict`, or `score`/`level`/`confidence`/`probabilities`, with `model` and `success`); a wired `questions` object (several System One questions) replaces the single question and fills `answers`. It lowers to the same `LLM_CALL` with `{"modality":"decision","questions":{...}}` and the state as the prompt; see [decisions](integrations/abstractcore.md#decisions). Hosts should persist the authoring node type rather than pre-lowering to `llm_call`.
 - Runtime also recognizes file/document nodes. `read_file` and `write_file`
   handle UTF-8 text/JSON workspace paths. In Gateway-hosted runs, those paths
   follow the shared canonical contract: `rel/path` for the main workspace root
@@ -332,6 +428,13 @@ This produces a portable record of a run’s state + ledger + artifacts suitable
 When available, it also includes `resolved_actions`: bounded capability/action summaries derived
 from Core route resolution and persisted from `LLM_CALL` results.
 
+Voice transport is never part of a conversation turn: the recording of a spoken question and the
+read-aloud audio synthesized from an answer are left out of each session turn's `attachments` and
+`artifacts`. `is_voice_transport(tags)` (in `abstractruntime.history_bundle`) recognizes them:
+`purpose` `voice_playback` or `voice_dictation`, `artifact_space` `voice`, or a `voice/` or
+`client:voice/` path. The bundle's own `artifacts` section stays complete, and conversation search
+applies the same rule.
+
 ## Replay view (one reconstruction of a run, every client)
 
 Implementation: `src/abstractruntime/replay/` (ADR 0010). Guide: [replay.md](replay.md).
@@ -355,7 +458,7 @@ Implementation: `src/abstractruntime/replay/` (ADR 0010). Guide: [replay.md](rep
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install abstractruntime` (AbstractCore 2.30.0 or newer is part of the base install).
+Requires: `pip install abstractruntime` (AbstractCore 2.32.0 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -379,7 +482,7 @@ Entry points:
 - local `list_model_residency` merges AbstractCore's host-wide loaded-model sweep into text-generation listings (sweep-only rows carry `source: "provider_server"` and no `task` label), and residency rows normalize provider size extras to `size_bytes` / `size_vram_bytes` while keeping the originals; local text rows also carry registry-declared `modalities` (omitted on a registry miss), host identity (`host_id` / `host_name`), and runtime-owned lock truth (`locked` / `lockable`, with `pinned` a truthful alias of `locked` — never the default-identity flag, which `default` alone carries), while remote listings keep the Core server's row identity
 - host-local prompt-cache export/import admin also lives on the host facade and client delegation layer (`list_prompt_cache_exports`, `prompt_cache_export`, `prompt_cache_import`) and is intentionally local-only
 - host-facade email helpers (`list_email_accounts`, `list_emails`, `read_email`, `send_email`) use the process's own AbstractCore account (single-user installs)
-- run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `edit_image`, `upscale_image`, `generate_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
+- run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `edit_image`, `upscale_image`, `generate_video`, `image_to_video`, `generate_voice`, `generate_music`, `decide`, `transcribe_audio`, `send_email`, `send_telegram_message`)
 - task-specific image/video helpers preserve batch and adapter controls such as
   `count`/`n`, `seeds`, ordered `lora_adapters`, and video `flow_shift`; local
   subprocess isolation stays within the same public contract.
@@ -396,15 +499,17 @@ Execution controls and cancellation:
 - `media`: a media path, artifact ref (`{"$artifact": "..."}` or `{"artifact_id": "..."}`), media dict, or list of those
 - `output`: AbstractCore output selector; top-level `outputs` is accepted as a runtime alias
 - `params`: provider/model routing, generation controls, prompt-cache keys or `prompt_cache_binding`, structured-output schema options, and tracing metadata
+- `response_schema` / `response_schema_name`: JSON schema data and name for a structured result at `result.data`; local execution creates the validator at the provider boundary. Structured calls do not stream tokens. Remote/hybrid clients forward an OpenAI JSON-schema response format; Python validator classes cannot cross HTTP. See [structured responses](integrations/abstractcore.md#structured-responses).
 
 Multimodal support:
 - common remote-light AbstractCore media, vision, voice, audio, and music dependencies are part of the base Runtime install
 - local clients call AbstractCore's unified `generate(..., media=..., output=...)`
-- remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, image edits, image upscaling, text-to-video, image-to-video, speech, music generation, and transcription endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
+- remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, image edits, image upscaling, text-to-video, image-to-video, speech, music generation, transcription, and decision (`POST /v1/decisions`) endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
 - remote transcription requires one audio media item that resolves to a local file path or artifact-backed temporary file
 - generated image/video/voice/music/audio bytes require a runtime `ArtifactStore`; the result contains `artifact_id` / `artifact_ref` instead of inline bytes
+- a decision (`output: {"modality": "decision", "questions": {...}}`, the state as the prompt) is typed answers, not bytes: no `ArtifactStore` is needed, and the result carries `content` (the answers as JSON), `decision` (`model`, `answers`, `usage`, `latency_ms`, optional `truncated`), `answers`, and the `provider` / `model` of the decision model; the resolved action id is `decision`. Without a `model` the call uses the `output.decision` capability default, so a text runtime on any provider can answer decisions once that default is set (see [decisions](integrations/abstractcore.md#decisions))
 - streamed TTS playback artifacts carry `purpose=voice_playback`, `artifact_space=voice` and a logical `voice/tts-<id>.wav` path in their tags; hosts can separate read-aloud recordings from user attachments while retaining their artifact refs and provenance
-- with the pooled local client (`MultiLocalAbstractCoreLLMClient`), a request whose outputs are all non-text (image, video, voice, music, transcription) and that carries no tools never builds the text client: it runs on AbstractCore's capability host (`CapabilityHostProvider`, no text model), and so does streaming TTS. A text default that cannot be built (an engine not installed) therefore never blocks speech or image generation
+- with the pooled local client (`MultiLocalAbstractCoreLLMClient`), a request whose outputs are all non-text (image, video, voice, music, transcription, decision) and that carries no tools never builds the text client: it runs on AbstractCore's capability host (`CapabilityHostProvider`, no text model), and so does streaming TTS. A text default that cannot be built (an engine not installed) therefore never blocks speech or image generation
 - media-only normalized results expose `runtime_provider` / `runtime_model` separately from `media_provider` / `media_model`
 - local image/video generation runs in a one-shot subprocess (`execution_mode="local_one_shot_subprocess"`) unless every requested media model is resident (explicitly loaded with `load_model_residency`), in which case it runs in-process on the loaded pipeline (`execution_mode="resident_in_process"`, `resident_load_ids`)
 - a media spec whose `provider` is an endpoint profile (`endpoint:<id>`) never uses the one-shot subprocess: it is an HTTP call to that endpoint, and the host's endpoint-profile resolver (`set_provider_endpoint_profile_resolver`) exists only in this process
@@ -416,7 +521,7 @@ Prompt cache / cached sessions:
 - LLM clients expose cache control methods listed above for host-side preparation and inspection
 - `LLM_CALL.params.prompt_cache_key` selects a cache key for a call; runtime can also derive a session-scoped key from `run.vars["_runtime"]["prompt_cache"]` or the Runtime-owned `ABSTRACTRUNTIME_PROMPT_CACHE` process default
 - `LLM_CALL.params.prompt_cache_binding` is the durable exact-reuse input for bloc-backed prompt caching; if a binding includes `key`, Runtime adopts it as the effective prompt-cache key and refuses mismatches before provider execution
-- Runtime only auto-derives session prompt-cache keys for text/chat calls; non-text output selectors such as image, voice, music, and transcription keep explicit `prompt_cache_binding` support but do not receive an inferred cache key
+- Runtime only auto-derives session prompt-cache keys for text/chat calls; non-text output selectors such as image, voice, music, decision, and transcription keep explicit `prompt_cache_binding` support but do not receive an inferred cache key
 - when Runtime injects the derived session key, the client stamps session attribution (`session_id`, `run_id`, `workflow_id`, `node_id`, `namespace`) into the cache entry's metadata after each generate; caller-supplied `prompt_cache_key`s and binding keys are never stamped, so session-scoped clearing cannot destroy caches shared across sessions
 - `get_abstractcore_host_facade(...)` exposes `get_memory_snapshot()`, `list_session_prompt_caches(session_id=None)`, and `clear_session_prompt_caches(session_id)`; session caches persist until a host clears them, the owning model is unloaded, or the provider evicts them — completing a run does not clear them
 - `get_abstractcore_host_facade(...)` also exposes durable bloc helpers (`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`)
@@ -474,6 +579,8 @@ inside an effect handler. Details: [integrations/abstractmemory.md](integrations
 
 ### Host ASGI serving
 
+`abstractruntime.integrations.abstractcore.server_facade.start_core_server(*, host=None, port=None)` starts Core's optional listener in the calling execution process. It returns a Core-owned handle with `url`, `is_running`, `status()` and `stop()`. Core owns configuration, credentials and HTTP request handling; stopping the listener does not unload resident providers. Omitted bind arguments use Core server settings; explicit port `0` selects an ephemeral port. Startup errors raise to the caller. Importing the facade starts nothing. See [host-managed serving](integrations/abstractcore.md#host-managed-serving).
+
 `abstractruntime.integrations.abstractcore.server_facade.serve_core_request(scope, receive, send, *, token: str, allow_unauthenticated: bool = False)` delegates host-admitted ASGI requests with request-scoped Core authentication. See [host-managed serving](integrations/abstractcore.md#host-managed-serving) for network and credential responsibilities.
 
 ### Structured-output checks