@segmentstream/agent 0.2.1 → 0.3.1

package/dist/extension/lib/attachment-tables.mjs

@@ -0,0 +1,186 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { decodeText, detectFile, extensionOf } from "./attachment-formats.mjs";
+async function delimitedRows(text) {
+	const { parse } = await import("csv-parse/sync");
+	const chosen = [
+		",",
+		";",
+		"	"
+	].map((delimiter) => {
+		try {
+			const records = parse(text, {
+				delimiter,
+				bom: true,
+				skip_empty_lines: true,
+				relax_column_count: true
+			});
+			const widths = records.slice(0, 50).map((row) => row.length);
+			const common = Math.max(0, ...widths.map((width) => widths.filter((item) => item === width).length));
+			const width = widths.find((item) => widths.filter((candidate) => candidate === item).length === common) ?? 1;
+			return {
+				records,
+				score: width > 1 ? common * 100 + width : 0
+			};
+		} catch (error) {
+			return {
+				records: null,
+				score: -1,
+				error
+			};
+		}
+	}).sort((a, b) => b.score - a.score)[0];
+	if (chosen.records === null) throw new Error("Unable to parse delimited file; check quotes and delimiter.", { cause: chosen.error });
+	return chosen.records;
+}
+async function readSheets(attachment, bytes) {
+	const file = await detectFile(attachment, bytes);
+	if (file.format !== "table") throw new Error("This attachment is not a CSV/TSV/XLSX/XLS/ODS table.");
+	const extension = extensionOf(attachment.filename);
+	const compound = bytes[0] === 208 && bytes[1] === 207;
+	if (!file.zip && !compound) {
+		if ([
+			"xlsx",
+			"xls",
+			"ods"
+		].includes(extension) || file.mediaType.includes("spreadsheetml")) throw new Error("Spreadsheet container is invalid or encrypted.");
+		return [{
+			name: "Sheet1",
+			rows: await delimitedRows(decodeText(bytes))
+		}];
+	}
+	const XLSX = await import("xlsx");
+	const workbook = XLSX.read(Buffer.from(bytes), {
+		type: "buffer",
+		cellDates: true
+	});
+	return workbook.SheetNames.map((name) => ({
+		name,
+		rows: XLSX.utils.sheet_to_json(workbook.Sheets[name], {
+			header: 1,
+			defval: null,
+			raw: true
+		})
+	}));
+}
+function numeric(value) {
+	if (value === null || value === "") return null;
+	let text = String(value).trim();
+	const negative = /^\(.*\)$/.test(text) || /-$/.test(text);
+	text = text.replace(/[£$€¥\s\u00a0]/g, "").replace(/^\((.*)\)$/, "$1").replace(/-$/, "");
+	if (text === "") return null;
+	const comma = text.lastIndexOf(",");
+	const dot = text.lastIndexOf(".");
+	if (comma >= 0 && dot >= 0) text = comma > dot ? text.replace(/\./g, "").replace(",", ".") : text.replace(/,/g, "");
+	else if (comma >= 0) text = /^[+-]?\d{1,3}(,\d{3})+$/.test(text) ? text.replace(/,/g, "") : text.replace(",", ".");
+	if (!/^[+-]?\d+(?:\.\d+)?$/.test(text) || text.replace(/\D/g, "").length > 40) return null;
+	return negative ? `-${text.replace(/^[+-]/, "")}` : text;
+}
+function dateParts(value) {
+	if (typeof value !== "string") return;
+	const match = value.trim().match(/^(\d{1,2})[/.\-](\d{1,2})[/.\-](\d{2}|\d{4})(?:\s.*)?$/);
+	return match ? match.slice(1).map(Number) : void 0;
+}
+function dateValue(value, order, serial = false) {
+	if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.toISOString() : null;
+	if (serial && typeof value === "number" && value >= 1 && value < 1e5) return new Date((value < 60 ? Date.UTC(1899, 11, 31) : Date.UTC(1899, 11, 30)) + Math.round(value * 864e5)).toISOString();
+	if (typeof value !== "string") return null;
+	const text = value.trim();
+	const iso = text.match(/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})?)?$/);
+	const local = text.match(/^(\d{1,2})[/.\-](\d{1,2})[/.\-](\d{2}|\d{4})(?:[ T](\d{1,2}):(\d{2})(?::(\d{2}))?)?$/);
+	if (!iso && !local) return null;
+	const match = iso ?? local;
+	let year = Number(iso ? match[1] : match[3]);
+	const month = Number(iso ? match[2] : order === "day_first" ? match[2] : match[1]);
+	const day = Number(iso ? match[3] : order === "day_first" ? match[1] : match[2]);
+	const hour = Number(match[4] ?? 0);
+	const minute = Number(match[5] ?? 0);
+	const second = Number(match[6] ?? 0);
+	const millisecond = iso ? Number((match[7] ?? "0").padEnd(3, "0")) : 0;
+	if (year < 100) year += year < 70 ? 2e3 : 1900;
+	const stamp = new Date(Date.UTC(year, month - 1, day, hour, minute, second, millisecond));
+	if (stamp.getUTCFullYear() !== year || stamp.getUTCMonth() !== month - 1 || stamp.getUTCDate() !== day || hour > 23 || minute > 59 || second > 59) return null;
+	if (iso?.[8] && iso[8] !== "Z") {
+		const shifted = Date.parse(`${iso[1]}-${iso[2]}-${iso[3]}T${iso[4]}:${iso[5]}:${iso[6] ?? "00"}${iso[8]}`);
+		return Number.isFinite(shifted) ? new Date(shifted).toISOString() : null;
+	}
+	return stamp.toISOString();
+}
+function present(value) {
+	return value !== void 0 && value !== null && String(value).trim() !== "";
+}
+function detectedHeader(rows) {
+	const candidates = rows.slice(0, 50);
+	const width = candidates.reduce((maximum, row) => Math.max(maximum, row.length), 0);
+	const labels = candidates.findIndex((row) => row.length >= Math.max(1, width - 1) && row.some(present) && row.filter(present).every((value) => typeof value === "string" && numeric(value) === null && dateValue(value, "day_first") === null && dateValue(value, "month_first") === null));
+	if (labels >= 0) return labels;
+	return -1;
+}
+function typedTable(sheets, options = {}) {
+	const sheet = options.sheet === void 0 ? sheets[0] : sheets.find((item) => item.name === options.sheet);
+	if (!sheet) throw new Error(`Unknown sheet. Available sheets: ${sheets.map((item) => item.name).join(", ")}`);
+	const headerRow = options.header_row ?? detectedHeader(sheet.rows);
+	const header = sheet.rows[headerRow] ?? [];
+	const rows = sheet.rows.slice(headerRow + 1).filter((row) => row.some(present));
+	const width = rows.reduce((maximum, row) => Math.max(maximum, row.length), header.length);
+	if (headerRow >= 0 && rows.some((row) => row.slice(header.length).some(present))) throw new Error("Data has more columns than the header. Check CSV quoting/delimiter or override header_row.");
+	const names = new Set();
+	const warnings = [];
+	const columns = [];
+	const parsed = [];
+	for (let index = 0; index < width; index++) {
+		const base = present(header[index]) ? String(header[index]).trim() : `Column ${index + 1}`;
+		let name = base;
+		let suffix = 2;
+		while (names.has(name)) name = `${base} (${suffix++})`;
+		names.add(name);
+		const values = rows.map((row) => row[index] ?? null);
+		const nonblank = values.filter(present);
+		const dayFirst = nonblank.some((value) => (dateParts(value)?.[0] ?? 0) > 12);
+		const monthFirst = nonblank.some((value) => (dateParts(value)?.[1] ?? 0) > 12);
+		const order = options.date_order ?? (monthFirst && !dayFirst ? "month_first" : "day_first");
+		const dateLike = /date|time/i.test(name) || nonblank.some((value) => value instanceof Date || typeof value === "string" && /^(\d{4}-\d{2}-\d{2}|\d{1,2}\/\d{1,2}\/\d{2,4})/.test(value));
+		const dates = values.map((value) => dateValue(value, order, dateLike));
+		const numbers = values.map(numeric);
+		const allDates = nonblank.length > 0 && dateLike && values.every((value, at) => !present(value) || dates[at] !== null);
+		const allNumbers = nonblank.length > 0 && values.every((value, at) => !present(value) || numbers[at] !== null);
+		if (allDates && (options.date_order !== void 0 || !dayFirst || !monthFirst)) {
+			columns.push({
+				name,
+				type: "date",
+				date_order: order
+			});
+			parsed.push(dates);
+			if (options.date_order === void 0 && !dayFirst && !monthFirst && nonblank.some((value) => dateParts(value))) warnings.push(`${name}: ambiguous day/month order; ${order} used. Set date_order to override.`);
+		} else if (allNumbers && !dateLike) {
+			columns.push({
+				name,
+				type: "decimal"
+			});
+			parsed.push(numbers);
+		} else {
+			columns.push({
+				name,
+				type: "text"
+			});
+			parsed.push(values.map((value) => present(value) ? String(value) : null));
+			if (dateLike || /debit|credit|amount|balance/i.test(name)) warnings.push(`${name}: contains unparseable or conflicting values; kept as text. No values replaced with zero.`);
+		}
+	}
+	return {
+		sheets: sheets.map((item) => ({
+			name: item.name,
+			total_rows: item.rows.slice((item === sheet ? headerRow : detectedHeader(item.rows)) + 1).filter((row) => row.some(present)).length
+		})),
+		sheet: sheet.name,
+		header_row: headerRow,
+		columns,
+		warnings,
+		rows: rows.map((_, index) => Object.fromEntries(columns.map((column, at) => [column.name, parsed[at][index]])))
+	};
+}
+export { dateValue, numeric, readSheets, typedTable };

