@haywoodmarx/agent-pager 0.2.0 → 0.2.1

package/README.md

@@ -52,9 +52,9 @@ pager status
 pager <implementation-id> [--session-name <name>] -- <implementation-arguments>
 ```
 
-The bare implementation form starts or adopts the loopback service automatically. A command already running in a hosted terminal keeps the implementation in that terminal with inherited stdio. Otherwise, it prefers an available discovered terminal provider and falls back to inherited stdio; implementation exit status is propagated to the invoking shell. A session name is also the agent's routable alias and is unique within its workspace across implementations. A session's workspace is the Git repository its working directory belongs to, so the main worktree, every linked worktree, and every subdirectory of them share one; a directory outside any repository is a workspace of its own. Agents in one workspace address each other by bare alias. Supplying it again rejoins that broker identity once its holder's harness has shut down gracefully and its connector has said so, its attachment heartbeat lease has lapsed, or the holder was archived; while the holder is attached, the launch exits non-zero naming the holder and the harness does not start. Omitting it creates an ephemeral identity that is reaped once its attachment heartbeat lease lapses, or, when a conversation key makes it resumable, once it has been detached for the resumable retention window, shortened to the unused window while it has never sent a message or received one addressed to it alone. An ephemeral identity that never attached is reaped once its attach reservations have lapsed. Archiving an identity from the operator TUI ends its attachments and hides it, while messages sent to it wait; attaching again un-archives it. A named identity detached for the named archive window is archived too, and comes back when its conversation attaches or its holder resumes its attachment. Otherwise an archived identity, ephemeral or named, is reaped once the archive retention window has passed since its first archive, and reaping dead-letters its unsettled mail. The first sweep after an upgrade reaps every identity already archived for longer than that window.
+The bare implementation form starts or adopts the loopback service automatically. A command already running in a hosted terminal keeps the implementation in that terminal with inherited stdio. Otherwise, it prefers an available discovered terminal provider and falls back to inherited stdio; implementation exit status is propagated to the invoking shell. A session name is also the agent's routable alias and is unique within its workspace across implementations. A session's workspace is the Git repository its working directory belongs to, so the main worktree, every linked worktree, and every subdirectory of them share one; a directory outside any repository is a workspace of its own. Agents in one workspace address each other by bare alias. Supplying it again rejoins that broker identity once its holder's harness has shut down gracefully and its connector has said so, its attachment heartbeat lease has lapsed, or the holder was archived; while the holder is attached, the launch exits non-zero naming the holder and the harness does not start. Omitting it creates an ephemeral identity that is reaped once its attachment heartbeat lease lapses, or, when a conversation key makes it resumable, once it has been detached for the resumable retention window, shortened to the unused window while it has never sent a message or received one addressed to it alone. An ephemeral identity that never attached is reaped once its attach reservations have lapsed. Archiving an identity from the operator TUI ends its attachments and hides it, while messages sent to it wait; attaching again un-archives it. Purging an identity from the operator TUI, on its own or with others in its workspace's archive section, deletes it and ends any session still attached to it; a message it exchanged with an identity that remains stays in that identity's history, and any still waiting in its inbox is dead-lettered. A named identity detached for the named archive window is archived too, and comes back when its conversation attaches or its holder resumes its attachment. Otherwise an archived identity, ephemeral or named, is reaped once the archive retention window has passed since its first archive, and reaping dead-letters its unsettled mail. The first sweep after an upgrade reaps every identity already archived for longer than that window.
 
-The authenticated `whoami` MCP tool returns the caller's identity and the address that reaches it from any workspace. [`src/messaging/tools.ts`](src/messaging/tools.ts) describes what each tool returns. `update_agent_alias` atomically replaces the current alias and durable session name; assigning one to an unnamed agent makes that identity durable. `move_to_workspace` moves an agent into another workspace, keeping its identity and inbox. Prior names and addresses remain reserved. Sending to one is rejected with `recipient_alias_changed` and the current address rather than silently redirecting the message. An alias another agent holds is taken over only with `force`, which hands that agent's identity to the caller, tells its session and ends it, so that session's next call runs as a fresh unnamed agent.
+The authenticated `whoami` MCP tool returns the caller's identity and the address that reaches it from any workspace. [`src/messaging/tools.ts`](src/messaging/tools.ts) describes what each tool returns. `update_agent_alias` atomically replaces the current alias and durable session name; assigning one to an unnamed agent makes that identity durable. `move_to_workspace` moves an agent into another workspace, keeping its identity and inbox. Prior names and addresses remain reserved until the identity is purged. Sending to one is rejected with `recipient_alias_changed` and the current address rather than silently redirecting the message. An alias another agent holds is taken over only with `force`, which hands that agent's identity to the caller, tells its session and ends it, so that session's next call runs as a fresh unnamed agent.
 
 The package also exposes its Pi integration as a Pi package. `pi install npm:@haywoodmarx/agent-pager` enables directly started Pi sessions to discover or start the broker and register themselves; `pager pi -- <pi-arguments>` loads the same extension explicitly for a wrapper-managed session.
 

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

@@ -616,7 +616,8 @@ export declare class Broker {
     operationalEvents(): BrokerOperationalEvent[];
     /**
      * Append an operational event recording the outcome of a delivery notification attempt.
-     * @param messageId - Message the notification outcome is recorded against.
+     * @param messageId - Message the notification outcome is recorded against; an outcome for a
+     * message deleted while its notification was in flight is dropped.
      * @param outcome - Observed notification result recorded for diagnostics.
      */
     recordNotification(messageId: string, outcome: NotificationOutcome): void;
@@ -672,6 +673,25 @@ export declare class Broker {
      * @returns - Durable acceptance, reporting whether this call created it.
      */
     acceptOperatorArchive(commandId: string, agentId: AgentId): BrokerOperatorCommandAcceptance;
+    /**
+     * Accept one operator purge request, deleting the named identities and their records.
+     *
+     * A message is deleted with its events and claims only when neither end is an identity that
+     * outlives the purge. A message exchanged with one that does stays in that identity's history,
+     * naming the purged end by its raw id, and is dead-lettered if it was still waiting in a purged
+     * inbox. Operator command records keep the ids they targeted, so a retried command is still
+     * answered from its record, and the identity's sessions are kept ended, so a process still
+     * attached to it is told it was ended. Claims a purged identity made on a kept message stay as
+     * that message's delivery attempts, and operator stream events already published about the
+     * identity stay in the replay journal until it trims them. Every other row naming a purged identity
+     * is deleted.
+     * Workspace rows are kept even when no identity remains in them, because previous addresses
+     * into a workspace and the short names of other workspaces are resolved from them.
+     * @param commandId - Correlates retries of the same operator request.
+     * @param agentIds - Distinct agents the operator asked to purge, in any lifecycle state.
+     * @returns - Durable acceptance, reporting whether this call created it.
+     */
+    acceptOperatorPurge(commandId: string, agentIds: readonly AgentId[]): BrokerOperatorCommandAcceptance;
     /**
      * Returns the broker snapshot, optionally scoped to one workspace.
      *

package/dist/src/broker/broker.js

@@ -6,7 +6,7 @@ import { PAGER_DEFAULTS } from "../configuration-defaults.js";
 import { publicEpoch } from "./snapshot.js";
 import { formatAgentAddress, normalizeAlias, parseAgentAddress, parseWorkspaceName, uniquePathNames, validateRegistrationSessionName, workspaceIdentity, workspaceTeamId, } from "./address.js";
 import { ATTACHMENT_CHANNELS, BrokerSchema, MESSAGE_STATES, } from "./schema.js";
-import { assertDurableOperatorId, readStoredAgentId, readStoredEnum, BrokerOperatorProjection, } from "./operator-projection.js";
+import { assertDurableOperatorId, encodePurgeTargets, samePurgeTargets, readStoredAgentId, readStoredEnum, BrokerOperatorProjection, } from "./operator-projection.js";
 const notificationDisplay = {
     delivered: { text: "notify delivered", tone: "ok" },
     shed: { text: "notify shed — budget exceeded", tone: "warn" },
@@ -842,15 +842,20 @@ export class Broker {
             const settled = this.#db
                 .prepare("select id from messages where state in ('acknowledged', 'expired', 'dead_lettered', 'failed') and created_at <= ?")
                 .all(cutoff);
-            for (const row of settled) {
-                const messageId = String(row.id);
-                this.#write("delete from message_events where message_id = ?", messageId);
-                this.#write("delete from claims where message_id = ?", messageId);
-                this.#write("delete from idempotency where message_id = ?", messageId);
-                this.#write("delete from messages where id = ?", messageId);
-            }
+            for (const row of settled)
+                this.#deleteMessage(String(row.id));
         });
     }
+    /**
+     * Delete one message and every row that belongs to it.
+     * @param messageId - Message whose events, claims and idempotency keys go with it.
+     */
+    #deleteMessage(messageId) {
+        this.#write("delete from message_events where message_id = ?", messageId);
+        this.#write("delete from claims where message_id = ?", messageId);
+        this.#write("delete from idempotency where message_id = ?", messageId);
+        this.#write("delete from messages where id = ?", messageId);
+    }
     /**
      * 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.
@@ -941,8 +946,8 @@ export class Broker {
      * Name why a known session no longer resolves.
      * @param row - The session row the caller presented, inactive or past its lease.
      * @returns - `ended` when the newest generation of the row's rotation lineage was deactivated by an
-     * operator archive or by a newer attachment of the same identity and channel, otherwise `expired`,
-     * which includes a lineage whose end cause is a claim of its identity.
+     * operator archive or purge or by a newer attachment of the same identity and channel, otherwise
+     * `expired`, which includes a lineage whose end cause is a claim of its identity.
      */
     #sessionEndedError(row) {
         const newest = this.#newestGeneration(row);
@@ -950,6 +955,8 @@ export class Broker {
             return new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
         if (newest.end_cause === "claimed")
             return new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+        if (newest.end_cause === "purged")
+            return new ProtocolError("ended", "MCP session ended because an operator purged this agent");
         const archived = this.#db.prepare("select archived_at from agents where id = ?").get(String(newest.agent_id));
         if (typeof archived?.archived_at === "number")
             return new ProtocolError("ended", "MCP session ended because an operator archived this agent");
@@ -1533,12 +1540,15 @@ export class Broker {
     }
     /**
      * Append an operational event recording the outcome of a delivery notification attempt.
-     * @param messageId - Message the notification outcome is recorded against.
+     * @param messageId - Message the notification outcome is recorded against; an outcome for a
+     * message deleted while its notification was in flight is dropped.
      * @param outcome - Observed notification result recorded for diagnostics.
      */
     recordNotification(messageId, outcome) {
         const display = notificationDisplay[outcome];
         this.#transaction(() => {
+            if (this.#db.prepare("select 1 as present from messages where id = ?").get(messageId) === undefined)
+                return;
             this.#appendEvent(messageId, "notify", `notify_${outcome}`, display.text, display.tone);
         });
     }
@@ -1660,6 +1670,86 @@ export class Broker {
         });
         return acceptance;
     }
+    /**
+     * Accept one operator purge request, deleting the named identities and their records.
+     *
+     * A message is deleted with its events and claims only when neither end is an identity that
+     * outlives the purge. A message exchanged with one that does stays in that identity's history,
+     * naming the purged end by its raw id, and is dead-lettered if it was still waiting in a purged
+     * inbox. Operator command records keep the ids they targeted, so a retried command is still
+     * answered from its record, and the identity's sessions are kept ended, so a process still
+     * attached to it is told it was ended. Claims a purged identity made on a kept message stay as
+     * that message's delivery attempts, and operator stream events already published about the
+     * identity stay in the replay journal until it trims them. Every other row naming a purged identity
+     * is deleted.
+     * Workspace rows are kept even when no identity remains in them, because previous addresses
+     * into a workspace and the short names of other workspaces are resolved from them.
+     * @param commandId - Correlates retries of the same operator request.
+     * @param agentIds - Distinct agents the operator asked to purge, in any lifecycle state.
+     * @returns - Durable acceptance, reporting whether this call created it.
+     */
+    acceptOperatorPurge(commandId, agentIds) {
+        assertDurableOperatorId(commandId, "command");
+        const targetId = encodePurgeTargets(agentIds);
+        return this.#transaction(() => {
+            const prior = this.operatorCommand(commandId);
+            if (prior) {
+                if (prior.type !== "purge_agents" || !samePurgeTargets(prior.targetIds, agentIds)) {
+                    throw new ProtocolError("conflict", "Operator command already exists");
+                }
+                return { status: "existing", record: prior };
+            }
+            const targets = new Set(agentIds);
+            if (agentIds.length === 0 || targets.size !== agentIds.length)
+                throw new ProtocolError("validation_failed", "Purge targets must be distinct and non-empty");
+            const present = this.#db.prepare("select 1 as present from agents where id = ?");
+            for (const agentId of targets) {
+                if (present.get(agentId) === undefined)
+                    throw new ProtocolError("validation_failed", "Unknown agent");
+            }
+            const survivors = new Map();
+            const outlives = (agentId) => {
+                if (typeof agentId !== "string" || targets.has(agentId))
+                    return false;
+                let known = survivors.get(agentId);
+                if (known === undefined) {
+                    known = present.get(agentId) !== undefined;
+                    survivors.set(agentId, known);
+                }
+                return known;
+            };
+            const involving = this.#db.prepare("select id, sender_id, recipient_id, state from messages where sender_id = ? or recipient_id = ? order by sequence");
+            for (const agentId of targets) {
+                const waiting = [];
+                for (const row of involving.all(agentId, agentId)) {
+                    if (!outlives(row.sender_id) && !outlives(row.recipient_id))
+                        this.#deleteMessage(String(row.id));
+                    else if (row.recipient_id === agentId && (row.state === "queued" || row.state === "claimed"))
+                        waiting.push(row);
+                }
+                this.#deadLetter(waiting, "dead-lettered — recipient was purged");
+            }
+            for (const agentId of targets) {
+                this.#write("delete from idempotency where agent_id = ? or recipient_id = ?", agentId, agentId);
+                this.#write("delete from alias_history where agent_id = ?", agentId);
+                // Kept, ended, so a process still attached is told it was ended rather than that its session
+                // lapsed, which a connector answers by registering again under the same alias. A session a
+                // claim already ended keeps that cause, which tells its process to register again.
+                this.#write("update sessions set active = 0, end_cause = coalesce(end_cause, 'purged') where agent_id = ?", agentId);
+                this.#write("delete from reservations where agent_id = ?", agentId);
+                this.#write("delete from wakes where agent_id = ?", agentId);
+                this.#write("delete from operator_ping_audits where target_agent_id = ?", agentId);
+                this.#write("update agents set parent_id = null where parent_id = ?", agentId);
+                this.#write("delete from agents where id = ?", agentId);
+            }
+            const acceptedAt = this.#now();
+            this.#write("insert into operator_commands(command_id, type, target_id, accepted_at, control_id) values (?, 'purge_agents', ?, ?, null)", commandId, targetId, acceptedAt);
+            return {
+                status: "created",
+                record: { type: "purge_agents", commandId, targetIds: [...agentIds], acceptedAt },
+            };
+        });
+    }
     /**
      * Returns the broker snapshot, optionally scoped to one workspace.
      *

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

@@ -187,6 +187,15 @@ export type BrokerOperatorCommandRecord = {
     targetId: string;
     /** Records broker acceptance time. */
     acceptedAt: number;
+} | {
+    /** Identifies an agent-purge request. */
+    type: "purge_agents";
+    /** Correlates retries of the same request. */
+    commandId: string;
+    /** Identifies the purged agents, in the order the request named them. */
+    targetIds: readonly AgentId[];
+    /** Records broker acceptance time. */
+    acceptedAt: number;
 };
 /** Distinguishes a newly committed command from an exact durable retry. */
 export type BrokerOperatorCommandAcceptance = {
@@ -219,6 +228,19 @@ export declare function readStoredAgentId(value: unknown, column: string): Agent
  * @returns - The value, narrowed to a validated durable identity string.
  */
 export declare function assertDurableOperatorId(value: unknown, label: string): string;
+/**
+ * Encode the agents one purge names into the single `operator_commands.target_id` column.
+ * @param agentIds - Purged agents, in the order the request named them.
+ * @returns - Stored text that `decodePurgeTargets` reads back to the same list.
+ */
+export declare function encodePurgeTargets(agentIds: readonly AgentId[]): string;
+/**
+ * Report whether two purges name the same agents in the same order, as a retry of one must.
+ * @param left - Targets in the order one request listed them; order is significant.
+ * @param right - Targets in the order the other request listed them.
+ * @returns - Whether a command id recorded for one purge answers the other.
+ */
+export declare function samePurgeTargets(left: readonly AgentId[], right: readonly AgentId[]): boolean;
 /**
  * Reads durable operator-facing state over a broker connection: traffic records, command
  * idempotency, and snapshot projections. Holds the in-memory operational event log, which only this

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

@@ -190,6 +190,38 @@ function assertDurableAgentId(value) {
     if (!isAgentId(value))
         throw new ProtocolError("validation_failed", "Operator command target is corrupt");
 }
+/**
+ * Encode the agents one purge names into the single `operator_commands.target_id` column.
+ * @param agentIds - Purged agents, in the order the request named them.
+ * @returns - Stored text that `decodePurgeTargets` reads back to the same list.
+ */
+export function encodePurgeTargets(agentIds) {
+    return JSON.stringify(agentIds);
+}
+/**
+ * Report whether two purges name the same agents in the same order, as a retry of one must.
+ * @param left - Targets in the order one request listed them; order is significant.
+ * @param right - Targets in the order the other request listed them.
+ * @returns - Whether a command id recorded for one purge answers the other.
+ */
+export function samePurgeTargets(left, right) {
+    return left.length === right.length && left.every((agentId, index) => agentId === right[index]);
+}
+function decodePurgeTargets(value) {
+    let decoded;
+    try {
+        decoded = typeof value === "string" ? JSON.parse(value) : null;
+    }
+    catch {
+        decoded = null;
+    }
+    if (!Array.isArray(decoded) || decoded.length === 0)
+        throw new ProtocolError("validation_failed", "Operator command target is corrupt");
+    return decoded.map((entry) => {
+        assertDurableAgentId(entry);
+        return entry;
+    });
+}
 /**
  * Reads durable operator-facing state over a broker connection: traffic records, command
  * idempotency, and snapshot projections. Holds the in-memory operational event log, which only this
@@ -393,6 +425,14 @@ export class BrokerOperatorProjection {
             assertDurableAgentId(row.target_id);
             return { type: "archive_agent", commandId: String(row.command_id), targetId: row.target_id, acceptedAt };
         }
+        if (row.type === "purge_agents") {
+            return {
+                type: "purge_agents",
+                commandId: String(row.command_id),
+                targetIds: decodePurgeTargets(row.target_id),
+                acceptedAt,
+            };
+        }
         if (row.type !== "expire_message") {
             throw new ProtocolError("validation_failed", "Operator command is corrupt");
         }

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

@@ -4,7 +4,7 @@
  * Declared here rather than beside the schema it names, because the service lock compares it and is
  * loaded by adapters running inside hosts that have no `bun:sqlite`.
  */
-export declare const SCHEMA_MARKER = "agent-session-key+message-event-index+queryable-timestamps+no-body-absence-reason+message-type+session-resume-lineage+session-supersession-timestamp+message-type-required+single-delivery-state-home+checked-stored-columns+unorderable-position-index+orderable-position-predicate+no-occupancy-contract+single-session-encoding+no-reservation-bindings+reservation-id-column+repository-workspace+session-end-cause";
+export declare const SCHEMA_MARKER = "agent-session-key+message-event-index+queryable-timestamps+no-body-absence-reason+message-type+session-resume-lineage+session-supersession-timestamp+message-type-required+single-delivery-state-home+checked-stored-columns+unorderable-position-index+orderable-position-predicate+no-occupancy-contract+single-session-encoding+no-reservation-bindings+reservation-id-column+repository-workspace+session-end-cause+operator-purge";
 /**
  * Identifies the only protocol version accepted by this process.
  *

package/dist/src/broker/protocol.js

@@ -5,7 +5,7 @@ import { randomBytes, randomUUID } from "node:crypto";
  * Declared here rather than beside the schema it names, because the service lock compares it and is
  * loaded by adapters running inside hosts that have no `bun:sqlite`.
  */
-export const SCHEMA_MARKER = "agent-session-key+message-event-index+queryable-timestamps+no-body-absence-reason+message-type+session-resume-lineage+session-supersession-timestamp+message-type-required+single-delivery-state-home+checked-stored-columns+unorderable-position-index+orderable-position-predicate+no-occupancy-contract+single-session-encoding+no-reservation-bindings+reservation-id-column+repository-workspace+session-end-cause";
+export const SCHEMA_MARKER = "agent-session-key+message-event-index+queryable-timestamps+no-body-absence-reason+message-type+session-resume-lineage+session-supersession-timestamp+message-type-required+single-delivery-state-home+checked-stored-columns+unorderable-position-index+orderable-position-predicate+no-occupancy-contract+single-session-encoding+no-reservation-bindings+reservation-id-column+repository-workspace+session-end-cause+operator-purge";
 /**
  * Identifies the only protocol version accepted by this process.
  *

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

@@ -35,9 +35,9 @@ export declare const MESSAGE_STATES: readonly MessageState[];
 /** Names one lifecycle state of an agent; `AGENT_STATES` lists them. */
 export type AgentLifecycleState = "active" | "terminal" | "reaped";
 /** Names why a session was ended on purpose rather than lapsing; `SESSION_END_CAUSES` lists them. */
-export type SessionEndCause = "claimed";
+export type SessionEndCause = "claimed" | "purged";
 /** Every cause `sessions.end_cause` may hold. */
-export declare const SESSION_END_CAUSES: readonly "claimed"[];
+export declare const SESSION_END_CAUSES: readonly SessionEndCause[];
 /** Every lifecycle state `agents.state` may hold. */
 export declare const AGENT_STATES: readonly AgentLifecycleState[];
 /** Every channel a reservation or session may occupy. */

package/dist/src/broker/schema.js

@@ -74,7 +74,7 @@ export const MESSAGE_STATES = vocabulary({
     failed: true,
 });
 /** Every cause `sessions.end_cause` may hold. */
-export const SESSION_END_CAUSES = vocabulary({ claimed: true });
+export const SESSION_END_CAUSES = vocabulary({ claimed: true, purged: true });
 /** Every lifecycle state `agents.state` may hold. */
 export const AGENT_STATES = vocabulary({
     active: true,
@@ -304,7 +304,7 @@ export class BrokerSchema {
             [
                 "operator_commands",
                 commandSql,
-                "typein('ping_agent','expire_message','archive_agent')",
+                "typein('ping_agent','expire_message','archive_agent','purge_agents')",
                 "does not constrain its command types",
             ],
             [
@@ -411,20 +411,29 @@ export class BrokerSchema {
       create table if not exists agents(id text primary key, team_id text not null, workspace_id text not null, working_directory text not null, branch text, parent_id text, state text not null ${vocabularyClause("state", AGENT_STATES)}, created_at integer not null, implementation_id text, implementation_version text, registration_name text, registration_ephemeral integer not null default 0, session_key text, archived_at integer, check(implementation_id is not null or implementation_version is null));
       create unique index if not exists agent_registration_name on agents(workspace_id, registration_name) where registration_name is not null and state != 'reaped';
       create unique index if not exists agent_session_key on agents(working_directory, implementation_id, session_key) where session_key is not null and state = 'active';
+      create index if not exists agent_parent on agents(parent_id) where parent_id is not null;
       create table if not exists alias_history(id integer primary key autoincrement, workspace_id text not null, alias text not null, agent_id text not null, unique(workspace_id, alias));
+      create index if not exists alias_history_agent on alias_history(agent_id);
       create table if not exists reservations(reservation_id text primary key, agent_id text not null, channel text not null ${vocabularyClause("channel", ATTACHMENT_CHANNELS)}, expires_at integer not null, consumed_at integer);
+      create index if not exists reservation_agent on reservations(agent_id);
       create table if not exists sessions(id text primary key, agent_id text not null, channel text not null ${vocabularyClause("channel", ATTACHMENT_CHANNELS)}, fencing_token text not null, expires_at integer not null, active integer not null, created_at integer not null, superseded_by text, epoch text not null, superseded_at integer, end_cause text ${vocabularyClause("end_cause", SESSION_END_CAUSES)});
+      create index if not exists session_agent on sessions(agent_id);
       create table if not exists traffic_positions(id integer primary key autoincrement);
       create table if not exists messages(id text primary key, team_id text not null, workspace_id text not null, sender_id text not null, recipient_id text not null, addressed_to text not null, address_outcome text not null, subject text not null, type text not null, body text, body_size integer, content_type text, state text not null ${vocabularyClause("state", MESSAGE_STATES)}, created_at integer not null, sequence integer not null, claim_token text, claim_expires_at integer);
       create unique index if not exists message_traffic_position on messages(sequence);
+      create index if not exists message_sender on messages(sender_id);
+      create index if not exists message_recipient on messages(recipient_id);
       create table if not exists message_events(id integer primary key autoincrement, message_id text not null, at integer not null, source text not null ${vocabularyClause("source", MESSAGE_EVENT_SOURCES)}, type text not null, text text not null, tone text not null ${vocabularyClause("tone", MESSAGE_EVENT_TONES)});
       create index if not exists message_events_message on message_events(message_id, id);
       create table if not exists claims(message_id text not null, token text not null, agent_id text not null, expires_at integer not null, created_at integer not null, primary key(message_id, token));
       create unique index if not exists claim_token on claims(token);
       create table if not exists wakes(agent_id text primary key, attempts integer not null, next_wake_at integer not null);
       create table if not exists idempotency(agent_id text not null, recipient_id text not null, key text not null, message_id text not null, created_at integer not null, primary key(agent_id, recipient_id, key));
-      create table if not exists operator_commands(command_id text primary key, type text not null check(type in ('ping_agent','expire_message','archive_agent')), target_id text not null, accepted_at integer not null, control_id text unique, check((type = 'ping_agent' and control_id is not null) or (type != 'ping_agent' and control_id is null)));
+      create index if not exists idempotency_recipient on idempotency(recipient_id);
+      create index if not exists idempotency_message on idempotency(message_id);
+      create table if not exists operator_commands(command_id text primary key, type text not null check(type in ('ping_agent','expire_message','archive_agent','purge_agents')), target_id text not null, accepted_at integer not null, control_id text unique, check((type = 'ping_agent' and control_id is not null) or (type != 'ping_agent' and control_id is null)));
       create table if not exists operator_ping_audits(audit_id text primary key, command_id text not null unique references operator_commands(command_id), control_id text not null unique, target_agent_id text not null, actor text not null check(actor = 'operator'), accepted_at integer not null, traffic_position integer not null unique);
+      create index if not exists operator_ping_audit_target on operator_ping_audits(target_agent_id);
       create table if not exists operator_stream_state(singleton integer primary key check(singleton = 1), epoch text not null, sequence integer not null check(sequence >= 0));
       create table if not exists operator_stream_events(epoch text not null, sequence integer not null check(sequence > 0), payload text not null, unique(epoch, sequence));
     `);

