pcode 0.1.0__py3-none-any.whl

pcode/models.py

@@ -0,0 +1,209 @@
+"""Local model suggestions for configured providers; no credential or network reads."""
+
+import importlib.util
+import os
+import re
+import shutil
+from pathlib import Path
+from typing import get_args
+
+# Every prefix the picker accepts, with a display label. Each provider's SDK
+# extra must be installed (see pyproject.toml) or infer_model raises on switch.
+PROVIDERS = {
+    "alibaba": "Alibaba",
+    "anthropic": "Anthropic",
+    "azure": "Azure OpenAI",
+    "bedrock": "Bedrock",
+    "bedrock-mantle": "Bedrock Mantle",
+    "cerebras": "Cerebras",
+    "claude": "Claude Code",
+    "crusoe": "Crusoe",
+    "deepseek": "DeepSeek",
+    "fireworks": "Fireworks",
+    "github-copilot": "GitHub Copilot",
+    "google": "Google",
+    "google-cloud": "Google Cloud",
+    "groq": "Groq",
+    "heroku": "Heroku",
+    "meridian": "Meridian",
+    "moonshotai": "Moonshot",
+    "nebius": "Nebius",
+    "ollama": "Ollama",
+    "openai": "OpenAI",
+    "openai-chat": "OpenAI (chat)",
+    "openai-codex": "OpenAI Codex",
+    "openai-responses": "OpenAI (responses)",
+    "openrouter": "OpenRouter",
+    "ovhcloud": "OVHcloud",
+    "sambanova": "SambaNova",
+    "snowflake": "Snowflake",
+    "together": "Together",
+    "vercel": "Vercel",
+    "vllm": "vLLM",
+    "xai": "xAI",
+    "zai": "Z.ai",
+}
+
+# Providers activated by environment. Each inner tuple is one requirement
+# satisfied by any listed variable; every requirement must hold. Only names
+# are inspected, never values. Providers needing an endpoint as well as a key
+# (azure, github-copilot) list both so a lone key is not a false positive.
+ENV_PROVIDERS: dict[str, tuple[tuple[str, ...], ...]] = {
+    "alibaba": (("ALIBABA_API_KEY", "DASHSCOPE_API_KEY"),),
+    "azure": (("AZURE_OPENAI_API_KEY",), ("AZURE_OPENAI_ENDPOINT",)),
+    "bedrock": (("AWS_BEARER_TOKEN_BEDROCK", "AWS_ACCESS_KEY_ID", "AWS_PROFILE"),),
+    "bedrock-mantle": (("AWS_BEARER_TOKEN_BEDROCK",),),
+    "cerebras": (("CEREBRAS_API_KEY",),),
+    "crusoe": (("CRUSOE_API_KEY",),),
+    "deepseek": (("DEEPSEEK_API_KEY",),),
+    "fireworks": (("FIREWORKS_API_KEY",),),
+    "github-copilot": (
+        ("GITHUB_COPILOT_API_KEY", "GITHUB_COPILOT_API_TOKEN", "COPILOT_GITHUB_TOKEN"),
+        ("GITHUB_COPILOT_BASE_URL", "GITHUB_COPILOT_API_BASE", "COPILOT_API_URL"),
+    ),
+    "google": (("GOOGLE_API_KEY", "GEMINI_API_KEY"),),
+    "google-cloud": (("GOOGLE_CLOUD_PROJECT", "GOOGLE_APPLICATION_CREDENTIALS"),),
+    "groq": (("GROQ_API_KEY",),),
+    "heroku": (("HEROKU_INFERENCE_KEY",),),
+    "moonshotai": (("MOONSHOTAI_API_KEY",),),
+    "nebius": (("NEBIUS_API_KEY",),),
+    "ollama": (("OLLAMA_BASE_URL",),),
+    "openai": (("OPENAI_API_KEY",),),
+    "openrouter": (("OPENROUTER_API_KEY",),),
+    "ovhcloud": (("OVHCLOUD_API_KEY",),),
+    "sambanova": (("SAMBANOVA_API_KEY",),),
+    "snowflake": (("SNOWFLAKE_TOKEN",), ("SNOWFLAKE_ACCOUNT",)),
+    "together": (("TOGETHER_API_KEY",),),
+    "vercel": (("VERCEL_AI_GATEWAY_API_KEY", "VERCEL_OIDC_TOKEN"),),
+    "vllm": (("VLLM_BASE_URL",),),
+    "xai": (("XAI_API_KEY",),),
+    "zai": (("ZAI_API_KEY",),),
+}
+
+# The subscription routes that predate `claude:` models (the Claude Agent SDK):
+# `meridian:` models and pcode's own Anthropic browser sign-in. Off while
+# `claude:` is tried as the way forward; True restores both unchanged.
+# `anthropic:` models on ANTHROPIC_API_KEY work either way.
+LEGACY_ANTHROPIC_AUTH = False
+
+
+def login_sources() -> tuple[str, ...]:
+    """What `/login` accepts; the first is what a bare `/login` signs in to."""
+    if LEGACY_ANTHROPIC_AUTH:
+        return ("anthropic", "openai-codex", "claude", "meridian")
+    return ("claude", "openai-codex")
+
+
+def anthropic_credential_hint() -> str:
+    """How to give an `anthropic:` model that has no credential one."""
+    if LEGACY_ANTHROPIC_AUTH:
+        return "Run /login, or set ANTHROPIC_API_KEY."
+    return "Set ANTHROPIC_API_KEY, or switch to a claude: model."
+
+
+# Catalog prefix -> KnownModelName prefixes whose IDs it accepts. Codex has no
+# separate SDK catalog, so expose every OpenAI model ID and let the provider
+# enforce account access; Meridian and Claude Code front Anthropic models.
+CATALOG_SOURCES = {"openai-codex": "openai", "meridian": "anthropic", "claude": "anthropic"}
+
+
+def claude_code_configured() -> bool:
+    """Whether this machine has used Claude Code, whose login `claude:` models share.
+
+    The Agent SDK bundles the CLI, so an install is not required; its config
+    is the signal, checked for existence only.
+    """
+    config = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
+    try:
+        return bool(
+            (Path(config).expanduser() if config else Path.home() / ".claude").is_dir()
+            or (Path.home() / ".claude.json").is_file()
+            or shutil.which("claude")
+        )
+    except OSError:
+        return False
+
+
+def claude_sdk_installed() -> bool:
+    """Whether pcode was installed with its `claude` extra (claude-agent-sdk)."""
+    return importlib.util.find_spec("claude_agent_sdk") is not None
+
+
+def _configured(requirements: tuple[tuple[str, ...], ...]) -> bool:
+    return all(any(os.environ.get(name, "").strip() for name in group) for group in requirements)
+
+
+def active_providers(current: str | None) -> set[str]:
+    active = set()
+    if current and current.partition(":")[0] in PROVIDERS:
+        active.add(current.partition(":")[0])
+    if os.environ.get("PCODE_MERIDIAN_BASE_URL", "").strip() or shutil.which("meridian"):
+        active.add("meridian")
+    if claude_sdk_installed() and claude_code_configured():
+        active.add("claude")
+    active.update(name for name, needs in ENV_PROVIDERS.items() if _configured(needs))
+    from pcode.anthropic_oauth import anthropic_auth_source
+
+    # Resolution checks for a stored login file, never its contents.
+    source = anthropic_auth_source()
+    if source == "oauth" or (
+        source == "api-key" and os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    ):
+        active.add("anthropic")
+    from pcode.codex_login import have_credentials
+
+    # Only check existence, never read a credential to populate the picker.
+    codex_home = os.environ.get("CODEX_HOME", "").strip()
+    directory = Path(codex_home).expanduser() if codex_home else Path.home() / ".codex"
+    try:
+        if have_credentials() or (directory / "auth.json").is_file():
+            active.add("openai-codex")
+    except OSError:
+        pass
+    from pcode.preferences import load_preferences
+
+    allowed = load_preferences().get("model_providers", "")
+    if allowed:
+        active.intersection_update(name.strip() for name in allowed.split(","))
+    if not LEGACY_ANTHROPIC_AUTH:
+        # Even when the current model is a saved `meridian:` one.
+        active.discard("meridian")
+    return active
+
+
+def model_catalog(providers: set[str], current: str | None = None) -> list[str]:
+    # Imported here so the terminal can read this module's settings without
+    # loading the agent stack. KnownModelName is a TypeAliasType on supported
+    # Pydantic versions.
+    from pydantic_ai.models import KnownModelName
+
+    known = get_args(getattr(KnownModelName, "__value__", KnownModelName))
+    by_source: dict[str, set[str]] = {}
+    for name in known:
+        if isinstance(name, str):
+            source, _, model = name.partition(":")
+            by_source.setdefault(source, set()).add(model)
+    models = set()
+    for provider in providers:
+        source = CATALOG_SOURCES.get(provider, provider)
+        # Providers without a catalog (openrouter, ollama, vllm...) take any
+        # model ID typed into the picker instead.
+        models.update(f"{provider}:{model}" for model in by_source.get(source, ()))
+    if current and current.partition(":")[0] in providers:
+        models.add(current)
+    return sorted(models, key=model_sort_key)
+
+
+def model_sort_key(name: str):
+    """Group providers/families alphabetically, then numeric versions newest first.
+
+    Compare numeric components as integers so 4.10 precedes 4.9. Undated aliases
+    sort before dated snapshots of the same version. Do not pin the current model
+    above newer suggestions; the picker marks it separately.
+    """
+    provider, _, model = name.partition(":")
+    parts = tuple(
+        (1, -int(part)) if part.isdigit() else (0, part.casefold())
+        for part in re.split(r"(\d+)", model)
+    )
+    return provider, parts

