AbstractRuntime 0.4.29__tar.gz → 0.4.32__tar.gz

{abstractruntime-0.4.29 → abstractruntime-0.4.32}/.gitignore

@@ -87,3 +87,25 @@ venv.bak/
 ```
 
 .DS_Store
+
+# Agent session artifacts
+.cursor/
+
+# ---------------------------------------------------------------------------
+# Agent harness and local tooling
+#
+# This repository is worked on with coding agents, and their configuration
+# embeds absolute local paths, hook commands, seat identities and empty API-key
+# slots. None of it belongs in a public repository.
+# ---------------------------------------------------------------------------
+.claude/
+.codex/
+.cursor/
+.agora/
+.abstractcode/
+.mcp.json
+CLAUDE.md
+/AGENTS.md
+abstractcode-export-*.md
+untracked/
+.venv/

{abstractruntime-0.4.29 → abstractruntime-0.4.32}/CHANGELOG.md

@@ -7,6 +7,216 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.32] - 2026-09-23
+
+This release also contains everything listed under 0.4.31, which was never
+published on its own.
+
+### Added
+- **Stop reaches the running effect.** `Runtime.cancel_run(...)` now signals the
+  effect that is executing for the run (and for its in-flight descendants), not
+  only the stored status. The `LLM_CALL` handler passes the signal to
+  AbstractCore as `cancel_event=`, so a local provider stops within one token,
+  and the remote client closes its request to the AbstractCore server, which
+  treats the disconnect as a cancel. The stopped attempt is recorded as
+  `cancelled` (new `StepStatus.CANCELLED`, `EffectOutcome.cancelled`) with
+  `cancelled_by`, `reason` and timing fields, is never retried, and nothing
+  after it runs. Remaining calls of a tool batch are reported as not started.
+  `cancel_run(..., cancelled_by=...)` is a new keyword (default `"api"`).
+- `core/effect_cancellation.py`: `inflight_effects()` lists executing effects;
+  `request_model_effects_cancel(provider, model)` stops the effects using a
+  model; `kill_inflight_effect(step_id, killed_by=...)` is an in-process hard
+  stop for a call that ignores its cancel event.
+- **Model eject stops its calls first.** Local `unload_model_residency`
+  cancels the effects using the unloaded model before unloading it, and the
+  ledger records `cancelled_by: "model_eject"` with the model named.
+- **Speculation (MTP) controls.** `LLM_CALL.params.speculation` (`False`,
+  `True`, or a Core speculation object) and boolean or string `thinking` are
+  forwarded by local and remote clients. `_runtime.speculation` sets a
+  run-wide preference inherited by subworkflows, Agent loops, delegated
+  children and structured-output follow-up calls; an explicit `False` stays
+  Off across every boundary. VisualFlow LLM Call and Agent nodes accept a
+  `speculation` input. Scoped AbstractCore defaults reach provider
+  construction, and `config_facade.normalize_speculation_control()` validates
+  host values with Core's vocabulary.
+- **Native MLX execution controls.** Local clients admit concurrent calls only
+  when the loaded MLX instance advertises safe scheduling; other instances
+  stay serialized through streamed completion. Remote results expose Core's
+  `execution`, `speculation`, `performance` and `prompt_cache` metadata.
+  New `get_execution_capabilities(model_name=None, provider=None)` on the
+  clients and the discovery facade asks the actual execution host without
+  loading a model.
+- **Text phase progress.** Every `LLM_CALL` is offered the durable progress
+  channel. Providers that report prefill/generation phases produce
+  `abstract.progress` ledger events with `kind: "llm"` (`phase`,
+  `prompt_tokens`, `cached_tokens`, `fed_tokens`, `generated_tokens`,
+  `ttft_s`, `tokens_per_second`). The callback travels beside the effect
+  (`core/progress_channel.py`), so `effect.payload` stays JSON-serializable.
+- **Run-tree tool ceiling.** An explicit `allowed_tools` list in `_runtime`, in
+  a child run, or in a tool payload is intersected across the run tree
+  (`core/tool_scope.py`). Approval policy can remove a prompt but never grant
+  a tool outside the ceiling; malformed lists and broken ancestry fail closed.
+- `Runtime.tick(..., step_gate=callable)` lets a host pause a run at the next
+  step boundary; the run stays `RUNNING` and a later tick continues.
+- `Runtime.set_default_provider_model(...)` and the pooled client's
+  `set_default_provider_model(...)` / `set_capability_defaults(...)` re-point
+  the default provider/model without a restart.
+- `abstractruntime.turn_grounding`: `stamp_user_turn_grounding()` writes the
+  grounding envelope once into the stored user turn, so each turn's prompt is
+  a byte prefix of the next one and provider prompt caches survive across
+  turns. Session replay returns the stored bytes.
+- `JsonFileRunStore.list_event_waiters(...)` / `list_event_waiters_by_prefix(...)`
+  (optional `EventWaiterQueryableRunStore` protocol, also forwarded by
+  `OffloadingRunStore`). `emit_event` uses this index instead of scanning
+  every run file.
+- The model receives a description of its workspace scope (default directory,
+  access mode, extra roots and exclusions), and out-of-scope path errors list
+  the authorized roots.
+- VisualFlow: inline pin expressions (`node.data.pinExpressions`, sandboxed
+  with RestrictedPython), `continueOnError` on effect nodes, a `write_chart`
+  node, a `write_docx` node, image embedding and branded exports in PDF/DOCX
+  renderers, and `shq` / `text_of` sandbox helpers.
+- `abstractruntime.__version__`.
+- The configured reasoning effort on AbstractCore's text capability route is
+  applied when a call names no `thinking`.
+- `config_facade.read_email_settings()` and `read_maintenance_settings()`.
+- LLM results carry `route` (the provider, model and `base_url` that actually
+  served the call, with a `mismatch` flag).
+- In-process `on_token` streaming callbacks (`set_on_token`) on local and
+  pooled clients; `read_idle_timeout_s` for LLM calls.
+- `WAIT_EVENT` accepts a deadline; `_runtime.wait_until_streak` counts
+  consecutive `WAIT_UNTIL` parks.
+- `RuntimeHealth` counters, bounded run-vars growth for long-running runs,
+  an indexed idempotency lookup, fair scheduling across several run stores
+  (`scheduler/multi_store.py`), a steer sidecar store, and durable session
+  conversation replay.
+- `history_bundle`: a `detail="replay"` profile and in-band `warnings[]` when a
+  bundle cannot be complete.
+- Entity runtime (`abstractruntime.identity`): the per-entity home runtime,
+  chat driver, visit workflow, life loop, diary and memory effects
+  (`MEMORY_CONSOLIDATE`, `MEMORY_PROBE`, `MEMORY_TEND`, `LIFE_QUERY`,
+  `ENTITY_TOOLS_QUERY`, `ENTITY_TOOLS_EXECUTE`), phase graph and entity tools.
+  See `docs/entity-runtime.md`.
+- Tool surfaces: `browser_probe` in the `web` toolset (asks for approval by
+  default), a camera toolset registered when `abstractcamera` is installed,
+  a `git_read_only@v1` approval refiner, and agora hub tools.
+
+### Changed
+- Dependency floors: `abstractcore[remote,tools,vision,voice,audio,music]>=2.13.41`,
+  `abstractcore[all-apple]>=2.13.41` (`apple` extra),
+  `abstractcore[all-gpu]>=2.13.41` (`gpu` extra), `AbstractMemory>=0.3.0`,
+  `abstractsemantics>=0.0.5`. `RestrictedPython>=7.0` and `pyyaml>=6.0` are
+  declared dependencies.
+- The `gpu` extra's setuptools floor is `>=77.0.3` (was `>=80.10.2`), which
+  vLLM's `setuptools<80` requirement can satisfy.
+- Migration: with RestrictedPython installed, VisualFlow Code nodes always run
+  under its policy. Augmented assignment on subscripts (`d["k"] += 1`) is
+  refused; rewrite it as read, modify, write.
+- The default iteration budget (`RuntimeConfig.max_iterations` and the
+  Agent-node fallback) is 20. Workflow-declared values still win.
+- LLM calls default to `read_idle_timeout_s=300`: a stream that delivers
+  nothing for 5 minutes is aborted. Pass `read_idle_timeout_s: None` in
+  `llm_kwargs` to disable it.
+- Tool approval waits use a unique, replay-stable key per approval
+  (`tool_approval:{run_id}:{node_id}:{effect_identity}`). Runs already
+  waiting on an older key can still be approved.
+- A connected VisualFlow node of an unknown type fails compilation with
+  `UnknownNodeTypeError` instead of running as a no-op.
+- Terminal ledger records are slimmer, the offloading ledger store is used by
+  the durable factories, and hot-path store reads avoid full-document parses.
+- Deterministic LLM client errors and prompt-cache binding failures are not
+  retried.
+
+### Fixed
+- A per-call provider pin reaches the provider it names: pooled clients no
+  longer hand the default endpoint's `base_url` / `api_key` to other providers.
+- Catalog discovery works when the default text client cannot be built.
+- A fresh install with no provider configured constructs its runtime; calls
+  without a provider fail with a message naming what to configure.
+- The session prompt-cache prefix is prepared with the `thinking` value the
+  call generates with, and prompt-only calls under a runtime-derived key no
+  longer append to their own cache.
+- The remote client forwards `thinking`; streamed reasoning keeps the complete
+  final text.
+- Effect-only paths into a VisualFlow End node no longer copy runtime
+  bookkeeping into the result.
+- Visual `llm_call` nodes forward provider and model independently.
+- Native tool calls are kept by the chat driver.
+- `JsonlCommandStore.append` fsyncs before returning.
+- Run-output offload reduces the largest children first, so a small answer
+  stays inline next to a large scratchpad.
+- The JSON run store cache is LRU-bounded; hash-chained ledgers no longer fork
+  under concurrent handles.
+- Entity-lane `execute_command` kills its whole process tree on timeout.
+- PDF export renders scientific and typographic glyphs.
+
+## [0.4.31] - 2026-08-27
+
+Never published separately; these changes ship in 0.4.32.
+
+### Added
+- Host facade methods `get_memory_snapshot()`, `list_session_prompt_caches(session_id=None)`, and
+  `clear_session_prompt_caches(session_id)`. Hosts can read the Core-owned host memory snapshot
+  (RAM, process RSS, device allocation) and enumerate or clear live session prompt caches per
+  session across local, multi-local, and remote runtimes. The three methods are optional in the
+  LLM-client contract: a configured client that does not implement one still binds, and the facade
+  answers `{"ok": false, "supported": false, ...}` for that call.
+- Session attribution on derived prompt-cache keys. When Runtime injects the session-scoped
+  prompt-cache key for a text/chat `LLM_CALL`, the client stamps `session_id`, `run_id`,
+  `workflow_id`, `node_id`, and `namespace` into the cache entry's metadata after each generate —
+  locally through the provider's key-meta contract, remotely via `POST /acore/prompt_cache/key_meta`
+  (skipped for servers without the route). Caller-supplied `prompt_cache_key`s and binding keys are
+  never stamped, so clearing a session cannot destroy caches shared across sessions. Session caches
+  are not cleared automatically when a run ends; clearing stays an explicit host operation.
+- Local `list_model_residency` merges AbstractCore's host-wide loaded-model sweep into
+  text-generation listings: models resident on host-local provider servers (for example Ollama or
+  LM Studio) now appear with `source: "provider_server"` even when they were not loaded through
+  this runtime. Rows loaded by this runtime win deduplication and absorb the sweep's size fields.
+- Model-residency locks. The host facade and all execution modes expose
+  `lock_model_residency(...)`, `unlock_model_residency(...)`, and `get_context_estimate(...)`,
+  each accepting an optional payload mapping and/or keyword arguments (keyword arguments win on
+  conflicts). A locked model refuses `unload_model_residency` with a structured
+  `{"ok": false, "error": "model_locked", ...}` payload instead of an exception; `force=true`
+  unloads it, and the lock is released only after the unload succeeds. Lock requires
+  provider-verified residency: a warm client or configured default alone is configuration, not
+  memory, and locking a non-resident pair refuses with
+  `{"ok": false, "error": "model_not_resident", ...}` (load with `lock: true` instead); unlock
+  never requires residency, so a locked-but-since-evicted pair can always be released, and the
+  Ollama keep-alive restore is skipped for a non-resident model so unlock never loads it back as
+  a side effect. Local clients enforce the
+  lock per `(provider, model)` pair, reinforce it best-effort with Ollama's `keep_alive` knob
+  (reported under `provider_side`), refuse foreign runtime ids with a not-found payload, and
+  exempt locked pairs from the multi-local pool eviction when the default provider/model is
+  re-pointed (a locked pair that becomes the new default identity is rebuilt and its lock cleared,
+  with a logged warning). Remote clients relay `POST /acore/models/lock|unlock` and convert the
+  server's HTTP 409 refusals into the same structured payloads (`model_locked` on unload,
+  `model_not_resident` on lock). The three methods are
+  optional in the LLM-client contract, degrading to `{"ok": false, "supported": false, ...}` at
+  the facade; locks apply to text-generation runtimes only.
+- `MODEL_RESIDENCY` effect operations `lock` and `unlock`, with the same soft-fail semantics as
+  the existing operations; on `unload`, `force` is forwarded only when authored in the effect
+  payload.
+- `get_context_estimate(...)` relays AbstractCore's analytical context-fit estimator: in-process
+  for local clients (defaulting to the client's provider/model identity), via
+  `GET /acore/models/context_estimate` for remote clients.
+- Local text-residency rows carry AbstractCore's registry-declared `modalities` (omitted on a
+  registry miss; `input.image` is stripped with `modalities_note: "vision_unusable"` when the
+  provider reports its vision lane unusable), the serving host's identity (`host_id` /
+  `host_name`), and runtime-owned lock truth (`locked` / `lockable`); provider claims cannot
+  supply lock state. `pinned` on local rows is a truthful alias of `locked` (same value, Core
+  parity), never the default-identity flag — `default` alone marks the client's default pair, so
+  a configured capability default is no longer presented as pinned. Remote listings keep the
+  Core server's row identity and are never re-stamped
+  with the client's.
+
+### Changed
+- Residency rows normalize provider-reported `size` / `size_vram` extras to `size_bytes` /
+  `size_vram_bytes` across local and remote listings; the original fields are kept.
+- `unload_model_residency` also drops the runtime's client-side prompt-cache mirrors for the
+  unloaded model, alongside AbstractCore's clearing of the in-provider cache stores.
+- Raised the AbstractCore dependency floor to `abstractcore>=2.13.40`, the release that provides
+  the shared memory/residency utility surface and the prompt-cache `key_meta` endpoint.
+
 ## [0.4.29] - 2026-06-14
 
 ### Changed
@@ -617,7 +827,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.29...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.31...HEAD
+[0.4.31]: https://github.com/lpalbou/abstractruntime/compare/v0.4.29...v0.4.31
 [0.4.29]: https://github.com/lpalbou/abstractruntime/compare/v0.4.28...v0.4.29
 [0.4.28]: https://github.com/lpalbou/abstractruntime/compare/v0.4.27...v0.4.28
 [0.4.27]: https://github.com/lpalbou/abstractruntime/compare/v0.4.26...v0.4.27

{abstractruntime-0.4.29 → abstractruntime-0.4.32}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.4.29
+Version: 0.4.32
 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,9 +20,9 @@ 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.13.38
-Requires-Dist: abstractmemory>=0.2.6
-Requires-Dist: abstractsemantics>=0.0.3
+Requires-Dist: abstractcore[audio,music,remote,tools,vision,voice]>=2.13.41
+Requires-Dist: abstractmemory>=0.3.0
+Requires-Dist: abstractsemantics>=0.0.5
 Requires-Dist: anyio<5.0.0,>=4.12.1
 Requires-Dist: httpx<1.0.0,>=0.28.1
 Requires-Dist: openai<2.0.0,>=1.109.1
@@ -30,18 +30,20 @@ Requires-Dist: pandas<3.0.0,>=1.0.0
 Requires-Dist: pillow<13.0.0,>=10.0.0
 Requires-Dist: pypdf<7.0.0,>=6.0.0
 Requires-Dist: python-pptx<2.0.0,>=1.0.2
+Requires-Dist: pyyaml>=6.0
 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.13.38; extra == 'apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.41; 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.13.38; extra == 'gpu'
-Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.41; extra == 'gpu'
+Requires-Dist: setuptools<82.0.0,>=77.0.3; extra == 'gpu'
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown
@@ -52,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.29 • **Python:** 3.10+
+**Version:** 0.4.32 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -80,17 +82,18 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.13.38 or newer with remote provider,
+The base install includes AbstractCore 2.13.41 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
 sentence-transformer embeddings are not selected unless you choose a hardware
 profile or another package-specific local extra.
 
-VisualFlow PDF document nodes use permissive dependencies in Runtime's base
-install: `Read PDF` extracts text and metadata with `pypdf`, and `Write PDF`
-renders text or Markdown-style report content to real PDF bytes with
-`reportlab`.
+VisualFlow document nodes use permissive dependencies in Runtime's base install:
+`Read PDF` extracts text and metadata with `pypdf`, `Write PDF` renders text or
+Markdown-style report content to real PDF bytes with `reportlab`, and
+`Write DOCX` renders Markdown-style report content to Word-compatible `.docx`
+bytes with the Python standard library.
 
 Native Python hardware profiles add local inferencer stacks:
 
@@ -143,7 +146,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.26)
+## What’s included (v0.4.32)
 
 Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -151,7 +154,10 @@ Kernel (import-light):
 - durable waits/events: `WAIT_EVENT`, `WAIT_UNTIL`, `ASK_USER`, `EMIT_EVENT`
 - append-only ledger (`StepRecord`) + node traces (`vars["_runtime"]["node_traces"]`)
 - retries/idempotency hooks: `src/abstractruntime/core/policy.py`
-- runtime-aware limits (`_limits`) with a default iteration budget of 50 (`docs/limits.md`)
+- runtime-aware limits (`_limits`) with a default iteration budget of 20 (`docs/limits.md`)
+- Stop that reaches the running effect: `Runtime.cancel_run(...)` signals the in-flight model or tool call, which ends as a `cancelled` ledger record (never retried); a model unload stops the calls using that model first (`docs/api.md`)
+- host pause at step boundaries: `Runtime.tick(..., step_gate=...)`
+- run-tree tool ceiling: an explicit `allowed_tools` list can only narrow across child runs, and approval policy never widens it
 
 Durability + storage:
 - stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
@@ -165,20 +171,24 @@ Drivers + distribution:
 - VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
 - VisualFlow multi-entry execution lowering for fan-in routes and per-entry input overrides (`docs/workflow-bundles.md`)
 - VisualFlow LLM Call and Agent nodes propagate Core generation params such as
-  `thinking` through Runtime effects. Provider Models nodes can apply Core
+  `thinking` and `speculation` through Runtime effects; `_runtime.speculation`
+  sets a run-wide MTP preference that nested workflows and Agent loops inherit. Provider Models nodes can apply Core
   `capability_route` filters so run-time model discovery matches Gateway/Flow
   authoring.
 - VisualFlow image/video nodes and Runtime media helpers preserve task-specific
   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
+  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
   the schema-conformant object on `data`, so Break Object and Switch can consume
   fields without reparsing the response string.
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Runtime-owned integrations:
-- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, 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, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
 - 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
   depends on the light AbstractMemory contract; hosts choose storage backends

{abstractruntime-0.4.29 → abstractruntime-0.4.32}/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.29 • **Python:** 3.10+
+**Version:** 0.4.32 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -32,17 +32,18 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.13.38 or newer with remote provider,
+The base install includes AbstractCore 2.13.41 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
 sentence-transformer embeddings are not selected unless you choose a hardware
 profile or another package-specific local extra.
 
-VisualFlow PDF document nodes use permissive dependencies in Runtime's base
-install: `Read PDF` extracts text and metadata with `pypdf`, and `Write PDF`
-renders text or Markdown-style report content to real PDF bytes with
-`reportlab`.
+VisualFlow document nodes use permissive dependencies in Runtime's base install:
+`Read PDF` extracts text and metadata with `pypdf`, `Write PDF` renders text or
+Markdown-style report content to real PDF bytes with `reportlab`, and
+`Write DOCX` renders Markdown-style report content to Word-compatible `.docx`
+bytes with the Python standard library.
 
 Native Python hardware profiles add local inferencer stacks:
 
@@ -95,7 +96,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.26)
+## What’s included (v0.4.32)
 
 Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -103,7 +104,10 @@ Kernel (import-light):
 - durable waits/events: `WAIT_EVENT`, `WAIT_UNTIL`, `ASK_USER`, `EMIT_EVENT`
 - append-only ledger (`StepRecord`) + node traces (`vars["_runtime"]["node_traces"]`)
 - retries/idempotency hooks: `src/abstractruntime/core/policy.py`
-- runtime-aware limits (`_limits`) with a default iteration budget of 50 (`docs/limits.md`)
+- runtime-aware limits (`_limits`) with a default iteration budget of 20 (`docs/limits.md`)
+- Stop that reaches the running effect: `Runtime.cancel_run(...)` signals the in-flight model or tool call, which ends as a `cancelled` ledger record (never retried); a model unload stops the calls using that model first (`docs/api.md`)
+- host pause at step boundaries: `Runtime.tick(..., step_gate=...)`
+- run-tree tool ceiling: an explicit `allowed_tools` list can only narrow across child runs, and approval policy never widens it
 
 Durability + storage:
 - stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
@@ -117,20 +121,24 @@ Drivers + distribution:
 - VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
 - VisualFlow multi-entry execution lowering for fan-in routes and per-entry input overrides (`docs/workflow-bundles.md`)
 - VisualFlow LLM Call and Agent nodes propagate Core generation params such as
-  `thinking` through Runtime effects. Provider Models nodes can apply Core
+  `thinking` and `speculation` through Runtime effects; `_runtime.speculation`
+  sets a run-wide MTP preference that nested workflows and Agent loops inherit. Provider Models nodes can apply Core
   `capability_route` filters so run-time model discovery matches Gateway/Flow
   authoring.
 - VisualFlow image/video nodes and Runtime media helpers preserve task-specific
   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
+  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
   the schema-conformant object on `data`, so Break Object and Switch can consume
   fields without reparsing the response string.
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Runtime-owned integrations:
-- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, 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, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
 - 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
   depends on the light AbstractMemory contract; hosts choose storage backends

{abstractruntime-0.4.29 → abstractruntime-0.4.32}/docs/README.md

@@ -27,12 +27,15 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `troubleshooting.md` — symptom-oriented setup, runtime, and integration fixes
 - `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`, cached sessions, 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`, 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