package/dist/src/index.d.ts

@@ -22,6 +22,6 @@ export { PushDeliveryService, type DeliveryAddressRegistration, type PushDeliver
 export { MCP_TOOLS, type McpToolDefinition } from "./messaging/tools.js";
 export { PAGER_WAKE_TYPE, wakeLine, wakeMetadata } from "./messaging/wake.js";
 export { classifyOperatorEvent, validateOperatorAgent, validateOperatorCommand, validateOperatorCommandResult, validateOperatorCommandResultForCommand, validateOperatorControlId, validateOperatorCursor, validateOperatorDiagnostic, validateOperatorEventEnvelope, validateOperatorMessageBody, validateOperatorRepository, validateOperatorSnapshot, validateOperatorSnapshotByteLength, validateOperatorTraffic, validateOperatorTransportRequest, OperatorValidationError, OPERATOR_ARRAY_LENGTH_LIMIT, } from "./operator/validation.js";
-export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, type OperatorAcceptedDelivery, type OperatorAdapterState, type OperatorAgent, type OperatorCommand, type OperatorCommandEnvelope, type OperatorCommandEnvelopeFor, type OperatorCommandResult, type OperatorCorrelatedCommandResult, type OperatorCursor, type OperatorCursorResult, type OperatorDeliveryLifecycleEntry, type OperatorDiagnostic, type OperatorDiagnosticSeverity, type OperatorEventEnvelope, type OperatorImplementation, type OperatorImplementationVersion, type OperatorJsonObject, type OperatorJsonValue, type OperatorMessageBody, type OperatorPingAudit, type OperatorRejectionReason, type OperatorRepository, type OperatorResyncReason, type OperatorSnapshot, type OperatorStateEvent, type OperatorTraffic, type OperatorTransportFrame, type OperatorTransportRequest, type OperatorWorktree, } from "./operator/protocol.js";
+export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_PURGE_TARGET_LIMIT, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES, type OperatorAcceptedDelivery, type OperatorAdapterState, type OperatorAgent, type OperatorCommand, type OperatorCommandEnvelope, type OperatorCommandEnvelopeFor, type OperatorCommandResult, type OperatorCorrelatedCommandResult, type OperatorCursor, type OperatorCursorResult, type OperatorDeliveryLifecycleEntry, type OperatorDiagnostic, type OperatorDiagnosticSeverity, type OperatorEventEnvelope, type OperatorImplementation, type OperatorImplementationVersion, type OperatorJsonObject, type OperatorJsonValue, type OperatorMessageBody, type OperatorPingAudit, type OperatorRejectionReason, type OperatorRepository, type OperatorResyncReason, type OperatorSnapshot, type OperatorStateEvent, type OperatorTraffic, type OperatorTransportFrame, type OperatorTransportRequest, type OperatorWorktree, } from "./operator/protocol.js";
 export { PAGER_VERSION } from "./version.js";
 export { shellQuote } from "./shared/shell.js";

