@segmentstream/agent 0.1.3 → 0.1.5

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

@@ -0,0 +1,84 @@
+import type { TelegramMessage } from "eve/channels/telegram";
+import type { SessionSettings } from "../../config.js";
+/**
+ * Session policy for the Telegram channel (`agent-design.md`, section 4, and docs/agent.md,
+ * "Sessions"): what a group session spans, the daily compaction and the idle reset. The policy
+ * runs in the webhook route, before eve delivers a message, with the operations the route offers
+ * on a continuation address (`resolveSession`, `compact`, `clear`); the history it needs is read
+ * from the session's own durable stream, so nothing is stored beside eve.
+ */
+/** eve's Telegram continuation address: `chat:thread:conversation`, the last two possibly empty. */
+export interface TelegramAddress {
+    readonly chatId: string;
+    readonly messageThreadId: string;
+    readonly conversationId: string;
+}
+export declare function parseAddress(address: string): TelegramAddress;
+export declare function formatAddress(address: TelegramAddress): string;
+/**
+ * The address eve derives from an inbound message: the chat, the forum topic and, in a group, the
+ * reply thread (a reply to the bot continues the bot's message, anything else starts its own).
+ */
+export declare function messageAddress(message: TelegramMessage): string;
+/**
+ * The address a message continues under the configured scope. `chat` drops eve's reply-thread
+ * anchor, so every message of a group chat (and forum topic) reaches one session; `thread` keeps
+ * eve's own address. A private chat has no anchor either way.
+ */
+export declare function scopedAddress(address: string, scope: SessionSettings["scope"]): string;
+/** The most recent `HH:MM` in `timezone` at or before `now`. */
+export declare function compactBoundary(now: Date, compactAt: string, timezone: string): Date;
+/** What the policy knows about one session: from its stream, then kept per process. */
+export interface SessionHistory {
+    /** When the session last did anything. */
+    readonly lastAt: number;
+    /** When its history last started afresh: creation, compaction or clear. */
+    readonly resetAt: number;
+    /** Turns completed since `resetAt`; a compaction is worth nothing before the first. */
+    readonly turnsSinceReset: number;
+}
+/** One recorded event, as much of eve's envelope as the policy reads. */
+export interface RecordedEvent {
+    readonly type: string;
+    readonly meta: {
+        readonly at: string;
+    };
+}
+/** The last events of a session, oldest first. Production reads eve's durable stream. */
+export type HistoryReader = (sessionId: string) => Promise<ReadonlyArray<RecordedEvent>>;
+/** How many events of the tail the reader fetches: enough for a day of a busy group. */
+export declare const HISTORY_TAIL = 400;
+/** Folds a tail into a history; with no reset marker in it, `resetAt` is its earliest event. */
+export declare function historyOf(events: ReadonlyArray<RecordedEvent>): SessionHistory;
+/** The route's operations on a continuation address, as eve gives them to the handler. */
+export interface SessionOperations {
+    readonly resolveSession: (address: string) => Promise<{
+        readonly id: string;
+    } | undefined>;
+    readonly from: (address: string) => {
+        compact(): Promise<unknown>;
+        clear(): Promise<unknown>;
+    };
+}
+export type SessionAction = "none" | "cleared" | "compacted";
+export interface SessionPolicy {
+    /**
+     * Applies the policy to the session `address` continues, before a message is delivered to it:
+     * clears a history idle for longer than `idleResetHours`, else compacts it once after each
+     * day's `compactAt`. A session that does not exist yet needs neither.
+     */
+    apply(input: {
+        readonly address: string;
+        readonly operations: SessionOperations;
+        /** The newest activity the stream does not show, such as an observed group message. */
+        readonly activeAt?: number;
+        readonly now?: Date;
+    }): Promise<SessionAction>;
+    /** Records that a message was just delivered to the session. */
+    delivered(address: string, now?: Date): void;
+}
+export declare function sessionPolicy(input: {
+    readonly settings: () => SessionSettings;
+    readonly read: HistoryReader;
+    readonly log?: (message: string, error: unknown) => void;
+}): SessionPolicy;

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

