@segmentstream/agent 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,7 @@
+/**
+ * `segmentstream__ontology`: the ontology's MCP tools, acting as the member of each turn. It is
+ * resolved per turn because a group chat's session serves several members; a turn without a
+ * paired member, or a mount with `ontology.connection: false`, gets no connection.
+ */
+declare const _default: import("eve").DynamicSentinel<import("eve/connections").DynamicConnectionResult>;
+export default _default;

package/dist/extension/connections/ontology.mjs

@@ -0,0 +1,11 @@
+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.mjs";
+import { ontologyConnection } from "../lib/ontology-connection.mjs";
+import { defineDynamic } from "eve/connections";
+var ontology_default = defineDynamic({ events: { "turn.started": (_event, context) => segmentstream.config.ontology.connection ? ontologyConnection({ principal: context.session.auth.current }) : null } });
+export { ontology_default as default };

package/dist/extension/extension.d.ts

@@ -0,0 +1,19 @@
+import { manifestOf } from "./config.js";
+import { model } from "./model.js";
+export declare const segmentstream: import("eve/extension").ExtensionHandle<{
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: "segmentstream";
+        readonly validate: typeof import("./config.js").validateConfig;
+        readonly types: {
+            readonly input: import("./config.js").SegmentStreamAgentConfigInput;
+            readonly output: import("./config.js").SegmentStreamAgentConfig;
+        };
+    };
+}> & {
+    model: typeof model;
+    manifestOf: typeof manifestOf;
+};
+export default segmentstream;
+export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, manifestOf, type SegmentStreamAgentConfig, type SegmentStreamAgentConfigInput, type TelegramPolicy, type TelegramSettings, } from "./config.js";
+export { chooseModel, model, type DynamicModel, type ModelChoice } from "./model.js";

package/dist/extension/extension.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);
+import { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, configSchema, manifestOf } from "./config.mjs";
+import { chooseModel, model } from "./model.mjs";
+import { defineExtension } from "eve/extension";
+const extension = defineExtension({ config: configSchema });
+const segmentstream = Object.assign(extension, {
+	model,
+	manifestOf
+});
+export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, chooseModel, segmentstream as default, segmentstream, manifestOf, model };

package/dist/extension/instructions.md

@@ -0,0 +1,13 @@
+# SegmentStream platform
+
+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 the `segmentstream__ontology`
+  connection. Call `describe` for the catalog of entities and actions, and `me` for whom you act
+  for and what they may do. The tools you see are already narrowed to that member's permissions;
+  if a tool is missing, the member may not use it, so say so instead of looking for a way around.
+- Every change goes through an action. Never claim a record changed unless an action reported it.
+- Never invent records or values. Say when the ontology does not hold what was asked.
+- When you have been routed a message but a reply would add nothing, answer with exactly
+  `[SILENT]` and nothing else. Use it only in that case; it suppresses delivery to the chat.

package/dist/extension/lib/connection-proxy.d.ts

@@ -0,0 +1,57 @@
+import type { ProxyEnvironment } from "./environment.js";
+import type { RuntimeToken } from "./runtime-token.js";
+/**
+ * A client for backend-next's connection proxy, the route the deployed ontology service already
+ * uses (`ontology-connections-spec.md`, "The proxy for the ontology service"). The agent is the
+ * same deployment, so it authenticates the same way: the Vercel OIDC token proves the workspace's
+ * application, and the organization id only selects the tenant. The provider credential stays in
+ * backend-next; this process never sees it.
+ */
+/** The largest request or response body the proxy forwards. */
+export declare const MAXIMUM_PROXY_BODY_BYTES: number;
+/** One provider request: `OntologyProxyRequest` before it is encoded. */
+export interface ProxyCall {
+    /** One of the connection's APIs, such as Telegram's `bot` or `file`; its default when omitted. */
+    readonly api?: string;
+    readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    /** The path and query relative to the API's base URL. */
+    readonly path: string;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+    readonly body: Uint8Array;
+}
+/** What the provider answered, buffered by the proxy. */
+export interface ProxyReply {
+    readonly status: number;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+    readonly body: Uint8Array;
+}
+/**
+ * SegmentStream refused or could not complete a proxy call. A provider's non-2xx status is a
+ * reply, not this error. `code` is the proxy's error code, such as `connection_not_granted`.
+ */
+export declare class ConnectionProxyError extends Error {
+    readonly name = "ConnectionProxyError";
+    readonly connection: string;
+    readonly code: string;
+    readonly status: number | undefined;
+    readonly requestId: string | undefined;
+    constructor(input: {
+        readonly connection: string;
+        readonly code: string;
+        readonly message: string;
+        readonly status?: number;
+        readonly requestId?: string;
+        readonly cause?: unknown;
+    });
+}
+export interface ConnectionProxy {
+    readonly connection: string;
+    request(call: ProxyCall): Promise<ProxyReply>;
+}
+/** Sends calls through one connection with the deployment's OIDC token. */
+export declare function connectionProxy(input: {
+    readonly environment: ProxyEnvironment;
+    readonly connection: string;
+    readonly token: RuntimeToken;
+    readonly fetch?: typeof fetch;
+}): ConnectionProxy;

