@haywoodmarx/agent-pager 0.1.0

package/dist/src/launch/skill.d.ts

@@ -0,0 +1,57 @@
+/** Names the skill directory this package ships. */
+export declare const packagedSkillName = "pager";
+/** Names where the packaged skill is installed from. */
+export type SkillSource = {
+    /** Installs a directory shipped inside this package. */
+    kind: "local";
+    /** Directory the skill is installed from. */
+    path: string;
+};
+/** Describes the child process that performs the install. */
+export type SkillInstallCommand = {
+    /** Executable to run. */
+    command: string;
+    /** Arguments passed to the executable. */
+    args: string[];
+};
+/**
+ * Locate the skill directory shipped inside this package.
+ *
+ * Ancestors are walked rather than resolved at a fixed depth because the compiled entrypoint and the
+ * TypeScript source sit at different distances from the package root.
+ * @param from - Directory the upward search starts in.
+ * @returns - Absolute path to the packaged skill directory.
+ * @throws {Error} When no ancestor holds the packaged skill.
+ */
+export declare function packagedSkillPath(from?: string): string;
+/** One skill this package can install, and where it is installed from. */
+export type PackagedSkill = {
+    /** Directory the skill installs as, and the name an operator sees. */
+    readonly name: string;
+    /** Where the skill is installed from. */
+    readonly source: SkillSource;
+};
+/**
+ * List the skills this build offers to install, in the order an operator is shown them.
+ *
+ * The one place the catalogue is decided. A further skill is an entry here; nothing that consumes
+ * this names a particular one. A build whose skill directory is absent offers nothing rather than
+ * throwing, so the operator screen that lists the catalogue still opens without the entry.
+ * @returns - Every installable skill this package ships.
+ */
+export declare function packagedSkills(): readonly PackagedSkill[];
+/**
+ * Report where this build installs its skill from.
+ *
+ * The one place the source is decided.
+ * @param path - Local skill directory, resolved from this package by default.
+ * @returns - Source the install command is built against.
+ */
+export declare function packagedSkillSource(path?: string): SkillSource;
+/**
+ * Build the `skills` CLI invocation that installs the skill.
+ * @param passthrough - Arguments forwarded to the CLI unaltered.
+ * @param source - Source to install, defaulting to the one this build ships.
+ * @returns - Executable and arguments for the install child process.
+ */
+export declare function skillInstallCommand(passthrough?: readonly string[], source?: SkillSource): SkillInstallCommand;