pcode/native_results.py

@@ -0,0 +1,119 @@
+"""Repair a history whose native-tool results the current login cannot read.
+
+Anthropic returns each server-side `web_search` hit as an opaque
+`encrypted_content` blob that only the organization it was issued to can
+decrypt. Replay is therefore credential-bound: sign in as a different account
+-- a second `/login`, another `PCODE_CONFIG_DIR`, an API key in place of a
+subscription -- and the request comes back as
+`400 Invalid encrypted_content in search_result block`. The blobs live in the
+message history, so without a repair every later request in that session fails
+the same way and the conversation is stranded.
+
+Dropping them is the whole repair. The page text inside a blob is unrecoverable,
+but the titles and URLs beside it are plaintext, and the model's own reading of
+the search sits in the same response. Thinking signatures cross accounts
+untouched (verified against the live endpoint), so they are left alone.
+"""
+
+from collections.abc import Iterable
+
+from pydantic_ai.exceptions import ModelHTTPError
+from pydantic_ai.messages import (
+    ModelMessage,
+    ModelResponse,
+    ModelResponsePart,
+    NativeToolCallPart,
+    NativeToolReturnPart,
+    TextPart,
+)
+
+# Enough to place the search without turning one dead result set into a wall.
+MAX_SOURCES = 10
+
+
+def unreadable_native_results(error: BaseException) -> bool:
+    """Whether the provider rejected replayed results it cannot decrypt.
+
+    Deliberately narrow: a 400 naming `encrypted_content` is the provider
+    saying this history is unsendable as it stands, which no amount of retrying
+    changes. Every other 400 is a request pcode built wrong.
+    """
+    return (
+        isinstance(error, ModelHTTPError)
+        and error.status_code == 400
+        and "encrypted_content" in str(error.body)
+    )
+
+
+def drop_unreadable_results(messages: Iterable[ModelMessage]) -> int:
+    """Replace credential-bound native results with a plain trace, in place.
+
+    Returns how many results were dropped. The part lists are rewritten through
+    a slice assignment because the same `ModelResponse` objects are shared by
+    the turn's history, the request already checkpointed, and the next
+    snapshot: replacing the messages would repair only one of them.
+    """
+    dropped = 0
+    for message in messages:
+        if not isinstance(message, ModelResponse):
+            continue
+        stale = {
+            part.tool_call_id
+            for part in message.parts
+            if isinstance(part, NativeToolReturnPart) and _encrypted(part.content)
+        }
+        if not stale:
+            continue
+        queries = {
+            part.tool_call_id: _query(part)
+            for part in message.parts
+            if isinstance(part, NativeToolCallPart) and part.tool_call_id in stale
+        }
+        kept: list[ModelResponsePart] = []
+        for part in message.parts:
+            if isinstance(part, NativeToolCallPart) and part.tool_call_id in stale:
+                # The call cannot outlive its result: an unpaired server tool
+                # use is rejected in its own right.
+                continue
+            if isinstance(part, NativeToolReturnPart) and part.tool_call_id in stale:
+                kept.append(TextPart(content=_note(part, queries.get(part.tool_call_id))))
+                dropped += 1
+                continue
+            kept.append(part)
+        message.parts[:] = kept
+    return dropped
+
+
+def _encrypted(content: object) -> bool:
+    """Whether anything in a result carries provider-encrypted text."""
+    if isinstance(content, dict):
+        return "encrypted_content" in content or any(_encrypted(v) for v in content.values())
+    if isinstance(content, list):
+        return any(_encrypted(item) for item in content)
+    return False
+
+
+def _query(part: NativeToolCallPart) -> str | None:
+    try:
+        args = part.args_as_dict()
+    except Exception:
+        return None
+    query = args.get("query")
+    return query if isinstance(query, str) else None
+
+
+def _note(part: NativeToolReturnPart, query: str | None) -> str:
+    items = part.content if isinstance(part.content, list) else [part.content]
+    sources = [
+        f"{item.get('title') or item['url']}: {item['url']}"
+        for item in items
+        if isinstance(item, dict) and item.get("url")
+    ]
+    searched = f" for {query!r}" if query else ""
+    listed = "".join(f"\n- {source}" for source in sources[:MAX_SOURCES])
+    found = f" Pages found:{listed}" if listed else ""
+    return (
+        f"[pcode: the {part.tool_name} results{searched} were encrypted for a different "
+        f"account and cannot be replayed, so they were dropped from this conversation. "
+        f"Search again if you still need them.{found}]"
+    )