+- run history bundle replay now also exports `resolved_actions` summaries for cross-client capability replay; see `api.md` and `integrations/abstractcore.md`
 - `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
-- `api.md#workflowbundles-flow-and-visualflow-distribution` — VisualFlow compiler APIs, media nodes, and PDF document nodes (`read_pdf` / `write_pdf`)
+- `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`)
 
 ## Features (reference)
 
+- `entity-runtime.md` — per-entity runtimes for summoned entities: homes, the one-writer lease, act-only diary privacy (`$act_only` refs), durable visit waits with deadlines
 - `evidence.md` — artifact-backed evidence capture for external-boundary tools
 - `mcp-worker.md` — MCP worker CLI (`abstractruntime-mcp-worker`)
 - `snapshots.md` — snapshot/bookmark model and stores

{abstractruntime-0.4.29 → abstractruntime-0.4.32}/docs/api.md

@@ -64,12 +64,24 @@ Implementation: `src/abstractruntime/core/runtime.py`.
 
 - `Runtime.start(workflow, vars=..., actor_id=..., session_id=...) -> run_id`
   - creates and persists a new `RunState`
-- `Runtime.tick(workflow, run_id, max_steps=...) -> RunState`
+- `Runtime.tick(workflow, run_id, max_steps=..., step_gate=None) -> RunState`
   - executes node handlers and effects until the run becomes `WAITING`, `COMPLETED`, `FAILED`, or `CANCELLED`
