Smithers as a Matrix package

In substrate vocabulary: Smithers is a Package (@open-matrix/smithers) — the same primitive Docker calls an image and npm calls a package, mapped onto the actor system. Unlike FlowPad (browser-only) or system services (headless-only), Smithers is a dual package: it ships a webapp shell and an autostarted headless supervisor with three children. Both halves are declared in matrix.json.

A Package deploys into a Runtime as a DeploymentInstance; the substrate's manifest declares which components mount where. The target-state model for that deployment lives in P1.40, P1.41, and P1.42. Smithers' current matrix.json is a v1 shape; the schema target is the consolidated matrix.json documented in P1.41.

Manifest at a glance

projects/matrix-3/packages/smithers/matrix.json declares (excerpt):

json

{
  "name": "@open-matrix/smithers",
  "version": "0.1.6",
  "runtime": {
    "language": "typescript",
    "entry": "dist/index.js",
    "engineVersion": "node>=20"
  },
  "webapp": {
    "distDir": "dist",
    "entry": "index.html",
    "appName": "smithers",
    "displayName": "Smithers",
    "icon": "🧰",
    "navOrder": 50,
    "shells": ["platform", "edge"]
  },
  "components": [
    { "type": "SmithersSupervisor", "mount": "smithers", "autoStart": true,
      "accepts": [ ... 28 ops ... ],
      "intentFilters": [
        { "action": "manage", "category": "devtools", "dataType": "constraint-convergence" },
        { "action": "start", "category": "devtools", "dataType": "convergence-worker" }
      ]
    },
    { "type": "ConstraintGraph",  "surface": "headless", "description": "Child of SmithersSupervisor" },
    { "type": "GitHubAdapter",    "surface": "headless", "description": "Child of SmithersSupervisor" },
    { "type": "ContainerManager", "surface": "headless", "description": "Child of SmithersSupervisor" }
  ],
  "permissions": { "fsPolicy": "none", "network": true, "subprocess": true, "env": true },
  "mx": { "category": "application", "visibility": "public",
          "tags": ["devtools", "automation", "convergence", "constraints", "ai-developer", "ratchet"] }
}

Two halves

Headless half (Node)

Entry: dist/index.js.
Auto-mounted: SmithersSupervisor at the smithers mount.
Children of the supervisor — ConstraintGraph, GitHubAdapter, ContainerManager, WorkspaceActor — are declared in the manifest as surface: "headless" but explicitly noted as created by parent, not auto-mounted. The supervisor's onBootstrap calls addChild for each (SmithersSupervisor.ts:594-616).
Permissions: network: true (to call gh issue list), subprocess: true (to spawn Docker containers and shell out), env: true (for resolving inference credentials), fsPolicy: 'none' (no arbitrary FS access).

Browser half

Entry: dist/index.html plus dist/index.js from the browser bundle (built by vite.config.ts).
Custom elements registered in src/browser/index.ts:7-49: <smithers-app>, <smithers-topology-rail>, <smithers-source-graph>, <smithers-inspector>, <smithers-control-palette>, <smithers-runner-panel>, <smithers-agent-chat>, <smithers-constraint-collector>, <smithers-status-bar>, plus <mx-split> for layout.
The shell is Pattern A (the shell IS the component) per src/browser/SmithersApp.ts:132-148 — SmithersApp extends MatrixActorHtmlElement directly. This is different from FlowPad's Pattern B (separated shell + actor).

The supervisor metadata

SmithersSupervisor.ts:253-311 exposes a richer-than-usual metadata surface for cognitive routing:

static description = 'Constraint convergence supervisor for coding-agent workstreams.';
static purpose = 'Orchestrate constraint convergence for workstream issues — ...';
static systemPrompt = [...].join('\n');
static promptable = true;
static regime = 'focused' as const;
static memoryScope = 'actor' as const;
static planScope = 'actor' as const;
static continuationType = 'persistent' as const;

static promptTriggers = [
  { event: 'child.completed', prompt: 'A coding agent completed its work...', debounceMs: 2000, maxPerHour: 10 },
  { event: 'child.error',     prompt: 'A child actor errored...',             debounceMs: 5000, maxPerHour: 20 },
  { event: 'smithers.requested', ... },
  { event: 'smithers.request-message', ... },
  { event: 'timer:1h', ... }
];

static childEventWhitelist = ['ready', 'disposed', 'error', 'completed', 'converged', 'escalated'];

This is Smithers' contribution to Cognitive Director routing: a workstream actor whose $prompt triggers fire on child events, request messages, and an hourly health timer. Other Matrix actors do not declare this much; Smithers does because it is itself an autonomous workstream owner.

Skills

matrix.json declares two skills exposed via the bus:

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"
  }
}

These are skill descriptors that the agent dispatched by Smithers can declare it has — they appear in the constraint prompt the agent receives.

Where Smithers runs

By default hivecast install does not spin up Smithers as a default runtime — Smithers is opt-in (it consumes inference credit and Docker, both heavier than other packages). Operators bring it up with:

bash

matrix up @open-matrix/smithers --serve --home /tmp/matrix-home

Once up, the gateway serves the workbench at http://127.0.0.1:3100/apps/smithers/. The headless supervisor is also reachable from any other actor:

bash

matrix invoke smithers smithers.status '{}' --home /tmp/matrix-home

Smithers as a Matrix package ​

Manifest at a glance ​

Two halves ​

Headless half (Node) ​

Browser half ​

The supervisor metadata ​

Skills ​

Where Smithers runs ​

See also ​