@xingular/harness 0.0.0-stage → 0.1.1

package/src/accounts/store.ts

@@ -0,0 +1,338 @@
+// Accounts. One profile (settings, registry, memory) and any number of Pi accounts, each with
+// its own isolated agent folder, stored credentials, sign-in state, limits, health, and audit
+// trail.
+//
+// Device-local layout under `<state dir>/accounts/`:
+//   accounts.json        accounts, the default, pools (no secrets)
+//   <id>/state.json      health, plan, limits, last error (no secrets)
+//   <id>/home/pi/        Pi's own agent folder for this account
+//   _shared/pi/          settings, skills, prompts linked into every account's agent folder
+//   audit.jsonl          append-only account actions (secrets scrubbed)
+//
+// Switching is always manual. A pool only chooses an account when a session starts; a running
+// or resumed session keeps the account it started with.
+import { mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { HarnessError, invalid, notFound } from '../core/errors'
+import { appendLine, newId, now, readJsonOr, safeId, writeJson } from '../core/fs'
+import { charCount, compareText, lines, takeChars } from '../core/text'
+
+/** The only provider the harness runs. Records of other providers are kept in the file and ignored. */
+export const PROVIDER = 'pi'
+
+export interface Account {
+  id: string
+  provider: string
+  label: string
+  /** `subscription` (a provider's own sign-in) or `apiKey`. */
+  authKind: string
+  credentialStore?: string
+  createdAt: string
+}
+
+export interface Pool {
+  id: string
+  provider: string
+  label: string
+  accountIds: string[]
+}
+
+interface Registry {
+  accounts: Account[]
+  defaults: Record<string, string>
+  pools: Pool[]
+  migratedProviderKeys: boolean
+}
+
+export interface Limit {
+  id: string
+  label: string
+  usedPercent?: number | null
+  resetsAt?: string | null
+  windowMinutes?: number | null
+  /** `allowed`, `warning`, or `rejected` when the provider reports it. */
+  status?: string | null
+}
+
+export interface Issue {
+  /** `auth_expired`, `rate_limited`, `quota`, `network`, or `unknown`. */
+  category: string
+  message: string
+  at: string
+  resetsAt: string | null
+}
+
+export interface AccountState {
+  /** `ok`, `limited`, `auth_expired`, `signed_out`, `error`, or `unknown`. */
+  health: string
+  signedIn: boolean | null
+  authMethod: string | null
+  plan: string | null
+  identity: string | null
+  limits: Limit[]
+  lastError: Issue | null
+  lastCheckedAt: string | null
+  cliVersion: string | null
+  /** Features detected for this account, e.g. `models:12`, `provider:anthropic`. */
+  capabilities: string[]
+  /** Providers with a stored credential (names only). */
+  piProviders: string[]
+}
+
+export const emptyState = (): AccountState => ({ health: 'unknown', signedIn: null, authMethod: null, plan: null, identity: null, limits: [], lastError: null, lastCheckedAt: null, cliVersion: null, capabilities: [], piProviders: [] })
+
+export type AccountView = Account & { isDefault: boolean; state: AccountState }
+
+export interface AccountsOverview {
+  accounts: AccountView[]
+  pools: Pool[]
+  defaults: Record<string, string>
+}
+
+export interface AuditEntry {
+  at: string
+  accountId: string | null
+  action: string
+  detail: string
+}
+
+// ---- Files ------------------------------------------------------------------------------
+
+const registryPath = (dir: string): string => join(dir, 'accounts.json')
+const statePath = (dir: string, accountId: string): string => join(dir, safeId(accountId), 'state.json')
+
+export function loadRegistry(dir: string): Registry {
+  const stored = readJsonOr<Partial<Registry>>(registryPath(dir), {}) ?? {}
+  return { accounts: stored.accounts ?? [], defaults: stored.defaults ?? {}, pools: stored.pools ?? [], migratedProviderKeys: stored.migratedProviderKeys ?? false }
+}
+
+export function saveRegistry(dir: string, registry: Registry): void {
+  mkdirSync(dir, { recursive: true })
+  writeJson(registryPath(dir), registry)
+}
+
+export function loadState(dir: string, accountId: string): AccountState {
+  try {
+    return { ...emptyState(), ...(readJsonOr<Partial<AccountState>>(statePath(dir, accountId), {}) ?? {}) }
+  } catch {
+    return emptyState()
+  }
+}
+
+function saveState(dir: string, accountId: string, state: AccountState): void {
+  writeJson(statePath(dir, accountId), state)
+}
+
+/** Replaces anything that looks like a token so audit lines and stored errors never hold secrets. */
+export function scrub(text: string): string {
+  const words = text.split(' ').map((word) => {
+    const bytes = Buffer.byteLength(word)
+    const tokenLike = bytes >= 24 && (word.match(/[A-Za-z0-9]/g)?.length ?? 0) * 10 >= bytes * 8
+    return tokenLike || word.startsWith('sk-') || word.startsWith('sess-') ? '[redacted]' : word
+  })
+  return takeChars(words.join(' '), 500)
+}
+
+export function audit(dir: string, accountId: string | null, action: string, detail: string): void {
+  try {
+    mkdirSync(dir, { recursive: true })
+    appendLine(join(dir, 'audit.jsonl'), JSON.stringify({ at: now(), accountId, action, detail: scrub(detail) } satisfies AuditEntry))
+  } catch {
+    // An audit line that cannot be written never fails the action it describes.
+  }
+}
+
+/** The newest audit entries first, optionally for one account. */
+export function readAudit(dir: string, accountId?: string | null, limit = 100): AuditEntry[] {
+  let text = ''
+  try {
+    text = readFileSync(join(dir, 'audit.jsonl'), 'utf8')
+  } catch {
+    text = ''
+  }
+  const entries = lines(text).flatMap((line) => {
+    try {
+      const entry = JSON.parse(line) as AuditEntry
+      return entry && typeof entry.at === 'string' && typeof entry.action === 'string' && (!accountId || entry.accountId === accountId) ? [entry] : []
+    } catch {
+      return []
+    }
+  })
+  return entries.reverse().slice(0, Math.min(limit, 1000))
+}
+
+// ---- Health -----------------------------------------------------------------------------
+
+function inFuture(timestamp: string | null | undefined): boolean {
+  const time = timestamp ? Date.parse(timestamp) : Number.NaN
+  return !Number.isNaN(time) && time > Date.now()
+}
+
+// How long a limit error that came without a reset time keeps the account limited. Providers
+// report no limit windows, so nothing else would ever lift it.
+const UNTIMED_LIMIT_ERROR_SECS = 3600
+
+export const isLimitCategory = (category: string): boolean => category === 'rate_limited' || category === 'quota'
+
+/**
+ * Whether a `rate_limited` or `quota` error still counts. With a reset time it counts until
+ * then; without one it counts for a short while after it was recorded.
+ */
+export function limitErrorActive(issue: Issue): boolean {
+  if (issue.resetsAt) return inFuture(issue.resetsAt)
+  const at = Date.parse(issue.at)
+  return !Number.isNaN(at) && Math.trunc((Date.now() - at) / 1000) < UNTIMED_LIMIT_ERROR_SECS
+}
+
+export function deriveHealth(state: AccountState): string {
+  const limitedByWindow = state.limits.some((limit) => (limit.status === 'rejected' || (limit.usedPercent ?? 0) >= 100) && (!limit.resetsAt || inFuture(limit.resetsAt)))
+  const issue = state.lastError
+  if (issue?.category === 'auth_expired') return 'auth_expired'
+  if (issue && isLimitCategory(issue.category) && limitErrorActive(issue)) return 'limited'
+  if (state.signedIn === false) return 'signed_out'
+  if (limitedByWindow) return 'limited'
+  if (issue && !isLimitCategory(issue.category)) return 'error'
+  return state.signedIn === true ? 'ok' : 'unknown'
+}
+
+/** Read-modify-write on one account's state. Returns the previous health and the new state. */
+export function updateState(dir: string, accountId: string, change: (state: AccountState) => void): { previous: string; state: AccountState } {
+  const state = loadState(dir, accountId)
+  const previous = state.health
+  change(state)
+  state.health = deriveHealth(state)
+  saveState(dir, accountId, state)
+  return { previous, state }
+}
+
+// ---- Lookup and pinning -----------------------------------------------------------------
+
+export function find(dir: string, accountId: string): Account {
+  const account = loadRegistry(dir).accounts.find((entry) => entry.id === accountId)
+  if (!account) throw new HarnessError('account_required', "This session's account was removed.", 'Choose another account for it.')
+  return account
+}
+
+const usable = (state: AccountState): boolean => state.health === 'ok' || state.health === 'unknown'
+
+/**
+ * Chooses the account for a new session: the explicit account, else the pool's first usable
+ * account, else the default, else the first account. It never skips to another one silently.
+ */
+export function resolve(dir: string, accountId?: string | null, poolId?: string | null): Account {
+  const registry = loadRegistry(dir)
+  if (accountId) {
+    const account = find(dir, accountId)
+    if (account.provider !== PROVIDER) throw invalid('That account belongs to another provider.')
+    return account
+  }
+  if (poolId) {
+    const pool = registry.pools.find((entry) => entry.id === poolId)
+    if (!pool) throw notFound('Pool')
+    const members = pool.accountIds.flatMap((id) => registry.accounts.find((account) => account.id === id) ?? [])
+    const ready = members.find((account) => usable(loadState(dir, account.id)))
+    if (ready) return ready
+    const resets = members.flatMap((account) => {
+      const state = loadState(dir, account.id)
+      return [...state.limits.map((limit) => limit.resetsAt), state.lastError?.resetsAt].filter((reset): reset is string => Boolean(reset))
+    })
+    const earliest = resets.sort(compareText)[0]
+    throw new HarnessError('account_unavailable', `Every account in ${pool.label} is unavailable.`, earliest ? `The earliest reset is ${earliest}.` : 'Reauthenticate an account in Accounts.')
+  }
+  const account = registry.accounts.find((entry) => entry.id === registry.defaults[PROVIDER]) ?? registry.accounts.find((entry) => entry.provider === PROVIDER)
+  if (!account) throw new HarnessError('account_required', 'Add a Pi account first.', 'Open Accounts (⌘4) to sign in.')
+  return account
+}
+
+/** The default account, if any exists. */
+export function defaultAccount(dir: string): Account | null {
+  try {
+    return resolve(dir)
+  } catch {
+    return null
+  }
+}
+
+export function summaryAuthentication(dir: string): 'authenticated' | 'unauthenticated' | 'unknown' {
+  const states = loadRegistry(dir).accounts.filter((account) => account.provider === PROVIDER).map((account) => loadState(dir, account.id))
+  if (states.some((state) => state.signedIn === true)) return 'authenticated'
+  return states.some((state) => state.signedIn === false) ? 'unauthenticated' : 'unknown'
+}
+
+export function overview(dir: string): AccountsOverview {
+  const registry = loadRegistry(dir)
+  return {
+    accounts: registry.accounts.filter((account) => account.provider === PROVIDER).map((account) => ({ ...account, isDefault: registry.defaults[account.provider] === account.id, state: loadState(dir, account.id) })),
+    pools: registry.pools.filter((pool) => pool.provider === PROVIDER),
+    defaults: registry.defaults
+  }
+}
+
+// ---- Changes ----------------------------------------------------------------------------
+
+export function cleanLabel(label: string): string {
+  const cleaned = label.trim()
+  if (!cleaned || charCount(cleaned) > 60) throw invalid('Give the account a name of 1–60 characters.')
+  return cleaned
+}
+
+export function addAccount(dir: string, label: string, authKind: string): Account {
+  if (authKind !== 'subscription' && authKind !== 'apiKey') throw invalid('Unknown sign-in type.')
+  const account: Account = { id: newId(), provider: PROVIDER, label: cleanLabel(label), authKind, credentialStore: 'keyring', createdAt: now() }
+  const registry = loadRegistry(dir)
+  registry.defaults[PROVIDER] ??= account.id
+  registry.accounts.push(account)
+  saveRegistry(dir, registry)
+  return account
+}
+
+export function renameAccount(dir: string, accountId: string, label: string): void {
+  const cleaned = cleanLabel(label)
+  const registry = loadRegistry(dir)
+  const account = registry.accounts.find((entry) => entry.id === accountId)
+  if (!account) throw notFound('Account')
+  account.label = cleaned
+  saveRegistry(dir, registry)
+}
+
+export function setDefault(dir: string, accountId: string): Account {
+  const account = find(dir, accountId)
+  const registry = loadRegistry(dir)
+  registry.defaults[account.provider] = account.id
+  saveRegistry(dir, registry)
+  return account
+}
+
+/** Drops the account from the registry, its pools, and the default. Its folder and secrets are the caller's to remove. */
+export function forgetAccount(dir: string, account: Account): void {
+  const registry = loadRegistry(dir)
+  registry.accounts = registry.accounts.filter((entry) => entry.id !== account.id)
+  if (registry.defaults[account.provider] === account.id) {
+    const next = registry.accounts.find((entry) => entry.provider === account.provider)
+    if (next) registry.defaults[account.provider] = next.id
+    else delete registry.defaults[account.provider]
+  }
+  for (const pool of registry.pools) pool.accountIds = pool.accountIds.filter((id) => id !== account.id)
+  saveRegistry(dir, registry)
+}
+
+export function savePool(dir: string, pool: { id?: string; label: string; accountIds: string[] }): Pool {
+  const label = cleanLabel(pool.label)
+  const registry = loadRegistry(dir)
+  for (const id of pool.accountIds) {
+    const account = registry.accounts.find((entry) => entry.id === id)
+    if (!account) throw notFound('Account')
+    if (account.provider !== PROVIDER) throw invalid('A pool holds accounts of one provider.')
+  }
+  const next: Pool = { id: pool.id ? safeId(pool.id) : newId(), provider: PROVIDER, label, accountIds: [...pool.accountIds] }
+  registry.pools = [...registry.pools.filter((existing) => existing.id !== next.id), next]
+  saveRegistry(dir, registry)
+  return next
+}
+
+export function removePool(dir: string, poolId: string): void {
+  const registry = loadRegistry(dir)
+  registry.pools = registry.pools.filter((pool) => pool.id !== poolId)
+  saveRegistry(dir, registry)
+}

package/src/capabilities/api.ts

@@ -0,0 +1,75 @@
+// A generic view of what is available to a caller. The existing plugin, registry, and connector
+// stores remain the source of truth; this module gives hosts one capability-shaped contract.
+import { invalid } from '../core/errors'
+import type { Harness } from '../harness'
+import type { CallerContext } from '../memory/caller'
+import type { Launch } from '../prompt/compile'
+import * as pluginApi from '../plugins/api'
+import type { Plugin } from '../plugins/types'
+import type { Capability, CapabilityCatalogue, CapabilityScope, CapabilitySet } from './types'
+
+export interface ListParams extends CapabilityScope {}
+
+export interface InventoryParams extends CapabilityScope {
+  context?: CallerContext
+  launch?: Launch
+  tools?: string[]
+  connections?: boolean
+}
+
+const unique = (values: readonly string[]): string[] => [...new Set(values.filter((value) => value.length > 0))]
+
+function contributions(plugins: readonly Plugin[]): Capability[] {
+  return plugins.flatMap((plugin) => plugin.contributions.map((item) => ({
+    id: item.id,
+    pluginId: plugin.id,
+    kind: item.kind,
+    name: item.name,
+    description: item.description,
+    source: plugin.source,
+    state: item.state,
+    attachment: item.attachment
+  })))
+}
+
+export async function list(harness: Harness, params: ListParams = {}): Promise<CapabilityCatalogue> {
+  const plugins = await pluginApi.list(harness, params)
+  return { plugins, capabilities: contributions(plugins) }
+}
+
+/** The resolved callable set for one caller, based on the stores and caller-supplied tool list. */
+export async function resolve(harness: Harness, params: ListParams & { tools?: readonly string[] }): Promise<CapabilitySet> {
+  const caller = { agentId: params.agentId ?? null, projectId: params.projectId ?? null }
+  const catalogue = await list(harness, params)
+  const connectors = harness.apps.connections.forScope(caller).map((connection) => connection.id)
+  return {
+    version: 1,
+    tools: unique(params.tools ?? []),
+    connectors: unique(connectors),
+    contributions: catalogue.capabilities.filter((item) => item.state === 'on').map((item) => item.id)
+  }
+}
+
+export function toolIntersection(parent: CapabilitySet, assignee: CapabilitySet, taskTools?: readonly string[]): CapabilitySet {
+  const permitted = taskTools === undefined ? null : new Set(taskTools)
+  return {
+    version: 1,
+    tools: parent.tools.filter((tool) => assignee.tools.includes(tool) && (!permitted || permitted.has(tool))),
+    connectors: parent.connectors.filter((id) => assignee.connectors.includes(id)),
+    contributions: parent.contributions.filter((id) => assignee.contributions.includes(id))
+  }
+}
+
+export function inventory(harness: Harness, params: InventoryParams = {}) {
+  return pluginApi.inventoryFor(harness, params)
+}
+
+export async function attach(harness: Harness, params: pluginApi.AttachParams, on: boolean): Promise<CapabilityCatalogue> {
+  const plugins = await pluginApi.attach(harness, params, on)
+  return { plugins, capabilities: contributions(plugins) }
+}
+
+export async function switchCapability(harness: Harness, params: pluginApi.AttachParams, on: boolean): Promise<CapabilityCatalogue> {
+  if (!params.id.trim()) throw invalid('A capability id is required.')
+  return attach(harness, params, on)
+}

package/src/capabilities/runSnapshot.ts

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { HarnessError, invalid } from '../core/errors'
+import { readJson, safeId, writeJson } from '../core/fs'
+import type { CapabilitySet } from './types'
+
+export interface RunCapabilitySnapshot {
+  version: 1
+  caller: { agentId: string | null; projectId: string | null }
+  tools: string[]
+  connectors: string[]
+  contributions: string[]
+}
+
+const path = (root: string, runId: string): string => join(root, 'runs', safeId(runId), 'capabilities.json')
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? [...new Set(value.filter((item): item is string => typeof item === 'string' && item.length > 0))] : []
+}
+
+export function capabilitySet(value: unknown): CapabilitySet {
+  if (!value || typeof value !== 'object' || (value as { version?: unknown }).version !== 1) throw invalid('A capability set must use version 1.')
+  const record = value as Record<string, unknown>
+  return { version: 1, tools: strings(record.tools), connectors: strings(record.connectors), contributions: strings(record.contributions) }
+}
+
+/** Writes a run's capability set once. A resumed or duplicate launch cannot replace it. */
+export function freezeRun(root: string, runId: string, caller: { agentId?: string | null; projectId?: string | null }, set: CapabilitySet): RunCapabilitySnapshot {
+  const target = path(root, runId)
+  const snapshot: RunCapabilitySnapshot = {
+    version: 1,
+    caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null },
+    tools: strings(set.tools),
+    connectors: strings(set.connectors),
+    contributions: strings(set.contributions)
+  }
+  const existing = existsSync(target) ? readJson<RunCapabilitySnapshot>(target) : null
+  if (existing) {
+    if (JSON.stringify(existing) !== JSON.stringify(snapshot)) throw new HarnessError('capabilities_frozen', 'This run already has a different frozen capability set.')
+    return existing
+  }
+  writeJson(target, snapshot)
+  return snapshot
+}
+
+export function loadRun(root: string, runId: string): RunCapabilitySnapshot | null {
+  const stored = readJson<unknown>(path(root, runId))
+  if (!stored || typeof stored !== 'object' || (stored as { version?: unknown }).version !== 1) return null
+  const record = stored as Record<string, unknown>
+  const caller = record.caller && typeof record.caller === 'object' ? record.caller as Record<string, unknown> : {}
+  return {
+    version: 1,
+    caller: { agentId: typeof caller.agentId === 'string' ? caller.agentId : null, projectId: typeof caller.projectId === 'string' ? caller.projectId : null },
+    tools: strings(record.tools),
+    connectors: strings(record.connectors),
+    contributions: strings(record.contributions)
+  }
+}