package/dist/extension/lib/connection-proxy.mjs

@@ -0,0 +1,113 @@
+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 MAXIMUM_PROXY_BODY_BYTES = 2097152;
+const CALL_TIMEOUT_MS = 4e4;
+var ConnectionProxyError = class extends Error {
+	name = "ConnectionProxyError";
+	connection;
+	code;
+	status;
+	requestId;
+	constructor(input) {
+		super(input.message, input.cause === void 0 ? void 0 : { cause: input.cause });
+		this.connection = input.connection;
+		this.code = input.code;
+		this.status = input.status;
+		this.requestId = input.requestId;
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHeaderPairs(value) {
+	return Array.isArray(value) && value.every((pair) => Array.isArray(pair) && pair.length === 2 && typeof pair[0] === "string" && typeof pair[1] === "string");
+}
+function decodeReply(connection, value) {
+	if (!isRecord(value) || typeof value.statusCode !== "number" || !isHeaderPairs(value.headers) || typeof value.body !== "string") throw new ConnectionProxyError({
+		connection,
+		code: "invalid_response",
+		message: "The connection proxy answered with an invalid response."
+	});
+	return {
+		status: value.statusCode,
+		headers: value.headers,
+		body: new Uint8Array(Buffer.from(value.body, "base64"))
+	};
+}
+function refusal(connection, status, value, cause) {
+	const code = isRecord(value) && typeof value.error === "string" ? value.error : `http_${status}`;
+	const detail = isRecord(value) && typeof value.detail === "string" ? value.detail : void 0;
+	const requestId = isRecord(value) && typeof value.requestId === "string" ? value.requestId : void 0;
+	return new ConnectionProxyError({
+		connection,
+		code,
+		status,
+		message: detail ?? `SegmentStream refused the call through the connection ${connection} (${code}).`,
+		...requestId === void 0 ? {} : { requestId },
+		...cause === void 0 ? {} : { cause }
+	});
+}
+function connectionProxy(input) {
+	const { environment, connection } = input;
+	const fetchImpl = input.fetch ?? fetch;
+	const url = `${`${environment.segmentstreamUrl}/api/internal/v1/workspaces/${environment.workspaceId}`}/ontology/connections/${encodeURIComponent(connection)}/request`;
+	return {
+		connection,
+		async request(call) {
+			if (call.body.byteLength > 2097152) throw new ConnectionProxyError({
+				connection,
+				code: "invalid_request",
+				message: "The request body exceeds the proxy's 2 MiB limit."
+			});
+			const token = await input.token();
+			let response;
+			try {
+				response = await fetchImpl(url, {
+					method: "POST",
+					headers: {
+						"x-segmentstream-runtime-identity": token,
+						"x-segmentstream-organization-id": environment.organizationId,
+						"content-type": "application/json",
+						accept: "application/json"
+					},
+					body: JSON.stringify({
+						...call.api === void 0 ? {} : { api: call.api },
+						method: call.method,
+						path: call.path,
+						headers: call.headers,
+						body: Buffer.from(call.body).toString("base64")
+					}),
+					redirect: "error",
+					signal: AbortSignal.timeout(CALL_TIMEOUT_MS)
+				});
+			} catch (error) {
+				throw new ConnectionProxyError({
+					connection,
+					code: error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "unavailable",
+					message: "SegmentStream's connection proxy could not be reached.",
+					cause: error
+				});
+			}
+			const text = await response.text();
+			let value;
+			try {
+				value = JSON.parse(text);
+			} catch (error) {
+				if (response.ok) throw new ConnectionProxyError({
+					connection,
+					code: "invalid_response",
+					message: "The connection proxy answered with an invalid response.",
+					cause: error
+				});
+				throw refusal(connection, response.status, void 0, error);
+			}
+			if (!response.ok) throw refusal(connection, response.status, value);
+			return decodeReply(connection, value);
+		}
+	};
+}
+export { ConnectionProxyError, MAXIMUM_PROXY_BODY_BYTES, connectionProxy };

package/dist/extension/lib/environment.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The deployment's environment, as the platform sets it on the workspace's Vercel project. Only
+ * the webhook secret is sensitive; the rest names where things are.
+ */
+export type Environment = Readonly<Record<string, string | undefined>>;
+/** A variable the agent needs is missing or malformed. The message names it, never its value. */
+export declare class AgentEnvironmentError extends Error {
+    readonly name = "AgentEnvironmentError";
+}
+/**
+ * Where the workspace app answers: the ontology service's `/mcp` and `/api/ontology/*`, and the
+ * app's `/agent/connect` page. `SEGMENTSTREAM_AGENT_ONTOLOGY_URL` overrides it in local
+ * development; deployments use their production domain.
+ */
+export declare function appOrigin(environment?: Environment): string;
+/** What the connection proxy needs: backend-next's URL and the tenant it selects. */
+export interface ProxyEnvironment {
+    readonly segmentstreamUrl: string;
+    readonly workspaceId: string;
+    readonly organizationId: string;
+}
+export declare function proxyEnvironment(environment?: Environment): ProxyEnvironment;
+/** The secret Telegram echoes in `X-Telegram-Bot-Api-Secret-Token`; `undefined` when unset. */
+export declare function webhookSecret(environment?: Environment): string | undefined;
+/**
+ * Channels answer only in production. A preview shares the production bot's credential through
+ * the same connection, so it must never answer a real chat.
+ */
+export declare function channelsEnabled(environment?: Environment): boolean;
+export declare function isPreview(environment?: Environment): boolean;

package/dist/extension/lib/environment.mjs

@@ -0,0 +1,46 @@
+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);
+var AgentEnvironmentError = class extends Error {
+	name = "AgentEnvironmentError";
+};
+function required(environment, name) {
+	const value = environment[name];
+	if (value === void 0 || value.trim() === "") throw new AgentEnvironmentError(`${name} is not set on this deployment.`);
+	return value.trim();
+}
+function withoutTrailingSlashes(url) {
+	let end = url.length;
+	while (end > 0 && url[end - 1] === "/") end -= 1;
+	return url.slice(0, end);
+}
+function appOrigin(environment = process.env) {
+	const override = environment.SEGMENTSTREAM_AGENT_ONTOLOGY_URL;
+	if (override !== void 0 && override.trim() !== "") {
+		const url = URL.canParse(override) ? new URL(override) : void 0;
+		if (url === void 0 || url.protocol !== "https:" && url.protocol !== "http:") throw new AgentEnvironmentError("SEGMENTSTREAM_AGENT_ONTOLOGY_URL must be an http(s) URL.");
+		return withoutTrailingSlashes(`${url.origin}${url.pathname}`);
+	}
+	return `https://${required(environment, "VERCEL_PROJECT_PRODUCTION_URL")}`;
+}
+function proxyEnvironment(environment = process.env) {
+	return {
+		segmentstreamUrl: withoutTrailingSlashes(required(environment, "SEGMENTSTREAM_URL")),
+		workspaceId: required(environment, "SEGMENTSTREAM_WORKSPACE_ID"),
+		organizationId: required(environment, "SEGMENTSTREAM_ORGANIZATION_ID")
+	};
+}
+function webhookSecret(environment = process.env) {
+	const secret = environment.SEGMENTSTREAM_AGENT_WEBHOOK_SECRET;
+	return secret === void 0 || secret === "" ? void 0 : secret;
+}
+function channelsEnabled(environment = process.env) {
+	return environment.VERCEL_ENV === "production";
+}
+function isPreview(environment = process.env) {
+	return environment.VERCEL_ENV === "preview";
+}
+export { AgentEnvironmentError, appOrigin, channelsEnabled, isPreview, proxyEnvironment, webhookSecret };

package/dist/extension/lib/identities.d.ts

@@ -0,0 +1,65 @@
+import type { RuntimeToken } from "./runtime-token.js";
+/**
+ * The ontology service's pairing routes (`agent-design.md`, section 13, "Identity"). The agent
+ * calls them as the deployment, with its OIDC token: it looks up which member a chat account is
+ * paired with, and asks for a pairing code when it is paired with nobody. The member approves the
+ * code on the app's `/agent/connect` page.
+ */
+/** A member as the ontology resolves a paired chat account, with their current roles. */
+export interface PairedMember {
+    readonly id: string;
+    readonly name: string | null;
+    readonly roles: ReadonlyArray<string>;
+}
+export type IdentityLookup = {
+    readonly status: "paired";
+    readonly member: PairedMember;
+}
+/** The account is paired with nobody. */
+ | {
+    readonly status: "unknown";
+}
+/** The pairing was revoked, or the member is inactive. */
+ | {
+    readonly status: "refused";
+};
+/** A pairing code the member approves at `/agent/connect?code=<code>`. */
+export interface Pairing {
+    readonly code: string;
+    readonly expiresAt: string;
+}
+/** A chat account on one channel, such as Telegram user `42`. */
+export interface ChatAccount {
+    readonly provider: string;
+    readonly externalId: string;
+}
+export interface AgentIdentities {
+    lookup(account: ChatAccount): Promise<IdentityLookup>;
+    /** Issues a pairing code, or returns the account's pending one while it has time left. */
+    createPairing(account: ChatAccount & {
+        readonly display?: string;
+    }): Promise<Pairing>;
+}
+/** The ontology service refused or failed a pairing call. Carries its error code, not its body. */
+export declare class AgentIdentityError extends Error {
+    readonly name = "AgentIdentityError";
+    readonly code: string;
+    readonly status: number | undefined;
+    constructor(input: {
+        readonly code: string;
+        readonly message: string;
+        readonly status?: number;
+        readonly cause?: unknown;
+    });
+}
+/**
+ * The pairing client. Every message looks its sender up afresh, so a revoked account or a removed
+ * member is refused at once; only pending pairing codes are remembered per process.
+ */
+export declare function agentIdentities(input: {
+    /** The workspace app's origin, where the ontology service answers `/api/ontology/*`. */
+    readonly origin: string;
+    readonly token: RuntimeToken;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+}): AgentIdentities;

package/dist/extension/lib/identities.mjs

@@ -0,0 +1,133 @@
+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);
+var AgentIdentityError = class extends Error {
+	name = "AgentIdentityError";
+	code;
+	status;
+	constructor(input) {
+		super(input.message, input.cause === void 0 ? void 0 : { cause: input.cause });
+		this.code = input.code;
+		this.status = input.status;
+	}
+};
+const PAIRING_MARGIN_MS = 6e4;
+const MAXIMUM_CACHED_ACCOUNTS = 1e3;
+const CALL_TIMEOUT_MS = 1e4;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function accountKey(account) {
+	return `${account.provider}:${account.externalId}`;
+}
+function remember(cache, key, value) {
+	cache.delete(key);
+	cache.set(key, value);
+	if (cache.size > MAXIMUM_CACHED_ACCOUNTS) {
+		const oldest = cache.keys().next();
+		if (oldest.done !== true) cache.delete(oldest.value);
+	}
+}
+function pairedMember(value) {
+	const user = isRecord(value) ? value.user : void 0;
+	const roles = isRecord(value) ? value.roles : void 0;
+	if (!isRecord(user) || typeof user.id !== "string" || user.name !== void 0 && user.name !== null && typeof user.name !== "string" || !Array.isArray(roles) || !roles.every((role) => typeof role === "string")) throw new AgentIdentityError({
+		code: "invalid_response",
+		message: "The ontology service answered the identity lookup with an invalid body."
+	});
+	return {
+		id: user.id,
+		name: typeof user.name === "string" ? user.name : null,
+		roles
+	};
+}
+function pairing(value) {
+	if (!isRecord(value) || typeof value.code !== "string" || typeof value.expires_at !== "string") throw new AgentIdentityError({
+		code: "invalid_response",
+		message: "The ontology service answered the pairing request with an invalid body."
+	});
+	return {
+		code: value.code,
+		expiresAt: value.expires_at
+	};
+}
+async function refusal(response, call) {
+	const status = response.status;
+	let value;
+	try {
+		value = await response.json();
+	} catch (error) {
+		return new AgentIdentityError({
+			code: `http_${status}`,
+			status,
+			message: `The ontology service refused the ${call} with HTTP ${status} and a body that is not JSON.`,
+			cause: error
+		});
+	}
+	const body = isRecord(value) ? value : {};
+	const code = typeof body.error === "string" ? body.error : `http_${status}`;
+	return new AgentIdentityError({
+		code,
+		status,
+		message: `The ontology service refused the ${call} with HTTP ${status}, ${code}${typeof body.detail === "string" ? `: ${body.detail}` : ""}${typeof body.request_id === "string" ? ` (request ${body.request_id})` : ""}.`
+	});
+}
+function agentIdentities(input) {
+	const fetchImpl = input.fetch ?? fetch;
+	const now = input.now ?? Date.now;
+	const pending = new Map();
+	async function call(path, request) {
+		const token = await input.token();
+		try {
+			return await fetchImpl(`${input.origin}/api/ontology/agent${path}`, {
+				method: request.body === void 0 ? "GET" : "POST",
+				headers: {
+					authorization: `Bearer ${token}`,
+					accept: "application/json",
+					...request.body === void 0 ? {} : { "content-type": "application/json" }
+				},
+				...request.body === void 0 ? {} : { body: JSON.stringify(request.body) },
+				redirect: "error",
+				signal: AbortSignal.timeout(CALL_TIMEOUT_MS)
+			});
+		} catch (error) {
+			throw new AgentIdentityError({
+				code: "unavailable",
+				message: "The ontology service could not be reached.",
+				cause: error
+			});
+		}
+	}
+	return {
+		async lookup(account) {
+			const response = await call(`/identities/${encodeURIComponent(account.provider)}/${encodeURIComponent(account.externalId)}`, {});
+			if (response.status === 404) return { status: "unknown" };
+			if (response.status === 403) return { status: "refused" };
+			if (!response.ok) throw await refusal(response, "identity lookup");
+			const member = pairedMember(await response.json());
+			pending.delete(accountKey(account));
+			return {
+				status: "paired",
+				member
+			};
+		},
+		async createPairing(account) {
+			const key = accountKey(account);
+			const existing = pending.get(key);
+			if (existing !== void 0 && Date.parse(existing.expiresAt) - PAIRING_MARGIN_MS > now()) return existing;
+			const response = await call("/pairings", { body: {
+				provider: account.provider,
+				external_id: account.externalId,
+				...account.display === void 0 ? {} : { display: account.display }
+			} });
+			if (!response.ok) throw await refusal(response, "pairing request");
+			const created = pairing(await response.json());
+			remember(pending, key, created);
+			return created;
+		}
+	};
+}
+export { AgentIdentityError, agentIdentities };

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

