@haywoodmarx/agent-pager 0.1.3 → 0.2.1

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. */
@@ -143,9 +152,9 @@ export type OperatorAgent = {
      */
     archivedAt: number | null;
     /**
-     * Reports whether the recorded workspace path still resolves on the broker's machine.
+     * Reports whether the agent's recorded working directory still resolves on the broker's machine.
      *
-     * Presentation-only, like the rest of repository grouping: a removed workspace archives its
+     * Presentation-only, like the rest of repository grouping: a removed directory archives its
      * agents in the operator view without changing broker lifecycle, routing, or addressability.
      */
     workspaceAvailable: boolean;
@@ -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.
  *

package/dist/src/operator/repository-system.d.ts

@@ -5,6 +5,8 @@ export declare const REPOSITORY_GIT_OUTPUT_LIMIT = 65536;
 export type SystemRepositoryProjectionOptions = {
     /** Selects the Git executable without mutating process PATH. */
     gitExecutable?: string;
+    /** Bounds each Git command's run time in milliseconds; unbounded when omitted. */
+    gitTimeoutMs?: number;
 };
 /**
  * Compose production filesystem and Git discovery adapters.
@@ -12,3 +14,30 @@ export type SystemRepositoryProjectionOptions = {
  * @returns Dependencies whose process execution is isolated from pure projection logic.
  */
 export declare function createSystemRepositoryProjectionDependencies(options?: SystemRepositoryProjectionOptions): RepositoryProjectionDependencies;
+/** Reports how one Git command ended, separating the two answers Git gives for a path it cannot serve. */
+export type GitCommandResult = {
+    kind: "ok";
+    stdout: string;
+} | {
+    kind: "not_git";
+} | {
+    kind: "no_worktree";
+};
+/**
+ * Report the Git directory every worktree of the repository containing a directory shares.
+ * @param path - Absolute directory inside a worktree, or inside a bare repository.
+ * @param options - Executable and time bound for the Git command.
+ * @returns The repository's common Git directory, canonical and absolute, or null when the directory
+ * is not inside a Git repository.
+ * @throws {RepositoryDiscoveryError} When Git is unavailable, times out, or answers with something other than one absolute path.
+ */
+export declare function discoverRepositoryCommonDirectory(path: string, options?: SystemRepositoryProjectionOptions): string | null;
+/**
+ * Run one Git command about the repository its arguments name, with a bounded, captured output.
+ * @param executable - Git executable to spawn.
+ * @param args - Arguments, including the `-C` directory the command is about.
+ * @param timeoutMs - Milliseconds the command may run before it is treated as unavailable; unbounded when undefined.
+ * @returns The command's output, or which of Git's two refusals it answered with.
+ * @throws {RepositoryDiscoveryError} When Git cannot be run, exceeds the timeout or the output limit, or fails for any other reason.
+ */
+export declare function runGit(executable: string, args: string[], timeoutMs: number | undefined): GitCommandResult;

package/dist/src/operator/repository-system.js

@@ -11,6 +11,7 @@ export const REPOSITORY_GIT_OUTPUT_LIMIT = 65_536;
  */
 export function createSystemRepositoryProjectionDependencies(options = {}) {
     const gitExecutable = options.gitExecutable ?? "git";
+    const timeoutMs = options.gitTimeoutMs;
     return {
         fileSystem: {
             canonicalPath: (path) => realpathSync(path),
@@ -18,25 +19,52 @@ export function createSystemRepositoryProjectionDependencies(options = {}) {
         },
         git: {
             inspect: (workspacePath) => {
-                const topLevel = runGit(gitExecutable, ["-C", workspacePath, "rev-parse", "--show-toplevel"], true);
+                const topLevel = runGit(gitExecutable, ["-C", workspacePath, "rev-parse", "--show-toplevel"], timeoutMs);
                 if (topLevel.kind === "not_git")
                     return topLevel;
-                const worktreeRoot = parseSingleAbsolutePath(topLevel.stdout, "Git top-level output is invalid");
-                const topology = runGit(gitExecutable, ["-C", workspacePath, "worktree", "list", "--porcelain", "-z"], false);
-                if (topology.kind === "not_git")
+                const topology = runGit(gitExecutable, ["-C", workspacePath, "worktree", "list", "--porcelain", "-z"], timeoutMs);
+                if (topology.kind !== "ok")
                     throw new RepositoryDiscoveryError("invalid", "Git topology disappeared");
-                const repositoryRoot = parsePrimaryWorktree(topology.stdout, worktreeRoot);
+                const repositoryRoot = parsePrimaryWorktree(topology.stdout);
+                if (topLevel.kind === "no_worktree")
+                    return { kind: "git", repositoryRoot, worktreeRoot: repositoryRoot };
+                const worktreeRoot = parseSingleAbsolutePath(topLevel.stdout, "Git top-level output is invalid");
                 return { kind: "git", repositoryRoot, worktreeRoot };
             },
         },
     };
 }
-function runGit(executable, args, allowNotGit) {
+/**
+ * Report the Git directory every worktree of the repository containing a directory shares.
+ * @param path - Absolute directory inside a worktree, or inside a bare repository.
+ * @param options - Executable and time bound for the Git command.
+ * @returns The repository's common Git directory, canonical and absolute, or null when the directory
+ * is not inside a Git repository.
+ * @throws {RepositoryDiscoveryError} When Git is unavailable, times out, or answers with something other than one absolute path.
+ */
+export function discoverRepositoryCommonDirectory(path, options = {}) {
+    const answer = runGit(options.gitExecutable ?? "git", ["-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"], options.gitTimeoutMs);
+    if (answer.kind !== "ok")
+        return null;
+    return parseSingleAbsolutePath(answer.stdout, "Git common directory output is invalid");
+}
+/**
+ * Run one Git command about the repository its arguments name, with a bounded, captured output.
+ * @param executable - Git executable to spawn.
+ * @param args - Arguments, including the `-C` directory the command is about.
+ * @param timeoutMs - Milliseconds the command may run before it is treated as unavailable; unbounded when undefined.
+ * @returns The command's output, or which of Git's two refusals it answered with.
+ * @throws {RepositoryDiscoveryError} When Git cannot be run, exceeds the timeout or the output limit, or fails for any other reason.
+ */
+export function runGit(executable, args, timeoutMs) {
+    // Git redirects itself to whatever these name, which would answer for a repository other than the one asked about.
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => !["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR"].includes(name)));
     const result = spawnSync(executable, args, {
         encoding: "utf8",
-        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+        env: { ...environment, LC_ALL: "C", LANG: "C" },
         maxBuffer: REPOSITORY_GIT_OUTPUT_LIMIT,
         stdio: ["ignore", "pipe", "pipe"],
+        ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
     });
     if (result.error) {
         const code = "code" in result.error ? result.error.code : undefined;
@@ -53,8 +81,10 @@ function runGit(executable, args, allowNotGit) {
     if (result.signal !== null)
         throw new RepositoryDiscoveryError("unavailable", "Git discovery process was interrupted");
     if (result.status !== 0) {
-        if (allowNotGit && result.status === 128 && /not a git repository/u.test(stderr))
+        if (result.status === 128 && /not a git repository/u.test(stderr))
             return { kind: "not_git" };
+        if (result.status === 128 && /must be run in a work tree/u.test(stderr))
+            return { kind: "no_worktree" };
         throw new RepositoryDiscoveryError("unavailable", "Git discovery command failed");
     }
     return { kind: "ok", stdout };
@@ -66,7 +96,7 @@ function parseSingleAbsolutePath(output, message) {
     }
     return normalized;
 }
-function parsePrimaryWorktree(output, currentWorktree) {
+function parsePrimaryWorktree(output) {
     if (!output.endsWith("\0\0"))
         throw new RepositoryDiscoveryError("invalid", "Git topology output is truncated");
     const tokens = output.split("\0");
@@ -100,9 +130,6 @@ function parsePrimaryWorktree(output, currentWorktree) {
             throw new RepositoryDiscoveryError("invalid", "Only the primary Git topology record may be bare");
         }
     }
-    if (!worktrees.has(currentWorktree)) {
-        throw new RepositoryDiscoveryError("invalid", "Git topology omitted the current worktree");
-    }
     const primary = topology[0]?.path;
     if (!primary)
         throw new RepositoryDiscoveryError("invalid", "Git topology omitted its primary worktree");

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

@@ -3,7 +3,7 @@ import type { OperatorRepository, OperatorWorktree } from "./protocol.js";
 export type RepositoryGitLocation = {
     /** Supplies the root of the primary repository worktree. */
     repositoryRoot: string;
-    /** Supplies the root of the worktree containing the inspected workspace. */
+    /** Supplies the root of the worktree containing the inspected directory. */
     worktreeRoot: string;
 };
 /** Reports either confirmed Git topology or a confirmed non-Git workspace. */
@@ -16,13 +16,13 @@ export type RepositoryGitInspection = ({
 export interface RepositoryFileSystemPort {
     /**
      * Resolve aliases and symbolic links in one existing path.
-     * @param path - Absolute workspace or Git root to canonicalize.
+     * @param path - Absolute path or Git root to canonicalize.
      * @returns The canonical absolute filesystem path.
      */
     canonicalPath(path: string): string;
     /**
      * Report whether one recorded path still resolves on this machine.
-     * @param path - Absolute broker workspace path recorded when the agent registered.
+     * @param path - Absolute path recorded at registration.
      * @returns True when the path resolves through any symbolic links, false when it has been removed, is a dangling link, or is unreachable.
      */
     exists(path: string): boolean;
@@ -30,12 +30,28 @@ export interface RepositoryFileSystemPort {
 /** Discovers Git topology without granting it broker routing authority. */
 export interface RepositoryGitPort {
     /**
-     * Inspect one canonical workspace for Git repository topology.
-     * @param workspacePath - Canonical absolute workspace path.
+     * Inspect one canonical directory for Git repository topology.
+     * @param path - Canonical absolute directory to inspect.
      * @returns Confirmed Git topology or a confirmed non-Git result.
      */
-    inspect(workspacePath: string): RepositoryGitInspection;
+    inspect(path: string): RepositoryGitInspection;
 }
+/** Configures how long one Git inspection answers for its path. */
+export type RememberedInspectionOptions = {
+    /** Supplies the clock the expiry is measured against. */
+    now: () => number;
+    /** Milliseconds an inspection answers for before the path is inspected again. */
+    ttlMs: number;
+};
+/**
+ * Wrap a Git port so each path is inspected at most once per expiry window.
+ *
+ * A thrown inspection is remembered like an answered one, and rethrown for the rest of its window.
+ * @param git - Port that performs the inspection when nothing current is remembered.
+ * @param options - Clock and expiry window.
+ * @returns A port answering repeated requests for one path from the last inspection within the window.
+ */
+export declare function rememberRepositoryInspections(git: RepositoryGitPort, options: RememberedInspectionOptions): RepositoryGitPort;
 /** Supplies filesystem and Git collaborators to repository projection. */
 export type RepositoryProjectionDependencies = {
     /** Canonicalizes discovered paths. */
@@ -49,7 +65,7 @@ export type ProjectedRepositoryLocation = {
     repository: Omit<OperatorRepository, "name">;
     /** Carries worktree detail for the inspected workspace. */
     worktree: OperatorWorktree;
-    /** Reports whether the workspace path still resolves, which decides operator archive membership. */
+    /** Reports whether the inspected path still resolves, which decides operator archive membership. */
     available: boolean;
 };
 /** Reports invalid or unavailable repository projection inputs. */
@@ -66,14 +82,15 @@ export declare class RepositoryDiscoveryError extends RepositoryProjectionError
     constructor(code: "unavailable" | "invalid" | "output_limit", message: string);
 }
 /**
- * Project one broker workspace into repository grouping and worktree detail.
+ * Project one directory, a broker workspace or an agent's working directory, into repository
+ * grouping and worktree detail.
  *
- * A workspace whose path no longer resolves is projected from its recorded path alone. Neither
+ * A directory whose path no longer resolves is projected from its recorded path alone. Neither
  * canonicalization nor Git discovery can run against a removed directory, and both throw rather
  * than reporting absence, so the removal is detected before either is attempted.
- * @param workspacePath - Absolute broker workspace path to inspect.
+ * @param workspacePath - Absolute broker workspace path, or agent working directory, to inspect.
  * @param dependencies - Explicit filesystem and Git discovery collaborators.
- * @returns Presentation-only repository and worktree values, and whether the workspace still resolves.
+ * @returns Presentation-only repository and worktree values, and whether the directory still resolves.
  */
 export declare function projectRepositoryLocation(workspacePath: string, dependencies: RepositoryProjectionDependencies): ProjectedRepositoryLocation;
 export {};

package/dist/src/operator/repository.js

@@ -1,4 +1,36 @@
 import { createHash } from "node:crypto";
+/**
+ * Wrap a Git port so each path is inspected at most once per expiry window.
+ *
+ * A thrown inspection is remembered like an answered one, and rethrown for the rest of its window.
+ * @param git - Port that performs the inspection when nothing current is remembered.
+ * @param options - Clock and expiry window.
+ * @returns A port answering repeated requests for one path from the last inspection within the window.
+ */
+export function rememberRepositoryInspections(git, options) {
+    const remembered = new Map();
+    const inspectAndRemember = (path, now) => {
+        let outcome;
+        try {
+            outcome = { kind: "answered", inspection: git.inspect(path) };
+        }
+        catch (error) {
+            outcome = { kind: "threw", error };
+        }
+        remembered.set(path, { outcome, expiresAt: now + options.ttlMs });
+        return outcome;
+    };
+    return {
+        inspect: (path) => {
+            const now = options.now();
+            const current = remembered.get(path);
+            const outcome = current && current.expiresAt > now ? current.outcome : inspectAndRemember(path, now);
+            if (outcome.kind === "threw")
+                throw outcome.error;
+            return outcome.inspection;
+        },
+    };
+}
 /** Reports invalid or unavailable repository projection inputs. */
 class RepositoryProjectionError extends Error {
 }
@@ -17,14 +49,15 @@ export class RepositoryDiscoveryError extends RepositoryProjectionError {
     }
 }
 /**
- * Project one broker workspace into repository grouping and worktree detail.
+ * Project one directory, a broker workspace or an agent's working directory, into repository
+ * grouping and worktree detail.
  *
- * A workspace whose path no longer resolves is projected from its recorded path alone. Neither
+ * A directory whose path no longer resolves is projected from its recorded path alone. Neither
  * canonicalization nor Git discovery can run against a removed directory, and both throw rather
  * than reporting absence, so the removal is detected before either is attempted.
- * @param workspacePath - Absolute broker workspace path to inspect.
+ * @param workspacePath - Absolute broker workspace path, or agent working directory, to inspect.
  * @param dependencies - Explicit filesystem and Git discovery collaborators.
- * @returns Presentation-only repository and worktree values, and whether the workspace still resolves.
+ * @returns Presentation-only repository and worktree values, and whether the directory still resolves.
  */
 export function projectRepositoryLocation(workspacePath, dependencies) {
     if (!dependencies.fileSystem.exists(workspacePath)) {

package/dist/src/operator/transport.js

@@ -3,9 +3,8 @@ import { StringDecoder } from "node:string_decoder";
 import { randomBytes } from "node:crypto";
 import { LOOPBACK_HOST } from "../configuration-defaults.js";
 import { closeServer, listenServer, urlHost } from "../shared/http.js";
-import { OPERATOR_PROTOCOL_VERSION, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, } from "./protocol.js";
+import { OPERATOR_PROTOCOL_VERSION, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES, } from "./protocol.js";
 import { OperatorValidationError, validateOperatorCommandResultForCommand, validateOperatorSnapshotByteLength, validateOperatorTransportRequest, } from "./validation.js";
-const INPUT_LIMIT_BYTES = 64 * 1_024;
 const LIVE_QUEUE_LIMIT = 32;
 const DIAGNOSTIC_LIMIT = 256;
 const DEFAULT_MAX_CONNECTIONS = 64;
@@ -214,10 +213,16 @@ class OperatorConnection {
         this.#socket.destroy();
     }
     #receive(chunk) {
-        if (this.#closed)
+        // A connection that is closing reads nothing more, so input from a peer that has stopped reading
+        // cannot pile up while its last frames wait to flush.
+        if (this.#closed || this.#closeAfterFlush) {
+            this.#buffer = "";
             return;
+        }
         this.#buffer += chunk;
-        if (Buffer.byteLength(this.#buffer, "utf8") > INPUT_LIMIT_BYTES) {
+        // One read can carry several whole requests, so only the unterminated one is measured here.
+        const unterminated = this.#buffer.slice(this.#buffer.lastIndexOf("\n") + 1);
+        if (Buffer.byteLength(unterminated, "utf8") > OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES) {
             this.#malformed();
             return;
         }
@@ -227,7 +232,7 @@ class OperatorConnection {
                 return;
             const line = this.#buffer.slice(0, newline);
             this.#buffer = this.#buffer.slice(newline + 1);
-            if (!line || Buffer.byteLength(line, "utf8") > INPUT_LIMIT_BYTES) {
+            if (!line || Buffer.byteLength(line, "utf8") > OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES) {
                 this.#malformed();
                 return;
             }

package/dist/src/operator/updates.js

@@ -8,7 +8,13 @@ const UPDATE_DIAGNOSTIC_LIMIT = 64;
 /** Broker tables whose rows feed the repository and agent halves of an operator snapshot. */
 const AGENT_SOURCE_TABLES = ["agents", "sessions", "workspaces", "alias_history"];
 /** Broker tables whose rows feed the traffic half of an operator snapshot. */
-const TRAFFIC_SOURCE_TABLES = ["messages", "message_events", "claims", "traffic_positions"];
+const TRAFFIC_SOURCE_TABLES = [
+    "messages",
+    "message_events",
+    "claims",
+    "traffic_positions",
+    "operator_ping_audits",
+];
 /** Produces complete snapshots and durable strictly ordered projection changes. */
 export class OperatorUpdateService {
     #source;

package/dist/src/operator/validation.js

@@ -1,4 +1,4 @@
-import { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, } from "./protocol.js";
+import { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_PURGE_TARGET_LIMIT, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, } from "./protocol.js";
 import { BROKER_OPERATOR_TRAFFIC_LIMIT, hasControlCharacter, isAgentId, isImplementationId, isOpaqueId, lifecycleEventState, MESSAGE_BODY_LIMIT_BYTES, MESSAGE_SUBJECT_LIMIT_CHARACTERS, MESSAGE_TYPE_LIMIT_CHARACTERS, } from "../broker/protocol.js";
 import { MESSAGE_STATES } from "../broker/schema.js";
 import { exactFields as guardExactFields, readArray as guardReadArray, readOwnEnumerableEntries as guardReadOwnEnumerableEntries, readRecord as guardReadRecord, } from "../shared/guards.js";
@@ -407,6 +407,22 @@ export function validateOperatorCommandResult(value) {
                 commandId: readOpaqueId(record.commandId, "commandResult.commandId"),
                 acceptedAt: readTimestamp(record.acceptedAt, "commandResult.acceptedAt"),
             };
+        case "purge_accepted":
+            exactFields({
+                record,
+                required: ["protocolVersion", "type", "status", "commandId", "acceptedAt"],
+                optional: [],
+                path: "commandResult",
+            });
+            if (record.status !== "accepted")
+                throw new OperatorValidationError("commandResult.status", "purge result must be accepted");
+            return {
+                protocolVersion: readProtocolVersion(record.protocolVersion, "commandResult.protocolVersion"),
+                type: "purge_accepted",
+                status: "accepted",
+                commandId: readOpaqueId(record.commandId, "commandResult.commandId"),
+                acceptedAt: readTimestamp(record.acceptedAt, "commandResult.acceptedAt"),
+            };
         case "command_rejected":
             exactFields({
                 record,
@@ -452,6 +468,10 @@ export function validateOperatorCommandResultForCommand(commandValue, resultValu
             if (result.type === "archive_accepted" || result.type === "command_rejected")
                 return { command: { ...command, command: command.command }, result };
             break;
+        case "purge_agents":
+            if (result.type === "purge_accepted" || result.type === "command_rejected")
+                return { command: { ...command, command: command.command }, result };
+            break;
     }
     throw new OperatorValidationError("commandResult.type", `${resultDescriptions[result.type]} cannot answer ${commandDescriptions[command.command.type]}`);
 }
@@ -708,11 +728,13 @@ const commandDescriptions = {
     ping_agent: "a ping command",
     expire_message: "an expiry command",
     archive_agent: "an archive command",
+    purge_agents: "a purge command",
 };
 const resultDescriptions = {
     ping_accepted: "ping acceptance",
     expiry_accepted: "expiry acceptance",
     archive_accepted: "archive acceptance",
+    purge_accepted: "purge acceptance",
     command_rejected: "rejection",
 };
 function validateCommandMember(value) {
@@ -727,6 +749,9 @@ function validateCommandMember(value) {
         case "archive_agent":
             exactFields({ record, required: ["type", "targetAgentId"], optional: [], path: "commandEnvelope.command" });
             return { type: "archive_agent", targetAgentId: readAgentId(record.targetAgentId, "command.targetAgentId") };
+        case "purge_agents":
+            exactFields({ record, required: ["type", "targetAgentIds"], optional: [], path: "commandEnvelope.command" });
+            return { type: "purge_agents", targetAgentIds: readPurgeTargets(record.targetAgentIds, "command.targetAgentIds") };
         default:
             throw new OperatorValidationError("commandEnvelope.command.type", "unknown command");
     }
@@ -858,6 +883,15 @@ function readAgentId(value, path) {
         throw new OperatorValidationError(path, "invalid agent identity");
     return id;
 }
+function readPurgeTargets(value, path) {
+    const entries = readArray(value, path);
+    if (entries.length === 0 || entries.length > OPERATOR_PURGE_TARGET_LIMIT)
+        throw new OperatorValidationError(path, "must name between one and the bounded number of agents");
+    const ids = entries.map((entry, index) => readAgentId(entry, `${path}[${String(index)}]`));
+    if (new Set(ids).size !== ids.length)
+        throw new OperatorValidationError(path, "must not repeat an agent");
+    return ids;
+}
 function readOpaqueId(value, path) {
     const id = readNonemptyString(value, path);
     if (!isOpaqueId(id))

package/dist/src/shared/versions.d.ts

@@ -0,0 +1,18 @@
+/** A `major.minor.patch` version as three numbers. */
+export type NumericVersion = readonly [number, number, number];
+/**
+ * Read the `major.minor.patch` numbers of a version string.
+ * @param version - Version text, such as a runtime's reported version or a package release.
+ * @param extent - `prefix` accepts trailing text such as a prerelease or build suffix and ignores it;
+ * `exact` rejects any version carrying one.
+ * @returns - The three numbers, or undefined when the text does not start with, or is not exactly, a
+ * numeric version.
+ */
+export declare function parseNumericVersion(version: string, extent: "prefix" | "exact"): NumericVersion | undefined;
+/**
+ * Order two numeric versions.
+ * @param left - First version.
+ * @param right - Second version.
+ * @returns - Negative when `left` is lower, positive when it is higher, zero when they are equal.
+ */
+export declare function compareNumericVersions(left: NumericVersion, right: NumericVersion): number;