package/dist/extension/lib/attachment-tools.d.ts

@@ -1,5 +1,6 @@
 import type { SessionAuthContext } from "eve/context";
 import { type AgentAttachments, type Attachment, type AttachmentOwner } from "./attachments.js";
+import { type DateOrder } from "./attachment-tables.js";
 import { type Environment } from "./environment.js";
 import { type RuntimeToken } from "./runtime-token.js";
 /**
@@ -7,7 +8,7 @@ import { type RuntimeToken } from "./runtime-token.js";
  * the member and chat on the session's principal, which the channel set from the pairing, and the
  * session's own id. A tool's arguments name only the attachment and what to do with it.
  */
-/** The longest text `attachments_read` returns; the rest is cut and marked as truncated. */
+/** Maximum characters in a read/query response; remaining data is available by continuation. */
 export declare const MAXIMUM_TEXT_CHARACTERS = 50000;
 /** The largest file `attachments_read` hands the model inline. */
 export declare const MAXIMUM_INLINE_BYTES: number;
@@ -33,22 +34,52 @@ export declare function attachmentForModel(attachment: Attachment): {
     state: string;
     expires_at: string;
 };
+export interface ReadOptions {
+    readonly sheet?: string;
+    readonly offset?: number;
+    readonly limit?: number;
+    readonly character_offset?: number;
+    readonly header_row?: number;
+    readonly date_order?: DateOrder;
+}
 export type ReadOutput = {
     readonly attachment: ReturnType<typeof attachmentForModel>;
     readonly kind: "text";
+    readonly format: string;
     readonly text: string;
     readonly truncated: boolean;
+    readonly pagination: {
+        readonly unit: "characters" | "rows";
+        readonly offset: number;
+        readonly limit: number;
+        readonly total: number;
+        readonly total_pages: number;
+        readonly next_offset: number | null;
+        readonly next_character_offset?: number;
+    };
+    readonly sheet?: string;
+    readonly sheets?: ReadonlyArray<{
+        readonly name: string;
+        readonly total_rows: number;
+    }>;
+    readonly columns?: unknown;
+    readonly warnings?: ReadonlyArray<string>;
 } | {
     readonly attachment: ReturnType<typeof attachmentForModel>;
     readonly kind: "file";
+    readonly media_type: string;
     readonly data: string;
 } | {
     readonly attachment: ReturnType<typeof attachmentForModel>;
     readonly kind: "unreadable";
     readonly note: string;
 };
