pcode 0.1.0__py3-none-any.whl

pcode/completion.py

@@ -0,0 +1,263 @@
+"""Shell completion scripts generated from the argparse parser.
+
+Generating from the live parser (rather than checking in hand-written scripts)
+keeps the completions honest: a new flag shows up without a second edit.
+
+Values that only exist at runtime (running session hosts) cannot be baked into
+the script, so an option marked with `complete_with` makes the script call
+back into `pcode __complete KIND`, which prints `value<TAB>description` lines.
+`pcode.cli` answers that before importing the frontend, so a Tab stays quick.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+SHELLS = ("zsh", "fish", "bash")
+
+# The hidden first argument the generated scripts call back with.
+COMPLETE_COMMAND = "__complete"
+
+
+_TITLE_WIDTH = 50
+
+
+def _hosts() -> list[tuple[str, str]]:
+    from pcode.host_protocol import list_hosts
+
+    candidates = []
+    for entry in list_hosts():
+        title = " ".join(entry.label().split())
+        if len(title) > _TITLE_WIDTH:
+            title = title[: _TITLE_WIDTH - 1] + "…"
+        candidates.append((entry.id, f"{entry.state} · {Path(entry.workspace).name} · {title}"))
+    return candidates
+
+
+# Kinds of runtime value an option can complete, by the name the scripts pass.
+_DYNAMIC: dict[str, Callable[[], list[tuple[str, str]]]] = {"hosts": _hosts}
+
+
+def complete_with(action: argparse.Action, kind: str) -> argparse.Action:
+    """Mark `action` as completing `kind` values, looked up when Tab is pressed."""
+    if kind not in _DYNAMIC:
+        raise ValueError(f"unknown completion kind: {kind}")
+    action.complete_kind = kind  # type: ignore[attr-defined]
+    return action
+
+
+def _dynamic(action: argparse.Action) -> str | None:
+    return getattr(action, "complete_kind", None)
+
+
+def print_candidates(argv: list[str], stream=None) -> int:
+    """`pcode __complete KIND`: one `value<TAB>description` line per candidate."""
+    stream = stream or sys.stdout
+    if len(argv) != 1 or argv[0] not in _DYNAMIC:
+        print(f"usage: pcode {COMPLETE_COMMAND} {{{','.join(_DYNAMIC)}}}", file=sys.stderr)
+        return 2
+    for value, description in _DYNAMIC[argv[0]]():
+        # A tab or newline would split the line the shells read.
+        print(f"{value}\t{' '.join(description.split())}", file=stream)
+    return 0
+
+
+_INSTALL_HINTS = {
+    "zsh": "pcode --completions zsh > ~/.zsh/completions/_pcode  # dir must be on $fpath",
+    "fish": "pcode --completions fish > ~/.config/fish/completions/pcode.fish",
+    "bash": 'eval "$(pcode --completions bash)"  # add to ~/.bashrc',
+}
+
+
+def install_hint(shell: str) -> str:
+    return _INSTALL_HINTS[shell]
+
+
+def _visible_actions(parser: argparse.ArgumentParser) -> list[argparse.Action]:
+    return [
+        action
+        for action in parser._actions
+        if action.option_strings and action.help is not argparse.SUPPRESS
+    ]
+
+
+def _takes_value(action: argparse.Action) -> bool:
+    return action.nargs != 0 and not isinstance(
+        action, argparse._StoreTrueAction | argparse._StoreFalseAction | argparse._CountAction
+    )
+
+
+def _optional_value(action: argparse.Action) -> bool:
+    return action.nargs == "?"
+
+
+def _choices(action: argparse.Action) -> list[str]:
+    return [str(choice) for choice in (action.choices or [])]
+
+
+def _wants_path(action: argparse.Action) -> bool:
+    return action.type is Path
+
+
+def _help(action: argparse.Action) -> str:
+    return " ".join((action.help or "").split())
+
+
+def _zsh_quote(text: str) -> str:
+    return text.replace("\\", "\\\\").replace("'", "'\\''").replace("[", "\\[").replace("]", "\\]")
+
+
+def _zsh(parser: argparse.ArgumentParser, prog: str) -> str:
+    lines = [f"#compdef {prog}", ""]
+    kinds = sorted({kind for action in _visible_actions(parser) if (kind := _dynamic(action))})
+    for kind in kinds:
+        # Helpers are defined at the top level so both the autoloaded and the
+        # sourced form of this file have them before `_{prog}` first runs.
+        lines += [
+            f"_{prog}_{kind}() {{",
+            "  local -a values",
+            f'  values=(${{(f)"$({prog} {COMPLETE_COMMAND} {kind} 2>/dev/null)"}})',
+            # _describe splits value from description on the first colon.
+            "  values=(\"${(@)values//$'\\t'/:}\")",
+            f"  _describe -t {kind} {kind} values",
+            "}",
+            "",
+        ]
+    lines += [f"_{prog}() {{", "  local -a specs", "  specs=("]
+    for action in _visible_actions(parser):
+        # Repeating an option is almost never meaningful here, so tell zsh to
+        # drop every spelling of a flag once any of them is on the line.
+        exclusion = f"({' '.join(action.option_strings)})" if len(action.option_strings) > 1 else ""
+        kind = _dynamic(action)
+        for option in action.option_strings:
+            name = option
+            if _takes_value(action) and _optional_value(action):
+                # `=-` marks an option whose value, if any, must be glued on as
+                # `--flag=value`, so the next word still completes as a prompt.
+                # A runtime value is the reason to type the option at all, so
+                # there `=` also completes it as the next word.
+                name = f"{option}=" if kind else f"{option}=-"
+            spec = f"{exclusion}{name}[{_zsh_quote(_help(action))}]"
+            if _takes_value(action):
+                metavar = str(action.metavar or action.dest)
+                if kind:
+                    optional = ":" if _optional_value(action) else ""
+                    spec += f":{optional}{metavar}:_{prog}_{kind}"
+                elif choices := _choices(action):
+                    spec += f":{metavar}:({' '.join(choices)})"
+                elif _wants_path(action):
+                    spec += f":{metavar}:_files"
+                else:
+                    spec += f":{metavar}: "
+            lines.append(f"    '{spec}'")
+    lines += [
+        "    '*:prompt:_files'",
+        "  )",
+        "  _arguments -s -S $specs && return 0",
+        "}",
+        "",
+        # In $fpath the file is autoloaded *as* the completion function, so it
+        # must call itself; when sourced from .zshrc it must register instead.
+        f'if [ "$funcstack[1]" = "_{prog}" ]; then',
+        f'  _{prog} "$@"',
+        "else",
+        f"  compdef _{prog} {prog}",
+        "fi",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _fish(parser: argparse.ArgumentParser, prog: str) -> str:
+    lines = ["# fish completions for pcode", ""]
+    for action in _visible_actions(parser):
+        flags = []
+        for option in action.option_strings:
+            if option.startswith("--"):
+                flags += ["-l", option[2:]]
+            else:
+                flags += ["-s", option[1:]]
+        parts = [f"complete -c {prog}", *flags]
+        if help_text := _help(action):
+            parts += ["-d", _fish_quote(help_text)]
+        kind = _dynamic(action)
+        if _takes_value(action):
+            # -r demands a value; an optional value stays -f so fish still
+            # offers the other flags. A runtime value is the reason to type the
+            # option at all, so it takes -r anyway (a `-` still lists flags).
+            parts.append("-r" if kind or not _optional_value(action) else "")
+            if kind:
+                parts += ["-f", "-a", _fish_quote(f"({prog} {COMPLETE_COMMAND} {kind})")]
+            elif choices := _choices(action):
+                parts += ["-f", "-a", _fish_quote(" ".join(choices))]
+            elif _wants_path(action):
+                parts.append("-F")
+            else:
+                parts.append("-f")
+        else:
+            parts.append("-f")
+        lines.append(" ".join(part for part in parts if part))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _fish_quote(text: str) -> str:
+    return "'" + text.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def _bash(parser: argparse.ArgumentParser, prog: str) -> str:
+    options = [option for action in _visible_actions(parser) for option in action.option_strings]
+    choice_cases = []
+    for action in _visible_actions(parser):
+        if not _takes_value(action):
+            continue
+        if kind := _dynamic(action):
+            pattern = "|".join(action.option_strings)
+            values = f"$({prog} {COMPLETE_COMMAND} {kind} 2>/dev/null | cut -f1)"
+            # An optional value leaves a `-` word to the flag list below.
+            choice_cases.append(
+                f'    {pattern})\n      if [[ "$cur" != -* ]]; then\n'
+                f'        COMPREPLY=($(compgen -W "{values}" -- "$cur")); return 0\n'
+                "      fi ;;"
+            )
+        elif choices := _choices(action):
+            pattern = "|".join(action.option_strings)
+            choice_cases.append(
+                f"    {pattern})\n"
+                f'      COMPREPLY=($(compgen -W "{" ".join(choices)}" -- "$cur")); return 0 ;;'
+            )
+        elif _wants_path(action):
+            pattern = "|".join(action.option_strings)
+            choice_cases.append(
+                f'    {pattern})\n      COMPREPLY=($(compgen -f -- "$cur")); return 0 ;;'
+            )
+    cases = "\n".join(choice_cases)
+    return f"""_{prog}() {{
+  local cur prev
+  cur="${{COMP_WORDS[COMP_CWORD]}}"
+  prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+  case "$prev" in
+{cases}
+  esac
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=($(compgen -W "{" ".join(options)}" -- "$cur"))
+    return 0
+  fi
+  COMPREPLY=($(compgen -f -- "$cur"))
+}}
+complete -F _{prog} {prog}
+"""
+
+
+def render(parser: argparse.ArgumentParser, shell: str, prog: str = "pcode") -> str:
+    """Return a completion script for `shell` describing `parser`."""
+    if shell == "zsh":
+        return _zsh(parser, prog)
+    if shell == "fish":
+        return _fish(parser, prog)
+    if shell == "bash":
+        return _bash(parser, prog)
+    raise ValueError(f"unsupported shell: {shell}")

pcode/config.py

@@ -0,0 +1,223 @@
+"""Defaults commands, shared by the CLI and interactive terminal.
+
+Editing defaults deliberately does not mutate a running conversation. In-session
+shortcuts change both the active setting and its saved default; the terminal also
+applies layout-only settings (`attach_tasks`, `tasks_max_height`, `task_style`,
+`tool_glyphs`, `tool_max_lines`, `tool_linger_seconds` and `show_hints`) immediately.
+
+`config project ...` edits the workspace's `.pcode/preferences.json`, which is
+layered over the user file at launch (except for `USER_ONLY` keys).
+"""
+
+import json
+from collections.abc import Sequence
+from pathlib import Path
+
+from pcode.preferences import (
+    MODEL_EFFORTS_KEY,
+    SETTINGS,
+    USER_ONLY,
+    Setting,
+    preferences_path,
+    project_preferences_path,
+    read_preferences,
+    update_preferences,
+)
+
+USAGE = "config [list | diff | path | get KEY | set KEY VALUE | unset KEY | reset | project ...]"
+PROJECT_USAGE = "config project [list | path | set KEY VALUE | unset KEY | reset]"
+
+# Resetting clears the recorded /login choice and every per-repository extension
+# grant, so say so rather than leaving the next launch to re-prompt unexplained.
+_RESET_NOTICE = {
+    "anthropic_auth": "re-run /login to choose a credential",
+    "trusted_projects": "repositories must be trusted again",
+}
+
+
+def _setting(key: str) -> Setting:
+    if key not in SETTINGS:
+        raise ValueError(f"Unknown setting '{key}'. Available: {', '.join(SETTINGS)}")
+    return SETTINGS[key]
+
+
+def _effective(data: dict, key: str) -> str | None:
+    setting = SETTINGS[key]
+    value = data.get(key)
+    if isinstance(value, str):
+        try:
+            setting.validate(key, value)
+        except ValueError:
+            pass
+        else:
+            return value
+    return setting.default
+
+
+def _effective_data() -> dict:
+    """Both files read strictly, so a broken one is reported instead of hidden."""
+    data = read_preferences()
+    project = project_preferences_path()
+    if project is not None:
+        data.update({k: v for k, v in read_preferences(project).items() if k not in USER_ONLY})
+    return data
+
+
+def _reset(path: Path | None, label: str) -> str:
+    """Drop every known setting, leaving unrecognized keys the file may carry."""
+    # Per-model efforts are a setting in every sense a user cares about, so a
+    # reset must clear them too even though they live outside SETTINGS.
+    known = set(SETTINGS) | {MODEL_EFFORTS_KEY}
+    removed = sorted(set(read_preferences(path)) & known)
+    if not removed:
+        return f"No {label} defaults to reset."
+    update_preferences({}, remove=tuple(removed), path=path)
+    notice = "".join(f" {_RESET_NOTICE[key]}." for key in removed if key in _RESET_NOTICE)
+    return f"Reset {label} defaults: {', '.join(removed)}. Applies on next launch.{notice}"
+
+
+def _diff() -> str:
+    """Only the settings actually changed, and which file changed them.
+
+    A stored value equal to the default is not a difference, and neither is an
+    invalid one: both leave the effective value where `list` shows it.
+    """
+    user = read_preferences()
+    project_path = project_preferences_path()
+    project = read_preferences(project_path) if project_path is not None else {}
+    data = _effective_data()
+    lines = []
+    for key, setting in SETTINGS.items():
+        value = _effective(data, key)
+        if value == setting.default:
+            continue
+        source = "project" if key in project and key not in USER_ONLY else "user"
+        default = "unset" if setting.default is None else setting.default
+        lines.append(f"{key} = {value} (default {default}, from {source})")
+    efforts = user.get(MODEL_EFFORTS_KEY)
+    if isinstance(efforts, dict) and efforts:
+        chosen = ", ".join(f"{model}={effort}" for model, effort in sorted(efforts.items()))
+        lines.append(f"{MODEL_EFFORTS_KEY} = {chosen} (default none, from user)")
+    if not lines:
+        return "Every setting is at its default."
+    return "\n".join(lines)
+
+
+def _project_path() -> Path:
+    path = project_preferences_path()
+    if path is None:
+        raise ValueError("No workspace is selected, so there is no project config to edit.")
+    return path
+
+
+def _configure_project(args: list[str]) -> str:
+    action = args[0] if args else "list"
+    if action == "path" and len(args) == 1:
+        return str(_project_path())
+    if action == "list" and len(args) == 1:
+        return json.dumps(read_preferences(_project_path()), indent=2)
+    if action == "set" and len(args) == 3:
+        key, value = args[1:]
+        if key in USER_ONLY:
+            raise ValueError(f"{key} is user-only; a repository cannot set it. Use config set.")
+        _setting(key).validate(key, value)
+        update_preferences({key: value}, path=_project_path())
+        return f"Saved project default: {key} = {value}. Applies on next launch."
+    if action == "unset" and len(args) == 2:
+        key = args[1]
+        _setting(key)
+        update_preferences({}, remove=(key,), path=_project_path())
+        return f"Removed project default: {key}. Applies on next launch."
+    if action == "reset" and len(args) == 1:
+        return _reset(_project_path(), "project")
+    raise ValueError(f"Usage: {PROJECT_USAGE}")
+
+
+def configure(arguments: Sequence[str]) -> str:
+    """Inspect or edit saved defaults without starting a model or session.
+
+    `list`, `diff`, and `get` report the effective value, with the project
+    overlay applied; `set`, `unset`, and `reset` edit the user file.
+    """
+    args = list(arguments) or ["list"]
+    action = args[0]
+    if action == "project":
+        return _configure_project(args[1:])
+    if action == "path" and len(args) == 1:
+        return str(preferences_path())
+    if action == "list" and len(args) == 1:
+        data = _effective_data()
+        return json.dumps({key: _effective(data, key) for key in SETTINGS}, indent=2)
+    if action == "diff" and len(args) == 1:
+        return _diff()
+    if action == "get" and len(args) == 2:
+        key = args[1]
+        _setting(key)
+        value = _effective(_effective_data(), key)
+        return "null" if value is None else value
+    if action == "set" and len(args) == 3:
+        key, value = args[1:]
+        _setting(key).validate(key, value)
+        update_preferences({key: value})
+        return f"Saved global default: {key} = {value}. Applies on next launch."
+    if action == "unset" and len(args) == 2:
+        key = args[1]
+        setting = _setting(key)
+        update_preferences({}, remove=(key,))
+        value = setting.default if setting.default is not None else "null (offline preview)"
+        return f"Reset global default: {key} = {value}. Applies on next launch."
+    if action == "reset" and len(args) == 1:
+        return _reset(None, "global")
+    raise ValueError(f"Usage: {USAGE}")
+
+
+def config_argument_descriptions() -> dict[str, str]:
+    """Completion-menu text: the setting's purpose beside each key, its default beside values."""
+    described: dict[str, str] = {
+        "list": "Show every effective setting",
+        "diff": "Show only settings that differ from their defaults",
+        "path": "Print the user preferences file",
+        "get": "Show one effective setting",
+        "set": "Save a user default (applies on next launch)",
+        "unset": "Remove a user default",
+        "reset": "Remove every user default",
+        "project": "Edit the workspace's .pcode/preferences.json",
+        "project list": "Show the project file",
+        "project path": "Print the project preferences file",
+        "project reset": "Remove every project default",
+    }
+    for key, setting in SETTINGS.items():
+        default = "unset" if setting.default is None else setting.default
+        text = f"{setting.description} (default {default})" if setting.description else ""
+        for action in ("get", "unset", "set", "project set", "project unset"):
+            described[f"{action} {key}"] = text
+        for value in setting.choices:
+            marker = " (default)" if value == setting.default else ""
+            described[f"set {key} {value}"] = f"{setting.description}{marker}"
+            described[f"project set {key} {value}"] = described[f"set {key} {value}"]
+    return described
+
+
+def config_arguments() -> tuple[str, ...]:
+    """Complete subcommands, keys, and enum values with the existing completer."""
+    project_keys = [key for key in SETTINGS if key not in USER_ONLY]
+    return (
+        "list",
+        "diff",
+        "path",
+        "get",
+        "set",
+        "unset",
+        "reset",
+        "project",
+        *(f"get {key}" for key in SETTINGS),
+        *(f"unset {key}" for key in SETTINGS),
+        *(f"set {key}" for key in SETTINGS),
+        *(f"set {key} {value}" for key, setting in SETTINGS.items() for value in setting.choices),
+        "project list",
+        "project path",
+        "project reset",
+        *(f"project set {key}" for key in project_keys),
+        *(f"project unset {key}" for key in project_keys),
+        *(f"project set {key} {value}" for key in project_keys for value in SETTINGS[key].choices),
+    )

