world-model-optimizer 0.2.0__py3-none-any.whl

wmo/core/render.py

@@ -0,0 +1,271 @@
+"""Canonical text rendering of states, actions, and steps.
+
+These are the *single* source of truth for turning the core types into prompt/embedding text. The
+retriever embeds `encode_state_action` (phi in DreamGym Eq. 4), the world-model engine and the GEPA
+optimizer both render the env prompt from the same helpers, and demos render via `render_demo`.
+
+Keeping this in `wmo.core` (which depends on nothing) lets engine, optimize, and retrieval all share
+one rendering without an import cycle — so a step embedded for retrieval and the same step shown to
+the model as a demo are described identically.
+"""
+
+from __future__ import annotations
+
+import json
+
+from wmo.core.types import Action, EnvState, JsonObject, Step
+
+
+def render_json(value: JsonObject) -> str:
+    """Stable, compact one-liner for a JSON object: sorted keys, no whitespace churn.
+
+    Sorting makes semantically equal objects render byte-identically regardless of insertion order,
+    which is what keeps cosine similarity (and cross-run prompt text) meaningful.
+    """
+    if not value:
+        return "{}"
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)
+
+
+def render_action(action: Action) -> str:
+    """One-line rendering of an action: tool call (name + args) or a free-text message."""
+    if action.kind.value == "tool_call":
+        name = action.name or "(unnamed)"
+        return f"tool_call {name}({render_json(action.arguments)})"
+    return f"message: {action.content or ''}"
+
+
+def encode_action(action: Action) -> str:
+    """Command-only retrieval key: the action itself (tool + arguments, or message) with none of the
+    `STATE:` / `ACTION kind=` scaffolding `encode_state_action` adds.
+
+    For stateless traces (empty env state) that scaffolding is constant across every step, so it
+    dominates the embedding and dilutes the part that actually varies — the command. Embedding just
+    the action concentrates the signal, which helps a semantic embedder find same-intent neighbours.
+    """
+    # Truthy checks (not `is not None`): a blank name/content contributes no retrieval signal, and
+    # an all-blank action would otherwise embed as an empty string — indistinguishable from every
+    # other blank step. Fall back to `render_action` (labelled, never empty) in that case.
+    parts: list[str] = []
+    if action.name:
+        parts.append(action.name)
+    if action.arguments:
+        parts.append(render_json(action.arguments))
+    if action.content:
+        parts.append(action.content)
+    return " ".join(parts) if parts else render_action(action)
+
+
+def encode_state_action(state: EnvState, action: Action) -> str:
+    """Render (state, action) into the text embedded for phi(s, a) and reused in prompts.
+
+    A labelled, line-oriented structured summary: env state (structured config + scratchpad
+    "database") then the action (kind, tool name, arguments, message). Empty fields are omitted so
+    equal steps render identically.
+    """
+    lines = ["STATE:", f"  structured: {render_json(state.structured)}"]
+    if state.scratchpad:
+        lines.append(f"  scratchpad: {state.scratchpad}")
+    lines.append(f"ACTION kind={action.kind.value}")
+    if action.name is not None:
+        lines.append(f"  tool: {action.name}")
+    if action.arguments:
+        lines.append(f"  arguments: {render_json(action.arguments)}")
+    if action.content is not None:
+        lines.append(f"  message: {action.content}")
+    return "\n".join(lines)
+
+
+def render_demo(step: Step, *, max_observation_chars: int | None = None) -> str:
+    """Render a retrieved past step as a (state, action) -> observation few-shot example.
+
+    `max_observation_chars`, when set, keeps only the first N characters of the observation and
+    appends a "… [+N chars]" marker. Retrieval keys on (state, action), so the *format* and salient
+    head of a past observation carry the signal; capping the tail bounds prompt growth when many or
+    large past examples are retrieved (a big `top_k` over verbose shell/log output crowds context).
+    """
+    obs = step.observation
+    content = obs.content
+    if max_observation_chars is not None and len(content) > max_observation_chars:
+        dropped = len(content) - max_observation_chars
+        content = f"{content[:max_observation_chars]}… [+{dropped} chars]"
+    return (
+        f"{encode_state_action(step.state_before, step.action)}\n"
+        f"OBSERVATION (is_error={obs.is_error}): {content}"
+    )
+
+
+def build_env_prompt(
+    base_prompt: str,
+    task: str | None,
+    state: EnvState,
+    action: Action,
+    *,
+    history: list[Step] | None = None,
+    demos: list[Step] | None = None,
+    knowledge: str | None = None,
+    reasoning: bool = False,
+    grounding: bool = False,
+    confidence: bool = False,
+    confidence_why: bool = False,
+    max_retrieved_observation_chars: int | None = None,
+) -> tuple[str, str]:
+    """Assemble the (system, user) world-model completion that predicts the next observation.
+
+    Mirrors DreamGym Eq. 4 ``M_exp(R_t | {(s_i,a_i)}, {d_j}, tau)``: the base/optimized prompt is
+    the system message; the task, current state, recent history, retrieved demos, and the incoming
+    action form the user message. This is the *single* assembly used by both the serving engine
+    (`wmo.engine.prompts`) and the GEPA optimizer, so prompts are evolved against exactly what the
+    world model serves.
+
+    `knowledge`/`reasoning`/`grounding`/`confidence` are the opt-in agentic-mode extensions; at
+    their defaults the rendering is byte-identical to the pre-knowledge shape (pinned in
+    render_test), so prebuilt models keep serving unchanged. `knowledge` (the cross-session
+    knowledge base, rendered by `wmo.engine.knowledge`) becomes an authoritative facts section;
+    `reasoning` switches the output contract to deliberate-then-answer; `grounding` offers the
+    `ground_query` escape hatch (pass it only when a live grounder will actually serve it).
+    """
+    system = base_prompt
+    demo_block = (
+        "\n\n".join(
+            render_demo(d, max_observation_chars=max_retrieved_observation_chars) for d in demos
+        )
+        if demos
+        else "(no similar past examples)"
+    )
+    history_block = (
+        "\n".join(
+            f"{encode_state_action(h.state_before, h.action)}\n"
+            f"OBSERVATION (is_error={h.observation.is_error}): {h.observation.content}"
+            for h in history
+        )
+        if history
+        else "(start of session)"
+    )
+    knowledge_block = (
+        "KNOWLEDGE BASE (canonical facts about this environment — authoritative over your priors;"
+        f" entities, rules, schemas, and state-dependent gates):\n{knowledge}\n\n"
+        if knowledge
+        else ""
+    )
+    user = (
+        f"TASK:\n{task or '(none)'}\n\n"
+        f"{knowledge_block}"
+        f"INTERACTION HISTORY:\n{history_block}\n\n"
+        f"SIMILAR PAST EXAMPLES:\n{demo_block}\n\n"
+        f"CURRENT ENV STATE:\n  structured: {render_json(state.structured)}\n"
+        f"  scratchpad: {state.scratchpad or '(empty)'}\n\n"
+        f"AGENT ACTION:\n{render_action(action)}\n\n"
+        + output_contract(
+            reasoning=reasoning,
+            grounding=grounding,
+            confidence=confidence,
+            confidence_why=confidence_why,
+        )
+    )
+    return system, user
+
+
+# The world-model output contract. Parsed by `wmo.core.parsing.parse_observation`; kept next to the
+# prompt assembly so the instruction and the parser never drift.
+OUTPUT_CONTRACT = (
+    "Respond with ONLY a JSON object describing the environment's response to this action:\n"
+    '{"output": "<exactly what the environment returns to the agent>", '
+    '"is_error": <true if the action failed/was invalid>, '
+    '"state_note": "<one short fact to remember about the new env state, or empty>"}'
+)
+
+# Reasoning-mode contract pieces. `reasoning` MUST be the first key: decoding is ordered, so
+# putting the deliberation before `output` is what makes it an actual deliberation rather than a
+# post-hoc rationalization. `kb_note` is the cross-session counterpart of `state_note` (persisted
+# to the knowledge base by the engine); `ground_query` is offered only when a grounder is active.
+# Deliberation instruction, tuned on observed live failures (.agents/docs/research/
+# agentic_results inspection):
+# unbounded deliberations blew the token budget and truncated the output (hence "1-4 short
+# sentences"); agent-side policy was mistaken for an env gate (a cancel the policy forbids still
+# EXECUTES — tools are mechanical); unobserved state was assumed ("already installed");
+# exploratory greps/finds were assumed to hit because the task narrative implied the target
+# exists; and exact computations missed edge cases (fold/wc off-by-one on a trailing newline).
+# NOTE the search guidance is deliberately evidence-NEUTRAL: a first draft said "searches miss
+# often — predict empty", derived from a corpus whose empties turned out to be capture junk
+# (D24), and it measurably hurt on the clean corpus. Bias neither way; follow the evidence.
+_REASONING_FIELD = (
+    '{"reasoning": "<1-4 short sentences BEFORE deciding the output: what would this action'
+    " really do given the current state? Check the gates the ENVIRONMENT itself enforces (auth"
+    " checks, availability, preconditions, timeouts) against the knowledge base, history, and"
+    " examples — policy the AGENT is merely supposed to follow does not make a tool refuse, so"
+    " predict refusal only where the environment demonstrably enforces it. Never assume"
+    " unobserved state (installed packages, existing files) — default to a fresh environment."
+    " Searches and reads (grep/find for guessed strings, line ranges that may exceed the file)"
+    " can genuinely miss: decide hit vs. miss from the evidence and from how similar commands"
+    " behaved in the examples, not from what the task narrative hopes is there. Work exact"
+    ' computations carefully (counts, off-by-one, trailing newlines)>", '
+)
+_OUTPUT_IS_ERROR_FIELDS = (
+    '"output": "<exactly what the environment returns to the agent>", '
+    '"is_error": <true if the action failed/was invalid>'
+)
+_STATE_NOTE_FIELD = (
+    ', "state_note": "<one short fact to remember about the new env state, or empty>"'
+)
+# Verbalized-confidence fields (WS-A6, D75). `confidence` sits AFTER output/is_error so ordered
+# decoding conditions it on the answer actually emitted (the post-hoc p(true) framing, better
+# calibrated than prospective confidence). One decimal = 11 levels: enough resolution for a
+# risk-coverage sweep, coarse enough not to invite false precision. The optional `confidence_why`
+# one-liner comes BEFORE the number (justify-then-rate) so the rating conditions on the
+# articulated reason. Stated confidence is analysis-only: the judge and GEPA never see it
+# (guarded by tests in judge_test/gepa_test).
+_CONFIDENCE_WHY_FIELD = (
+    ', "confidence_why": "<one short sentence: the strongest reason to trust or doubt the'
+    ' "output" above>"'
+)
+_CONFIDENCE_FIELD = (
+    ', "confidence": <your probability, 0.0-1.0 with ONE decimal, that the "output" above'
+    " matches what the real environment would return for this action>"
+)
+_KB_NOTE_FIELD = (
+    ', "kb_note": "<one canonical fact about this environment worth remembering across ALL'
+    ' future sessions (an entity that exists, a rule, a schema), or empty>"'
+    ', "state_update": "<the REVISED environment profile: what is running/installed/existing'
+    " right now, with beliefs this step contradicted removed — the FULL replacement profile,"
+    ' or empty to keep the previous one>"'
+)
+_GROUND_QUERY_FIELD = (
+    ', "ground_query": "<a web search query IF the action references a real-world entity (API,'
+    " package, flight, product) you cannot ground in the knowledge base, examples, or history —"
+    ' the search runs and you answer again with the results; else empty>"'
+)
+
+
+def output_contract(
+    *,
+    reasoning: bool = False,
+    grounding: bool = False,
+    confidence: bool = False,
+    confidence_why: bool = False,
+) -> str:
+    """Return the output-contract instruction for the requested mode.
+
+    The base contract (all flags off) is exactly `OUTPUT_CONTRACT` — the shape every existing
+    model was built against. All variants are parsed by the one lenient
+    `wmo.core.parsing.parse_observation`. `confidence` inserts the verbalized-confidence field
+    after `is_error`; `confidence_why` (a no-op without `confidence`) prepends its one-line
+    justification.
+    """
+    if not reasoning and not grounding and not confidence:
+        return OUTPUT_CONTRACT
+    conf_fields = ""
+    if confidence:
+        conf_fields = (_CONFIDENCE_WHY_FIELD if confidence_why else "") + _CONFIDENCE_FIELD
+    fields = f"{_OUTPUT_IS_ERROR_FIELDS}{conf_fields}{_STATE_NOTE_FIELD}"
+    ground_field = _GROUND_QUERY_FIELD if grounding else ""
+    if reasoning:
+        return (
+            "First deliberate, then answer. Respond with ONLY a JSON object whose FIRST key is"
+            f" your deliberation:\n{_REASONING_FIELD}{fields}{_KB_NOTE_FIELD}{ground_field}}}"
+        )
+    # No deliberation pass: the base fields + whichever optional fields are on.
+    return (
+        "Respond with ONLY a JSON object describing the environment's response to this action:\n"
+        f"{{{fields}{ground_field}}}"
+    )