package/src/capabilities/types.ts

@@ -0,0 +1,34 @@
+import type { AttachScope, Attachment } from '../plugins/attachments'
+import type { ContributionKind, ContributionState, PluginSource } from '../plugins/types'
+
+export type CapabilityKind = ContributionKind | 'plugin'
+
+/** One item the caller can switch on or off, or that a plugin makes available. */
+export interface Capability {
+  id: string
+  pluginId: string
+  kind: CapabilityKind
+  name: string
+  description: string
+  source: PluginSource
+  state: ContributionState
+  attachment: Attachment | null
+}
+
+export interface CapabilityCatalogue {
+  plugins: import('../plugins/types').Plugin[]
+  capabilities: Capability[]
+}
+
+/** The callable capabilities a run starts with. Permission to run still goes through the gate. */
+export interface CapabilitySet {
+  version: 1
+  tools: string[]
+  connectors: string[]
+  contributions: string[]
+}
+
+export interface CapabilityScope extends AttachScope {
+  cwd?: string | null
+  accountId?: string | null
+}

package/src/cli.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// The `xingular-harness` command.
+//
+//   xingular-harness serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]…
+//                          [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
+//       Serves the harness to a host process over stdin/stdout (newline-delimited JSON).
+//   xingular-harness wiki <command>     Memory and Wiki, from inside a terminal session.
+//   xingular-harness mcp <command>      Connected apps, from inside a terminal session.
+//   xingular-harness plugins <command>  List, install, switch and trust plugins.
+import { log } from './core/bus'
+import { createHarness, type HarnessOptions } from './harness'
+import { runPluginsCli, terminalAsk } from './plugins/cli'
+import { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'
+import { RpcPeer, stdioTransport } from './server/rpc'
+import { attach } from './server/serve'
+import { runAppsCli, runWikiCli } from './terminal/cli'
+import { runStandaloneTerminal, standaloneArguments } from './terminal/standalone'
+
+const USAGE = `Usage: xingular-harness [--data <dir>] [--state <dir>]
+       xingular-harness <terminal | serve | wiki | mcp | plugins> [arguments]
+
+  (no command)       Start the interactive Pi terminal
+  terminal           Start the interactive Pi terminal
+  serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]
+        [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
+                     Serve the harness over newline-delimited JSON
+  wiki <command>     Memory and Wiki commands for a terminal session
+  mcp <command>      Connected-app commands for a terminal session
+  plugins <command>  List, install, switch and trust plugins (plugins help)
+
+Standalone terminal options:
+  --data <dir>       Data directory (default: ~/.xingular-harness/data)
+  --state <dir>      State directory (default: ~/.xingular-harness/state)
+`
+
+function flags(argv: string[]): { values: Record<string, string[]>; switches: Set<string> } {
+  const values: Record<string, string[]> = {}
+  const switches = new Set<string>()
+  for (let index = 0; index < argv.length; index += 1) {
+    const name = argv[index]
+    if (!name.startsWith('--')) continue
+    const next = argv[index + 1]
+    if (next !== undefined && !next.startsWith('--')) {
+      ;(values[name.slice(2)] ??= []).push(next)
+      index += 1
+    } else switches.add(name.slice(2))
+  }
+  return { values, switches }
+}
+
+function serveCommand(argv: string[]): Promise<number> {
+  const { values, switches } = flags(argv)
+  const stateDir = values.state?.[0]
+  if (!stateDir) {
+    process.stderr.write('serve needs --state <dir>.\n')
+    return Promise.resolve(2)
+  }
+  const peer = new RpcPeer(stdioTransport())
+  const options: HarnessOptions = {
+    stateDir,
+    dataRoot: values.data?.[0] ?? null,
+    productName: values.name?.[0],
+    builtins: values.builtins,
+    ...(switches.has('host-secrets') ? { secrets: remoteSecrets(peer) } : {}),
+    ...(switches.has('host-policy') ? { policy: remotePolicy(peer) } : {}),
+    ...(switches.has('host-directory') ? { directory: remoteDirectory(peer) } : {})
+  }
+  const harness = createHarness(options)
+  if (switches.has('host-tools')) harness.sessions.provide(remoteTools(peer))
+  attach(harness, peer)
+  return new Promise<number>((resolve) => {
+    let closing = false
+    const shutdown = (): void => {
+      if (closing) return
+      closing = true
+      void Promise.race([harness.close(), new Promise((done) => setTimeout(done, 5000))]).then(() => resolve(0))
+    }
+    peer.handle('harness.shutdown', () => void setImmediate(shutdown))
+    process.stdin.on('end', shutdown)
+    process.on('SIGTERM', shutdown)
+    process.on('SIGINT', shutdown)
+    peer.send({ notice: { type: 'ready' } })
+    log('ready')
+  })
+}
+
+async function main(): Promise<number> {
+  const argv = process.argv.slice(2)
+  const [command, ...rest] = argv
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(USAGE)
+    return 0
+  }
+  const terminalArgs = standaloneArguments(argv)
+  if (terminalArgs !== null) return runStandaloneTerminal(terminalArgs)
+  if (command === 'serve') return serveCommand(rest)
+  if (command === 'wiki') return runWikiCli(rest)
+  if (command === 'mcp') return runAppsCli(rest)
+  if (command === 'plugins') return runPluginsCli(rest, { ask: terminalAsk() })
+  process.stdout.write(USAGE)
+  return command ? 2 : 0
+}
+
+void main().then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exit(1)
+  }
+)

