Pi Integration Architecture
This document describes how Mayros integrates with pi-coding-agent and its sibling packages (pi-ai, pi-agent-core, pi-tui) to power its AI agent capabilities.
Overview
Mayros uses the pi SDK to embed an AI coding agent into its messaging gateway architecture. Instead of spawning pi as a subprocess or using RPC mode, Mayros directly imports and instantiates pi's AgentSession via createAgentSession(). This embedded approach provides:
- Full control over session lifecycle and event handling
- Custom tool injection (messaging, sandbox, channel-specific actions)
- System prompt customization per channel/context
- Session persistence with branching/compaction support
- Multi-account auth profile rotation with failover
- Provider-agnostic model switching
Package Dependencies
json{ "@mariozechner/pi-agent-core": "0.49.3", "@mariozechner/pi-ai": "0.49.3", "@mariozechner/pi-coding-agent": "0.49.3", "@mariozechner/pi-tui": "0.49.3" }
| Package | Purpose |
|---|---|
pi-ai | Core LLM abstractions: Model, streamSimple, message types, provider APIs |
pi-agent-core | Agent loop, tool execution, AgentMessage types |
pi-coding-agent | High-level SDK: createAgentSession, SessionManager, AuthStorage, ModelRegistry, built-in tools |
pi-tui | Terminal UI components (used in Mayros's local TUI mode) |
File Structure
src/agents/
βββ pi-embedded-runner.ts # Re-exports from pi-embedded-runner/
βββ pi-embedded-runner/
β βββ run.ts # Main entry: runEmbeddedPiAgent()
β βββ run/
β β βββ attempt.ts # Single attempt logic with session setup
β β βββ params.ts # RunEmbeddedPiAgentParams type
β β βββ payloads.ts # Build response payloads from run results
β β βββ images.ts # Vision model image injection
β β βββ types.ts # EmbeddedRunAttemptResult
β βββ abort.ts # Abort error detection
β βββ cache-ttl.ts # Cache TTL tracking for context pruning
β βββ compact.ts # Manual/auto compaction logic
β βββ extensions.ts # Load pi extensions for embedded runs
β βββ extra-params.ts # Provider-specific stream params
β βββ google.ts # Google/Gemini turn ordering fixes
β βββ history.ts # History limiting (DM vs group)
β βββ lanes.ts # Session/global command lanes
β βββ logger.ts # Subsystem logger
β βββ model.ts # Model resolution via ModelRegistry
β βββ runs.ts # Active run tracking, abort, queue
β βββ sandbox-info.ts # Sandbox info for system prompt
β βββ session-manager-cache.ts # SessionManager instance caching
β βββ session-manager-init.ts # Session file initialization
β βββ system-prompt.ts # System prompt builder
β βββ tool-split.ts # Split tools into builtIn vs custom
β βββ types.ts # EmbeddedPiAgentMeta, EmbeddedPiRunResult
β βββ utils.ts # ThinkLevel mapping, error description
βββ pi-embedded-subscribe.ts # Session event subscription/dispatch
βββ pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams
βββ pi-embedded-subscribe.handlers.ts # Event handler factory
βββ pi-embedded-subscribe.handlers.lifecycle.ts
βββ pi-embedded-subscribe.handlers.types.ts
βββ pi-embedded-block-chunker.ts # Streaming block reply chunking
βββ pi-embedded-messaging.ts # Messaging tool sent tracking
βββ pi-embedded-helpers.ts # Error classification, turn validation
βββ pi-embedded-helpers/ # Helper modules
βββ pi-embedded-utils.ts # Formatting utilities
βββ pi-tools.ts # createMayrosCodingTools()
βββ pi-tools.abort.ts # AbortSignal wrapping for tools
βββ pi-tools.policy.ts # Tool allowlist/denylist policy
βββ pi-tools.read.ts # Read tool customizations
βββ pi-tools.schema.ts # Tool schema normalization
βββ pi-tools.types.ts # AnyAgentTool type alias
βββ pi-tool-definition-adapter.ts # AgentTool -> ToolDefinition adapter
βββ pi-settings.ts # Settings overrides
βββ pi-extensions/ # Custom pi extensions
β βββ compaction-safeguard.ts # Safeguard extension
β βββ compaction-safeguard-runtime.ts
β βββ context-pruning.ts # Cache-TTL context pruning extension
β βββ context-pruning/
βββ model-auth.ts # Auth profile resolution
βββ auth-profiles.ts # Profile store, cooldown, failover
βββ model-selection.ts # Default model resolution
βββ models-config.ts # models.json generation
βββ model-catalog.ts # Model catalog cache
βββ context-window-guard.ts # Context window validation
βββ failover-error.ts # FailoverError class
βββ defaults.ts # DEFAULT_PROVIDER, DEFAULT_MODEL
βββ system-prompt.ts # buildAgentSystemPrompt()
βββ system-prompt-params.ts # System prompt parameter resolution
βββ system-prompt-report.ts # Debug report generation
βββ tool-summaries.ts # Tool description summaries
βββ tool-policy.ts # Tool policy resolution
βββ transcript-policy.ts # Transcript validation policy
βββ skills.ts # Skill snapshot/prompt building
βββ skills/ # Skill subsystem
βββ sandbox.ts # Sandbox context resolution
βββ sandbox/ # Sandbox subsystem
βββ channel-tools.ts # Channel-specific tool injection
βββ mayros-tools.ts # Mayros-specific tools
βββ bash-tools.ts # exec/process tools
βββ apply-patch.ts # apply_patch tool (OpenAI)
βββ tools/ # Individual tool implementations
β βββ browser-tool.ts
β βββ canvas-tool.ts
β βββ cron-tool.ts
β βββ discord-actions*.ts
β βββ gateway-tool.ts
β βββ image-tool.ts
β βββ message-tool.ts
β βββ nodes-tool.ts
β βββ session*.ts
β βββ slack-actions.ts
β βββ telegram-actions.ts
β βββ web-*.ts
β βββ whatsapp-actions.ts
βββ ...
Core Integration Flow
1. Running an Embedded Agent
The main entry point is runEmbeddedPiAgent() in pi-embedded-runner/run.ts:
typescriptimport { runEmbeddedPiAgent } from "./agents/pi-embedded-runner.js"; const result = await runEmbeddedPiAgent({ sessionId: "user-123", sessionKey: "main:whatsapp:+1234567890", sessionFile: "/path/to/session.jsonl", workspaceDir: "/path/to/workspace", config: mayrosConfig, prompt: "Hello, how are you?", provider: "anthropic", model: "claude-sonnet-4-20250514", timeoutMs: 120_000, runId: "run-abc", onBlockReply: async (payload) => { await sendToChannel(payload.text, payload.mediaUrls); }, });
2. Session Creation
Inside runEmbeddedAttempt() (called by runEmbeddedPiAgent()), the pi SDK is used:
typescriptimport { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent"; const resourceLoader = new DefaultResourceLoader({ cwd: resolvedWorkspace, agentDir, settingsManager, additionalExtensionPaths, }); await resourceLoader.reload(); const { session } = await createAgentSession({ cwd: resolvedWorkspace, agentDir, authStorage: params.authStorage, modelRegistry: params.modelRegistry, model: params.model, thinkingLevel: mapThinkingLevel(params.thinkLevel), tools: builtInTools, customTools: allCustomTools, sessionManager, settingsManager, resourceLoader, }); applySystemPromptOverrideToSession(session, systemPromptOverride);
3. Event Subscription
subscribeEmbeddedPiSession() subscribes to pi's AgentSession events:
typescriptconst subscription = subscribeEmbeddedPiSession({ session: activeSession, runId: params.runId, verboseLevel: params.verboseLevel, reasoningMode: params.reasoningLevel, toolResultFormat: params.toolResultFormat, onToolResult: params.onToolResult, onReasoningStream: params.onReasoningStream, onBlockReply: params.onBlockReply, onPartialReply: params.onPartialReply, onAgentEvent: params.onAgentEvent, });
Events handled include:
message_start/message_end/message_update(streaming text/thinking)tool_execution_start/tool_execution_update/tool_execution_endturn_start/turn_endagent_start/agent_endauto_compaction_start/auto_compaction_end
4. Prompting
After setup, the session is prompted:
typescriptawait session.prompt(effectivePrompt, { images: imageResult.images });
The SDK handles the full agent loop: sending to LLM, executing tool calls, streaming responses.
Tool Architecture
Tool Pipeline
- Base Tools: pi's
codingTools(read, bash, edit, write) - Custom Replacements: Mayros replaces bash with
exec/process, customizes read/edit/write for sandbox - Mayros Tools: messaging, browser, canvas, sessions, cron, gateway, etc.
- Channel Tools: Discord/Telegram/Slack/WhatsApp-specific action tools
- Policy Filtering: Tools filtered by profile, provider, agent, group, sandbox policies
- Schema Normalization: Schemas cleaned for Gemini/OpenAI quirks
- AbortSignal Wrapping: Tools wrapped to respect abort signals
Tool Definition Adapter
pi-agent-core's AgentTool has a different execute signature than pi-coding-agent's ToolDefinition. The adapter in pi-tool-definition-adapter.ts bridges this:
typescriptexport function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { return tools.map((tool) => ({ name: tool.name, label: tool.label ?? name, description: tool.description ?? "", parameters: tool.parameters, execute: async (toolCallId, params, onUpdate, _ctx, signal) => { // pi-coding-agent signature differs from pi-agent-core return await tool.execute(toolCallId, params, signal, onUpdate); }, })); }
Tool Split Strategy
splitSdkTools() passes all tools via customTools:
typescriptexport function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) { return { builtInTools: [], // Empty. We override everything customTools: toToolDefinitions(options.tools), }; }
This ensures Mayros's policy filtering, sandbox integration, and extended toolset remain consistent across providers.
System Prompt Construction
The system prompt is built in buildAgentSystemPrompt() (system-prompt.ts). It assembles a full prompt with sections including Tooling, Tool Call Style, Safety guardrails, Mayros CLI reference, Skills, Docs, Workspace, Sandbox, Messaging, Reply Tags, Voice, Silent Replies, Heartbeats, Runtime metadata, plus Memory and Reactions when enabled, and optional context files and extra system prompt content. Sections are trimmed for minimal prompt mode used by subagents.
The prompt is applied after session creation via applySystemPromptOverrideToSession():
typescriptconst systemPromptOverride = createSystemPromptOverride(appendPrompt); applySystemPromptOverrideToSession(session, systemPromptOverride);
Session Management
Session Files
Sessions are JSONL files with tree structure (id/parentId linking). Pi's SessionManager handles persistence:
typescriptconst sessionManager = SessionManager.open(params.sessionFile);
Mayros wraps this with guardSessionManager() for tool result safety.
Session Caching
session-manager-cache.ts caches SessionManager instances to avoid repeated file parsing:
typescriptawait prewarmSessionFile(params.sessionFile); sessionManager = SessionManager.open(params.sessionFile); trackSessionManagerAccess(params.sessionFile);
History Limiting
limitHistoryTurns() trims conversation history based on channel type (DM vs group).
Compaction
Auto-compaction triggers on context overflow. compactEmbeddedPiSessionDirect() handles manual compaction:
typescriptconst compactResult = await compactEmbeddedPiSessionDirect({ sessionId, sessionFile, provider, model, ... });
Authentication & Model Resolution
Auth Profiles
Mayros maintains an auth profile store with multiple API keys per provider:
typescriptconst authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false }); const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile });
Profiles rotate on failures with cooldown tracking:
typescriptawait markAuthProfileFailure({ store, profileId, reason, cfg, agentDir }); const rotated = await advanceAuthProfile();
Model Resolution
typescriptimport { resolveModel } from "./pi-embedded-runner/model.js"; const { model, error, authStorage, modelRegistry } = resolveModel( provider, modelId, agentDir, config, ); // Uses pi's ModelRegistry and AuthStorage authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);
Failover
FailoverError triggers model fallback when configured:
typescriptif (fallbackConfigured && isFailoverErrorMessage(errorText)) { throw new FailoverError(errorText, { reason: promptFailoverReason ?? "unknown", provider, model: modelId, profileId, status: resolveFailoverStatus(promptFailoverReason), }); }
Pi Extensions
Mayros loads custom pi extensions for specialized behavior:
Compaction Safeguard
pi-extensions/compaction-safeguard.ts adds guardrails to compaction, including adaptive token budgeting plus tool failure and file operation summaries:
typescriptif (resolveCompactionMode(params.cfg) === "safeguard") { setCompactionSafeguardRuntime(params.sessionManager, { maxHistoryShare }); paths.push(resolvePiExtensionPath("compaction-safeguard")); }
Context Pruning
pi-extensions/context-pruning.ts implements cache-TTL based context pruning:
typescriptif (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { setContextPruningRuntime(params.sessionManager, { settings, contextWindowTokens, isToolPrunable, lastCacheTouchAt, }); paths.push(resolvePiExtensionPath("context-pruning")); }
Streaming & Block Replies
Block Chunking
EmbeddedBlockChunker manages streaming text into discrete reply blocks:
typescriptconst blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null;
Thinking/Final Tag Stripping
Streaming output is processed to strip <think>/<thinking> blocks and extract <final> content:
typescriptconst stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => { // Strip <think>...</think> content // If enforceFinalTag, only return <final>...</final> content };
Reply Directives
Reply directives like [[media:url]], [[voice]], [[reply:id]] are parsed and extracted:
typescriptconst { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk);
Error Handling
Error Classification
pi-embedded-helpers.ts classifies errors for appropriate handling:
typescriptisContextOverflowError(errorText) // Context too large isCompactionFailureError(errorText) // Compaction failed isAuthAssistantError(lastAssistant) // Auth failure isRateLimitAssistantError(...) // Rate limited isFailoverAssistantError(...) // Should failover classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ...
Thinking Level Fallback
If a thinking level is unsupported, it falls back:
typescriptconst fallbackThinking = pickFallbackThinkingLevel({ message: errorText, attempted: attemptedThinking, }); if (fallbackThinking) { thinkLevel = fallbackThinking; continue; }
Sandbox Integration
When sandbox mode is enabled, tools and paths are constrained:
typescriptconst sandbox = await resolveSandboxContext({ config: params.config, sessionKey: sandboxSessionKey, workspaceDir: resolvedWorkspace, }); if (sandboxRoot) { // Use sandboxed read/edit/write tools // Exec runs in container // Browser uses bridge URL }
Provider-Specific Handling
Anthropic
- Refusal magic string scrubbing
- Turn validation for consecutive roles
- Claude Code parameter compatibility
Google/Gemini
- Turn ordering fixes (
applyGoogleTurnOrderingFix) - Tool schema sanitization (
sanitizeToolsForGoogle) - Session history sanitization (
sanitizeSessionHistory)
OpenAI
apply_patchtool for Codex models- Thinking level downgrade handling
TUI Integration
Mayros also has a local TUI mode that uses pi-tui components directly:
typescript// src/tui/tui.ts import { ... } from "@mariozechner/pi-tui";
This provides the interactive terminal experience similar to pi's native mode.
Key Differences from Pi CLI
| Aspect | Pi CLI | Mayros Embedded |
|---|---|---|
| Invocation | pi command / RPC | SDK via createAgentSession() |
| Tools | Default coding tools | Custom Mayros tool suite |
| System prompt | AGENTS.md + prompts | Dynamic per-channel/context |
| Session storage | ~/.pi/agent/sessions/ | ~/.mayros/agents/<agentId>/sessions/ (or $MAYROS_STATE_DIR/agents/<agentId>/sessions/) |
| Auth | Single credential | Multi-profile with rotation |
| Extensions | Loaded from disk | Programmatic + disk paths |
| Event handling | TUI rendering | Callback-based (onBlockReply, etc.) |
Future Considerations
Areas for potential rework:
- Tool signature alignment: Currently adapting between pi-agent-core and pi-coding-agent signatures
- Session manager wrapping:
guardSessionManageradds safety but increases complexity - Extension loading: Could use pi's
ResourceLoadermore directly - Streaming handler complexity:
subscribeEmbeddedPiSessionhas grown large - Provider quirks: Many provider-specific codepaths that pi could potentially handle
Tests
All existing tests that cover the pi integration and its extensions:
src/agents/pi-embedded-block-chunker.test.tssrc/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.tssrc/agents/pi-embedded-helpers.classifyfailoverreason.test.tssrc/agents/pi-embedded-helpers.downgradeopenai-reasoning.test.tssrc/agents/pi-embedded-helpers.formatassistanterrortext.test.tssrc/agents/pi-embedded-helpers.formatrawassistanterrorforui.test.tssrc/agents/pi-embedded-helpers.image-dimension-error.test.tssrc/agents/pi-embedded-helpers.image-size-error.test.tssrc/agents/pi-embedded-helpers.isautherrormessage.test.tssrc/agents/pi-embedded-helpers.isbillingerrormessage.test.tssrc/agents/pi-embedded-helpers.iscloudcodeassistformaterror.test.tssrc/agents/pi-embedded-helpers.iscompactionfailureerror.test.tssrc/agents/pi-embedded-helpers.iscontextoverflowerror.test.tssrc/agents/pi-embedded-helpers.isfailovererrormessage.test.tssrc/agents/pi-embedded-helpers.islikelycontextoverflowerror.test.tssrc/agents/pi-embedded-helpers.ismessagingtoolduplicate.test.tssrc/agents/pi-embedded-helpers.messaging-duplicate.test.tssrc/agents/pi-embedded-helpers.normalizetextforcomparison.test.tssrc/agents/pi-embedded-helpers.resolvebootstrapmaxchars.test.tssrc/agents/pi-embedded-helpers.sanitize-session-messages-images.keeps-tool-call-tool-result-ids-unchanged.test.tssrc/agents/pi-embedded-helpers.sanitize-session-messages-images.removes-empty-assistant-text-blocks-but-preserves.test.tssrc/agents/pi-embedded-helpers.sanitizegoogleturnordering.test.tssrc/agents/pi-embedded-helpers.sanitizesessionmessagesimages-thought-signature-stripping.test.tssrc/agents/pi-embedded-helpers.sanitizetoolcallid.test.tssrc/agents/pi-embedded-helpers.sanitizeuserfacingtext.test.tssrc/agents/pi-embedded-helpers.stripthoughtsignatures.test.tssrc/agents/pi-embedded-helpers.validate-turns.test.tssrc/agents/pi-embedded-runner-extraparams.live.test.ts(live)src/agents/pi-embedded-runner-extraparams.test.tssrc/agents/pi-embedded-runner.applygoogleturnorderingfix.test.tssrc/agents/pi-embedded-runner.buildembeddedsandboxinfo.test.tssrc/agents/pi-embedded-runner.createsystempromptoverride.test.tssrc/agents/pi-embedded-runner.get-dm-history-limit-from-session-key.falls-back-provider-default-per-dm-not.test.tssrc/agents/pi-embedded-runner.get-dm-history-limit-from-session-key.returns-undefined-sessionkey-is-undefined.test.tssrc/agents/pi-embedded-runner.google-sanitize-thinking.test.tssrc/agents/pi-embedded-runner.guard.test.tssrc/agents/pi-embedded-runner.limithistoryturns.test.tssrc/agents/pi-embedded-runner.resolvesessionagentids.test.tssrc/agents/pi-embedded-runner.run-embedded-pi-agent.auth-profile-rotation.test.tssrc/agents/pi-embedded-runner.sanitize-session-history.test.tssrc/agents/pi-embedded-runner.splitsdktools.test.tssrc/agents/pi-embedded-runner.test.tssrc/agents/pi-embedded-subscribe.code-span-awareness.test.tssrc/agents/pi-embedded-subscribe.reply-tags.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.calls-onblockreplyflush-before-tool-execution-start-preserve.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-append-text-end-content-is.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-call-onblockreplyflush-callback-is-not.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-duplicate-text-end-repeats-full.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-emit-duplicate-block-replies-text.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.emits-block-replies-text-end-does-not.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.emits-reasoning-as-separate-message-enabled.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.filters-final-suppresses-output-without-start-tag.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.includes-canvas-action-metadata-tool-summaries.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-assistanttexts-final-answer-block-replies-are.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-indented-fenced-blocks-intact.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.reopens-fenced-blocks-splitting-inside-them.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.splits-long-single-line-fenced-blocks-reopen.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.streams-soft-chunks-paragraph-preference.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.subscribeembeddedpisession.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.suppresses-message-end-block-replies-message-tool.test.tssrc/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.waits-multiple-compaction-retries-before-resolving.test.tssrc/agents/pi-embedded-subscribe.tools.test.tssrc/agents/pi-embedded-utils.test.tssrc/agents/pi-extensions/compaction-safeguard.test.tssrc/agents/pi-extensions/context-pruning.test.tssrc/agents/pi-settings.test.tssrc/agents/pi-tool-definition-adapter.test.tssrc/agents/pi-tools-agent-config.test.tssrc/agents/pi-tools.create-mayros-coding-tools.adds-claude-style-aliases-schemas-without-dropping-b.test.tssrc/agents/pi-tools.create-mayros-coding-tools.adds-claude-style-aliases-schemas-without-dropping-d.test.tssrc/agents/pi-tools.create-mayros-coding-tools.adds-claude-style-aliases-schemas-without-dropping-f.test.tssrc/agents/pi-tools.create-mayros-coding-tools.adds-claude-style-aliases-schemas-without-dropping.test.tssrc/agents/pi-tools.policy.test.tssrc/agents/pi-tools.safe-bins.test.tssrc/agents/pi-tools.workspace-paths.test.ts