@xopcai/xopc 0.0.188 → 0.0.190

package/dist/src/realtime/runtime.js

@@ -0,0 +1,263 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { REALTIME_HEARTBEAT_INTERVAL_MS, REALTIME_HEARTBEAT_TIMEOUT_MS, REALTIME_HELLO_TIMEOUT_MS, REALTIME_MAX_CLIENT_FRAME_BYTES, parseClientRealtimeJsonFrame, parseClientRealtimeMessage } from "../../packages/realtime-protocol/src/index.js";
+import { createPreauthConnectionBudget } from "../gateway/security/preauth-connection-budget.js";
+import { RealtimeBroker } from "./broker.js";
+import { RealtimeTicketStore } from "./tickets.js";
+import { RealtimeSocketWriter } from "./writer.js";
+import { createRequire } from "node:module";
+import crypto from "node:crypto";
+//#region src/realtime/runtime.ts
+init_logger();
+const log = createLogger("Realtime");
+const { WebSocketServer } = createRequire(import.meta.url)("ws");
+const REALTIME_WS_PATH = "/api/realtime/v1/ws";
+const MAX_MESSAGE_CLOCK_SKEW_MS = 6e4;
+const MAX_SUBSCRIPTIONS = 100;
+const MAX_CONNECTIONS = 100;
+function serverMessage(kind, payload) {
+	return {
+		protocolVersion: 1,
+		messageId: crypto.randomUUID(),
+		kind,
+		sentAt: Date.now(),
+		payload
+	};
+}
+function isAuthorizedTopic(topic) {
+	return topic === "gateway" || topic === "sessions" || topic === "logs" || topic.startsWith("session:") && topic.length > 8 || topic.startsWith("run:") && topic.length > 4 || topic.startsWith("workflow:") && topic.length > 9;
+}
+var RealtimeRuntime = class {
+	broker = new RealtimeBroker(void 0, (error, topic) => {
+		log.warn({
+			err: error,
+			topic
+		}, "Realtime subscriber failed");
+	});
+	tickets = new RealtimeTicketStore();
+	preauthBudget = createPreauthConnectionBudget();
+	wss = new WebSocketServer({
+		noServer: true,
+		maxPayload: REALTIME_MAX_CLIENT_FRAME_BYTES,
+		perMessageDeflate: false
+	});
+	topicCleanupTimers = /* @__PURE__ */ new Map();
+	closed = false;
+	constructor(endpointTools) {
+		this.endpointTools = endpointTools;
+		this.wss.on("connection", (socket, request) => this.handleConnection(socket, request));
+		this.wss.on("error", (err) => log.error({ err }, "Realtime WebSocket server failed"));
+	}
+	handleUpgrade(req, socket, head) {
+		if (new URL(req.url ?? "/", "http://gateway.local").pathname !== REALTIME_WS_PATH) return false;
+		if (this.closed) {
+			socket.destroy();
+			return true;
+		}
+		if (this.wss.clients.size >= MAX_CONNECTIONS) {
+			socket.destroy();
+			return true;
+		}
+		const clientIp = req.socket.remoteAddress;
+		if (!this.preauthBudget.acquire(clientIp)) {
+			socket.destroy();
+			return true;
+		}
+		try {
+			this.wss.handleUpgrade(req, socket, head, (ws) => {
+				this.wss.emit("connection", ws, req);
+			});
+		} catch (error) {
+			this.preauthBudget.release(clientIp);
+			throw error;
+		}
+		return true;
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		for (const client of this.wss.clients) client.close(1001, "Gateway stopping");
+		for (const timer of this.topicCleanupTimers.values()) clearTimeout(timer);
+		this.topicCleanupTimers.clear();
+		this.wss.close();
+	}
+	completeTopic(topic, ttlMs = 5 * 6e4) {
+		const existing = this.topicCleanupTimers.get(topic);
+		if (existing) clearTimeout(existing);
+		this.topicCleanupTimers.set(topic, setTimeout(() => {
+			this.topicCleanupTimers.delete(topic);
+			this.broker.removeTopic(topic);
+		}, ttlMs));
+	}
+	handleConnection(socket, request) {
+		const clientIp = request.socket.remoteAddress;
+		const writer = new RealtimeSocketWriter(socket);
+		const subscriptions = /* @__PURE__ */ new Map();
+		let authenticated = false;
+		let lastSeenAt = Date.now();
+		let connectionId;
+		let endpointId;
+		let budgetHeld = true;
+		const releaseBudget = () => {
+			if (!budgetHeld) return;
+			budgetHeld = false;
+			this.preauthBudget.release(clientIp);
+		};
+		const helloTimer = setTimeout(() => socket.close(4401, "Realtime hello timeout"), REALTIME_HELLO_TIMEOUT_MS);
+		const heartbeatTimer = setInterval(() => {
+			if (Date.now() - lastSeenAt > 45e3) socket.close(4408, "Realtime heartbeat timeout");
+		}, REALTIME_HEARTBEAT_INTERVAL_MS);
+		const sendError = (code, message) => {
+			writer.enqueue(serverMessage("realtime.error", {
+				code,
+				message
+			}), "critical");
+		};
+		const subscribe = (requested) => {
+			const authorized = requested.filter((item) => {
+				if (isAuthorizedTopic(item.topic)) return true;
+				sendError("FORBIDDEN_TOPIC", `Topic is not available: ${item.topic}`);
+				return false;
+			});
+			if (new Set([...subscriptions.keys(), ...authorized.map((item) => item.topic)]).size > MAX_SUBSCRIPTIONS) {
+				sendError("TOO_MANY_SUBSCRIPTIONS", `At most ${MAX_SUBSCRIPTIONS} topics may be subscribed`);
+				return false;
+			}
+			for (const item of authorized) {
+				if (item.topic.startsWith("run:") && item.afterSeq !== void 0 && !this.broker.hasTopic(item.topic)) {
+					writer.enqueue(serverMessage("realtime.gap", {
+						topic: item.topic,
+						requestedSeq: item.afterSeq,
+						earliestSeq: 1,
+						recoverable: false
+					}));
+					continue;
+				}
+				subscriptions.get(item.topic)?.unsubscribe();
+				const handle = this.broker.subscribe(item.topic, item.afterSeq, (event) => {
+					writer.enqueue(event);
+				});
+				subscriptions.set(item.topic, handle);
+				writer.enqueue(serverMessage("realtime.subscribed", {
+					topic: item.topic,
+					cursor: handle.cursor
+				}), "critical");
+				for (const message of handle.initial) writer.enqueue(message);
+			}
+			return true;
+		};
+		socket.on("message", (data, isBinary) => {
+			if (isBinary) {
+				socket.close(4400, "Binary realtime frames are not supported");
+				return;
+			}
+			let message;
+			try {
+				message = parseClientRealtimeMessage(parseClientRealtimeJsonFrame(this.rawDataToText(data)));
+				if (Math.abs(Date.now() - message.sentAt) > MAX_MESSAGE_CLOCK_SKEW_MS) throw new Error("Realtime message timestamp is outside the allowed window");
+			} catch (error) {
+				log.warn({ err: error }, "Realtime client sent an invalid frame");
+				socket.close(4400, "Invalid realtime protocol frame");
+				return;
+			}
+			lastSeenAt = Date.now();
+			if (!authenticated) {
+				if (message.kind !== "realtime.hello") {
+					socket.close(4401, "First realtime message must be hello");
+					return;
+				}
+				const claim = this.tickets.consume(message.payload.ticket, message.payload.clientId, message.payload.clientKind);
+				if (!claim) {
+					socket.close(4401, "Realtime authentication failed");
+					return;
+				}
+				authenticated = true;
+				connectionId = crypto.randomUUID();
+				let endpointReady;
+				if (message.payload.endpoint) {
+					if (!this.endpointTools || message.payload.endpoint.kind !== message.payload.clientKind) {
+						socket.close(4401, "Realtime endpoint identity is invalid");
+						return;
+					}
+					const transport = {
+						get readyState() {
+							return socket.readyState;
+						},
+						send: (data) => {
+							writer.enqueue(serverMessage("endpoint.message", JSON.parse(data)), "critical");
+						},
+						close: (code, reason) => socket.close(code, reason)
+					};
+					try {
+						const registration = this.endpointTools.connect(message.payload.endpoint, connectionId, transport);
+						endpointId = message.payload.endpoint.endpointId;
+						endpointReady = {
+							endpointId,
+							turnToken: registration.turnToken
+						};
+					} catch (error) {
+						log.warn({
+							err: error,
+							principalId: message.payload.endpoint.principalId
+						}, "Realtime endpoint authentication failed");
+						socket.close(4401, "Realtime endpoint authentication failed");
+						return;
+					}
+				}
+				clearTimeout(helloTimer);
+				releaseBudget();
+				writer.enqueue(serverMessage("realtime.ready", {
+					connectionId,
+					heartbeatIntervalMs: REALTIME_HEARTBEAT_INTERVAL_MS,
+					heartbeatTimeoutMs: REALTIME_HEARTBEAT_TIMEOUT_MS,
+					...endpointReady ? { endpoint: endpointReady } : {}
+				}), "critical");
+				subscribe(message.payload.subscriptions);
+				log.info({
+					connectionId,
+					clientId: claim.clientId,
+					clientKind: claim.clientKind
+				}, "Realtime client connected");
+				return;
+			}
+			if (message.kind === "realtime.hello") socket.close(4400, "Realtime hello may only be sent once");
+			else if (message.kind === "realtime.subscribe") subscribe(message.payload.subscriptions);
+			else if (message.kind === "realtime.unsubscribe") for (const topic of message.payload.topics) {
+				subscriptions.get(topic)?.unsubscribe();
+				subscriptions.delete(topic);
+			}
+			else if (message.kind === "realtime.ping") {
+				if (endpointId && connectionId) this.endpointTools?.touch(endpointId, connectionId);
+				writer.enqueue(serverMessage("realtime.pong", {}), "critical");
+			} else if (!endpointId || !connectionId || !this.endpointTools) sendError("ENDPOINT_NOT_REGISTERED", "Endpoint messages require an endpoint identity");
+			else try {
+				this.endpointTools.handleMessage(endpointId, connectionId, message.payload);
+			} catch (error) {
+				log.warn({
+					err: error,
+					endpointId,
+					connectionId
+				}, "Realtime endpoint message failed");
+				socket.close(4400, "Invalid endpoint message");
+			}
+		});
+		socket.on("close", () => {
+			clearTimeout(helloTimer);
+			clearInterval(heartbeatTimer);
+			releaseBudget();
+			writer.close();
+			for (const handle of subscriptions.values()) handle.unsubscribe();
+			subscriptions.clear();
+			if (endpointId && connectionId) this.endpointTools?.remove(endpointId, connectionId);
+			if (connectionId) log.info({ connectionId }, "Realtime client disconnected");
+		});
+	}
+	rawDataToText(data) {
+		if (typeof data === "string") return data;
+		if (Array.isArray(data)) return Buffer.concat(data).toString("utf8");
+		if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
+		return data.toString("utf8");
+	}
+};
+//#endregion
+export { RealtimeRuntime };

