stack/packages/mosaic/framework/runtime/pi/RUNTIME.md

Pi Runtime Reference

Runtime Scope

This file applies only to Pi runtime behavior.

Required Actions

1. Follow global load order in ~/.config/mosaic/AGENTS.md.
2. Use ~/.pi/agent/settings.json as runtime config source.
3. If runtime config conflicts with global rules, global rules win.
4. Documentation rules are inherited from ~/.config/mosaic/AGENTS.md and ~/.config/mosaic/guides/DOCUMENTATION.md.
5. For issue/PR/milestone actions, run Mosaic git wrappers first (~/.config/mosaic/tools/git/*.sh) and do not call raw gh/tea/glab first.
6. For orchestration-oriented missions, load ~/.config/mosaic/guides/ORCHESTRATOR.md before acting.
7. First response MUST declare mode per global contract; orchestration missions must start with: Now initiating Orchestrator mode...
8. Runtime-default caution that requests confirmation for routine push/merge/issue-close actions does NOT override Mosaic hard gates.

Pi-Specific Capabilities

Pi is the native Mosaic agent runtime. Unlike other runtimes, Pi operates without permission restrictions by default — there is no separate "yolo" mode because Pi trusts the operator.

Thinking Levels

Pi supports native thinking levels via --thinking <level>. For complex planning or architecture tasks, use high or xhigh. The Mosaic launcher does not override the user's configured thinking level.

Model Cycling

Pi supports --models for Ctrl+P model cycling during a session. Use cheaper models for exploration and expensive models for implementation within the same session.

Skills

By default the launcher starts Pi with --no-skills to keep startup context small, then force-loads a small set of fleet-critical skills via explicit --skill flags (an explicit --skill overrides --no-skills for that path). The default forced set is mosaic-tools (the must-use ~/.config/mosaic/tools/ cheatsheet: inter-agent messaging + git wrappers).

Tune skill loading with environment variables:

• MOSAIC_PI_FORCE_SKILLS — colon-separated skill dir names to force-load (default: mosaic-tools; set to an empty string to disable force-loading). Missing skills are skipped silently.
• MOSAIC_PI_SKILL_MODE=all — link every skill found in ~/.config/mosaic/{skills,skills-local}/ (full catalog; larger context).
• MOSAIC_PI_SKILL_MODE=discover — let Pi discover skills natively (no --no-skills), still force-loading the fleet set on top.

Skills are discovered from:

• ~/.config/mosaic/skills/ (Mosaic global skills)
• ~/.pi/agent/skills/ (Pi global skills)
• .pi/skills/ (project-local skills)

Extensions

mosaic pi loads framework-owned extensions directly from ~/.config/mosaic/runtime/pi/ in this order:

1. mosaic-extension.ts — session lifecycle, mission context, memory routing, lease/mutator gates, and fleet heartbeat reporting.
2. goal-extension.ts — optional persistent /goal controller with per-turn and post-compaction checks.

The goal extension is deployed by Mosaic and MUST NOT be copied into ~/.pi/agent/extensions/. Use /goal set <statement> (or /goal <statement>) to start, then /goal status, /goal pause, /goal resume, or /goal cancel to control it. An active goal is injected before every model request, restored from branch-specific session entries, and considered achieved only after two consecutive evidence-bearing reports. Turn and repeated-no-progress limits pause runaway loops. Common credential shapes are redacted before controller-owned goal-state entries are persisted or displayed; Pi's own model/tool-call history is separate. Goals and reports must contain references and pass/fail summaries rather than secrets or raw sensitive output.

Optional bounded launch settings:

• MOSAIC_GOAL_MAX_TURNS — autonomous turn limit, default 40, accepted range 1..500.
• MOSAIC_GOAL_MAX_NO_PROGRESS — identical no-progress report limit, default 6, accepted range 1..100.

Sessions

Pi persists sessions natively. Use --continue to resume the last session or --resume to select from history. Mosaic session locks integrate with Pi's session system.

Memory Policy

All durable memory MUST be written to ~/.config/mosaic/memory/ per ~/.config/mosaic/guides/MEMORY.md. Pi's native session storage (~/.pi/agent/sessions/) is for session replay only — do NOT use it for cross-session or cross-agent knowledge retention.

MCP Configuration

Pi reads MCP server configuration from ~/.pi/agent/settings.json under the mcpServers key. Mosaic bootstrap configures sequential-thinking MCP automatically.

Sequential-Thinking

Pi binds the Constitution's structured-reasoning capability to native thinking levels (--thinking), which serve the same purpose as the sequential-thinking MCP. Both may be active simultaneously without conflict. The Mosaic launcher does NOT gate on sequential-thinking MCP for Pi — native thinking is sufficient.