Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ dist/
*.tsbuildinfo
*.tgz
.DS_Store
reports/
24 changes: 16 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<work id>`. 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down
29 changes: 29 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:<user>@<computer>`). 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
Expand Down
7 changes: 4 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 `## [<version>] - <today>`, 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=<full sha>`, or from Actions → release →
Run workflow, on `master`.
Expand Down Expand Up @@ -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" }] }
```
25 changes: 18 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<version>`.

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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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" },
Expand All @@ -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.

Expand Down Expand Up @@ -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" }
}]
}
Expand Down Expand Up @@ -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-<work id> -y` destroys one.
Expand Down
13 changes: 10 additions & 3 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
9 changes: 8 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
}]
}
Expand Down Expand Up @@ -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):

Expand All @@ -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" },
Expand All @@ -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" },
Expand All @@ -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" },
Expand Down
4 changes: 4 additions & 0 deletions docs/jelly.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading
Loading