@opvs-ai/mcp 2.6.1 → 2.7.1

package/README.md

@@ -1,6 +1,6 @@
 # @opvs-ai/mcp
 
-OPVS MCP server for the **on-demand model** — 10 always-on tools that give any MCP host (Claude Desktop, Cursor, Antigravity, Windsurf, Claude Code) the same surface OPVS-hosted agents see. Everything else is reached through `tool_call` indirection so the package fits under the ~100-tool cap every current MCP client enforces.
+OPVS MCP server for the **on-demand model** — 16 tools that give any MCP host (Claude Desktop, Cursor, Antigravity, Windsurf, Claude Code) the same surface OPVS-hosted agents see: 10 always-on marketplace tools, `sandbox_chat` (a vendor test mode), and 5 **fleet** tools for machines and slots. Everything else is reached through `tool_call` indirection so the package fits under the ~100-tool cap every current MCP client enforces.
 
 | Tool | Wraps | Purpose |
 |------|-------|---------|
@@ -13,7 +13,53 @@ OPVS MCP server for the **on-demand model** — 10 always-on tools that give any
 | `tool_install` | `/marketplace/packages/{id}/install` | Add a package with explicit consent |
 | `tool_uninstall` | `DELETE /marketplace/installed/{id}` | Remove a package |
 | `whoami` | `/auth/me` | Session probe — brand, agent, workspace |
-| `board_as_markdown` | `/board/boards/{id}/export?format=md` | A whole AgentBoard as a Markdown plan in one call (`detail` summary/standard/full, `columns` filter) |
+| `board_as_markdown` | `/board/boards/{id}/export?format=md` | A whole AgentBoard as a Markdown plan in one call (`detail` summary/standard/full, `columns` filter). A board over the server's 1 MiB export ceiling is **refused, not truncated** — the refusal carries `actual_bytes`/`limit_bytes`/`retry_with` as fields. It does **not** silently retry at a lower detail: the tool promises these exact bytes, so substituting a different document is the caller's decision |
+
+### Fleet — machines and slots
+
+The environment layer had **no agent-reachable surface at all** until these landed, so
+"dashboard or MCP" was dashboard-only. They are native tools rather than `tool_call` routes
+for the same reason `board_as_markdown` is: there is no marketplace skill for environments,
+so there is no `schema.yaml` to route through.
+
+| Tool | Wraps | Purpose |
+|------|-------|---------|
+| `fleet_list` | `/environments` + `/environments/allowance` | Every slot this brand owns + the machine allowance it spends, grouped by machine. `detail` compact/full |
+| `slot_get` | `/environments/{ref}` → `/workstations/{uuid}` | One slot + its per-step onboarding checklist, and `next_action` — the single step to act on |
+| `slot_health` | `/environments/{ref}/health` | **Live** sidecar probe (reaches the box over WireGuard) |
+| `fleet_logins` | `/environments/credentials/reauth-status` | Lapsed logins on both credential lanes, reported separately |
+| `slot_order` | `POST /workstations` | Order a slot — **writes**: spends the allowance, mints a one-shot install PAT |
+
+#### Vocabulary
+
+At the product surface there are exactly two nouns, and the tool names use them
+([`MACHINE-AND-SLOT.md`](../../docs/planning/opvsRunner/MACHINE-AND-SLOT.md) §3, owner ruling
+2026-09-07):
+
+- **MACHINE** — the physical host. What a tunnel terminates at. Keyed by `machine_id`.
+- **SLOT** — the worker at a desk on it. What a card is claimed by, what a terminal opens into.
+
+**On the wire it is still `environments`**, and that disagreement is deliberate — renaming a
+live table, its router and its TS type buys nothing a reader needs. The words *box* and *desk*
+are retired from new writing but appear throughout the older docs. Every tool description names
+the synonyms, so an agent told "list my environments" or "check my box" still finds the tool.
+
+#### Three things that surprise people
+
+1. **Any ref shape works on `slot_get` and `slot_health`.** Full UUID, an 8-or-more hex prefix,
+   or the `env_…` short code. `slot_get` resolves the ref *first* and then uses the canonical
+   UUID for the checklist hop — because `/workstations/{id}` accepts **only** a UUID and 404s a
+   short code, which would otherwise read as "your slot does not exist".
+2. **A `null` is never a green light.** `allowance: null` is paired with `allowance_error`;
+   `onboarding: null` with `onboarding_error`. Both mean *unknown*, never *fine* — do not tell
+   an operator they have room, or that nothing is outstanding, on the strength of a null.
+3. **`fleet_logins` reports two lanes and never sums them.** `lease` is the build credential
+   (lapsed → builds fall back to metered pricing); `desk` is what the box's terminal opens
+   (lapsed → the desk will not start). A box can be perfect on one and unusable on the other,
+   so a single total could not say which broke. Desk state is four-valued —
+   `healthy | not_applicable | unknown | lapsed` — and "nobody asked OPVS to manage this desk"
+   is a different sentence from "OPVS was asked and cannot vouch for it".
+
 
 All tool names match `^[a-zA-Z0-9_-]+$` (the OpenAI tool-name regex; dots break Lola/Roni/planner on first call).
 
