@haywoodmarx/agent-pager 0.1.0

package/dist/src/operator/agent-projection.js

@@ -0,0 +1,249 @@
+import { uniquePathNames } from "../broker/address.js";
+import { operatorDiagnostic } from "./diagnostics.js";
+import { projectRepositoryLocation } from "./repository.js";
+import { OPERATOR_ARRAY_LENGTH_LIMIT, validateOperatorAgent, validateOperatorRepository } from "./validation.js";
+/** Reports an invalid or unbounded projection source. */
+export 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 function projectOperatorAgents(snapshot, dependencies) {
+    assertBounded(snapshot.workspaces.length, "workspace projection");
+    assertBounded(snapshot.agents.length, "agent projection");
+    const connections = snapshot.connections;
+    const locationsByWorkspace = new Map();
+    const rootPathsById = new Map();
+    const admitted = [];
+    for (const [index, workspace] of snapshot.workspaces.entries()) {
+        if (locationsByWorkspace.has(workspace.id)) {
+            throw new OperatorAgentProjectionError(`duplicate broker workspace identity: ${workspace.id}`);
+        }
+        const location = projectRepositoryLocation(workspace.path, dependencies);
+        const existing = rootPathsById.get(location.repository.id);
+        if (existing !== undefined && existing !== location.repository.rootPath) {
+            throw new OperatorAgentProjectionError(`repository identity collision: ${location.repository.id}`);
+        }
+        rootPathsById.set(location.repository.id, location.repository.rootPath);
+        admitted.push({ index, id: location.repository.id });
+        locationsByWorkspace.set(workspace.id, location);
+    }
+    const repositoryNames = uniquePathNames([...rootPathsById].map(([id, path]) => ({ id, path })));
+    const repositoriesById = new Map();
+    for (const { index, id } of admitted) {
+        try {
+            repositoriesById.set(id, validateOperatorRepository({
+                id,
+                rootPath: rootPathsById.get(id) ?? "",
+                name: repositoryNames.get(id) ?? id,
+            }));
+        }
+        catch (error) {
+            reportSkipped(dependencies, "repository", index, error);
+        }
+    }
+    const workspaceNames = uniquePathNames(snapshot.workspaces);
+    const connectionsByAgent = new Map(connections.map((connection) => [connection.agentId, connection]));
+    const agents = [];
+    for (const [index, agent] of snapshot.agents.entries()) {
+        const location = locationsByWorkspace.get(agent.workspaceId);
+        if (!location) {
+            reportSkipped(dependencies, "agent", index, new Error("agent references an unprojected broker workspace"));
+            continue;
+        }
+        try {
+            agents.push(validateOperatorAgent({
+                id: agent.id,
+                alias: bareAlias(agent.alias),
+                previousAliases: agent.previousAliases.map(bareAlias),
+                registeredAt: agent.createdAt,
+                lifecycle: agent.state,
+                archivedAt: agent.archivedAt,
+                workspaceAvailable: location.available,
+                workspace: workspaceNames.get(agent.workspaceId) ?? agent.workspaceId,
+                brokerIdentity: { teamId: agent.teamId, workspaceId: agent.workspaceId },
+                repository: { repositoryId: location.repository.id, worktree: location.worktree },
+                adapter: adapterFromConnection(connectionsByAgent.get(agent.id)),
+                implementation: projectImplementation(agent, dependencies.implementations),
+            }));
+        }
+        catch (error) {
+            reportSkipped(dependencies, "agent", index, error);
+        }
+    }
+    agents.sort((left, right) => left.registeredAt - right.registeredAt || compareStableText(left.id, right.id));
+    const repositories = [...repositoriesById.values()].sort((left, right) => compareStableText(left.rootPath, right.rootPath) || compareStableText(left.id, right.id));
+    assertBounded(repositories.length, "repository projection");
+    return { repositories, agents };
+}
+/**
+ * Strip the at-sign a broker alias is displayed with.
+ *
+ * The at-sign is a presentation pattern, so the operator contract carries the name without it.
+ * @param alias - Broker alias, which may carry a leading at-sign.
+ * @returns The alias without its at-sign.
+ */
+function bareAlias(alias) {
+    return alias.replace(/^@/u, "");
+}
+/**
+ * Recover the three-state adapter contract from the snapshot's single connection encoding.
+ *
+ * `connections[].state` alone cannot distinguish a session that expired from one that was closed
+ * or never existed; `lastSeenAt` (the creation time of the open session the connection state is
+ * read from: the newest unexpired one, else the newest open one) does.
+ * @param connection - This agent's entry in the snapshot's connections list, if any.
+ * @returns Adapter state and last observation for the projected agent.
+ */
+function adapterFromConnection(connection) {
+    if (!connection)
+        return { state: "disconnected", lastSeenAt: null };
+    // A connected connection always came from a session row, so its lastSeenAt is never null.
+    if (connection.state === "connected" && connection.lastSeenAt !== null)
+        return { state: "connected", lastSeenAt: connection.lastSeenAt };
+    if (connection.lastSeenAt !== null)
+        return { state: "expired", lastSeenAt: connection.lastSeenAt };
+    return { state: "disconnected", lastSeenAt: null };
+}
+function reportSkipped(dependencies, scope, index, error) {
+    dependencies.diagnostics?.report(operatorDiagnostic("broker", "warning", `${scope} projection`, `row ${String(index)} skipped: ${error instanceof Error ? error.message : "unknown projection failure"}`, (dependencies.now ?? Date.now)()));
+}
+/**
+ * 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 function operatorArchiveReason(agent) {
+    if (agent.archivedAt !== null)
+        return "operator";
+    if (agent.lifecycle !== "active")
+        return "lifecycle";
+    if (!agent.workspaceAvailable)
+        return "workspace_removed";
+    return 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 function isOperatorAgentArchived(agent) {
+    return operatorArchiveReason(agent) !== null;
+}
+/**
+ * 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 function archivedOperatorRepositoryIds(agents) {
+    const active = new Set();
+    const seen = new Set();
+    for (const agent of agents) {
+        seen.add(agent.repository.repositoryId);
+        if (!isOperatorAgentArchived(agent))
+            active.add(agent.repository.repositoryId);
+    }
+    return new Set([...seen].filter((id) => !active.has(id)));
+}
+/**
+ * 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 function selectOperatorAgentHealth(agent, traffic) {
+    if (isOperatorAgentArchived(agent))
+        return { kind: "archived" };
+    switch (agent.adapter.state) {
+        case "disconnected":
+        case "expired":
+            return { kind: "connection_disconnected" };
+        case "connected":
+            break;
+    }
+    const acceptedSequences = new Set();
+    let newest;
+    for (const entry of traffic) {
+        if (entry.kind !== "accepted_delivery")
+            continue;
+        if (acceptedSequences.has(entry.acceptedSequence)) {
+            throw new OperatorAgentProjectionError(`duplicate accepted traffic sequence: ${String(entry.acceptedSequence)}`);
+        }
+        acceptedSequences.add(entry.acceptedSequence);
+        if (entry.fromAgentId !== agent.id && entry.toAgentId !== agent.id)
+            continue;
+        if (!newest || entry.acceptedSequence > newest.acceptedSequence)
+            newest = entry;
+    }
+    if (!newest)
+        return { kind: "neutral" };
+    switch (newest.state) {
+        case "queued":
+            return { kind: "delivery_queued" };
+        case "claimed":
+            return { kind: "delivery_claimed" };
+        case "failed":
+        case "dead_lettered":
+            return { kind: "delivery_failed" };
+        case "acknowledged":
+            return { kind: "delivery_acknowledged" };
+        case "expired":
+            return { kind: "neutral" };
+    }
+}
+function projectImplementation(agent, catalog) {
+    if (agent.implementation.id === null)
+        return { available: false, id: null, version: { known: false } };
+    const version = agent.implementation.version;
+    const descriptor = catalog.find(agent.implementation.id);
+    if (!descriptor)
+        return { available: false, id: agent.implementation.id, version };
+    return {
+        available: true,
+        id: agent.implementation.id,
+        displayName: descriptor.displayName,
+        version,
+        metadata: descriptor.metadata,
+    };
+}
+function assertBounded(length, label) {
+    if (length > OPERATOR_ARRAY_LENGTH_LIMIT) {
+        throw new OperatorAgentProjectionError(`${label} exceeds maximum array length of ${String(OPERATOR_ARRAY_LENGTH_LIMIT)}`);
+    }
+}
+function compareStableText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * 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 function isTuiExpirable(message) {
+    switch (message.state) {
+        case "queued":
+        case "claimed":
+            return true;
+        case "acknowledged":
+        case "expired":
+        case "dead_lettered":
+        case "failed":
+            return false;
+    }
+}

package/dist/src/operator/commands.d.ts

@@ -0,0 +1,50 @@
+import type { BrokerOperatorCommandAcceptance, BrokerOperatorCommandRecord } from "../broker/broker.js";
+import { type AgentId } from "../broker/protocol.js";
+import type { OperatorPingAdmission } from "../messaging/notifications.js";
+import { type OperatorCommandResult } from "./protocol.js";
+/** Supplies transactional command persistence without exposing broker storage to the operator boundary. */
+export interface OperatorCommandBrokerPort {
+    /** Return a prior durable acceptance for command-id idempotency. */
+    operatorCommand(commandId: string): BrokerOperatorCommandRecord | null;
+    /** Persist ping acceptance and audit before a wake becomes observable. */
+    acceptOperatorPing(commandId: string, targetAgentId: AgentId, controlId: string): BrokerOperatorCommandAcceptance;
+    /** Expire a message and persist command acceptance in one transaction. */
+    acceptOperatorExpiry(commandId: string, messageId: string): BrokerOperatorCommandAcceptance;
+    /** Mark an agent archived and persist command acceptance in one transaction, ending its attachments but leaving its inbox and addressability intact. */
+    acceptOperatorArchive(commandId: string, targetAgentId: AgentId): BrokerOperatorCommandAcceptance;
+}
+/** Supplies non-reentrant notification admission around durable ping acceptance. */
+export interface OperatorPingSchedulerPort {
+    /**
+     * Preflight a control wake, run durable acceptance, then publish or retain it.
+     * @param agentId - Broker target of the body-free control.
+     * @param controlId - Opaque durable correlation.
+     * @param commitAcceptance - Synchronous transaction callback classifying creation or an exact durable retry.
+     * @returns Scheduler-boundary admission without an adapter-delivery claim.
+     */
+    notifyOperatorPing(agentId: AgentId, controlId: string, commitAcceptance: () => "created" | "existing", resolveExisting: () => "absent" | "existing"): OperatorPingAdmission;
+}
+/** Explicit collaborators used by the renderer-neutral operator command boundary. */
+export type OperatorCommandDependencies = {
+    /** Owns durable command and traffic state. */
+    broker: OperatorCommandBrokerPort;
+    /** Owns body-free notification admission. */
+    scheduler: OperatorPingSchedulerPort;
+    /** Issues bounded opaque control correlations. */
+    issueControlId: () => string;
+};
+/** Admits validated operator commands without treating their submissions as authoritative state. */
+export declare class OperatorCommandService {
+    #private;
+    /**
+     * Construct a command boundary from explicit durable, scheduler, and correlation collaborators.
+     * @param dependencies - Collaborators selected by the production composition root.
+     */
+    constructor(dependencies: OperatorCommandDependencies);
+    /**
+     * Validate and admit one untrusted operator command envelope.
+     * @param value - Candidate request received at the operator boundary.
+     * @returns Correlated acceptance or stable pre-acceptance rejection.
+     */
+    execute(value: unknown): OperatorCommandResult;
+}

