@pinet/broker-core 0.2.0 → 0.2.2

package/dist/schema.d.ts

@@ -1,6 +1,6 @@
 import { DatabaseSync } from "node:sqlite";
 import type { PinetMailClass } from "./mail-classification.js";
-import type { AgentInfo, ThreadInfo, BrokerMessage, InboxEntry, InboxReadOptions, InboxReadResult, InboxThreadUnreadSummary, DeliveredInboundMessageResult, BacklogEntry, BrokerDBInterface, InboundMessage, ChannelAssignment, TaskAssignmentInfo, TaskAssignmentKind, TaskAssignmentStatus, ScheduledWakeupInfo, ScheduledWakeupDelivery, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./types.js";
+import type { AgentInfo, ThreadInfo, BrokerMessage, InboxEntry, InboxReadOptions, InboxReadResult, InboxThreadUnreadSummary, DeliveredInboundMessageResult, BacklogEntry, BrokerDBInterface, InboundMessage, ChannelAssignment, TaskAssignmentInfo, TaskAssignmentKind, TaskAssignmentStatus, ScheduledWakeupInfo, ScheduledWakeupDelivery, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, AgentSessionSearchInfo, AgentSessionSearchOptions, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./types.js";
 export interface TaskAssignmentAwaitingReplyInfo {
     id: number;
     agentId: string;
@@ -40,6 +40,8 @@ export declare class BrokerDB implements BrokerDBInterface {
     private rowToAgentWithCurrentSessionOutboundCount;
     getAgents(): AgentInfo[];
     getAllAgents(): AgentInfo[];
+    private getAgentRelatedThreadIds;
+    searchAgentSessions(options?: AgentSessionSearchOptions): AgentSessionSearchInfo[];
     getSetting<T = unknown>(key: string): T | null;
     setSetting(key: string, value: unknown): void;
     deleteSetting(key: string): void;

package/dist/schema.js

@@ -315,6 +315,101 @@ function getOptionalMetadataString(metadata, keys) {
     }
     return null;
 }
+function getOptionalNestedMetadataString(metadata, keys) {
+    const direct = getOptionalMetadataString(metadata ?? undefined, keys);
+    if (direct)
+        return direct;
+    const capabilities = metadata?.capabilities &&
+        typeof metadata.capabilities === "object" &&
+        !Array.isArray(metadata.capabilities)
+        ? metadata.capabilities
+        : undefined;
+    return getOptionalMetadataString(capabilities, keys);
+}
+function normalizeSessionSearchNeedle(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed.toLowerCase() : null;
+}
+function matchesSessionSearchNeedle(value, needle) {
+    if (!needle)
+        return true;
+    return Boolean(value?.toLowerCase().includes(needle));
+}
+function matchesSessionSearchPrefixOrExact(value, needle) {
+    if (!needle)
+        return true;
+    const normalized = value?.toLowerCase();
+    return Boolean(normalized && (normalized === needle || normalized.startsWith(needle)));
+}
+function parseSessionSearchTime(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+function normalizeSessionSearchLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 20;
+    return Math.max(1, Math.min(100, Math.floor(value)));
+}
+function agentSessionOverlapsRange(agent, sinceMs, untilMs) {
+    const connectedMs = Date.parse(agent.connectedAt);
+    const lastSeenMs = Date.parse(agent.lastSeen || agent.lastHeartbeat || agent.connectedAt);
+    const startMs = Number.isNaN(connectedMs) ? null : connectedMs;
+    const endMs = Number.isNaN(lastSeenMs) ? startMs : lastSeenMs;
+    if (sinceMs !== null && endMs !== null && endMs < sinceMs)
+        return false;
+    if (untilMs !== null && startMs !== null && startMs > untilMs)
+        return false;
+    return true;
+}
+function getAgentSessionMatchedBy(input) {
+    const matchedBy = [];
+    const agentName = normalizeSessionSearchNeedle(input.options.agentName);
+    const agentId = normalizeSessionSearchNeedle(input.options.agentId);
+    const threadId = normalizeSessionSearchNeedle(input.options.threadId);
+    const repo = normalizeSessionSearchNeedle(input.options.repo);
+    const worktreePath = normalizeSessionSearchNeedle(input.options.worktreePath);
+    const tmuxSession = normalizeSessionSearchNeedle(input.options.tmuxSession);
+    if (agentName && matchesSessionSearchNeedle(input.agent.name, agentName)) {
+        matchedBy.push("agent_name");
+    }
+    if (agentId && matchesSessionSearchPrefixOrExact(input.agent.id, agentId)) {
+        matchedBy.push("agent_id");
+    }
+    if (threadId &&
+        input.relatedThreadIds.some((candidate) => candidate.toLowerCase().includes(threadId))) {
+        matchedBy.push("thread_id");
+    }
+    const repoValues = [
+        getOptionalNestedMetadataString(input.metadata, ["repo"]),
+        getOptionalNestedMetadataString(input.metadata, ["repoRoot"]),
+        getOptionalNestedMetadataString(input.metadata, ["cwd"]),
+    ];
+    if (repo && repoValues.some((value) => matchesSessionSearchNeedle(value, repo))) {
+        matchedBy.push("repo");
+    }
+    const worktreeValues = [
+        getOptionalNestedMetadataString(input.metadata, ["worktreePath"]),
+        getOptionalNestedMetadataString(input.metadata, ["cwd"]),
+        getOptionalNestedMetadataString(input.metadata, ["repoRoot"]),
+    ];
+    if (worktreePath &&
+        worktreeValues.some((value) => matchesSessionSearchNeedle(value, worktreePath))) {
+        matchedBy.push("worktree_path");
+    }
+    const tmux = getOptionalNestedMetadataString(input.metadata, ["tmuxSession", "tmux"]);
+    if (tmuxSession && matchesSessionSearchNeedle(tmux, tmuxSession)) {
+        matchedBy.push("tmux_session");
+    }
+    if (input.options.since || input.options.until) {
+        matchedBy.push("time_range");
+    }
+    if (matchedBy.length === 0) {
+        matchedBy.push("recent");
+    }
+    return matchedBy;
+}
 function rowToPinetLaneParticipant(row) {
     return {
         laneId: row.lane_id,
@@ -1470,6 +1565,137 @@ export class BrokerDB {
             .all();
         return rows.map((row) => this.rowToAgentWithCurrentSessionOutboundCount(row));
     }
+    getAgentRelatedThreadIds(agentId, limit = 12) {
+        const db = this.getDb();
+        const rows = db
+            .prepare(`SELECT thread_id, MAX(activity_at) AS activity_at
+         FROM (
+           SELECT thread_id, updated_at AS activity_at
+             FROM threads
+            WHERE owner_agent = ? OR channel = ?
+           UNION ALL
+           SELECT thread_id, created_at AS activity_at
+             FROM messages
+            WHERE sender = ?
+           UNION ALL
+           SELECT m.thread_id, i.created_at AS activity_at
+             FROM inbox i
+             JOIN messages m ON m.id = i.message_id
+            WHERE i.agent_id = ?
+           UNION ALL
+           SELECT thread_id, updated_at AS activity_at
+             FROM threads
+            WHERE thread_id LIKE ? OR thread_id LIKE ?
+         ) related
+         GROUP BY thread_id
+         ORDER BY activity_at DESC
+         LIMIT ?`)
+            .all(agentId, `agent:${agentId}`, agentId, agentId, `a2a:${agentId}:%`, `a2a:%:${agentId}`, limit);
+        return rows.map((row) => row.thread_id);
+    }
+    searchAgentSessions(options = {}) {
+        const agentName = normalizeSessionSearchNeedle(options.agentName);
+        const agentId = normalizeSessionSearchNeedle(options.agentId);
+        const threadId = normalizeSessionSearchNeedle(options.threadId);
+        const repo = normalizeSessionSearchNeedle(options.repo);
+        const worktreePath = normalizeSessionSearchNeedle(options.worktreePath);
+        const tmuxSession = normalizeSessionSearchNeedle(options.tmuxSession);
+        const sinceMs = parseSessionSearchTime(options.since);
+        const untilMs = parseSessionSearchTime(options.until);
+        const limit = normalizeSessionSearchLimit(options.limit);
+        const results = this.getAllAgents()
+            .map((agent) => {
+            const metadata = agent.metadata ?? null;
+            const relatedThreadIds = this.getAgentRelatedThreadIds(agent.id);
+            const matchedBy = getAgentSessionMatchedBy({ agent, metadata, relatedThreadIds, options });
+            return {
+                agent,
+                metadata,
+                relatedThreadIds,
+                matchedBy,
+                lastSeenMs: Date.parse(agent.lastSeen || agent.lastHeartbeat || agent.connectedAt),
+            };
+        })
+            .filter(({ agent, metadata, relatedThreadIds }) => {
+            if (agentName && !matchesSessionSearchNeedle(agent.name, agentName))
+                return false;
+            if (agentId && !matchesSessionSearchPrefixOrExact(agent.id, agentId))
+                return false;
+            if (threadId &&
+                !relatedThreadIds.some((candidate) => candidate.toLowerCase().includes(threadId))) {
+                return false;
+            }
+            if (repo) {
+                const values = [
+                    getOptionalNestedMetadataString(metadata, ["repo"]),
+                    getOptionalNestedMetadataString(metadata, ["repoRoot"]),
+                    getOptionalNestedMetadataString(metadata, ["cwd"]),
+                ];
+                if (!values.some((value) => matchesSessionSearchNeedle(value, repo)))
+                    return false;
+            }
+            if (worktreePath) {
+                const values = [
+                    getOptionalNestedMetadataString(metadata, ["worktreePath"]),
+                    getOptionalNestedMetadataString(metadata, ["cwd"]),
+                    getOptionalNestedMetadataString(metadata, ["repoRoot"]),
+                ];
+                if (!values.some((value) => matchesSessionSearchNeedle(value, worktreePath))) {
+                    return false;
+                }
+            }
+            if (tmuxSession) {
+                const tmux = getOptionalNestedMetadataString(metadata, ["tmuxSession", "tmux"]);
+                if (!matchesSessionSearchNeedle(tmux, tmuxSession))
+                    return false;
+            }
+            return agentSessionOverlapsRange(agent, sinceMs, untilMs);
+        })
+            .sort((left, right) => {
+            const liveDelta = Number(Boolean(left.agent.disconnectedAt)) - Number(Boolean(right.agent.disconnectedAt));
+            if (liveDelta !== 0)
+                return liveDelta;
+            const leftSeen = Number.isNaN(left.lastSeenMs) ? 0 : left.lastSeenMs;
+            const rightSeen = Number.isNaN(right.lastSeenMs) ? 0 : right.lastSeenMs;
+            if (leftSeen !== rightSeen)
+                return rightSeen - leftSeen;
+            return left.agent.name.localeCompare(right.agent.name);
+        })
+            .slice(0, limit)
+            .map(({ agent, metadata, relatedThreadIds, matchedBy }) => ({
+            agentId: agent.id,
+            agentName: agent.name,
+            emoji: agent.emoji,
+            pid: agent.pid,
+            status: agent.status,
+            stableId: agent.stableId ?? null,
+            connectedAt: agent.connectedAt,
+            lastSeen: agent.lastSeen,
+            lastHeartbeat: agent.lastHeartbeat,
+            disconnectedAt: agent.disconnectedAt ?? null,
+            resumableUntil: agent.resumableUntil ?? null,
+            idleSince: agent.idleSince ?? null,
+            lastActivity: agent.lastActivity ?? null,
+            cwd: getOptionalNestedMetadataString(metadata, ["cwd"]),
+            repo: getOptionalNestedMetadataString(metadata, ["repo"]),
+            repoRoot: getOptionalNestedMetadataString(metadata, ["repoRoot"]),
+            worktreePath: getOptionalNestedMetadataString(metadata, ["worktreePath"]),
+            branch: getOptionalNestedMetadataString(metadata, ["branch"]),
+            tmuxSession: getOptionalNestedMetadataString(metadata, ["tmuxSession", "tmux"]),
+            brokerManaged: metadata?.brokerManaged === true,
+            brokerManagedBy: getOptionalNestedMetadataString(metadata, ["brokerManagedBy"]),
+            launchSource: getOptionalNestedMetadataString(metadata, ["launchSource"]),
+            parentAgentId: agent.parentAgentId ?? null,
+            rootAgentId: agent.rootAgentId ?? null,
+            treeDepth: agent.treeDepth ?? 0,
+            supervisionState: agent.supervisionState ?? "root",
+            subtreeRole: agent.subtreeRole ?? null,
+            laneId: agent.laneId ?? null,
+            relatedThreadIds,
+            matchedBy,
+        }));
+        return results;
+    }
     getSetting(key) {
         const db = this.getDb();
         const row = db.prepare("SELECT value FROM settings WHERE key = ?").get(key);

package/dist/types.d.ts

@@ -27,7 +27,61 @@ export interface AgentInfo {
     outboundCount?: number;
     pendingInboxCount?: number;
 }
-export type ClientAgentInfo = Omit<AgentInfo, "stableId">;
+export type AgentSessionKind = "session" | "leaf" | "cwd" | "broker" | "unknown";
+export interface AgentSessionSummary {
+    kind: AgentSessionKind;
+    /** Broker-safe, path-free stable session reference such as "session:1a2b3c4d5e6f". */
+    ref: string;
+    host?: string | null;
+    hasPath?: boolean;
+}
+export type ClientAgentInfo = Omit<AgentInfo, "stableId"> & {
+    /** Redacted session indicator. Raw stableId/session paths are intentionally not exposed here. */
+    session?: AgentSessionSummary | null;
+};
+export interface AgentSessionSearchOptions {
+    agentName?: string;
+    agentId?: string;
+    threadId?: string;
+    repo?: string;
+    worktreePath?: string;
+    tmuxSession?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+}
+export interface AgentSessionSearchInfo {
+    agentId: string;
+    agentName: string;
+    emoji: string;
+    pid: number;
+    status: "working" | "idle";
+    stableId: string | null;
+    connectedAt: string;
+    lastSeen: string;
+    lastHeartbeat: string;
+    disconnectedAt: string | null;
+    resumableUntil: string | null;
+    idleSince: string | null;
+    lastActivity: string | null;
+    cwd: string | null;
+    repo: string | null;
+    repoRoot: string | null;
+    worktreePath: string | null;
+    branch: string | null;
+    tmuxSession: string | null;
+    brokerManaged: boolean;
+    brokerManagedBy: string | null;
+    launchSource: string | null;
+    parentAgentId: string | null;
+    rootAgentId: string | null;
+    treeDepth: number;
+    supervisionState: AgentSupervisionState;
+    subtreeRole: string | null;
+    laneId: string | null;
+    relatedThreadIds: string[];
+    matchedBy: string[];
+}
 export interface ThreadInfo {
     threadId: string;
     source: string;
@@ -296,6 +350,7 @@ export interface BrokerDBInterface {
     getAgentById(agentId: string): AgentInfo | null;
     getAgentByStableId(stableId: string): AgentInfo | null;
     getAgents(): AgentInfo[];
+    searchAgentSessions?(options?: AgentSessionSearchOptions): AgentSessionSearchInfo[];
     getChannelAssignment(channel: string): ChannelAssignment | null;
     acquirePortLease?(input: PortLeaseAcquireInput): PortLeaseInfo;
     renewPortLease?(input: PortLeaseRenewInput): PortLeaseInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinet/broker-core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Transport-neutral broker kernel primitives for pi transports",
   "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
@@ -43,7 +43,7 @@
     "test": "vitest run *.test.ts"
   },
   "dependencies": {
-    "@pinet/transport-core": "0.2.0"
+    "@pinet/transport-core": "0.2.2"
   },
   "types": "./dist/index.d.ts"
 }