@segmentstream/agent 0.8.23 → 0.9.0

package/dist/extension/lib/group-routing/router.d.ts

@@ -0,0 +1,109 @@
+import { type GroupPolicy } from "./policy.js";
+import type { ObservedMessage, PendingConfirmation, RecentMessage } from "./observed.js";
+import { type MessageAudience, type AgentIdentity as BotIdentity, type AddressingReason, type GroupMessageSignals } from "./signals.js";
+import type { PendingQuestion } from "../questions.js";
+export type { AddressingReason } from "./signals.js";
+export type Route = "observe" | "reply";
+/** What the decision model sees. */
+export interface RouteQuestion {
+    readonly groups?: GroupPolicy;
+    readonly signals?: GroupMessageSignals;
+    readonly agentInstructions?: string;
+    /** The agent's own description, so the model knows what it can be asked for. */
+    readonly agent: string;
+    readonly agentIdentity?: Partial<BotIdentity> & {
+        readonly aliases: ReadonlyArray<string>;
+    };
+    readonly pendingQuestions?: ReadonlyArray<PendingQuestion & {
+        readonly at?: string;
+    }>;
+    readonly pendingConfirmations?: ReadonlyArray<PendingConfirmation>;
+    /** Registry purpose and usage guidance, available before deciding whether to answer. */
+    readonly chat?: ReadonlyArray<string>;
+    /** Recent received messages and delivered agent replies, oldest first. */
+    readonly recent: ReadonlyArray<RecentMessage>;
+    readonly message: ObservedMessage;
+    readonly audience?: MessageAudience;
+    /** Provider media types when the sender supplied no caption (a transcript may still exist). */
+    readonly captionlessAttachments?: ReadonlyArray<string>;
+}
+export interface RouteDecision {
+    readonly route: Route;
+    readonly reason: string;
+    /** Short observable routing explanation, not hidden model reasoning. */
+    readonly note: string;
+    readonly diagnostics?: RouteDiagnostics;
+    readonly router?: Readonly<Record<string, unknown>>;
+    readonly shadow?: Readonly<Record<string, unknown>>;
+}
+export interface RouteDiagnostics {
+    readonly model: string;
+    readonly latencyMs: number;
+    readonly probabilities?: Readonly<Record<Route, number>>;
+}
+/** Decides whether a group message not addressed to the bot is still for it. */
+export type RouteDecider = (question: RouteQuestion) => Promise<Route | {
+    readonly route: Route;
+    readonly diagnostics: RouteDiagnostics;
+    readonly router?: Readonly<Record<string, unknown>>;
+}>;
+/**
+ * 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;
+            readonly probabilities?: Readonly<Record<Route, number>>;
+        };
+    };
+}>;
+/** One decision should take a moment; a slow one gives up and observes. */
+/** An unthreaded answer minutes later may continue a question, but old questions are not hints. */
+export declare const FOLLOW_UP_WINDOW_MS: number;
+/** Shared bounded conversation evidence for routing and the main model. Facts are hints only. */
+export declare function conversationContext(question: RouteQuestion): Parameters<DecideFunction>[0]["state"];
+/** 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 groups?: GroupPolicy;
+    readonly metrics?: boolean;
+    readonly signals?: GroupMessageSignals;
+    readonly pendingQuestionAt?: string;
+    readonly chatId: string;
+    readonly memberId: string;
+    readonly policy: "smart" | "mention";
+    readonly addressed: AddressingReason | undefined;
+    /** A mention-only answer to a recent durable question, replying to this bot. */
+    readonly recipientAnswer?: boolean;
+    readonly audience?: MessageAudience;
+    readonly record?: (decision: RouteDecision) => void;
+    /** Builds the question only when a decision is needed: it reads the agent's description. */
+    readonly question: () => Promise<RouteQuestion>;
+    readonly beforeDecide?: () => Promise<boolean>;
+    readonly decide: RouteDecider;
+}): Promise<Route>;

package/dist/extension/lib/group-routing/router.mjs