pcode/oauth_pages.py

@@ -0,0 +1,66 @@
+"""Browser-facing HTML for the loopback OAuth callback.
+
+The loopback server answers exactly one request and then shuts down, so the page
+has to be a single self-contained document: no stylesheet fetch, no fonts, no
+scripts that outlive the response.
+
+Adapted from the MIT-licensed templates in kriasoft/oauth-callback
+(https://github.com/kriasoft/oauth-callback), Copyright (c) 2025-present
+Konstantin Tarkus, Kriasoft.
+"""
+
+from __future__ import annotations
+
+from html import escape
+
+_STYLE = """
+:root{color-scheme:light dark}
+body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Ubuntu,"Helvetica Neue",sans-serif;
+background:linear-gradient(180deg,#fafafa 0%,#f0f0f0 100%);color:#1a1a1a}
+.card{background:#fff;border-radius:16px;padding:48px 40px 40px;max-width:420px;width:90%;
+text-align:center;box-shadow:0 1px 3px rgba(0,0,0,.04),0 6px 16px rgba(0,0,0,.08);
+animation:fadeUp .4s ease-out}
+h1{font-size:24px;font-weight:600;margin:0 0 8px;letter-spacing:-.02em;line-height:1.2}
+p{font-size:15px;color:#666;margin:0;line-height:1.5}
+svg{width:56px;height:56px;margin:0 auto 24px;display:block;fill:none;stroke-width:3;
+stroke-linecap:round;stroke-linejoin:round}
+circle{stroke-width:2;stroke-dasharray:157;stroke-dashoffset:157;
+animation:stroke .6s cubic-bezier(.65,0,.45,1) forwards}
+path{stroke-dasharray:60;stroke-dashoffset:60;
+animation:stroke .3s cubic-bezier(.65,0,.45,1) .4s forwards}
+.ok svg{stroke:#10b981}
+.bad svg{stroke:#ef4444}
+@keyframes stroke{to{stroke-dashoffset:0}}
+@keyframes fadeUp{from{opacity:0;transform:translateY(8px)}to{opacity:1;transform:none}}
+@media (prefers-color-scheme:dark){
+body{background:linear-gradient(180deg,#0a0a0a 0%,#1a1a1a 100%);color:#fafafa}
+.card{background:#1f1f1f;box-shadow:0 1px 3px rgba(0,0,0,.2),0 8px 24px rgba(0,0,0,.4)}
+p{color:#999}}
+@media (prefers-reduced-motion:reduce){*{animation:none!important}
+circle,path{stroke-dashoffset:0}}
+"""
+
+_CHECK = '<path d="M14.1 27.2l7.1 7.2 16.7-16.8"/>'
+_CROSS = '<path d="M17 17l18 18M35 17L17 35"/>'
+
+_PAGE = (
+    "<!doctype html><html lang=en><head><meta charset=utf-8>"
+    '<meta name=viewport content="width=device-width, initial-scale=1">'
+    "<title>{title} &middot; pcode</title><style>{style}</style></head>"
+    '<body class="{kind}"><main class=card>'
+    '<svg viewBox="0 0 52 52" role=img aria-hidden=true>'
+    "<circle cx=26 cy=26 r=25/>{icon}</svg>"
+    "<h1>{title}</h1><p>{message}</p></main></body></html>"
+)
+
+
+def callback_page(title: str, message: str, *, ok: bool) -> str:
+    """Render the single page the browser sees after the OAuth redirect."""
+    return _PAGE.format(
+        title=escape(title),
+        message=escape(message),
+        style=_STYLE,
+        kind="ok" if ok else "bad",
+        icon=_CHECK if ok else _CROSS,
+    )

