Smithers package layout

projects/matrix-3/packages/smithers/ is a dual-build package: node build.mjs produces both the headless Node bundle and the browser bundle (vite build). The source tree is organised so the headless and browser halves do not bleed into each other.

Directory map

projects/matrix-3/packages/smithers/
├── matrix.json                    # Manifest (webapp + 4 components, autoStart SmithersSupervisor)
├── package.json                   # @open-matrix/smithers, deps include claude-agent + codex-agent + chat
├── README.md
├── DESIGN.md                      # The Projection Principle and convergence protocol
├── BOOTSTRAP.md
├── IMPLEMENTATION_PLAN.md
├── ARCHITECTURE-CONSTRAINT-CONVERGENCE.md
├── SMITHERS-PHASE2-UI-DECISIONS.md
├── SMITHERS-UI-WORKBENCH-SPEC.md
├── outstanding.md
├── gaps-constraint-convergence.md
├── build.mjs                      # Combined Node + Vite build
├── vite.config.ts                 # Browser bundle config
├── tsconfig.json
├── playwright.config.ts
├── deploy.sh
├── matrix.service.json            # Optional service-wrapper manifest
├── e2e/                           # Playwright workbench tests
├── tests/                         # Phase-style runner scripts
└── src/
    ├── index.ts                   # Public API: type re-exports + actor exports + utilities
    ├── ambient.d.ts               # Module augmentation
    ├── addressing.ts              # createSmithersAddress helpers (encode/parse)
    ├── container-agent-entry.ts   # Entry point for in-container coding agents
    ├── actors/                    # Headless actors (the bulk of the package)
    │   ├── SmithersSupervisor.ts            # Root orchestrator
    │   ├── ConstraintGraph.ts               # Projection engine
    │   ├── ConstraintActor.ts               # Per-constraint actor
    │   ├── ConstraintGroupActor.ts          # Group-level constraint surface
    │   ├── ConstraintChecker.ts             # runMechanicalChecks
    │   ├── ConstraintVersionStore.ts
    │   ├── GitHubAdapter.ts                 # gh CLI wrapper + body parsing
    │   ├── ContainerManager.ts              # Docker container management
    │   ├── WorkspaceActor.ts                # UI state owner
    │   ├── IssueActor.ts                    # Per-issue lifecycle
    │   ├── ReviewerAgent.ts                 # Single-constraint reviewer
    │   ├── SmithersSupervisor.ts
    │   ├── SprintOrchestrator.ts            # Multi-issue sprint coordination
    │   ├── EscalationPolicy.ts              # continue / fallback / escalate decisions
    │   ├── ProviderAffinityTracker.ts       # Provider preference per issue
    │   ├── RatchetStore.ts                  # Ratchet append-only log
    │   ├── ArchitectureDocWatcher.ts        # Architecture doc → constraint sync
    │   ├── system-constraints.ts            # SYSTEM_CONSTRAINTS data
    │   ├── bootstrap-constraints.ts         # getBootstrapConstraints()
    │   ├── constraint-templates.ts          # CONSTRAINT_TEMPLATES + instantiateTemplate
    │   ├── evidence-extraction.ts
    │   ├── smithers-log.ts                  # Convergence log writer
    │   └── __tests__/                       # 70+ spec files
    ├── browser/
    │   ├── SmithersApp.ts                   # Pattern A workbench shell
    │   ├── index.ts                         # customElements.define
    │   ├── index.html
    │   └── workbench/
    │       ├── TopologyRail.ts
    │       ├── SourceGraph.ts
    │       ├── Inspector.ts
    │       ├── ControlPalette.ts
    │       ├── RunnerPanel.ts
    │       ├── AgentChat.ts
    │       ├── ConstraintCollector.ts
    │       └── StatusBar.ts
    ├── coding-agent/
    │   ├── CodingAgent.ts                   # Path A in-process coding agent
    │   ├── applyPatch.ts                    # Patch application helpers
    │   ├── inferenceAdapter.ts              # piai adapter wiring
    │   ├── streamingOracle.ts               # Streaming LLM tool loop
    │   ├── taskPlanner.ts
    │   └── index.ts
    ├── runtime/
    │   └── create-host-managed-smithers.ts  # createHostManagedSmithers()
    ├── prompts/
    │   ├── constraint-prompt.ts             # buildCodingAgentPrompt()
    │   ├── codex-base-prompt.md
    │   ├── task-template.md
    │   └── skills/                          # Per-skill markdown
    ├── config/
    │   ├── defaults.ts                      # SMITHERS_DEFAULTS + mergeConfig()
    │   └── index.ts
    └── types/
        ├── constraint.ts                    # Constraint, ConstraintProjection, etc.
        ├── convergence.ts                   # ConvergencePhase, RoundRecord, SignOffReport
        ├── review.ts                        # ReviewRequest, ReviewResult
        ├── workspace.ts                     # WorkspaceState, SmithersRoute, GraphMode
        └── index.ts