-/** What `attachments_read` answers for a file: its text, the file itself, or why neither. */
-export declare function readOutput(attachment: Attachment, bytes: Uint8Array): ReadOutput;
+export declare function pageInteger(value: unknown, fallback: number, maximum?: number): number;
+export declare function headerArgument(value: unknown): number | undefined;
+/** Keep envelopes and structured query results inside the same response budget as file text. */
+export declare function boundedResultPage<T>(items: readonly T[], offset: number, limit: number, envelope: unknown): T[];
+/** Reads never discard the remainder. Parsers process the entire file before selecting a page. */
+export declare function readOutput(attachment: Attachment, bytes: Uint8Array, options?: ReadOptions): Promise<ReadOutput>;
 /** A required string argument. */
 export declare function stringArgument(input: Readonly<Record<string, unknown>>, name: string): string;
 /** An optional string argument. */

package/dist/extension/lib/attachment-tools.mjs

@@ -9,22 +9,10 @@ import { memberIdOf } from "./telegram/principal.mjs";
 import { runtimeToken } from "./runtime-token.mjs";
 import { agentAttachments } from "./attachments.mjs";
 import { telegramConversation } from "./telegram/files.mjs";
+import { detectFile, documentText } from "./attachment-formats.mjs";
+import { readSheets, typedTable } from "./attachment-tables.mjs";
 const MAXIMUM_TEXT_CHARACTERS = 5e4;
 const MAXIMUM_INLINE_BYTES = 5242880;
