@haywoodmarx/agent-pager 0.1.0

package/dist/src/implementations/pi/extension.js

@@ -0,0 +1,253 @@
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { Type } from "typebox";
+import { isAgentId } from "../../broker/protocol.js";
+import { adapterHeartbeatIntervalMs } from "../../configuration-defaults.js";
+import { ensureBrokerService } from "../../launch/on-demand.js";
+import { readEmbeddedRuntimeEnvironment, resolveBunExecutable } from "../../launch/runtime.js";
+import { MCP_TOOLS } from "../../messaging/tools.js";
+import { isPlainObject } from "../../shared/guards.js";
+import { openPagerInbox, pagerInboxGuidance, } from "../../messaging/inbox-socket.js";
+import { PAGER_WAKE_TYPE } from "../../messaging/wake.js";
+import { PiBrokerClient, registerPiAgent } from "./broker-client.js";
+import { PI_AGENT_ID_ENVIRONMENT, PI_BROKER_URL_ENVIRONMENT, PI_DELIVERY_RESERVATION_ENVIRONMENT, PI_MESSAGING_RESERVATION_ENVIRONMENT, } from "./environment.js";
+import { loadedApis, systemPiRuntimeSlot } from "./host-slots.js";
+import { registerPiSelfCloseTool } from "./self-close-tool.js";
+import { harnessSessionKey } from "../session-key.js";
+/** Names the tool whose prompt guidelines carry the standing Pager guidance. */
+const PI_ACK_TOOL = "ack_agent_messages";
+/**
+ * Construct the Pager Pi extension around explicit host dependencies.
+ * @param dependencies - Service, HTTP, environment, and scheduling operations.
+ * @returns - Pi extension factory that registers broker tools and session lifecycle hooks.
+ */
+export function createPiExtension(dependencies) {
+    let runtime;
+    const sharedRuntime = () => {
+        if (runtime)
+            return runtime;
+        const existing = dependencies.runtimeSlot.get();
+        if (isPiExtensionRuntime(existing)) {
+            runtime = existing;
+            return runtime;
+        }
+        runtime = { directCwd: undefined, tasks: [] };
+        dependencies.runtimeSlot.set(runtime);
+        return runtime;
+    };
+    return (pi) => {
+        const apis = loadedApis();
+        if (apis.has(pi))
+            return;
+        apis.add(pi);
+        for (const tool of MCP_TOOLS) {
+            pi.registerTool({
+                name: tool.name,
+                label: tool.name,
+                description: tool.description,
+                ...(tool.name === PI_ACK_TOOL ? { promptGuidelines: [...pagerInboxGuidance(PI_ACK_TOOL)] } : {}),
+                parameters: Type.Unsafe(tool.inputSchema),
+                execute: async (_toolCallId, params) => {
+                    const client = sharedRuntime().client;
+                    if (!client)
+                        throw new Error("Pager is not connected");
+                    const result = await client.callTool(tool.name, recordInput(params));
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(result) }],
+                        details: { result },
+                    };
+                },
+            });
+        }
+        registerPiSelfCloseTool(pi, () => {
+            stopTasks(sharedRuntime());
+        });
+        pi.on("session_start", async (_event, ctx) => {
+            stopTasks(sharedRuntime());
+            try {
+                const runtime = sharedRuntime();
+                if (!hasLaunchIdentity(dependencies.processEnv) &&
+                    runtime.client &&
+                    runtime.directCwd !== undefined &&
+                    resolve(runtime.directCwd) === resolve(ctx.cwd)) {
+                    startTasks(pi, ctx, dependencies, runtime);
+                    await presentInbox(ctx, dependencies, runtime);
+                    return;
+                }
+                // The process-wide inbox follows this process to the identity it registers next, so the one it
+                // leaves must be detached first; otherwise the broker keeps pushing that identity's messages here,
+                // where they are claimed and cannot be acknowledged.
+                if (!hasLaunchIdentity(dependencies.processEnv) && runtime.client && runtime.directCwd !== undefined) {
+                    const departing = runtime.client;
+                    delete runtime.client;
+                    delete runtime.connectionKey;
+                    await departing.detach().catch(() => undefined);
+                }
+                const connection = await resolveConnection(dependencies, ctx);
+                // A direct-mode registration displaced whatever the identity held, so its fresh reservations
+                // are the only working ones.
+                if (!runtime.client || runtime.connectionKey !== connection.key || connection.directCwd !== undefined) {
+                    runtime.client = await PiBrokerClient.connect(connection.brokerUrl, connection.identity, dependencies.fetch, connection.sessionKey);
+                    runtime.connectionKey = connection.key;
+                    runtime.directCwd = connection.directCwd;
+                }
+                startTasks(pi, ctx, dependencies, runtime);
+                await presentInbox(ctx, dependencies, runtime);
+            }
+            catch (error) {
+                notifyFailure(ctx, error);
+            }
+        });
+        pi.on("session_shutdown", async (event) => {
+            const shared = sharedRuntime();
+            stopTasks(shared);
+            // Every other reason replaces the session inside this process, which reuses the connection.
+            if (event.reason !== "quit")
+                return;
+            const client = shared.client;
+            delete shared.client;
+            delete shared.connectionKey;
+            shared.inbox?.close();
+            delete shared.inbox;
+            // A failed notice leaves the lease to lapse, as after a crash.
+            await client?.detach().catch(() => undefined);
+        });
+    };
+}
+function startTasks(pi, ctx, dependencies, runtime) {
+    runtime.inject = (content) => {
+        pi.sendMessage({ customType: PAGER_WAKE_TYPE, content, display: true }, { triggerTurn: true, ...(ctx.isIdle() ? {} : { deliverAs: "followUp" }) });
+    };
+    runtime.tasks.push({
+        cancel: dependencies.scheduler.repeat(adapterHeartbeatIntervalMs(dependencies.processEnv), () => {
+            void runtime.client?.heartbeat().catch((error) => {
+                notifyFailure(ctx, error);
+            });
+        }),
+    });
+}
+/**
+ * Open this process's inbox if it has none, present it on the current connection, and register it
+ * at once with a heartbeat.
+ *
+ * A failure to open is reported once and not retried: the session keeps its tools but receives no
+ * delivery, and its messages wait for a later session.
+ * @param ctx - Session context the failure is reported through.
+ * @param dependencies - Supplies the inbox opener.
+ * @param runtime - Shared runtime holding the connection and the inbox.
+ */
+async function presentInbox(ctx, dependencies, runtime) {
+    if (!runtime.inbox && !runtime.inboxFailed) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/require-await -- async turns a throwing sendMessage into the rejection the inbox reports as a refused delivery.
+            runtime.inbox = await dependencies.openInbox(async (content) => {
+                if (!runtime.inject)
+                    throw new Error("No Pi session is active");
+                runtime.inject(content);
+            });
+        }
+        catch (error) {
+            runtime.inboxFailed = true;
+            const cause = error instanceof Error ? error.message : String(error);
+            notifyFailure(ctx, new Error(`Pager inbox could not be opened, so this session receives no messages: ${cause}`));
+        }
+    }
+    if (runtime.inbox)
+        runtime.client?.presentDeliveryAddress(runtime.inbox.address);
+    await runtime.client?.heartbeat();
+}
+async function resolveConnection(dependencies, ctx) {
+    const brokerUrl = dependencies.processEnv[PI_BROKER_URL_ENVIRONMENT];
+    const agentId = dependencies.processEnv[PI_AGENT_ID_ENVIRONMENT];
+    const messagingReservation = dependencies.processEnv[PI_MESSAGING_RESERVATION_ENVIRONMENT];
+    const deliveryReservation = dependencies.processEnv[PI_DELIVERY_RESERVATION_ENVIRONMENT];
+    const sessionKey = harnessSessionKey("pi", ctx.sessionManager.getSessionId());
+    const launchValues = [brokerUrl, agentId, messagingReservation, deliveryReservation];
+    if (launchValues.some(Boolean)) {
+        if (!brokerUrl || !isAgentId(agentId) || !messagingReservation || !deliveryReservation) {
+            throw new Error("Pager launch identity is incomplete");
+        }
+        return {
+            brokerUrl,
+            identity: { agentId, messagingReservation, deliveryReservation },
+            key: `${brokerUrl}\u0000${agentId}`,
+            sessionKey,
+            directCwd: undefined,
+        };
+    }
+    const endpoints = await dependencies.ensureService(dependencies.readEnvironment());
+    const identity = await registerPiAgent({
+        request: dependencies.fetch,
+        brokerUrl: endpoints.mcpUrl,
+        workspacePath: ctx.cwd,
+        sessionName: ctx.sessionManager.getSessionId(),
+        sessionKey,
+    });
+    return {
+        brokerUrl: endpoints.mcpUrl,
+        identity,
+        key: `${endpoints.mcpUrl}\u0000${identity.agentId}`,
+        sessionKey,
+        directCwd: ctx.cwd,
+    };
+}
+function stopTasks(runtime) {
+    delete runtime.inject;
+    for (const task of runtime.tasks.splice(0))
+        task.cancel();
+}
+function notifyFailure(ctx, error) {
+    if (ctx.hasUI)
+        ctx.ui.notify(error instanceof Error ? error.message : "Pager request failed", "warning");
+}
+/**
+ * Recognise a runtime this build published, so a value from a differently shaped copy of the
+ * extension is replaced rather than adopted; whatever it scheduled keeps running with nothing
+ * holding it.
+ * @param value - Candidate runtime read from a shared runtime slot.
+ * @returns - True when every field this build reads is present and well formed.
+ */
+function isPiExtensionRuntime(value) {
+    return (isPlainObject(value) &&
+        "tasks" in value &&
+        Array.isArray(value.tasks) &&
+        value.tasks.every(isScheduledTask) &&
+        (!("inbox" in value) || value.inbox === undefined || isPagerInbox(value.inbox)));
+}
+function isPagerInbox(value) {
+    return isPlainObject(value) && typeof value.address === "string" && typeof value.close === "function";
+}
+function isScheduledTask(value) {
+    return isPlainObject(value) && typeof value.cancel === "function";
+}
+function recordInput(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("Pi tool arguments must be an object");
+    }
+    return Object.fromEntries(Object.entries(value));
+}
+function hasLaunchIdentity(environment) {
+    return [
+        environment[PI_BROKER_URL_ENVIRONMENT],
+        environment[PI_AGENT_ID_ENVIRONMENT],
+        environment[PI_MESSAGING_RESERVATION_ENVIRONMENT],
+        environment[PI_DELIVERY_RESERVATION_ENVIRONMENT],
+    ].some(Boolean);
+}
+const defaultDependencies = {
+    readEnvironment: () => readEmbeddedRuntimeEnvironment(process.env, resolveBunExecutable),
+    ensureService: (environment) => ensureBrokerService(environment),
+    processEnv: process.env,
+    fetch: (url, init) => globalThis.fetch(url, init),
+    runtimeSlot: systemPiRuntimeSlot(),
+    openInbox: (accept) => openPagerInbox(accept, tmpdir()),
+    scheduler: {
+        repeat: (intervalMs, task) => {
+            const handle = setInterval(task, intervalMs);
+            return () => {
+                clearInterval(handle);
+            };
+        },
+    },
+};
+export default createPiExtension(defaultDependencies);

