@pinet/broker-core 0.1.0

package/dist/maintenance.js

@@ -0,0 +1,134 @@
+export const DEFAULT_BROKER_MAINTENANCE_INTERVAL_MS = 5_000;
+export const DEFAULT_BUSY_ASSIGNMENT_AGE_MS = 30_000;
+export const OVERLOADED_INBOX_THRESHOLD = 10;
+export function selectBacklogAssignee(backlog, agentLoads, now = Date.now(), busyAssignmentAgeMs = DEFAULT_BUSY_ASSIGNMENT_AGE_MS) {
+    if (agentLoads.length === 0) {
+        return null;
+    }
+    const idle = agentLoads.filter((entry) => entry.agent.status === "idle").sort(compareAgentLoad);
+    if (idle.length > 0) {
+        return idle[0].agent;
+    }
+    const backlogAgeMs = now - Date.parse(backlog.createdAt);
+    if (backlogAgeMs < busyAssignmentAgeMs) {
+        return null;
+    }
+    const working = [...agentLoads].sort(compareAgentLoad);
+    return working[0]?.agent ?? null;
+}
+export function runBrokerMaintenancePass(db, options) {
+    const now = options.now ?? Date.now();
+    const busyAssignmentAgeMs = options.busyAssignmentAgeMs ?? DEFAULT_BUSY_ASSIGNMENT_AGE_MS;
+    const reapedAgentIds = db.pruneStaleAgents(options.staleAfterMs);
+    const expiredPortLeases = db.expirePortLeases?.(new Date(now).toISOString()) ?? [];
+    db.purgeDisconnectedAgents();
+    const repaired = db.repairThreadOwnership();
+    for (const agentId of repaired.releasedAgentIds) {
+        db.requeueUndeliveredMessages(agentId, "agent_disconnected");
+    }
+    const repairedAssignments = db.repairOrphanedAssignedBacklog();
+    const repairedThreadClaims = repaired.releasedClaimCount;
+    const brokerAgentId = options.brokerAgentId;
+    const agents = db
+        .getAgents()
+        .filter((agent) => agent.id !== brokerAgentId)
+        .filter((agent) => agent.metadata?.role !== "broker");
+    const agentLoads = agents.map((agent) => ({
+        agent,
+        pendingInboxCount: db.getPendingInboxCount(agent.id),
+    }));
+    const nudgedAgentIds = new Set();
+    let assignedBacklogCount = 0;
+    let reboundBrokerBacklogCount = 0;
+    const resetAssignedBacklogCount = repairedAssignments.resetToPendingCount;
+    let droppedBacklogCount = repairedAssignments.droppedCount;
+    for (const backlog of db.getPendingBacklog(options.backlogLimit ?? 50)) {
+        if (brokerAgentId && backlog.preferredAgentId === brokerAgentId) {
+            const assigned = db.assignBacklogEntry(backlog.id, brokerAgentId);
+            if (!assigned) {
+                continue;
+            }
+            assignedBacklogCount += 1;
+            reboundBrokerBacklogCount += 1;
+            continue;
+        }
+        const preferredAgent = backlog.preferredAgentId
+            ? (agents.find((agent) => agent.id === backlog.preferredAgentId) ?? null)
+            : null;
+        if (backlog.preferredAgentId && !preferredAgent) {
+            const knownPreferredAgent = db.getAgentById(backlog.preferredAgentId);
+            if (!knownPreferredAgent) {
+                const dropped = db.dropBacklogEntry(backlog.id, "preferred_agent_missing");
+                if (dropped) {
+                    droppedBacklogCount += 1;
+                }
+            }
+            continue;
+        }
+        const threadOwner = db.getThread(backlog.threadId)?.ownerAgent ?? null;
+        const ownerAgent = threadOwner ? agents.find((agent) => agent.id === threadOwner) : null;
+        const assignee = preferredAgent ??
+            ownerAgent ??
+            selectBacklogAssignee(backlog, agentLoads, now, busyAssignmentAgeMs);
+        if (!assignee) {
+            continue;
+        }
+        const assigned = db.assignBacklogEntry(backlog.id, assignee.id);
+        if (!assigned) {
+            continue;
+        }
+        assignedBacklogCount += 1;
+        nudgedAgentIds.add(assignee.id);
+        const load = agentLoads.find((entry) => entry.agent.id === assignee.id);
+        if (load) {
+            load.pendingInboxCount += 1;
+        }
+    }
+    const pendingBacklogCount = db.getBacklogCount("pending");
+    const anomalies = [];
+    if (reapedAgentIds.length > 0) {
+        anomalies.push(`reaped ${reapedAgentIds.length} stale agent${reapedAgentIds.length === 1 ? "" : "s"}`);
+    }
+    if (expiredPortLeases.length > 0) {
+        anomalies.push(`expired ${expiredPortLeases.length} port lease${expiredPortLeases.length === 1 ? "" : "s"}`);
+    }
+    if (repairedThreadClaims > 0) {
+        anomalies.push(`released ${repairedThreadClaims} orphaned thread claim${repairedThreadClaims === 1 ? "" : "s"}`);
+    }
+    if (reboundBrokerBacklogCount > 0) {
+        anomalies.push(`rebound ${reboundBrokerBacklogCount} broker-targeted backlog item${reboundBrokerBacklogCount === 1 ? "" : "s"} to the live broker`);
+    }
+    if (resetAssignedBacklogCount > 0) {
+        anomalies.push(`reset ${resetAssignedBacklogCount} orphaned backlog assignment${resetAssignedBacklogCount === 1 ? "" : "s"} to pending`);
+    }
+    if (droppedBacklogCount > 0) {
+        anomalies.push(`dropped ${droppedBacklogCount} undeliverable targeted backlog entr${droppedBacklogCount === 1 ? "y" : "ies"}`);
+    }
+    if (pendingBacklogCount > 0 && agentLoads.length === 0) {
+        anomalies.push("pending unrouted backlog has no live workers");
+    }
+    else if (pendingBacklogCount > 0 &&
+        !agentLoads.some((entry) => entry.agent.status === "idle")) {
+        anomalies.push("pending unrouted backlog is waiting for an idle worker");
+    }
+    const overloadedAgents = agentLoads
+        .filter((entry) => entry.pendingInboxCount >= OVERLOADED_INBOX_THRESHOLD)
+        .map((entry) => entry.agent.name);
+    if (overloadedAgents.length > 0) {
+        anomalies.push(`overloaded workers: ${overloadedAgents.join(", ")}`);
+    }
+    return {
+        reapedAgentIds,
+        repairedThreadClaims,
+        assignedBacklogCount,
+        nudgedAgentIds: [...nudgedAgentIds],
+        pendingBacklogCount,
+        anomalies,
+    };
+}
+function compareAgentLoad(left, right) {
+    if (left.pendingInboxCount !== right.pendingInboxCount) {
+        return left.pendingInboxCount - right.pendingInboxCount;
+    }
+    return Date.parse(left.agent.lastSeen) - Date.parse(right.agent.lastSeen);
+}

