@segmentstream/agent 0.8.6 → 0.8.8

package/README.md

@@ -609,6 +609,25 @@ Such a failure must not become an HTTP success with no queued work.
 
 ### Legacy held approvals
 
+Deferred mode supplies four eager tools: `segmentstream__ontology_discover`,
+`segmentstream__ontology_describe`, `segmentstream__ontology_inspect` and `segmentstream__ontology_call`. Registration
+does not fetch the full ontology catalog. Discovery and descriptions remain
+permission-filtered reads; descriptions provide the exact `tool_name` and input
+schema for execution. Calls retain the same member-bound deferred confirmation
+boundary. Metadata failures are reported by the tool instead of removing the
+entire ontology surface from the turn.
+The inspector exposes the full member-permitted input schemas for ordinary record
+find/get/history operations on demand. Describe/discover accept `expected_hash`
+to reject mixed ontology versions.
+
+With `attachmentLifecycle.contextVersion: 2`, lifecycle data includes `source_at` when Telegram provides its
+original message timestamp, so a workspace can group related uploads despite
+serial webhook delivery delays. A completion hook receives the model's `reply`
+alongside its intake key, allowing workspace-owned status copy to retain an
+actionable explanation. Reply delivery carries the owning turn's reply anchor
+explicitly after restore. Omitting the version preserves existing closed lifecycle
+data schemas; workspaces opt in only after their hook accepts the additional fields.
+
 Explicit `confirmations.mode: "held"` overrides the deferred default. Switching a package version
 does not migrate already-running held turns. In deferred mode the Telegram adapter reads the owning session's
 recorded approval inputs and requests cancellation of that exact turn before admitting a new