wmo/core/text.py

@@ -0,0 +1,40 @@
+"""Text canonicalization for UTF-8 files, transports, and durable JSON stores."""
+
+from __future__ import annotations
+
+_REPLACEMENT_CHARACTER = "\N{REPLACEMENT CHARACTER}"
+
+
+def normalize_durable_text(value: str) -> str:
+    """Replace code points that cannot safely cross every WMO persistence boundary.
+
+    PostgreSQL JSONB rejects embedded NULs and lone UTF-16 surrogates; UTF-8 filesystem and HTTP
+    clients reject surrogates as well. A valid surrogate pair is folded into its Unicode scalar.
+    """
+    normalized: list[str] = []
+    index = 0
+    while index < len(value):
+        code_point = ord(value[index])
+        if code_point == 0:
+            normalized.append(_REPLACEMENT_CHARACTER)
+        elif 0xD800 <= code_point <= 0xDBFF:
+            if index + 1 < len(value) and 0xDC00 <= (low := ord(value[index + 1])) <= 0xDFFF:
+                scalar = 0x10000 + ((code_point - 0xD800) << 10) + (low - 0xDC00)
+                normalized.append(chr(scalar))
+                index += 1
+            else:
+                normalized.append(_REPLACEMENT_CHARACTER)
+        elif 0xDC00 <= code_point <= 0xDFFF:
+            normalized.append(_REPLACEMENT_CHARACTER)
+        else:
+            normalized.append(value[index])
+        index += 1
+    return "".join(normalized)
+
+
+def validate_durable_text(value: str, *, field: str) -> None:
+    """Reject content-addressed text that canonicalization would change."""
+    if "\x00" in value:
+        raise ValueError(f"{field} contains an embedded NUL character")
+    if any(0xD800 <= ord(char) <= 0xDFFF for char in value):
+        raise ValueError(f"{field} contains an unpaired UTF-16 surrogate")

