Appendix A — References and Further Reading

This book makes three kinds of statement and keeps them apart: what Pi’s documentation and exported types say (documented), what was run and recorded (observed), and what this book recommends (proposed). A reader who wants to check a claim needs to know which pile it came from, so this page says where the material lives.

External papers and projects do not define Pi’s behaviour. For Pi-specific claims, use the pinned documentation and declarations, inspect implementation where needed, and distinguish those sources from the book’s own recorded tests. The references below provide context and comparisons, not a substitute for that evidence.

How to read a citation here

The three source kinds below behave differently as evidence, and mixing them up is how a book’s bibliography turns into its weakest chapter. This is the same distinction the prose uses, applied to the sources themselves.

    flowchart TD
  Q{"What is the claim about?"}
  Q -->|"Pi behaviour"| D["Pi docs, declarations and source<br/>at the pinned 1.0.4 release"]
  Q -->|"A general agent finding"| R["Research paper<br/>identify its version and test setting"]
  Q -->|"A third-party design"| E["Repository<br/>inspect the commit and implementation"]
  D --> D2["Check the declared API against<br/>implementation and observed tests"]
  R --> R2["Attribute results to the study<br/>do not generalise beyond its sample"]
  E --> E2["Describe what that version implements<br/>do not infer superiority from existence"]
  D2 --> L["Keep source, version and<br/>evidence status attached to the claim"]
  R2 --> L
  E2 --> L
  

The final node is the rule to keep in mind. A paper about agents does not establish what Pi 1.0.4 implements; a live third-party repository may have changed since it was read. Preserve each source’s version, date and evidentiary role. An unpinned architectural comparison is a tentative interpretation, not a verified comparison of releases.

Pi primary sources

The book’s Pi-specific API claims are intended to be checked against release 1.0.4 rather than today’s latest documentation. Start by identifying the executable you actually invoked and locating its matching package. An npm global install and Pi’s standalone installer need not use the same directory:

pi --version
npm root -g
# For a global npm install, inspect:
# <npm-global-root>/@earendil-works/pi-coding-agent/
# For an installer, fork, or local install, locate the package used by that executable.

In the matching coding-agent package, consult docs/ for the written contracts, examples/extensions/ for examples and dist/ for exported declarations. Declarations describe the typed API; implementation and tests are still needed to establish runtime behaviour. The upstream source is earendil-works/pi. Read the changelog when behaviour differs across versions, and do not mistake a newer version’s declarations for the pinned 1.0.4 contract.

Agent loops and tool use

• ReAct — Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models, ICLR 2023, arXiv:2210.03629. A foundational demonstration of interleaving reasoning and tool-mediated action, not a claim to have invented every agent loop. It provides background for the turn structure in chapter 1; Pi’s exact event and tool contracts still come from Pi.

• Inside the Scaffold — Inside the Scaffold: A Source-Code Taxonomy of Coding Agent Architectures, Rombaut, arXiv:2604.03515. Surveys thirteen open-source coding-agent scaffolds at pinned commit hashes, and finds eleven of thirteen compose multiple loop primitives rather than relying on a single control structure. Its context-compaction taxonomy spans seven distinct strategies, and its tool counts range from zero to thirty-seven. The load-bearing point for this book: compaction is not one mechanism, and a “narrow runtime” is one point in a design space rather than the settled answer. Unrefereed preprint; treat its specifics as directional.

• Towards a Science of Scaling Agent Systems — Kim et al., arXiv:2512.08296. The arXiv abstract checked for this edition reports 180 configurations across four benchmarks (Finance-Agent, BrowseComp-Plus, PlanCraft and Workbench) and three model families, comparing five coordination architectures under standardised tools and token budgets. It reports cross-validated R² = 0.513, a +80.9% improvement from centralised coordination on parallelisable financial-reasoning tasks, and 39–70% degradation for multi-agent variants on sequential-reasoning tasks. The framework selected the best coordination strategy for 87% of held-out configurations. These are results of that study, not measurements of Pi; if citing an earlier manuscript version, identify its version separately.

  Our interpretation: adding coordination can help or hurt, depending on the task and architecture. The paper’s measured conditions support that warning, not a general rule that orchestration is bad or that the reported percentages transfer to other benchmarks or Pi installations. Preprint.

