diff --git a/.changeset/mcp-waits-for-busy-board.md b/.changeset/mcp-waits-for-busy-board.md new file mode 100644 index 00000000..50134488 --- /dev/null +++ b/.changeset/mcp-waits-for-busy-board.md @@ -0,0 +1,7 @@ +--- +"@shivaedev/work-board": patch +--- + +### Fixed + +- `work-board mcp` waits 30 seconds for a busy board instead of 10, so a Fleet view that takes most of its 25-second budget no longer reads as a stopped board. A board that does not answer in time is reported as busy, and an unreachable board as not reachable with the command that starts it. diff --git a/packages/work-board/README.md b/packages/work-board/README.md index 9b3527af..544023ca 100644 --- a/packages/work-board/README.md +++ b/packages/work-board/README.md @@ -567,7 +567,9 @@ claude mcp add --transport stdio work-board -- work-board mcp /absolute/path/to/ codex mcp add work-board -- work-board mcp /absolute/path/to/notes ``` -Both commands require `work-board` on the client's PATH. `work-board mcp ` reads the running board through `/board.sock`; it uses the same computed queries as the browser. If no board answers, every tool returns one error naming the directory and the `work-board ` command to start it. +Both commands require `work-board` on the client's PATH. Without a global install, register `pnpm dlx @shivaedev/work-board mcp /absolute/path/to/notes`. Avoid `npx -y @shivaedev/work-board`: npm keeps its first install of the package, refuses to update that copy once a release pins another Effect version, and the server exits before the client connects. + +`work-board mcp ` reads the running board through `/board.sock`; it uses the same computed queries as the browser. The server starts and lists its tools whether or not a board runs, and each tool call reads the board when it runs, so a board that starts later answers the next call. A call waits for a busy board while its Fleet view finishes. If no board answers, the tool returns one error naming the directory and the `work-board ` command to start it. | Tool | Returns | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | diff --git a/packages/work-board/src/server/diagnostics/daemon.ts b/packages/work-board/src/server/diagnostics/daemon.ts index 76eae6cf..4ccb74cc 100644 --- a/packages/work-board/src/server/diagnostics/daemon.ts +++ b/packages/work-board/src/server/diagnostics/daemon.ts @@ -10,8 +10,10 @@ function makeDaemonClient() { type DaemonClient = Effect.Success>; const FLEET_STOPPED = "Fleet isn't running, so agent work and its health are unknown."; -// A busy Fleet took up to 15 seconds for one read in measurement. +// A busy Fleet took up to 15 seconds for one read in measurement. Both reads of the Fleet view share one budget, +// so the Board answers inside the 30 seconds Claude Code's plugin fetch waits. const FLEET_WAIT_SECONDS = 20; +export const FLEET_VIEW_MS = 25_000; // npx runs the project's own @shivaedev/work-fleet, because the bare work-fleet command is rarely on PATH. export function daemonUnavailable(error: unknown, port: number, folder: string): { readonly reason: string; readonly startCommand?: string } { diff --git a/packages/work-board/src/server/mcp.slow.spec.ts b/packages/work-board/src/server/mcp.slow.spec.ts new file mode 100644 index 00000000..b900f979 --- /dev/null +++ b/packages/work-board/src/server/mcp.slow.spec.ts @@ -0,0 +1,18 @@ +import { expect, vi } from "vitest"; +import { boardStory, projectFiles } from "#test/boardStory.ts"; +import { slowFleetDaemon } from "#test/workspaceBoardTraits.ts"; + +vi.setConfig({ testTimeout: 60_000 }); + +const project = projectFiles({ "one.md": "---\nid: one\nkind: task\nstatus: draft\n---\n# First task" }); +const reported = { completed: [], items: [{ stage: "queued" as const, stageEnteredAt: 100, updatedAt: 200, workId: "one" }] }; + +boardStory.it( + "an agent's board_overview waits for a busy Fleet that answers after 15 seconds", + [project, slowFleetDaemon(reported, 15)], + function* ({ agentReads }) { + expect(yield* agentReads("board_overview")).toMatchObject({ + fleet: { items: [expect.objectContaining({ stage: "queued", workId: "one" })], state: "ready" }, + }); + }, +); diff --git a/packages/work-board/src/server/mcp.spec.ts b/packages/work-board/src/server/mcp.spec.ts index 2b9ecdc8..fe252166 100644 --- a/packages/work-board/src/server/mcp.spec.ts +++ b/packages/work-board/src/server/mcp.spec.ts @@ -22,7 +22,7 @@ const withFleet = [ })), ]; const unavailable = { reason: "Fleet isn't set up for this Board.", state: "unavailable" }; -const NO_BOARD = "error: No board answers in the project folder. Start one with: work-board 'the project folder'"; +const NO_BOARD = "error: The Work Board in the project folder is not reachable. Start it with: work-board 'the project folder'"; boardStory.it("an agent connecting over MCP stdio finds three read-only tools", withFleet, function* ({ agentTools }) { expect(yield* agentTools()).toEqual([ @@ -32,6 +32,18 @@ boardStory.it("an agent connecting over MCP stdio finds three read-only tools", ]); }); +boardStory.it( + "with no board running, an agent connecting over MCP stdio still finds the three tools", + [project, deferredServing], + function* ({ agentTools }) { + expect(yield* agentTools()).toEqual([ + { name: "board_overview", readOnly: true }, + { name: "item", readOnly: true }, + { name: "needs_you", readOnly: true }, + ]); + }, +); + boardStory.it( "board_overview reports the Fleet items, the goal counts and the Needs-you list the browser computes", withFleet, @@ -86,7 +98,7 @@ for (const [tool, args] of [ ["item", { id: "task.first" }], ] as const) { boardStory.it( - `with no board running, ${tool} answers one error that says how to start the board`, + `with no board running, ${tool} answers that the board is not reachable and how to start it`, [project, deferredServing], function* ({ agentReads }) { expect(yield* agentReads(tool, args)).toBe(NO_BOARD); @@ -94,6 +106,18 @@ for (const [tool, args] of [ ); } +boardStory.it( + "an agent that connected before the board started reads the board once it starts", + [project, deferredServing], + function* ({ agentReads, boardStarts }) { + expect(yield* agentReads("board_overview")).toBe(NO_BOARD); + + yield* boardStarts(); + + expect(yield* agentReads("board_overview")).toEqual(expect.objectContaining({ fleet: expect.objectContaining(unavailable) })); + }, +); + boardStory.it( "without Fleet, board_overview and item say Fleet isn't set up instead of failing", [project, boardWithoutFleet], @@ -147,7 +171,7 @@ boardStory.it("item answers an error that names a missing item", [project, board }); boardStory.it( - "after the board stops, an agent's next read says no board answers", + "after the board stops, an agent's next read says the board is not reachable", [project, boardWithoutFleet], function* ({ agentReads, boardStops }) { expect(yield* agentReads("board_overview")).toEqual(expect.objectContaining({ fleet: expect.objectContaining(unavailable) })); diff --git a/packages/work-board/src/server/mcp/client.ts b/packages/work-board/src/server/mcp/client.ts index 99b2ee23..f32d5dd9 100644 --- a/packages/work-board/src/server/mcp/client.ts +++ b/packages/work-board/src/server/mcp/client.ts @@ -1,12 +1,13 @@ import { connect } from "node:net"; import { join } from "node:path"; import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"; -import { Effect, Layer, Schema } from "effect"; +import { Cause, Effect, Layer, Schema } from "effect"; import { HttpClient, HttpClientRequest } from "effect/http"; import { RpcClient, RpcSerialization } from "effect/rpc"; import { RpcClientError } from "effect/rpc/RpcClientError"; import { errorMessage } from "#errorMessage.ts"; import { workContract } from "#rpc/contract.ts"; +import { FLEET_VIEW_MS } from "#server/diagnostics/daemon.ts"; import { RPC_PATH } from "#server/http/rpcPolicy.ts"; export class BoardToolError extends Schema.TaggedError()("BoardToolError", { message: Schema.String }) {} @@ -16,9 +17,19 @@ function makeClient() { } export type BoardClient = Effect.Success>; +// The Board's Fleet view alone may take its whole budget, and the Board's own index and document reads come on top. +const BOARD_WAIT_SECONDS = FLEET_VIEW_MS / 1000 + 5; + function toolError(directory: string, error: unknown) { - if (error instanceof RpcClientError || (error instanceof Error && "_tag" in error && error._tag === "TimeoutError")) { - return new BoardToolError({ message: `No board answers in ${directory}. Start one with: work-board '${directory.replaceAll("'", "'\\''")}'` }); + if (Cause.isTimeoutError(error)) { + return new BoardToolError({ + message: `The Work Board in ${directory} did not answer within ${BOARD_WAIT_SECONDS} seconds. It may be busy; try again.`, + }); + } + if (error instanceof RpcClientError) { + return new BoardToolError({ + message: `The Work Board in ${directory} is not reachable. Start it with: work-board '${directory.replaceAll("'", "'\\''")}'`, + }); } return new BoardToolError({ message: errorMessage(error) }); } @@ -38,7 +49,7 @@ export function readBoard(directory: string, read: (client: BoardClient) = }).pipe(Layer.provide([http, RpcSerialization.layerNdjson])); return Effect.scoped(Effect.flatMap(makeClient(), read)).pipe( Effect.provide(protocol), - Effect.timeout("10 seconds"), + Effect.timeout(`${BOARD_WAIT_SECONDS} seconds`), Effect.mapError((error) => toolError(directory, error)), ); } diff --git a/packages/work-board/src/server/views/fleetItems.ts b/packages/work-board/src/server/views/fleetItems.ts index aa431707..574d5467 100644 --- a/packages/work-board/src/server/views/fleetItems.ts +++ b/packages/work-board/src/server/views/fleetItems.ts @@ -6,7 +6,7 @@ import { laneOf } from "#browser/views/now.ts"; import { DAEMON_PORT } from "#diagnostics/daemonContract.ts"; import { inboxItems } from "#server/attention/inbox.ts"; import { requestInbox } from "#server/attention/requestInbox.ts"; -import { daemonUnavailable, readDaemon } from "#server/diagnostics/daemon.ts"; +import { daemonUnavailable, FLEET_VIEW_MS, readDaemon } from "#server/diagnostics/daemon.ts"; import { fleetChecksBrief } from "#server/document/briefDiagnostic.ts"; import { itemRequests } from "#server/document/requests.ts"; import type { Snapshot } from "#server/search/snapshot.ts"; @@ -39,9 +39,6 @@ const fleetItemsUnavailable = Effect.fn("WorkBoard.fleetItemsUnavailable")(funct return projection; }); -// Both Fleet reads share one budget, so the Board answers inside the 30 seconds Claude Code's plugin fetch waits. -const FLEET_VIEW_MS = 25_000; - export function fleetItems(folder: string, fleetPort: number | null = DAEMON_PORT): Effect.Effect { if (fleetPort === null) { return fleetItemsUnavailable({ reason: "Fleet isn't set up for this Board." }); diff --git a/packages/work-board/src/test-support/mcpClient.ts b/packages/work-board/src/test-support/mcpClient.ts index 9416f003..d7d18f81 100644 --- a/packages/work-board/src/test-support/mcpClient.ts +++ b/packages/work-board/src/test-support/mcpClient.ts @@ -76,7 +76,7 @@ export const mcpClient = Effect.fn("Test.mcpClient")(function* (directory: strin pending.set(id, { reject, resolve }); child.stdin.write(`${JSON.stringify({ id, jsonrpc: "2.0", method, params })}\n`); }), - ).pipe(Effect.timeout("15 seconds")); + ).pipe(Effect.timeout("45 seconds")); } yield* send("initialize", { capabilities: {}, clientInfo: { name: "board-test", version: "1" }, protocolVersion: "2025-11-25" }); child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);