@tangle-network/agent-runtime 3.0.31 → 3.0.34

package/dist/{server-BXveLAfq.js → server-CAxz7X8H.js}

@@ -1,9 +1,10 @@
-import { In as buildLoopSpanNodes } from "./scope-D5T_q60y.js";
+import { In as buildLoopSpanNodes } from "./scope-CCHfmCvY.js";
 import { m as ValidationError, o as NotFoundError, t as AgentEvalError } from "./errors-AzSuGI23.js";
 import { X as fnv1a32Hex, Y as errorMessage } from "./workspace-streams-8ALHaZzx.js";
 import { n as createStdioToolServer } from "./tool-server-CZWd_Opp.js";
-import { n as delegate } from "./delegate-CYpe4KH1.js";
+import { n as delegate } from "./delegate-D1urT1fO.js";
 import { t as UI_LENSES } from "./substrate-Db2pp6y3.js";
+import { randomUUID } from "node:crypto";
 import path, { dirname } from "node:path";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import "node:stream";
@@ -1515,6 +1516,296 @@ function createDelegationStatusHandler(options) {
 		return status;
 	};
 }
+// src/mcp/tools/events.ts
+/**
+* `events_*` MCP tools — the runtime-owned piece of the agent-inbox event track (chatgpt-plugins
+* #18 / agent-runtime #1497): expose the NATIVE event journal (the durable `ObserverJournal`:
+* runtime hook events + decision points, digest-chained) via an explicit subscription lifecycle.
+* Boundaries, by design:
+* - No scheduler, no cron, no second schedule authority. Recurrence and wake-ups stay with the
+*   native trigger owners; these tools only read and acknowledge what the journal already recorded.
+* - Delivery is at-least-once until acknowledged: `events_fetch` pages from the acknowledged
+*   cursor, so a lost response is redelivered, and sequence numbers deduplicate on the client.
+* - Records are verified against the journal's digest chain on every page; a mutated, reordered
+*   or deleted tail refuses the page instead of serving unverifiable history.
+* - Subscriptions are idempotent by caller key: a reconnect resubscribes to the SAME subscription
+*   (same id, same cursor), never a duplicate stream.
+* - Optional expiry is lazy: an expired subscription reads as gone, and the caller resubscribes
+*   with the same key to resume from its cursor.
+* @experimental
+*/
+/** @experimental */
+var InMemoryEventSubscriptionStore = class {
+	byId = /* @__PURE__ */ new Map();
+	byKey = /* @__PURE__ */ new Map();
+	async get(subscriptionId) {
+		return this.byId.get(subscriptionId) ?? null;
+	}
+	async findByKey(key) {
+		const id = this.byKey.get(key);
+		return id ? this.byId.get(id) ?? null : null;
+	}
+	async put(subscription) {
+		this.byId.set(subscription.subscriptionId, subscription);
+		this.byKey.set(subscription.key, subscription.subscriptionId);
+	}
+	async delete(subscriptionId) {
+		const existing = this.byId.get(subscriptionId);
+		this.byId.delete(subscriptionId);
+		if (existing && this.byKey.get(existing.key) === subscriptionId) this.byKey.delete(existing.key);
+	}
+};
+const DEFAULT_TTL_SECONDS = 86400;
+const MAX_PAGE_LIMIT = 200;
+function isMcpEventRecord(value) {
+	if (value === null || typeof value !== "object") return false;
+	const record = value;
+	return Number.isSafeInteger(record.sequence) && record.sequence >= 0 && typeof record.pursuitId === "string" && (record.kind === "event" || record.kind === "decision") && Number.isFinite(record.observedAt) && typeof record.digest === "string" && (record.previousDigest === void 0 || typeof record.previousDigest === "string");
+}
+/** The read model: journal order, digest-chain linked. The durable journal
+* verifies record digests on read; this linkage check is the second fence that
+* refuses a page carved from reordered or spliced history. */
+async function verifiedPage(source, after, limit, kinds) {
+	const all = (await source.read()).filter(isMcpEventRecord).sort((a, b) => a.sequence - b.sequence);
+	const page = [];
+	for (let index = 0; index < all.length; index += 1) {
+		const record = all[index];
+		if (!record) continue;
+		const previous = index > 0 ? all[index - 1] : void 0;
+		if (previous && record.previousDigest !== previous.digest) throw new ValidationError("events: journal chain verification failed; refusing to serve unverifiable history");
+		if (record.sequence > after && kinds.includes(record.kind) && page.length < limit) page.push(record);
+	}
+	const last = all[all.length - 1];
+	return {
+		records: page,
+		highWatermark: last ? last.sequence : 0
+	};
+}
+async function currentHighWatermark(source) {
+	return (await verifiedPage(source, 0, 0, ["event", "decision"])).highWatermark;
+}
+function parseKinds(raw) {
+	if (raw === void 0) return void 0;
+	if (!Array.isArray(raw) || raw.length === 0 || !raw.every((kind) => kind === "event" || kind === "decision")) throw new ValidationError("events: `kinds` must be a non-empty array of \"event\" or \"decision\"");
+	return raw;
+}
+function expired(subscription, nowMs) {
+	return subscription.expiresAt !== null && subscription.expiresAt <= nowMs;
+}
+async function liveSubscription(store, subscriptionId, nowMs) {
+	const subscription = await store.get(subscriptionId);
+	if (!subscription || expired(subscription, nowMs)) throw new ValidationError(`events: unknown or expired subscription "${subscriptionId}"; resubscribe with the same key to resume from its cursor`);
+	return subscription;
+}
+/** Build the four `events_*` tool descriptors. Register them only when an event source is wired. @experimental */
+function createEventsTools(options) {
+	const source = options.eventSource;
+	const store = options.subscriptionStore ?? new InMemoryEventSubscriptionStore();
+	const now = options.now ?? Date.now;
+	async function subscribe(raw) {
+		if (raw === null || typeof raw !== "object") throw new ValidationError("events_subscribe: arguments must be an object");
+		const value = raw;
+		if (typeof value.key !== "string" || value.key.trim().length === 0 || value.key.length > 256) throw new ValidationError("events_subscribe: `key` must be a non-empty string (max 256 chars)");
+		const key = value.key.trim();
+		const kinds = parseKinds(value.kinds) ?? ["event", "decision"];
+		const rawFrom = value.fromSequence;
+		if (rawFrom !== void 0 && (typeof rawFrom !== "number" || !Number.isSafeInteger(rawFrom) || rawFrom < 0)) throw new ValidationError("events_subscribe: `fromSequence` must be a non-negative integer");
+		const fromSequence = rawFrom;
+		const rawTtl = value.ttlSeconds;
+		if (rawTtl !== void 0 && (typeof rawTtl !== "number" || !Number.isSafeInteger(rawTtl) || rawTtl <= 0 || rawTtl > 2592e3)) throw new ValidationError("events_subscribe: `ttlSeconds` must be an integer in (0, 2592000]");
+		const ttlSeconds = rawTtl ?? DEFAULT_TTL_SECONDS;
+		const existing = await store.findByKey(key);
+		if (existing && !expired(existing, now())) {
+			const renewed = {
+				...existing,
+				expiresAt: now() + ttlSeconds * 1e3
+			};
+			await store.put(renewed);
+			return {
+				subscriptionId: renewed.subscriptionId,
+				key,
+				cursor: renewed.cursor,
+				kinds: [...renewed.kinds],
+				expiresAt: renewed.expiresAt
+			};
+		}
+		const resumedCursor = existing ? existing.cursor : void 0;
+		if (existing) await store.delete(existing.subscriptionId);
+		const cursor = fromSequence !== void 0 ? fromSequence : resumedCursor ?? await currentHighWatermark(source);
+		const subscription = {
+			subscriptionId: randomUUID(),
+			key,
+			kinds,
+			cursor,
+			createdAt: now(),
+			expiresAt: now() + ttlSeconds * 1e3
+		};
+		await store.put(subscription);
+		return {
+			subscriptionId: subscription.subscriptionId,
+			key,
+			cursor,
+			kinds: [...kinds],
+			expiresAt: subscription.expiresAt
+		};
+	}
+	async function fetch(raw) {
+		if (raw === null || typeof raw !== "object") throw new ValidationError("events_fetch: arguments must be an object");
+		const value = raw;
+		if (typeof value.subscriptionId !== "string" || value.subscriptionId.length === 0) throw new ValidationError("events_fetch: `subscriptionId` must be a non-empty string");
+		const rawLimit = value.limit;
+		if (rawLimit !== void 0 && (typeof rawLimit !== "number" || !Number.isSafeInteger(rawLimit) || rawLimit <= 0 || rawLimit > MAX_PAGE_LIMIT)) throw new ValidationError(`events_fetch: \`limit\` must be an integer in (0, ${MAX_PAGE_LIMIT}]`);
+		const limit = rawLimit ?? MAX_PAGE_LIMIT;
+		const subscription = await liveSubscription(store, value.subscriptionId, now());
+		const page = await verifiedPage(source, subscription.cursor, limit, subscription.kinds);
+		return {
+			subscriptionId: subscription.subscriptionId,
+			cursor: subscription.cursor,
+			records: page.records.map((record) => ({
+				sequence: record.sequence,
+				pursuitId: record.pursuitId,
+				kind: record.kind,
+				observedAt: record.observedAt,
+				digest: record.digest,
+				payload: record.payload
+			})),
+			highWatermark: page.highWatermark
+		};
+	}
+	async function acknowledge(raw) {
+		if (raw === null || typeof raw !== "object") throw new ValidationError("events_ack: arguments must be an object");
+		const value = raw;
+		if (typeof value.subscriptionId !== "string" || value.subscriptionId.length === 0) throw new ValidationError("events_ack: `subscriptionId` must be a non-empty string");
+		if (typeof value.sequence !== "number" || !Number.isSafeInteger(value.sequence) || value.sequence < 0) throw new ValidationError("events_ack: `sequence` must be a non-negative integer");
+		const subscription = await liveSubscription(store, value.subscriptionId, now());
+		const highWatermark = await currentHighWatermark(source);
+		if (value.sequence > highWatermark) throw new ValidationError(`events_ack: \`sequence\` ${value.sequence} is beyond the journal high-watermark ${highWatermark}; acknowledge only delivered records`);
+		if (value.sequence > subscription.cursor) subscription.cursor = value.sequence;
+		await store.put(subscription);
+		return {
+			subscriptionId: subscription.subscriptionId,
+			cursor: subscription.cursor
+		};
+	}
+	async function unsubscribe(raw) {
+		if (raw === null || typeof raw !== "object") throw new ValidationError("events_unsubscribe: arguments must be an object");
+		const value = raw;
+		if (typeof value.subscriptionId !== "string" || value.subscriptionId.length === 0) throw new ValidationError("events_unsubscribe: `subscriptionId` must be a non-empty string");
+		if (!await store.get(value.subscriptionId)) return {
+			subscriptionId: value.subscriptionId,
+			removed: false
+		};
+		await store.delete(value.subscriptionId);
+		return {
+			subscriptionId: value.subscriptionId,
+			removed: true
+		};
+	}
+	return {
+		subscribeTool: {
+			name: "events_subscribe",
+			description: [
+				"Subscribe to the native runtime event journal (task events and decision points).",
+				"Idempotent by `key`: reconnecting with the same key resumes the same",
+				"subscription and its acknowledged cursor — never a duplicate stream.",
+				"Default cursor is the current high-watermark (only new records); pass",
+				"`fromSequence` to replay history. Optional `kinds` filter and `ttlSeconds`",
+				"expiry. This is a read surface over recorded history: it schedules nothing",
+				"and triggers nothing; recurrence and wake-ups stay with their native owners."
+			].join("\n"),
+			inputSchema: EVENTS_SUBSCRIBE_INPUT_SCHEMA,
+			handler: subscribe
+		},
+		fetchTool: {
+			name: "events_fetch",
+			description: [
+				"Fetch one page of journaled records after the acknowledged cursor.",
+				"At-least-once: records are redelivered until `events_ack` advances the",
+				"cursor; deduplicate by `sequence`. Every page is verified against the",
+				"journal digest chain. An expired or unknown subscription errors: resubscribe",
+				"with the same key to resume from its cursor."
+			].join("\n"),
+			inputSchema: EVENTS_FETCH_INPUT_SCHEMA,
+			handler: fetch
+		},
+		ackTool: {
+			name: "events_ack",
+			description: "Acknowledge records up to `sequence` (forward-only). Unacknowledged records are redelivered.",
+			inputSchema: EVENTS_ACK_INPUT_SCHEMA,
+			handler: acknowledge
+		},
+		unsubscribeTool: {
+			name: "events_unsubscribe",
+			description: "Remove a subscription. Idempotent; the journal itself is unaffected.",
+			inputSchema: EVENTS_UNSUBSCRIBE_INPUT_SCHEMA,
+			handler: unsubscribe
+		}
+	};
+}
+const EVENTS_SUBSCRIBE_INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		key: {
+			type: "string",
+			description: "Caller-chosen idempotency key; one consumer key resumes one stream."
+		},
+		kinds: {
+			type: "array",
+			items: { enum: ["event", "decision"] },
+			description: "Optional kind filter."
+		},
+		fromSequence: {
+			type: "integer",
+			description: "Inclusive replay start; default: current high-watermark."
+		},
+		ttlSeconds: {
+			type: "integer",
+			description: "Subscription expiry in seconds; default 86400."
+		}
+	},
+	required: ["key"],
+	additionalProperties: false
+};
+const EVENTS_FETCH_INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		subscriptionId: { type: "string" },
+		limit: {
+			type: "integer",
+			description: `Max records per page (max ${MAX_PAGE_LIMIT}).`
+		}
+	},
+	required: ["subscriptionId"],
+	additionalProperties: false
+};
+const EVENTS_ACK_INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		subscriptionId: { type: "string" },
+		sequence: { type: "integer" }
+	},
+	required: ["subscriptionId", "sequence"],
+	additionalProperties: false
+};
+const EVENTS_UNSUBSCRIBE_INPUT_SCHEMA = {
+	type: "object",
+	properties: { subscriptionId: { type: "string" } },
+	required: ["subscriptionId"],
+	additionalProperties: false
+};
+function observerJournalEventSource(journal) {
+	return { async read() {
+		return (await journal.read()).map((record) => ({
+			sequence: record.sequence,
+			pursuitId: record.pursuitId,
+			kind: record.kind,
+			observedAt: record.observedAt,
+			digest: record.digest,
+			...record.previousDigest !== void 0 ? { previousDigest: record.previousDigest } : {},
+			payload: record.event ?? record.decision ?? null
+		}));
+	} };
+}
 // src/mcp/server.ts
 const DEFAULT_SERVER_NAME = "agent-runtime-mcp";
 const DEFAULT_SERVER_VERSION = "0.22.0";