pcode/output_limits.py

@@ -0,0 +1,41 @@
+"""Model-aware output defaults, separate from reasoning effort and visibility."""
+
+from dataclasses import replace
+
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.models.anthropic import AnthropicModel
+
+from pcode.model_metadata import catalog, refresh_context
+
+# Anthropic requires max_tokens. Pydantic AI before 2.52 sent 4096, which thinking
+# or one file-writing tool call can exhaust; 2.52 asks for the model's maximum
+# output when its own profile knows it. pcode resolves the serving route's limit
+# (Meridian ids, Claude Code aliases) from its catalog instead, and unknown or
+# offline routes cannot safely borrow another endpoint's model limits.
+FALLBACK_OUTPUT_TOKENS = 16_384
+
+
+class ModelOutputLimits(AbstractCapability):
+    """Resolve each request's default, including model switches and subagents.
+
+    Use the serving model's advertised maximum, not a guessed family-name table.
+    A maximum is a ceiling, not a requested response length or thinking budget.
+    Other adapters retain their provider defaults; explicit settings always win.
+    """
+
+    async def before_model_request(self, ctx, request_context):
+        if not isinstance(request_context.model, AnthropicModel):
+            return request_context
+        settings = request_context.model_settings or {}
+        if settings.get("max_tokens") is not None:
+            return request_context
+        await refresh_context(request_context.model)
+        limits = catalog.limits(request_context.model)
+        maximum = limits.output if limits else None
+        if maximum is None and request_context.model.system == "claude":
+            # The CLI's own default beats a guess below it (a `claude:opus` alias).
+            return request_context
+        return replace(
+            request_context,
+            model_settings={**settings, "max_tokens": maximum or FALLBACK_OUTPUT_TOKENS},
+        )

