@pinet/slack-bridge 0.1.0

package/dist/broker/control-plane-dashboard.d.ts

@@ -0,0 +1,98 @@
+import type { RalphLoopAgentWorkload, RalphLoopEvaluationOptions, RalphLoopEvaluationResult } from "../helpers.js";
+import type { ResolvedTaskAssignment } from "../task-assignments.js";
+import type { BrokerMaintenanceResult } from "./maintenance.js";
+import type { PinetLaneInfo } from "./types.js";
+export type BrokerControlPlaneRecentCycle = {
+    startedAt: string;
+    completedAt: string | null;
+    durationMs: number | null;
+    ghostAgentIds: string[];
+    stuckAgentIds: string[];
+    anomalies: string[];
+    followUpDelivered: boolean;
+    agentCount: number;
+    backlogCount: number;
+};
+export interface BrokerControlPlaneAgentRow {
+    id: string;
+    role: string;
+    label: string;
+    status: string;
+    health: string;
+    workload: string;
+    taskSummary: string;
+    heartbeat: string;
+    branch: string;
+    worktree: string;
+}
+export interface BrokerControlPlaneDashboardSnapshot {
+    cycleStartedAt: string;
+    cycleDurationMs: number;
+    currentBranch: string | null;
+    ralphSnooze?: {
+        active: boolean;
+        until: string | null;
+        reason: string | null;
+        source: string | null;
+        emptyCycleCount: number;
+    } | null;
+    totalAgents: number;
+    liveAgents: number;
+    brokerCount: number;
+    workerCount: number;
+    idleWorkers: number;
+    workingWorkers: number;
+    ghostAgents: number;
+    stuckAgents: number;
+    pendingBacklogCount: number;
+    nudgesThisCycle: number;
+    idleDrainCandidates: number;
+    assignedBacklogCount: number;
+    reapedAgents: number;
+    repairedThreadClaims: number;
+    maintenanceAnomalies: string[];
+    anomalies: string[];
+    taskCounts: {
+        assigned: number;
+        branchPushed: number;
+        openPrs: number;
+        mergedPrs: number;
+        closedPrs: number;
+    };
+    activeTasks: string[];
+    recentOutcomes: string[];
+    activeLanes: string[];
+    detachedLanes: string[];
+    roster: BrokerControlPlaneAgentRow[];
+    recentCycles: Array<{
+        startedAt: string;
+        duration: string;
+        agentCount: number;
+        backlogCount: number;
+        ghostCount: number;
+        stuckCount: number;
+        anomalySummary: string;
+        followUpDelivered: boolean;
+    }>;
+}
+export interface BuildBrokerControlPlaneDashboardSnapshotInput {
+    workloads: RalphLoopAgentWorkload[];
+    evaluation: RalphLoopEvaluationResult;
+    evaluationOptions?: RalphLoopEvaluationOptions;
+    maintenance: BrokerMaintenanceResult | null;
+    assignments: Array<Pick<ResolvedTaskAssignment, "agentId" | "issueNumber" | "branch" | "status" | "prNumber" | "updatedAt" | "issueState">>;
+    lanes?: PinetLaneInfo[];
+    recentCycles: BrokerControlPlaneRecentCycle[];
+    cycleStartedAt: string;
+    cycleDurationMs: number;
+    currentBranch: string | null;
+    homedir?: string;
+    snooze?: {
+        active: boolean;
+        until: string | null;
+        reason: string | null;
+        source: string | null;
+        emptyCycleCount: number;
+    } | null;
+}
+export declare function buildBrokerControlPlaneDashboardSnapshot(input: BuildBrokerControlPlaneDashboardSnapshotInput): BrokerControlPlaneDashboardSnapshot;

package/dist/broker/control-plane-dashboard.js

