fred-runtime 3.5.2__tar.gz → 4.0.0__tar.gz

{fred_runtime-3.5.2 → fred_runtime-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-runtime
-Version: 3.5.2
+Version: 4.0.0
 Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -12,8 +12,8 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Operating System :: OS Independent
 Requires-Python: <3.13,>=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: fred-core>=3.8.3
-Requires-Dist: fred-sdk>=3.5.0
+Requires-Dist: fred-core>=4.0.0
+Requires-Dist: fred-sdk>=4.0.0
 Requires-Dist: alembic>=1.18.4
 Requires-Dist: deepagents>=0.6.12
 Requires-Dist: httpx>=0.28.1

{fred_runtime-3.5.2 → fred_runtime-4.0.0}/fred_runtime/app/agent_app.py

@@ -932,6 +932,7 @@ class _AgentExecuteRequest(BaseModel):
     context: dict[str, Any] | None = None
     checkpoint_id: str | None = Field(default=None, min_length=1)
     interrupt_id: str | None = Field(default=None, min_length=1)
+    occurrence_id: str | None = Field(default=None, min_length=1)
     resume_payload: Any | None = Field(
         default=None,
         description=(
@@ -956,6 +957,10 @@ class _AgentExecuteRequest(BaseModel):
             "TurnOptionsModel; the middleware receives only its own typed slice."
         ),
     )
+    # Server-derived, never caller-supplied: the occurrences already pending
+    # when this resume arrived, stamped by `_authorize_and_resolve` from the
+    # admission gate's own checkpoint read. See `_write_turn_history`.
+    previously_pending_occurrence_ids: tuple[str, ...] = ()
 
     @model_validator(mode="after")
     def _require_message_or_resume(self) -> "_AgentExecuteRequest":
@@ -1002,6 +1007,7 @@ def _to_internal_request(r: RuntimeExecuteRequest) -> "_AgentExecuteRequest":
         context=r.to_legacy_context() or None,
         checkpoint_id=r.checkpoint_id,
         interrupt_id=r.interrupt_id,
+        occurrence_id=r.occurrence_id,
         resume_payload=r.resume_payload,
         invocation_turns=r.invocation_turns,
         inline_tuning=r.inline_tuning,
@@ -1842,11 +1848,14 @@ async def _authorize_and_resolve(
                 "access_token_expires_at": None,  # nosec B105
             }
         )
-    await _validate_session_checkpoint_access(request)
+    previously_pending_occurrence_ids = await _validate_session_checkpoint_access(
+        request
+    )
     await _enforce_session_ownership(request, authenticated_user, container)
     async with runtime_stage_timer(container.get_kpi_writer(), "pod_authz"):
         await _authorize_execution_or_raise(request, authenticated_user, container)
     internal_req = _to_internal_request(request)
+    internal_req.previously_pending_occurrence_ids = previously_pending_occurrence_ids
     # Stamp the trusted service-agent verdict (never the caller-supplied
     # context) so per-tool-call re-authorization can mirror the bypass
     # `_authorize_execution_or_raise` already granted above (RFC EVAL-AUTH,
