@segmentstream/agent 0.24.0 → 0.24.2

package/README.md

@@ -267,8 +267,9 @@ promotes it like any attachment. The ontology accepts that source from Ontology
 `segmentstream__attachments_stage` is the way in: given a chat attachment's `id`, or a record's
 `entity`, `id` and optional `property`, the runtime reads the file as the member through the same
 grants as `attachments_read`, checks its SHA-256 and writes it to
-`/workspace/.segmentstream/files/<first 16 hex of the digest>/<safe name>`, answering the path. No
-URL, header or credential enters the sandbox. `segmentstream__read_file` keeps eve's model output,
+`/workspace/.segmentstream/files/<first 16 hex of the digest>/<safe name>`, answering the path. A
+stored file staged again is granted again but not transferred while that path holds the same
+SHA-256. No URL, header or credential enters the sandbox. `segmentstream__read_file` keeps eve's model output,
 so PNG, JPEG, GIF and WebP images up to 3 MiB and PDFs up to 20 MiB reach the model as files.
 
 For a script-generated JSON payload, use `segmentstream__ontology_call_file` with the bare tool

package/dist/_chunks/{build-metadata-DDV7Rc51.mjs → build-metadata-BvsLNBnp.mjs}

@@ -4,7 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-var version = "0.24.0";
+var version = "0.24.2";
 function agentBuild(environment = process.env) {
 	return {
 		agent: version,

package/dist/extension/lib/build-metadata.mjs

@@ -4,5 +4,5 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import { t as agentBuild } from "../../_chunks/build-metadata-DDV7Rc51.mjs";
+import { t as agentBuild } from "../../_chunks/build-metadata-BvsLNBnp.mjs";
 export { agentBuild };

package/dist/extension/lib/confirmation-description.d.ts

@@ -16,6 +16,11 @@ export interface ConfirmationDescription {
     readonly chatPost?: ChatPostPreview;
     readonly warning?: boolean;
 }
+/** A target the card cannot name, by its field's safe label, so the model learns which one and why. */
+export declare class UnsafeConfirmationTarget extends Error {
+    readonly label: string;
+    constructor(label: string);
+}
 export declare function object(value: unknown): Record<string, unknown>;
 export declare function humanize(value: string): string;
 /** Reject machine identifiers and structured data even in authored labels or resolved titles. */

package/dist/extension/lib/confirmation-description.mjs

@@ -5,6 +5,14 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { isTechnicalText } from "./customer-text-safety.mjs";
+var UnsafeConfirmationTarget = class extends Error {
+	label;
+	constructor(label) {
+		super(`Every confirmation target requires an authorized, safe record title: ${label}.`);
+		this.label = label;
+		this.name = "UnsafeConfirmationTarget";
+	}
+};
 function object(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
 }
@@ -16,7 +24,7 @@ function humanText(value, maximum = 180) {
 	const text = value.trim();
 	if (text === "" || text.length > maximum || isTechnicalText(text) || [
 		/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}<>`*_~|\\\[\]{}]|^(?:#{1,6}|[-+])\s/u,
-		/[a-z][a-z0-9+.-]*:\/\/|www\.|\b[a-z][a-z0-9]*\.[a-z][a-z_0-9]*\b/iu,
+		/[a-z][a-z0-9+.-]*:\/\/|www\.|\b[a-z][a-z0-9]*\.[a-z][a-z_0-9]+\b/iu,
 		/&(?:#\d+|#x[0-9a-f]+|[a-z]+);/iu,
 		/\bBearer\s+|\b(?:password|secret|token|credential|api[ _-]?key)\s*[:=]/iu,
 		/\b(?:sk|ssw|ghp)[_-][a-z0-9]+/iu,
@@ -70,7 +78,7 @@ async function describeConfirmation(input) {
 					const value = (await read.get(cacheKey))?.[target.title];
 					title = value === item ? void 0 : factText(value, 3584);
 				}
-				if (title === void 0) throw new Error("Every confirmation target requires an authorized, safe record title.");
+				if (title === void 0) throw new UnsafeConfirmationTarget(label);
 				values.push(title);
 				targets.push({
 					label,
@@ -100,4 +108,4 @@ async function describeConfirmation(input) {
 		...targets.length === 0 ? {} : { targets }
 	};
 }
-export { describeConfirmation, fieldSchema, humanText, humanize, object };
+export { UnsafeConfirmationTarget, describeConfirmation, fieldSchema, humanText, humanize, object };

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

@@ -1,7 +1,7 @@
 import { type StateHandle } from "eve/context";
 import type { ApprovalConfiguration } from "eve/tools/approval";
 import { type OntologyActor } from "./actor.js";
-import type { ConfirmationDescription } from "./confirmation-description.js";
+import { type ConfirmationDescription } from "./confirmation-description.js";
 import { type ConfirmationCopy } from "./telegram/confirmation-text.js";
 import { type TelegramTexts } from "./telegram/texts.js";
 export declare const CONFIRMATION_TTL_MS: number;

package/dist/extension/lib/confirmations.mjs

@@ -6,6 +6,7 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { withTelegramTexts } from "./telegram/texts.mjs";
 import { i as memberIdOf } from "../../_chunks/principal-DMNXj4PX.mjs";
+import { UnsafeConfirmationTarget } from "./confirmation-description.mjs";
 import { confirmationCopy, confirmationLocale, renderConfirmation } from "./telegram/confirmation-text.mjs";
 import { chatPostCard } from "./telegram/chat-post-card.mjs";
 import { actorOf, member } from "./actor.mjs";
@@ -100,6 +101,7 @@ function actionApproval(options) {
 				if (description === void 0) throw new Error("A trusted confirmation description is required.");
 			} catch (error) {
 				console.warn("The confirmation description could not be read.", error);
+				if (error instanceof UnsafeConfirmationTarget) return denied(`No confirmation card can name the ${error.label}: its title is missing, unreadable, or looks like a file name, link or identifier. Another call will be refused the same way; tell the member, who can rename that record or make the change in the app.`);
 				return denied("Trusted confirmation facts are incomplete, unsafe or too long. Resolve every target title and narrow the input before making a new call.");
 			}
 			description = description === void 0 ? void 0 : {

package/dist/extension/lib/conversation-runtime.mjs

@@ -127,7 +127,20 @@ function conversationRecorder(archive = conversations(), closing = async (messag
 				errorText: contentText(event.data.error?.message, CONTENT_CAPS.error)
 			}));
 			if (event.type === "turn.settled" || event.type === "session.ended") await recordModelServiceAlert(archive, base, event.data.error);
-		} else if (event.type === "content.completed" && event.data.kind === "text" && event.data.phase === "reply" && !event.data.interrupted) {
+		} else if (event.type === "model.retried") await archive.append(conversationEvent({
+			...base,
+			eventId,
+			kind: "decision",
+			decision: "silent",
+			reason: event.type,
+			status: "failed",
+			argsSummary: JSON.stringify({
+				attempt: event.data.attempt,
+				...typeof event.data.error?.code === "string" ? { code: event.data.error.code } : {}
+			}),
+			errorText: contentText(event.data.error?.message, CONTENT_CAPS.error)
+		}));
+		else if (event.type === "content.completed" && event.data.kind === "text" && event.data.phase === "reply" && !event.data.interrupted) {
 			const message = typeof event.data.value === "string" ? event.data.value : "";
 			const kind = completionKind(message);
 			const silent = kind !== "reply";

package/dist/extension/lib/stored-files.d.ts

@@ -1,17 +1,32 @@
 import type { SessionAuthContext } from "eve/context";
 import { ontologyTools } from "./ontology-tools.js";
+/** A stored file's immutable revision metadata, as its download grant states it. */
+export interface StoredFile {
+    readonly id: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly sha256: string;
+}
 /** A permanent blob is read through the same current-member grant used by the ontology UI. */
 export declare function readStoredFile(input: {
     readonly entity: string;
     readonly id: string;
     readonly property?: string;
 }, principal: SessionAuthContext | null, options?: Parameters<typeof ontologyTools>[0]): Promise<{
-    attachment: {
-        id: string;
-        filename: string;
-        contentType: string;
-        size: number;
-        sha256: string;
-    };
-    bytes: Buffer<ArrayBuffer>;
+    attachment: StoredFile;
+    bytes: Buffer<ArrayBufferLike>;
+}>;
+/**
+ * The member's current grant for a stored file: its revision metadata at once, and its bytes only
+ * when read. Every call checks the member's access; a caller that already holds bytes with the
+ * same digest need not transfer them again.
+ */
+export declare function storedFileGrant(input: {
+    readonly entity: string;
+    readonly id: string;
+    readonly property?: string;
+}, principal: SessionAuthContext | null, options?: Parameters<typeof ontologyTools>[0]): Promise<{
+    readonly file: StoredFile;
+    read(): Promise<Buffer>;
 }>;

package/dist/extension/lib/stored-files.mjs

@@ -11,6 +11,13 @@ import { member } from "./actor.mjs";
 import { OntologyFileUnavailable, ontologyTools } from "./ontology-tools.mjs";
 import { createHash } from "node:crypto";
 async function readStoredFile(input, principal, options = {}) {
+	const grant = await storedFileGrant(input, principal, options);
+	return {
+		attachment: grant.file,
+		bytes: await grant.read()
+	};
+}
+async function storedFileGrant(input, principal, options = {}) {
 	const memberId = memberIdOf(principal);
 	if (memberId === void 0) throw new Error("A current member is required to read a stored file.");
 	const tools = ontologyTools({
@@ -33,48 +40,52 @@ async function readStoredFile(input, principal, options = {}) {
 	const headers = object(grant.headers);
 	const size = file.size;
 	const secrets = new Set([...typeof grant.url === "string" ? [grant.url] : [], ...Object.values(headers).filter((value) => typeof value === "string")]);
-	try {
-		if (file.id !== input.id || file.entity !== input.entity || file.property !== (input.property ?? "content") || grant.method !== "GET" || typeof file.filename !== "string" || typeof file.content_type !== "string" || typeof file.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(file.sha256) || typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || size > 26214400 || typeof grant.url !== "string" || new URL(grant.url).protocol !== "https:" || Object.values(headers).some((value) => typeof value !== "string")) throw new Error("The stored file grant or bounded metadata is invalid.", { cause: {
-			file,
-			download: grant
-		} });
-		const response = await (options.fetch ?? fetch)(grant.url, {
-			method: "GET",
-			headers: Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, String(value)])),
-			redirect: "error",
-			signal: AbortSignal.timeout(12e4)
-		});
-		if (!response.ok || response.body === null) throw new Error(`Stored file transfer refused (HTTP ${response.status}).`);
-		const reader = response.body.getReader(), chunks = [];
-		let received = 0;
-		try {
-			for (;;) {
-				const chunk = await reader.read();
-				if (chunk.done) break;
-				received += chunk.value.byteLength;
-				if (received > size) throw new Error("Stored file transfer exceeded its declared size.");
-				chunks.push(chunk.value);
+	const unreadable = (error) => new Error("The permanent file could not be read.", { cause: redactDiagnostic(error, secrets) });
+	if (file.id !== input.id || file.entity !== input.entity || file.property !== (input.property ?? "content") || grant.method !== "GET" || typeof file.filename !== "string" || typeof file.content_type !== "string" || typeof file.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(file.sha256) || typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || size > 26214400 || typeof grant.url !== "string" || !URL.canParse(grant.url) || new URL(grant.url).protocol !== "https:" || Object.values(headers).some((value) => typeof value !== "string")) throw unreadable(new Error("The stored file grant or bounded metadata is invalid.", { cause: {
+		file,
+		download: grant
+	} }));
+	const url = grant.url, sha256 = file.sha256;
+	return {
+		file: {
+			id: input.id,
+			filename: file.filename,
+			contentType: file.content_type,
+			size,
+			sha256
+		},
+		async read() {
+			try {
+				const response = await (options.fetch ?? fetch)(url, {
+					method: "GET",
+					headers: Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, String(value)])),
+					redirect: "error",
+					signal: AbortSignal.timeout(12e4)
+				});
+				if (!response.ok || response.body === null) throw new Error(`Stored file transfer refused (HTTP ${response.status}).`);
+				const reader = response.body.getReader(), chunks = [];
+				let received = 0;
+				try {
+					for (;;) {
+						const chunk = await reader.read();
+						if (chunk.done) break;
+						received += chunk.value.byteLength;
+						if (received > size) throw new Error("Stored file transfer exceeded its declared size.");
+						chunks.push(chunk.value);
+					}
+				} finally {
+					await reader.cancel().catch((error) => {
+						console.warn("Stored file reader cleanup failed.", redactDiagnostic(error, secrets));
+					});
+					reader.releaseLock();
+				}
+				const bytes = Buffer.concat(chunks);
+				if (bytes.byteLength !== size || createHash("sha256").update(bytes).digest("hex") !== sha256) throw new Error("Stored file bytes differ from their immutable revision metadata.");
+				return bytes;
+			} catch (error) {
+				throw unreadable(error);
 			}
-		} finally {
-			await reader.cancel().catch((error) => {
-				console.warn("Stored file reader cleanup failed.", redactDiagnostic(error, secrets));
-			});
-			reader.releaseLock();
 		}
-		const bytes = Buffer.concat(chunks);
-		if (bytes.byteLength !== size || createHash("sha256").update(bytes).digest("hex") !== file.sha256) throw new Error("Stored file bytes differ from their immutable revision metadata.");
-		return {
-			attachment: {
-				id: input.id,
-				filename: file.filename,
-				contentType: file.content_type,
-				size,
-				sha256: file.sha256
-			},
-			bytes
-		};
-	} catch (error) {
-		throw new Error("The permanent file could not be read.", { cause: redactDiagnostic(error, secrets) });
-	}
+	};
 }
-export { readStoredFile };
+export { readStoredFile, storedFileGrant };

package/dist/extension/lib/telegram/adapter.mjs

@@ -24,7 +24,7 @@ import { MAXIMUM_DOWNLOAD_BYTES, connectionProxy } from "../connection-proxy.mjs
 import { dispatchStructuredMessage, structuredMessage } from "./structured.mjs";
 import { scopedAddress, sessionPolicy } from "./sessions.mjs";
 import { handleWorkspaceCallback, isWorkspaceCallback } from "./callbacks.mjs";
-import { t as agentBuild } from "../../../_chunks/build-metadata-DDV7Rc51.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-BvsLNBnp.mjs";
 import { attachmentLifecycle } from "./lifecycle.mjs";
 import { gatewayImageDescriber } from "./images.mjs";
 import { gatewayAttachmentDescriber } from "./attachment-description.mjs";

package/dist/extension/lib/telegram/health.mjs

@@ -5,7 +5,7 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { runtimeRequestFailure } from "./runtime-request.mjs";
-import { t as agentBuild } from "../../../_chunks/build-metadata-DDV7Rc51.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-BvsLNBnp.mjs";
 import { GET } from "eve/channels";
 const HEALTH_ROUTE = "/eve/v1/telegram/health";
 function healthRoute(input) {

package/dist/extension/lib/telegram/lifecycle.mjs

@@ -10,7 +10,7 @@ import { n as currentInboundRequest, p as reportTelegramError } from "../../../_
 import { member } from "../actor.mjs";
 import { needsConfirmation } from "../confirmations.mjs";
 import { OntologyActionNotPermitted, actionToolName, ontologyTools } from "../ontology-tools.mjs";
-import { t as agentBuild } from "../../../_chunks/build-metadata-DDV7Rc51.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-BvsLNBnp.mjs";
 var AttachmentLifecycleNotPermitted = class extends Error {
 	code = "attachment_lifecycle_not_permitted";
 };

package/dist/extension/tools/attachments_stage.d.ts

@@ -3,7 +3,8 @@
  * so scripts can work on its bytes: a chat attachment by id, or a permanent record's file by entity
  * and record id. The runtime reads it as the member, through the same grants as
  * `attachments_read`, checks its SHA-256 and writes it under `/workspace/.segmentstream/files/`.
- * No URL, header or credential enters the sandbox. The way back is `attachments_promote` with a
+ * A stored file is granted on every call, but its bytes are not transferred again while its digest
+ * path in the sandbox holds the same SHA-256. No URL, header or credential enters the sandbox. The way back is `attachments_promote` with a
  * path. Offered only when the sandbox is on, and never to a task session, which has no member
  * files.
  */

package/dist/extension/tools/attachments_stage.mjs

@@ -9,7 +9,7 @@ import segmentstream from "../extension.mjs";
 import { actorOf } from "../lib/actor.mjs";
 import { sessionSandbox } from "../lib/sandbox-session.mjs";
 import { attachmentOwner, optionalString, stringArgument, toolAttachments } from "../lib/attachment-tools.mjs";
-import { readStoredFile } from "../lib/stored-files.mjs";
+import { storedFileGrant } from "../lib/stored-files.mjs";
 import { createHash } from "node:crypto";
 import { posix } from "node:path";
 import { defineDynamic, defineTool } from "eve/tools";
@@ -21,6 +21,15 @@ function stagedFileName(filename) {
 	const stem = (dot > 0 ? base.slice(0, dot) : base).normalize("NFKD").replace(/[^\w.-]+/g, "_").replace(/^[._-]+|[._-]+$/g, "").slice(0, 120);
 	return `${stem === "" ? "file" : stem}${extension}`;
 }
+async function holds(sandbox, path, sha256) {
+	try {
+		const hashed = await sandbox.run({ command: `sha256sum -- '${path.replaceAll("'", `'\\''`)}' 2>/dev/null` });
+		return hashed.exitCode === 0 && hashed.stdout.slice(0, 64) === sha256;
+	} catch (error) {
+		console.warn("A staged file could not be checked; staging it again.", error);
+		return false;
+	}
+}
 function stagedFilePath(sha256, filename) {
 	return `${STAGED_FILES_DIRECTORY}/${sha256.slice(0, 16)}/${stagedFileName(filename)}`;
 }
@@ -51,27 +60,51 @@ const tool = defineTool({
 		const entity = optionalString(input, "entity");
 		const property = optionalString(input, "property");
 		if (entity === void 0 && property !== void 0) throw new TypeError("property requires entity.");
-		const { attachment, bytes } = entity === void 0 ? await toolAttachments().read(attachmentOwner({
-			principal: ctx.session.auth.current,
-			sessionId: ctx.session.id
-		}), id) : await readStoredFile({
-			entity,
-			id,
-			...property === void 0 ? {} : { property }
-		}, ctx.session.auth.current);
-		const sha256 = createHash("sha256").update(bytes).digest("hex");
-		if (sha256 !== attachment.sha256) throw new Error("The file's bytes differ from its recorded SHA-256; nothing was staged.");
-		const path = stagedFilePath(sha256, attachment.filename);
-		await (await sessionSandbox(ctx)).writeBinaryFile({
-			path,
-			content: bytes
-		});
+		const sandboxOf = () => sessionSandbox(ctx);
+		let staged;
+		if (entity === void 0) {
+			const { attachment, bytes } = await toolAttachments().read(attachmentOwner({
+				principal: ctx.session.auth.current,
+				sessionId: ctx.session.id
+			}), id);
+			const sha256 = createHash("sha256").update(bytes).digest("hex");
+			if (sha256 !== attachment.sha256) throw new Error("The file's bytes differ from its recorded SHA-256; nothing was staged.");
+			const path = stagedFilePath(sha256, attachment.filename);
+			await (await sandboxOf()).writeBinaryFile({
+				path,
+				content: bytes
+			});
+			staged = {
+				path,
+				file: {
+					...attachment,
+					size: bytes.byteLength
+				}
+			};
+		} else {
+			const grant = await storedFileGrant({
+				entity,
+				id,
+				...property === void 0 ? {} : { property }
+			}, ctx.session.auth.current);
+			const path = stagedFilePath(grant.file.sha256, grant.file.filename);
+			const sandbox = await sandboxOf();
+			if (!await holds(sandbox, path, grant.file.sha256)) await sandbox.writeBinaryFile({
+				path,
+				content: await grant.read()
+			});
+			staged = {
+				path,
+				file: grant.file
+			};
+		}
+		const { path, file } = staged;
 		return workflowToolResult({
 			path,
-			filename: attachment.filename,
-			content_type: attachment.contentType,
-			size: bytes.byteLength,
-			sha256,
+			filename: file.filename,
+			content_type: file.contentType,
+			size: file.size,
+			sha256: file.sha256,
 			...entity === void 0 ? { attachment_id: id } : {
 				entity,
 				record_id: id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "Mount a SegmentStream workspace's agent on eve: the ontology as tools, acting as the member who writes, and Telegram through the workspace's connection.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
@@ -74,7 +74,7 @@
   },
   "dependencies": {
     "@chat-adapter/telegram": "4.41.0",
-    "@segmentstream-cloud/ontology": "0.78.0",
+    "@segmentstream-cloud/ontology": "0.79.0",
     "@vercel/oidc": "^3.8.4",
     "ai": "^7.0.137",
     "csv-parse": "^7.0.3",