Architecture

Copy Markdown View Source

pi_bridge is an isolated control plane. It does not run inside target projects.

Runtime boundaries

  • Control bridge — the supervised pi_bridge application started by the TypeScript extension.
  • Project worker — a separate dependencyless VM that loads the target Mix project without starting its application.
  • Application worker — the same isolated worker boundary with intentional target application startup.
  • Attached runtime — an explicitly configured distributed node inspected without starting another application copy.

Target-worker source is a manifest-driven bundle under priv/target. The control bridge resolves it with Application.app_dir/2; package layouts and compile-time source paths are not part of the runtime contract.

Supervision

The application callback owns all always-on infrastructure through the root supervisor:

  • transport task supervision;
  • eval and target registries/dynamic supervisors;
  • attached-runtime state;
  • the BEAM-to-pi LLM broker;
  • an optional-service supervisor for lazy plugin, session, agent, log, and mirror services.

Lazy services are transient supervised children. Normal shutdown removes them; unexpected exits restart them. Callers never unlink infrastructure processes or become their accidental owners.

Dependency direction

Pi.Transport is the outbound port used by domain code. Pi.Transport.Stdio is the concrete adapter and orchestration boundary. Plugins, sessions, and LLM code may emit through the port but must not call the stdio adapter.

Pi.Protocol.* defines wire values. TypeScript decodes stdio envelopes into a discriminated union before dispatch. The policy in .reach.exs enforces the transport/protocol/target-runtime dependency rules.

The output facade invokes its rendering protocol, while built-in protocol implementations live in a separate module boundary. This preserves the public output and protocol contracts without introducing an xref cycle.

Project context

Filesystem, git, Mix environment, and build paths flow through Pi.Project.Context. Helpers must not infer target identity from the control bridge's current working directory.