package/dist/src/operator/commands.js

@@ -0,0 +1,199 @@
+import { ProtocolError } from "../broker/protocol.js";
+import { OPERATOR_PROTOCOL_VERSION, } from "./protocol.js";
+import { validateOperatorCommand, validateOperatorCommandResult, validateOperatorControlId } from "./validation.js";
+/** Admits validated operator commands without treating their submissions as authoritative state. */
+export class OperatorCommandService {
+    #broker;
+    #scheduler;
+    #issueControlId;
+    /**
+     * Construct a command boundary from explicit durable, scheduler, and correlation collaborators.
+     * @param dependencies - Collaborators selected by the production composition root.
+     */
+    constructor(dependencies) {
+        this.#broker = dependencies.broker;
+        this.#scheduler = dependencies.scheduler;
+        this.#issueControlId = dependencies.issueControlId;
+    }
+    /**
+     * Validate and admit one untrusted operator command envelope.
+     * @param value - Candidate request received at the operator boundary.
+     * @returns Correlated acceptance or stable pre-acceptance rejection.
+     */
+    execute(value) {
+        const command = validateOperatorCommand(value);
+        try {
+            const prior = this.#broker.operatorCommand(command.commandId);
+            if (prior)
+                return this.#priorResult(command, prior);
+        }
+        catch (error) {
+            return rejected(command.commandId, rejectionReason(error));
+        }
+        switch (command.command.type) {
+            case "ping_agent":
+                return this.#ping({ ...command, command: command.command });
+            case "expire_message":
+                return this.#expire({ ...command, command: command.command });
+            case "archive_agent":
+                return this.#archive({ ...command, command: command.command });
+        }
+    }
+    #ping(command) {
+        const targetAgentId = command.command.targetAgentId;
+        let acceptedResult;
+        try {
+            const controlId = validateOperatorControlId(this.#issueControlId());
+            const admission = this.#scheduler.notifyOperatorPing(targetAgentId, controlId, () => {
+                const acceptance = this.#broker.acceptOperatorPing(command.commandId, targetAgentId, controlId);
+                assertPingAcceptance(acceptance, command.commandId, targetAgentId, controlId);
+                const result = pingAccepted(command.commandId, acceptance.record);
+                acceptedResult = result;
+                return acceptance.status;
+            }, () => {
+                const prior = this.#broker.operatorCommand(command.commandId);
+                if (!prior)
+                    return "absent";
+                const result = this.#priorResult(command, prior);
+                acceptedResult = result;
+                return "existing";
+            });
+            if (acceptedResult)
+                return acceptedResult;
+            if (admission.status === "budget_rejected")
+                return rejected(command.commandId, "wake_budget");
+            if (admission.status === "correlation_rejected")
+                return rejected(command.commandId, admission.reason);
+            throw new Error("Scheduler accepted a ping without durable command acceptance");
+        }
+        catch (error) {
+            if (acceptedResult)
+                return acceptedResult;
+            return rejected(command.commandId, rejectionReason(error));
+        }
+    }
+    #expire(command) {
+        try {
+            const acceptance = this.#broker.acceptOperatorExpiry(command.commandId, command.command.messageId);
+            assertExpiryAcceptance(acceptance, command.commandId, command.command.messageId);
+            const accepted = acceptance.record;
+            return validateOperatorCommandResult({
+                protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                type: "expiry_accepted",
+                status: "accepted",
+                commandId: command.commandId,
+                acceptedAt: accepted.acceptedAt,
+            });
+        }
+        catch (error) {
+            return rejected(command.commandId, rejectionReason(error));
+        }
+    }
+    #archive(command) {
+        try {
+            const acceptance = this.#broker.acceptOperatorArchive(command.commandId, command.command.targetAgentId);
+            const accepted = acceptance.record;
+            if (accepted.type !== "archive_agent" || accepted.commandId !== command.commandId) {
+                throw new Error("Broker returned a mismatched archive acceptance");
+            }
+            return validateOperatorCommandResult({
+                protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                type: "archive_accepted",
+                status: "accepted",
+                commandId: command.commandId,
+                acceptedAt: accepted.acceptedAt,
+            });
+        }
+        catch (error) {
+            return rejected(command.commandId, rejectionReason(error));
+        }
+    }
+    #priorResult(command, prior) {
+        const expectedTarget = command.command.type === "expire_message" ? command.command.messageId : command.command.targetAgentId;
+        if (prior.commandId !== command.commandId)
+            throw new Error("Broker returned a mismatched command lookup");
+        if (prior.type !== command.command.type || prior.targetId !== expectedTarget) {
+            return rejected(command.commandId, "command_id_conflict");
+        }
+        if (prior.type === "ping_agent")
+            validateOperatorControlId(prior.controlId);
+        if (prior.type === "ping_agent")
+            return validateOperatorCommandResult({
+                protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                type: "ping_accepted",
+                status: "accepted",
+                commandId: prior.commandId,
+                acceptedAt: prior.acceptedAt,
+                controlId: prior.controlId,
+            });
+        return validateOperatorCommandResult({
+            protocolVersion: OPERATOR_PROTOCOL_VERSION,
+            type: prior.type === "expire_message" ? "expiry_accepted" : "archive_accepted",
+            status: "accepted",
+            commandId: prior.commandId,
+            acceptedAt: prior.acceptedAt,
+        });
+    }
+}
+function pingAccepted(commandId, accepted) {
+    if (accepted.type !== "ping_agent" || accepted.commandId !== commandId)
+        throw new Error("Broker returned the wrong ping command acceptance");
+    return validateOperatorCommandResult({
+        protocolVersion: OPERATOR_PROTOCOL_VERSION,
+        type: "ping_accepted",
+        status: "accepted",
+        commandId,
+        acceptedAt: accepted.acceptedAt,
+        controlId: accepted.controlId,
+    });
+}
+function assertPingAcceptance(acceptance, commandId, targetAgentId, controlId) {
+    const { record, status } = acceptance;
+    assertAcceptanceStatus(status);
+    if (record.type !== "ping_agent" ||
+        record.commandId !== commandId ||
+        record.targetId !== targetAgentId ||
+        (status === "created" && record.controlId !== controlId)) {
+        throw new Error("Broker returned a mismatched ping command acceptance");
+    }
+    validateOperatorControlId(record.controlId);
+}
+function assertExpiryAcceptance(acceptance, commandId, messageId) {
+    const { record, status } = acceptance;
+    assertAcceptanceStatus(status);
+    if (record.type !== "expire_message" || record.commandId !== commandId || record.targetId !== messageId) {
+        throw new Error("Broker returned a mismatched expiry command acceptance");
+    }
+}
+function assertAcceptanceStatus(value) {
+    if (value !== "created" && value !== "existing") {
+        throw new Error("Broker returned an invalid command acceptance status");
+    }
+}
+function rejected(commandId, reason) {
+    return validateOperatorCommandResult({
+        protocolVersion: OPERATOR_PROTOCOL_VERSION,
+        type: "command_rejected",
+        status: "rejected",
+        commandId,
+        reason,
+    });
+}
+function rejectionReason(error) {
+    if (error instanceof ProtocolError) {
+        switch (error.code) {
+            case "validation_failed":
+            case "expired":
+                return "target_unavailable";
+            case "conflict":
+                return "conflict";
+            case "unsupported_version":
+            case "oversized_content":
+            case "unknown_recipient":
+            case "recipient_alias_changed":
+            case "alias_conflict":
+                return "rejected";
+        }
+    }
+    return "internal_error";
+}

