@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/engineBrokerMcpFacade.js

@@ -0,0 +1,343 @@
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { GROK_WORKER_MAX_TURNS } from "../contracts/grokWorkerContract.js";
+import { EngineBrokerCapabilities } from "./engineBrokerCapabilities.js";
+import { EngineBrokerMcpCallLog } from "./engineBrokerMcpCallLog.js";
+/**
+ * The brokered worker's only route to its own per-wake Daimon MCP mount. The
+ * worker holds a turn capability and nothing else: it never learns the mount's
+ * address, and the mount never learns the capability. Every header crossing
+ * either way is rebuilt from a closed allowlist, so this stays a boundary and
+ * not a transparent proxy — a blanket passthrough would hand the mount the
+ * worker's bearer and hand the worker whatever the mount chose to say.
+ *
+ * The allowlists are exactly the Streamable HTTP transport's own routing
+ * headers. Anything outside them (authorization above all, cookies, auth
+ * challenges, forwarding and tracing headers) is dropped in both directions.
+ *
+ * Client -> mount:
+ * - `content-type`: the JSON-RPC body's media type; the mount refuses a POST
+ *   without it.
+ * - `accept`: the transport negotiates `application/json, text/event-stream`
+ *   per request and the mount answers 406 when a POST does not accept both.
+ * - `mcp-session-id`: the opaque session the mount issued on `initialize`.
+ *   Dropping it made the mount answer every later request with HTTP 400
+ *   `Mcp-Session-Id header is required`, so no tool was ever reachable. It is
+ *   a routing value, not a secret — and not a value to log either.
+ * - `mcp-protocol-version`: the version the handshake settled on. The mount
+ *   validates it and otherwise assumes a default that can disagree with what
+ *   the client negotiated.
+ * - `last-event-id`: SSE resumability. A reconnecting stream replays from the
+ *   last event it saw; without it the mount cannot tell where to resume.
+ *
+ * Mount -> client:
+ * - `content-type`: tells the client whether it got JSON or an SSE stream.
+ * - `mcp-session-id`: the id minted on `initialize`. The client must learn it
+ *   or it can never make a second request.
+ * - `mcp-protocol-version`: the version the mount confirms for the session.
+ * - `cache-control: no-store` is the facade's own, not the mount's.
+ *
+ * Methods are the three the transport uses: POST for JSON-RPC, GET for the
+ * server-to-client SSE stream (notifications and progress arrive only there),
+ * and DELETE to end a session. POST alone left the GET stream answering 403.
+ */
+const FORWARDED_REQUEST_HEADERS = ["content-type", "accept", "mcp-session-id", "mcp-protocol-version", "last-event-id"];
+const FORWARDED_RESPONSE_HEADERS = ["content-type", "mcp-session-id", "mcp-protocol-version"];
+const FORWARDED_METHODS = new Set(["POST", "GET", "DELETE"]);
+const MAX_REQUEST_BYTES = 1024 * 1024;
+export const ENGINE_BROKER_MCP_FACADE_PORT = 43_124;
+/** Requests one worker round may legitimately make: its `search_tool`, its `use_tool`, and one spare for a retry or a second discovery. */
+export const ENGINE_BROKER_MCP_ROUND_REQUESTS = 3;
+/** The session's fixed cost, once per turn: `initialize`, `notifications/initialized`, `tools/list`, the standalone GET tunnel, the closing DELETE. */
+export const ENGINE_BROKER_MCP_SESSION_REQUESTS = 5;
+/**
+ * Requests one turn capability may spend, across all three methods — *derived*
+ * from the compiled turn bound rather than chosen.
+ *
+ * It was 128, and a legitimate 48-round wake needs ~101 of them: a worker's
+ * round is a `search_tool` and a `use_tool`, so the first round that also
+ * retries, or looks something up twice, eats the margin. A bound that can be
+ * predicted to bite mid-turn is not a bound, it is a 403 storm waiting for a
+ * real wake — and a number raised until it feels comfortable is not one
+ * either, because the budget exists to cap a *compromised* worker.
+ *
+ * So the two numbers that must agree are kept in one place: the launcher's
+ * `--max-turns` backstop ({@link GROK_WORKER_MAX_TURNS}) times what a round
+ * may legitimately spend, plus the session's fixed cost. Raising the turn
+ * bound raises this with it, and a compromised worker still gets exactly three
+ * MCP calls per round it was compiled to take and not one more. The arithmetic
+ * is spelled out rather than folded into a literal so it can be audited: the
+ * two multiplicands above each say what they are.
+ */
+export const ENGINE_BROKER_MCP_CAPABILITY_REQUESTS = GROK_WORKER_MAX_TURNS * ENGINE_BROKER_MCP_ROUND_REQUESTS + ENGINE_BROKER_MCP_SESSION_REQUESTS;
+export const ENGINE_BROKER_MCP_CAPABILITY_TTL_MS = 15 * 60_000;
+class FacadeRefusal extends Error {
+}
+export async function startEngineBrokerMcpFacade() {
+    const capabilities = new EngineBrokerCapabilities();
+    const targets = new Map();
+    /** In-flight upstream calls per turn, so a revoke or a close tears down any open SSE tunnel. */
+    const inflight = new Map();
+    /**
+     * What the facade saw of each turn's tool calls. A tool receipt is written
+     * only on completion, so without this a call that started and never returned
+     * and a call never made are the same absence (`engineBrokerMcpCallLog.ts`).
+     */
+    const calls = new EngineBrokerMcpCallLog();
+    const server = createServer((request, response) => {
+        void route(request, response).catch((error) => {
+            if (response.headersSent || response.destroyed) {
+                response.destroy();
+                return;
+            }
+            const status = error instanceof FacadeRefusal ? 403 : 502;
+            const body = error instanceof FacadeRefusal ? '{"error":"forbidden"}' : '{"error":"bad_gateway"}';
+            response.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+            response.end(body);
+        });
+    });
+    /**
+     * A 403 the call log can read, whenever the bearer names a turn.
+     *
+     * The refusal itself is unchanged — same status, same body, same silence
+     * towards the worker — but it is attributed first, through a lookup that
+     * does not spend the capability's budget. A bearer no grant matches names no
+     * turn and stays unattributed, because guessing whose it was would be
+     * inventing the measurement. A capability that is *also* spent or expired
+     * reports that instead of the route it asked for: it is the fault the
+     * operator can act on.
+     */
+    function refuse(bearer, live) {
+        const classified = bearer === undefined ? undefined : capabilities.classifyToken(bearer);
+        if (classified !== undefined)
+            calls.refuse(classified.turnId, classified.state === "live" ? live : classified.state);
+        return new FacadeRefusal();
+    }
+    async function route(request, response) {
+        const method = request.method ?? "";
+        const bearer = request.headers.authorization?.match(/^Bearer ([A-Za-z0-9_-]{40,})$/u)?.[1];
+        if (request.url !== "/mcp" || !FORWARDED_METHODS.has(method))
+            throw refuse(bearer, "route");
+        if (bearer === undefined)
+            throw new FacadeRefusal();
+        const scope = capabilities.authorizeToken(bearer);
+        // A live grant that authorizes is the only way past here; anything else is
+        // classified so an exhausted budget and an expired TTL reach the turn's
+        // sealed row as themselves. `live` cannot be the answer on this path —
+        // `authorizeToken` read the same grant a moment ago, expiry only moves
+        // forward and a budget only spends — so it is the unreachable arm.
+        if (!scope)
+            throw refuse(bearer, "expired");
+        const target = targets.get(scope.turnId);
+        if (target === undefined) {
+            calls.refuse(scope.turnId, "unrouted");
+            throw new FacadeRefusal();
+        }
+        // Only POST carries a JSON-RPC body; drain anything else so the socket
+        // never stalls waiting for a body the facade will not forward.
+        let body;
+        // A body refused for size is a call the log can never name, and counting
+        // it keeps "no tool call started" an honest reading rather than a gap.
+        try {
+            body = method === "POST" ? await bounded(request) : (request.resume(), undefined);
+        }
+        catch (error) {
+            calls.undecodable(scope.turnId);
+            // A body past the bound is refused, not merely unreadable: the worker
+            // gets a 403 for it, so it is counted as one too.
+            if (error instanceof FacadeRefusal)
+                calls.refuse(scope.turnId, "oversized");
+            throw error;
+        }
+        const payload = body === undefined ? undefined : body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+        const call = calls.begin(scope.turnId, body);
+        // The GET SSE tunnel is the session's other channel and the one that
+        // outlives every request: it stays open until the worker or the mount ends
+        // it, so a turn sealed with one still open is a turn whose worker may be
+        // parked on it. Observed only — never closed, timed out or refused here.
+        const tunnel = method === "GET" ? calls.openTunnel(scope.turnId) : undefined;
+        const controller = new AbortController();
+        const open = inflight.get(scope.turnId) ?? new Set();
+        open.add(controller);
+        inflight.set(scope.turnId, open);
+        const abort = () => controller.abort();
+        response.on("close", abort);
+        try {
+            // Answered only on a relay that reached its own end: a tunnel torn down
+            // by the worker's death must not mark the call it was blocked on as
+            // finished.
+            if (await forward(target, method, headersFor(method, request), payload, controller.signal, response, tunnel))
+                call.answer();
+        }
+        finally {
+            call.close();
+            tunnel?.close();
+            response.off("close", abort);
+            open.delete(controller);
+            if (open.size === 0)
+                inflight.delete(scope.turnId);
+        }
+    }
+    function endTurnStreams(turnId) {
+        for (const controller of inflight.get(turnId) ?? [])
+            controller.abort();
+        inflight.delete(turnId);
+    }
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(ENGINE_BROKER_MCP_FACADE_PORT, "127.0.0.1", () => { server.off("error", reject); resolve(); });
+    });
+    return {
+        register(agentId, turnId, endpoint) {
+            const url = new URL(endpoint);
+            if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || url.pathname !== "/mcp")
+                throw new TypeError("invalid scoped MCP mount");
+            if (targets.has(turnId))
+                throw new Error("MCP turn already registered");
+            targets.set(turnId, url.href);
+            calls.open(turnId);
+            return capabilities.issue(agentId, turnId, ENGINE_BROKER_MCP_CAPABILITY_TTL_MS, ENGINE_BROKER_MCP_CAPABILITY_REQUESTS);
+        },
+        revoke(turnId) {
+            targets.delete(turnId);
+            capabilities.revoke(turnId);
+            endTurnStreams(turnId);
+            calls.close(turnId);
+        },
+        /**
+         * What the facade saw of this turn's tool calls, GET tunnels and refusals,
+         * or `undefined` for a turn
+         * it never registered. Read on the failure path, before `revoke`.
+         */
+        observe: (turnId) => calls.observe(turnId),
+        close: async () => {
+            for (const turnId of [...inflight.keys()])
+                endTurnStreams(turnId);
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+                // A GET SSE tunnel keeps its socket open indefinitely, and `close`
+                // only stops accepting; without this a shutdown would hang on it.
+                server.closeAllConnections();
+            });
+        }
+    };
+}
+/** The client -> mount allowlist, with the two defaults the mount requires of a POST. */
+function headersFor(method, request) {
+    const headers = {};
+    for (const name of FORWARDED_REQUEST_HEADERS) {
+        const value = request.headers[name];
+        if (typeof value === "string" && value.length > 0)
+            headers[name] = value;
+    }
+    if (method === "POST") {
+        headers["content-type"] ??= "application/json";
+        headers["accept"] ??= "application/json, text/event-stream";
+    }
+    else {
+        delete headers["content-type"];
+    }
+    return headers;
+}
+/**
+ * Streams the exchange rather than buffering it: a GET stream stays open for
+ * the whole session, and a buffered POST would withhold progress
+ * notifications until the call had already finished.
+ */
+async function forward(target, method, headers, body, signal, response, tunnel) {
+    const upstream = await fetch(target, { method, headers, body, signal, redirect: "manual" });
+    // MCP never redirects, and following one would let the mount aim the facade
+    // at a host the capability was never scoped to. `manual` also reports an
+    // opaque redirect as status 0, which is not a status to relay at all.
+    const relayable = (upstream.status >= 200 && upstream.status < 300) || (upstream.status >= 400 && upstream.status <= 599);
+    if (!relayable)
+        throw new Error("unexpected MCP mount status");
+    const outbound = { "cache-control": "no-store" };
+    for (const name of FORWARDED_RESPONSE_HEADERS) {
+        const value = upstream.headers.get(name);
+        if (value !== null && value.length > 0)
+            outbound[name] = value;
+    }
+    outbound["content-type"] ??= "application/json";
+    response.writeHead(upstream.status, outbound);
+    if (upstream.body === null) {
+        response.end();
+        return true;
+    }
+    const stream = Readable.fromWeb(upstream.body);
+    let delivered = false;
+    try {
+        for await (const chunk of stream) {
+            // The first byte the mount pushes: a tunnel that carried frames is a
+            // different fact from one held open having delivered nothing.
+            if (!delivered) {
+                delivered = true;
+                tunnel?.deliver();
+            }
+            if (response.destroyed || response.writableEnded)
+                throw new Error("MCP tunnel closed");
+            if (!response.write(chunk))
+                await awaitMcpTunnelDrain(response, signal);
+        }
+        response.end();
+        return true;
+    }
+    catch {
+        // The client hung up or the mount's stream broke: tear the tunnel down
+        // rather than leaving a half-written response open.
+        response.destroy();
+        return false;
+    }
+    finally {
+        stream.destroy();
+    }
+}
+/**
+ * Waits for a backpressured tunnel to drain, or for the tunnel to end —
+ * whichever happens first, but always one of them.
+ *
+ * A bare `once("drain")` never settles for a client that hung up mid-write:
+ * `drain` cannot fire on a socket nobody is reading, and neither the
+ * response's own `close` nor the turn's abort woke that await. The GET SSE
+ * tunnel stays open for a whole session, so the handler — and the upstream
+ * call it was relaying — leaked for the life of the broker process, with no
+ * refusal, no status and no line anywhere to read. Every outcome settles this
+ * now, and every outcome but an actual drain *rejects*, so the caller tears
+ * the tunnel down instead of writing into a socket that is gone.
+ *
+ * Exported for its own test: a hang is only observable from inside.
+ */
+export function awaitMcpTunnelDrain(response, signal) {
+    if (response.destroyed || response.writableEnded)
+        return Promise.reject(new Error("MCP tunnel closed"));
+    if (signal.aborted)
+        return Promise.reject(new Error("MCP tunnel aborted"));
+    return new Promise((resolve, reject) => {
+        const settle = (finish) => () => {
+            response.off("drain", onDrain);
+            response.off("close", onClosed);
+            response.off("error", onClosed);
+            signal.removeEventListener("abort", onAborted);
+            finish();
+        };
+        const onDrain = settle(resolve);
+        const onClosed = settle(() => reject(new Error("MCP tunnel closed")));
+        const onAborted = settle(() => reject(new Error("MCP tunnel aborted")));
+        response.once("drain", onDrain);
+        response.once("close", onClosed);
+        response.once("error", onClosed);
+        signal.addEventListener("abort", onAborted, { once: true });
+    });
+}
+async function bounded(request) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const value = Buffer.from(chunk);
+        bytes += value.length;
+        if (bytes > MAX_REQUEST_BYTES)
+            throw new FacadeRefusal();
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+}

