API Reference super_pi v#0.1.0

Documentation for SuperPi.

Agent Client Protocol agent over stdio: bin/super-pi acp.

One ACP session: its id, its conversation, the renderer state and the running prompt.

Direct Google Generative AI (Gemini) client with SSE streaming, tool-calling schemas, and cross-provider model normalization (spec.md §3).

Behaviour for a model provider.

Provider registry. Selects the SuperPi.AI.Provider that serves a model.

Anthropic Messages API (claude-*).

Google Gemini provider. Wraps SuperPi.AI.GeminiClient.

Streams one request to an SSE model API and normalizes the events (SuperPi.AI.StreamNormalizer). Shared by the Anthropic and OpenAI providers.

Echo provider for tests and demos. Active only when config :super_pi, mock_llm: true.

OpenAI Chat Completions and Responses APIs (gpt-*, o1*, o3*, o4*).

Unified multi-provider LLM SSE stream normalizer and cross-provider message sanitizer (REQ-PBT-04).

JSON Schema ("type": "object") for the built-in tools, which are registered with a name and a description only. The providers send these as the tool's parameter schema.

Virtual Model Router and Prompt-Cache Session Affinity Manager (spec.md §4, Step 5).

Explicit storage for files that an agent wants to keep.

Artifact store in the repo (artifacts table): PostgreSQL, or SQLite on a single node.

Backend contract for SuperPi.Artifacts. Validation (name, size) happens before a call, so a backend only stores and fetches. Implement it for another store, such as an S3-compatible bucket.

Runs artifact_put, artifact_get and artifact_list for a conversation and its workspace.

Bearer-token authentication and conversation ownership for the Gateway and RPC server.

Unified Command-Line Interface for Super-Pi-BEAM.

The distributed BEAM cluster: nodes connected by libcluster, one shared PostgreSQL, one machine per conversation (SuperPi.Conversation.Locator).

Deterministic Codemode Replay Journal (Decision 07, Step 8).

4-Mode Context Compaction Engine (Decision 08, REQ-PBT-06).

Finds, or starts, the one machine of a conversation. The machine is unique in the whole cluster: its name is registered in Horde.Registry, so a request that lands on any node reaches the same process (a pid on another node works with Machine.submit/3 and the rest of the API).

Runtime Conversation Turn Coordinator (:gen_statem with [:handle_event_function, :state_enter]) synchronized with durable Fsmx tasks (SuperPi.Durable.TaskEngine) and the 12-hook SuperPi.Extension pipeline (REQ-FSM-01..REQ-FSM-06, 09 - Data Flows and Extension Injection Points.md).

Multi-Tier Customization Discovery Engine (23 - Deprecating AGY and Unifying Workspace Plugins and CLI.md).

Graceful shutdown of a node (REQ-CLU-07).

Normative 10-Rule Context Derivation Engine (packages/durable/docs/spec.md §2.1).

Implements pi-durable deferred commit batching (REQ-DUR-04, REQ-DUR-05).

Scoped JSON document manager supporting latest and rewindable (fork: "as_of") policies.

Keeps the document cache (SuperPi.Durable.Doc) coherent across nodes.

A durable note of the Memory plugin (memories table).

A typed edge between two notes of one scope (memory_links table): related, derived_from or supersedes. A supersedes edge also sets superseded_by_id on the older note.

A scheduled or webhook-triggered run (schedules table).

Durable conversation submission lifecycle managed with Fsmx.

Persisted durable task state machine managed with Fsmx (REQ-FSM-01..REQ-FSM-05).

Transactional durable storage engine (SuperPi.Durable.Storage) implementing

Durable task state machine scheduler (REQ-FSM-01..REQ-FSM-05, REQ-OBAN-01..REQ-OBAN-02).

Unified execution environment contract (SuperPi.Env, REQ-SAFE-01..REQ-SAFE-04).

Reads a file through the ACP client, so the agent sees the unsaved editor buffer.

Per-path advisory file lock server (REQ-SAFE-04, REQ-PBT-05).

Local host execution environment implementing SuperPi.Env.Behaviour (REQ-SAFE-01..REQ-SAFE-04).

4-Layer Safe Tool & Process Execution Sandbox (REQ-SAFE-01..REQ-SAFE-03, REQ-PBT-05).

Execution environment for a workspace on shared storage (NFS, CephFS, a read-write-many volume).

The workspace of a conversation: where file and command tools act.

