sms-baseline

A headless baseline for self-modifying software driven by agentic AI. Users prompt a model; the software’s behaviour changes live — no rebuild, no restart — and stays reliable because every change is a plugin that is judged before it mounts, undone mechanically when it fails or is disabled, and persisted so it survives restarts.

It is a set of packages, not an app. A downstream project installs the baseline, brings its own plugins (domain modules) and its own UI (any frontend against the JSON admin API), picks the drivers for its stack, and gets self-modification for free.

ring 0  @sms/kernel                      loader · registry · fibers · derived undo · event log · trust tiers
ring 1  @sms/plugin-sdk | @sms/contracts what agent code sees | the driver contracts
ring 2  drivers | plugins                store · host · executor · model · objects | http · collections · judge · agent-loop · admin-api · …
ring 3  @sms/baseline                    createBaseline() · createTenantPool()
ring 4  examples/* — and your app

Quick start

pnpm add "github:<owner>/sms-baseline#vX.Y.Z&path:/packages/baseline"   # + the drivers you use (see docs/getting-started.md)

import { createBaseline } from "@sms/baseline";
import { QuickJSExecutor } from "@sms/executor-quickjs";
import { createNodeHost } from "@sms/host-node";
import { createClaudeModel } from "@sms/model-claude";
import { openSqliteStore } from "@sms/store-sqlite";

const app = await createBaseline({
  store: await openSqliteStore("app.db"),
  executor: new QuickJSExecutor(),
  model: createClaudeModel(),
  plugins: [/* your plugins */],
  adminToken: process.env.SMS_ADMIN_TOKEN,
});
await createNodeHost({ port: 8787 }).listen(app.handle);

Documentation

Everything lives in docs/ (also published as an mdBook site — see docs/documentation-site.md):

• Getting started · Writing plugins · Building a UI
• Drivers · Tenancy
• Architecture · Dependency graph · Research positioning
• Releasing · Quality gate · Benchmarking

Developing the baseline

pnpm install
pnpm check                 # typecheck · lint · quality gate · knip · tests with coverage — run before every push (no CI on main)
pnpm --filter @sms/example-reference-node-sqlite demo
git tag vX.Y.Z && git push origin vX.Y.Z   # cut a release; CD does the rest (docs/releasing.md)

Agent notes for this repo are in CLAUDE.md at the repo root.

Getting started: the baseline inside your project

You are building sm-erp (or any app). You want users to be able to say “add a discount field to invoices and a tool that finds overdue ones” and have it happen — safely, live, persistently. This is how.

1. Install

The baseline is private and distributed as git tags with committed dist/. Pick the umbrella plus the drivers for your stack (every package is a separate git+path dependency; they all pin the same tag):

TAG=v0.2.0; REPO=github:<owner>/sms-baseline
pnpm add "$REPO#$TAG&path:/packages/baseline" \
         "$REPO#$TAG&path:/packages/drivers/store/sqlite" \
         "$REPO#$TAG&path:/packages/drivers/executor/quickjs" \
         "$REPO#$TAG&path:/packages/drivers/host/node" \
         "$REPO#$TAG&path:/packages/drivers/model/claude"   # or model-gpt

Requirements: Node ≥ 22.13 (or Workers with nodejs_compat), pnpm, ESM ("type": "module"). TypeScript types ship in dist/.

2. Compose a kernel

// src/app.ts — your composition root
import { createBaseline } from '@sms/baseline'
import { QuickJSExecutor } from '@sms/executor-quickjs'
import { createClaudeModel } from '@sms/model-claude'
import { openSqliteStore } from '@sms/store-sqlite'
import { invoicesPlugin } from './plugins/invoices.ts'

export async function createApp() {
  return createBaseline({
    name: 'sm-erp',
    store: await openSqliteStore(process.env.SMS_DB ?? 'erp.db'),
    executor: new QuickJSExecutor(),
    model: createClaudeModel({ model: process.env.SMS_MODEL }), // or createGptModel() from @sms/model-gpt
    plugins: [invoicesPlugin],                       // your modules (docs/writing-plugins.md)
    identity: 'You are the assistant inside sm-erp. You can extend the ERP itself.',
    adminToken: process.env.SMS_ADMIN_TOKEN,         // mutating /api routes: this token, or an admin session
    auth: { bootstrapAdmin: { login: 'root', password: process.env.SMS_ROOT_PASSWORD! } }, // users + rbac + orm guard; `false` = dev only
    // what needs a human; default: scope 'net' and the points in DEFAULT_SENSITIVE_POINTS
    // ('route', 'schedule', 'model-method', 'model-hook', 'automation') — your list replaces it
    judge: { sensitiveScopes: ['net'], sensitivePoints: ['route', 'schedule'] },
    // rpc: true, meta: true — /api/rpc and the view/action/menu points (docs/building-a-ui.md); off by default
  })
}

createBaseline installs, in order: the database key → http → collections → scheduler → auth → rbac → orm (+ the rbac→orm guard) → meta / rpc when enabled → judge → model → agent-loop → admin-api → your plugins; then settle()s and restore()s agent plugins from the log. It throws if a system plugin is not active. You get { kernel, store, http, handle, tick, close } — tick() runs due schedules; the host decides the cadence.

3. Put it on the wire

// src/main.ts
import { createNodeHost } from '@sms/host-node'
import { createApp } from './app.ts'
const app = await createApp()
const server = await createNodeHost({ port: 8787 }).listen(app.handle)
console.log(server.url)

Fastify (your existing app keeps its routes): createFastifyHost({ app: fastify, prefix: '/sms' }).listen(app.handle). Cloudflare: see tenancy.md and examples/cloudflare-worker.

4. Talk to it

curl -s localhost:8787/api/state | jq '.plugins[].id'
curl -s -H "authorization: Bearer $SMS_ADMIN_TOKEN" -H 'content-type: application/json' \
     -d '{"text":"Add a discount field to invoices and a tool that lists overdue ones"}' localhost:8787/api/chat
curl -s localhost:8787/api/state | jq '.pending'          # anything waiting for a human?
curl -s -X POST -H "authorization: Bearer $SMS_ADMIN_TOKEN" localhost:8787/api/approvals/agent.invoice-discount/approve

Your UI does exactly this — building-a-ui.md.

5. Multi-tenant

Replace createBaseline with createTenantPool (one kernel per tenant, each on its own store) — see tenancy.md. examples/erp-fastify-postgres is the full picture on Postgres.

Layout of a downstream repo

sm-erp/
  package.json            @sms/* git deps pinned to one tag
  src/app.ts              composition root (createBaseline / createTenantPool)
  src/main.ts             host driver → listen
  src/plugins/*.ts        your modules (SystemPlugin objects)
  ui/                     your frontend, talks to /api/*
  test/                   boot createApp with createScriptedModel([...]) and assert

Testing tip: createTestBaseline({ plugins, turns }) from @sms/baseline/testkit (or createScriptedModel(turns) from @sms/baseline) replays canned model turns so the whole prompt → judge → mount → use → undo loop runs offline (see packages/baseline/test/baseline.test.ts, examples/reference-node-sqlite/src/demo.ts and writing-plugins.md → Testing).

Upgrading

Bump the tag in every @sms/* specifier (they must match) and pnpm install. Release notes live on the release tags; the event log format is append-only and versions fold forward.

Writing plugins

Everything in the baseline is a plugin, and so is everything you add. There are two kinds:

Both share the same manifest and the same two effects: provide(key, value) and contribute(point, item). The kernel records each and derives its inverse — never write teardown.

A system plugin

import { type CollectionsService, type SystemPlugin, json } from '@sms/baseline'

export const invoicesPlugin: SystemPlugin = {
  manifest: {
    id: 'erp.invoices',           // stable; agent plugins can never take a system id
    version: '0.1.0',
    inject: ['collections'],      // keys read via ctx.get — activation waits until they exist
    contributes: {                // declarative: applied by the kernel, no code needed
      collection: [{ name: 'invoice', fields: [
        { name: 'customer', type: 'text', required: true },
        { name: 'amount', type: 'real', required: true },
        { name: 'paid', type: 'boolean', default: false },
      ] }],
      prompt: [{ section: 'application', order: 20, text: 'Invoices live in the `invoice` collection.' }],
    },
  },
  async activate(ctx) {
    const collections = ctx.get<CollectionsService>('collections')
    await ctx.contribute('tool', {
      name: 'overdue_invoices', description: 'Unpaid invoices past due',
      input_schema: { type: 'object', properties: {} },
      handler: async () => (await collections.list('invoice', { where: { paid: false } })),
    })
    await ctx.contribute('route', {
      method: 'GET', path: '/api/invoices/summary',
      handler: async () => json({ count: (await collections.list('invoice', { limit: 1000 })).length }),
    })
  },
}

Rules that the kernel enforces: you may only get keys you inject, only provide keys you declare in provide, only during activation. Contributions are validated by the point owner and can be rejected (your fiber fails; siblings keep running). Disabling the plugin undoes everything in reverse order.

Depending on other plugins: contracts, inject, optional

A plugin never imports another plugin’s provider. Each one publishes its definitions at @sms/plugin-<x>/contract — X_KEY, X_POINT constants, the service and item types, validators and pure helpers — and that is the only subpath a plugin may import from a sibling (pnpm quality enforces it). Your own plugins follow the same shape: src/contract.ts with the definitions, src/index.ts re-exporting it plus the provider. Composition roots (createBaseline, your app) import the roots.

import { ORM_KEY, type OrmService } from '@sms/plugin-orm/contract'
import { AUDIT_KEY, type AuditService } from '@sms/plugin-audit/contract'

manifest: {
  id: 'erp.invoices', version: '1',
  inject: [ORM_KEY],        // hard: activation waits for it, deactivation follows it
  optional: [AUDIT_KEY],    // soft: used when present — read with ctx.kernel.getValue(AUDIT_KEY)
}

inject is what the kernel reconciles on (a fiber activates only when every injected key exists and is unloaded before its provider). optional declares a soft dependency so it is visible — in FiberView, in the admin API, and to the gate, which fails a plugin that uses another plugin’s contract at runtime or calls getValue(key) without declaring the key in one of the two.

Extension points shipped

Keys: database and objects (system↔system; the host provides them), http, collections, scheduler, model (system provides), judge, agent (system↔system), identity (auth; read-only, agent may inject), identity-admin (auth; system↔system), rbac / rbac-admin, orm, meta (compiled views, actions, menu tree — view() is undefined when nothing was contributed; there is no default view generation) and audit (post(model, id, { body, kind }, ctx)). Define your own with ctx.kernel.defineKey/definePoint and mark trust on them — that is how you keep the agent out of something (never by hiding an object).

Models

@sms/plugin-orm (createOrmPlugin({ contextOf?, prefix? }), install after httpPlugin) turns a model contribution into a table m_<name> on the database key, additively migrated on every boot:

contributes: {
  model: [{
    name: 'invoice',
    fields: {
      number: { kind: 'char', required: true },
      partner: { kind: 'many2one', target: 'contact', onDelete: 'restrict' },
      partner_email: { kind: 'related', path: 'partner.email' },
      state: { kind: 'selection', options: [{ value: 'draft' }, { value: 'paid' }], default: 'draft' },
      lines: { kind: 'one2many', target: 'invoice_line', inverse: 'invoice' },
      tags: { kind: 'many2many', target: 'tag' },
      total: { kind: 'computed', returns: 'float', depends: ['lines.subtotal'], compute: 'compute_total' },
    },
    displayField: 'number',
    order: 'number desc',
  }],
  'model-method': [{
    model: 'invoice', name: 'compute_total',
    // computes get `{ records }` (scalar values of `ids`) and answer `{ [id]: value }` — no I/O needed,
    // so an agent plugin can contribute one from inside the executor
    handler: (env, ids, { records }) => Object.fromEntries(records.map((r) => [r.id, /* … */ 0])),
  }],
}

Kinds: char text int float bool date datetime json selection many2one one2many many2many computed related. Every model has id, display (from displayField, default name), created_at/updated_at, created_by/updated_by. Defaults accept $uid, $now, $today.

System plugins talk to the orm key (system-only):

const orm = ctx.get<OrmService>('orm')
const ids = await orm.search('invoice', [['state', '=', 'draft'], '|', ['total', '>', 100], ['partner.name', 'ilike', 'acme']], ctx, { limit: 20 })
const [inv] = await orm.read('invoice', ids, { number: {}, partner: { email: {} }, lines: { subtotal: {} } }, ctx)
await orm.write('invoice', ids, { lines: [{ op: 'create', values: { qty: 2 } }] }, ctx)   // x2many commands: create/update/delete/link/unlink/set or a bare id list
await orm.readGroup('invoice', { domain: [], groupBy: ['state', 'created_at:month'], aggregates: { sum: 'sum:total' } }, ctx)
orm.on('write', ({ model, ids, values }) => { /* automation, audit */ })

Domains are prefix notation (& implicit, |, !), ops = != < <= > >= in not in like ilike (a like value without % is a literal substring — %, _, \ are escaped and it is wrapped in %…%; a value containing % is used as a raw pattern); dotted paths cross relations. ctx is { userId?, isAdmin?, sudo? }; sudo bypasses the guard. An access-control plugin narrows every operation with orm.setGuard({ can({ ctx, model, op }), domain({ ctx, model, op }) }). orm.spec(model) is the resolved schema a UI can render forms from; REST lives under /api/orm (docs/building-a-ui.md). Handlers owned by agent plugins run in the executor and get env = { model, ctx }; system handlers also get env.orm.

Automation and audit (@sms/plugin-automation, @sms/plugin-audit)

Both are ordinary plugins: [...] entries, installed after the ORM and rbac. createAutomationPlugin() owns the automation point: on create/write/unlink of a model (optionally only when a watched field changed and the record still matches filter) or every everyMinutes (the scheduler ticks automation.tick, last runs are kept in au_automation_run), it calls a model method, writes values, posts an audit note (when audit is provided — otherwise a no-op) or runs an inline handler — all as sudo, guarded against re-entering itself. createAuditPlugin({ contextOf, group? }) provides audit and the audit_message / audit_activity / audit_follower models (user references are plain ints), tracks the fields listed in audit-track contributions, cascades on unlink and serves /api/audit/.... group contributes the rbac access rows and the “own activities” rule for that group; without it, grant access yourself (under rbac the models are closed by default).

Your own extension point

activate(ctx) {
  const kernel = ctx.kernel!
  kernel.definePoint({
    name: 'report',
    description: 'A report the finance page shows: { title, query }',
    validate: (item) => { if (typeof (item as { title?: unknown }).title !== 'string') throw new Error('title required') },
  })
  kernel.observePoint<Report>('report', {
    added: (c) => reports.set(c.id, c.item),     // react
    removed: (c) => reports.delete(c.id),        // the exact inverse — the kernel calls it on undo
  })
}

removed must be a true inverse of added; the kernel does the bookkeeping, you do the reaction.

Gates and invariants: your safety policy

await ctx.contribute('gate', {
  name: 'no-finance-writes',
  run: ({ manifest }) => manifest.contributes?.['collection-hook']?.some((h) => (h as { collection: string }).collection === 'ledger')
    ? 'agent plugins may not hook the ledger' : undefined,
})
await ctx.contribute('invariant', {
  name: 'ledger-intact',
  check: (kernel) => { if (!kernel.has('ledger')) throw new Error('ledger service withdrawn') },
})

Both points are system-only: the agent cannot see, add or remove them. Pair them with judge.sensitiveScopes / sensitivePoints in createBaseline to decide what needs a human (default: scope net and DEFAULT_SENSITIVE_POINTS = route, schedule, model-method, model-hook, automation).