package/dist/runtime/engineBrokerNativeClient.d.ts

@@ -0,0 +1,52 @@
+export declare const ENGINE_BROKER_NATIVE_REQUEST_BYTES = 396;
+export declare const ENGINE_BROKER_NATIVE_RESULT_BYTES = 128;
+/** `DBL_MAX_DIAGNOSTIC`: the launcher's bounded tail of a failed worker's own merged stdout/stderr. */
+export declare const ENGINE_BROKER_NATIVE_DIAGNOSTIC_BYTES = 512;
+declare const statuses: readonly ["ok", "prelaunch_failed", "worker_failed", "output_failed", "cancelled"];
+declare const stages: readonly ["none", "peer", "request", "registration", "executable", "exec", "wait", "output", "attestation"];
+declare const failures: readonly ["none", "peer", "protocol", "registration", "executable", "exec", "wait", "output_limit", "cancelled", "profile_missing", "profile_invalid"];
+export interface NativeBrokerDiagnostic {
+    exitCode: number;
+    failureClass: typeof failures[number];
+    profileApplied: boolean;
+    reason?: string;
+    stage: typeof stages[number];
+    startTicks: string;
+    status: typeof statuses[number];
+    termSignal: number;
+    workerPid: number;
+    workerUid: number;
+}
+export declare class NativeBrokerTurnFailure extends Error {
+    readonly diagnostic: NativeBrokerDiagnostic;
+    constructor(diagnostic: NativeBrokerDiagnostic);
+}
+export type NativeBrokerTurn = Readonly<{
+    slot: number;
+    requestId: string;
+    turnId: string;
+    agentId: string;
+    wakeId: string;
+    prompt: string;
+    providerCapability: string;
+    mcpCapability: string;
+}>;
+export interface NativeBrokerTurnResult {
+    text: string;
+    workerPid: number;
+    workerUid: number;
+    startTicks: bigint;
+    diagnostic: NativeBrokerDiagnostic;
+}
+export declare function runNativeBrokerTurn(executable: string, input: NativeBrokerTurn, signal?: AbortSignal): Promise<Readonly<NativeBrokerTurnResult>>;
+export declare function encodeNativeBrokerTurn(input: NativeBrokerTurn): Buffer;
+/**
+ * `output` is accepted as any byte view, and normalized to a `Buffer` once
+ * here: `Uint8Array.prototype.toString("utf8")` ignores its argument and
+ * renders the bytes as comma-separated decimals, which is how a live worker's
+ * last words reached an operator as `reason=108,111,110,101,...` instead of a
+ * sentence. Decoding is explicit from here on, never a stringification.
+ */
+export declare function decodeNativeBrokerResult(input: Uint8Array, turnId: string, secrets?: readonly string[]): NativeBrokerTurnResult;
+export {};
+//# sourceMappingURL=engineBrokerNativeClient.d.ts.map