+  - optional `step_gate()` is consulted at every step boundary; when it returns `False` the tick returns the persisted state and the run stays `RUNNING` (a later tick continues where it stopped)
 - `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`
 - `Runtime.get_state(run_id) -> RunState` and `Runtime.get_ledger(run_id) -> list[dict]`
   - host-facing read APIs for checkpoints and the append-only ledger
+- `Runtime.cancel_run(run_id, reason=None, cancelled_by="api") -> RunState`
+  - 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
+
+Effect cancellation helpers (`src/abstractruntime/core/effect_cancellation.py`):
+- `inflight_effects(run_ids=None)` lists executing effects (run, step, provider, model, elapsed time)
+- `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)
+
+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`.
 
@@ -170,12 +182,14 @@ VisualFlow authoring note (media and document nodes):
   follow the shared canonical contract: `rel/path` for the main workspace root
   and `mount_alias/rel/path` for approved mounts. `read_pdf` extracts text and
   metadata from PDF paths with `pypdf`; `write_pdf` renders text or
-  Markdown-style content to real PDF bytes with `reportlab`; `list_folder_files`
-  enumerates workspace-scoped folders with family/extension filters;
+  Markdown-style content to real PDF bytes with `reportlab`; `write_docx`
+  renders Markdown-style content to real `.docx` bytes with the standard
+  library; `list_folder_files` enumerates workspace-scoped folders with
+  family/extension filters;
   `import_workspace_file` snapshots a workspace file into a durable artifact;
   `read_artifact` projects saved file content back out as text/JSON/bounded
   binary metadata; and `export_artifact` writes a durable artifact back to a