@@ -0,0 +1,213 @@
+import { buildAgentDisplayInfo, shortenPath } from "../helpers.js";
+function formatDuration(ms) {
+    if (ms == null || !Number.isFinite(ms))
+        return "n/a";
+    if (ms < 1_000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1_000;
+    if (seconds < 60)
+        return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
+    const minutes = seconds / 60;
+    return `${minutes.toFixed(minutes < 10 ? 1 : 0)}m`;
+}
+function formatTimestamp(value) {
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+        return value;
+    }
+    return new Date(parsed)
+        .toISOString()
+        .replace("T", " ")
+        .replace(".000", "")
+        .replace(/:\d\dZ$/, "Z");
+}
+function truncateText(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    return `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+function getAgentRole(agent) {
+    const capabilitiesRole = agent.metadata?.capabilities?.role;
+    const metadataRole = agent.metadata?.role;
+    return capabilitiesRole ?? metadataRole ?? "worker";
+}
+function buildWorkloadSummary(workload) {
+    const parts = [
+        `${workload.pendingInboxCount} inbox`,
+        `${workload.ownedThreadCount} thread${workload.ownedThreadCount === 1 ? "" : "s"}`,
+    ];
+    return parts.join(" / ");
+}
+function formatTaskStatusShort(assignment) {
+    switch (assignment.status) {
+        case "pr_open":
+            return `#${assignment.issueNumber} PR #${assignment.prNumber ?? "?"} open`;
+        case "pr_merged":
+            return `#${assignment.issueNumber} PR #${assignment.prNumber ?? "?"} merged`;
+        case "pr_closed":
+            return `#${assignment.issueNumber} PR #${assignment.prNumber ?? "?"} closed`;
+        case "branch_pushed":
+            return `#${assignment.issueNumber} pushed ${assignment.branch ?? "branch"}`;
+        case "assigned":
+        default:
+            return `#${assignment.issueNumber} assigned`;
+    }
+}
+function formatLaneStatusShort(lane) {
+    const refs = [
+        lane.issueNumber != null ? `#${lane.issueNumber}` : null,
+        lane.prNumber != null ? `PR #${lane.prNumber}` : null,
+        lane.pmMode ? "PM" : null,
+    ].filter((ref) => Boolean(ref));
+    const owner = lane.ownerAgentId ? ` owner ${lane.ownerAgentId}` : "";
+    const lead = lane.implementationLeadAgentId ? ` lead ${lane.implementationLeadAgentId}` : "";
+    return `${lane.laneId} [${lane.state}]${refs.length > 0 ? ` (${refs.join(" · ")})` : ""}${owner}${lead}${lane.summary ? ` — ${lane.summary}` : ""}`;
+}
+function summarizeAgentTasks(assignments) {
+    if (assignments.length === 0)
+        return "—";
+    const ordered = [...assignments].sort((left, right) => left.issueNumber - right.issueNumber);
+    const visible = ordered.slice(0, 2).map(formatTaskStatusShort);
+    if (ordered.length > 2) {
+        visible.push(`+${ordered.length - 2} more`);
+    }
+    return visible.join("; ");
+}
+function summarizeCycleAnomalies(anomalies) {
+    if (anomalies.length === 0)
+        return "healthy";
+    return truncateText(anomalies.join("; "), 72);
+}
+export function buildBrokerControlPlaneDashboardSnapshot(input) {
+    const homedir = input.homedir ?? process.env.HOME ?? "";
+    const visibleAssignments = input.assignments.filter((assignment) => assignment.issueState !== "CLOSED");
+    const assignmentsByAgent = new Map();
+    for (const assignment of visibleAssignments) {
+        const bucket = assignmentsByAgent.get(assignment.agentId);
+        const summaryAssignment = {
+            issueNumber: assignment.issueNumber,
+            status: assignment.status,
+            prNumber: assignment.prNumber,
+            branch: assignment.branch,
+        };
+        if (bucket) {
+            bucket.push(summaryAssignment);
+        }
+        else {
+            assignmentsByAgent.set(assignment.agentId, [summaryAssignment]);
+        }
+    }
+    const displays = input.workloads
+        .map((workload) => ({
+        workload,
+        display: buildAgentDisplayInfo(workload, input.evaluationOptions ?? {}),
+    }))
+        .sort((left, right) => {
+        const leftRole = getAgentRole(left.display);
+        const rightRole = getAgentRole(right.display);
+        if (leftRole !== rightRole) {
+            return leftRole === "broker" ? -1 : 1;
+        }
+        return left.display.name.localeCompare(right.display.name);
+    });
+    const brokerCount = displays.filter(({ display }) => getAgentRole(display) === "broker").length;
+    const workerDisplays = displays.filter(({ display }) => getAgentRole(display) !== "broker");
+    const liveAgents = displays.filter(({ workload }) => !workload.disconnectedAt).length;
+    const roster = displays.map(({ workload, display }) => {
+        const worktree = display.metadata?.worktreeKind === "linked" && display.metadata.worktreePath
+            ? shortenPath(display.metadata.worktreePath, homedir)
+            : display.metadata?.worktreeKind === "main"
+                ? "main checkout"
+                : "—";
+        const branch = display.metadata?.branch ?? "—";
+        const heartbeat = display.heartbeatSummary ?? display.leaseSummary ?? "unknown";
+        const health = display.stuck
+            ? `${display.health ?? "unknown"} / stuck`
+            : (display.health ?? "unknown");
+        return {
+            id: display.id,
+            role: getAgentRole(display),
+            label: `${display.emoji} ${display.name}`,
+            status: display.status,
+            health,
+            workload: buildWorkloadSummary(workload),
+            taskSummary: summarizeAgentTasks(assignmentsByAgent.get(display.id) ?? []),
+            heartbeat,
+            branch,
+            worktree,
+        };
+    });
+    const sortedAssignments = [...visibleAssignments].sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+    const sortedLanes = [...(input.lanes ?? [])].sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+    const activeTasks = sortedAssignments
+        .filter((assignment) => assignment.status === "assigned" ||
+        assignment.status === "branch_pushed" ||
+        assignment.status === "pr_open")
+        .map((assignment) => formatTaskStatusShort(assignment))
+        .slice(0, 8);
+    const recentOutcomes = sortedAssignments
+        .filter((assignment) => assignment.status === "pr_merged" || assignment.status === "pr_closed")
+        .map((assignment) => formatTaskStatusShort(assignment))
+        .slice(0, 8);
+    return {
+        cycleStartedAt: input.cycleStartedAt,
+        cycleDurationMs: input.cycleDurationMs,
+        currentBranch: input.currentBranch,
+        ralphSnooze: input.snooze
+            ? {
+                active: input.snooze.active,
+                until: input.snooze.until,
+                reason: input.snooze.reason,
+                source: input.snooze.source,
+                emptyCycleCount: input.snooze.emptyCycleCount,
+            }
+            : null,
+        totalAgents: displays.length,
+        liveAgents,
+        brokerCount,
+        workerCount: workerDisplays.length,
+        idleWorkers: workerDisplays.filter(({ display }) => display.status === "idle").length,
+        workingWorkers: workerDisplays.filter(({ display }) => display.status === "working").length,
+        ghostAgents: input.evaluation.ghostAgentIds.length,
+        stuckAgents: input.evaluation.stuckAgentIds.length,
+        pendingBacklogCount: input.maintenance?.pendingBacklogCount ?? 0,
+        nudgesThisCycle: input.evaluation.nudgeAgentIds.length,
+        idleDrainCandidates: input.evaluation.idleDrainAgentIds.length,
+        assignedBacklogCount: input.maintenance?.assignedBacklogCount ?? 0,
+        reapedAgents: input.maintenance?.reapedAgentIds.length ?? 0,
+        repairedThreadClaims: input.maintenance?.repairedThreadClaims ?? 0,
+        maintenanceAnomalies: input.maintenance?.anomalies ?? [],
+        anomalies: input.evaluation.anomalies,
+        taskCounts: {
+            assigned: visibleAssignments.filter((assignment) => assignment.status === "assigned").length,
+            branchPushed: visibleAssignments.filter((assignment) => assignment.status === "branch_pushed")
+                .length,
+            openPrs: visibleAssignments.filter((assignment) => assignment.status === "pr_open").length,
+            mergedPrs: visibleAssignments.filter((assignment) => assignment.status === "pr_merged")
+                .length,
+            closedPrs: visibleAssignments.filter((assignment) => assignment.status === "pr_closed")
+                .length,
+        },
+        activeTasks,
+        recentOutcomes,
+        activeLanes: sortedLanes
+            .filter((lane) => lane.state !== "done" && lane.state !== "cancelled" && lane.state !== "detached")
+            .map(formatLaneStatusShort)
+            .slice(0, 8),
+        detachedLanes: sortedLanes
+            .filter((lane) => lane.state === "detached")
+            .map(formatLaneStatusShort)
+            .slice(0, 8),
+        roster,
+        recentCycles: input.recentCycles.slice(0, 5).map((cycle) => ({
+            startedAt: formatTimestamp(cycle.startedAt),
+            duration: formatDuration(cycle.durationMs),
+            agentCount: cycle.agentCount,
+            backlogCount: cycle.backlogCount,
+            ghostCount: cycle.ghostAgentIds.length,
+            stuckCount: cycle.stuckAgentIds.length,
+            anomalySummary: summarizeCycleAnomalies(cycle.anomalies),
+            followUpDelivered: cycle.followUpDelivered,
+        })),
+    };
+}