package/dist/_chunks/{build-metadata-BIjXU_y3.mjs → build-metadata-CRUM3DfA.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.8.6";
+var version = "0.8.8";
 function agentBuild(environment = process.env) {
 	return {
 		agent: version,

package/dist/extension/config.d.ts

@@ -47,7 +47,8 @@ export interface AdmissionSettings {
 }
 /**
  * `agent/segmentstream.json` as authored. A JSON import widens string literals to `string` and
- * `false` to `boolean`, so the accepted types are wider than the values validation allows.
+ * `false` to `boolean` and numeric literals to `number`, so the accepted types are wider than
+ * the values validation allows.
  */
 export interface SegmentStreamAgentConfigInput {
     readonly firstContact?: FirstContactSettings;
@@ -63,7 +64,9 @@ export interface SegmentStreamAgentConfigInput {
             readonly linkPreviews?: string;
             /** Additional exact HTTP(S) origins belonging to this workspace. */
             readonly additionalOwnOrigins?: readonly string[];
-            readonly attachmentLifecycle?: AttachmentLifecycle;
+            readonly attachmentLifecycle?: Omit<AttachmentLifecycle, "contextVersion"> & {
+                readonly contextVersion?: number;
+            };
         };
     };
     readonly models?: {

package/dist/extension/config.mjs

@@ -95,13 +95,25 @@ function telegramSettings(value, issues) {
 	const lifecycle = section({
 		value: telegram.attachmentLifecycle,
 		path: [...path, "attachmentLifecycle"],
-		allowed: ["entity", "action"],
+		allowed: [
+			"entity",
+			"action",
+			"contextVersion"
+		],
 		issues
 	});
 	if (lifecycle !== void 0 && ["entity", "action"].some((key) => typeof lifecycle[key] !== "string" || !/^(?:[a-z][a-zA-Z0-9]*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/.test(String(lifecycle[key])))) issues.push({
 		message: "must name a valid ontology entity and action",
 		path: [...path, "attachmentLifecycle"]
 	});
+	if (lifecycle?.contextVersion !== void 0 && lifecycle.contextVersion !== 2) issues.push({
+		message: "must be 2 when specified",
+		path: [
+			...path,
+			"attachmentLifecycle",
+			"contextVersion"
+		]
+	});
 	return typeof connection === "string" && isTelegramPolicy(policy) ? {
 		connection,
 		policy,
@@ -109,7 +121,8 @@ function telegramSettings(value, issues) {
 		additionalOwnOrigins,
 		...lifecycle === void 0 ? {} : { attachmentLifecycle: {
 			entity: String(lifecycle.entity),
-			action: String(lifecycle.action)
+			action: String(lifecycle.action),
+			...lifecycle.contextVersion === 2 ? { contextVersion: 2 } : {}
 		} }
 	} : null;
 }

package/dist/extension/instructions.md

@@ -3,7 +3,15 @@
 You are the workspace's agent on SegmentStream. Every conversation runs as the member who is
 talking to you, and you act with exactly their permissions.
 
-- The company's records live in the ontology, reached through `segmentstream__ontology`.
+- The company's records live in the ontology. With deferred confirmations, use
+  `segmentstream__ontology_discover` to search permitted definitions,
+  `segmentstream__ontology_describe` to inspect their refs and schemas, and
+  `segmentstream__ontology_call` to run their exact `tool_name` with schema-matching arguments.
+  For record reads (find/get/history), use `segmentstream__ontology_inspect` to discover
+  exact MCP names and input schemas. Pass returned ontology hashes as `expected_hash`
+  on subsequent describe/discover requests so a redeployment cannot mix definitions.
+  These tools are directly available; do not search a connection namespace to find them.
+  With held confirmations the same operations are reached through `segmentstream__ontology`.
   Call `me` when you need to check whom you act for. For an unfamiliar task, call `describe`
   without a ref for a compact entity index, or `discover` to search names and descriptions.
   Inspect relevant `entity:`, `action:`, or `measure:` refs with `describe` for their complete

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

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

@@ -0,0 +1,20 @@
+import type { ToolContext } from "eve/tools";
+import { ontologyTools } from "./ontology-tools.js";
+type Options = Omit<NonNullable<Parameters<typeof ontologyTools>[0]>, "principal">;
+/** Metadata is requested only when the model uses it, never while registering its tools. */
+export declare function ontologyMetadata(memberId: string, operation: "describe" | "discover", input: Record<string, unknown>, context: ToolContext, options?: Options): Promise<Record<string, unknown>>;
+/** Ordinary record operations are not part of entity/action discovery. Inspect their
+ * real member-filtered MCP schemas on demand, never during dynamic registration. */
+export declare function ontologyInspect(memberId: string, input: {
+    name?: string;
+    query?: string;
+    after?: string;
+    limit?: number;
+}, context: ToolContext, options?: Options): Promise<{
+    next_after?: string | undefined;
+    tools: {
+        name: string;
+        description: string;
+    }[];
+}>;
+export {};

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

@@ -0,0 +1,44 @@
+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 { object } from "./confirmation-description.mjs";
+import { ontologyTools } from "./ontology-tools.mjs";
+async function ontologyMetadata(memberId, operation, input, context, options = {}) {
+	const principal = context.session.auth.current;
+	if (memberIdOf(principal) !== memberId) throw new Error("The ontology tool belongs to another member.");
+	const result = await ontologyTools({
+		...options,
+		principal
+	}).rpc(memberId, "tools/call", {
+		name: operation,
+		arguments: input
+	});
+	return result.structuredContent === void 0 ? result : object(result.structuredContent);
+}
+async function ontologyInspect(memberId, input, context, options = {}) {
+	const principal = context.session.auth.current;
+	if (memberIdOf(principal) !== memberId) throw new Error("The ontology tool belongs to another member.");
+	const tools = (await ontologyTools({
+		...options,
+		principal
+	}).list(memberId)).flatMap((tool) => typeof tool.name === "string" ? [{
+		...tool,
+		name: tool.name,
+		description: String(tool.description ?? "")
+	}] : []);
+	const words = input.query?.toLowerCase().split(/\s+/u).filter(Boolean) ?? [];
+	const matched = tools.filter((tool) => input.name !== void 0 ? tool.name === input.name : words.every((word) => `${tool.name} ${tool.description}`.toLowerCase().includes(word))).sort((a, b) => a.name.localeCompare(b.name));
+	if (input.name !== void 0 && matched.length === 0) throw new Error("The requested operation is not available to the current member.");
+	const remaining = matched.filter((tool) => input.after === void 0 || tool.name.localeCompare(input.after) > 0);
+	const limit = Math.min(50, Math.max(1, input.limit ?? 20));
+	const page = remaining.slice(0, limit);
+	return {
+		tools: page,
+		...remaining.length > limit ? { next_after: page.at(-1).name } : {}
+	};
+}
+export { ontologyInspect, ontologyMetadata };

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

@@ -8,7 +8,7 @@ import { manifestOf } from "../../config.mjs";
 import { appOrigin, channelsEnabled, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret } from "../environment.mjs";
 import { conversationLanguage, telegramPrincipal } from "./principal.mjs";
 import { chooseModel } from "../../model.mjs";
-import { t as agentBuild } from "../../../_chunks/build-metadata-BIjXU_y3.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-CRUM3DfA.mjs";
 import { confirmationLocale } from "./confirmation-text.mjs";
 import { telegramSendScope } from "./send-queue.mjs";
 import { d as failureText, h as withDeliveryLocale, i as withReplacedText, m as safeTelegramFetch, n as currentInboundRequest, p as reportTelegramError, r as runInboundRequest, t as InboundRequest } from "../../../_chunks/inbound-request-B98tr4Pd.mjs";
@@ -319,7 +319,10 @@ function segmentstreamTelegram(options) {
 							messageThreadId: channel.telegram.messageThreadId,
 							from: { id: principal.subject ?? "" }
 						}
-					})("completed", { key: taskId });
+					})("completed", {
+						key: taskId,
+						...configuration.contextVersion === 2 ? { reply: event.message } : {}
+					});
 					if (result.message !== void 0 || result.complete === false) event = {
 						...event,
 						message: result.message ?? ""

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

@@ -4,7 +4,7 @@ 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-BIjXU_y3.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-CRUM3DfA.mjs";
 import { runtimeRequestFailure } from "./runtime-request.mjs";
 import { GET } from "eve/channels";
 const HEALTH_ROUTE = "/eve/v1/telegram/health";

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

@@ -368,7 +368,8 @@ async function handleInboundMessage(input) {
 	if (input.request !== void 0 && sent.attachments.length > 0 && dependencies.lifecycle !== void 0 && await admitTurn(true)) {
 		const principal = telegramPrincipal({
 			message: sent,
-			member
+			member,
+			conversationLanguage: conversationLanguage([sent.text || sent.caption, ...dependencies.observed.recent(chat).map((message) => message.text).reverse()])
 		});
 		input.request.lifecycle = dependencies.lifecycle(principal, member.id, sent);
 		input.request.stopTyping = startTypingHeartbeat(context.telegram);

package/dist/extension/lib/telegram/lifecycle.d.ts

@@ -6,6 +6,8 @@ import type { RuntimeToken } from "../runtime-token.js";
 export interface AttachmentLifecycle {
     readonly entity: string;
     readonly action: string;
+    /** Opt into provider timestamps and completion replies in lifecycle data. Omit for the legacy data contract. */
+    readonly contextVersion?: 2;
 }
 export interface LifecycleResult {
     readonly key?: string;
@@ -35,6 +37,7 @@ export declare function attachmentLifecycle(options: {
         readonly from?: {
             readonly id: string;
         };
+        readonly raw?: Record<string, unknown>;
     };
     readonly environment?: Environment;
     readonly token?: RuntimeToken;

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

@@ -4,7 +4,7 @@ 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-BIjXU_y3.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-CRUM3DfA.mjs";
 import { object } from "../confirmation-description.mjs";
 import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-B98tr4Pd.mjs";
 import { needsConfirmation } from "../confirmations.mjs";
@@ -32,7 +32,10 @@ function attachmentLifecycle(options) {
 				sender: options.message.from.id,
 				locale: String(options.principal.attributes.conversationLanguage ?? options.principal.attributes.locale ?? "en")
 			},
-			data
+			data: {
+				...data,
+				...options.configuration.contextVersion === 2 && typeof options.message.raw?.date === "number" && Number.isSafeInteger(options.message.raw.date) && options.message.raw.date > 0 ? { source_at: options.message.raw.date * 1e3 } : {}
+			}
 		};
 		if (needsConfirmation(await tools.labels(options.memberId, action, input))) throw new Error("An attachment lifecycle hook must be a permitted routine action.");
 		const raw = await tools.rpc(options.memberId, "tools/call", {

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

@@ -24,11 +24,20 @@ function replyDelivery(observed, scope = () => "telegram") {
 	return async (event, channel, context) => {
 		if (completionKind(event.message, event.finishReason) !== "reply") return;
 		const message = customerMessage(event.message, confirmationLocale(context.session?.auth.current ?? null, currentLocale()));
+		const principal = context.session?.auth.current;
+		const replyTo = principal?.attributes.replyToMessageId;
+		const replyParameters = typeof replyTo === "string" && /^[1-9]\d*$/u.test(replyTo) ? { reply_parameters: {
+			message_id: Number(replyTo),
+			allow_sending_without_reply: true
+		} } : {};
 		const deliveredIds = await inTelegramSendQueue(scope(), channel.telegram.chatId, async () => {
 			const messageIds = [];
 			try {
 				for (const part of splitTelegramText(message)) {
-					const result = await channel.telegram.post(part);
+					const result = await channel.telegram.post({
+						...part,
+						...replyParameters
+					});
 					if (!/^[1-9]\d*$/u.test(result.id)) throw new Error("Telegram did not acknowledge the reply with a message id.");
 					messageIds.push(Number(result.id));
 				}
@@ -40,7 +49,6 @@ function replyDelivery(observed, scope = () => "telegram") {
 		});
 		const text = message.text;
 		if (observed === void 0 || channel.telegram.chatType === "private") return;
-		const principal = context.session.auth.current;
 		const sender = principal?.authenticator === "segmentstream-telegram" ? principal.subject : void 0;
 		const username = principal?.attributes.username;
 		const name = principal?.attributes.memberName;

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

@@ -1,4 +1,27 @@
 declare const _default: import("eve").DynamicSentinel<{
-    [k: string]: import("eve/tools").ToolDefinition<Record<string, unknown>, Record<string, unknown>>;
+    ontology_discover: import("eve/tools").ToolDefinition<Record<string, unknown>, Record<string, unknown>> & {
+        execute(input: Record<string, unknown>, ctx: import("eve/tools").ToolContext): Promise<Record<string, unknown>>;
+    };
+    ontology_describe: import("eve/tools").ToolDefinition<Record<string, unknown>, Record<string, unknown>> & {
+        execute(input: Record<string, unknown>, ctx: import("eve/tools").ToolContext): Promise<Record<string, unknown>>;
+    };
+    ontology_inspect: import("eve/tools").ToolDefinition<Record<string, unknown>, {
+        next_after?: string | undefined;
+        tools: {
+            name: string;
+            description: string;
+        }[];
+    }> & {
+        execute(input: Record<string, unknown>, ctx: import("eve/tools").ToolContext): Promise<{
+            next_after?: string | undefined;
+            tools: {
+                name: string;
+                description: string;
+            }[];
+        }>;
+    };
+    ontology_call: import("eve/tools").ToolDefinition<Record<string, unknown>, Record<string, unknown>> & {
+        execute(input: Record<string, unknown>, ctx: import("eve/tools").ToolContext): Promise<Record<string, unknown>>;
+    };
 } | null>;
 export default _default;

package/dist/extension/tools/ontology.mjs

@@ -6,25 +6,125 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { memberIdOf } from "../lib/telegram/principal.mjs";
 import segmentstream from "../extension.mjs";
-import { ontologyTools } from "../lib/ontology-tools.mjs";
 import { executeDeferredTool } from "../lib/deferred-confirmations.mjs";
+import { ontologyInspect, ontologyMetadata } from "../lib/ontology-gateway.mjs";
 import { defineDynamic, defineTool } from "eve/tools";
 var ontology_default = defineDynamic({ events: { "turn.started": async (_event, context) => {
 	const memberId = memberIdOf(context.session.auth.current);
 	if (!segmentstream.config.ontology.connection || segmentstream.config.confirmations.mode !== "deferred" || memberId === void 0) return null;
-	return Object.fromEntries((await ontologyTools().list(memberId)).map((tool) => {
-		const action = String(tool.name);
-		const schema = tool.inputSchema;
-		const properties = Object.fromEntries(Object.entries(schema.properties ?? {}).filter(([key]) => key !== "_segmentstream"));
-		return [`ontology__${action}`, defineTool({
-			deferred: true,
-			description: String(tool.description ?? tool.title ?? action),
+	return {
+		ontology_discover: defineTool({
+			description: "Search the permitted ontology's entities, actions and measures by words. Inspect returned refs with ontology_describe before calling ontology_call.",
 			inputSchema: {
-				...schema,
-				properties
+				type: "object",
+				properties: {
+					query: {
+						type: "string",
+						minLength: 1,
+						maxLength: 512
+					},
+					kind: {
+						type: "string",
+						enum: [
+							"entity",
+							"action",
+							"measure"
+						]
+					},
+					entity: { type: "string" },
+					mode: {
+						type: "string",
+						enum: [
+							"auto",
+							"literal",
+							"fuzzy"
+						]
+					},
+					after: { type: "string" },
+					expected_hash: {
+						type: "string",
+						pattern: "^sha256:[a-f0-9]{64}$"
+					},
+					limit: {
+						type: "integer",
+						minimum: 1,
+						maximum: 50
+					}
+				},
+				required: ["query"],
+				additionalProperties: false
 			},
-			execute: (input, ctx) => executeDeferredTool(memberId, action, input, ctx)
-		})];
-	}));
+			execute: (input, ctx) => ontologyMetadata(memberId, "discover", input, ctx)
+		}),
+		ontology_describe: defineTool({
+			description: "Inspect an ontology entity:, action: or measure: ref, including its exact operation names and schemas. Omit ref for the entity index. Follow next_cursor with after.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					ref: {
+						type: "string",
+						minLength: 1,
+						maxLength: 256
+					},
+					after: { type: "string" },
+					expected_hash: {
+						type: "string",
+						pattern: "^sha256:[a-f0-9]{64}$"
+					},
+					limit: {
+						type: "integer",
+						minimum: 1,
+						maximum: 100
+					}
+				},
+				additionalProperties: false
+			},
+			execute: (input, ctx) => ontologyMetadata(memberId, "describe", input, ctx)
+		}),
+		ontology_inspect: defineTool({
+			description: "Find permission-filtered MCP operation names and complete input schemas, including entity find/get/history reads. Supply name for an exact definition, query for words, or omit both for a paged tool index. Use next_after as after. This reads metadata only.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					name: {
+						type: "string",
+						minLength: 1
+					},
+					query: {
+						type: "string",
+						minLength: 1,
+						maxLength: 512
+					},
+					after: { type: "string" },
+					limit: {
+						type: "integer",
+						minimum: 1,
+						maximum: 50
+					}
+				},
+				additionalProperties: false
+			},
+			execute: (input, ctx) => ontologyInspect(memberId, input, ctx)
+		}),
+		ontology_call: defineTool({
+			description: "Run a permitted ontology operation by the exact MCP tool name from its inspected definition, with arguments matching that schema. Reads and routine actions run immediately; consequential actions retain native deferred confirmation. An awaiting_confirmation result means the action has not run.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					name: {
+						type: "string",
+						minLength: 1
+					},
+					arguments: {
+						type: "object",
+						additionalProperties: true
+					}
+				},
+				required: ["name"],
+				additionalProperties: false
+			},
+			execute: (input, ctx) => executeDeferredTool(memberId, input.name, input.arguments ?? {}, ctx)
+		})
+	};
 } } });
 export { ontology_default as default };

package/package.json

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