package/dist/src/launch/skill.js

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Names the skill directory this package ships. */
+export const packagedSkillName = "pager";
+/**
+ * Pins the `skills` CLI to the major line whose `add` flags this command was written against.
+ * @see https://github.com/vercel-labs/skills
+ */
+const skillsCliSpecifier = "skills@^1.5";
+/**
+ * Locate the skill directory shipped inside this package.
+ *
+ * Ancestors are walked rather than resolved at a fixed depth because the compiled entrypoint and the
+ * TypeScript source sit at different distances from the package root.
+ * @param from - Directory the upward search starts in.
+ * @returns - Absolute path to the packaged skill directory.
+ * @throws {Error} When no ancestor holds the packaged skill.
+ */
+export function packagedSkillPath(from = dirname(fileURLToPath(import.meta.url))) {
+    let directory = from;
+    for (;;) {
+        const candidate = join(directory, "skills", packagedSkillName);
+        if (existsSync(join(candidate, "SKILL.md")))
+            return candidate;
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw new Error(`Packaged skill ${packagedSkillName} was not found above ${from}`);
+        directory = parent;
+    }
+}
+/** Resolved catalogue, kept because locating it walks the filesystem and it cannot move mid-process. */
+let catalogue;
+/**
+ * List the skills this build offers to install, in the order an operator is shown them.
+ *
+ * The one place the catalogue is decided. A further skill is an entry here; nothing that consumes
+ * this names a particular one. A build whose skill directory is absent offers nothing rather than
+ * throwing, so the operator screen that lists the catalogue still opens without the entry.
+ * @returns - Every installable skill this package ships.
+ */
+export function packagedSkills() {
+    catalogue ??= resolveCatalogue(packagedSkillPath);
+    return catalogue;
+}
+/**
+ * List the catalogue from an injected skill locator, bypassing the cache.
+ * @internal
+ * @param locate - Resolves the packaged skill directory.
+ * @returns - Every installable skill this package ships.
+ */
+export function packagedSkillsAt(locate) {
+    return resolveCatalogue(locate);
+}
+function resolveCatalogue(locate) {
+    try {
+        return [{ name: packagedSkillName, source: packagedSkillSource(locate()) }];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Report where this build installs its skill from.
+ *
+ * The one place the source is decided.
+ * @param path - Local skill directory, resolved from this package by default.
+ * @returns - Source the install command is built against.
+ */
+export function packagedSkillSource(path = packagedSkillPath()) {
+    return { kind: "local", path };
+}
+/**
+ * Build the `skills` CLI invocation that installs the skill.
+ * @param passthrough - Arguments forwarded to the CLI unaltered.
+ * @param source - Source to install, defaulting to the one this build ships.
+ * @returns - Executable and arguments for the install child process.
+ */
+export function skillInstallCommand(passthrough = [], source = packagedSkillSource()) {
+    return { command: "bunx", args: ["--bun", skillsCliSpecifier, "add", source.path, ...passthrough] };
+}

package/dist/src/launch/terminal.d.ts

@@ -0,0 +1,26 @@
+import type { ForegroundProcessSpawner, TerminalLaunch } from "./launch.js";
+/**
+ * Spawn a foreground child process inheriting this process's terminal.
+ * @returns - Process id and a one-shot listener registration, matching {@link ForegroundProcessSpawner}.
+ */
+export declare function spawnForegroundProcess(command: string, args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdio: "inherit";
+    detached: false;
+}): ReturnType<ForegroundProcessSpawner>;
+/**
+ * Spawn a foreground child inheriting the caller's terminal, and settle once it exits.
+ * @param spawnProcess - Foreground process boundary used to start the child.
+ * @param request - Neutral terminal launch request supplying the command and environment layers.
+ * @returns - The spawned child and a promise that settles with its exit disposition.
+ */
+export declare function spawnInheritedSession(spawnProcess: ForegroundProcessSpawner, request: TerminalLaunch): {
+    /** Spawned child process handle. */
+    child: ReturnType<ForegroundProcessSpawner>;
+    /** Settles with the child's exit disposition. */
+    exit: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+};

package/dist/src/launch/terminal.js

@@ -0,0 +1,43 @@
+import { spawn } from "node:child_process";
+// eslint-disable-next-line jsdoc/require-param -- forwarded to spawn unmodified; options is the closed shape ForegroundProcessSpawner's contract already states.
+/**
+ * Spawn a foreground child process inheriting this process's terminal.
+ * @returns - Process id and a one-shot listener registration, matching {@link ForegroundProcessSpawner}.
+ */
+export function spawnForegroundProcess(command, args, options) {
+    const child = spawn(command, args, options);
+    return {
+        pid: child.pid,
+        once: (event, listener) => {
+            if (event === "error")
+                child.once("error", listener);
+            else
+                child.once("exit", listener);
+        },
+    };
+}
+/**
+ * Spawn a foreground child inheriting the caller's terminal, and settle once it exits.
+ * @param spawnProcess - Foreground process boundary used to start the child.
+ * @param request - Neutral terminal launch request supplying the command and environment layers.
+ * @returns - The spawned child and a promise that settles with its exit disposition.
+ */
+export function spawnInheritedSession(spawnProcess, request) {
+    const child = spawnProcess(request.plan.command, [...request.plan.args], {
+        cwd: request.plan.workspacePath,
+        env: {
+            ...request.baseEnvironment,
+            ...request.plan.environment,
+            ...request.plan.sensitiveEnvironment,
+        },
+        stdio: "inherit",
+        detached: false,
+    });
+    const exit = new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            resolve({ code, signal });
+        });
+    });
+    return { child, exit };
+}

package/dist/src/launch/workspace-branch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Report the branch checked out at a workspace path.
+ *
+ * A standalone module so a caller composing only the broker itself avoids pulling in the whole
+ * `BrokerService` module graph for one `git` lookup.
+ * @param path - Absolute workspace path to inspect.
+ * @returns - Current branch name, or null when the path is not a repository, is detached, or the
+ * lookup did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
+ */
+export declare function systemWorkspaceBranch(path: string): string | null;

package/dist/src/launch/workspace-branch.js

