Pi Runtime Integration
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- apps/noesis/test/application-acceptance.test.ts
- packages/domain/test/architecture.test.ts
- packages/runtime-pi/test/import-boundary.test.ts
- plans/noesis-autonomous-compounding-implementation-plan.html
- plans/noesis-first-complete-iteration.html
- plans/compounding-partnership-product-loop.html
The Pi Runtime Integration serves as the specialized adapter layer between the Noesis platform and the underlying Pi execution substrate. Its primary purpose is to encapsulate Pi-specific primitives, such as the AgentHarness, while providing an adapter-neutral interface to the rest of the Noesis system. This ensures that the core domain logic remains decoupled from the specific implementation details of the Pi SDK.
In the Noesis architecture, the Pi integration is strictly limited to turn execution. While Pi handles the mechanics of model interaction and tool execution, Noesis retains authority over turn interpretation, capability promotion, and the overall learning lifecycle.
Sources: AGENTS.md:15-17, plans/noesis-first-complete-iteration.html: Architecture Section
Architectural Boundary and Isolation
The integration is architecturally confined to the packages/runtime-pi package. This isolation is enforced through strict automated boundary tests that prevent Pi-specific types and imports from leaking into other modules, including the core runtime and the TUI application.
Strict Import Rules
The project enforces the following import constraints:
- Restricted Imports: Only
packages/runtime-piis permitted to import from@earendil-works/pi-aiand@earendil-works/pi-agent-core. - Dependency Direction:
packages/runtimeremains adapter-neutral and does not import frompackages/runtime-pi. Instead, the composition root (apps/noesis) injects the Pi-based implementations into the runtime. - Type Safety: Shared data structures between Noesis and the Pi integration use adapter-neutral types defined in
packages/agent-types.
Sources: packages/domain/test/architecture.test.ts:114-130, packages/runtime-pi/test/import-boundary.test.ts:1-25, plans/noesis-autonomous-compounding-implementation-plan.html:361-365
Core Components
| Component | Responsibility |
|---|---|
NoesisAgentRuntime | The public boundary interface implementing Noesis-specific agent behavior via Pi. |
createPiAgentRuntime | Factory function that initializes the Pi runtime with session tools and model providers. |
createPiAgentRoleRunner | Factory for executing specialized LLM roles (e.g., reflector, judge) using Pi configurations. |
AgentHarness | The Pi-native substrate used to stream provider responses and execute typed tools. |
Sources: plans/noesis-first-complete-iteration.html: Architecture Table, apps/noesis/test/application-acceptance.test.ts:25-30
Turn Execution Flow
Turn execution follows a strict "frozen plan" model. Before any interaction with the Pi substrate occurs, Noesis admits a FrozenTurnPlan (or TurnIntelligencePlan) to the workspace. This plan pins specific revisions of prompts, capabilities, and tools, ensuring that the Pi runtime executes against a stable and audit-able configuration.
Turn Orchestration Logic
- Plan Initialization: Noesis determines the collaboration posture and selects the required capability revisions.
- Tool Adaptation: Noesis-scoped tools and session retrieval executors are adapted to the Pi tool registration format.
- Execution: The Pi
AgentHarnessprocesses the turn using the pinned revisions and the provided context snapshot. - Settlement: Once the turn is complete, the results are persisted in the authoritative
WorkspaceStore.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:283-300, plans/compounding-partnership-product-loop.html: Loop Section
Sequence: Turn Execution via Pi Adapter
The following diagram illustrates how a turn is coordinated through the Pi integration layer.
The diagram shows the decoupled relationship where the Noesis Runtime manages the plan and uses the injected Pi Adapter for the actual execution mechanics.
Sources: plans/compounding-partnership-product-loop.html: Loop Section, apps/noesis/test/application-acceptance.test.ts:25-50
Configuration and Providers
The Pi integration supports credential-free execution for testing and integration purposes. In a development or CI environment, a "controlled Pi provider" is used to simulate model responses and tool traces without requiring actual provider credentials or paid model calls.
Controlled Provider Architecture
The controlled provider allows developers to:
- Mock role runner outputs for reflection, authorship, and evaluation.
- Simulate turn execution to verify that the "causal spine" (from activation to serving) is functioning correctly.
- Verify that served behavior matches the pinned capability revisions in the turn plan.
Sources: apps/noesis/test/application-acceptance.test.ts:20-25, plans/noesis-high-leverage-correction-plan.html: HL-08 Section
Deployment Responsibilities
| Module | Dependency Constraint | Role in Integration |
|---|---|---|
packages/runtime-pi | Imports Pi SDK | Implements NoesisAgentRuntime and role runners. |
packages/runtime | No Pi Imports | Orchestrates the turn plan and handles settlement. |
apps/noesis | Imports both | Composes the final application by injecting the adapter. |
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:361-367, packages/domain/test/architecture.test.ts:135-155
Conclusion
The Pi Runtime Integration is a critical boundary layer that enables Noesis to leverage the Pi execution substrate while maintaining strict architectural isolation. By enforcing this separation through automated tests and using a frozen turn plan architecture, the system ensures that Pi is used solely for execution, while the intelligence and authority remain within the Noesis domain.