wmo/core/types.py

@@ -0,0 +1,116 @@
+"""Core data types shared across the harness.
+
+These are the normalized, vendor-agnostic representations that ingestion produces and that the
+WorldModel, retriever, optimizer, and providers all operate on.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field, JsonValue
+
+# Tool arguments, env config, and span metadata are user-defined JSON. `JsonValue` is pydantic's
+# concrete recursive JSON type — honest about the shape without falling back to `Any`.
+JsonObject = dict[str, JsonValue]
+
+
+class ActionKind(StrEnum):
+    TOOL_CALL = "tool_call"
+    MESSAGE = "message"
+
+
+class Action(BaseModel):
+    """What the agent did this step. Either a tool call or a free-text message."""
+
+    kind: ActionKind
+    name: str | None = None  # tool name, when kind == tool_call
+    arguments: JsonObject = Field(default_factory=dict)
+    content: str | None = None  # message text, when kind == message
+
+
+class Observation(BaseModel):
+    """What the environment returned in response to an action.
+
+    `reward` is optional and exists to support RL-style use (DreamGym assigns r at terminal steps).
+    """
+
+    content: str
+    is_error: bool = False
+    reward: float | None = None
+    metadata: JsonObject = Field(default_factory=dict)
+
+
+class EnvState(BaseModel):
+    """A snapshot of the environment as seen by the agent.
+
+    `structured` holds machine-readable env config (cwd, open files, cart contents, ...).
+    `scratchpad` is the free-text "database" the world model writes to itself to stay consistent
+    across a session (e.g. "user created foo.txt", "logged in as alice").
+    """
+
+    structured: JsonObject = Field(default_factory=dict)
+    scratchpad: str = ""
+
+
+class ErrorClass(StrEnum):
+    """Who owns a step's failure: the model (retrainable) or the environment (not)."""
+
+    CONTROLLABLE = "controllable"  # the LLM call itself failed (refusal, bad call, provider error)
+    ENVIRONMENTAL = "environmental"  # the tool/environment failed executing a well-formed action
+
+
+class StepAttribution(BaseModel):
+    """Per-step provenance of the LLM call behind an action.
+
+    These fields are what make an ingested corpus policy-trainable: a routing optimizer clusters
+    and prices steps by which model produced them, at what token/dollar/latency cost, and whether
+    failures were the model's fault. All fields are optional; adapters populate them best-effort
+    from whatever the source recorded, and a step with nothing known carries no attribution at all.
+    """
+
+    model: str | None = None  # the serving model id (response model preferred over request)
+    provider: str | None = None  # the model provider/system (e.g. "anthropic", "openai")
+    config: JsonObject = Field(
+        default_factory=dict
+    )  # request params (temperature, max_tokens, ...)
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cost_usd: float | None = None
+    latency_ms: float | None = None
+    error_class: ErrorClass | None = None
+    provenance: str | None = None  # versioned capture-system marker, when the source carries one
+
+
+class Step(BaseModel):
+    """One (state, action) -> observation transition. The unit of retrieval and scoring."""
+
+    action: Action
+    observation: Observation
+    state_before: EnvState = Field(default_factory=EnvState)
+    task: str | None = None  # originating instruction (tau in DreamGym Eq. 4)
+    raw_span_ids: list[str] = Field(default_factory=list)
+    attribution: StepAttribution | None = None
+
+
+class Trace(BaseModel):
+    """One full agent session: an ordered list of steps, plus provenance."""
+
+    trace_id: str
+    steps: list[Step] = Field(default_factory=list)
+    source: str = "unknown"  # vendor name or file path
+    metadata: JsonObject = Field(default_factory=dict)
+
+
+class Session(BaseModel):
+    """A live interaction the WorldModel maintains while an agent steps against it."""
+
+    id: str
+    task: str | None = None
+    state: EnvState = Field(default_factory=EnvState)
+    history: list[Step] = Field(default_factory=list)  # {(s_i, a_i)} fed back into the prompt
+    # Whether this session's steps enrich the shared retrieval buffer. Serve-time default is True
+    # (DreamGym-style online enrichment). Evaluation sessions set False: a closed-loop rollout's
+    # PREDICTED steps must not become retrieval demos for later rollouts, or scores become
+    # order-dependent and self-reinforcing.
+    enrich: bool = True