@@ -0,0 +1,29 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Bounds the branch lookup, which runs a subprocess against a path this process does not control.
+ *
+ * The branch is a label on a workspace row; nothing waits on it, so a slow answer is discarded
+ * rather than waited for.
+ */
+const WORKSPACE_BRANCH_TIMEOUT_MS = 2_000;
+/**
+ * Report the branch checked out at a workspace path.
+ *
+ * A standalone module so a caller composing only the broker itself avoids pulling in the whole
+ * `BrokerService` module graph for one `git` lookup.
+ * @param path - Absolute workspace path to inspect.
+ * @returns - Current branch name, or null when the path is not a repository, is detached, or the
+ * lookup did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
+ */
+export function systemWorkspaceBranch(path) {
+    try {
+        return (execFileSync("git", ["-C", path, "branch", "--show-current"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: WORKSPACE_BRANCH_TIMEOUT_MS,
+        }).trim() || null);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/messaging/delivery-client.d.ts

@@ -0,0 +1,144 @@
+import { type AgentId } from "../broker/protocol.js";
+/** Performs one broker HTTP request on behalf of an out-of-process implementation adapter. */
+export type BrokerRequest = (url: string, init: RequestInit) => Promise<Response>;
+/** Holds one fenced broker attachment established by an adapter process. */
+export type AttachedSession = {
+    /** Identifies the attached broker session. */
+    sessionId: string;
+    /** Fences the attachment against a superseded broker epoch. */
+    epoch: string;
+    /** Presented back to the broker so it can rotate a lapsed or superseded session in place. */
+    resumeToken?: string;
+    /** Carries the identity the broker resolved, which a conversation key may redirect. */
+    agentId?: AgentId;
+};
+/** Carries the single-use attachments a directly started implementation process receives. */
+export type BrokerIdentity = {
+    /** Identifies the registered broker agent. */
+    agentId: AgentId;
+    /** Attaches the model-callable messaging channel. */
+    messagingReservation: string;
+    /** Attaches the delivery channel, over which the session presents its inbox address. */
+    deliveryReservation: string;
+};
+/**
+ * Register a directly started implementation session through the unauthenticated broker boundary.
+ * @param request - HTTP operation used to reach the loopback broker.
+ * @param brokerUrl - Shared broker MCP endpoint.
+ * @param registration - Workspace and implementation identity, an optional stable session name the
+ * broker adopts as the alias instead of assigning one, the optional conversation key that rejoins
+ * an existing identity instead of forking a new one, and the optional key of the conversation that
+ * one continues.
+ * @returns - Registered identity with separate messaging and delivery attachments.
+ */
+export declare function registerAgent(request: BrokerRequest, brokerUrl: string, registration: {
+    workspacePath: string;
+    implementationId: string;
+    sessionName?: string;
+    sessionKey?: string;
+    continuesSessionKey?: string;
+}): Promise<BrokerIdentity>;
+/** Options for {@link BrokerDeliveryClient.attach}. */
+export type AttachDeliveryClientOptions = {
+    /** Shared broker MCP endpoint. */
+    brokerUrl: string;
+    /** Agent whose wakes this attachment may carry. */
+    agentId: AgentId;
+    /** Single-use delivery attachment credential. */
+    reservation: string;
+    /** HTTP operation used to reach the loopback broker. */
+    request: BrokerRequest;
+    /** Conversation key the broker may resolve to an existing identity. */
+    sessionKey?: string | undefined;
+};
+/**
+ * Holds one fenced delivery attachment: it keeps the identity's lease alive, presents the session's
+ * inbox address, and ends the identity when the harness leaves.
+ */
+export declare class BrokerDeliveryClient {
+    #private;
+    private constructor();
+    /**
+     * Consume a delivery reservation and hold the resulting fenced attachment.
+     * @param options - Endpoint, agent identity, the attachment credential, the request seam, and an
+     * optional resumable conversation key.
+     * @returns - Connected delivery client bound to the identity the broker resolved.
+     */
+    static attach({ brokerUrl, agentId, reservation, request, sessionKey, }: AttachDeliveryClientOptions): Promise<BrokerDeliveryClient>;
+    /**
+     * Return the identity this attachment resolved to.
+     * @returns - Agent id the broker bound to this attachment.
+     */
+    agentId(): AgentId;
+    /**
+     * Present an inbox address on every later request, so the broker pushes this identity's wakes to it.
+     *
+     * Sent with each request rather than once, so a broker that restarted, or that dropped the address
+     * after a failed delivery, learns it again on the next heartbeat.
+     * @param address - Address text the session's inbox produced.
+     */
+    presentDeliveryAddress(address: string): void;
+    /** Renew the delivery attachment lease, presenting the inbox address when one is held. */
+    heartbeat(): Promise<void>;
+    /** Tell the broker the harness is shutting down, ending every attachment of this identity, this one included. */
+    detach(): Promise<void>;
+    /**
+     * Invoke one delivery-attached broker tool.
+     * @param tool - Delivery-channel tool name.
+     * @param args - Validated tool arguments.
+     * @returns - Decoded broker result payload.
+     */
+    call(tool: string, args: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Build one compatibility-path tool call, without session headers.
+ * @param tool - Tool the broker dispatches on; connector-only tools are accepted on this path.
+ * @param args - Tool arguments as the broker validates them.
+ * @returns - Request the caller sends as is for a pre-attach tool, or with its session headers merged
+ * into `headers` for an authenticated one.
+ */
+export declare function compatibilityToolRequest(tool: string, args: Record<string, unknown>): {
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+};
+/**
+ * Take up the session generation a response announces, so a resumed attachment stays usable.
+ *
+ * A broker that rotates the session mid-request answers with the replacement credentials; keeping the
+ * spent ones would resume once and then fence every later call.
+ * @param current - Session the request was made with.
+ * @param response - Broker response, carrying replacement headers only when the session rotated.
+ * @returns - The announced session, or the current one unchanged.
+ */
+export declare function adoptRotation(current: AttachedSession, response: Response): AttachedSession;
+/**
+ * Decode a broker compatibility envelope, raising the broker's own message on failure.
+ * @param response - Broker response carrying an `{ ok, result }` envelope.
+ * @param operation - Operation named in the raised diagnostic.
+ * @returns - Envelope result payload.
+ */
+export declare function compatibilityPayload(response: Response, operation: string): Promise<unknown>;
+/**
+ * Decode a JSON-RPC envelope, raising the broker's own message on failure.
+ * @param response - Broker response carrying a JSON-RPC result.
+ * @param operation - Operation named in the raised diagnostic.
+ * @returns - JSON-RPC result payload.
+ */
+export declare function rpcEnvelope(response: Response, operation: string): Promise<{
+    result: unknown;
+}>;
+/**
+ * Accept an object carrying only permitted fields, rejecting anything additional.
+ * @param value - Untrusted decoded payload.
+ * @param label - Subject named in the raised diagnostic.
+ * @param permitted - Field names the payload may carry.
+ * @returns - The payload as a plain record.
+ */
+export declare function exactRecord(value: unknown, label: string, permitted: readonly string[]): Record<string, unknown>;
+/**
+ * Narrow an untrusted value to a plain record.
+ * @param value - Untrusted decoded payload.
+ * @returns - The value as a plain record, or undefined when it is not one.
+ */
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;

package/dist/src/messaging/delivery-client.js

@@ -0,0 +1,261 @@
+import { ATTACH_HEADER, isAgentId, PROTOCOL_VERSION } from "../broker/protocol.js";
+import { exactFields as guardExactFields, isPlainObject } from "../shared/guards.js";
+import { DELIVERY_ADDRESS_HEADER } from "./mcp.js";
+/**
+ * Register a directly started implementation session through the unauthenticated broker boundary.
+ * @param request - HTTP operation used to reach the loopback broker.
+ * @param brokerUrl - Shared broker MCP endpoint.
+ * @param registration - Workspace and implementation identity, an optional stable session name the
+ * broker adopts as the alias instead of assigning one, the optional conversation key that rejoins
+ * an existing identity instead of forking a new one, and the optional key of the conversation that
+ * one continues.
+ * @returns - Registered identity with separate messaging and delivery attachments.
+ */
+export async function registerAgent(request, brokerUrl, registration) {
+    const response = await request(brokerUrl, compatibilityToolRequest("register_agent", registration));
+    const payload = await compatibilityPayload(response, "Broker registration");
+    const result = exactRecord(payload, "Broker registration result", [
+        "agentId",
+        "reservation",
+        "deliveryReservation",
+        "sessionName",
+        "ephemeral",
+        "resumed",
+    ]);
+    if (!isAgentId(result.agentId))
+        throw new Error("Broker registration returned an invalid agent identity");
+    if (typeof result.reservation !== "string" || typeof result.deliveryReservation !== "string") {
+        throw new Error("Broker registration omitted attachment reservations");
+    }
+    return {
+        agentId: result.agentId,
+        messagingReservation: result.reservation,
+        deliveryReservation: result.deliveryReservation,
+    };
+}
+/**
+ * Holds one fenced delivery attachment: it keeps the identity's lease alive, presents the session's
+ * inbox address, and ends the identity when the harness leaves.
+ */
+export class BrokerDeliveryClient {
+    #brokerUrl;
+    #agentId;
+    #request;
+    #delivery;
+    #deliveryAddress;
+    constructor(brokerUrl, agentId, request, delivery) {
+        this.#brokerUrl = brokerUrl;
+        this.#agentId = agentId;
+        this.#request = request;
+        this.#delivery = delivery;
+    }
+    /**
+     * Consume a delivery reservation and hold the resulting fenced attachment.
+     * @param options - Endpoint, agent identity, the attachment credential, the request seam, and an
+     * optional resumable conversation key.
+     * @returns - Connected delivery client bound to the identity the broker resolved.
+     */
+    static async attach({ brokerUrl, agentId, reservation, request, sessionKey, }) {
+        const attach = compatibilityToolRequest("attach", {});
+        const response = await request(brokerUrl, {
+            ...attach,
+            headers: {
+                ...attach.headers,
+                [ATTACH_HEADER]: reservation,
+                ...(sessionKey ? { "x-pager-session-key": sessionKey } : {}),
+            },
+        });
+        await compatibilityPayload(response, "Broker delivery attachment");
+        const session = deliverySession(response);
+        return new BrokerDeliveryClient(brokerUrl, session.agentId ?? agentId, request, session);
+    }
+    /**
+     * Return the identity this attachment resolved to.
+     * @returns - Agent id the broker bound to this attachment.
+     */
+    agentId() {
+        return this.#agentId;
+    }
+    /**
+     * Present an inbox address on every later request, so the broker pushes this identity's wakes to it.
+     *
+     * Sent with each request rather than once, so a broker that restarted, or that dropped the address
+     * after a failed delivery, learns it again on the next heartbeat.
+     * @param address - Address text the session's inbox produced.
+     */
+    presentDeliveryAddress(address) {
+        this.#deliveryAddress = address;
+    }
+    /** Renew the delivery attachment lease, presenting the inbox address when one is held. */
+    async heartbeat() {
+        await this.call("whoami", {});
+    }
+    /** Tell the broker the harness is shutting down, ending every attachment of this identity, this one included. */
+    async detach() {
+        await this.call("detach", {});
+    }
+    /**
+     * Invoke one delivery-attached broker tool.
+     * @param tool - Delivery-channel tool name.
+     * @param args - Validated tool arguments.
+     * @returns - Decoded broker result payload.
+     */
+    async call(tool, args) {
+        const call = compatibilityToolRequest(tool, args);
+        const response = await this.#request(this.#brokerUrl, {
+            ...call,
+            headers: {
+                ...call.headers,
+                "mcp-session-id": this.#delivery.sessionId,
+                "x-pager-epoch": this.#delivery.epoch,
+                // The attach reservation is single-use, so this token is the only way back after the broker
+                // fences the session.
+                ...(this.#delivery.resumeToken ? { "x-pager-resume-token": this.#delivery.resumeToken } : {}),
+                ...(this.#deliveryAddress ? { [DELIVERY_ADDRESS_HEADER]: this.#deliveryAddress } : {}),
+            },
+        });
+        this.#delivery = adoptRotation(this.#delivery, response);
+        return compatibilityPayload(response, `Broker ${tool}`);
+    }
+}
+/**
+ * Build one compatibility-path tool call, without session headers.
+ * @param tool - Tool the broker dispatches on; connector-only tools are accepted on this path.
+ * @param args - Tool arguments as the broker validates them.
+ * @returns - Request the caller sends as is for a pre-attach tool, or with its session headers merged
+ * into `headers` for an authenticated one.
+ */
+export function compatibilityToolRequest(tool, args) {
+    return {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ version: PROTOCOL_VERSION, tool, arguments: args }),
+    };
+}
+/**
+ * Take up the session generation a response announces, so a resumed attachment stays usable.
+ *
+ * A broker that rotates the session mid-request answers with the replacement credentials; keeping the
+ * spent ones would resume once and then fence every later call.
+ * @param current - Session the request was made with.
+ * @param response - Broker response, carrying replacement headers only when the session rotated.
+ * @returns - The announced session, or the current one unchanged.
+ */
+export function adoptRotation(current, response) {
+    const sessionId = response.headers.get("mcp-session-id");
+    const epoch = response.headers.get("x-pager-epoch");
+    const resumeToken = response.headers.get("x-pager-resume-token");
+    if (!sessionId || !epoch)
+        return current;
+    return {
+        ...current,
+        sessionId,
+        epoch,
+        ...(resumeToken ? { resumeToken } : {}),
+    };
+}
+/**
+ * Read the fenced session headers a delivery attachment response must carry.
+ * @param response - Broker response opening a delivery attachment.
+ * @returns - Session identity and epoch, plus the resume token and resolved agent id when the response carried them.
+ */
+function deliverySession(response) {
+    const sessionId = response.headers.get("mcp-session-id");
+    const epoch = response.headers.get("x-pager-epoch");
+    const resumeToken = response.headers.get("x-pager-resume-token");
+    const agentId = response.headers.get("x-pager-agent-id");
+    if (!sessionId || !epoch)
+        throw new Error("Broker attachment omitted session headers");
+    return {
+        sessionId,
+        epoch,
+        ...(resumeToken ? { resumeToken } : {}),
+        ...(isAgentId(agentId) ? { agentId } : {}),
+    };
+}
+/**
+ * Decode a broker compatibility envelope, raising the broker's own message on failure.
+ * @param response - Broker response carrying an `{ ok, result }` envelope.
+ * @param operation - Operation named in the raised diagnostic.
+ * @returns - Envelope result payload.
+ */
+export async function compatibilityPayload(response, operation) {
+    const payload = await parseEnvelopeBody(response, operation);
+    if (!response.ok || payload?.ok !== true || !("result" in payload)) {
+        throw envelopeFailure(response, payload, operation);
+    }
+    return payload.result;
+}
+/**
+ * Decode a JSON-RPC envelope, raising the broker's own message on failure.
+ * @param response - Broker response carrying a JSON-RPC result.
+ * @param operation - Operation named in the raised diagnostic.
+ * @returns - JSON-RPC result payload.
+ */
+export async function rpcEnvelope(response, operation) {
+    const payload = await parseEnvelopeBody(response, operation);
+    if (!response.ok || !payload || payload.jsonrpc !== "2.0" || !("result" in payload)) {
+        throw envelopeFailure(response, payload, operation);
+    }
+    return { result: payload.result };
+}
+/**
+ * Decode a response body as JSON, keeping the response's status in the raised diagnostic when a
+ * failing response's body isn't JSON at all (an ok response with an unparseable body still rejects
+ * with the raw parse error, since there is no failing status to fold it into).
+ * @param response - Broker response whose body is decoded.
+ * @param operation - Operation named in the raised diagnostic.
+ * @returns - Decoded body as a plain record, or undefined when it decoded to something else.
+ */
+async function parseEnvelopeBody(response, operation) {
+    try {
+        return asRecord(await response.json());
+    }
+    catch (error) {
+        if (response.ok)
+            throw error;
+        throw new Error(`${operation} failed (${String(response.status)})`, { cause: error });
+    }
+}
+/**
+ * Build the error for a broker response that failed to carry a usable envelope.
+ * @param response - Broker response that failed to decode into a successful envelope.
+ * @param payload - Decoded response body, when it was valid JSON.
+ * @param operation - Operation named in the raised diagnostic.
+ * @returns - Error describing the failure.
+ */
+function envelopeFailure(response, payload, operation) {
+    const error = asRecord(payload?.error);
+    const message = typeof error?.message === "string" ? error.message : `${operation} failed (${String(response.status)})`;
+    return new Error(message);
+}
+/**
+ * Accept an object carrying only permitted fields, rejecting anything additional.
+ * @param value - Untrusted decoded payload.
+ * @param label - Subject named in the raised diagnostic.
+ * @param permitted - Field names the payload may carry.
+ * @returns - The payload as a plain record.
+ */
+export function exactRecord(value, label, permitted) {
+    const output = asRecord(value);
+    if (!output)
+        throw new Error(`${label} must be an object`);
+    guardExactFields({
+        record: output,
+        required: [],
+        optional: permitted,
+        path: label,
+        fail: (path, reason) => {
+            throw new Error(`${path}: ${reason}`);
+        },
+    });
+    return output;
+}
+/**
+ * Narrow an untrusted value to a plain record.
+ * @param value - Untrusted decoded payload.
+ * @returns - The value as a plain record, or undefined when it is not one.
+ */
+export function asRecord(value) {
+    return isPlainObject(value) ? { ...value } : undefined;
+}