AbstractRuntime 0.4.9__tar.gz → 0.4.10__tar.gz

{abstractruntime-0.4.9 → abstractruntime-0.4.10}/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.10] - 2026-05-12
+
+### Fixed
+- Generated media VisualFlow nodes now keep media model selection in the output spec and reserve LLM `provider`/`model` routing for explicit `runtime_provider`/`runtime_model` overrides.
+- Legacy `provider`/`model` pins on image, TTS, and STT media nodes remain accepted as media selector fallbacks for existing flows.
+
+### Changed
+- Minimum AbstractCore optional dependency floor is now `abstractcore>=2.13.13` so generated media and audio catalog contracts stay aligned.
+
 ## [0.4.9] - 2026-05-09
 
 ### Changed

{abstractruntime-0.4.9 → abstractruntime-0.4.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.9
+Version: 0.4.10
 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
@@ -23,23 +23,23 @@ Requires-Python: >=3.10
 Requires-Dist: abstractmemory>=0.2.6
 Requires-Dist: abstractsemantics>=0.0.3
 Provides-Extra: abstractcore
-Requires-Dist: abstractcore>=2.13.12; extra == 'abstractcore'
+Requires-Dist: abstractcore>=2.13.13; extra == 'abstractcore'
 Provides-Extra: all-apple
-Requires-Dist: abstractcore[all-apple]>=2.13.12; extra == 'all-apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.13; extra == 'all-apple'
 Provides-Extra: all-gpu
-Requires-Dist: abstractcore[all-gpu]>=2.13.12; extra == 'all-gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.13; extra == 'all-gpu'
 Provides-Extra: apple
-Requires-Dist: abstractcore[apple]>=2.13.12; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.13.13; 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.13.12; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.13.13; extra == 'gpu'
 Provides-Extra: mcp-worker
-Requires-Dist: abstractcore[tools]>=2.13.12; extra == 'mcp-worker'
+Requires-Dist: abstractcore[tools]>=2.13.13; extra == 'mcp-worker'
 Provides-Extra: multimodal
-Requires-Dist: abstractcore[audio,media,openai,vision,voice]>=2.13.12; extra == 'multimodal'
+Requires-Dist: abstractcore[audio,media,openai,vision,voice]>=2.13.13; extra == 'multimodal'
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown
@@ -50,7 +50,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.9 • **Python:** 3.10+
+**Version:** 0.4.10 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -84,7 +84,7 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
-The `abstractcore` extra installs AbstractCore 2.13.12 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool catalog, public output-selector contract, and async/sync text-generation output-selector parity are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+The `abstractcore` extra installs AbstractCore 2.13.13 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool catalog, public output-selector contract, and async/sync text-generation output-selector parity are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
 
 Hardware profile cascades are available for native Python installs:
 `abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
@@ -138,7 +138,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.9)
+## What’s included (v0.4.10)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)

{abstractruntime-0.4.9 → abstractruntime-0.4.10}/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.9 • **Python:** 3.10+
+**Version:** 0.4.10 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -38,7 +38,7 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
-The `abstractcore` extra installs AbstractCore 2.13.12 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool catalog, public output-selector contract, and async/sync text-generation output-selector parity are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+The `abstractcore` extra installs AbstractCore 2.13.13 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool catalog, public output-selector contract, and async/sync text-generation output-selector parity are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
 
 Hardware profile cascades are available for native Python installs:
 `abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
@@ -92,7 +92,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.9)
+## What’s included (v0.4.10)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)

abstractruntime-0.4.10/docs/backlog/proposed/2026-05-09_runtime_retention_and_purge_contract.md