The typed turn event: one schema that every interface renders.

The visible messages of a conversation in a neutral shape, for protocols that must replay history: the AG-UI MESSAGES_SNAPSHOT (a reconnect, or a compaction) and the ACP session/load.

Turns SuperPi.Events into the output of one protocol.

Renders events as Agent Client Protocol session/update payloads, for SuperPi.ACP.Server.

Renders events as AG-UI events, for SuperPi.Gateway.AGUI.

Renders events as OpenAI chat.completion.chunk maps for the Gateway's SSE stream.

Identity renderer for the JSON-RPC server: the wire map of an event is what a watcher receives. The server adds batching and backpressure (session.ack) on top.

Renders events for a terminal. The output is tagged, so the terminal code decides what to print

Unified 12-Hook Extension Pipeline behaviour (09 - Data Flows and Extension Injection Points.md).

AG-UI over Server-Sent Events, forwarded from SuperPi.Gateway.Router at /agui/v1. The router's authenticate, reject_when_draining and trace_request plugs already ran, so this module has no auth of its own.

OpenAI-Compatible Upstream Inference HTTP Router (REQ-GATEWAY-01, REQ-GATEWAY-02). Allows OpenCode, Cursor, Aider, LibreChat, and other AI clients to treat Super-Pi-BEAM as an upstream inference provider and agent runtime.

SuperPi HTTP Gateway Server for OpenAI-compatible client integrations (REQ-GATEWAY-01). Starts Bandit serving SuperPi.Gateway.Router on a configured port (default 4000).

Stored mapping from a client session id to a conversation, per principal.

Pluggable agent harness specification and registry (REQ-HARNESS-01).

Assistant harness (super-pi-assistant): works with a human present and reaches the web.

Coding harness (super-pi-code): mutates a repository, reversibly.

The use SuperPi.Harness macro, kept in a module with no runtime dependencies.

Builds the pi.agent defaults of a harness declared with use SuperPi.Harness.

Librarian harness (super-pi-librarian): runs with no human present and remembers.

Read-only planning harness (super-pi-planner).

Client for one Model Context Protocol server, over stdio or Streamable HTTP.

The MCP server over Streamable HTTP (revisions 2025-03-26 to 2025-06-18), as a Plug.

Starts the MCP servers from mcp_config.json and exposes their tools to the agent.

Model Context Protocol (MCP) server (REQ-MCP-01..REQ-MCP-04), over stdio here and over Streamable HTTP in SuperPi.MCP.HTTPPlug.

Sessions of the Streamable HTTP server (SuperPi.MCP.HTTPPlug): the id a client carries in Mcp-Session-Id, and the connection state that SuperPi.MCP.Server.handle_mcp_line/2 threads.

How SuperPi.MCP.Client talks to one MCP server. The client owns the protocol (handshake, request ids, timeouts); a transport only moves JSON-RPC messages.

Stdio transport: the server runs as an OS process and speaks one JSON-RPC 2.0 object per line.

Streamable HTTP transport (MCP 2025-03-26 and later) on Finch, with the deprecated HTTP+SSE transport (2024-11-05) as a fallback.

Durable notes that outlive a conversation: the store behind SuperPi.Plugins.Memory.

The memory index that the Memory plugin injects as the memory_index system section.

Lexical search over notes, without a vector store.

SQLite backend: the memories_fts FTS5 table, ranked by bm25() (title 10, topics 5, body 1).

Naive backend for tests, for a topic-only listing and for any storage without a native index.

PostgreSQL backend: the generated memories.search tsvector column under a GIN index, ranked by ts_rank_cd (title weight A, topics B, body C).

Plugin Registry & Dispatcher for Super-Pi-BEAM.

Auto-Commit Plugin (migrated from Pi ecosystem auto-commit-on-exit.ts).

Confirm Destructive Actions Plugin (migrated from Pi ecosystem confirm-destructive.ts).

Custom Compaction Plugin (migrated from Pi ecosystem custom-compaction.ts).

Git Checkpoint Plugin (migrated from Pi ecosystem git-checkpoint.ts).

Handoff & Context Distillation Plugin (migrated from Pi ecosystem handoff.ts).

Lifecycle Hooks Plugin (SuperPi.Extension behaviour).

Inline Bash Plugin (migrated from Pi ecosystem inline-bash.ts).

Jev Router Plugin (migrated from Pi ecosystem jev-router.ts).

