@pinet/broker-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Porcellini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @pinet/broker-core
+
+Transport-neutral broker kernel primitives for the `extensions` repo.
+
+## What lives here
+
+- broker domain types
+- broker SQLite state and persistence
+- routing and backlog maintenance logic
+- direct/broadcast agent messaging helpers
+- broker auth / lock / path / loopback utilities
+
+## What stays out of scope
+
+- Slack adapter and event normalization
+- Slack tools, Home tabs, canvases, and manifest concerns
+- Pi extension command/tool wiring
+- broker runtime orchestration and RALPH UI flows
+- follower runtime and single-player runtime glue
+
+## Publishing
+
+This package is part of the full npm publish set tracked in
+[`../plans/npm-publish.md`](../plans/npm-publish.md). Use the GitHub Actions
+workflow's default dry-run/readiness path for validation; do not publish, tag, or
+bump versions without explicit maintainer release approval.

package/dist/agent-messaging.d.ts

@@ -0,0 +1,47 @@
+import type { AgentInfo, BrokerMessage } from "./types.js";
+export interface AgentMessageStorage {
+    getAgents(): AgentInfo[];
+    getThread(threadId: string): {
+        threadId: string;
+    } | null;
+    createThread(threadId: string, source: string, channel: string, ownerAgent: string | null): void;
+    insertMessage(threadId: string, source: string, direction: "inbound" | "outbound", sender: string, body: string, targetAgentIds: string[], metadata?: Record<string, unknown>): BrokerMessage;
+}
+export interface AgentDispatchTarget {
+    id: string;
+    name: string;
+}
+export interface DirectAgentDispatchInput {
+    senderAgentId: string;
+    senderAgentName: string;
+    target: string;
+    body: string;
+    metadata?: Record<string, unknown>;
+}
+export interface BroadcastAgentDispatchInput {
+    senderAgentId: string;
+    senderAgentName: string;
+    channel: string;
+    body: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DirectAgentDispatchResult {
+    target: AgentDispatchTarget;
+    messageId: number;
+    threadId: string;
+}
+export interface BroadcastAgentDispatchResult {
+    channel: string;
+    targets: AgentDispatchTarget[];
+    messageIds: number[];
+    threadIds: string[];
+}
+export type AgentDispatchCallback = (target: AgentDispatchTarget, message: BrokerMessage, metadata: Record<string, unknown>) => void;
+export declare function isBroadcastChannelTarget(target: string): boolean;
+export declare function normalizeBroadcastChannel(channel: string): string | null;
+export declare function getAgentBroadcastChannels(agent: Pick<AgentInfo, "metadata">): string[];
+export declare function agentSubscribesToBroadcastChannel(agent: Pick<AgentInfo, "metadata">, channel: string): boolean;
+export declare function resolveDirectAgentTarget(agents: AgentInfo[], target: string): AgentInfo | null;
+export declare function resolveBroadcastTargets(agents: AgentInfo[], senderAgentId: string, channel: string): AgentInfo[];
+export declare function dispatchDirectAgentMessage(storage: AgentMessageStorage, input: DirectAgentDispatchInput, onDispatch?: AgentDispatchCallback): DirectAgentDispatchResult;
+export declare function dispatchBroadcastAgentMessage(storage: AgentMessageStorage, input: BroadcastAgentDispatchInput, onDispatch?: AgentDispatchCallback): BroadcastAgentDispatchResult;

package/dist/agent-messaging.js

@@ -0,0 +1,176 @@
+import { classifyPinetMail } from "./mail-classification.js";
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function extractAgentCapabilities(metadata) {
+    const record = asRecord(metadata);
+    const capabilitiesRecord = asRecord(record?.capabilities);
+    return {
+        repo: asString(capabilitiesRecord?.repo) ?? asString(record?.repo),
+        role: asString(capabilitiesRecord?.role) ?? asString(record?.role),
+        tools: asStringArray(capabilitiesRecord?.tools),
+        tags: asStringArray(capabilitiesRecord?.tags),
+    };
+}
+function buildAgentCapabilityTags(capabilities) {
+    const tags = new Set();
+    if (capabilities.role)
+        tags.add(`role:${capabilities.role}`);
+    if (capabilities.repo)
+        tags.add(`repo:${capabilities.repo}`);
+    for (const tool of capabilities.tools ?? []) {
+        tags.add(`tool:${tool}`);
+    }
+    for (const tag of capabilities.tags ?? []) {
+        tags.add(tag);
+    }
+    return [...tags];
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function normalizeChannelName(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const withoutHash = trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+    const normalized = withoutHash.trim().toLowerCase();
+    return normalized.length > 0 ? normalized : null;
+}
+function addChannel(set, rawValue) {
+    const normalized = normalizeChannelName(rawValue);
+    if (!normalized)
+        return;
+    set.add(normalized);
+    if (normalized.startsWith("channel:") || normalized.startsWith("topic:")) {
+        const derived = normalized.slice(normalized.indexOf(":") + 1).trim();
+        if (derived) {
+            set.add(derived);
+        }
+    }
+}
+function ensurePairThread(storage, senderAgentId, targetAgentId) {
+    const threadId = `a2a:${senderAgentId}:${targetAgentId}`;
+    if (!storage.getThread(threadId)) {
+        storage.createThread(threadId, "agent", "", senderAgentId);
+    }
+    return threadId;
+}
+function buildAgentMessageMetadata(senderAgentName, body, metadata, broadcastChannel) {
+    const baseMetadata = {
+        ...metadata,
+        senderAgent: senderAgentName,
+        a2a: true,
+        ...(broadcastChannel ? { broadcast: true, broadcastChannel } : {}),
+    };
+    const classification = classifyPinetMail({ source: "agent", body, metadata: baseMetadata });
+    return {
+        ...baseMetadata,
+        pinetMailClass: classification.class,
+    };
+}
+function deliverAgentMessage(storage, senderAgentId, target, body, metadata, onDispatch) {
+    const threadId = ensurePairThread(storage, senderAgentId, target.id);
+    const msg = storage.insertMessage(threadId, "agent", "inbound", senderAgentId, body, [target.id], metadata);
+    onDispatch?.(target, msg, metadata);
+    return { threadId, messageId: msg.id };
+}
+export function isBroadcastChannelTarget(target) {
+    return target.trim().startsWith("#");
+}
+export function normalizeBroadcastChannel(channel) {
+    return normalizeChannelName(channel);
+}
+export function getAgentBroadcastChannels(agent) {
+    const subscriptions = new Set(["all"]);
+    const metadata = asRecord(agent.metadata);
+    const capabilities = extractAgentCapabilities(metadata);
+    if (capabilities.repo) {
+        addChannel(subscriptions, capabilities.repo);
+    }
+    const role = capabilities.role?.trim().toLowerCase();
+    if (role) {
+        addChannel(subscriptions, `role:${role}`);
+    }
+    if (role !== "broker") {
+        addChannel(subscriptions, "standup");
+    }
+    for (const tag of buildAgentCapabilityTags(capabilities)) {
+        addChannel(subscriptions, tag);
+    }
+    for (const channel of asStringArray(metadata?.broadcastChannels)) {
+        addChannel(subscriptions, channel);
+    }
+    for (const channel of asStringArray(metadata?.channels)) {
+        addChannel(subscriptions, channel);
+    }
+    for (const topic of asStringArray(metadata?.topics)) {
+        addChannel(subscriptions, `topic:${topic}`);
+    }
+    return [...subscriptions].sort();
+}
+export function agentSubscribesToBroadcastChannel(agent, channel) {
+    const normalized = normalizeBroadcastChannel(channel);
+    if (!normalized)
+        return false;
+    return getAgentBroadcastChannels(agent).includes(normalized);
+}
+export function resolveDirectAgentTarget(agents, target) {
+    return (agents.find((agent) => agent.id === target) ??
+        agents.find((agent) => agent.name === target) ??
+        null);
+}
+export function resolveBroadcastTargets(agents, senderAgentId, channel) {
+    return agents
+        .filter((agent) => agent.id !== senderAgentId)
+        .filter((agent) => agentSubscribesToBroadcastChannel(agent, channel))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+export function dispatchDirectAgentMessage(storage, input, onDispatch) {
+    const target = resolveDirectAgentTarget(storage.getAgents(), input.target);
+    if (!target) {
+        throw new Error(`Agent not found: ${input.target}`);
+    }
+    const resolvedTarget = { id: target.id, name: target.name };
+    const metadata = buildAgentMessageMetadata(input.senderAgentName, input.body, input.metadata);
+    const { threadId, messageId } = deliverAgentMessage(storage, input.senderAgentId, resolvedTarget, input.body, metadata, onDispatch);
+    return {
+        target: resolvedTarget,
+        messageId,
+        threadId,
+    };
+}
+export function dispatchBroadcastAgentMessage(storage, input, onDispatch) {
+    const normalizedChannel = normalizeBroadcastChannel(input.channel);
+    if (!normalizedChannel) {
+        throw new Error("Broadcast channel is required");
+    }
+    const agents = storage.getAgents();
+    const targets = resolveBroadcastTargets(agents, input.senderAgentId, normalizedChannel).map((agent) => ({ id: agent.id, name: agent.name }));
+    if (targets.length === 0) {
+        throw new Error(`No agents subscribed to #${normalizedChannel} other than the sender.`);
+    }
+    const broadcastChannel = `#${normalizedChannel}`;
+    const metadata = buildAgentMessageMetadata(input.senderAgentName, input.body, input.metadata, broadcastChannel);
+    const messageIds = [];
+    const threadIds = [];
+    for (const target of targets) {
+        const delivery = deliverAgentMessage(storage, input.senderAgentId, target, input.body, metadata, onDispatch);
+        messageIds.push(delivery.messageId);
+        threadIds.push(delivery.threadId);
+    }
+    return {
+        channel: broadcastChannel,
+        targets,
+        messageIds,
+        threadIds,
+    };
+}

package/dist/auth.d.ts

@@ -0,0 +1,7 @@
+export interface MeshSecretOptions {
+    meshSecret?: string | null;
+    meshSecretPath?: string | null;
+}
+export declare function readMeshSecret(secretPath?: string): string;
+export declare function loadOrCreateMeshSecret(secretPath?: string): string;
+export declare function resolveMeshSecret(options?: MeshSecretOptions): string | null;

package/dist/auth.js

@@ -0,0 +1,59 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getDefaultMeshSecretPath } from "./paths.js";
+function normalizeMeshSecret(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : null;
+}
+function getErrorCode(err) {
+    if (typeof err !== "object" || err == null || !("code" in err)) {
+        return null;
+    }
+    const code = err.code;
+    return typeof code === "string" ? code : null;
+}
+export function readMeshSecret(secretPath = getDefaultMeshSecretPath()) {
+    const secret = normalizeMeshSecret(fs.readFileSync(secretPath, "utf-8"));
+    if (!secret) {
+        throw new Error(`Pinet mesh secret file is empty: ${secretPath}`);
+    }
+    return secret;
+}
+export function loadOrCreateMeshSecret(secretPath = getDefaultMeshSecretPath()) {
+    try {
+        return readMeshSecret(secretPath);
+    }
+    catch (err) {
+        if (getErrorCode(err) !== "ENOENT") {
+            throw err;
+        }
+    }
+    fs.mkdirSync(path.dirname(secretPath), { recursive: true, mode: 0o700 });
+    const meshSecret = crypto.randomBytes(32).toString("hex");
+    try {
+        fs.writeFileSync(secretPath, `${meshSecret}\n`, {
+            encoding: "utf-8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        return meshSecret;
+    }
+    catch (err) {
+        if (getErrorCode(err) !== "EEXIST") {
+            throw err;
+        }
+        return readMeshSecret(secretPath);
+    }
+}
+export function resolveMeshSecret(options = {}) {
+    const explicitSecret = normalizeMeshSecret(options.meshSecret);
+    if (explicitSecret) {
+        return explicitSecret;
+    }
+    const meshSecretPath = options.meshSecretPath?.trim();
+    if (!meshSecretPath) {
+        return null;
+    }
+    return readMeshSecret(meshSecretPath);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./agent-messaging.js";
+export * from "./auth.js";
+export * from "./leader.js";
+export * from "./maintenance.js";
+export * from "./mail-classification.js";
+export * from "./message-send.js";
+export * from "./paths.js";
+export * from "./raw-tcp-loopback.js";
+export * from "./router.js";
+export * from "./schema.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+export * from "./agent-messaging.js";
+export * from "./auth.js";
+export * from "./leader.js";
+export * from "./maintenance.js";
+export * from "./mail-classification.js";
+export * from "./message-send.js";
+export * from "./paths.js";
+export * from "./raw-tcp-loopback.js";
+export * from "./router.js";
+export * from "./schema.js";
+export * from "./types.js";

package/dist/leader.d.ts

@@ -0,0 +1,29 @@
+export declare function defaultLockPath(): string;
+/**
+ * Leader election via PID lock file.
+ *
+ * Only one broker process should run at a time. The leader writes its
+ * PID to the lock file. Stale locks (PID no longer running) are
+ * automatically reclaimed.
+ */
+export declare class LeaderLock {
+    private readonly lockPath;
+    private acquired;
+    constructor(lockPath?: string);
+    /**
+     * Try to acquire the lock. Returns true if this process is now the leader.
+     */
+    tryAcquire(): boolean;
+    /**
+     * Release the lock if we hold it.
+     */
+    release(): void;
+    /**
+     * Check if this instance currently holds the lock.
+     */
+    isLeader(): boolean;
+    /**
+     * Get the lock file path (for testing).
+     */
+    getLockPath(): string;
+}

package/dist/leader.js

@@ -0,0 +1,95 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+export function defaultLockPath() {
+    return path.join(os.homedir(), ".pi", "pinet-broker.lock");
+}
+/**
+ * Leader election via PID lock file.
+ *
+ * Only one broker process should run at a time. The leader writes its
+ * PID to the lock file. Stale locks (PID no longer running) are
+ * automatically reclaimed.
+ */
+export class LeaderLock {
+    lockPath;
+    acquired = false;
+    constructor(lockPath) {
+        this.lockPath = lockPath ?? defaultLockPath();
+    }
+    /**
+     * Try to acquire the lock. Returns true if this process is now the leader.
+     */
+    tryAcquire() {
+        if (this.acquired)
+            return true;
+        fs.mkdirSync(path.dirname(this.lockPath), { recursive: true });
+        // Check existing lock
+        if (fs.existsSync(this.lockPath)) {
+            const content = fs.readFileSync(this.lockPath, "utf-8").trim();
+            const existingPid = parseInt(content, 10);
+            if (!isNaN(existingPid) && isProcessRunning(existingPid)) {
+                // Another live process holds the lock
+                return false;
+            }
+            // Stale lock — remove it
+            fs.unlinkSync(this.lockPath);
+        }
+        // Write our PID atomically (write to temp, rename)
+        const pid = process.pid;
+        const tmpPath = `${this.lockPath}.${pid}.tmp`;
+        fs.writeFileSync(tmpPath, String(pid), "utf-8");
+        fs.renameSync(tmpPath, this.lockPath);
+        // Verify we actually won (guard against race)
+        const written = fs.readFileSync(this.lockPath, "utf-8").trim();
+        if (written !== String(pid)) {
+            return false;
+        }
+        this.acquired = true;
+        return true;
+    }
+    /**
+     * Release the lock if we hold it.
+     */
+    release() {
+        if (!this.acquired)
+            return;
+        try {
+            // Only remove if it's still our PID
+            if (fs.existsSync(this.lockPath)) {
+                const content = fs.readFileSync(this.lockPath, "utf-8").trim();
+                if (content === String(process.pid)) {
+                    fs.unlinkSync(this.lockPath);
+                }
+            }
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        this.acquired = false;
+    }
+    /**
+     * Check if this instance currently holds the lock.
+     */
+    isLeader() {
+        return this.acquired;
+    }
+    /**
+     * Get the lock file path (for testing).
+     */
+    getLockPath() {
+        return this.lockPath;
+    }
+}
+/**
+ * Check if a process with the given PID is currently running.
+ */
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/mail-classification.d.ts

@@ -0,0 +1,17 @@
+export declare const PINET_MAIL_CLASSES: readonly ["steering", "fwup", "maintenance_context"];
+export type PinetMailClass = (typeof PINET_MAIL_CLASSES)[number];
+export interface PinetMailClassificationInput {
+    source?: string | null;
+    threadId?: string | null;
+    sender?: string | null;
+    body?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface PinetMailClassification {
+    class: PinetMailClass;
+    reason: string;
+    explicit: boolean;
+}
+export declare function normalizePinetMailClass(value: unknown): PinetMailClass | null;
+export declare function classifyPinetMail(input: PinetMailClassificationInput): PinetMailClassification;
+export declare function formatPinetMailClassLabel(mailClass: PinetMailClass): string;

package/dist/mail-classification.js

@@ -0,0 +1,103 @@
+export const PINET_MAIL_CLASSES = ["steering", "fwup", "maintenance_context"];
+const EXPLICIT_CLASS_KEYS = [
+    "pinetMailClass",
+    "pinet_mail_class",
+    "mailClass",
+    "mail_class",
+    "mailKind",
+    "mail_kind",
+    "classification",
+];
+const STEERING_PATTERNS = [
+    /\back(?:\/|\s*)work(?:\/|\s*)ask(?:\/|\s*)report\b/i,
+    /\back briefly\b/i,
+    /\bplease (?:take|continue|implement|fix|review|inspect|reassign|handle|work on)\b/i,
+    /\b(?:new|fresh) (?:implementation )?(?:lane|task|worktree)\b/i,
+    /\b(?:task|issue|worktree setup|scope|workflow|acceptance criteria|constraints?)\s*:/i,
+    /\b(?:take|continue|implement|fix|review|inspect|reassign|handle|work on)\s+(?:issue|pr)\s*#\d+\b/i,
+    /\b(?:issue|pr)\s*#\d+\b.*\back(?:\/|\s*)work(?:\/|\s*)ask(?:\/|\s*)report\b/i,
+    /\breport blockers? immediately\b/i,
+];
+const MAINTENANCE_CONTEXT_PATTERNS = [
+    /\bralph\b.*\b(?:maintenance|ghost|reap|nudge|drain)\b/i,
+    /\bbroker[- ]only maintenance\b/i,
+    /\bmaintenance (?:anomaly|recovery|timer|pass)\b/i,
+    /\bno further repl(?:y|ies) (?:are|is) needed\b/i,
+    /\bno further acknowledg(?:ement|ements) (?:are|is) needed\b/i,
+    /\bno reply is needed\b/i,
+    /\bno action needed\b/i,
+    /\bhard stop on this [^.\n]*thread\b/i,
+    /\bstand down\b/i,
+    /\bthread is already satisfied\b/i,
+    /\bunless I (?:assign|ask for) (?:a )?(?:genuinely )?new task\b/i,
+    /\bstay free(?:\/| and )quiet\b/i,
+    /\bstay quiet(?:\/| and )free\b/i,
+];
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+export function normalizePinetMailClass(value) {
+    const raw = asString(value)
+        ?.toLowerCase()
+        .replace(/[\s-]+/g, "_");
+    if (!raw)
+        return null;
+    if (raw === "steering" || raw === "steer" || raw === "directive")
+        return "steering";
+    if (raw === "fwup" || raw === "follow_up" || raw === "followup")
+        return "fwup";
+    if (raw === "maintenance_context" ||
+        raw === "maintenance" ||
+        raw === "context_only" ||
+        raw === "context") {
+        return "maintenance_context";
+    }
+    return null;
+}
+function getExplicitMailClass(metadata) {
+    if (!metadata)
+        return null;
+    for (const key of EXPLICIT_CLASS_KEYS) {
+        const normalized = normalizePinetMailClass(metadata[key]);
+        if (normalized)
+            return normalized;
+    }
+    return null;
+}
+function hasPattern(patterns, value) {
+    return patterns.some((pattern) => pattern.test(value));
+}
+function metadataLooksLikeMaintenance(metadata) {
+    const kind = asString(metadata?.kind)?.toLowerCase() ?? "";
+    const type = asString(metadata?.type)?.toLowerCase() ?? "";
+    const eventType = asString(metadata?.event_type)?.toLowerCase() ?? "";
+    return [kind, type, eventType].some((value) => {
+        const normalized = value.replace(/_/g, ":");
+        return (normalized.includes("maintenance") ||
+            normalized.includes("ralph") ||
+            normalized === "pinet:control" ||
+            normalized === "pinet:skin");
+    });
+}
+export function classifyPinetMail(input) {
+    const metadata = input.metadata ?? null;
+    const explicitClass = getExplicitMailClass(metadata);
+    if (explicitClass) {
+        return { class: explicitClass, reason: "explicit metadata", explicit: true };
+    }
+    const body = input.body ?? "";
+    if (metadataLooksLikeMaintenance(metadata) || hasPattern(MAINTENANCE_CONTEXT_PATTERNS, body)) {
+        return {
+            class: "maintenance_context",
+            reason: "maintenance/context-only cues",
+            explicit: false,
+        };
+    }
+    if (hasPattern(STEERING_PATTERNS, body)) {
+        return { class: "steering", reason: "actionable steering cues", explicit: false };
+    }
+    return { class: "fwup", reason: "default follow-up mail", explicit: false };
+}
+export function formatPinetMailClassLabel(mailClass) {
+    return mailClass === "maintenance_context" ? "maintenance/context" : mailClass;
+}

package/dist/maintenance.d.ts

@@ -0,0 +1,50 @@
+import type { AgentInfo, BacklogEntry, PortLeaseInfo, ThreadInfo } from "./types.js";
+export declare const DEFAULT_BROKER_MAINTENANCE_INTERVAL_MS = 5000;
+export declare const DEFAULT_BUSY_ASSIGNMENT_AGE_MS = 30000;
+export declare const OVERLOADED_INBOX_THRESHOLD = 10;
+export interface ThreadRepairResult {
+    releasedClaimCount: number;
+    releasedAgentIds: string[];
+}
+export interface BacklogAssignmentRepairResult {
+    resetToPendingCount: number;
+    droppedCount: number;
+}
+export interface BrokerMaintenanceDB {
+    pruneStaleAgents(staleAfterMs: number): string[];
+    purgeDisconnectedAgents(graceMs?: number): string[];
+    repairThreadOwnership(): ThreadRepairResult;
+    repairOrphanedAssignedBacklog(): BacklogAssignmentRepairResult;
+    requeueUndeliveredMessages(agentId: string, reason?: string): number;
+    getPendingBacklog(limit?: number): BacklogEntry[];
+    getBacklogCount(status?: BacklogEntry["status"]): number;
+    getAgentById(agentId: string): AgentInfo | null;
+    getAgents(): AgentInfo[];
+    getPendingInboxCount(agentId: string): number;
+    getThread(threadId: string): ThreadInfo | null;
+    assignBacklogEntry(id: number, agentId: string): BacklogEntry | null;
+    dropBacklogEntry(id: number, reason: string): BacklogEntry | null;
+    expirePortLeases?: (nowIso?: string) => PortLeaseInfo[];
+}
+export interface BrokerMaintenanceOptions {
+    brokerAgentId?: string;
+    staleAfterMs: number;
+    backlogLimit?: number;
+    busyAssignmentAgeMs?: number;
+    now?: number;
+}
+export interface BrokerMaintenanceResult {
+    reapedAgentIds: string[];
+    repairedThreadClaims: number;
+    assignedBacklogCount: number;
+    nudgedAgentIds: string[];
+    pendingBacklogCount: number;
+    anomalies: string[];
+}
+interface AgentLoad {
+    agent: AgentInfo;
+    pendingInboxCount: number;
+}
+export declare function selectBacklogAssignee(backlog: BacklogEntry, agentLoads: AgentLoad[], now?: number, busyAssignmentAgeMs?: number): AgentInfo | null;
+export declare function runBrokerMaintenancePass(db: BrokerMaintenanceDB, options: BrokerMaintenanceOptions): BrokerMaintenanceResult;
+export {};