Agent plugins

The model defines them through the plugin_define tool; you can submit the same shape yourself with kernel.getValue<JudgeService>('judge').submit(manifest, 'me'). Ids must start with agent.. Code is an ES module with no imports:

export default async function activate(cap) {
  await cap.contribute('tool', {
    name: 'high_value_invoices', description: 'Invoices over 10k',
    input_schema: { type: 'object', properties: {} },
    handler: async () => (await cap.invoke('collections', 'list', 'invoice', { limit: 500 })).filter((i) => i.amount > 10000),
  })
}

cap.get / invoke return JSON snapshots; functions inside contributed items become host-callable refs and stop working the instant the plugin is disposed. In the QuickJS executor the code also has a memory limit and a CPU deadline per slice; there are no timers, no fetch, no process.

Testing your plugins

@sms/baseline/testkit boots a real baseline (in-memory SQLite, Node executor, scripted model, approvals skipped) and gives you a fetch-style call:

import { call, createTestBaseline } from '@sms/baseline/testkit'
const app = await createTestBaseline({ plugins: [invoicesPlugin], turns: [() => 'pong'] })
expect((await call(app, '/api/collections/invoice', { body: { total: 3 } })).status).toBe(200)
expect((await call(app, '/api/chat', { body: { text: 'hi' } })).json.reply).toBe('pong')
await app.tick() // run due schedules
await app.close()

Auth and rbac are off by default (open admin routes, sudo ORM); pass auth: { iterations: 1000, bootstrapAdmin } to test permissions. Pass store / executor to test on the exact drivers production uses — for Cloudflare, openDurableObjectStore(fakeSqlStorage()) from @sms/store-do/testing with QuickJSExecutor.

Persistence

Installed/enabled state is an event log; bundles are content-addressed blobs. Collection tables are kept when a declaration is withdrawn, so disable/enable never loses data. Your system plugins are re-installed on every boot from code; agent plugins are re-mounted from the log by kernel.restore().

Building a UI

The baseline ships no HTML. The admin-api plugin exposes JSON routes and your application owns the frontend — React, HTMX, a Slack bot, a CLI — whatever your product already is. This keeps the agent’s reach and the human’s approval surface identical no matter how you render them.

Routes (@sms/plugin-admin-api, prefix /api by default)

The ORM routes take their OpContext from createOrmPlugin({ contextOf }) (an auth plugin’s session, for example); with the default {} every request is anonymous and only the guard decides.

One round-trip: /api/rpc (createBaseline({ rpc: true, meta: true }))

Token: authorization: Bearer <adminToken> or x-admin-token. Configure it in createBaseline({ adminToken }). When your app has its own users, a system plugin can admit its admin sessions instead of (or as well as) the token by contributing to the admin-authorizer point (system-only):

contributes: { 'admin-authorizer': [{ name: 'session', authorize: (req) => isAdminSession(cookieValue(req, 'sid')) }] }

With neither a token nor an authorizer, mutating routes are open (local development only). The baseline deliberately knows only “may mutate / may not” — per-user permissions live in your plugins.

Users and sessions (@sms/plugin-auth)

Install createAuthPlugin({ bootstrapAdmin: { login, password } }) and the baseline has users: PBKDF2 passwords (WebCrypto — works in a Worker), cookie sessions, and an admin-authorizer so an admin’s session drives every /api/* route above without the bearer token.

Your own routes ask identity.whoami(req) (key identity, injectable by agent plugins too — it never returns secrets). User management (identity-admin: create, setPassword, setAdmin, deactivate, activate) is a system-only key. Groups and permissions are @sms/plugin-rbac’s job.

Groups and permissions (@sms/plugin-rbac)

“Admin” here means the identity provider (your auth plugin) says isAdmin for the session — not the admin token. In your own routes: await rbac.assertCan({ userId, model, op }) (403 on failure) and AND await rbac.ruleDomain({ userId, model, op }) into the query.

Errors

Every baseline route answers errors as { error: { message, kind } } with a matching status (validation 400, auth 401, forbidden 403, not_found 404, conflict 409, internal 500 — the last one also carries plugin, the owner of the failing route). Use the same shape in your own routes: throw new HttpError(404, 'no such invoice') or return errorJson('bad id', 400) from @sms/plugin-http.

A minimal chat + approvals screen

const api = (path, init = {}) => fetch(path, { ...init, headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', ...init.headers } })
async function send(text) {
  const r = await (await api('/api/chat', { method: 'POST', body: JSON.stringify({ session: userId, text }) })).json()
  render(r.reply, r.steps)               // show tool calls: plugin_define → verdict, etc.
  refresh()
}
async function refresh() {
  const s = await (await fetch('/api/state')).json()
  renderPending(s.pending)               // approve/reject buttons → POST /api/approvals/:id/approve
  renderPlugins(s.plugins)               // enable/disable toggles for trust === 'agent'
  renderCollections(s.collections)       // tables from schema; rows from /api/collections/:name
}

Showing agent-made UI safely

Agent plugins cannot contribute HTML to the baseline (there is no such point). If your product wants agent-authored panels, define your own extension point in a system plugin (ui-panel: { title, html }), mark it sensitivePoints so a human approves each one, and render the HTML in a sandboxed iframe or through a strict sanitizer. The kernel will validate, record and undo those contributions like any other.

Streaming, long chats

POST /api/chat returns when the turn is done (tool loops included; maxSteps in the agent-loop options). POST /api/chat/stream is the same turn as text/event-stream: one data: <json> frame per AgentEvent (@sms/plugin-agent-loop):

Read it with fetch + ReadableStream (cookies and the bearer token work; EventSource cannot POST): split on blank lines, JSON.parse after data: . The turn keeps running server-side if the client disconnects, and turns on one session run one after another. Your own routes get the same stream from agent.chatStream(session, text) and can return sse(events) from @sms/plugin-http; the agent key is system-only, so such a route lives in one of your system plugins. For durable transcripts implement AgentSessionStore (load on a cache miss, append per message) and pass a factory as createBaseline({ sessionStore: (kernel) => store }) — it runs before your plugins install, so load() may read any key from the kernel it is given.

Drivers

Host specifics are drivers behind contracts in @sms/contracts (Linux device-driver style, and dsh’s “consumers depend on definitions, never providers”). Plugins and the baseline depend only on the contract; a downstream app picks a driver per concern.

Store drivers

@sms/store-sql turns any Database into a Store (tables kernel_events, kernel_blobs). A driver is therefore just a Database:

export function myDatabase(conn): Database {
  return {
    dialect: 'postgres' | 'sqlite',
    exec: async (sql) => { /* DDL, may be several statements */ },
    query: async (sql, params = []) => rows,  // `?` placeholders; return rows (INSERT … RETURNING id)
    columns: async (table) => [...names],     // [] if the table does not exist
    close: async () => {},
  }
}
export const openMyStore = async (conn) => createSqlStore(myDatabase(conn))

Dialect rules the collections plugin relies on (sqlDialect(dialect) in store-sql): auto-increment id column, BOOLEAN vs INTEGER, DOUBLE PRECISION vs REAL, ? → $n (use numberPlaceholders). All identifiers are validated against ^[a-z][a-z0-9_]{0,40}$ and double-quoted.

• sqlite — node:sqlite, one file per kernel (:memory: for tests), WAL on.
• postgres — pg.Pool from a connectionString (creates the schema, pins search_path per connection) or any { query } client such as PGlite (in-process Postgres, used by the tests). schema = one per tenant.
• do — a Durable Object’s ctx.storage.sql (structural type, no workers-types dependency).
• d1 — a Cloudflare D1 binding (openD1Store(env.DB); structural type). D1 is SQLite without schemas and single-writer per database, so tenancy is one D1 database per tenant — pick the binding by tenant id in createCloudflareApp({ store }). Multi-line DDL is flattened because D1Database.exec runs one statement per line. Use it when a tenant’s data must be reachable outside its Durable Object (dashboards, wrangler d1 queries); store-do is otherwise simpler and faster.

Two suites run against every driver — run both against yours: packages/core/contracts/test/database-contract.ts (databaseContract(name, () => db): DDL, ? binding, columns(), quoting) and packages/plugins/collections/test/contract.ts, which boots the collections plugin on top.

Object storage drivers

ObjectStore is the file/attachment counterpart of Database: an S3-shaped key → bytes store the composition root provides under the key objects (OBJECTS_KEY; createBaseline defines it system ↔ system, same wall as database). Keys are /-separated paths (no leading /, no ..); put accepts a string, bytes or a ReadableStream; get returns metadata plus body (stream) / bytes() / text(); list({ prefix, delimiter, limit, cursor }) pages S3-style and groups folders into prefixes when a delimiter is given. No multipart, no presigned URLs.

• s3 — createS3ObjectStore({ bucket, endpoint, region, accessKeyId, secretAccessKey, sessionToken, forcePathStyle }): Signature V4 over pure fetch + WebCrypto, no aws-sdk, runs in Node and Workers. One driver for AWS S3 (no endpoint), MinIO (endpoint: 'http://localhost:9000' — path style is on whenever an endpoint is set) and R2 from outside Cloudflare (endpoint: 'https://<account>.r2.cloudflarestorage.com', region: 'auto', an R2 API token). Errors are S3Error { status, code }.
• r2 — createR2ObjectStore(env.FILES) on a bucket binding inside a Worker / Durable Object: no credentials, streams pass straight through. Structural R2BucketLike type, no workers-types dependency.

Provide it from your composition root exactly like the database:

{ manifest: { id: 'app.objects', version: '1', provide: [OBJECTS_KEY] },
  activate: (ctx) => ctx.provide(OBJECTS_KEY, createS3ObjectStore({ … })) }

The contract suite packages/core/contracts/test/objects-contract.ts (objectsContract(name, () => store)) runs offline against the memory store and both drivers’ fakes in pnpm test; SMS_LIVE_OBJECTS=1 S3_ENDPOINT=http://localhost:9000 S3_BUCKET=… S3_ACCESS_KEY_ID=… S3_SECRET_ACCESS_KEY=… pnpm test (optional S3_REGION) runs it against a real MinIO / R2 / S3 bucket (a fresh t-…/ prefix per run).

Host drivers

A host takes RequestHandler = (Request) → Promise<Response> and puts it on the wire.

• node — createNodeHost({ port, host }).listen(handle); toRequest/sendResponse are exported for reuse.
• fastify — createFastifyHost({ app, prefix }).listen(handle) mounts a catch-all under prefix on your existing Fastify instance (raw bodies, reply.hijack()), or creates one.
• cloudflare — createCloudflareApp({ resolve, binding, tenant }) returns the Worker fetch and a Durable Object class; each tenant’s DO opens store-do on its SQLite and calls your tenant({ tenantId, env, store }), which returns anything with a handle (a createBaseline() result). One traditional Worker, no Dynamic Workers. store: ({ tenantId, env, state }) => Store swaps the DO SQLite for e.g. openD1Store(env.DB). The driver depends only on contracts, so it can host any RequestHandler.

Executors

Both implement Executor.load(bundle, host, opts?) → { call, dispose } and both pass the same executor tests (packages/drivers/executor/{node,quickjs}/test/executor.test.ts). Guest limits in QuickJS: no timers, no fetch, no process; functions inside contributed items are marshalled as { $fn } refs; every value crossing is JSON.

Model drivers

ModelService.complete({ system, messages, tools }) → { content, stopReason } is stateless and mirrors the Messages API shape: the loop executes tool_use blocks and calls again with tool_results. A driver may also implement stream(req): AsyncIterable<ModelEvent> — the same turn as text_delta / thinking_delta (reasoning, where the provider exposes it) / tool_use (complete calls) events ending in done: { response }, which must equal what complete() returns. Consumers call streamOf(model, req) from @sms/contracts, which falls back to complete() for drivers without it. model-openrouter and model-gpt-oauth stream today; the CLI-backed drivers fall back.

Six drivers ship. Two run on a locally logged-in CLI — a subscription, no API key — which means a Node process that can spawn claude / codex, so neither works in a Worker:

• @sms/model-claude — the Claude Agent SDK (claude login). Kernel tools become an in-process MCP server; one SDK session per conversation, resumed when the system prompt changes.
• @sms/model-gpt — the Codex SDK (codex login). Codex has no in-process tool API, so the driver runs a localhost streamable-HTTP MCP server (bearer token per process) and points each codex exec at it. One codex exec per turn, resumed by thread id; developer_instructions carries the system prompt; read-only sandbox in an empty scratch dir, no network, no web search (Codex’s shell tools cannot be removed, only contained). codex exec forces approval_policy=never and then only auto-approves MCP tools annotated readOnlyHint — the driver marks the kernel’s tools so (they never touch the host; the judge is their gate).

Both are built on SessionBridge from @sms/contracts: an agent SDK runs its own loop and executes tools itself, so the bridge exposes the kernel’s tools to the SDK and makes each tool handler block until the next complete() delivers the matching tool_result, handing the accumulated assistant blocks back to the loop as one turn. A new agent-SDK driver implements SessionBackend (start / setTools / send / close) and calls bridge.onText / toolCall / onTurnEnd / onError from the SDK’s stream. A plain request/response provider (an HTTP model API) needs none of that: map messages and tools in complete() directly, as createScriptedModel does. The two API-key drivers are exactly that, and being pure fetch they run anywhere — Node, Cloudflare Workers, Durable Objects (so does model-openrouter):

• @sms/model-claude-api — @anthropic-ai/sdk, Messages API (createClaudeApiModel({ apiKey, model, effort }); default claude-opus-5, adaptive thinking). Thinking blocks are not ModelContent, so the driver caches those that preceded a tool call and re-attaches them when the loop replays that assistant turn. Pass client to use a Bedrock/Vertex/Foundry client instead.
• @sms/model-gpt-api — openai, Responses API (createGptApiModel({ apiKey, model, effort }); default gpt-5.5, store: false with encrypted reasoning replayed the same way).
• @sms/model-openrouter — openai pointed at https://openrouter.ai/api/v1, Chat Completions (createOpenRouterModel({ apiKey, model, effort, appName, siteUrl }); model is an OpenRouter slug, default anthropic/claude-sonnet-4.5; effort maps to OpenRouter’s unified reasoning.effort, none…max). OpenRouter’s HTTP-200 errors (choices[0].error / finish_reason: 'error') are thrown. OpenRouter’s reasoning_details are cached and replayed before tool calls the same way. One key, any vendor — the simplest way to try a model none of the other drivers cover.

Subscription vs API key: a personal Claude / ChatGPT subscription is officially usable only through the CLI drivers on a machine you log in on; anything serverless or multi-user needs the -api drivers and a key.

• @sms/model-gpt-oauth — the exception, for personal single-user instances: the OAuth tokens codex login writes to ~/.codex/auth.json sent to Codex’s own backend (chatgpt.com/backend-api/codex, Responses-shaped, SSE) with Codex CLI’s headers — the same wiring OpenClaw, Hermes, pi and opencode use. Pure fetch, so it runs in a Worker. createGptOauthModel({ unofficial: true, tokens, store?, model, effort }); tokens is a CodexTokens, or the text of auth.json (in Node: readCodexAuth() from @sms/model-gpt-oauth/node); store (kvTokenStore(kv), or fileTokenStore(path) from /node) persists refreshed tokens. Tokens are refreshed before expiry and once more on a 401. unofficial: true is mandatory because the endpoint is undocumented, fingerprints clients and may change, and OpenAI’s docs say programmatic use should go through API keys and that tokens must not be pooled or shared — never put it behind a multi-user service. SMS_LIVE_MODELS=1 runs its contract on your login.