-  workspace path. PDF bytes are written to the workspace path and only
+  workspace path. PDF/DOCX bytes are written to the workspace path and only
   JSON-safe metadata/path values are stored in run state. In local Runtime-only
   runs with no workspace scope, relative file-node paths still fall back to the
   process working directory.
@@ -195,12 +209,14 @@ Implementation: `src/abstractruntime/history_bundle.py`.
 - `persist_workflow_snapshot(...)`
 
 This produces a portable record of a run’s state + ledger + artifacts suitable for debugging/review.
+When available, it also includes `resolved_actions`: bounded capability/action summaries derived
+from Core route resolution and persisted from `LLM_CALL` results.
 
 ## Runtime-owned integrations
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install abstractruntime` (AbstractCore 2.13.38 or newer is part of the base install).
+Requires: `pip install abstractruntime` (AbstractCore 2.13.41 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -214,7 +230,10 @@ Entry points:
 - effect handler wiring: `build_effect_handlers(...)` (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`)
 - tool executors: `MappingToolExecutor`, `AbstractCoreToolExecutor`, `PassthroughToolExecutor`, `ApprovalToolExecutor`, `ToolApprovalPolicy` (`src/abstractruntime/integrations/abstractcore/tool_executor.py`)
 - discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog`, `list_tts_models`, `list_stt_models`, `list_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`, `list_vision_adapters`)
-- 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`)
+- 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
+- `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
 - 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 delegate to Runtime's host-local comms facade/export layer (`list_email_accounts`, `list_emails`, `read_email`, `send_email`)
 - 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`)