Per-area responsibility

src/actors/

The 20+ actor files are the headless half. The hierarchy is:

SmithersSupervisor (mount: smithers, autoStart)
├── ConstraintGraph         (mount: smithers.graph)
├── GitHubAdapter           (mount: smithers.github)
├── ContainerManager        (mount: smithers.containers)
├── WorkspaceActor          (mount: smithers.workspace)
├── IssueActor              (one per active issue, ephemeral)
├── ReviewerAgent           (one per review dispatch, ephemeral)
└── ArchitectureDocWatcher  (mount: smithers.archdocs)

SmithersSupervisor.onBootstrap (SmithersSupervisor.ts:556-617) creates graph and workspace directly. GitHubAdapter, ContainerManager, and ArchitectureDocWatcher are mounted by the manifest's components block (their surface: 'headless' declaration) but instantiated lazily — the supervisor checks this.getChildIds() and only addChilds missing ones.

src/browser/

Pattern A. Every workbench panel is a MatrixActorHtmlElement. The shell — SmithersApp — owns split layout, theme, polling, and activity-frame routing. Each child panel's accept/emit is the panel's own contract.

src/coding-agent/

The local in-process agent (Path A). CodingAgent is a MatrixActor with ops code.run, code.steer, code.stop, code.status, code.history, code.chat. streamingOracle.ts is the LLM tool loop — it reads tokens from the provider, dispatches tool calls, and streams code.event activity frames back. applyPatch.ts validates and applies file diffs. inferenceAdapter.ts bridges to system.inference via omega-lisp/piai.

src/runtime/

createHostManagedSmithers (runtime/create-host-managed-smithers.ts) is the runner-provided bootstrap. The MatrixRuntime is provided by the runner; if the supervisor mount doesn't exist, it creates a supervised instance. Returns { runtime, mount, mounts }.

src/prompts/

buildCodingAgentPrompt and buildCodingAgentPromptParts materialise a ConstraintProjection into the system + user message that the agent sees. The base prompt for Codex lives at codex-base-prompt.md so it can be edited without recompilation.

prompts/skills/ is the directory the manifest's skills.<name>.file points at.

src/config/

SMITHERS_DEFAULTS is the single config source. mergeConfig deep-merges manifest props with defaults. Zero config = identical behaviour to pre-productization. See Configuration.

src/types/

The full type taxonomy used across the package. constraint.ts defines the projection data structure; convergence.ts defines the phase/round/sign-off types; review.ts defines reviewer types; workspace.ts defines all UI state shapes (SmithersRoute, InspectorTab, GraphOverlay, GraphMode, TopologyQueue, WorkspaceState).

Build outputs

build.mjs runs both Node and browser builds. After it completes:

dist/
├── index.js                # Headless entry (SmithersSupervisor + children + types)
├── index.d.ts              # Type declarations
├── index.html              # Browser entry
├── assets/                 # Hashed JS/CSS bundles for the workbench
└── ...

The package.json files field ships dist, matrix.json, LICENSE.

Workspace dependencies

"dependencies": {
  "@open-matrix/chat":              "workspace:*",
  "@open-matrix/claude-agent":      "workspace:*",
  "@open-matrix/codex-agent":       "workspace:*",
  "@open-matrix/core":              "workspace:*",
  "@open-matrix/inference-catalog": "workspace:*",
  "@mariozechner/pi-ai":            "^0.52.12"
}

pi-ai is the third-party library used as the inference adapter under omega-lisp/piai. claude-agent and codex-agent are the SDK worker sibling packages — Smithers depends on them as types (the runtime registration is decoupled, but Smithers' types reference theirs).

@open-matrix/chat is depended on for the ActivityFrame type and shared chat surface conventions. Smithers does not embed the chat panel directly.

See also

• Coding agent and inference integration
• Actor topology
• Package manifest (matrix.json)

Source: projects/matrix-3/packages/smithers/src/index.ts:1-99 (re-exports), projects/matrix-3/packages/smithers/package.json, projects/matrix-3/packages/smithers/build.mjs.