wmo/distill/__init__.py

@@ -0,0 +1,14 @@
+"""On-policy distillation optimizer mode.
+
+Trains a Tinker LoRA student from rollouts harbor's own terminus-2 agent
+produces on harbor tasks (TerminalBench-2), sampling the student through
+Tinker. The teacher scores the student's sampled tokens via
+compute_logprobs, and the reverse-KL advantages feed the advantage-weighted
+loss `train.loss` names (`importance_sampling` or `ppo`).
+The public surface is deliberately minimal for now: the per-run TOML config
+model and its loader.
+"""
+
+from wmo.distill.config import DistillConfig, load_distill_config
+
+__all__ = ["DistillConfig", "load_distill_config"]

wmo/distill/agents.py

@@ -0,0 +1,140 @@
+"""Harbor agent bridge for distillation rollouts with token-span capture.
+
+Harbor instantiates `WmoDistillHarborAgent` (via
+`WMO_DISTILL_HARBOR_AGENT_IMPORT_PATH` plus JSON kwargs) for every distillation
+trial. The one behavioral difference from the base `WmoHarborAgent` is
+provider construction: the worker provider must be the Tinker student, and it
+is built with a `TokenRecorder` that writes the trial's exact sampled token
+spans to `{token_sink_dir}/{trial_name}.jsonl`.
+
+The sink lives OUTSIDE harbor's trial directory on purpose: the scorer's
+entry prune deletes invalid trial dirs wholesale before re-running them, and
+a sink inside the trial dir would vanish with it. The rollout collector keys
+the sink dir per training step and joins sinks back to trials by name.
+
+Like every module in `wmo.evals.harbor`, this module imports the harbor SDK
+at module scope and is therefore imported lazily by its consumers; `import
+wmo.distill` must succeed without the harbor extra.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Literal
+
+from harbor.models.task.config import MCPServerConfig
+
+from wmo.core.types import JsonObject
+from wmo.evals.harbor.agent import (
+    DEFAULT_EPISODE_WORKERS,
+    MAX_ENVIRONMENT_COMMAND_TIMEOUT_SEC,
+    WmoHarborAgent,
+)
+from wmo.harness.runtime import DEFAULT_EVAL_EPISODE_TIMEOUT_S
+from wmo.providers.base import Provider, ProviderConfig, ProviderKind
+from wmo.providers.retry import wrap_provider_with_retries
+from wmo.providers.tinker import TinkerChatProvider, TokenRecorder
+
+WMO_DISTILL_HARBOR_AGENT_IMPORT_PATH = "wmo.distill.agents:WmoDistillHarborAgent"
+
+
+class WmoDistillHarborAgent(WmoHarborAgent):
+    """Runs the candidate with a Tinker student provider that records token spans.
+
+    Everything else (episode execution, trace persistence, cancellation
+    semantics) is inherited from `WmoHarborAgent` unchanged.
+
+    Args:
+        token_sink_dir: Directory the per-trial span sink is written into; the
+            sink file is named `{trial_name}.jsonl` where the trial name is
+            derived from harbor's logs-dir layout (`{trial_dir}/agent`).
+    """
+
+    token_sink_path: Path
+    """The exact sink file this trial's recorder writes (set at construction)."""
+
+    def __init__(
+        self,
+        logs_dir: Path,
+        model_name: str | None = None,
+        logger: logging.Logger | None = None,
+        mcp_servers: list[MCPServerConfig] | None = None,
+        skills_dir: str | None = None,
+        *,
+        token_sink_dir: str,
+        command_timeout_sec: int = MAX_ENVIRONMENT_COMMAND_TIMEOUT_SEC,
+        extra_env: dict[str, str] | None = None,
+        harness: JsonObject,
+        provider_config: JsonObject,
+        harness_backend: Literal["local", "e2b"] = "local",
+        e2b_template: str | None = None,
+        episode_timeout_sec: float = DEFAULT_EVAL_EPISODE_TIMEOUT_S,
+        episode_workers: int = DEFAULT_EPISODE_WORKERS,
+        context_window: int | None = None,
+    ) -> None:
+        if not isinstance(token_sink_dir, str) or not token_sink_dir:
+            raise ValueError(
+                "token_sink_dir must be a nonempty path string; the distill rollout "
+                "collector passes it through the scorer's extra_agent_kwargs"
+            )
+        # Set before super().__init__: the base constructor calls _build_provider,
+        # which reads this (and the BaseAgent-assigned logs_dir).
+        self._token_sink_dir = Path(token_sink_dir)
+        super().__init__(
+            logs_dir=logs_dir,
+            model_name=model_name,
+            logger=logger,
+            mcp_servers=mcp_servers,
+            skills_dir=skills_dir,
+            command_timeout_sec=command_timeout_sec,
+            extra_env=extra_env,
+            harness=harness,
+            provider_config=provider_config,
+            harness_backend=harness_backend,
+            e2b_template=e2b_template,
+            episode_timeout_sec=episode_timeout_sec,
+            episode_workers=episode_workers,
+            context_window=context_window,
+        )
+
+    def _build_provider(self, config: ProviderConfig) -> Provider:
+        """Build the retry-wrapped Tinker student provider with this trial's span sink.
+
+        Args:
+            config: The validated worker provider config; must be the tinker kind
+                (distillation trains on the student's exact sampled tokens, which
+                only the Tinker provider records).
+
+        Returns:
+            The retry-wrapped `TinkerChatProvider`. Spans record only after a
+            completion fully succeeds, so retries never duplicate them.
+
+        Raises:
+            ValueError: If the provider kind is not tinker, or the trial name
+                cannot be derived from the logs dir.
+        """
+        if config.kind is not ProviderKind.TINKER:
+            raise ValueError(
+                "distillation rollouts must sample the Tinker student so its token "
+                f"spans can be recorded, got provider kind {config.kind.value!r}; "
+                "configure the worker provider with kind 'tinker' (or run the standard "
+                "WmoHarborAgent when no token capture is wanted)"
+            )
+        trial_name = self.logs_dir.parent.name
+        if not trial_name:
+            raise ValueError(
+                f"cannot derive the harbor trial name from logs_dir {self.logs_dir}; "
+                "the distill agent expects harbor's per-trial {trial_dir}/agent layout"
+            )
+        self._token_sink_dir.mkdir(parents=True, exist_ok=True)
+        sink_path = self._token_sink_dir / f"{trial_name}.jsonl"
+        # The recorder appends and call_index restarts at 0 per recorder; a leftover
+        # sink from a pruned earlier attempt of the same trial name would corrupt the
+        # contiguous call_index sequence load_trial_spans enforces.
+        sink_path.unlink(missing_ok=True)
+        self.token_sink_path = sink_path
+        provider = TinkerChatProvider(config, recorder=TokenRecorder(jsonl_path=sink_path))
+        # Same retry contract as the base bridge: one transient capacity error must
+        # not kill a whole trial.
+        return wrap_provider_with_retries(provider)