@@ -0,0 +1,383 @@
+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 { DEFAULT_GROUP_POLICY, groupPolicy, overlaySmartPolicy } from "./policy.mjs";
+import { addressingReason, otherRecipient, signalAudience } from "./signals.mjs";
+import { recordRoutingMetric } from "./health.mjs";
+import { humanAddressee, humanThread, questionInvitation, restoreEngagement } from "./engagement.mjs";
+import { boundedRouterPayload, policyHash } from "./record.mjs";
+const FOLLOW_UP_WINDOW_MS = 18e5;
+function isAgentMessage(message) {
+	return "role" in message && message.role === "agent";
+}
+function confirmationProjection(pending, at) {
+	return {
+		action: pending.action.slice(0, 180),
+		requested_by: pending.requestedBy?.slice(0, 180) ?? null,
+		age_seconds: Math.floor((Date.parse(at) - Date.parse(pending.at)) / 1e3),
+		state: pending.state ?? "pending"
+	};
+}
+function recipientLine(recipient) {
+	const identity = [...recipient.id === void 0 ? [] : [`user_id ${recipient.id}`], ...recipient.username === void 0 || recipient.author === `@${recipient.username}` ? [] : [`@${recipient.username}`]];
+	return identity.length === 0 ? recipient.author : `${recipient.author} (${identity.join(", ")})`;
+}
+function line(message, bot, roster, at) {
+	const kind = (recipient) => {
+		if (bot?.id !== void 0 && recipient.id === bot.id || recipient.username !== void 0 && recipient.username.toLowerCase() === bot?.username?.toLowerCase()) return "bot";
+		return roster.find((entry) => recipient.id !== void 0 && recipient.id === entry.authorId || recipient.username !== void 0 && recipient.username.toLowerCase() === entry.username?.toLowerCase())?.kind ?? recipient.kind;
+	};
+	const structure = JSON.stringify({
+		message_id: message.messageId ?? null,
+		sender: {
+			id: (isAgentMessage(message) ? bot?.id : void 0) ?? message.authorId ?? null,
+			kind: isAgentMessage(message) || bot?.id !== void 0 && message.authorId === bot.id ? "bot" : message.kind ?? "unknown",
+			membership: message.membership ?? "unknown"
+		},
+		reply_to: message.replyTo === void 0 ? null : {
+			...message.replyTo,
+			kind: kind(message.replyTo)
+		},
+		tagged_users: (message.taggedUsers ?? []).map((recipient) => ({
+			...recipient,
+			kind: kind(recipient)
+		})),
+		attachment_kinds: message.attachmentKinds ?? [],
+		has_caption: message.hasCaption ?? false,
+		revision: message.revision ?? { edited: false }
+	});
+	if (isAgentMessage(message)) {
+		if (message.confirmation !== void 0) return JSON.stringify(confirmationProjection(message.confirmation, at));
+		const addressedTo = message.addressedTo.map(recipientLine).join(", ");
+		const replyingTo = message.inReplyTo === void 0 ? void 0 : recipientLine(message.inReplyTo);
+		const recipients = addressedTo === "" ? "recipient unspecified" : `addressed to ${addressedTo}`;
+		const reply = replyingTo === void 0 ? "" : `; responding to ${replyingTo}`;
+		return `[${message.at}] THE AGENT (${recipients}${reply}): ${message.text.slice(0, 1e3)}\nstructure: ${structure}`;
+	}
+	const author = recipientLine({
+		author: message.author,
+		...message.authorId === void 0 ? {} : { id: message.authorId },
+		...message.username === void 0 ? {} : { username: message.username }
+	});
+	return [
+		`[${message.at}] ${author}: ${message.text.slice(0, 1e3)}`,
+		...message.media ? [message.media.slice(0, 4e3)] : [],
+		`structure: ${structure}`
+	].join("\n");
+}
+function recentlyAddressed(message, sender) {
+	return message.addressedTo.some((recipient) => recipient.id !== void 0 ? recipient.id === sender.authorId : recipient.username !== void 0 && sender.username !== void 0 && recipient.username.toLowerCase() === sender.username.toLowerCase());
+}
+function lastOutbound(question) {
+	return question.recent.findLast((message) => isAgentMessage(message) && message.messageId !== void 0 && Date.parse(message.at) <= Date.parse(question.message.at));
+}
+function conversationContext(question) {
+	const sentAt = Date.parse(question.message.at);
+	const policy = question.groups ?? DEFAULT_GROUP_POLICY;
+	const recent = question.recent.slice(-policy.smart.context.messages).filter((message) => {
+		if (!isAgentMessage(message)) return true;
+		const age = sentAt - Date.parse(message.at);
+		return age >= 0 && age <= policy.smart.engagement.followUpMinutes * 6e4;
+	});
+	const followUps = recent.filter((message) => isAgentMessage(message) && recentlyAddressed(message, question.message));
+	const bot = question.agentIdentity;
+	const outbound = lastOutbound(question);
+	const roster = [...recent, question.message];
+	const participants = new Map();
+	for (const message of [...recent, question.message]) {
+		if (isAgentMessage(message) && message.confirmation !== void 0) continue;
+		const id = (isAgentMessage(message) ? bot?.id : void 0) ?? message.authorId;
+		participants.set(id ?? message.username ?? message.author, JSON.stringify({
+			id: id ?? null,
+			display_name: isAgentMessage(message) ? bot?.displayName ?? "the agent" : message.author,
+			username: message.username ?? (isAgentMessage(message) ? bot?.username : void 0) ?? null,
+			kind: isAgentMessage(message) || bot?.id !== void 0 && id === bot.id ? "bot" : message.kind ?? "unknown",
+			membership: message.membership ?? "unknown"
+		}));
+	}
+	const openQuestions = recent.filter(isAgentMessage).filter((message) => message.confirmation === void 0).map((message) => JSON.stringify({
+		source: "recent_agent_message",
+		status: "candidate",
+		message_id: message.messageId ?? null,
+		at: message.at,
+		age_seconds: Math.floor((sentAt - Date.parse(message.at)) / 1e3),
+		addressed_to: message.addressedTo,
+		in_reply_to: message.inReplyTo ?? null
+	}));
+	for (const pending of (question.pendingQuestions ?? []).slice(-5)) openQuestions.push(JSON.stringify({
+		source: "durable_pending_question",
+		status: questionInvitation(pending.at, question.message.at, policy.smart.engagement.openQuestionMinutes) ? "pending" : "stale",
+		id: pending.id,
+		question: pending.question.slice(0, 1e3),
+		task: pending.task.slice(0, 1e3),
+		member_id: pending.memberId,
+		at: pending.at ?? null,
+		age_seconds: pending.at === void 0 ? null : Math.max(0, Math.floor((sentAt - Date.parse(pending.at)) / 1e3))
+	}));
+	return {
+		agent: policy.smart.context.includeAgentDescription ? question.agent.slice(0, 4e3) : "",
+		...policy.smart.context.includeAgentInstructions ? { agent_instructions: (question.agentInstructions ?? "").slice(0, typeof policy.smart.context.includeAgentInstructions === "object" ? policy.smart.context.includeAgentInstructions.maxChars : 6e3) } : {},
+		agent_identity: JSON.stringify({
+			display_name: bot?.displayName ?? null,
+			username: bot?.username ?? null,
+			aliases: bot?.aliases ?? []
+		}),
+		group_guidance: (policy.smart.context.includeChatGuidance ? question.chat ?? [] : []).slice(0, 5).map((line) => line.slice(0, 2e3)),
+		participants: policy.smart.context.includeParticipants ? [...participants.values()] : [],
+		...question.signals === void 0 || policy.smart.engagement.policy === "legacy" ? {} : {
+			channel: JSON.stringify({
+				provider: question.signals.provider,
+				thread_with_agent: question.signals.addressing.threadWithAgent
+			}),
+			engagement: JSON.stringify(restoreEngagement(question.signals, question.recent, policy) ?? null),
+			addressee_analysis: JSON.stringify({
+				human: humanAddressee(question.signals, question.recent, policy.participants) ?? null,
+				human_thread: humanThread(question.signals, question.recent, policy.smart.engagement.followUpMinutes)
+			})
+		},
+		recent_messages: recent.map((message) => line(message, bot, roster, question.message.at)),
+		possible_follow_up_to: followUps.map((message) => line(message, bot, roster, question.message.at)),
+		open_questions: openQuestions,
+		last_outbound: JSON.stringify(outbound === void 0 ? null : {
+			...outbound.confirmation === void 0 ? { text: outbound.text.slice(0, 1e3) } : { confirmation: confirmationProjection(outbound.confirmation, question.message.at) },
+			age_seconds: Math.floor((sentAt - Date.parse(outbound.at)) / 1e3),
+			is_question: outbound.confirmation === void 0 && /[?？]/u.test(outbound.text),
+			is_confirmation_prompt: outbound.confirmation !== void 0
+		}),
+		pending_confirmations: (question.pendingConfirmations ?? []).slice(-5).map((pending) => JSON.stringify(confirmationProjection(pending, question.message.at))),
+		message: line(question.message, bot, roster, question.message.at),
+		original_text: (question.audience?.originalText ?? question.message.text).slice(0, 1e3),
+		reply_target: JSON.stringify(question.recent.some((message) => isAgentMessage(message) && message.confirmation !== void 0 && message.messageId === question.audience?.replyTo?.messageId) ? {
+			...question.audience?.replyTo,
+			text: void 0
+		} : question.audience?.replyTo ?? null),
+		tagged_users: (question.audience?.mentions ?? []).map((item) => JSON.stringify(item)),
+		bot_tagged: String(question.audience?.botTagged ?? false),
+		conversation_signals: JSON.stringify({
+			reply_to: question.message.replyTo ?? null,
+			tagged_users: question.message.taggedUsers ?? [],
+			human_to_human_reply: question.message.kind === "human" && question.message.replyTo?.kind === "human",
+			recent_human_reply_edges: recent.filter((message) => !isAgentMessage(message) && message.replyTo?.kind === "human").slice(-5).map((message) => ({
+				message_id: message.messageId ?? null,
+				sender_id: message.authorId ?? null,
+				reply_to: message.replyTo
+			})),
+			seconds_since_last_outbound: outbound === void 0 ? null : Math.floor((sentAt - Date.parse(outbound.at)) / 1e3)
+		}),
+		captionless_attachments: question.captionlessAttachments ?? []
+	};
+}
+function decisionRouter(input) {
+	return async (question) => {
+		const policy = question.groups?.smart;
+		const started = performance.now();
+		const abortSignal = AbortSignal.timeout(Math.ceil((policy?.timeoutSeconds ?? 15) * 1e3));
+		const state = conversationContext(question);
+		const questions = { route: {
+			type: "choice",
+			instructions: policy?.instructions ?? DEFAULT_GROUP_POLICY.smart.instructions,
+			criteria: policy?.criteria ?? DEFAULT_GROUP_POLICY.smart.criteria
+		} };
+		const result = await input.decide({
+			model: policy?.model ?? input.model,
+			state,
+			questions,
+			abortSignal
+		}).catch((error) => {
+			if (abortSignal.aborted) throw new RoutingTimeoutError(error);
+			throw error;
+		});
+		const { choice, probabilities } = result.answers.route;
+		return {
+			route: choice,
+			router: {
+				state,
+				questions,
+				answer: result.answers.route
+			},
+			diagnostics: {
+				model: policy?.model ?? input.model,
+				latencyMs: Math.round(performance.now() - started),
+				...probabilities === void 0 ? {} : { probabilities }
+			}
+		};
+	};
+}
+var RoutingTimeoutError = class extends Error {
+	constructor(cause) {
+		super("Group routing decision timed out.", { cause });
+		this.name = "TimeoutError";
+	}
+};
+async function routeMessage(input) {
+	const groups = input.groups ?? groupPolicy({}, { mode: input.policy });
+	const signals = input.signals;
+	const audience = input.audience ?? (signals === void 0 ? void 0 : signalAudience(signals));
+	let addressed = input.addressed ?? (signals === void 0 ? void 0 : addressingReason(signals));
+	if (addressed === "pending-question" && !questionInvitation(input.pendingQuestionAt, signals?.message.at ?? new Date().toISOString(), groups.smart.engagement.openQuestionMinutes)) addressed = void 0;
+	let payload = {
+		policy_hash: policyHash(groups),
+		provider: signals?.provider,
+		signals,
+		addressed: input.addressed,
+		pending_question_at: input.pendingQuestionAt,
+		recipient_answer: input.recipientAnswer,
+		policy: {
+			...groups,
+			chats: {},
+			observability: { storeRouterPayload: false }
+		}
+	};
+	let question;
+	let shadow;
+	let shadowRun;
+	const evaluateShadow = () => {
+		if (shadowRun !== void 0) return shadowRun;
+		shadowRun = (async () => {
+			if (groups.observability.shadow === void 0) return;
+			try {
+				await routeMessage({
+					...input,
+					groups: {
+						...groups,
+						smart: overlaySmartPolicy(groups.observability.shadow, groups),
+						observability: {
+							...groups.observability,
+							shadow: void 0
+						}
+					},
+					beforeDecide: void 0,
+					metrics: false,
+					question: async () => question ?? input.question(),
+					record: (decision) => {
+						shadow = { ...decision };
+					}
+				});
+			} catch (error) {
+				console.error("[segmentstream] group shadow routing failed", { error });
+				shadow = { reason: "shadow_failed" };
+			}
+		})();
+		return shadowRun;
+	};
+	const complete = async (route, reason, note, logReason = reason, diagnostics) => {
+		if (reason !== "admission_refused") await evaluateShadow();
+		payload = {
+			...payload,
+			decision: {
+				route,
+				reason
+			}
+		};
+		if (input.metrics !== false) recordRoutingMetric(signals?.provider ?? "unknown", route, reason, diagnostics?.latencyMs);
+		input.record?.({
+			route,
+			reason,
+			note,
+			...groups.observability.storeRouterPayload ? { router: boundedRouterPayload(payload) } : {},
+			...shadow === void 0 ? {} : { shadow: groups.observability.storeRouterPayload ? boundedRouterPayload(shadow) : {
+				route: shadow.route,
+				reason: shadow.reason,
+				diagnostics: shadow.diagnostics
+			} },
+			...diagnostics === void 0 ? {} : { diagnostics }
+		});
+		if (reason !== "decision_model_failed" && reason !== "decision_model_timeout") console.info("[segmentstream] telegram route", {
+			route,
+			reason: logReason,
+			...diagnostics
+		});
+		return route;
+	};
+	if (addressed !== void 0 && addressed !== "pending-question" && addressed !== "reply-to-bot") return complete("reply", addressed, `Bot addressed directly: ${addressed}.`);
+	if (input.recipientAnswer && addressed === "reply-to-bot") return complete("reply", "pending-question", "Recipient supplied as the pending question's answer.");
+	const elsewhere = otherRecipient(audience);
+	if (elsewhere !== void 0) return complete("observe", "other_recipient", elsewhere);
+	if (addressed === "reply-to-bot") return complete("reply", "reply-to-bot", "Bot addressed directly: reply-to-bot.");
+	if (signals !== void 0 && groups.smart.engagement.addresseeGate) {
+		const human = humanAddressee(signals, [], groups.participants);
+		if (human !== void 0) {
+			payload = {
+				...payload,
+				addressee_analysis: { human }
+			};
+			return complete("observe", "human_addressee", "Workspace participant alias addresses another person.");
+		}
+	}
+	if (addressed === "pending-question") return complete("reply", "pending-question", "Answer to this member's pending agent question, without another explicit recipient.");
+	if (signals?.addressing.eligible === false) return complete("observe", "channel_ineligible", "Channel signal excludes ambient messages.");
+	if (groups.mode === "mention") return complete("observe", "mention_policy", "Mention policy observes unaddressed messages.");
+	if (input.beforeDecide !== void 0 && !await input.beforeDecide()) return complete("observe", "admission_refused", "Admission refused before decoding or inference.");
+	try {
+		question = {
+			...await input.question(),
+			...input.groups === void 0 ? {} : { groups },
+			...signals === void 0 ? {} : { signals }
+		};
+		const elsewhere = otherRecipient(question.audience);
+		if (elsewhere !== void 0) return complete("observe", "other_recipient", elsewhere);
+		const human = signals === void 0 ? void 0 : humanAddressee(signals, question.recent, groups.participants);
+		const thread = signals !== void 0 && humanThread(signals, question.recent, groups.smart.engagement.followUpMinutes);
+		const engagement = signals === void 0 ? void 0 : restoreEngagement(signals, question.recent, groups);
+		payload = {
+			...payload,
+			engagement,
+			addressee_analysis: {
+				human,
+				human_thread: thread
+			}
+		};
+		if (groups.smart.engagement.addresseeGate && human !== void 0) return complete("observe", "human_addressee", "Participant name addresses another person.");
+		payload = {
+			...payload,
+			question: {
+				recent: question.recent,
+				pendingQuestions: question.pendingQuestions,
+				pendingConfirmations: question.pendingConfirmations,
+				agentIdentity: question.agentIdentity,
+				chat: question.chat,
+				audience: question.audience
+			},
+			state: conversationContext(question),
+			questions: { route: {
+				type: "choice",
+				instructions: groups.smart.instructions,
+				criteria: groups.smart.criteria
+			} }
+		};
+		evaluateShadow();
+		const result = await input.decide(question);
+		const probability = typeof result === "string" ? void 0 : result.diagnostics.probabilities?.reply;
+		const threshold = thread ? groups.smart.thresholds.humanThread : engagement?.strength === "explicit" ? groups.smart.thresholds.engaged : groups.smart.thresholds.neutral;
+		const selected = typeof result === "string" ? result : result.route;
+		const below = (groups.smart.engagement.policy === "engaged" || Object.entries(groups.sources).some(([path, source]) => path.startsWith("smart.thresholds.") && source !== "platform")) && selected === "reply" && probability !== void 0 && probability < threshold;
+		const route = below ? "observe" : selected;
+		payload = {
+			...payload,
+			...typeof result === "string" ? {
+				state: conversationContext(question),
+				answer: { choice: result }
+			} : result.router,
+			thresholds_applied: {
+				threshold,
+				probability,
+				category: thread ? "humanThread" : engagement?.strength === "explicit" ? "engaged" : "neutral"
+			}
+		};
+		return complete(route, below ? "decision_model_below_threshold" : `decision_model_${route}`, `Smart model selected ${route}; reply target: ${question.audience?.replyTo?.kind ?? "none"}; tagged recipients: ${question.audience?.mentions.length ?? 0}.`, "decision-model", typeof result === "string" ? void 0 : result.diagnostics);
+	} catch (error) {
+		const timeout = error instanceof Error && error.name === "TimeoutError";
+		const note = timeout ? "Routing timed out; observe fallback." : "Routing failed; observe fallback.";
+		console.error("[segmentstream] telegram route", {
+			route: "observe",
+			reason: timeout ? "decision-timeout" : "decision-failure",
+			note,
+			error
+		});
+		return complete("observe", timeout ? "decision_model_timeout" : "decision_model_failed", note);
+	}
+}
+export { FOLLOW_UP_WINDOW_MS, conversationContext, decisionRouter, routeMessage };

