AbstractRuntime 0.4.35__tar.gz → 0.5.0__tar.gz

{abstractruntime-0.4.35 → abstractruntime-0.5.0}/CHANGELOG.md

@@ -5,7 +5,114 @@ 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.5.0] - 2026-09-26
+
+### Fixed
+
+- When an LLM call is re-run after a stray kill, its interrupted first run ends with
+  `delta_end` `cancelled` with `detail: "reinvoked"` (the run continues) and the re-run streams
+  under its own call id, so a live view never shows a partial answer followed by the full one.
+- The last batch of a streamed reply is sent before the call's final record is written, never just
+  after it; text arriving once the call has returned is dropped.
+- A streamed reply that only turns out to lack token usage at the end now ends with
+  `reason: "completed"` in the live view (the text did stream); `usage_unavailable` is recorded on
+  the `LLM_CALL` record only.
+- Streamed answers without usage are no longer invisible to the aborted-generation check: it judges
+  them from `finish_reason` and the text, and the record says so with `metadata.usage_estimated`.
+- Servers that reject `stream_options` but still send token usage (LM Studio) stream again.
+  Streaming is refused for missing usage only when the provider reports the rejection AND a
+  streamed answer came back without usage; one call in ten streams again to re-check, and a
+  streamed answer with usage lifts the refusal.
+- A child run or a VisualFlow node can no longer switch off the host's built-in workspace
+  protection: it may add `workspace_builtin_deny_prefixes`, never remove the host's, and cannot
+  widen `workspace_builtin_allow` beyond the parent's (its own folder counts only when it is
+  inside an allowed folder).
+- Harmony-format models (gpt-oss) stream their answers live: the `final` channel is sent as
+  content, `analysis` as reasoning, and tool calls are held back. A call whose whole answer is held
+  back ends with `reason: "unavailable"`, `detail: "tool_envelope_holdback"` instead of a silent
+  empty live view.
+- One streamed answer without token usage no longer turns streaming off for that model until
+  restart. That call is reported (`usage_unavailable`) and the next call streams again; streaming
+  stays off only when the provider reports that its server rejects usage in streams.
+- Host-protected folders no longer grow the system prompt. A host can pass its own protection as
+  `workspace_builtin_deny_prefixes` (for example the gateway's data folder and credential folders)
+  and `workspace_builtin_allow` (the run's own folder inside it). File tools, listings and the
+  shell's starting folder are refused under a denied prefix, except under an allow entry. These
+  entries are enforced but never written into the model's system prompt, which keeps it identical
+  from turn to turn (and the prompt cache warm); only the operator's own `workspace_ignored_paths`
+  are shown to the model. Child runs inherit both lists.
+- MLX calls stream again when they use a prompt-cache key: AbstractCore now puts the prompt-cache
+  record on the stream's last chunk, so the streamed record matches the non-streamed one.
+- Streamed LLM calls now record the same result as non-streamed ones: `raw_response` is present
+  (the provider's terminal chunk), and the last reasoning fragment no longer leaks into
+  `metadata.reasoning_delta`.
+- Changing the default text model no longer leaves the previous model in memory. The previous
+  in-process model (MLX or HuggingFace) is unloaded from the whole process before the new default
+  is loaded, unless the pool still uses it or it is locked. A call still generating on it is not
+  cancelled; the model is unloaded when that call ends. Measured on a 27B MLX model: 17 GB stayed
+  resident after a console switch; now it is freed.
+- Changing the default model in one service never unloads a model another service, user or
+  entity in the same process still uses or has locked. The check covers every owner in the
+  process and runs under one lock with the unload, so a model being loaded again at that moment
+  is not unloaded either.
+- `list_model_residency` diagnostics carry `pending_ejects` (a previous model waiting for its
+  running call to end before it is unloaded) and `last_switch_ejects` (unloaded, kept because
+  something still uses it, or failed, with the reason).
+- A load with `ttl_s` or `keep_alive` on an in-process model, or on a model that was already
+  loaded, now reports them under `unsupported_options` with a warning; provider warnings appear in
+  the response's top-level `warnings`.
+- A model load that fails part-way unloads what it had loaded.
+- Chat compaction summarizes a run with the model the run uses, instead of loading the default
+  model just for the summary. A run with no model of its own is summarized with the current
+  default model, resolved on each call; the summarizer no longer holds the model that was the
+  default at startup.
+- Unloading a model by `runtime_id` alone now works for every task: TTS, STT, image, music and
+  embedding rows, not only text. A backend's own id is looked up in the listing.
+- Listings no longer report a task error on every call for `image_upscale`, `video_generation`,
+  `text_to_video`, `image_to_video` and `text_to_audio`; they are served by the image and music
+  capabilities.
+- Changing a capability default unloads the models the previous capability routes had loaded
+  instead of leaving them in memory.
+- Unloading a local MLX model through the runtime (`model_residency` unload, on
+  a single client or the multi-model pool) now frees it from every holder in
+  the process, not only from the runtime's own instance. Before, the weights
+  could stay in memory when another part of the process still held the model
+  (for example a client created with a per-request override, a chat summarizer
+  built at startup, or a runtime left over after a bundle reload), and the
+  unload still reported success. The unload result now includes a
+  `process_eject` report and names what, if anything, is still held.
+- Model residency listings now show MLX models the process still holds, even
+  when the runtime's own pool no longer references them
+  (`provider_state: "resident_via_other_holders"`). Such a model can be
+  unloaded from the listing like any other.
+
+### Added
+
+- **Live token streaming.** `Runtime.set_live_delta_sink(sink)` lets a host receive the text of an
+  answer while it is generated. For runs started with `_runtime.stream: true`, each LLM call streams
+  and the sink gets `llm.delta` events (`run_id`, `parent_run_id`, `node_id`, `call_id` = the LLM
+  call's step id, `seq`, `text`, `channel` = `content` or `reasoning`) and one `llm.delta_end`
+  (`completed`, `failed`, `cancelled`, or `unavailable` with a `detail`) after the call's final
+  record is written. Deltas are never written to the ledger. Thinking is sent on its own `reasoning`
+  channel, including inline `<think>` markup, and tool-call markup never reaches the live text.
+  A call streams only when its recorded result keeps its usage, `raw_response` and prompt-cache
+  telemetry; otherwise it runs non-streamed and the reason is sent to the client and recorded as
+  `_runtime_observability.stream_unavailable`. Child runs inherit `stream`. `Runtime.start`
+  refuses a non-boolean `_runtime.stream`. Remote mode (AbstractCore server) stays non-streaming.
+  See `docs/integrations/abstractcore.md#live-token-streaming`.
+- Embedding models loaded in the process appear in `list_model_residency` as `task: "embedding"`
+  rows (`local:embedding:huggingface:<model>`, with holders and bytes) and can be unloaded like any
+  other model.
+- HuggingFace models held in the process outside the runtime's pool are listed and unloaded like
+  MLX ones.
+
+### Changed
+
+- Compatibility: AbstractRuntime 0.5.0 requires AbstractCore 2.16.0 or newer (was 2.15.1 in
+  0.4.35) in the base install and in the `apple` and `gpu` extras, and `models_engines_support()`
+  reports 2.16.0 as `required`. The live streaming, process-wide unload and residency features above
+  use modules that first ship in AbstractCore 2.16.0. Upgrading AbstractRuntime upgrades AbstractCore
+  accordingly; if you pin AbstractCore yourself, raise the pin to 2.16.0.
 
 ## [0.4.35] - 2026-09-25
 
@@ -888,7 +995,8 @@ AbstractRuntime is the durable execution substrate designed to pair with Abstrac
 
 Initial development version with basic proof-of-concept features.
 
-[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.35...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/lpalbou/abstractruntime/compare/v0.4.35...v0.5.0
 [0.4.35]: https://github.com/lpalbou/abstractruntime/compare/v0.4.34...v0.4.35
 [0.4.34]: https://github.com/lpalbou/abstractruntime/compare/v0.4.33...v0.4.34
 [0.4.33]: https://github.com/lpalbou/abstractruntime/compare/v0.4.32...v0.4.33

{abstractruntime-0.4.35 → abstractruntime-0.5.0}/CONTRIBUTING.md

@@ -22,6 +22,9 @@ python -m pip install -e ".[test,docs]"
 python -m pytest -q
 ```
 
+Inside the AbstractFramework workspace, prefer `python -P -m pytest tests -q`: `-P` keeps the current folder off
+`sys.path`, so a workspace folder named like a package (for example `abstractflow/`) cannot shadow it.
+
 If you cloned **only** this repo (without the AbstractFramework workspace), make sure the sibling packages above are importable (install them or clone them next to this repo) before running the full test suite.
 
 ## Repo map (source of truth)
@@ -56,6 +59,12 @@ When behavior changes, update:
 - `docs/architecture.md` (semantics/invariants)
 - `CHANGELOG.md` (user-visible changes)
 
+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:
+run `python scripts/generate_llms_full.py` after editing any page it includes, and
+`python scripts/generate_llms_full.py --check` to confirm it is current (it exits 1 when the file
+is stale). Add a page to the script's `DOCUMENTS` list when it joins the core set.
+
 ## Releases
 
 - Bump `version` in `pyproject.toml`

{abstractruntime-0.4.35 → abstractruntime-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.4.35
+Version: 0.5.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.15.1
+Requires-Dist: abstractcore[audio,music,remote,tools,vision,voice]>=2.16.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.15.1; extra == 'apple'
+Requires-Dist: abstractcore[all-apple]>=2.16.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.15.1; extra == 'gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.16.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.4.35 • **Python:** 3.10+
+**Version:** 0.5.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.15.1 or newer with remote provider,
+The base install includes AbstractCore 2.16.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.4.35)
+## What’s included (v0.5.0)
 
 Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -179,7 +179,7 @@ Drivers + distribution:
   Core media controls, including `count`/`n`, `seeds`, ordered
   `lora_adapters`, and video `flow_shift`, while keeping provider/model/task
   truth in AbstractCore and AbstractVision.
-- `history_bundle` now exports replay-safe `resolved_actions` summaries derived
+- `history_bundle` exports replay-safe `resolved_actions` summaries derived
   from Core request/output route resolution, so thin clients can reconstruct
   what capability ran without reverse-engineering prompt prose.
 - VisualFlow structured LLM/Agent results preserve `response` as text and expose
@@ -195,6 +195,9 @@ Runtime-owned integrations:
   depends on the light AbstractMemory contract; hosts choose storage backends
   such as LanceDB, SQLite, or in-memory stores.
 - comms toolset gating (email/WhatsApp/Telegram): `docs/tools-comms.md`
+- live token streaming: `Runtime.set_live_delta_sink(sink)` plus `_runtime.stream: true` delivers `llm.delta` / `llm.delta_end` events while an answer is generated, outside the ledger (`docs/integrations/abstractcore.md#live-token-streaming`)
+- model switching in a shared process: changing the default model unloads the previous in-process model unless another owner in the process still uses it (`docs/integrations/abstractcore.md#unloading-and-switching-models`)
+- workspace-scoped file and shell tools driven by `workspace_*` run vars, including host-only protected folders that are enforced without being shown to the model (`docs/integrations/abstractcore.md#workspace-scoped-tools`)
 
 ## Built-in scheduler (zero-config)
 

{abstractruntime-0.4.35 → abstractruntime-0.5.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.4.35 • **Python:** 3.10+
+**Version:** 0.5.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.15.1 or newer with remote provider,
+The base install includes AbstractCore 2.16.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.4.35)
+## What’s included (v0.5.0)
 
 Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -129,7 +129,7 @@ Drivers + distribution:
   Core media controls, including `count`/`n`, `seeds`, ordered
   `lora_adapters`, and video `flow_shift`, while keeping provider/model/task
   truth in AbstractCore and AbstractVision.
-- `history_bundle` now exports replay-safe `resolved_actions` summaries derived
+- `history_bundle` exports replay-safe `resolved_actions` summaries derived
   from Core request/output route resolution, so thin clients can reconstruct
   what capability ran without reverse-engineering prompt prose.
 - VisualFlow structured LLM/Agent results preserve `response` as text and expose
@@ -145,6 +145,9 @@ Runtime-owned integrations:
   depends on the light AbstractMemory contract; hosts choose storage backends
   such as LanceDB, SQLite, or in-memory stores.
 - comms toolset gating (email/WhatsApp/Telegram): `docs/tools-comms.md`
+- live token streaming: `Runtime.set_live_delta_sink(sink)` plus `_runtime.stream: true` delivers `llm.delta` / `llm.delta_end` events while an answer is generated, outside the ledger (`docs/integrations/abstractcore.md#live-token-streaming`)
+- model switching in a shared process: changing the default model unloads the previous in-process model unless another owner in the process still uses it (`docs/integrations/abstractcore.md#unloading-and-switching-models`)
+- workspace-scoped file and shell tools driven by `workspace_*` run vars, including host-only protected folders that are enforced without being shown to the model (`docs/integrations/abstractcore.md#workspace-scoped-tools`)
 
 ## Built-in scheduler (zero-config)
 

{abstractruntime-0.4.35 → abstractruntime-0.5.0}/docs/README.md

@@ -26,7 +26,7 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `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, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, model-residency listings and locks, 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, cached sessions with per-session prompt-cache listing/clearing, host memory snapshots, model-residency listings, locks and model switching, live token streaming, workspace-scoped tools, durable bloc prompt-cache control, media inputs, generated media outputs, video progress events, and tool approval waits via AbstractCore
 - `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
 - `tool-approval.md` — tool risk tiers, the run-policy rank ceiling, and per-call refiners (the `send_email` self-recipient rule)
 - `api.md#workflowbundles-flow-and-visualflow-distribution` — VisualFlow compiler APIs, media nodes, and document nodes (`read_pdf` / `write_pdf` / `write_docx`)

{abstractruntime-0.4.35 → abstractruntime-0.5.0}/docs/api.md

@@ -75,6 +75,8 @@ Implementation: `src/abstractruntime/core/runtime.py`.
   - persists `CANCELLED`, then signals every effect of that run (and its in-flight descendants) executing in this process; the running attempt is recorded as `cancelled` (`StepStatus.CANCELLED`, never retried) with `cancelled_by` and `reason`, and no further effect starts
 - `Runtime.set_default_provider_model(provider=..., model=...)`
   - re-points the default provider/model seeded into new runs; pair it with the pooled client's `set_default_provider_model(...)` so both agree
+- `Runtime.set_live_delta_sink(sink)` where `sink(event: dict) -> None`, or `None` to remove it
+  - receives live token deltas (`llm.delta`, `llm.delta_end`) for LLM calls of runs started with `_runtime.stream: true` (a boolean; `start` refuses any other value); nothing is written to the ledger. See [Live token streaming](integrations/abstractcore.md#live-token-streaming)
 
 Effect cancellation helpers (`src/abstractruntime/core/effect_cancellation.py`):
 - `inflight_effects(run_ids=None)` lists executing effects (run, step, provider, model, elapsed time)
@@ -216,7 +218,7 @@ from Core route resolution and persisted from `LLM_CALL` results.
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install abstractruntime` (AbstractCore 2.15.1 or newer is part of the base install).
+Requires: `pip install abstractruntime` (AbstractCore 2.16.0 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -231,6 +233,7 @@ Entry points:
 - 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`)
 - 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
 - the `MODEL_RESIDENCY` effect supports `list_loaded`, `load`, `unload`, `lock`, and `unlock` operations with the same soft-fail semantics; on `unload`, `force` is forwarded only when authored in the effect payload
 - local `list_model_residency` merges AbstractCore's host-wide loaded-model sweep into text-generation listings (sweep-only rows carry `source: "provider_server"` and no `task` label), and residency rows normalize provider size extras to `size_bytes` / `size_vram_bytes` while keeping the originals; local text rows also carry registry-declared `modalities` (omitted on a registry miss), host identity (`host_id` / `host_name`), and runtime-owned lock truth (`locked` / `lockable`, with `pinned` a truthful alias of `locked` — never the default-identity flag, which `default` alone carries), while remote listings keep the Core server's row identity
@@ -275,6 +278,9 @@ Prompt cache / cached sessions:
 - local Runtime owns the bloc root policy: `~/.abstractruntime/blocs` by default, `<base_dir>/blocs` for `create_local_file_runtime(...)`, and explicit `bloc_root_dir=...` overrides when needed
 - provider cache/session handles are not durable runtime state and should not be stored in `RunState.vars`
 
+Workspace scope:
+- run vars `workspace_root`, `workspace_access_mode`, `workspace_allowed_paths`, `workspace_ignored_paths`, and the host-only `workspace_builtin_deny_prefixes` / `workspace_builtin_allow` scope file and shell tools; child runs inherit them (see `integrations/abstractcore.md#workspace-scoped-tools`)
+
 Attachment registration limits:
 - `TOOL_CALLS.payload.max_attachment_bytes`, `run.vars["_runtime"]["max_attachment_bytes"]`, or `ABSTRACTRUNTIME_MAX_ATTACHMENT_BYTES` bound the bytes Runtime stores when local `read_file` outputs are captured as session attachments
 

{abstractruntime-0.4.35 → abstractruntime-0.5.0}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-09-25
-> Version: 0.4.35
+> Updated: 2026-09-26
+> Version: 0.5.0
 > Scope: this describes **what is implemented in this repository**.
 
 AbstractRuntime is a **durable workflow runtime**: it executes workflow graphs as a persisted state machine with explicit waits (user, time, events, jobs, subworkflows). A run can pause for hours/days and resume **without** keeping Python stacks/coroutines alive.
@@ -86,6 +86,54 @@ engine installer, host job registry"]
 
 This keeps the runtime usable by `../abstractgateway` and application layers such as `../abstractflow`, `../abstractassistant`, `../abstractobserver`, and `../abstractcode` without embedding provider-specific model logic in the durable kernel.
 
+### Live token streaming (outside the ledger)
+
+Live text travels on a side channel next to the durable path. A run opts in with `_runtime.stream: true`, the host registers one sink with `Runtime.set_live_delta_sink(sink)`, and each `LLM_CALL` hands a per-call emitter (`src/abstractruntime/core/live_deltas.py`) to the AbstractCore client. The emitter batches fragments (about 40 ms), splits reasoning from content, holds back tool-call markup, and always closes the call with one `llm.delta_end` after the durable record is appended. Nothing on the live path is persisted, so replay and the ledger are the same with streaming on or off. See [Live token streaming](integrations/abstractcore.md#live-token-streaming).
+
+```mermaid
+flowchart LR
+  Provider["AbstractCore provider
+(stream=True)"] -->|"chunks"| Client["LLM client
+think / harmony split,
+tool-markup hold-back"]
+  Client -->|"content / reasoning fragments"| Emitter["LiveDeltaEmitter
+(per call, ~40 ms batches)"]
+  Emitter -->|"llm.delta / llm.delta_end"| Sink["host sink
+set_live_delta_sink"]
+  Client -->|"final result
+(content, usage, raw_response, prompt_cache)"| Handler["LLM_CALL handler"]
+  Handler -->|"StepRecord"| Ledger["LedgerStore"]
+  Handler -.->|"after the record: delta_end"| Emitter
+```
+
+### Model residency in a shared process
+
+In-process models (MLX, HuggingFace, embeddings) belong to the process, not to one runtime. Every multi-local client registers what it still needs (pooled, per-override, locked, being built, default) with AbstractCore's process residency registry. An unload after a default switch or a failed load goes through `eject_unclaimed`, which checks every owner's claims and unloads under one lock, so one service never unloads a model another service, user, entity runtime or the AbstractCore server still uses. A model that is still generating is unloaded when its call ends. See [Unloading and switching models](integrations/abstractcore.md#unloading-and-switching-models).
+
+```mermaid
+flowchart TB
+  subgraph Process["One host process"]
+    ClientA["multi-local client
+(service A)"]
+    ClientB["multi-local client
+(service B / entity runtime)"]
+    Server["AbstractCore server
+managed runtimes"]
+    Registry["process residency registry
+claims: pool, override, lock,
+building, default"]
+    Weights["in-process weights
+MLX / HuggingFace / embeddings"]
+  end
+
+  ClientA -->|"register claims"| Registry
+  ClientB -->|"register claims"| Registry
+  Server -->|"register claims"| Registry
+  ClientA -->|"default switch:
+eject_unclaimed(old model)"| Registry
+  Registry -->|"unload only if no owner claims it"| Weights
+```
+
 ## Component map
 
 ```mermaid
@@ -238,7 +286,7 @@ Registered in `Runtime._register_builtin_handlers()` (`src/abstractruntime/core/
 
 ### Host-wired effects
 The kernel defines the protocol; concrete integrations provide handlers:
-- `LLM_CALL`, `TOOL_CALLS`, `MODEL_RESIDENCY`: provided by AbstractCore integration (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). The integration supports local/remote/hybrid execution, cached sessions/prompt-cache control with per-session attribution and clearing, host memory snapshots, discovery/catalog snapshots, model residency including host-wide provider-server rows in listings, residency locks with `force`-gated unload and context-estimate relays, durable run-scoped media child runs, media inputs, generated media outputs, provider progress callbacks as ledger events, provider-key header routing for remote servers, passthrough tools, and approval-gated local tool execution.
+- `LLM_CALL`, `TOOL_CALLS`, `MODEL_RESIDENCY`: provided by AbstractCore integration (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). The integration supports local/remote/hybrid execution, cached sessions/prompt-cache control with per-session attribution and clearing, host memory snapshots, discovery/catalog snapshots, model residency including host-wide provider-server rows in listings, residency locks with `force`-gated unload and context-estimate relays, durable run-scoped media child runs, media inputs, generated media outputs, provider progress callbacks as ledger events, provider-key header routing for remote servers, passthrough tools, approval-gated local tool execution, and workspace-scoped file and shell tools (run vars `workspace_*`, inherited by child runs; the host's built-in deny prefixes are enforced without being rendered into the model's prompt).
 - `MEMORY_KG_*`: provided by the AbstractMemory bridge (`src/abstractruntime/integrations/abstractmemory/effect_handlers.py`)
 
 ### Reliability: retries + idempotency

{abstractruntime-0.4.35 → abstractruntime-0.5.0}/docs/faq.md

@@ -118,7 +118,7 @@ If a binding includes `key`, Runtime uses it as the effective prompt-cache key a
 
 Gateway-specific prompt-cache environment variables should be consumed by Gateway and passed to Runtime explicitly; Runtime does not read the Gateway env namespace directly.
 
-Hosts can inspect, prepare, and now clean up caches through `abstractruntime.integrations.abstractcore.get_abstractcore_host_facade(runtime)`, which exposes the normal prompt-cache/model-residency controls plus durable bloc helpers such as `upsert_text_bloc(...)`, `ensure_bloc_kv_artifact(...)`, `load_bloc_kv_artifact(...)`, `list_bloc_kv_artifacts(...)`, `delete_bloc_kv_artifact(...)`, and `delete_bloc(...)` without depending on the private runtime attachment directly.
+Hosts can inspect, prepare, and clean up caches through `abstractruntime.integrations.abstractcore.get_abstractcore_host_facade(runtime)`, which exposes the normal prompt-cache/model-residency controls plus durable bloc helpers such as `upsert_text_bloc(...)`, `ensure_bloc_kv_artifact(...)`, `load_bloc_kv_artifact(...)`, `list_bloc_kv_artifacts(...)`, `delete_bloc_kv_artifact(...)`, and `delete_bloc(...)` without depending on the private runtime attachment directly.
 Docs: `integrations/abstractcore.md`. Code: `src/abstractruntime/integrations/abstractcore/host_facade.py`, `src/abstractruntime/integrations/abstractcore/llm_client.py`.
 
 ## Can a host still export or import local provider prompt caches?
@@ -286,6 +286,8 @@ If your `LedgerStore` supports subscriptions (or is wrapped with `ObservableLedg
 
 Long-running generated media uses the same ledger stream. Runtime converts provider progress callbacks into `EMIT_EVENT` ledger records named `abstract.progress` with JSON-safe payloads such as `phase`, `step`, `total_steps`, `frame`, `total_frames`, and `progress`.
 
+For the text of an answer while it is generated, register a live sink with `Runtime.set_live_delta_sink(sink)` and start the run with `_runtime.stream: True`. Live deltas never reach the ledger; see `integrations/abstractcore.md#live-token-streaming`.
+
 Docs: `architecture.md`. Code: `src/abstractruntime/core/runtime.py` (`subscribe_ledger`), `src/abstractruntime/storage/observable.py`.
 
 ## What is “evidence capture”?

{abstractruntime-0.4.35 → abstractruntime-0.5.0}/docs/getting-started.md

@@ -12,7 +12,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-This installs AbstractCore 2.15.1 or newer with remote provider, vision,
+This installs AbstractCore 2.16.0 or newer with remote provider, vision,
 voice, audio, music, tool, and MCP-worker support. The base install is
 remote-light: it can route multimodal workflows to hosted or OpenAI-compatible
 endpoints, but it does not select local inferencer stacks such as MLX, vLLM,