package/dist/src/operator/diagnostics.d.ts

@@ -0,0 +1,21 @@
+import { type OperatorDiagnostic, type OperatorDiagnosticSeverity } from "./protocol.js";
+/** Receives operator-visible conditions without deciding how they are presented or transported. */
+export interface OperatorDiagnosticSink {
+    /**
+     * Record one condition.
+     * @param diagnostic - Content-free description of what was observed.
+     */
+    report(diagnostic: OperatorDiagnostic): void;
+}
+/** Discards every diagnostic, for callers that do not surface them. */
+export declare const SILENT_OPERATOR_DIAGNOSTICS: OperatorDiagnosticSink;
+/**
+ * Build one diagnostic whose text cannot exceed the bounded contract length.
+ * @param origin - Whether the broker reported the condition or the client observed it.
+ * @param severity - Attention the condition asks of an operator.
+ * @param scope - Subsystem the condition arose in.
+ * @param summary - Operator-facing statement carrying no message or identity content.
+ * @param at - Epoch milliseconds the condition was observed.
+ * @returns A diagnostic ready for the operator contract.
+ */
+export declare function operatorDiagnostic(origin: OperatorDiagnostic["origin"], severity: OperatorDiagnosticSeverity, scope: string, summary: string, at: number): OperatorDiagnostic;