package/dist/src/index.js

@@ -21,6 +21,6 @@ export { PushDeliveryService, } from "./messaging/push-delivery.js";
 export { MCP_TOOLS } from "./messaging/tools.js";
 export { PAGER_WAKE_TYPE, wakeLine, wakeMetadata } from "./messaging/wake.js";
 export { classifyOperatorEvent, validateOperatorAgent, validateOperatorCommand, validateOperatorCommandResult, validateOperatorCommandResultForCommand, validateOperatorControlId, validateOperatorCursor, validateOperatorDiagnostic, validateOperatorEventEnvelope, validateOperatorMessageBody, validateOperatorRepository, validateOperatorSnapshot, validateOperatorSnapshotByteLength, validateOperatorTraffic, validateOperatorTransportRequest, OperatorValidationError, OPERATOR_ARRAY_LENGTH_LIMIT, } from "./operator/validation.js";
-export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, } from "./operator/protocol.js";
+export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_PURGE_TARGET_LIMIT, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES, } from "./operator/protocol.js";
 export { PAGER_VERSION } from "./version.js";
 export { shellQuote } from "./shared/shell.js";

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

@@ -12,6 +12,8 @@ export interface OperatorCommandBrokerPort {
     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;
+    /** Delete agents and their records, and persist command acceptance, in one transaction. */
+    acceptOperatorPurge(commandId: string, targetAgentIds: readonly AgentId[]): BrokerOperatorCommandAcceptance;
 }
 /** Supplies non-reentrant notification admission around durable ping acceptance. */
 export interface OperatorPingSchedulerPort {

package/dist/src/operator/commands.js

@@ -1,3 +1,4 @@
+import { samePurgeTargets } from "../broker/operator-projection.js";
 import { ProtocolError } from "../broker/protocol.js";
 import { OPERATOR_PROTOCOL_VERSION, } from "./protocol.js";
 import { validateOperatorCommand, validateOperatorCommandResult, validateOperatorControlId } from "./validation.js";
@@ -37,6 +38,8 @@ export class OperatorCommandService {
                 return this.#expire({ ...command, command: command.command });
             case "archive_agent":
                 return this.#archive({ ...command, command: command.command });
+            case "purge_agents":
+                return this.#purge({ ...command, command: command.command });
         }
     }
     #ping(command) {