package/dist/extension/lib/group-routing/routing-context.d.ts

@@ -0,0 +1,4 @@
+import { type RecentMessage } from "./observed.js";
+import { type ConversationPage } from "../conversations.js";
+/** Cold ring: the same 30 messages, including unlinked humans and confirmed delivered bot messages. */
+export declare function archivedRoutingMessages(events: ConversationPage["events"], limit?: number): ReadonlyArray<RecentMessage>;

package/dist/extension/lib/group-routing/routing-context.mjs

@@ -0,0 +1,96 @@
+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 { agentMessage } from "./observed.mjs";
+import { collapseConversationEvents } from "../conversations.mjs";
+function archivedMetadata(event) {
+	try {
+		return JSON.parse(event.argsSummary ?? "null")?.routing ?? {};
+	} catch {
+		return {};
+	}
+}
+function archivedRoutingMessages(events, limit = 30) {
+	const messages = collapseConversationEvents(events).filter((event) => event.kind === "inbound" || event.kind === "outbound" && (event.status === "sent" || event.status === "completed"));
+	const deferredStates = new Map();
+	for (const event of [...events].reverse()) {
+		if (event.kind !== "tool_result" || event.operationId == null) continue;
+		const state = event.reason === "done" ? "completed" : event.reason;
+		if ([
+			"approved",
+			"cancelled",
+			"expired",
+			"completed",
+			"failed"
+		].includes(state ?? "")) deferredStates.set(event.operationId, state);
+	}
+	const invitations = new Map(events.filter((event) => event.kind === "decision" && event.decision === "reply" && event.messageId !== null && [
+		"mention",
+		"command",
+		"reply-to-bot",
+		"thread-with-agent",
+		"pending-question"
+	].includes(event.reason ?? "")).map((event) => [event.messageId, event.reason]));
+	const membership = new Map();
+	for (const event of [...events].reverse()) {
+		if (event.kind !== "decision" || event.senderId === null) continue;
+		const known = archivedMetadata(event).membership;
+		if (known === "linked" || known === "unlinked") membership.set(event.senderId, known);
+		else if (event.reason === "identity_unknown") membership.set(event.senderId, "unlinked");
+	}
+	return messages.slice(0, limit).reverse().map((event) => {
+		const metadata = archivedMetadata(event);
+		const prompt = metadata.confirmation;
+		const decision = prompt?.mode === "deferred" ? deferredStates.get(prompt.requestId) : void 0;
+		const parent = messages.find((candidate) => candidate.messageId !== null && candidate.messageId === event.replyToMessageId);
+		const replyTo = metadata.replyTo ?? (event.replyToMessageId === null ? void 0 : {
+			messageId: event.replyToMessageId,
+			kind: parent === void 0 ? "unknown" : parent.kind === "outbound" ? "bot" : parent.senderIsBot ? "other_bot" : "human",
+			...parent?.senderId == null ? {} : { id: parent.senderId },
+			...parent?.senderName == null ? {} : { name: parent.senderName }
+		});
+		const derivedText = metadata.decoded?.flatMap((item) => item.content === void 0 ? [] : [item.content]).join("\n");
+		const text = (event.text || derivedText || (metadata.media ? "" : "[attachment or service message]")).slice(0, 2e3);
+		const common = {
+			invitation: metadata.invitation ?? invitations.get(event.messageId ?? ""),
+			author: event.senderName ?? event.senderId ?? "unknown sender",
+			text,
+			...metadata.media === void 0 ? {} : { media: metadata.media },
+			at: event.at,
+			...event.messageId === null ? {} : { messageId: event.messageId },
+			...event.senderId === null ? {} : { authorId: event.senderId },
+			...metadata.username === void 0 ? {} : { username: metadata.username },
+			kind: metadata.kind ?? (event.senderIsBot ? "other_bot" : event.senderId === null ? "unknown" : "human"),
+			membership: metadata.membership ?? membership.get(event.senderId ?? "") ?? "unknown",
+			...replyTo === void 0 ? {} : { replyTo },
+			taggedUsers: metadata.taggedUsers ?? [...text.matchAll(/(?:^|[^A-Za-z0-9_])@([A-Za-z0-9_]+)/gu)].map((match) => ({
+				type: "mention",
+				kind: "unknown",
+				username: match[1],
+				text: `@${match[1]}`
+			})),
+			attachmentKinds: metadata.attachmentKinds ?? [...new Set(event.attachments.map((file) => file.kind))],
+			hasCaption: metadata.hasCaption ?? (event.attachments.length > 0 && (event.text?.trim() ?? "") !== ""),
+			revision: metadata.revision ?? { edited: event.eventId.includes(":edit:") }
+		};
+		return event.kind === "outbound" ? {
+			...common,
+			...prompt === void 0 ? {} : { confirmation: {
+				...prompt,
+				...decision === void 0 ? {} : { state: decision }
+			} },
+			...agentMessage({
+				text,
+				at: event.at,
+				...metadata.inReplyTo !== void 0 ? { inReplyTo: metadata.inReplyTo } : parent?.senderId == null ? {} : { inReplyTo: {
+					id: parent.senderId,
+					author: parent.senderName ?? parent.senderId
+				} }
+			})
+		} : common;
+	});
+}
+export { archivedRoutingMessages };