package/dist/src/realtime/tickets.d.ts

@@ -0,0 +1,15 @@
+import type { RealtimeClientKind } from '@xopcai/realtime-protocol';
+export interface RealtimeTicketClaim {
+    clientId: string;
+    clientKind: RealtimeClientKind;
+    expiresAt: number;
+}
+export interface IssuedRealtimeTicket extends RealtimeTicketClaim {
+    ticket: string;
+}
+export declare class RealtimeTicketStore {
+    private readonly claims;
+    issue(clientId: string, clientKind: RealtimeClientKind, now?: number): IssuedRealtimeTicket;
+    consume(ticket: string, clientId: string, clientKind: RealtimeClientKind, now?: number): RealtimeTicketClaim | undefined;
+    private prune;
+}

package/dist/src/realtime/tickets.js

@@ -0,0 +1,38 @@
+import crypto from "node:crypto";
+//#region src/realtime/tickets.ts
+const TICKET_TTL_MS = 3e4;
+const MAX_OUTSTANDING_TICKETS = 1e3;
+function ticketKey(ticket) {
+	return crypto.createHash("sha256").update(ticket).digest("hex");
+}
+var RealtimeTicketStore = class {
+	claims = /* @__PURE__ */ new Map();
+	issue(clientId, clientKind, now = Date.now()) {
+		this.prune(now);
+		if (this.claims.size >= MAX_OUTSTANDING_TICKETS) throw new Error("Too many outstanding realtime tickets");
+		const ticket = crypto.randomBytes(32).toString("base64url");
+		const claim = {
+			clientId,
+			clientKind,
+			expiresAt: now + TICKET_TTL_MS
+		};
+		this.claims.set(ticketKey(ticket), claim);
+		return {
+			ticket,
+			...claim
+		};
+	}
+	consume(ticket, clientId, clientKind, now = Date.now()) {
+		const key = ticketKey(ticket);
+		const claim = this.claims.get(key);
+		this.claims.delete(key);
+		if (!claim || claim.expiresAt < now) return void 0;
+		if (claim.clientId !== clientId || claim.clientKind !== clientKind) return void 0;
+		return claim;
+	}
+	prune(now) {
+		for (const [key, claim] of this.claims) if (claim.expiresAt < now) this.claims.delete(key);
+	}
+};
+//#endregion
+export { RealtimeTicketStore };

