Glossary
Canonical Pi terms used throughout the English and Vietnamese documentation.
These definitions follow the current Pi packages. Code identifiers, package names, commands, paths, configuration keys, and environment variables are always preserved exactly.
Why a glossary
Pi uses a small technical vocabulary consistently across its packages. These definitions make the source faster to read and keep the English and Vietnamese pages aligned. Preserve exact identifiers and package names. If a term is not listed here, read it as ordinary English unless the source defines it more narrowly. The Vietnamese edition may translate a general concept after giving its canonical English term on first use.
Agent
The runtime that sends context to a model, exposes tools, processes tool calls, and tracks state. The core implementation is published as @earendil-works/pi-agent-core.
Agent Loop
The repeated prompt -> model response -> tool calls -> tool results -> model response sequence that drives an agent turn. Pi exposes typed events while this loop runs.
Block
A typed item inside message content. Common block types include text, thinking, and toolCall. A toolResult message returns the output of a tool call.
Coding Agent
The Pi command-line application published as @earendil-works/pi-coding-agent. It adds the terminal UI, project context, managed tools, sessions, extensions, skills, and configuration around the agent runtime.
Compaction
The process of replacing older conversation context with a structured summary while keeping recent messages verbatim. Compaction lets a session continue before it exceeds the model's context window. See Chapter 9: Context Compaction.
Composition Root
The single startup boundary where concrete dependencies are created and connected to the interfaces used by the rest of the application. For example, a CLI composition root can construct the provider adapter, session store, and tools, then inject them into the agent runtime.
Context Window
The maximum number of tokens a model can process in one request. Pi estimates current usage and can compact older context before the request exceeds this limit.
Descriptor
A structured Model record containing the provider ID, model ID, API, capabilities, context limits, and pricing metadata. Models.getModel(provider, id) resolves one from a registered model collection.
Event
A typed update emitted by a model stream or the agent runtime. Model-stream events include start, text_start, text_delta, text_end, toolcall_start, toolcall_delta, toolcall_end, done, and error.
Extension
A TypeScript module loaded inside the coding-agent process. Extensions can register tools and commands, subscribe to lifecycle events, and customize behavior through the documented extension API.
Fail-closed
A safety behavior that rejects or stops an operation when a required decision is missing, invalid, or unavailable, instead of allowing the operation by default. For example, if a policy judge fails, a fail-closed tool gate records a rejected verdict and does not execute the tool.
Fixture
Fixed, reusable input, state, or expected output for one test or evaluation case. A fixture is the case data—for example, a conversation plus scripted model events—while a harness is the infrastructure that runs it.
Harness
Executable test or evaluation infrastructure that drives the system under test, loads fixtures, captures behavior, and reports results. A harness runs a fixture; it does not decide whether the result is acceptable unless it also invokes a judge.
Held-out Evaluation
An evaluation performed on cases excluded from implementation and prompt tuning. Comparing held-out evaluation results with results from the visible development set helps detect overfitting to known fixtures.
Judge
An evaluator—implemented by code, a model, or a human—that applies explicit criteria to an observed result. A judge produces a verdict; the harness only supplies the observation and records that outcome.
Managed Tools
The built-in read, write, edit, and bash tools supplied to the coding agent by default. Additional read-only tools such as grep, find, and ls can be enabled through tool options.
Message
A typed record passed through the model and agent layers. The Pi AI package defines SystemMessage, UserMessage, AssistantMessage, and ToolResultMessage; provider adapters translate these records to each provider's wire format.
Model Provider
The service that handles a model request, such as Anthropic, OpenAI, Google, Bedrock, or a compatible local server. A provider registration supplies models, authentication, and streaming functions to a Models collection.
Pi
The open-source agent toolkit maintained in the earendil-works/pi repository. Lowercase pi refers to the coding-agent CLI command.
Stable Pi core
The Pi 1.0 agent and Coding Agent surface released as a small, extensible foundation. The former experimental Agent Core harness and runtime subpaths were removed from the public exports; the separate Pi Durable package remains experimental.
Pi Durable
The separate experimental @earendil-works/pi-durable package for long-running agent applications with persisted Conversations, Tasks, recovery, and explicit Tool replay rules. It shares lower-level Pi packages but does not replace the Coding Agent or make its own APIs part of the stable Pi core. See Durable Harness for the runtime entry point.
Session
A persisted conversation history. The coding agent stores sessions as JSONL, supports branching, and can resume a previous branch. See Chapter 10: Session Management.
Skill
A reusable instruction file discovered from configured skill directories. A skill describes when it applies and provides task-specific guidance to the agent.
Stream
An AssistantMessageEventStream, which is both an async iterable of typed events and a handle for retrieving the final result.
Subagent
An agent launched to perform a bounded task on behalf of another agent. Pi supports subagent workflows through extensions and example implementations rather than treating one orchestration policy as part of the core loop.
System Prompt
The instruction text sent with model context. The coding agent assembles it from its defaults, project context files, command-line options, and extension contributions. See Chapter 8: Context Engineering.
Test Double
A controlled replacement for a real dependency during a test. For example, a scripted model-provider test double can emit deterministic stream events without network access, allowing the harness to exercise the agent loop reproducibly.
Tool
A function exposed to the model with a name, description, and TypeBox parameter schema. When the model returns a ToolCall, the agent validates the arguments, runs the matching implementation, and adds a ToolResultMessage.
Tool Use
The protocol sequence in which an assistant message contains a ToolCall and a later ToolResultMessage references that call by ID.
Provider Adapter
The provider-specific implementation that converts Pi messages and options to a provider request, then converts the provider response stream back to Pi events.
Turn
One assistant response plus the Tool batch accepted from that response, bounded by turn_start and turn_end. A single Agent run can contain multiple turns and therefore multiple model calls.
Verdict
The structured outcome produced by a judge, such as pass/fail, a score or label, and supporting reasons. The judge is the decision mechanism; the verdict is the recorded result.
Codemode
A Pi coding-agent execution mode that gives the model a JavaScript environment for orchestrating deferred tools. It exposes compact discovery metadata first, then loads and calls only the tools a script needs.
MCP server/Tool exposure
An MCP server supplies a default exposure, while toolExposure is the per-Tool override boundary. A direct Tool is declared to the model; a codemode Tool stays out of model declarations; a deferred Tool stays undeclared until tool_search loads it for direct model use; and a hidden Tool cannot be discovered or called. Eligible direct, codemode, and deferred Tools can all be invoked from Codemode; hidden Tools cannot.
Virtual Model
A registered model-like route whose selector chooses a physical model at request time. Session history records the Virtual Model identity while routing metadata preserves the selected physical target for the request.
physical model
The concrete provider and model descriptor selected behind a Virtual Model. Provider credentials, thinking support, token limits, and usage accounting come from this physical model.
Durable Harness
The experimental @earendil-works/pi-durable runtime entry point that owns durable storage, registered Tools, Conversations, Documents, and Tasks. After a process restart, it resumes durable Tasks from committed checkpoints. Interrupted Tool execution is rerun only when its replay policy is safe (replay: "safe"); unsafe execution becomes an error Tool result instead.
Submission
A durable handle returned when input or a write is admitted to a Conversation. It can be awaited or aborted independently; cancelling a wait does not cancel the durable work.
replay policy
A Tool declaration that states whether interrupted execution may be replayed. Only replay: "safe" authorizes the Durable Harness to rerun that Tool after recovery.