Repository navigation
feat(sources): boxd.works - #31
Merged
Merged
Conversation
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
force-pushed
the
feat/sources
branch
from
November 17, 2026 18:46
f6aea3d to
291a820
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the
boxd.workssource under the source contract (pinned tosource-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'sevents.jsonl, throughLedgerPort.eventsSince. It makes no boxd CLI or network call, never wakes a machine and takes no lock (the log is append-only).external_id<work id>:<seq>,kindx-boxd/work,occurred_at(the line'sat),threadboxd-work:<work id>. Thetitleis the plugin's own sentence, for exampleWork fix-auth: its run failed (RUN_FAILED).labelsarephase:,outcome:,code:,asleep-by:andneeds:. There is notext, noactorsand nourl. 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 withreason: "secret".seq, bound to plugin, source and account, plus the time it covered. The ledger'scursorExpired(the log rotated, or the cursor came from another ledger) answers the oldest kept events withgap: { 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>.LEDGER_IMPORTING), or after it failed,events_listanswersUNAVAILABLEwith 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 alsoUNAVAILABLE.boxd_events_list,boxd_probe), not model tools. The default rules allow them at everyaccessvalue.Also in this PR
Tools RPC: it now comes from the package's
tools-rpc(bundled), replacing thesrc/host/tools-rpc.tscopy. boxd's plugin value issrc/tools-rpc.ts. The family's shared suites run unchanged against it.npm run conformancewritesreports/conformance-report.jsonwithok: true. Nine checks run, includinggap-and-cursor-expiredandgap-once-per-read, which run against a real rotatedEventLog.failed-holds-cursoris not applicable, throughatomicPages: a page is one read of the local log. The report has nonoExpiry.Descriptor: it uses
permission.rules(boxd_events_liston*), because there is no provider operation. It declares no key that 0.1.x consumers refuse: noidentityRules,identity: [],readsIdentity,accounts.server,removals[]orverified.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 checkpasses locally on every stage, on the final head: host tests on six SDKs, and pack tests on every stock binary.After review:
EventLog.sincenow readsevents.1.jsonlandevents.jsonlas one consistent pair (contiguous sequence numbers, a stable rotated file, no missingevents.jsonl). It tries again, then answersLEDGER_LOCKED/UNAVAILABLEwith the cursor held. That closes a silent loss when a read races a rotation, andboxd_statusgets the fix too. Regression tests cover the forced interleaving and an unforced stress.