@haywoodmarx/agent-pager 0.1.0

package/dist/src/broker/broker.d.ts

@@ -0,0 +1,665 @@
+import { type DatabaseDurability } from "./database.js";
+import { type AgentId, type MessageState } from "./protocol.js";
+import { type BrokerSnapshot, type SnapshotHealth } from "./snapshot.js";
+import { ATTACHMENT_CHANNELS } from "./schema.js";
+import { type BrokerOperationalEvent, type BrokerOperatorCommandAcceptance, type BrokerOperatorCommandRecord, type BrokerTrafficReadResult } from "./operator-projection.js";
+export type { BrokerAgentSkippedEvent, BrokerLifecycleSkippedEvent, BrokerOperationalEvent, BrokerOperatorCommandAcceptance, BrokerOperatorCommandRecord, BrokerShedReason, BrokerTrafficLifecycleRecord, BrokerTrafficReadResult, BrokerPingSkippedEvent, BrokerStoredRowSkippedEvent, BrokerTrafficRecord, BrokerTrafficSkippedEvent, } from "./operator-projection.js";
+/**
+ * Names what an attachment does, so re-attaching fences only the session it replaces. An agent
+ * exchanges messages and observes its inbox over separate attachments, and either may restart alone.
+ */
+export type AttachmentChannel = (typeof ATTACHMENT_CHANNELS)[number];
+/** Identifies an agent implementation without constraining adapter-specific values. */
+export type AgentImplementation = {
+    /** Supplies the opaque implementation identity chosen by the composition boundary. */
+    id: string;
+    /** Supplies an implementation version when the boundary can determine one. */
+    version?: string;
+};
+/**
+ * Records how far a wake got. `delivered` requires a recipient that confirms it accepted the wake;
+ * `shed` records a wake the broker's own budget policy discarded before it reached the transport.
+ */
+export type NotificationOutcome = "delivered" | "shed" | "failed" | "deferred";
+/** Represents a durable message currently claimed by an agent. */
+export type ClaimedMessage = {
+    /** Identifies the durable message. */
+    id: string;
+    /** Identifies the sending agent. */
+    from: AgentId;
+    /**
+     * Addresses the sending agent as `alias@workspace`, or by its agent id when it registered no
+     * alias. Always workspace-qualified, because a bare alias resolves against the sender's own
+     * workspace and a recipient elsewhere would reach a different agent with it.
+     */
+    fromAddress: string;
+    /** Identifies the receiving agent. */
+    to: AgentId;
+    /**
+     * Names the broadcast this message is one copy of, as `*@workspace` with the recipient's workspace
+     * under its current name; absent on a message sent to one agent.
+     */
+    broadcastAddress?: string;
+    /** Carries the one-line subject the sender supplied. */
+    subject: string;
+    /** Carries the sender-supplied message type. */
+    type: string;
+    /** Carries the claimed message body. */
+    body: unknown;
+    /** Authorizes acknowledgement of this specific claim. */
+    claimToken: string;
+    /** Records when the claim becomes eligible for redelivery. */
+    claimExpiresAt: number;
+};
+/** Records which path made a claim: the recipient fetching, or the broker delivering into its host. */
+export type ClaimSource = "fetch" | "delivery";
+/**
+ * Why an acknowledgement changed nothing. Every reason but `unknown_token` and `foreign_token` means
+ * the message is (or was) this agent's, and a `claim_expired` one is back in the queue for a fetch.
+ */
+export type AckRejectionReason = "unknown_token" | "foreign_token" | "claim_expired" | "already_acknowledged" | "message_settled";
+/** Outcome of {@link Broker.ack}: every distinct submitted token appears in exactly one of the two lists. */
+export type AckResult = {
+    /** Tokens whose claims this call acknowledged. */
+    acked: string[];
+    /** Tokens that acknowledged nothing, each with the reason, in submission order. */
+    rejected: {
+        claimToken: string;
+        reason: AckRejectionReason;
+    }[];
+};
+/** Outcome of {@link Broker.broadcast}: every recipient appears in exactly one of the two lists. */
+export type BroadcastResult = {
+    /** Names the broadcast as `*@workspace`, as every copy carries it. */
+    address: string;
+    /** Messages sent, one per recipient that received the broadcast. */
+    sent: {
+        messageId: string;
+        to: AgentId;
+    }[];
+    /** Recipients a pair rate or inbox limit refused, each with the refusal as a send would raise it. */
+    refused: {
+        to: AgentId;
+        code: "conflict";
+        message: string;
+    }[];
+};
+/** Options for {@link Broker.fetch}. */
+export type BrokerFetchRequest = {
+    /** Agent whose queue is fetched from. */
+    agentId: AgentId;
+    /** Maximum number of queued messages to claim. */
+    limit?: number;
+    /** Path making the claim; recorded on the message's lifecycle for the operator. */
+    claimedBy?: ClaimSource;
+};
+/** Configures broker timing, routing, and epoch ownership policies. */
+export type BrokerOptions = {
+    /**
+     * Supplies the clock used for durable lease timestamps.
+     *
+     * Required rather than defaulted, so one process cannot end up running its broker on a different
+     * clock from the collaborators that read the rows it writes.
+     */
+    now: () => number;
+    /**
+     * Reports the branch checked out at a workspace path, or null when it is not a repository.
+     *
+     * A port rather than a direct call because the real one is a `git` subprocess: it must run before
+     * the write transaction opens, and a test must be able to assert the persisted row without
+     * shelling out to whatever branch the developer's own checkout happens to be on.
+     */
+    workspaceBranch: (path: string) => string | null;
+    /** Sets the lifetime of an unacknowledged message claim. */
+    visibilityTimeoutMs?: number;
+    /** Sets the delay before the first redelivery wake for an inbox whose messages went unclaimed. */
+    redeliveryBaseDelayMs?: number;
+    /** Sets how long one inbox is retried before its undelivered messages are dead-lettered. */
+    redeliveryGiveUpMs?: number;
+    /** Sets the lifetime of an unattached agent reservation. */
+    reservationTtlMs?: number;
+    /** Sets the lifetime of an attached agent lease. */
+    leaseTtlMs?: number;
+    /** Sets how long a detached, unnamed identity remains resumable by its harness session key. */
+    resumableRetentionMs?: number;
+    /** Sets how long a named identity stays detached before it is archived. */
+    namedArchiveAfterMs?: number;
+    /** Sets how long an archived identity of any kind is kept, measured from its archival. */
+    archivedRetentionMs?: number;
+    /**
+     * Sets how long a detached, unnamed, resumable identity is kept while it has sent no message and
+     * received none addressed to it alone.
+     */
+    unusedResumableRetentionMs?: number;
+    /** Sets the maximum sends allowed for one sender-recipient pair. */
+    perPairRateLimit?: number;
+    /** Sets the measurement window for the pair rate limit. */
+    perPairRateWindowMs?: number;
+    /** Sets the maximum retained body size accepted by one send. */
+    maxBodyBytes?: number;
+    /** Sets the maximum queued or claimed messages retained for one recipient. */
+    maxInboxMessages?: number;
+    /**
+     * Whether this handle owns the broker epoch. The long-running singleton mints a fresh epoch on
+     * start, which invalidates outstanding MCP sessions. Handles opened for local bookkeeping must
+     * set this false so they read the current epoch without rotating it and detaching live agents.
+     */
+    epochOwner?: boolean;
+    /**
+     * Receives operator-facing diagnostics the broker cannot raise to a caller.
+     *
+     * A notification the broker sends on an agent's behalf has no caller to throw to: the sweep that
+     * triggered it must keep draining. Required rather than optional so that discarding these
+     * observations is something a root says, not something it gets by leaving a field out — the
+     * broker cannot write to a stream the embedding process may be using for something else, and an
+     * embedder that genuinely wants them gone can pass a sink that drops them.
+     */
+    report: (message: string) => void;
+};
+/** Reports which tables one committed transaction changed rows in. */
+export type BrokerCommit = {
+    /**
+     * Names every table the transaction changed rows in, or is undefined when a write bypassed the
+     * broker's write handle and left the set incomplete. An undefined set means "assume everything
+     * changed": a consumer applying a delta must fall back to a full rebuild rather than trust it.
+     */
+    tables: ReadonlySet<string> | undefined;
+};
+/**
+ * Observes that one broker mutation committed without participating in its transaction.
+ *
+ * A transaction that changed no rows never reaches a listener, so an idle sweep costs its observers
+ * nothing.
+ */
+export type BrokerCommitListener = (commit: BrokerCommit) => void;
+/** Options for {@link Broker.resumeSession}. */
+export type ResumeSessionRequest = {
+    /** Last broker session issued to this gateway launch. */
+    sessionId: string;
+    /** Generation proof; required on every path, whether renewing or rotating. */
+    fencingToken?: string | undefined;
+    /** Broker generation the caller last saw, when available. */
+    epoch?: string | undefined;
+};
+/** Durable single-writer SQLite broker for Pager. */
+export declare class Broker {
+    #private;
+    /**
+     * Opens a durable broker database with the supplied timing and routing policies.
+     * @param path - SQLite database location, or memory sentinel, for durable state.
+     * @param options - Clock, workspace-branch lookup, and diagnostics sink are required; see {@link BrokerOptions} for its optional fields.
+     */
+    constructor(path: string, options: BrokerOptions);
+    /** Close the broker database connection. */
+    close(): void;
+    /**
+     * Report the durability settings of the connection that owns broker writes.
+     *
+     * `synchronous` and `busy_timeout` are connection-local, so a second connection opened elsewhere
+     * cannot attest to them and must ask the running service instead.
+     * @returns - Journal mode, synchronous level, busy timeout, and foreign-key enforcement.
+     */
+    durability(): DatabaseDurability;
+    /**
+     * Report broker generation and durability without projecting any traffic.
+     *
+     * Liveness callers poll this on a deadline, so it must not depend on how much history the
+     * database holds.
+     * @param generatedAt - Observation time to stamp, defaulting to now.
+     * @returns - Epoch, observation time, and live durability settings.
+     */
+    snapshotHealth(generatedAt?: number): SnapshotHealth;
+    /**
+     * Return the current singleton epoch for local service ownership.
+     * @returns - Opaque generation identifier owned by this broker process.
+     */
+    epoch(): string;
+    /**
+     * Observe successful broker commits after their SQLite transaction is durable.
+     * @param listener - Isolated observer that cannot change the committed caller outcome.
+     * @returns A callback that removes this observer.
+     */
+    subscribeCommits(listener: BrokerCommitListener): () => void;
+    /**
+     * Register a concrete agent under one workspace-unique session name.
+     * @param args - Caller-supplied identity, topology, and implementation values.
+     * @returns - Stable agent identity registered in the requested team.
+     */
+    registerAgent(args: {
+        teamId: string;
+        agentId?: AgentId;
+        parentId?: AgentId | null;
+        sessionName?: string;
+        ephemeral?: boolean;
+        workspacePath: string;
+        implementation?: AgentImplementation | null;
+    }): AgentId;
+    /**
+     * Register or rejoin an implementation identity without a prior launch reservation.
+     *
+     * A `sessionKey` makes the identity resumable: the same harness conversation returning after a
+     * restart resolves to the identity it already owns, keeping its alias, inbox, and traffic, whatever
+     * the caller passes as `sessionName`. Without one, rejoining still falls back to matching the alias.
+     *
+     * A `continuesSessionKey` is the key a conversation was known by before it continued under
+     * `sessionKey`. When `sessionKey` owns no identity yet, the identity the continued key owns moves
+     * to `sessionKey`, its holder displaced, so the alias, inbox, and traffic follow the conversation.
+     * @param args - Validated workspace, implementation, optional alias, optional resumable key, and
+     * the key of the conversation that one continues, which requires the resumable key.
+     * @returns - Stable agent identity, its current alias, and a fresh single-use attachment reservation.
+     */
+    registerAgentWithoutReservation(args: {
+        workspacePath: string;
+        implementation: AgentImplementation;
+        sessionName?: string;
+        sessionKey?: string;
+        continuesSessionKey?: string;
+    }): {
+        agentId: AgentId;
+        reservation: string;
+        sessionName: string;
+        ephemeral: boolean;
+        resumed: boolean;
+    };
+    /**
+     * Replace an agent's routable alias and durable reconnection name.
+     * @param agentId - Authenticated identity whose name is changing.
+     * @param requestedAlias - Workspace-unique name, with an optional leading at-sign.
+     * @returns - Current identity and alias history after the replacement.
+     */
+    updateAgentAlias(agentId: AgentId, requestedAlias: string): {
+        id: AgentId;
+        alias: string;
+        previousAliases: string[];
+    };
+    /**
+     * Return the authenticated identity, current alias, and prior routable names.
+     * @param agentId - Stable identity to inspect.
+     * @returns - Identity details safe to return to the owning agent.
+     */
+    agentIdentity(agentId: AgentId): {
+        id: AgentId;
+        alias: string;
+        previousAliases: string[];
+    };
+    /**
+     * Reserve an identity and single-use attach reservation for a future process.
+     * @param args - Registration name, team, and workspace the reservation is created under.
+     * @returns - Reservation identity and one-time reservation for the future agent.
+     */
+    reserveAgent(args: {
+        teamId: string;
+        parentId: AgentId;
+        sessionName?: string;
+        workspacePath: string;
+        implementation?: AgentImplementation | null;
+    }): {
+        agentId: AgentId;
+        reservation: string;
+    };
+    /**
+     * Issue an additional single-use attach reservation for an existing broker identity.
+     * @param agentId - Registered agent the new reservation attaches.
+     * @param channel - Attachment channel the reservation may occupy; a new session evicts only its own channel.
+     * @returns - One-time reservation that can attach the registered agent.
+     */
+    reserveAttachment(agentId: AgentId, channel?: AttachmentChannel): string;
+    /**
+     * Consume a single-use reservation and bind it to an agent identity plus fenced session.
+     *
+     * A launch reserves an identity before the harness has started, so it cannot know which conversation
+     * will occupy it. Presenting `sessionKey` here closes that gap: an unclaimed key is bound to the
+     * reserved identity, and a key already held by another identity attaches to its owner instead, so
+     * relaunching a harness against an existing conversation rejoins rather than forking a duplicate.
+     *
+     * A durable session name outlives the conversation that first claimed it. When a new conversation
+     * rejoins that name, it takes the identity over: the prior session is deactivated and loses its
+     * fencing token, rather than the attach being refused and the caller left with no channel at all.
+     * @param reservationId - One-time secret used to attach a reserved agent.
+     * @param options - Optional resumable session key presented by the attaching conversation.
+     * @returns - Attached identity, which is the key's owner when adoption occurred, plus its session.
+     */
+    attach(reservationId: string, options?: {
+        sessionKey?: string;
+    }): {
+        agentId: AgentId;
+        sessionId: string;
+        fencingToken: string;
+        epoch: string;
+    };
+    /**
+     * Claim a conversation key for an already attached identity, or move to the identity that holds it.
+     *
+     * A harness whose channels are attached by the editor rather than by us cannot present its key at
+     * attach time, so it says who it is once it is connected. When the key belongs to another identity,
+     * that identity is the real one: this one is a launch artefact, and it is removed along with its
+     * connections after its outstanding reservations move across. An identity that has already sent or
+     * received a message is never removed: the call throws `conflict` and nothing is bound.
+     * @param agentId - Authenticated identity making the claim.
+     * @param sessionKey - Resumable key identifying the caller's conversation.
+     * @returns - Resolved identity, and fresh attachments for both channels when it moved.
+     */
+    adoptSessionKey(agentId: AgentId, sessionKey: string): {
+        agentId: AgentId;
+        adopted: boolean;
+        reservation?: string;
+        deliveryReservation?: string;
+    };
+    /**
+     * Renew an active attachment when its complete broker-issued identity is presented.
+     * @param sessionId - Attached session identity being renewed.
+     * @param fencingToken - Token proving ownership of the active attachment generation.
+     * @param epoch - Broker generation that issued the attachment.
+     * @returns - Agent identity whose durable attachment lease was renewed.
+     */
+    renewAttachment(sessionId: string, fencingToken: string, epoch: string): AgentId;
+    /**
+     * End every active attachment of an agent whose harness is shutting down, leaving the identity in place.
+     *
+     * The caller must have authenticated as this agent over one of those attachments. This is the graceful
+     * shutdown path for a harness whose messaging attachment is held by a client the connector cannot
+     * reach into, so an attachment the connector never opened still ends before its lease lapses.
+     * @param agentId - Identity whose harness is shutting down.
+     */
+    releaseAttachments(agentId: AgentId): void;
+    /**
+     * Persist terminal disposition and detach every active connection for an agent.
+     * @param agentId - Stable identity whose process reached terminal disposition.
+     */
+    markAgentTerminal(agentId: AgentId): void;
+    /** Enqueue terminal outcomes for parents and persist the completed disposition. */
+    reapTerminalAgents(): void;
+    /**
+     * Report how long until a sweep could next find work.
+     *
+     * A sweep scheduled from this value does nothing on an idle broker. Zero means work is already due.
+     * @returns - Delay in milliseconds, or null when nothing is pending.
+     */
+    nextSweepDelayMs(): number | null;
+    /**
+     * Resume an MCP attachment while rotating a lapsed or prior-epoch session generation.
+     * @param request - Session, fencing proof, and last-seen generation the caller resumes with.
+     * @returns - Current attachment credentials and the stable owning agent identity.
+     */
+    resumeSession({ sessionId, fencingToken, epoch }: ResumeSessionRequest): {
+        agentId: AgentId;
+        sessionId: string;
+        fencingToken: string;
+        epoch: string;
+    };
+    /**
+     * Return the configured lifetime of an authenticated MCP attachment.
+     * @returns - Milliseconds from successful authentication until renewal is required.
+     */
+    sessionLeaseTtlMs(): number;
+    /**
+     * Resolve a live session ID to an agent identity, expiring sessions on timeout or restart epoch mismatch.
+     *
+     * Resolving renews the session lease. The lease reaps sessions whose process is gone, and a caller
+     * presenting the session is evidence its process is not; an attach reservation is single-use, so a
+     * session allowed to lapse under continuous use could never be re-established.
+     * @param sessionId - Session id presented by the attached process.
+     * @param epoch - Broker generation used to fence stale sessions, when the client protocol carries one.
+     * @returns - Agent identity owned by the current fenced session.
+     */
+    resolveSession(sessionId: string, epoch?: string): AgentId;
+    /**
+     * Send a message from an agent to a concrete recipient or alias address.
+     * `from` is taken as given: the broker looks the agent up and does not authenticate the caller, so
+     * the caller must have authenticated the identity itself and never pass one read from request
+     * content. An alias resolves to a concrete recipient here, at send time, and a
+     * queued message keeps that recipient rather than following a later rebinding. Only an explicit
+     * send creates a message; assistant output is never forwarded automatically.
+     * @param args - Sender identity, address, subject, type, and body of the message to send.
+     * @returns - Durable message identity, the resolved recipient, and whether that recipient is archived.
+     */
+    send(args: {
+        from: AgentId;
+        to: string;
+        subject: string;
+        body: unknown;
+        type: string;
+        idempotencyKey?: string;
+    }): {
+        messageId: string;
+        to: AgentId;
+        recipientArchived: boolean;
+    };
+    /**
+     * Send one message from an agent to the other agents in a workspace.
+     *
+     * `from` is taken as given, as for {@link Broker.send}. The recipients are the workspace's active,
+     * unarchived agents other than the sender that are named, attached now, or still able to attach
+     * for the first time; an agent that joins later receives nothing. Each recipient gets its own
+     * message. A recipient refused by its pair rate or inbox limit is reported and the others still
+     * receive. A repeat carrying an earlier broadcast's key to the same workspace returns the message
+     * that broadcast queued for each recipient it reached, whatever has become of that recipient
+     * since, and sends to every other recipient. A key a direct send carried names a different send.
+     * @param args - Sender identity, subject, type, and body of the message, and the name of the
+     * workspace to broadcast to, the sender's own when absent.
+     * @returns - The broadcast address, the message sent to each recipient, and each recipient refused.
+     */
+    broadcast(args: {
+        from: AgentId;
+        workspace?: string;
+        subject: string;
+        body: unknown;
+        type: string;
+        idempotencyKey?: string;
+    }): BroadcastResult;
+    /**
+     * Claim queued messages for an agent atomically, returning opaque acknowledgement metadata.
+     * @param request - Agent to claim for, the claim cap, and the path making the claim.
+     * @returns - Messages claimed for the agent with fresh claim tokens.
+     */
+    fetch({ agentId, limit, claimedBy }: BrokerFetchRequest): ClaimedMessage[];
+    /**
+     * Acknowledge claims while preserving their bodies for later inspection or explicit expiry.
+     *
+     * A token identifies both its message and its claim generation, so a token superseded by a re-claim
+     * after expiry matches nothing and leaves the live claim outstanding.
+     * @param agentId - Agent acknowledging its own claimed messages.
+     * @param claimTokens - Claim tokens proving ownership of fetched messages; a token repeated in one call counts once.
+     * @returns - The tokens acknowledged and, for each token that was not, the reason.
+     */
+    ack(agentId: AgentId, claimTokens: readonly string[]): AckResult;
+    /**
+     * Return claims the broker made on a recipient's behalf whose delivery never reached the host.
+     *
+     * Waiting out the visibility window would hold a message the recipient never saw for the whole
+     * window; the transport has already said nothing arrived, so the queue gets it back now. The
+     * redelivery schedule armed when the message was queued is still in place, because a claimed
+     * message keeps its inbox's schedule, and it decides when the message is offered again.
+     * @param agentId - Recipient the claims were made for.
+     * @param claimTokens - Claim tokens the failed delivery carried.
+     * @returns - Message identities returned to the queue; a claim already acknowledged or expired is skipped.
+     */
+    releaseClaims(agentId: AgentId, claimTokens: readonly string[]): string[];
+    /**
+     * Return whether an agent has queued durable inbox messages without claiming them.
+     * @param agentId - Agent whose queue is checked.
+     * @returns - Whether the agent has at least one deliverable queued message.
+     */
+    hasQueuedMessages(agentId: AgentId): boolean;
+    /**
+     * Expire active claims back to the durable queue for redelivery.
+     *
+     * The only thing that settles a lapsed claim, and so the only thing that makes {@link snapshot}'s
+     * claim states current: a reader that never runs it sees a dead claimant's claim as `claimed`.
+     */
+    expireClaims(): void;
+    /**
+     * Advance the redelivery schedule and report the inboxes now owed another wake.
+     *
+     * Claims are expired first, so an inbox whose messages are merely in flight is distinguished from
+     * one whose recipient stopped answering: only the second spends an attempt. An inbox that has been
+     * retried past the give-up budget is dead-lettered here rather than retried again, because a
+     * sender waiting on a delivery outcome is owed a terminal state. An inbox whose stored recipient
+     * cannot be read is dead-lettered on its first due wake, claimed messages included, since none can
+     * be fetched or acknowledged.
+     * @returns - Recipients whose queued messages should be notified again, in no guaranteed order.
+     */
+    dueRedeliveryWakes(): AgentId[];
+    /**
+     * Record that a redelivery wake reached one recipient, against each message it covered.
+     *
+     * Separate from scheduling because only the caller that published the wake knows whether it was
+     * admitted: a wake the budget shed still costs an attempt, but writing it to the lifecycle would
+     * tell an operator a message was delivered again when nothing left the broker.
+     * @param agentId - Recipient the wake was published for.
+     */
+    recordRedeliveryAttempt(agentId: AgentId): void;
+    /**
+     * Mark expired unattached reservations and parent-visible dead-letter outcomes.
+     *
+     * Scoped to an agent with no active session at all: an agent already attached on one channel can
+     * hold an unconsumed reservation on another (its delivery channel, when its implementation has no
+     * host-push capability and so never attaches it) that outlives the reservation TTL forever. That
+     * reservation expiring is not the agent going unanswered — it is alive and reachable — so treating
+     * it as a never-attached identity would dead-letter its live mail out from under it.
+     */
+    reapExpiredReservations(): void;
+    /**
+     * Mark a message expired, retaining the stored body and the sender-visible status of its row.
+     * @param messageId - Message being marked expired.
+     * @param actor - Identity performing the audited action.
+     */
+    expireMessage(messageId: string, actor: "ttl" | "operator"): void;
+    /**
+     * Mark a message failed, retaining the stored body and the sender-visible status of its row.
+     * @param messageId - Message being marked failed.
+     */
+    failMessage(messageId: string): void;
+    /**
+     * Return body-free status for a sender-visible message.
+     * @param messageId - Message whose status is read.
+     * @param requester - Agent identity authorized to inspect sender-visible status.
+     * @returns - Sender-visible delivery status without retained message content.
+     */
+    status(messageId: string, requester?: AgentId): {
+        messageId: string;
+        state: MessageState;
+        to: AgentId;
+    };
+    /**
+     * Return the broker's observable operational events.
+     * @returns - Copy of accumulated operational events, safe for caller inspection.
+     */
+    operationalEvents(): BrokerOperationalEvent[];
+    /**
+     * Append an operational event recording the outcome of a delivery notification attempt.
+     * @param messageId - Message the notification outcome is recorded against.
+     * @param outcome - Observed notification result recorded for diagnostics.
+     */
+    recordNotification(messageId: string, outcome: NotificationOutcome): void;
+    /**
+     * Reads a message's retained body, available until the settled-message prune deletes its row.
+     * @param messageId - Message whose retained body is read.
+     * @returns - Retained body content and its stored representation metadata.
+     */
+    readMessageBody(messageId: string): {
+        messageId: string;
+        body: unknown;
+        rawCopy: string;
+        sizeBytes: number;
+        contentType: string;
+    };
+    /**
+     * Read bounded durable traffic without claiming, acknowledging, or changing retained bodies.
+     * @returns Traffic source rows in their single broker-owned durable order.
+     */
+    operatorTrafficRecords(): BrokerTrafficReadResult;
+    /**
+     * Return a prior operator command acceptance for idempotent request handling.
+     * @param commandId - Opaque command correlation supplied by the operator boundary.
+     * @returns Stored acceptance, or null when this command has not been accepted.
+     */
+    operatorCommand(commandId: string): BrokerOperatorCommandRecord | null;
+    /**
+     * Persist ping request acceptance and its audit before the scheduler publishes a wake.
+     * @param commandId - Opaque idempotency correlation for the operator request.
+     * @param targetAgentId - Active broker agent requested by the operator.
+     * @param controlId - Opaque correlation carried by the body-free wake.
+     * @returns Newly persisted command acceptance.
+     */
+    acceptOperatorPing(commandId: string, targetAgentId: AgentId, controlId: string): BrokerOperatorCommandAcceptance;
+    /**
+     * Atomically expire one retained message and persist command acceptance for idempotent retry.
+     * @param commandId - Opaque idempotency correlation for the operator request.
+     * @param messageId - Accepted message whose retained body stays readable until the settled-message prune.
+     * @returns Newly persisted command acceptance.
+     */
+    acceptOperatorExpiry(commandId: string, messageId: string): BrokerOperatorCommandAcceptance;
+    /**
+     * Accept one operator archive request, putting the agent away without disturbing its mail.
+     *
+     * The same lifecycle holds for every identity, ephemeral or named: active, archived, then reaped.
+     * Until the reaper takes it, once `archivedRetentionMs` has passed since this acceptance, the
+     * identity keeps its name, its conversation key, its inbox and its addressability, so the ordinary
+     * reconnection path is what brings it back and everything queued for it, before or since, is
+     * waiting when it does. Attaching un-archives it and stops the clock. Archiving an identity that is
+     * already archived keeps the first `archived_at`, so a repeat request never extends the window.
+     * @param commandId - Correlates retries of the same operator request.
+     * @param agentId - Agent the operator asked to archive.
+     * @returns - Durable acceptance, reporting whether this call created it.
+     */
+    acceptOperatorArchive(commandId: string, agentId: AgentId): BrokerOperatorCommandAcceptance;
+    /**
+     * Returns the broker snapshot, optionally scoped to one workspace.
+     *
+     * A read: it writes nothing and publishes no commit. Claim states are as current as the last
+     * {@link expireClaims}.
+     * @param workspaceId - Workspace whose agents, and the messages they sent or received, the
+     * snapshot is scoped to; every workspace when absent.
+     * @returns - Broker snapshot, optionally scoped to the requested workspace.
+     */
+    snapshot(workspaceId?: string): BrokerSnapshot;
+    /**
+     * Return the agent-derived state an operator projection reads, without any delivery.
+     * @returns - The snapshot's workspace, agent, and connection sections; deliveries and diagnostics are omitted.
+     */
+    operatorAgentSource(): Pick<BrokerSnapshot, "workspaces" | "agents" | "connections">;
+    /**
+     * Return the concrete team for a registered agent.
+     * @param agentId - Registered agent whose team is looked up.
+     * @returns - Team identity that owns the registered agent.
+     */
+    teamForAgent(agentId: AgentId): string;
+    /**
+     * Return the implementation identity recorded for an agent when it was registered.
+     * @param agentId - Registered agent whose implementation is looked up.
+     * @returns - Implementation recorded by the composition boundary, or null when none was supplied.
+     */
+    implementationForAgent(agentId: AgentId): AgentImplementation | null;
+    /**
+     * Return team directory entries visible to the attached agent.
+     *
+     * A reaped identity is omitted, since a send to it is refused.
+     * @param agentId - Attached agent whose team roster is listed.
+     * @returns - Registered identities and current aliases visible within the agent team.
+     */
+    listTeamMembers(agentId: AgentId): Array<{
+        id: AgentId;
+        alias: string;
+    }>;
+    /**
+     * Return every agent a sender can currently reach, with the address that reaches it from any workspace.
+     *
+     * A reaped identity is omitted, since a send to it is refused. So is a detached ephemeral identity
+     * that is not archived: it is retained only so its own conversation can resume, and offering it
+     * here invites a sender to address an inbox nothing will ever claim. An archived identity is listed
+     * because a send to it is accepted and waits.
+     * @returns - Registered identities, aliases, workspace names, and routable addresses.
+     */
+    listAgents(): Array<{
+        id: AgentId;
+        alias: string;
+        workspace: string;
+        address: string;
+    }>;
+    /**
+     * Name every registered workspace by the shortest trailing path segments unique across the broker.
+     * @returns - Addressable workspace name for each workspace identity.
+     */
+    workspaceNames(): Map<string, string>;
+}