Releases

Small agent tasks and the groundwork for multi-core: a generic agentOS runner for cheap, bounded agent work, destinations that hand results back to the core, a log file input, telemetry and a core registry that identify cores and destinations, and a Web UI flow built on them.

Upgrading:

- Migrations `0003_cores` and `0004_node_stats` run automatically on start.
- The Docker image omits optional dependencies (the agentOS VM runtime). Build with `--build-arg INSTALL_OPTIONAL=true` to use `agentos-runner` in Docker.
- Handed-off observations no longer pretend to come from an input named `destination:<id>`: their `input` is empty and `origin` names the destination. Consumers of telemetry or output envelopes that relied on that input id should read `origin`.
- Web UI destination nodes show `delivered` instead of `outputs`. Per-node totals start counting from the upgrade; earlier history isn't backfilled.

Changes:

- Per-node totals: the API counts polls, observations, decisions, completed deliveries, handoffs, errors and the last event time per flow node in a new `stat_nodes` table (migration `0004_node_stats`) as telemetry arrives, and returns them as `nodes` in `GET /api/stats`. The Flow page shows these totals, so node counters no longer reset when events leave the 2000-event window. Destination nodes now show `delivered` (completed deliveries) instead of `outputs`, which only ever counted the HTTP JSON destination's output events.

- `agentos-runner` fails fast and clearly: a missing model API key is reported before a VM boots, and a sidecar that can't start (`EPIPE` and similar) becomes a permanent, readable error ("the agentOS sidecar could not start … on NixOS enable programs.nix-ld") instead of retried pipe errors. On NixOS, nix-ld is now the recommended setup; the real-VM test runs whenever nix-ld (or `AGENTOS_SIDECAR_BIN`) is available.
- Fix: `npm run check` now fails on syntax errors (it used `find -exec`, which ignored them) and also checks `brainstem-api.mjs` and the Web UI flow model.

- Web UI Flow page brought up to date with the runtime: structure from `/api/topology` (one node per configured id, so tasks of the same plugin are no longer merged), a core pool node and a Cores panel from the core registry, handoffs shown only while they happen (a short-lived "handing off" pill node linked to the destination) instead of fake `destination:<id>` input nodes, and an inspector that matches destinations by id and shows each decision's origin and core. Falls back to snapshot events against an older backend. The graph logic moved into a pure, unit-tested `web/src/flow/model.js`.

- Core registry and `GET /api/topology`: each runtime registers in a new `cores` table (migration `0003_cores`) with its role, queues, version and loaded topology, heartbeats every `runtime.cores.heartbeatMs` (default 10 s) and marks itself stopped on shutdown. Cores that miss 3 heartbeats are reported as `lost`, and rows unseen for 24 h are pruned. `/api/topology` serves the cores plus the inputs and destinations (with ids) from the freshest running core, and flags running cores that loaded different configs. The Web UI no longer has to derive structure from snapshot events.

- Telemetry identity fields for multi-core and handoffs: every event carries `coreId` (`runtime.coreId` / `BRAINSTEM_CORE_ID`, also the job worker id); decisions and output envelopes carry `origin` (`{ kind: "input", id }` or `{ kind: "destination", id, depth, lineage }`); the snapshot and destination plugin logs carry destination `id`s; a new `brainstem.destination.emitted` event marks each handoff. A handed-off observation no longer pretends to come from an input named `destination:<id>`. Its `input` is empty and `origin` names the destination. Jobs queued by the previous version are still understood.

- Destinations can hand observations back to the core with `ctx.emit(observation)`. They are enqueued in the same transaction that marks the delivery delivered, never routed back to a destination already in their chain, and limited by `runtime.handoff.maxDepth` (default 2) and `maxPerDelivery` (default 5).
- `agentos-runner` gains `handoff`: a successful run's report becomes an `agent_report` observation (with `facts.minimum_decision`) that Matrix or a bigger agent can pick up.
- New `log-file` input: watches a log file and emits new matching lines (default `ERROR|FATAL|CRITICAL|PANIC`) as one bounded observation per poll, with offset checkpoints and truncation/rotation handling.
- Fix: the agentOS prompt and docs used `observation.summary`, which doesn't exist; they now use `title`, `message` and `source.type`/`source.name`.