package/dist/runtime/engineBrokerNativeClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineBrokerNativeClient.d.ts","sourceRoot":"","sources":["../../src/runtime/engineBrokerNativeClient.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,kCAAkC,MAAM,CAAC;AACtD,eAAO,MAAM,iCAAiC,MAAM,CAAC;AACrD,uGAAuG;AACvG,eAAO,MAAM,qCAAqC,MAAM,CAAC;AAGzD,QAAA,MAAM,QAAQ,oFAAqF,CAAC;AACpG,QAAA,MAAM,MAAM,6GAA8G,CAAC;AAC3H,QAAA,MAAM,QAAQ,wJAAyJ,CAAC;AAExK,MAAM,WAAW,sBAAsB;IAAG,QAAQ,EAAC,MAAM,CAAC;IAAA,YAAY,EAAC,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;IAAA,cAAc,EAAC,OAAO,CAAC;IAAA,MAAM,CAAC,EAAC,MAAM,CAAC;IAAA,KAAK,EAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAAA,UAAU,EAAC,MAAM,CAAC;IAAA,MAAM,EAAC,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;IAAA,UAAU,EAAC,MAAM,CAAC;IAAA,SAAS,EAAC,MAAM,CAAC;IAAA,SAAS,EAAC,MAAM,CAAA;CAAE;AACvQ,qBAAa,uBAAwB,SAAQ,KAAK;IAAe,QAAQ,CAAC,UAAU,EAAC,sBAAsB;gBAAjC,UAAU,EAAC,sBAAsB;CAAwC;AACnJ,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IAAC,IAAI,EAAC,MAAM,CAAC;IAAA,SAAS,EAAC,MAAM,CAAC;IAAA,MAAM,EAAC,MAAM,CAAC;IAAA,OAAO,EAAC,MAAM,CAAC;IAAA,MAAM,EAAC,MAAM,CAAC;IAAA,MAAM,EAAC,MAAM,CAAC;IAAA,kBAAkB,EAAC,MAAM,CAAC;IAAA,aAAa,EAAC,MAAM,CAAA;CAAC,CAAC,CAAC;AAChL,MAAM,WAAW,sBAAsB;IAAE,IAAI,EAAC,MAAM,CAAC;IAAA,SAAS,EAAC,MAAM,CAAC;IAAA,SAAS,EAAC,MAAM,CAAC;IAAA,UAAU,EAAC,MAAM,CAAC;IAAA,UAAU,EAAC,sBAAsB,CAAA;CAAC;AAE3I,wBAAsB,mBAAmB,CAAC,UAAU,EAAC,MAAM,EAAC,KAAK,EAAC,gBAAgB,EAAC,MAAM,CAAC,EAAC,WAAW,GAAE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC,CAIhJ;AACD,wBAAgB,sBAAsB,CAAC,KAAK,EAAC,gBAAgB,GAAE,MAAM,CAAqkC;AAE1oC;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAC,UAAU,EAAC,MAAM,EAAC,MAAM,EAAC,OAAO,GAAC,SAAS,MAAM,EAAK,GAAE,sBAAsB,CAkB3H"}

