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
11 changes: 11 additions & 0 deletions .changeset/slim-board-overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
"@shivaedev/work-board": minor
---

### Fixed

- `@shivaedev/work-board`: The Claude Code pane and its overview tool read the Board again on a board with much finished work. The overview answer had grown past the 4 MiB Claude Code reads of a plugin's answer, so the pane showed "The Work Board sent no answer to work-board.overview." It now carries only what the pane and the overview tools show, which keeps it small however much finished work the board keeps.

### Breaking

- `@shivaedev/work-board`: `work-board.overview` no longer returns `goals.items` or the ready Fleet's `completed` list. Read `work-board.goals` for the items and `work-board.fleetItems` for completed Fleet work.
2 changes: 1 addition & 1 deletion packages/work-board-plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The plugin needs a running Work Board. It finds one by walking up from the sessi
npx @shivaedev/work-board .work
```

Without a `.work` folder, the pane and every tool say the session's folder has no Work Board and how to start one; with a Board that is not running, they say so and name the start command. Claude Code waits 30 seconds for each Board answer; a Board still working after that is reported as busy, not stopped, and the next refresh asks again. The band stays hidden until the Board answers. Pressing a Needs you item opens it with `open -g` at the URL the Board says it is served on, so opening items works on macOS.
Without a `.work` folder, the pane and every tool say the session's folder has no Work Board and how to start one; with a Board that is not running, they say so and name the start command. Claude Code waits 30 seconds for each Board answer; a Board still working after that is reported as busy, not stopped, and the next refresh asks again. Claude Code also reads at most 4 MiB of each answer; an answer cut off there is reported as broken off at that limit, not as no answer. The band stays hidden until the Board answers. Pressing a Needs you item opens it with `open -g` at the URL the Board says it is served on, so opening items works on macOS.

The plugin only reads the Board. Answer decisions in the Board itself or through [`@shivaedev/work-board`](../work-board/README.md).

Expand Down
5 changes: 5 additions & 0 deletions packages/work-board-plugin/src/adapters/hostProtocol.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@ const exchange = Effect.fn("WorkboardPlugin.exchange")(function* (
catch: (cause) => defect(cause instanceof Error ? cause.message : String(cause), cause),
try: () => post(body),
});
if (text !== "" && !text.endsWith("\n")) {
return yield* defect(
`The Work Board's answer to ${request.tag} breaks off mid-message after ${text.length} characters. Claude Code reads at most 4 MiB of an answer.`,
);
}
const responses = yield* Effect.try({
catch: (cause) => defect("The Work Board answered with an unreadable RPC stream.", cause),
try: () => parser.decode(text).filter(isServerMessage),
Expand Down
2 changes: 1 addition & 1 deletion packages/work-board/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -432,7 +432,7 @@ Call this function with a revision whose source/context you have reviewed and a

`client.api.goals.query()` returns `{ closedGoals, deferredGoals, goals, items }`. Goals are uniquely identified goal documents grouped by authored status, with standing homes kept active. `items` holds identified implementing documents with source metadata and open-ask context; answer records are excluded. Each goal has authored fields, `criteria`, `asks`, `openAsks`, task `counts`, `linked` and `unlinked`, plus `lanes` containing each implementing goal and its own task counts. Counts use `done`, `running`, `blocked`, `scheduled` and `parked`, count each task once through child goals, and exclude dropped tasks. Each criterion includes its task counts and the number of recorded evidence claims targeting it. Started Fleet work stays running until done or released, including turns waiting for an answer, CI or merge; work blocked before it starts counts as blocked. Fleet replies without execution details use their working or reviewing stage. Approved work that has not started counts as scheduled; draft, deferred, held and manual work stays parked. Mounted queries refresh when indexed source changes. [Read a goal](docs/reading.md#read-a-goal) describes the goal page that renders this query.

`client.api.overview.query()` returns `{ fleet, goals }` from one Board index and one Fleet read. The pane and overview tools use this snapshot so In flight and goal running counts agree. An unreachable Fleet returns an explicit unavailable state.
`client.api.overview.query()` returns `{ fleet, goals }` from one Board index and one Fleet read. The pane and overview tools use this snapshot so In flight and goal running counts agree. `goals` holds the three goal lists without `items`, and a ready `fleet` holds `items` and `areas` without `completed`, so the answer stays within the 4 MiB Claude Code reads of a plugin's answer however much finished work the board keeps; `goals` and `fleetItems` return those. An unreachable Fleet returns an explicit unavailable state.

For a handoff, first read the preview with `client.run(client.handoffs.handoffSource.run({ item: "work.search" }))` and inspect its `context`. This complete program takes that reviewed path and revision as inputs:

Expand Down
10 changes: 8 additions & 2 deletions packages/work-board/src/browser/views/OverviewProjection.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
import { Schema } from "effect";
import { Schema, Struct } from "effect";
import { FleetItemsProjection } from "./FleetItemsProjection.ts";
import { GoalsProjection } from "./GoalsProjection.ts";

export const OverviewProjection = Schema.Struct({ fleet: FleetItemsProjection, goals: GoalsProjection });
// Claude Code reads at most 4 MiB of a plugin's answer, so the overview leaves out the finished history that grows
// with the board: every item's record and Fleet's completed work.
const [ReadyFleet, UnavailableFleet] = FleetItemsProjection.members;
export const OverviewProjection = Schema.Struct({
fleet: Schema.Union([ReadyFleet.mapFields(Struct.omit(["completed"])), UnavailableFleet]),
goals: GoalsProjection.mapFields(Struct.omit(["items"])),
});
20 changes: 14 additions & 6 deletions packages/work-board/src/server/document/deliveredId.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ const SHOWN = Array.from({ length: 30 }, (_, index) => `fleet.shown-${index}`);
const fleetItem = { attentionOwner: "automation" as const, stage: "working" as const, stageEnteredAt: 100, updatedAt: 200 };

boardStory.it(
"the overview checks all thirty shown briefs with Fleet in one request and hides the one Fleet refuses",
"the Fleet work view checks all thirty shown briefs with Fleet in one request and hides the one Fleet refuses",
[
projectFiles({
...Object.fromEntries(SHOWN.map((id, index) => [`tasks/${index}.md`, `---\nid: ${id}\nkind: task\nstatus: ready\n---\n# Shown ${index}\n`])),
Expand All @@ -54,10 +54,18 @@ boardStory.it(
},
),
],
function* ({ fleetBriefRequests, overviewFleet }) {
const overview = yield* overviewFleet();

expect(overview).toEqual({ completed: ["fleet.delivered"], shown: SHOWN.slice(1) });
expect(yield* fleetBriefRequests()).toEqual([SHOWN.map((id, index) => `${id} at tasks/${index}.md`)]);
function* ({ fleetBriefRequests, fleetWork }) {
yield* outcomes([
[
"Fleet work",
() => fleetWork(),
expect.objectContaining({
completed: [expect.objectContaining({ workId: "fleet.delivered" })],
items: SHOWN.slice(1).map((workId) => expect.objectContaining({ workId })),
state: "ready",
}),
],
["briefs asked about", () => fleetBriefRequests(), [SHOWN.map((id, index) => `${id} at tasks/${index}.md`)]],
]);
},
);
48 changes: 48 additions & 0 deletions packages/work-board/src/server/rpc/pluginReadLimit.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import { expect } from "vitest";
import { boardStory, projectFiles } from "#test/boardStory.ts";

const NOTE = "n".repeat(512 * 1024);
const FINISHED = Array.from({ length: 9 }, (_, index) => index);

boardStory.it(
"the plugin reads goal progress from a board whose finished tasks hold more than Claude Code reads of one answer",
[
projectFiles({
"goal.md": "---\nid: goal.ship\nkind: goal\nstatus: ready\n---\n# Ship the Board",
...Object.fromEntries(
FINISHED.map((index) => [
`done/${index}.md`,
`---\nid: task.done-${index}\nkind: task\nstatus: done\nnext_action: ${NOTE}\nrelationships:\n - kind: implements\n target: goal.ship\n---\n# Finished ${index}\n`,
]),
),
}),
],
function* ({ openPlugin, pluginProgress }) {
yield* openPlugin();

expect(yield* pluginProgress()).toBe("9 of 9 done");
},
);

const CRITERION = "c".repeat(1536 * 1024);

boardStory.it(
"the plugin says the Board's answer broke off at Claude Code's read limit instead of saying it sent none",
[
projectFiles(
Object.fromEntries(
[1, 2, 3].map((index) => [
`goal-${index}.md`,
`---\nid: goal.wide-${index}\nkind: goal\nstatus: ready\ncriteria:\n - id: wide\n text: ${CRITERION}\n---\n# Wide goal ${index}\n`,
]),
),
),
],
function* ({ openPlugin, pluginProblem }) {
yield* openPlugin();

expect(yield* pluginProblem()).toBe(
"The Work Board's answer to work-board.overview breaks off mid-message after 4194304 characters. Claude Code reads at most 4 MiB of an answer.",
);
},
);
43 changes: 31 additions & 12 deletions packages/work-board/src/test-support/socketVerbs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ import { type BoardEngine, connected, served } from "#test/storyEngine.ts";

type WorkboardBoard = ReturnType<typeof readSnapshot>;

const HOST_READ_BYTES = 4 * 1024 * 1024;

export interface SocketObservations {
readonly connections: string[];
}
Expand All @@ -33,9 +35,17 @@ export function socketVerbs(engine: BoardEngine, tell: (line: string) => void) {
}
function boardSocket(body: string) {
return socketExchange(join(engine.notes.root, "board.sock"), rpcPost(engine.notes.root, body)).then((reply) =>
reply.ok ? reply.text : Promise.reject(new Error(`The board refused the plugin's request (${reply.status})`)),
reply.ok
? new TextDecoder().decode(new TextEncoder().encode(reply.text).subarray(0, HOST_READ_BYTES))
: Promise.reject(new Error(`The board refused the plugin's request (${reply.status})`)),
);
}
function opened() {
if (plugin === undefined) {
throw new Error("The plugin is not open; call openPlugin first");
}
return plugin;
}
return {
followDocument: (url: string) =>
Effect.gen(function* () {
Expand All @@ -53,24 +63,33 @@ export function socketVerbs(engine: BoardEngine, tell: (line: string) => void) {
Effect.gen(function* () {
const clock = yield* Clock.Clock;
const { platformClient } = yield* bundledClient();
tell("the Claude plugin opens its shipped client, which posts each request over board.sock as the host's fetch does");
tell(
"the Claude plugin opens its shipped client, which posts each request over board.sock and reads at most 4 MiB of each answer, as the host's fetch does",
);
const client = platformClient(engine.notes.root, boardSocket, () => Promise.resolve(clock.currentTimeMillisUnsafe()));
plugin = client;
return client;
}),
(client) => Effect.sync(client.close),
),
pluginProgress: () => {
tell("the plugin reads the board, as its Refresh button and timer do, and shows its goal progress");
const client = plugin;
if (client === undefined) {
return Effect.die(new Error("The plugin is not open; call openPlugin first"));
}
return Effect.map(
Effect.promise(() => client.board()),
pluginProblem: () =>
Effect.promise(() => {
tell("the plugin reads the board, as its Refresh button and timer do, and shows why it could not");
return opened()
.board()
.then(
() => "the board answered",
(error: unknown) => (error instanceof Error ? error.message : String(error)),
);
}),
pluginProgress: () =>
Effect.map(
Effect.promise(() => {
tell("the plugin reads the board, as its Refresh button and timer do, and shows its goal progress");
return opened().board();
}),
progressOf,
);
},
),
socketsOpened: () =>
Effect.sync(() => {
tell("the reader lists the sockets the page and the node clients opened");
Expand Down
10 changes: 0 additions & 10 deletions packages/work-board/src/test-support/workspaceBoardVerbs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -227,15 +227,5 @@ export function workspaceBoardVerbs(engine: BoardEngine, tell: (line: string) =>
return { goals: navigation.counts.goals, inbox: navigation.inboxCount ?? "unknown" };
},
),
overviewFleet: () =>
Effect.map(
rpc((client) => client("work-board.overview", undefined)),
({ fleet }) => {
tell("the reader checks the Fleet work the overview shows");
return fleet.state === "ready"
? { completed: fleet.completed.map((item) => item.workId), shown: fleet.items.map((item) => item.workId) }
: fleet.state;
},
),
};
}
Loading