- New `agentos-runner` destination: runs a configured task in a [Rivet agentOS](https://rivet.dev/agent-os) VM for each matching decision. One plugin serves many tasks; each destination entry has its own filters, `command` (or agent `prompt`), network allowlist, read-only mounts, env, and host-side tools. Tools are validated, limited by `maxCalls`, can be `required`, and are replayed instead of repeated when a delivery is retried. `runOnce: "revision"` skips re-emitted observations by default. See `docs/plugins/agentos-runner.md`.
- `prompt` tasks run a host-side agent loop against any OpenAI-compatible endpoint (`model: { baseUrl, name, apiKeyEnv }`). The model gets `run_command` (inside the VM) plus the entry's tools. Every run is bounded by `limits` (turns, output tokens, commands, tool output size, prompt size, conversation size, request spacing), duplicate calls are refused, and a delivery that already talked to the model fails permanently instead of being retried (`maxAgentAttempts: 1`).
- `@rivet-dev/agentos-core` is an optional dependency. The Docker image omits optional dependencies unless built with `--build-arg INSTALL_OPTIONAL=true`.

First release on the way to 2.0: one database for all state (SQLite or Postgres) and a durable decide/deliver pipeline. Includes the unreleased 2.0 Phase 0 and Phase 1 work. See "Behaviour changes" below before upgrading.

Brainstem 2.0 Phase 0 (safety net), see `docs/roadmap-2.0.md`:

- CI workflow running the syntax check, unit/integration tests, and acceptance tests on every PR and push to `main`.
- Tests for the runtime polling loop, shutdown and abort handling, poll-retry re-delivery (1.x behaviour), per-ID ordering and decision caching in the core, config saves, and the SSE stream.
- Multi-core acceptance harness (`npm run test:acceptance`) that runs several real core processes against shared state. The 2.0 cluster guarantees are tracked as `todo` tests until Phase 3.
- Architecture decision records for the 2.0 design in `docs/adr/`.

Brainstem 2.0 Phase 1 (storage abstraction):

- One database for all state, via Kysely: SQLite (default, `sqlite:data/brainstem.sqlite`) or Postgres (`BRAINSTEM_DATABASE_URL=postgres://...`). The runtime and the embedded API share one connection.
- Records, checkpoints, telemetry, stats, and auth stores are async and database-backed. Checkpoints are read from the database on every poll, with no per-process cache.
- New `ctx.state` plugin API for durable plugin state. The Matrix destination keeps its suppression state there, claiming a notification before sending so two processes can't both send it.
- Record writes check the expected revision (groundwork for multi-core).
- Safe first-admin creation under concurrent setup requests; login rate limiting stored in the database and keyed by client IP behind trusted proxies (`BRAINSTEM_TRUSTED_PROXIES`); retention pruning moved to a periodic maintenance job.
- `brainstem migrate`, `migrate status`, `migrate import-v1`, and `migrate copy` / `sqlite-to-pg` commands.
- 1.x state (`web-stats.sqlite`, `checkpoints.json`, `matrix-notifications.json`) is imported automatically on first start; legacy files are never modified.
- CI runs every storage test against both SQLite and Postgres 17.
- Behaviour change: with no `records`/`checkpoints` config, state now persists to the database (previously records were in memory and checkpoints in JSON). Explicit `memory`, `json`, and `sqlite` types still work.

Brainstem 2.0 Phase 2 (durable pipeline), see `docs/delivery-pipeline.md`:

- The runtime is split into `poll`, `decide` and `deliver` stages connected by jobs in the new `jobs` table. Each stage commits its outputs and the next stage's jobs in one transaction. Checkpoints advance in the same transaction that stores the polled observations.
- One deliver job per (decision, destination). A failing destination is retried on its own with exponential backoff and jitter (`runtime.queue.deliver.retry`, or `retry` per destination). It no longer re-triggers other destinations, the decision or the poll, and a slow destination no longer stalls polling.
- Jobs that run out of attempts become dead jobs. The new **Deliveries** page in the Web UI shows queue depth, the delivery log and dead jobs, with redrive and discard. API: `GET /api/pipeline`, `GET /api/jobs`, `GET /api/deliveries`, `POST /api/jobs/redrive`, `POST /api/jobs/discard`.
- Delivery log (`deliveries` table) keyed by an idempotency key, which is checked before sending. Delivered rows are pruned after `runtime.deliveries.pruneAfterDays` (14).
- Decide jobs are serialized per observation ID through the queue (`queue_key`), and record writes are compare-and-set on the revision.
- Jobs hold renewable leases. Jobs from crashed processes are reclaimed, and jobs interrupted by shutdown are handed back without using up an attempt.
- **Destination plugin SDK v2** (`brainstem.destination/v2`): `handle(ctx, output)` receives the serializable `brainstem.output` envelope, plus `ctx.idempotencyKey` and `ctx.attempt`. v1 destinations keep working through an adapter, which logs a deprecation warning, until 3.0.
- Built-in destinations are on v2:
  - `http-json` sends an `Idempotency-Key` header.
  - Matrix uses the key as `txnId`, replacing the random id per attempt.
  - opencode-runner resumes the session of a retried delivery instead of starting a new one.
  - log-decisions is migrated.
- Migration `0002_pipeline` adds the `jobs` and `deliveries` tables. `migrate copy` includes them.
- New telemetry: `brainstem.core.failed`. `brainstem.destination.failed` now carries `attempt`, `dead` and `retryInMs`. New metrics: `decisions.failed`, `decisions.dead` and `destinations.dead`.
- Behaviour changes:
  - `runtime.destinations.blockInputOnFailure` is ignored, with a warning.
  - A failing decision no longer holds back the input checkpoint. It stays queued and is retried.
  - `--once` runs every due job after polling, and exits non-zero if any poll or job failed.
  - Config callbacks of the built-in destinations (`notificationKey`, `titleForEvent`, `promptTemplate`) receive `output.payload`.
  - Give destinations an `id`: it is part of the idempotency key.


Docker image: `ghcr.io/jurrebuunk/brainstem:v1.3.0`. Upgrade notes: `docs/delivery-pipeline.md#upgrading-from-1x`.

# Brainstem v0.1.0

First non-alpha release of Brainstem as a local-first headless decision runtime with a protected operations UI.

## Highlights

- Local-first headless runtime with SQLite records, checkpoints, telemetry history, stats, and event retention.
- Protected backend API and SSE with first-run administrator onboarding.
- Argon2id password hashing, persistent sessions, CSRF protection, and backend-enforced RBAC.
- Built-in Administrator, Operator, and Viewer roles plus custom role creation/deletion.
- User creation, disabling/enabling, deletion, and last-active-administrator protections.
- Presentation-only Web UI with Flow, Stats, Config, Users, and Roles pages.
- New README and documentation with fresh screenshots.
- Docker/Compose templates updated for `ghcr.io/jurrebuunk/brainstem:v0.1.0`.

## Validation

- `npm run check`
- `npm test` — 29 passing
- `npm run plugin:test`
- `npm run web:build`
- `npm pack --dry-run`

Backend/Web UI decoupling and modularization release.

- Backend API now owns telemetry ingestion, event history, stats, retention, SSE, and config management.
- Web UI is presentation-only and proxies `/api/*` to the backend via `WEB_BACKEND_URL`.
- Added standalone `brainstem-api.mjs` and `brainstem-api` binary.
- Runtime can start the backend API with `runtime.api.enabled` and automatically send telemetry to it.
- Added optional backend bearer-token auth via `BRAINSTEM_API_TOKEN` / `WEB_BACKEND_TOKEN`.
- Refactored shared telemetry selectors and metric derivation into `src/telemetry`.
- Further modularized runtime internals, Web server modules, node inspector code, and the opencode runner plugin.
- Fixed node inspector crashes for core and destination nodes.

Container image: `ghcr.io/jurrebuunk/brainstem:v0.1.0-alpha.5`

Web UI node inspector and flow readability release.

- Replaced the node click log table with a larger operational node inspector.
- Input nodes now group activity by poll with poll logs and emitted observation envelopes.
- Core nodes now show observation input envelopes alongside decision output envelopes.
- Destination nodes now show received decision/observation envelopes with destination-scoped logs and output envelopes.
- Tightened the inspector into a compact table-like layout with less duplicated metadata.
- Standardized application font-size and line-height CSS tokens for more readable UI sizing.
- Increased flow graph row spacing so stacked nodes no longer overlap.

Container image: `ghcr.io/jurrebuunk/brainstem:v0.1.0-alpha.4`

Production-ready Web UI observability persistence.

- Web UI now persists raw telemetry/output events in SQLite, so Flow/node logs survive restarts.
- `/api/events` reads from the persisted event log and supports `limit`, `before`, `after`, `kind`, `level`, and `source` filters.
- Stats and event-log writes are committed together to keep derived metrics aligned with stored telemetry.
- Event-log retention is configurable with `WEB_EVENTS_PRUNE_AFTER_DAYS` and `WEB_EVENTS_MAX_ROWS`; either pruning mode can be disabled with `0`.
- Docker/Compose examples updated for the new release tag and event-log retention settings.

Container image: `ghcr.io/jurrebuunk/brainstem:v0.1.0-alpha.3`

## Brainstem v0.1.0-alpha.2

Docker and documentation production-template release.

### Highlights
- Docker image now includes the production Web UI server and built static assets.
- Docker Compose template now runs separate runtime and Web UI containers.
- README and Docker docs updated for production-style deployment.
- Added Web UI screenshot to the README.
- Fixed Flow handle highlighting to use Web UI receive time, so active dots/edges light up reliably.
- Bundled Inter and Material Symbols fonts in the Web UI instead of relying on remote font loading.

### Docker
This release publishes:

- ghcr.io/jurrebuunk/brainstem:v0.1.0-alpha.2
- ghcr.io/jurrebuunk/brainstem:latest
- ghcr.io/jurrebuunk/brainstem:sha-59c6ef6

You can verify with:

```sh
docker manifest inspect ghcr.io/jurrebuunk/brainstem:v0.1.0-alpha.2
```

### Validation
- npm test
- npm run check
- npm run plugin:test
- npm run web:build
- npm run pack:dry-run
- docker build -t brainstem:release-check .
- docker run Web UI health check

## Brainstem v0.1.0-alpha.1

Release hardening for headless agent routing and the Web UI.

### Highlights
- Source-side input dedupe/checkpointing improvements.
- Destination failures isolated from input checkpointing by default.
- HTTP JSON output destination and structured telemetry.
- React Flow Web UI with node logs, persisted stats, and CodeMirror config editor.
- OpenCode runner now uses the OpenCode server API and logs assistant output.
- Web server hardening: invalid JSON handling, request limits, atomic config saves with backups, stats pruning, safer static serving.

### Docker
The Docker workflow is triggered by this tag and publishes:

- ghcr.io/jurrebuunk/brainstem:v0.1.0-alpha.1
- ghcr.io/jurrebuunk/brainstem:latest
- ghcr.io/jurrebuunk/brainstem:sha-<commit>

### Validation
- npm test
- npm run check
- npm run plugin:test
- npm run web:build
- npm run pack:dry-run

**Full Changelog**: https://github.com/jurrebuunk/flatwork-ui/commits/v0.1.0

Initial alpha release of Brainstem.

Brainstem is a lightweight decision and orchestration layer for autonomous AI agents. It watches configured sources, deduplicates observations, uses Laya for local bounded decisions, and routes actionable decisions to destinations.

## Included

- Laya-backed Brainstem core decision engine
- Polling input plugin runtime
- Routed destination plugin runtime
- Durable SQLite core record cache
- Deferred input checkpoints
- GitHub issues input plugin
- HTTP health input plugin
- Console logging destination plugin
- Matrix room destination plugin
- Local config and `.env` support
- User-facing README and release docs

## Status

This is an alpha release. It is ready for local experimentation, but APIs and plugin contracts may still change.

# 8BitCPU Toolkit v1.0.0

First stable learning release of the 8BitCPU Toolkit.

## Highlights

- Reliable headless CPU core in `cpu.py`
- Assembly assembler in `assemblerasm.py`
- Graphical Tkinter emulator in `compute.py`
- Real `.bin` machine-code output alongside readable `.mc` output
- Architecture documentation in `docs/architecture.md`
- RAM-backed stack with `PUSH`, `POP`, `CAL`, and `RET`
- `MOV`, branch aliases, constants, sections, `.org`, and data directives
- Unit tests for the CPU core, assembler, binary encoding, and examples
- Legacy and experimental files separated into `archive/` and `experimental/`

## Release assets

This release includes standalone copies of:

- `cpu.py`
- `assemblerasm.py`

The standard GitHub source archives are also available below.

# 8BitCPU Toolkit v0.1.0-alpha.1

Initial alpha pre-release of the 8-bit CPU assembler and simulator toolkit.

## Includes

- Assembly assembler for `.asm` files
- Jutcode assembler for `.jc` files
- CPU simulation utilities
- Example programs in `programs/`

## Known limitations

- Documentation is still incomplete
- APIs and CLI behavior may change before a stable release
- Packaging/PyPI release is not available yet