localcode 0.3.36__tar.gz → 0.3.37__tar.gz

{localcode-0.3.36/src/localcode.egg-info → localcode-0.3.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localcode
-Version: 0.3.36
+Version: 0.3.37
 Summary: High-performance AI coding on consumer hardware.
 Author: LocalCode contributors
 License-Expression: Apache-2.0
@@ -70,7 +70,7 @@ Dynamic: license-file
 ## Install
 
 ```bash
-pip install localcode
+pip install localcode      # or: uv pip install localcode
 ```
 
 ## Run
@@ -80,8 +80,6 @@ cd your-project
 localcode
 ```
 
-That's it. First launch builds the inference server and downloads the model (~5 min, one time). After that, startup is ~15 seconds.
-
 ## Docs
 
 Docs are published at [mjwsolo.github.io/localcode](https://mjwsolo.github.io/localcode/).
@@ -119,11 +117,15 @@ LocalCode is early software. Hardware support is expected to broaden, but only t
 
 | Mac | Memory | Status | Notes |
 | --- | ---: | --- | --- |
-| M4 MacBook | 16 GB | Tested | Primary development and validation machine |
+| M5 Apple Silicon | up to 128 GB | Tested | Primary development machine (M5 Max) |
+| M4 MacBook | 16 GB | Tested | Validated at the 16 GB floor |
 | M1/M2/M3 Apple Silicon | 16 GB+ | Not yet tested | Expected to work, but needs validation |
 | M4 Apple Silicon | 24 GB+ | Not yet tested | Expected to support larger contexts, but needs validation |
 | Intel Mac | Any | Not supported | LocalCode targets Apple Silicon |
 
+> Linux installs and runs in CI for development, but Apple Silicon is the
+> supported target — the Metal-accelerated inference path is Mac-only.
+
 ## Models
 
 On launch, LocalCode recommends the best model for **your Mac's RAM** — there's no fixed default. You can pick any of these (or a different quant) in the model picker.

{localcode-0.3.36 → localcode-0.3.37}/README.md

@@ -23,7 +23,7 @@
 ## Install
 
 ```bash
-pip install localcode
+pip install localcode      # or: uv pip install localcode
 ```
 
 ## Run
@@ -33,8 +33,6 @@ cd your-project
 localcode
 ```
 
-That's it. First launch builds the inference server and downloads the model (~5 min, one time). After that, startup is ~15 seconds.
-
 ## Docs
 
 Docs are published at [mjwsolo.github.io/localcode](https://mjwsolo.github.io/localcode/).
@@ -72,11 +70,15 @@ LocalCode is early software. Hardware support is expected to broaden, but only t
 
 | Mac | Memory | Status | Notes |
 | --- | ---: | --- | --- |
-| M4 MacBook | 16 GB | Tested | Primary development and validation machine |
+| M5 Apple Silicon | up to 128 GB | Tested | Primary development machine (M5 Max) |
+| M4 MacBook | 16 GB | Tested | Validated at the 16 GB floor |
 | M1/M2/M3 Apple Silicon | 16 GB+ | Not yet tested | Expected to work, but needs validation |
 | M4 Apple Silicon | 24 GB+ | Not yet tested | Expected to support larger contexts, but needs validation |
 | Intel Mac | Any | Not supported | LocalCode targets Apple Silicon |
 
+> Linux installs and runs in CI for development, but Apple Silicon is the
+> supported target — the Metal-accelerated inference path is Mac-only.
+
 ## Models
 
 On launch, LocalCode recommends the best model for **your Mac's RAM** — there's no fixed default. You can pick any of these (or a different quant) in the model picker.

{localcode-0.3.36 → localcode-0.3.37}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "localcode"
-version = "0.3.36"
+version = "0.3.37"
 description = "High-performance AI coding on consumer hardware."
 readme = "README.md"
 requires-python = ">=3.10"

localcode-0.3.37/src/localcode/__init__.py

@@ -0,0 +1,11 @@
+__all__ = ["__version__"]
+
+# Read the version from installed package metadata so it can never drift from
+# pyproject.toml (it was hardcoded and went ~12 releases stale). Falls back to a
+# hardcoded value only when running from a source tree that isn't installed.
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("localcode")
+except PackageNotFoundError:  # not installed (e.g. raw source checkout)
+    __version__ = "0.3.37"

{localcode-0.3.36 → localcode-0.3.37}/src/localcode/output.py

@@ -285,8 +285,11 @@ class OutputManager:
         self._stop_indicator()
         lines = result.strip().splitlines()
         if error:
+            # A tool returning an error is normal, recoverable agentic operation
+            # (the model reads it and adjusts) — render it calm amber, NOT alarm
+            # red. Red is reserved for a terminal, turn-ending failure (set_error).
             for line in lines[:5]:
-                sys.stdout.write(f"\033[31m  └ {line[:90]}\033[0m\n")
+                sys.stdout.write(f"\033[33m  └ {line[:90]}\033[0m\n")
         elif lines:
             max_lines = 8
             for i, line in enumerate(lines[:max_lines]):

localcode-0.3.37/src/localcode/protocol/__init__.py

@@ -0,0 +1,56 @@
+"""LocalCode public automation protocol.
+
+The single, versioned, dependency-light definition of the `localcode run --json`
+event stream. Both the native `eval/` harness and the Harbor plugin consume
+LocalCode through this package — neither maintains its own JSONL parser or
+failure taxonomy (integration plan §7.2.1). Standard library only, so any
+consumer can import it without pulling in LocalCode's full dependency tree.
+
+Typical use:
+
+    from localcode.protocol import parse_stream, outcome_from_parse
+
+    parsed = parse_stream(process.stdout)      # incremental, memory-bounded
+    outcome = outcome_from_parse(parsed)       # normalized RunOutcome
+    if outcome.clean_finish:                    # LocalCode's loop finished...
+        ...                                     # ...verifier still decides pass/fail
+"""
+from __future__ import annotations
+
+from .events import (
+    SCHEMA_MAJOR,
+    SCHEMA_MINOR,
+    SCHEMA_VERSION,
+    Event,
+    SchemaVersion,
+    UnsupportedSchemaError,
+)
+from .jsonl import ParseProblem, ParseResult, iter_events, parse_stream
+from .outcomes import (
+    FailureCategory,
+    RunOutcome,
+    normalize_reason,
+    outcome_from_parse,
+    redact,
+)
+
+__all__ = [
+    # schema
+    "SCHEMA_MAJOR",
+    "SCHEMA_MINOR",
+    "SCHEMA_VERSION",
+    "SchemaVersion",
+    "UnsupportedSchemaError",
+    # events + parsing
+    "Event",
+    "ParseProblem",
+    "ParseResult",
+    "parse_stream",
+    "iter_events",
+    # outcomes
+    "FailureCategory",
+    "RunOutcome",
+    "normalize_reason",
+    "outcome_from_parse",
+    "redact",
+]

localcode-0.3.37/src/localcode/protocol/events.py

@@ -0,0 +1,116 @@
+"""Typed envelope + schema versioning for the `localcode run --json` stream.
+
+This is the single public definition of a LocalCode automation event. Both the
+native `eval/` harness and the Harbor plugin consume it through
+`localcode.protocol` — neither may re-interpret the raw stream itself (see the
+integration plan, §7.2.1). Keeping the envelope here means a schema change is a
+review of one file with one compatibility policy.
+
+Compatibility policy (semantic-version style, on the SCHEMA only):
+  • MAJOR — a breaking change to the meaning/shape of existing fields. A reader
+    built for major N MUST reject major N+1 rather than guess.
+  • MINOR — purely additive: new event types or new fields on existing events.
+    Older readers ignore what they don't recognise and keep working.
+So a reader accepts a stream iff `stream.major == reader.major`, regardless of
+minor. Unknown event types and unknown fields are always preserved verbatim on
+the `Event` so a newer producer never breaks an older consumer.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "SCHEMA_MAJOR",
+    "SCHEMA_MINOR",
+    "SCHEMA_VERSION",
+    "Event",
+    "SchemaVersion",
+    "UnsupportedSchemaError",
+]
+
+# The schema version this build of LocalCode emits and reads. Bump MINOR for
+# additive changes (new event types/fields); bump MAJOR only for a breaking
+# reshape of existing fields, and only with a documented deprecation.
+SCHEMA_MAJOR = 1
+SCHEMA_MINOR = 0
+SCHEMA_VERSION = f"{SCHEMA_MAJOR}.{SCHEMA_MINOR}"
+
+
+class UnsupportedSchemaError(Exception):
+    """Raised when a stream declares a MAJOR schema this reader can't interpret.
+
+    Explicit failure, never silent misinterpretation — a major bump means the
+    meaning of existing fields changed, so guessing would produce wrong metrics.
+    """
+
+    def __init__(self, found_major: int, reader_major: int = SCHEMA_MAJOR) -> None:
+        self.found_major = found_major
+        self.reader_major = reader_major
+        super().__init__(
+            f"stream schema major {found_major} is not readable by this build "
+            f"(supports major {reader_major}); upgrade localcode or the consumer"
+        )
+
+
+@dataclass(frozen=True)
+class SchemaVersion:
+    """A parsed `MAJOR.MINOR` schema version with a readable-by check."""
+
+    major: int
+    minor: int
+
+    @classmethod
+    def parse(cls, raw: Any) -> "SchemaVersion":
+        """Parse `1`, `"1"`, or `"1.0"` into a SchemaVersion.
+
+        A bare integer/`"1"` means major 1, minor 0. Anything unparseable is
+        treated as the baseline (1.0) rather than crashing the stream — the
+        stricter major-rejection happens in `readable_by`, driven by a value we
+        could actually parse.
+        """
+        s = str(raw).strip()
+        if not s:
+            return cls(SCHEMA_MAJOR, 0)
+        parts = s.split(".")
+        try:
+            major = int(parts[0])
+            minor = int(parts[1]) if len(parts) > 1 else 0
+        except (ValueError, IndexError):
+            return cls(SCHEMA_MAJOR, 0)
+        return cls(major, minor)
+
+    def readable_by(self, reader_major: int = SCHEMA_MAJOR) -> bool:
+        return self.major == reader_major
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}"
+
+
+@dataclass(frozen=True)
+class Event:
+    """One decoded stream record.
+
+    `type` and `payload` are always present; `payload` holds every field the
+    producer emitted for this record EXCEPT `type` (so unknown/future fields are
+    preserved verbatim, never dropped). `raw` keeps the exact source dict for
+    consumers that want lossless passthrough.
+    """
+
+    type: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_obj(cls, obj: dict[str, Any]) -> "Event":
+        etype = str(obj.get("type") or "")
+        payload = {k: v for k, v in obj.items() if k != "type"}
+        return cls(type=etype, payload=payload, raw=dict(obj))
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.payload.get(key, default)
+
+    @property
+    def is_terminal(self) -> bool:
+        """The single mandatory closing record of every run."""
+        return self.type == "result"

localcode-0.3.37/src/localcode/protocol/jsonl.py

@@ -0,0 +1,153 @@
+"""Incremental JSONL parser for the `localcode run --json` stream.
+
+Consumes the event stream one line at a time from a text or byte iterable
+without buffering the whole transcript, so a long agent run or a live process
+pipe never has to be held in memory. It is deliberately tolerant of the messy
+realities of a subprocess stream (partial final line after a kill, an
+occasional non-JSON line, non-UTF-8 bytes) up to a small threshold, while still
+surfacing genuine protocol violations (a missing or duplicated terminal event,
+an unreadable major schema) as structured problems rather than swallowing them.
+
+The parser NEVER decides whether a benchmark task passed. It reports what the
+stream said; grading lives in the caller's verifier (integration plan §9).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Iterator
+
+from .events import Event, SchemaVersion, UnsupportedSchemaError
+
+__all__ = ["ParseProblem", "ParseResult", "parse_stream", "iter_events"]
+
+# Stop tolerating junk once this many lines fail to decode — a stream that is
+# mostly noise is a real problem, not a stray line, and should be reported.
+_MAX_MALFORMED = 50
+
+
+@dataclass
+class ParseProblem:
+    """A non-fatal issue found while parsing, kept for diagnostics."""
+
+    kind: str          # "malformed_line" | "missing_terminal" | "duplicate_terminal" | "decode_error"
+    detail: str
+    line_no: int = 0
+
+
+@dataclass
+class ParseResult:
+    """Everything a consumer needs from one parsed run stream."""
+
+    events: list[Event] = field(default_factory=list)
+    schema: SchemaVersion | None = None
+    terminal: Event | None = None          # the mandatory `result` event, if present
+    problems: list[ParseProblem] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        """True when the stream was well-formed: a terminal event, no protocol problems."""
+        return self.terminal is not None and not any(
+            p.kind in {"missing_terminal", "duplicate_terminal"} for p in self.problems
+        )
+
+    def events_of(self, event_type: str) -> list[Event]:
+        return [e for e in self.events if e.type == event_type]
+
+
+def _to_text_lines(source: Iterable[Any]) -> Iterator[str]:
+    """Yield decoded text lines from a text- or byte-iterable.
+
+    Accepts an open file, a list of str/bytes, or any iterable of lines. Bytes
+    are decoded as UTF-8 with replacement so a stray non-UTF-8 byte degrades one
+    character instead of killing the stream. Handles the case of a single string
+    blob (splitlines) as well as a pre-split iterable.
+    """
+    if isinstance(source, (str, bytes)):
+        blob = source.decode("utf-8", "replace") if isinstance(source, bytes) else source
+        yield from blob.splitlines()
+        return
+    for line in source:
+        if isinstance(line, bytes):
+            yield line.decode("utf-8", "replace")
+        else:
+            yield str(line)
+
+
+def iter_events(source: Iterable[Any]) -> Iterator[Event]:
+    """Stream `Event`s lazily, skipping blank/malformed lines silently.
+
+    Use this for memory-bounded live consumption where you handle terminal /
+    schema logic yourself. Use `parse_stream` for a fully-checked result.
+    """
+    import json
+
+    for raw_line in _to_text_lines(source):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (ValueError, TypeError):
+            continue
+        if isinstance(obj, dict):
+            yield Event.from_obj(obj)
+
+
+def parse_stream(source: Iterable[Any]) -> ParseResult:
+    """Fully parse a run stream into a checked `ParseResult`.
+
+    - Decodes each line; a small number of malformed lines are recorded and
+      skipped, but crossing `_MAX_MALFORMED` records a `decode_error` problem.
+    - Reads `schema_version` from any record that carries it (typically the
+      leading `run_start`); a MAJOR mismatch raises `UnsupportedSchemaError`
+      rather than risk misreading reshaped fields.
+    - Requires exactly one terminal (`result`) event: zero → `missing_terminal`,
+      more than one → `duplicate_terminal`.
+    """
+    import json
+
+    result = ParseResult()
+    malformed = 0
+
+    for line_no, raw_line in enumerate(_to_text_lines(source), start=1):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (ValueError, TypeError) as exc:
+            malformed += 1
+            if malformed <= _MAX_MALFORMED:
+                result.problems.append(ParseProblem("malformed_line", str(exc), line_no))
+            elif malformed == _MAX_MALFORMED + 1:
+                result.problems.append(ParseProblem(
+                    "decode_error",
+                    f"more than {_MAX_MALFORMED} malformed lines; stream is likely not JSONL",
+                    line_no,
+                ))
+            continue
+        if not isinstance(obj, dict):
+            result.problems.append(ParseProblem("malformed_line", "line is not a JSON object", line_no))
+            continue
+
+        # Schema version can ride on any record; the first one we see wins and
+        # gates the whole stream. A major we can't read is a hard stop.
+        if result.schema is None and "schema_version" in obj:
+            sv = SchemaVersion.parse(obj.get("schema_version"))
+            if not sv.readable_by():
+                raise UnsupportedSchemaError(sv.major)
+            result.schema = sv
+
+        event = Event.from_obj(obj)
+        result.events.append(event)
+        if event.is_terminal:
+            if result.terminal is not None:
+                result.problems.append(ParseProblem(
+                    "duplicate_terminal", "more than one terminal 'result' event", line_no))
+            else:
+                result.terminal = event
+
+    if result.terminal is None:
+        result.problems.append(ParseProblem(
+            "missing_terminal", "stream ended with no terminal 'result' event"))
+    return result

localcode-0.3.37/src/localcode/protocol/outcomes.py

@@ -0,0 +1,228 @@
+"""Stable outcome + failure normalization for a parsed run stream.
+
+Turns a `ParseResult` into a `RunOutcome`: one normalized failure category from
+the plan's fixed taxonomy (§10), the raw LocalCode reason preserved alongside,
+and objective counts (rounds, tool calls, tokens). Both harnesses normalize
+here so a regression comparison never depends on two consumers bucketing the
+same reason string differently.
+
+Boundary that matters (integration plan §9): this module only classifies the
+LocalCode side — setup, model server, agent, protocol. Whether the *task*
+passed is the verifier's call, never inferred from `status == "ok"`. The three
+verifier-owned categories (`task_passed`, `task_failed`, `verifier_failure`)
+are defined here for a shared vocabulary but are assigned by the caller, not by
+this parser.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .jsonl import ParseResult
+
+__all__ = ["FailureCategory", "RunOutcome", "normalize_reason", "redact", "outcome_from_parse"]
+
+
+class FailureCategory:
+    """The fixed failure taxonomy (integration plan §10). String constants so
+    they serialize cleanly and compare stably across releases."""
+
+    # LocalCode-side — assignable from the stream alone.
+    SETUP_FAILURE = "setup_failure"
+    MODEL_SERVER_UNREACHABLE = "model_server_unreachable"
+    MODEL_SERVER_FAILURE = "model_server_failure"
+    AGENT_TIMEOUT = "agent_timeout"
+    AGENT_CRASH = "agent_crash"
+    AGENT_INCOMPLETE = "agent_incomplete"
+    EVENT_PROTOCOL_ERROR = "event_protocol_error"
+    TOOL_FAILURE = "tool_failure"
+    CONTEXT_EXHAUSTED = "context_exhausted"
+    REASONING_LOOP_ABORT = "reasoning_loop_abort"
+    # Clean finish (LocalCode's own loop completed). NOT "task passed".
+    COMPLETED = "completed"
+    # Verifier-owned — assigned by the caller, never by this parser.
+    VERIFIER_FAILURE = "verifier_failure"
+    TASK_FAILED = "task_failed"
+    TASK_PASSED = "task_passed"
+
+
+# Exact LocalCode `result.reason` / status strings → category. Matched first;
+# substring rules below catch the parameterized ones (e.g. "stream_error:...").
+_EXACT: dict[str, str] = {
+    "completed": FailureCategory.COMPLETED,
+    "verified_run_or_launch": FailureCategory.COMPLETED,
+    "no model found on disk": FailureCategory.SETUP_FAILURE,
+    "could not start the model server": FailureCategory.MODEL_SERVER_FAILURE,
+    "model_server_unreachable": FailureCategory.MODEL_SERVER_UNREACHABLE,
+    "keyboard interrupt": FailureCategory.AGENT_INCOMPLETE,
+    "user_cancel": FailureCategory.AGENT_INCOMPLETE,
+    "stream_interrupt": FailureCategory.AGENT_INCOMPLETE,
+    "stall_exhausted": FailureCategory.AGENT_INCOMPLETE,
+    "max_rounds": FailureCategory.AGENT_INCOMPLETE,
+    "max_output_recovery_exhausted": FailureCategory.CONTEXT_EXHAUSTED,
+    "context_exhausted": FailureCategory.CONTEXT_EXHAUSTED,
+    "thinking_loop_exhausted": FailureCategory.REASONING_LOOP_ABORT,
+    "truncated_tool_call_exhausted": FailureCategory.TOOL_FAILURE,
+}
+
+# (substring, category) — ordered; first hit wins. For reasons that carry a
+# suffix payload like "stream_error:ConnectionError".
+_SUBSTRING: tuple[tuple[str, str], ...] = (
+    ("model_server", FailureCategory.MODEL_SERVER_FAILURE),
+    ("stream_error", FailureCategory.MODEL_SERVER_FAILURE),
+    ("reasoning_loop", FailureCategory.REASONING_LOOP_ABORT),
+    ("thinking_loop", FailureCategory.REASONING_LOOP_ABORT),
+    ("context", FailureCategory.CONTEXT_EXHAUSTED),
+    ("tool", FailureCategory.TOOL_FAILURE),
+    ("timeout", FailureCategory.AGENT_TIMEOUT),
+)
+
+
+def normalize_reason(status: str, reason: str) -> str:
+    """Map a LocalCode terminal (status, reason) to a stable failure category.
+
+    `status` is the coarse `result.status` ("ok"/"error"/"timeout"/
+    "interrupted"/"incomplete"); `reason` is the finer machine reason. Status is
+    consulted first for the unambiguous coarse cases, then the reason string.
+    An unrecognised failing reason falls back to `agent_crash` (something went
+    wrong we haven't named) rather than being silently treated as success.
+    """
+    status = (status or "").strip().lower()
+    reason = (reason or "").strip()
+    rl = reason.lower()
+
+    if status == "ok":
+        return _EXACT.get(rl, FailureCategory.COMPLETED)
+    if status == "timeout":
+        return FailureCategory.AGENT_TIMEOUT
+    if status == "interrupted":
+        return FailureCategory.AGENT_INCOMPLETE
+
+    # status in {"error","incomplete",...}: classify by the reason.
+    if rl in _EXACT:
+        return _EXACT[rl]
+    for needle, category in _SUBSTRING:
+        if needle in rl:
+            return category
+    if status == "incomplete":
+        return FailureCategory.AGENT_INCOMPLETE
+    # An error we couldn't place — name it a crash, never a pass.
+    return FailureCategory.AGENT_CRASH
+
+
+@dataclass
+class RunOutcome:
+    """Normalized, objective summary of one run stream."""
+
+    status: str
+    category: str
+    raw_reason: str
+    final_text: str = ""
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    rounds: int = 0
+    tool_calls: int = 0
+    tool_failures: int = 0
+    schema: str = ""
+    protocol_ok: bool = True
+    problems: list[str] = field(default_factory=list)
+
+    @property
+    def clean_finish(self) -> bool:
+        """LocalCode's own loop completed without a failure category.
+
+        NOT a statement about task success — the verifier owns that."""
+        return self.category == FailureCategory.COMPLETED and self.protocol_ok
+
+
+def _as_int(v: Any) -> int:
+    try:
+        return int(v or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def outcome_from_parse(parsed: ParseResult) -> RunOutcome:
+    """Build a `RunOutcome` from a parsed stream.
+
+    Token counts come from the terminal `result` event when present (it already
+    carries the accumulated totals); rounds and tool calls are counted from the
+    event stream by their real type names (`round_end`, `tool_call`). A tool
+    result carrying an error status counts toward `tool_failures`.
+    """
+    terminal = parsed.terminal
+    status = str(terminal.get("status") if terminal else "") or ""
+    reason = str(terminal.get("reason") if terminal else "") or ""
+
+    # A protocol violation (missing/duplicate terminal) is itself a category —
+    # the stream can't be trusted, so we don't pretend to know the LocalCode
+    # outcome.
+    protocol_problems = [p for p in parsed.problems
+                         if p.kind in {"missing_terminal", "duplicate_terminal", "decode_error"}]
+    if protocol_problems:
+        category = FailureCategory.EVENT_PROTOCOL_ERROR
+    else:
+        category = normalize_reason(status, reason)
+
+    tokens = terminal.get("tokens", {}) if terminal else {}
+    if isinstance(tokens, dict):
+        prompt = _as_int(tokens.get("prompt"))
+        completion = _as_int(tokens.get("completion"))
+        total = _as_int(tokens.get("total")) or (prompt + completion)
+    else:
+        prompt = completion = total = 0
+
+    tool_calls = 0
+    tool_failures = 0
+    rounds = 0
+    for ev in parsed.events:
+        if ev.type == "round_end":
+            rounds += 1
+        elif ev.type == "tool_call":
+            tool_calls += 1
+        elif ev.type == "tool_result":
+            st = str(ev.get("status") or ev.get("result_status") or "").lower()
+            if st in {"error", "failed", "rejected"}:
+                tool_failures += 1
+
+    return RunOutcome(
+        status=status,
+        category=category,
+        raw_reason=reason,
+        final_text=str(terminal.get("final_text") if terminal else "") or "",
+        prompt_tokens=prompt,
+        completion_tokens=completion,
+        total_tokens=total,
+        rounds=rounds,
+        tool_calls=tool_calls,
+        tool_failures=tool_failures,
+        schema=str(parsed.schema) if parsed.schema else "",
+        protocol_ok=not protocol_problems,
+        problems=[f"{p.kind}: {p.detail}" for p in parsed.problems],
+    )
+
+
+# Field names whose values are secrets and must never be persisted in a
+# trajectory or archived config. Case-insensitive substring match.
+_SECRET_HINTS = ("token", "secret", "password", "api_key", "apikey",
+                 "authorization", "auth_header", "bearer", "credential")
+_REDACTED = "***REDACTED***"
+
+
+def redact(obj: Any) -> Any:
+    """Recursively redact secret-looking fields from a dict/list before it is
+    persisted (integration plan §11). Returns a redacted copy; the input is not
+    mutated. Non-container values pass through unchanged."""
+    if isinstance(obj, dict):
+        out: dict[str, Any] = {}
+        for k, v in obj.items():
+            key = str(k).lower()
+            if any(hint in key for hint in _SECRET_HINTS):
+                out[k] = _REDACTED
+            else:
+                out[k] = redact(v)
+        return out
+    if isinstance(obj, list):
+        return [redact(v) for v in obj]
+    return obj