Extension factory, tool definition, events, UI context
These are the intended host contracts. They still require version-pinned verification.
Pi extension types ↗Reference · verified 2026-08-24
Architecture atlas
Use this page while reading or reviewing the code. It names the owner of each behavior, points to the narrow runtime seam, and keeps interpretation separate from direct evidence.
01
Owner map
Ask “who can make this state transition?” before asking where a symbol lives.
| Behavior | Owner | Primary seam | Source trace |
|---|---|---|---|
| Model turn and tool loop | Pi | Agent inside AgentSession | Agent state and queues ↗ |
| Session assembly and persistence | Pi | createAgentSession(), SessionManager | SDK factory ↗ |
| Agent tool contract | Shared seam | Pi executes; extension defines policy | Tool definition and execute ↗ |
| Child runtime assembly | pi-subagents | runAgent() configures a Pi session | Runner path ↗ |
| Records, queue, parent/child state | pi-subagents | AgentManager | Manager lifecycle ↗ |
| Nested delegation authority | pi-subagents | injected tools + ownership checks | Nested boundary ↗ |
| Child completion delivery | Shared seam | extension policy through Pi messages/events | Result routing ↗ |
| Fleet widget and viewer | pi-subagents | project components through Pi UI APIs | Fleet projection ↗ |
02
Topology vocabulary
Use these names consistently when a session tree and a delegation tree overlap.
Main session
The Pi session in which the extension is installed and the user or parent model calls Agent.
Root session ID
When present, the stable identifier used to group records beneath one main-session ownership tree; it is not another running session.
Top-level agent
A managed child spawned directly from the main session. Only its ordinary background form uses the default concurrency pool.
Parent and child
One immediate ownership edge. Control checks use that direct edge rather than granting every ancestor equal authority.
Nested agent
A child spawned by another managed agent through explicitly injected nested tools, under its own agent definition.
03
Coupling map
Not every reachable field has the same compatibility strength.
modelRegistry.runtime, extensionRunner, mutable tool hook
These seams make the integration effective and increase upgrade sensitivity.
Runtime and call-time hook ↗“Pi is the data plane; pi-subagents is the control plane.”
A useful model supported by several paths—not a literal upstream type or protocol name.
Trace the argument →04
Boundary checks
These phrases require narrower, operationally accurate meanings.
isolated: true
It narrows inherited extensions, skills, and context. It is not an OS process or security sandbox.
maxConcurrent: 10
The pool covers ordinary top-level background work. Foreground and nested runs follow different liveness rules.
inherit_context
It projects selected branch text. It does not clone the complete parent session or tool-result history.
worktree isolation
It changes the Git working directory. It does not contain filesystem access or include uncommitted parent changes.
scheduled execution
It is a timer-triggered call into the same manager, not an exactly-once durable job service.
persistent memory
It is prompt guidance plus ordinary Pi filesystem tools, separate from Pi session persistence.