package/dist/src/realtime/writer.d.ts

@@ -0,0 +1,15 @@
+import type { ServerRealtimeMessage } from '@xopcai/realtime-protocol';
+import type { WebSocket } from 'ws';
+export declare class RealtimeSocketWriter {
+    private readonly socket;
+    private readonly critical;
+    private readonly normal;
+    private queuedBytes;
+    private sending;
+    private closed;
+    private retryTimer?;
+    constructor(socket: WebSocket);
+    enqueue(message: ServerRealtimeMessage, priority?: 'critical' | 'normal'): boolean;
+    close(): void;
+    private flush;
+}

package/dist/src/realtime/writer.js

@@ -0,0 +1,78 @@
+//#region src/realtime/writer.ts
+const SOFT_BUFFERED_BYTES = 512 * 1024;
+const HARD_BUFFERED_BYTES = 4 * 1024 * 1024;
+const MAX_QUEUED_BYTES = 2 * 1024 * 1024;
+var RealtimeSocketWriter = class {
+	critical = [];
+	normal = [];
+	queuedBytes = 0;
+	sending = false;
+	closed = false;
+	retryTimer;
+	constructor(socket) {
+		this.socket = socket;
+	}
+	enqueue(message, priority = "normal") {
+		if (this.closed || this.socket.readyState !== 1) return false;
+		let data;
+		try {
+			data = JSON.stringify(message);
+		} catch {
+			this.socket.close(1011, "Realtime message serialization failed");
+			this.close();
+			return false;
+		}
+		const item = {
+			data,
+			bytes: Buffer.byteLength(data)
+		};
+		if (this.queuedBytes + item.bytes > MAX_QUEUED_BYTES) {
+			this.socket.close(4413, "Realtime client is too slow");
+			this.close();
+			return false;
+		}
+		this.queuedBytes += item.bytes;
+		(priority === "critical" ? this.critical : this.normal).push(item);
+		this.flush();
+		return true;
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		if (this.retryTimer) clearTimeout(this.retryTimer);
+		this.retryTimer = void 0;
+		this.critical.length = 0;
+		this.normal.length = 0;
+		this.queuedBytes = 0;
+	}
+	flush() {
+		if (this.closed || this.sending || this.socket.readyState !== 1) return;
+		if (this.socket.bufferedAmount > HARD_BUFFERED_BYTES) {
+			this.socket.close(4413, "Realtime client is too slow");
+			this.close();
+			return;
+		}
+		if (this.socket.bufferedAmount > SOFT_BUFFERED_BYTES) {
+			if (!this.retryTimer) this.retryTimer = setTimeout(() => {
+				this.retryTimer = void 0;
+				this.flush();
+			}, 10);
+			return;
+		}
+		const item = this.critical.shift() ?? this.normal.shift();
+		if (!item) return;
+		this.sending = true;
+		this.socket.send(item.data, (error) => {
+			this.sending = false;
+			this.queuedBytes -= item.bytes;
+			if (error) {
+				this.socket.close(1011, "Realtime delivery failed");
+				this.close();
+				return;
+			}
+			this.flush();
+		});
+	}
+};
+//#endregion
+export { RealtimeSocketWriter };