package/dist/broker/ghost-reaper.d.ts

@@ -0,0 +1,49 @@
+import type { AgentInfo } from "./types.js";
+export type GhostReaperSignal = "SIGTERM" | "SIGKILL";
+export interface ProcessSnapshot {
+    pid: number;
+    command: string;
+    startedAt?: string | null;
+}
+export interface GhostReaperDeps {
+    inspectProcess?: (pid: number) => ProcessSnapshot | null;
+    signalProcess?: (pid: number, signal: GhostReaperSignal) => void;
+    setTimeout?: (callback: () => void, delayMs: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+    now?: () => number;
+    brokerAgentId?: () => string | null;
+    getAgentById?: (agentId: string) => AgentInfo | null;
+}
+export interface BrokerGhostReaperOptions {
+    killAfterMs?: number;
+}
+export type GhostReapDecision = {
+    eligible: true;
+    agentId: string;
+    pid: number;
+    command: string;
+} | {
+    eligible: false;
+    agentId: string;
+    pid?: number;
+    reason: string;
+};
+export interface GhostReapAttempt {
+    agentId: string;
+    pid?: number;
+    action: "sigterm" | "sigkill" | "skipped" | "pending" | "failed";
+    reason?: string;
+}
+export interface GhostReapResult {
+    attempts: GhostReapAttempt[];
+    signaledAgentIds: string[];
+    skippedAgentIds: string[];
+}
+export declare function isBrokerManagedAgent(agent: Pick<AgentInfo, "metadata">): boolean;
+export declare function inspectProcess(pid: number): ProcessSnapshot | null;
+export declare function decideGhostReapEligibility(agent: AgentInfo, snapshot: ProcessSnapshot | null, brokerAgentId?: string | null, now?: number): GhostReapDecision;
+export interface BrokerGhostReaper {
+    reapGhosts: (agents: AgentInfo[]) => GhostReapResult;
+    dispose: () => void;
+}
+export declare function createBrokerGhostReaper(deps?: GhostReaperDeps, options?: BrokerGhostReaperOptions): BrokerGhostReaper;

package/dist/broker/ghost-reaper.js

@@ -0,0 +1,209 @@
+import { execFileSync } from "node:child_process";
+const DEFAULT_KILL_AFTER_MS = 10_000;
+const PS_LSTART_MAX_FRACTION_MS = 999;
+const CLOCK_SKEW_TOLERANCE_MS = 1_000;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+export function isBrokerManagedAgent(agent) {
+    const metadata = asRecord(agent.metadata);
+    if (!metadata)
+        return false;
+    if (metadata.brokerManaged === true)
+        return true;
+    const managed = asRecord(metadata.pinetBrokerManaged);
+    return managed?.brokerManaged === true;
+}
+function getBrokerManagedBy(metadata) {
+    if (!metadata)
+        return null;
+    const direct = asString(metadata.brokerManagedBy);
+    if (direct)
+        return direct;
+    const managed = asRecord(metadata.pinetBrokerManaged);
+    return asString(managed?.brokerAgentId);
+}
+function commandLooksLikePiFollower(command) {
+    const lower = command.toLowerCase();
+    return lower.includes("pi-coding-agent") || /(^|[/\s])pi(\s|$)/.test(lower);
+}
+function parsePsSnapshot(pid, output) {
+    const line = output.trim();
+    if (!line)
+        return null;
+    const match = line.match(/^(\d+)\s+(\S+\s+\S+\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(.+)$/);
+    if (!match)
+        return null;
+    const parsedPid = Number(match[1]);
+    if (!Number.isFinite(parsedPid) || parsedPid !== pid)
+        return null;
+    return {
+        pid: parsedPid,
+        startedAt: match[2] ?? null,
+        command: match[3]?.trim() ?? "",
+    };
+}
+export function inspectProcess(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return null;
+    try {
+        const output = execFileSync("ps", ["-p", String(pid), "-o", "pid=", "-o", "lstart=", "-o", "command="], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return parsePsSnapshot(pid, output);
+    }
+    catch {
+        return null;
+    }
+}
+function defaultSignalProcess(pid, signal) {
+    process.kill(pid, signal);
+}
+function parseIso(value) {
+    if (!value)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? null : ms;
+}
+export function decideGhostReapEligibility(agent, snapshot, brokerAgentId, now = Date.now()) {
+    const metadata = asRecord(agent.metadata);
+    const pid = agent.pid;
+    if (!Number.isInteger(pid) || pid <= 1) {
+        return { eligible: false, agentId: agent.id, reason: "missing_or_unsafe_pid" };
+    }
+    if (pid === process.pid) {
+        return { eligible: false, agentId: agent.id, pid, reason: "refuse_current_process" };
+    }
+    if (agent.metadata?.role === "broker") {
+        return { eligible: false, agentId: agent.id, pid, reason: "broker_role" };
+    }
+    if (!isBrokerManagedAgent(agent)) {
+        return { eligible: false, agentId: agent.id, pid, reason: "not_broker_managed" };
+    }
+    const managedBy = getBrokerManagedBy(metadata);
+    if (!brokerAgentId) {
+        return { eligible: false, agentId: agent.id, pid, reason: "missing_broker_identity" };
+    }
+    if (!managedBy) {
+        return { eligible: false, agentId: agent.id, pid, reason: "missing_broker_managed_by" };
+    }
+    if (managedBy !== brokerAgentId) {
+        return { eligible: false, agentId: agent.id, pid, reason: "managed_by_different_broker" };
+    }
+    if (!agent.disconnectedAt) {
+        return { eligible: false, agentId: agent.id, pid, reason: "agent_not_disconnected" };
+    }
+    if (!snapshot) {
+        return { eligible: false, agentId: agent.id, pid, reason: "process_not_found" };
+    }
+    if (snapshot.pid !== pid) {
+        return { eligible: false, agentId: agent.id, pid, reason: "pid_mismatch" };
+    }
+    if (!commandLooksLikePiFollower(snapshot.command)) {
+        return { eligible: false, agentId: agent.id, pid, reason: "unexpected_command" };
+    }
+    const startedAtMs = parseIso(snapshot.startedAt);
+    if (startedAtMs == null) {
+        return { eligible: false, agentId: agent.id, pid, reason: "missing_process_start_time" };
+    }
+    const connectedAtMs = parseIso(agent.connectedAt);
+    if (connectedAtMs == null) {
+        return { eligible: false, agentId: agent.id, pid, reason: "missing_agent_connected_at" };
+    }
+    const disconnectedAtMs = parseIso(agent.disconnectedAt);
+    if (disconnectedAtMs == null) {
+        return { eligible: false, agentId: agent.id, pid, reason: "missing_agent_disconnected_at" };
+    }
+    if (startedAtMs + PS_LSTART_MAX_FRACTION_MS >= disconnectedAtMs) {
+        return { eligible: false, agentId: agent.id, pid, reason: "pid_reused_after_disconnect" };
+    }
+    if (startedAtMs + PS_LSTART_MAX_FRACTION_MS >= connectedAtMs) {
+        return { eligible: false, agentId: agent.id, pid, reason: "pid_reused_after_registration" };
+    }
+    if (disconnectedAtMs > now + CLOCK_SKEW_TOLERANCE_MS) {
+        return { eligible: false, agentId: agent.id, pid, reason: "disconnect_time_in_future" };
+    }
+    return { eligible: true, agentId: agent.id, pid, command: snapshot.command };
+}
+export function createBrokerGhostReaper(deps = {}, options = {}) {
+    const inspect = deps.inspectProcess ?? inspectProcess;
+    const signal = deps.signalProcess ?? defaultSignalProcess;
+    const schedule = deps.setTimeout ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+    const cancel = deps.clearTimeout ?? ((handle) => clearTimeout(handle));
+    const now = deps.now ?? (() => Date.now());
+    const killAfterMs = options.killAfterMs ?? DEFAULT_KILL_AFTER_MS;
+    const pendingKills = new Map();
+    function scheduleBoundedKill(agent, pid) {
+        if (pendingKills.has(pid))
+            return;
+        const handle = schedule(() => {
+            pendingKills.delete(pid);
+            const latestAgent = deps.getAgentById?.(agent.id) ?? agent;
+            if (!latestAgent || latestAgent.pid !== pid)
+                return;
+            const snapshot = inspect(pid);
+            const decision = decideGhostReapEligibility(latestAgent, snapshot, deps.brokerAgentId?.(), now());
+            if (!decision.eligible)
+                return;
+            try {
+                signal(pid, "SIGKILL");
+            }
+            catch {
+                // Best effort: maintenance should never crash while cleaning up ghosts.
+            }
+        }, killAfterMs);
+        pendingKills.set(pid, handle);
+    }
+    function reapGhosts(agents) {
+        const attempts = [];
+        const signaledAgentIds = [];
+        const skippedAgentIds = [];
+        for (const agent of agents) {
+            const pid = Number.isInteger(agent.pid) ? agent.pid : undefined;
+            if (pid != null && pendingKills.has(pid)) {
+                attempts.push({
+                    agentId: agent.id,
+                    pid,
+                    action: "pending",
+                    reason: "bounded_kill_pending",
+                });
+                continue;
+            }
+            const snapshot = pid != null ? inspect(pid) : null;
+            const decision = decideGhostReapEligibility(agent, snapshot, deps.brokerAgentId?.(), now());
+            if (!decision.eligible) {
+                skippedAgentIds.push(agent.id);
+                attempts.push({ agentId: agent.id, pid, action: "skipped", reason: decision.reason });
+                continue;
+            }
+            try {
+                signal(decision.pid, "SIGTERM");
+                signaledAgentIds.push(agent.id);
+                attempts.push({ agentId: agent.id, pid: decision.pid, action: "sigterm" });
+                scheduleBoundedKill(agent, decision.pid);
+            }
+            catch (error) {
+                attempts.push({
+                    agentId: agent.id,
+                    pid: decision.pid,
+                    action: "failed",
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return { attempts, signaledAgentIds, skippedAgentIds };
+    }
+    function dispose() {
+        for (const handle of pendingKills.values()) {
+            cancel(handle);
+        }
+        pendingKills.clear();
+    }
+    return { reapGhosts, dispose };
+}

package/dist/broker/index.d.ts

@@ -0,0 +1,36 @@
+import { BrokerDB } from "./schema.js";
+import { BrokerSocketServer } from "./socket-server.js";
+import type { ListenTarget } from "./socket-server.js";
+import { LeaderLock } from "./leader.js";
+import type { MessageAdapter } from "./types.js";
+export { BrokerDB } from "./schema.js";
+export { BrokerSocketServer } from "./socket-server.js";
+export { LeaderLock } from "./leader.js";
+export type { ListenTarget } from "./socket-server.js";
+export type { AgentMessageCallback, AgentRegistrationResolver } from "./socket-server.js";
+export type { AgentInfo, ThreadInfo, ScheduledWakeupInfo, ScheduledWakeupDelivery, BrokerMessage, InboxEntry, InboundMessage, OutboundMessage, AdapterCapabilityRequest, AdapterCapabilityResult, MessageAdapter, JsonRpcRequest, JsonRpcResponse, TaskAssignmentInfo, TaskAssignmentStatus, } from "./types.js";
+export interface BrokerOptions {
+    dbPath?: string;
+    /** Unix socket path (shorthand for { type: "unix", path }) */
+    socketPath?: string;
+    /** Full listen target — overrides socketPath when provided */
+    listenTarget?: ListenTarget;
+    lockPath?: string;
+    meshSecret?: string;
+    meshSecretPath?: string;
+}
+export interface Broker {
+    db: BrokerDB;
+    server: BrokerSocketServer;
+    lock: LeaderLock;
+    adapters: MessageAdapter[];
+    addAdapter(adapter: MessageAdapter): void;
+    stop(): Promise<void>;
+}
+/**
+ * Start the broker: acquire leader lock, initialize SQLite, start the Unix socket server.
+ * Only one broker may run at a time — enforced by a PID lock file.
+ *
+ * Throws if another broker process already holds the lock.
+ */
+export declare function startBroker(options?: BrokerOptions): Promise<Broker>;