Any driver must pass packages/core/contracts/test/model-contract.ts (streaming drivers get an extra case that checks the deltas add up to done.response); the -api / -oauth drivers run it offline against a scripted fetch, and live behind SMS_LIVE_MODELS=1 (CLI and oauth drivers: the login; -api drivers: the key in ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY).

Writing a new driver

1. Implement the contract in a new package packages/drivers/<kind>/<name> depending only on @sms/contracts (and @sms/kernel for Executor). Never import a sibling driver — the gate (scripts/quality/layers.ts) allows only the store-sql helper and the listed exceptions (host-fastify → host-node, host-cloudflare → store-do).
2. Reuse the shared tests: store drivers run databaseContract and collectionsContractTests; object stores run objectsContract; executors copy packages/drivers/executor/quickjs/test/executor.test.ts; model drivers run modelContract from packages/core/contracts/test.
3. Add it to tsconfig.build.json references and keep package.json in the standard shape (exports with sms-source / types / import, files: ["dist"]).

Tenancy

The kernel is single-tenant on purpose. One kernel = one event log, one set of plugins, one database, one judge state. Multi-tenancy is a host concern: resolve the tenant from the request, give each tenant its own kernel on its own store. Nothing is shared between tenants except code, so an agent plugin that one tenant approves can never touch another tenant’s data or schema.

request ──resolve──▶ tenantId ──▶ kernel[tenantId] ──▶ http.handle(request)
                                     │
                                     └── store: sqlite file / postgres schema / durable object

On Node / Fastify: createTenantPool

import { createTenantPool, tenantFromHeader } from '@sms/baseline'
import { openPostgresStore } from '@sms/store-postgres'

const tenants = createTenantPool({
  resolve: tenantFromHeader('x-tenant'),                // or tenantFromSubdomain(), or (req) => jwt(req).org
  tenant: async (id) => ({                               // BaselineOptions for this tenant
    store: await openPostgresStore({ connectionString: DATABASE_URL, schema: `tenant_${id}` }),
    executor, model, plugins: [invoicesPlugin],
    adminToken: tokens[id],
  }),
  idleMs: 30 * 60_000,                                   // close kernels idle for 30 min; they re-boot on demand
})
await createFastifyHost({ app, prefix: '/sms' }).listen(tenants.handle)

• Tenant ids are validated (^[a-z0-9][a-z0-9_-]{0,62}$) because they become file / schema names.
• Booting is memoised per tenant; a failed boot is retried on the next request.
• pool.get(id) returns the tenant’s Baseline (for jobs, migrations, tests); tenants() lists the booted ones; evict(id) closes one; close() closes all.
• A request whose tenant does not resolve gets onMissing(request) (both createTenantPool and createCloudflareApp take it) or a 400 no tenant by default.
• Postgres: one Pool per tenant with search_path pinned to the schema; the store creates the schema. SQLite: one file per tenant (openSqliteStore(data/${id}.db)).

Cost model: a warm kernel is a few objects plus the executor instances of its agent plugins (QuickJS: one small WASM runtime each). Thousands of idle tenants are fine with idleMs; keep hot ones warm.

On Cloudflare: one Durable Object per tenant

const app = createCloudflareApp<Env>({
  resolve: (req, env) => tenantFromSubdomain({ root: env.ROOT_DOMAIN, fallback: 'dev' })(req),
  binding: 'TENANT',
  tenants: (env) => (env.CRON_TENANTS ?? '').split(',').filter(Boolean), // who the cron trigger ticks
  tenant: ({ tenantId, env, store }) =>
    createBaseline({ name: tenantId, store, executor: new QuickJSExecutor({ variant: import('@jitl/quickjs-singlefile-mjs-release-sync') }), model, plugins }),
})
export const TenantKernel = app.DurableObject
export default { fetch: app.fetch, scheduled: app.scheduled }

tenantFromSubdomain({ root, fallback, reserved }) maps acme.example.com → acme, the bare root / localhost / IPs → fallback, acme.localhost → acme (local dev without DNS) and refuses reserved labels (www, api, …). resolve receives env, so root domains can come from wrangler vars.

Scheduled jobs (@sms/plugin-scheduler): a Durable Object cannot enumerate itself, so the Worker’s scheduled() ticks the tenants tenants(env) returns (a wrangler var, a KV list, a registry DO you keep). The tick travels as an internal request the public fetch can never forge. On Node, setInterval(() => pool.tick(), 60_000) does the same for every booted tenant.

The Worker’s fetch resolves the tenant and forwards to TENANT.get(idFromName(tenantId)); the DO opens @sms/store-do on its own SQLite (or whatever the store option returns, e.g. openD1Store(env.DB)), boots the kernel once and keeps it in memory until the platform evicts it (the log + blobs survive in DO storage; restore() re-mounts plugins on the next boot). Single-threaded per DO, transactional storage, global addressing — the Durable Object is the tenant pool.

Sharing across tenants

Share code (system plugins, drivers, the model) — pass the same objects to every tenant. Do not share a Store, an Executor instance’s plugin instances, or admin tokens. If you need cross-tenant features (a marketplace of approved agent plugins, say), implement them as a system plugin that talks to other kernels through the pool — never by pointing two kernels at one log.

Architecture

Where this comes from

The design follows the thesis in the companion research vault (../sms-research): safe live self-modification needs a substrate (revertible effects + reactive dependencies, from Cordis / the Spatiotemporal Composability paper), a judge the agent cannot reach (the lesson of the Darwin Gödel Machine’s objective hacking), and persistence (which DeepSeek Harness deliberately skipped: “scratch, not memory”). No shipped system had all three; this repo is an attempt to — packaged so that other applications can adopt it. docs/research-positioning.md maps every concept to code and carries the threat model.

What we copied, and from whom:

Rings

Deeper is more abstract — the Linux kernel / OSI shape. A package imports its own ring or below; the tree is the diagram, and scripts/quality/layers.ts is the same model as code (pnpm quality enforces it, docs/dependency-graph.md is generated from it by pnpm graph).