@@ -1559,6 +1850,16 @@ function createMcpServer(options = {}) {
 		inputSchema: DELEGATION_STATUS_INPUT_SCHEMA,
 		handler: createDelegationStatusHandler({ queue })
 	});
+	if (options.eventSource) {
+		const events = createEventsTools({
+			eventSource: options.eventSource,
+			...options.eventSubscriptionStore !== void 0 ? { subscriptionStore: options.eventSubscriptionStore } : {}
+		});
+		tools.set(events.subscribeTool.name, events.subscribeTool);
+		tools.set(events.fetchTool.name, events.fetchTool);
+		tools.set(events.ackTool.name, events.ackTool);
+		tools.set(events.unsubscribeTool.name, events.unsubscribeTool);
+	}
 	tools.set(DELEGATION_HISTORY_TOOL_NAME, {
 		name: DELEGATION_HISTORY_TOOL_NAME,
 		description: DELEGATION_HISTORY_DESCRIPTION,
@@ -1583,6 +1884,6 @@ function createMcpServer(options = {}) {
 		stop: stdio.stop
 	};
 }
-export { composeLoopTraceEmitters as a, FileDelegationStore as i, createDelegateHandler as n, DelegationTaskQueue as r, createMcpServer as t };
+export { FileDelegationStore as a, DelegationTaskQueue as i, observerJournalEventSource as n, composeLoopTraceEmitters as o, createDelegateHandler as r, createMcpServer as t };
 
-//# sourceMappingURL=server-BXveLAfq.js.map
+//# sourceMappingURL=server-CAxz7X8H.js.map