pcode/context_breakdown.py

@@ -0,0 +1,178 @@
+"""Attribute fixed prompt overhead to the thing that contributed it.
+
+`context_usage` reports one number for the whole request, which says nothing
+about *why* it is that large. Pydantic AI already tags every instruction part
+with the capability that authored it, so the breakdown here is a grouping of
+`ModelRequestParameters`, not a second estimate of the prompt.
+
+Repository instructions arrive as one part holding several `<context-file>`
+blocks; they are split for display only. Nothing in this module changes what is
+sent, so a wrong label can never cost a cache hit.
+"""
+
+import json
+import re
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from pcode.context_usage import compact_tokens
+
+# `compaction.schema_tokens` uses the same divisor. Provider tokenizers disagree
+# with each other anyway; a consistent estimate keeps these rows comparable with
+# the compaction threshold that acts on them.
+CHARS_PER_TOKEN = 4
+
+# An instruction part is attributed to its source only when that source has an
+# `id`, so pcode names the ones it constructs (see `agent.create_coder`) and reads
+# Harness's own ids for the rest. Anything unlisted falls back to the bare id.
+REPO_CONTEXT = "repo_context"
+SOURCE_LABELS = {
+    REPO_CONTEXT: "Repository context",
+    "code_mode": "Code mode",
+    "file_tools": "File tools",
+    "mcp_servers": "MCP servers",
+    "planning": "Planning tool",
+    "sub_agents": "Sub-agents",
+    "tool_output_limits": "Tool output limits",
+    "ext.web_research": "Web research",
+}
+AGENT_LABEL = "Terminal instructions"
+# Coder's base prompt is a concrete `Capability`, which attributes its
+# instructions at construction and so cannot be named after the fact.
+ANONYMOUS_LABEL = "Harness base prompts"
+
+CONTEXT_FILE = re.compile(r'<context-file path="(?P<path>[^"]*)">\n.*?\n</context-file>', re.DOTALL)
+ASSISTANT_CONFIG = re.compile(
+    r"<assistant-configuration>\n.*?\n</assistant-configuration>", re.DOTALL
+)
+
+
+def estimate_tokens(text: str) -> int:
+    return len(text) // CHARS_PER_TOKEN
+
+
+@dataclass(frozen=True)
+class Row:
+    """One attributed slice of the fixed prompt overhead."""
+
+    label: str
+    tokens: int
+    detail: str = ""
+
+
+def source_id(part) -> str | None:
+    """Name the capability that authored `part`; None for the agent's own or anonymous."""
+    return getattr(getattr(getattr(part, "id", None), "source", None), "id", None)
+
+
+def _short(path: str) -> str:
+    """Shorten a home-relative instruction path the way a shell prompt would."""
+    candidate = Path(path)
+    return (
+        f"~/{candidate.relative_to(Path.home())}"
+        if candidate.is_absolute() and candidate.is_relative_to(Path.home())
+        else path
+    )
+
+
+def _asset_detail(block: str) -> str:
+    """Count the discovered assets the block lists, without re-scanning the disk."""
+    try:
+        inventory = next(
+            (json.loads(line) for line in block.splitlines() if line.startswith("{")), None
+        )
+    except ValueError:
+        # An unreadable inventory is still a measurable number of tokens, and
+        # /status must not be the thing that fails on it.
+        inventory = None
+    if inventory is None:
+        return "paths only"
+    counts = [
+        (sum(len(root.get(key, ())) for root in inventory.get("roots", ())), noun)
+        for key, noun in (("skills", "skill"), ("agents", "agent"))
+    ]
+    listed = ", ".join(f"{count} {noun}" for count, noun in counts if count)
+    return f"paths only · {listed}" if listed else "paths only · nothing discovered"
+
+
+def repo_rows(text: str) -> Iterator[Row]:
+    """Split repository context into the instruction files and the asset inventory."""
+    remainder = text
+    for match in CONTEXT_FILE.finditer(text):
+        remainder = remainder.replace(match.group(), "", 1)
+        yield Row(_short(match["path"]), estimate_tokens(match.group()), "instructions")
+    if config := ASSISTANT_CONFIG.search(text):
+        remainder = remainder.replace(config.group(), "", 1)
+        yield Row(
+            "Assistant config", estimate_tokens(config.group()), _asset_detail(config.group())
+        )
+    if leftover := remainder.strip():
+        yield Row(SOURCE_LABELS[REPO_CONTEXT], estimate_tokens(leftover))
+
+
+def instruction_rows(parts: Sequence) -> list[Row]:
+    """One row per instruction source, largest first, with repository context expanded."""
+    rows: list[Row] = []
+    anonymous = 0
+    for part in parts or ():
+        identity = source_id(part)
+        if identity == REPO_CONTEXT:
+            rows.extend(repo_rows(part.content))
+        elif identity:
+            rows.append(Row(SOURCE_LABELS.get(identity, identity), estimate_tokens(part.content)))
+        elif getattr(part, "id", None) is None:
+            anonymous += estimate_tokens(part.content)
+        else:
+            rows.append(Row(AGENT_LABEL, estimate_tokens(part.content)))
+    if anonymous:
+        rows.append(Row(ANONYMOUS_LABEL, anonymous))
+    return sorted(rows, key=lambda row: -row.tokens)
+
+
+def tool_rows(parameters) -> list[Row]:
+    """Size each tool the way `compaction.schema_tokens` sizes them in aggregate."""
+    return sorted(
+        (
+            Row(
+                tool.name,
+                estimate_tokens(json.dumps(tool.parameters_json_schema) + (tool.description or "")),
+            )
+            for tool in [*parameters.function_tools, *parameters.output_tools]
+        ),
+        key=lambda row: -row.tokens,
+    )
+
+
+def overhead_rows(parameters, *, window: int | None = None) -> list[tuple[str, str]]:
+    """Label/value rows describing the fixed cost of the last request's prompt.
+
+    Fixed means what the provider is re-sent whatever the conversation did:
+    instructions and tool schemas, never message history.
+    """
+    instructions = instruction_rows(parameters.instruction_parts or [])
+    tools = tool_rows(parameters)
+    prompt = sum(row.tokens for row in instructions)
+    schemas = sum(row.tokens for row in tools)
+    total = prompt + schemas
+    share = f" · {total * 100 // window}% of {compact_tokens(window)}" if window else ""
+    rows = [
+        ("Prompt overhead", f"~{compact_tokens(total)} tokens{share} · estimated"),
+        ("  Instructions", f"~{compact_tokens(prompt)}"),
+    ]
+    for row in instructions:
+        rows.append(
+            (
+                f"    {row.label}",
+                f"~{compact_tokens(row.tokens)}" + (f" · {row.detail}" if row.detail else ""),
+            )
+        )
+    rows.append(("  Tool schemas", f"~{compact_tokens(schemas)} · {len(tools)} tools"))
+    if tools:
+        rows.append(
+            (
+                "    Largest",
+                " · ".join(f"{row.label} {compact_tokens(row.tokens)}" for row in tools[:5]),
+            )
+        )
+    return rows