@segmentstream/agent 0.17.16 → 0.17.17

package/README.md

@@ -748,3 +748,24 @@ Workspace [callback actions](../../docs/agent.md#workspace-callback-actions) and
 mappings. They require the ontology runtime-source capability and dispatch only a currently
 permitted routine action as the verified member. The workspace owns callback tokens, presentation
 and business idempotency.
+
+### Durable typing
+
+The webhook monitor ends with its host request. For turns that can outlive that
+request, an application's authored Workflow can call `telegramTypingBlock` from
+`@segmentstream/agent/extension` in a `"use step"` helper. Each activity runs for
+at most about thirty seconds, follows a bounded cursor through one session's
+durable stream, and sends only `sendChatAction` through the declared connection.
+It stops for its source turn's completion, failure, cancellation or input wait,
+or when the source session is terminal. Pass an exact `turnId` from a real
+`turn.started` hook, or a unique `marker` in a private acceptance message.
+
+The application owns the Workflow directives: Eve does not permit them in an
+SDK extension. Its step reads `getRun(source.sessionId).status` through
+`workflow/api` and calls `telegramTypingBlock(source, cursor, status)`. Its
+workflow carries the returned cursor between activities and ends when `done` is
+true. Start a continuation periodically to bound the workflow history, then
+retire the previous monitor. `recordTelegramTypingStart(source, workflowRunId)`
+records the monitor reference in the conversation archive. Source arguments
+contain transport coordinates and a member ID, never credentials or message
+contents. Repeated typing actions are idempotent; the activity never posts text.

package/dist/_chunks/{build-metadata-D7rtiSxQ.mjs → build-metadata-9SHckxvW.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.17.16";
+var version = "0.17.17";
 function agentBuild(environment = process.env) {
 	return {
 		agent: version,

package/dist/extension/extension.d.ts

@@ -31,3 +31,4 @@ export { replayRouterPayload } from "./lib/group-routing/replay.js";
 export { conversationState as groupConversationState, conversationAddressing as groupConversationAddressing, type ConversationAnalysis, type ConversationPath, } from "./lib/group-routing/conversation.js";
 export { routingBurst, debounceBurst } from "./lib/group-routing/burst.js";
 export type { TelegramTexts } from "./lib/telegram/texts.js";
+export { telegramTypingBlock, recordTelegramTypingStart, type TelegramTypingSource, type TypingCursor, type TypingBlockResult, } from "./lib/telegram/durable-typing.js";

package/dist/extension/extension.mjs

@@ -14,10 +14,11 @@ import { agentMessage, observedMessages } from "./lib/group-routing/observed.mjs
 import { archivedRoutingMessages } from "./lib/group-routing/routing-context.mjs";
 import { replayRouterPayload } from "./lib/group-routing/replay.mjs";
 import { debounceBurst, routingBurst } from "./lib/group-routing/burst.mjs";
+import { recordTelegramTypingStart, telegramTypingBlock } from "./lib/telegram/durable-typing.mjs";
 import { defineExtension } from "eve/extension";
 const extension = defineExtension({ config: configSchema });
 const segmentstream = Object.assign(extension, {
 	model: (choice) => model(choice ?? (() => extension.config.models.chat)),
 	manifestOf
 });
-export { DEFAULT_ADMISSION_LIMITS, DEFAULT_DECISION_MODEL, DEFAULT_GROUP_POLICY, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, archivedRoutingMessages, chooseModel, conversationKey, debounceBurst, segmentstream as default, segmentstream, effectiveGroupPolicy, addressingReason as groupAddressingReason, agentMessage as groupAgentMessage, conversationAddressing as groupConversationAddressing, conversationState as groupConversationState, decisionRouter as groupDecisionRouter, observedMessages as groupObservedMessages, groupPolicy, manifestOf, model, replayRouterPayload, routeMessage as routeGroupMessage, routingBurst };
+export { DEFAULT_ADMISSION_LIMITS, DEFAULT_DECISION_MODEL, DEFAULT_GROUP_POLICY, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, archivedRoutingMessages, chooseModel, conversationKey, debounceBurst, segmentstream as default, segmentstream, effectiveGroupPolicy, addressingReason as groupAddressingReason, agentMessage as groupAgentMessage, conversationAddressing as groupConversationAddressing, conversationState as groupConversationState, decisionRouter as groupDecisionRouter, observedMessages as groupObservedMessages, groupPolicy, manifestOf, model, recordTelegramTypingStart, replayRouterPayload, routeMessage as routeGroupMessage, routingBurst, telegramTypingBlock };

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

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

@@ -18,16 +18,16 @@ import { chooseModel } from "../../model.mjs";
 import { groupRoutingHealth } from "../group-routing/health.mjs";
 import { decisionRouter } from "../group-routing/router.mjs";
 import { archivedRoutingMessages } from "../group-routing/routing-context.mjs";
+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-D7rtiSxQ.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-9SHckxvW.mjs";
 import { attachmentLifecycle } from "./lifecycle.mjs";
 import { observedMessages } from "./observed.mjs";
 import { expireDeferredCards, handleDeferredCallback, isDeferredCallback } from "./deferred-confirmations.mjs";
 import { gatewayImageDescriber } from "./images.mjs";
 import { gatewayAttachmentDescriber } from "./attachment-description.mjs";
-import { MAXIMUM_DOWNLOAD_BYTES, connectionProxy } from "../connection-proxy.mjs";
 import { agentAttachments, parseAttachmentUrl } from "../attachments.mjs";
 import { agentIdentities } from "../identities.mjs";
 import { interimTexts, replyDelivery } from "./silent.mjs";

package/dist/extension/lib/telegram/confirmation-expiry.mjs

@@ -10,9 +10,9 @@ import { telegramSendScope } from "./send-queue.mjs";
 import { runtimeToken } from "../runtime-token.mjs";
 import { conversations } from "../conversations.mjs";
 import { m as safeTelegramFetch, p as reportTelegramError } from "../../../_chunks/inbound-request-Buuv7b1I.mjs";
+import { connectionProxy } from "../connection-proxy.mjs";
 import { deferredConfirmations } from "../deferred-confirmations.mjs";
 import { expireDeferredRecord } from "./deferred-confirmations.mjs";
-import { connectionProxy } from "../connection-proxy.mjs";
 import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
 import { telegramPreviewEnvironment } from "@segmentstream-cloud/ontology/telegram";
 import { editTelegramMessageText } from "eve/channels/telegram";

package/dist/extension/lib/telegram/durable-typing.d.ts

@@ -0,0 +1,37 @@
+/** Transport coordinates from an admitted turn; never a token or provider credential. */
+export interface TelegramTypingSource {
+    readonly sessionId: string;
+    readonly marker?: string;
+    readonly turnId?: string;
+    readonly connection: string;
+    readonly chatId: string;
+    readonly threadId?: number;
+    readonly memberId: string;
+}
+export interface TypingCursor {
+    readonly index: number;
+    readonly turnId: string | null;
+}
+interface TypingEvent {
+    readonly type: string;
+    readonly data?: unknown;
+}
+interface TypingBlockDependencies {
+    readonly events: (index: number, signal: AbortSignal) => AsyncIterable<TypingEvent>;
+    readonly status: () => Promise<string>;
+    readonly send: () => Promise<boolean>;
+    readonly now: () => number;
+    readonly pause: (milliseconds: number) => Promise<void>;
+}
+export interface TypingBlockResult {
+    readonly cursor: TypingCursor;
+    readonly done: boolean;
+    readonly reason: string;
+    readonly sent: number;
+}
+/** One bounded activity. Its durable parent continues independently of the webhook host. */
+export declare function runTypingBlock(source: TelegramTypingSource, cursor: TypingCursor, dependencies: TypingBlockDependencies): Promise<TypingBlockResult>;
+export declare function telegramTypingBlock(source: TelegramTypingSource, cursor: TypingCursor, sessionStatus: string): Promise<TypingBlockResult>;
+/** Link the durable monitor to the source turn without any customer-visible message. */
+export declare function recordTelegramTypingStart(source: TelegramTypingSource, workflowRunId: string): Promise<void>;
+export {};

package/dist/extension/lib/telegram/durable-typing.mjs

@@ -0,0 +1,178 @@
+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 { channelsEnabled, proxyEnvironment } from "../environment.mjs";
+import { redactTelegramDiagnostic } from "./diagnostic-redaction.mjs";
+import { runtimeToken } from "../runtime-token.mjs";
+import { conversationEvent, conversations } from "../conversations.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-Buuv7b1I.mjs";
+import { connectionProxy } from "../connection-proxy.mjs";
+import { sessions } from "eve/server";
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+async function runTypingBlock(source, cursor, dependencies) {
+	const deadline = dependencies.now() + 3e4;
+	let index = cursor.index, turnId = cursor.turnId ?? source.turnId ?? null, sent = 0;
+	const result = (done, reason) => ({
+		cursor: {
+			index,
+			turnId
+		},
+		done,
+		reason,
+		sent
+	});
+	if ([
+		"completed",
+		"failed",
+		"cancelled"
+	].includes(await dependencies.status())) return result(true, "session_terminal");
+	while (dependencies.now() < deadline) {
+		const started = dependencies.now();
+		const controller = new AbortController();
+		const iterator = dependencies.events(index, controller.signal)[Symbol.asyncIterator]();
+		let timer;
+		const expired = new Promise((resolve) => {
+			timer = setTimeout(() => {
+				resolve(null);
+				controller.abort();
+			}, Math.min(1500, Math.max(0, deadline - dependencies.now())));
+		});
+		try {
+			while (dependencies.now() < deadline) {
+				const next = await Promise.race([iterator.next(), expired]);
+				if (next === null) return result(false, "history_read_timeout");
+				if (next.done) break;
+				const event = next.value;
+				index += 1;
+				const data = object(event.data) ? event.data : {};
+				if (event.type === "message.received" && typeof data.message === "string" && typeof source.marker === "string" && source.marker !== "" && data.message.includes(source.marker) && typeof data.turnId === "string") turnId = data.turnId;
+				if (["session.failed", "session.completed"].includes(event.type)) return result(true, event.type);
+				if (turnId !== null && data.turnId === turnId && ([
+					"turn.completed",
+					"turn.failed",
+					"turn.cancelled",
+					"input.requested"
+				].includes(event.type) || event.type === "turn.waiting" && data.on === "input")) return result(true, event.type);
+			}
+		} finally {
+			clearTimeout(timer);
+			controller.abort();
+			iterator.return?.().catch(() => {});
+		}
+		if (dependencies.now() >= deadline) return result(false, "continue");
+		if (turnId !== null) {
+			if (await dependencies.send()) sent += 1;
+		}
+		await dependencies.pause(Math.max(0, 2e3 - (dependencies.now() - started)));
+	}
+	return result(false, "continue");
+}
+async function telegramTypingBlock(source, cursor, sessionStatus) {
+	try {
+		if (!channelsEnabled()) return {
+			cursor,
+			done: true,
+			reason: "channels_disabled",
+			sent: 0
+		};
+		const proxy = connectionProxy({
+			environment: proxyEnvironment(),
+			connection: source.connection,
+			token: runtimeToken
+		});
+		const result = await runTypingBlock(source, cursor, {
+			status: async () => sessionStatus,
+			events: (index, signal) => sessions.attach(source.sessionId).stream({
+				startIndex: index,
+				follow: false,
+				signal
+			}),
+			now: Date.now,
+			pause: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+			send: async () => {
+				try {
+					const response = await proxy.request({
+						api: "bot",
+						method: "POST",
+						path: "/sendChatAction",
+						headers: [["content-type", "application/json"]],
+						body: Buffer.from(JSON.stringify({
+							chat_id: source.chatId,
+							action: "typing",
+							...source.threadId === void 0 ? {} : { message_thread_id: source.threadId }
+						}))
+					}, AbortSignal.timeout(5e3));
+					const body = JSON.parse(Buffer.from(response.body).toString("utf8"));
+					const accepted = response.status >= 200 && response.status < 300 && object(body) && body.ok === true;
+					console.info("[segmentstream] telegram.method", {
+						method: "sendChatAction",
+						at: new Date().toISOString(),
+						chatId: source.chatId,
+						status: response.status,
+						accepted,
+						sessionId: source.sessionId,
+						durable: true
+					});
+					if (!accepted) throw new Error("Telegram rejected sendChatAction.", { cause: {
+						status: response.status,
+						body
+					} });
+					return true;
+				} catch (error) {
+					reportTelegramError("typing_failed", error, {
+						chatId: source.chatId,
+						sessionId: source.sessionId,
+						durable: true
+					});
+					return false;
+				}
+			}
+		});
+		console.info("[segmentstream] telegram.typing_block", {
+			sessionId: source.sessionId,
+			turnId: result.cursor.turnId,
+			cursor: result.cursor.index,
+			done: result.done,
+			reason: result.reason,
+			sent: result.sent
+		});
+		return result;
+	} catch (error) {
+		reportTelegramError("typing_monitor_failed", error, {
+			sessionId: source.sessionId,
+			durable: true
+		});
+		throw new Error("Durable typing monitor failed.", { cause: redactTelegramDiagnostic(error) });
+	}
+}
+async function recordTelegramTypingStart(source, workflowRunId) {
+	console.info("[segmentstream] telegram.typing_started", {
+		sessionId: source.sessionId,
+		workflowRunId
+	});
+	try {
+		await conversations().append(conversationEvent({
+			provider: "telegram",
+			chatId: source.chatId,
+			chatType: source.chatId.startsWith("-") ? "group" : "private",
+			threadId: source.threadId === void 0 ? null : String(source.threadId),
+			eventId: `telegram:typing:${workflowRunId}`,
+			sessionId: source.sessionId,
+			turnId: source.turnId ?? null,
+			participantIds: [source.memberId],
+			kind: "decision",
+			decision: "silent",
+			reason: "typing_monitor_started",
+			argsSummary: JSON.stringify({ workflowRunId })
+		}));
+	} catch (error) {
+		reportTelegramError("typing_monitor_recording_failed", error, {
+			sessionId: source.sessionId,
+			workflowRunId
+		});
+	}
+}
+export { recordTelegramTypingStart, runTypingBlock, telegramTypingBlock };

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

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

@@ -9,7 +9,7 @@ import { object } from "../confirmation-description.mjs";
 import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-Buuv7b1I.mjs";
 import { needsConfirmation } from "../confirmations.mjs";
 import { OntologyActionNotPermitted, actionToolName, ontologyTools } from "../ontology-tools.mjs";
-import { t as agentBuild } from "../../../_chunks/build-metadata-D7rtiSxQ.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-9SHckxvW.mjs";
 var AttachmentLifecycleNotPermitted = class extends Error {
 	code = "attachment_lifecycle_not_permitted";
 };

package/dist/extension/tools/sandbox.mjs

@@ -12,7 +12,9 @@ import { readFile } from "eve/tools/read_file";
 import { writeFile } from "eve/tools/write_file";
 function gated(tool, description = tool.description) {
 	return defineTool({
-		...tool,
+		inputSchema: tool.inputSchema,
+		outputSchema: tool.outputSchema,
+		label: tool.label,
 		description,
 		async execute(input, ctx) {
 			await sessionSandbox(ctx);

package/package.json

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