@segmentstream/agent 0.21.7 → 0.22.0

package/README.md

@@ -264,6 +264,14 @@ Eve has no public connection API for reading arguments from a sandbox file. This
 has no discovery or inline-call API; ordinary calls use Eve. Chat posting is excluded.
 File-taking actions remain reachable through `segmentstream__attachments_promote`.
 
+Set `save_result: true` on that file call to save a permitted read-only tool's exact JSON response
+in the same session's verified sandbox. The response gives a generated `result_file`, byte size,
+SHA-256 and query/paging metadata, without copying rows through the model. This mode refuses write
+tools before dispatch and checks their read-only annotation again at execution. Files are limited
+to 8 MiB; the query's existing permissions and bounds still apply. A file's row count covers that
+result only: follow continuations or split truncated aggregate groups into disjoint filters before
+combining and deduplicating them with a script. The file is temporary, like the sandbox itself.
+
 Under `eve dev` the sandbox is a Vercel Sandbox too and needs local Vercel credentials; without
 them the sandbox tools, and turns carrying files, fail.
 

package/dist/_chunks/{build-metadata-96xS1MkA.mjs → build-metadata-B_3wcMyz.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.21.7";
+var version = "0.22.0";
 function agentBuild(environment = process.env) {
 	return {
 		agent: version,

package/dist/extension/instructions/sandbox.mjs

@@ -25,6 +25,12 @@ Downloads and package installs fail. For reading one file or exact totals over o
   Discover the target's schema through Eve first. Write the complete object to the file; never
   retype calculated amounts, dates or digests. The call snapshots the file before approval.
   Ordinary inline calls and chat posting use Eve's native ontology connection.
+- To combine or deduplicate large ontology read results with a script, set \`save_result: true\`
+  on \`segmentstream__ontology_call_file\`. Write the normal read arguments into its JSON file;
+  the tool saves the exact response in this sandbox and returns \`result_file\`, its SHA-256 and
+  paging metadata. Scripts can read that JSON directly; do not retype rows. This mode accepts only
+  permitted read-only tools. A saved result's row count covers that result only. Follow its cursor
+  or split truncated aggregate groups into disjoint filters, verify coverage, then combine files.
 - A command still running after 30 seconds keeps running and returns status "running" with a
   directory under /tmp/.eve/jobs; check its stdout and exit files with later commands. Output over
   50 KiB is truncated: write large output to a file and read it in parts.

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-96xS1MkA.mjs";
+import { t as agentBuild } from "../../_chunks/build-metadata-B_3wcMyz.mjs";
 export { agentBuild };

package/dist/extension/lib/ontology-file-call.d.ts

@@ -2,6 +2,7 @@ import type { TelegramTexts } from "./telegram/texts.js";
 export interface FileCall {
     readonly name: string;
     readonly arguments_file: string;
+    readonly save_result?: boolean;
 }
 export declare function releaseOntologyFilePayloads(): void;
 /** Eve has no public API for supplying connection arguments from a sandbox file. Keep this

package/dist/extension/lib/ontology-file-call.mjs

@@ -10,6 +10,7 @@ import { isChatPost } from "./chat-post-confirmation.mjs";
 import { actionApproval, confirmations, inputHash } from "./confirmations.mjs";
 import { ontologyTools } from "./ontology-tools.mjs";
 import { sandboxFile } from "./sandbox-session.mjs";
+import { saveOntologyResult } from "./ontology-result-file.mjs";
 import { defineState } from "eve/context";
 import { defineTool } from "eve/tools";
 const snapshots = defineState("segmentstream.ontologyFiles", () => ({}));
@@ -41,7 +42,9 @@ function ontologyFileCall(texts) {
 	const policy = (principal) => actionApproval({
 		labels: async (actor, _action, input) => {
 			const saved = bound(input, ownerOf(actor));
-			return ontologyTools({ principal }).labels(actor, saved.name, saved.arguments);
+			const labels = await ontologyTools({ principal }).labels(actor, saved.name, saved.arguments);
+			if (saved.saveResult && labels.readOnlyHint !== true) throw new Error("Saving a result requires a permitted read-only ontology tool.");
+			return labels;
 		},
 		describe: async (actor, _action, input) => {
 			const saved = bound(input, ownerOf(actor));
@@ -67,7 +70,7 @@ function ontologyFileCall(texts) {
 	}
 	return defineTool({
 		deferred: true,
-		description: "Call an ontology tool with the complete JSON object computed in a sandbox file. Use only for script-generated arguments that must not be retyped. Find the real tool and its schema through Eve search first; ordinary inline calls use Eve directly. Chat posting is excluded.",
+		description: "Call an ontology tool with the complete JSON object computed in a sandbox file. Use for script-generated arguments, or set save_result to save a permitted read's exact JSON result in the isolated sandbox for scripts, without copying rows through the model. Find the real tool and its schema through Eve search first; ordinary inline calls use Eve. Chat posting is excluded. Saving a result never permits a write tool or expands query limits.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -79,6 +82,10 @@ function ontologyFileCall(texts) {
 				arguments_file: {
 					type: "string",
 					description: "Absolute path of a JSON object inside /workspace; maximum 1 MiB."
+				},
+				save_result: {
+					type: "boolean",
+					description: "For read-only tools, save the exact result as JSON in this session's sandbox and return its generated path, digest and paging metadata instead of the rows. Maximum 8 MiB."
 				}
 			},
 			required: ["name", "arguments_file"],
@@ -105,7 +112,8 @@ function ontologyFileCall(texts) {
 								requestHash: inputHash(input),
 								name: input.name,
 								digest: inputHash(args),
-								arguments: args
+								arguments: args,
+								...input.save_result === true ? { saveResult: true } : {}
 							}
 						}));
 					}
@@ -151,6 +159,7 @@ function ontologyFileCall(texts) {
 			const saved = bound(request(ctx.callId, input, owner), owner);
 			const confirmation = confirmations.get()[ctx.callId];
 			if (confirmation !== void 0 && confirmation.status !== "consumed") throw new Error("The file call has not been confirmed.");
+			if (saved.saveResult && (await ontologyTools({ principal: ctx.session.auth.current }).labels(actor, saved.name, saved.arguments)).readOnlyHint !== true) throw new Error("Saving a result requires a permitted read-only ontology tool.");
 			const result = await ontologyTools({
 				principal: ctx.session.auth.current,
 				envelope: runtimeEnvelope({
@@ -169,7 +178,8 @@ function ontologyFileCall(texts) {
 				name: saved.name,
 				arguments: saved.arguments
 			});
-			return result.structuredContent ?? result;
+			const output = result.structuredContent ?? result;
+			return saved.saveResult ? saveOntologyResult(ctx, output) : output;
 		}
 	});
 }

package/dist/extension/lib/ontology-result-file.d.ts

@@ -0,0 +1,10 @@
+import { type SandboxContext } from "./sandbox-session.js";
+/** Exact, caller-authorized read data goes only into the same session's verified sandbox.
+ * The generated directory cannot be chosen by a prompt or overwrite an authored file. */
+export declare function saveOntologyResult(context: SandboxContext, result: unknown): Promise<{
+    row_count?: number | undefined;
+    row_count_scope?: string | undefined;
+    result_file: string;
+    bytes: number;
+    sha256: string;
+}>;

package/dist/extension/lib/ontology-result-file.mjs

@@ -0,0 +1,46 @@
+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 { sessionSandbox } from "./sandbox-session.mjs";
+import { createHash, randomUUID } from "node:crypto";
+const MAXIMUM_BYTES = 8388608;
+const METADATA = [
+	"deploymentId",
+	"definitionDigest",
+	"fields",
+	"execution",
+	"truncated",
+	"next_cursor",
+	"nextCursor",
+	"page_count",
+	"page_count_scope",
+	"total_scope"
+];
+async function saveOntologyResult(context, result) {
+	const content = JSON.stringify(result);
+	if (content === void 0) throw new TypeError("The ontology read returned no JSON result.");
+	const bytes = Buffer.byteLength(content, "utf8");
+	if (bytes > MAXIMUM_BYTES) throw new RangeError("The ontology read result exceeds 8 MiB; request smaller groups or pages.");
+	const sandbox = await sessionSandbox(context);
+	const path = `/workspace/.segmentstream/results/${randomUUID()}/result.json`;
+	await sandbox.writeTextFile({
+		path,
+		content
+	});
+	const value = result !== null && typeof result === "object" && !Array.isArray(result) ? result : {};
+	const rows = Array.isArray(value.rows) ? value.rows : Array.isArray(value.items) ? value.items : void 0;
+	return {
+		result_file: path,
+		bytes,
+		sha256: createHash("sha256").update(content).digest("hex"),
+		...rows === void 0 ? {} : {
+			row_count: rows.length,
+			row_count_scope: "result"
+		},
+		...Object.fromEntries(METADATA.filter((key) => value[key] !== void 0).map((key) => [key, value[key]]))
+	};
+}
+export { saveOntologyResult };

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-96xS1MkA.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-B_3wcMyz.mjs";
 import { attachmentLifecycle } from "./lifecycle.mjs";
 import { observedMessages } from "./observed.mjs";
 import { expireDeferredCards, handleDeferredCallback, isDeferredCallback } from "./deferred-confirmations.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-96xS1MkA.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-B_3wcMyz.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-96xS1MkA.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-B_3wcMyz.mjs";
 var AttachmentLifecycleNotPermitted = class extends Error {
 	code = "attachment_lifecycle_not_permitted";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.21.7",
+  "version": "0.22.0",
   "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",