@@ -1923,19 +1932,18 @@ def _validate_resolved_team(
 _REACT_V2_INTERRUPT_CHANNEL = "__interrupt__"
 
 
-def _pending_react_v2_interrupt_ids(
+def _pending_react_v2_interrupt_occurrences(
     pending_writes: Sequence[tuple[str, str, Any]],
-) -> frozenset[str]:
+) -> frozenset[tuple[str, str | None]]:
     """
-    Extract LangGraph's own `Interrupt.id` for every currently pending
-    `"__interrupt__"` write on a ReAct V2 checkpoint (#2216).
+    Extract every pending ReAct V2 `(interrupt_id, occurrence_id)` pair.
 
     Collects ALL matching ids rather than the first one found: FRED's own
     `FredHitlMiddleware` never raises more than one interrupt per task
     (`test_hitl_resume_two_sequential_prompts_get_different_interrupt_ids`),
     but this function does not assume that — it proves the caller's
-    `interrupt_id` matches *some* currently pending occurrence, not merely
-    "a" pending write chosen arbitrarily.
+    resume identity matches the exact occurrence, not merely a pending write
+    chosen arbitrarily. Legacy payloads without an occurrence id keep `None`.
 
     Why `pending_writes` is read directly instead of going through
     LangGraph's supported `compiled_graph.aget_state(...).tasks[*].interrupts`:
@@ -1969,7 +1977,7 @@ def _pending_react_v2_interrupt_ids(
       that don't round-trip through LangGraph's own serde
     """
 
-    ids: set[str] = set()
+    occurrences: set[tuple[str, str | None]] = set()
     for _task_id, channel, value in pending_writes:
         if channel != _REACT_V2_INTERRUPT_CHANNEL:
             continue
@@ -1982,8 +1990,21 @@ def _pending_react_v2_interrupt_ids(
         if interrupt_id is None and isinstance(candidate, dict):
             interrupt_id = candidate.get("id")
         if isinstance(interrupt_id, str) and interrupt_id:
-            ids.add(interrupt_id)
-    return frozenset(ids)
+            payload = getattr(candidate, "value", None)
+            if payload is None and isinstance(candidate, dict):
+                payload = candidate.get("value")
+            occurrence_id = getattr(payload, "occurrence_id", None)
+            if occurrence_id is None and isinstance(payload, dict):
+                occurrence_id = payload.get("occurrence_id")
+            occurrences.add(
+                (
+                    interrupt_id,
+                    occurrence_id
+                    if isinstance(occurrence_id, str) and occurrence_id
+                    else None,
+                )
+            )
+    return frozenset(occurrences)
 
 
 def _resume_checkpoint_namespaces(request: RuntimeExecuteRequest) -> tuple[str, ...]:
@@ -2020,7 +2041,7 @@ def _resume_checkpoint_namespaces(request: RuntimeExecuteRequest) -> tuple[str,
 
 async def _validate_session_checkpoint_access(
     request: RuntimeExecuteRequest,
-) -> None:
+) -> tuple[str, ...]:
     """
     Validate session/checkpoint consistency for resume-capable runtime requests.
 
@@ -2047,6 +2068,11 @@ async def _validate_session_checkpoint_access(
     - this helper is intentionally conservative: it only validates local
       session/checkpoint consistency that the runtime can prove itself
 
+    Returns the occurrence ids already pending on the resumed checkpoint —
+    the pauses an earlier run has therefore already surfaced and persisted.
+    `_write_turn_history` skips their re-emission so one question keeps one
+    history row. Every non-resume path returns an empty tuple.
+
     Example:
     - `await _validate_session_checkpoint_access(request)`
 
@@ -2066,7 +2092,7 @@ async def _validate_session_checkpoint_access(
       `request.interrupt_id`, LangGraph's own `Interrupt.id` — this
       function requires it to exactly match one of the ids currently
       pending on the thread's latest checkpoint
-      (`_pending_react_v2_interrupt_ids`) — a stale response for an earlier
+      (`_pending_react_v2_interrupt_occurrences`) — a stale response for an earlier
       interrupt must never be accepted for a later one (#2216 P1).
       `react_message_codec.py` threads the same id into LangGraph's own
       targeted `Command(resume={id: ...})` form as defense in depth, so the
@@ -2080,7 +2106,7 @@ async def _validate_session_checkpoint_access(
         or request.resume_payload is not None
     )
     if not needs_checkpoint_validation:
-        return
+        return ()
 
     session_id = request.effective_session_id()
     if not session_id:
@@ -2092,7 +2118,7 @@ async def _validate_session_checkpoint_access(
 
     checkpointer = get_runtime_context().config.checkpointer
     if checkpointer is None:
-        return
+        return ()
 
     loaded = None
     for checkpoint_ns in _resume_checkpoint_namespaces(request):
@@ -2142,7 +2168,7 @@ async def _validate_session_checkpoint_access(
         )
 
     if request.resume_payload is None:
-        return
+        return ()
 
     if channel_values.get("runtime_kind") == "graph_v2":
         if channel_values.get("pending") is not True:
@@ -2161,7 +2187,7 @@ async def _validate_session_checkpoint_access(
                 status_code=status.HTTP_409_CONFLICT,
                 detail="checkpoint_id does not match the pending checkpoint for this session.",
             )
-        return
+        return ()
 
     # Not the legacy Graph runtime (ReAct V2, or the fallback lookup landed on
     # some other non-graph_v2 checkpoint kind). #2216 P1: a checkpoint being
@@ -2169,20 +2195,33 @@ async def _validate_session_checkpoint_access(
     # an EARLIER interrupt on this same thread must never be allowed to
     # resume a LATER one. `request.interrupt_id` must exactly match one of
     # the ids currently pending on this checkpoint.
-    pending_interrupt_ids = _pending_react_v2_interrupt_ids(pending_writes)
-    if not pending_interrupt_ids:
+    pending_occurrences = _pending_react_v2_interrupt_occurrences(pending_writes)
+    if not pending_occurrences:
         raise HTTPException(
             status_code=status.HTTP_409_CONFLICT,
             detail="checkpoint is not waiting for resume.",
         )
-    if (
-        request.interrupt_id is None
-        or request.interrupt_id not in pending_interrupt_ids
-    ):
+    matching_occurrence_ids = {
+        occurrence_id
+        for interrupt_id, occurrence_id in pending_occurrences
+        if interrupt_id == request.interrupt_id
+    }
+    if not matching_occurrence_ids:
         raise HTTPException(
             status_code=status.HTTP_409_CONFLICT,
             detail="interrupt_id does not match the pending HITL request for this session.",
         )
+    if request.occurrence_id not in matching_occurrence_ids:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="occurrence_id does not match the pending HITL request for this session.",
+        )
+
+    return tuple(
+        occurrence_id
+        for _, occurrence_id in pending_occurrences
+        if occurrence_id is not None
+    )
 
 
 @dataclass
@@ -2217,6 +2256,8 @@ async def _write_turn_history(
     agent_instance_id: str | None = None,
     exchange_id: str | None = None,
     resume_payload: Any | None = None,
+    occurrence_id: str | None = None,
+    previously_pending_occurrence_ids: tuple[str, ...] = (),
 ) -> None:
     """
     Persist one agent turn to the history store.
@@ -2236,6 +2277,9 @@ async def _write_turn_history(
     - ``payloads`` is the list of ``dict`` produced by ``_iterate_runtime_event_payloads``
     - ``resume_payload`` is set for HITL resume turns; the user's choice is stored
       as a ``Channel.hitl_response`` row instead of a plain user text row
+    - ``previously_pending_occurrence_ids`` comes from the admission gate
+      (`_validate_session_checkpoint_access`): a resumed run re-raises every
+      sibling pause still waiting, and re-emitting one is not a new question
     - silently no-ops when ``session_id`` or ``history_store`` is absent
 
     Event-to-message mapping:
@@ -2279,16 +2323,33 @@ async def _write_turn_history(
 
     # 1. Opening row: user text on normal turns, HITL response on resume turns.
     if resume_payload is not None:
-        # Extract choice_id from whatever shape the resume payload takes.
+        choice_id: str | None = None
+        text: str | None = None
         if isinstance(resume_payload, dict):
-            choice_id = str(resume_payload.get("choice_id") or "")
+            raw_choice_id = resume_payload.get("choice_id")
+            if isinstance(raw_choice_id, str) and raw_choice_id:
+                choice_id = raw_choice_id
+            raw_text = resume_payload.get("text")
+            if isinstance(raw_text, str) and raw_text:
+                text = raw_text
+            elif choice_id is None:
+                raw_answer = resume_payload.get("answer")
+                if isinstance(raw_answer, str) and raw_answer:
+                    text = raw_answer
         elif isinstance(resume_payload, str):
             choice_id = resume_payload
         else:
             choice_id = str(resume_payload)
-        if choice_id:
+        if choice_id or text:
             messages.append(
-                make_hitl_response(session_id, exchange_id, rank, choice_id=choice_id)
+                make_hitl_response(
+                    session_id,
+                    exchange_id,
+                    rank,
+                    choice_id=choice_id,
+                    text=text,
+                    occurrence_id=occurrence_id,
+                )
             )
             rank += 1
     elif request_message:
@@ -2432,6 +2493,15 @@ async def _write_turn_history(
             # AND a reload while the gate is still open can reconstruct a
             # working (not just readable) prompt.
             req = payload.get("request", {})
+            # A resumed run re-raises the siblings still waiting, so the same
+            # pause is emitted again. One question keeps one row: the run that
+            # first surfaced it already wrote it.
+            surfaced_occurrence_id = req.get("occurrence_id")
+            if (
+                surfaced_occurrence_id
+                and surfaced_occurrence_id in previously_pending_occurrence_ids
+            ):
+                continue
             question = req.get("question") or req.get("title") or "HITL pause"
             raw_choices = req.get("choices") or []
             raw_pending_calls = req.get("pending_calls") or []
@@ -2453,6 +2523,7 @@ async def _write_turn_history(
                     title=req.get("title"),
                     free_text=bool(req.get("free_text")),
                     interrupt_id=req.get("interrupt_id"),
+                    occurrence_id=req.get("occurrence_id"),
                     checkpoint_id=req.get("checkpoint_id"),
                     pending_calls=[
                         {
@@ -2917,6 +2988,8 @@ async def _stream(
                     agent_instance_id=request.agent_instance_id,
                     exchange_id=exchange_id,
                     resume_payload=request.resume_payload,
+                    occurrence_id=request.occurrence_id,
+                    previously_pending_occurrence_ids=request.previously_pending_occurrence_ids,
                 )
             )
 
@@ -3222,6 +3295,7 @@ class _HitlResumeClaim:
     _thread_id: str
     _checkpoint_ns: str
     _interrupt_id: str
+    _occurrence_id: str | None
     _claim_token: str
 
     async def consume(self) -> None:
@@ -3229,6 +3303,7 @@ class _HitlResumeClaim:
             thread_id=self._thread_id,
             checkpoint_ns=self._checkpoint_ns,
             interrupt_id=self._interrupt_id,
+            occurrence_id=self._occurrence_id,
             claim_token=self._claim_token,
         )
 
@@ -3238,6 +3313,7 @@ async def _claim_hitl_resume_before_invocation(
     session_id: str | None,
     checkpoint_ns: str,
     interrupt_id: str,
+    occurrence_id: str | None = None,
 ) -> _HitlResumeClaim | None:
     """
     Acquire and confirm the durable single-use HITL resume claim,
@@ -3296,7 +3372,10 @@ async def _claim_hitl_resume_before_invocation(
         )
         return None
     claim_token = await checkpointer.aclaim_hitl_resume(
-        thread_id=session_id, checkpoint_ns=checkpoint_ns, interrupt_id=interrupt_id
+        thread_id=session_id,
+        checkpoint_ns=checkpoint_ns,
+        interrupt_id=interrupt_id,
+        occurrence_id=occurrence_id,
     )
     if claim_token is None:
         raise RuntimeError("This HITL request is already being resumed.")
@@ -3305,6 +3384,7 @@ async def _claim_hitl_resume_before_invocation(
             thread_id=session_id,
             checkpoint_ns=checkpoint_ns,
             interrupt_id=interrupt_id,
+            occurrence_id=occurrence_id,
             claim_token=claim_token,
         )
     except Exception:
@@ -3317,6 +3397,7 @@ async def _claim_hitl_resume_before_invocation(
             thread_id=session_id,
             checkpoint_ns=checkpoint_ns,
             interrupt_id=interrupt_id,
+            occurrence_id=occurrence_id,
             claim_token=claim_token,
         )
         raise
@@ -3330,6 +3411,7 @@ async def _claim_hitl_resume_before_invocation(
             thread_id=session_id,
             checkpoint_ns=checkpoint_ns,
             interrupt_id=interrupt_id,
+            occurrence_id=occurrence_id,
             claim_token=claim_token,
         )
         raise RuntimeError(
@@ -3341,6 +3423,7 @@ async def _claim_hitl_resume_before_invocation(
         _thread_id=session_id,
         _checkpoint_ns=checkpoint_ns,
         _interrupt_id=interrupt_id,
+        _occurrence_id=occurrence_id,
         _claim_token=claim_token,
     )
 
@@ -3405,6 +3488,7 @@ async def _iterate_runtime_event_payloads(
     )
     resolved_checkpoint_id = request.checkpoint_id or ctx.get("checkpoint_id")
     resolved_interrupt_id = request.interrupt_id or ctx.get("interrupt_id")
+    resolved_occurrence_id = request.occurrence_id or ctx.get("occurrence_id")
 
     portable_context = PortableContext(
         request_id=request_id,
@@ -3425,6 +3509,7 @@ async def _iterate_runtime_event_payloads(
                 "template_agent_id": definition.agent_id,
                 "checkpoint_id": resolved_checkpoint_id,
                 "interrupt_id": resolved_interrupt_id,
+                "occurrence_id": resolved_occurrence_id,
                 "execution_action": execution_action,
                 "exchange_id": exchange_id,
                 "is_service_agent": ctx.get("is_service_agent"),
@@ -3663,6 +3748,7 @@ async def _iterate_runtime_event_payloads(
                     # regardless of runtime configuration.
                     checkpoint_ns="",
                     interrupt_id=request.interrupt_id,
+                    occurrence_id=request.occurrence_id,
                 )
 
             async for event in executor.stream(react_input, execution_config):
@@ -4738,6 +4824,8 @@ def _build_agent_router(
                     agent_instance_id=request.agent_instance_id,
                     exchange_id=exchange_id,
                     resume_payload=request.resume_payload,
+                    occurrence_id=request.occurrence_id,
+                    previously_pending_occurrence_ids=internal_req.previously_pending_occurrence_ids,
                 )
         return _terminal_execute_payload(payloads)
 
@@ -4825,6 +4913,8 @@ def _build_agent_router(
                     agent_instance_id=request.agent_instance_id,
                     exchange_id=exchange_id,
                     resume_payload=request.resume_payload,
+                    occurrence_id=request.occurrence_id,
+                    previously_pending_occurrence_ids=internal_req.previously_pending_occurrence_ids,
                 )
         return _build_eval_trace(
             payloads=payloads,
@@ -5030,7 +5120,7 @@ def create_agent_app(
         # 10. start_kpi_tasks  — asyncio tasks, after SQL engine is known
         # 11. set_runtime_context — wires all built parts into the global config
         log_setup(
-            service_name=config.app.name,
+            service_name=config.app.runtime_id,
             log_level=config.app.log_level,
             store=build_log_store(
                 log_store_config=config.storage.log_store,
@@ -5078,7 +5168,7 @@ def create_agent_app(
             FredRuntimeContext(
                 RuntimeConfig(
                     knowledge_flow_url=config.ai.knowledge_flow_url,
-                    service_name=config.app.name,
+                    service_name=config.app.runtime_id,
                     timeouts=config.ai.timeout,
                     chat_model_factory=chat_factory,
                     checkpointer=checkpointer,

{fred_runtime-3.5.2 → fred_runtime-4.0.0}/fred_runtime/app/config.py

@@ -89,23 +89,36 @@ from ..runtime_context import RuntimeTimeouts
 
 class PodAppConfig(BaseModel):
     """
-    Basic HTTP server and local observability settings for an agent pod.
+    Identity and HTTP server settings for an agent pod.
 
     Why this exists:
-    - every pod needs the same HTTP binding knobs plus the small Prometheus/KPI
-      settings already used by the other Fred backends
+    - every pod needs the same identity and HTTP binding knobs, in the same
+      place, whoever built it
     - keeping these fields in `app` preserves the familiar startup contract for
       local benches and scrape-based debugging
 
     How to use it:
-    - keep the defaults for simple local development
-    - set `metrics_port` / `metrics_address` when `observability.metrics` is
-      `prometheus`
+    - declare `runtime_id`; every other field defaults sanely for local work
+    - the metrics exporter is configured under `observability.kpi.prometheus`,
+      not here
 
     Example:
-    - `PodAppConfig(base_url="/pod/v1", port=8000, metrics_port=9115)`
+    - `PodAppConfig(runtime_id="my-agents", base_url="/pod/v1", port=8000)`
     """
 
+    runtime_id: str = Field(
+        ...,
+        pattern=r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+        description=(
+            "Slug identifying this pod across every telemetry stream: the KPI "
+            "`service` dimension, the `runtime_id` KPI dimension, and the "
+            "`service` field of every log record. MUST equal the id the "
+            "control-plane registers this pod under in "
+            "`runtime_catalog_sources[].runtime_id` — that equality is what "
+            "lets a log line be joined to its own KPI. Lowercase slug only, so "
+            "no display prose can reach a Prometheus label."
+        ),
+    )
     name: str = "Fred Agent Pod"
     base_url: str = "/api/v1"
     host: str = "127.0.0.1"
@@ -369,7 +382,9 @@ class AgentPodConfig(BaseModel):
     _mcp_configuration: McpConfigurationLike | None = PrivateAttr(default=None)
     _platform_prompt_file: Any | None = PrivateAttr(default=None)
 
-    app: PodAppConfig = Field(default_factory=PodAppConfig)
+    # Required, unlike every other section: `app.runtime_id` has no default, so
+    # an omitted `app:` block would leave the pod unable to name itself.
+    app: PodAppConfig
     security: SecurityConfiguration
     ai: PodAIConfig = Field(default_factory=PodAIConfig)
     observability: PodObservabilityConfig = Field(

{fred_runtime-3.5.2 → fred_runtime-4.0.0}/fred_runtime/app/context.py

@@ -142,7 +142,7 @@ class PodApplicationContext:
         self._kpi_writer = build_kpi_writer(
             kpi_config=config.observability.kpi,
             opensearch_config=config.storage.opensearch,
-            service_name="fred-runtime",
+            service_name=config.app.runtime_id,
             log_level=config.app.log_level,
         )
 

{fred_runtime-3.5.2 → fred_runtime-4.0.0}/fred_runtime/capabilities/document_read_common.py

@@ -196,7 +196,9 @@ def _pagination_footer(result: DocumentMarkdownResult, *, exhaustive: bool) -> s
                 f"the end is reached.]"
             )
         return (
-            f"\n\n[{seen}. More text remains — call again with "
+            f"\n\n[More text remains — {seen} read. You have NOT seen the "
+            f"whole document yet; do not present this page as the complete "
+            f"document. You may call this tool again with "
             f"offset={result.next_offset} to continue reading.]"
         )
     if result.offset == 0 and result.total_chars == 0:

{fred_runtime-3.5.2 → fred_runtime-4.0.0}/fred_runtime/capabilities/mcp.py

@@ -283,6 +283,11 @@ def build_mcp_capability(server: MCPServerConfiguration) -> McpCapability:
     manifest = CapabilityManifest(
         id=server.id,
         version=MCP_CAPABILITY_SCHEMA_VERSION,
+        # An MCP server has no version of its own: the constant above is the
+        # stored-config schema version, and every other capability declares a
+        # real semver here. Surfacing the schema constant made every MCP row
+        # read "v1" in the admin catalog, which looked like information.
+        public_version=None,
         name=server.name,
         description=server.description or server.name,
         icon=_MCP_CAPABILITY_ICON,

{fred_runtime-3.5.2 → fred_runtime-4.0.0}/fred_runtime/cli/history_display.py

@@ -327,6 +327,7 @@ def run_single_turn(
     color_enabled: bool,
     checkpoint_id: str | None = None,
     interrupt_id: str | None = None,
+    occurrence_id: str | None = None,
     resume_payload: Any = None,
     inline_tuning: dict[str, Any] | None = None,
 ) -> tuple[int, dict[str, Any] | None]:
@@ -336,12 +337,12 @@ def run_single_turn(
     Returns (exit_code, hitl_request) where hitl_request is set when the agent
     is paused at a HITL gate, or None when the turn completed normally.
 
-    checkpoint_id / interrupt_id (#2216):
+    checkpoint_id / interrupt_id / occurrence_id:
     - forwarded verbatim to the pod, never aliased for each other — the
       legacy Graph V2 runtime resumes via checkpoint_id, ReAct V2 resumes
-      via interrupt_id (LangGraph's own `Interrupt.id`). The caller extracts
-      whichever one the pending `AwaitingHumanRuntimeEvent.request` actually
-      carries; only one is ever set per resume.
+      via interrupt_id (LangGraph's own `Interrupt.id`). Tool-raised pauses
+      additionally carry occurrence_id. The caller echoes the identifiers
+      present on the pending `AwaitingHumanRuntimeEvent.request` verbatim.
     """
     if not stream:
         payload = client.execute(
@@ -352,6 +353,7 @@ def run_single_turn(
             team_id=team_id,
             checkpoint_id=checkpoint_id,
             interrupt_id=interrupt_id,
+            occurrence_id=occurrence_id,
             resume_payload=resume_payload,
             inline_tuning=inline_tuning,
         )
@@ -390,6 +392,7 @@ def run_single_turn(
         team_id=team_id,
         checkpoint_id=checkpoint_id,
         interrupt_id=interrupt_id,
+        occurrence_id=occurrence_id,
         resume_payload=resume_payload,
         inline_tuning=inline_tuning,
     ):
@@ -422,7 +425,8 @@ def run_single_turn(
 def build_hitl_resume_payload(
     *,
     raw_response: str,
-    choices: list[dict[str, Any]] | tuple[dict[str, Any], ...],
+    choices: list[dict[str, Any]] | tuple[dict[str, Any], ...] = (),
+    free_text: bool = False,
 ) -> Any:
     """
     Convert one terminal HITL answer into the runtime resume payload shape.
@@ -431,7 +435,12 @@ def build_hitl_resume_payload(
     - the interactive shell accepts either a 1-based menu index or a raw
       choice id, but graph `choice_step(...)` expects a structured
       `{"choice_id": ...}` resume payload
+    - a typed answer must travel as `{"answer": ...}`, the same field the web
+      client sends: a bare string is stored as the chosen `choice_id`, which
+      is exactly the audit shape the response contract dropped
     """
+    if free_text:
+        return {"answer": raw_response}
     selected_choice_id = raw_response
     if raw_response.isdigit():
         idx = int(raw_response) - 1

{fred_runtime-3.5.2 → fred_runtime-4.0.0}/fred_runtime/cli/pod_client.py

@@ -93,6 +93,7 @@ class AgentPodClient:
         agent_instance_id: str | None = None,
         checkpoint_id: str | None = None,
         interrupt_id: str | None = None,
+        occurrence_id: str | None = None,
         resume_payload: Any = None,
         inline_tuning: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
@@ -111,6 +112,8 @@ class AgentPodClient:
             payload["checkpoint_id"] = checkpoint_id
         if interrupt_id is not None:
             payload["interrupt_id"] = interrupt_id
+        if occurrence_id is not None:
+            payload["occurrence_id"] = occurrence_id
         if resume_payload is not None:
             payload["resume_payload"] = resume_payload
         if inline_tuning:
@@ -172,6 +175,7 @@ class AgentPodClient:
         agent_instance_id: str | None = None,
         checkpoint_id: str | None = None,
         interrupt_id: str | None = None,
+        occurrence_id: str | None = None,
         resume_payload: Any = None,
         inline_tuning: dict[str, Any] | None = None,
     ) -> list[dict[str, Any]]:
@@ -185,6 +189,7 @@ class AgentPodClient:
             agent_instance_id=agent_instance_id,
             checkpoint_id=checkpoint_id,
             interrupt_id=interrupt_id,
+            occurrence_id=occurrence_id,
             resume_payload=resume_payload,
             inline_tuning=inline_tuning,
         ):
@@ -202,6 +207,7 @@ class AgentPodClient:
         agent_instance_id: str | None = None,
         checkpoint_id: str | None = None,
         interrupt_id: str | None = None,
+        occurrence_id: str | None = None,
         resume_payload: Any = None,
         inline_tuning: dict[str, Any] | None = None,
     ) -> Iterator[dict[str, Any]]:
@@ -220,6 +226,8 @@ class AgentPodClient:
             payload["checkpoint_id"] = checkpoint_id
         if interrupt_id is not None:
             payload["interrupt_id"] = interrupt_id
+        if occurrence_id is not None:
+            payload["occurrence_id"] = occurrence_id
         if resume_payload is not None:
             payload["resume_payload"] = resume_payload
         if inline_tuning: