Agents vs Director

These are two different layers. Confusing them is the most common reason an "agent fix" lands in the wrong package.

The split

	system.agents (@open-matrix/agents)	Director (@open-matrix/director)
Surface	Headless backend actors on the bus	Browser webapp shell + actor graph UI
Mounts	system.agents, system.agents.memory, system.agents.embeddings	App at /apps/director/; in-process actors for the canvas
Owns	Sessions, memory, embeddings, agent loop, oracle, traces	Visualization, drag-drop graph, "ask about this actor" UX
Reads	Inference, credential, observability state	system.agents (for sessions/transcripts) and system.runtimes (for the graph)
Backend mount	—	backendMount: 'system.agents' (DirectorApp.ts:1829)

What Director actually does

Director is a workbench. It enumerates actors on the local Host (via system.runtimes and system.registry), draws them on a canvas, and lets the user select one and ask a question. The "ask" is the only place where Director crosses into agent territory:

1. User selects an actor (a TargetRef).
2. Director sends a prompt to system.agents with the TargetRef attached.
3. AgentsRoot either resumes an existing session for that target or creates a new one and spawns an AgentActor child.
4. AgentActor runs the introspect→infer→tool loop, streaming activity frames back.
5. Director renders the streaming response and persists nothing — the transcript belongs to system.agents, not Director.

DirectorRuntimeAdapter.ts:2119 and DirectorDataAdapter.ts:265 confirm system.agents is the only cognitive backend Director talks to.

What Director does NOT own

• Sessions. Director cannot create, mutate, or delete sessions on its own. Those go through AgentsRoot ops (session.create, $sessionDelete, $sessionClearAll).
• Memory. Director never writes to system.agents.memory.
• Inference credentials. Director never reads provider tokens; that flows from Factotum → system.inference → AgentActor.
• Tool execution. Director can target an actor but the tool calls happen inside the agent loop, on the Host running system.agents.

Why this matters

If you fix a "Director bug" by editing AgentsRoot, you have probably either (a) fixed an agent-platform bug that happens to surface in Director, or (b) coupled UI behavior to backend state in a way that will surface as a bug somewhere else (Chat, Smithers, headless prompts). The vertical-slice rule says: Director ships the UI for its own concerns; the agent platform ships the UI hooks for cognitive state.

Target state

A "cognitive readiness panel" surface (P1.12 in WORKSTREAMS/loose-ends/items/) is a Director feature that exposes whether system.agents, system.inference, providers, ActivityFrames, and persistence are all healthy. The panel does not exist today. When it lands it will live in the Director package and read from system.agents.$status / $metrics.

See also

• What is the agent platform?
• Director integration
• Sessions overview

Source: projects/matrix-3/packages/director/src/DirectorApp.ts:1829, projects/matrix-3/packages/agents/src/AgentsRoot.ts, WORKSTREAMS/loose-ends/items/P1.12-cognitive-readiness-panel.md.