Agent–computer interfaces

• SWE-agent — Yang et al., SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering, arXiv:2405.15793, NeurIPS 2024. Treats the interface given to an agent as a design variable: with the model’s weights unchanged, a purpose-built agent-computer interface beats a default Linux-shell interface by 10.7 percentage points on SWE-bench Lite. The reason chapter 17 treats how a tool is presented as a decision rather than an afterthought.

• CodeAct — Wang et al., Executable Code Actions Elicit Better LLM Agents, ICML 2024, arXiv:2402.01030. It compares executable-code actions with alternative action formats across 17 models and reports up to 20% higher success rate in the studied settings. That headline is not automatically a 20-percentage-point improvement, nor evidence that every workload benefits.

  Included as a counterexample, not a universal replacement for schema-driven tools: executable code can make multi-tool composition easier, while structured tool calls offer a narrower, more inspectable action surface. The comparison depends on benchmark, model and action format. The study does not establish that code execution is the better choice for Pi’s security model, or that differences in closed-model training can be isolated from the reported format effects.

Context and memory

• MemGPT — Packer et al., MemGPT: Towards LLMs as Operating Systems, arXiv:2310.08560. Argues that long-running systems need explicit policies for what stays in active context. It supports the general principle behind chapter 4, but does not establish Pi’s compaction trigger; the chapter’s contextTokens > contextWindow − reserveTokens rule must be checked against Pi’s pinned implementation and settings.
• Lost in the Middle — Liu et al., Lost in the Middle: How Language Models Use Long Contexts, TACL 12 (2024), arXiv:2307.03172. Relevant to chapter 4’s warning that a large window is not the same as reliably usable attention. In the paper’s tested retrieval and question-answering settings, models often performed better when relevant material was near the beginning or end of a long context than in the middle. This is task- and model-dependent, not a universal positional law or an established usable-context threshold. The published TACL volume is 2024.
• The companion books Context From First Principles and Memory From First Principles develop admission, scope, survival, pruning and retrieval in general. This book only needs Pi’s concrete terms.

Evaluation and reliability

• τ-bench — Yao et al., τ-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains, ICLR 2025, arXiv:2406.12045. Introduces pass^k, the task-averaged probability of succeeding on all k trials under the benchmark’s repeated-run protocol. By contrast, pass@k concerns at least one success. The original paper reports GPT-4o with function calling at approximately 61% pass^1 on τ-retail and 35% on τ-airline, while pass^8 on retail is below 25%. That means a full set of eight successes is uncommon under the measured conditions; it does not mean that eight attempts each have a near-certain failure, or that 75% of all individual runs fail.

  For this book, the practical point is that a successful demo is one trial, not an estimate of repeated-run reliability. Chapter 41 distinguishes an observed all-k success fraction from an inferred probability and explains the sampling limitations; chapter 10 discusses finishable tasks. Do not transfer τ-bench percentages to Pi without measuring Pi on the relevant tasks.

• SWE-Bench Illusion — Liang, Garg & Zilouchian Moghaddam, arXiv:2506.12286. Probes model knowledge rather than evaluating agents: naming the buggy file from the issue description alone, and reproducing the ground-truth function from file context alone. State-of-the-art models reach up to 76% path accuracy from the issue text alone against up to 53% on repositories absent from SWE-bench, and verbatim function reproduction reaches up to 35% consecutive 5-gram accuracy on SWE-bench Verified and Full against up to 18% elsewhere. The paper’s own conclusion is deliberately hedged — gains “may be partially driven by memorization rather than genuine problem-solving” — and it argues for contamination-resistant benchmarks rather than declaring the leaderboards invalid.

• Does SWE-bench-Verified Test Agent Ability or Model Memory? — Prathifkumar, Mathews & Nagappan, arXiv:2512.10218. A separate study, with separate comparators, and it is the one that uses logically impossible tasks: it tests two Claude models on file localisation only, withholding repository context “to the extent the task should be logically impossible to solve”. Against comparable Python projects in BeetleBox and SWE-rebench, the models score roughly 3× higher on SWE-bench-Verified, and 6× higher at naming edited files with no project context at all — which it argues biases leaderboards toward agents that happen to use those models rather than toward strong agent design.

  Two papers, two findings, attributed separately on purpose. An earlier draft merged them into one bullet, which borrowed the memorisation framing for one and the impossible-task framing for the other. Any leaderboard number quoted alongside this book should carry the caveat, and the caveat belongs to a named paper.