pcode/paste.py

@@ -0,0 +1,45 @@
+"""Collapse large pastes in the editor to a short preview plus a size marker.
+
+A multi-kilobyte paste turns the prompt into a wall of text that hides the
+question being typed around it. Pastes longer than ``PASTE_THRESHOLD`` are
+inserted as ``<preview>…[+N chars]`` instead; the full text is kept aside and
+substituted back into the buffer when the prompt is submitted, so the model
+still receives everything. A placeholder the user has edited no longer matches
+and is sent verbatim, which is deliberate: the marker is visible and the
+transcript shows exactly what went out.
+"""
+
+from __future__ import annotations
+
+import re
+
+PASTE_THRESHOLD = 100
+PREVIEW_CHARS = 60
+MARKER_PATTERN = re.compile(r"…\[\+[\d,]+ chars\]")
+
+__all__ = ["MARKER_PATTERN", "PASTE_THRESHOLD", "PastedText"]
+
+
+class PastedText:
+    """Placeholders currently standing in for pasted text in the editor."""
+
+    def __init__(self) -> None:
+        self._full: dict[str, str] = {}
+
+    def collapse(self, text: str) -> str:
+        """Return what to insert for ``text``: itself, or a placeholder."""
+        if len(text) <= PASTE_THRESHOLD:
+            return text
+        preview = text[:PREVIEW_CHARS].replace("\n", "⏎")
+        placeholder = f"{preview}…[+{len(text) - PREVIEW_CHARS:,} chars]"
+        self._full[placeholder] = text
+        return placeholder
+
+    def expand(self, text: str) -> str:
+        """Substitute every intact placeholder back with its full paste."""
+        for placeholder, full in self._full.items():
+            text = text.replace(placeholder, full)
+        return text
+
+    def clear(self) -> None:
+        self._full.clear()