package/dist/src/implementations/pi/host-slots.d.ts

@@ -0,0 +1,18 @@
+/** Shares one value across every loaded copy of the Pi extension within one host process. */
+export type PiHostSlot<T> = {
+    /** Reads the value another loaded copy of the extension may already have published. */
+    get(): T | undefined;
+    /** Publishes a value for another loaded copy of the extension to adopt. */
+    set(value: T): void;
+};
+/**
+ * Build the production runtime slot backed by the shared host global.
+ * @returns - Slot reading and writing the process-wide runtime symbol.
+ */
+export declare function systemPiRuntimeSlot<T>(): PiHostSlot<T>;
+/**
+ * Track which `pi` hosts this build has already registered tools on, across every loaded copy of the
+ * extension module.
+ * @returns - Set shared through the process-wide api-registration symbol.
+ */
+export declare function loadedApis(): WeakSet<object>;

package/dist/src/implementations/pi/host-slots.js

@@ -0,0 +1,27 @@
+const runtimeKey = Symbol.for("pager.pi.runtime");
+const apiKey = Symbol.for("pager.pi.apis");
+/**
+ * Build the production runtime slot backed by the shared host global.
+ * @returns - Slot reading and writing the process-wide runtime symbol.
+ */
+export function systemPiRuntimeSlot() {
+    return {
+        get: () => Reflect.get(globalThis, runtimeKey),
+        set: (value) => {
+            Reflect.set(globalThis, runtimeKey, value);
+        },
+    };
+}
+/**
+ * Track which `pi` hosts this build has already registered tools on, across every loaded copy of the
+ * extension module.
+ * @returns - Set shared through the process-wide api-registration symbol.
+ */
+export function loadedApis() {
+    const existing = Reflect.get(globalThis, apiKey);
+    if (existing instanceof WeakSet)
+        return existing;
+    const apis = new WeakSet();
+    Reflect.set(globalThis, apiKey, apis);
+    return apis;
+}

