diff --git a/docs/herdr-workspaces-mcp.md b/docs/herdr-workspaces-mcp.md new file mode 100644 index 00000000..74e6cf58 --- /dev/null +++ b/docs/herdr-workspaces-mcp.md @@ -0,0 +1,57 @@ +# Herdr workspace reads from MCP + +`herdr_workspaces` reads the selected local broker's +`GET /v1/terminal-hosts/herdr/workspaces` projection. The broker owns the +TTL-cached Herdr probes. The MCP client does not run Herdr, enumerate local +sessions, start services or use the private web server. + +The existing `session`, `query` and `limit` tool inputs and ranked digest output +remain. A session is an exact host selector, not a Scout routing address. Pane +names and reported harness sessions remain observations, not verified bindings. +Stopped or saved projections never offer a live read handoff. + +## Observation and error metadata + +Structured results add `runtimeRead` when a valid broker observation was read. +It preserves the schema, node, scan time, requested session, availability, +reason, count, truncation and coverage limits. Its `sessions` list carries each +returned session's availability; the existing digest or candidate fields carry +the presentation. No duplicate full digest is added to the metadata. + +- `available` observations can establish an observed empty bounded inventory. +- `partial` observations remain usable, but the tool marks them truncated and + does not describe an empty result as proof that no sessions exist. +- `not_scanned` and `unavailable` produce `available: false`. They are not + available-empty results. Valid unavailable observations can still carry + per-session failure provenance in `runtimeRead`. +- Transport, HTTP and validation failures produce `readError` with a safe code + and HTTP status when received. Raw server bodies are not reflected. A 403 + remains a refusal; a 404 is not converted into an available empty session. + +This is an additive MCP result change and a read-backend switch. It adds no +runtime route, protocol DTO, package export, host control or answer authority. +The tool remains machine-local and read-only. + +## Transport and validation bounds + +The client selects `OPENSCOUT_BROKER_URL` or the runtime's control URL. Only +literal `localhost`, `127.0.0.1` and `[::1]` HTTP(S) authorities are accepted. +If `OPENSCOUT_BROKER_SOCKET_PATH` is set, that socket is used; failure never +falls back to HTTP. Socket-only mode without a socket fails before a request. + +One eight-second signal covers headers and body. Redirects and ambient +credentials are disabled. The client never sends web bearer tokens, cookies, +browser origins or forwarding headers, and never requests `/api/bootstrap.js`. +It makes no retry or alternate-source read after failure. + +The response has a two-MiB byte ceiling, strict UTF-8/JSON validation and the +versioned digest shape. It validates the requested session, count, duplicate +sessions, saved/live consistency, nested arrays and the broker's declared +limits. Unrecognized or oversized shapes are unavailable, not silently +truncated into a valid observation. The broker's 40 emitted panes can occupy +up to 256 directory groups, including groups whose panes were all omitted. + +The browser-cookie adapter and its temporary private inventory exception are +removed. The named inventory records its source as forbidden to return. Other +private app commands and packaged app artifacts remain separate cutover work; +this reader does not make the whole CLI package app-independent. diff --git a/packages/cli/src/cli/commands/fixtures/web-stdio.ts b/packages/cli/src/cli/commands/fixtures/web-stdio.ts new file mode 100644 index 00000000..59759fc3 --- /dev/null +++ b/packages/cli/src/cli/commands/fixtures/web-stdio.ts @@ -0,0 +1,44 @@ +// Exercise the real install, then the next command's lazy stdout initialization. +// The GC schedule follows https://github.com/oven-sh/bun/pull/44581: an older +// Bun finalizes stdio sinks against the wrong epoll while a synchronous child is active. +import { createHash } from "node:crypto"; +import { readFileSync, writeSync } from "node:fs"; +import { createScoutCommandContext } from "../../context.ts"; +import { mock } from "bun:test"; +// --no-restart never calls server control. Keep unrelated service discovery out +// of the deliberately allocation-heavy GC child (and away from real services). +mock.module("../server.ts", () => ({ requestScoutWebControl() { throw new Error("Unexpected server control"); } })); +const { runWebCommand } = await import("../web.ts"); + +const tarball = new Uint8Array(readFileSync(process.argv[2]!)); +const held = globalThis as typeof globalThis & { stdioSinks: unknown }; +held.stdioSinks = Array.from({ length: 4 }, () => { + const sink = Bun.file(1).writer(); + sink.write(""); + return sink; +}); +await Bun.sleep(0); +const original = Bun.spawnSync; +Bun.spawnSync = ((options: { cmd: string[]; maxBuffer?: number }) => original({ + ...options, + get maxBuffer() { + Bun.gc(true); + held.stdioSinks = null; + return options.maxBuffer; + }, +})) as typeof Bun.spawnSync; +try { + await runWebCommand(createScoutCommandContext({ env: { SCOUT_DIST_KEY: "osdist_stdio_regression" }, isTty: false, stdout() {}, stderr() {} }), ["install", "--no-restart"], { + supportDirectory: process.argv[3]!, version: "9.8.7", keyStores: [], + fetchImpl: async () => new Response(tarball, { headers: { "x-openscout-sha256": createHash("sha256").update(tarball).digest("hex") } }), + }); +} finally { + Bun.spawnSync = original; +} +held.stdioSinks = null; +Bun.gc(true); +await Bun.sleep(50); +// Do not preinitialize process.stdout: this is where the following test failed. +createScoutCommandContext({ env: {}, stdout() {}, stderr() {} }); +process.stdout.write("stdio survived install\n"); +writeSync(2, "stdio regression finished\n"); diff --git a/packages/cli/src/cli/commands/web.test.ts b/packages/cli/src/cli/commands/web.test.ts index 51fbb96a..e891d01b 100644 --- a/packages/cli/src/cli/commands/web.test.ts +++ b/packages/cli/src/cli/commands/web.test.ts @@ -1,10 +1,11 @@ import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test"; import * as childProcess from "node:child_process"; -import { spawnSync } from "node:child_process"; +import { execFile } from "node:child_process"; import { createHash } from "node:crypto"; import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; +import { promisify } from "node:util"; import { resolveInstalledWebFullClient } from "@openscout/runtime/web-full-client"; @@ -33,16 +34,14 @@ afterEach(() => { rmSync(root, { recursive: true, force: true }); }); -function packClient(version: string, profileVersion = version): Uint8Array { +async function packClient(version: string, profileVersion = version): Promise> { const client = join(root, `client-${version}-${profileVersion}`); mkdirSync(join(client, "assets"), { recursive: true }); writeFileSync(join(client, "index.html"), "Scout"); writeFileSync(join(client, "assets", "app.js"), "Mission Control"); writeFileSync(join(client, "scout-web-profile.json"), JSON.stringify({ profile: "full", version: profileVersion })); const tarball = join(root, `${version}-${profileVersion}.tar.gz`); - const packed = spawnSync("tar", ["-czf", tarball, "-C", client, "."], { timeout: 5_000, killSignal: "SIGKILL" }); - expect(packed.error).toBeUndefined(); - expect(packed.status, packed.stderr?.toString()).toBe(0); + await promisify(execFile)("tar", ["-czf", tarball, "-C", client, "."], { timeout: 5_000, killSignal: "SIGKILL", maxBuffer: 128 * 1024 }); return new Uint8Array(readFileSync(tarball)); } @@ -95,6 +94,27 @@ function harness(options: { } describe("scout web", () => { + test.skipIf(process.platform !== "linux")("install leaves stdout usable for the next command even under GC", async () => { + const tarball = await packClient(VERSION); + const archive = join(root, "stdio.tar.gz"); + writeFileSync(archive, tarball); + // Own the risky old-Bun state in a child, with real pollable stdio pipes. + const child = Bun.spawn({ + cmd: [process.execPath, new URL("./fixtures/web-stdio.ts", import.meta.url).pathname, archive, support], + env: { ...process.env, BUN_JSC_slowPathAllocsBetweenGCs: "3" }, + stdout: "pipe", stderr: "pipe", stdin: "ignore", + }); + const timeout = setTimeout(() => child.kill("SIGKILL"), 30_000); + try { + const [stdout, stderr, exit] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]); + expect({ exit, stdout, stderr }).toEqual({ exit: 0, stdout: "stdio survived install\n", stderr: "stdio regression finished\n" }); + } finally { + clearTimeout(timeout); + child.kill("SIGKILL"); + await child.exited; + } + }, 35_000); + test("login checks the key with the host and saves it privately", async () => { const { context, deps, lines, requests } = harness(); await runWebCommand(context, ["login", "--key", KEY], deps); @@ -114,7 +134,7 @@ describe("scout web", () => { test("install downloads, verifies and installs the full client for this version, then restarts web", async () => { const restarted: string[] = []; - const tarball = packClient(VERSION); + const tarball = await packClient(VERSION); const { context, deps, lines, requests } = harness({ tarball, env: { SCOUT_DIST_KEY: KEY }, restarted }); await runWebCommand(context, ["install"], deps); @@ -139,11 +159,11 @@ describe("scout web", () => { }); test("a checksum mismatch or a client for another version is never installed", async () => { - const tarball = packClient(VERSION); + const tarball = await packClient(VERSION); const tampered = harness({ tarball, digest: "0".repeat(64), env: { SCOUT_DIST_KEY: KEY } }); await expect(runWebCommand(tampered.context, ["install"], tampered.deps)).rejects.toThrow("Checksum mismatch"); - const wrong = harness({ tarball: packClient(VERSION, "1.0.0"), env: { SCOUT_DIST_KEY: KEY } }); + const wrong = harness({ tarball: await packClient(VERSION, "1.0.0"), env: { SCOUT_DIST_KEY: KEY } }); await expect(runWebCommand(wrong.context, ["install"], wrong.deps)).rejects.toThrow("isn't the full web app"); expect(resolveInstalledWebFullClient(VERSION, { env: {}, supportDirectory: support })).toBeNull(); @@ -151,20 +171,41 @@ describe("scout web", () => { }); test("a stuck unpack child has a hard deadline, reports its error and leaves no partial install", async () => { - const tarball = packClient(VERSION); + const tarball = await packClient(VERSION); const { context, deps } = harness({ tarball, env: { SCOUT_DIST_KEY: KEY } }); - const child = spyOn(childProcess, "spawnSync").mockReturnValue({ - status: null, signal: "SIGKILL", error: Object.assign(new Error("spawnSync tar ETIMEDOUT"), { code: "ETIMEDOUT" }), - pid: 0, output: [], stdout: "", stderr: "partial tar diagnostic", - }); + const child = spyOn(childProcess, "execFile").mockImplementation(((_file: string, ...args: unknown[]) => { + const callback = args.at(-1) as (error: Error, stdout: string, stderr: string) => void; + callback(Object.assign(new Error("tar ETIMEDOUT"), { code: "ETIMEDOUT" }), "", "partial tar diagnostic"); + return {}; + }) as typeof childProcess.execFile); try { - await expect(runWebCommand(context, ["install", "--no-restart"], deps)).rejects.toThrow("Couldn't unpack the download: spawnSync tar ETIMEDOUT"); - expect(child).toHaveBeenCalledWith("tar", expect.any(Array), expect.objectContaining({ timeout: 30_000, killSignal: "SIGKILL" })); + await expect(runWebCommand(context, ["install", "--no-restart"], deps)).rejects.toThrow("Couldn't unpack the download: tar ETIMEDOUT"); + expect(child).toHaveBeenCalledWith("tar", expect.any(Array), expect.objectContaining({ timeout: 30_000, killSignal: "SIGKILL", maxBuffer: 128 * 1024 }), expect.any(Function)); expect(resolveInstalledWebFullClient(VERSION, { env: {}, supportDirectory: support })).toBeNull(); expect(readdirSync(join(support, "web", "full"))).toEqual([]); } finally { child.mockRestore(); } }); + test("a stalled body is cancelled at the download deadline and leaves no partial install", async () => { + let cancelled = false; + let controller!: ReadableStreamDefaultController; + const body = new ReadableStream({ + start(value) { controller = value; controller.enqueue(new Uint8Array([1, 2, 3])); }, + cancel() { cancelled = true; }, + }); + const run = harness({ env: { SCOUT_DIST_KEY: KEY } }); + // Cleanup-only EOF: without the consumer deadline this yields a normal test failure, not a hung runner. + const watchdog = setTimeout(() => { if (!cancelled) controller.close(); }, 750); + try { await expect(runWebCommand(run.context, ["install", "--no-restart"], { + ...run.deps, downloadTimeoutMs: 25, + // Deliberately not connected to fetch's signal: the consumer must own a deadline. + fetchImpl: async () => new Response(body, { headers: { "x-openscout-sha256": "0".repeat(64) } }), + })).rejects.toThrow(/abort/i); } finally { clearTimeout(watchdog); } + expect(cancelled).toBe(true); + expect(resolveInstalledWebFullClient(VERSION, { env: {}, supportDirectory: support })).toBeNull(); + expect(readdirSync(join(support, "web", "full"))).toEqual([]); + }); + test("install explains a missing key and an unpublished version", async () => { const none = harness(); await expect(runWebCommand(none.context, ["install"], none.deps)).rejects.toThrow("No download key"); @@ -174,7 +215,7 @@ describe("scout web", () => { }); test("status reports what is served; uninstall goes back to basic", async () => { - const tarball = packClient(VERSION); + const tarball = await packClient(VERSION); const run = harness({ tarball, env: { SCOUT_DIST_KEY: KEY } }); await runWebCommand(run.context, ["status"], run.deps); expect(run.lines.join("\n")).toContain("serves the basic web app"); @@ -206,11 +247,11 @@ describe("scout web", () => { test("an upgraded CLI diagnoses the old Full client and recovers with the saved key", async () => { const previousVersion = "9.8.6"; - const previous = harness({ tarball: packClient(previousVersion), env: { SCOUT_DIST_KEY: KEY } }); + const previous = harness({ tarball: await packClient(previousVersion), env: { SCOUT_DIST_KEY: KEY } }); await fileDistKeyStore(support).write(KEY); await runWebCommand(previous.context, ["install", "--no-restart"], { ...previous.deps, version: previousVersion }); - const current = harness({ tarball: packClient(VERSION), json: true }); + const current = harness({ tarball: await packClient(VERSION), json: true }); await runWebCommand(current.context, ["status"], current.deps); expect(JSON.parse(current.lines[0]!)).toMatchObject({ version: VERSION, serves: "basic", reason: "version-mismatch", installed: null, @@ -232,8 +273,41 @@ describe("scout web", () => { }); }); + test("a stalled upgrade preserves the old Full client and key after cancelling its download", async () => { + const previousVersion = "9.8.6"; + const previous = harness({ tarball: await packClient(previousVersion), env: { SCOUT_DIST_KEY: KEY } }); + await fileDistKeyStore(support).write(KEY); + await runWebCommand(previous.context, ["install", "--no-restart"], { ...previous.deps, version: previousVersion }); + const tarball = await packClient(VERSION); + let cancelled = false; + let controller!: ReadableStreamDefaultController; + const body = new ReadableStream({ + start(value) { controller = value; controller.enqueue(tarball); }, // All bytes, but no EOF. + cancel() { cancelled = true; }, + }); + const restarted: string[] = []; + const current = harness({ json: true, restarted }); + // Cleanup-only EOF: without the consumer deadline this yields a normal test failure, not a hung runner. + const watchdog = setTimeout(() => { if (!cancelled) controller.close(); }, 750); + try { await expect(runWebCommand(current.context, ["install"], { + ...current.deps, downloadTimeoutMs: 25, + fetchImpl: async (_url, init) => { + expect(init?.signal).toBeInstanceOf(AbortSignal); + return new Response(body, { headers: { "x-openscout-sha256": sha256(tarball) } }); + }, + })).rejects.toThrow(/abort/i); } finally { clearTimeout(watchdog); } + expect(cancelled).toBe(true); + expect(restarted).toEqual([]); + expect(await fileDistKeyStore(support).read()).toBe(KEY); + expect(resolveInstalledWebFullClient(previousVersion, { env: {}, supportDirectory: support })).not.toBeNull(); + expect(resolveInstalledWebFullClient(VERSION, { env: {}, supportDirectory: support })).toBeNull(); + expect(readdirSync(join(support, "web", "full"))).toEqual([previousVersion]); + await runWebCommand(current.context, ["status"], current.deps); + expect(JSON.parse(current.lines[0]!)).toMatchObject({ reason: "version-mismatch", installedVersions: [previousVersion] }); + }); + test("forcing Basic preserves the installed Full path and explains the override", async () => { - const run = harness({ tarball: packClient(VERSION), env: { SCOUT_DIST_KEY: KEY, OPENSCOUT_WEB_CLIENT_PROFILE: " basic " }, json: true }); + const run = harness({ tarball: await packClient(VERSION), env: { SCOUT_DIST_KEY: KEY, OPENSCOUT_WEB_CLIENT_PROFILE: " basic " }, json: true }); await runWebCommand(run.context, ["install", "--no-restart"], run.deps); run.lines.length = 0; await runWebCommand(run.context, ["status"], run.deps); @@ -277,7 +351,7 @@ describe("scout web", () => { test("an unpublished upgrade leaves the old Full install and saved key intact", async () => { const previousVersion = "9.8.6"; - const previous = harness({ tarball: packClient(previousVersion), env: { SCOUT_DIST_KEY: KEY } }); + const previous = harness({ tarball: await packClient(previousVersion), env: { SCOUT_DIST_KEY: KEY } }); await fileDistKeyStore(support).write(KEY); await runWebCommand(previous.context, ["install", "--no-restart"], { ...previous.deps, version: previousVersion }); const restarted: string[] = []; diff --git a/packages/cli/src/cli/commands/web.ts b/packages/cli/src/cli/commands/web.ts index 5f6d9c41..f03d2d4e 100644 --- a/packages/cli/src/cli/commands/web.ts +++ b/packages/cli/src/cli/commands/web.ts @@ -1,8 +1,9 @@ -import { spawnSync } from "node:child_process"; +import { execFile } from "node:child_process"; import { createHash } from "node:crypto"; import { createWriteStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs"; import { join } from "node:path"; import { createInterface } from "node:readline"; +import { promisify } from "node:util"; import { Writable } from "node:stream"; import { Readable } from "node:stream"; import { pipeline } from "node:stream/promises"; @@ -48,6 +49,8 @@ export type ScoutWebCommandDeps = { keyStores?: DistKeyStore[]; promptKey?: () => Promise; restartWeb?: () => Promise; + /** May shorten the complete download budget; never extends the production cap. */ + downloadTimeoutMs?: number; }; export function renderWebCommandHelp(): string { @@ -123,13 +126,14 @@ async function distRequest( key: string, path: string, timeoutMs = 15_000, + signal = AbortSignal.timeout(timeoutMs), ): Promise { const fetchImpl = deps.fetchImpl ?? fetch; const url = `${distBaseUrl(context.env)}${path}`; try { return await fetchImpl(url, { headers: { authorization: `Bearer ${key}`, accept: "application/json, application/gzip" }, - signal: AbortSignal.timeout(timeoutMs), + signal, }); } catch (error) { throw new ScoutCliError(`Couldn't reach ${distBaseUrl(context.env)}: ${error instanceof Error ? error.message : String(error)}`); @@ -202,7 +206,12 @@ async function runInstall(context: ScoutCommandContext, args: string[], deps: Sc return; } - const response = await distRequest(context, deps, resolved.key, `/v1/dist/web-full/${encodeURIComponent(version)}`, DOWNLOAD_TIMEOUT_MS); + const timeoutMs = Number.isFinite(deps.downloadTimeoutMs) + ? Math.max(1, Math.min(DOWNLOAD_TIMEOUT_MS, deps.downloadTimeoutMs!)) : DOWNLOAD_TIMEOUT_MS; + // One budget covers headers, body consumption AND the file writer. Passing + // a signal only to fetch leaves a stalled stream/pipeline without a deadline. + const downloadSignal = AbortSignal.timeout(timeoutMs); + const response = await distRequest(context, deps, resolved.key, `/v1/dist/web-full/${encodeURIComponent(version)}`, timeoutMs, downloadSignal); if (!response.ok) { const body = await response.json().catch(() => null) as { error?: string } | null; const reason = explainFailure(response.status, body); @@ -223,7 +232,7 @@ async function runInstall(context: ScoutCommandContext, args: string[], deps: Sc const hash = createHash("sha256"); const source = Readable.fromWeb(response.body as unknown as NodeWebReadableStream); source.on("data", (chunk: Buffer) => hash.update(chunk)); - await pipeline(source, createWriteStream(tarball)); + await pipeline(source, createWriteStream(tarball), { signal: downloadSignal }); const actual = hash.digest("hex"); if (actual !== expected) { throw new ScoutCliError(`Checksum mismatch (expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…); not installing.`); @@ -231,8 +240,15 @@ async function runInstall(context: ScoutCommandContext, args: string[], deps: Sc const unpacked = join(workDirectory, "client"); mkdirSync(unpacked, { recursive: true }); - const tar = spawnSync("tar", ["-xzf", tarball, "-C", unpacked], { encoding: "utf8", timeout: 30_000, killSignal: "SIGKILL" }); - if (tar.status !== 0) throw new ScoutCliError(`Couldn't unpack the download: ${(tar.error?.message || tar.stderr || "tar failed").trim()}`); + // Keep extraction on the main event loop. On Bun 1.3.13/1.3.14, GC + // inside synchronous child execution can poison Linux stdio epoll entries. + try { + await promisify(execFile)("tar", ["-xzf", tarball, "-C", unpacked], { + encoding: "utf8", timeout: 30_000, killSignal: "SIGKILL", maxBuffer: 128 * 1024, + }); + } catch (error) { + throw new ScoutCliError(`Couldn't unpack the download: ${error instanceof Error ? error.message : String(error)}`); + } const profile = readWebFullClientProfile(unpacked); if (!existsSync(join(unpacked, "index.html")) || profile?.version !== version) { throw new ScoutCliError(`The download isn't the full web app for ${version}; not installing it.`); diff --git a/packages/cli/src/cli/web-api.test.ts b/packages/cli/src/cli/web-api.test.ts deleted file mode 100644 index 6816f62f..00000000 --- a/packages/cli/src/cli/web-api.test.ts +++ /dev/null @@ -1,100 +0,0 @@ -import { describe, expect, test } from "bun:test"; - -import { createScoutCommandContext } from "./context.ts"; -import { readScoutWebJson } from "./web-api.ts"; - -describe("readScoutWebJson", () => { - test("retries a loopback 401 with a bootstrapped session cookie", async () => { - const calls: Array<{ url: string; headers: Headers }> = []; - const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => { - const url = input instanceof Request ? input.url : String(input); - const headers = new Headers(init?.headers); - calls.push({ url, headers }); - if (url.endsWith("/api/bootstrap.js")) { - return new Response("window.__OPENSCOUT_WEB_BOOTSTRAP__ = {};", { - headers: { - "content-type": "application/javascript", - "set-cookie": "openscout_web_session=local-secret; Path=/; HttpOnly; SameSite=Strict", - }, - }); - } - if (!headers.has("cookie")) return Response.json({ error: "unauthorized" }, { status: 401 }); - return Response.json({ gauges: [] }); - }) as typeof fetch; - const context = createScoutCommandContext({ - env: { OPENSCOUT_WEB_URL: "http://127.0.0.1:43120" }, - }); - - const payload = await readScoutWebJson<{ gauges: unknown[] }>( - context, - "/api/service-budgets?refresh=1", - { fetchImpl }, - ); - - expect(payload).toEqual({ gauges: [] }); - expect(calls.map((call) => call.url)).toEqual([ - "http://127.0.0.1:43120/api/service-budgets?refresh=1", - "http://127.0.0.1:43120/api/bootstrap.js", - "http://127.0.0.1:43120/api/service-budgets?refresh=1", - ]); - expect(calls[0]?.headers.get("cookie")).toBeNull(); - expect(calls[2]?.headers.get("cookie")).toBe("openscout_web_session=local-secret"); - expect(calls[2]?.headers.get("authorization")).toBeNull(); - }); - - test("does not bootstrap when the first loopback request succeeds", async () => { - const calls: string[] = []; - const fetchImpl = (async (input: string | URL | Request) => { - calls.push(input instanceof Request ? input.url : String(input)); - return Response.json({ gauges: [] }); - }) as typeof fetch; - const context = createScoutCommandContext({ - env: { OPENSCOUT_WEB_URL: "http://127.0.0.1:43120" }, - }); - - await expect(readScoutWebJson(context, "/api/service-budgets", { fetchImpl })) - .resolves.toEqual({ gauges: [] }); - expect(calls).toEqual(["http://127.0.0.1:43120/api/service-budgets"]); - }); - - test("uses an explicit bearer for a configured non-loopback web URL", async () => { - const calls: Array<{ url: string; headers: Headers }> = []; - const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => { - calls.push({ - url: input instanceof Request ? input.url : String(input), - headers: new Headers(init?.headers), - }); - return Response.json({ ok: true }); - }) as typeof fetch; - const context = createScoutCommandContext({ - env: { - OPENSCOUT_WEB_URL: "https://scout.example", - OPENSCOUT_WEB_AUTH_TOKEN: "configured-secret", - }, - }); - - await expect(readScoutWebJson<{ ok: boolean }>(context, "/api/health", { fetchImpl })) - .resolves.toEqual({ ok: true }); - expect(calls).toHaveLength(1); - expect(calls[0]?.headers.get("authorization")).toBe("Bearer configured-secret"); - expect(calls[0]?.headers.get("cookie")).toBeNull(); - }); - - test("surfaces authenticated API error details", async () => { - const fetchImpl = (async (input: string | URL | Request) => { - const url = input instanceof Request ? input.url : String(input); - if (url.endsWith("/api/bootstrap.js")) { - return new Response("bootstrap", { - headers: { "set-cookie": "openscout_web_session=local-secret; Path=/" }, - }); - } - return Response.json({ error: "quota feed unavailable" }, { status: 503 }); - }) as typeof fetch; - const context = createScoutCommandContext({ - env: { OPENSCOUT_WEB_URL: "http://localhost:43120" }, - }); - - await expect(readScoutWebJson(context, "/api/service-budgets", { fetchImpl })) - .rejects.toThrow("Scout web API request failed: quota feed unavailable"); - }); -}); diff --git a/packages/cli/src/cli/web-api.ts b/packages/cli/src/cli/web-api.ts deleted file mode 100644 index 0439d7dd..00000000 --- a/packages/cli/src/cli/web-api.ts +++ /dev/null @@ -1,92 +0,0 @@ -import { resolveHost, resolveWebPort } from "@openscout/runtime/local-config"; - -import type { ScoutCommandContext } from "./context.ts"; -import { ScoutCliError } from "./errors.ts"; - -const SCOUT_WEB_AUTH_COOKIE = "openscout_web_session"; -const SCOUT_WEB_BOOTSTRAP_PATH = "/api/bootstrap.js"; -const LOOPBACK_IPV4_HOST_PATTERN = /^127(?:\.\d{1,3}){3}$/u; - -export function resolveScoutWebApiBaseUrl(env: NodeJS.ProcessEnv): string { - const configured = env.OPENSCOUT_WEB_URL?.trim() || env.SCOUT_WEB_URL?.trim(); - if (configured) return configured.replace(/\/+$/u, ""); - return `http://${resolveHost()}:${resolveWebPort()}`; -} - -export async function readScoutWebJson( - context: Pick, - path: string, - options: { fetchImpl?: typeof fetch } = {}, -): Promise { - return await (await readScoutWebResponse(context, path, options)).json() as T; -} - -export async function readScoutWebResponse( - context: Pick, - path: string, - options: { fetchImpl?: typeof fetch } = {}, -): Promise { - const baseUrl = resolveScoutWebApiBaseUrl(context.env); - const fetchImpl = options.fetchImpl ?? fetch; - const url = new URL(path, baseUrl); - const headers = new Headers({ accept: "application/json" }); - const authToken = context.env.OPENSCOUT_WEB_AUTH_TOKEN?.trim(); - if (authToken) { - headers.set("authorization", `Bearer ${authToken}`); - } - - let response = await fetchImpl(url, { headers }); - if (response.status === 401 && !authToken) { - const cookie = await readLocalScoutWebAuthCookie(fetchImpl, url); - if (cookie) { - headers.set("cookie", cookie); - response = await fetchImpl(url, { headers }); - } - } - if (!response.ok) { - let detail = `${response.status} ${response.statusText}`.trim(); - try { - const body = await response.json() as { error?: unknown }; - if (typeof body.error === "string" && body.error.trim()) detail = body.error.trim(); - } catch { - // Keep the HTTP status detail. - } - throw new ScoutCliError(`Scout web API request failed: ${detail}`); - } - return response; -} - -async function readLocalScoutWebAuthCookie( - fetchImpl: typeof fetch, - requestUrl: URL, -): Promise { - if (!isLoopbackScoutWebUrl(requestUrl)) return null; - - try { - const response = await fetchImpl(new URL(SCOUT_WEB_BOOTSTRAP_PATH, requestUrl), { - headers: { accept: "application/javascript" }, - }); - await response.text(); - if (!response.ok) return null; - return scoutWebCookieFromSetCookie(response.headers.get("set-cookie")); - } catch { - // Let the actual API request surface the normal connection/auth error. - return null; - } -} - -function isLoopbackScoutWebUrl(url: URL): boolean { - const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/gu, ""); - return hostname === "localhost" - || hostname === "0.0.0.0" - || hostname === "::1" - || LOOPBACK_IPV4_HOST_PATTERN.test(hostname); -} - -function scoutWebCookieFromSetCookie(value: string | null): string | null { - if (!value) return null; - const match = value.match(new RegExp(`(?:^|,\\s*)${SCOUT_WEB_AUTH_COOKIE}=([^;,\\r\\n]+)`, "u")); - return match?.[1] - ? `${SCOUT_WEB_AUTH_COOKIE}=${match[1]}` - : null; -} diff --git a/packages/cli/src/mcp/herdr-workspaces-runtime.test.ts b/packages/cli/src/mcp/herdr-workspaces-runtime.test.ts new file mode 100644 index 00000000..6587bcea --- /dev/null +++ b/packages/cli/src/mcp/herdr-workspaces-runtime.test.ts @@ -0,0 +1,176 @@ +import { expect, test } from "bun:test"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { digestHerdrTopology, type HerdrSessionTopology, type HerdrWorkspacesRead } from "@openscout/protocol"; +import { readHerdrWorkspaces } from "../../../runtime/src/broker-herdr-workspaces-read.ts"; +import type { HerdrSessionInfo } from "../../../runtime/src/system-probes/herdr.ts"; +import type { ProbeSnapshot } from "../../../runtime/src/system-probes/registry.ts"; +import { readRuntimeHerdrWorkspaces } from "./herdr-workspaces-runtime.ts"; +import { herdrWorkspacesDependencies, registerHerdrWorkspaceTools } from "./herdr-workspaces.ts"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; + +const path = "/v1/terminal-hosts/herdr/workspaces"; +const limits = { sessions: 8, enumeratedSessions: 256, workspacesPerSession: 16, tabsPerSession: 64, + inputPanesPerSession: 256, emittedPanesPerSession: 40, leadsPerSession: 12, concurrentSessions: 2 }; +function topology(session = "alpha"): HerdrSessionTopology { + return { session, running: true, observedAt: 123, workspaces: [{ workspaceId: "w1", label: "Work", number: 1, + focused: true, activeTabId: "t1", agentStatus: "blocked", tabs: [{ tabId: "t1", workspaceId: "w1", label: "Tab", + number: 1, focused: true, agentStatus: "blocked", layout: null, panes: [{ paneId: "p1", terminalId: "T1", + workspaceId: "w1", tabId: "t1", name: "panel", label: "Title", agent: "codex", agentStatus: "blocked", + agentSession: { agent: "codex", kind: "id", source: "herdr", value: "Case/Native" }, cwd: "/work", + foregroundCwd: null, focused: true, scroll: null }] }] }] }; +} +function value(overrides: Partial = {}): HerdrWorkspacesRead { + return { schema: "scout.herdr-workspaces/v1", nodeId: "node-one", scannedAt: 100, availability: "available", + reason: null, requestedSession: null, count: 1, digests: [{ ...digestHerdrTopology(topology()), availability: "available" }], + truncated: false, coverage: { kind: "ttl_cached_probes", scope: "this_host_only", listedSessions: 1, limits }, ...overrides }; +} +const fetcher = (fn: (...args: Parameters) => ReturnType): typeof fetch => Object.assign(fn, { preconnect() {} }); +const read = (response: Response, session?: string) => readRuntimeHerdrWorkspaces({ session, + env: { OPENSCOUT_BROKER_URL: "http://localhost:1" }, fetchImpl: fetcher(async () => response) }); + +test("one selected local broker GET carries no web cookie, bearer, origin or forwarding authority", async () => { + let calls = 0; + const result = await readRuntimeHerdrWorkspaces({ session: "Space & Case", env: { OPENSCOUT_BROKER_URL: "http://localhost:43121/base", + OPENSCOUT_WEB_URL: "https://must-not-use.invalid", OPENSCOUT_WEB_AUTH_TOKEN: "must-not-send" }, + fetchImpl: fetcher(async (input, init) => { + calls++; const url = new URL(String(input)); expect(url.pathname).toBe(path); + expect(url.searchParams.get("session")).toBe("Space & Case"); + expect(init).toMatchObject({ method: "GET", credentials: "omit", redirect: "error" }); + expect(init?.signal).toBeInstanceOf(AbortSignal); + for (const header of ["authorization", "cookie", "origin", "x-openscout-forwarded-node-id"]) expect(new Headers(init?.headers).get(header)).toBeNull(); + return Response.json(value({ requestedSession: "Space & Case", digests: [{ ...value().digests[0]!, session: "Space & Case" }] })); + }) }); + expect(result.requestedSession).toBe("Space & Case"); expect(calls).toBe(1); +}); + +test("actual runtime projection preserves live, saved, unavailable, partial and available-empty observations", async () => { + const snapshot: ProbeSnapshot = { id: "herdr.sessions", value: [{ name: "alpha", running: true, isDefault: false, sessionDir: "/fixture-only" }], + at: 100, ageMs: 0, stale: false, refreshing: false, status: "fresh", error: null, consecutiveFailures: 0, backend: "local" }; + for (const kind of ["live", "saved", "unavailable", "empty", "not_scanned", "list_failed", "partial"] as const) { + const projected = await readHerdrWorkspaces({ nodeId: "node-one", sessions: async () => kind === "empty" ? { ...snapshot, value: [] } + : kind === "not_scanned" ? { ...snapshot, at: null, value: null, status: "empty" } + : kind === "list_failed" ? { ...snapshot, status: "failed" } : kind === "partial" ? { ...snapshot, stale: true } : snapshot, + topology: async () => { + if (kind === "unavailable") throw Error("fixture-only"); + return { topology: kind === "saved" ? { ...topology(), running: false, savedAt: 90, unavailable: "not_running" } : topology(), + availability: kind === "saved" ? "partial" : "available" }; + } }, new URL("http://localhost" + path)); + expect(projected.status).toBe(200); + if (!("schema" in projected.body)) throw Error("expected a runtime observation"); + const parsed = await read(Response.json(projected.body)); expect(parsed).toEqual(projected.body); + if (kind === "saved") expect(parsed.digests[0]!.groups[0]!.panes[0]).toMatchObject({ target: null, status: "unknown" }); + } +}); + +test.each([401, 403, 404, 409, 503])("HTTP %i preserves safe status/code without retry or cookie bootstrap", async status => { + let calls = 0; + await expect(readRuntimeHerdrWorkspaces({ env: { OPENSCOUT_BROKER_URL: "http://localhost:1" }, fetchImpl: fetcher(async () => { + calls++; return Response.json({ error: "herdr_session_not_listed", detail: "private body" }, { status }); + }) })).rejects.toMatchObject({ status, code: "herdr_session_not_listed" }); + expect(calls).toBe(1); +}); + +test("actual maximum distinct-directory groups fit even when most panes were omitted", async () => { + const input = topology(); const p = input.workspaces[0]!.tabs[0]!.panes[0]!; + input.workspaces[0]!.tabs[0]!.panes = Array.from({ length: 300 }, (_, i) => ({ ...p, paneId: `p${i}`, cwd: `/dir/${i}` })); + const projected = await readHerdrWorkspaces({ nodeId: "node-one", sessions: async () => ({ id: "herdr.sessions", + value: [{ name: "alpha", running: true, isDefault: false, sessionDir: "/fixture" }], at: 100, ageMs: 0, + stale: false, refreshing: false, status: "fresh", error: null, consecutiveFailures: 0, backend: "local" }), + topology: async () => ({ topology: input, availability: "available" }) }, new URL("http://localhost" + path)); + if (!("schema" in projected.body)) throw Error("expected a runtime observation"); + expect(projected.body.digests[0]!.groups).toHaveLength(256); + const result = await read(Response.json(projected.body)); expect(result).toEqual(projected.body); + expect(result.digests[0]!.groups.flatMap(g => g.panes)).toHaveLength(40); + expect(result.truncated).toBe(true); +}); + +test("non-JSON denial preserves status without reflecting raw server text", async () => { + await expect(read(new Response("SECRET", { status: 403 }))).rejects.toMatchObject({ status: 403, code: "herdr_workspaces_unavailable" }); +}); + +test("scope, schema, count, session binding, duplicate and nested malformed responses refuse", async () => { + const v = value(), d = v.digests[0]!; + for (const bad of [{}, { ...v, schema: "other" }, { ...v, count: 0 }, { ...v, nodeId: "" }, + { ...v, coverage: { ...v.coverage, scope: "fleet" } }, { ...v, digests: [d, d], count: 2 }, + { ...v, digests: [{ ...d, live: true, savedAt: 90 }] }, { ...v, digests: [{ ...d, groups: [{ ...d.groups[0], panes: [{}] }] }] }, + { ...v, digests: [{ ...d, session: "../outside" }] }, { ...v, availability: "not_scanned" }, + { ...v, digests: [{ ...d, live: false }] }, { ...v, digests: [{ ...d, notes: Array(129).fill("x") }] }, + { ...v, digests: Array(9).fill(d), count: 9 }, { ...v, credential: "never accept" }]) { + await expect(read(Response.json(bad))).rejects.toMatchObject({ code: "invalid_herdr_workspaces_response" }); + } + await expect(read(Response.json(v), "alpha")).rejects.toThrow(); + await expect(read(Response.json({ ...v, requestedSession: "alpha", digests: [{ ...d, session: "beta" }] }), "alpha")).rejects.toThrow(); +}); + +test("declared/streamed oversize, invalid UTF8 and redirects refuse and cancel their streams", async () => { + for (const response of [new Response("small", { headers: { "content-length": "2097153" } }), new Response("x".repeat(2097153)), + new Response(new Uint8Array([0xff])), new Response(null, { status: 302, headers: { location: "https://must-not-use.invalid" } })]) { + await expect(read(response)).rejects.toMatchObject({ code: "invalid_herdr_workspaces_response" }); + } + let cancelled = false; + const stream = new ReadableStream({ start(controller) { controller.enqueue(new Uint8Array(2097153)); }, cancel() { cancelled = true; } }); + await expect(read(new Response(stream))).rejects.toThrow(); expect(cancelled).toBe(true); +}); + +test("invalid local authority, selectors and socket-only configuration refuse before any request", async () => { + let calls = 0; const fetchImpl = fetcher(async () => { calls++; throw Error("must not fetch"); }); + for (const url of ["https://remote.invalid", "http://user:secret@localhost", "file:///tmp/no", "not a url", "http://127.1", "http://2130706433"]) + await expect(readRuntimeHerdrWorkspaces({ env: { OPENSCOUT_BROKER_URL: url }, fetchImpl })).rejects.toThrow(); + for (const session of ["", " ", "..", "../outside", "a/b", "a\\b", "a\0b", "x".repeat(129)]) + await expect(readRuntimeHerdrWorkspaces({ session, env: { OPENSCOUT_BROKER_URL: "http://localhost:1" }, fetchImpl })).rejects.toThrow(); + await expect(readRuntimeHerdrWorkspaces({ env: { OPENSCOUT_BROKER_URL: "http://localhost:1", OPENSCOUT_BROKER_SOCKET_ONLY: "1" }, fetchImpl })).rejects.toMatchObject({ code: "broker_socket_required" }); + expect(calls).toBe(0); +}); + +test("the actual Unix socket wins and an absent socket cannot fall back to an HTTP trap", async () => { + const root = mkdtempSync(join(tmpdir(), "herdr_read_")); const socket = join(root, "control.sock"); + let httpCalls = 0, socketCalls = 0; + const trap = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch() { httpCalls++; return Response.json(value()); } }); + const server = Bun.serve({ unix: socket, fetch(request) { socketCalls++; expect(new URL(request.url).pathname).toBe(path); return Response.json(value()); } }); + try { + expect(await readRuntimeHerdrWorkspaces({ env: { OPENSCOUT_BROKER_URL: trap.url.origin, OPENSCOUT_BROKER_SOCKET_PATH: socket } })).toEqual(value()); + await expect(readRuntimeHerdrWorkspaces({ env: { OPENSCOUT_BROKER_URL: trap.url.origin, OPENSCOUT_BROKER_SOCKET_PATH: join(root, "absent.sock") } })).rejects.toThrow(); + expect(httpCalls).toBe(0); expect(socketCalls).toBe(1); + } finally { await server.stop(true); await trap.stop(true); rmSync(root, { recursive: true, force: true }); } +}); + +test("real HTTP redirect does not reach its target", async () => { + let targetCalls = 0; + const target = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch() { targetCalls++; return Response.json(value()); } }); + const redirect = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch() { return new Response(null, { status: 302, headers: { location: target.url.origin } }); } }); + try { await expect(readRuntimeHerdrWorkspaces({ env: { OPENSCOUT_BROKER_URL: redirect.url.origin } })).rejects.toThrow(); expect(targetCalls).toBe(0); } + finally { await redirect.stop(true); await target.stop(true); } +}); + +test("MCP preserves runtime availability/coverage and never upgrades missing observations into absence", async () => { + for (const availability of ["not_scanned", "unavailable", "partial", "available"] as const) { + const reply = value({ availability, scannedAt: availability === "not_scanned" ? null : 100, + reason: availability === "not_scanned" ? "not_scanned" : null, count: 0, digests: [] }); + const server = new McpServer({ name: "fixture", version: "1" }); + registerHerdrWorkspaceTools(server, herdrWorkspacesDependencies({ env: { OPENSCOUT_BROKER_URL: "http://localhost:1" }, fetchImpl: fetcher(async () => Response.json(reply)) })); + const client = new Client({ name: "fixture", version: "1" }); const [a, b] = InMemoryTransport.createLinkedPair(); + try { + await Promise.all([client.connect(a), server.connect(b)]); + for (const args of [{}, { query: "missing" }]) { + const result = await client.callTool({ name: "herdr_workspaces", arguments: args }); + expect(result.structuredContent).toMatchObject({ available: availability === "available" || availability === "partial", + runtimeRead: { schema: "scout.herdr-workspaces/v1", nodeId: "node-one", availability, scannedAt: reply.scannedAt } }); + if (availability !== "available") expect(JSON.stringify(result.content)).not.toContain("No herdr sessions on this host."); + } + } finally { await client.close(); await server.close(); } + } +}); + +test("the retired browser-cookie adapter is absent and its named inventory exception cannot return", () => { + const inventory = JSON.parse(readFileSync(new URL("../../temporary-private-files.json", import.meta.url), "utf8")); + expect(inventory.sources.some((row: { source: string }) => row.source === "packages/cli/src/cli/web-api.ts")).toBe(false); + expect(inventory.removedSources).toContain("packages/cli/src/cli/web-api.ts"); + const source = readFileSync(new URL("./herdr-workspaces.ts", import.meta.url), "utf8"); + expect(source).not.toContain("web-api"); expect(source).not.toContain("/api/terminal-hosts"); + const factory = readFileSync(new URL("./scout-mcp.ts", import.meta.url), "utf8"); + expect(factory).toContain("herdrWorkspacesDependencies({ env })"); +}); diff --git a/packages/cli/src/mcp/herdr-workspaces-runtime.ts b/packages/cli/src/mcp/herdr-workspaces-runtime.ts new file mode 100644 index 00000000..c9c69ed3 --- /dev/null +++ b/packages/cli/src/mcp/herdr-workspaces-runtime.ts @@ -0,0 +1,129 @@ +import * as z from "zod/v4"; +import type { HerdrWorkspacesRead } from "@openscout/protocol"; +import { resolveBrokerControlUrl } from "@openscout/runtime/local-config"; + +const availability = z.enum(["not_scanned", "available", "unavailable", "partial"]); +const integer = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER); +const id = z.string().min(1).max(1024).regex(/^[^\x00-\x1f\x7f]+$/u); +const session = z.string().min(1).max(128).refine(value => value === value.trim() + && value !== "." && value !== ".." && !/[/\\\x00-\x1f\x7f]/u.test(value)); +const text = z.string().max(4096); +const counts = z.object({ blocked: integer, working: integer, idle: integer, done: integer, unknown: integer }).strict(); +const pane = z.object({ + target: id.nullable(), paneId: id, workspaceId: id, tabId: id, + name: text.nullable().optional(), label: text.nullable(), + agentSession: z.object({ agent: id, kind: id, source: id, value: text }).strict().nullable().optional(), + agent: text.nullable(), status: z.enum(["idle", "working", "blocked", "done", "unknown"]), + directory: text.nullable(), focused: z.boolean(), backlog: integer.nullable(), +}).strict(); +const digest = z.object({ + session, live: z.boolean(), observedAt: z.number().finite(), savedAt: z.number().finite().nullable(), + unavailable: z.enum(["not_running", "unreadable"]).nullable(), availability, + totals: z.object({ workspaces: integer, tabs: integer, panes: integer, agents: integer }).strict(), counts, + needsYou: z.array(pane).max(12), working: z.array(pane).max(12), + groups: z.array(z.object({ directory: text.nullable(), name: text, counts, + panes: z.array(pane).max(40), omitted: integer, omittedCounts: counts }).strict()).max(256), + shapes: z.array(z.object({ workspaceId: id, workspaceLabel: text, tabId: id, tabLabel: text, + paneCount: integer, arrangement: text, zoomed: z.boolean(), focused: z.boolean() }).strict()).max(64), + truncated: z.boolean(), notes: z.array(text).max(128), +}).strict(); +const schema = z.object({ + schema: z.literal("scout.herdr-workspaces/v1"), nodeId: id, scannedAt: z.number().finite().nullable(), + availability, reason: z.enum(["not_scanned", "session_list_unavailable"]).nullable(), + requestedSession: session.nullable(), count: integer.max(8), digests: z.array(digest).max(8), truncated: z.boolean(), + coverage: z.object({ kind: z.literal("ttl_cached_probes"), scope: z.literal("this_host_only"), + listedSessions: integer.nullable(), limits: z.object({ + sessions: z.literal(8), enumeratedSessions: z.literal(256), workspacesPerSession: z.literal(16), + tabsPerSession: z.literal(64), inputPanesPerSession: z.literal(256), emittedPanesPerSession: z.literal(40), + leadsPerSession: z.literal(12), concurrentSessions: z.literal(2), + }).strict(), + }).strict(), +}).strict(); + +export class HerdrWorkspacesReadError extends Error { + constructor(readonly status: number | null, readonly code: string) { + super(`Herdr workspaces unavailable: ${code}${status === null ? "" : ` (HTTP ${status})`}.`); + } +} +const invalid = () => new HerdrWorkspacesReadError(null, "invalid_herdr_workspaces_response"); + +function validate(value: unknown, requestedSession: string | undefined): HerdrWorkspacesRead { + const parsed = schema.safeParse(value); + if (!parsed.success) throw invalid(); + const result = parsed.data; + if (result.requestedSession !== (requestedSession ?? null) || result.count !== result.digests.length) throw invalid(); + const names = new Set(); + for (const row of result.digests) { + if (names.has(row.session) || requestedSession !== undefined && row.session !== requestedSession) throw invalid(); + names.add(row.session); + const panes = row.groups.flatMap(group => group.panes); + if (panes.length > 40 || new Set(panes.map(p => JSON.stringify([p.workspaceId, p.paneId]))).size !== panes.length + || row.live && (row.savedAt !== null || row.unavailable !== null) + || !row.live && [...panes, ...row.needsYou, ...row.working].some(p => p.target !== null || p.status !== "unknown")) throw invalid(); + } + if (result.availability === "not_scanned" && result.digests.length) throw invalid(); + if (result.availability === "available" && (result.reason !== null || result.scannedAt === null + || result.digests.some(row => row.availability !== "available"))) throw invalid(); + return result; +} + +/** Read the selected machine-local broker once. A selected socket never falls + * back to HTTP. No web auth/bootstrap, local Herdr probe, app start or retry. + * The broker owns its TTL-cached probes and reports their coverage explicitly. */ +export async function readRuntimeHerdrWorkspaces(options: { + env?: NodeJS.ProcessEnv; fetchImpl?: typeof fetch; session?: string; +} = {}): Promise { + if (options.session !== undefined && !session.safeParse(options.session).success) + throw new HerdrWorkspacesReadError(null, "invalid_herdr_session"); + const env = options.env ?? process.env; + const configured = env.OPENSCOUT_BROKER_URL?.trim() || resolveBrokerControlUrl(); + // URL normalizes abbreviated/numeric IPv4 spellings. Require a literal + // supported loopback authority before normalization, as the ingress promises. + if (!/^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?(?:[/?#]|$)/iu.test(configured)) + throw new HerdrWorkspacesReadError(null, "local_broker_required"); + let origin: URL; + try { origin = new URL(configured); } + catch { throw new HerdrWorkspacesReadError(null, "local_broker_required"); } + if (!["http:", "https:"].includes(origin.protocol) || origin.username || origin.password + || !["localhost", "127.0.0.1", "[::1]"].includes(origin.hostname)) + throw new HerdrWorkspacesReadError(null, "local_broker_required"); + const socketPath = env.OPENSCOUT_BROKER_SOCKET_PATH?.trim(); + if (env.OPENSCOUT_BROKER_SOCKET_ONLY === "1" && !socketPath) + throw new HerdrWorkspacesReadError(null, "broker_socket_required"); + const url = new URL("/v1/terminal-hosts/herdr/workspaces", origin); + if (options.session !== undefined) url.searchParams.set("session", options.session); + // One signal covers both response headers and body consumption. + const signal = AbortSignal.timeout(8_000); + let response: Response; + try { + response = await (options.fetchImpl ?? fetch)(url, { + method: "GET", headers: { accept: "application/json" }, credentials: "omit", redirect: "error", signal, + ...(socketPath ? { unix: socketPath } : {}), + }); + } catch { throw new HerdrWorkspacesReadError(null, "herdr_workspaces_unavailable"); } + const reader = response.body?.getReader(); + try { + const maxBytes = 2 * 1024 * 1024; + if (response.redirected || response.status >= 300 && response.status < 400 + || Number(response.headers.get("content-length")) > maxBytes) throw invalid(); + const chunks: Uint8Array[] = []; let size = 0; + if (reader) while (true) { + const chunk = await reader.read(); if (chunk.done) break; + size += chunk.value.byteLength; if (size > maxBytes) throw invalid(); chunks.push(chunk.value); + } + let payload: unknown; + try { payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks))); } + catch { + if (response.status !== 200) throw new HerdrWorkspacesReadError(response.status, "herdr_workspaces_unavailable"); + throw invalid(); + } + if (response.status !== 200) { + const error = z.object({ error: z.string().regex(/^[a-z_]{1,128}$/u) }).safeParse(payload); + throw new HerdrWorkspacesReadError(response.status, error.success ? error.data.error : "herdr_workspaces_unavailable"); + } + return validate(payload, options.session); + } catch (error) { + if (error instanceof HerdrWorkspacesReadError) throw error; + throw invalid(); + } finally { await reader?.cancel().catch(() => {}); reader?.releaseLock(); } +} diff --git a/packages/cli/src/mcp/herdr-workspaces.test.ts b/packages/cli/src/mcp/herdr-workspaces.test.ts index 864c36aa..f3760200 100644 --- a/packages/cli/src/mcp/herdr-workspaces.test.ts +++ b/packages/cli/src/mcp/herdr-workspaces.test.ts @@ -170,28 +170,39 @@ describe("herdr_workspaces", () => { }); describe("herdrWorkspacesDependencies", () => { - test("asks the web server for the digest and never shells herdr itself", async () => { + test("asks only the selected broker and snapshots its environment", async () => { const seen: string[] = []; - const deps = herdrWorkspacesDependencies("http://localhost:43120", { - env: {}, - fetchImpl: (async (input: unknown) => { + const env = { OPENSCOUT_BROKER_URL: "http://localhost:43121", OPENSCOUT_WEB_URL: "https://web-must-not-be-used.invalid" }; + const deps = herdrWorkspacesDependencies({ env, + fetchImpl: Object.assign(async (input: Parameters[0]) => { seen.push(String(input)); - return new Response(JSON.stringify({ ok: true, digests: [], truncated: true }), { - status: 200, - headers: { "content-type": "application/json" }, - }); - }) as unknown as typeof fetch, + return Response.json({ schema: "scout.herdr-workspaces/v1", nodeId: "node-one", scannedAt: 100, + availability: "partial", reason: null, requestedSession: "openscout", count: 0, digests: [], truncated: true, + coverage: { kind: "ttl_cached_probes", scope: "this_host_only", listedSessions: 1, + limits: { sessions: 8, enumeratedSessions: 256, workspacesPerSession: 16, tabsPerSession: 64, + inputPanesPerSession: 256, emittedPanesPerSession: 40, leadsPerSession: 12, concurrentSessions: 2 } } }); + }, { preconnect() {} }) as typeof fetch, }); - const result = await deps.readDigests("openscout"); - expect(seen[0]).toBe("http://localhost:43120/api/terminal-hosts/herdr/workspaces?session=openscout"); - expect(result).toEqual({ digests: [], truncated: true, available: true }); + env.OPENSCOUT_BROKER_URL = "https://changed.invalid"; + expect(await deps.readDigests("openscout")).toMatchObject({ digests: [], truncated: true, available: true, + runtimeRead: { nodeId: "node-one", availability: "partial", requestedSession: "openscout", sessions: [] } }); + expect(seen).toEqual(["http://localhost:43121/v1/terminal-hosts/herdr/workspaces?session=openscout"]); }); - test("a failed read is unavailable, not empty", async () => { - const deps = herdrWorkspacesDependencies("http://localhost:43120", { - env: {}, - fetchImpl: (async () => new Response("nope", { status: 500 })) as unknown as typeof fetch, + test("a failed read is unavailable, with safe HTTP status and no web fallback", async () => { + let calls = 0; + const deps = herdrWorkspacesDependencies({ env: { OPENSCOUT_BROKER_URL: "http://localhost:43121" }, + fetchImpl: Object.assign(async () => { calls++; return Response.json({ error: "local_only", detail: "do-not-reflect" }, { status: 403 }); }, { preconnect() {} }) as typeof fetch, }); - expect(await deps.readDigests()).toEqual({ digests: [], truncated: false, available: false }); + expect(await deps.readDigests()).toEqual({ digests: [], truncated: false, available: false, + readError: { status: 403, code: "local_only" } }); + expect(calls).toBe(1); + }); + + test("partial empty observations never claim there are no sessions", async () => { + const client = await clientFor(dependencies({ readDigests: async () => ({ digests: [], available: true, truncated: true }) })); + const result = await client.callTool({ name: "herdr_workspaces", arguments: {} }); + expect((result.content as Array<{ text: string }>)[0]!.text).toContain("incomplete observation"); + expect(result.structuredContent).toMatchObject({ available: true, truncated: true }); }); }); diff --git a/packages/cli/src/mcp/herdr-workspaces.ts b/packages/cli/src/mcp/herdr-workspaces.ts index a1bfe7f5..01547793 100644 --- a/packages/cli/src/mcp/herdr-workspaces.ts +++ b/packages/cli/src/mcp/herdr-workspaces.ts @@ -4,9 +4,10 @@ import { renderHerdrWorkspaceDigest, type HerdrDigestPane, type HerdrWorkspaceDigest, + type HerdrWorkspacesRead, } from "@openscout/protocol"; -import { readScoutWebJson } from "../cli/web-api.ts"; +import { HerdrWorkspacesReadError, readRuntimeHerdrWorkspaces } from "./herdr-workspaces-runtime.ts"; /** * `herdr_workspaces` — the read side of Scout's herdr coordination layer. @@ -14,7 +15,7 @@ import { readScoutWebJson } from "../cli/web-api.ts"; * Herdr owns workspaces, tabs and panes; Scout coordinates over whatever host * is present and never becomes a second layout manager. So this tool reads a * ranked digest and stops there. It has no mutation verb, and it deliberately - * does not shell `herdr` itself: the web server already owns that probe and its + * does not shell `herdr` itself: the broker already owns that probe and its * cache, and a caller that cannot reach the server should learn that rather * than quietly open a second path to the same binary. * @@ -29,6 +30,10 @@ export type HerdrWorkspacesDependencies = { digests: HerdrWorkspaceDigest[]; truncated: boolean; available: boolean; + runtimeRead?: Omit & { + sessions: Array<{ session: string; availability: HerdrWorkspacesRead["availability"] }>; + }; + readError?: { status: number | null; code: string }; }>; }; @@ -66,29 +71,22 @@ export function matchesHerdrPanel(panel: HerdrPanelIdentity, query: string): boo } export function herdrWorkspacesDependencies( - webOrigin: string, options: { env?: NodeJS.ProcessEnv; fetchImpl?: typeof fetch } = {}, ): HerdrWorkspacesDependencies { - const fetchImpl = options.fetchImpl ?? fetch; - const boundedFetch = ((input: Parameters[0], init?: Parameters[1]) => - fetchImpl(input, { ...init, signal: AbortSignal.timeout(8_000) })) as typeof fetch; - const context = { env: { ...(options.env ?? process.env), OPENSCOUT_WEB_URL: webOrigin } }; + const env = { ...(options.env ?? process.env) }; return { readDigests: async (session) => { - const path = session - ? `/api/terminal-hosts/herdr/workspaces?session=${encodeURIComponent(session)}` - : "/api/terminal-hosts/herdr/workspaces"; try { - const result = await readScoutWebJson<{ - digests?: HerdrWorkspaceDigest[]; - truncated?: boolean; - }>(context, path, { fetchImpl: boundedFetch }); - if (!Array.isArray(result.digests)) return { digests: [], truncated: false, available: false }; - return { digests: result.digests, truncated: result.truncated === true, available: true }; - } catch { - // Herdr not installed, or the web server unreachable. Both are "we - // cannot answer", which is a different claim from "no workspaces". - return { digests: [], truncated: false, available: false }; + const { digests, ...metadata } = await readRuntimeHerdrWorkspaces({ ...options, env, session }); + return { + digests, available: ["available", "partial"].includes(metadata.availability), + truncated: metadata.truncated || metadata.availability === "partial", + runtimeRead: { ...metadata, sessions: digests.map(({ session, availability }) => ({ session, availability })) }, + }; + } catch (error) { + return { digests: [], truncated: false, available: false, + readError: { status: error instanceof HerdrWorkspacesReadError ? error.status : null, + code: error instanceof HerdrWorkspacesReadError ? error.code : "herdr_workspaces_unavailable" } }; } }, }; @@ -114,13 +112,15 @@ export function registerHerdrWorkspaceTools(server: McpServer, deps: HerdrWorksp }), annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false }, }, async ({ session, query, limit }) => { - const { digests, truncated, available } = await deps.readDigests(session); + const { digests, truncated, available, runtimeRead, readError } = await deps.readDigests(session); + const provenance = { ...(runtimeRead ? { runtimeRead } : {}), ...(readError ? { readError } : {}) }; if (!available) { const structuredContent = { source: "herdr_topology_projection", available: false, reason: "herdr_unavailable", - note: "Could not read herdr on this host: it may not be installed, or the Scout web server is unreachable. This is not evidence that there are no workspaces.", + note: "Could not read an available Herdr observation from the local broker. The broker or host probes may be unavailable or not scanned. This is not evidence that there are no workspaces.", + ...provenance, sessions: [] as HerdrWorkspaceDigest[], }; return { content: [{ type: "text" as const, text: structuredContent.note }], structuredContent }; @@ -134,6 +134,7 @@ export function registerHerdrWorkspaceTools(server: McpServer, deps: HerdrWorksp source: "herdr_topology_projection", available: true, coverage: "this_host_only", query, truncated: bounded, candidateCount: candidates.length, selection: "candidates_only", results, + ...provenance, note: "Names are Herdr panel labels, not Scout addresses. Session references are reported by Herdr, not independently verified against transcripts. Idle is ready for input, not proof of completed work. Recheck the mapping before reading if the pane has changed since observedAt. A bounded miss is not proof of absence; scope by Herdr session to narrow coverage.", }; return { content: [{ type: "text" as const, text: JSON.stringify(structuredContent) }], structuredContent }; @@ -148,13 +149,14 @@ export function registerHerdrWorkspaceTools(server: McpServer, deps: HerdrWorksp const sessions = ordered.slice(0, limit); const text = sessions.length ? sessions.map(renderHerdrWorkspaceDigest).join("\n\n") - : "No herdr sessions on this host."; + : truncated ? "No herdr sessions in this incomplete observation; absence is not established." : "No herdr sessions on this host."; const structuredContent = { source: "herdr_topology_projection", available: true, coverage: "this_host_only", truncated: truncated || ordered.length > sessions.length || sessions.some((digest) => digest.truncated), sessions, + ...provenance, }; return { content: [{ type: "text" as const, text }], structuredContent }; }); diff --git a/packages/cli/src/mcp/scout-mcp.ts b/packages/cli/src/mcp/scout-mcp.ts index aca40240..268d2a55 100644 --- a/packages/cli/src/mcp/scout-mcp.ts +++ b/packages/cli/src/mcp/scout-mcp.ts @@ -3279,7 +3279,7 @@ export function createScoutMcpServer(options: { registerRouteContext(server, routeContextDependencies({ brokerUrl: deps.resolveBrokerUrl() }), !toolFilter || (toolFilter("route_context") && toolFilter("ask"))); registerSessionDiscoveryTools(server, sessionDiscoveryDependencies(resolveScoutWebOrigin(env), { env })); - registerHerdrWorkspaceTools(server, herdrWorkspacesDependencies(resolveScoutWebOrigin(env), { env })); + registerHerdrWorkspaceTools(server, herdrWorkspacesDependencies({ env })); registerSessionSendTool(server, sessionSendDependencies(env)); registerFlightCancelTool(server, id => cancelScoutFlight(deps.resolveBrokerUrl(), id)); registerAttachmentReaderTool(server, { diff --git a/packages/cli/temporary-private-files.json b/packages/cli/temporary-private-files.json index e18de749..73849891 100644 --- a/packages/cli/temporary-private-files.json +++ b/packages/cli/temporary-private-files.json @@ -386,12 +386,6 @@ "package/dist/main.mjs" ] }, - { - "source": "packages/cli/src/cli/web-api.ts", - "packagedDestinations": [ - "package/dist/main.mjs" - ] - }, { "source": "packages/cli/src/lib/core/setup/service.ts", "packagedDestinations": [ @@ -4582,7 +4576,8 @@ ], "removedSources": [ "apps/desktop/src/core/setup/local-edge-dependencies.ts", - "apps/desktop/src/core/setup/terminal-pty-dependencies.ts" + "apps/desktop/src/core/setup/terminal-pty-dependencies.ts", + "packages/cli/src/cli/web-api.ts" ], "removedOutputs": [] } diff --git a/scripts/check-cli-private-inventory.test.mjs b/scripts/check-cli-private-inventory.test.mjs index 306763ed..c99cd681 100644 --- a/scripts/check-cli-private-inventory.test.mjs +++ b/scripts/check-cli-private-inventory.test.mjs @@ -20,3 +20,4 @@ test('same filenames cannot hide substituted bundle bytes',()=>assert.match(chec for (const p of ['apps/desktop/src/core/setup/local-edge-dependencies.ts', 'apps/desktop/src/core/setup/terminal-pty-dependencies.ts']) { test(`retired readiness input cannot return: ${p}`, () => assert.match(check({...expected,removedSources:[p]}, {...observed,sources:[source,{...source,source:p}]}, expected.packedFiles).join('\n'), /Removed private source returned/)); } +test('removed private source cannot return inside an existing bundle',()=>assert.match(check({...expected,removedSources:[source.source]},observed,expected.packedFiles).join('\n'),/Removed private source returned/)); diff --git a/scripts/extension-channel-fence-inventory.json b/scripts/extension-channel-fence-inventory.json index 1d33e36d..60d0dc90 100644 --- a/scripts/extension-channel-fence-inventory.json +++ b/scripts/extension-channel-fence-inventory.json @@ -196,6 +196,35 @@ "reason": "PR #100 adds bounded isolated setup/doctor regression fixtures for core readiness. This test-only allowance does not permit production synchronous spawning or private app dependencies." } ] + }, + { + "id": "pr-95-async-web-install", + "sourceHead": "f3bf9527705b102f2b46f68ea3cb53af83c7a710", + "reason": "PR #95 replaces synchronous web-install extraction with bounded async spawning. Two obsolete spawnSync pairs retire; one child-only Bun.spawnSync regression fixture is added. No other policy entry changes. This transition follows the separately accounted PR #100 core-readiness fixture addition; that pair remains unchanged.", + "fromCount": 175, + "toCount": 174, + "retired": [ + { + "path": "packages/cli/src/cli/commands/web.ts", + "symbol": "spawnSync", + "policySha256": "788cab900901b09cb28f5d2a3c36ed6198b64f055b1729fc05c3cd3f4a9719a2", + "reason": "PR #95 removes the synchronous production web-install tar extraction and retires this spawnSync allowance." + }, + { + "path": "packages/cli/src/cli/commands/web.test.ts", + "symbol": "spawnSync", + "policySha256": "bdae1b073d30957f80a62fa271b72cd42355ffe567ed3ce3b835552ef844f9bb", + "reason": "PR #95 uses async tar fixture helpers in the web-install tests, retiring this spawnSync allowance." + } + ], + "added": [ + { + "path": "packages/cli/src/cli/commands/fixtures/web-stdio.ts", + "symbol": "Bun.spawnSync", + "policySha256": "3e407ac66cce75c4139ec54af0ef8f1f494d3f6e2e1fe5171ea2dc92d2a8e160", + "reason": "New child-only regression fixture forces GC during the legacy synchronous native-call negative control; production installation does not use it." + } + ] } ] } diff --git a/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/fixtures/web-stdio.ts/Bun.spawnSync.json b/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/fixtures/web-stdio.ts/Bun.spawnSync.json new file mode 100644 index 00000000..a8098888 --- /dev/null +++ b/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/fixtures/web-stdio.ts/Bun.spawnSync.json @@ -0,0 +1,7 @@ +{ + "path": "packages/cli/src/cli/commands/fixtures/web-stdio.ts", + "symbol": "Bun.spawnSync", + "category": "test", + "reason": "Child-only Linux regression intercepts legacy synchronous extraction to force GC during the native call; never used by production installation", + "owner": "desktop" +} diff --git a/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/web.test.ts/spawnSync.json b/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/web.test.ts/spawnSync.json deleted file mode 100644 index 284a24b5..00000000 --- a/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/web.test.ts/spawnSync.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "path": "packages/cli/src/cli/commands/web.test.ts", - "symbol": "spawnSync", - "category": "test", - "reason": "packs and lists test tarballs for the `scout web install` tests", - "owner": "desktop" -} diff --git a/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/web.ts/spawnSync.json b/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/web.ts/spawnSync.json deleted file mode 100644 index ffe5df1d..00000000 --- a/scripts/sync-exec-allowlist/packages/cli/src/cli/commands/web.ts/spawnSync.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "path": "packages/cli/src/cli/commands/web.ts", - "symbol": "spawnSync", - "category": "cli", - "reason": "one-shot `scout web` commands: credential-store reads/writes (security, secret-tool) with the download key on stdin, and the tar extract of a verified download", - "owner": "desktop" -}