package/dist/src/operator/diagnostics.js

@@ -0,0 +1,22 @@
+import { OPERATOR_DIAGNOSTIC_TEXT_LIMIT } from "./protocol.js";
+/** Discards every diagnostic, for callers that do not surface them. */
+export const SILENT_OPERATOR_DIAGNOSTICS = { report: () => undefined };
+/**
+ * Build one diagnostic whose text cannot exceed the bounded contract length.
+ * @param origin - Whether the broker reported the condition or the client observed it.
+ * @param severity - Attention the condition asks of an operator.
+ * @param scope - Subsystem the condition arose in.
+ * @param summary - Operator-facing statement carrying no message or identity content.
+ * @param at - Epoch milliseconds the condition was observed.
+ * @returns A diagnostic ready for the operator contract.
+ */
+export function operatorDiagnostic(origin, severity, scope, summary, at) {
+    return { at, origin, severity, scope: clamp(scope), summary: clamp(summary) };
+}
+function clamp(text) {
+    const collapsed = text.replaceAll(/\s+/gu, " ").trim();
+    const bounded = collapsed.length > OPERATOR_DIAGNOSTIC_TEXT_LIMIT
+        ? `${collapsed.slice(0, OPERATOR_DIAGNOSTIC_TEXT_LIMIT - 1)}…`
+        : collapsed;
+    return bounded === "" ? "unspecified" : bounded;
+}