package/dist/src/implementations/pi/manifest.d.ts

@@ -0,0 +1,11 @@
+import { type PagerInboxWriter } from "../../messaging/inbox-socket.js";
+import type { ImplementationProvider } from "../model.js";
+/**
+ * Construct the built-in Pi implementation provider.
+ * @param readVersion - Injected installed-version reader.
+ * @param writeInbox - Connection that writes one delivery into a session's inbox.
+ * @returns - Provider owning Pi launch and notification integration.
+ */
+export declare function createPiImplementationProvider(readVersion: () => string | null, writeInbox: PagerInboxWriter): ImplementationProvider;
+declare const _default: ImplementationProvider;
+export default _default;

package/dist/src/implementations/pi/manifest.js

@@ -0,0 +1,61 @@
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { deliverToPagerInbox, parsePagerInboxAddress, writePagerInbox, } from "../../messaging/inbox-socket.js";
+import { implementationId } from "../registry.js";
+import { PI_AGENT_ID_ENVIRONMENT, PI_BROKER_URL_ENVIRONMENT, PI_DELIVERY_RESERVATION_ENVIRONMENT, PI_MESSAGING_RESERVATION_ENVIRONMENT, } from "./environment.js";
+import { harnessSessionKey } from "../session-key.js";
+const extensionPath = fileURLToPath(new URL("./extension.js", import.meta.url));
+/**
+ * Construct the built-in Pi implementation provider.
+ * @param readVersion - Injected installed-version reader.
+ * @param writeInbox - Connection that writes one delivery into a session's inbox.
+ * @returns - Provider owning Pi launch and notification integration.
+ */
+export function createPiImplementationProvider(readVersion, writeInbox) {
+    const version = readVersion();
+    return {
+        descriptor: {
+            id: implementationId("pi"),
+            displayName: "Pi",
+            version: version ? { known: true, value: version } : { known: false },
+            capabilities: ["launch", "notification", "session-identity"],
+        },
+        launch: {
+            supported: true,
+            buildPlan: (request) => Promise.resolve({
+                command: "pi",
+                args: ["--extension", extensionPath, ...request.passthroughArgs],
+                environment: {
+                    [PI_AGENT_ID_ENVIRONMENT]: request.agentId,
+                    [PI_BROKER_URL_ENVIRONMENT]: request.brokerUrl,
+                },
+                sensitiveEnvironment: {
+                    [PI_MESSAGING_RESERVATION_ENVIRONMENT]: request.reservation,
+                    [PI_DELIVERY_RESERVATION_ENVIRONMENT]: request.deliveryReservation,
+                },
+                workspacePath: request.workspacePath,
+                title: "Pager — Pi",
+            }),
+        },
+        sessionIdentity: {
+            supported: true,
+            sessionKey: ({ hostSessionId }) => harnessSessionKey("pi", hostSessionId),
+        },
+        hostRegistration: { supported: false },
+        notification: {
+            supported: true,
+            mode: "host-push",
+            parseAddress: parsePagerInboxAddress,
+            deliver: (address, wake) => deliverToPagerInbox(writeInbox, address, wake),
+        },
+    };
+}
+function installedVersion() {
+    try {
+        return execFileSync("pi", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export default createPiImplementationProvider(installedVersion, writePagerInbox);

package/dist/src/implementations/pi/self-close-tool.d.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/**
+ * Register the Pi-local tool that requests an orderly process exit.
+ * @param pi - Pi extension API receiving the tool registration.
+ * @param beforeShutdown - Synchronous cleanup that prevents extension work from delaying exit.
+ */
+export declare function registerPiSelfCloseTool(pi: ExtensionAPI, beforeShutdown: () => void): void;

package/dist/src/implementations/pi/self-close-tool.js

@@ -0,0 +1,27 @@
+import { Type } from "typebox";
+/**
+ * Register the Pi-local tool that requests an orderly process exit.
+ * @param pi - Pi extension API receiving the tool registration.
+ * @param beforeShutdown - Synchronous cleanup that prevents extension work from delaying exit.
+ */
+export function registerPiSelfCloseTool(pi, beforeShutdown) {
+    let shutdownRequested = false;
+    pi.registerTool({
+        name: "close_pi_session",
+        label: "Close Pi Session",
+        description: "Gracefully close this Pi session after assigned work is complete and no further response is needed.",
+        parameters: Type.Object({}, { additionalProperties: false }),
+        execute: (_toolCallId, _params, _signal, _onUpdate, ctx) => {
+            if (!shutdownRequested) {
+                beforeShutdown();
+                ctx.shutdown();
+                shutdownRequested = true;
+            }
+            return Promise.resolve({
+                content: [{ type: "text", text: "Graceful Pi shutdown requested." }],
+                details: { requested: true },
+                terminate: true,
+            });
+        },
+    });
+}

package/dist/src/implementations/registry.d.ts

@@ -0,0 +1,47 @@
+import type { ImplementationDescriptor, ImplementationId, ImplementationProvider } from "./model.js";
+/** Supplies generic filesystem and module-loading operations for provider discovery. */
+export interface ImplementationDiscoveryPort {
+    /** Lists immediate implementation directories beneath the configured root. */
+    listDirectories(root: string): Promise<readonly string[]>;
+    /** Loads the provider exported by one conventionally named manifest. */
+    loadProvider(manifestPath: string): Promise<unknown>;
+}
+/**
+ * Validate and brand an open implementation identifier.
+ * @param value - Untrusted identifier value to validate.
+ * @returns - Validated open implementation identifier.
+ */
+export declare function implementationId(value: unknown): ImplementationId;
+/**
+ * Validate an implementation provider loaded across a manifest boundary.
+ * @param value - Untrusted manifest export to validate.
+ * @param manifestPath - Manifest path named in validation diagnostics.
+ */
+export declare function assertImplementationProvider(value: unknown, manifestPath: string): asserts value is ImplementationProvider;
+/** Resolve open implementation ids through injected provider instances. */
+export declare class ImplementationRegistry {
+    #private;
+    /**
+     * Construct a registry after validating every provider and duplicate id.
+     * @param providers - Provider instances to validate and index.
+     */
+    constructor(providers: readonly ImplementationProvider[]);
+    /**
+     * Resolve one provider by opaque implementation id.
+     * @param id - Validated implementation identifier to resolve.
+     * @returns - Registered provider for the identifier.
+     */
+    resolve(id: ImplementationId): ImplementationProvider;
+    /**
+     * List validated descriptors without exposing concrete provider types.
+     * @returns - Validated descriptors in registry insertion order.
+     */
+    descriptors(): readonly ImplementationDescriptor[];
+}
+/**
+ * Discover implementation manifests beneath a configured root by convention.
+ * @param root - Configured directory containing implementation subdirectories.
+ * @param port - Injected discovery and module-loading boundary.
+ * @returns - Registry containing every validated discovered provider.
+ */
+export declare function discoverImplementationRegistry(root: string, port: ImplementationDiscoveryPort): Promise<ImplementationRegistry>;

package/dist/src/implementations/registry.js

@@ -0,0 +1,157 @@
+import { join } from "node:path";
+import { ProtocolError, validateImplementationId } from "../broker/protocol.js";
+import { isPlainObject as isRecord } from "../shared/guards.js";
+const DISPLAY_NAME_MAX_LENGTH = 80;
+/**
+ * Spells the capability vocabulary as the keys of an exhaustive record, so the compiler refuses a
+ * list that has drifted from {@link ImplementationCapabilityName}.
+ */
+const capabilityNames = Object.keys({
+    launch: true,
+    notification: true,
+    "session-identity": true,
+    "host-registration": true,
+});
+/**
+ * Validate and brand an open implementation identifier.
+ * @param value - Untrusted identifier value to validate.
+ * @returns - Validated open implementation identifier.
+ */
+export function implementationId(value) {
+    return validateImplementationId(value);
+}
+/**
+ * Validate an implementation provider loaded across a manifest boundary.
+ * @param value - Untrusted manifest export to validate.
+ * @param manifestPath - Manifest path named in validation diagnostics.
+ */
+export function assertImplementationProvider(value, manifestPath) {
+    if (!isRecord(value))
+        invalidManifest(manifestPath, "must export an implementation provider");
+    const descriptor = value.descriptor;
+    if (!isRecord(descriptor))
+        invalidManifest(manifestPath, "must export a descriptor");
+    implementationId(descriptor.id);
+    if (typeof descriptor.displayName !== "string" ||
+        descriptor.displayName.length < 1 ||
+        descriptor.displayName.length > DISPLAY_NAME_MAX_LENGTH) {
+        invalidManifest(manifestPath, "has an invalid display name");
+    }
+    if (!isKnownVersion(descriptor.version))
+        invalidManifest(manifestPath, "has an invalid version value");
+    if (!Array.isArray(descriptor.capabilities))
+        invalidManifest(manifestPath, "must declare capabilities");
+    const declared = new Set();
+    for (const capability of descriptor.capabilities) {
+        if (!isCapabilityName(capability))
+            invalidManifest(manifestPath, "declares an unknown capability");
+        if (declared.has(capability))
+            invalidManifest(manifestPath, `declares duplicate capability ${capability}`);
+        declared.add(capability);
+    }
+    const capabilitySupport = {
+        launch: capabilitySupportState(value.launch, "buildPlan", manifestPath, "launch"),
+        notification: notificationSupportState(value.notification, manifestPath),
+        "session-identity": capabilitySupportState(value.sessionIdentity, "sessionKey", manifestPath, "session-identity"),
+        "host-registration": capabilitySupportState(value.hostRegistration, "registrationCommand", manifestPath, "host-registration"),
+    };
+    for (const capability of capabilityNames) {
+        if (declared.has(capability) !== capabilitySupport[capability]) {
+            invalidManifest(manifestPath, `descriptor and provider disagree about capability ${capability}`);
+        }
+    }
+}
+/** Resolve open implementation ids through injected provider instances. */
+export class ImplementationRegistry {
+    #providers;
+    /**
+     * Construct a registry after validating every provider and duplicate id.
+     * @param providers - Provider instances to validate and index.
+     */
+    constructor(providers) {
+        const indexed = new Map();
+        for (const provider of providers) {
+            assertImplementationProvider(provider, `provider:${String(provider.descriptor.id)}`);
+            if (indexed.has(provider.descriptor.id)) {
+                throw new ProtocolError("conflict", `duplicate implementation id: ${provider.descriptor.id}`);
+            }
+            indexed.set(provider.descriptor.id, provider);
+        }
+        this.#providers = indexed;
+    }
+    /**
+     * Resolve one provider by opaque implementation id.
+     * @param id - Validated implementation identifier to resolve.
+     * @returns - Registered provider for the identifier.
+     */
+    resolve(id) {
+        const provider = this.#providers.get(id);
+        if (!provider)
+            throw new ProtocolError("validation_failed", `unknown implementation id: ${id}`);
+        return provider;
+    }
+    /**
+     * List validated descriptors without exposing concrete provider types.
+     * @returns - Validated descriptors in registry insertion order.
+     */
+    descriptors() {
+        return [...this.#providers.values()].map((provider) => provider.descriptor);
+    }
+}
+/**
+ * Discover implementation manifests beneath a configured root by convention.
+ * @param root - Configured directory containing implementation subdirectories.
+ * @param port - Injected discovery and module-loading boundary.
+ * @returns - Registry containing every validated discovered provider.
+ */
+export async function discoverImplementationRegistry(root, port) {
+    const directories = [...(await port.listDirectories(root))].sort();
+    const providers = [];
+    for (const directory of directories) {
+        implementationId(directory);
+        const manifestPath = join(root, directory, "manifest.js");
+        const provider = await port.loadProvider(manifestPath);
+        assertImplementationProvider(provider, manifestPath);
+        if (provider.descriptor.id !== directory) {
+            invalidManifest(manifestPath, "descriptor id must match its implementation directory");
+        }
+        providers.push(provider);
+    }
+    return new ImplementationRegistry(providers);
+}
+function notificationSupportState(value, manifestPath) {
+    if (!isRecord(value) || typeof value.supported !== "boolean") {
+        invalidManifest(manifestPath, "has an invalid notification capability");
+    }
+    if (!value.supported)
+        return false;
+    if (value.mode !== "host-push")
+        invalidManifest(manifestPath, "has an invalid notification mode");
+    if (typeof value.parseAddress !== "function" || typeof value.deliver !== "function") {
+        invalidManifest(manifestPath, "has no parseAddress and deliver operations for notification mode host-push");
+    }
+    return true;
+}
+function capabilitySupportState(value, operation, manifestPath, capability) {
+    if (!isRecord(value) || typeof value.supported !== "boolean") {
+        invalidManifest(manifestPath, `has an invalid ${capability} capability`);
+    }
+    if (value.supported && typeof value[operation] !== "function") {
+        invalidManifest(manifestPath, `has no ${operation} operation for capability ${capability}`);
+    }
+    if (!value.supported && operation in value) {
+        invalidManifest(manifestPath, `exposes ${operation} while capability ${capability} is unsupported`);
+    }
+    return value.supported;
+}
+function isCapabilityName(value) {
+    return typeof value === "string" && capabilityNames.includes(value);
+}
+function isKnownVersion(value) {
+    if (!isRecord(value) || typeof value.known !== "boolean")
+        return false;
+    return value.known ? typeof value.value === "string" && value.value.length > 0 : !("value" in value);
+}
+function invalidManifest(manifestPath, reason) {
+    throw new ProtocolError("validation_failed", `invalid implementation manifest ${manifestPath}: ${reason}`);
+}

package/dist/src/implementations/session-key.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Qualify a harness-supplied conversation identifier so keys cannot collide between implementations.
+ *
+ * The broker accepts a key as an opaque string, so an unqualified identifier from one harness could
+ * name another harness's conversation. A value the harness did not supply, or one the broker would
+ * refuse once qualified, yields no key: registering anew is correct, adopting a guess is not. The
+ * qualified form is what is checked, so the bound this applies is the broker's own rather than a
+ * second, tighter one that would refuse keys the broker accepts.
+ * @param implementationId - Validated implementation identity that owns the conversation.
+ * @param hostSessionId - Conversation identifier reported by the harness, when it reported one.
+ * @returns - Qualified session key, or nothing when no usable identifier was supplied.
+ */
+export declare function harnessSessionKey(implementationId: string, hostSessionId: string | undefined): string | undefined;

package/dist/src/implementations/session-key.js

@@ -0,0 +1,19 @@
+import { isSessionKey } from "../broker/protocol.js";
+/**
+ * Qualify a harness-supplied conversation identifier so keys cannot collide between implementations.
+ *
+ * The broker accepts a key as an opaque string, so an unqualified identifier from one harness could
+ * name another harness's conversation. A value the harness did not supply, or one the broker would
+ * refuse once qualified, yields no key: registering anew is correct, adopting a guess is not. The
+ * qualified form is what is checked, so the bound this applies is the broker's own rather than a
+ * second, tighter one that would refuse keys the broker accepts.
+ * @param implementationId - Validated implementation identity that owns the conversation.
+ * @param hostSessionId - Conversation identifier reported by the harness, when it reported one.
+ * @returns - Qualified session key, or nothing when no usable identifier was supplied.
+ */
+export function harnessSessionKey(implementationId, hostSessionId) {
+    if (!hostSessionId)
+        return undefined;
+    const key = `${implementationId}:${hostSessionId}`;
+    return isSessionKey(key) ? key : undefined;
+}