@@ -222,6 +241,13 @@ Entry points:
   `count`/`n`, `seeds`, ordered `lora_adapters`, and video `flow_shift`; local
   subprocess isolation stays within the same public contract.
 
+Execution controls and cancellation:
+- `params.thinking` (bool or reasoning level) and `params.speculation` (`False`, `True`, or a Core speculation object such as `{"mode": "native_mtp", "num_draft_tokens": 2}`) are forwarded locally and remotely; `run.vars["_runtime"]["speculation"]` sets a run-wide preference inherited by subworkflows, Agent loops and delegated calls, and `False` stays Off across every boundary (see `integrations/abstractcore.md#execution-controls-and-local-concurrency`)
+- `get_abstractcore_discovery_facade(...).get_execution_capabilities(model_name=None, provider=None)` asks the actual execution host (local or remote) what it supports, without loading a model
+- the `LLM_CALL` handler hands the effect's cancel event to AbstractCore (`generate(..., cancel_event=...)`); remote clients close the request to the AbstractCore server on Stop, which the server treats as a cancel
+- every `LLM_CALL` is offered a progress callback; providers that report text phases (prefill / generate / complete) produce `abstract.progress` ledger events with `kind: "llm"`
+- `abstractruntime.turn_grounding.stamp_user_turn_grounding(messages, grounding=...)` writes the grounding envelope once into the stored user turn, so the prompt sent to the model stays a byte prefix of the next turn's prompt
+
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:
 - `prompt`, `messages`, `system_prompt`, and convenience `text`
 - `media`: a media path, artifact ref (`{"$artifact": "..."}` or `{"artifact_id": "..."}`), media dict, or list of those
@@ -243,6 +269,8 @@ Prompt cache / cached sessions:
 - `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
+- 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`)
 - 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`