@@ -0,0 +1,82 @@
+# Proposed: Runtime Retention And Purge Contract
+
+## Metadata
+- Created: 2026-05-09
+- Status: Proposed
+- Completed: N/A
+
+## Context
+
+AbstractRuntime is the durable graph ledger. Durability is still the default, but hosts such as
+AbstractGateway need a principled way to handle temporary/private runs created by authoring tools
+like AbstractFlow.
+
+Current Runtime reality:
+
+- `RunStore` exposes `save()` and `load()`.
+- `QueryableRunStore` exposes listing and child traversal.
+- `LedgerStore` is append-only with `append()` and `list()`.
+- `ArtifactStore` implementations already have delete helpers such as `delete_by_run()`.
+- There is no generic retention class, purge protocol, or host-neutral cleanup helper for a run tree.
+
+## Why this might matter
+
+Gateway can implement cleanup itself, but the concepts are generic:
+
+- deleting or archiving a root run and all child/subworkflow runs;
+- deleting ledgers and artifacts for a run tree;
+- preserving append-only production ledgers while allowing explicitly temporary authoring runs to
+  expire;
+- hiding private runs from default indexes.
+
+If every host invents its own cleanup behavior, run history, artifacts, and child runs can drift.
+
+## Proposed direction
+
+Add optional runtime-level retention/purge contracts:
+
+- Run metadata convention:
+  - `run.vars["_runtime"]["purpose"]`;
+  - `run.vars["_runtime"]["visibility"]`;
+  - `run.vars["_runtime"]["retention"]`;
+  - `expires_at` or `ttl_s` where appropriate.
+- Optional storage protocols:
+  - `DeletableRunStore.delete(run_id)`;
+  - `DeletableLedgerStore.delete(run_id)` or `delete_by_run(run_id)`;
+  - query helpers for expired/private/draft runs.
+- Runtime helper:
+  - collect a run tree from a root;
+  - purge or archive run checkpoints, ledgers, and artifacts;
+  - return a structured cleanup report.
+- Documentation:
+  - durability remains default;
+  - purge is allowed only for explicitly temporary/private runs unless a host chooses otherwise.
+
+## Evidence to gather before promotion
+
+- Determine whether JSON file and SQLite stores can implement deletion safely without weakening
+  provenance guarantees for production runs.
+- Decide whether "private" means hidden, encrypted, or merely excluded from default listings in v0.
+- Decide whether purge should be hard-delete or archive-to-artifact for auditability.
+- Check Gateway's needs for draft Flow tests and backlog/UAT workspaces before finalizing fields.
+
+## Validation ideas
+
+- Store contract tests for JSON, SQLite, and in-memory implementations.
+- Runtime helper tests:
+  - root + child run tree cleanup;
+  - artifact cleanup;
+  - no accidental cleanup of non-temporary runs unless explicitly forced.
+- Gateway integration tests once promoted.
+
+## Non-goals
+
+- Do not make Runtime responsible for Gateway's retention policy defaults.
+- Do not remove append-only ledger semantics for normal production runs.
+- Do not require every store backend to implement deletion immediately; keep protocols optional and
+  capability-detected.
+
+## Guidance for future agents
+
+Promote this only when Gateway starts implementing first-class draft/private run cleanup. Keep the
+boundary clean: Runtime defines reusable storage mechanics; Gateway decides policy; Flow decides UX.