@@ -0,0 +1,36 @@
+import type { SessionAuthContext } from "eve/context";
+import { type McpClientConnectionDefinition } from "eve/connections";
+import { type Environment } from "./environment.js";
+import { type RuntimeToken } from "./runtime-token.js";
+/**
+ * The ontology as tools: an MCP connection to the workspace app's `/mcp`
+ * (`ontology-mcp-design.md`). The agent authenticates as the deployment with its Vercel OIDC token
+ * and names the member it acts for in `X-SegmentStream-Act-As`; the ontology service checks that
+ * the member is active and has a live pairing, lists only the tools the member may run, and
+ * records the member in history.
+ */
+/** The header that names the member a runtime caller acts for. */
+export declare const ACT_AS_HEADER = "X-SegmentStream-Act-As";
+/** The session has no member to act for, so the ontology must not be reached. */
+export declare class MemberRequiredError extends Error {
+    readonly name = "MemberRequiredError";
+}
+/**
+ * The headers that name the member, from the session principal of the turn. The connection fails
+ * without one, and fails when the turn's member is not the one the connection instance was opened
+ * for, so a client opened for one member never serves another.
+ */
+export declare function actAsHeaders(input: {
+    readonly principal: SessionAuthContext | null;
+    readonly expectedMemberId: string;
+}): Record<string, string>;
+/**
+ * The connection for one turn, or `null` when the turn has no member principal: an unpaired
+ * caller never reaches the ontology. The instance key names the member, so eve opens a separate
+ * client per member even when members share a group chat's session.
+ */
+export declare function ontologyConnection(input: {
+    readonly principal: SessionAuthContext | null;
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+}): McpClientConnectionDefinition | null;

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

