@haywoodmarx/agent-pager 0.1.0

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

@@ -0,0 +1,187 @@
+import { FETCH_LIMIT_DEFAULT } from "../broker/protocol.js";
+/**
+ * Turns wakes for host-push recipients into deliveries written by their implementation.
+ *
+ * The service claims on the recipient's behalf immediately before writing, so a message is never
+ * held by a session that has not been handed it. A wake for a recipient without a registered
+ * address is left to the redelivery schedule, which offers it again once an address arrives.
+ */
+export class PushDeliveryService {
+    /**
+     * Hand one diagnostic to the report port, absorbing whatever the port does with it.
+     *
+     * Every call site is annotating an outcome it is in the middle of handling — a delivery that
+     * failed, an address that would not parse — so a sink that throws would replace the outcome with
+     * its own.
+     * @param message - Operator-facing diagnostic to report.
+     */
+    #report(message) {
+        try {
+            this.#dependencies.report(message);
+        }
+        catch {
+            // A diagnostic that cannot be delivered is not worth losing the outcome it described.
+        }
+    }
+    #dependencies;
+    #registrations = new Map();
+    #chains = new Map();
+    /**
+     * Construct the service over injected broker, hub, scheduler, and capability resolution.
+     * @param dependencies - Collaborators the service reaches outside its own state.
+     */
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    /**
+     * Hold the address a session registered, and deliver anything already waiting for it.
+     *
+     * An unchanged address is a no-op.
+     * @param agentId - Recipient whose session supplied the address.
+     * @param raw - Untrusted address text exactly as the session supplied it.
+     * @returns - What the registration changed.
+     */
+    registerAddress(agentId, raw) {
+        const existing = this.#registrations.get(agentId);
+        if (existing?.raw === raw)
+            return "unchanged";
+        const implementation = this.#dependencies.broker.implementationForAgent(agentId);
+        const capability = implementation ? this.#dependencies.capabilityFor(implementation.id) : undefined;
+        if (!capability)
+            return "not_push";
+        const parsed = capability.parseAddress(raw);
+        if (!parsed.known) {
+            this.#report(`pager delivery: ${agentId} registered a malformed delivery address`);
+            return "rejected";
+        }
+        existing?.unsubscribe();
+        // A host process reuses one physical inbox across the identities it registers in turn (Pi's
+        // direct-mode re-registration is the case this guards): if the identity that previously held it
+        // never got the chance to detach — the call itself failed, not only a successful one — its
+        // registration would otherwise sit here pointing at the same address this new one is about to
+        // claim, and a wake meant for it would still land in the inbox the new identity now reads.
+        for (const [holder, registration] of this.#registrations) {
+            if (holder !== agentId && registration.raw === raw)
+                this.forget(holder);
+        }
+        const unsubscribe = this.#dependencies.hub.subscribe(agentId, (event) => {
+            this.#enqueue(agentId, event);
+        });
+        this.#registrations.set(agentId, { raw, address: parsed.value, capability, unsubscribe });
+        this.#dependencies.scheduler.declareAdapter(agentId, { coalescing: true, maxProtocolVersion: 1 });
+        if (this.#dependencies.broker.hasQueuedMessages(agentId))
+            this.#dependencies.scheduler.notify(agentId, "resync");
+        return "registered";
+    }
+    /**
+     * Drop a recipient's address so no further wake is written to it.
+     * @param agentId - Recipient whose address is no longer usable.
+     */
+    forget(agentId) {
+        this.#registrations.get(agentId)?.unsubscribe();
+        this.#registrations.delete(agentId);
+    }
+    /**
+     * Report whether a recipient currently has an address to deliver to.
+     * @param agentId - Recipient to check.
+     * @returns - Whether a delivery address is held for the recipient.
+     */
+    hasAddress(agentId) {
+        return this.#registrations.has(agentId);
+    }
+    /**
+     * Resolve once every delivery in flight, and every one released by their completion, has finished.
+     * @returns - Settles when no delivery chain remains.
+     */
+    async settled() {
+        while (this.#chains.size > 0)
+            await Promise.all([...this.#chains.values()]);
+    }
+    /** Drop every address and stop listening for wakes. */
+    close() {
+        for (const agentId of [...this.#registrations.keys()])
+            this.forget(agentId);
+    }
+    #enqueue(agentId, event) {
+        const previous = this.#chains.get(agentId) ?? Promise.resolve();
+        const next = previous.then(() => this.#deliver(agentId, event));
+        this.#chains.set(agentId, next);
+        void next.finally(() => {
+            if (this.#chains.get(agentId) === next)
+                this.#chains.delete(agentId);
+        });
+    }
+    async #deliver(agentId, event) {
+        const registration = this.#registrations.get(agentId);
+        if (!registration)
+            return;
+        // A shed wake is the scheduler recording that budget refused this one; the schedule offers the
+        // inbox again later, so nothing is written now.
+        if (event.reason === "shed")
+            return;
+        this.#dependencies.scheduler.setBusy(agentId, true);
+        try {
+            if (event.reason === "operator_ping") {
+                await this.#write(agentId, registration, event, []);
+                return;
+            }
+            const claims = this.#dependencies.broker
+                .fetch({ agentId, limit: FETCH_LIMIT_DEFAULT, claimedBy: "delivery" })
+                .map(({ id, fromAddress, broadcastAddress, subject, type, body, claimToken }) => ({
+                id,
+                fromAddress,
+                ...(broadcastAddress === undefined ? {} : { broadcastAddress }),
+                subject,
+                type,
+                body,
+                claimToken,
+            }));
+            if (claims.length === 0)
+                return;
+            const wake = {
+                type: "claims_delivered",
+                agentId,
+                pushedAt: this.#dependencies.now(),
+                claims,
+            };
+            await this.#write(agentId, registration, wake, claims);
+        }
+        finally {
+            this.#dependencies.scheduler.setBusy(agentId, false);
+        }
+    }
+    async #write(agentId, registration, wake, claims) {
+        let reach;
+        try {
+            reach = await registration.capability.deliver(registration.address, wake);
+        }
+        catch (error) {
+            reach = { reach: "undelivered", cause: error instanceof Error ? error.message : String(error) };
+        }
+        switch (reach.reach) {
+            case "claimed":
+                for (const claim of claims)
+                    this.#dependencies.broker.recordNotification(claim.id, "delivered");
+                return;
+            case "notified":
+                // A body-free wake carries no claims, so a transport reporting one for a claim-carrying wake
+                // handed nothing over; the recipient must be offered the messages again.
+                if (claims.length > 0)
+                    this.#release(agentId, claims, "transport wrote a body-free wake for claims");
+                return;
+            case "undelivered":
+                this.#release(agentId, claims, reach.cause);
+                // The session re-registers on its next request if it is still alive.
+                if (this.#registrations.get(agentId) === registration)
+                    this.forget(agentId);
+                return;
+        }
+    }
+    #release(agentId, claims, cause) {
+        const broker = this.#dependencies.broker;
+        broker.releaseClaims(agentId, claims.map(({ claimToken }) => claimToken));
+        for (const claim of claims)
+            broker.recordNotification(claim.id, "failed");
+        this.#report(`pager delivery: ${agentId} not delivered: ${cause}`);
+    }
+}

package/dist/src/messaging/tools.d.ts

@@ -0,0 +1,11 @@
+/** Describes one MCP tool at the shared server discovery boundary. */
+export type McpToolDefinition = {
+    /** Supplies the stable tool name. */
+    name: string;
+    /** Explains the operation to an MCP client. */
+    description: string;
+    /** Validates caller-controlled tool arguments. */
+    inputSchema: Record<string, unknown>;
+};
+/** Supplies the single discovery declaration consumed by every Pager MCP server. */
+export declare const MCP_TOOLS: readonly McpToolDefinition[];

package/dist/src/messaging/tools.js

@@ -0,0 +1,102 @@
+import { FETCH_LIMIT_DEFAULT, MESSAGE_SUBJECT_LIMIT_CHARACTERS, MESSAGE_TYPE_LIMIT_CHARACTERS, } from "../broker/protocol.js";
+const noArguments = { type: "object", properties: {}, additionalProperties: false };
+const schema = (properties, required = []) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+});
+const messageContent = {
+    subject: {
+        type: "string",
+        description: `One line, at most ${String(MESSAGE_SUBJECT_LIMIT_CHARACTERS)} characters. Keep it terse, like a commit summary; detail belongs in the body.`,
+    },
+    type: {
+        type: "string",
+        description: `Message category, at most ${String(MESSAGE_TYPE_LIMIT_CHARACTERS)} characters, such as "brief", "idle", or "question". Free text, first-class on the wire.`,
+    },
+    body: { description: "Message payload retained for the recipient to claim." },
+};
+/** Supplies the single discovery declaration consumed by every Pager MCP server. */
+export const MCP_TOOLS = [
+    {
+        name: "whoami",
+        description: "Return the authenticated agent id, current alias, and prior aliases.",
+        inputSchema: noArguments,
+    },
+    {
+        name: "update_agent_alias",
+        description: "Replace this agent's workspace-unique alias and durable session name. The alias is lowercased and inner whitespace becomes hyphens, so use the alias returned in the result rather than the one requested.",
+        inputSchema: schema({
+            alias: {
+                type: "string",
+                description: "New workspace-unique alias, with an optional leading @. Lowercased, and inner whitespace becomes hyphens.",
+            },
+        }, ["alias"]),
+    },
+    {
+        name: "list_team_members",
+        description: "List agents in this agent's own workspace.",
+        inputSchema: noArguments,
+    },
+    {
+        name: "list_agents",
+        description: "List every agent on the broker with the address that reaches it from any workspace.",
+        inputSchema: noArguments,
+    },
+    {
+        name: "send_agent_message",
+        description: "Durably send a message to an agent.",
+        inputSchema: schema({
+            to: {
+                type: "string",
+                description: "Recipient agent id, an alias in this workspace, or alias@workspace for an agent elsewhere.",
+            },
+            ...messageContent,
+            idempotencyKey: { type: "string", description: "Repeat of an earlier send; returns the original message." },
+        }, ["to", "subject", "body", "type"]),
+    },
+    {
+        name: "broadcast_agent_message",
+        description: "Durably send its own copy of one message to each other agent in a workspace, skipping archived agents and ended ephemeral sessions. The result lists each copy under `sent`, and under `refused` each recipient a rate or inbox limit turned away.",
+        inputSchema: schema({
+            workspace: {
+                type: "string",
+                description: "Workspace name, as it appears after the @ of an address; defaults to this agent's own.",
+            },
+            ...messageContent,
+            idempotencyKey: {
+                type: "string",
+                description: "Repeat of an earlier broadcast; returns its original message to each recipient it reached and sends to the rest.",
+            },
+        }, ["subject", "body", "type"]),
+    },
+    {
+        name: "fetch_agent_messages",
+        description: "Claim available inbox messages.",
+        inputSchema: schema({
+            limit: {
+                type: "number",
+                description: `Maximum messages to claim in this call; defaults to ${String(FETCH_LIMIT_DEFAULT)}.`,
+            },
+        }),
+    },
+    {
+        name: "ack_agent_messages",
+        description: "Acknowledge claimed messages. The result lists `acked` tokens and, for each token that acknowledged nothing, `rejected` with a reason: unknown_token, foreign_token, claim_expired (the message is back in the queue: fetch it again), already_acknowledged, or message_settled.",
+        inputSchema: schema({
+            claimTokens: {
+                type: "array",
+                description: "One claim token per message you hold; unacknowledged claims are redelivered.",
+                items: { type: "string", description: "Token delivered with the claim, authorizing this ack." },
+            },
+        }, ["claimTokens"]),
+    },
+    {
+        name: "get_message_status",
+        description: "Return a sender-visible message status.",
+        inputSchema: schema({ messageId: { type: "string", description: "Id of a message this agent sent." } }, [
+            "messageId",
+        ]),
+    },
+];

package/dist/src/messaging/wake.d.ts

@@ -0,0 +1,23 @@
+import type { InboxChanged } from "./notifications.js";
+/** Names the wake vocabulary shared by every implementation adapter. */
+export declare const PAGER_WAKE_TYPE = "pager-inbox";
+/**
+ * Build the flat body-free metadata every implementation exposes for one wake.
+ *
+ * The broker epoch is supplied rather than read from the event because implementations differ in
+ * whether they expose the raw epoch or its public digest to the model.
+ * @param event - Body-free inbox event published by the broker.
+ * @param brokerEpoch - Epoch value this implementation exposes to the model.
+ * @returns - Flat string metadata carrying no peer message body.
+ */
+export declare function wakeMetadata(event: InboxChanged, brokerEpoch: string): Record<string, string>;
+/**
+ * Render one wake as a single line, for adapters whose transport is line-delimited.
+ *
+ * Standing guidance is omitted because such an adapter establishes it once per session; the line
+ * carries only the shared metadata vocabulary.
+ * @param event - Body-free inbox event published by the broker.
+ * @param brokerEpoch - Epoch value this implementation exposes to the model.
+ * @returns - Single line with no embedded newline, never carrying a peer message body.
+ */
+export declare function wakeLine(event: InboxChanged, brokerEpoch: string): string;

package/dist/src/messaging/wake.js

@@ -0,0 +1,39 @@
+import { PROTOCOL_VERSION } from "../broker/protocol.js";
+/** Names the wake vocabulary shared by every implementation adapter. */
+export const PAGER_WAKE_TYPE = "pager-inbox";
+/**
+ * Build the flat body-free metadata every implementation exposes for one wake.
+ *
+ * The broker epoch is supplied rather than read from the event because implementations differ in
+ * whether they expose the raw epoch or its public digest to the model.
+ * @param event - Body-free inbox event published by the broker.
+ * @param brokerEpoch - Epoch value this implementation exposes to the model.
+ * @returns - Flat string metadata carrying no peer message body.
+ */
+export function wakeMetadata(event, brokerEpoch) {
+    return {
+        protocol_version: String(PROTOCOL_VERSION),
+        agent_id: event.agentId,
+        broker_epoch: brokerEpoch,
+        inbox_sequence: String(event.sequence),
+        reason: event.reason,
+        ...(event.reason === "operator_ping"
+            ? {
+                control_id: event.controlId,
+                coalesced_control_ids: JSON.stringify(event.coalescedControlIds),
+            }
+            : {}),
+    };
+}
+/**
+ * Render one wake as a single line, for adapters whose transport is line-delimited.
+ *
+ * Standing guidance is omitted because such an adapter establishes it once per session; the line
+ * carries only the shared metadata vocabulary.
+ * @param event - Body-free inbox event published by the broker.
+ * @param brokerEpoch - Epoch value this implementation exposes to the model.
+ * @returns - Single line with no embedded newline, never carrying a peer message body.
+ */
+export function wakeLine(event, brokerEpoch) {
+    return `${PAGER_WAKE_TYPE} ${JSON.stringify(wakeMetadata(event, brokerEpoch))}`;
+}

package/dist/src/operator/agent-projection.d.ts

@@ -0,0 +1,102 @@
+import type { BrokerSnapshot } from "../broker/snapshot.js";
+import { type OperatorDiagnosticSink } from "./diagnostics.js";
+import type { OperatorAcceptedDelivery, OperatorAgent, OperatorJsonObject, OperatorRepository, OperatorTraffic } from "./protocol.js";
+import { type RepositoryProjectionDependencies } from "./repository.js";
+/** Supplies installed-provider presentation data without interpreting open provider identities. */
+export interface OperatorImplementationCatalogPort {
+    /**
+     * Resolve public presentation metadata for one persisted provider identity.
+     * @param implementationId - Open provider identity stored with the agent.
+     * @returns Public provider data, or null when the provider is unavailable.
+     */
+    find(implementationId: string): {
+        displayName: string;
+        metadata: OperatorJsonObject;
+    } | null;
+}
+/** Supplies explicit collaborators to the repository and agent projection. */
+export type OperatorAgentProjectionDependencies = RepositoryProjectionDependencies & {
+    /** Resolves provider-owned public presentation data. */
+    implementations: OperatorImplementationCatalogPort;
+    /** Receives rows the projection could not admit; defaults to discarding them. */
+    diagnostics?: OperatorDiagnosticSink;
+    /** Supplies the observation clock; defaults to the wall clock. */
+    now?: () => number;
+};
+/** Carries bounded repository and agent collections for an operator snapshot producer. */
+export type OperatorAgentProjection = {
+    /** Lists presentation-only repository groups. */
+    repositories: OperatorRepository[];
+    /** Lists durable agents in stable registration order. */
+    agents: OperatorAgent[];
+};
+/** Reports an invalid or unbounded projection source. */
+export declare class OperatorAgentProjectionError extends Error {
+}
+/**
+ * Project broker snapshot repositories and agents without changing broker identities.
+ * @param snapshot - Authoritative broker state containing durable identity and attachment facts.
+ * @param dependencies - Explicit repository and implementation collaborators.
+ * @returns Bounded repositories and agents suitable for an operator snapshot.
+ */
+export declare function projectOperatorAgents(snapshot: Pick<BrokerSnapshot, "workspaces" | "agents" | "connections">, dependencies: OperatorAgentProjectionDependencies): OperatorAgentProjection;
+/** Describes the presentation-neutral health classification for one agent. */
+export type OperatorAgentHealth = {
+    kind: "archived";
+} | {
+    kind: "connection_disconnected";
+} | {
+    kind: "delivery_queued";
+} | {
+    kind: "delivery_claimed";
+} | {
+    kind: "delivery_failed";
+} | {
+    kind: "delivery_acknowledged";
+} | {
+    kind: "neutral";
+};
+/**
+ * Report why an agent belongs to the operator archive rather than the active list.
+ *
+ * Archive membership is not lifecycle alone: an agent whose workspace directory has been removed
+ * can no longer be worked in, so it archives while the broker still holds it active and routable.
+ * An operator-archived agent whose workspace is still there did not lose its workspace, so a surface
+ * naming the cause must be told which one it is. The causes can hold together, and the first that holds
+ * is reported, in this order: the operator's archive, then lifecycle, then a removed workspace. The
+ * operator's own action comes first because it is why they see the agent archived.
+ * @param agent - Projected agent whose archive cause is requested.
+ * @returns The first cause that holds, or null when the agent is still active.
+ */
+export declare function operatorArchiveReason(agent: OperatorAgent): "operator" | "lifecycle" | "workspace_removed" | null;
+/**
+ * Decide whether an agent belongs to the operator archive rather than the active list.
+ * @param agent - Projected agent whose archive membership is requested.
+ * @returns True when the agent belongs in a repository's archived section.
+ */
+export declare function isOperatorAgentArchived(agent: OperatorAgent): boolean;
+/**
+ * Select the repositories whose every conversation is archived.
+ *
+ * A repository holding no agents at all is not archived: there is nothing in it that ended.
+ * @param agents - Projected agents across every repository.
+ * @returns - Identities of the repositories that are archived in their entirety.
+ */
+export declare function archivedOperatorRepositoryIds(agents: readonly OperatorAgent[]): ReadonlySet<string>;
+/**
+ * Select one exhaustive health classification from authoritative agent and traffic facts.
+ * @param agent - Projected agent whose health is requested.
+ * @param traffic - Complete operator traffic collection for the snapshot.
+ * @returns The first classification that applies: archived, then disconnected (an expired connection
+ * counts), then the state of the agent's newest accepted delivery, where an expired delivery is neutral.
+ */
+export declare function selectOperatorAgentHealth(agent: OperatorAgent, traffic: readonly OperatorTraffic[]): OperatorAgentHealth;
+/**
+ * Report whether the broker would still accept an expiry for one delivery.
+ *
+ * Expiry moves a message to a terminal state, so a delivery already in one is refused with a conflict.
+ * Offering the action anyway would put the operator's only feedback in the diagnostics log.
+ * @param message - Delivery the operator is being offered expiry for.
+ * @returns Whether expiry can still change this delivery's state.
+ */
+export declare function isTuiExpirable(message: OperatorAcceptedDelivery): boolean;