@pinet/broker-core 0.2.12 → 0.2.13

package/dist/message-send.d.ts

@@ -2,6 +2,7 @@ import type { TransportJsonObject, TransportRichBlock } from "@pinet/transport-c
 import type { BrokerMessage, MessageAdapter, NormalizedMessageContent, OutboundAttachmentFile, ThreadInfo } from "./types.js";
 export interface BrokerMessageSenderDb {
     getThread(threadId: string): ThreadInfo | null;
+    getDocumentRecipients?(documentId: string): string[];
     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;

package/dist/message-send.js

@@ -67,7 +67,14 @@ export async function sendBrokerMessage(deps, input) {
         ...(input.metadata ? { metadata: input.metadata } : {}),
     };
     await adapter.send(outbound);
-    const message = deps.db.insertMessage(threadId, source, "outbound", input.senderAgentId, messageBody, [], input.metadata);
+    const documentId = typeof thread.metadata?.documentId === "string" ? thread.metadata.documentId : null;
+    const documentRecipients = documentId
+        ? (deps.db.getDocumentRecipients?.(documentId) ?? []).filter((agentId) => agentId !== input.senderAgentId)
+        : [];
+    const message = deps.db.insertMessage(threadId, source, "outbound", input.senderAgentId, messageBody, [...new Set(documentRecipients)], {
+        ...(input.metadata ?? {}),
+        ...(documentId ? { documentId } : {}),
+    });
     return {
         thread,
         message,

package/dist/router.js

@@ -236,6 +236,27 @@ export class MessageRouter {
                 return { action: "deliver", agentId: explicitDirective.agent.id };
             }
         }
+        const messageDocumentId = typeof msg.metadata?.documentId === "string" ? msg.metadata.documentId : null;
+        const threadDocumentId = typeof thread?.metadata?.documentId === "string" ? thread.metadata.documentId : null;
+        const documentId = messageDocumentId ?? threadDocumentId;
+        if (documentId) {
+            const document = this.db.getDocument?.(documentId) ?? null;
+            if (thread?.ownerAgent &&
+                document &&
+                document.ownerAgent !== thread.ownerAgent &&
+                this.db.setDocumentOwner) {
+                this.db.setDocumentOwner(documentId, thread.ownerAgent);
+            }
+            const recipientIds = (this.db.getDocumentRecipients?.(documentId) ?? [])
+                .map((agentId) => resolveRoutableThreadOwner(this.db, agentId))
+                .filter((agent) => agent !== null)
+                .map((agent) => agent.id);
+            const recipients = [...new Set(recipientIds)];
+            if (recipients.length === 1)
+                return { action: "deliver", agentId: recipients[0] };
+            if (recipients.length > 1)
+                return { action: "broadcast", agentIds: recipients };
+        }
         if (thread) {
             if (thread.ownerBinding === "explicit") {
                 const explicitOwner = resolveRoutableThreadOwner(this.db, thread.ownerAgent);

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, AgentSessionSearchInfo, AgentSessionSearchOptions, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput, AgentHibernatePolicy, AgentLifecycleLease, AgentLifecycleOperation, AgentLifecycleTransitionInput, AgentLifecycleRetentionInfo, AgentRuntimeSpec, AgentRuntimeSpecInput, AgentCheckpointReceipt, AgentCheckpointReceiptInput, AgentWakeReservation, AgentWakeAcceptanceReceipt, AcceptRuntimeGenerationInput, RuntimeGenerationAcceptance, AgentWakeQueueEntry, EnqueueWakeInput, AgentLifecycleEvent, AgentLifecycleEventInput } from "./types.js";
+import type { AgentInfo, ThreadInfo, DocumentAliasInfo, DocumentInfo, 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, AgentHibernatePolicy, AgentLifecycleLease, AgentLifecycleOperation, AgentLifecycleTransitionInput, AgentLifecycleRetentionInfo, AgentRuntimeSpec, AgentRuntimeSpecInput, AgentCheckpointReceipt, AgentCheckpointReceiptInput, AgentWakeReservation, AgentWakeAcceptanceReceipt, AcceptRuntimeGenerationInput, RuntimeGenerationAcceptance, AgentWakeQueueEntry, EnqueueWakeInput, AgentLifecycleEvent, AgentLifecycleEventInput } from "./types.js";
 export interface TaskAssignmentAwaitingReplyInfo {
     id: number;
     agentId: string;
@@ -12,7 +12,7 @@ export interface TaskAssignmentAwaitingReplyInfo {
 export declare function defaultDbPath(): string;
 export declare const DEFAULT_RESUMABLE_WINDOW_MS = 15000;
 export declare const DEFAULT_DISCONNECTED_PURGE_GRACE_MS: number;
-export declare const CURRENT_BROKER_SCHEMA_VERSION = 24;
+export declare const CURRENT_BROKER_SCHEMA_VERSION = 25;
 export declare class BrokerDB implements BrokerDBInterface {
     private db;
     private readonly dbPath;
@@ -254,6 +254,15 @@ export declare class BrokerDB implements BrokerDBInterface {
         name: string;
     } | null;
     private getAgentRowByStableId;
+    getDocument(documentId: string): DocumentInfo | null;
+    getDocumentByAlias(source: string, externalId: string): DocumentInfo | null;
+    upsertDocument(document: Omit<DocumentInfo, "createdAt" | "updatedAt">): DocumentInfo;
+    bindDocumentAlias(source: string, externalId: string, documentId: string, metadata?: DocumentInfo["metadata"]): DocumentAliasInfo;
+    setDocumentOwner(documentId: string, ownerAgent: string | null): DocumentInfo;
+    subscribeDocument(documentId: string, agentId: string): void;
+    unsubscribeDocument(documentId: string, agentId: string): void;
+    listDocumentSubscribers(documentId: string): string[];
+    getDocumentRecipients(documentId: string): string[];
     createThread(thread: ThreadInfo): ThreadInfo;
     createThread(threadId: string, source: string, channel: string, ownerAgent: string | null): ThreadInfo;
     updateThread(threadId: string, updates: Partial<ThreadInfo>): void;
@@ -303,6 +312,7 @@ export declare class BrokerDB implements BrokerDBInterface {
         releasedAgentIds: string[];
     };
     queueMessage(agentId: string, message: InboundMessage): void;
+    queueMessageToAgents(agentIds: string[], message: InboundMessage): void;
     queueDeliveredMessage(agentId: string, message: InboundMessage): DeliveredInboundMessageResult;
     private buildInboundMessageMetadata;
     private withInboundMailClassMetadata;

package/dist/schema.js

@@ -65,6 +65,21 @@ function rowToThread(row) {
         updatedAt: row.updated_at,
     };
 }
+function rowToDocument(row) {
+    const kind = row.kind === "slack_thread" || row.kind === "slack_channel" ? row.kind : "git_file";
+    return {
+        documentId: row.document_id,
+        kind,
+        title: row.title,
+        ownerAgent: row.owner_agent,
+        ownerBinding: row.owner_binding === "explicit" ? "explicit" : null,
+        metadata: row.metadata
+            ? JSON.parse(row.metadata)
+            : null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
 function rowToPortLease(row) {
     return {
         id: row.id,
@@ -602,7 +617,7 @@ export function defaultDbPath() {
 }
 export const DEFAULT_RESUMABLE_WINDOW_MS = 15_000;
 export const DEFAULT_DISCONNECTED_PURGE_GRACE_MS = 60 * 60_000;
-export const CURRENT_BROKER_SCHEMA_VERSION = 24;
+export const CURRENT_BROKER_SCHEMA_VERSION = 25;
 /**
  * Lifecycle states whose durable identity, inbox, thread ownership, and runtime
  * mapping MUST survive routine maintenance. A hibernation identity is
@@ -1443,6 +1458,41 @@ function widenRuntimeSpecPayload(db) {
     DROP TABLE agent_runtime_specs_v23;
   `);
 }
+// agent-standards-ignore prefer-inline-single-use-helper: one-function-per-migration-case is the established schema-migration seam.
+function createDocumentTables(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS documents (
+      document_id TEXT PRIMARY KEY NOT NULL,
+      kind TEXT NOT NULL CHECK(kind IN ('git_file','slack_thread','slack_channel')),
+      title TEXT NOT NULL,
+      owner_agent TEXT,
+      owner_binding TEXT,
+      metadata TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS document_aliases (
+      source TEXT NOT NULL,
+      external_id TEXT NOT NULL,
+      document_id TEXT NOT NULL,
+      metadata TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY(source, external_id),
+      FOREIGN KEY(document_id) REFERENCES documents(document_id) ON DELETE CASCADE
+    );
+    CREATE TABLE IF NOT EXISTS document_subscriptions (
+      document_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY(document_id, agent_id),
+      FOREIGN KEY(document_id) REFERENCES documents(document_id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_document_subscriptions_agent
+      ON document_subscriptions(agent_id, document_id);
+  `);
+}
 function runSchemaMigrations(db) {
     const currentVersion = getUserVersion(db);
     if (currentVersion >= CURRENT_BROKER_SCHEMA_VERSION) {
@@ -1524,6 +1574,9 @@ function runSchemaMigrations(db) {
                 case 24:
                     widenRuntimeSpecPayload(db);
                     break;
+                case 25:
+                    createDocumentTables(db);
+                    break;
                 default:
                     throw new Error(`Unsupported broker schema migration target: ${nextVersion}`);
             }
@@ -3298,6 +3351,93 @@ export class BrokerDB {
         const row = db.prepare("SELECT * FROM agents WHERE stable_id = ?").get(stableId);
         return row ?? null;
     }
+    // ─── Documents ───────────────────────────────────────
+    getDocument(documentId) {
+        const row = this.getDb()
+            .prepare("SELECT * FROM documents WHERE document_id = ?")
+            .get(documentId);
+        return row ? rowToDocument(row) : null;
+    }
+    getDocumentByAlias(source, externalId) {
+        const row = this.getDb()
+            .prepare(`SELECT d.* FROM documents d
+         JOIN document_aliases a ON a.document_id = d.document_id
+         WHERE a.source = ? AND a.external_id = ?`)
+            .get(source, externalId);
+        return row ? rowToDocument(row) : null;
+    }
+    upsertDocument(document) {
+        const db = this.getDb();
+        const now = new Date().toISOString();
+        db.prepare(`INSERT INTO documents
+       (document_id, kind, title, owner_agent, owner_binding, metadata, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(document_id) DO UPDATE SET
+         kind = excluded.kind,
+         title = excluded.title,
+         metadata = excluded.metadata,
+         updated_at = excluded.updated_at`).run(document.documentId, document.kind, document.title, document.ownerAgent, document.ownerBinding, document.metadata ? JSON.stringify(document.metadata) : null, now, now);
+        return this.getDocument(document.documentId);
+    }
+    bindDocumentAlias(source, externalId, documentId, metadata = null) {
+        const db = this.getDb();
+        const now = new Date().toISOString();
+        db.prepare(`INSERT INTO document_aliases
+       (source, external_id, document_id, metadata, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(source, external_id) DO UPDATE SET
+         document_id = excluded.document_id,
+         metadata = excluded.metadata,
+         updated_at = excluded.updated_at`).run(source, externalId, documentId, metadata ? JSON.stringify(metadata) : null, now, now);
+        return {
+            source,
+            externalId,
+            documentId,
+            metadata,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    setDocumentOwner(documentId, ownerAgent) {
+        const db = this.getDb();
+        const result = db
+            .prepare(`UPDATE documents SET owner_agent = ?, owner_binding = 'explicit', updated_at = ?
+         WHERE document_id = ?`)
+            .run(ownerAgent, new Date().toISOString(), documentId);
+        if (Number(result.changes ?? 0) === 0)
+            throw new Error(`Unknown document ${documentId}`);
+        return this.getDocument(documentId);
+    }
+    subscribeDocument(documentId, agentId) {
+        const now = new Date().toISOString();
+        this.getDb()
+            .prepare(`INSERT INTO document_subscriptions (document_id, agent_id, created_at, updated_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(document_id, agent_id) DO UPDATE SET updated_at = excluded.updated_at`)
+            .run(documentId, agentId, now, now);
+    }
+    unsubscribeDocument(documentId, agentId) {
+        this.getDb()
+            .prepare("DELETE FROM document_subscriptions WHERE document_id = ? AND agent_id = ?")
+            .run(documentId, agentId);
+    }
+    listDocumentSubscribers(documentId) {
+        const rows = this.getDb()
+            .prepare("SELECT agent_id FROM document_subscriptions WHERE document_id = ? ORDER BY agent_id")
+            .all(documentId);
+        return rows.map((row) => row.agent_id);
+    }
+    getDocumentRecipients(documentId) {
+        const document = this.getDocument(documentId);
+        if (!document)
+            return [];
+        return [
+            ...new Set([
+                ...(document.ownerAgent ? [document.ownerAgent] : []),
+                ...this.listDocumentSubscribers(documentId),
+            ]),
+        ];
+    }
     createThread(threadOrId, source, channel, ownerAgent) {
         const db = this.getDb();
         const now = new Date().toISOString();
@@ -4067,6 +4207,15 @@ export class BrokerDB {
             this.reclassifyReferencedMessageFromReaction(message);
         });
     }
+    queueMessageToAgents(agentIds, message) {
+        const recipients = [...new Set(agentIds.filter((agentId) => agentId.length > 0))];
+        if (recipients.length === 0)
+            return;
+        this.withTransaction(() => {
+            this.insertMessage(message.threadId, message.source, "inbound", message.userId, message.text, recipients, this.buildInboundMessageMetadata(message));
+            this.reclassifyReferencedMessageFromReaction(message);
+        });
+    }
     queueDeliveredMessage(agentId, message) {
         return this.withTransaction(() => {
             const db = this.getDb();

package/dist/types.d.ts

@@ -372,6 +372,24 @@ export interface ThreadInfo {
     createdAt: string;
     updatedAt: string;
 }
+export interface DocumentInfo {
+    documentId: string;
+    kind: "git_file" | "slack_thread" | "slack_channel";
+    title: string;
+    ownerAgent: string | null;
+    ownerBinding: "explicit" | null;
+    metadata: ThreadInfo["metadata"];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface DocumentAliasInfo {
+    source: string;
+    externalId: string;
+    documentId: string;
+    metadata: ThreadInfo["metadata"];
+    createdAt: string;
+    updatedAt: string;
+}
 export interface BrokerMessage {
     id: number;
     threadId: string;
@@ -633,6 +651,15 @@ export declare const buildCompatibilityInstanceScope: typeof _buildCompatibility
 export declare const buildRuntimeScopeCarrier: typeof _buildRuntimeScopeCarrier;
 export interface BrokerDBInterface {
     getThread(threadId: string): ThreadInfo | null;
+    getDocument?(documentId: string): DocumentInfo | null;
+    getDocumentByAlias?(source: string, externalId: string): DocumentInfo | null;
+    upsertDocument?(document: Omit<DocumentInfo, "createdAt" | "updatedAt">): DocumentInfo;
+    bindDocumentAlias?(source: string, externalId: string, documentId: string, metadata?: ThreadInfo["metadata"]): DocumentAliasInfo;
+    setDocumentOwner?(documentId: string, ownerAgent: string | null): DocumentInfo;
+    subscribeDocument?(documentId: string, agentId: string): void;
+    unsubscribeDocument?(documentId: string, agentId: string): void;
+    listDocumentSubscribers?(documentId: string): string[];
+    getDocumentRecipients?(documentId: string): string[];
     getAgentById(agentId: string): AgentInfo | null;
     getAgentByStableId(stableId: string): AgentInfo | null;
     getAgents(): AgentInfo[];
@@ -660,5 +687,6 @@ export interface BrokerDBInterface {
      */
     claimThread(threadId: string, agentId: string, source?: string, channel?: string): boolean;
     queueMessage(agentId: string, message: InboundMessage): void;
+    queueMessageToAgents?(agentIds: string[], message: InboundMessage): void;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinet/broker-core",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "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 --config ../vitest.config.ts *.test.ts"
   },
   "dependencies": {
-    "@pinet/transport-core": "0.2.12"
+    "@pinet/transport-core": "0.2.13"
   },
   "types": "./dist/index.d.ts"
 }