Security, prompt injection and authority

• AgentDojo — Debenedetti et al., AgentDojo: A Dynamic Environment to Evaluate Prompt Injection Attacks and Defenses for LLM Agents, NeurIPS 2024 Datasets & Benchmarks Track, arXiv:2406.13352. A tool-using agent operating over untrusted data is a distinct security object, and the attack surface arrives through tool output rather than only through user input. Its results also show how weak the baseline is before any attack: the best model tested, Claude 3.5 Sonnet, solves only 78.2% of benign tasks with no attack present at all, and GPT-4o 69.0%. A benchmark where even the no-attack baseline is imperfect reinforces chapter 42’s distinction between correct task completion and security. These are results on AgentDojo’s simulated tasks, not failure rates for every agent or production workload.
• Pi’s own docs/security.md is the authority for Pi’s position, and chapter 42 quotes it directly. Third-party permission systems exist in the ecosystem and are good implementations of a decision layer; they are not Pi’s semantics and are not presented as such.

Agent runtimes and architecture

For the layering argument in chapters 1 and 11, the primary evidence is Pi’s own package graph. One number here is verified and the rest is not, so they are separated.

Verified. pi-agent-core at 1.0.4 imports @earendil-works/pi-ai, typebox, and relative modules only. Its two declared runtime dependencies are those first two, and every module specifier appearing in its dist/ is one of them or a relative path: zero interface imports. The transitive graph closes the question too — pi-ai depends on provider SDKs, telemetry and schema libraries, and on no UI or TUI package. The number is worth stating precisely because it is countable, and it is stated at 1.0.4 so that it cannot drift silently under a reader who is looking at a later release.

Not pinned. The four comparisons below are proposed — hedged reading, not a measured dependency graph. No release or commit for any of them is pinned anywhere in this repository, which means a reader cannot reproduce them and a release can move them. Treat the direction of each as the claim and not the detail.

• pydantic-ai — a framework worth comparing for typed model interactions and provider abstractions. Its optional dependencies and precise import boundaries must be checked against a pinned pyproject.toml before making a package-graph claim. No such comparison is verified here.
• smolagents — a useful comparison for code-executing agents and tool interfaces. A claim that a particular dependency is mandatory, or that the runtime cannot be embedded independently of a UI, needs a pinned distribution and an import-graph check. Neither is established here.
• opencode — distinguish the coding-agent project anomalyco/opencode from the opencode provider identifier used in Pi. Its repository contains multiple packages, but that fact alone does not establish independent runtime embeddability or a security boundary. The architecture comparison requires pinned source and dependency evidence; this edition does not claim which system isolates its loop more effectively.
• LangGraph — a useful point of comparison for explicit graph-based orchestration, persistence and state handling. The relevant packages and versions must be pinned before making an import-boundary or deployment-isolation claim. Release frequency alone does not make the architecture impossible to verify.

Pi ecosystem projects

These projects are leads for inspecting specific implementation ideas, not independent validation of their claims or comparative quality. The links are not pinned to commits for this edition, so their current implementations may differ from the descriptions. Check a particular revision before relying on its behaviour.

Comparative agent frameworks

pydantic-ai, smolagents, langgraph, mastra and opencode, read on the axes in chapter 1: where the provider boundary sits, where the loop lives, where state lives, and whether the runtime embeds independently of a UI.

This is a comparison checklist, not a ranking or a count of frameworks with clean boundaries. Without pinning all five to releases and tracing their imports, runtime state and UI dependencies, the book cannot establish which are independently embeddable or where each stores persistence. The measured statement retained here is narrower: pi-agent-core at 1.0.4 has zero interface imports in the inspected distribution. Use the four axes above to conduct a reproducible comparison rather than inferring one from repository layout.

Companion books

Applied AI is worth singling out: it argues for separating the runtime from the model so that models can be swapped, which is the substitutability argument. The argument this book makes is about layer ownership — which layer owns a decision — which is a different question and does not restate that one.