package/dist/runtime/engineBrokerNativeClient.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import { redactCredentialText } from "../core/credentialRedaction.js";
+import { boundedDiagnosticWindow, CLI_ENGINE_MAX_DIAGNOSTIC_BYTES } from "../pi/cliChildOutput.js";
+import { terminateChild, trackCliChild } from "../pi/cliProcess.js";
+export const ENGINE_BROKER_NATIVE_REQUEST_BYTES = 396;
+export const ENGINE_BROKER_NATIVE_RESULT_BYTES = 128;
+/** `DBL_MAX_DIAGNOSTIC`: the launcher's bounded tail of a failed worker's own merged stdout/stderr. */
+export const ENGINE_BROKER_NATIVE_DIAGNOSTIC_BYTES = 512;
+/** `DBL_MAX_OUTPUT`: the launcher's bound on a whole turn's stdout, and the control protocol's own `text` bound, which is the next boundary this output crosses. */
+const MAX_PROMPT = 65_536, MAX_CAPABILITY = 4_096, MAX_OUTPUT = 262_144;
+const statuses = ["ok", "prelaunch_failed", "worker_failed", "output_failed", "cancelled"];
+const stages = ["none", "peer", "request", "registration", "executable", "exec", "wait", "output", "attestation"];
+const failures = ["none", "peer", "protocol", "registration", "executable", "exec", "wait", "output_limit", "cancelled", "profile_missing", "profile_invalid"];
+export class NativeBrokerTurnFailure extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super("engine broker turn failed");
+        this.diagnostic = diagnostic;
+    }
+}
+export async function runNativeBrokerTurn(executable, input, signal) {
+    const frame = encodeNativeBrokerTurn(input), child = trackCliChild(spawn(executable, ["--client"], { detached: process.platform !== "win32", env: { LANG: "C", LC_ALL: "C", TZ: "UTC" }, stdio: ["pipe", "pipe", "ignore"], ...(signal === undefined ? {} : { signal }) }));
+    const chunks = [];
+    let bytes = 0;
+    child.stdout.on("data", (chunk) => { bytes += chunk.length; if (bytes <= ENGINE_BROKER_NATIVE_RESULT_BYTES + MAX_OUTPUT)
+        chunks.push(chunk); });
+    child.stdin.end(frame);
+    frame.fill(0);
+    try {
+        const code = await new Promise((resolve, reject) => { child.once("error", reject); child.once("exit", resolve); });
+        if (code !== 0 || bytes > ENGINE_BROKER_NATIVE_RESULT_BYTES + MAX_OUTPUT)
+            throw new Error();
+        return decodeNativeBrokerResult(Buffer.concat(chunks), input.turnId, [input.providerCapability, input.mcpCapability]);
+    }
+    catch (error) {
+        if (error instanceof NativeBrokerTurnFailure)
+            throw error;
+        throw new Error("engine broker turn failed");
+    }
+    finally {
+        await terminateChild(child).catch(() => undefined);
+    }
+}
+export function encodeNativeBrokerTurn(input) { if (!Number.isInteger(input.slot) || input.slot < 0)
+    throw new TypeError("invalid engine broker turn"); const p = Buffer.from(input.prompt), provider = Buffer.from(input.providerCapability), mcp = Buffer.from(input.mcpCapability); if (p.length < 1 || p.length > MAX_PROMPT || provider.length < 1 || provider.length > MAX_CAPABILITY || mcp.length < 1 || mcp.length > MAX_CAPABILITY || provider.equals(mcp))
+    throw new TypeError("invalid engine broker turn"); const c = Buffer.alloc(4 + provider.length + mcp.length); c.writeUInt16LE(provider.length, 0); provider.copy(c, 2); c.writeUInt16LE(mcp.length, 2 + provider.length); mcp.copy(c, 4 + provider.length); const frame = Buffer.alloc(ENGINE_BROKER_NATIVE_REQUEST_BYTES + 8 + p.length + c.length); frame.writeUInt32LE(2, 0); frame.writeUInt32LE(input.slot, 4); field(frame, 8, 65, input.requestId); field(frame, 73, 65, input.turnId); field(frame, 138, 129, input.agentId); field(frame, 267, 129, input.wakeId); let o = ENGINE_BROKER_NATIVE_REQUEST_BYTES; frame.writeUInt32LE(p.length, o); o += 4; p.copy(frame, o); o += p.length; frame.writeUInt32LE(c.length, o); o += 4; c.copy(frame, o); p.fill(0); provider.fill(0); mcp.fill(0); c.fill(0); return frame; }
+/**
+ * `output` is accepted as any byte view, and normalized to a `Buffer` once
+ * here: `Uint8Array.prototype.toString("utf8")` ignores its argument and
+ * renders the bytes as comma-separated decimals, which is how a live worker's
+ * last words reached an operator as `reason=108,111,110,101,...` instead of a
+ * sentence. Decoding is explicit from here on, never a stringification.
+ */
+export function decodeNativeBrokerResult(input, turnId, secrets = []) {
+    const output = Buffer.isBuffer(input) ? input : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+    if (output.length < ENGINE_BROKER_NATIVE_RESULT_BYTES)
+        throw new Error("engine broker turn failed");
+    const status = output.readUInt32LE(4), uid = output.readUInt32LE(8), length = output.readUInt32LE(12), pid = output.readInt32LE(16), exitCode = output.readInt32LE(20), termSignal = output.readInt32LE(24), ticks = output.readBigUInt64LE(32), stage = output.readUInt32LE(108), failure = output.readUInt32LE(112), profile = output.readUInt32LE(116), diagnosticLength = output.readUInt32LE(120), observed = output.subarray(40, 105).toString("utf8").replace(/\0.*$/u, "");
+    const paddingZero = [output.subarray(28, 32), output.subarray(105, 108), output.subarray(124, 128)].every((bytes) => bytes.every((byte) => byte === 0));
+    if (output.length !== ENGINE_BROKER_NATIVE_RESULT_BYTES + length + diagnosticLength || output.readUInt32LE(0) !== 2 || status >= statuses.length || stage >= stages.length || failure >= failures.length || profile > 1 || !paddingZero || observed !== turnId || length > MAX_OUTPUT || diagnosticLength > ENGINE_BROKER_NATIVE_DIAGNOSTIC_BYTES)
+        throw new Error("engine broker turn failed");
+    // Decoded from the caller's own view, not from the normalized frame: the
+    // decode is what must be correct for any byte view, and it is the step the
+    // live `reason=108,111,110,...` failure came from.
+    const reason = workerReason(input.subarray(ENGINE_BROKER_NATIVE_RESULT_BYTES + length), secrets);
+    const diagnostic = { status: statuses[status], stage: stages[stage], failureClass: failures[failure], profileApplied: profile === 1, ...(reason === undefined ? {} : { reason }), exitCode, termSignal, workerPid: pid, workerUid: uid, startTicks: ticks.toString() };
+    const success = status === 0 && stage === 7 && failure === 0 && profile === 0 && pid > 0 && uid >= 2200 && ticks > 0n && exitCode === 0 && termSignal === 0 && diagnosticLength === 0;
+    const prelaunch = status === 1 && stage >= 1 && stage <= 5 && failure >= 1 && failure <= 5 && profile === 0 && pid === 0 && uid === 0 && ticks === 0n && diagnosticLength === 0;
+    const worker = status === 2 && stage === 6 && (failure === 5 || failure === 6) && profile === 0 && pid > 0 && uid >= 2200 && ticks > 0n;
+    const outputFailure = status === 3 && stage === 7 && failure === 7 && profile === 0 && pid > 0 && uid >= 2200 && ticks > 0n;
+    const cancelled = status === 4 && stage === 6 && failure === 8 && profile === 0 && pid > 0 && uid >= 2200 && ticks > 0n;
+    if (!success) {
+        if (length !== 0 || (!prelaunch && !worker && !outputFailure && !cancelled))
+            throw new Error("engine broker turn failed");
+        throw new NativeBrokerTurnFailure(diagnostic);
+    }
+    return { text: output.subarray(ENGINE_BROKER_NATIVE_RESULT_BYTES).toString("utf8"), workerUid: uid, workerPid: pid, startTicks: ticks, diagnostic };
+}
+/**
+ * The worker's own last words, fit to cross a boundary.
+ *
+ * A failed brokered turn otherwise reports nothing but `exit=1`: the launcher
+ * merges the worker's stdout and stderr into one pipe and publishes no output
+ * for a failure, so this bounded window is the only account of why it failed.
+ * It keeps both ends of what it is given (`boundedDiagnosticWindow`), because
+ * a worker that dies early prints its error before it echoes anything.
+ * It is worker-controlled text, so it is redacted exactly as the CLI child
+ * path redacts a failed engine child (`redactCredentialText` with the turn's
+ * own capabilities as exact secrets, the same diagnostic bound) and flattened
+ * to one line, because it travels inside a failure message.
+ */
+function workerReason(tail, secrets) {
+    if (tail.byteLength === 0)
+        return undefined;
+    // Decoded explicitly, and with replacement rather than a throw: the window
+    // is a byte count, so it can cut a multi-byte sequence in half at either
+    // end, and a worker's last words must not be lost to its own encoding.
+    const flattened = UTF8.decode(tail).replace(/[\u0000-\u001f\u007f]+/gu, " ").replace(/\s+/gu, " ").trim();
+    // Redact first, unbounded, then window: redaction can lengthen the text
+    // ([REDACTED] is longer than a short secret), so bounding before it could
+    // hand back more bytes than the boundary admits.
+    const redacted = redactCredentialText(scrubCutFragments(flattened, secrets), secrets, Number.MAX_SAFE_INTEGER).trim();
+    const reason = boundedDiagnosticWindow(redacted, CLI_ENGINE_MAX_DIAGNOSTIC_BYTES).trim();
+    return reason.length === 0 ? undefined : reason;
+}
+/** Non-fatal by construction: a cut multi-byte sequence becomes U+FFFD, never an exception. */
+const UTF8 = new TextDecoder("utf-8");
+/**
+ * A credential the launcher's window cut in half, at either side of a cut.
+ *
+ * Exact redaction matches a secret whole, so a secret a cut split survives as
+ * a fragment it can never match: the piece before a cut can end with a
+ * secret's prefix, and the piece after it can begin with a secret's suffix.
+ * The trick that answers this where Daimon owns both ends — retain one whole
+ * secret more than is reported (`cliChildOutput.ts`) — cannot work at this
+ * boundary, because the launcher's window *is* what it sends: a margin
+ * reserved there would be reported along with everything else. So the fragment
+ * is matched here, where the turn's own capabilities are known, and every cut
+ * the window can make is covered: the two sides of each elision marker, and
+ * the outer ends, where the launcher's capture itself stopped reading.
+ *
+ * Only a fragment long enough to be a credential is scrubbed. Below
+ * {@link MIN_CREDENTIAL_FRAGMENT} characters a piece of a random token is
+ * indistinguishable from ordinary words and carries nothing usable, and
+ * scrubbing it would eat real text.
+ */
+const MIN_CREDENTIAL_FRAGMENT = 12;
+const ELISION_MARKER = /(\[… \d+ bytes elided …\])/u;
+const scrubCutFragments = (value, secrets) => value.split(ELISION_MARKER).map((part) => ELISION_MARKER.test(part) ? part : scrubEnds(part, secrets)).join("");
+function scrubEnds(part, secrets) {
+    let result = part;
+    for (const secret of secrets) {
+        if (secret.length <= MIN_CREDENTIAL_FRAGMENT)
+            continue;
+        for (let length = Math.min(secret.length - 1, result.length); length >= MIN_CREDENTIAL_FRAGMENT; length -= 1) {
+            if (result.endsWith(secret.slice(0, length))) {
+                result = `${result.slice(0, result.length - length)}[REDACTED]`;
+                break;
+            }
+        }
+        for (let length = Math.min(secret.length - 1, result.length); length >= MIN_CREDENTIAL_FRAGMENT; length -= 1) {
+            if (result.startsWith(secret.slice(secret.length - length))) {
+                result = `[REDACTED]${result.slice(length)}`;
+                break;
+            }
+        }
+    }
+    return result;
+}
+function field(target, offset, length, value) { if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(value) || Buffer.byteLength(value) >= length)
+    throw new TypeError("invalid engine broker turn"); target.write(value, offset, "utf8"); }