package/src/core/bus.ts

@@ -0,0 +1,34 @@
+// Notices: what the harness tells whoever embeds it. Run events travel separately, through the
+// run tracker; a notice says that some state changed and should be read again.
+
+export interface Notice {
+  /** `accounts.changed`, `accounts.login`, `accounts.loginEvent`, `wiki.changed`, `wiki.maintenance`, … */
+  type: string
+  [key: string]: unknown
+}
+
+export type NoticeListener = (notice: Notice) => void
+
+export class Bus {
+  private readonly listeners = new Set<NoticeListener>()
+
+  on(listener: NoticeListener): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  emit(notice: Notice): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(notice)
+      } catch (error) {
+        log('a notice listener failed', error instanceof Error ? error.message : String(error))
+      }
+    }
+  }
+}
+
+/** Diagnostics go to stderr; stdout may be carrying a protocol. */
+export function log(...parts: unknown[]): void {
+  process.stderr.write(`[harness] ${parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')}\n`)
+}

package/src/core/changes.ts

@@ -0,0 +1,33 @@
+// A note that something in a Wiki was written: a fact, a memory block, or a page. The memory
+// code calls `noteChange` after the file is in place; whoever wants to react listens. Listeners
+// run inline and must only take the note down: a write never waits for, or fails with, a listener.
+export interface Change {
+  /** The Wiki folder the entry is in. */
+  wiki: string
+  id: string
+  /** The file that was written. */
+  path: string
+  /** Its new contents, front matter included. */
+  text: string
+  actor: string
+  reason: string
+}
+
+type Listener = (change: Change) => void
+
+const listeners = new Set<Listener>()
+
+export function noteChange(change: Change): void {
+  for (const listener of listeners) {
+    try {
+      listener(change)
+    } catch {
+      // A listener must never break the write it is told about.
+    }
+  }
+}
+
+export function onChange(listener: Listener): () => void {
+  listeners.add(listener)
+  return () => void listeners.delete(listener)
+}