From ddc6920cd131c45bb5c68fee11fbd4921c843b86 Mon Sep 17 00:00:00 2001 From: joe-broadhead <91376460+joe-broadhead@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:46:23 +0100 Subject: [PATCH 1/5] feat(sources): boxd.works The boxd.works source under the source contract (v0.2.0): events_list lists each phase change of this laptop's works from the ledger's events.jsonl through LedgerPort.eventsSince (no boxd call, no machine woken, no lock), in the plugin's own words, with the log's sequence number as the bound cursor and cursorExpired as gap: { reason: "expired" }; probe names this computer and its OS user. Both are tools RPC methods, allowed at every access value. The tools RPC is now the contract package's tools-rpc module, bundled into dist/index.js, in place of the copy. npm run conformance runs the kit and writes reports/conformance-report.json (ok). The bundles are minified (whitespace and syntax, not names) to stay within the 192 KiB pack budget. --- .gitignore | 1 + AGENTS.md | 22 +- CHANGELOG.md | 22 + README.md | 13 +- docs/architecture.md | 13 +- docs/configuration.md | 7 + docs/jelly.md | 4 + docs/scripting.md | 31 ++ docs/v1-design.md | 4 +- package-lock.json | 10 + package.json | 39 +- scripts/build.mjs | 6 +- scripts/check-copies.mjs | 17 +- scripts/check-forbidden.mjs | 7 +- scripts/check.mjs | 2 + scripts/conformance.ts | 25 + src/host/tools-rpc.ts | 822 --------------------------------- src/permissions.ts | 12 +- src/plugin.ts | 15 +- src/redact.ts | 2 +- src/sources.ts | 387 ++++++++++++++++ src/tools-rpc.ts | 69 +++ src/tools.ts | 2 +- test/fixtures/conformance.json | 26 ++ test/host/boxd.test.ts | 43 +- test/host/machines.test.ts | 2 +- test/host/sessions.test.ts | 2 +- test/pack/pack.test.ts | 11 +- test/support/conformance.ts | 147 ++++++ test/unit/docs.test.ts | 6 +- test/unit/permissions.test.ts | 9 +- test/unit/resolve.test.ts | 5 +- test/unit/sources.test.ts | 238 ++++++++++ test/unit/tools-rpc.test.ts | 15 +- 34 files changed, 1149 insertions(+), 887 deletions(-) create mode 100644 scripts/conformance.ts delete mode 100644 src/host/tools-rpc.ts create mode 100644 src/sources.ts create mode 100644 src/tools-rpc.ts create mode 100644 test/fixtures/conformance.json create mode 100644 test/support/conformance.ts create mode 100644 test/unit/sources.test.ts diff --git a/.gitignore b/.gitignore index 3305536..8685a0e 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ dist/ *.tsbuildinfo *.tgz .DS_Store +reports/ diff --git a/AGENTS.md b/AGENTS.md index 80c4433..716b8e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ and keeps the transcript on the laptop. It has no MCP server: its twelve tools a a temp folder. - **Ship prebuilt, one file per entry.** `scripts/build.mjs` bundles `src/index.ts` and `src/tui.ts` into the self-contained `dist/index.js` and `dist/tui.js`: no chunks, no relative imports, and only host-provided modules - external. `tsc` only typechecks. + external. Whitespace and syntax are minified and names are not. `tsc` only typechecks. - **Two folders per work.** The laptop folder is the project or an allowed root; the guest folder is always `/home/boxd/work/`. A laptop path is never sent to the guest. - **Files carry three facts.** A moved file is recorded by name, size and sha256, never content. A laptop path must be @@ -62,12 +62,18 @@ and keeps the transcript on the laptop. It has no MCP server: its twelve tools a family's shared fields `version`, `host`, `state`, `unguardedAgents` and `nextStep`. Status makes no boxd call beyond a machine read, cuts a failure's reason to one line of 160 characters with `src/redact.ts`, and names at most 20 unknown tools, plain names only. -- **The tools RPC (v2).** `src/host/tools-rpc.ts` is a copy of the v2 module shared by several plugins (shared-part - hash `57377eb3…`). Change only its block between the `PLUGIN-SPECIFIC` markers; change the rest in the shared copy - first, and `npm run check` fails on drift (`check-copies.mjs`). Its methods are every tool in `src/tools.ts`, by exact - name and with its class, and the rule is resolved before dispatch: only an `allow` runs. -- **Stages.** `npm run check` runs `typecheck`, `unit`, `build`, `icons`, `copies`, `host` (every SDK in - `TESTED_HOSTS`), `pack` (every `OPENCODE_BIN_*`), `forbidden`, `whitelist` and `actionlint`. +- **The tools RPC.** The transport is `@we-the-rebel-alliance/source-contract/tools-rpc`, pinned to a tag and bundled + into `dist/index.js`; boxd's plugin value is `src/tools-rpc.ts`. Its methods are every tool in `src/tools.ts`, by + exact name and with its class, then the `boxd.works` source's `events_list` and `probe`, and the rule is resolved + before dispatch: only an `allow` runs. +- **The source (`boxd.works`).** `src/sources.ts` implements the source contract's `events_list` and `probe` with the + package's `events` and `cursor` modules, never copies of them. It reads only the published ledger's `events.jsonl` + through `LedgerPort.eventsSince`: no boxd call, no machine woken, no lock, and no start or retry of the v0 import. An + event's words are the plugin's own (work id, phase, outcome, code), never a prompt, a transcript or guest text. + `npm run conformance` runs the package's conformance kit over it and writes `reports/conformance-report.json`, which a + release attaches; it must be `ok`. The descriptor declares no key that a consumer on an older contract refuses. +- **Stages.** `npm run check` runs `typecheck`, `unit`, `conformance`, `build`, `icons`, `copies`, `host` (every SDK + in `TESTED_HOSTS`), `pack` (every `OPENCODE_BIN_*`), `forbidden`, `whitelist` and `actionlint`. - **The `jelly` section** declares every tool, the skill, a one-line `summary` and the icon, with only the keys Jelly reads. `test/unit/jelly.test.ts` keeps it in step with the tool table and the default rules. - **The icon** is boxd's own mark, https://boxd.sh/favicon.svg with only `width` and `height` dropped, centred on a @@ -98,7 +104,7 @@ and keeps the transcript on the laptop. It has no MCP server: its twelve tools a `scripts/check-forbidden.mjs` enforces this list in `src/`, `test/`, `scripts/` and `dist/`: fork-only markers, tool `options.mcp` delegation, `Plugin.image`, imported OAuth grants, the V1 plugin API (`@opencode-ai/*` and hooks such as `tool.execute.before`), `ctx.generate.text`, `experimental.policies`, an import of `@opencode/ai`, a permission hook -except the one `permission.hook("evaluate")` the tools RPC module needs, private host source, machine-local home and temp +except the one `permission.hook("evaluate")` the bundled tools RPC module needs, private host source, machine-local home and temp paths, and `.tsx` or `.jsx` in `dist/`. The pack test also rejects anything in `dist/` other than the two bundles, and any relative import in them. diff --git a/CHANGELOG.md b/CHANGELOG.md index b9a3102..2c1c094 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,28 @@ All notable changes to this project are documented here. The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added + +- **The `boxd.works` source** under the source contract (`package.json`'s `sources`, contract version 1), for Memory's + collector and other scripts. `events_list` lists each phase change of this laptop's works as one event, oldest first, + read from the ledger's `events.jsonl` only: no boxd call, no machine woken, no lock taken. An event's title and labels + are the plugin's own words (the work id, the phase, how a run ended, its code, who put a machine to sleep), never a + prompt, a transcript or guest text, and a title that holds a secret is refused. The cursor is the log's sequence + number; one the log no longer keeps answers `gap: { reason: "expired" }`. `probe` names the account (this computer) + and its owner (`os-user:@`). Both are tools RPC methods, `boxd_events_list` and `boxd_probe`, which + every `access` value allows. While the v0 import runs, `events_list` answers `UNAVAILABLE`. +- **`npm run conformance`** runs the source contract's conformance kit over the source and writes + `reports/conformance-report.json`, which the release attaches. + +### Changed + +- The tools RPC is the source contract package's `tools-rpc` module (v0.2.0), bundled into `dist/index.js`, in place of + the copied module; boxd's methods, codes and next steps are unchanged. +- The bundles are minified (whitespace and syntax, not names), so the package stays within its size budget with the + contract's modules inside. + ## [0.1.0] - 2026-11-16 ### Breaking diff --git a/README.md b/README.md index 2499fbf..b235c24 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,14 @@ when the name now points at another machine. A work whose machine is gone in every region closes without destroying anything, and says what was not saved. +The plugin also declares one source, `boxd.works`, under the source contract (`package.json`'s `sources`), for +Memory's collector and other scripts, not for answering questions. `events_list` (`boxd_events_list`) lists each phase +change of this laptop's works as one event, oldest first, from the ledger's event log only: no boxd call, no machine +woken, no lock taken. Each event's title is the plugin's own sentence (the work id, its phase, how a run ended, its +code), never a prompt, a transcript or anything a guest wrote. `probe` (`boxd_probe`) names whose ledger it is: this +computer and its OS user. Both are tools RPC methods, not model tools, and every `access` value allows them. +[docs/scripting.md](docs/scripting.md#the-boxdworks-source) describes the calls. + ### What it costs boxd bills a running machine for its active CPU and its resident memory, a hibernated one for its disk only, and a @@ -166,6 +174,8 @@ directly after it: { "action": "boxd_status", "resource": "*", "effect": "allow" }, { "action": "boxd_job", "resource": "*", "effect": "allow" }, { "action": "boxd_read", "resource": "*", "effect": "allow" }, + { "action": "boxd_events_list", "resource": "*", "effect": "allow" }, + { "action": "boxd_probe", "resource": "*", "effect": "allow" }, { "action": "boxd_ensure", "resource": "*", "effect": "allow" }, { "action": "boxd_submit", "resource": "*", "effect": "allow" }, { "action": "boxd_harvest", "resource": "*", "effect": "allow" }, @@ -180,7 +190,8 @@ directly after it: That includes the changes: `boxd_ensure` creates a billing machine, `boxd_submit` starts a model run on it, `boxd_harvest` writes this laptop, `boxd_sleep`, `boxd_resume`, `boxd_reassign`, `boxd_golden` and `boxd_exec` change -or run on machines, and `boxd_drop` destroys one. `boxd_status`, `boxd_job` and `boxd_read` are the reads. +or run on machines, and `boxd_drop` destroys one. `boxd_status`, `boxd_job` and `boxd_read` are the reads, and so are +`boxd_events_list` and `boxd_probe`, the `boxd.works` source's methods. `boxd_cleanup` is `/boxd-cleanup`'s own action, not a tool: it asks at every level, so each cleanup action is your answer to a prompt. diff --git a/docs/architecture.md b/docs/architecture.md index 31b58a9..10f7f7d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -175,6 +175,13 @@ measure again. ## The tools RPC -`boxd.machines.tools` is the family's v2 module, copied verbatim outside its plugin block: a script calls each tool with -no model, as a session and its agent. The rules decide: only a resolved `allow` runs, an `ask` is refused because no one -can answer it, and every change still asserts inside its own run. +`boxd.machines.tools` is the source contract package's `tools-rpc` module, bundled into `dist/index.js`, with boxd's +plugin value in `src/tools-rpc.ts`: a script calls each tool with no model, as a session and its agent. The rules +decide: only a resolved `allow` runs, an `ask` is refused because no one can answer it, and every change still asserts +inside its own run. + +The same RPC carries the `boxd.works` source's `events_list` and `probe` (`src/sources.ts`), which are methods only, +not model tools. `events_list` reads `events.jsonl` through `LedgerPort.eventsSince`, the ledger's own sequence number +as its cursor and `cursorExpired` as the contract's `gap`. It reads only a published ledger: while the v0 import runs it +answers `UNAVAILABLE` rather than joining the import's gate, which could retry the import's machine listing. Reading the +log takes no lock, and nothing it does reaches boxd or a machine. diff --git a/docs/configuration.md b/docs/configuration.md index 2688906..2c51ee5 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -71,6 +71,7 @@ yours later in the agent, or in the session, still decides. The block is generated from `defaultRules(access)`, and it is printed here in full for each value, so it can be copied into an agent that gets no block of its own. `boxd_cleanup` is `/boxd-cleanup`'s own action: it asks at every level. +`boxd_events_list` and `boxd_probe` are the `boxd.works` source's two reads of the local ledger: every value allows them. `access: "all"` (the default): @@ -81,6 +82,8 @@ into an agent that gets no block of its own. `boxd_cleanup` is `/boxd-cleanup`'s { "action": "boxd_status", "resource": "*", "effect": "allow" }, { "action": "boxd_job", "resource": "*", "effect": "allow" }, { "action": "boxd_read", "resource": "*", "effect": "allow" }, + { "action": "boxd_events_list", "resource": "*", "effect": "allow" }, + { "action": "boxd_probe", "resource": "*", "effect": "allow" }, { "action": "boxd_ensure", "resource": "*", "effect": "allow" }, { "action": "boxd_submit", "resource": "*", "effect": "allow" }, { "action": "boxd_harvest", "resource": "*", "effect": "allow" }, @@ -102,6 +105,8 @@ into an agent that gets no block of its own. `boxd_cleanup` is `/boxd-cleanup`'s { "action": "boxd_status", "resource": "*", "effect": "allow" }, { "action": "boxd_job", "resource": "*", "effect": "allow" }, { "action": "boxd_read", "resource": "*", "effect": "allow" }, + { "action": "boxd_events_list", "resource": "*", "effect": "allow" }, + { "action": "boxd_probe", "resource": "*", "effect": "allow" }, { "action": "boxd_ensure", "resource": "*", "effect": "ask" }, { "action": "boxd_submit", "resource": "*", "effect": "ask" }, { "action": "boxd_harvest", "resource": "*", "effect": "ask" }, @@ -123,6 +128,8 @@ into an agent that gets no block of its own. `boxd_cleanup` is `/boxd-cleanup`'s { "action": "boxd_status", "resource": "*", "effect": "allow" }, { "action": "boxd_job", "resource": "*", "effect": "allow" }, { "action": "boxd_read", "resource": "*", "effect": "allow" }, + { "action": "boxd_events_list", "resource": "*", "effect": "allow" }, + { "action": "boxd_probe", "resource": "*", "effect": "allow" }, { "action": "boxd_ensure", "resource": "*", "effect": "deny" }, { "action": "boxd_submit", "resource": "*", "effect": "deny" }, { "action": "boxd_harvest", "resource": "*", "effect": "deny" }, diff --git a/docs/jelly.md b/docs/jelly.md index cc31f22..ffe36e7 100644 --- a/docs/jelly.md +++ b/docs/jelly.md @@ -27,6 +27,10 @@ what a Jelly may call. command's own action `boxd_cleanup`, which the default rules set to ask at every level; it is a command action, not a tool, so it is not in `tools`. +The `boxd.works` source is declared beside it, in `package.json`'s top-level `sources`, not in `jelly`: its +`events_list` and `probe` are tools RPC methods, not tools, so they are not in `tools`. They read only this laptop's +ledger, and the plugin's default rules allow them at every access value (`boxd_events_list`, `boxd_probe`). + Every tool the plugin registers is declared: the twelve tools are the plugin's own, and `test/unit/jelly.test.ts` fails when a tool in `src/tools.ts` is missing from `jelly.tools`, so a release cannot add an undeclared one. diff --git a/docs/scripting.md b/docs/scripting.md index 0ed8ce4..ee37285 100644 --- a/docs/scripting.md +++ b/docs/scripting.md @@ -77,9 +77,40 @@ opencode api post /api/rpc/boxd.machines.tools/boxd_sleep -H "x-opencode-directo | `boxd_golden` | write | the agent or session allows `boxd_golden` | | `boxd_exec` | write | the agent or session allows `boxd_exec` | | `boxd_drop` | destructive | the agent or session allows `boxd_drop` | +| `events_list` | read | allowed (its action is `boxd_events_list`) | +| `probe` | read | allowed (its action is `boxd_probe`) | A class is the worst thing the method does; it never decides whether a call runs. The rules do. +## The boxd.works source + +`events_list` and `probe` are the `boxd.works` source's methods (source contract, `package.json`'s `sources`), for a +collector such as Memory's. They read this laptop's ledger only: no boxd call, no machine woken, no lock taken. + +```sh +opencode api post /api/rpc/boxd.machines.tools/probe -H "x-opencode-directory:$PWD" -d '{"input":{"sessionID":"","input":{}}}' +opencode api post /api/rpc/boxd.machines.tools/events_list -H "x-opencode-directory:$PWD" \ + -d '{"input":{"sessionID":"","input":{"since":"2026-11-01T00:00:00Z","limit":100}}}' +``` + +- **The account and owner.** The account is this computer's host name, as a slug, and the owner its OS user, + `{ "id": "os-user:@", "label": " on " }`. A read that names another account is + `ACCOUNT_MISMATCH`. +- **An event** is one line of the ledger's `events.jsonl`: `external_id` `:`, `kind` `x-boxd/work`, + `occurred_at` the change's time, `thread` `boxd-work:`, a `title` in the plugin's own words, such as + `Work fix-auth: its run failed (RUN_FAILED)`, and `labels` `phase:`, `outcome:`, `code:`, + `asleep-by:` and `needs:
` where they apply. It has no `text`, `actors` or `url`. An event + whose title holds a secret (a work id shaped like a key) is listed in `refused[]` with reason `secret`, never sent. +- **The cursor** is the log's sequence number, bound to the plugin, the source and the account. The ledger keeps at + least the last 5 MiB of events: a cursor older than the oldest kept event, or one from another ledger, answers the + oldest kept events with `gap: { "reason": "expired", "since": }`, once, and a first + read whose `since` is older than the oldest kept event answers the same. Without a cursor or `since`, a read starts + 24 hours ago. +- **While the v0 import runs**, or after it failed, there is no ledger to read: `events_list` answers `UNAVAILABLE` with + the import's progress, and never starts the import itself. A ledger that cannot be read is `UNAVAILABLE` too. +- **Refusals** carry the source contract's codes: `INPUT_INVALID`, `SOURCE_UNKNOWN` (any source but `works`), + `ACCOUNT_MISMATCH`, `CURSOR_INVALID` and `UNAVAILABLE`, each as `CODE: what happened. Next step: …`. + ## Files in and out `boxd_submit` takes `files` to copy data to the machine, and `boxd_harvest` takes `files` to copy results back. A path is diff --git a/docs/v1-design.md b/docs/v1-design.md index effe193..ef4dfef 100644 --- a/docs/v1-design.md +++ b/docs/v1-design.md @@ -1725,8 +1725,8 @@ events and C2's runs, through their Day-0 interfaces), each filling its own stubs in the registry → integration on one branch → the live check (L1–L11 here if the owner provides a key, then L12–L13 by the owner) → the release-prep PR → `gh workflow run release.yml` → the owner approves. -Kit r4.1 files stay untouched (`scripts/check-copies.mjs`; `src/host/tools-rpc.ts` changes only between its -`PLUGIN-SPECIFIC` markers). The host range stays `>=2.2.3 <2.4.0`, tested on 2.2.3–2.2.7 and 2.3.0. No runtime +Kit r4.1 files stay untouched (`scripts/check-copies.mjs` pins them). The tools RPC is the source contract package's +module, bundled into `dist/index.js`, with boxd's plugin value in `src/tools-rpc.ts`. The host range stays `>=2.2.3 <2.4.0`, tested on 2.2.3–2.2.7 and 2.3.0. No runtime dependencies. ### 9.2 Options in v0.1.0 diff --git a/package-lock.json b/package-lock.json index da8a0d0..f23c6f9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16,6 +16,7 @@ "@opentui/solid": "0.8.0", "@types/bun": "1.4.4", "@types/node": "24.19.2", + "@we-the-rebel-alliance/source-contract": "github:we-the-rebel-alliance/source-contract#v0.2.0", "esbuild": "0.28.2", "solid-js": "1.9.17", "typescript": "5.9.3" @@ -3862,6 +3863,15 @@ "@types/node": "*" } }, + "node_modules/@we-the-rebel-alliance/source-contract": { + "version": "0.2.0", + "resolved": "git+ssh://git@github.com/we-the-rebel-alliance/source-contract.git#88bdc1e32af83098e06e6fb234ae267d91a4320e", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=22" + } + }, "node_modules/@yuuang/ffi-rs-android-arm64": { "version": "1.3.7", "resolved": "https://registry.npmjs.org/@yuuang/ffi-rs-android-arm64/-/ffi-rs-android-arm64-1.3.7.tgz", diff --git a/package.json b/package.json index 1b98007..09c2bef 100644 --- a/package.json +++ b/package.json @@ -185,6 +185,41 @@ ] } }, + "sources": { + "contractVersion": 1, + "rpc": "boxd.machines.tools", + "probe": { + "action": "boxd_probe" + }, + "items": [ + { + "id": "boxd.works", + "kind": "events", + "reads": "x-boxd/work", + "tool": "events_list", + "input": { + "source": "works" + }, + "accounts": { + "named": false + }, + "permission": { + "events": "boxd_events_list", + "rules": [ + { + "action": "boxd_events_list", + "resource": "*" + } + ] + }, + "private": true, + "cost": { + "class": "free" + }, + "maxBytes": 65536 + } + ] + }, "scripts": { "check": "node scripts/check.mjs", "typecheck": "node scripts/check.mjs typecheck", @@ -193,7 +228,8 @@ "test:host": "node scripts/check.mjs host", "test:pack": "node scripts/check.mjs pack", "lint": "node scripts/check.mjs forbidden", - "capture": "node scripts/capture-tools.mjs" + "capture": "node scripts/capture-tools.mjs", + "conformance": "bun scripts/conformance.ts" }, "devDependencies": { "@opencode/client": "2.2.3", @@ -203,6 +239,7 @@ "@opentui/solid": "0.8.0", "@types/bun": "1.4.4", "@types/node": "24.19.2", + "@we-the-rebel-alliance/source-contract": "github:we-the-rebel-alliance/source-contract#v0.2.0", "esbuild": "0.28.2", "solid-js": "1.9.17", "typescript": "5.9.3" diff --git a/scripts/build.mjs b/scripts/build.mjs index 9c7ac48..879eeee 100644 --- a/scripts/build.mjs +++ b/scripts/build.mjs @@ -2,7 +2,9 @@ // src/tui.ts to dist/tui.js (the terminal UI part). Shared code, such as the status model and the RPC contract, is // inlined into both. No chunks and no relative imports, because OpenCode reloads a plugin in place and reuses the // module records it already holds for unchanged paths: a new entry must never import an older sibling module. -// Only the modules the host provides stay external. The build fails if an output imports anything else. +// Only the modules the host provides stay external. The build fails if an output imports anything else. Whitespace and +// syntax are minified, names are not: the source contract's modules bundled into dist/index.js keep the package within +// its size budget, and a stack trace still names each function. import { build } from "esbuild" import { readdirSync, readFileSync, rmSync } from "node:fs" import { join } from "node:path" @@ -35,6 +37,8 @@ const result = await build({ target: "es2023", external: HOST, legalComments: "none", + minifyWhitespace: true, + minifySyntax: true, metafile: true, logLevel: "warning", plugins: [version], diff --git a/scripts/check-copies.mjs b/scripts/check-copies.mjs index 2c7d7f0..5aa5c6d 100644 --- a/scripts/check-copies.mjs +++ b/scripts/check-copies.mjs @@ -1,17 +1,13 @@ // Fails when a shared module's copy in this plugin differs from the one every plugin carries. // node scripts/check-copies.mjs check the copies this plugin has // node scripts/check-copies.mjs --print print each copy's hash, after a change made in every plugin at once -// Each plugin keeps its own copy, because each bundle and each test suite stands alone. The hashes below name the one -// version all plugins carry: the tools RPC outside its PLUGIN-SPECIFIC block, and the jelly kit and Jelly's setting -// rules whole. +// Each plugin keeps its own copy, because each test suite stands alone. The hashes below name the one version all +// plugins carry: the jelly kit and Jelly's setting rules whole, and the release kit whole. The tools RPC is not a copy +// here: it comes from the source contract package, pinned in package-lock.json and bundled into dist/index.js. import { createHash } from "node:crypto" import { existsSync, readFileSync } from "node:fs" -const BEGIN = "// >>> PLUGIN-SPECIFIC >>>" -const END = "// <<< PLUGIN-SPECIFIC <<<" - const COPIES = [ - { path: "src/host/tools-rpc.ts", optional: false, sha256: "15d82caa53aaae7ad9efb88dddb97056d3895c4dbf49b8efbb85b743871b2a6d", part: sharedPart }, // The declaration test kit every plugin's jelly test runs. { path: "test/support/jelly-kit.ts", optional: false, sha256: "de4bed563f37e39a596ba50908cac32f596a1d616b068daa327c2942e3f0aed5", part: (text) => text }, // Jelly's setting rules, restated without zod (the file's header says what it restates and how to update it). @@ -36,13 +32,6 @@ const COPIES = [ { path: "scripts/tested-hosts.mjs", optional: false, sha256: "370b2d6d7243cbc55ef435682bd75f113d0e18e5f7e063dd35407324362ce381", part: (text) => text }, ] -function sharedPart(text, path) { - const begin = text.indexOf(BEGIN) - const end = text.indexOf(END) - if (begin === -1 || end === -1 || end < begin) throw new Error(`${path}: the PLUGIN-SPECIFIC markers are missing or out of order`) - return text.slice(0, begin) + text.slice(end + END.length) -} - const print = process.argv.includes("--print") let failed = 0 for (const copy of COPIES) { diff --git a/scripts/check-forbidden.mjs b/scripts/check-forbidden.mjs index 88b3ada..c6839ab 100644 --- a/scripts/check-forbidden.mjs +++ b/scripts/check-forbidden.mjs @@ -10,8 +10,8 @@ const self = fileURLToPath(import.meta.url) const ROOTS = ["src", "test", "scripts", "dist"] const MEMBER = String.raw`\s*(?:\?\.|\.)\s*` const PERMISSION_HOOK = new RegExp(String.raw`\bpermission${MEMBER}hook\b`) -/** The copy of the module shared by several plugins, and the bundle that inlines it. */ -const TOOLS_RPC = ["src/host/tools-rpc.ts", "dist/index.js"] +/** The bundle that inlines the source contract's tools RPC module, the one place its evaluate hook may appear. */ +const TOOLS_RPC = ["dist/index.js"] /** The guest's own absolute paths, inside the machine: the only absolute paths this plugin may write down. */ const GUEST_PATH = /\/(?:home\/boxd|tmp\/opencode-boxd)(?:\/|(?=["'`\s)\],]))/g @@ -46,7 +46,8 @@ for (const top of ROOTS) { if (buffer.includes(0)) continue const lines = buffer.toString("utf8").split(/\r?\n/) if (TOOLS_RPC.includes(path)) { - const hooks = lines.filter((text) => PERMISSION_HOOK.test(text)).length + // Counted per match, not per line: the bundle is minified, so one line may hold more than one. + const hooks = lines.reduce((count, text) => count + (text.match(new RegExp(PERMISSION_HOOK.source, "g"))?.length ?? 0), 0) if (hooks !== 1) findings.push({ path, line: 0, id: "permission-hook", why: `the tools RPC must have exactly one permission hook, found ${hooks}` }) } for (const rule of RULES) { diff --git a/scripts/check.mjs b/scripts/check.mjs index 647bf79..64ba217 100644 --- a/scripts/check.mjs +++ b/scripts/check.mjs @@ -37,6 +37,8 @@ const LIFECYCLE_SCRIPTS = ["preinstall", "install", "postinstall", "preprepare", const stages = { typecheck: () => run("tsc", ["--noEmit", "-p", "tsconfig.json"]), unit: () => run("bun", ["test", "./test/unit"]), + // The source contract's conformance kit over the boxd.works source; writes reports/conformance-report.json. + conformance: () => run("bun", ["scripts/conformance.ts"]), kit: () => run("node", ["--test", "scripts/release-kit.test.mjs"]), build: () => run("node", ["scripts/build.mjs"]), icons: () => run("node", ["scripts/check-icons.mjs"]), diff --git a/scripts/conformance.ts b/scripts/conformance.ts new file mode 100644 index 0000000..d0f3a77 --- /dev/null +++ b/scripts/conformance.ts @@ -0,0 +1,25 @@ +// `npm run conformance`: source-contract's kit over the boxd.works source's own reads and the offline fixture +// (test/support/conformance.ts), with its report written to reports/conformance-report.json for the release to attach +// beside SHA256SUMS. Fails when the report is not ok. +import { mkdirSync, readFileSync, writeFileSync } from "node:fs" +import { join } from "node:path" +import { ROOT, conformanceReports } from "../test/support/conformance.js" + +const contract = JSON.parse(readFileSync(join(ROOT, "node_modules", "@we-the-rebel-alliance", "source-contract", "package.json"), "utf8")) as { version: string } +const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")) as { name: string; version: string } +const reports = await conformanceReports() +const ok = reports.every((report) => report.ok) +mkdirSync(join(ROOT, "reports"), { recursive: true }) +writeFileSync( + join(ROOT, "reports", "conformance-report.json"), + `${JSON.stringify({ plugin: pkg.name, version: pkg.version, contract: `source-contract ${contract.version}`, fixture: "test/fixtures/conformance.json", ok, reports }, null, 2)}\n`, +) +for (const report of reports) { + const ran = report.checks.filter((check) => check.ran).length + const skipped = report.checks.filter((check) => check.notApplicable).map((check) => check.name) + console.log(`${report.ok ? "ok" : "NOT OK"}: ${report.source}: ${ran} checks ran${skipped.length > 0 ? `; not applicable: ${skipped.join(", ")}` : ""}`) + for (const problem of report.problems) console.error(` - ${problem}`) + if (report.incomplete) console.error(` incomplete: ${report.checks.filter((check) => !check.ran && !check.notApplicable).map((check) => check.name).join(", ")}`) +} +console.log("wrote reports/conformance-report.json") +process.exit(ok ? 0 : 1) diff --git a/src/host/tools-rpc.ts b/src/host/tools-rpc.ts deleted file mode 100644 index 56fe754..0000000 --- a/src/host/tools-rpc.ts +++ /dev/null @@ -1,822 +0,0 @@ -/** - * The tools RPC, version 2: every known tool a plugin owns or exposes, as an RPC method, so a script can call it - * with no model. - * - * POST /api/rpc/.tools/ - * { "input": { "sessionID": "", "input": } } - * - * A script runs as a session and the agent it names. The rules that decide are the agent's, then the session's, with - * the host's own order (the last matching rule wins), which is also the order the model path uses: - * - the rule for the method's permission action is resolved BEFORE dispatch; only `allow` runs, so an `ask` is refused - * with no prompt and no tool call, and a `deny` is refused with no tool call; - * - an MCP method then runs through OpenCode's own executor from `ctx.tool.list()`, which checks `_` - * against the agent's rules, the session's rules and saved approvals, and sends OpenCode's own credential; - * - a plugin-owned method runs its own spec, with its own `ctx.permission.assert` calls; - * - the `evaluate` hook still refuses any inner `ask` of this RPC's own calls in flight (their source ids), so an - * inner action the method needs is named in the error, not left waiting; - * - a saved approval from an earlier "Always allow" is NOT part of `agent ++ session` rules, so it does not authorize - * an ad-hoc script. That is deliberate (v2, D-F): a script's grant is a rule in config, or a Jobs run session. - * - * Every known tool is a method, by exact name, with a class. A tool the server adds later is not a method until it is - * classified in the plugin's table; `describe` lists it as `unclassified`. - * - * The executor bypasses `execute.before` and `execute.after` hooks, so `shapeInput` runs before dispatch and - * `shapeResult` after it, whatever those hooks do on the model path. - * - * Shared module. Each plugin keeps its own copy, because each bundle is self-contained. Edit only the block between - * the PLUGIN-SPECIFIC markers. Everything else is identical in every plugin: the plugin's `check-copies.mjs` fails - * its check when it is not, so change it in every plugin at once. - */ -import { randomUUID } from "node:crypto" -import type { Plugin } from "@opencode/plugin" -import { Rpc } from "@opencode/plugin/rpc" - -// >>> PLUGIN-SPECIFIC >>> -import { PLUGIN_ID as BOXD_PLUGIN_ID } from "../constants.js" - -/** - * The plugin's id. The RPC id is `.tools`, and a script calls a method as `boxd.machines.tools/`. - */ -export const PLUGIN_ID = BOXD_PLUGIN_ID - -/** - * boxd has no MCP server, so no method comes from one. Every method is plugin-owned and built where it has the plugin's - * context (its own `permission.assert`), in `ownedMethods`: the three reads and the nine changes, each with its - * class. That table is the one list the tools, `describe`, status and the tests share; this export is the block's - * declaration that nothing is external. - */ -export const METHODS: readonly MethodSpec[] = [] - -/** The model path has no MCP call to reshape; an owned method's input is its own tool input. */ -export function shapeInput(_method: string, input: unknown, _call: ShapeCall): unknown { - return input -} - -/** Nothing on the model path reshapes a result either. */ -export function shapeResult(_method: string, result: McpResult, _call: ShapeCall): McpResult { - return result -} - -/** - * The next step for each code. boxd has no MCP methods, so the MCP-only steps are unused here; they stay because this - * block is also the fixture the shared module's own suite runs against, and a code's text must not drift. - */ -export const NEXT_STEPS: NextSteps = { - SESSION_UNKNOWN: `Create a session in the location you mean, such as POST /api/session with {"agent":"build"} sent with the header "x-opencode-directory: " or the location[directory] query, and pass its id.`, - SESSION_AGENT_REQUIRED: `Create a session that names an agent this project has, with its project as the location, such as POST /api/session with {"agent":"build","location":{"directory":"/path/to/project"}}, and pass its id.`, - PERMISSION_DENIED: - "A script cannot answer an approval prompt: add an allow rule for the method to the session's agent, then call it again.", - SERVER_CONFLICT: `Remove your own server from opencode.json so that the plugin manages it, then run "opencode reload".`, - AUTH_REQUIRED: "Run /connect and choose the plugin's account to connect it.", - CONNECTING: "Wait a few seconds, then call the method again.", - CONNECTION_FAILED: "Run /boxd-status and follow its next step.", - DISABLED: `Enable the plugin's server in /mcps, or remove "disabled": true from its entry in opencode.json.`, - NOT_REGISTERED: "Run /boxd-status and follow its next step.", - TOOL_UNAVAILABLE: "Call describe to see which methods OpenCode lists now, and run /boxd-status.", - UPSTREAM_ERROR: "Check the input against the method's schema from describe, and run /boxd-status if it keeps failing.", - CANCELLED: "Call the method again if you still need the result.", -} - -/** A boxd error, thrown by one of the plugin's own methods, as the script's code, what happened and the next step. */ -export function pluginError(error: unknown): Failure | undefined { - if (!(error instanceof Error)) return undefined - const { code, next } = error as { readonly code?: unknown; readonly next?: unknown } - if (typeof code !== "string" || typeof next !== "string") return undefined - // Strip the code and the next step from the message: the envelope carries them separately. - const message = error.message.startsWith(`${code}: `) ? error.message.slice(code.length + 2) : error.message - const what = message.split(" Next step: ")[0] ?? message - return { code, what: what.replace(/[.\s]+$/, ""), next } -} - -// <<< PLUGIN-SPECIFIC <<< - -export const TOOLS_RPC_ID = `${PLUGIN_ID}.tools` - -export type JsonSchema = Readonly> - -/** An MCP method's result: the tool's structured content, when it has any, and its text parts joined by newlines. */ -export interface McpResult { - readonly output?: unknown - readonly text: string -} - -/** What a method can do. It never decides whether a call runs; the rules do. */ -export type MethodClass = "read" | "write" | "send" | "export" | "destructive" - -export const CLASSES: readonly MethodClass[] = ["read", "write", "send", "export", "destructive"] - -/** The session, agent and action a shaper runs for. */ -export interface ShapeCall { - readonly sessionID: string - readonly agent: string - readonly action: string -} - -/** An MCP tool, classified. Its description and schemas come from the live tool. */ -export interface McpMethod { - readonly kind: "mcp" - readonly name: string - readonly class: MethodClass - /** `codemode: false` on the model path. Informational: every known tool is a method. */ - readonly directOnly?: boolean -} - -/** - * A plugin-owned tool, run through its own spec. Its asserts must pass - * `source: { type: "tool", messageID: call.messageID, id: call.id }`, as a tool does with its own context, so that - * the `evaluate` hook can tell this call's ask apart. - */ -export interface PluginMethod { - readonly kind: "plugin" - readonly class: MethodClass - readonly directOnly?: boolean - readonly name: string - /** The tool's permission action (its `options.permission`, or its id): the rule resolution uses it. */ - readonly action: string - readonly description: string - /** The input's JSON Schema, for the contract and describe. OpenCode does not check it: `run` checks its own input. */ - readonly input: JsonSchema - readonly output: JsonSchema - run(input: unknown, call: ToolCall): Promise - /** - * Whether the method can run now, for describe only: undefined when it can, otherwise the plugin's own code for why - * not, such as a module that is turned off or has no build for this platform. Without it, describe reports the method - * as available. A call never consults it: `run` reports the same state as its own error. - */ - available?(): string | undefined | Promise -} - -/** Every method: an MCP tool or a plugin-owned tool, each with a class. */ -export type MethodSpec = McpMethod | PluginMethod - -/** The v1 name for a plugin-owned method; kept so an adopting block reads the same. */ -export type OwnedMethod = PluginMethod - -/** Every code the module itself returns. ACCOUNT_UNKNOWN only with per-account servers. */ -type Code = - | "SESSION_UNKNOWN" - | "SESSION_AGENT_REQUIRED" - | "PERMISSION_DENIED" - | "SERVER_CONFLICT" - | "AUTH_REQUIRED" - | "CONNECTING" - | "CONNECTION_FAILED" - | "DISABLED" - | "NOT_REGISTERED" - | "TOOL_UNAVAILABLE" - | "UPSTREAM_ERROR" - | "CANCELLED" - | "ACCOUNT_UNKNOWN" - -/** The codes only an MCP method raises. A block without MCP methods may omit their next steps. */ -const MCP_ONLY = ["SERVER_CONFLICT", "AUTH_REQUIRED", "CONNECTING", "CONNECTION_FAILED", "DISABLED", "NOT_REGISTERED", "TOOL_UNAVAILABLE", "UPSTREAM_ERROR"] as const -type McpCode = (typeof MCP_ONLY)[number] - -/** - * One next step per code. The MCP-only steps are required, at registration, only for a block with MCP methods, and - * SERVER_CONFLICT not even then: the shared default names the server. ACCOUNT_UNKNOWN only with per-account servers. - */ -type NextSteps = Readonly, string>> & { readonly [code in McpCode | "ACCOUNT_UNKNOWN"]?: string } - -/** A refusal: the RPC error `failed` with this message and `data: { code, next }`. */ -interface Failure { - readonly code: string - /** What happened, without the code or a final full stop. */ - readonly what: string - readonly next: string -} - -/** The shapers a call uses. The block's `shapeInput` / `shapeResult` are the default. */ -export interface Shapers { - input?(method: string, input: unknown, call: ShapeCall): unknown - result?(method: string, result: McpResult, call: ShapeCall): McpResult -} - -export interface ToolsRpcOptions { - /** - * The plugin's declared table. Pass the block's `METHODS`: one list, so the default rules, describe, the methods and - * the skills cannot drift apart. It is an argument rather than a module-level read so that a test can exercise the - * shared part with its own table. - */ - readonly methods: readonly MethodSpec[] - /** - * Optional overrides for the block's shapers, for a plugin whose shapers are built at runtime. Omitted, the block's - * `shapeInput` and `shapeResult` are used. A test passes spies here to see the call order. - */ - readonly shapers?: Shapers - /** The MCP server whose methods are `_`. Required when the table has any `kind: "mcp"` entry. */ - readonly mcp?: { - /** - * The server name. A function makes `account` part of the envelope and maps it to that account's server, or to - * undefined for an account that does not exist. - */ - readonly server: string | ((account: string | undefined) => string | undefined) - /** False while the name belongs to a server the plugin does not manage, such as the user's own. */ - readonly managed: (server: string) => boolean - /** - * Optional. For a method that OpenCode does not list, `describe` adds the text this returns as `detail` - * beside the code in `reason`, such as the toolset and option that turn the method on. Called with the method - * name and that code; undefined adds nothing. Without it, describe is unchanged. - */ - readonly unavailableDetail?: (method: string, code: Code) => string | undefined - /** - * Optional. The code and next step used instead of NOT_REGISTERED while the server is not registered, such as a - * missing client ID that keeps the plugin from registering it; undefined keeps NOT_REGISTERED. Read at each call - * and each describe. Without it, NOT_REGISTERED stays. - */ - readonly notRegistered?: (server: string) => { readonly code: string; readonly next: string } | undefined - } -} - -export type ToolsRpcContext = Pick - -/** The executor context a script's call runs with. */ -export interface ToolCall { - readonly sessionID: string - readonly agent: string - readonly messageID: string - readonly id: string - readonly signal: AbortSignal - readonly progress: () => Promise - /** - * A plugin-owned method's call only, with per-account servers: the envelope's `account`, already known to the - * `mcp.server` function. Absent when the envelope has none (the default account). - */ - readonly account?: string -} - -type Rule = { readonly action: string; readonly resource: string; readonly effect: "allow" | "deny" | "ask" } -type Envelope = { readonly sessionID: string; readonly account?: string; readonly input: unknown } -type RpcContext = { readonly signal: AbortSignal; readonly error: (type: "failed", message: string, data: { code: string; next: string }) => unknown } -type Tool = Awaited>[number] -type ToolResult = Awaited> - -const UNATTENDED = "A script cannot answer an approval prompt; this needs an allow rule for the session's agent." -const MESSAGE_ID = "msg_script" -const UPSTREAM_LIMIT = 300 - -/** The header and query an external caller uses to name the location whose plugins and sessions it means. */ -export const LOCATION_HEADER = "x-opencode-directory" -export const LOCATION_HINT = `Send the call to the location you mean: run it in that project with "opencode api ... -H \\"${LOCATION_HEADER}:$PWD\\"", or pass the location[directory] query parameter to the HTTP request.` - -const object = (properties: Record, required: readonly string[]): JsonSchema => ({ - type: "object", - properties, - required, - additionalProperties: false, -}) -const STRING = { type: "string" } as const -const ANY_OBJECT = { type: "object" } as const -const FAILED = object({ code: STRING, next: STRING }, ["code", "next"]) -const mcpOutput = (output: JsonSchema = {}) => object({ output, text: STRING }, ["text"]) -const DESCRIBED = object( - { - name: STRING, - tool: STRING, - kind: { type: "string", enum: ["mcp", "plugin"] }, - class: { type: "string", enum: [...CLASSES] }, - action: STRING, - description: STRING, - available: { type: "boolean" }, - reason: STRING, - detail: STRING, - permission: { type: "string", enum: ["allow", "ask", "deny"] }, - input: ANY_OBJECT, - output: ANY_OBJECT, - }, - ["name", "tool", "kind", "class", "action", "description", "available", "input", "output"], -) -const DESCRIPTION = object( - { - id: STRING, - call: STRING, - location: STRING, - locationHint: STRING, - methods: { type: "array", items: DESCRIBED }, - unclassified: { type: "array", items: STRING }, - }, - ["id", "call", "location", "locationHint", "methods"], -) - -const plainObject = (value: unknown): value is Record => typeof value === "object" && value !== null && !Array.isArray(value) - -/** The envelope's messages, one wording for every plugin (README, "Envelope errors"). */ -const ENVELOPE_MESSAGES = { - notObject: `the envelope must be an object, such as {"sessionID":"","input":}`, - unknownKey: (key: string) => `"${key}" is not allowed`, - sessionID: `"sessionID" must be a non-empty string`, - account: `"account" must be a non-empty string`, - inputMissing: `"input" is missing`, - inputNotObject: `"input" must be an object`, - describe: `describe takes nothing, or {"sessionID":""}`, -} as const - -const standard = (schema: JsonSchema, validate: (value: unknown) => unknown): JsonSchema => - Object.defineProperty({ ...schema }, "~standard", { value: { version: 1, vendor: "tools-rpc", validate }, enumerable: false }) - -/** describe's input: nothing, or an object with one optional sessionID. */ -const DESCRIBE_INPUT = standard( - object({ sessionID: { type: "string", minLength: 1 } }, []), - (value) => { - if (value === undefined || value === null) return { value: {} } - if (!plainObject(value)) return { issues: [{ message: ENVELOPE_MESSAGES.describe }] } - const issues = [ - ...Object.keys(value).filter((key) => key !== "sessionID").map(ENVELOPE_MESSAGES.unknownKey), - ...(value["sessionID"] === undefined || (typeof value["sessionID"] === "string" && value["sessionID"] !== "") ? [] : [ENVELOPE_MESSAGES.sessionID]), - ] - return issues.length === 0 ? { value } : { issues: issues.map((message) => ({ message })) } - }, -) - -/** - * A JSON Schema object with a strict validator attached. OpenCode decodes a plain JSON Schema with Effect, which drops - * unknown keys of an object that has properties instead of refusing them; it prefers a Standard Schema validator when - * the schema has one. The validator refuses unknown keys and checks `issues`; it is not enumerable, so the contract - * still reads and serialises as plain JSON Schema. OpenCode answers a refusal with `rpc.invalid_input`. - */ -function strict(schema: JsonSchema, issues: (value: Record) => string[]): JsonSchema { - const keys = Object.keys(schema["properties"] as object) - return standard(schema, (value) => { - if (!plainObject(value)) return { issues: [{ message: ENVELOPE_MESSAGES.notObject }] } - const found = [...Object.keys(value).filter((key) => !keys.includes(key)).map(ENVELOPE_MESSAGES.unknownKey), ...issues(value)] - return found.length === 0 ? { value } : { issues: found.map((message) => ({ message })) } - }) -} - -class ScriptError extends Error { - readonly failure: Failure - constructor(failure: Failure) { - // `what` may end with its own full stop (a refused ask's reason, an upstream first line); keep exactly one. - super(`${failure.code}: ${failure.what.replace(/[.\s]+$/, "")}. Next step: ${failure.next}`) - this.failure = failure - } -} - -const fail = (code: Exclude, what: string) => { - const next = NEXT_STEPS[code] - // registerToolsRpc checks the MCP-only steps for a block with MCP methods, so this is a bug in the module. - if (next === undefined) throw new Error(`tools-rpc: NEXT_STEPS.${code} is missing`) - return new ScriptError({ code, what, next }) -} - -/** SERVER_CONFLICT's next step: the block's own, or the shared default that names the server. */ -const conflictNext = (server: string) => - NEXT_STEPS.SERVER_CONFLICT ?? `Remove your own "${server}" server from opencode.json so that the plugin manages it, then run "opencode reload".` - -const record = (value: unknown): value is Record => typeof value === "object" && value !== null - -/** True when OpenCode says the thing looked up does not exist: its tagged not-found error, or an HTTP 404. */ -function notFound(error: unknown, tags: readonly string[]): boolean { - if (!record(error)) return false - const tag = error["_tag"] ?? error["name"] - return (typeof tag === "string" && tags.includes(tag)) || error["status"] === 404 || error["statusCode"] === 404 -} - -/** OpenCode's `Tool.Error`. A permission refusal carries its cause in `error`; an upstream failure has none. */ -const toolError = (error: unknown): error is { message: string; error?: unknown } => record(error) && error["_tag"] === "Tool.Error" - -/** The action of the permission request a refusal's cause carries (OpenCode's `Permission.Request`), if any. */ -const requestAction = (cause: unknown): string | undefined => { - const request = record(cause) ? cause["request"] : undefined - return record(request) && typeof request["action"] === "string" && request["action"] !== "" ? request["action"] : undefined -} - -/** - * The action in OpenCode's fixed text for a rule deny, `Permission denied: `. A rule deny never reaches - * `evaluate` hooks and its cause carries no request, so this text is how the refusal can name the action. - */ -const deniedAction = (message: string): string | undefined => /^Permission denied: ([\w.:-]*[\w-])\.?\s*$/.exec(message.split(/\r?\n/, 1)[0] ?? "")?.[1] - -/** Host wildcards: `*` matches any run of characters and `?` one character, over the whole string. */ -const wildcard = (pattern: string, value: string) => - new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`).test(value) - -/** - * The host's evaluation for one action on resource `*`: the last matching rule wins, and no match asks. This is the - * whole of the resolve-before-dispatch rule; `hidden` is the same predicate, under its model-path name. - */ -export const evaluate = (rules: readonly Rule[], action: string): Rule["effect"] => - rules.findLast((rule) => wildcard(rule.action, action) && wildcard(rule.resource, "*"))?.effect ?? "ask" - -/** OpenCode hides a tool from the model when the last rule matching its action on `*` is a deny. */ -export const hidden = (rules: readonly Rule[], action: string) => evaluate(rules, action) === "deny" - -/** Token shapes, replaced in order. URLs are handled first, by `withoutQuery`. */ -const SECRETS: readonly [RegExp, string][] = [ - [/\b(bearer|basic|token)\s+[\w.~+/=-]{8,}/gi, "$1 [redacted]"], - [/\b([\w-]*(?:api[_-]?key|access[_-]?key|private[_-]?key|token|secret|password|signature|credential)["']?\s*[:=]\s*)["']?[^\s"'&,;]+["']?/gi, "$1[redacted]"], - [/\beyJ[\w-]{4,}\.[\w-]{4,}\.[\w-]{4,}/g, "[redacted]"], - [/\b(?:tvly|sk|pk|rk|ghp|gho|ghu|ghs|ghr|github_pat|glpat|xox[abposr]|lin_api|lin_oauth)[-_][\w-]{8,}/gi, "[redacted]"], - [/[\w+=-]{40,}/g, "[redacted]"], -] - -/** A URL keeps its origin and path; its query and fragment, where signatures and tokens travel, go. */ -const withoutQuery = (text: string) => - text.replace(/\bhttps?:\/\/[^\s"'<>()]+/gi, (url) => { - const cut = url.search(/[?#]/) - return cut === -1 ? url : `${url.slice(0, cut)}?[redacted]` - }) - -/** Upstream text for an error message: its first line, with tokens and signed URLs redacted, at most 300 characters. */ -export function upstreamText(text: string): string { - const line = text.split(/\r?\n/).find((part) => part.trim() !== "")?.trim() ?? "no message" - const redacted = SECRETS.reduce((value, [pattern, replacement]) => value.replace(pattern, replacement), withoutQuery(line)) - return redacted.length <= UPSTREAM_LIMIT ? redacted : `${redacted.slice(0, UPSTREAM_LIMIT - 1)}…` -} - -/** A tool's schema when it is plain JSON Schema, as an MCP tool's is; an Effect or Standard Schema is not. */ -const jsonSchema = (schema: unknown): JsonSchema | undefined => - record(schema) && !("ast" in schema) && !("~standard" in schema) ? schema : undefined - -function normalise(result: ToolResult): McpResult { - const text = typeof result.content === "string" ? result.content : (result.content ?? []).flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n") - return result.output === undefined ? { text } : { output: result.output, text } -} - -/** The code for a server that is not connected, from OpenCode's MCP status; undefined when it is connected. */ -function connection(status: string | undefined): Exclude | undefined { - switch (status) { - case "connected": - return undefined - case "pending": - return "CONNECTING" - case "needs_auth": - return "AUTH_REQUIRED" - case "failed": - return "CONNECTION_FAILED" - case "disabled": - return "DISABLED" - default: - return "NOT_REGISTERED" - } -} - -const STATUS_TEXT: Record = { - CONNECTING: "is still connecting", - AUTH_REQUIRED: "needs a sign-in", - CONNECTION_FAILED: "could not connect", - DISABLED: "is disabled", - NOT_REGISTERED: "is not registered", -} - -export async function registerToolsRpc(ctx: ToolsRpcContext, options: ToolsRpcOptions): Promise<() => Promise> { - const { mcp, methods } = options - const shapeIn = options.shapers?.input ?? shapeInput - const shapeOut = options.shapers?.result ?? shapeResult - const accounts = typeof mcp?.server === "function" - const anyMcp = methods.some((method) => method.kind === "mcp") - if (anyMcp && !mcp) throw new Error("registerToolsRpc: an MCP method needs the mcp option") - if (accounts && NEXT_STEPS.ACCOUNT_UNKNOWN === undefined) throw new Error("registerToolsRpc: per-account servers need NEXT_STEPS.ACCOUNT_UNKNOWN") - const missing = anyMcp ? MCP_ONLY.find((code) => code !== "SERVER_CONFLICT" && NEXT_STEPS[code] === undefined) : undefined - if (missing) throw new Error(`registerToolsRpc: MCP methods need NEXT_STEPS.${missing}`) - const names = methods.map((method) => method.name) - const duplicate = names.find((name, index) => name === "describe" || names.indexOf(name) !== index) - if (duplicate) throw new Error(`registerToolsRpc: the method name "${duplicate}" is taken`) - for (const method of methods) { - if (!CLASSES.includes(method.class)) throw new Error(`registerToolsRpc: ${method.name} has the class "${String(method.class)}"; use one of ${CLASSES.join(", ")}`) - if (method.kind === "plugin" && (typeof method.run !== "function" || method.action === "")) throw new Error(`registerToolsRpc: the plugin method ${method.name} needs a run function and an action`) - } - - // This RPC's calls in flight, by the source id their permission checks carry. - const live = new Set() - // Each live call's last refused check the hook saw, by source id: its action, which may not be the method's, and its - // effect. A rule deny never reaches the hook, so only asks (and other hooks' denies) are recorded here. - const refused = new Map() - - const serverOf = (account: string | undefined): string => { - const server = typeof mcp!.server === "function" ? mcp!.server(account) : mcp!.server - if (server !== undefined) return server - throw new ScriptError({ code: "ACCOUNT_UNKNOWN", what: `there is no account '${account}'`, next: NEXT_STEPS.ACCOUNT_UNKNOWN! }) - } - - /** The action a method resolves and asserts. For an MCP tool, the host's `_`. */ - const actionOf = (method: MethodSpec, envelope: Envelope): string => - method.kind === "plugin" ? method.action : `${serverOf(envelope.account)}_${method.name}` - - /** The session's agent and the rules that decide what its model sees: the agent's, then the session's. */ - const session = async (sessionID: string) => { - let info: Awaited> - try { - info = await ctx.session.get({ sessionID: sessionID as never }) - } catch (error) { - // Only OpenCode's "no such session" is SESSION_UNKNOWN; any other failure propagates as it is. - if (notFound(error, ["Session.NotFoundError", "SessionNotFoundError"])) throw fail("SESSION_UNKNOWN", `there is no session '${sessionID}' in this location`) - throw error - } - if (!info.agent) throw fail("SESSION_AGENT_REQUIRED", `session '${sessionID}' names no agent`) - let agent: Awaited> - try { - // No location argument: the session was read in this plugin's own location, and the agent is looked up there. - // Passing `info.location` back (a Location.Ref, which can carry a workspace) made a project-level plugin fail - // with "Agent not found" on 2.2.3/2.2.4, so the location is left to the context, which is per location. - agent = await ctx.agent.get({ agentID: info.agent }) - } catch (error) { - // A host may report a missing agent as a plain Error whose message names it (stock 2.2.3 to 2.2.6), not as a tagged - // NotFoundError. Both are the same refusal: the session names an agent this location does not have. - const missing = notFound(error, ["Agent.NotFoundError", "AgentNotFoundError"]) || (error instanceof Error && error.message.startsWith("Agent not found")) - if (missing) throw fail("SESSION_AGENT_REQUIRED", `session '${sessionID}' names the agent '${info.agent}', which does not exist in this location`) - throw error - } - const rules: Rule[] = [...agent.data.permissions, ...(info.permissions ?? [])] - return { agent: info.agent as string, rules } - } - - /** The plugin's own code and next step for a server that is not registered, if its `notRegistered` hook gives one. */ - const notRegistered = (server: string) => mcp?.notRegistered?.(server) - - /** Why the server's tool is missing: its connection state, or TOOL_UNAVAILABLE while it is connected. */ - const unavailable = async (server: string, tool: string, connected: Exclude) => { - const status = (await ctx.mcp.list()).data.find((entry) => entry.name === server)?.status.status - const code = connection(status) ?? connected - if (code === "TOOL_UNAVAILABLE") return fail(code, `OpenCode does not list ${tool} on the connected "${server}" server`) - // The call found the server not connected, and it reads connected now: it reconnected meanwhile. - if (status === "connected") return fail(code, `the "${server}" server was reconnecting when ${tool} ran`) - const what = `the "${server}" server ${STATUS_TEXT[code] ?? "is unavailable"}` - const own = code === "NOT_REGISTERED" ? notRegistered(server) : undefined - return own ? new ScriptError({ code: own.code, what, next: own.next }) : fail(code, what) - } - - /** The next step for a deny rule: no prompt can be answered, so the rule itself must change. */ - const denyNext = (action: string, agent: string) => - `Remove or narrow the deny rule for ${action} in the agent "${agent}" or in the session, or add a later allow rule for ${action} to the session, or use a session whose agent allows it.` - - /** - * A refused ask (the hook turned it into a deny). `asked` is the action whose check was refused, when that is known - * and is not the method's own, such as a speech download that a transcription asks for: the message and the next - * step name it. - */ - const denied = (action: string, error: unknown, asked = action) => { - const reason = upstreamText(record(error) && typeof error["message"] === "string" ? error["message"] : String(error)) - if (asked === action) return fail("PERMISSION_DENIED", `${action} was refused for this session's agent: ${reason}`) - return new ScriptError({ - code: "PERMISSION_DENIED", - what: `${action} needs ${asked}, which was refused for this session's agent: ${reason}`, - next: `Add an allow rule for ${asked} to the session's agent or to the session, or use a session whose agent allows it.`, - }) - } - - /** - * A check a deny rule refused, the method's own or an inner one such as the read Plaud's recent makes. A rule deny - * never reaches the hook, so its action comes from OpenCode's own text. - */ - const ruleDenied = (action: string, error: unknown, agent: string, inner = action) => { - const reason = upstreamText(record(error) && typeof error["message"] === "string" ? error["message"] : String(error)) - const what = inner === action ? `${action} was refused by a deny rule for this session's agent: ${reason}` : `${action} needs ${inner}, which a deny rule refuses for this session's agent: ${reason}` - return new ScriptError({ code: "PERMISSION_DENIED", what, next: denyNext(inner, agent) }) - } - - /** - * The resolve before dispatch: only `allow` runs. An `ask` is refused because no one can answer it, and a `deny` - * because a rule refuses it. Both refuse with no tool call and no prompt. - */ - const resolve = (rules: readonly Rule[], action: string, agent: string) => { - const effect = evaluate(rules, action) - if (effect === "allow") return - if (effect === "ask") - throw new ScriptError({ - code: "PERMISSION_DENIED", - what: `${action} would ask for this session's agent, and a script cannot answer`, - next: `Add an allow rule for ${action} to the session's agent or to the session, or use a session whose agent allows it.`, - }) - if (hidden(rules, action)) throw new ScriptError({ code: "PERMISSION_DENIED", what: `${action} is hidden from this session's agent by a deny rule`, next: denyNext(action, agent) }) - throw new ScriptError({ code: "PERMISSION_DENIED", what: `${action} is denied for this session's agent`, next: denyNext(action, agent) }) - } - - /** A method's call: how it runs as the session, and the call it runs with. */ - interface Target { - readonly action: string - readonly method: MethodSpec - run(call: ToolCall): Promise - } - - const mcpTarget = (method: McpMethod, envelope: Envelope, action: string, server: string): Target => ({ - action, - method, - async run(call) { - if (!mcp!.managed(server)) { - throw new ScriptError({ code: "SERVER_CONFLICT", what: `the "${server}" server in your config is not the one this plugin manages`, next: conflictNext(server) }) - } - const tool = (await ctx.tool.list()).find((entry) => entry.id === action) - if (!tool) throw await unavailable(server, action, "TOOL_UNAVAILABLE") - const shaped = shapeIn(method.name, envelope.input, { sessionID: call.sessionID, agent: call.agent, action }) - let result: ToolResult - try { - // OpenCode asserts `action` on `*` inside the executor, for the call's session and agent. - result = await tool.execute(shaped as never, call as never) - } catch (error) { - // OpenCode's fixed message for a call to a server that is not connected. - if (error instanceof Error && error.message.startsWith(`MCP server "${server}" `)) throw await unavailable(server, action, "CONNECTING") - throw error - } - const shapedResult = shapeOut(method.name, normalise(result), { sessionID: call.sessionID, agent: call.agent, action }) - return shapedResult - }, - }) - - const pluginTarget = (method: PluginMethod, envelope: Envelope, action: string): Target => { - // With per-account servers, an unknown account is ACCOUNT_UNKNOWN before the spec runs, as for an MCP method. - if (accounts) serverOf(envelope.account) - const account = accounts && envelope.account !== undefined ? { account: envelope.account } : {} - return { - action, - method, - run: async (call) => (await method.run(envelope.input, { ...call, ...account })) ?? null, - } - } - - const targetOf = (method: MethodSpec, envelope: Envelope): Target => { - const action = actionOf(method, envelope) - if (method.kind === "plugin") return pluginTarget(method, envelope, action) - return mcpTarget(method, envelope, action, serverOf(envelope.account)) - } - - const invoke = async (method: MethodSpec, raw: unknown, context: RpcContext) => { - const envelope = raw as Envelope - let target: Target | undefined - let id: string | undefined - let agent: string | undefined - try { - if (context.signal.aborted) throw fail("CANCELLED", "the call was cancelled") - target = targetOf(method, envelope) - const resolved = await session(envelope.sessionID) - agent = resolved.agent - resolve(resolved.rules, target.action, agent) - id = `script:${randomUUID()}` - const call: ToolCall = { - sessionID: envelope.sessionID, - agent, - messageID: MESSAGE_ID, - id, - signal: context.signal, - progress: async () => {}, - } - live.add(call.id) - try { - // RPC output must be a JSON value. - return JSON.parse(JSON.stringify(await target.run(call))) - } finally { - live.delete(call.id) - } - } catch (error) { - const failure = refusal(error, target, context.signal, agent, id === undefined ? undefined : refused.get(id)) - if (!failure) throw error - return context.error("failed", new ScriptError(failure).message, { code: failure.code, next: failure.next }) - } finally { - if (id !== undefined) refused.delete(id) - } - } - - /** The failure a script reads, or undefined for a host error that propagates unchanged. */ - const refusal = ( - error: unknown, - target: Target | undefined, - signal: AbortSignal, - agent: string | undefined, - seen?: { readonly action: string; readonly effect: "ask" | "deny" }, - ): Failure | undefined => { - if (signal.aborted) return fail("CANCELLED", "the call was cancelled").failure - if (error instanceof ScriptError) return error.failure - const own = pluginError(error) - if (own || !target || !toolError(error)) return own - // A deny, or an ask the hook refused, carries its cause; an upstream failure (MCP `isError`) has none. - if (error.error !== undefined) { - const request = requestAction(error.error) - // An ask: the hook refused it, or the cause carries its request (only an ask has one). - if (seen?.effect === "ask" || request !== undefined || agent === undefined) return denied(target.action, error, request ?? seen?.action).failure - // A deny: a rule deny reaches no hook and carries no request, so OpenCode's own text names its action. - return ruleDenied(target.action, error, agent, seen?.action ?? deniedAction(error.message) ?? target.action).failure - } - if (target.method.kind === "mcp") return fail("UPSTREAM_ERROR", `${target.action} failed: ${upstreamText(error.message)}`).failure - return undefined - } - - /** - * The live tools this table does not classify, by their upstream name. Never methods. A plugin-owned tool can also be - * registered under the server's namespace, so a tool whose declared permission is one of this plugin's own actions - * is not an unclassified MCP tool. - */ - const unclassified = async (tools: readonly Tool[]) => { - const server = serverOf(undefined) - const prefix = `${server}_` - const known = new Set(methods.filter((method) => method.kind === "mcp").map((method) => method.name)) - // A plugin-owned tool may be registered under the server's namespace; its short id is the plugin method's name. - const owned = new Set(methods.filter((method) => method.kind === "plugin").flatMap((method) => [method.name, method.action])) - return tools - .filter((tool) => tool.id.startsWith(prefix) && !known.has(tool.id.slice(prefix.length)) && !owned.has(tool.id.slice(prefix.length))) - .map((tool) => tool.id.slice(prefix.length)) - .sort() - } - - const describe = async (raw: unknown) => { - const input = (raw ?? {}) as { readonly sessionID?: string } - const resolved = input.sessionID === undefined ? undefined : await session(input.sessionID) - const tools = mcp ? await ctx.tool.list() : [] - // One server lookup and one mcp.list() for the whole describe, whatever the number of MCP methods. - const server = anyMcp ? serverOf(undefined) : "" - const managed = mcp !== undefined && server !== "" ? mcp.managed(server) : false - const status = managed ? (await ctx.mcp.list()).data.find((entry) => entry.name === server)?.status.status : undefined - const methodsOut: Record[] = [] - for (const method of methods) { - if (method.kind === "mcp") { - const id = `${server}_${method.name}` - const tool = managed ? tools.find((entry) => entry.id === id) : undefined - const code: Code | undefined = !managed ? "SERVER_CONFLICT" : tool ? undefined : (connection(status) ?? "TOOL_UNAVAILABLE") - const reason = code === "NOT_REGISTERED" ? (notRegistered(server)?.code ?? code) : code - const detail = code === undefined ? undefined : mcp!.unavailableDetail?.(method.name, code) - methodsOut.push({ - name: method.name, - tool: id, - kind: "mcp", - class: method.class, - action: id, - description: tool?.description ?? "", - available: reason === undefined, - ...(reason ? { reason } : {}), - ...(detail === undefined ? {} : { detail }), - ...(resolved ? { permission: evaluate(resolved.rules, id) } : {}), - input: jsonSchema(tool?.input) ?? ANY_OBJECT, - output: mcpOutput(jsonSchema(tool?.output)), - }) - continue - } - const reason = await method.available?.() - methodsOut.push({ - name: method.name, - tool: method.name, - kind: "plugin", - class: method.class, - action: method.action, - description: method.description, - available: reason === undefined, - ...(reason === undefined ? {} : { reason }), - ...(resolved ? { permission: evaluate(resolved.rules, method.action) } : {}), - input: method.input, - output: method.output, - }) - } - const loose = mcp && mcp.managed(serverOf(undefined)) ? await unclassified(tools) : [] - return JSON.parse( - JSON.stringify({ - id: TOOLS_RPC_ID, - call: `POST /api/rpc/${TOOLS_RPC_ID}/ with {"input":{"sessionID":"",${accounts ? `"account":"",` : ""}"input":}}`, - location: ctx.location.directory, - locationHint: LOCATION_HINT, - methods: methodsOut, - ...(loose.length > 0 ? { unclassified: loose } : {}), - }), - ) - } - - const envelope = (input: JsonSchema, objectInput: boolean) => - strict( - object({ sessionID: { type: "string", minLength: 1 }, ...(accounts ? { account: { type: "string", minLength: 1 } } : {}), input }, ["sessionID", "input"]), - (value) => [ - ...(typeof value["sessionID"] === "string" && value["sessionID"] !== "" ? [] : [ENVELOPE_MESSAGES.sessionID]), - ...(value["account"] === undefined || (typeof value["account"] === "string" && value["account"] !== "") ? [] : [ENVELOPE_MESSAGES.account]), - ...(!("input" in value) ? [ENVELOPE_MESSAGES.inputMissing] : objectInput && !plainObject(value["input"]) ? [ENVELOPE_MESSAGES.inputNotObject] : []), - ], - ) - const contract = Rpc.define({ - id: TOOLS_RPC_ID, - methods: { - describe: { input: DESCRIBE_INPUT, output: DESCRIPTION, errors: { failed: FAILED } }, - ...Object.fromEntries( - methods.map((method) => [ - method.name, - method.kind === "mcp" - ? { input: envelope(ANY_OBJECT, true), output: mcpOutput(), errors: { failed: FAILED } } - : { input: envelope(method.input, false), output: method.output, errors: { failed: FAILED } }, - ]), - ), - }, - events: {}, - } as never) - const handlers = { - describe: async (raw: unknown, context: RpcContext) => { - try { - return await describe(raw) - } catch (error) { - if (!(error instanceof ScriptError)) throw error - return context.error("failed", error.message, { code: error.failure.code, next: error.failure.next }) - } - }, - ...Object.fromEntries(methods.map((method) => [method.name, (raw: unknown, context: RpcContext) => invoke(method, raw, context)])), - } - const registration = await ctx.rpc.register(contract, handlers as never) - - // A script's ask has no one to answer it: refuse it now instead of leaving a prompt that waits. Only this RPC's own - // calls in flight match, so the model's calls and other plugins' calls are never touched. The hook only tightens. - const hook = await ctx.permission.hook("evaluate", (evaluation) => { - if (evaluation.source === undefined || !live.has(evaluation.source.id) || evaluation.effect === "allow") return - // Remember which check was refused and how, so the refusal names it; an allow or a deny is never changed. - refused.set(evaluation.source.id, { action: evaluation.action, effect: evaluation.effect === "ask" ? "ask" : "deny" }) - if (evaluation.effect !== "ask") return - evaluation.effect = "deny" - evaluation.message = UNATTENDED - }) - - return async () => { - await hook.dispose().catch(() => undefined) - await registration.dispose().catch(() => undefined) - } -} diff --git a/src/permissions.ts b/src/permissions.ts index 9f0f793..06aa3c2 100644 --- a/src/permissions.ts +++ b/src/permissions.ts @@ -1,4 +1,5 @@ import type { Plugin } from "@opencode/plugin" +import { EVENTS_ACTION, PROBE_ACTION } from "./sources.js" import { CHANGING_TOOLS, READ_TOOLS } from "./tools.js" import { reasonOf } from "./redact.js" @@ -22,14 +23,20 @@ const rule = (action: string, effect: Rule["effect"]): Rule => ({ action, resour */ export const CLEANUP_ACTION = "boxd_cleanup" +/** + * The `boxd.works` source's two tools RPC methods (`src/sources.ts`): reads of the local ledger that a collector runs + * with no one there, so every access value allows them, as it allows the read-only tools. + */ +export const SOURCE_ACTIONS: readonly string[] = [EVENTS_ACTION, PROBE_ACTION] + /** The effect a tool that is not read-only gets under one access value. A read-only tool always allows (OD-29). */ const changingEffect = (access: Access): Rule["effect"] => (access === "all" ? "allow" : access === "ask-changes" ? "ask" : "deny") /** * The block the plugin inserts after each agent's base allow, generated from the tool table's `readOnly` and the * `access` option (OD-29). Every tool this plugin registers is allowed at `all`, the default; `ask-changes` allows only - * the read-only tools and asks for the rest; `read-only` allows only them and denies the rest. `/boxd-cleanup`'s own - * action asks at every level (design §C.5). The namespace pattern's effect follows the value, + * the read-only tools and the source's two reads, and asks for the rest; `read-only` allows only them and denies the + * rest. `/boxd-cleanup`'s own action asks at every level (design §C.5). The namespace pattern's effect follows the value, * so a tool a later release adds runs at once under `all`, asks under `ask-changes` and is denied under `read-only`; * the known reads are allowed after it. The order is a safety net, not a decision point: the last matching rule wins, * and the exact-name rule comes after the pattern. @@ -40,6 +47,7 @@ export const defaultRules = (access: Access = "all"): Rule[] => { rule("boxd_*", changing), rule(CLEANUP_ACTION, "ask"), ...READ_TOOLS.map((tool) => rule(tool, "allow")), + ...SOURCE_ACTIONS.map((action) => rule(action, "allow")), ...CHANGING_TOOLS.map((tool) => rule(tool, changing)), ] } diff --git a/src/plugin.ts b/src/plugin.ts index 87613af..72cb37a 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -26,7 +26,9 @@ import { loadSkills, registerSkills } from "./skills.js" import { registerStatusCommand, registerStatusRpc, statusReader } from "./status.js" import { ownedMethods, toolTransform, type RegistryDeps } from "./tools.js" import { createWatch } from "./watch.js" -import { registerToolsRpc } from "./host/tools-rpc.js" +import { registerToolsRpc } from "@we-the-rebel-alliance/source-contract/tools-rpc" +import { localIdentity, sourceMethods } from "./sources.js" +import { PLUGIN } from "./tools-rpc.js" /** Internal seam: the host tests point the plugin at a fake boxd CLI, their own ledger root and their own skills. */ interface BoxdSeam { @@ -99,8 +101,15 @@ export function createBoxdPlugin(seam: BoxdSeam = {}) { await registerSkills(ctx.skill, skills).then((registration) => registration.dispose), await registerStatusCommand(ctx, read).then((registration) => registration.dispose), await registerStatusRpc(ctx.rpc, read).then((registration) => registration.dispose), - // Every tool as a method with its class: a script calls them with no model, and the rules decide what runs. - await registerToolsRpc(ctx, { methods: ownedMethods(registry, ctx.permission.assert) }), + // Every tool as a method with its class: a script calls them with no model, and the rules decide what runs. The + // boxd.works source's events_list and probe are methods only: they read the local ledger, never a machine. + await registerToolsRpc(ctx as never, { + plugin: PLUGIN, + methods: [ + ...ownedMethods(registry, ctx.permission.assert), + ...sourceMethods({ ledger: core.ledger, importV0, identity: localIdentity, now: () => hostServices.clock.now() }, ctx.permission.assert), + ], + }), await ctx.tool.transform(toolTransform(registry, ctx.permission.assert)).then((registration) => registration.dispose), watcher.dispose, // Cost and cleanup (design §C): the session hooks and events, the person's /boxd-cleanup, and automation. diff --git a/src/redact.ts b/src/redact.ts index c95810c..0390ac8 100644 --- a/src/redact.ts +++ b/src/redact.ts @@ -2,7 +2,7 @@ // No imports: status.ts, which the terminal UI bundle inlines, uses it too. Ported from opencode-wisprflow's redact.ts. /** - * Token shapes, the same as the tools RPC's for upstream errors (src/host/tools-rpc.ts): bearer and basic values, + * Token shapes, the same as the tools RPC's for upstream errors (the source contract's `tools-rpc`): bearer and basic values, * `key=value` secrets, JWTs, vendor-prefixed keys, and any long run of key characters; then email addresses and the * owner's name in a home folder (macOS, Linux or Windows), which becomes `~`. */ diff --git a/src/sources.ts b/src/sources.ts new file mode 100644 index 0000000..45e3019 --- /dev/null +++ b/src/sources.ts @@ -0,0 +1,387 @@ +/** + * boxd's side of the source contract (`@we-the-rebel-alliance/source-contract`, declared in `package.json`'s `sources` + * as `boxd.works`): `events_list`, each phase change of each work as one normalised event, oldest first, and `probe`, + * whose ledger it is. Both are tools RPC methods, for a consumer such as Memory's collector, and neither is a model tool. + * + * - **Local only.** `events_list` reads the laptop ledger's `events.jsonl` through `LedgerPort.eventsSince`, the log + * `boxd_status` reads its cursor from. It makes no boxd call and no network call, never wakes a machine, and never + * takes the ledger's write locks: the log is append-only, and reading it takes no lock. `probe` reads nothing at all: + * the account is this computer and the owner its OS user, as `os-user:@`. + * - **The plugin's own words.** An event's title is the plugin's sentence for the change (the work id, the phase, how + * a run ended and its code, who put a machine to sleep); its labels are the same facts as `phase:`, `outcome:`, + * `code:`, `asleep-by:` and `needs:`. Nothing a guest wrote, no prompt, no transcript and no work title reaches an + * event, and an event has no text, actors or link. A title that holds a secret (a work id shaped like a key) is + * refused for good, as `refused[]` with reason `secret`. + * - **The cursor** is the log's own sequence number, bound to the plugin, the source and the account, with the time of + * the last event it covers. A sequence number the log no longer keeps (it rotates at 5 MiB) or never had (another + * ledger's) is the ledger's `cursorExpired`: the page starts again at the oldest kept event and carries + * `gap: { reason: "expired", since }`, `since` being the time of the last event the cursor covered. A first read whose + * window starts before the oldest kept event says so the same way. + * - **While the v0 import runs** there is no published ledger to read: `events_list` answers `UNAVAILABLE` and the import + * progress, and never starts or retries the import itself (a retry lists machines with the boxd CLI). A failed import + * answers `UNAVAILABLE` too, until a boxd tool has run it again. + */ +import { hostname, userInfo } from "node:os" +import { decodeBoundCursor, encodeBoundCursor, type CursorBinding } from "@we-the-rebel-alliance/source-contract/cursor" +import { + EVENT_LIMITS, + EVENTS_LIST, + PAGE, + PROBE, + SourceError, + eventsListResult, + fitPage, + makeEvent, + oldestFirst, + parseEventsListInput, + parseProbeInput, + probeResult, + screenEvents, + startTime, + type EventsGap, + type EventsListIdentity, + type EventsListResult, + type EventsOwner, + type ProbeResult, + type SourceEvent, +} from "@we-the-rebel-alliance/source-contract/events" +import type { JsonSchema, PluginMethod, ToolCall } from "@we-the-rebel-alliance/source-contract/tools-rpc" +import type { Plugin } from "@opencode/plugin" +import { BoxdError } from "./errors.js" +import type { ImportV0Port, LedgerPort, OpContext, WorkEvent } from "./ports.js" + +/** The plugin's package name, which every page names. */ +export const PACKAGE = "@joe-broadhead/opencode-boxd" +/** The cursor binding's plugin: the descriptor's source-id prefix. */ +export const NAMESPACE = "boxd" +/** The source every event names, and the descriptor's `input.source`. */ +export const SOURCE = "works" +/** The descriptor's id for it. */ +export const SOURCE_ID = "boxd.works" +/** Every event's kind: boxd's own, one phase change of one work. */ +export const KIND = "x-boxd/work" +/** The permission action of events_list: the descriptor's `permission.events`. */ +export const EVENTS_ACTION = `${NAMESPACE}_${EVENTS_LIST}` +/** The permission action of probe: the descriptor's `sources.probe.action`. */ +export const PROBE_ACTION = `${NAMESPACE}_${PROBE}` +/** The most bytes of JSON one page holds: the descriptor's `maxBytes`. */ +export const MAX_BYTES = 65_536 + +/** Whose ledger this is: the computer it is on, and the OS user who runs OpenCode there. */ +export interface LocalIdentity { + /** The computer's host name as a slug, such as `studio-mac`. */ + readonly account: string + /** `os-user:@`, labelled ` on `. */ + readonly owner: EventsOwner +} + +const slug = (text: string, max: number) => + text + .toLowerCase() + .replace(/[^a-z0-9._-]+/g, "-") + .replace(/^[-.]+|[-.]+$/g, "") + .slice(0, max) + +/** The identity for an OS user and a host name, as given. */ +export function identityOf(user: string, host: string): LocalIdentity { + const account = slug(host.replace(/\.local\.?$/i, ""), 63) || "local" + const name = slug(user, 64) || "user" + return { account, owner: { id: `os-user:${name}@${account}`, label: `${name} on ${account}` } } +} + +/** This process's OS user and host name. A user with no password entry, as in some containers, falls back to $USER. */ +export function localIdentity(): LocalIdentity { + let user: string + try { + user = userInfo().username + } catch { + user = process.env.USER ?? process.env.LOGNAME ?? "" + } + return identityOf(user, hostname()) +} + +/** What the source reads: the ledger's event log, the import's state, whose ledger it is, and the clock. */ +export interface SourceDeps { + readonly ledger: Pick + readonly importV0: Pick + readonly identity: () => LocalIdentity + readonly now: () => Date +} + +/** The cursor's state: the last sequence number it covers (`q`), and that event's time or the window's start (`t`). */ +export interface CursorState { + readonly q: number + readonly t: string +} + +const binding = (account: string): CursorBinding => ({ plugin: NAMESPACE, source: SOURCE, account }) + +export const encodeWorksCursor = (account: string, state: CursorState): string => encodeBoundCursor(binding(account), { q: state.q, t: state.t }) + +const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/ + +function decodeWorksCursor(account: string, cursor: string): CursorState { + const decoded = decodeBoundCursor(binding(account), cursor) + const q = decoded.ok ? decoded.state["q"] : undefined + const t = decoded.ok ? decoded.state["t"] : undefined + if (!decoded.ok || typeof q !== "number" || !Number.isSafeInteger(q) || q < 0 || typeof t !== "string" || !ISO.test(t) || Number.isNaN(Date.parse(t))) { + throw new SourceError({ + code: "CURSOR_INVALID", + what: `The cursor is not one this source issued for the works of ${account}`, + next: "Call events_list again without a cursor, with since, to start over.", + }) + } + return { q, t } +} + +const opContext = (call: Pick | undefined, source: "boxd_events_list" | "boxd_probe"): OpContext => ({ + call: { callId: `${source}-${Date.now().toString(36)}`, source }, + pool: "foreground", + ...(call?.signal ? { signal: call.signal } : {}), +}) + +/** The import's state as a refusal, or nothing when the published ledger may be read. */ +function notReadable(state: ReturnType): SourceError | undefined { + if (state.state === "complete") return undefined + if (state.state === "importing") { + const progress = state.total > 0 ? ` (${state.done} of ${state.total} works)` : "" + return new SourceError({ + code: "UNAVAILABLE", + what: `boxd's ledger is still importing the works of opencode-boxd v0${progress}, so there is no event log to read yet`, + next: "Call events_list again in a minute, with the same cursor.", + }) + } + return new SourceError({ + code: "UNAVAILABLE", + what: "boxd's v0 import could not finish, so there is no event log to read yet", + next: "Run /boxd-status and follow its next step, then call events_list again.", + }) +} + +/** A ledger refusal as the contract's table names it. */ +function ledgerFailure(error: unknown): unknown { + if (!(error instanceof BoxdError)) return error + if (error.code === "LEDGER_IMPORTING" || error.code === "IMPORT_V0_FAILED") { + return new SourceError({ code: "UNAVAILABLE", what: `boxd's ledger is not readable yet (${error.code})`, next: "Call events_list again in a minute, with the same cursor." }) + } + return new SourceError({ code: "UNAVAILABLE", what: `boxd's event log could not be read (${error.code})`, next: "Run /boxd-status and follow its next step, then call events_list again." }) +} + +const OUTCOME_WORDS: Readonly> = { + completed: "its run completed", + failed: "its run failed", + aborted: "its run was stopped", +} + +const ASLEEP_BY: Readonly> = { + boxd_sleep: "put to sleep by boxd_sleep", + automation: "put to sleep by the plugin's automation", + "idle-or-cli": "asleep after its idle timeout, or by the boxd CLI", +} + +const PHASE_WORDS: Readonly> = { + creating: "its machine is being created", + starting: "its machine is starting", + ready: "it is ready", + busy: "it is running a prompt", + idle: "it is idle", + asleep: "its machine is asleep", + gone: "its machine is gone", + unreachable: "its machine is unreachable", + closed: "it is closed", +} + +/** The plugin's own sentence for one change: the work id, then the phase, the outcome, the code and who slept it. */ +export function titleOf(event: WorkEvent): string { + const said = + event.to === "idle" && event.outcome && OUTCOME_WORDS[event.outcome] + ? OUTCOME_WORDS[event.outcome]! + : event.to === "asleep" && event.asleepBy && ASLEEP_BY[event.asleepBy] + ? `its machine is ${ASLEEP_BY[event.asleepBy]}` + : (PHASE_WORDS[event.to] ?? `it is ${event.to}`) + const needs = event.needsInput === "permission" ? ", waiting for a permission answer" : event.needsInput === "form" ? ", waiting for an answer to a question" : "" + const code = event.code ? ` (${event.code})` : "" + return `Work ${event.workId}: ${said}${code}${needs}` +} + +/** One work event as a contract event. */ +export function eventOf(event: WorkEvent, account: string): SourceEvent { + return makeEvent({ + source: SOURCE, + account, + external_id: `${event.workId}:${event.seq}`, + kind: KIND, + occurred_at: event.at, + thread: `boxd-work:${event.workId}`, + title: titleOf(event), + labels: [ + `phase:${event.to}`, + ...(event.outcome ? [`outcome:${event.outcome}`] : []), + ...(event.code ? [`code:${event.code}`] : []), + ...(event.asleepBy ? [`asleep-by:${event.asleepBy}`] : []), + ...(event.needsInput ? [`needs:${event.needsInput}`] : []), + ], + }) +} + +/** The account a read names, checked against this computer's; a read of another computer's ledger is refused. */ +function checkAccount(account: string | undefined, identity: LocalIdentity): void { + if (account === undefined || account === identity.account) return + throw new SourceError({ + code: "ACCOUNT_MISMATCH", + what: `This source reads the boxd works of ${identity.account} only, and the read named another account`, + next: `Call it with account "${identity.account}", as probe names it, or without an account.`, + }) +} + +function checkSource(source: string | undefined): void { + if (source === undefined || source === SOURCE) return + throw new SourceError({ code: "SOURCE_UNKNOWN", what: `boxd has no source named ${source}`, next: `Call it with source "${SOURCE}", or without a source.` }) +} + +/** + * One page of `events_list`. The input is checked first; then, with the published ledger only, the log after the + * cursor (or from the window's start) is read once, cut to the limit and to `MAX_BYTES`, screened for secrets, and + * answered oldest first. + */ +export async function listWorks(deps: SourceDeps, input: unknown, call?: Pick): Promise { + const parsed = parseEventsListInput(input) + if (!parsed.ok) { + throw new SourceError({ code: "INPUT_INVALID", what: `events_list's input is invalid: ${parsed.problems.join("; ")}`, next: "Fix the input as the method's schema says, then call it again." }) + } + const request = parsed.value + checkSource(request.source) + const identity = deps.identity() + checkAccount(request.account, identity) + const from = request.cursor === undefined ? undefined : decodeWorksCursor(identity.account, request.cursor) + const refusal = notReadable(deps.importV0.state()) + if (refusal) throw refusal + + const now = deps.now() + let page + try { + page = await deps.ledger.eventsSince(from?.q ?? 0, opContext(call, "boxd_events_list")) + } catch (error) { + throw ledgerFailure(error) + } + + // Where this read starts in the log, and the history it says is lost. + let lines: readonly WorkEvent[] = page.events + let gap: EventsGap | undefined + let start: string + if (from) { + start = from.t + if (page.cursorExpired) gap = { reason: "expired", since: from.t } + } else { + const windowStart = startTime(request, now.getTime()) + start = new Date(windowStart).toISOString() + const first = lines.findIndex((line) => Date.parse(line.at) >= windowStart) + lines = first === -1 ? [] : lines.slice(first) + // The log no longer starts at its first event, and its oldest kept event is later than the window's start. + const oldest = page.events[0] + if (page.cursorExpired && oldest !== undefined && Date.parse(oldest.at) > windowStart) gap = { reason: "expired", since: start } + } + + // The page: at most `limit` lines in log order, as many as fit in MAX_BYTES once screened. + const candidates = lines.slice(0, request.limit) + const built = candidates.map((line) => ({ line, event: eventOf(line, identity.account) })) + const screened = screenEvents(built.map((entry) => entry.event)) + const refusedIds = new Set(screened.refused.map((entry) => entry.external_id)) + const refusedBytes = screened.refused.reduce((sum, entry) => sum + Buffer.byteLength(JSON.stringify(entry)) + 1, 0) + const fit = fitPage(screened.events, request.limit, MAX_BYTES - refusedBytes) + const lastKept = screened.events[fit - 1] + // The page covers every line up to the last kept event that fits, or every candidate when none was cut. + const cutAt = fit < screened.events.length && lastKept ? built.findIndex((entry) => entry.event.external_id === lastKept.external_id) + 1 : built.length + const covered = built.slice(0, cutAt) + const events = oldestFirst(covered.filter((entry) => !refusedIds.has(entry.event.external_id)).map((entry) => entry.event)) + const refused = screened.refused.filter((entry) => covered.some((item) => item.event.external_id === entry.external_id)) + const last = covered[covered.length - 1]?.line + // With nothing listed, the cursor is the log's newest sequence number: every line before the window is skipped. + const state: CursorState = last ? { q: last.seq, t: last.at } : { q: page.cursor, t: start } + const more = lines.length > covered.length + const whose: EventsListIdentity = { source: SOURCE, account: identity.account, owner: identity.owner } + return eventsListResult(whose, events, encodeWorksCursor(identity.account, state), more, { + refused, + ...(gap ? { gap } : {}), + plugin: PACKAGE, + asOf: now.toISOString(), + }) +} + +/** `probe`: whose ledger this is. It reads nothing, not even the ledger. */ +export function probeWorks(deps: Pick, input: unknown): ProbeResult { + const parsed = parseProbeInput(input) + if (!parsed.ok) throw new SourceError({ code: "INPUT_INVALID", what: `probe's input is invalid: ${parsed.problems.join("; ")}`, next: "Pass only source and account." }) + checkSource(parsed.value.source) + const identity = deps.identity() + checkAccount(parsed.value.account, identity) + return probeResult({ source: SOURCE, account: identity.account, owner: identity.owner }) +} + +const STRING = { type: "string" } as const + +const EVENTS_INPUT: JsonSchema = { + type: "object", + additionalProperties: false, + properties: { + source: { type: "string", enum: [SOURCE], description: `The source: "${SOURCE}", the only one.` }, + account: { type: "string", maxLength: EVENT_LIMITS.account, description: "This computer, as probe names it. Another computer's account is refused." }, + since: { ...STRING, description: "Where a read without a cursor starts: an ISO date or date-time. Default: 24 hours ago." }, + cursor: { ...STRING, description: "The previous page's cursor, to list what came after it." }, + limit: { type: "integer", minimum: PAGE.min, maximum: PAGE.max, description: `At most this many events; ${PAGE.default} by default.` }, + }, +} + +const PROBE_INPUT: JsonSchema = { + type: "object", + additionalProperties: false, + properties: { + source: { type: "string", enum: [SOURCE] }, + account: { type: "string", maxLength: EVENT_LIMITS.account }, + }, +} + +const EVENTS_DESCRIPTION = + "For a collector such as Memory's, not for answering questions: the phase changes of this laptop's boxd works, oldest first, as normalised events, " + + "read from the local ledger only (no boxd call, no machine woken). Each says, in the plugin's own words, which work changed and to what phase, how a run ended and its code. " + + "Pass the previous page's cursor to list what came after it; without one it starts at since, or 24 hours ago." + +const PROBE_DESCRIPTION = "For a consumer binding the boxd.works source: whose ledger this is (this computer, and its OS user). It reads nothing else." + +type Assert = Plugin.Context["permission"]["assert"] + +/** Each method asserts its own action with the call's source, as a tool does, then reads. */ +const asserting = (assert: Assert, action: string, call: ToolCall) => + assert({ sessionID: call.sessionID, agent: call.agent, action, resources: ["*"], source: { type: "tool", messageID: call.messageID, id: call.id } }) + +/** The source's two tools RPC methods, both reads. */ +export function sourceMethods(deps: SourceDeps, assert: Assert): readonly PluginMethod[] { + return [ + { + kind: "plugin", + class: "read", + name: EVENTS_LIST, + action: EVENTS_ACTION, + description: EVENTS_DESCRIPTION, + input: EVENTS_INPUT, + output: { type: "object" }, + run: async (input, call) => { + await asserting(assert, EVENTS_ACTION, call) + return listWorks(deps, input, call) + }, + }, + { + kind: "plugin", + class: "read", + name: PROBE, + action: PROBE_ACTION, + description: PROBE_DESCRIPTION, + input: PROBE_INPUT, + output: { type: "object" }, + run: async (input, call) => { + await asserting(assert, PROBE_ACTION, call) + return probeWorks(deps, input) + }, + }, + ] +} diff --git a/src/tools-rpc.ts b/src/tools-rpc.ts new file mode 100644 index 0000000..a1209ca --- /dev/null +++ b/src/tools-rpc.ts @@ -0,0 +1,69 @@ +/** + * boxd's part of the tools RPC (`boxd.machines.tools`): the plugin value and the method table that the source contract's + * `tools-rpc` module takes. The module (`@we-the-rebel-alliance/source-contract/tools-rpc`, bundled into + * `dist/index.js`) is the transport the plugin family shares: + * + * POST /api/rpc/boxd.machines.tools/ + * { "input": { "sessionID": "", "input": } } + * + * A script runs as a session and the agent it names; the rule for the method's permission action is resolved before + * dispatch, and only `allow` runs. boxd has no MCP server, so every method is the plugin's own: the twelve tools + * (`ownedMethods` in `src/tools.ts`) and the `boxd.works` source's `events_list` and `probe` (`src/sources.ts`). + */ +import { toolsRpcId, type Failure, type McpResult, type MethodSpec, type NextSteps, type ShapeCall, type ToolsRpcPlugin } from "@we-the-rebel-alliance/source-contract/tools-rpc" +import { PLUGIN_ID } from "./constants.js" + +export { PLUGIN_ID } + +/** The RPC's id: the plugin's id and `.tools`. Scripts call it by name, so it never changes. */ +export const TOOLS_RPC_ID = toolsRpcId(PLUGIN_ID) + +/** + * boxd has no MCP server, so no method comes from one. Every method is plugin-owned and built where it has the plugin's + * context (its own `permission.assert`): the tools in `ownedMethods`, and the source's reads in `sourceMethods`. + */ +export const METHODS: readonly MethodSpec[] = [] + +/** The model path has no MCP call to reshape; an owned method's input is its own tool input. */ +export function shapeInput(_method: string, input: unknown, _call: ShapeCall): unknown { + return input +} + +/** Nothing on the model path reshapes a result either. */ +export function shapeResult(_method: string, result: McpResult, _call: ShapeCall): McpResult { + return result +} + +/** + * The next step for each code. boxd has no MCP methods, so the MCP-only steps are unused here; they stay because this + * value is also the fixture the family's shared suites run against, and a code's text must not drift. + */ +export const NEXT_STEPS: NextSteps = { + SESSION_UNKNOWN: `Create a session in the location you mean, such as POST /api/session with {"agent":"build"} sent with the header "x-opencode-directory: " or the location[directory] query, and pass its id.`, + SESSION_AGENT_REQUIRED: `Create a session that names an agent this project has, with its project as the location, such as POST /api/session with {"agent":"build","location":{"directory":"/path/to/project"}}, and pass its id.`, + PERMISSION_DENIED: + "A script cannot answer an approval prompt: add an allow rule for the method to the session's agent, then call it again.", + SERVER_CONFLICT: `Remove your own server from opencode.json so that the plugin manages it, then run "opencode reload".`, + AUTH_REQUIRED: "Run /connect and choose the plugin's account to connect it.", + CONNECTING: "Wait a few seconds, then call the method again.", + CONNECTION_FAILED: "Run /boxd-status and follow its next step.", + DISABLED: `Enable the plugin's server in /mcps, or remove "disabled": true from its entry in opencode.json.`, + NOT_REGISTERED: "Run /boxd-status and follow its next step.", + TOOL_UNAVAILABLE: "Call describe to see which methods OpenCode lists now, and run /boxd-status.", + UPSTREAM_ERROR: "Check the input against the method's schema from describe, and run /boxd-status if it keeps failing.", + CANCELLED: "Call the method again if you still need the result.", +} + +/** A boxd error, thrown by one of the plugin's own methods, as the script's code, what happened and the next step. */ +export function pluginError(error: unknown): Failure | undefined { + if (!(error instanceof Error)) return undefined + const { code, next } = error as { readonly code?: unknown; readonly next?: unknown } + if (typeof code !== "string" || typeof next !== "string") return undefined + // Strip the code and the next step from the message: the envelope carries them separately. + const message = error.message.startsWith(`${code}: `) ? error.message.slice(code.length + 2) : error.message + const what = message.split(" Next step: ")[0] ?? message + return { code, what: what.replace(/[.\s]+$/, ""), next } +} + +/** The plugin value the transport takes. */ +export const PLUGIN: ToolsRpcPlugin = { id: PLUGIN_ID, nextSteps: NEXT_STEPS, shapeInput, shapeResult, pluginError } diff --git a/src/tools.ts b/src/tools.ts index 290216a..42e9f8c 100644 --- a/src/tools.ts +++ b/src/tools.ts @@ -15,7 +15,7 @@ import type { Plugin } from "@opencode/plugin" import { BoxdError, boxdError, errorState } from "./errors.js" import { NAMESPACE } from "./constants.js" -import type { JsonSchema, MethodClass, PluginMethod, ToolCall } from "./host/tools-rpc.js" +import type { JsonSchema, MethodClass, PluginMethod, ToolCall } from "@we-the-rebel-alliance/source-contract/tools-rpc" import { LIST_MAX_ITEMS, REGIONS, SIZES } from "./ports.js" import type { Refusal } from "./results.js" import type { Selector, SelectorValues, Selectors, ToolRuns } from "./services.js" diff --git a/test/fixtures/conformance.json b/test/fixtures/conformance.json new file mode 100644 index 0000000..b8f6cb4 --- /dev/null +++ b/test/fixtures/conformance.json @@ -0,0 +1,26 @@ +{ + "now": "2026-11-17T12:00:00.000Z", + "user": "sam", + "host": "studio-mac", + "rotateBytes": 700, + "events": [ + { "at": "2026-11-16T08:00:00.000Z", "workId": "fix-auth", "from": null, "to": "creating" }, + { "at": "2026-11-16T08:01:00.000Z", "workId": "fix-auth", "from": "creating", "to": "starting" }, + { "at": "2026-11-16T08:03:00.000Z", "workId": "fix-auth", "from": "starting", "to": "ready" }, + { "at": "2026-11-16T08:04:00.000Z", "workId": "fix-auth", "from": "ready", "to": "busy" }, + { "at": "2026-11-16T09:30:00.000Z", "workId": "fix-auth", "from": "busy", "to": "idle", "outcome": "completed" }, + { "at": "2026-11-16T10:00:00.000Z", "workId": "docs-pass", "from": null, "to": "creating" }, + { "at": "2026-11-16T10:01:00.000Z", "workId": "docs-pass", "from": "creating", "to": "starting" }, + { "at": "2026-11-16T10:02:00.000Z", "workId": "docs-pass", "from": "starting", "to": "ready" }, + { "at": "2026-11-16T10:05:00.000Z", "workId": "docs-pass", "from": "ready", "to": "busy" }, + { "at": "2026-11-16T10:40:00.000Z", "workId": "docs-pass", "from": "busy", "to": "idle", "outcome": "failed", "code": "RUN_FAILED" }, + { "at": "2026-11-16T11:00:00.000Z", "workId": "fix-auth", "from": "idle", "to": "asleep", "asleepBy": "automation" }, + { "at": "2026-11-17T08:00:00.000Z", "workId": "sk-proj9x7k2m4q8r1t6w3z", "from": null, "to": "creating" }, + { "at": "2026-11-17T08:01:00.000Z", "workId": "sk-proj9x7k2m4q8r1t6w3z", "from": "creating", "to": "starting" }, + { "at": "2026-11-17T08:02:00.000Z", "workId": "sk-proj9x7k2m4q8r1t6w3z", "from": "starting", "to": "ready" }, + { "at": "2026-11-17T09:00:00.000Z", "workId": "docs-pass", "from": "idle", "to": "busy", "needsInput": "permission" }, + { "at": "2026-11-17T09:20:00.000Z", "workId": "docs-pass", "from": "busy", "to": "idle", "outcome": "aborted" }, + { "at": "2026-11-17T10:00:00.000Z", "workId": "fix-auth", "from": "asleep", "to": "closed" }, + { "at": "2026-11-17T11:00:00.000Z", "workId": "docs-pass", "from": "idle", "to": "asleep", "asleepBy": "boxd_sleep" } + ] +} diff --git a/test/host/boxd.test.ts b/test/host/boxd.test.ts index e53e4a4..27eccef 100644 --- a/test/host/boxd.test.ts +++ b/test/host/boxd.test.ts @@ -9,7 +9,7 @@ import { join } from "node:path" import { SUPPORTED_HOST } from "../../src/constants.js" import { defaultRules, type Rule } from "../../src/permissions.js" import { TOOLS, CHANGING_TOOLS, READ_TOOLS } from "../../src/tools.js" -import { TOOLS_RPC_ID } from "../../src/host/tools-rpc.js" +import { TOOLS_RPC_ID } from "../../src/tools-rpc.js" import { agentRules, attempt, cleanup, effect, HOST_VERSION, session, startHost, statusThroughRpc, until } from "./harness.js" /** The released version, from package.json: status reports it. */ @@ -129,11 +129,13 @@ describe("the plugin on a stock host", () => { try { const build = await session(host) const listing = (await rpcCall(host, "describe", { sessionID: build })).output as { methods: Array>; unclassified: string[] } - expect(listing.methods.map((method) => method.name)).toEqual(TOOLS.map((tool) => tool.id)) + // The twelve tools, then the boxd.works source's two reads. + expect(listing.methods.map((method) => method.name)).toEqual([...TOOLS.map((tool) => tool.id), "events_list", "probe"]) expect(listing.unclassified ?? []).toEqual([]) for (const method of listing.methods) { - const spec = TOOLS.find((tool) => tool.id === method.name)! - expect({ name: method.name, kind: method.kind, class: method.class, action: method.action }).toEqual({ name: method.name, kind: "plugin", class: spec.class, action: spec.id }) + const spec = TOOLS.find((tool) => tool.id === method.name) + const want = spec ? { class: spec.class, action: spec.id } : { class: "read", action: `boxd_${method.name}` } + expect({ name: method.name, kind: method.kind, class: method.class, action: method.action }).toEqual({ name: method.name, kind: "plugin", ...want }) } expect((await rpcCall(host, "boxd_submit", { sessionID: build, input: { workId: "review-api", text: "Add a health check." } })).output).toMatchObject(NOT_OURS) @@ -153,6 +155,39 @@ describe("the plugin on a stock host", () => { }) }) +describe("the boxd.works source on a stock host", () => { + test("probe and events_list answer over the tools RPC from the local ledger, with no boxd call, at every access value", async () => { + for (const access of ["all", "ask-changes", "read-only"] as const) { + const host = await startHost({ options: { access } }) + try { + const build = await session(host) + const probed = (await rpcCall(host, "probe", { sessionID: build, input: { source: "works" } })).output as Record + expect(probed).toMatchObject({ source: "works", trust: "untrusted" }) + expect(probed.owner.id).toStartWith("os-user:") + // The ledger is readable once the start's import check is done; until then the source answers UNAVAILABLE. + const page = await until("events_list answers a page", async () => { + const answer = await rpcCall(host, "events_list", { sessionID: build, input: { source: "works", since: "2026-01-01T00:00:00Z" } }).then( + (result) => result.output as Record, + (error: { data?: { code?: string } }) => (error?.data?.code === "UNAVAILABLE" ? undefined : Promise.reject(error)), + ) + return answer + }) + expect(page).toMatchObject({ source: "works", account: probed.account, owner: probed.owner, events: [], more: false, trust: "untrusted", plugin: "@joe-broadhead/opencode-boxd" }) + expect(typeof page.cursor).toBe("string") + // Once the ledger is published, the source's reads make no boxd call at all. + const before = host.boxd.calls().length + const again = (await rpcCall(host, "events_list", { sessionID: build, input: { cursor: page.cursor } })).output as Record + expect(again).toMatchObject({ events: [], cursor: page.cursor, more: false }) + await rpcCall(host, "probe", { sessionID: build, input: {} }) + expect(await refusedCode(rpcCall(host, "events_list", { sessionID: build, input: { account: "another-computer" } }))).toBe("ACCOUNT_MISMATCH") + expect(host.boxd.calls().slice(before)).toEqual([]) + } finally { + await host.close() + } + } + }) +}) + describe("cost and cleanup's surfaces (design §C)", () => { test("the session hooks and the session-events subscription register on this host, and /boxd-cleanup changes nothing yet", async () => { const host = await startHost() diff --git a/test/host/machines.test.ts b/test/host/machines.test.ts index 6108195..a4c2de7 100644 --- a/test/host/machines.test.ts +++ b/test/host/machines.test.ts @@ -5,7 +5,7 @@ import { MEASURE_DEBUG, MEASURE_MINUTES as MEASURE } from "./measure-env.js" import { afterAll, describe, expect, setDefaultTimeout, test } from "bun:test" import { join } from "node:path" -import { TOOLS_RPC_ID } from "../../src/host/tools-rpc.js" +import { TOOLS_RPC_ID } from "../../src/tools-rpc.js" import { attempt, cleanup, HOST_VERSION, session, startHost, until, type Host } from "./harness.js" setDefaultTimeout(120_000) diff --git a/test/host/sessions.test.ts b/test/host/sessions.test.ts index aafe1e7..59e6c08 100644 --- a/test/host/sessions.test.ts +++ b/test/host/sessions.test.ts @@ -8,7 +8,7 @@ import { createHash } from "node:crypto" import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs" import { join } from "node:path" import { createRuntime } from "../../src/exec/runtime.js" -import { TOOLS_RPC_ID } from "../../src/host/tools-rpc.js" +import { TOOLS_RPC_ID } from "../../src/tools-rpc.js" import { ledgerPort } from "../../src/ledger/index.js" import { Ledger } from "../../src/ledger/store.js" import type { WorkRecord } from "../../src/ledger/types.js" diff --git a/test/pack/pack.test.ts b/test/pack/pack.test.ts index c5adad1..7b9b342 100644 --- a/test/pack/pack.test.ts +++ b/test/pack/pack.test.ts @@ -154,6 +154,8 @@ describe("package tarball", () => { test("dist imports only modules the host provides", () => { const dist = join(installedPackage(true), "dist") + // The scan finds the bundle's real imports, so an empty foreign list means something. + expect(specifiers(readFileSync(join(dist, "index.js"), "utf8"))).toContain("@opencode/plugin") expect(foreign(join(dist, "index.js"), SERVER_HOST_MODULES)).toEqual([]) expect(foreign(join(dist, "tui.js"), TUI_HOST_MODULES)).toEqual([]) }, 300_000) @@ -312,10 +314,13 @@ function tree(dir: string, base = root): string[] { .map((item) => relative(base, join(item.parentPath, item.name)).split(sep).join("/")) } -/** Every module specifier a file really imports: a whole statement line, or a call with a literal specifier. */ +/** + * Every module specifier a file really imports: a whole statement, at a line's start or after a `;` (the bundles are + * minified, so several statements share a line), or a call with a literal specifier. + */ const specifiers = (source: string) => [ - ...[...source.matchAll(/^[ \t]*(?:import|export)[ \t][^'"`\n]*?from[ \t]*["']([^"']+)["']/gm)].map((match) => match[1]!), - ...[...source.matchAll(/^[ \t]*import[ \t]*["']([^"']+)["']/gm)].map((match) => match[1]!), + ...[...source.matchAll(/(?:^|;)[ \t]*(?:import|export)\b[^'"`;\n]*?\bfrom[ \t]*["']([^"']+)["']/gm)].map((match) => match[1]!), + ...[...source.matchAll(/(?:^|;)[ \t]*import[ \t]*["']([^"']+)["']/gm)].map((match) => match[1]!), ...[...source.matchAll(/\b(?:import|require)\s*\(\s*["']([^"']+)["']\s*\)/g)].map((match) => match[1]!), ] diff --git a/test/support/conformance.ts b/test/support/conformance.ts new file mode 100644 index 0000000..3424efb --- /dev/null +++ b/test/support/conformance.ts @@ -0,0 +1,147 @@ +// source-contract's conformance kit over the boxd.works source, run on the plugin's own tools RPC methods `events_list` +// and `probe` (`sourceMethods`, as setup registers them), over a real event log (`EventLog`, src/ledger/events.ts) in a +// temp ledger, written from test/fixtures/conformance.json. Its rotation size is small, so the log has already +// dropped its first events and an old cursor meets the ledger's own `cursorExpired`. No boxd CLI, no network. Each +// method asserts its action through the kit's recording permission, as the host's `ctx.permission.assert` would. +// `npm run conformance` writes the report (reports/conformance-report.json); test/unit/sources.test.ts asserts it. +import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { sourceConformance, type ConformanceReport, type PageCase, type SessionContext, type ToolDeclaration } from "@we-the-rebel-alliance/source-contract/conformance" +import { encodeBoundCursor } from "@we-the-rebel-alliance/source-contract/cursor" +import { readInstalledDescriptor } from "@we-the-rebel-alliance/source-contract/descriptor" +import { SOURCES_SCHEMA, type Sources } from "@we-the-rebel-alliance/source-contract/schema" +import type { PluginMethod, ToolCall } from "@we-the-rebel-alliance/source-contract/tools-rpc" +import { EventLog, type NewEvent } from "../../src/ledger/events.js" +import type { ImportState, WorkEvent } from "../../src/ports.js" +import { encodeWorksCursor, identityOf, PACKAGE, SOURCE, sourceMethods, type LocalIdentity, type SourceDeps } from "../../src/sources.js" +import { TOOLS } from "../../src/tools.js" +import { TOOLS_RPC_ID } from "../../src/tools-rpc.js" + +export const ROOT = join(import.meta.dir, "..", "..") + +export interface Fixture { + readonly now: string + readonly user: string + readonly host: string + readonly rotateBytes: number + readonly events: readonly NewEvent[] +} + +export const FIXTURE = JSON.parse(readFileSync(join(ROOT, "test", "fixtures", "conformance.json"), "utf8")) as Fixture + +/** A temp ledger folder whose event log holds the fixture's events, rotated as the fixture's size says. */ +export async function fixtureLog(fixture: Fixture = FIXTURE): Promise<{ readonly log: EventLog; readonly kept: readonly WorkEvent[]; readonly cleanup: () => void }> { + const dir = mkdtempSync(join(realpathSync(tmpdir()), "boxd-sources-")) + const log = new EventLog(dir, { rotateBytes: fixture.rotateBytes, now: () => new Date(fixture.now) }) + for (const event of fixture.events) await log.append(event) + const kept = (await log.since(0)).events + return { log, kept, cleanup: () => rmSync(dir, { recursive: true, force: true }) } +} + +const COMPLETE: ImportState = { state: "complete", works: 3, blocked: [] } + +/** The source's deps over one event log: the published ledger, this fixture's computer and user, and its clock. */ +export function fixtureDeps(log: EventLog, fixture: Fixture = FIXTURE, overrides: Partial = {}): SourceDeps { + const identity: LocalIdentity = identityOf(fixture.user, fixture.host) + return { + ledger: { eventsSince: (cursor) => log.since(cursor) }, + importV0: { state: () => COMPLETE }, + identity: () => identity, + now: () => new Date(fixture.now), + ...overrides, + } +} + +export const call = (): ToolCall => ({ sessionID: "ses_conformance", agent: "build", messageID: "msg_conformance", id: "call_conformance", signal: new AbortController().signal, progress: async () => {} }) + +/** The plugin's tools RPC methods, as describe lists them: the twelve tools and the source's two reads. */ +export function declaredTools(deps: SourceDeps): ToolDeclaration[] { + const source = sourceMethods(deps, async () => {}) + return [...TOOLS.map((tool) => ({ id: tool.id, readOnly: tool.readOnly })), ...source.map((method) => ({ id: method.name, readOnly: method.class === "read" }))] +} + +/** package.json's sources, as Memory's schema parses them for the kit; first read as a consumer reads the install. */ +export function declaredSources(): Sources { + const installed = readInstalledDescriptor(ROOT) + if (!installed.ok) throw new Error(`package.json's sources: ${installed.problems.join("; ")}`) + const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")) as { sources: unknown } + const checked = SOURCES_SCHEMA.check(pkg.sources) + if (!checked.ok) throw new Error(`package.json's sources: ${checked.problems.join("; ")}`) + return checked.value +} + +/** The kit's report for boxd.works. */ +export async function conformanceReports(fixture: Fixture = FIXTURE): Promise { + const sources = declaredSources() + const { log, kept, cleanup } = await fixtureLog(fixture) + try { + const deps = fixtureDeps(log, fixture) + const identity = deps.identity() + const account = identity.account + // The methods assert into whichever kit session is calling. + let current: SessionContext["permission"] | undefined + const methods = sourceMethods(deps, async (request) => { + if (current === undefined) throw new Error("an assert ran outside a kit call") + await current.assert({ action: request.action, resources: [...(request.resources ?? [])] }) + }) + const run = (method: PluginMethod) => (input: Readonly>, context: SessionContext) => { + current = context.permission + return method.run(input, call()).finally(() => (current = undefined)) + } + const [list, probe] = methods as [PluginMethod, PluginMethod] + const oldest = kept[0]! + const newest = kept[kept.length - 1]! + if (oldest.seq <= 1) throw new Error("the fixture's log has not rotated: lower rotateBytes, so an old cursor expires") + const keptSince = kept[1]!.at + const other = "other-mac" + const cases: PageCase[] = [ + { + name: "the works since a time the log still keeps, with the events of a work whose id is shaped like an API key refused", + input: { source: SOURCE, account, since: keptSince }, + }, + { name: "the same, two at a time", input: { source: SOURCE, account, since: keptSince, limit: 2 } }, + { name: "the newest cursor lists nothing, and still answers a cursor", input: { cursor: encodeWorksCursor(account, { q: newest.seq, t: newest.at }) }, expect: "empty" }, + { + name: "a window that starts before the oldest kept event says once that the history before it is gone", + input: { since: "2026-11-15T00:00:00Z", limit: 3 }, + }, + { + name: "a cursor the log has rotated away answers a gap and reads on from the oldest kept event", + input: { cursor: encodeWorksCursor(account, { q: 1, t: fixture.events[0]!.at! }) }, + expect: "expired", + }, + { + name: "a cursor of another ledger, newer than this log, answers a gap too", + input: { cursor: encodeWorksCursor(account, { q: newest.seq + 50, t: newest.at }) }, + expect: "expired", + }, + { name: "another computer's account is refused", input: { account: other, since: keptSince }, expect: { refuses: "ACCOUNT_MISMATCH" } }, + { name: "another computer's cursor is refused", input: { cursor: encodeWorksCursor(other, { q: oldest.seq, t: oldest.at }) }, expect: { refuses: "CURSOR_INVALID" } }, + { + name: "a cursor bound to another plugin is refused", + input: { cursor: encodeBoundCursor({ plugin: "jobs", source: SOURCE, account }, { q: oldest.seq, t: oldest.at }) }, + expect: { refuses: "CURSOR_INVALID" }, + }, + { name: "a scope is refused: this source has none", input: { scope: { works: ["fix-auth"] } }, expect: { refuses: "INPUT_INVALID" } }, + { name: "a source boxd does not have is refused", input: { source: "machines" }, expect: { refuses: "SOURCE_UNKNOWN" } }, + ] + const report = await sourceConformance({ + plugin: PACKAGE, + source: sources.items[0]!, + tools: declaredTools(deps), + calls: { list: run(list), probe: run(probe) }, + cases, + account, + sources: { rpc: sources.rpc, probe: sources.probe }, + describe: { id: TOOLS_RPC_ID }, + atomicPages: { + reason: + "a page is one read of the local event log, where a line is read whole or not at all (a line cut off by a crash was never an event), so no single event can fail on its own", + }, + }) + return [report] + } finally { + cleanup() + } +} diff --git a/test/unit/docs.test.ts b/test/unit/docs.test.ts index 1188240..1ab0fb0 100644 --- a/test/unit/docs.test.ts +++ b/test/unit/docs.test.ts @@ -9,6 +9,7 @@ import { COMMAND_STEM, TESTED_HOSTS } from "../../src/constants.js" import { CHANGING_TOOLS, TOOLS } from "../../src/tools.js" import { defaultRules } from "../../src/permissions.js" import { DEFAULT_OPTIONS, parseOptions } from "../../src/options.js" +import { sourceMethods } from "../../src/sources.js" const root = new URL("../../", import.meta.url) const read = (path: string) => readFileSync(new URL(path, root), "utf8") @@ -17,6 +18,8 @@ const CONFIG = read("docs/configuration.md") const SCRIPTING = read("docs/scripting.md") const codes = Object.keys(CODES) +/** The source's methods, for their names and input schemas only: nothing here calls them. */ +const SOURCE_METHODS = sourceMethods({ ledger: { eventsSince: async () => ({ events: [], cursor: 0, cursorExpired: false }) }, importV0: { state: () => ({ state: "complete", works: 0, blocked: [] }) }, identity: () => ({ account: "local", owner: { id: "os-user:user@local", label: "user on local" } }), now: () => new Date() }, async () => {}) /** Every file under a folder, relative to the repository. */ @@ -198,7 +201,8 @@ describe("the docs set", () => { expect({ method, keys: Object.keys(envelope) }).toEqual({ method, keys: ["input"] }) expect(typeof envelope.input?.sessionID).toBe("string") if (method === "describe") continue - const spec = TOOLS.find((tool) => tool.id === method) + // A tool, or one of the boxd.works source's two methods. + const spec = [...TOOLS.map((tool) => ({ id: tool.id, input: tool.input })), ...SOURCE_METHODS.map((entry) => ({ id: entry.name, input: entry.input }))].find((tool) => tool.id === method) expect({ method, known: spec !== undefined }).toEqual({ method, known: true }) expect({ method, problem: conforms(envelope.input?.input ?? {}, spec!.input as Record) }).toEqual({ method, problem: undefined }) } diff --git a/test/unit/permissions.test.ts b/test/unit/permissions.test.ts index 4b54138..587110d 100644 --- a/test/unit/permissions.test.ts +++ b/test/unit/permissions.test.ts @@ -1,5 +1,5 @@ import { describe, expect, test } from "bun:test" -import { ACCESS_VALUES, defaultRules, evaluate, hasDefaultRules, insertRules, unguardedAgents, type Access, type Rule } from "../../src/permissions.js" +import { ACCESS_VALUES, SOURCE_ACTIONS, defaultRules, evaluate, hasDefaultRules, insertRules, unguardedAgents, type Access, type Rule } from "../../src/permissions.js" import { TOOLS } from "../../src/tools.js" const BASE: Rule = { action: "*", resource: "*", effect: "allow" } @@ -10,7 +10,7 @@ describe("the generated default rules", () => { expect(all[0]).toEqual({ action: "boxd_*", resource: "*", effect: "allow" }) for (const tool of TOOLS) expect(all).toContainEqual({ action: tool.id, resource: "*", effect: "allow" }) // The pattern is what a tool a later release adds inherits. - expect(all).toHaveLength(2 + TOOLS.length) + expect(all).toHaveLength(2 + TOOLS.length + SOURCE_ACTIONS.length) expect(all[1]).toEqual({ action: "boxd_cleanup", resource: "*", effect: "ask" }) }) @@ -31,9 +31,12 @@ describe("the generated default rules", () => { test("every access value generates a block", () => { expect(ACCESS_VALUES).toEqual(["all", "ask-changes", "read-only"]) for (const access of ACCESS_VALUES) { - expect(defaultRules(access).length).toBe(2 + TOOLS.length) + expect(defaultRules(access).length).toBe(2 + TOOLS.length + SOURCE_ACTIONS.length) // /boxd-cleanup confirms each action with a prompt at every access level (design §C.5). expect(evaluate([BASE, ...defaultRules(access)], "boxd_cleanup")).toBe("ask") + // The boxd.works source's events_list and probe only read the local ledger: a collector runs them at every level. + expect(SOURCE_ACTIONS).toEqual(["boxd_events_list", "boxd_probe"]) + for (const action of SOURCE_ACTIONS) expect(evaluate([BASE, ...defaultRules(access)], action)).toBe("allow") } }) }) diff --git a/test/unit/resolve.test.ts b/test/unit/resolve.test.ts index 04486ec..1087a60 100644 --- a/test/unit/resolve.test.ts +++ b/test/unit/resolve.test.ts @@ -7,7 +7,8 @@ import { describe, expect, test } from "bun:test" import { tmpdir } from "node:os" import { join } from "node:path" -import { NEXT_STEPS, registerToolsRpc, type MethodSpec, type ToolCall, type ToolsRpcOptions } from "../../src/host/tools-rpc.js" +import { registerToolsRpc, type MethodSpec, type ToolCall, type ToolsRpcOptions } from "@we-the-rebel-alliance/source-contract/tools-rpc" +import { NEXT_STEPS, PLUGIN } from "../../src/tools-rpc.js" type Effect = "allow" | "deny" | "ask" type Rule = { action: string; resource: string; effect: Effect } @@ -127,7 +128,7 @@ async function setup(input: { agent: readonly Rule[]; session: readonly Rule[]; mcp: { list: async () => ({ data: [{ name: SERVER, status: { status: "connected" } }] }) }, } const serverOptions: ToolsRpcOptions["mcp"] = { server: SERVER, managed: () => true } - await registerToolsRpc(ctx as never, { methods, mcp: serverOptions }) + await registerToolsRpc(ctx as never, { plugin: PLUGIN, methods, mcp: serverOptions }) return { handlers, executions } } diff --git a/test/unit/sources.test.ts b/test/unit/sources.test.ts new file mode 100644 index 0000000..847437a --- /dev/null +++ b/test/unit/sources.test.ts @@ -0,0 +1,238 @@ +// The boxd.works source (src/sources.ts): the conformance kit's report, the family's events_list suite, and the cases the +// kit does not name on its own: paging, an empty page, an expired cursor, the ledger failing, the v0 import still +// running, another account at the probe, the plugin's own words, and a read while the event log's lock is held. +import { afterAll, describe, expect, test } from "bun:test" +import { readFileSync } from "node:fs" +import { join } from "node:path" +import { assertEventsListConformance, type EventsListResult } from "@we-the-rebel-alliance/source-contract/events" +import { sessionRules } from "@we-the-rebel-alliance/source-contract/permission" +import { boxdError } from "../../src/errors.js" +import { acquireLock } from "../../src/ledger/lock.js" +import type { WorkEvent } from "../../src/ports.js" +import { encodeWorksCursor, eventOf, listWorks, probeWorks, sourceMethods, titleOf } from "../../src/sources.js" +import { TOOLS_RPC_ID } from "../../src/tools-rpc.js" +import { call, conformanceReports, declaredSources, FIXTURE, fixtureDeps, fixtureLog } from "../support/conformance.js" + +const fixture = await fixtureLog() +afterAll(fixture.cleanup) +const deps = fixtureDeps(fixture.log) +const { account, owner } = deps.identity() +const kept = fixture.kept +const KEY_SHAPED = "sk-proj9x7k2m4q8r1t6w3z" +const list = (input: Record) => listWorks(deps, input) as Promise +/** The refusal a read ends in. */ +const refusalOf = (promise: Promise) => + promise.then( + () => { + throw new Error("the read answered, and it must be refused") + }, + (error: unknown) => error as Error & { code: string; next: string }, + ) +const code = (promise: Promise) => + promise.then( + () => undefined, + (error: { code?: string; message?: string }) => error.code, + ) + +describe("the declaration", () => { + test("is one events source on this plugin's tools RPC, whose fenced session allows only its own action", () => { + const sources = declaredSources() + expect(sources.rpc).toBe(TOOLS_RPC_ID) + expect(sources.probe).toEqual({ action: "boxd_probe" }) + expect(sources.items.map((item) => [item.id, item.kind, item.kind === "events" ? item.reads : undefined, item.input?.["source"]])).toEqual([["boxd.works", "events", "x-boxd/work", "works"]]) + const rules = sessionRules(sources.items[0]! as never, { source: "boxd.works", account }) + expect(rules.ok ? rules.value : rules.problems).toEqual([ + { action: "*", resource: "*", effect: "deny" }, + { action: "boxd_events_list", resource: "*", effect: "allow" }, + ]) + }) + + test("declares none of the keys a consumer on source-contract 0.1.x refuses", () => { + const pkg = JSON.parse(readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8")) as { sources: { items: { permission: Record; accounts: Record }[] } } + for (const item of pkg.sources.items) { + for (const key of ["identityRules", "readsIdentity", "identity"]) expect(item.permission[key]).toBeUndefined() + expect(item.accounts["server"]).toBeUndefined() + } + }) +}) + +describe("the conformance kit", () => { + test("passes, with the expired-cursor check run for real: the log rotates", async () => { + const [report] = await conformanceReports() + expect(report!.problems).toEqual([]) + expect(report!.ok).toBe(true) + const byName = new Map(report!.checks.map((check) => [check.name, check])) + for (const name of ["page-result", "gap-and-cursor-expired", "gap-once-per-read", "refused-is-final", "probe", "unused-grants", "rpc-id"]) { + expect({ name, ran: byName.get(name)?.ran }).toEqual({ name, ran: true }) + } + expect(byName.get("failed-holds-cursor")).toMatchObject({ ran: false, notApplicable: true }) + expect(byName.get("failed-holds-cursor")!.reason).toContain("one read of the local event log") + }) + + test("the family's events_list suite: pages join up, an old cursor repeats its page, refusals carry the table's codes", async () => { + const since = kept[1]!.at + const listed = kept.filter((line) => line.seq >= kept[1]!.seq) + await assertEventsListConformance((input) => listWorks(deps, input), { + source: "works", + account, + owner, + since, + expected: listed.filter((line) => line.workId !== KEY_SHAPED).map((line) => `${line.workId}:${line.seq}`), + refused: listed.filter((line) => line.workId === KEY_SHAPED).map((line) => `${line.workId}:${line.seq}`), + maxBytes: 65_536, + kinds: ["x-boxd/work"], + namespace: "boxd", + binding: { plugin: "boxd" }, + codes: true, + }) + }) +}) + +describe("events_list", () => { + test("pages: each page's cursor lists what follows it, and the last answers more: false", async () => { + const since = kept[1]!.at + const ids: string[] = [] + let page = await list({ since, limit: 2 }) + for (let guard = 0; guard < 20; guard++) { + ids.push(...page.events.map((event) => event.external_id), ...(page.refused ?? []).map((entry) => entry.external_id)) + if (!page.more) break + page = await list({ cursor: page.cursor, limit: 2 }) + } + expect(page.more).toBe(false) + expect(ids.sort()).toEqual(kept.slice(1).map((line) => `${line.workId}:${line.seq}`).sort()) + }) + + test("an empty page names its source, account and owner, and answers a cursor that lists nothing new", async () => { + const newest = kept[kept.length - 1]! + const page = await list({ cursor: encodeWorksCursor(account, { q: newest.seq, t: newest.at }) }) + expect(page).toMatchObject({ source: "works", account, owner, events: [], more: false, trust: "untrusted" }) + expect(page.gap).toBeUndefined() + expect((await list({ cursor: page.cursor })).events).toEqual([]) + }) + + test("a cursor the log rotated away answers gap.reason expired, since the time it covered, and reads on from the oldest kept event", async () => { + const lost = FIXTURE.events[0]! + const page = await list({ cursor: encodeWorksCursor(account, { q: 1, t: lost.at! }), limit: 3 }) + expect(page.gap).toEqual({ reason: "expired", since: lost.at! }) + const first = [...page.events.map((event) => event.external_id), ...(page.refused ?? []).map((entry) => entry.external_id)].sort() + expect(first).toEqual(kept.slice(0, 3).map((line) => `${line.workId}:${line.seq}`).sort()) + expect(page.more).toBe(true) + // The gap is answered once: the page its cursor names carries none. + expect((await list({ cursor: page.cursor })).gap).toBeUndefined() + }) + + test("a window that starts before the oldest kept event says the history before it is gone", async () => { + const page = await list({ since: "2026-11-15T00:00:00Z", limit: 1 }) + expect(page.gap).toEqual({ reason: "expired", since: "2026-11-15T00:00:00.000Z" }) + // A window inside what the log keeps has no gap. + expect((await list({ since: kept[0]!.at })).gap).toBeUndefined() + }) + + test("the ledger failing to read answers UNAVAILABLE with a next step", async () => { + const failing = fixtureDeps(fixture.log, FIXTURE, { ledger: { eventsSince: async () => Promise.reject(boxdError("LEDGER_FAILED")) } }) + const error = await refusalOf(listWorks(failing, {})) + expect(error.code).toBe("UNAVAILABLE") + expect(error.message).toMatch(/^UNAVAILABLE: .*LEDGER_FAILED.*\. Next step: Run \/boxd-status/) + }) + + test("while the v0 import runs, or after it failed, it answers UNAVAILABLE and never reads the ledger or starts the import", async () => { + let reads = 0 + const counting = { eventsSince: async () => (reads++, { events: [], cursor: 0, cursorExpired: false }) } + const importing = fixtureDeps(fixture.log, FIXTURE, { ledger: counting, importV0: { state: () => ({ state: "importing", done: 2, total: 5 }) } }) + const busy = await refusalOf(listWorks(importing, {})) + expect(busy.code).toBe("UNAVAILABLE") + expect(busy.message).toContain("still importing the works of opencode-boxd v0 (2 of 5 works)") + const failed = fixtureDeps(fixture.log, FIXTURE, { ledger: counting, importV0: { state: () => ({ state: "failed", reason: "listing failed", retryAt: FIXTURE.now }) } }) + expect(await code(listWorks(failed, {}))).toBe("UNAVAILABLE") + // The import's own LEDGER_IMPORTING, raised by the ledger's gate, is the same answer. + const gated = fixtureDeps(fixture.log, FIXTURE, { ledger: { eventsSince: async () => Promise.reject(boxdError("LEDGER_IMPORTING")) } }) + expect(await code(listWorks(gated, {}))).toBe("UNAVAILABLE") + expect(reads).toBe(0) + }) + + test("reads while another process holds the event log's lock: a read takes no lock", async () => { + const lock = await acquireLock(join(fixture.log.file, "..", "events.lock"), { purpose: "events" }) + try { + expect(lock).not.toBeNull() + expect((await list({ since: kept[0]!.at })).events.length).toBeGreaterThan(0) + } finally { + await lock?.release() + } + }) + + test("events are oldest first even when the clock went back between two appends; the cursor still covers both", async () => { + const lines: WorkEvent[] = [ + { seq: 1, at: "2026-11-17T10:00:00.000Z", workId: "late-clock", from: null, to: "creating" }, + { seq: 2, at: "2026-11-17T09:59:00.000Z", workId: "late-clock", from: "creating", to: "starting" }, + ] + const skewed = fixtureDeps(fixture.log, FIXTURE, { ledger: { eventsSince: async (cursor) => ({ events: lines.filter((line) => line.seq > cursor), cursor: 2, cursorExpired: false }) } }) + const page = (await listWorks(skewed, { since: "2026-11-17T00:00:00Z" })) as EventsListResult + expect(page.events.map((event) => event.external_id)).toEqual(["late-clock:2", "late-clock:1"]) + expect(((await listWorks(skewed, { cursor: page.cursor })) as EventsListResult).events).toEqual([]) + }) + + test("refuses another computer's account, a source it does not have, a scope and a malformed cursor", async () => { + expect(await code(list({ account: "other-mac" }))).toBe("ACCOUNT_MISMATCH") + expect(await code(list({ source: "machines" }))).toBe("SOURCE_UNKNOWN") + expect(await code(list({ scope: { works: ["fix-auth"] } }))).toBe("INPUT_INVALID") + expect(await code(list({ cursor: "not-a-cursor" }))).toBe("CURSOR_INVALID") + expect(await code(list({ cursor: encodeWorksCursor("other-mac", { q: 1, t: FIXTURE.now }) }))).toBe("CURSOR_INVALID") + }) +}) + +describe("an event", () => { + test("is the plugin's own words: the work, its phase, how a run ended, its code and who slept it; no text, actors or link", () => { + const at = "2026-11-17T09:00:00.000Z" + const event = (fields: Partial): WorkEvent => ({ seq: 7, at, workId: "fix-auth", from: "busy", to: "idle", ...fields }) + expect(titleOf(event({ outcome: "completed" }))).toBe("Work fix-auth: its run completed") + expect(titleOf(event({ outcome: "failed", code: "RUN_FAILED" }))).toBe("Work fix-auth: its run failed (RUN_FAILED)") + expect(titleOf(event({ to: "asleep", asleepBy: "boxd_sleep" }))).toBe("Work fix-auth: its machine is put to sleep by boxd_sleep") + expect(titleOf(event({ to: "busy", needsInput: "permission" }))).toBe("Work fix-auth: it is running a prompt, waiting for a permission answer") + expect(titleOf(event({ from: null, to: "creating" }))).toBe("Work fix-auth: its machine is being created") + const normalised = eventOf(event({ outcome: "failed", code: "RUN_FAILED", reading: { residentGiB: 1.5, load1: 0.4 } }), account) + expect(normalised).toMatchObject({ + source: "works", + account, + external_id: "fix-auth:7", + kind: "x-boxd/work", + occurred_at: at, + thread: "boxd-work:fix-auth", + actors: [], + text: "", + url: null, + labels: ["phase:idle", "outcome:failed", "code:RUN_FAILED"], + }) + }) + + test("whose title holds a secret is refused for good, and the cursor moves past it", async () => { + const page = await list({ since: kept[0]!.at }) + expect((page.refused ?? []).map((entry) => entry.reason)).toEqual(kept.filter((line) => line.workId === KEY_SHAPED).map(() => "secret")) + expect(page.events.some((event) => event.title.includes(KEY_SHAPED))).toBe(false) + }) +}) + +describe("probe", () => { + test("names this computer and its OS user and reads nothing; another account is ACCOUNT_MISMATCH", () => { + expect(probeWorks(deps, { source: "works" })).toEqual({ source: "works", account, owner, trust: "untrusted" }) + expect(owner).toEqual({ id: "os-user:sam@studio-mac", label: "sam on studio-mac" }) + expect(() => probeWorks(deps, { account: "other-mac" })).toThrow(/^ACCOUNT_MISMATCH: /) + expect(() => probeWorks(deps, { source: "machines" })).toThrow(/^SOURCE_UNKNOWN: /) + }) +}) + +describe("the tools RPC methods", () => { + test("are two reads that each assert their own action with the call's source before answering", async () => { + const asserted: Record[] = [] + const methods = sourceMethods(deps, async (request) => void asserted.push(request as never)) + expect(methods.map((method) => [method.name, method.class, method.action])).toEqual([ + ["events_list", "read", "boxd_events_list"], + ["probe", "read", "boxd_probe"], + ]) + await methods[0]!.run({ since: kept[0]!.at }, call()) + await methods[1]!.run({}, call()) + expect(asserted).toEqual([ + { sessionID: "ses_conformance", agent: "build", action: "boxd_events_list", resources: ["*"], source: { type: "tool", messageID: "msg_conformance", id: "call_conformance" } }, + { sessionID: "ses_conformance", agent: "build", action: "boxd_probe", resources: ["*"], source: { type: "tool", messageID: "msg_conformance", id: "call_conformance" } }, + ]) + }) +}) diff --git a/test/unit/tools-rpc.test.ts b/test/unit/tools-rpc.test.ts index 713ab8e..5b5616a 100644 --- a/test/unit/tools-rpc.test.ts +++ b/test/unit/tools-rpc.test.ts @@ -1,5 +1,5 @@ -// Unit tests for the shared tools RPC module v2, against narrow fakes of the public plugin context. -// A copy in a plugin repository changes only the two imports: its test runner, and the path of its copy. +// The family's shared tools RPC suite (v2), against narrow fakes of the public plugin context, run on the source +// contract's bundled transport with boxd's plugin value: the module is the package's, and the block is src/tools-rpc.ts. import { describe, expect, test } from "bun:test" import { BoxdError } from "../../src/errors.js" import { tmpdir } from "node:os" @@ -7,20 +7,14 @@ import { join } from "node:path" import { CLASSES, hidden, - METHODS, - NEXT_STEPS, - PLUGIN_ID, - pluginError, registerToolsRpc, - shapeInput, - shapeResult, - TOOLS_RPC_ID, upstreamText, type MethodSpec, type PluginMethod, type ToolCall, type ToolsRpcOptions, -} from "../../src/host/tools-rpc.js" +} from "@we-the-rebel-alliance/source-contract/tools-rpc" +import { METHODS, NEXT_STEPS, PLUGIN, PLUGIN_ID, pluginError, shapeInput, shapeResult, TOOLS_RPC_ID } from "../../src/tools-rpc.js" type Effect = "allow" | "deny" | "ask" type Rule = { action: string; resource: string; effect: Effect } @@ -203,6 +197,7 @@ async function setup(options: Setup = {}): Promise { // Read by destructuring, the idiom the module uses: no dotted access from the options object for a forbidden scan to match. const { shapers, mcp: withMcp = true, server = SERVER, managed = true, unavailableDetail, notRegistered } = options const stop = await registerToolsRpc(ctx as never, { + plugin: PLUGIN, methods, ...(shapers === undefined ? {} : { shapers }), ...(withMcp === false From 610060290b9ae64d5f31ba8b18c50ae8673d8127 Mon Sep 17 00:00:00 2001 From: joe-broadhead <91376460+joe-broadhead@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:46:25 +0100 Subject: [PATCH 2/5] fix(sources): bound every page, refusals included, so a burst always drains A page is now one pass over the log in order, each line an event or a refusal, stopped before maxBytes: a burst of works whose titles are refused could otherwise carry more than maxBytes of refusals. Tests for the three ways a source has gone wrong before: no sliding gap after an expired cursor, no jam on a burst larger than a page, and a gap answered once across many small pages. --- src/sources.ts | 38 +++++++++++-------- test/unit/sources.test.ts | 78 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 16 deletions(-) diff --git a/src/sources.ts b/src/sources.ts index 45e3019..9e17eeb 100644 --- a/src/sources.ts +++ b/src/sources.ts @@ -30,7 +30,6 @@ import { PROBE, SourceError, eventsListResult, - fitPage, makeEvent, oldestFirst, parseEventsListInput, @@ -43,6 +42,7 @@ import { type EventsListResult, type EventsOwner, type ProbeResult, + type RefusedEvent, type SourceEvent, } from "@we-the-rebel-alliance/source-contract/events" import type { JsonSchema, PluginMethod, ToolCall } from "@we-the-rebel-alliance/source-contract/tools-rpc" @@ -66,6 +66,8 @@ export const EVENTS_ACTION = `${NAMESPACE}_${EVENTS_LIST}` export const PROBE_ACTION = `${NAMESPACE}_${PROBE}` /** The most bytes of JSON one page holds: the descriptor's `maxBytes`. */ export const MAX_BYTES = 65_536 +/** What a page's envelope takes beside its events and refusals: the source, account, owner, cursor, gap and the rest. */ +const PAGE_ENVELOPE_BYTES = 2_048 /** Whose ledger this is: the computer it is on, and the OS user who runs OpenCode there. */ export interface LocalIdentity { @@ -282,23 +284,27 @@ export async function listWorks(deps: SourceDeps, input: unknown, call?: Pick windowStart) gap = { reason: "expired", since: start } } - // The page: at most `limit` lines in log order, as many as fit in MAX_BYTES once screened. - const candidates = lines.slice(0, request.limit) - const built = candidates.map((line) => ({ line, event: eventOf(line, identity.account) })) - const screened = screenEvents(built.map((entry) => entry.event)) - const refusedIds = new Set(screened.refused.map((entry) => entry.external_id)) - const refusedBytes = screened.refused.reduce((sum, entry) => sum + Buffer.byteLength(JSON.stringify(entry)) + 1, 0) - const fit = fitPage(screened.events, request.limit, MAX_BYTES - refusedBytes) - const lastKept = screened.events[fit - 1] - // The page covers every line up to the last kept event that fits, or every candidate when none was cut. - const cutAt = fit < screened.events.length && lastKept ? built.findIndex((entry) => entry.event.external_id === lastKept.external_id) + 1 : built.length - const covered = built.slice(0, cutAt) - const events = oldestFirst(covered.filter((entry) => !refusedIds.has(entry.event.external_id)).map((entry) => entry.event)) - const refused = screened.refused.filter((entry) => covered.some((item) => item.event.external_id === entry.external_id)) - const last = covered[covered.length - 1]?.line + // The page: at most `limit` lines in log order, each an event or a refusal, as many as fit in MAX_BYTES. Every page + // that has a line covers at least one, so a burst larger than a page drains, page by page, and the cursor always moves. + let bytes = PAGE_ENVELOPE_BYTES + const kept: SourceEvent[] = [] + const refused: RefusedEvent[] = [] + let last: WorkEvent | undefined + let covered = 0 + for (const line of lines.slice(0, request.limit)) { + const screened = screenEvents([eventOf(line, identity.account)]) + const size = Buffer.byteLength(JSON.stringify(screened.events[0] ?? screened.refused[0])) + 1 + if (last !== undefined && bytes + size > MAX_BYTES) break + bytes += size + kept.push(...screened.events) + refused.push(...screened.refused) + last = line + covered++ + } + const events = oldestFirst(kept) // With nothing listed, the cursor is the log's newest sequence number: every line before the window is skipped. const state: CursorState = last ? { q: last.seq, t: last.at } : { q: page.cursor, t: start } - const more = lines.length > covered.length + const more = lines.length > covered const whose: EventsListIdentity = { source: SOURCE, account: identity.account, owner: identity.owner } return eventsListResult(whose, events, encodeWorksCursor(identity.account, state), more, { refused, diff --git a/test/unit/sources.test.ts b/test/unit/sources.test.ts index 847437a..9cf3abd 100644 --- a/test/unit/sources.test.ts +++ b/test/unit/sources.test.ts @@ -180,6 +180,84 @@ describe("events_list", () => { }) }) +/** + * An event log in memory with `EventLog.since`'s rules: the kept lines after a cursor, and `cursorExpired` for a cursor + * older than the oldest kept line or newer than the newest. `drop` lines are lost from the start, as a rotation loses them. + */ +function memoryLog(lines: readonly WorkEvent[], drop = 0) { + const kept = lines.slice(drop) + return { + eventsSince: async (since: number) => { + const newest = kept.length ? kept[kept.length - 1]!.seq : 0 + const oldest = kept.length ? kept[0]!.seq : newest + 1 + const expired = since > newest || since < oldest - 1 + const events = expired ? kept : kept.filter((line) => line.seq > since) + return { events, cursor: events.length ? events[events.length - 1]!.seq : expired ? newest : since, cursorExpired: expired } + }, + } +} + +/** Every page of a read, from its first input, following each cursor until more is false. */ +async function walk(read: (input: Record) => Promise, first: Record, limit?: number) { + const pages: EventsListResult[] = [] + let page = await read({ ...first, ...(limit ? { limit } : {}) }) + pages.push(page) + for (let guard = 0; page.more && guard < 1_000; guard++) { + page = await read({ cursor: page.cursor, ...(limit ? { limit } : {}) }) + pages.push(page) + } + return pages +} + +const listed = (pages: readonly EventsListResult[]) => pages.flatMap((page) => [...page.events.map((event) => event.external_id), ...(page.refused ?? []).map((entry) => entry.external_id)]) + +describe("the three ways a source has gone wrong before", () => { + const BURST_AT = "2026-11-17T10:00:00.000Z" + /** A 170-work fleet changing at once, three times: 510 lines at the same instant. */ + const burst: WorkEvent[] = Array.from({ length: 510 }, (_, index) => ({ seq: index + 1, at: BURST_AT, workId: `fleet-${String(index % 170).padStart(3, "0")}`, from: "busy", to: "idle", outcome: "completed" })) + + test("(a) no sliding gap: an expired cursor restarts from the gap line it carries, whatever the clock says", async () => { + const lost = "2026-11-16T07:00:00.000Z" + const cursor = encodeWorksCursor(account, { q: 3, t: lost }) + const log = memoryLog(burst.slice(0, 40), 10) + const at = (now: string) => (input: Record) => listWorks(fixtureDeps(fixture.log, FIXTURE, { ledger: log, now: () => new Date(now) }), input) as Promise + const early = await walk(at("2026-11-17T12:00:00Z"), { cursor }, 7) + const late = await walk(at("2026-12-25T12:00:00Z"), { cursor }, 7) + for (const pages of [early, late]) { + expect(pages[0]!.gap).toEqual({ reason: "expired", since: lost }) + expect(listed(pages)).toEqual(burst.slice(10, 40).map((line) => `${line.workId}:${line.seq}`)) + } + expect(late.map((page) => page.cursor)).toEqual(early.map((page) => page.cursor)) + }) + + test("(b) no jam: a burst larger than a page drains, page by page, with nothing repeated or skipped, and each page within maxBytes", async () => { + const read = (input: Record) => listWorks(fixtureDeps(fixture.log, FIXTURE, { ledger: memoryLog(burst) }), input) as Promise + for (const limit of [undefined, 1, 500]) { + const pages = await walk(read, { since: "2026-11-17T00:00:00Z" }, limit) + expect(listed(pages)).toEqual(burst.map((line) => `${line.workId}:${line.seq}`)) + for (const page of pages) expect(Buffer.byteLength(JSON.stringify(page))).toBeLessThanOrEqual(65_536) + expect(pages.at(-1)!.more).toBe(false) + } + // A burst of works whose ids are shaped like keys: every page is refusals only, and the cursor still moves. + const keyed = burst.map((line, index) => ({ ...line, workId: `sk-proj${String(index).padStart(4, "0")}x7k2m4q8r1t6w` })) + const keyedPages = await walk((input) => listWorks(fixtureDeps(fixture.log, FIXTURE, { ledger: memoryLog(keyed) }), input) as Promise, { since: "2026-11-17T00:00:00Z" }, 500) + expect(keyedPages.length).toBeGreaterThan(1) + expect(keyedPages.every((page) => page.events.length === 0 && Buffer.byteLength(JSON.stringify(page)) <= 65_536)).toBe(true) + expect(listed(keyedPages)).toEqual(keyed.map((line) => `${line.workId}:${line.seq}`)) + }) + + test("(c) a gap is answered once per read, across many small pages, from an expired cursor or an old window", async () => { + const log = memoryLog(burst.slice(0, 30), 12) + const read = (input: Record) => listWorks(fixtureDeps(fixture.log, FIXTURE, { ledger: log }), input) as Promise + for (const first of [{ cursor: encodeWorksCursor(account, { q: 2, t: "2026-11-16T00:00:00.000Z" }) }, { since: "2026-11-16T00:00:00Z" }]) { + const pages = await walk(read, first, 1) + expect(pages.length).toBe(18) + expect(pages.map((page) => page.gap !== undefined)).toEqual(pages.map((_, index) => index === 0)) + expect(listed(pages)).toEqual(burst.slice(12, 30).map((line) => `${line.workId}:${line.seq}`)) + } + }) +}) + describe("an event", () => { test("is the plugin's own words: the work, its phase, how a run ended, its code and who slept it; no text, actors or link", () => { const at = "2026-11-17T09:00:00.000Z" From ffe42cd8baa764b399cfdb993a5c6770449bea3c Mon Sep 17 00:00:00 2001 From: joe-broadhead <91376460+joe-broadhead@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:46:27 +0100 Subject: [PATCH 3/5] fix(ledger): read the event log as one consistent pair; build dist/tui.js unminified EventLog.since read events.1.jsonl and then events.jsonl with no lock, so a rotation between the two reads could leave the moved events in neither: a cursor inside them jumped past them with no gap, or the read looked like an expired cursor. The pair is now read again while it is not one contiguous run of sequence numbers, while the rotated file changes during the read, or while events.jsonl is missing beside it; after five tries it is LEDGER_LOCKED, with the cursor held. events_list answers any ledger failure as UNAVAILABLE without a path. boxd_status's cursor reads the same way. Tests: the forced interleaving, and a writer rotating a small log under a lagging reader. The TUI bundle is built in its own esbuild call, unminified: OpenCode rewrites a TUI plugin's host imports by a pattern that needs the space a minified bundle drops. The build fails if dist/tui.js is minified. The server bundle stays minified, names kept. --- AGENTS.md | 4 +- CHANGELOG.md | 10 ++- scripts/build.mjs | 26 +++++--- src/ledger/events.ts | 98 ++++++++++++++++++++++------- src/sources.ts | 16 +++-- test/unit/ledger-race.test.ts | 115 ++++++++++++++++++++++++++++++++++ test/unit/sources.test.ts | 12 ++++ 7 files changed, 240 insertions(+), 41 deletions(-) create mode 100644 test/unit/ledger-race.test.ts diff --git a/AGENTS.md b/AGENTS.md index 716b8e6..ec0ae8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,9 @@ and keeps the transcript on the laptop. It has no MCP server: its twelve tools a a temp folder. - **Ship prebuilt, one file per entry.** `scripts/build.mjs` bundles `src/index.ts` and `src/tui.ts` into the self-contained `dist/index.js` and `dist/tui.js`: no chunks, no relative imports, and only host-provided modules - external. Whitespace and syntax are minified and names are not. `tsc` only typechecks. + external. The server bundle's whitespace and syntax are minified, never its names; the TUI bundle is not minified, + because OpenCode rewrites its host imports only in the unminified form, and the build fails if it is. `tsc` only + typechecks. - **Two folders per work.** The laptop folder is the project or an allowed root; the guest folder is always `/home/boxd/work/`. A laptop path is never sent to the guest. - **Files carry three facts.** A moved file is recorded by name, size and sha256, never content. A laptop path must be diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c1c094..78b57de 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,8 +22,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - The tools RPC is the source contract package's `tools-rpc` module (v0.2.0), bundled into `dist/index.js`, in place of the copied module; boxd's methods, codes and next steps are unchanged. -- The bundles are minified (whitespace and syntax, not names), so the package stays within its size budget with the - contract's modules inside. +- The server bundle, `dist/index.js`, is minified (whitespace and syntax, not names), so the package stays within its + size budget with the contract's modules inside. The TUI bundle is not, so OpenCode can resolve its host imports. + +### Fixed + +- A read of the ledger's event log that raced the log's rotation could skip the events the rotation moved, with no + `gap`, or read as an expired cursor. The two files are now read as one consistent pair, read again while a rotation + is under way; `boxd_status`'s cursor reads the same way. ## [0.1.0] - 2026-11-16 diff --git a/scripts/build.mjs b/scripts/build.mjs index 879eeee..6633814 100644 --- a/scripts/build.mjs +++ b/scripts/build.mjs @@ -2,9 +2,11 @@ // src/tui.ts to dist/tui.js (the terminal UI part). Shared code, such as the status model and the RPC contract, is // inlined into both. No chunks and no relative imports, because OpenCode reloads a plugin in place and reuses the // module records it already holds for unchanged paths: a new entry must never import an older sibling module. -// Only the modules the host provides stay external. The build fails if an output imports anything else. Whitespace and -// syntax are minified, names are not: the source contract's modules bundled into dist/index.js keep the package within -// its size budget, and a stack trace still names each function. +// Only the modules the host provides stay external. The build fails if an output imports anything else. The server +// part, dist/index.js, is minified (whitespace and syntax, not names): with the source contract's modules bundled into +// it the package stays within its size budget, and a stack trace still names each function. The TUI part, dist/tui.js, +// is not: OpenCode rewrites a TUI plugin's host imports (`from "solid-js"`) by a pattern that needs the space a minified +// bundle drops, so the build fails if dist/tui.js is minified. import { build } from "esbuild" import { readdirSync, readFileSync, rmSync } from "node:fs" import { join } from "node:path" @@ -25,10 +27,14 @@ const version = { }, } +// A minified bundle writes its imports without spaces (`import{a}from"x"`, `import*as b from"y"`). The TUI part must keep +// them plain. The family's guard is /\bfrom"|\bimport[{*]/; its bare `from"` also matches the string "from" (an input +// field of boxd_exec's schema), so here it is anchored on the `}` a minified import list closes with. +const MINIFIED_IMPORT = /\}from"|\bimport[{*]/ + rmSync(join(root, "dist"), { recursive: true, force: true }) -const result = await build({ +const common = { absWorkingDir: root, - entryPoints: { index: "src/index.ts", tui: "src/tui.ts" }, outdir: "dist", bundle: true, splitting: false, @@ -37,18 +43,20 @@ const result = await build({ target: "es2023", external: HOST, legalComments: "none", - minifyWhitespace: true, - minifySyntax: true, metafile: true, logLevel: "warning", plugins: [version], -}) +} +const server = await build({ ...common, entryPoints: { index: "src/index.ts" }, minifyWhitespace: true, minifySyntax: true }) +const tui = await build({ ...common, entryPoints: { tui: "src/tui.ts" } }) +const outputs = { ...server.metafile.outputs, ...tui.metafile.outputs } -const problems = Object.entries(result.metafile.outputs).flatMap(([file, output]) => +const problems = Object.entries(outputs).flatMap(([file, output]) => output.imports.filter((entry) => !entry.external || !provided(entry.path)).map((entry) => `${file} imports ${entry.path}`), ) const files = readdirSync(join(root, "dist")).sort() if (JSON.stringify(files) !== JSON.stringify(["index.js", "tui.js"])) problems.push(`dist/ must hold exactly index.js and tui.js, found ${files.join(", ")}`) +else if (MINIFIED_IMPORT.test(readFileSync(join(root, "dist", "tui.js"), "utf8"))) problems.push("dist/tui.js is minified: OpenCode cannot rewrite its host imports, so bundle the TUI part unminified") if (problems.length) { console.error(`build: the bundles are not self-contained:\n ${problems.join("\n ")}`) process.exit(1) diff --git a/src/ledger/events.ts b/src/ledger/events.ts index 2b2ac7c..f7d15b1 100644 --- a/src/ledger/events.ts +++ b/src/ledger/events.ts @@ -91,14 +91,62 @@ export class EventLog { * newer. When `since` is older than the oldest kept event, `cursorExpired` is true and the events start at the oldest * kept one. A cursor newer than the log (another ledger's) is expired too: sequence numbers are never reused, so it can * only come from somewhere else. + * + * The two files are read as one consistent pair, with no lock: a rotation that lands between the two reads (a rename, + * then a fresh `events.jsonl`) would otherwise leave the moved events in neither, and a cursor inside them would jump + * past them unseen. Sequence numbers are contiguous across the two files (a line cut off by a crash gives its number + * to the next writer), so the pair is read again when the rotated file's last number is not one before the current + * file's first, when the rotated file changed while either file was read, or when `events.jsonl` is missing beside a + * rotated file (the moment between the rename and the next append). After `SINCE_TRIES` reads that are not a consistent pair it + * throws `LEDGER_LOCKED`: the caller tries again, and its cursor has not moved. */ async since(since: number): Promise { - const kept = [...(await readLines(this.rotated)), ...(await readLines(this.file))] - const newest = kept.length ? kept[kept.length - 1]!.seq : 0 - const oldest = kept.length ? kept[0]!.seq : newest + 1 - const expired = since > newest || since < oldest - 1 - const events = expired ? kept : kept.filter((line) => line.seq > since) - return { cursor: events.length ? events[events.length - 1]!.seq : expired ? newest : since, events, cursorExpired: expired } + for (let attempt = 0; attempt < SINCE_TRIES; attempt++) { + if (attempt > 0) await sleep(SINCE_PAUSE_MS * attempt) + const kept = await this.consistentPair() + if (kept === undefined) continue + const newest = kept.length ? kept[kept.length - 1]!.seq : 0 + const oldest = kept.length ? kept[0]!.seq : newest + 1 + const expired = since > newest || since < oldest - 1 + const events = expired ? kept : kept.filter((line) => line.seq > since) + return { cursor: events.length ? events[events.length - 1]!.seq : expired ? newest : since, events, cursorExpired: expired } + } + throw boxdError("LEDGER_LOCKED", "The event log was rotating each time it was read, so no consistent page could be read; nothing was skipped.") + } + + /** Both files' lines as one consistent run of sequence numbers, or undefined when a rotation raced the read. */ + private async consistentPair(): Promise { + const before = await identity(this.rotated) + const rotated = (await readLines(this.rotated)) ?? [] + const after = await identity(this.rotated) + if (before?.ino !== after?.ino || before?.size !== after?.size) return undefined + const current = await readLines(this.file) + // A rename after the rotated file was read (the first rotation, when there was none) leaves `events.jsonl` missing + // or new: the rotated file is checked once more. + const final = await identity(this.rotated) + if (after?.ino !== final?.ino || after?.size !== final?.size) return undefined + if (current === undefined) return after === undefined ? rotated : undefined + const last = rotated[rotated.length - 1] + const first = current[0] + if (last !== undefined && first !== undefined && last.seq + 1 !== first.seq) return undefined + return [...rotated, ...current] + } +} + +/** How often `since` reads the two files before it gives up on a consistent pair, and the pause that grows between. */ +const SINCE_TRIES = 5 +const SINCE_PAUSE_MS = 20 + +const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) + +/** A file's inode and size, or undefined when it does not exist. */ +async function identity(path: string): Promise<{ ino: number; size: number } | undefined> { + try { + const { ino, size } = await stat(path) + return { ino, size } + } catch (error) { + if (errnoOf(error) === "ENOENT") return undefined + throw error } } @@ -149,28 +197,30 @@ const parseSeq = (text: string): number | undefined => { } } -/** Every complete, parseable line of one file; a line cut off by a crash is skipped. Streamed, never read whole. */ -async function readLines(path: string): Promise { - try { - await stat(path) - } catch (error) { - if (errnoOf(error) === "ENOENT") return [] - throw error - } +/** + * Every complete, parseable line of one file, or undefined when it does not exist (also when it is renamed away before + * the read opens it); a line cut off by a crash is skipped. Streamed, never read whole. + */ +async function readLines(path: string): Promise { const lines: EventLine[] = [] let rest = "" - for await (const chunk of createReadStream(path, { encoding: "utf8", highWaterMark: 256 * 1024 })) { - const parts = (rest + (chunk as string)).split("\n") - rest = parts.pop() ?? "" - for (const part of parts) { - if (!part) continue - try { - const parsed = JSON.parse(part) as EventLine - if (typeof parsed.seq === "number" && typeof parsed.workId === "string" && typeof parsed.to === "string") lines.push(parsed) - } catch { - // a line cut off by a crash, fenced by the next writer's newline + try { + for await (const chunk of createReadStream(path, { encoding: "utf8", highWaterMark: 256 * 1024 })) { + const parts = (rest + (chunk as string)).split("\n") + rest = parts.pop() ?? "" + for (const part of parts) { + if (!part) continue + try { + const parsed = JSON.parse(part) as EventLine + if (typeof parsed.seq === "number" && typeof parsed.workId === "string" && typeof parsed.to === "string") lines.push(parsed) + } catch { + // a line cut off by a crash, fenced by the next writer's newline + } } } + } catch (error) { + if (errnoOf(error) === "ENOENT") return undefined + throw error } return lines } diff --git a/src/sources.ts b/src/sources.ts index 9e17eeb..7fc0091 100644 --- a/src/sources.ts +++ b/src/sources.ts @@ -160,13 +160,19 @@ function notReadable(state: ReturnType): SourceError | un }) } -/** A ledger refusal as the contract's table names it. */ -function ledgerFailure(error: unknown): unknown { - if (!(error instanceof BoxdError)) return error - if (error.code === "LEDGER_IMPORTING" || error.code === "IMPORT_V0_FAILED") { +/** + * A ledger failure as the contract's table names it: always `UNAVAILABLE`, with the ledger's code when it has one and + * never a path. The cursor is not moved: the same call again reads on from it. + */ +function ledgerFailure(error: unknown): SourceError { + if (error instanceof BoxdError && (error.code === "LEDGER_IMPORTING" || error.code === "IMPORT_V0_FAILED")) { return new SourceError({ code: "UNAVAILABLE", what: `boxd's ledger is not readable yet (${error.code})`, next: "Call events_list again in a minute, with the same cursor." }) } - return new SourceError({ code: "UNAVAILABLE", what: `boxd's event log could not be read (${error.code})`, next: "Run /boxd-status and follow its next step, then call events_list again." }) + if (error instanceof BoxdError && error.state === "busy") { + return new SourceError({ code: "UNAVAILABLE", what: `boxd's event log was busy (${error.code})`, next: "Call events_list again in a few seconds, with the same cursor." }) + } + const code = error instanceof BoxdError ? error.code : "the file system refused the read" + return new SourceError({ code: "UNAVAILABLE", what: `boxd's event log could not be read (${code})`, next: "Run /boxd-status and follow its next step, then call events_list again." }) } const OUTCOME_WORDS: Readonly> = { diff --git a/test/unit/ledger-race.test.ts b/test/unit/ledger-race.test.ts new file mode 100644 index 0000000..5c14ca4 --- /dev/null +++ b/test/unit/ledger-race.test.ts @@ -0,0 +1,115 @@ +// A read of the event log racing a rotation (`EventLog.since`): the reads of `events.1.jsonl` and `events.jsonl` must be +// one consistent pair, or a cursor inside the moved events jumps past them unseen. First the interleaving a review found, +// forced: the rotation lands right after the rotated file is read. Then the same race unforced: a writer rotating a small +// log while a reader pages behind it, checked for holes, repeats, spurious gaps and uncoded errors. +import { expect, mock, test } from "bun:test" +import * as realFs from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import type { EventsListResult } from "@we-the-rebel-alliance/source-contract/events" +import type { ImportState } from "../../src/ports.js" + +let armed: undefined | (() => void) +const realCreate = realFs.createReadStream +mock.module("node:fs", () => ({ + ...realFs, + createReadStream: (path: string, options: unknown) => { + const stream = realCreate(path, options as never) + if (!String(path).endsWith("events.1.jsonl") || !armed) return stream + const after = armed + armed = undefined + const iterate = stream[Symbol.asyncIterator].bind(stream) + ;(stream as unknown as Record)[Symbol.asyncIterator] = async function* () { + for await (const chunk of { [Symbol.asyncIterator]: iterate }) yield chunk + after() // the writer's rotation lands right after the reader finished the rotated file + } + return stream + }, +})) + +const { EventLog } = await import("../../src/ledger/events.js") +const { encodeWorksCursor, identityOf, listWorks } = await import("../../src/sources.js") +const COMPLETE: ImportState = { state: "complete", works: 0, blocked: [] } +const identity = identityOf("sam", "studio-mac") +const temp = (prefix: string) => realFs.mkdtempSync(join(realFs.realpathSync(tmpdir()), prefix)) +const depsOf = (log: InstanceType, now = () => new Date("2026-11-17T12:00:00.000Z")) => ({ + ledger: { eventsSince: (q: number) => log.since(q) }, + importV0: { state: () => COMPLETE }, + identity: () => identity, + now, +}) + +test("a read that a rotation lands in lists the moved events: no hole, no gap", async () => { + const dir = temp("boxd-race-") + try { + const line = (seq: number) => `${JSON.stringify({ seq, at: "2026-11-17T10:00:00.000Z", workId: "w", from: "idle", to: "busy" })}\n` + // As a log looks after one rotation: the rotated file holds 1..10, events.jsonl 11..20. + realFs.writeFileSync(join(dir, "events.1.jsonl"), Array.from({ length: 10 }, (_, i) => line(i + 1)).join("")) + realFs.writeFileSync(join(dir, "events.jsonl"), Array.from({ length: 10 }, (_, i) => line(i + 11)).join("")) + const deps = depsOf(new EventLog(dir)) + // A reader that has listed up to seq 12, behind the head, as a periodic collector is. + const cursor = encodeWorksCursor(identity.account, { q: 12, t: "2026-11-17T10:00:00.000Z" }) + armed = () => { + // What EventLog.append does at the rotation size: rename, then append seq 21 to a fresh events.jsonl. + realFs.renameSync(join(dir, "events.jsonl"), join(dir, "events.1.jsonl")) + realFs.appendFileSync(join(dir, "events.jsonl"), line(21)) + } + const page = (await listWorks(deps, { cursor })) as EventsListResult + expect(armed).toBeUndefined() + expect(page.gap).toBeUndefined() + expect(page.events.map((event) => event.external_id)).toEqual(Array.from({ length: 9 }, (_, i) => `w:${i + 13}`)) + const next = (await listWorks(deps, { cursor: page.cursor })) as EventsListResult + expect(next.events).toEqual([]) + expect(next.gap).toBeUndefined() + } finally { + realFs.rmSync(dir, { recursive: true, force: true }) + } +}) + +test("a log rotating under a reader that pages behind it: no hole, no repeat, no spurious gap, only UNAVAILABLE to retry", async () => { + const problems: string[] = [] + for (let trial = 0; trial < 8; trial++) { + const dir = temp("boxd-race-stress-") + try { + let clock = Date.parse("2026-11-17T10:00:00.000Z") + const log = new EventLog(dir, { rotateBytes: 4000, now: () => new Date(clock++) }) + const deps = depsOf(log, () => new Date(clock)) + for (let i = 0; i < 5; i++) await log.append({ workId: "w", from: null, to: "busy" }) + let cursor = ((await listWorks(deps, { since: "2026-11-17T00:00:00Z" })) as EventsListResult).cursor + let head = 5 + let writing = true + const writer = (async () => { + for (let i = 0; i < 200; i++) await log.append({ workId: "w", from: "idle", to: "busy" }) + writing = false + })() + for (let reads = 0; writing || reads === 0; reads++) { + let page: EventsListResult + try { + page = (await listWorks(deps, { cursor, limit: 500 })) as EventsListResult + } catch (error) { + const { code, message } = error as { code?: string; message: string } + // The one retryable answer: the cursor is held, so the next read loses nothing. + if (code !== "UNAVAILABLE" || message.includes(dir)) problems.push(`trial ${trial}: ${message}`) + continue + } + const seqs = page.events.map((event) => Number(event.external_id.split(":")[1])) + // Nothing was lost while the reader kept up, so a gap that lists nothing is a spurious one. + if (page.gap !== undefined && seqs.length === 0) problems.push(`trial ${trial}: a gap that lists nothing after ${head}`) + if (seqs.length > 0) { + if (seqs[0]! > head + 1 && page.gap === undefined) problems.push(`trial ${trial}: a hole with no gap after ${head}: ${seqs[0]}`) + if (seqs[0]! <= head) problems.push(`trial ${trial}: a repeat${page.gap ? " with a spurious gap" : ""} after ${head}: ${seqs[0]}`) + head = Math.max(head, seqs[seqs.length - 1]!) + } + cursor = page.cursor + } + await writer + // Whatever the reader saw while racing, it reads on to the head with nothing skipped. + const rest = (await listWorks(deps, { cursor, limit: 500 })) as EventsListResult + const last = rest.events.length ? Number(rest.events.at(-1)!.external_id.split(":")[1]) : head + if (last !== 205) problems.push(`trial ${trial}: the read ended at ${last}, not 205`) + } finally { + realFs.rmSync(dir, { recursive: true, force: true }) + } + } + expect(problems).toEqual([]) +}, 300_000) diff --git a/test/unit/sources.test.ts b/test/unit/sources.test.ts index 9cf3abd..2e36280 100644 --- a/test/unit/sources.test.ts +++ b/test/unit/sources.test.ts @@ -135,6 +135,18 @@ describe("events_list", () => { expect(error.message).toMatch(/^UNAVAILABLE: .*LEDGER_FAILED.*\. Next step: Run \/boxd-status/) }) + test("an uncoded file-system error, or a log busy rotating, is UNAVAILABLE, never the ledger's path", async () => { + const path = join(fixture.log.file, "..", "events.jsonl") + const enoent = Object.assign(new Error(`ENOENT: no such file or directory, open '${path}'`), { code: "ENOENT" }) + const missing = await refusalOf(listWorks(fixtureDeps(fixture.log, FIXTURE, { ledger: { eventsSince: async () => Promise.reject(enoent) } }), {})) + expect(missing.code).toBe("UNAVAILABLE") + expect(missing.message).not.toContain(path) + expect(missing.message).not.toContain("ENOENT") + const busy = await refusalOf(listWorks(fixtureDeps(fixture.log, FIXTURE, { ledger: { eventsSince: async () => Promise.reject(boxdError("LEDGER_LOCKED")) } }), {})) + expect(busy.code).toBe("UNAVAILABLE") + expect(busy.message).toContain("Next step: Call events_list again in a few seconds, with the same cursor.") + }) + test("while the v0 import runs, or after it failed, it answers UNAVAILABLE and never reads the ledger or starts the import", async () => { let reads = 0 const counting = { eventsSince: async () => (reads++, { events: [], cursor: 0, cursorExpired: false }) } From 291a820cde3991072f2c40ccc35a893ea55037cb Mon Sep 17 00:00:00 2001 From: joe-broadhead <91376460+joe-broadhead@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:46:30 +0100 Subject: [PATCH 4/5] chore(release): prepare v0.1.1 Version 0.1.1 in package.json and the lockfile, the CHANGELOG's Unreleased section released as 0.1.1 with the tested OpenCode releases, and every install spec at #v0.1.1; the upgrade example removes #v0.1.0. --- CHANGELOG.md | 3 ++- CONTRIBUTING.md | 4 ++-- README.md | 12 ++++++------ docs/configuration.md | 2 +- package-lock.json | 4 ++-- package.json | 2 +- test/unit/docs.test.ts | 2 +- 7 files changed, 15 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 78b57de..7f26214 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ All notable changes to this project are documented here. The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.1.1] - 2026-11-17 ### Added @@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- The host range is unchanged: `>=2.2.3 <2.4.0`, tested on 2.2.3, 2.2.4, 2.2.5, 2.2.6, 2.2.7 and 2.3.0. - The tools RPC is the source contract package's `tools-rpc` module (v0.2.0), bundled into `dist/index.js`, in place of the copied module; boxd's methods, codes and next steps are unchanged. - The server bundle, `dist/index.js`, is minified (whitespace and syntax, not names), so the package stays within its diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f078bc..1965129 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ Only for development. Install the package into an OpenCode project from the fold { "plugins": ["./opencode-boxd"] } ``` -A published install is `opencode plugin add github:joe-broadhead/opencode-boxd#v0.1.0`. +A published install is `opencode plugin add github:joe-broadhead/opencode-boxd#v0.1.1`. ## Rules @@ -168,5 +168,5 @@ Each release has its own tag, and a Git install does not update by itself. To mo Or add the plugin to `opencode.json` instead, with the same spec: ```json -{ "plugins": [{ "package": "github:joe-broadhead/opencode-boxd#v0.1.0" }] } +{ "plugins": [{ "package": "github:joe-broadhead/opencode-boxd#v0.1.1" }] } ``` diff --git a/README.md b/README.md index b235c24..71d3df9 100644 --- a/README.md +++ b/README.md @@ -19,19 +19,19 @@ boxd is a trademark of Azin Tech Operating Company B.V.; this unofficial plugin ## Install ```sh -opencode plugin add github:joe-broadhead/opencode-boxd#v0.1.0 +opencode plugin add github:joe-broadhead/opencode-boxd#v0.1.1 ``` Run `opencode reload`, or restart OpenCode, then run `/boxd-status`. Each release has its own tag, and a Git install does not update by itself. To move to a newer release, remove the old -entry with `opencode plugin remove github:joe-broadhead/opencode-boxd#v0.0.6`, then add the new tag with +entry with `opencode plugin remove github:joe-broadhead/opencode-boxd#v0.1.0`, then add the new tag with `opencode plugin add github:joe-broadhead/opencode-boxd#v`. Or add the plugin to `opencode.json` instead, with the same spec: ```json -{ "plugins": [{ "package": "github:joe-broadhead/opencode-boxd#v0.1.0" }] } +{ "plugins": [{ "package": "github:joe-broadhead/opencode-boxd#v0.1.1" }] } ``` The install takes the GitHub release tag. Its commit carries the built `dist/`, so the install runs no build. @@ -61,7 +61,7 @@ The first start imports the earlier ledger, `~/.local/share/opencode-boxd/works/ Going back is safe only before this release's first change (a submit, harvest, drop or reassign): after that, the old drop could accept a stale record and destroy unharvested work. To go back, run -`opencode plugin remove github:joe-broadhead/opencode-boxd#v0.1.0`, then +`opencode plugin remove github:joe-broadhead/opencode-boxd#v0.1.1`, then `opencode plugin add github:joe-broadhead/opencode-boxd#v0.0.6`, and keep only the options it knows (`snapshot`, `allowUntestedHost`, `allowedRoots`, `access`). It reads `works/` as it was before the upgrade and sees nothing this release did; the machines this release created keep billing until you destroy them. `v1/` stays, and upgrading again @@ -225,7 +225,7 @@ The region choice, the CI reserve and the image recipe are the policies worth se // /Library/Application Support/opencode/opencode.json on macOS { "plugins": [{ - "package": "github:joe-broadhead/opencode-boxd#v0.1.0", + "package": "github:joe-broadhead/opencode-boxd#v0.1.1", "options": { "region": "auto", "keepFree": { "fra": 20, "nyc": 0 }, "size": "2x8" } }] } @@ -360,7 +360,7 @@ and notices, health, tools, agents without the default rules, the OpenCode versi ## Uninstall ```sh -opencode plugin remove github:joe-broadhead/opencode-boxd#v0.1.0 +opencode plugin remove github:joe-broadhead/opencode-boxd#v0.1.1 ``` The ledger is yours to keep or delete. Machines are boxd's: `boxd machine remove oc- -y` destroys one. diff --git a/docs/configuration.md b/docs/configuration.md index 2c51ee5..8f0d06f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -7,7 +7,7 @@ All options go in the plugin entry in `opencode.json`, and every one is optional ```jsonc { "plugins": [{ - "package": "github:joe-broadhead/opencode-boxd#v0.1.0", + "package": "github:joe-broadhead/opencode-boxd#v0.1.1", "options": { "region": "auto", "size": "2x8", "notices": "wake" } }] } diff --git a/package-lock.json b/package-lock.json index f23c6f9..570d364 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@joe-broadhead/opencode-boxd", - "version": "0.1.0", + "version": "0.1.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@joe-broadhead/opencode-boxd", - "version": "0.1.0", + "version": "0.1.1", "license": "MIT", "devDependencies": { "@opencode/client": "2.2.3", diff --git a/package.json b/package.json index 09c2bef..23b602b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@joe-broadhead/opencode-boxd", - "version": "0.1.0", + "version": "0.1.1", "private": true, "description": "Unofficial OpenCode plugin for boxd: run a session on a private boxd machine and keep the transcript on your laptop", "keywords": [ diff --git a/test/unit/docs.test.ts b/test/unit/docs.test.ts index 1ab0fb0..b53368d 100644 --- a/test/unit/docs.test.ts +++ b/test/unit/docs.test.ts @@ -84,7 +84,7 @@ describe("the README", () => { }) test("installs from the GitHub release tag, not from a checkout or the registry", () => { - expect(README).toContain("opencode plugin add github:joe-broadhead/opencode-boxd#v0.1.0") + expect(README).toContain("opencode plugin add github:joe-broadhead/opencode-boxd#v0.1.1") expect(README).not.toMatch(/plugins.*\.\/opencode-boxd/) expect(README).not.toMatch(/npm run build/) }) From 2971ff1d0dfbaa307e3c703febc59b2a58be2db8 Mon Sep 17 00:00:00 2001 From: joe-broadhead <91376460+joe-broadhead@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:11:34 +0100 Subject: [PATCH 5/5] =?UTF-8?q?chore(release):=20kit=20r4.2=20=E2=80=94=20?= =?UTF-8?q?macos-26-intel=20no=20longer=20required?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/ci.yml | 4 ++-- CONTRIBUTING.md | 3 ++- scripts/check-copies.mjs | 2 +- scripts/release-kit.test.mjs | 18 ++++++++++++++++-- 4 files changed, 21 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f9334c5..94d025c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,9 +41,9 @@ jobs: strategy: fail-fast: false matrix: - # A pull request runs the two Linux runners; a push to master, or a run by hand, runs all four, macOS too. macOS + # A pull request runs the two Linux runners; a push to master, or a run by hand, runs three: macOS arm64 too. macOS # runs on master and for releases only, and the release planner requires that push run with every runner. - os: ${{ fromJSON(github.event_name == 'pull_request' && '["ubuntu-24.04","ubuntu-24.04-arm"]' || '["ubuntu-24.04","ubuntu-24.04-arm","macos-26","macos-26-intel"]') }} + os: ${{ fromJSON(github.event_name == 'pull_request' && '["ubuntu-24.04","ubuntu-24.04-arm"]' || '["ubuntu-24.04","ubuntu-24.04-arm","macos-26"]') }} runs-on: ${{ matrix.os }} timeout-minutes: 60 steps: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1965129..7a01d2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,7 +55,8 @@ a `## [x.y.z] - YYYY-MM-DD` heading below it, newest first, and the npm history `node scripts/changelog.mjs release`: it turns `## [Unreleased]` into `## [] - `, above the earlier releases, and refuses a CHANGELOG it cannot shape. Run `npm run check`. 2. Push that commit to `master`, and wait for CI to pass on it. A pull request's CI runs the Linux runners only; the - push to `master` runs every runner, macOS too, and the release stands on that run. + push to `master` runs every runner, Apple-silicon macOS (`macos-26`) too, and the release stands on that run. An + Intel Mac (`macos-26-intel`) is not required. 3. Start the release with that commit's full sha: `gh workflow run release.yml --ref master -f sha=`, or from Actions → release → Run workflow, on `master`. diff --git a/scripts/check-copies.mjs b/scripts/check-copies.mjs index 5aa5c6d..a0dbcf1 100644 --- a/scripts/check-copies.mjs +++ b/scripts/check-copies.mjs @@ -25,7 +25,7 @@ const COPIES = [ { path: "scripts/publish-release.mjs", optional: false, sha256: "9615e2eaab236a8ba01c133be87a2428d17a5612716a4df05c788ff1be7668a1", part: (text) => text }, { path: "scripts/release-commit.mjs", optional: false, sha256: "fb08f19a3bf659eeff960944fa4eb53b4cf74f94c4e12e123c2d104185667f44", part: (text) => text }, { path: "scripts/release-github.mjs", optional: false, sha256: "44b7c768be3fb0e8f0f42f17a47c582df873ae9cf4074449d588692a2b9e2de7", part: (text) => text }, - { path: "scripts/release-kit.test.mjs", optional: false, sha256: "821db1681c7e912db03476da4dd7ef06e68495f7b8afff8112f4448ee0f17ecd", part: (text) => text }, + { path: "scripts/release-kit.test.mjs", optional: false, sha256: "57ef690684bbe020913db40611c089565513194ef57ac5e30ff7116e6569c411", part: (text) => text }, { path: "scripts/release-pack.mjs", optional: false, sha256: "47400eb783dbdcb710efa7073619ac577c044434681113daf782271538cf8e22", part: (text) => text }, { path: "scripts/release-rules.mjs", optional: false, sha256: "7a9f985fe5ccb3c1c30c6727d6390329b07fdb30d25bf8de5838dcbb36883c63", part: (text) => text }, { path: "scripts/release-version.mjs", optional: false, sha256: "24c2b5f9caca6f381cbadd069178a4c3522c09a8f7a6acb06ce1b347f1c4994b", part: (text) => text }, diff --git a/scripts/release-kit.test.mjs b/scripts/release-kit.test.mjs index a7eb192..62589a2 100644 --- a/scripts/release-kit.test.mjs +++ b/scripts/release-kit.test.mjs @@ -899,7 +899,10 @@ describe("check-release-shape.mjs: releases move forward from the last published }) /** A plugin's source, as the release workflow sees it: a build, TESTED_HOSTS, and, when native, native.yml. */ -/** The four runners every plugin's CI has, and a ci.yml whose matrix runs macOS on a push to master only. */ +/** + * Four runners a ci.yml may name, and a ci.yml whose matrix runs macOS on a push to master only. The family's push set is + * the first three (both Linux runners and Apple-silicon macOS, kit r4.2); an Intel Mac, when a ci.yml names one, must pass too. + */ const RUNNERS = ["ubuntu-24.04", "ubuntu-24.04-arm", "macos-26", "macos-26-intel"] const gatedLine = (key, pr, all) => ` ${key}: \${{ fromJSON(github.event_name == 'pull_request' && '${JSON.stringify(pr)}' || '${JSON.stringify(all)}') }}` const ciYml = (matrixLine) => `name: CI\non:\n pull_request:\n push:\n branches: [master]\njobs:\n check:\n strategy:\n matrix:\n${matrixLine}\n runs-on: \${{ matrix.os }}\n steps:\n - run: npm run check\n` @@ -1107,6 +1110,17 @@ describe("release-github.mjs plan", () => { assert.throws(() => run(), /no ci\.yml run for a push to master/) }) + test("stands on a push run of the family's three runners, with no Intel Mac, and still requires Apple-silicon macOS", () => { + const repo = repository({ ...pluginSource("0.0.1"), ".github/workflows/ci.yml": ciYml(gatedLine("os", RUNNERS.slice(0, 2), RUNNERS.slice(0, 3))) }) + const github = fakeGitHub(repo) + github.state.ciRuns = [ciRun(repo.head)] + github.state.ciJobs = fullJobs(RUNNERS.slice(0, 3)) + const run = () => plan({ sha: repo.head, env: ENV(repo), gh: github.gh, cwd: repo.dir }) + assert.equal(run().ci_run, "501") + github.state.ciJobs = [...fullJobs(RUNNERS.slice(0, 2)), ...fullJobs(["macos-26-intel"])] + assert.throws(run, /CI run 501 on [0-9a-f]{12} is not a full master push run: no successful job on macos-26$/) + }) + test("refuses a ci.yml whose matrix runs macOS on pull requests, or not on master", () => { for (const [line, problem] of [ [" os: [ubuntu-24.04, ubuntu-24.04-arm, macos-26, macos-26-intel]", /names a macOS runner outside the matrix gated by event/], @@ -1964,7 +1978,7 @@ describe("CI: macOS on pushes to master and for releases, never on pull requests const matrix = ciMatrix(readFileSync(join(SCRIPTS, "..", ".github", "workflows", "ci.yml"), "utf8")) assert.deepEqual(matrix.problems, []) assert.equal(matrix.pullRequest.some((runner) => /^macos-/.test(runner)), false) - assert.ok(matrix.push.includes("macos-26") && matrix.push.includes("macos-26-intel"), `a push to master runs ${matrix.push.join(", ")}`) + assert.ok(matrix.push.includes("macos-26"), `a push to master runs ${matrix.push.join(", ")}`) }) })