Skip to content

feat(sources): boxd.works - #31

Merged
joe-broadhead merged 5 commits into
masterfrom
feat/sources
Nov 17, 2026
Merged

joe-broadhead merged 5 commits into
masterfrom
feat/sources

Conversation

@joe-broadhead

@joe-broadhead joe-broadhead commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Adds the boxd.works source under the source contract (pinned to source-contract#v0.2.0).

What it does

  • events_list: lists each phase change of this laptop's works as one event, oldest first. It reads only the ledger's events.jsonl, through LedgerPort.eventsSince. It makes no boxd CLI or network call, never wakes a machine and takes no lock (the log is append-only).
  • An event: external_id <work id>:<seq>, kind x-boxd/work, occurred_at (the line's at), thread boxd-work:<work id>. The title is the plugin's own sentence, for example Work fix-auth: its run failed (RUN_FAILED). labels are phase:, outcome:, code:, asleep-by: and needs:. There is no text, no actors and no url. No prompt, transcript, work title or guest text reaches an event. A title that holds a secret (a work id shaped like a key) is refused with reason: "secret".
  • Cursor: the log's own seq, bound to plugin, source and account, plus the time it covered. The ledger's cursorExpired (the log rotated, or the cursor came from another ledger) answers the oldest kept events with gap: { reason: "expired", since }, once. A first read whose window starts before the oldest kept event says the same.
  • probe: reads nothing. The account is this computer (a host-name slug) and the owner its OS user, os-user:<user>@<computer>.
  • During the v0 import (LEDGER_IMPORTING), or after it failed, events_list answers UNAVAILABLE with the progress. It never joins the import gate, because a failed import's retry would list machines with the boxd CLI. A ledger read failure is also UNAVAILABLE.
  • Methods: both are tools RPC methods (boxd_events_list, boxd_probe), not model tools. The default rules allow them at every access value.

Also in this PR

  • Tools RPC: it now comes from the package's tools-rpc (bundled), replacing the src/host/tools-rpc.ts copy. boxd's plugin value is src/tools-rpc.ts. The family's shared suites run unchanged against it.

  • npm run conformance writes reports/conformance-report.json with ok: true. Nine checks run, including gap-and-cursor-expired and gap-once-per-read, which run against a real rotated EventLog. failed-holds-cursor is not applicable, through atomicPages: a page is one read of the local log. The report has no noExpiry.

  • Descriptor: it uses permission.rules (boxd_events_list on *), because there is no provider operation. It declares no key that 0.1.x consumers refuse: no identityRules, identity: [], readsIdentity, accounts.server, removals[] or verified.

  • Bundles: the server bundle is now minified (whitespace and syntax only, names kept), so the contract code fits the budget. The packed size is 181,053 B, against a 196,608 B budget (master: 185,842 B). The TUI bundle stays unminified, and the build fails if it is minified, because OpenCode rewrites its host imports. The pack and forbidden checks now read minified output.

  • Paging: a page is one byte-bounded pass over the log, in which every line is an event or a refusal. A burst bigger than a page (a 170-work fleet changing at once) drains, and the cursor always moves. Tests cover the sliding gap, the jam and gap-once-per-read across many small pages.

  • Last commit: chore(release): prepare v0.1.1 (version, lockfile, CHANGELOG released as 0.1.1 with the tested hosts, install specs at #v0.1.1, and the upgrade example removing #v0.1.0).

npm run check passes locally on every stage, on the final head: host tests on six SDKs, and pack tests on every stock binary.

After review: EventLog.since now reads events.1.jsonl and events.jsonl as one consistent pair (contiguous sequence numbers, a stable rotated file, no missing events.jsonl). It tries again, then answers LEDGER_LOCKED/UNAVAILABLE with the cursor held. That closes a silent loss when a read races a rotation, and boxd_status gets the fix too. Regression tests cover the forced interleaving and an unforced stress.

The boxd.works source under the source contract (v0.2.0): events_list lists
each phase change of this laptop's works from the ledger's events.jsonl
through LedgerPort.eventsSince (no boxd call, no machine woken, no lock), in
the plugin's own words, with the log's sequence number as the bound cursor and
cursorExpired as gap: { reason: "expired" }; probe names this computer and
its OS user. Both are tools RPC methods, allowed at every access value.

The tools RPC is now the contract package's tools-rpc module, bundled into
dist/index.js, in place of the copy. npm run conformance runs the kit and
writes reports/conformance-report.json (ok). The bundles are minified
(whitespace and syntax, not names) to stay within the 192 KiB pack budget.
…drains

A page is now one pass over the log in order, each line an event or a refusal, stopped before maxBytes: a burst of
works whose titles are refused could otherwise carry more than maxBytes of refusals. Tests for the three ways a source
has gone wrong before: no sliding gap after an expired cursor, no jam on a burst larger than a page, and a gap answered
once across many small pages.
…i.js unminified

EventLog.since read events.1.jsonl and then events.jsonl with no lock, so a rotation between the two reads could leave
the moved events in neither: a cursor inside them jumped past them with no gap, or the read looked like an expired
cursor. The pair is now read again while it is not one contiguous run of sequence numbers, while the rotated file
changes during the read, or while events.jsonl is missing beside it; after five tries it is LEDGER_LOCKED, with the
cursor held. events_list answers any ledger failure as UNAVAILABLE without a path. boxd_status's cursor reads the same
way. Tests: the forced interleaving, and a writer rotating a small log under a lagging reader.

The TUI bundle is built in its own esbuild call, unminified: OpenCode rewrites a TUI plugin's host imports by a
pattern that needs the space a minified bundle drops. The build fails if dist/tui.js is minified. The server bundle
stays minified, names kept.
Version 0.1.1 in package.json and the lockfile, the CHANGELOG's Unreleased section released as 0.1.1 with the tested
OpenCode releases, and every install spec at #v0.1.1; the upgrade example removes #v0.1.0.
@joe-broadhead
joe-broadhead merged commit 4da0847 into master Nov 17, 2026
3 checks passed
@joe-broadhead
joe-broadhead deleted the feat/sources branch November 17, 2026 22:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant