@segmentstream/agent 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,69 @@
+import type { TelegramMessage } from "eve/channels/telegram";
+import type { TelegramPolicy } from "../../config.js";
+import type { ObservedMessage } from "./observed.js";
+/**
+ * The inbound router (`agent-design.md`, section 4): every message from a paired member is either
+ * answered or observed before eve starts a turn. A private chat, a mention, a reply to the bot and
+ * a command are always answered. Any other group message is observed, or, with the `smart`
+ * policy, put to one decision on the decision model.
+ */
+export type Route = "observe" | "reply";
+/** The bot, as Telegram's `getMe` describes it. Unknown when `getMe` failed. */
+export interface BotIdentity {
+    readonly id: string;
+    readonly username: string | undefined;
+}
+/** Whether the message is for the bot without asking any model. */
+export declare function isAddressed(message: TelegramMessage, bot: BotIdentity | undefined): boolean;
+/** What the decision model sees. */
+export interface RouteQuestion {
+    /** The agent's own description, so the model knows what it can be asked for. */
+    readonly agent: string;
+    readonly observed: ReadonlyArray<ObservedMessage>;
+    readonly message: ObservedMessage;
+}
+/** Decides whether a group message not addressed to the bot is still for it. */
+export type RouteDecider = (question: RouteQuestion) => Promise<Route>;
+/**
+ * The shape of eve's `decide` this router uses. Tests pass a fake; production passes `decide`
+ * from `eve/ai`, which authenticates to AI Gateway like every other model call.
+ */
+export type DecideFunction = (options: {
+    readonly model: string;
+    readonly state: {
+        readonly [key: string]: string | ReadonlyArray<string>;
+    };
+    readonly questions: {
+        readonly route: {
+            readonly type: "choice";
+            readonly instructions: string;
+            readonly criteria: {
+                readonly observe: string;
+                readonly reply: string;
+            };
+        };
+    };
+    readonly abortSignal?: AbortSignal;
+}) => Promise<{
+    readonly answers: {
+        readonly route: {
+            readonly choice: Route;
+        };
+    };
+}>;
+/** A {@link RouteDecider} that asks one `decide` question on the configured decision model. */
+export declare function decisionRouter(input: {
+    readonly decide: DecideFunction;
+    readonly model: string;
+}): RouteDecider;
+/**
+ * Routes one message from a paired member. A failed decision observes: staying quiet is the safe
+ * mistake in a group chat.
+ */
+export declare function routeMessage(input: {
+    readonly policy: TelegramPolicy;
+    readonly addressed: boolean;
+    /** Builds the question only when a decision is needed: it reads the agent's description. */
+    readonly question: () => Promise<RouteQuestion>;
+    readonly decide: RouteDecider;
+}): Promise<Route>;

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

@@ -0,0 +1,64 @@
+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);
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isCommand(text, bot) {
+	const match = /^\/[A-Za-z0-9_]+(?:@(?<target>[A-Za-z0-9_]+))?(?:\s|$)/u.exec(text);
+	if (match === null) return false;
+	const target = match.groups?.target;
+	return target === void 0 || target.toLowerCase() === bot?.username?.toLowerCase();
+}
+function mentions(text, bot) {
+	if (bot?.username === void 0) return false;
+	return new RegExp(`(?:^|[^A-Za-z0-9_])@${escapeRegExp(bot.username)}(?=$|[^A-Za-z0-9_])`, "iu").test(text);
+}
+function repliesToBot(message, bot) {
+	const author = message.replyToMessage?.from;
+	if (author === void 0) return false;
+	return bot !== void 0 && author.id === bot.id;
+}
+function isAddressed(message, bot) {
+	const text = message.text || message.caption;
+	return message.chat.type === "private" || isCommand(text, bot) || mentions(text, bot) || repliesToBot(message, bot);
+}
+const DECISION_TIMEOUT_MS = 15e3;
+function line(message) {
+	return `${message.author}: ${message.text}`;
+}
+function decisionRouter(input) {
+	return async (question) => {
+		return (await input.decide({
+			model: input.model,
+			state: {
+				agent: question.agent,
+				recent_messages: question.observed.map(line),
+				message: line(question.message)
+			},
+			questions: { route: {
+				type: "choice",
+				instructions: "A group chat message arrived that does not mention the agent. Decide whether the agent should answer it, given what the agent does and what the chat was talking about.",
+				criteria: {
+					observe: "The message is people talking among themselves, or nothing the agent can help with.",
+					reply: "The message asks the agent, or asks for something the agent does, even without naming it."
+				}
+			} },
+			abortSignal: AbortSignal.timeout(DECISION_TIMEOUT_MS)
+		})).answers.route.choice;
+	};
+}
+async function routeMessage(input) {
+	if (input.addressed) return "reply";
+	if (input.policy === "mention") return "observe";
+	try {
+		return await input.decide(await input.question());
+	} catch (error) {
+		console.error("[segmentstream] inbound routing decision failed; observing the message", { error });
+		return "observe";
+	}
+}
+export { decisionRouter, isAddressed, routeMessage };

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

@@ -0,0 +1,9 @@
+import type { TelegramChannelEvents } from "eve/channels/telegram";
+export declare function isSilentReply(text: string): boolean;
+type MessageCompleted = NonNullable<TelegramChannelEvents["message.completed"]>;
+/**
+ * The channel's `message.completed` handler: eve's default delivery (plain text through
+ * `sendMessage`, nothing for a tool-call step) unless the reply is a silence marker.
+ */
+export declare const deliverUnlessSilent: MessageCompleted;
+export {};

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

@@ -0,0 +1,15 @@
+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);
+const SILENT_MARKERS = new Set(["[silent]", "no_reply"]);
+function isSilentReply(text) {
+	return SILENT_MARKERS.has(text.trim().toLowerCase());
+}
+const deliverUnlessSilent = async (event, channel) => {
+	if (event.finishReason === "tool-calls" || !event.message || isSilentReply(event.message)) return;
+	await channel.telegram.post(event.message);
+};
+export { deliverUnlessSilent, isSilentReply };

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

@@ -0,0 +1,52 @@
+import { type ConnectionProxy } from "../connection-proxy.js";
+/**
+ * Voice, audio and video notes. eve's Telegram parser reads only photos and documents, so these
+ * arrive as a message with no text; the adapter reads them from the raw update, downloads them
+ * through the connection's `file` API and turns them into text with the configured speech-to-text
+ * model before the conversation sees them, whatever the main model accepts.
+ */
+export type VoiceKind = "voice" | "audio" | "video_note";
+export interface VoiceMessage {
+    readonly kind: VoiceKind;
+    readonly fileId: string;
+    readonly seconds: number | undefined;
+    readonly size: number | undefined;
+}
+/** The voice, audio or video note a raw Telegram message carries, if any. */
+export declare function voiceOf(raw: Readonly<Record<string, unknown>>): VoiceMessage | undefined;
+/** The note that tells the model a message was spoken, such as `[voice message, 12 s]`. */
+export declare function voiceNote(voice: VoiceMessage, detail?: string): string;
+/** Speech to text: the audio bytes in, the transcript out. */
+export type Transcriber = (input: {
+    readonly audio: Uint8Array;
+    readonly model: string;
+}) => Promise<string>;
+/**
+ * Transcribes through AI Gateway. The Gateway provider authenticates with `AI_GATEWAY_API_KEY`
+ * when set and otherwise with the deployment's Vercel OIDC token, so a deployment needs no key.
+ */
+export declare const gatewayTranscriber: Transcriber;
+/** A Telegram file could not be downloaded through the connection. */
+export declare class TelegramFileError extends Error {
+    readonly name = "TelegramFileError";
+}
+/** Downloads a file by id: `getFile` on the `bot` API, then the bytes from the `file` API. */
+export declare function downloadTelegramFile(input: {
+    readonly proxy: ConnectionProxy;
+    readonly fileId: string;
+}): Promise<Uint8Array>;
+/** What a voice message becomes: the text of the turn and the note that goes with it. */
+export interface VoiceText {
+    readonly text: string;
+    readonly note: string;
+}
+/**
+ * Turns a voice message into text. When it cannot (transcription is off, the file exceeds what the
+ * proxy forwards, or a call fails), the text says so, so the agent can ask for a typed message.
+ */
+export declare function voiceText(input: {
+    readonly voice: VoiceMessage;
+    readonly model: string | false;
+    readonly download: (fileId: string) => Promise<Uint8Array>;
+    readonly transcribe: Transcriber;
+}): Promise<VoiceText>;

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

@@ -0,0 +1,115 @@
+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 "../connection-proxy.mjs";
+import { gateway, transcribe } from "ai";
+const LABELS = {
+	voice: "voice message",
+	audio: "audio file",
+	video_note: "video message"
+};
+const TRANSCRIPTION_TIMEOUT_MS = 6e4;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function voiceOf(raw) {
+	for (const kind of [
+		"voice",
+		"audio",
+		"video_note"
+	]) {
+		const media = raw[kind];
+		if (isRecord(media) && typeof media.file_id === "string" && media.file_id !== "") return {
+			kind,
+			fileId: media.file_id,
+			seconds: optionalNumber(media.duration),
+			size: optionalNumber(media.file_size)
+		};
+	}
+}
+function voiceNote(voice, detail) {
+	const parts = [LABELS[voice.kind]];
+	if (voice.seconds !== void 0) parts.push(`${Math.round(voice.seconds)} s`);
+	if (detail !== void 0) parts.push(detail);
+	return `[${parts.join(", ")}]`;
+}
+const gatewayTranscriber = async ({ audio, model }) => {
+	return (await transcribe({
+		model: gateway.transcription(model),
+		audio,
+		abortSignal: AbortSignal.timeout(TRANSCRIPTION_TIMEOUT_MS)
+	})).text.trim();
+};
+var TelegramFileError = class extends Error {
+	name = "TelegramFileError";
+};
+async function downloadTelegramFile(input) {
+	const metadata = await input.proxy.request({
+		api: "bot",
+		method: "POST",
+		path: "/getFile",
+		headers: [["content-type", "application/json"]],
+		body: new TextEncoder().encode(JSON.stringify({ file_id: input.fileId }))
+	});
+	let filePath;
+	let description = "";
+	try {
+		const value = JSON.parse(new TextDecoder().decode(metadata.body));
+		filePath = isRecord(value) && isRecord(value.result) ? value.result.file_path : void 0;
+		description = isRecord(value) && typeof value.description === "string" ? value.description.slice(0, 200) : "";
+	} catch (error) {
+		throw new TelegramFileError("Telegram answered getFile with an invalid body.", { cause: error });
+	}
+	if (metadata.status !== 200 || typeof filePath !== "string" || filePath === "") throw new TelegramFileError(`Telegram refused getFile with HTTP ${metadata.status}${description ? `: ${description}` : "."}`);
+	const file = await input.proxy.request({
+		api: "file",
+		method: "GET",
+		path: `/${filePath}`,
+		headers: [],
+		body: new Uint8Array()
+	});
+	if (file.status !== 200) throw new TelegramFileError(`Telegram refused the file download with HTTP ${file.status}.`);
+	return file.body;
+}
+async function voiceText(input) {
+	const { voice, model } = input;
+	const note = voiceNote(voice);
+	if (model === false) return {
+		text: voiceNote(voice, "voice transcription is off"),
+		note
+	};
+	if (voice.size !== void 0 && voice.size > 2097152) return {
+		text: voiceNote(voice, "too long to transcribe"),
+		note
+	};
+	try {
+		const audio = await input.download(voice.fileId);
+		const transcript = await input.transcribe({
+			audio,
+			model
+		});
+		return transcript === "" ? {
+			text: voiceNote(voice, "no speech recognized"),
+			note
+		} : {
+			text: transcript,
+			note
+		};
+	} catch (error) {
+		console.error("[segmentstream] voice transcription failed", {
+			kind: voice.kind,
+			error
+		});
+		return {
+			text: voiceNote(voice, "could not be transcribed"),
+			note
+		};
+	}
+}
+export { TelegramFileError, downloadTelegramFile, gatewayTranscriber, voiceNote, voiceOf, voiceText };

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

@@ -0,0 +1,13 @@
+/** The header Telegram echoes the `secret_token` given to `setWebhook` in. */
+export declare const TELEGRAM_SECRET_HEADER = "x-telegram-bot-api-secret-token";
+/**
+ * Compares in constant time. Hashing both sides first gives buffers of equal length, so neither
+ * the comparison nor an early length check reveals how long the secret is.
+ */
+export declare function secretsMatch(expected: string, received: string): boolean;
+/**
+ * The Telegram channel's `webhookVerifier`: accepts a webhook whose secret header equals the
+ * project's `SEGMENTSTREAM_AGENT_WEBHOOK_SECRET`, which the platform generates once per project and
+ * registers with `setWebhook`. Without a configured secret every webhook is refused.
+ */
+export declare function telegramWebhookVerifier(secret: () => string | undefined): (request: Request) => boolean;

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