pcode/path_completion.py

@@ -0,0 +1,66 @@
+"""Complete a filesystem path typed as a slash command's argument.
+
+Only the directory being typed is listed, never walked, and a huge directory
+is read only up to `SCAN_LIMIT` entries, so completion stays instant anywhere.
+"""
+
+import os
+from collections.abc import Iterator
+from itertools import islice
+from pathlib import Path
+
+from prompt_toolkit.completion import Completion
+
+SCAN_LIMIT = 2000
+SHOWN = 100
+
+
+def path_fragment(argument: str) -> str:
+    """The path being typed: the argument after any leading `--option` words."""
+    words = argument.lstrip()
+    while words.startswith("--"):
+        _option, space, words = words.partition(" ")
+        if not space:  # Still typing the option itself.
+            return ""
+        words = words.lstrip()
+    return words
+
+
+def complete_paths(argument: str, workspace: Path) -> Iterator[Completion]:
+    """Entries of the typed directory starting with the typed name, directories first.
+
+    Relative paths resolve against `workspace`. Nothing completes until
+    something is typed, and a bare `/` does not list the filesystem root.
+    """
+    fragment = path_fragment(argument)
+    if not fragment or fragment == "/":
+        return
+    if fragment == "~":
+        yield Completion("~/", start_position=-1)
+        return
+    head, _, name = fragment.rpartition("/")
+    if "/" in fragment:
+        directory = Path(os.path.expanduser(head or "/"))
+    else:
+        directory = Path()
+    if not directory.is_absolute():
+        directory = workspace / directory
+    needle = name.casefold()
+    found: list[tuple[bool, str]] = []
+    try:
+        with os.scandir(directory) as entries:
+            for entry in islice(entries, SCAN_LIMIT):
+                if entry.name.startswith(".") and not name.startswith("."):
+                    continue
+                if entry.name.casefold().startswith(needle):
+                    try:
+                        is_dir = entry.is_dir()
+                    except OSError:
+                        is_dir = False
+                    found.append((not is_dir, entry.name))
+    except OSError:
+        return
+    found.sort(key=lambda item: (item[0], item[1].casefold()))
+    for is_file, entry in found[:SHOWN]:
+        suffix = "" if is_file else "/"
+        yield Completion(entry + suffix, start_position=-len(name), display=entry + suffix)

pcode/plan_preview.py

