hivecast-sdk/README.md

Matrix SDK

Matrix SDK is the package-author layer for building Matrix actors, browser surfaces, and broker-connected applications without depending on a managed platform repo.

This repository contains the SDK packages under their target @open-matrix/* package names. The workspace is proven as a standalone workspace: a fresh clone can install, build, test, type-check, pack every package, and compile an external consumer against the packed tarballs.

What You Can Build

• Headless actors with MatrixActor
• Browser custom elements with MatrixActorHtmlElement
• In-memory actor graphs for tests and local development
• NATS-backed transports for broker-connected actors
• Browser host integrations for Matrix web surfaces
• Package-author CLIs and project scaffolds

Matrix SDK is provider-neutral. It does not require a managed platform account, machine-link ceremony, managed host service, local platform install, Postgres database, or provider-owned broker authority. A provider overlay can issue broker credentials and host runtimes on top of the SDK, but the SDK itself must remain usable against any compatible broker.

See STANDALONE-AUDIT.md for the current standalone boundary audit, including the remaining Omega/oracle extraction debt that is not part of the package-author SDK proof.

Packages

Package	Purpose
@open-matrix/sdk	Public umbrella facade for actor/package authors
@open-matrix/core	Actor kernel, runtime, transports, serialization, browser actor base classes
@open-matrix/cli	Package-author matrix CLI
@open-matrix/browser-kit	Browser app shims, theme tokens, Vite helpers, shell components
@open-matrix/browser-host	Browser runtime host shell and app-ready integration
@open-matrix/contracts	Shared type contracts for placement, service registry, and runtime presence
@open-matrix/federation	Cross-realm messaging, MX envelope handling, and routing helpers
@open-matrix/omega-core	Narrow Omega interpreter facade used by Matrix membranes

Prefer narrow imports when possible:

import { MatrixActor } from '@open-matrix/core';

Use the umbrella package when you intentionally want the public SDK facade:

import { MatrixActor } from '@open-matrix/sdk';

Quick Start

Prerequisites:

• Node.js 22+
• pnpm 10+
• nats-server on PATH for the no-account standalone broker demo
• Google Chrome/Chromium on PATH, or run pnpm exec playwright install chromium, for the browser proof in prove:fresh-samples

git clone git@github.com:matrix-sdk/matrix-sdk.git
cd matrix-sdk
pnpm install --frozen-lockfile
pnpm prove

pnpm prove runs the standalone proof:

clean -> build -> test -> type-check -> pack all packages

For the external-consumer proof:

pnpm prove:external-consumer

That proof packs the SDK packages, creates a temporary consumer outside this repo, installs the packed tarballs, compiles TypeScript, starts a MatrixActor, and calls it through the Matrix runtime/transport path.

Minimal Actor

import {
  InMemoryBroker,
  InMemoryTransport,
  MatrixActor,
  MatrixRuntime,
  TopicRouter,
} from '@open-matrix/core';

class EchoActor extends MatrixActor {
  static accepts = {
    echo: {},
  };

  onEcho(payload: { message?: string }) {
    return {
      ok: true,
      message: payload.message ?? null,
    };
  }
}

const broker = new InMemoryBroker();
const transport = new InMemoryTransport(broker, { name: 'demo' });
const runtime = new MatrixRuntime({ transport, logging: false });

await runtime.create(EchoActor, 'demo.echo');

const replyTo = '$replies.demo';
const response = new Promise((resolve) => {
  const unsubscribe = transport.subscribe(replyTo, (value) => {
    unsubscribe();
    resolve(value);
  });
});

transport.publish(TopicRouter.inbox('demo.echo'), {
  op: 'echo',
  payload: { message: 'hello' },
  replyTo,
  correlationId: 'demo-1',
});

console.log(await response);
await runtime.shutdown();

CLI

The SDK CLI package owns the package-author matrix binary.

matrix init [dir]
matrix actor <name>
matrix actor run ./dist/MyActor.js --mount demo.actor --nats-url nats://127.0.0.1:4222 --root demo --check-op ping
matrix package run . --nats-url nats://127.0.0.1:4222 --root demo --check-op ping
matrix config list

The current SDK CLI proof is:

pnpm prove:cli

The CLI is intended to let a package author initialize a folder, add actors, configure broker access, and run/check actors without importing provider overlay packages into the SDK layer. Managed-host promotion and provider login belong in overlay packages, not in the SDK CLI core.

Demos

Standalone SDK demo, no provider account or key required:

pnpm demo:standalone

This builds the SDK and examples/standalone-greeter, starts the actor with matrix package run, calls it with --check-op over a real local NATS broker, and shuts it down. It does not use a provider account, machine link, managed host service, or local HTTP control server.

Provider API-key login/config work has been moved out of the active SDK demo set and preserved under archive/sdk-provider-overlay-candidates/. It belongs to a provider overlay that can write the same broker config shape consumed by the SDK CLI.

HiveCast-managed SDK demos, API key required:

MATRIX_CLOUD=https://<your-hivecast-cloud> \
MATRIX_SPACE=<your-space-root> \
MATRIX_API_KEY=<your-hivecast-api-key> \
pnpm prove:fresh-samples

That proof builds and runs two fresh package-author demos:

• examples/fresh-server-actor exchanges the API key for an actor-scoped credential, connects to HiveCast NATS TCP, mounts fresh.server.echo, and calls it over the Matrix runtime/NATS transport path.
• examples/fresh-web-page is served by Vite, not Matrix Web or HiveCast HTTP. Its Vite dev endpoint exchanges the API key for an actor-scoped browser credential, the page connects to HiveCast NATS WebSocket, mounts fresh.web.echo, and calls it in a real browser.

The API key stays server-side for the web demo. The browser receives only the short-lived actor JWT/seed returned by the HiveCast credential exchange.

Repository Layout

packages/
  browser-host/
  browser-kit/
  cli/
  contracts/
  core/
  federation/
  omega-core/
  sdk/
scripts/
  demo:standalone
  prove-external-consumer.mjs
  prove-fresh-samples.mjs

Current Status

Done and proven:

• The SDK packages build independently from their original source monorepo.
• Package identities use final @open-matrix/* names.
• @open-matrix/sdk re-exports the public actor facade.
• A fresh clone passes pnpm install --frozen-lockfile && pnpm prove.
• A temporary external consumer can install packed SDK tarballs, compile, start a MatrixActor, and call it through Matrix runtime/transport.
• matrix package run can mount and check a package against an explicit NATS broker without provider-specific API key exchange.
• Fresh server and browser examples can run against HiveCast-issued actor-scoped NATS credentials.

Still planned:

• A polished provider-neutral matrix configure UX for broker URL/root/JWT/seed files.
• Provider login commands in overlay packages that write the same broker config shape consumed by SDK direct-run commands.
• Managed-provider mode where an overlay issues scoped broker credentials.

Publishing is intentionally not part of this repository's normal developer workflow yet. The repo proves source, package, and consumer behavior with pnpm pack; public package release is an owner-controlled release decision and must be added as an explicit release policy before any npm publication.

Relationship To Provider Overlays

Matrix SDK is the provider-neutral actor SDK.

Provider overlays can provide account management, namespaces, API keys, broker credential issuance, runtime hosting, package distribution, and operator UI. SDK users should still be able to connect to another broker directly when they already manage their own broker credentials.