ring 4  examples/*                    composition roots: pick drivers, add plugins, listen
ring 3  packages/baseline             @sms/baseline: createBaseline() · createTenantPool() · testkit · re-exports every plugin
ring 2  packages/plugins/*      │     packages/drivers/{store,host,executor,model,objects}/*
        features, platform-free │     one contract each, platform-specific; never import a plugin
        http · collections · judge · agent-loop · admin-api · scheduler · auth · rbac · orm · meta · rpc · automation · audit
ring 1  packages/core/plugin-sdk │    packages/core/contracts
        what agent code sees:    │    the waist: Database · Store · Host · TenantResolver · ModelService · ObjectStore
        cap.provide/contribute/  │    (kernel types only — never plugin-sdk)
        get/invoke/log + channel │
ring 0  packages/core/kernel          loader · registry · fibers · derived undo · event log · trust tiers · Executor interface

The kernel is the single root; every ring above it is a pair of siblings that never import each other and meet only in the ring above. Ring 1 splits ergonomics (plugin-sdk) from vocabulary (contracts); ring 2 is the hourglass: plugins and drivers are siblings on top of contracts, and neither column imports the other. Plugins are also platform-free (no node:*, no SDKs) so they run wherever the kernel runs.

Plugins depend on definitions, never providers (the Cordis rule; Linux modules link against exported symbols, not each other’s source). Each plugin has two faces:

The manifest is the runtime counterpart: inject (hard — the reconciler waits for it and unloads the fiber before its provider) and optional (soft — read with ctx.kernel.getValue, present in FiberView). The gate cross-checks the three: a runtime import of a sibling’s contract, a getValue(key) call, and the manifest must agree. The plugin graph is a DAG.

The kernel

Kernel
├─ keys        name → { value, owner }          + KeyMeta { minProviderTrust, minConsumerTrust }
├─ points      name → Contribution[]            + ExtensionPointMeta { minContributorTrust, validate }
├─ fibers      id   → { manifest, trust, enabled, state, effects[] }
├─ settle()    reconciler: enabled ∧ inject satisfied → activate; disabled ∨ dependency gone → deactivate
├─ log         append-only events; foldTarget(events) = what should be installed/enabled
└─ executor    Executor.load(bundle, HostBridge) for code the kernel will not run in-process

Fiber lifecycle: inactive → loading → active → unloading → inactive, or loading → failed. Activation applies manifest.contributes first (declarative), then runs the plugin’s activate (in-process for system plugins; through the executor for agent plugins). Every provide/contribute pushes an AppliedEffect with its inverse. A throw anywhere unwinds what ran.

Ordering (Cordis Thm 63, “provider outlives consumers”): deactivating a fiber first deactivates every active fiber that injects one of its provided keys, recursively, then undoes its own effects. settle() then re-activates whatever became satisfiable again.

Trust tiers: system (installed by the composition root, in-process, holds ctx.kernel) and agent (proposed at run time; never holds KernelApi). Keys and points carry minimum trust; Registry.get/provide/ contribute check it every time. Kernel.propose() refuses an agent manifest without a MountAuthorization minted by Kernel.authorize() — which is only reachable through ctx.kernel, i.e. from system code. A forged or reused nonce, or a manifest whose code hash differs from the authorized one, is rejected. An agent manifest whose id belongs to a system fiber is rejected (RESERVED_ID) — otherwise “update” would replace the judge itself — and uninstall refuses system fibers unless the composition root passes force.

Executor boundary: plugin code never receives objects. It gets cap whose calls go over a bridge to the kernel’s HostBridge, which re-checks inject and trust on every get/invoke. Functions inside contributed items are marshalled as { $fn: id } and turned into async proxies by the kernel, so a tool handler written by the agent is callable by the host, and stops working the instant the fiber is disposed. Values flowing to plugin code are JSON snapshots.

Drivers (the “device” layer)

@sms/contracts defines what a host must supply; the baseline and plugins depend on that, never on an engine:

Every store driver passes packages/core/contracts/test/database-contract.ts and the collections contract suite; object stores pass packages/core/contracts/test/objects-contract.ts; both executors pass the same executor tests; model drivers pass packages/core/contracts/test/model-contract.ts. See docs/drivers.md.

Persistence

The event log is the source of truth; mounted state is a cache. plugin/installed (with manifest and code hash), plugin/enabled, plugin/disabled, plugin/uninstalled fold into a target map. Kernel.restore() re-creates agent fibers from that map (fetching code from the blob store by hash) and settles. System plugins are re-installed by the composition root each boot; their enabled flag is taken from the log. fiber/*, judge/* and chat/* events are audit only. Tables: kernel_events, kernel_blobs, c_<collection>; withdrawing a collection or field keeps its table/column.

Tenancy

The kernel is single-tenant. createTenantPool({ resolve, tenant }) boots one baseline per tenant id on its own store (file / schema / DO) and routes each request; on Cloudflare the Durable Object is that pool entry. Tenant ids are validated because they become file and schema names. See docs/tenancy.md.

The judge (a plugin)

Gates (the gate point, system-only): manifest → trust → source-lint → load (activate in a throwaway executor with a recording bridge; provided keys must be declared; unknown points fail). Then policy: sensitive scopes/points → pending human approval (/api/approvals). Then mount, then invariant contributions run against the live kernel; a violation rolls back and, for an update, restores the previous version from the log + blobs.

The judge is unreachable from agent code by four independent facts: judge is a system-only key; gate and invariant are system-only points; authorization minting lives on KernelApi; and system plugin ids are reserved (the judge additionally requires agent ids to start with agent.). The services other plugins rely on (http, collections, model, agent, database) can only be provided by system fibers. Tests: packages/core/kernel/test, packages/plugins/judge/test, packages/baseline/test.

Admin surface (headless)

plugin-admin-api contributes JSON routes only: /api/state, /api/catalog, /api/chat, plugin enable/disable/uninstall, approvals, /api/events. Users, groups and models come from @sms/plugin-auth, @sms/plugin-rbac and @sms/plugin-orm; createBaseline installs all three (auth: false opts out of the first two) and plugs rbac into the ORM’s guard: anonymous requests are denied, users pass the access matrix and record rules ($uid = caller), sudo contexts bypass. Mutating routes require the bearer token (createBaseline({ adminToken })) or the nod of an admin-authorizer contribution (system-only point — an auth plugin admitting its own admin sessions). There is no HTML and no UI extension point in the baseline; a consumer renders whatever it wants on top (docs/building-a-ui.md). Agent-authored UI, if a product wants it, is a consumer-defined extension point marked sensitive.

Containment

Neither executor can reach the judge or the kernel; that boundary is the trust tier, not the sandbox.

Cloudflare (one Worker, one Durable Object class)

Dynamic Workers (worker_loader) would give a stronger per-plugin boundary but was ruled out for v1 to keep to one traditional Worker; QuickJS provides the per-plugin boundary inside the DO.

Packaging

Development runs TypeScript directly; releases are git tags pointing at detached release commits with dist/ committed and workspace:* rewritten to github:…#tag&path:/packages/x, cut by .github/workflows/cd.yml when a vX.Y.Z tag is pushed after pnpm check (scripts/release.ts, docs/releasing.md). Package exports carry an sms-source condition for in-repo source resolution and default to dist/.

Extension points shipped

Keys: database (system↔system), http, collections, model (system provides), judge (system↔system), agent (system↔system).

Dependency graph

Workspace packages by ring (deeper = more abstract; an edge points at what a package depends on). The layering rules that keep it this shape are in scripts/quality/layers.ts and docs/quality.md.

flowchart BT
  subgraph ring_kernel["ring 0 · kernel"]
    kernel["@sms/kernel"]
  end
  subgraph ring_contracts["ring 1 · contracts"]
    contracts["@sms/contracts"]
  end
  subgraph ring_plugin_sdk["ring 1 · plugin-sdk"]
    plugin_sdk["@sms/plugin-sdk"]
  end
  subgraph ring_driver["ring 2 · drivers"]
    executor_node["@sms/executor-node"]
    executor_quickjs["@sms/executor-quickjs"]
    host_cloudflare["@sms/host-cloudflare"]
    host_fastify["@sms/host-fastify"]
    host_node["@sms/host-node"]
    model_claude["@sms/model-claude"]
    model_claude_api["@sms/model-claude-api"]
    model_gpt["@sms/model-gpt"]
    model_gpt_api["@sms/model-gpt-api"]
    model_gpt_oauth["@sms/model-gpt-oauth"]
    model_openrouter["@sms/model-openrouter"]
    objects_r2["@sms/objects-r2"]
    objects_s3["@sms/objects-s3"]
    store_d1["@sms/store-d1"]
    store_do["@sms/store-do"]
    store_postgres["@sms/store-postgres"]
    store_sql["@sms/store-sql"]
    store_sqlite["@sms/store-sqlite"]
  end
  subgraph ring_plugin["ring 2 · plugins"]
    plugin_admin_api["@sms/plugin-admin-api"]
    plugin_agent_loop["@sms/plugin-agent-loop"]
    plugin_audit["@sms/plugin-audit"]
    plugin_auth["@sms/plugin-auth"]
    plugin_automation["@sms/plugin-automation"]
    plugin_collections["@sms/plugin-collections"]
    plugin_http["@sms/plugin-http"]
    plugin_judge["@sms/plugin-judge"]
    plugin_meta["@sms/plugin-meta"]
    plugin_orm["@sms/plugin-orm"]
    plugin_rbac["@sms/plugin-rbac"]
    plugin_rpc["@sms/plugin-rpc"]
    plugin_scheduler["@sms/plugin-scheduler"]
  end
  subgraph ring_baseline["ring 3 · baseline"]
    baseline["@sms/baseline"]
  end
  subgraph ring_app["ring 4 · apps"]
    example_cloudflare_worker["@sms/example-cloudflare-worker"]
    example_erp_fastify_postgres["@sms/example-erp-fastify-postgres"]
    example_reference_node_sqlite["@sms/example-reference-node-sqlite"]
  end
  contracts --> kernel
  executor_node --> kernel
  executor_node --> plugin_sdk
  executor_quickjs --> kernel
  host_cloudflare --> contracts
  host_cloudflare --> store_do
  host_fastify --> contracts
  host_fastify --> host_node
  host_node --> contracts
  model_claude --> contracts
  model_claude --> kernel
  model_claude_api --> contracts
  model_claude_api --> kernel
  model_gpt --> contracts
  model_gpt --> kernel
  model_gpt_api --> contracts
  model_gpt_api --> kernel
  model_gpt_oauth --> contracts
  model_gpt_oauth --> kernel
  model_openrouter --> contracts
  model_openrouter --> kernel
  objects_r2 --> contracts
  objects_s3 --> contracts
  store_d1 --> contracts
  store_d1 --> store_sql
  store_do --> contracts
  store_do --> store_sql
  store_postgres --> contracts
  store_postgres --> store_sql
  store_sql --> contracts
  store_sql --> kernel
  store_sqlite --> contracts
  store_sqlite --> store_sql
  plugin_admin_api --> kernel
  plugin_admin_api --> plugin_agent_loop
  plugin_admin_api --> plugin_auth
  plugin_admin_api --> plugin_collections
  plugin_admin_api --> plugin_http
  plugin_admin_api --> plugin_judge
  plugin_admin_api --> plugin_scheduler
  plugin_agent_loop --> contracts
  plugin_agent_loop --> kernel
  plugin_agent_loop --> plugin_judge
  plugin_audit --> kernel
  plugin_audit --> plugin_http
  plugin_audit --> plugin_orm
  plugin_auth --> contracts
  plugin_auth --> kernel
  plugin_auth --> plugin_http
  plugin_automation --> contracts
  plugin_automation --> kernel
  plugin_automation --> plugin_audit
  plugin_automation --> plugin_orm
  plugin_collections --> contracts
  plugin_collections --> kernel
  plugin_collections --> plugin_http
  plugin_http --> kernel
  plugin_judge --> kernel
  plugin_meta --> kernel
  plugin_meta --> plugin_orm
  plugin_orm --> contracts
  plugin_orm --> kernel
  plugin_orm --> plugin_http
  plugin_rbac --> contracts
  plugin_rbac --> kernel
  plugin_rbac --> plugin_auth
  plugin_rbac --> plugin_http
  plugin_rpc --> kernel
  plugin_rpc --> plugin_auth
  plugin_rpc --> plugin_http
  plugin_rpc --> plugin_meta
  plugin_rpc --> plugin_orm
  plugin_rpc --> plugin_rbac
  plugin_scheduler --> contracts
  plugin_scheduler --> kernel
  baseline --> contracts
  baseline --> executor_node
  baseline --> kernel
  baseline --> plugin_admin_api
  baseline --> plugin_agent_loop
  baseline --> plugin_auth
  baseline --> plugin_collections
  baseline --> plugin_http
  baseline --> plugin_judge
  baseline --> plugin_meta
  baseline --> plugin_orm
  baseline --> plugin_rbac
  baseline --> plugin_rpc
  baseline --> plugin_scheduler
  baseline --> plugin_sdk
  baseline --> store_sql
  baseline --> store_sqlite
  example_cloudflare_worker --> baseline
  example_cloudflare_worker --> executor_quickjs
  example_cloudflare_worker --> host_cloudflare
  example_cloudflare_worker --> model_claude_api
  example_cloudflare_worker --> model_gpt_api
  example_cloudflare_worker --> model_gpt_oauth
  example_cloudflare_worker --> model_openrouter
  example_cloudflare_worker --> objects_r2
  example_cloudflare_worker --> store_d1
  example_cloudflare_worker --> store_do
  example_erp_fastify_postgres --> baseline
  example_erp_fastify_postgres --> executor_quickjs
  example_erp_fastify_postgres --> host_fastify
  example_erp_fastify_postgres --> model_claude
  example_erp_fastify_postgres --> store_postgres
  example_reference_node_sqlite --> baseline
  example_reference_node_sqlite --> executor_node
  example_reference_node_sqlite --> host_node
  example_reference_node_sqlite --> model_claude
  example_reference_node_sqlite --> model_claude_api
  example_reference_node_sqlite --> model_gpt
  example_reference_node_sqlite --> model_gpt_api
  example_reference_node_sqlite --> model_gpt_oauth
  example_reference_node_sqlite --> model_openrouter
  example_reference_node_sqlite --> store_sqlite

Research positioning

The companion vault (../sms-research, see wiki/thesis.md) argues that safe live self-modification needs three things no shipped system combined: a substrate with revertible effects and reactive dependencies (Cordis / Spatiotemporal Composability), a judge outside the agent’s write set (the lesson of the Darwin Gödel Machine’s objective hacking), and persistence with an audit trail (what DeepSeek’s dsh deliberately skipped — “scratch, not memory”). sms-baseline is the attempt to have all three, packaged so that ordinary applications can adopt it.

The four questions, answered for sms-baseline

The vault compares systems along what / who / when / judge and the lifecycle Bootstrap → Propose → Evaluate → Commit → Serve. Our row:

Concepts from the vault and where they live here

Threat model over the extension points (MLAS-style pass)

Stages: Propose (model calls plugin_define), Evaluate (gates/human), Commit (log + blob), Serve (fiber active).

Open questions (deliberately not solved here)

1. Emissions. activate() code cannot do I/O in QuickJS, but a system-provided service it invokes might. The vocabulary covers registry effects only; side effects through services are the plugin owner’s problem. A “compensating action” contract for services is future work.
2. Evaluator co-evolution. Invariants are frozen per release. The vault’s RQGM answer (freeze per epoch, promote against held-out ground truth) would need a second, offline judge.
3. The human gate at scale. needs-human is a policy on scopes/points. Per-tenant approvers, quorum, and expiry are host concerns to build on /api/approvals.
4. Regulatory. A self-modifying production system is a substantial modification generator in EU AI Act terms; the event log is the evidence trail. Nothing here claims conformity.

Status (2026-08-28)

Implemented and tested: kernel guarantees (15 tests), both executors incl. interrupt/memory limits, judge gates/approval/rollback, collections contract on SQLite / Postgres (PGlite) / D1- and Durable-Object-shaped storage, object storage (S3, R2), node/fastify/cloudflare hosts, the system plugins (admin-api, agent-loop, audit, auth, automation, collections, http, judge, meta, orm, rbac, rpc, scheduler), createBaseline + createTenantPool, end-to-end prompt → judge → mount → restart → undo, and a real pnpm add git+…#tag&path: install of the built packages from a scratch clone. Not run by pnpm test: wrangler/workerd (Cloudflare pieces are tested against structural fakes) and a network Postgres (PGlite stands in), and the CLI/HTTP model drivers against live providers (SMS_LIVE_MODELS=1) or live buckets (SMS_LIVE_OBJECTS=1).

Roadmap: what the Linux kernel still has to teach us

The baseline already borrows the Linux module model (drivers, plugins, EXPORT_SYMBOL-style trust on keys). Linux has several other mechanisms for changing a running system safely that map directly onto the needs of self-modifying software. This doc records the mapping and the features we intend to build from it, so future work has a reference and a rationale.

Status legend: planned (agreed, not started) · later (worth doing, not scheduled) · rejected (with reason).

The mapping

Planned features (the 80% cut)

Three features give most of the value; each rides on state the kernel already tracks. Order: §1 → §3 → §2.

§1 Taint flags — planned, ~1 day

What. A sticky set of bits on the kernel, set for the kernel’s lifetime the first time something unusual happens:

The set is attached to every kernel error, every log line (packages/core/kernel/src/log.ts), and the admin-api status response.

Why. The first question in every incident with a self-modifying system is “did the agent do this, or did I?” Taint answers it on every failure report without anyone remembering to look. It also strengthens the judge tests: assert that no test path sets TRUST_ESCALATED.

Where. packages/core/kernel — a taint: Set<TaintFlag> on the kernel, set from the provide/contribute resolution path and from assertTrust; exported type in types.ts; surfaced by plugin-admin-api. No new package.

§3 Capability sets per extension point — planned, ~2 days

What. Augment the Trust rank with a set of named capabilities (db.read, db.write, model.complete, plugin.install, trust.grant, …) declared in @sms/contracts.

• A provided key declares the capabilities a consumer needs (requires: ['db.write']).
• A plugin’s capability set is derived from the points it contributes to (an http.route contributor gets db.read, model.complete; an admin.hook contributor also gets plugin.install) — the eBPF “helpers per program type” rule.
• Monotonic: a plugin’s set is always a subset of its author’s set. An agent can write a plugin more restricted than itself, never less (seccomp rule).
• minConsumerTrust: 'system' remains valid as shorthand for “the full set” — backward compatible.

Why. A rank forces “system vs not”. The interesting agent-authored plugins sit in between: may write rows, may not install plugins. Sets give that grain, and the judge’s unreachability tests become mechanical: no capability path from agent to plugin.install.

Where. @sms/contracts (capability names, requires on key metadata), kernel assertTrust → assertCapabilities. Optional follow-up: a static pre-load pass (the eBPF verifier analog) that rejects a plugin source importing keys outside its set before the judge ever runs.

§2 Livepatch-style plugin transition — planned, ~2–3 days

What. Replacing plugin v1 with v2 becomes an explicit, abortable state machine:

active(v1) ──begin──▶ transitioning(v1→v2) ──complete──▶ active(v2)
                             │
                           abort
                             ▼
                          active(v1)

• In-flight work pinned to v1 finishes on v1; new work takes v2.
• “Safe point” = request boundary, signalled by the executor driver.
• complete fires only when every pinned unit has reached a safe point; abort at any time returns to active(v1) using the kernel’s derived undo, so the system can never be half-patched.

Why. “The agent updated itself” is the central story, and it needs a swap that cannot strand the system between versions. We already own both halves (effect undo, observePoint added/removed); this only sequences them and adds a version pin per unit of work.

Where. Kernel (state + pinning); drivers/executor/* supply the safe-point signal; admin-api exposes the transition state and an abort. Builds on §1 (transitions taint on force) and §3 (v2’s capability set must be ⊆ v1’s author’s set).

Later

§4 cgroup-style budgets

Per-plugin / per-agent budgets (model tokens, wall time, rows written) enforced by the host, accounted in a hierarchy the judge can read. Real value, but needs metering in each driver — do after §1–§3.

Others

• Publish the judge’s hook list (the LSM lesson: the canonical list of sensitive operations is the security model).
• Module refcounts: refuse to unload a plugin while another holds its provided key.
• Global lockdown bit: “agent-authored plugins must pass judge; human-authored may skip”.
• Safe-mode boot (human-authored plugins only) and tenant-level kernel hot-swap (kexec).
• Kconfig-style satisfiability for the plugin set.
• Write the stable/unstable ABI policy in releasing.md (@sms/contracts never breaks; plugin-sdk internals may).

Rejected (for now)

§5 Kprobe-style undeclared hooks

Attaching to any plugin function without the plugin declaring an extension point. Useful for observability, but it undercuts the “declared points only” safety story that the judge’s unreachability tests rely on. Revisit only as an observation-only input to the judge, never as a way to alter behaviour.

Reading

• eBPF verifier and helpers: Documentation/bpf/verifier.rst, include/uapi/linux/bpf.h
• Livepatch consistency model: Documentation/livepatch/livepatch.rst
• Taint flags: Documentation/admin-guide/tainted-kernels.rst
• Capabilities: capabilities(7); seccomp: seccomp(2)
• Positioning against the research thesis: research-positioning.md

Releasing

The baseline is private: no npm registry. Downstream repos install git tags; each tag points at a release commit (not on any branch) that carries built dist/ and package.jsons whose internal deps point back at the same tag.

Why this shape

• pnpm add github:owner/repo#tag&path:/packages/x installs one subdirectory of a monorepo — but pnpm does not rewrite workspace:* ranges for git dependencies. So in the release commit every "@sms/kernel": "workspace:*" becomes "@sms/kernel": "github:owner/repo#v0.2.0&path:/packages/core/kernel". pnpm then resolves the whole @sms/* graph transitively, deduplicated, one Kernel class in the process.
• Node refuses to type-strip .ts inside node_modules, so consumers need real .js + .d.ts: tsc -b emits dist/ per package (tsconfig.package.json → per-package tsconfig.build.json).
• Development stays build-free: package exports list sms-source → src/index.ts first. tsconfig.json (customConditions), vitest.config.ts (resolve.conditions) and the app scripts (--conditions=sms-source) enable it; consumers never see it (default condition → dist/).
• main never carries build output (dist/ and *.tsbuildinfo are gitignored). Release commits do; they are reachable only through their tag, so no release/* branches exist.

Cutting a release: push a tag

pnpm check                          # no CI on main — the gate runs here first
git tag v0.2.0 && git push origin v0.2.0

That is the whole procedure. .github/workflows/cd.yml (the only workflow in the repo) runs pnpm check, builds, makes a detached release commit with rewritten package.jsons and committed dist/, moves the tag onto that commit, pushes it, and publishes a GitHub Release with the install line. The workflow pins Node 22.14 (newer 22.x changes .ts handling for the worker-thread executor).

Rules:

• The tag must point at a commit on main with a clean workspace layout. CD refuses a tag whose commit is not on main (e.g. one that already points at a release commit).
• Do not re-use a tag name after it has shipped; releases are lockstep (one version for every package).
• Do not push tags from a local pnpm release --push. CD owns the tag: a locally-moved tag makes CD check out the release commit and fail on --frozen-lockfile. If that happens, the tag is still valid — create the GitHub Release by hand (gh release create vX.Y.Z).

Rehearsing locally

scripts/release.ts is what CD runs; you can run it without pushing to see what a release would contain:

pnpm release 0.2.0 --dry-run  # show what would be rewritten
pnpm release 0.2.0            # runs pnpm check, builds, makes a detached release commit, tags it locally
git tag -d v0.2.0                                   # discard the rehearsal
pnpm release 0.2.0 --repo other/fork   # for forks (default: parsed from `git remote get-url origin`)

What the script does: clean tree required → pnpm check → pnpm clean && pnpm build → pnpm check:pkg (publint + arethetypeswrong on the built packages, see docs/quality.md §6) → detach HEAD → for each non-private package: set version, rewrite workspace:* in dependencies/ peerDependencies to git+path specs, drop devDependencies and scripts, rewrite exports to dist only (every subpath kept — ./testkit, ./testing, ./node — just the sms-source condition dropped), git add -f dist → commit → annotated tag → switch back to your branch.

Verifying a release

mkdir /tmp/consumer && cd /tmp/consumer && pnpm init
pnpm add "github:owner/sms-baseline#v0.2.0&path:/packages/baseline" \
         "github:owner/sms-baseline#v0.2.0&path:/packages/drivers/store/sqlite" \
         "github:owner/sms-baseline#v0.2.0&path:/packages/drivers/executor/quickjs"
node -e "import('@sms/baseline').then(m => console.log(Object.keys(m).length, 'exports'))"

The same mechanics were validated with a git+file:// clone in this repo’s development (see the session notes in docs/research-positioning.md → “Status”).

Do not

• Check out a release tag to develop on it (its package.jsons are not a valid workspace).
• Commit dist/ on main.
• Publish a package that imports a sibling driver; consumers must be able to install one driver alone.

Quality gate

pnpm check = typecheck → lint → quality → knip → test:coverage. CD runs it before every release; there is no CI on main (private repo, limited Actions minutes), so run it locally before pushing. pnpm release adds check:pkg (§6) after the build. Benchmarks (pnpm bench, benchmarking.md) are deliberately not part of the gate. Each stage is described below with the reasoning, borrowed from projects that treat quality checks as executable specs rather than advice.

1. Typecheck — tsc --noEmit, strict + noUncheckedIndexedAccess + erasableSyntaxOnly

Unchanged. Types are the first spec.

2. Lint — Biome (biome.json)

Formatter + recommended rules, plus complexity limits in the spirit of ESLint’s complexity/max-params presets used by projects such as Node core and TypeScript-ESLint:

No function is currently grandfathered. If one must be, mark it inline with biome-ignore … grandfathered (score N, expires YYYY-MM-DD): the marker is the tech-debt list — split the function when you next touch it, and delete the marker. The date is enforced (§3, Expiry).

3. Structural rules — pnpm quality (scripts/quality.ts)

A dependency-free checker (TypeScript’s own parser, no build) — the same idea as dependency-cruiser / eslint-plugin-boundaries, but reading the layering straight out of CLAUDE.md so the rule and the doc cannot drift. Rules live in scripts/quality/rules.ts as pure functions with their own tests in scripts/test/, so changing a rule is itself TDD.

Rings (layering). Packages are assigned a ring from their path (scripts/quality/layers.ts is the model; docs/dependency-graph.md, generated by pnpm graph, is the picture — rule graph-doc fails when it is stale):

ring 0  kernel                       imports nothing
ring 1  plugin-sdk | contracts       two siblings over the kernel: what agent code sees | the waist (Database · Store · Host ·
                                     ModelService · ObjectStore, kernel types only); neither imports the other
ring 2  drivers    | plugins         two columns on top of contracts; neither imports the other
ring 3  baseline                     composition: picks plugins, exposes createBaseline / createTenantPool
ring 4  examples/*                   composition roots that also pick drivers

A runtime import may only point at the same ring or below. Additionally:

• kernel, plugin-sdk, contracts and every plugin import no platform code at all (node:*, fastify, @anthropic-ai/*, …) — a plugin must run wherever the kernel runs (Node, Workers, tests).
• Drivers never import each other, except host-fastify → host-node, host-cloudflare → store-do (composition-level, from CLAUDE.md) and the shared SQL helper store-sql.
• Plugins import each other only through @sms/plugin-<x>/contract (below). LAYERING_EXCEPTIONS (dated, per package) exists for grandfathering and is currently empty — keep it that way.
• import type and test files are ignored — types are free, and tests may compose anything.

Plugin contracts (contract-surface). Every plugin ships src/contract.ts (exported as ./contract): keys as export const X_KEY = 'x', point names, service and item types, validators, pure helpers. Nothing reachable from it through relative imports may be src/index.ts or declare a manifest: — a contract has no provider in it, so depending on one never drags a plugin body along (Cordis: “consumers depend on service definitions, never providers”; Linux: modules link against exported symbols, not each other’s source).

Manifest honesty (plugin-inject). The manifest is the dependency declaration the kernel reconciles on, and there are two ways around it that the kernel cannot see: importing another plugin’s contract at runtime, and ctx.kernel.getValue(key). The rule reads every inject/optional array in the plugin (string literals or *_KEY identifiers), and fails when a runtime-imported plugin’s keys appear in neither, or when a getValue() argument is undeclared. Manifests it cannot read statically (spreads, computed keys) are skipped.

Plugin DAG (plugin-cycle). The plugin-to-plugin import graph (runtime and type) must be acyclic.

Package metadata (deps, build-refs). package.json must tell the same story as the imports: every @sms/* in dependencies/peerDependencies obeys the rings (at package level — a plugin may depend on a plugin package; the /contract restriction is on import sites), is imported by src/, and everything src/ imports is declared; a workspace dependency only tests use belongs in devDependencies. Each package’s tsconfig.build.json references must equal its @sms/* dependencies, and the root tsconfig.build.json must list every buildable package.

File length (file-length): ≤ 400 non-blank lines per source file. LIMITS.fileLength.allow is empty; a grandfathered ceiling added there carries an expires date — lower the number as the file shrinks, never raise it.

Parameters (max-params): ≤ 4 per function/method/constructor. Beyond that, pass an options object (the codebase already does this everywhere — createBaseline(opts), createJudgePlugin(opts)).

Tests present (tests-present): every package with src/ ships test/*.test.ts. Exemptions (LIMITS.testsExempt) are type-only/helper packages (store-sql) and the sample apps under examples/. Model drivers (drivers/model/*) ship the live contract test (SMS_LIVE_MODELS=1) and are only excluded from coverage, since without a CLI login nothing in them executes.

Expiry (expired-exception): every grandfathered exception is a promise with a date, not configuration — LIMITS.fileLength.allow entries and LAYERING_EXCEPTIONS carry expires: 'YYYY-MM-DD', and each biome-ignore … grandfathered marker must say expires YYYY-MM-DD (a marker without a date fails). Once the date passes the gate fails until the debt is paid or the date is extended, deliberately, in a reviewed commit. Borrowed from Prisma’s expiring coverage exceptions.

Output is file:line [rule] message, exit 1 on any violation.

4. Dead code and dependencies — pnpm knip (knip.json)

knip walks the workspace graph from each package’s src/index.ts (and the app/example entrypoints, scripts/, bench/) and reports unused files, exports, dependencies and unlisted imports. Its first run here found four dead workspace dependencies. Exceptions are per-workspace in knip.json: the driver test packages list @sms/plugin-collections/@sms/plugin-http only so the shared contract test resolves; publint/attw are invoked via pnpm exec from scripts/check-pkg.ts. Add to ignore* only with a comment-worthy reason; prefer deleting the thing.

5. Tests and coverage — pnpm test:coverage

Vitest with V8 coverage. Tests are the spec of the system: they describe behaviour, change rarely, and the judge’s unreachability tests are load-bearing for safety (see CLAUDE.md).

TDD is enforced structurally, not by ceremony: a package cannot exist without tests (rule above), and coverage cannot go down (below). The habit that satisfies both is to write the failing test first.

Coverage ratchet. SQLite reaches 100% branch coverage by treating every uncovered line as a defect and never letting the number regress. We take the mechanism, not the number: vitest.config.ts holds thresholds with autoUpdate: true. A run that beats the thresholds rewrites them upward in the config (commit that change); a run below them fails. Never lower a threshold by hand — add a test. Current floor: ~93% lines, ~90% functions, ~89% statements, ~78% branches; the goal is to walk it toward 100.

The ratchet was re-baselined once, on 2026-08-24, when moving from Vitest 2 to 4. Vitest 2’s V8 remapping was non-deterministic — the same tree reported 1037 or 1038 total branches run to run, so a threshold sitting at an exact boundary failed spuriously — and Vitest 4’s AST-aware remapping counts statements and functions on a finer grain (arrow callbacks, per-statement). The numbers changed because the ruler changed; the measurement is now identical across runs, which is what makes a ratchet trustworthy.

Excluded from coverage, each for a stated reason (coverage.exclude): code running in a worker thread or isolate that V8 cannot observe (executor-node/src/worker.ts, plugin-sdk/src/runtime.ts), process entrypoints (main.ts, demo.ts), the credential-bound model adapters, and type-only modules. The HTML report is written to coverage/ (git-ignored) — open coverage/index.html to find the uncovered branches to test next.

6. Package shape — pnpm check:pkg (release only)

After pnpm build, scripts/check-pkg.ts runs publint --strict and arethetypeswrong --pack on every publishable package: package.json exports/types must match what is in dist/, and the packed tarball must resolve types under Node’s ESM resolution the way a consumer sees it (our custom sms-source condition is exactly the kind of thing attw catches when it leaks). It also asserts (scripts/release-exports.ts) that every subpath in the workspace exports survives the release rewrite with import/types present in dist/ — v0.1.1 shipped without @sms/baseline/testkit because release.ts replaced the map instead of rewriting it. pnpm release runs it right after the build; run pnpm build && pnpm check:pkg by hand when changing a package’s exports. It is not in pnpm check because dev has no build step.

Adding a package

Use .claude/skills/new-plugin or .claude/skills/new-driver (they scaffold the shape that passes every rule on the first run), or copy the package shape from CLAUDE.md, add test/<name>.test.ts before src/, run pnpm graph, then pnpm check. The ring is read from the path; if a new kind of package does not fit, extend layerOf in scripts/quality/layers.ts — with a test.

Benchmarks (local only)

pnpm bench runs micro-benchmarks under bench/*.bench.ts with Vitest’s bench (tinybench). They are a local signal, not a gate: they are not part of pnpm check and there is no CI on main (private repo). Shared-runner timings are too noisy to threshold anyway — the projects that gate on perf (Prisma, TanStack Router) do it with CPU-simulation services; everyone else (Node, Deno, Hono, Effect) treats benchmarks as informational. We do the same.

pnpm bench                  # run everything, print the tables
pnpm bench bench/kernel     # one file
pnpm bench:baseline         # write bench/.baseline.json (git-ignored: numbers are machine-specific)
pnpm bench:compare          # re-run and print the delta against the saved baseline

Workflow for a change that might affect performance: pnpm bench:baseline on the base commit, make the change, pnpm bench:compare. Read the mean/p99 columns and the rme (relative margin of error): a delta inside the rme of either run is noise.

What is measured

Benchmarks live in a top-level bench/ directory, outside the package layering on purpose: they import every layer at once, which no package may do. scripts/quality.ts still applies file-length and parameter limits to them; tests-present and layering do not apply (no package.json, app layer).

Adding one

Copy the shape of the nearest file: describe per surface, bench per workload, do all setup inside the bench callback unless it is genuinely shared (then a top-level await plus afterAll teardown, as host-node.bench.ts does with its server). Prefer a workload with a stated N (x100) over a single call, so the number is above the timer’s resolution. Reuse test helpers by relative import (bootCollections, fakeSqlStorage) rather than duplicating boot code.

Known numbers worth watching

From the first run (Apple Silicon, Node 22): installing a 100-plugin chain costs ~40× a 10-plugin chain (settle is superlinear); a full judge submission is dominated by the load gate’s sandbox spin-up (tens of ms) versus microseconds for the static gates; QuickJS mounts an order of magnitude faster than a worker thread but its tool-call round-trip is slower per call. These are observations, not targets.

Vitest 4’s --outputJson/--compare are removed in Vitest 5 (replaced by an in-file bench.compare API); bench:baseline/bench:compare will need rewriting on that upgrade.

The documentation site

The docs you are reading are published as an mdBook site on Cloudflare Pages, deployed by hand from a checkout. The book has two halves:

• Prose — the hand-written docs/*.md in this repo, plus the root README.md as the landing page.
• API reference — generated from the package sources by TypeDoc at build time, never committed.

One-time setup

mdBook is a Rust binary, so pnpm install does not bring it in. Install it once:

cargo install mdbook          # or: brew install mdbook
mdbook --version              # 0.5 or newer

TypeDoc is a dev dependency, so nothing else is needed.

Working on the docs

pnpm docs:dev     # stage + build + serve on http://localhost:3000, opens a browser
pnpm docs:build   # stage + build into .docs-build/book

scripts/docs.ts stages everything into .docs-build/src and then runs mdBook over it (book.toml points src there). .docs-build/ is generated and gitignored — never edit anything under it; your changes are wiped on the next build. Because the sources are staged copies, pnpm docs:dev does not hot-reload edits to docs/*.md: re-run it.

Adding a page

1. Write docs/your-page.md.
2. Add it to docs/SUMMARY.md — that file is the book’s table of contents and the sidebar order. A page that is not in SUMMARY.md is not in the book.
3. Add a row to the table in docs/README.md, which stays the index for people reading on GitHub.

Two entries in SUMMARY.md deliberately do not resolve when browsing docs/ on GitHub: index.md (the root README, staged under that name) and everything under api/ (generated). They resolve in the built book.

The API reference needs no maintenance — it follows the src/index.ts of every package under packages/. TypeDoc names modules after their path, so scripts/docs.ts retitles each page with the package name from its package.json.

Deployment

The docs are not deployed by CI (the only workflow is the release one, cd.yml); deploy from your machine (needs wrangler 4.x and wrangler login, or CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID in the environment; Pages project sms-docs):

pnpm docs:build
wrangler pages deploy .docs-build/book --project-name=sms-docs --branch=main                          # production
wrangler pages deploy .docs-build/book --project-name=sms-docs --branch="$(git branch --show-current)" # preview

The publish-docs skill (.claude/skills/publish-docs) walks through the same steps plus the one-time Pages project setup and Cloudflare Access restrictions.

The docs build is deliberately not part of pnpm check: it needs a binary that is not in the lockfile, and a broken sidebar should not block a release.

API reference

Generated from the package sources by TypeDoc.

• @sms/baseline
• @sms/contracts
• @sms/executor-node
• @sms/executor-quickjs
• @sms/host-cloudflare
• @sms/host-fastify
• @sms/host-node
• @sms/kernel
• @sms/model-claude
• @sms/model-claude-api
• @sms/model-gpt
• @sms/model-gpt-api
• @sms/model-gpt-oauth
• @sms/model-openrouter
• @sms/objects-r2
• @sms/objects-s3
• @sms/plugin-admin-api
• @sms/plugin-agent-loop
• @sms/plugin-audit
• @sms/plugin-auth
• @sms/plugin-automation
• @sms/plugin-collections
• @sms/plugin-http
• @sms/plugin-judge
• @sms/plugin-meta
• @sms/plugin-orm
• @sms/plugin-rbac
• @sms/plugin-rpc
• @sms/plugin-scheduler
• @sms/plugin-sdk
• @sms/store-d1
• @sms/store-do
• @sms/store-postgres
• @sms/store-sql
• @sms/store-sqlite

@sms/baseline

Interfaces

Baseline

Defined in: packages/baseline/src/create-baseline.ts:70

Properties

handle

handle: RequestHandler;

Defined in: packages/baseline/src/create-baseline.ts:75

http.handle bound — hand it to a Host driver.

http

http: HttpService;

Defined in: packages/baseline/src/create-baseline.ts:73

kernel

kernel: Kernel;

Defined in: packages/baseline/src/create-baseline.ts:71

store

store: Store;

Defined in: packages/baseline/src/create-baseline.ts:72

Methods

close()

close(): Promise<void>;

Defined in: packages/baseline/src/create-baseline.ts:78

Returns

Promise<void>

tick()

tick(now?): Promise<TickResult>;

Defined in: packages/baseline/src/create-baseline.ts:77

Run due scheduled jobs (@sms/plugin-scheduler). The host decides the cadence: cron trigger, interval…

Parameters

Returns

Promise<TickResult>

BaselineOptions

Defined in: packages/baseline/src/create-baseline.ts:23

Properties

admin?

optional admin?: Omit<AdminApiOptions, "token">;

Defined in: packages/baseline/src/create-baseline.ts:66

Admin API options beyond the token (prefix).

adminToken?

optional adminToken?: string;

Defined in: packages/baseline/src/create-baseline.ts:64

Bearer token for mutating admin routes. Omit to leave them open (local dev only).

auth?

optional auth?: false | AuthOptions;

Defined in: packages/baseline/src/create-baseline.ts:37

Users, sessions and permissions (@sms/plugin-auth + @sms/plugin-rbac, wired into the ORM’s guard). Default: installed, no users until bootstrapAdmin or identity-admin.create. false = no auth and no rbac: every ORM request runs as sudo — local development only.

autoApprove?

optional autoApprove?: boolean;

Defined in: packages/baseline/src/create-baseline.ts:62

Skip human approval entirely (tests / unattended). Shorthand for judge.autoApprove.

executor

executor: Executor;

Defined in: packages/baseline/src/create-baseline.ts:29

Runs agent-written code. @sms/executor-node (worker threads) or @sms/executor-quickjs (WASM interpreter).

identity?

optional identity?: string;

Defined in: packages/baseline/src/create-baseline.ts:48

First line of the agent’s system prompt.

judge?

optional judge?: Omit<JudgeOptions, "executor">;

Defined in: packages/baseline/src/create-baseline.ts:60

Judge policy. Default: scope net and the route / schedule points need a human (an agent plugin that answers HTTP or runs unattended is not metadata); nothing auto-approved. Pass your own sensitivePoints to replace the default list.

logger?

optional logger?: (...args) => void;

Defined in: packages/baseline/src/create-baseline.ts:67

Parameters

Returns

void

meta?

optional meta?: boolean;

Defined in: packages/baseline/src/create-baseline.ts:44

@sms/plugin-meta: headless views / actions / menus (view, action, menu points). Off by default.

model

model: ModelService;

Defined in: packages/baseline/src/create-baseline.ts:31

The language model behind agent.chat().

name?

optional name?: string;

Defined in: packages/baseline/src/create-baseline.ts:25

Kernel name (shows up in logs and /api/state).

plugins?

optional plugins?: SystemPlugin[];

Defined in: packages/baseline/src/create-baseline.ts:46

Your application’s own system-trust plugins (collections, routes, tools, prompts, gates, invariants…).

rpc?

optional rpc?: 
  | boolean
| Omit<RpcOptions, "contextOf">;

Defined in: packages/baseline/src/create-baseline.ts:42

@sms/plugin-rpc: batched JSON-RPC over the ORM at /api/rpc (+ /api/rpc/meta), sharing the ORM’s caller resolution. Off by default; true or options (prefix).

sessionStore?

optional sessionStore?: (kernel) => AgentSessionStore;

Defined in: packages/baseline/src/create-baseline.ts:54

Rehydrates chat sessions the agent loop does not hold in memory (fresh process, evicted Durable Object). A factory because the loop installs before your plugins: load() runs at chat time, after settle(), so it may read any key from the kernel it is given.

Parameters

Returns

AgentSessionStore

store

store: Store;

Defined in: packages/baseline/src/create-baseline.ts:27

Persistence driver. The baseline owns it and closes it on close().

TenantPool

Defined in: packages/baseline/src/tenant-pool.ts:17

Properties

handle

handle: RequestHandler;

Defined in: packages/baseline/src/tenant-pool.ts:18

Methods

close()

close(): Promise<void>;

Defined in: packages/baseline/src/tenant-pool.ts:26

Returns

Promise<void>

evict()

evict(tenantId): Promise<void>;

Defined in: packages/baseline/src/tenant-pool.ts:25

Close one tenant’s kernel (it will boot again on the next request).

Parameters

Returns

Promise<void>

get()

get(tenantId): Promise<Baseline>;

Defined in: packages/baseline/src/tenant-pool.ts:20

Get (or boot) a tenant’s kernel.

Parameters

Returns

Promise<Baseline>

tenants()

tenants(): string[];

Defined in: packages/baseline/src/tenant-pool.ts:21

Returns

string[]

tick()

tick(now?): Promise<Record<string, TickResult>>;

Defined in: packages/baseline/src/tenant-pool.ts:23

Run due scheduled jobs on every booted tenant (idle tenants are not woken).

Parameters

Returns

Promise<Record<string, TickResult>>

TenantPoolOptions

Defined in: packages/baseline/src/tenant-pool.ts:6

Properties

idleMs?

optional idleMs?: number;

Defined in: packages/baseline/src/tenant-pool.ts:14

Close kernels idle for this long (ms). Default: never.

onMissing?

optional onMissing?: (request) => Response | Promise<Response>;

Defined in: packages/baseline/src/tenant-pool.ts:12

Response for requests with no tenant. Default: 400.

Parameters

Returns

Response | Promise<Response>

resolve

resolve: TenantResolver;

Defined in: packages/baseline/src/tenant-pool.ts:8

Which tenant a request belongs to.

tenant

tenant: (tenantId) => 
  | BaselineOptions
| Promise<BaselineOptions>;

Defined in: packages/baseline/src/tenant-pool.ts:10

Build the options for a tenant’s kernel: its own store (file / schema / DO), plugins, model…

Parameters

Returns

| BaselineOptions | Promise<BaselineOptions>

Variables

DEFAULT_SENSITIVE_POINTS

const DEFAULT_SENSITIVE_POINTS: string[];

Defined in: packages/baseline/src/create-baseline.ts:21

Extension points whose agent contributions need a human by default.

Functions

createBaseline()

function createBaseline(opts): Promise<Baseline>;

Defined in: packages/baseline/src/create-baseline.ts:114

Compose one kernel: database key → http → collections → scheduler → auth → rbac → orm → [meta, rpc] → judge → model → agent loop → admin api → your plugins, then settle and restore agent plugins from the log. Throws if any system plugin is not active.

Parameters

Returns

Promise<Baseline>

createTenantPool()

function createTenantPool(opts): TenantPool;

Defined in: packages/baseline/src/tenant-pool.ts:33

Kernel-per-tenant. The kernel itself is single-tenant by design (one log, one plugin set, one database); tenancy is a host concern. On Cloudflare a Durable Object plays this role instead.

Parameters

Returns

TenantPool

References

Access

Re-exports Access

ACCESS_POINT

Re-exports ACCESS_POINT

ACTION_POINT

Re-exports ACTION_POINT

ActionSpec

Re-exports ActionSpec

Activate

Re-exports Activate

ADMIN_AUTHORIZER_POINT

Re-exports ADMIN_AUTHORIZER_POINT

ADMIN_ROUTES

Re-exports ADMIN_ROUTES

AdminApiOptions

Re-exports AdminApiOptions

AdminAuthorizer

Re-exports AdminAuthorizer

AGENT_KEY

Re-exports AGENT_KEY

AgentEvent

Re-exports AgentEvent

AgentLoopOptions

Re-exports AgentLoopOptions

AgentService

Re-exports AgentService

AgentSessionStore

Re-exports AgentSessionStore

AppliedEffect

Re-exports AppliedEffect

applyOps

Re-exports applyOps

assertObjectKey

Re-exports assertObjectKey

assertTenantId

Re-exports assertTenantId

assertTrust

Re-exports assertTrust

AsyncQueue

Re-exports AsyncQueue

AuthOptions

Re-exports AuthOptions

BlobStore

Re-exports BlobStore

bodyOf

Re-exports bodyOf

bodyToBytes

Re-exports bodyToBytes

buildMenuTree

Re-exports buildMenuTree

CallRequest

Re-exports CallRequest

Cap

Re-exports Cap

catalog

Re-exports catalog

Channel

Re-exports Channel

ChatResult

Re-exports ChatResult

ChatStep

Re-exports ChatStep

cloneNode

Re-exports cloneNode

COLLECTION_FIELD_POINT

Re-exports COLLECTION_FIELD_POINT

COLLECTION_HOOK_POINT

Re-exports COLLECTION_HOOK_POINT

COLLECTION_POINT

Re-exports COLLECTION_POINT

CollectionFieldContribution

Re-exports CollectionFieldContribution

CollectionHook

Re-exports CollectionHook

COLLECTIONS_KEY

Re-exports COLLECTIONS_KEY

CollectionSchema

Re-exports CollectionSchema

collectionsPlugin

Re-exports collectionsPlugin

CollectionsService

Re-exports CollectionsService

Command

Re-exports Command

CompiledView

Re-exports CompiledView

compileFromBase

Re-exports compileFromBase

ComputedField

Re-exports ComputedField

ComputedReturns

Re-exports ComputedReturns

Contribution

Re-exports Contribution

conversationKey

Re-exports conversationKey

cookieValue

Re-exports cookieValue

createAdminApiPlugin

Re-exports createAdminApiPlugin

createAgentLoopPlugin

Re-exports createAgentLoopPlugin

createAuthPlugin

Re-exports createAuthPlugin

createChannel

Re-exports createChannel

createJudgePlugin

Re-exports createJudgePlugin

createMemoryObjectStore

Re-exports createMemoryObjectStore

createMetaService

Re-exports createMetaService

createModelPlugin

Re-exports createModelPlugin

createOrmPlugin

Re-exports createOrmPlugin

createPluginRuntime

Re-exports createPluginRuntime

createReasoningCache

Re-exports createReasoningCache

createRpcPlugin

Re-exports createRpcPlugin

createScriptedModel

Re-exports createScriptedModel

createSessionModel

Re-exports createSessionModel

createSqlStore

Re-exports createSqlStore

Database

Re-exports Database

DATABASE_KEY

Re-exports DATABASE_KEY

deferred

Re-exports deferred

Deferred

Re-exports Deferred

Dialect

Re-exports Dialect

Domain

Re-exports Domain

DomainLeaf

Re-exports DomainLeaf

DomainOp

Re-exports DomainOp

DSL_PROMPT

Re-exports DSL_PROMPT

EffectKind

Re-exports EffectKind

ErrorBody

Re-exports ErrorBody

errorJson

Re-exports errorJson

EventLog

Re-exports EventLog

eventsOf

Re-exports eventsOf

Executor

Re-exports Executor

ExecutorInstance

Re-exports ExecutorInstance

expandGroups

Re-exports expandGroups

ExtensionPointMeta

Re-exports ExtensionPointMeta

FiberState

Re-exports FiberState

FiberView

Re-exports FiberView

Field

Re-exports Field

FieldBase

Re-exports FieldBase

FieldKind

Re-exports FieldKind

FieldSpec

Re-exports FieldSpec

FieldType

Re-exports FieldType

findNode

Re-exports findNode

firstToolUseId

Re-exports firstToolUseId

FN_MARKER

Re-exports FN_MARKER

foldTarget

Re-exports foldTarget

Gate

Re-exports Gate

GATE_POINT

Re-exports GATE_POINT

GateContext

Re-exports GateContext

GateResult

Re-exports GateResult

Group

Re-exports Group

GROUP_POINT

Re-exports GROUP_POINT

GroupRow

Re-exports GroupRow

groupsOf

Re-exports groupsOf

hashPassword

Re-exports hashPassword

HOOK_POINT

Re-exports HOOK_POINT

HookEvent

Re-exports HookEvent

HookPayload

Re-exports HookPayload

Host

Re-exports Host

HostBridge

Re-exports HostBridge

HostServer

Re-exports HostServer

html

Re-exports html

HTTP_KEY

Re-exports HTTP_KEY

HttpError

Re-exports HttpError

httpErrorOf

Re-exports httpErrorOf

httpPlugin

Re-exports httpPlugin

HttpService

Re-exports HttpService

IDENTITY_ADMIN_KEY

Re-exports IDENTITY_ADMIN_KEY

IDENTITY_KEY

Re-exports IDENTITY_KEY

IdentityAdminService

Re-exports IdentityAdminService

IdentityService

Re-exports IdentityService

Invariant

Re-exports Invariant

INVARIANT_POINT

Re-exports INVARIANT_POINT

json

Re-exports json

JUDGE_KEY

Re-exports JUDGE_KEY

JudgeOptions

Re-exports JudgeOptions

JudgeService

Re-exports JudgeService

Kernel

Re-exports Kernel

KernelApi

Re-exports KernelApi

KernelError

Re-exports KernelError

KernelErrorCode

Re-exports KernelErrorCode

KernelEvent

Re-exports KernelEvent

KernelOptions

Re-exports KernelOptions

KeyMeta

Re-exports KeyMeta

KeyObserver

Re-exports KeyObserver

KINDS

Re-exports KINDS

listKeys

Re-exports listKeys

ListObjectsOptions

Re-exports ListObjectsOptions

lowerKeys

Re-exports lowerKeys

Many2manyField

Re-exports Many2manyField

Many2oneField

Re-exports Many2oneField

matchPath

Re-exports matchPath

MemoryBlobStore

Re-exports MemoryBlobStore

MemoryEventLog

Re-exports MemoryEventLog

MENU_POINT

Re-exports MENU_POINT

MenuNode

Re-exports MenuNode

MenuSpec

Re-exports MenuSpec

META_KEY

Re-exports META_KEY

metaPlugin

Re-exports metaPlugin

MetaService

Re-exports MetaService

METHOD_POINT

Re-exports METHOD_POINT

MethodEnv

Re-exports MethodEnv

MODEL_FIELD_POINT

Re-exports MODEL_FIELD_POINT

MODEL_KEY

Re-exports MODEL_KEY

MODEL_POINT

Re-exports MODEL_POINT

ModelContent

Re-exports ModelContent

ModelEvent

Re-exports ModelEvent

ModelFieldContribution

Re-exports ModelFieldContribution

ModelHook

Re-exports ModelHook

ModelMessage

Re-exports ModelMessage

ModelMethod

Re-exports ModelMethod

ModelOnchange

Re-exports ModelOnchange

ModelRequest

Re-exports ModelRequest

ModelResponse

Re-exports ModelResponse

ModelService

Re-exports ModelService

ModelSpec

Re-exports ModelSpec

ModelTool

Re-exports ModelTool

MountAuthorization

Re-exports MountAuthorization

ObjectBody

Re-exports ObjectBody

objectContent

Re-exports objectContent

ObjectContent

Re-exports ObjectContent

ObjectList

Re-exports ObjectList

ObjectMeta

Re-exports ObjectMeta

OBJECTS_KEY

Re-exports OBJECTS_KEY

ObjectStore

Re-exports ObjectStore

ONCHANGE_POINT

Re-exports ONCHANGE_POINT

One2manyField

Re-exports One2manyField

Op

Re-exports Op

OpContext

Re-exports OpContext

OPS

Re-exports OPS

orDomains

Re-exports orDomains

ORM_KEY

Re-exports ORM_KEY

OrmError

Re-exports OrmError

OrmErrorKind

Re-exports OrmErrorKind

OrmEvent

Re-exports OrmEvent

OrmEventPayload

Re-exports OrmEventPayload

OrmGuard

Re-exports OrmGuard

OrmListener

Re-exports OrmListener

OrmOptions

Re-exports OrmOptions

ormPlugin

Re-exports ormPlugin

OrmService

Re-exports OrmService

parseCall

Re-exports parseCall

parseSelector

Re-exports parseSelector

parseToolArgs

Re-exports parseToolArgs

PendingApproval

Re-exports PendingApproval

pickBase

Re-exports pickBase

PluginBundle

Re-exports PluginBundle

PluginContext

Re-exports PluginContext

PluginManifest

Re-exports PluginManifest

PluginModule

Re-exports PluginModule

PluginRuntime

Re-exports PluginRuntime

PointObserver

Re-exports PointObserver

PROMPT_POINT

Re-exports PROMPT_POINT

PromptSection

Re-exports PromptSection

PutObjectOptions

Re-exports PutObjectOptions

Query

Re-exports Query

RBAC_ADMIN_KEY

Re-exports RBAC_ADMIN_KEY

RBAC_KEY

Re-exports RBAC_KEY

RbacAdminService

Re-exports RbacAdminService

rbacPlugin

Re-exports rbacPlugin

RbacService

Re-exports RbacService

ReadGroupRequest

Re-exports ReadGroupRequest

ReadSpec

Re-exports ReadSpec

Rec

Re-exports Rec

Record_

Re-exports Record_

RelatedField

Re-exports RelatedField

replayPrompt

Re-exports replayPrompt

RequestHandler

Re-exports RequestHandler

resolveActivate

Re-exports resolveActivate

Rights

Re-exports Rights

rightsOf

Re-exports rightsOf

Route

Re-exports Route

ROUTE_POINT

Re-exports ROUTE_POINT

RouteRequest

Re-exports RouteRequest

RouteResult

Re-exports RouteResult

RPC_METHODS

Re-exports RPC_METHODS

RpcCall

Re-exports RpcCall

RpcEnv

Re-exports RpcEnv

RpcMessage

Re-exports RpcMessage

RpcMethod

Re-exports RpcMethod

RpcOptions

Re-exports RpcOptions

rpcPlugin

Re-exports rpcPlugin

RpcResult

Re-exports RpcResult

Rule

Re-exports Rule

RULE_POINT

Re-exports RULE_POINT

runOne

Re-exports runOne

ScalarField

Re-exports ScalarField

ScalarKind

Re-exports ScalarKind

Schedule

Re-exports Schedule

SCHEDULE_POINT

Re-exports SCHEDULE_POINT

ScheduledJob

Re-exports ScheduledJob

SCHEDULER_KEY

Re-exports SCHEDULER_KEY

schedulerPlugin

Re-exports schedulerPlugin

SchedulerService

Re-exports SchedulerService

SearchOptions

Re-exports SearchOptions

SearchReadRequest

Re-exports SearchReadRequest

SelectionField

Re-exports SelectionField

serializeCookie

Re-exports serializeCookie

Session

Re-exports Session

SESSION_COOKIE

Re-exports SESSION_COOKIE

SessionBackend

Re-exports SessionBackend

SessionBridge

Re-exports SessionBridge

SessionBridgeOptions

Re-exports SessionBridgeOptions

sha256

Re-exports sha256

sqlDialect

Re-exports sqlDialect

sse

Re-exports sse

Store

Re-exports Store

streamOf

Re-exports streamOf

SubdomainOptions

Re-exports SubdomainOptions

Subject

Re-exports Subject

sudo

Re-exports sudo

SystemPlugin

Re-exports SystemPlugin

TargetEntry

Re-exports TargetEntry

tenantFromHeader

Re-exports tenantFromHeader

tenantFromSubdomain

Re-exports tenantFromSubdomain

TenantResolver

Re-exports TenantResolver

text

Re-exports text

TickResult

Re-exports TickResult

toJson

Re-exports toJson

tokenOf

Re-exports tokenOf

Tool

Re-exports Tool

TOOL_POINT

Re-exports TOOL_POINT

ToolCallResult

Re-exports ToolCallResult

toolSignature

Re-exports toolSignature

toResponse

Re-exports toResponse

transcript

Re-exports transcript

Trust

Re-exports Trust

TRUST_RANK

Re-exports TRUST_RANK

unmarshal

Re-exports unmarshal

User

Re-exports User

validateAccess

Re-exports validateAccess

validateAction

Re-exports validateAction

validateField

Re-exports validateField

validateGroup

Re-exports validateGroup

validateMenu

Re-exports validateMenu

validateModel

Re-exports validateModel

validateModelField

Re-exports validateModelField

validateModelFieldSpec

Renames and re-exports validateField

validateRoute

Re-exports validateRoute

validateRule

Re-exports validateRule

validateSchedule

Re-exports validateSchedule

validateSchema

Re-exports validateSchema

validateView

Re-exports validateView

Values

Re-exports Values

Verdict

Re-exports Verdict

VerdictStatus

Re-exports VerdictStatus

verifyPassword

Re-exports verifyPassword

VIEW_POINT

Re-exports VIEW_POINT

ViewKind

Re-exports ViewKind

ViewNode

Re-exports ViewNode

ViewOp

Re-exports ViewOp

ViewSpec

Re-exports ViewSpec

@sms/contracts

Classes

AsyncQueue

Defined in: packages/core/contracts/src/model-session.ts:43

Push-based async iterable (a queue), e.g. as an SDK’s streaming prompt input.

Type Parameters

Implements

• AsyncIterable<T>

Constructors

Constructor

new AsyncQueue<T>(): AsyncQueue<T>;

Returns

AsyncQueue<T>

Methods

[asyncIterator]()

asyncIterator: AsyncIterator<T>;

Defined in: packages/core/contracts/src/model-session.ts:56

Returns

AsyncIterator<T>

Implementation of

AsyncIterable.[asyncIterator]

close()

close(): void;

Defined in: packages/core/contracts/src/model-session.ts:52

Returns

void

push()

push(v): void;

Defined in: packages/core/contracts/src/model-session.ts:47

Parameters

Returns

void

SessionBridge

Defined in: packages/core/contracts/src/model-session.ts:91

Constructors

Constructor

new SessionBridge(make, opts?): SessionBridge;

Defined in: packages/core/contracts/src/model-session.ts:112

Parameters

Returns

SessionBridge

Properties

historyLength

historyLength: number = 0;

Defined in: packages/core/contracts/src/model-session.ts:110

Length of the loop history at the last complete(); a shorter one means a reset.

Methods

close()

close(): void;

Defined in: packages/core/contracts/src/model-session.ts:265

Returns

void

complete()

complete(req): Promise<ModelResponse>;

Defined in: packages/core/contracts/src/model-session.ts:213

Parameters

Returns

Promise<ModelResponse>

onError()

onError(err): void;

Defined in: packages/core/contracts/src/model-session.ts:164

The SDK stream failed; rejects the in-flight complete() and every blocked tool handler.

Parameters

Returns

void

onText()

onText(text): void;

Defined in: packages/core/contracts/src/model-session.ts:124

Assistant text produced by the SDK.

Parameters

Returns

void

onToolUse()

onToolUse(
   id, 
   name, 
   input
): void;

Defined in: packages/core/contracts/src/model-session.ts:129

The SDK announced a tool call (optional — toolCall synthesises one if it was not announced).

Parameters

Returns

void

onTurnEnd()

onTurnEnd(error?): void;

Defined in: packages/core/contracts/src/model-session.ts:158

The SDK finished its turn; error becomes a trailing text block.

Parameters

Returns

void

toolCall()

toolCall(name, input): Promise<ToolCallResult>;

Defined in: packages/core/contracts/src/model-session.ts:139

The SDK is executing a tool: hand the accumulated assistant blocks to the loop and block until the next complete() brings the result for it.

Parameters

Returns

Promise<ToolCallResult>

Interfaces

Database

Defined in: packages/core/contracts/src/index.ts:33

A relational database as the collections plugin and the SQL store see it. Placeholders are always ? — a driver rewrites them for its engine. Inserts return their id with RETURNING id (SQLite ≥ 3.35, Postgres, DO SQLite all support it).

Properties

dialect

readonly dialect: Dialect;

Defined in: packages/core/contracts/src/index.ts:34

Methods

close()

close(): Promise<void>;

Defined in: packages/core/contracts/src/index.ts:41

Returns

Promise<void>

columns()

columns(table): Promise<string[]>;

Defined in: packages/core/contracts/src/index.ts:40

Column names of a table; [] if it does not exist.

Parameters

Returns

Promise<string[]>

exec()

exec(sql): Promise<void>;

Defined in: packages/core/contracts/src/index.ts:36

Run one or more statements without results (DDL).

Parameters

Returns

Promise<void>

query()

query<T>(sql, params?): Promise<T[]>;

Defined in: packages/core/contracts/src/index.ts:38

Run one statement with ? placeholders and return its rows.

Type Parameters

Parameters

Returns

Promise<T[]>

Deferred

Defined in: packages/core/contracts/src/model-session.ts:27

Type Parameters

Properties

promise

promise: Promise<T>;

Defined in: packages/core/contracts/src/model-session.ts:28

reject

reject: (e) => void;

Defined in: packages/core/contracts/src/model-session.ts:30

Parameters

Returns

void

resolve

resolve: (v) => void;

Defined in: packages/core/contracts/src/model-session.ts:29

Parameters

Returns

void

Host

Defined in: packages/core/contracts/src/index.ts:64

An HTTP host: takes a fetch-style handler and puts it on the wire.

Methods

listen()

listen(handler): Promise<HostServer>;

Defined in: packages/core/contracts/src/index.ts:65

Parameters

Returns

Promise<HostServer>

HostServer

Defined in: packages/core/contracts/src/index.ts:57

Properties

url?

optional url?: string;

Defined in: packages/core/contracts/src/index.ts:59

Base URL when the host listens on a socket (absent for serverless hosts).

Methods

close()

close(): Promise<void>;

Defined in: packages/core/contracts/src/index.ts:60

Returns

Promise<void>

ListObjectsOptions

Defined in: packages/core/contracts/src/objects.ts:28

Properties

cursor?

optional cursor?: string;

Defined in: packages/core/contracts/src/objects.ts:35

Opaque token from a previous page’s cursor.

delimiter?

optional delimiter?: string;

Defined in: packages/core/contracts/src/objects.ts:31

'/' groups keys under the next delimiter into prefixes (folder-style listing).

limit?

optional limit?: number;

Defined in: packages/core/contracts/src/objects.ts:33

Page size; the backend’s own maximum applies.

prefix?

optional prefix?: string;

Defined in: packages/core/contracts/src/objects.ts:29

ModelMessage

Defined in: packages/core/contracts/src/model.ts:14

Properties

content

content: ModelContent[];

Defined in: packages/core/contracts/src/model.ts:16

role

role: "user" | "assistant";

Defined in: packages/core/contracts/src/model.ts:15

ModelRequest

Defined in: packages/core/contracts/src/model.ts:26

Properties

messages

messages: ModelMessage[];

Defined in: packages/core/contracts/src/model.ts:28

system

system: string;

Defined in: packages/core/contracts/src/model.ts:27

tools

tools: ModelTool[];

Defined in: packages/core/contracts/src/model.ts:29

ModelResponse

Defined in: packages/core/contracts/src/model.ts:32

Properties

content

content: ModelContent[];

Defined in: packages/core/contracts/src/model.ts:33

stopReason

stopReason: string;

Defined in: packages/core/contracts/src/model.ts:35

'end_turn', 'tool_use', or a provider-specific reason. The loop only looks at content.

ModelService

Defined in: packages/core/contracts/src/model.ts:49

Properties

name

name: string;

Defined in: packages/core/contracts/src/model.ts:50

Methods

complete()

complete(req): Promise<ModelResponse>;

Defined in: packages/core/contracts/src/model.ts:51

Parameters

Returns

Promise<ModelResponse>

stream()?

optional stream(req): AsyncIterable<ModelEvent>;

Defined in: packages/core/contracts/src/model.ts:53

Optional: the same turn as complete(), incrementally. Consumers use streamOf() to not care.

Parameters

Returns

AsyncIterable<ModelEvent>

ModelTool

Defined in: packages/core/contracts/src/model.ts:19

Properties

description

description: string;

Defined in: packages/core/contracts/src/model.ts:21

input_schema

input_schema: Record<string, unknown>;

Defined in: packages/core/contracts/src/model.ts:23

JSON schema of the tool input (an object schema; type: 'object' is implied).

name

name: string;

Defined in: packages/core/contracts/src/model.ts:20

ObjectContent

Defined in: packages/core/contracts/src/objects.ts:47

A get() result: the metadata plus the bytes, as a stream or collected.

Extends

• ObjectMeta

Properties

body

body: ReadableStream<Uint8Array<ArrayBufferLike>>;

Defined in: packages/core/contracts/src/objects.ts:48

contentType?

optional contentType?: string;

Defined in: packages/core/contracts/src/objects.ts:16

Inherited from

ObjectMeta.contentType

etag?

optional etag?: string;

Defined in: packages/core/contracts/src/objects.ts:18

Backend entity tag (unquoted); absent on backends that do not expose one.

Inherited from

ObjectMeta.etag

key

key: string;

Defined in: packages/core/contracts/src/objects.ts:11

Inherited from

ObjectMeta.key

lastModified

lastModified: number;

Defined in: packages/core/contracts/src/objects.ts:15

Unix ms.

Inherited from

ObjectMeta.lastModified

metadata

metadata: Record<string, string>;

Defined in: packages/core/contracts/src/objects.ts:20

User metadata (x-amz-meta-* / R2 customMetadata). Keys are lower-case.

Inherited from

ObjectMeta.metadata

size

size: number;

Defined in: packages/core/contracts/src/objects.ts:13

Bytes.

Inherited from

ObjectMeta.size

Methods

bytes()

bytes(): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: packages/core/contracts/src/objects.ts:49

Returns

Promise<Uint8Array<ArrayBufferLike>>

text()

text(): Promise<string>;

Defined in: packages/core/contracts/src/objects.ts:50

Returns

Promise<string>

ObjectList

Defined in: packages/core/contracts/src/objects.ts:38

Properties

cursor?

optional cursor?: string;

Defined in: packages/core/contracts/src/objects.ts:43

Present when there is another page.

objects

objects: ObjectMeta[];

Defined in: packages/core/contracts/src/objects.ts:39

prefixes

prefixes: string[];

Defined in: packages/core/contracts/src/objects.ts:41

Only with delimiter.

ObjectMeta

Defined in: packages/core/contracts/src/objects.ts:10

Extended by

• ObjectContent

Properties

contentType?

optional contentType?: string;

Defined in: packages/core/contracts/src/objects.ts:16

etag?

optional etag?: string;

Defined in: packages/core/contracts/src/objects.ts:18

Backend entity tag (unquoted); absent on backends that do not expose one.

key

key: string;

Defined in: packages/core/contracts/src/objects.ts:11

lastModified

lastModified: number;

Defined in: packages/core/contracts/src/objects.ts:15

Unix ms.

metadata

metadata: Record<string, string>;

Defined in: packages/core/contracts/src/objects.ts:20

User metadata (x-amz-meta-* / R2 customMetadata). Keys are lower-case.

size

size: number;

Defined in: packages/core/contracts/src/objects.ts:13

Bytes.

ObjectStore

Defined in: packages/core/contracts/src/objects.ts:53

Methods

delete()

delete(key): Promise<void>;

Defined in: packages/core/contracts/src/objects.ts:59

Idempotent: deleting a missing key is not an error.

Parameters

Returns

Promise<void>

get()

get(key): Promise<ObjectContent | undefined>;

Defined in: packages/core/contracts/src/objects.ts:56

undefined when the key does not exist.

Parameters

Returns

Promise<ObjectContent | undefined>

head()

head(key): Promise<ObjectMeta | undefined>;

Defined in: packages/core/contracts/src/objects.ts:57

Parameters

Returns

Promise<ObjectMeta | undefined>

list()

list(opts?): Promise<ObjectList>;

Defined in: packages/core/contracts/src/objects.ts:60

Parameters

Returns

Promise<ObjectList>

put()

put(
   key, 
   body, 
   opts?
): Promise<ObjectMeta>;

Defined in: packages/core/contracts/src/objects.ts:54

Parameters

Returns

Promise<ObjectMeta>

PutObjectOptions

Defined in: packages/core/contracts/src/objects.ts:23

Properties

contentType?

optional contentType?: string;

Defined in: packages/core/contracts/src/objects.ts:24

metadata?

optional metadata?: Record<string, string>;

Defined in: packages/core/contracts/src/objects.ts:25

SessionBackend

Defined in: packages/core/contracts/src/model-session.ts:69

What a driver supplies: the SDK-specific half of a session.

Methods

close()

close(): void;

Defined in: packages/core/contracts/src/model-session.ts:80

Returns

void

send()

send(text): void | Promise<void>;

Defined in: packages/core/contracts/src/model-session.ts:79

Deliver the user’s text for a new turn.

Parameters

Returns

void | Promise<void>

setTools()

setTools(tools): void | Promise<void>;

Defined in: packages/core/contracts/src/model-session.ts:77

The tool set changed (mid-turn or between turns).

Parameters

Returns

void | Promise<void>

start()

start(
   system, 
   tools, 
   prior
): void | Promise<void>;

Defined in: packages/core/contracts/src/model-session.ts:75

(Re)start the SDK session with this system prompt and tool set. Called before the first user turn and whenever the system prompt changes. prior is the loop’s history before the current message: replay it (see transcript) when the backend cannot resume an earlier session.

Parameters

Returns

void | Promise<void>

SessionBridgeOptions

Defined in: packages/core/contracts/src/model-session.ts:83

Properties

debug?

optional debug?: (...args) => void;

Defined in: packages/core/contracts/src/model-session.ts:86

Parameters

Returns

void

flushDelayMs?

optional flushDelayMs?: number;

Defined in: packages/core/contracts/src/model-session.ts:88

Delay before handing a tool_use batch to the loop, so parallel calls arrive together.

tag?

optional tag?: string;

Defined in: packages/core/contracts/src/model-session.ts:85

Prefix for debug lines, e.g. the driver name.

Store

Defined in: packages/core/contracts/src/index.ts:45

Everything a kernel needs to persist: the event log, bundle blobs, and a database for plugins (key database).

Extended by

• SqliteStore

Properties

blobs

blobs: BlobStore;

Defined in: packages/core/contracts/src/index.ts:48

db

db: Database;

Defined in: packages/core/contracts/src/index.ts:46

log

log: EventLog;

Defined in: packages/core/contracts/src/index.ts:47

Methods

close()

close(): Promise<void>;

Defined in: packages/core/contracts/src/index.ts:49

Returns

Promise<void>

SubdomainOptions

Defined in: packages/core/contracts/src/index.ts:77

Properties

fallback?

optional fallback?: string;

Defined in: packages/core/contracts/src/index.ts:79

Tenant when the host has no tenant label (bare root domain, localhost, an IP).

reserved?

optional reserved?: Iterable<string, any, any>;

Defined in: packages/core/contracts/src/index.ts:83

Labels that are never tenants (www, api…): resolve to undefined.

root?

optional root?: string;

Defined in: packages/core/contracts/src/index.ts:81

The domain tenants live under (example.com). Without it the first label of any host is the tenant.

ToolCallResult

Defined in: packages/core/contracts/src/model-session.ts:22

Properties

content

content: string;

Defined in: packages/core/contracts/src/model-session.ts:23

isError?

optional isError?: boolean;

Defined in: packages/core/contracts/src/model-session.ts:24

Type Aliases

Dialect

type Dialect = "sqlite" | "postgres";

Defined in: packages/core/contracts/src/index.ts:14

ModelContent

type ModelContent = 
  | {
  text: string;
  type: "text";
}
  | {
  id: string;
  input: unknown;
  name: string;
  type: "tool_use";
}
  | {
  content: string;
  is_error?: boolean;
  tool_use_id: string;
  type: "tool_result";
};

Defined in: packages/core/contracts/src/model.ts:9

ModelEvent

type ModelEvent = 
  | {
  text: string;
  type: "text_delta";
}
  | {
  text: string;
  type: "thinking_delta";
}
  | {
  block: Extract<ModelContent, {
     type: "tool_use";
  }>;
  type: "tool_use";
}
  | {
  response: ModelResponse;
  type: "done";
};

Defined in: packages/core/contracts/src/model.ts:43

What a streaming driver emits while producing one turn. Deltas arrive as the provider sends them; tool_use is emitted once a call’s arguments are complete; done always ends the stream and carries the same ModelResponse that complete() would have returned for the request.

ObjectBody

type ObjectBody = string | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;

Defined in: packages/core/contracts/src/objects.ts:8

Bytes going in: a string is UTF-8 encoded; a stream is passed through where the backend supports it.

RequestHandler

type RequestHandler = (request) => Promise<Response>;

Defined in: packages/core/contracts/src/index.ts:55

Parameters

Returns

Promise<Response>

TenantResolver

type TenantResolver = (request) => string | undefined | Promise<string | undefined>;

Defined in: packages/core/contracts/src/index.ts:69

Maps a request to a tenant id. undefined = no tenant (reject or use a default, host’s choice).

Parameters

Returns

string | undefined | Promise<string | undefined>

Variables

DATABASE_KEY

const DATABASE_KEY: "database" = 'database';

Defined in: packages/core/contracts/src/index.ts:53

The key under which the composition root provides the Database (system ↔ system).

MODEL_KEY

const MODEL_KEY: "model" = 'model';

Defined in: packages/core/contracts/src/model.ts:73

The key under which the model driver is provided (system → agent-loop).

OBJECTS_KEY

const OBJECTS_KEY: "objects" = 'objects';

Defined in: packages/core/contracts/src/objects.ts:64

The key under which the composition root provides the ObjectStore (system ↔ system, like database).

Functions

assertObjectKey()

function assertObjectKey(key): void;

Defined in: packages/core/contracts/src/objects.ts:69

Object keys are paths without a leading /, //, ./.. segments or control characters.

Parameters

Returns

void

assertTenantId()

function assertTenantId(id): void;

Defined in: packages/core/contracts/src/index.ts:114

Tenant ids become file names / schema names: keep them boring.

Parameters

Returns

void

bodyToBytes()

function bodyToBytes(body): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: packages/core/contracts/src/objects.ts:75

Collect any ObjectBody into bytes (drivers that cannot stream use this).

Parameters

Returns

Promise<Uint8Array<ArrayBufferLike>>

conversationKey()

function conversationKey(req): string;

Defined in: packages/core/contracts/src/model-session.ts:300

Sessions are identified by the first user message of the loop’s history.

Parameters

Returns

string

createMemoryObjectStore()

function createMemoryObjectStore(): ObjectStore;

Defined in: packages/core/contracts/src/objects.ts:151

In-memory reference implementation: tests, and the contract suite’s oracle.

Returns

ObjectStore

createModelPlugin()

function createModelPlugin(id, model): SystemPlugin;

Defined in: packages/core/contracts/src/model.ts:104

Wrap any ModelService as a system plugin providing model.

Parameters

Returns

SystemPlugin

createReasoningCache()

function createReasoningCache<T>(max?): Pick<Map<string, T>, "get"> & {
  set: void;
};

Defined in: packages/core/contracts/src/model.ts:90

Bounded FIFO map for provider-side reasoning items that must be replayed with the next tool call.

Type Parameters

Parameters

Returns

Pick<Map<string, T>, "get"> & { set: void; }

createScriptedModel()

function createScriptedModel(turns): ModelService & {
  calls: ModelRequest[];
  stream: AsyncIterable<ModelEvent>;
};

Defined in: packages/core/contracts/src/model.ts:115

A scripted model for tests and offline demos: each turn pops the next canned response. stream() replays the same turn as events, text split per word so consumers see several deltas.

Parameters

Returns

ModelService & { calls: ModelRequest[]; stream: AsyncIterable<ModelEvent>; }

createSessionModel()

function createSessionModel(name, session): ModelService & {
  close: void;
};

Defined in: packages/core/contracts/src/model-session.ts:305

A ModelService with one SessionBridge per conversation.

Parameters

Returns

ModelService & { close: void; }

deferred()

function deferred<T>(): Deferred<T>;

Defined in: packages/core/contracts/src/model-session.ts:32

Type Parameters

Returns

Deferred<T>

eventsOf()

function eventsOf(response): Iterable<ModelEvent>;

Defined in: packages/core/contracts/src/model.ts:64

Replay a finished response as events (text as one delta, each tool call, then done).

Parameters

Returns

Iterable<ModelEvent>

firstToolUseId()

function firstToolUseId(content): string | undefined;

Defined in: packages/core/contracts/src/model.ts:85

Id of the first tool_use block — the handle drivers key per-turn provider state (reasoning) on.

Parameters

Returns

string | undefined

listKeys()

function listKeys(entries, opts?): ObjectList;

Defined in: packages/core/contracts/src/objects.ts:119

Shared S3-style listing over a set of objects; used by the memory store and the drivers’ fakes.

Parameters

Returns

ObjectList

lowerKeys()

function lowerKeys(m): Record<string, string>;

Defined in: packages/core/contracts/src/objects.ts:147

Parameters

Returns

Record<string, string>

objectContent()

function objectContent(source): {
  body: ReadableStream<Uint8Array<ArrayBufferLike>>;
  bytes: () => Promise<Uint8Array<ArrayBufferLike>>;
  text: () => Promise<string>;
};

Defined in: packages/core/contracts/src/objects.ts:96

The body part of an ObjectContent from a stream (or bytes).

Parameters

Returns

{
  body: ReadableStream<Uint8Array<ArrayBufferLike>>;
  bytes: () => Promise<Uint8Array<ArrayBufferLike>>;
  text: () => Promise<string>;
}

body

body: ReadableStream<Uint8Array<ArrayBufferLike>>;

bytes

bytes: () => Promise<Uint8Array<ArrayBufferLike>> = collect;

Returns

Promise<Uint8Array<ArrayBufferLike>>

text

text: () => Promise<string>;

Returns

Promise<string>

parseToolArgs()

function parseToolArgs(raw): unknown;

Defined in: packages/core/contracts/src/model.ts:76

Parse a tool call’s JSON arguments string; unparsable text is kept as { _raw } so the tool sees it.

Parameters

Returns

unknown

replayPrompt()

function replayPrompt(prior): string;

Defined in: packages/core/contracts/src/model-session.ts:295

transcript() framed as the opening message of an SDK session that cannot resume.

Parameters

Returns

string

sqlDialect()

function sqlDialect(dialect): {
  bigint: string;
  boolean: string;
  idColumn: string;
  real: string;
};

Defined in: packages/core/contracts/src/index.ts:17

Dialect-specific DDL fragments; pure, shared by store drivers and the collections plugin.

Parameters

Returns

bigint

bigint: string;

boolean

boolean: string;

idColumn

idColumn: string;

auto-increment integer primary key

real

real: string;

streamOf()

function streamOf(model, req): AsyncIterable<ModelEvent>;

Defined in: packages/core/contracts/src/model.ts:57

Stream a turn from any driver: a driver without stream() yields its complete() as one text + done.

Parameters

Returns

AsyncIterable<ModelEvent>

tenantFromHeader()

function tenantFromHeader(header?, fallback?): TenantResolver;

Defined in: packages/core/contracts/src/index.ts:73

Tenant id from a header (default x-tenant), falling back to fallback.

Parameters

Returns

TenantResolver

tenantFromSubdomain()

function tenantFromSubdomain(opts?): TenantResolver;

Defined in: packages/core/contracts/src/index.ts:93

Tenant id from the host-name label under root (acme.example.com → acme). localhost, IPs and the bare root resolve to fallback; acme.localhost → acme for local development without DNS. tenantFromSubdomain('dev') is shorthand for { fallback: 'dev' }.

Parameters

Returns

TenantResolver

toolSignature()

function toolSignature(tools): string;

Defined in: packages/core/contracts/src/model-session.ts:275

Parameters

Returns

string

transcript()

function transcript(messages): string;

Defined in: packages/core/contracts/src/model-session.ts:280

Loop history as plain text, to seed a fresh SDK session that cannot resume.

Parameters

Returns

string

@sms/executor-node

Classes

NodeExecutor

Defined in: packages/drivers/executor/node/src/index.ts:17

Runs each plugin bundle in its own worker thread. Local-dev executor.

Implements

• Executor

Constructors

Constructor

new NodeExecutor(opts?): NodeExecutor;

Defined in: packages/drivers/executor/node/src/index.ts:19

Parameters

Returns

NodeExecutor

Methods

load()

load(
   bundle, 
   host, 
   opts?
): Promise<ExecutorInstance>;

Defined in: packages/drivers/executor/node/src/index.ts:23

Parameters

Returns

Promise<ExecutorInstance>

Implementation of

Executor.load

Interfaces

NodeExecutorOptions

Defined in: packages/drivers/executor/node/src/index.ts:5

Properties

callTimeoutMs?

optional callTimeoutMs?: number;

Defined in: packages/drivers/executor/node/src/index.ts:7

Per-call timeout for calls into plugin code.

resourceLimits?

optional resourceLimits?: {
  maxOldGenerationSizeMb?: number;
  maxYoungGenerationSizeMb?: number;
};

Defined in: packages/drivers/executor/node/src/index.ts:9

Memory limits passed to the worker.

maxOldGenerationSizeMb?

optional maxOldGenerationSizeMb?: number;

maxYoungGenerationSizeMb?

optional maxYoungGenerationSizeMb?: number;

@sms/executor-quickjs

Classes

QuickJSExecutor

Defined in: packages/drivers/executor/quickjs/src/index.ts:90

Implements

• Executor

Constructors

Constructor

new QuickJSExecutor(opts?): QuickJSExecutor;

Defined in: packages/drivers/executor/quickjs/src/index.ts:94

Parameters

Returns

QuickJSExecutor

Methods

load()

load(
   bundle, 
   host, 
   opts?
): Promise<ExecutorInstance>;

Defined in: packages/drivers/executor/quickjs/src/index.ts:108

Parameters

Returns

Promise<ExecutorInstance>

Implementation of

Executor.load

Interfaces

QuickJSExecutorOptions

Defined in: packages/drivers/executor/quickjs/src/index.ts:24

Properties

callTimeoutMs?

optional callTimeoutMs?: number;

Defined in: packages/drivers/executor/quickjs/src/index.ts:37

Overall timeout for a call into the plugin (activate, tool handler…). Default 10 000 ms.

maxStackBytes?

optional maxStackBytes?: number;

Defined in: packages/drivers/executor/quickjs/src/index.ts:33

Stack limit per plugin. Default 1 MiB.

memoryLimitBytes?

optional memoryLimitBytes?: number;

Defined in: packages/drivers/executor/quickjs/src/index.ts:31

Heap limit per plugin. Default 64 MiB.

sliceMs?

optional sliceMs?: number;

Defined in: packages/drivers/executor/quickjs/src/index.ts:35

CPU time one synchronous slice of guest code may take before it is interrupted. Default 2000 ms.

variant?

optional variant?: 
  | QuickJSSyncVariant
  | Promise<
  | QuickJSSyncVariant
  | {
  default: QuickJSSyncVariant;
}>;

Defined in: packages/drivers/executor/quickjs/src/index.ts:29

WASM variant. Default: the Node/browser file-based release build. On Cloudflare Workers pass import('@jitl/quickjs-singlefile-mjs-release-sync') (WASM inlined, no filesystem).

@sms/host-cloudflare

Interfaces

CloudflareApp

Defined in: packages/drivers/host/cloudflare/src/index.ts:72

Type Parameters

Properties

DurableObject

DurableObject: (state, env) => {
  fetch: Promise<Response>;
};

Defined in: packages/drivers/host/cloudflare/src/index.ts:78

The Durable Object class: export { TenantKernel } under the name in wrangler.toml.

Parameters