mainframe

Pi + MAINFRAME Integration

MAINFRAME provides a generated registry of Bash functions and libraries for safe, portable agent shell work. Pi can use MAINFRAME through both Pi-native tools and normal bash sourcing.

Preferred Pi workflow

1. Check readiness first

   • Run /mainframe doctor for the live in-process verdict, or use mainframe_status with validation when tool output is preferable.
   • Confirm the exact Pi compatibility tier, canonical package root, seven tools, three hooks, verified gate, protected Bash, and core doctor status.
   • Treat LIMITED, COMPATIBILITY_UNVERIFIED, SETUP_REQUIRED, and RELOAD_REQUIRED as not ready even if individual runtime checks pass.

2. Discover before inventing

   • Use mainframe_search with purpose="script" (the default) for topics such as json, validate path, atomic write, awm, git, http, or retry.
   • Use purpose="execute" when selecting a function for mainframe_exec; this excludes functions that require a specialized Pi tool or an external human terminal.
   • Search results resolve through the canonical manifest and report risk, purity, idempotence, examples, and an explicit execution disposition. Relevance stays primary; those fields are decision aids, not proof that a script is safe.
   • Use mainframe_help for exact details of a specific function.

3. Execute with guardrails

   • Use mainframe_exec only for one explicitly named MAINFRAME function at a time.
   • Use bounded timeouts.
   • Stable-core functions run through the canonical mainframe invoke broker; Pi maps the public function name to its reviewed canonical ID and closed named-input contract. Every function outside stable-core stays on Pi's guarded legacy path and requires Pi to show a human confirmation; model text or an environment variable cannot approve it.
   • Treat executionDisposition="specialized-tool-required" as a route to the purpose-built Pi tool (for example, mainframe_awm), not permission to force the function through mainframe_exec.
   • Do not grant approval for high-risk or side-effecting functions unless the user explicitly approved that action.