Smithers

Appearance

Package manifest (matrix.json) ​

projects/matrix-3/packages/smithers/matrix.json declares both the webapp and four headless components, plus skills, intentFilters, and rich permissions. This page enumerates every field.

Top-level ​

json
{
  "name": "@open-matrix/smithers",
  "version": "0.1.6",
  "description": "Constraint convergence orchestrator — methodical agent coordination via depender-defined constraints"
}
FieldNotes
nameMust match package.json.
versionMust match package.json.
descriptionSurfaced in system.catalog and the Smithers package row in FlowPad's package browser.

runtime ​

json
"runtime": {
  "language": "typescript",
  "entry": "dist/index.js",
  "engineVersion": "node>=20"
}
FieldMeaning
runtime.languageTypeScript runtime kind.
runtime.entryHeadless entry — Host Service spawns this when starting the runtime.
runtime.engineVersionRefuses to start on Node < 20.

webapp ​

json
"webapp": {
  "distDir": "dist",
  "entry": "index.html",
  "appName": "smithers",
  "displayName": "Smithers",
  "icon": "🧰",
  "navOrder": 50,
  "description": "Constraint convergence workbench",
  "shells": ["platform", "edge"]
}

Same shape as FlowPad's webapp block. Reachable at /apps/smithers/. navOrder: 50 puts it after FlowPad (40) and Director (30) in the nav. Both platform and edge shells render it.

components ​

This is the field that distinguishes Smithers from a webapp-only package. Four entries:

SmithersSupervisor ​

json
{
  "type": "SmithersSupervisor",
  "export": "SmithersSupervisor",
  "mount": "smithers",
  "autoStart": true,
  "surface": "headless",
  "accepts": [ ... 28 ops ... ],
  "emits": [ ... 5 events ... ],
  "intentFilters": [
    { "action": "manage", "category": "devtools", "dataType": "constraint-convergence" },
    { "action": "start",  "category": "devtools", "dataType": "convergence-worker" }
  ],
  "examples": [
    {
      "label": "Start convergence on an issue",
      "operation": "smithers.start",
      "payload": { "issueNumber": 73 }
    },
    {
      "label": "Show convergence status",
      "operation": "smithers.status",
      "payload": {}
    }
  ]
}

autoStart: true makes Host Service mount the supervisor at smithers automatically when the runtime starts. The accepts/emits lists in the manifest are a subset of what the actor class declares — the manifest list is what tools and other actors should be encouraged to use; the class can accept more without breaking compatibility. intentFilters is what system.catalog.search matches against when a UI or LLM asks "which actors handle convergence?".

examples is rendered in FlowPad's example list when the user clicks SmithersSupervisor in the package browser.

ConstraintGraph, GitHubAdapter, ContainerManager ​

json
{ "type": "ConstraintGraph",  "export": "ConstraintGraph",  "surface": "headless",
  "description": "Child of SmithersSupervisor — created by parent, not auto-mounted" },
{ "type": "GitHubAdapter",    "export": "GitHubAdapter",    "surface": "headless",
  "description": "Child of SmithersSupervisor — created by parent, not auto-mounted" },
{ "type": "ContainerManager", "export": "ContainerManager", "surface": "headless",
  "description": "Child of SmithersSupervisor — created by parent, not auto-mounted" }

These are declared so that system.catalog knows the classes exist and can introspect them, but autoStart is omitted — the supervisor creates them via addChild during onBootstrap. The description makes the relationship explicit.

WorkspaceActor, IssueActor, ReviewerAgent, RatchetStore, and ArchitectureDocWatcher are NOT in this list because they either are also-children-of-supervisor (Workspace), ephemeral (Issue, Reviewer), or non-actor utilities (RatchetStore is class state in supervisor, ArchitectureDocWatcher is optional).

skills ​

json
"skills": {
  "emacs-code-intelligence": {
    "description": "Instant indexed search, call graphs, structural navigation via Emacs daemon",
    "file": "src/prompts/skills/emacs-code-intelligence.skill.md"
  },
  "matrix-awareness": {
    "description": "Understanding of the Matrix actor system, constraint convergence protocol, and self-improvement loop",
    "file": "src/prompts/skills/matrix-awareness.skill.md"
  }
}

Skills declare capability surfaces the agent dispatched by Smithers can claim. The file field points at markdown that gets folded into the agent's system prompt.

permissions ​

json
"permissions": {
  "fsPolicy": "none",
  "network": true,
  "subprocess": true,
  "env": true
}

Smithers needs:

  • network: true — to call gh issue list (which uses HTTPS), and for the SDK workers' inference calls.
  • subprocess: true — to spawn Docker containers via ContainerManager and to run gh and shell commands during the agent's tool loop.
  • env: true — to read inference credentials from the environment via inferenceCatalog.createInferenceConfig.
  • fsPolicy: 'none' — explicit: Smithers does not have arbitrary filesystem access. Patches are validated through applyPatch.ts and only applied via the agent's shell tool inside the agent's working directory.

mx ​

json
"mx": {
  "category": "application",
  "visibility": "public",
  "tags": ["devtools", "automation", "convergence", "constraints", "ai-developer", "ratchet"]
}

Catalog metadata. visibility: "public" means Smithers shows up in the catalog without a special role gate. The tags are searchable.

Package.json overlap ​

jsonc
"main": "dist/index.js",
"types": "dist/index.d.ts",
"files": ["dist", "matrix.json", "LICENSE"],
"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"
}

Compared with FlowPad: Smithers depends on @mariozechner/pi-ai directly (the inference adapter), and on the two SDK worker packages (claude-agent, codex-agent) for shared types. chat is a dependency for the ActivityFrame type and shared chat conventions.

Conformance ​

  • The pre-merge gate validates webapp.entry exists in webapp.distDir/.
  • The supervisor's actual accepts/emits (via static accepts/emits) is the authoritative contract; matrix.json's lists must be a subset.
  • permissions.fsPolicy: 'none' is a project Rule 4 / Rule 9 invariant — patches go through applyPatch.ts, never raw FS writes.

See also ​

Source: projects/matrix-3/packages/smithers/matrix.json (read in full above).