package/dist/extension/lib/group-routing/settings.d.ts

@@ -0,0 +1,14 @@
+import { type GroupPolicyInput } from "@segmentstream-cloud/ontology/groups";
+import { type Environment } from "../environment.js";
+import { type RuntimeToken } from "../runtime-token.js";
+export interface CloudGroupSettings {
+    readonly settings: GroupPolicyInput;
+    readonly instructions?: string;
+}
+/** Bounded request-scoped identity, one policy refresh per minute, last known override on transient failure. */
+export declare function groupSettings(input?: {
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+}): () => Promise<CloudGroupSettings | undefined>;

package/dist/extension/lib/group-routing/settings.mjs

@@ -0,0 +1,58 @@
+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 { proxyEnvironment } from "../environment.mjs";
+import { runtimeToken } from "../runtime-token.mjs";
+import { groupPolicyIssues } from "@segmentstream-cloud/ontology/groups";
+function groupSettings(input = {}) {
+	let cached;
+	let expires = 0;
+	let etag;
+	let pending;
+	const now = input.now ?? Date.now;
+	return async () => {
+		if (now() < expires) return cached;
+		if (pending !== void 0) return pending;
+		pending = (async () => {
+			try {
+				const env = proxyEnvironment(input.environment);
+				const identity = await (input.token ?? runtimeToken)();
+				const workspacePath = `/api/internal/v1/workspaces/${encodeURIComponent(env.workspaceId)}`;
+				const response = await (input.fetch ?? fetch)(`${env.segmentstreamUrl}${workspacePath}/agent/groups/effective`, {
+					redirect: "error",
+					headers: {
+						"x-segmentstream-organization-id": env.organizationId,
+						"x-segmentstream-runtime-identity": identity,
+						...etag === void 0 ? {} : { "if-none-match": etag }
+					},
+					signal: AbortSignal.timeout(5e3)
+				});
+				if (response.status === 304) return cached;
+				if (response.status === 404) return cached;
+				if (!response.ok) throw new Error(`Group settings read failed (${response.status}); request ${response.headers.get("x-request-id") ?? "unknown"}.`);
+				const value = await response.json();
+				if (value.settings === void 0 || groupPolicyIssues(value.settings).length > 0) throw new Error("Invalid group settings response.");
+				cached = {
+					settings: value.settings,
+					...typeof value.instructions === "string" ? { instructions: value.instructions.slice(0, 6e3) } : {}
+				};
+				etag = response.headers.get("etag") ?? (typeof value.version === "string" ? `"${value.version}"` : void 0);
+				return cached;
+			} catch (error) {
+				console.error("[segmentstream] group settings refresh failed", { error });
+				return cached;
+			} finally {
+				expires = now() + 6e4;
+			}
+		})();
+		try {
+			return await pending;
+		} finally {
+			pending = void 0;
+		}
+	};
+}
+export { groupSettings };