package/dist/message-send.d.ts

@@ -0,0 +1,31 @@
+import type { BrokerMessage, MessageAdapter, NormalizedMessageContent, ThreadInfo } from "./types.js";
+export interface BrokerMessageSenderDb {
+    getThread(threadId: string): ThreadInfo | null;
+    createThread(threadId: string, source: string, channel: string, ownerAgent: string | null): ThreadInfo;
+    updateThread(threadId: string, updates: Partial<ThreadInfo>): void;
+    claimThread(threadId: string, agentId: string, source?: string, channel?: string): boolean;
+    insertMessage(threadId: string, source: string, direction: "inbound" | "outbound", sender: string, body: string, targetAgentIds: string[], metadata?: Record<string, unknown>): BrokerMessage;
+}
+export interface BrokerMessageSenderDeps {
+    db: BrokerMessageSenderDb;
+    adapters: ReadonlyArray<Pick<MessageAdapter, "name" | "send">>;
+}
+export interface SendBrokerMessageInput {
+    threadId: string;
+    body: string;
+    senderAgentId: string;
+    source?: string;
+    channel?: string;
+    content?: NormalizedMessageContent;
+    blocks?: ReadonlyArray<Record<string, unknown>>;
+    agentName?: string;
+    agentEmoji?: string;
+    agentOwnerToken?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SendBrokerMessageResult {
+    thread: ThreadInfo;
+    message: BrokerMessage;
+    adapter: string;
+}
+export declare function sendBrokerMessage(deps: BrokerMessageSenderDeps, input: SendBrokerMessageInput): Promise<SendBrokerMessageResult>;

package/dist/message-send.js

@@ -0,0 +1,75 @@
+function normalizeMessageContent(content) {
+    if (!content) {
+        return undefined;
+    }
+    const text = content.text.trim();
+    if (!text) {
+        throw new Error("content.text is required when content is provided.");
+    }
+    const markdown = content.markdown?.trim();
+    return {
+        text,
+        ...(markdown ? { markdown } : {}),
+        ...(content.slackBlocks && content.slackBlocks.length > 0
+            ? { slackBlocks: content.slackBlocks }
+            : {}),
+    };
+}
+export async function sendBrokerMessage(deps, input) {
+    const threadId = input.threadId.trim();
+    const body = input.body.trim();
+    if (!threadId || !body) {
+        throw new Error("threadId and body are required.");
+    }
+    const existingThread = deps.db.getThread(threadId);
+    const source = (input.source ?? existingThread?.source ?? "").trim();
+    const channel = (input.channel ?? existingThread?.channel ?? "").trim();
+    if (!source) {
+        throw new Error(`No transport source is recorded for thread ${threadId}.`);
+    }
+    if (!channel) {
+        throw new Error(`No transport channel is recorded for thread ${threadId}.`);
+    }
+    const adapter = deps.adapters.find((candidate) => candidate.name === source);
+    if (!adapter) {
+        throw new Error(`No adapter is registered for transport source ${JSON.stringify(source)}.`);
+    }
+    const content = normalizeMessageContent(input.content);
+    const messageBody = content?.text ?? body;
+    let thread = existingThread;
+    if (thread?.ownerAgent && thread.ownerAgent !== input.senderAgentId) {
+        throw new Error(`Thread ${threadId} is already owned by another agent.`);
+    }
+    if (!thread || thread.ownerAgent === null) {
+        const claimed = deps.db.claimThread(threadId, input.senderAgentId, source, channel);
+        if (!claimed) {
+            throw new Error(`Thread ${threadId} is already owned by another agent.`);
+        }
+        thread = deps.db.getThread(threadId);
+        if (!thread) {
+            throw new Error(`Thread ${threadId} was claimed but could not be read back.`);
+        }
+    }
+    if (thread.source !== source || thread.channel !== channel) {
+        deps.db.updateThread(threadId, { source, channel });
+        thread = { ...thread, source, channel };
+    }
+    const outbound = {
+        threadId,
+        channel,
+        text: messageBody,
+        ...(content ? { content } : {}),
+        ...(input.blocks && input.blocks.length > 0 ? { blocks: input.blocks } : {}),
+        ...(input.agentName ? { agentName: input.agentName } : {}),
+        ...(input.agentEmoji ? { agentEmoji: input.agentEmoji } : {}),
+        ...(input.agentOwnerToken ? { agentOwnerToken: input.agentOwnerToken } : {}),
+        ...(input.metadata ? { metadata: input.metadata } : {}),
+    };
+    await adapter.send(outbound);
+    const message = deps.db.insertMessage(threadId, source, "outbound", input.senderAgentId, messageBody, [], input.metadata);
+    return {
+        thread,
+        message,
+        adapter: adapter.name,
+    };
+}

package/dist/paths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Centralized Pinet broker file paths.
+ * All socket and database path constants are defined here to ensure consistency
+ * across the broker, client, and schema modules.
+ */
+/** Default Pinet config directory: ~/.pi */
+export declare function getPinetConfigDir(): string;
+/** Default Unix socket path for broker communication: ~/.pi/pinet.sock */
+export declare function getDefaultSocketPath(): string;
+export declare const DEFAULT_SOCKET_PATH: string;
+/** Default SQLite database path for broker: ~/.pi/pinet-broker.db */
+export declare function getDefaultDbPath(): string;
+/** Shared secret file used to authenticate local Pinet mesh clients: ~/.pi/pinet.secret */
+export declare function getDefaultMeshSecretPath(): string;

package/dist/paths.js

@@ -0,0 +1,29 @@
+/**
+ * Centralized Pinet broker file paths.
+ * All socket and database path constants are defined here to ensure consistency
+ * across the broker, client, and schema modules.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+// ─── Directories ─────────────────────────────────────────
+/** Default Pinet config directory: ~/.pi */
+export function getPinetConfigDir() {
+    return path.join(os.homedir(), ".pi");
+}
+// ─── Socket Paths ────────────────────────────────────────
+/** Default Unix socket path for broker communication: ~/.pi/pinet.sock */
+export function getDefaultSocketPath() {
+    return path.join(getPinetConfigDir(), "pinet.sock");
+}
+// Re-export as static constant for backward compatibility
+export const DEFAULT_SOCKET_PATH = getDefaultSocketPath();
+// ─── Database Paths ──────────────────────────────────────
+/** Default SQLite database path for broker: ~/.pi/pinet-broker.db */
+export function getDefaultDbPath() {
+    return path.join(getPinetConfigDir(), "pinet-broker.db");
+}
+// ─── Mesh auth paths ─────────────────────────────────────
+/** Shared secret file used to authenticate local Pinet mesh clients: ~/.pi/pinet.secret */
+export function getDefaultMeshSecretPath() {
+    return path.join(getPinetConfigDir(), "pinet.secret");
+}

package/dist/raw-tcp-loopback.d.ts

@@ -0,0 +1,2 @@
+export declare function isLoopbackTcpHost(host: string): boolean;
+export declare function assertLoopbackTcpHost(host: string, targetDescription: string): void;

package/dist/raw-tcp-loopback.js

@@ -0,0 +1,39 @@
+import * as net from "node:net";
+function normalizeTcpHost(host) {
+    const trimmed = host.trim();
+    const unwrapped = trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+    return unwrapped.toLowerCase().replace(/\.$/, "");
+}
+function isLoopbackIpv4Host(host) {
+    if (net.isIP(host) !== 4) {
+        return false;
+    }
+    const octets = host.split(".");
+    if (octets.length !== 4) {
+        return false;
+    }
+    return (octets[0] === "127" &&
+        octets.every((octet) => {
+            if (!/^\d+$/.test(octet)) {
+                return false;
+            }
+            const value = Number(octet);
+            return value >= 0 && value <= 255;
+        }));
+}
+export function isLoopbackTcpHost(host) {
+    const normalized = normalizeTcpHost(host);
+    if (normalized === "localhost" || normalized === "::1") {
+        return true;
+    }
+    if (normalized.startsWith("::ffff:")) {
+        return isLoopbackTcpHost(normalized.slice("::ffff:".length));
+    }
+    return isLoopbackIpv4Host(normalized);
+}
+export function assertLoopbackTcpHost(host, targetDescription) {
+    if (isLoopbackTcpHost(host)) {
+        return;
+    }
+    throw new Error(`Refusing ${targetDescription} on non-loopback raw TCP host "${host}". Raw TCP broker endpoints are limited to loopback-only hosts until a secure remote transport exists.`);
+}

package/dist/router.d.ts

@@ -0,0 +1,60 @@
+import type { AgentInfo, BrokerDBInterface, InboundMessage, RoutingDecision } from "./types.js";
+export interface ThreadOwnerHint {
+    agentId?: string;
+    stableId?: string;
+    agentOwner?: string;
+    agentName?: string;
+}
+export type ExplicitThreadDirective = {
+    kind: "stand_down";
+    agent: AgentInfo;
+} | {
+    kind: "retarget";
+    agent: AgentInfo;
+};
+/**
+ * Extract an agent name mention from message text.
+ * Matches patterns like "hey AgentName," or "@AgentName" or just "AgentName"
+ * at word boundaries (case-insensitive).
+ *
+ * When multiple agents match, the longest name wins so that "CodeBot" is
+ * preferred over "Code" and similar-prefix collisions are avoided.
+ */
+export declare function findAgentMention(text: string, agents: AgentInfo[]): AgentInfo | null;
+export declare function extractPiAgentThreadOwnerHint(replies: ReadonlyArray<Record<string, unknown>>): ThreadOwnerHint | null;
+export declare function findExplicitThreadDirective(text: string, agents: AgentInfo[]): ExplicitThreadDirective | null;
+export declare class MessageRouter {
+    private readonly db;
+    constructor(db: BrokerDBInterface);
+    /**
+     * Route an inbound message to the right agent.
+     *
+     * Priority order:
+     * 1. User allowlist — reject if user not allowed
+     * 2. Explicit thread control — stand-down / reassignment signals in-thread
+     * 3. Known-thread ownership — authoritative owner hint, then broker DB owner
+     * 4. New-thread channel assignment / direct address
+     * 5. Unrouted — no match found
+     */
+    route(msg: InboundMessage): RoutingDecision;
+    /**
+     * Claim a thread for an agent (first-responder-wins).
+     * Optionally provide the transport source and channel to store when creating
+     * a new thread. Defaults to a neutral external source when callers do not
+     * provide one; Slack call sites should continue passing `source: "slack"`
+     * explicitly through inbound messages or compatibility wrappers.
+     * Returns true if the claim succeeded, false if another agent already owns it.
+     *
+     * Delegates to the DB layer which performs the claim atomically
+     * (single SQL statement) to avoid TOCTOU races. (#125)
+     */
+    claimThread(threadId: string, agentId: string, channel?: string, source?: string): boolean;
+    /**
+     * Get the owner of a thread, or null if unclaimed / nonexistent.
+     */
+    getThreadOwner(threadId: string): string | null;
+    /**
+     * List available (connected) agents for routing.
+     */
+    getAvailableAgents(): AgentInfo[];
+}