@maiaos/agent

The first-party Maia agent and managed worker, built on the official @mariozechner/pi-coding-agent SDK foundation.

This README describes the current package boundary. The normative target for activation, resources, extension behavior, Session attachment, and the Pi SDK TUI is docs/maia-agent/architecture.md.

maia agent is Pi rebranded for Maia, not a different agent interface. Pi SDK supplies the agent loop, model, provider, compaction, steering, TUI, session, and extension primitives. Extensions use the upstream Pi API and can register tools, slash commands, CLI flags, shortcuts, renderers, providers, and lifecycle hooks just as they can in standalone Pi. Maia adds its durable harness contract: exact Maia identities, Maia-owned resource paths, task and goal state, process boundaries, authorization, receipts, recovery, telemetry, and control-plane integration. It does not invoke an installed Pi CLI, use ~/.pi, or introduce a parallel plugin API.

Every public Maia Agent entry establishes PI_OFFLINE=1 and PI_SKIP_VERSION_CHECK=1 as permanent process invariants before constructing or running official Pi. With the pinned official Pi 0.73.1 SDK, these supported flags suppress automatic version, package-update, telemetry, and managed-tool download traffic at startup without disabling an explicitly selected model/provider transport. Inherited false-like values are overwritten rather than interpreted by Pi's inconsistent flag readers. Callers embedding @maiaos/agent should therefore dedicate that process to the Agent boundary.

Resource order follows the official Pi loader:

1. digest-pinned project extensions explicitly listed in .maia/maia.json;
2. reviewed Maia built-ins, which remain available even when discovered extensions are disabled.

maia agent -ne and maia agent --no-extensions preserve standalone Pi semantics: they skip discovered extensions without resolving or digesting configured Project extension paths, while an explicit -e/--extension path may still load. Reviewed Maia kernel extensions remain available because they are part of the harness contract rather than discovery. The switch intentionally leaves Skills and AGENTS.md unchanged.

The lean built-in surface currently includes:

• destructive-command safety;
• task and goal state keyed by the durable Maia session under the explicit private .maia state root;
• bounded, session-owned background processes that are stopped on session shutdown.

Managed workers bind state to the Maia session ID rather than the disposable in-memory Pi session ID. Durable history is rehydrated from Maia on activation. Session processes remain intentionally ephemeral; fire-and-forget jobs and reboot-durable services require Maia-owned job/daemon operations, idempotency, receipts, and recovery.

Direct parent/child messaging will be a narrow adapter to Maia-owned lineage, mailbox, idempotency, and delivery services. Durable daemon mutations likewise require Maia operation authorization. Factory scheduling, child creation, Codex account pools, provider-capacity allocation, and recursive orchestration belong to the separate maia swarm layer, not this package.

Project extension code executes with the agent process's operating-system permissions. Review it before pinning its digest. Pi extensions cannot bypass Maia's server-side operation authorization, confirmation, compare-and-set, idempotency, or receipt requirements.

The package also builds maia-agent-worker, a versioned NDJSON boundary for an out-of-process official-Pi session. It uses an in-memory Pi SessionManager; Maia durable history is supplied explicitly and Pi session files are not authoritative. A bounded, model-matched OAuth credential may be supplied during initialization and is installed in Pi's in-memory AuthStorage; the worker neither creates auth.json nor emits the credential. Request fingerprints retain only SHA-256 digests. Inputs, outputs, credentials, prompts, responses, history, and request identities are bounded. Duplicate request IDs replay a terminal result or fail on conflicting input.

The built-in destructive-command guard is a reviewed port from vllnt/pi-config's pi-safety extension, adapted from the forked package namespace to the official Pi extension API. The task, goal, and process tools are reduced Maia implementations informed by the reviewed pi-tasks, pi-goal, and pi-daemon contracts; they intentionally exclude Factory, fleet, hub, subagent, cron, terminal, and shared-account behavior.

The target terminal surface does not move durable state into this package. Local maia agent may use Pi SDK InteractiveMode; managed maia session attach renders the Node-owned Session timeline through a narrow PiTuiRenderer client adapter in apps/cli. Renderer failure detaches only the client and cannot terminate or mutate the Session.