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](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:

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

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

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

## Quick Start

Prerequisites:

- Node.js 22+
- pnpm 10+
- `nats-server` for the no-account standalone broker demo. The easiest path is
  `pnpm setup:nats`, which installs a repo-local server under `.tools/`.
- Google Chrome/Chromium on `PATH`, or run `pnpm exec playwright install chromium`,
  for the browser proof in `prove:fresh-samples`

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

If the standalone broker demo reports missing NATS:

```bash
pnpm setup:nats
pnpm run doctor:standalone
```

## Install From The HiveCast/Gitea Registry

This path does not require cloning this repository, a HiveCast account, a
HiveCast local install, or a preinstalled Matrix binary. It installs the SDK
packages from the npm-compatible Gitea registry and runs a local demo broker.

```bash
mkdir matrix-sdk-customer-demo
cd matrix-sdk-customer-demo
npm init -y

cat > .npmrc <<'EOF'
@open-matrix:registry=https://registry.hivecast.ai/api/packages/open-matrix/npm/
registry=https://registry.npmjs.org/
EOF

npm install @open-matrix/sdk @open-matrix/cli
npx matrix broker setup
npx matrix broker start --port 4222

cat > GreeterActor.mjs <<'EOF'
import { MatrixActor } from '@open-matrix/sdk';

export default class GreeterActor extends MatrixActor {
  static accepts = {
    echo: { description: 'Echo a message', message: 'string' },
  };
  onEcho(payload = {}) {
    return {
      ok: true,
      message: payload.message ?? null,
      actor: 'GreeterActor',
    };
  }
}
EOF

npx matrix actor run ./GreeterActor.mjs \
  --mount demo.greeter \
  --nats-url nats://127.0.0.1:4222 \
  --root demo \
  --check-op echo \
  --check-payload '{"message":"hello-from-npm-install"}' \
  --json

npx matrix broker stop
```

Expected result: the actor run command prints JSON with `ok: true` and the
`echo` result from `GreeterActor`.

Handler names are part of the Matrix actor contract: `static accepts = { echo:
... }` maps to `onEcho(payload)`. Do not implement `echo(payload)` directly; the
CLI rejects that shape before it connects to the broker. Include parameter
fields such as `message: 'string'` so agents can construct valid payloads.

If you need the HiveCast browser proof and `pnpm doctor:hivecast` reports
missing Chromium:

```bash
pnpm setup:browser
pnpm run doctor:hivecast
```

`pnpm prove` runs the standalone proof:

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

For the external-consumer proof:

```bash
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

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

class EchoActor extends MatrixActor {
  static accepts = {
    echo: { description: 'Echo a message', message: 'string' },
  };

  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.

```bash
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:

```bash
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

### Path A: Local Broker, No HiveCast Account

Use this path when you only want to prove the SDK can run an actor over a real
broker without a managed platform account.

```bash
pnpm install --frozen-lockfile
pnpm setup:nats
pnpm run doctor:standalone
pnpm demo:standalone
```

This builds the SDK and `demos/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.

### Path B: HiveCast Broker, HiveCast API Key

Use this path when you want HiveCast to issue the broker credential. The SDK
still runs the actor/page directly; HiveCast supplies NATS TCP/WebSocket URLs and
short-lived actor credentials.

Create a HiveCast API key in the HiveCast web UI:

```text
Settings -> API Keys -> Create Key
Purpose: Machine install
Required scopes: host:init host:credentials:issue profile:install
```

Then run:

```bash
export MATRIX_CLOUD=https://<your-hivecast-cloud>
export MATRIX_SPACE=<your-space-root>
export MATRIX_API_KEY=<your-hivecast-api-key>

pnpm install --frozen-lockfile
pnpm setup:browser
pnpm run doctor:hivecast
pnpm prove:fresh-samples
```

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.

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

- `demos/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.
- `demos/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.

### Path C: Custom Broker

Use this path when you already operate a broker and want to pass the connection
explicitly.

```bash
matrix package run . \
  --nats-url nats://<host>:4222 \
  --root <subject-root> \
  --jwt '<optional-user-jwt>' \
  --seed '<optional-user-seed>' \
  --check-op ping
```

The SDK CLI also reads `MATRIX_NATS_URL`, `MATRIX_ROOT`/`MATRIX_SPACE`,
`MATRIX_NATS_JWT`, and `MATRIX_NATS_SEED`, plus config files under `--home`,
`./.matrix`, and `~/.matrix`. The SDK CLI does not create custom-broker
accounts. It consumes broker access you already have.

## Repository Layout

```text
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 demos 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.