@@ -0,0 +1,48 @@
+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 { appOrigin } from "./environment.mjs";
+import { memberIdOf } from "./telegram/principal.mjs";
+import { runtimeToken, tokenExpiry } from "./runtime-token.mjs";
+import { defineMcpClientConnection } from "eve/connections";
+const ACT_AS_HEADER = "X-SegmentStream-Act-As";
+const DESCRIPTION = "The company's ontology: its records, their history, and the actions that change them, narrowed to what the member you act for may read and do. Call describe for the catalog and me for the member.";
+var MemberRequiredError = class extends Error {
+	name = "MemberRequiredError";
+};
+function actAsHeaders(input) {
+	const memberId = memberIdOf(input.principal);
+	if (memberId === void 0) throw new MemberRequiredError("The ontology is reachable only for a member paired with this agent.");
+	if (memberId !== input.expectedMemberId) throw new MemberRequiredError("The ontology connection was opened for another member.");
+	return { [ACT_AS_HEADER]: memberId };
+}
+function ontologyConnection(input) {
+	const memberId = memberIdOf(input.principal);
+	if (memberId === void 0) return null;
+	const origin = appOrigin(input.environment ?? process.env);
+	const token = input.token ?? runtimeToken;
+	return defineMcpClientConnection({
+		url: `${origin}/mcp`,
+		description: DESCRIPTION,
+		instanceKey: `${origin}/mcp#member:${memberId}`,
+		auth: {
+			credentialOwner: "app",
+			getToken: async () => {
+				const value = await token();
+				const expiresAt = tokenExpiry(value);
+				return expiresAt === void 0 ? { token: value } : {
+					token: value,
+					expiresAt
+				};
+			}
+		},
+		headers: (context) => actAsHeaders({
+			principal: context.session.auth.current,
+			expectedMemberId: memberId
+		})
+	});
+}
+export { ACT_AS_HEADER, MemberRequiredError, actAsHeaders, ontologyConnection };