@@ -0,0 +1,200 @@
+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 parseAddress(address) {
+	const [chatId = "", messageThreadId = "", conversationId = ""] = address.split(":");
+	return {
+		chatId,
+		messageThreadId,
+		conversationId
+	};
+}
+function formatAddress(address) {
+	return `${address.chatId}:${address.messageThreadId}:${address.conversationId}`;
+}
+function messageAddress(message) {
+	const group = message.chat.type === "group" || message.chat.type === "supergroup";
+	const reply = message.replyToMessage;
+	const conversationId = !group ? "" : reply?.from?.isBot === true ? reply.messageId : message.messageId;
+	return formatAddress({
+		chatId: message.chat.id,
+		messageThreadId: message.messageThreadId === void 0 ? "" : String(message.messageThreadId),
+		conversationId
+	});
+}
+function scopedAddress(address, scope) {
+	if (scope === "thread") return address;
+	return formatAddress({
+		...parseAddress(address),
+		conversationId: ""
+	});
+}
+function localParts(timezone, date) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone: timezone,
+		hourCycle: "h23",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit"
+	}).formatToParts(date);
+	const value = (type) => Number(parts.find((part) => part.type === type)?.value ?? "0");
+	return {
+		year: value("year"),
+		month: value("month"),
+		day: value("day"),
+		hour: value("hour"),
+		minute: value("minute"),
+		second: value("second")
+	};
+}
+function offsetMinutes(timezone, date) {
+	const local = localParts(timezone, date);
+	const asUtc = Date.UTC(local.year, local.month - 1, local.day, local.hour, local.minute, local.second);
+	return Math.round((asUtc - date.getTime()) / 6e4);
+}
+function instantOf(timezone, local) {
+	const guess = Date.UTC(local.year, local.month - 1, local.day, local.hour, local.minute);
+	const first = new Date(guess - offsetMinutes(timezone, new Date(guess)) * 6e4);
+	const second = new Date(guess - offsetMinutes(timezone, first) * 6e4);
+	const back = localParts(timezone, second);
+	if (back.hour !== local.hour || back.minute !== local.minute) return first > second ? first : second;
+	return second;
+}
+function compactBoundary(now, compactAt, timezone) {
+	const [hour = 0, minute = 0] = compactAt.split(":").map(Number);
+	const today = localParts(timezone, now);
+	const candidate = instantOf(timezone, {
+		...today,
+		hour,
+		minute
+	});
+	if (candidate.getTime() <= now.getTime()) return candidate;
+	const yesterday = new Date(Date.UTC(today.year, today.month - 1, today.day - 1));
+	return instantOf(timezone, {
+		year: yesterday.getUTCFullYear(),
+		month: yesterday.getUTCMonth() + 1,
+		day: yesterday.getUTCDate(),
+		hour,
+		minute
+	});
+}
+const HISTORY_TAIL = 400;
+function historyOf(events) {
+	let lastAt = 0;
+	let resetAt = 0;
+	let earliest = 0;
+	let marked = false;
+	let turnsSinceReset = 0;
+	for (const event of events) {
+		const at = Date.parse(event.meta.at);
+		if (Number.isNaN(at)) continue;
+		lastAt = Math.max(lastAt, at);
+		earliest = earliest === 0 ? at : Math.min(earliest, at);
+		if (event.type === "session.started" || event.type === "compaction.completed" || event.type === "context.cleared") {
+			resetAt = at;
+			marked = true;
+			turnsSinceReset = 0;
+		} else if (event.type === "turn.completed") turnsSinceReset += 1;
+	}
+	return {
+		lastAt,
+		resetAt: marked ? resetAt : earliest,
+		turnsSinceReset
+	};
+}
+const MAXIMUM_REMEMBERED = 500;
+function sessionPolicy(input) {
+	const remembered = new Map();
+	const log = input.log ?? ((message, error) => console.warn(message, error));
+	function remember(address, history) {
+		remembered.delete(address);
+		remembered.set(address, history);
+		if (remembered.size > MAXIMUM_REMEMBERED) {
+			const oldest = remembered.keys().next();
+			if (oldest.done !== true) remembered.delete(oldest.value);
+		}
+	}
+	async function history(address, operations, fresh = false) {
+		const known = fresh ? void 0 : remembered.get(address);
+		if (known !== void 0) return known;
+		const session = await operations.resolveSession(address);
+		if (session === void 0) {
+			remembered.delete(address);
+			return;
+		}
+		const read = historyOf(await input.read(session.id));
+		remember(address, read);
+		return read;
+	}
+	function due(known, settings, now, activeAt) {
+		const idle = settings.idleResetHours;
+		const lastAt = Math.max(known.lastAt, activeAt);
+		if (idle !== false && now.getTime() - lastAt >= idle * 36e5) return "clear";
+		if (settings.compactAt !== false) {
+			const boundary = compactBoundary(now, settings.compactAt, settings.timezone).getTime();
+			if (known.resetAt < boundary && known.turnsSinceReset > 0) return "compact";
+		}
+		return "none";
+	}
+	return {
+		async apply({ address, operations, activeAt = 0, now = new Date() }) {
+			const settings = input.settings();
+			const cached = remembered.has(address);
+			let known;
+			try {
+				known = await history(address, operations);
+			} catch (error) {
+				log("The session policy could not read the session's history; delivering as is.", error);
+				return "none";
+			}
+			if (known === void 0) return "none";
+			let action = due(known, settings, now, activeAt);
+			if (action !== "none" && cached) {
+				try {
+					known = await history(address, operations, true);
+				} catch (error) {
+					log("The session policy could not re-read the session's history; delivering as is.", error);
+					return "none";
+				}
+				if (known === void 0) return "none";
+				action = due(known, settings, now, activeAt);
+			}
+			if (action === "clear") try {
+				await operations.from(address).clear();
+				remember(address, {
+					lastAt: known.lastAt,
+					resetAt: now.getTime(),
+					turnsSinceReset: 0
+				});
+				return "cleared";
+			} catch (error) {
+				log("The idle reset could not clear the session; delivering as is.", error);
+				return "none";
+			}
+			if (action === "compact") try {
+				await operations.from(address).compact();
+				remembered.delete(address);
+				return "compacted";
+			} catch (error) {
+				log("The daily compaction could not be queued; delivering as is.", error);
+			}
+			return "none";
+		},
+		delivered(address, now = new Date()) {
+			const known = remembered.get(address);
+			if (known === void 0) return;
+			remember(address, {
+				lastAt: now.getTime(),
+				resetAt: known.resetAt,
+				turnsSinceReset: known.turnsSinceReset + 1
+			});
+		}
+	};
+}
+export { HISTORY_TAIL, compactBoundary, formatAddress, historyOf, messageAddress, parseAddress, scopedAddress, sessionPolicy };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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",
@@ -61,7 +61,8 @@
   },
   "dependencies": {
     "@vercel/oidc": "^3.8.4",
-    "ai": "^7.0.128"
+    "ai": "^7.0.128",
+    "jose": "^6.2.12"
   },
   "peerDependencies": {
     "eve": "0.76.3"