package/dist/src/share/share-config.js

@@ -85,7 +85,6 @@ function mergeShareConfigPatch(config, patch) {
 			intervalMs: 18e5,
 			includeSystemPromptSection: false
 		},
-		maxSseConnections: 100,
 		corsOrigins: []
 	};
 	const current = resolveShareConfig(config.gateway.share);

package/dist/src/share/site-share-config.js

@@ -73,7 +73,6 @@ function mergeSiteShareConfigPatch(config, patch) {
 			intervalMs: 18e5,
 			includeSystemPromptSection: false
 		},
-		maxSseConnections: 100,
 		corsOrigins: []
 	};
 	const cfg = config.gateway;

package/dist/src/storage/sqlite/connector-account-repository.js

@@ -36,7 +36,6 @@ function mergeAccountSourceData(db, connectorId, sourceAccountId, targetAccountI
 	db.prepare("UPDATE knowledge_source_items SET source_instance_id = ? WHERE source_instance_id = ?").run(targetId, sourceId);
 	db.prepare("UPDATE knowledge_sync_runs SET source_instance_id = ? WHERE source_instance_id = ?").run(targetId, sourceId);
 	db.prepare("UPDATE knowledge_source_changes SET source_instance_id = ? WHERE source_instance_id = ?").run(targetId, sourceId);
-	db.prepare("UPDATE user_claim_evidence SET source_instance_id = ? WHERE source_instance_id = ?").run(targetId, sourceId);
 	db.prepare(`
     DELETE FROM knowledge_collection_state AS source
     WHERE source.source_instance_id = ?

package/dist/src/storage/sqlite/context-consolidation-repository.d.ts

@@ -0,0 +1,37 @@
+export type ContextConsolidationRun = {
+    runId: string;
+    triggerKind: 'schedule' | 'manual';
+    status: 'running' | 'completed' | 'failed';
+    reason?: string;
+    metrics: Record<string, unknown>;
+    startedAt: number;
+    completedAt?: number;
+};
+export type ContextConsolidationDecision = {
+    id: string;
+    runId: string;
+    understandingId?: string;
+    action: 'needs_review' | 'stale';
+    reasonCode: string;
+    evidenceCount: number;
+    createdAt: number;
+};
+export declare function startContextConsolidationRun(triggerKind: ContextConsolidationRun['triggerKind'], now?: number): ContextConsolidationRun;
+export declare function finishContextConsolidationRun(input: {
+    runId: string;
+    ok: boolean;
+    reason: string;
+    metrics: Record<string, unknown>;
+    now?: number;
+}): ContextConsolidationRun | undefined;
+export declare function recordContextConsolidationDecision(input: {
+    runId: string;
+    understandingId: string;
+    action: ContextConsolidationDecision['action'];
+    reasonCode: string;
+    evidenceCount: number;
+    now?: number;
+}): ContextConsolidationDecision;
+export declare function getContextConsolidationRun(runId: string): ContextConsolidationRun | undefined;
+export declare function listContextConsolidationRuns(limit?: number): ContextConsolidationRun[];
+export declare function listContextConsolidationDecisions(runId: string): ContextConsolidationDecision[];

package/dist/src/storage/sqlite/context-consolidation-repository.js

@@ -0,0 +1,64 @@
+import { getSqliteDatabase } from "./transaction.js";
+import { randomUUID } from "node:crypto";
+//#region src/storage/sqlite/context-consolidation-repository.ts
+function parseJson(value) {
+	try {
+		const parsed = JSON.parse(value);
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+function runFromRow(row) {
+	return {
+		runId: row.run_id,
+		triggerKind: row.trigger_kind,
+		status: row.status,
+		...row.reason ? { reason: row.reason } : {},
+		metrics: parseJson(row.metrics_json),
+		startedAt: row.started_at,
+		...row.completed_at == null ? {} : { completedAt: row.completed_at }
+	};
+}
+function startContextConsolidationRun(triggerKind, now = Date.now()) {
+	const runId = randomUUID();
+	getSqliteDatabase().prepare(`INSERT INTO context_consolidation_runs (
+    run_id, trigger_kind, status, started_at
+  ) VALUES (?, ?, 'running', ?)`).run(runId, triggerKind, now);
+	return getContextConsolidationRun(runId);
+}
+function finishContextConsolidationRun(input) {
+	getSqliteDatabase().prepare(`UPDATE context_consolidation_runs
+    SET status = ?, reason = ?, metrics_json = ?, completed_at = ? WHERE run_id = ?`).run(input.ok ? "completed" : "failed", input.reason, JSON.stringify(input.metrics), input.now ?? Date.now(), input.runId);
+	return getContextConsolidationRun(input.runId);
+}
+function recordContextConsolidationDecision(input) {
+	const id = randomUUID();
+	getSqliteDatabase().prepare(`INSERT INTO context_consolidation_decisions (
+    decision_id, run_id, understanding_id, action, reason_code, evidence_count, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, input.runId, input.understandingId, input.action, input.reasonCode, input.evidenceCount, input.now ?? Date.now());
+	return listContextConsolidationDecisions(input.runId).find((item) => item.id === id);
+}
+function getContextConsolidationRun(runId) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM context_consolidation_runs WHERE run_id = ?").get(runId);
+	return row ? runFromRow(row) : void 0;
+}
+function listContextConsolidationRuns(limit = 20) {
+	const safeLimit = Math.max(1, Math.min(200, limit));
+	return getSqliteDatabase().prepare(`SELECT * FROM context_consolidation_runs
+    ORDER BY started_at DESC LIMIT ?`).all(safeLimit).map(runFromRow);
+}
+function listContextConsolidationDecisions(runId) {
+	return getSqliteDatabase().prepare(`SELECT * FROM context_consolidation_decisions
+    WHERE run_id = ? ORDER BY created_at, decision_id`).all(runId).map((row) => ({
+		id: row.decision_id,
+		runId: row.run_id,
+		...row.understanding_id ? { understandingId: row.understanding_id } : {},
+		action: row.action,
+		reasonCode: row.reason_code,
+		evidenceCount: row.evidence_count,
+		createdAt: row.created_at
+	}));
+}
+//#endregion
+export { finishContextConsolidationRun, getContextConsolidationRun, listContextConsolidationDecisions, listContextConsolidationRuns, recordContextConsolidationDecision, startContextConsolidationRun };