package/dist/extension/lib/runtime-token.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The deployment's Vercel OIDC token. It proves the workspace's agent to the ontology service and
+ * to backend-next's connection proxy. Vercel sets it on each function request
+ * (`x-vercel-oidc-token`), and `vercel env pull` writes `VERCEL_OIDC_TOKEN` for local development;
+ * `@vercel/oidc` reads both. It is used only in runtime code and never reaches the model.
+ */
+export type RuntimeToken = () => Promise<string>;
+/** The deployment has no OIDC token: it does not run on Vercel, or OIDC is off for the project. */
+export declare class RuntimeTokenError extends Error {
+    readonly name = "RuntimeTokenError";
+}
+export declare const runtimeToken: RuntimeToken;
+/**
+ * When the token expires, in milliseconds since the epoch, read from its `exp` claim without
+ * verifying it: the token is our own, and the value only schedules a refresh.
+ */
+export declare function tokenExpiry(token: string): number | undefined;

package/dist/extension/lib/runtime-token.mjs

@@ -0,0 +1,31 @@
+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 { getVercelOidcToken } from "@vercel/oidc";
+var RuntimeTokenError = class extends Error {
+	name = "RuntimeTokenError";
+};
+const runtimeToken = async () => {
+	let token;
+	try {
+		token = await getVercelOidcToken();
+	} catch (error) {
+		throw new RuntimeTokenError("The deployment has no Vercel OIDC token. The agent reaches SegmentStream only from a Vercel deployment.", { cause: error });
+	}
+	if (token === "") throw new RuntimeTokenError("The deployment's Vercel OIDC token is empty.");
+	return token;
+};
+function tokenExpiry(token) {
+	const payload = token.split(".")[1];
+	if (payload === void 0) return;
+	try {
+		const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		if (typeof claims === "object" && claims !== null && "exp" in claims && typeof claims.exp === "number") return claims.exp * 1e3;
+	} catch {
+		return;
+	}
+}
+export { RuntimeTokenError, runtimeToken, tokenExpiry };