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/.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..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. `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 @@ -62,12 +64,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 +106,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..7f26214 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,35 @@ 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). +## [0.1.1] - 2026-11-17 + +### 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 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 + 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 ### Breaking diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f078bc..7a01d2a 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 @@ -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`. @@ -168,5 +169,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 2499fbf..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 @@ -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. @@ -214,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" } }] } @@ -349,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/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..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" } }] } @@ -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..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", @@ -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..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": [ @@ -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..6633814 100644 --- a/scripts/build.mjs +++ b/scripts/build.mjs @@ -2,7 +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. +// 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" @@ -23,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, @@ -38,13 +46,17 @@ const result = await build({ 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/scripts/check-copies.mjs b/scripts/check-copies.mjs index 2c7d7f0..a0dbcf1 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). @@ -29,20 +25,13 @@ 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 }, { 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/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(", ")}`) }) }) 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/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/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..7fc0091 --- /dev/null +++ b/src/sources.ts @@ -0,0 +1,399 @@ +/** + * 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, + makeEvent, + oldestFirst, + parseEventsListInput, + parseProbeInput, + probeResult, + screenEvents, + startTime, + type EventsGap, + type EventsListIdentity, + 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" +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 +/** 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 { + /** 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 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." }) + } + 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> = { + 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, 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 + 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..b53368d 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. */ @@ -81,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/) }) @@ -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/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/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..2e36280 --- /dev/null +++ b/test/unit/sources.test.ts @@ -0,0 +1,328 @@ +// 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("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 }) } + 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") + }) +}) + +/** + * 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" + 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