Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
46 lines (33 loc) · 3.01 KB

ARCHITECTURE.md

File metadata and controls

46 lines (33 loc) · 3.01 KB
Raw

Architecture

pi-control is a thin, in-process Pi extension. It runs no daemon, hosts no control plane, and keeps no second copy of Pi's state — every read and write goes through the live Pi host.

Pi host
  └─ extensions/pi-control/index.ts
       ├─ commands/        operator slash workflows (/pi-demo, /pi-verify, /pi-qa)
       ├─ tools.ts         five structured agent tools
       ├─ guardrails.ts    lifecycle + tool-call safety hooks
       └─ Pi context APIs  sessions, model, tools, state
skills/pi-control/SKILL.md  packaged operating guidance

Module ownership

Module Owns Never does
index.ts Extension bootstrap; registers commands, tools, guardrails Holds no state of its own
tools.ts pi_session, pi_model, pi_tool, pi_state, pi_verify Bypasses Pi's own session/model/tool APIs
guardrails.ts Denies destructive shell patterns and gates unsafe mutations before execution Intercepts anything outside control/shell patterns
commands/ Operator workflows that compose the tools Introduces separate state or side effects
skills/pi-control The capture → change → verify → report discipline for agents Loads tools itself; Pi does that from the manifest

Data flow

  1. Capture — pi_session inspect / pi_state save record the current runtime state.
  2. Change — pi_session fork|switch|compact, pi_model set|thinking, pi_tool set_active, pi_state restore mutate the live process.
  3. Verify — pi_verify session|model|tool|state asserts observable expectations against the same process.
  4. Report — evidence comes from tool outputs and session dumps, not from a parallel model of the world.

Guardrails sit in front of step 2: a denied mutation never reaches Pi's runtime.

Boundaries

State that belongs to durable project work is intentionally outside this package — use @groeponline/pi-missions. Browser/terminal capture, QA evidence recipes, and showcase rendering belong to @groeponline/pi-agent-control-extension. Operator cockpit surfaces (status bar, queue, Skill Studio) belong to @groeponline/pi-wishcraft.

Packaging

The npm package carries the extension entrypoint, the skill, and the hero assets declared in package.json (pi.extensions, pi.skills, pi.image). The verify:pi-package gate validates the manifest, resource existence, public metadata, gallery preview format, Pi core peer-dependency rules, and the final packed tarball on every PR and before every publish.

Testing

  • scripts/package-contract-runtime.test.mjs — contract-parser regressions
  • extensions/pi-control/tests/ — extension unit tests (npm test --prefix extensions/pi-control)
  • CI (publish-npm.yml) runs both plus the full gate, then publishes with provenance when the version is new