@@ -149,7 +195,7 @@ Every tool returns a single text-content block whose payload is JSON with:
 - **Optional flat sibling `_findings: [...]`** — only when the server emits one (e.g. `audit_level=all`).
 - **`telemetry_signal`** in search results — closed enum: `absent | cold | warm | hot`.
 
-The contract was locked with SpiderIQ on 2026-05-15 PM. See [`docs/planning/Marketplace/architecture/skills-system-reference.md`](../../docs/planning/Marketplace/architecture/skills-system-reference.md#skills-meta) for the gateway-side semantics this MCP mirrors.
+The contract was locked with SpiderIQ on 2026-05-15 PM. See [`docs/planning/Marketplace/CLAUDE.md`](../../docs/planning/Marketplace/CLAUDE.md#architecture) for the gateway-side semantics this MCP mirrors.
 
 ## tool_pin status
 
@@ -175,6 +221,28 @@ The on-demand model (10 always-on + `tool_call` indirection) reaches the same sk
 
 Versions ≤ 0.7.4 are end-of-life. There is no `@opvs-ai/mcp@0.x → 1.0` migration code path — replace the old install with a fresh one.
 
+## Development
+
+```bash
+cd ../core && npm install && npx tsc   # REQUIRED FIRST — see below
+cd ../mcp  && npm install
+npx vitest run                          # unit tests
+npm run build && OPVS_TOKEN=smoke-test npm run list-tools
+```
+
+Two things bite from a clean checkout:
+
+- **Build `@opvs-ai/core` first.** Its `main` points at `dist/`, so without that step the
+  suite dies at *collection* with `Failed to resolve entry for package "@opvs-ai/core"` —
+  a missing build, not a broken suite.
+- **`npm run list-tools` is a real gate, not a printout.** It drives the actual stdio
+  protocol against the built server and exits non-zero on a tool name that fails
+  `^[a-zA-Z0-9_-]+$` (exit 2) or on going over the tool-count ceiling (exit 3). A unit test
+  of the `TOOLS` array cannot prove a tool is *registered*; this can. Both run in CI under
+  **TS Library Tests**.
+
+Counts move. Measure them at your SHA rather than citing a number from here.
+
 ## Related packages
 
 - [`@opvs-ai/cli`](../cli) — terminal access (no MCP layer)

package/dist/.build-stamp.json

@@ -0,0 +1,9 @@
+{
+  "stamp_version": 1,
+  "package": "@opvs-ai/mcp",
+  "version": "2.7.1",
+  "source_digest": "1655ead73749e2e1b930a8d31f87653be62fad744fd5aefceb2fe6ab20178f50",
+  "source_files": 6,
+  "built_at": "2026-09-15T21:57:10.606Z",
+  "node": "v22.22.0"
+}

package/dist/board.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Board tools — `board_as_markdown` (Topic 1 / S1.3).
+ *
+ * Lives outside `index.ts` because that file ends in a top-level
+ * `await server.connect(transport)` — importing it to unit-test a handler would
+ * start a server. See `http.ts` and `fleet.ts` for the same reasoning (OSB-119).
+ *
+ * Carved out at OSB-207, whose whole subject is what this tool does when the
+ * export is REFUSED, and which could not be tested where it was.
+ */
+import { type ToolResult } from "./http.js";
+export declare const BOARD_TOOLS: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            board_id: {
+                type: string;
+                description: string;
+            };
+            detail: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            columns: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+}[];
+/** The shape `@opvs-ai/core` throws, plus the parsed body it now carries. */
+type UpstreamError = {
+    detail?: string;
+    status?: number;
+    body?: unknown;
+};
+/** The structured half of AgentBoard's 413, when it sent one. */
+type ExportRefusal = {
+    error?: unknown;
+    message?: unknown;
+    actual_bytes?: unknown;
+    limit_bytes?: unknown;
+    detail_level?: unknown;
+    retry_with?: unknown;
+};
+/**
+ * Pull AgentBoard's structured refusal out of a thrown error, if it sent one.
+ *
+ * Returns `null` for the PROSE shape — which is not a failure to handle but the
+ * ordinary state during a deploy window: this package and AgentBoard ship on
+ * different schedules, so a rebuilt MCP will spend some hours talking to a
+ * server that still answers `{"detail": "<sentence>"}`. The caller must stay
+ * useful on that path, so nothing here parses the sentence for numbers — an
+ * absent field is honest, a number scraped out of English is a guess.
+ */
+export declare function exportRefusalFields(e: UpstreamError): ExportRefusal | null;
+export declare function handleBoardAsMarkdown(args: {
+    board_id: string;
+    detail?: string;
+    columns?: string;
+}): Promise<ToolResult>;
+export {};

package/dist/board.js

@@ -0,0 +1,175 @@
+/**
+ * Board tools — `board_as_markdown` (Topic 1 / S1.3).
+ *
+ * Lives outside `index.ts` because that file ends in a top-level
+ * `await server.connect(transport)` — importing it to unit-test a handler would
+ * start a server. See `http.ts` and `fleet.ts` for the same reasoning (OSB-119).
+ *
+ * Carved out at OSB-207, whose whole subject is what this tool does when the
+ * export is REFUSED, and which could not be tested where it was.
+ */
+import { err, errFields, getText, ok } from "./http.js";
+export const BOARD_TOOLS = [
+    {
+        name: "board_as_markdown",
+        description: "Read a WHOLE AgentBoard (or a chosen subset of its columns) as a single " +
+            "Markdown plan/PRD document — one call instead of N task fetches. Cheaper on " +
+            "tokens and gives narrative context, not raw rows. Returns the rendered " +
+            "Markdown string verbatim (read-only, deterministic — same board state → same " +
+            "bytes, each task row carries an HTML comment with its UUID for diffing). " +
+            "Brand is pinned server-side from the PAT — never pass a brand_id. Pick `detail`: " +
+            "`summary` = compact one-row-per-task table (token-cheapest); `standard` " +
+            "(default) = the nested plan format with task bodies, subtasks and stages; " +
+            "`full` = the exhaustive dump including comments. " +
+            "SIZE: a big board can exceed the server's 1 MiB export ceiling at `standard` " +
+            "or `full` and is then REFUSED (413) rather than truncated — the refusal is " +
+            "machine-readable (`actual_bytes`, `limit_bytes`, `retry_with`) and this tool " +
+            "does NOT silently retry at a lower detail, because it promises these exact " +
+            "bytes. On a board you know is large, ask for `detail='summary'` up front: it " +
+            "is the one narrowing that drops no card.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                board_id: {
+                    type: "string",
+                    description: "The board UUID to render.",
+                },
+                detail: {
+                    type: "string",
+                    enum: ["summary", "standard", "full"],
+                    description: "Render depth. Default `standard` (the nested plan/PRD shape). " +
+                        "`summary` is the compact table; `full` adds comments.",
+                },
+                columns: {
+                    type: "string",
+                    description: "Optional comma-separated column filter — names OR ids, mixed. Each token " +
+                        "is resolved name-first-then-id; an unknown token fails loud (400). Omit to " +
+                        "render every column.",
+                },
+            },
+            required: ["board_id"],
+        },
+    },
+];
+/**
+ * Pull AgentBoard's structured refusal out of a thrown error, if it sent one.
+ *
+ * Returns `null` for the PROSE shape — which is not a failure to handle but the
+ * ordinary state during a deploy window: this package and AgentBoard ship on
+ * different schedules, so a rebuilt MCP will spend some hours talking to a
+ * server that still answers `{"detail": "<sentence>"}`. The caller must stay
+ * useful on that path, so nothing here parses the sentence for numbers — an
+ * absent field is honest, a number scraped out of English is a guess.
+ */
+export function exportRefusalFields(e) {
+    const body = e.body;
+    const detail = body?.detail;
+    if (!detail || typeof detail !== "object" || Array.isArray(detail))
+        return null;
+    const d = detail;
+    return d.error === "markdown_export_too_large" ? d : null;
+}
+function asNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+/**
+ * Turn a 413 into a refusal an agent can act on without reading English.
+ *
+ * DECISION (OSB-207): this does NOT retry at `summary` itself.
+ *
+ * The tool's contract is "the rendered Markdown string verbatim — same board
+ * state → same bytes", which is what makes the output safe to commit and diff.
+ * There is no envelope on the success path to announce a substitution in, so
+ * auto-retrying would have to either corrupt those bytes with a banner or hand
+ * back a compact table where task bodies were asked for — and an agent that
+ * receives a table silently has no way to tell "the cards have no descriptions"
+ * from "I was served a different document than I requested". The cost of not
+ * retrying is one round-trip; the cost of retrying is a wrong conclusion that
+ * looks like data. The numbers and the exact next call go in the refusal
+ * instead, so that round-trip is always correct.
+ */
+function tooLargeResult(boardId, requested, e) {
+    const fields = exportRefusalFields(e);
+    const actual = asNumber(fields?.actual_bytes);
+    const limit = asNumber(fields?.limit_bytes);
+    // The server reports the level it refused; fall back to the one WE asked
+    // for, which is known here and is not a guess. Undefined only when the
+    // caller omitted `detail` AND the server sent prose — we do not assert the
+    // server's default on its behalf.
+    const level = typeof fields?.detail_level === "string" ? fields.detail_level : requested;
+    const sizes = actual != null && limit != null
+        ? ` — ${actual.toLocaleString("en-US")} bytes, over the ${limit.toLocaleString("en-US")}-byte limit`
+        : "";
+    const at = level ? ` at detail='${level}'` : "";
+    // `summary` is exempt from the ceiling server-side, so this branch is
+    // unreachable today. It exists because the alternative is guidance that
+    // names the level that just failed — the "a ceiling that can reject its own
+    // remedy is a dead end" shape, one layer out. Cheap to be right about.
+    const summaryAlsoRefused = level === "summary";
+    const guidance = summaryAlsoRefused
+        ? "#audit.error:too-large — even detail='summary' exceeds the server's " +
+            "Markdown export ceiling for this board, so there is no lossless export " +
+            "of the whole board. This is NOT an auth, brand or board_id problem. " +
+            `#next:board_as_markdown(board_id='${boardId}', detail='summary', ` +
+            "columns='<name,name>') — a SUBSET, lossy: cards outside the named " +
+            "columns are absent from the document entirely. Use " +
+            "tool_call(@opvs-ai/agentboard, list_columns) for the valid names."
+        : "#audit.error:too-large — the board exceeds the server's Markdown export " +
+            "ceiling at this detail level. This is NOT an auth, brand or board_id " +
+            "problem, and retrying the identical call will fail identically. " +
+            `#next:board_as_markdown(board_id='${boardId}', detail='summary') — a ` +
+            "compact one-row-per-task table over EVERY card, each keeping its " +
+            "<!-- task: uuid --> anchor, so no card is dropped. Pass " +
+            "columns='<name,name>' instead to export a SUBSET — lossy: cards outside " +
+            "the named columns are absent from the document entirely.";
+    return errFields(`board_as_markdown: board '${boardId}' is too large to export${at}${sizes}.`, {
+        code: "markdown_export_too_large",
+        ...(actual != null ? { actual_bytes: actual } : {}),
+        ...(limit != null ? { limit_bytes: limit } : {}),
+        ...(level != null ? { detail_level: level } : {}),
+        // The one narrowing that drops no card, as a parameter not a sentence —
+        // omitted when it is the thing that was just refused.
+        ...(summaryAlsoRefused ? {} : { retry_with: { detail: "summary" } }),
+        lossy_alternative: { columns: "<name,name>" },
+    }, guidance);
+}
+export async function handleBoardAsMarkdown(args) {
+    if (!args.board_id || typeof args.board_id !== "string") {
+        return err("board_id is required", "#audit.error:input=missing — board_as_markdown needs the board UUID. " +
+            "Use tool_call(@opvs-ai/agentboard, list_boards) to find one.");
+    }
+    if (args.detail != null &&
+        !["summary", "standard", "full"].includes(args.detail)) {
+        return err(`invalid detail '${args.detail}'`, "#audit.error:input=bad-detail — detail must be summary | standard | full. " +
+            "#next:omit it for the default (standard).");
+    }
+    // Mirror the export contract: format=md is fixed; detail/columns are forwarded
+    // only when the caller set them (don't synthesize defaults — let the backend
+    // own them; LEARNINGS #38, the silent-drop tax cuts both ways).
+    const q = new URLSearchParams({ format: "md" });
+    if (args.detail)
+        q.set("detail", args.detail);
+    if (args.columns)
+        q.set("columns", args.columns);
+    const path = `/api/v1/board/boards/${encodeURIComponent(args.board_id)}/export?${q.toString()}`;
+    try {
+        const md = await getText(path);
+        return ok(md);
+    }
+    catch (e) {
+        const error = e;
+        if (error.status === 413) {
+            return tooLargeResult(args.board_id, args.detail, error);
+        }
+        if (error.status === 400) {
+            return err(`board_as_markdown: ${error.detail ?? "bad request"}`, "#audit.error:bad-columns — an unknown column name/id was passed. " +
+                "#next:tool_call(@opvs-ai/agentboard, list_columns) to see valid columns, or omit `columns`.");
+        }
+        if (error.status === 404) {
+            return err(`board '${args.board_id}' not found (or not visible to this brand)`, "#audit.error:board=missing #next:whoami to confirm the PAT's brand; " +
+                "tool_call(@opvs-ai/agentboard, list_boards) to list boards.");
+        }
+        return err(`board_as_markdown failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:upstream #next:whoami to verify auth/brand; check the board_id.");
+    }
+}
+//# sourceMappingURL=board.js.map

package/dist/board.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board.js","sourceRoot":"","sources":["../src/board.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAmB,MAAM,WAAW,CAAC;AAEzE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EACT,0EAA0E;YAC1E,8EAA8E;YAC9E,yEAAyE;YACzE,+EAA+E;YAC/E,2EAA2E;YAC3E,mFAAmF;YACnF,0EAA0E;YAC1E,4EAA4E;YAC5E,mDAAmD;YACnD,+EAA+E;YAC/E,6EAA6E;YAC7E,+EAA+E;YAC/E,6EAA6E;YAC7E,+EAA+E;YAC/E,0CAA0C;QAC5C,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2BAA2B;iBACzC;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC;oBACrC,WAAW,EACT,gEAAgE;wBAChE,uDAAuD;iBAC1D;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,2EAA2E;wBAC3E,6EAA6E;wBAC7E,sBAAsB;iBACzB;aACF;YACD,QAAQ,EAAE,CAAC,UAAU,CAAC;SACvB;KACF;CACF,CAAC;AAeF;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAgB;IAClD,MAAM,IAAI,GAAG,CAAC,CAAC,IAAwC,CAAC;IACxD,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAChF,MAAM,CAAC,GAAG,MAAuB,CAAC;IAClC,OAAO,CAAC,CAAC,KAAK,KAAK,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,cAAc,CACrB,OAAe,EACf,SAA6B,EAC7B,CAAgB;IAEhB,MAAM,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC5C,yEAAyE;IACzE,uEAAuE;IACvE,2EAA2E;IAC3E,kCAAkC;IAClC,MAAM,KAAK,GACT,OAAO,MAAM,EAAE,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;IAE7E,MAAM,KAAK,GACT,MAAM,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI;QAC7B,CAAC,CAAC,MAAM,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,oBAAoB,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,aAAa;QACpG,CAAC,CAAC,EAAE,CAAC;IACT,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,eAAe,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEhD,sEAAsE;IACtE,wEAAwE;IACxE,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,kBAAkB,GAAG,KAAK,KAAK,SAAS,CAAC;IAC/C,MAAM,QAAQ,GAAG,kBAAkB;QACjC,CAAC,CAAC,sEAAsE;YACtE,yEAAyE;YACzE,sEAAsE;YACtE,qCAAqC,OAAO,uBAAuB;YACnE,oEAAoE;YACpE,qDAAqD;YACrD,mEAAmE;QACrE,CAAC,CAAC,0EAA0E;YAC1E,uEAAuE;YACvE,kEAAkE;YAClE,qCAAqC,OAAO,2BAA2B;YACvE,mEAAmE;YACnE,0DAA0D;YAC1D,0EAA0E;YAC1E,0DAA0D,CAAC;IAE/D,OAAO,SAAS,CACd,6BAA6B,OAAO,2BAA2B,EAAE,GAAG,KAAK,GAAG,EAC5E;QACE,IAAI,EAAE,2BAA2B;QACjC,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,wEAAwE;QACxE,sDAAsD;QACtD,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;QACpE,iBAAiB,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE;KAC9C,EACD,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAI3C;IACC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACxD,OAAO,GAAG,CACR,sBAAsB,EACtB,uEAAuE;YACrE,8DAA8D,CACjE,CAAC;IACJ,CAAC;IAED,IACE,IAAI,CAAC,MAAM,IAAI,IAAI;QACnB,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EACtD,CAAC;QACD,OAAO,GAAG,CACR,mBAAmB,IAAI,CAAC,MAAM,GAAG,EACjC,4EAA4E;YAC1E,2CAA2C,CAC9C,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,6EAA6E;IAC7E,gEAAgE;IAChE,MAAM,CAAC,GAAG,IAAI,eAAe,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,IAAI,IAAI,CAAC,MAAM;QAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,IAAI,CAAC,OAAO;QAAE,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAEjD,MAAM,IAAI,GAAG,wBAAwB,kBAAkB,CACrD,IAAI,CAAC,QAAQ,CACd,WAAW,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,CAAkB,CAAC;QACjC,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACzB,OAAO,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACzB,OAAO,GAAG,CACR,sBAAsB,KAAK,CAAC,MAAM,IAAI,aAAa,EAAE,EACrD,mEAAmE;gBACjE,6FAA6F,CAChG,CAAC;QACJ,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACzB,OAAO,GAAG,CACR,UAAU,IAAI,CAAC,QAAQ,4CAA4C,EACnE,sEAAsE;gBACpE,6DAA6D,CAChE,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CACR,6BAA6B,KAAK,CAAC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,EACxE,8EAA8E,CAC/E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/factory-guidance.d.ts

@@ -0,0 +1,14 @@
+/** Routing nudge for board/factory skills (GS.2). A POINTER to the canonical
+ *  sources (the skill's SKILL.md + its references, read with `tool_read`, and
+ *  the live claimTask/getRunnable `_guidance` envelopes), carrying the few
+ *  platform invariants an MCP agent needs at decision time so it can't drive a
+ *  factory board blind. Deliberately terse — the full recipe is
+ *  references/run-a-factory-board.md; this never restates it.
+ *
+ *  ASP-73: this used to send agents to `section='description'` for "the
+ *  operating model + references index". tool_help's description section is the
+ *  registry's one-line package description, so the pointer led back to this
+ *  same `_guidance` — a loop. The operating model is what `tool_read` serves.
+ *  ASP-75: the one-active-project claim gate is stated here too, because it
+ *  refuses every claim before any of the other invariants matter. */
+export declare const FACTORY_HELP_GUIDANCE: string;

package/dist/factory-guidance.js

@@ -0,0 +1,27 @@
+/** Routing nudge for board/factory skills (GS.2). A POINTER to the canonical
+ *  sources (the skill's SKILL.md + its references, read with `tool_read`, and
+ *  the live claimTask/getRunnable `_guidance` envelopes), carrying the few
+ *  platform invariants an MCP agent needs at decision time so it can't drive a
+ *  factory board blind. Deliberately terse — the full recipe is
+ *  references/run-a-factory-board.md; this never restates it.
+ *
+ *  ASP-73: this used to send agents to `section='description'` for "the
+ *  operating model + references index". tool_help's description section is the
+ *  registry's one-line package description, so the pointer led back to this
+ *  same `_guidance` — a loop. The operating model is what `tool_read` serves.
+ *  ASP-75: the one-active-project claim gate is stated here too, because it
+ *  refuses every claim before any of the other invariants matter. */
+export const FACTORY_HELP_GUIDANCE = "#use:board/DAG/factory task pipelines. " +
+    "#read:tool_read(name) for the operating model (the skill's SKILL.md) — its " +
+    "`layers[]` lists every recipe; tool_read(name, path='references/run-a-factory-board.md') " +
+    "is the factory recipe. " +
+    "#factory:the board must be in exactly ONE active project (moveBoardToProject " +
+    "mode=move) or every claimTask returns task_id:null reason board_project_unresolved. " +
+    "New cards land in Backlog (staging, NOT claimable) → move to Ready " +
+    "(claimable by role 'builder') → a worker claims and it auto-moves to Executing. " +
+    "A factory board runs NOTHING until an opvs-sidecar worker is pointed at its " +
+    "board_id; set a `mode:` label (auto|assisted|manual) per card for build autonomy. " +
+    "#next:the live claimTask + getRunnable responses carry their own `_guidance` " +
+    "envelope (e.g. a claim that returns task_id:null+reason is a misconfig, " +
+    "not no-work) — read it.";
+//# sourceMappingURL=factory-guidance.js.map

package/dist/factory-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-guidance.js","sourceRoot":"","sources":["../src/factory-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;qEAYqE;AACrE,MAAM,CAAC,MAAM,qBAAqB,GAChC,yCAAyC;IACzC,6EAA6E;IAC7E,2FAA2F;IAC3F,yBAAyB;IACzB,+EAA+E;IAC/E,sFAAsF;IACtF,qEAAqE;IACrE,kFAAkF;IAClF,8EAA8E;IAC9E,oFAAoF;IACpF,+EAA+E;IAC/E,0EAA0E;IAC1E,yBAAyB,CAAC"}

package/dist/fleet.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Fleet tools — the MACHINE and SLOT surface (OSB-119, BYO plan row 3.2).
+ *
+ * Until this module the MCP package had 11 tools and NONE of them reached the
+ * environment layer, so the owner's "dashboard or MCP" was dashboard-only.
+ *
+ * Lives outside `index.ts` because that file ends in a top-level
+ * `await server.connect(transport)` — importing it to unit-test a handler would
+ * start a server. See `http.ts` for the same reasoning.
+ */
+import { type ToolResult } from "./http.js";
+export declare const FLEET_TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            detail: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            slot?: undefined;
+            name?: undefined;
+            runtime?: undefined;
+            region?: undefined;
+            description?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            slot: {
+                type: string;
+                description: string;
+            };
+            detail?: undefined;
+            name?: undefined;
+            runtime?: undefined;
+            region?: undefined;
+            description?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            detail?: undefined;
+            slot?: undefined;
+            name?: undefined;
+            runtime?: undefined;
+            region?: undefined;
+            description?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            runtime: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            region: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            detail?: undefined;
+            slot?: undefined;
+        };
+        required: string[];
+    };
+})[];
+/** The slot fields a compact fleet row carries.
+ *
+ *  AN ENUMERATION IS ITSELF A CLAIM, so this list is exported into the
+ *  `fleet_list` description verbatim and `detail: "full"` exists to escape it.
+ *  A trim that nobody can see is indistinguishable from a field the server
+ *  stopped sending.
+ */
+export declare const COMPACT_SLOT_FIELDS: readonly ["id", "short_id", "name", "status", "dormant", "runtime", "machine_id", "sidecar_port", "wg_address", "sidecar_version", "last_health_check", "last_sync_at", "pending_sync_count"];
+export declare function compactSlot(row: Record<string, unknown>): Record<string, unknown>;
+/** Group slots under the machine that reported hosting them.
+ *
+ *  🔴 A NULL `machine_id` is NOT a group. The column is written by the health
+ *  poller from `/etc/machine-id` and is NULL whenever the sidecar is too old to
+ *  report it — which is still the common case. Two boxes that both decline to
+ *  say where they run are not thereby co-tenants, and collapsing them would
+ *  invent a co-tenancy the platform has no evidence for
+ *  (`schemas/environment.py`, `machine_id`). They go to `unplaced`, one entry
+ *  each, in list order.
+ */
+export declare function groupByMachine(rows: Array<Record<string, unknown>>): {
+    machines: Array<{
+        machine_id: string;
+        slot_count: number;
+        slots: string[];
+    }>;
+    unplaced: string[];
+};
+export declare function handleFleetList(args: {
+    detail?: string;
+}): Promise<ToolResult>;
+/** Resolve any slot ref (UUID | 8+ hex prefix | `env_…` short code) to the
+ *  canonical environment row.
+ *
+ *  🔑 THIS EXISTS BECAUSE THE TWO ROUTES DISAGREE ABOUT REF SHAPES.
+ *  `GET /environments/{ref}` funnels through `_resolve_env`, which accepts all
+ *  three. `GET /workstations/{id}` gates on `_is_uuid` and returns 404 for
+ *  anything else — so an agent that reads `short_id` out of `fleet_list` and
+ *  hands it to the checklist route gets "not found" for a slot that plainly
+ *  exists. Resolving here, once, and then using the row's own `id` for the
+ *  second hop is what keeps `slot_get` honest about which refs it accepts.
+ */
+export declare function resolveSlot(ref: string): Promise<{
+    ok: true;
+    row: Record<string, unknown>;
+} | {
+    ok: false;
+    result: ToolResult;
+}>;
+type OnboardingStep = {
+    key?: unknown;
+    state?: unknown;
+    reason?: unknown;
+    hint?: unknown;
+    title?: unknown;
+};
+/** The one step an operator should act on: the first that is not `done`.
+ *
+ *  Everything after it is `blocked_by:<key>` by construction (OSB-113), so
+ *  picking the first non-done step is what turns four competing lines into one.
+ *  Returns null when every step is done — a genuinely ready slot.
+ */
+export declare function nextAction(steps: OnboardingStep[]): Record<string, unknown> | null;
+export declare function handleSlotGet(args: {
+    slot: string;
+}): Promise<ToolResult>;
+export declare function handleSlotHealth(args: {
+    slot: string;
+}): Promise<ToolResult>;
+export declare function handleFleetLogins(): Promise<ToolResult>;
+export declare const SLOT_RUNTIMES: string[];
+export declare function handleSlotOrder(args: {
+    name: string;
+    runtime?: string;
+    region?: string;
+    description?: string;
+}): Promise<ToolResult>;
+export {};