@@ -90,31 +93,16 @@ export class OperatorCommandService {
         }
     }
     #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));
-        }
+        return agentCommandResult(command, () => this.#broker.acceptOperatorArchive(command.commandId, command.command.targetAgentId));
+    }
+    #purge(command) {
+        return agentCommandResult(command, () => this.#broker.acceptOperatorPurge(command.commandId, command.command.targetAgentIds));
     }
     #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) {
+        if (!sameTarget(command.command, prior))
             return rejected(command.commandId, "command_id_conflict");
-        }
         if (prior.type === "ping_agent")
             validateOperatorControlId(prior.controlId);
         if (prior.type === "ping_agent")
@@ -128,13 +116,61 @@ export class OperatorCommandService {
             });
         return validateOperatorCommandResult({
             protocolVersion: OPERATOR_PROTOCOL_VERSION,
-            type: prior.type === "expire_message" ? "expiry_accepted" : "archive_accepted",
+            type: ACCEPTED_RESULT_TYPES[prior.type],
             status: "accepted",
             commandId: prior.commandId,
             acceptedAt: prior.acceptedAt,
         });
     }
 }
+/** Names the result each command kind without a control correlation is accepted with. */
+const ACCEPTED_RESULT_TYPES = {
+    expire_message: "expiry_accepted",
+    archive_agent: "archive_accepted",
+    purge_agents: "purge_accepted",
+};
+/**
+ * Run one durable agent command and answer it with its acceptance or a rejection.
+ * @param command - Command being admitted, whose kind and target the broker's record must match.
+ * @param accept - Broker transaction that applies the command and records its acceptance.
+ * @returns - The acceptance, or a rejection naming why the broker refused or failed.
+ */
+function agentCommandResult(command, accept) {
+    try {
+        const { record, status } = accept();
+        assertAcceptanceStatus(status);
+        if (record.commandId !== command.commandId || !sameTarget(command.command, record)) {
+            throw new Error(`Broker returned a mismatched ${command.command.type} acceptance`);
+        }
+        return validateOperatorCommandResult({
+            protocolVersion: OPERATOR_PROTOCOL_VERSION,
+            type: ACCEPTED_RESULT_TYPES[command.command.type],
+            status: "accepted",
+            commandId: command.commandId,
+            acceptedAt: record.acceptedAt,
+        });
+    }
+    catch (error) {
+        return rejected(command.commandId, rejectionReason(error));
+    }
+}
+/**
+ * Report whether a stored acceptance answers the same request a retried command makes.
+ * @param command - Command carried by the retry.
+ * @param prior - Acceptance stored under the retry's command id.
+ * @returns - Whether both name the same command kind and the same target.
+ */
+function sameTarget(command, prior) {
+    switch (command.type) {
+        case "ping_agent":
+        case "archive_agent":
+            return prior.type === command.type && prior.targetId === command.targetAgentId;
+        case "expire_message":
+            return prior.type === command.type && prior.targetId === command.messageId;
+        case "purge_agents":
+            return prior.type === command.type && samePurgeTargets(prior.targetIds, command.targetAgentIds);
+    }
+}
 function pingAccepted(commandId, accepted) {
     if (accepted.type !== "ping_agent" || accepted.commandId !== commandId)
         throw new Error("Broker returned the wrong ping command acceptance");

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

@@ -29,6 +29,15 @@ export declare const OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES: number;
 export declare const OPERATOR_SNAPSHOT_CHUNK_BYTES: number;
 /** Bounds every newline-delimited server frame after JSON encoding. */
 export declare const OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES: number;
+/** Bounds every newline-delimited client request after JSON encoding; a longer one ends the connection. */
+export declare const OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES: number;
+/**
+ * Bounds how many agents one purge command names.
+ *
+ * A purge naming this many agents at the longest agent id still fits in one request under
+ * `OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES`.
+ */
+export declare const OPERATOR_PURGE_TARGET_LIMIT = 256;
 /** Represents JSON data that is safe to cross the operator boundary. */
 export type OperatorJsonValue = null | boolean | number | string | OperatorJsonValue[] | OperatorJsonObject;
 /** Represents an object whose values are safe to cross the operator boundary. */
@@ -310,6 +319,11 @@ export type OperatorCommand = {
     type: "archive_agent";
     /** Identifies the target using broker identity, not repository projection. */
     targetAgentId: AgentId;
+} | {
+    /** Requests that agent identities and their records be deleted in one transaction. */
+    type: "purge_agents";
+    /** Distinct broker identities to delete, at least one; a purge of any that is already gone is refused whole. */
+    targetAgentIds: readonly AgentId[];
 };
 /** Carries one versioned operator command request. */
 export type OperatorCommandEnvelope = {
@@ -367,6 +381,17 @@ export type OperatorCommandResult = {
     commandId: string;
     /** Records broker acceptance time. */
     acceptedAt: number;
+} | {
+    /** Identifies the operator wire contract. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies agent-purge command acceptance. */
+    type: "purge_accepted";
+    /** Reports that the broker accepted the command request. */
+    status: "accepted";
+    /** Correlates the result with the submitted command. */
+    commandId: string;
+    /** Records broker acceptance time. */
+    acceptedAt: number;
 } | {
     /** Identifies the operator wire contract. */
     protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
@@ -408,6 +433,13 @@ export type OperatorCorrelatedCommandResult = {
     result: Extract<OperatorCommandResult, {
         type: "archive_accepted" | "command_rejected";
     }>;
+} | {
+    /** Carries the originating purge request. */
+    command: OperatorCommandEnvelopeFor<"purge_agents">;
+    /** Carries purge acceptance or a command-agnostic rejection. */
+    result: Extract<OperatorCommandResult, {
+        type: "purge_accepted" | "command_rejected";
+    }>;
 };
 /** Classifies one event relative to a consumer cursor without conflating recovery actions. */
 export type OperatorCursorResult = {

package/dist/src/operator/protocol.js

@@ -28,6 +28,15 @@ export const OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES = 512 * 1_024 * 1_024;
 export const OPERATOR_SNAPSHOT_CHUNK_BYTES = 48 * 1_024;
 /** Bounds every newline-delimited server frame after JSON encoding. */
 export const OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES = 128 * 1_024;
+/** Bounds every newline-delimited client request after JSON encoding; a longer one ends the connection. */
+export const OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES = 64 * 1_024;
+/**
+ * Bounds how many agents one purge command names.
+ *
+ * A purge naming this many agents at the longest agent id still fits in one request under
+ * `OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES`.
+ */
+export const OPERATOR_PURGE_TARGET_LIMIT = 256;
 /**
  * Names every stable category a command rejection can carry.
  *