package/dist/src/storage/sqlite/endpoint-principal-repository.d.ts

@@ -0,0 +1,17 @@
+import type { EndpointKind } from '@xopcai/endpoint-tools-protocol';
+export interface EndpointPrincipal {
+    id: string;
+    kind: EndpointKind;
+    displayName: string;
+    platform: string;
+    publicKey: string;
+    createdAt: number;
+    lastSeenAt?: number;
+    revokedAt?: number;
+}
+export declare function createEndpointPrincipal(principal: Omit<EndpointPrincipal, 'createdAt' | 'lastSeenAt' | 'revokedAt'>): EndpointPrincipal;
+export declare function getEndpointPrincipal(id: string): EndpointPrincipal | undefined;
+export declare function listEndpointPrincipals(): EndpointPrincipal[];
+export declare function touchEndpointPrincipal(id: string, seenAt?: number): void;
+export declare function bindEndpointPrincipal(endpointId: string, principalId: string, boundAt?: number): boolean;
+export declare function revokeEndpointPrincipal(id: string, revokedAt?: number): boolean;

package/dist/src/storage/sqlite/endpoint-principal-repository.js

@@ -0,0 +1,54 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+//#region src/storage/sqlite/endpoint-principal-repository.ts
+function fromRow(row) {
+	return {
+		id: row.id,
+		kind: row.kind,
+		displayName: row.display_name,
+		platform: row.platform,
+		publicKey: row.public_key,
+		createdAt: row.created_at,
+		...row.last_seen_at === null ? {} : { lastSeenAt: row.last_seen_at },
+		...row.revoked_at === null ? {} : { revokedAt: row.revoked_at }
+	};
+}
+function createEndpointPrincipal(principal) {
+	const createdAt = Date.now();
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`
+      INSERT INTO endpoint_principals (
+        id, kind, display_name, platform, public_key, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?)
+    `).run(principal.id, principal.kind, principal.displayName, principal.platform, principal.publicKey, createdAt);
+	});
+	return {
+		...principal,
+		createdAt
+	};
+}
+function getEndpointPrincipal(id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM endpoint_principals WHERE id = ?").get(id);
+	return row ? fromRow(row) : void 0;
+}
+function listEndpointPrincipals() {
+	return getSqliteDatabase().prepare("SELECT * FROM endpoint_principals ORDER BY created_at DESC").all().map(fromRow);
+}
+function touchEndpointPrincipal(id, seenAt = Date.now()) {
+	getSqliteDatabase().prepare("UPDATE endpoint_principals SET last_seen_at = ? WHERE id = ? AND revoked_at IS NULL").run(seenAt, id);
+}
+function bindEndpointPrincipal(endpointId, principalId, boundAt = Date.now()) {
+	return runSqliteWriteTransaction((db) => {
+		db.prepare(`
+      INSERT OR IGNORE INTO endpoint_instance_bindings (endpoint_id, principal_id, bound_at)
+      VALUES (?, ?, ?)
+    `).run(endpointId, principalId, boundAt);
+		return db.prepare(`
+      SELECT principal_id FROM endpoint_instance_bindings WHERE endpoint_id = ?
+    `).get(endpointId)?.principal_id === principalId;
+	});
+}
+function revokeEndpointPrincipal(id, revokedAt = Date.now()) {
+	return getSqliteDatabase().prepare("UPDATE endpoint_principals SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL").run(revokedAt, id).changes > 0;
+}
+//#endregion
+export { bindEndpointPrincipal, createEndpointPrincipal, getEndpointPrincipal, listEndpointPrincipals, revokeEndpointPrincipal, touchEndpointPrincipal };

package/dist/src/storage/sqlite/endpoint-tool-invocation-repository.d.ts

@@ -0,0 +1,25 @@
+import type { EndpointEffect, EndpointToolErrorCode } from '@xopcai/endpoint-tools-protocol';
+export interface EndpointToolInvocationAudit {
+    id: string;
+    principalId: string;
+    endpointId: string;
+    toolCallId: string;
+    toolName: string;
+    effect: EndpointEffect;
+    confirmationRequired: boolean;
+    argumentsSha256: string;
+    status: 'running' | 'succeeded' | 'failed';
+    errorCode?: EndpointToolErrorCode;
+    errorMessage?: string;
+    startedAt: number;
+    completedAt?: number;
+}
+export declare function startEndpointToolInvocationAudit(audit: Omit<EndpointToolInvocationAudit, 'status' | 'completedAt' | 'errorCode' | 'errorMessage'>): void;
+export declare function finishEndpointToolInvocationAudit(params: {
+    id: string;
+    status: 'succeeded' | 'failed';
+    errorCode?: EndpointToolErrorCode;
+    errorMessage?: string;
+    completedAt?: number;
+}): void;
+export declare function listEndpointToolInvocationAudits(limit?: number): EndpointToolInvocationAudit[];