{abstractruntime-0.4.9 → abstractruntime-0.4.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "AbstractRuntime"
-version = "0.4.9"
+version = "0.4.10"
 description = "AbstractRuntime: a durable graph runner designed to pair with AbstractCore."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -46,34 +46,34 @@ dependencies = [
 [project.optional-dependencies]
 # Enables `abstractruntime.integrations.abstractcore.*` imports.
 abstractcore = [
-  "abstractcore>=2.13.12",
+  "abstractcore>=2.13.13",
 ]
 
 apple = [
-  "abstractcore[apple]>=2.13.12",
+  "abstractcore[apple]>=2.13.13",
 ]
 
 gpu = [
-  "abstractcore[gpu]>=2.13.12",
+  "abstractcore[gpu]>=2.13.13",
 ]
 
 all-apple = [
-  "abstractcore[all-apple]>=2.13.12",
+  "abstractcore[all-apple]>=2.13.13",
 ]
 
 all-gpu = [
-  "abstractcore[all-gpu]>=2.13.12",
+  "abstractcore[all-gpu]>=2.13.13",
 ]
 
 # Enables AbstractCore multimodal generation helpers with common OpenAI-backed
 # image/voice capability packages.
 multimodal = [
-  "abstractcore[media,openai,vision,voice,audio]>=2.13.12",
+  "abstractcore[media,openai,vision,voice,audio]>=2.13.13",
 ]
 
 # Enables `abstractruntime-mcp-worker` with the default toolsets (includes bs4/lxml).
 mcp-worker = [
-  "abstractcore[tools]>=2.13.12",
+  "abstractcore[tools]>=2.13.13",
 ]
 
 # CI/test dependencies. The workflow runs the basic contract suite plus focused

abstractruntime-0.4.10/release-notes.md

@@ -0,0 +1,6 @@
+### Fixed
+- Generated media VisualFlow nodes now keep media model selection in the output spec and reserve LLM `provider`/`model` routing for explicit `runtime_provider`/`runtime_model` overrides.
+- Legacy `provider`/`model` pins on image, TTS, and STT media nodes remain accepted as media selector fallbacks for existing flows.
+
+### Changed
+- Minimum AbstractCore optional dependency floor is now `abstractcore>=2.13.13` so generated media and audio catalog contracts stay aligned.

{abstractruntime-0.4.9 → abstractruntime-0.4.10}/src/abstractruntime/visualflow_compiler/compiler.py

@@ -169,7 +169,7 @@ def _create_effect_node_handler(
             input_key=input_key,
             output_key=output_key,
         )
-    elif effect_type == "llm_call":
+    elif effect_type in {"llm_call", "generate_image", "generate_voice", "transcribe_audio"}:
         base_handler = create_llm_call_handler(
             node_id=node_id,
             next_node=next_node,
@@ -180,6 +180,13 @@ def _create_effect_node_handler(
             temperature=effect_config.get("temperature", 0.7),
             seed=effect_config.get("seed", -1),
         )
+    elif effect_type == "listen_voice":
+        base_handler = create_wait_event_handler(
+            node_id=node_id,
+            next_node=next_node,
+            input_key=input_key,
+            output_key=output_key,
+        )
     elif effect_type == "tool_calls":
         base_handler = create_tool_calls_handler(
             node_id=node_id,
@@ -2571,6 +2578,71 @@ def _sync_effect_results_to_node_outputs(run: Any, flow: Flow) -> None:
                 if (node_id, "ttft_ms") in referenced_source_pins:
                     current["ttft_ms"] = ttft_ms
                 mapped_value = response_text
+        elif effect_type in {"generate_image", "generate_voice"}:
+            if isinstance(raw, dict):
+                modality = "image" if effect_type == "generate_image" else "voice"
+                outputs = raw.get("outputs")
+                current["outputs"] = outputs if isinstance(outputs, dict) else {}
+                resources = raw.get("resources")
+                if isinstance(resources, dict):
+                    current["resources"] = resources
+                artifact_id, artifact_ref = _first_generated_artifact(raw)
+                if artifact_ref:
+                    current["artifact_ref"] = artifact_ref
+                    current["image_artifact" if modality == "image" else "audio_artifact"] = artifact_ref
+                    ct = artifact_ref.get("content_type")
+                    if isinstance(ct, str) and ct.strip():
+                        current["content_type"] = ct.strip()
+                if artifact_id:
+                    current["artifact_id"] = artifact_id
+                current["success"] = bool(artifact_id or artifact_ref)
+                meta = {
+                    "schema": f"abstractflow.{effect_type}.v1.meta",
+                    "version": 1,
+                    "modality": modality,
+                    "provider": raw.get("provider"),
+                    "model": raw.get("model"),
+                }
+                current["meta"] = {k: v for k, v in meta.items() if v is not None}
+                current["raw"] = raw
+                mapped_value = artifact_ref or artifact_id
+        elif effect_type == "transcribe_audio":
+            if isinstance(raw, dict):
+                text_value = ""
+                text_obj = raw.get("text")
+                if isinstance(text_obj, dict):
+                    content = text_obj.get("content")
+                    if content is not None:
+                        text_value = str(content)
+                if not text_value:
+                    content = raw.get("content")
+                    if content is not None:
+                        text_value = str(content)
+                current["text"] = text_value
+                artifact_id, artifact_ref = _first_generated_artifact(raw)
+                if artifact_ref:
+                    current["artifact_ref"] = artifact_ref
+                    current["transcript_artifact"] = artifact_ref
+                if artifact_id:
+                    current["artifact_id"] = artifact_id
+                current["success"] = True
+                current["meta"] = {"schema": "abstractflow.transcribe_audio.v1.meta", "version": 1, "modality": "text", "task": "transcription"}
+                current["raw"] = raw
+                mapped_value = text_value
+        elif effect_type == "listen_voice":
+            if isinstance(raw, dict):
+                current.update(raw)
+                audio_ref = raw.get("audio_artifact") or raw.get("artifact") or raw.get("artifact_ref")
+                if isinstance(audio_ref, dict):
+                    current["audio_artifact"] = audio_ref
+                    current["artifact_ref"] = audio_ref
+                    aid = audio_ref.get("$artifact") or audio_ref.get("artifact_id")
+                    if isinstance(aid, str) and aid.strip():
+                        current["artifact_id"] = aid.strip()
+                mapped_value = current.get("audio_artifact") or raw
+            else:
+                current["event_data"] = raw
+                mapped_value = raw
         elif effect_type == "tool_calls":
             # Effect outcome is produced by AbstractRuntime TOOL_CALLS handler:
             # - executed: {"mode":"executed","results":[{call_id,name,success,output,error}, ...]}

{abstractruntime-0.4.9 → abstractruntime-0.4.10}/src/abstractruntime/visualflow_compiler/visual/executor.py

@@ -196,6 +196,10 @@ def visual_to_flow(visual: VisualFlow) -> Flow:
         "ask_user",
         "answer_user",
         "llm_call",
+        "generate_image",
+        "generate_voice",
+        "transcribe_audio",
+        "listen_voice",
         "tool_calls",
         "call_tool",
         "wait_until",
@@ -1356,6 +1360,14 @@ def visual_to_flow(visual: VisualFlow) -> Flow:
             return _create_answer_user_handler(data, effect_config)
         if effect_type == "llm_call":
             return _create_llm_call_handler(data, effect_config)
+        if effect_type == "generate_image":
+            return _create_generate_image_handler(data, effect_config)
+        if effect_type == "generate_voice":
+            return _create_generate_voice_handler(data, effect_config)
+        if effect_type == "transcribe_audio":
+            return _create_transcribe_audio_handler(data, effect_config)
+        if effect_type == "listen_voice":
+            return _create_listen_voice_handler(data, effect_config)
         if effect_type == "tool_calls":
             return _create_tool_calls_handler(data, effect_config)
         if effect_type == "call_tool":
@@ -1513,6 +1525,207 @@ def visual_to_flow(visual: VisualFlow) -> Flow:
 
         return handler
 
+    def _nonempty_str(value: Any) -> str:
+        return value.strip() if isinstance(value, str) and value.strip() else ""
+
+    def _coerce_int(value: Any) -> Optional[int]:
+        if value is None or isinstance(value, bool):
+            return None
+        try:
+            return int(float(value))
+        except Exception:
+            return None
+
+    def _coerce_float(value: Any) -> Optional[float]:
+        if value is None or isinstance(value, bool):
+            return None
+        try:
+            out = float(value)
+        except Exception:
+            return None
+        return out if out == out else None
+
+    def _dict_input(input_data: Any) -> Dict[str, Any]:
+        return input_data if isinstance(input_data, dict) else {}
+
+    def _input_or_config(input_data: Any, config: Dict[str, Any], *keys: str, default: Any = None) -> Any:
+        payload = _dict_input(input_data)
+        for key in keys:
+            if key in payload and payload.get(key) not in (None, ""):
+                return payload.get(key)
+        for key in keys:
+            if isinstance(config, dict) and key in config and config.get(key) not in (None, ""):
+                return config.get(key)
+        return default
+
+    def _create_generate_image_handler(data: Dict[str, Any], config: Dict[str, Any]):
+        def handler(input_data: Any):
+            payload = _dict_input(input_data)
+            prompt = str(_input_or_config(payload, config, "prompt", default="") or "")
+            fmt = str(_input_or_config(payload, config, "format", "response_format", default="png") or "png").strip().lower() or "png"
+            output_spec: Dict[str, Any] = {"modality": "image", "task": "image_generation", "format": fmt}
+            for key in ("size", "negative_prompt", "quality", "style"):
+                value = _input_or_config(payload, config, key)
+                if isinstance(value, str) and value.strip():
+                    output_spec[key] = value.strip()
+            for key in ("width", "height", "seed", "steps"):
+                value = _coerce_int(_input_or_config(payload, config, key))
+                if value is not None:
+                    output_spec[key] = value
+            guidance = _coerce_float(_input_or_config(payload, config, "guidance_scale", "guidanceScale"))
+            if guidance is not None:
+                output_spec["guidance_scale"] = guidance
+            extra = _input_or_config(payload, config, "extra")
+            if isinstance(extra, dict) and extra:
+                output_spec["extra"] = dict(extra)
+            image_provider = _nonempty_str(_input_or_config(payload, config, "image_provider", "imageProvider"))
+            image_model = _nonempty_str(_input_or_config(payload, config, "image_model", "imageModel"))
+            legacy_provider = _nonempty_str(_input_or_config(payload, config, "provider"))
+            legacy_model = _nonempty_str(_input_or_config(payload, config, "model"))
+            runtime_provider = _nonempty_str(
+                _input_or_config(payload, config, "runtime_provider", "runtimeProvider", "llm_provider", "llmProvider")
+            )
+            runtime_model = _nonempty_str(
+                _input_or_config(payload, config, "runtime_model", "runtimeModel", "llm_model", "llmModel")
+            )
+            if not image_provider:
+                image_provider = legacy_provider
+            if not image_model:
+                image_model = legacy_model
+            if image_provider:
+                output_spec["provider"] = image_provider
+            if image_model:
+                output_spec["model"] = image_model
+            pending: Dict[str, Any] = {
+                "type": "llm_call",
+                "prompt": prompt,
+                "system_prompt": "",
+                "tools": [],
+                "params": {},
+                "output": output_spec,
+            }
+            if runtime_provider:
+                pending["provider"] = runtime_provider
+            if runtime_model:
+                pending["model"] = runtime_model
+            return {"image_artifact": None, "artifact_ref": None, "artifact_id": "", "success": None, "_pending_effect": pending}
+
+        return handler
+
+    def _create_generate_voice_handler(data: Dict[str, Any], config: Dict[str, Any]):
+        def handler(input_data: Any):
+            payload = _dict_input(input_data)
+            text = str(_input_or_config(payload, config, "text", "prompt", default="") or "")
+            fmt = str(_input_or_config(payload, config, "format", "response_format", default="wav") or "wav").strip().lower() or "wav"
+            output_spec: Dict[str, Any] = {"modality": "voice", "task": "tts", "format": fmt}
+            for key in ("voice", "profile", "instructions"):
+                value = _input_or_config(payload, config, key)
+                if isinstance(value, str) and value.strip():
+                    output_spec[key] = value.strip()
+            tts_provider = _nonempty_str(_input_or_config(payload, config, "tts_provider", "ttsProvider", "provider"))
+            tts_model = _nonempty_str(_input_or_config(payload, config, "tts_model", "ttsModel", "model"))
+            runtime_provider = _nonempty_str(
+                _input_or_config(payload, config, "runtime_provider", "runtimeProvider", "llm_provider", "llmProvider")
+            )
+            runtime_model = _nonempty_str(
+                _input_or_config(payload, config, "runtime_model", "runtimeModel", "llm_model", "llmModel")
+            )
+            if tts_provider:
+                output_spec["provider"] = tts_provider
+            if tts_model:
+                output_spec["model"] = tts_model
+            speed = _coerce_float(_input_or_config(payload, config, "speed"))
+            if speed is not None:
+                output_spec["speed"] = speed
+            extra = _input_or_config(payload, config, "extra")
+            if isinstance(extra, dict) and extra:
+                output_spec["extra"] = dict(extra)
+            pending: Dict[str, Any] = {
+                "type": "llm_call",
+                "prompt": text,
+                "system_prompt": "",
+                "tools": [],
+                "params": {},
+                "output": output_spec,
+            }
+            if runtime_provider:
+                pending["provider"] = runtime_provider
+            if runtime_model:
+                pending["model"] = runtime_model
+            return {"audio_artifact": None, "artifact_ref": None, "artifact_id": "", "success": None, "_pending_effect": pending}
+
+        return handler
+
+    def _create_transcribe_audio_handler(data: Dict[str, Any], config: Dict[str, Any]):
+        def handler(input_data: Any):
+            payload = _dict_input(input_data)
+            audio_ref = _input_or_config(payload, config, "audio_artifact", "artifact", "audio")
+            output_spec: Dict[str, Any] = {"modality": "text", "task": "transcription"}
+            for key in ("language", "prompt", "response_format", "format"):
+                value = _input_or_config(payload, config, key)
+                if isinstance(value, str) and value.strip():
+                    output_spec[key] = value.strip()
+            stt_provider = _nonempty_str(_input_or_config(payload, config, "stt_provider", "sttProvider", "provider"))
+            stt_model = _nonempty_str(_input_or_config(payload, config, "stt_model", "sttModel", "model"))
+            runtime_provider = _nonempty_str(
+                _input_or_config(payload, config, "runtime_provider", "runtimeProvider", "llm_provider", "llmProvider")
+            )
+            runtime_model = _nonempty_str(
+                _input_or_config(payload, config, "runtime_model", "runtimeModel", "llm_model", "llmModel")
+            )
+            if stt_provider:
+                output_spec["provider"] = stt_provider
+            if stt_model:
+                output_spec["model"] = stt_model
+            temp = _coerce_float(_input_or_config(payload, config, "temperature"))
+            if temp is not None:
+                output_spec["temperature"] = temp
+            media_item: Any = audio_ref
+            if isinstance(audio_ref, str) and audio_ref.strip() and not audio_ref.startswith(("/", "~")):
+                media_item = {"$artifact": audio_ref.strip(), "type": "audio"}
+            pending: Dict[str, Any] = {
+                "type": "llm_call",
+                "prompt": str(output_spec.get("prompt") or "Transcribe this audio."),
+                "system_prompt": "",
+                "tools": [],
+                "params": {},
+                "media": [media_item] if media_item else [],
+                "output": output_spec,
+            }
+            if runtime_provider:
+                pending["provider"] = runtime_provider
+            if runtime_model:
+                pending["model"] = runtime_model
+            return {"text": "", "transcript_artifact": None, "success": None, "_pending_effect": pending}
+
+        return handler
+
+    def _create_listen_voice_handler(data: Dict[str, Any], config: Dict[str, Any]):
+        def handler(input_data: Any):
+            payload = _dict_input(input_data)
+            prompt = str(_input_or_config(payload, config, "prompt", default="Speak now.") or "Speak now.")
+            wait_key = str(_input_or_config(payload, config, "wait_key", "event_key", default="voice_input") or "voice_input")
+            details: Dict[str, Any] = {"input_mode": "voice", "content_types": ["audio/wav", "audio/mpeg", "audio/webm"]}
+            language = _input_or_config(payload, config, "language")
+            if isinstance(language, str) and language.strip():
+                details["language"] = language.strip()
+            max_duration_s = _coerce_float(_input_or_config(payload, config, "max_duration_s", "maxDurationS"))
+            if max_duration_s is not None:
+                details["max_duration_s"] = max_duration_s
+            return {
+                "audio_artifact": None,
+                "text": "",
+                "_pending_effect": {
+                    "type": "wait_event",
+                    "wait_key": wait_key,
+                    "prompt": prompt,
+                    "allow_free_text": True,
+                    "details": details,
+                },
+            }
+
+        return handler
+
     def _create_ask_user_handler(data: Dict[str, Any], config: Dict[str, Any]):
         def handler(input_data):
             prompt = input_data.get("prompt", "Please respond:") if isinstance(input_data, dict) else str(input_data)