-const INLINE_TYPES = new Set([
-	"application/pdf",
-	"image/png",
-	"image/jpeg",
-	"image/webp",
-	"image/gif"
-]);
-function isText(contentType) {
-	return contentType.startsWith("text/") || [
-		"application/json",
-		"application/xml",
-		"application/csv"
-	].includes(contentType);
-}
 var AttachmentOwnerError = class extends Error {
 	name = "AttachmentOwnerError";
 };
@@ -58,27 +46,148 @@ function attachmentForModel(attachment) {
 		...attachment.promotion === null ? {} : { promotion: attachment.promotion }
 	};
 }
-function readOutput(attachment, bytes) {
+function pageInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > maximum) throw new TypeError(`Pagination values must be integers from 0 to ${maximum}.`);
+	return value;
+}
+function headerArgument(value) {
+	if (value === void 0) return;
+	if (value === -1) return -1;
+	return pageInteger(value, 0);
+}
+function boundedResultPage(items, offset, limit, envelope) {
+	const budget = MAXIMUM_TEXT_CHARACTERS - JSON.stringify(envelope).length - 2e3;
+	const page = [];
+	let size = 2;
+	for (const item of items.slice(offset, offset + limit)) {
+		const length = JSON.stringify(item).length + 1;
+		if (size + length > budget) {
+			if (page.length === 0) throw new Error("One result exceeds the response budget. Use attachments_read and its character continuation.");
+			break;
+		}
+		page.push(item);
+		size += length;
+	}
+	return page;
+}
+async function readOutput(attachment, bytes, options = {}) {
 	const described = attachmentForModel(attachment);
-	if (isText(attachment.contentType)) {
-		const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+	const offset = pageInteger(options.offset, 0);
+	const requestedLimit = pageInteger(options.limit, MAXIMUM_TEXT_CHARACTERS, MAXIMUM_TEXT_CHARACTERS);
+	if (requestedLimit === 0) throw new TypeError("limit must be greater than zero.");
+	try {
+		const file = await detectFile(attachment, bytes);
+		if (file.format === "inline" && bytes.byteLength <= 5242880) return {
+			attachment: described,
+			kind: "file",
+			media_type: file.mediaType,
+			data: Buffer.from(bytes).toString("base64")
+		};
+		if (file.format === "inline" || file.format === "opaque" || file.format === "doc") return {
+			attachment: described,
+			kind: "unreadable",
+			note: file.format === "inline" ? "The file exceeds the inline display limit; it can still be promoted by id." : file.format === "doc" ? "Legacy binary Word document: text extraction is unavailable. Metadata is shown; the original can be promoted." : "No text extractor for this format. Metadata is shown; the original can be promoted by id."
+		};
+		if (file.format === "table") {
+			const table = typedTable(await readSheets(attachment, bytes), options);
+			const limit = pageInteger(options.limit, 100, MAXIMUM_TEXT_CHARACTERS);
+			const characterOffset = pageInteger(options.character_offset, 0);
+			const envelope = {
+				attachment: described,
+				columns: table.columns,
+				warnings: table.warnings,
+				sheets: table.sheets
+			};
+			const budget = Math.floor((MAXIMUM_TEXT_CHARACTERS - JSON.stringify(envelope).length - 2e3) / 6);
+			const csv = (values) => values.map((value) => `"${(value ?? "").replace(/"/g, "\"\"")}"`).join(",");
+			const heading = `Sheet: ${table.sheet}\n${csv(table.columns.map((column) => column.name))}\n`;
+			const lines = table.rows.map((row) => csv(table.columns.map((column) => row[column.name])) + "\n");
+			if (heading.length >= budget) throw new Error("Table headers exceed the response budget.");
+			const pageAt = (rowOffset, charOffset) => {
+				let text = heading;
+				let cursor = Math.min(rowOffset, lines.length);
+				let nextCharacter = 0;
+				for (; cursor < Math.min(lines.length, rowOffset + limit); cursor++) {
+					const line = lines[cursor];
+					const start = cursor === rowOffset ? charOffset : 0;
+					const remaining = line.slice(start);
+					if (start >= line.length) throw new TypeError("character_offset exceeds this row's text length.");
+					if (text.length + remaining.length > budget) {
+						if (cursor === rowOffset) {
+							const available = budget - text.length;
+							text += remaining.slice(0, available);
+							nextCharacter = start + available;
+						}
+						break;
+					}
+					text += remaining;
+				}
+				return {
+					text,
+					next: cursor < lines.length ? cursor : null,
+					nextCharacter
+				};
+			};
+			const { text, next, nextCharacter } = pageAt(offset, characterOffset);
+			let totalPages = 0;
+			let nextRow = 0;
+			let nextChar = 0;
+			while (nextRow !== null && lines.length > 0) {
+				const page = pageAt(nextRow, nextChar);
+				totalPages++;
+				nextRow = page.next;
+				nextChar = page.nextCharacter;
+			}
+			return {
+				...envelope,
+				kind: "text",
+				format: "table",
+				sheet: table.sheet,
+				text,
+				truncated: next !== null,
+				pagination: {
+					unit: "rows",
+					offset,
+					limit,
+					total: table.rows.length,
+					total_pages: totalPages,
+					next_offset: next,
+					...nextCharacter === 0 ? {} : { next_character_offset: nextCharacter }
+				}
+			};
+		}
+		const fullText = await documentText(file, bytes);
+		const budget = Math.floor((MAXIMUM_TEXT_CHARACTERS - JSON.stringify(described).length - 2e3) / 6);
+		const limit = Math.min(requestedLimit, budget);
+		const text = fullText.slice(offset, offset + limit);
+		const next = offset + text.length < fullText.length ? offset + text.length : null;
 		return {
 			attachment: described,
 			kind: "text",
-			text: text.slice(0, MAXIMUM_TEXT_CHARACTERS),
-			truncated: text.length > MAXIMUM_TEXT_CHARACTERS
+			format: file.format,
+			text,
+			truncated: next !== null,
+			pagination: {
+				unit: "characters",
+				offset,
+				limit,
+				total: fullText.length,
+				total_pages: Math.ceil(fullText.length / limit),
+				next_offset: next
+			}
+		};
+	} catch (error) {
+		console.error("[segmentstream] attachment parsing failed", {
+			id: attachment.id,
+			error
+		});
+		return {
+			attachment: described,
+			kind: "unreadable",
+			note: "The file could not be parsed (invalid, encrypted, or over the expanded parsing limit). The original can still be promoted."
 		};
 	}
-	if (INLINE_TYPES.has(attachment.contentType) && bytes.byteLength <= 5242880) return {
-		attachment: described,
-		kind: "file",
-		data: Buffer.from(bytes).toString("base64")
-	};
-	return {
-		attachment: described,
-		kind: "unreadable",
-		note: INLINE_TYPES.has(attachment.contentType) ? "The file is too large to show again; it was attached to the message it came with." : `A ${attachment.contentType} file cannot be shown; promote or discard it by its id.`
-	};
 }
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -107,4 +216,4 @@ const ID_INPUT = {
 	required: ["id"],
 	additionalProperties: false
 };
-export { AttachmentOwnerError, ID_INPUT, MAXIMUM_INLINE_BYTES, MAXIMUM_TEXT_CHARACTERS, attachmentForModel, attachmentOwner, optionalObject, optionalString, readOutput, stringArgument, toolAttachments };
+export { AttachmentOwnerError, ID_INPUT, MAXIMUM_INLINE_BYTES, MAXIMUM_TEXT_CHARACTERS, attachmentForModel, attachmentOwner, boundedResultPage, headerArgument, optionalObject, optionalString, pageInteger, readOutput, stringArgument, toolAttachments };

package/dist/extension/lib/confirmations.d.ts

@@ -0,0 +1,26 @@
+import { type StateHandle } from "eve/context";
+import type { ApprovalConfiguration } from "eve/tools/approval";
+export declare const CONFIRMATION_TTL_MS: number;
+export interface ActionAnnotations {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly irreversibleHint?: boolean;
+    readonly idempotentHint?: boolean;
+}
+/** Safety comes from the authenticated ontology, never from the name or model prose. */
+export declare function needsConfirmation(labels: ActionAnnotations): boolean;
+export declare function inputHash(input: unknown): string;
+export interface Confirmation {
+    readonly memberId: string;
+    readonly action: string;
+    readonly inputHash: string;
+    readonly expiresAt: number;
+    readonly status: "pending" | "approved" | "consumed" | "cancelled";
+}
+export declare const confirmations: StateHandle<Record<string, Confirmation>>;
+/** Eve pauses the original call and rechecks this policy immediately before executing it. */
+export declare function actionApproval(options: {
+    readonly labels: (memberId: string, action: string, input: Readonly<Record<string, unknown>>) => Promise<ActionAnnotations>;
+    readonly state?: StateHandle<Record<string, Confirmation>>;
+    readonly now?: () => number;
+}): ApprovalConfiguration;

package/dist/extension/lib/confirmations.mjs

@@ -0,0 +1,96 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { memberIdOf } from "./telegram/principal.mjs";
+import { createHash } from "node:crypto";
+import { defineState } from "eve/context";
+const CONFIRMATION_TTL_MS = 6e5;
+function needsConfirmation(labels) {
+	return labels.readOnlyHint !== true && (labels.destructiveHint === true || labels.irreversibleHint === true || labels.destructiveHint === void 0 && labels.irreversibleHint === void 0);
+}
+function canonical(value) {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (typeof value === "object" && value !== null) return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+	const encoded = JSON.stringify(value);
+	if (encoded === void 0) throw new TypeError("Action input must be JSON.");
+	return encoded;
+}
+function inputHash(input) {
+	return createHash("sha256").update(canonical(input)).digest("hex");
+}
+const confirmations = defineState("segmentstream.confirmations", () => ({}));
+function actionApproval(options) {
+	const state = options.state ?? confirmations;
+	const now = options.now ?? Date.now;
+	const denied = (reason) => ({
+		type: "denied",
+		reason
+	});
+	return {
+		async request(ctx) {
+			const memberId = memberIdOf(ctx.session.auth.current);
+			if (memberId === void 0) return denied("A paired member is required.");
+			const hash = inputHash(ctx.toolInput ?? {});
+			const saved = state.get()[ctx.callId];
+			if (saved !== void 0) {
+				if (saved.memberId !== memberId || saved.action !== ctx.toolName || saved.inputHash !== hash) return denied("The confirmation belongs to another member, action or input.");
+				if (saved.expiresAt <= now()) return denied("The confirmation expired. Make a new call.");
+				if (saved.status === "consumed" || saved.status === "cancelled") return denied("The confirmation has already been used or cancelled.");
+			}
+			let labels;
+			try {
+				labels = await options.labels(memberId, ctx.toolName, ctx.toolInput ?? {});
+			} catch (error) {
+				console.warn("The ontology action permission check failed.", error);
+				return denied("The action is unavailable or the member no longer has permission.");
+			}
+			if (saved?.status === "approved") {
+				state.update((all) => ({
+					...all,
+					[ctx.callId]: {
+						...saved,
+						status: "consumed"
+					}
+				}));
+				return "approved";
+			}
+			if (saved !== void 0) return denied("The original call is waiting for its Confirm / Cancel buttons.");
+			if (!needsConfirmation(labels)) return "approved";
+			state.update((all) => ({
+				...all,
+				[ctx.callId]: {
+					memberId,
+					action: ctx.toolName,
+					inputHash: hash,
+					expiresAt: now() + CONFIRMATION_TTL_MS,
+					status: "pending"
+				}
+			}));
+			return "user-approval";
+		},
+		response(ctx) {
+			const saved = state.get()[ctx.request.callId];
+			const reject = (reason) => ({
+				status: "rejected",
+				reason
+			});
+			if (saved === void 0 || saved.status !== "pending") return reject("This confirmation is no longer pending.");
+			if (ctx.response.principal.attributes.confirmationRequestId !== ctx.request.requestId || ctx.response.principal.attributes.confirmationDecision !== ctx.response.decision) return reject("Use the Confirm or Cancel button on the action's message.");
+			if (memberIdOf(ctx.response.principal) !== saved.memberId || memberIdOf(ctx.request.principal) !== saved.memberId) return reject("Only the requesting member can confirm or cancel this action.");
+			if (saved.action !== ctx.request.toolName || saved.inputHash !== inputHash(ctx.request.toolInput ?? {})) return reject("The action or input changed. Make a new call.");
+			if (ctx.response.decision === "approve" && saved.expiresAt <= now()) return reject("This confirmation expired.");
+			state.update((all) => ({
+				...all,
+				[ctx.request.callId]: {
+					...saved,
+					status: ctx.response.decision === "approve" ? "approved" : "cancelled"
+				}
+			}));
+			return { status: "allowed" };
+		}
+	};
+}
+export { CONFIRMATION_TTL_MS, actionApproval, confirmations, inputHash, needsConfirmation };

package/dist/extension/lib/ontology-connection.d.ts

@@ -33,4 +33,5 @@ export declare function ontologyConnection(input: {
     readonly principal: SessionAuthContext | null;
     readonly environment?: Environment;
     readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
 }): McpClientConnectionDefinition | null;

package/dist/extension/lib/ontology-connection.mjs

@@ -6,7 +6,9 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin } from "./environment.mjs";
 import { memberIdOf } from "./telegram/principal.mjs";