Durable memory: notes that outlive a conversation, with search and links.

Permissions, Execution Modes, & Workspace Confinement Plugin (SuperPi.Extension behaviour).

Prompt Customizer Plugin (migrated from Pi ecosystem prompt-customizer.ts).

Protected Paths Plugin (migrated from Pi ecosystem protected-paths.ts).

Questionnaire Plugin (migrated from Pi ecosystem questionnaire.ts & question.ts).

Project & Agent Rules Plugin (SuperPi.Extension behaviour).

Scheduled and webhook-triggered runs: the tools schedule_create, schedule_list and schedule_cancel.

Progressive Disclosure Skills Plugin (SuperPi.Extension behaviour).

Interactive Slash-Command Expansion Plugin (SuperPi.Extension behaviour).

Structured Output Plugin (migrated from Pi ecosystem structured-output.ts).

Subagent Orchestration Plugin (migrated from Pi ecosystem subagent/).

Todo Task Ledger Plugin (migrated from Pi ecosystem todo.ts).

Dual-Write JSONL Transcript Logger & MCP/Plugin Manager (SuperPi.Extension behaviour).

Web access: web_fetch, and web_search when a search provider is configured.

Day-1 JSON-RPC 2.0 Server over TCP, Unix Domain Socket, and stdio (REQ-RPC-01..REQ-RPC-05, REQ-PBT-07).

Release tasks. Run them before the new version takes traffic

Unified repository facade that dispatches to SuperPi.Repo.SQLite (default single-node WAL mode) or SuperPi.Repo.Postgres (a separate PostgreSQL instance; the only store a cluster of nodes can share) based on :storage_backend configuration.

Applies pending migrations when the application starts, so a fresh checkout works without a separate mix ecto.migrate step.

Scheduled and webhook-triggered runs: the logic behind SuperPi.Plugins.Scheduler, SuperPi.Workers.ScheduleTickWorker, SuperPi.Workers.ScheduleRunWorker and SuperPi.Triggers.

Cron expressions with time zones.

Day-1 Interactive Terminal UI built on Owl (Decision 10, Step 10).

Traces and metrics for conversations.

Built-in 3-Channel Tool Suite, 5 ToolExposure Modes, and Deferred tool_search Registry (Step 8).

Webhook triggers: POST /v1/triggers/:token.

Carries a question from a running turn to a client that can answer it, and the answer back. Works across nodes: the machine that asks and the client that answers can be on different nodes.

Hands a decision from before_tool to wrap_tool for the same tool call.

Asks a human whether a blocked tool call may run. Used by SuperPi.Plugins.Permissions and SuperPi.Plugins.Hooks.

Turns a fetched body into text a model can read: markdown for HTML, pretty JSON, plain text.

The HTTP side of web_fetch: one GET with the request-forgery policy, a decoded-byte cap and a deadline. It returns bytes and metadata. SuperPi.Web.Extract turns them into text.

Request-forgery policy for web_fetch: which URLs an agent may make the node request.

Search provider adapters for web_search.

Brave Search adapter (https://api.search.brave.com/res/v1/web/search).

SearxNG adapter. Needs an instance with the JSON format enabled (search.formats includes json in its settings.yml).

Tavily adapter (https://api.tavily.com/search).

Oban worker in :compaction queue that runs background (backgroundTokens) and threshold context compaction tasks (REQ-OBAN-02).

Oban worker in :generation_retry queue that wakes sleeping GenerationTask records when their rate-limit backoff deadline (sleep_until) expires (REQ-OBAN-01).

Oban worker in the :compaction queue that saves durable facts from the entries a compaction cuts.

Starts one fire of a schedule. Unique on [:schedule_id, :fire_at] forever (period: :infinity), where fire_at is the scheduled minute (or a webhook's Idempotency-Key), so a duplicate tick or a webhook retry inserts nothing. SuperPi.Schedule.run/2 then claims the fire with a conditional update, which makes an Oban retry or a Lifeline rescue harmless.

The one static Oban.Plugins.Cron entry ({"* * * * *", ScheduleTickWorker}). The cron leader inserts one tick job per minute for the whole cluster. The tick accounts for settled runs and enqueues a SuperPi.Workers.ScheduleRunWorker job for each due schedule (SuperPi.Schedule.tick/1).

Oban worker in the :subagents queue: runs one child conversation for delegate_subagent.

Oban worker in :verification queue for after_run (runEndTask) verification jobs.