@@ -0,0 +1,23 @@
+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 { createHash, timingSafeEqual } from "node:crypto";
+const TELEGRAM_SECRET_HEADER = "x-telegram-bot-api-secret-token";
+function digest(value) {
+	return createHash("sha256").update(value, "utf8").digest();
+}
+function secretsMatch(expected, received) {
+	return timingSafeEqual(digest(expected), digest(received));
+}
+function telegramWebhookVerifier(secret) {
+	return (request) => {
+		const expected = secret();
+		const received = request.headers.get(TELEGRAM_SECRET_HEADER);
+		if (expected === void 0 || received === null || received === "") return false;
+		return secretsMatch(expected, received);
+	};
+}
+export { TELEGRAM_SECRET_HEADER, secretsMatch, telegramWebhookVerifier };

package/dist/extension/model.d.ts

@@ -0,0 +1,29 @@
+import { type AgentModelDefinition, type AgentStaticModelDefinition } from "eve";
+import type { SessionAuthContext } from "eve/context";
+import { type Environment } from "./lib/environment.js";
+/** The models `segmentstream.model()` chooses between, as AI Gateway model ids. */
+export interface ModelChoice {
+    /** The model for every session no other rule picks. */
+    readonly default: string;
+    /**
+     * A model per member role. The first entry whose role the member holds wins, in the order
+     * written, so put the more specific roles first.
+     */
+    readonly byRole?: Readonly<Record<string, string>>;
+    /** The model of preview deployments, so a preview never spends on a large model. */
+    readonly preview?: string;
+}
+/** The dynamic form of an agent's `model`, which `defineAgent` accepts as the whole field. */
+export type DynamicModel = Exclude<AgentModelDefinition, AgentStaticModelDefinition>;
+/** The one model for a session started by `principal`. */
+export declare function chooseModel(input: {
+    readonly choice: ModelChoice;
+    readonly principal: SessionAuthContext | null;
+    readonly environment?: Environment;
+}): string;
+/**
+ * The agent's model, chosen once when a session starts from the member's roles and `VERCEL_ENV`.
+ * Choosing once keeps the provider's prompt cache: a switch mid-session re-reads the history at
+ * full price.
+ */
+export declare function model(choice: ModelChoice): DynamicModel;

package/dist/extension/model.mjs

@@ -0,0 +1,23 @@
+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 { isPreview } from "./lib/environment.mjs";
+import { rolesOf } from "./lib/telegram/principal.mjs";
+import { defineDynamic } from "eve";
+function chooseModel(input) {
+	const { choice } = input;
+	if (choice.preview !== void 0 && isPreview(input.environment ?? process.env)) return choice.preview;
+	const roles = rolesOf(input.principal);
+	for (const [role, model] of Object.entries(choice.byRole ?? {})) if (roles.includes(role)) return model;
+	return choice.default;
+}
+function model(choice) {
+	return defineDynamic({ events: { "session.started": (_event, context) => chooseModel({
+		choice,
+		principal: context.session.auth.current ?? context.session.auth.initiator
+	}) } });
+}
+export { chooseModel, model };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+// Generated by eve. Do not edit by hand.
+
+export { default } from "./extension/extension.js";
+export { default as agent } from "./extension/extension.js";

package/dist/index.mjs

@@ -0,0 +1,8 @@
+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 segmentstream from "./extension/extension.mjs";
+export { segmentstream as agent, segmentstream as default };

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+// Generated by eve. Do not edit by hand.
+

package/dist/tools/index.mjs

@@ -0,0 +1,7 @@
+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);
+export {};

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+  "homepage": "https://segmentstream.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/segmentstream/segmentstream.git",
+    "directory": "packages/agent-sdk"
+  },
+  "keywords": [
+    "segmentstream",
+    "eve",
+    "agent",
+    "ontology",
+    "telegram"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/extension/extension.d.ts",
+        "default": "./dist/extension/extension.mjs"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./extension": {
+      "types": "./dist/extension/extension.d.ts",
+      "default": "./dist/extension/extension.mjs"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "default": "./dist/tools/index.mjs"
+    }
+  },
+  "eve": {
+    "extension": {
+      "source": "./src",
+      "dist": "./dist/extension"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "eve extension build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src tests --config ../../eslint.config.mjs",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@vercel/oidc": "^3.8.4",
+    "ai": "^7.0.128"
+  },
+  "peerDependencies": {
+    "eve": "0.76.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "eve": "0.76.3",
+    "typescript": "^5.9",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}