@@ -0,0 +1,131 @@
+"""Ephemeral task-pane projections of streamed planning calls.
+
+These never mutate Harness's store. Complete strings/fields can be displayed while
+JSON is still arriving; validation, IDs, and persistence belong to the real tools.
+"""
+
+from copy import deepcopy
+
+from pydantic import ValidationError
+from pydantic_ai.messages import (
+    FunctionToolCallEvent,
+    FunctionToolResultEvent,
+    PartDeltaEvent,
+    PartEndEvent,
+    PartStartEvent,
+    ToolCallPart,
+    ToolCallPartDelta,
+)
+from pydantic_core import from_json
+
+from pcode.planning import SizedPlanItem
+from pcode.runtime import PlanPreview
+
+PLANNING_MUTATIONS = {
+    "write_plan",
+    "add_task",
+    "update_task_status",
+    "update_task_statuses",
+    "remove_task",
+}
+
+
+def project_plan(items: list[dict], part: ToolCallPart) -> list[dict]:
+    """Best-effort display only; malformed/incomplete fields leave the plan alone."""
+    try:
+        args = from_json(part.args, allow_partial=True) if isinstance(part.args, str) else part.args
+    except ValueError:
+        return items
+    if not isinstance(args, dict):
+        return items
+
+    def row(value, index):
+        if not isinstance(value, dict):
+            return None
+        try:
+            return SizedPlanItem.model_validate(
+                {"id": f"preview:{part.tool_call_id}:{index}", **value}
+            ).model_dump(mode="json")
+        except ValidationError:
+            return None
+
+    if part.tool_name == "write_plan":
+        values = args.get("items")
+        if isinstance(values, list):
+            rows = [item for i, value in enumerate(values) if (item := row(value, i)) is not None]
+            if rows:
+                return rows
+            # An unfinished `items: [` is not an instruction to clear the pane.
+            if values == []:
+                try:
+                    part.args_as_dict(raise_if_invalid=True)
+                except (ValueError, TypeError):
+                    return items
+                return []
+    elif part.tool_name == "add_task":
+        if (item := row(args, 0)) is not None:
+            return [*items, item]
+    elif part.tool_name in {"update_task_status", "update_task_statuses"}:
+        updates = args.get("updates") if part.tool_name == "update_task_statuses" else [args]
+        if isinstance(updates, list):
+            items = deepcopy(items)
+            for update in updates:
+                if not isinstance(update, dict):
+                    continue
+                for i, item in enumerate(items):
+                    if item["id"] == update.get("task_id"):
+                        changed = row({**item, "status": update.get("status")}, i)
+                        if changed is not None:
+                            items[i] = changed
+    elif part.tool_name == "remove_task":
+        return [item for item in items if item["id"] != args.get("task_id")]
+    return items
+
+
+class StreamingPlanPreview:
+    def __init__(self):
+        self.parts: dict[int, ToolCallPart] = {}
+        self.items: list[dict] | None = None
+        self.executing = False
+        self.confirmed: list[dict] = []
+
+    def update(self, event, confirmed: list[dict]) -> PlanPreview | None:
+        store_changed = confirmed != self.confirmed
+        self.confirmed = confirmed
+        if isinstance(event, PartStartEvent):
+            if self.executing or event.index == 0:
+                self.parts.clear()
+                self.executing = False
+            if isinstance(event.part, ToolCallPart):
+                self.parts[event.index] = event.part
+        elif isinstance(event, PartDeltaEvent):
+            if isinstance(event.delta, ToolCallPartDelta) and event.index in self.parts:
+                self.parts[event.index] = event.delta.apply(self.parts[event.index])
+        elif isinstance(event, PartEndEvent) and isinstance(event.part, ToolCallPart):
+            self.parts[event.index] = event.part
+        elif isinstance(event, FunctionToolCallEvent):
+            self.executing = True
+        elif isinstance(event, FunctionToolResultEvent):
+            if store_changed:
+                # The shared store can already contain sibling mutations whose
+                # result events have not arrived. Do not replay their arguments
+                # over that snapshot (e.g. duplicating concurrent add_task calls).
+                self.parts.clear()
+            else:
+                self.parts = {
+                    index: part
+                    for index, part in self.parts.items()
+                    if part.tool_call_id != event.tool_call_id
+                }
+        else:
+            return None
+
+        items = confirmed
+        for part in self.parts.values():
+            if part.tool_name in PLANNING_MUTATIONS:
+                items = project_plan(items, part)
+        preview = items if items != confirmed else None
+        if preview != self.items:
+            self.items = preview
+            return PlanPreview(preview)
+        return None