Pi Integration Architecture

यह दस्तावेज़ बताता है कि Mayros कैसे pi-coding-agent और इसके sibling packages (pi-ai, pi-agent-core, pi-tui) के साथ अपनी AI एजेंट क्षमताओं को power करने के लिए integrate करता है।

अवलोकन

Mayros अपने messaging gateway architecture में AI coding एजेंट embed करने के लिए pi SDK का उपयोग करता है। Subprocess के रूप में pi spawn करने या RPC mode का उपयोग करने के बजाय, Mayros सीधे createAgentSession() के माध्यम से pi की AgentSession को import और instantiate करता है। यह embedded दृष्टिकोण प्रदान करता है:

Session lifecycle और event handling पर पूर्ण नियंत्रण
Custom tool injection (messaging, sandbox, channel-विशिष्ट actions)
प्रति channel/context system prompt customization
Branching/compaction समर्थन के साथ session persistence
Failover के साथ multi-account auth profile rotation
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	उद्देश्य
`pi-ai`	मुख्य 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 (Mayros के local TUI mode में उपयोग किया गया)

File संरचना

src/agents/
├── pi-embedded-runner.ts          # pi-embedded-runner/ से re-exports
├── pi-embedded-runner/
│   ├── run.ts                     # मुख्य entry: runEmbeddedPiAgent()
│   ├── run/
│   │   ├── attempt.ts             # Session setup के साथ single attempt logic
│   │   ├── params.ts              # RunEmbeddedPiAgentParams type
│   │   ├── payloads.ts            # Run results से response payloads बनाएं
│   │   ├── images.ts              # Vision model image injection
│   │   └── types.ts               # EmbeddedRunAttemptResult
│   ├── abort.ts                   # Abort error पता लगाना
│   ├── cache-ttl.ts               # Context pruning के लिए cache TTL tracking
│   ├── compact.ts                 # Manual/auto compaction logic
│   ├── extensions.ts              # Embedded runs के लिए pi extensions load करें
│   ├── extra-params.ts            # Provider-विशिष्ट 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                   # ModelRegistry के माध्यम से model resolution
│   ├── runs.ts                    # Active run tracking, abort, queue
│   ├── sandbox-info.ts            # System prompt के लिए sandbox info
│   ├── session-manager-cache.ts   # SessionManager instance caching
│   ├── session-manager-init.ts    # Session file initialization
│   ├── system-prompt.ts           # System prompt builder
│   ├── tool-split.ts              # Tools को builtIn vs custom में split करें
│   ├── 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              # Tools के लिए AbortSignal wrapping
├── 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/
└── ...

मुख्य Integration Flow

1. Embedded Agent चलाना

मुख्य entry point pi-embedded-runner/run.ts में runEmbeddedPiAgent() है:

typescript
import { 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 निर्माण

runEmbeddedAttempt() के अंदर (runEmbeddedPiAgent() द्वारा कहा जाता है), pi SDK का उपयोग किया जाता है:

typescript
import {
  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() pi के AgentSession events को subscribe करता है:

typescript
const 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,
});

Handle किए गए events में शामिल हैं:

message_start / message_end / message_update (streaming text/thinking)
tool_execution_start / tool_execution_update / tool_execution_end
turn_start / turn_end
agent_start / agent_end
auto_compaction_start / auto_compaction_end

4. Prompting

Setup के बाद, session को prompted किया जाता है:

typescript
await session.prompt(effectivePrompt, { images: imageResult.images });

SDK पूर्ण agent loop को handle करता है: LLM को भेजना, tool calls execute करना, responses streaming करना।

Tool Architecture

Tool Pipeline

Base Tools: pi की codingTools (read, bash, edit, write)
Custom Replacements: Mayros bash को exec/process से बदलता है, sandbox के लिए read/edit/write customize करता है
Mayros Tools: messaging, browser, canvas, sessions, cron, gateway, आदि
Channel Tools: Discord/Telegram/Slack/WhatsApp-विशिष्ट action tools
Policy Filtering: Profile, provider, agent, group, sandbox policies द्वारा filtered tools
Schema Normalization: Gemini/OpenAI quirks के लिए schemas cleaned
AbortSignal Wrapping: Abort signals का सम्मान करने के लिए wrapped tools

Tool Definition Adapter

pi-agent-core की AgentTool में pi-coding-agent के ToolDefinition से अलग execute signature है। pi-tool-definition-adapter.ts में adapter इसे bridge करता है:

typescript
export 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) => {
      return await tool.execute(toolCallId, params, signal, onUpdate);
    },
  }));
}

System Prompt निर्माण

System prompt buildAgentSystemPrompt() (system-prompt.ts) में बनाया जाता है। यह Tooling, Tool Call Style, Safety guardrails, Mayros CLI reference, Skills, Docs, Workspace, Sandbox, Messaging, Reply Tags, Voice, Silent Replies, Heartbeats, Runtime metadata के sections के साथ एक पूर्ण prompt assemble करता है, साथ ही Memory और Reactions जब enabled हों, और वैकल्पिक context files और extra system prompt content।

Session Management

Session Files

Sessions tree structure (id/parentId linking) के साथ JSONL files हैं। Pi का SessionManager persistence handle करता है:

typescript
const sessionManager = SessionManager.open(params.sessionFile);

Mayros इसे tool result safety के लिए guardSessionManager() के साथ wrap करता है।

Authentication & Model Resolution

Auth Profiles

Mayros प्रति provider कई API keys के साथ एक auth profile store maintain करता है:

typescript
const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile });

Profiles cooldown tracking के साथ failures पर rotate करते हैं:

typescript
await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir });
const rotated = await advanceAuthProfile();

पहलू	Pi CLI	Mayros Embedded
Invocation	`pi` command / RPC	SDK के माध्यम से `createAgentSession()`
Tools	डिफ़ॉल्ट coding tools	Custom Mayros tool suite
System prompt	AGENTS.md + prompts	Dynamic per-channel/context
Session storage	`~/.pi/agent/sessions/`	`~/.mayros/agents/<agentId>/sessions/` (या `$MAYROS_STATE_DIR/agents/<agentId>/sessions/`)
Auth	Single credential	Rotation के साथ multi-profile
Extensions	Disk से loaded	Programmatic + disk paths
Event handling	TUI rendering	Callback-based (onBlockReply, आदि)

Tests

Pi integration और इसके extensions को कवर करने वाले सभी मौजूदा tests:

src/agents/pi-embedded-block-chunker.test.ts
src/agents/pi-embedded-helpers.*.test.ts
src/agents/pi-embedded-runner*.test.ts
src/agents/pi-embedded-subscribe*.test.ts
src/agents/pi-extensions/*.test.ts
src/agents/pi-settings.test.ts
src/agents/pi-tool-definition-adapter.test.ts
src/agents/pi-tools*.test.ts

Pi Integration Architecture

अवलोकन

Package Dependencies

File संरचना

मुख्य Integration Flow

1. Embedded Agent चलाना

2. Session निर्माण

3. Event Subscription

4. Prompting

Tool Architecture

Tool Pipeline

Tool Definition Adapter

System Prompt निर्माण

Session Management

Session Files

Authentication & Model Resolution

Auth Profiles

Pi Extensions

Compaction Safeguard

Context Pruning

Pi CLI से मुख्य अंतर

Tests

उत्पाद

कंपनी

समर्थन

कानूनी