Chat

Appearance

Chat ​

What this is and why it exists ​

Matrix is docker-for-actors / npm-for-actors — a typed pub/sub/RPC substrate where every Feed, Service, and Component is an actor on a federated bus. Chat is one vertical built on top of that substrate. It is the conversational UI: pick an actor (a chat agent, a workstream, the actor selected in Director), type a prompt, and watch thinking, tokens, tool calls, and final responses stream back inline.

This domain documents two cooperating packages:

  • @open-matrix/chat — the app. The /apps/chat/ surface a user opens in the browser. A Package in the substrate sense: published as @open-matrix/chat, deployed into a runtime as a DeploymentInstance, mounted on the bus.
  • @open-matrix/chat-component — the embeddable engine. Same conversation engine, plus a surface/ subpath registering <conversation-surface> and friends so other Packages (today: Director's Chat tab) can host the conversation surface inside their own UI without owning a chat app.

The cognition is not in either package. Chat sends $prompt to system.agents; system.agents resolves a session and routes inference through system.inference. Chat is a vertical UI; the substrate's cognitive runtime is what does the work.

Motivation ​

Chat is the lighthouse surface where a person actually talks to their agent and lands on a result. It exists because the rest of the platform — bus, actors, mounts, inference, identity — needs one human-facing demo that proves the wire works end to end, with thinking, tokens, and tool calls streaming back inline. It is also a reusable component: other apps embed <conversation-surface> rather than reinventing it, so this domain documents both the standalone Chat app and the embeddable engine. Read these docs if you use Chat in the browser, integrate the conversation surface into another package, or operate a Host that ships Chat to its users.

Where this fits ​

  • Tier 1, vertical-side. Chat runs on the user's local Host today (Tier 1: Local runtime). The same Package works on a hosted Host (Tier 2) without modification.
  • Vertical, not substrate. Substrate concepts (actors, bus, mounts, registry, identity, federation) are documented in the substrate-side packages: docs-matrix, docs-sdk, docs-runtime-host, docs-registry, docs-gateway. This domain is what one product surface looks like on the substrate.
  • App vs reusable component. @open-matrix/chat is the standalone app vertical. @open-matrix/chat-component is the reusable surface. Distinguish them; don't conflate.

Five-minute quickstart ​

Bring up a Host with the default package set (Chat is in there) and open the app:

bash
# Build chat and the wrapper
pnpm --filter @open-matrix/chat build
pnpm --filter hivecast build

# Install + start a Host into a fresh home
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs install --home /tmp/matrix-home
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs start --home /tmp/matrix-home

# Open the app in a browser
#   http://127.0.0.1:3100/apps/chat/

# Verify it from the bus directly
matrix invoke chat $introspect '{}'
matrix invoke system.agents $introspect '{}'

Real bus invocation, not an HTTP poke: system.agents is the cognitive runtime, addressed by mount path. The same $prompt payload the chat-app sends from the browser can be sent from the CLI:

bash
matrix invoke system.agents '$prompt' '{"prompt":"hello","activityTo":["..."]}' --home /tmp/matrix-home

Conceptual map ​

  • Overview — what Chat is, the app-vs-component distinction, and the call chain from user keystroke into system.agents and system.inference.
  • User Guide — using Chat: conversations, files, tools, agents, settings.
  • Developer Guide — embedding the component into a host shell, the runtime modes, the actor surface, surface registration, testing.
  • Operations — installing, running, logs, the inference dependency, troubleshooting.
  • Reference — package manifest, component API, actor ops, events, configuration schema.

Cross-references ​

  • Substrate framing: WORKSTREAMS/thesis/THESIS.md, Parts 1 and 5C (Compositional UI / Chat-as-builder vertical).
  • Bus is authority: P1.43. Inventory queries go through bus actors, not HTTP.
  • Multi-package runtimes (the docker-for-actors model Chat will deploy under): P1.40.
  • DeploymentInstance identity (how multiple chat instances per Space will work in target state): P1.42.
  • Sister vertical packages: docs-director (operator console; embeds the chat-component surface), docs-flowpad (pipeline editor), docs-smithers (convergence loop).

Status note. The runtime modes standalone-local / standalone-connected / daemon-hosted are code-level identifiers in chat/src/runtime/resolve-chat-config.ts. The product-language for the third mode is "deployed inside a runtime on a Host"; the daemon-hosted string is preserved as a v1 code identifier and will be renamed when the manifest reconciliation in P1.41 lands. The retired matrixd daemon is not the product path; Host Service supervises runtimes today.

Source: projects/matrix-3/packages/chat/src/, projects/matrix-3/packages/chat-component/src/, both matrix.json files. End-to-end cognitive proof status: WORKSTREAMS/loose-ends/items/P1.11-cognitive-product-proof.md.