+import { actionApproval } from "./confirmations.mjs";
 import { runtimeToken, tokenExpiry } from "./runtime-token.mjs";
+import { ontologyToolLabels } from "./ontology-tools.mjs";
 import { defineMcpClientConnection } from "eve/connections";
 const ACT_AS_HEADER = "X-SegmentStream-Act-As";
 const DESCRIPTION = "The company's ontology: its records, their history, and the actions that change them, narrowed to what the member you act for may read and do. Call describe for the catalog and me for the member.";
@@ -28,6 +30,7 @@ function ontologyConnection(input) {
 		url: `${origin}/mcp`,
 		description: DESCRIPTION,
 		instanceKey: `${origin}/mcp#member:${memberId}`,
+		approval: actionApproval({ labels: ontologyToolLabels(input) }),
 		auth: {
 			credentialOwner: "app",
 			getToken: async () => {

package/dist/extension/lib/ontology-tools.d.ts

@@ -0,0 +1,11 @@
+import type { ActionAnnotations } from "./confirmations.js";
+import { type Environment } from "./environment.js";
+import { type RuntimeToken } from "./runtime-token.js";
+/** A fresh, permission-filtered catalog. Listing tools cannot run an action's prepare step. */
+export declare function ontologyToolLabels(options?: {
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
+}): (memberId: string, action: string) => Promise<ActionAnnotations>;
+/** MCP normalizes an authored camelCase action to snake_case. */
+export declare function actionToolName(entity: string, action: string): string;

package/dist/extension/lib/ontology-tools.mjs

@@ -0,0 +1,41 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { appOrigin } from "./environment.mjs";
+import { runtimeToken } from "./runtime-token.mjs";
+function ontologyToolLabels(options = {}) {
+	return async (memberId, action) => {
+		const response = await (options.fetch ?? fetch)(`${appOrigin(options.environment ?? process.env)}/mcp`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${await (options.token ?? runtimeToken)()}`,
+				"X-SegmentStream-Act-As": memberId,
+				"content-type": "application/json",
+				accept: "application/json, text/event-stream",
+				"mcp-protocol-version": "2025-11-25"
+			},
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: "approval-tools",
+				method: "tools/list",
+				params: {}
+			}),
+			signal: AbortSignal.timeout(15e3),
+			redirect: "error"
+		});
+		if (!response.ok) throw new Error("Cannot check action permission.");
+		const body = await response.json();
+		const bareName = action.split("__").at(-1);
+		const tool = body.result?.tools?.find((candidate) => candidate.name === bareName);
+		if (tool === void 0) throw new Error("Action not permitted.");
+		return tool.annotations ?? {};
+	};
+}
+function actionToolName(entity, action) {
+	const snake = (name) => name.replace(/([A-Z])([A-Z][a-z])/g, "$1_$2").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+	return `${snake(entity)}_${snake(action)}`;
+}
+export { actionToolName, ontologyToolLabels };

package/dist/extension/lib/questions.d.ts

@@ -0,0 +1,14 @@
+export interface PendingQuestion {
+    readonly id: string;
+    readonly question: string;
+    readonly task: string;
+    readonly memberId: string;
+    readonly chatId: string;
+    readonly messageThreadId: string;
+    readonly address: string;
+}
+/** Intent survives turns and compaction in the session, independently of model history. */
+export declare const pendingQuestions: import("eve/context").StateHandle<Record<string, PendingQuestion>>;
+export declare function questionKey(question: Pick<PendingQuestion, "memberId" | "chatId" | "messageThreadId">): string;
+export declare function isPendingQuestion(value: unknown): value is PendingQuestion;
+export declare function answerMarker(id: string): string;