@segmentstream/agent 0.1.2 → 0.1.3

package/README.md

@@ -51,17 +51,15 @@ import { segmentstream } from "@segmentstream/agent";
 
 export default defineAgent({
   defaultTools: false,
-  model: segmentstream.model({
-    default: "spacexai/grok-4.7",
-    byRole: { finance: "anthropic/claude-opus-5.5" },
-    preview: "google/gemini-flash",
-  }),
+  model: segmentstream.model(),
   reasoning: "medium",
   limits: { maxTokenCostUsdPerSession: 2 },
 });
 ```
 
-`segmentstream.model()` resolves on `session.started`. On a preview deployment it returns `preview`
+`segmentstream.model()` resolves on `session.started` from `models.chat` in `agent/segmentstream.json`
+(`{ "default", "byRole", "preview" }`), where the platform reads it too; an inline
+`segmentstream.model({ default, byRole, preview })` works the same. On a preview deployment it returns `preview`
 when set. Otherwise it returns the model of the first `byRole` entry whose role the member holds, in
 the order written, and `default` when none matches. The roles come from the member's pairing, not
 from the message. The model is never switched mid-session, which keeps the provider's prompt cache.
@@ -118,7 +116,8 @@ share a group chat's session never share a client.
   proxy. The token stays in SegmentStream.
 - **Webhook.** A webhook is accepted only with `X-Telegram-Bot-Api-Secret-Token` equal to
   `SEGMENTSTREAM_AGENT_WEBHOOK_SECRET`, compared in constant time. The platform generates the
-  secret and registers the webhook after each production deployment.
+  secret and registers the webhook after each production deployment, and sets the bot's menu
+  button, shown in private chats, to open the workspace app.
 - **Production only.** Outside `VERCEL_ENV=production` the route answers 200 and does nothing, so a
   preview never answers a real chat. Without `channels.telegram` it answers 404.
 - **Pairing.** Messages from bots and channel posts are dropped. The sender's Telegram account is

package/dist/extension/config.d.ts

@@ -30,6 +30,16 @@ export interface SegmentStreamAgentConfigInput {
         };
     };
     readonly models?: {
+        /**
+         * The chat model `segmentstream.model()` chooses per session: `default` for everyone, one per
+         * member role in `byRole` (the first role the member holds wins, in the order written) and
+         * `preview` for preview deployments.
+         */
+        readonly chat?: {
+            readonly default: string;
+            readonly byRole?: Readonly<Record<string, string>>;
+            readonly preview?: string;
+        };
         /** A Gateway transcription model, or `false` to leave voice messages untranscribed. */
         readonly stt?: string | boolean;
         /** The Gateway decision model of the inbound router. */
@@ -44,12 +54,26 @@ export interface TelegramSettings {
     readonly connection: string;
     readonly policy: TelegramPolicy;
 }
+/** The chat models `segmentstream.model()` chooses between, as AI Gateway model ids. */
+export interface ChatModelChoice {
+    /** 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 validated configuration with defaults applied. It stays JSON-serializable. */
 export interface SegmentStreamAgentConfig {
     readonly channels: {
         readonly telegram: TelegramSettings | null;
     };
     readonly models: {
+        /** `null` when `agent.ts` passes the choice to `segmentstream.model()` itself. */
+        readonly chat: ChatModelChoice | null;
         readonly stt: string | false;
         readonly decision: string;
     };

package/dist/extension/config.mjs

@@ -72,6 +72,58 @@ function modelId(input) {
 	}
 	return input.value;
 }
+function chatModelChoice(value, issues) {
+	const path = ["models", "chat"];
+	const chat = section({
+		value,
+		path,
+		allowed: [
+			"default",
+			"byRole",
+			"preview"
+		],
+		issues
+	});
+	if (chat === void 0) return null;
+	const fallback = "";
+	if (chat.default === void 0) issues.push({
+		message: "is required",
+		path: [...path, "default"]
+	});
+	const defaultModel = modelId({
+		value: chat.default,
+		fallback,
+		path: [...path, "default"],
+		issues
+	});
+	const byRole = section({
+		value: chat.byRole,
+		path: [...path, "byRole"],
+		allowed: Object.keys(isRecord(chat.byRole) ? chat.byRole : {}),
+		issues
+	});
+	const roles = Object.fromEntries(Object.entries(byRole ?? {}).map(([role, model]) => [role, modelId({
+		value: model,
+		fallback,
+		path: [
+			...path,
+			"byRole",
+			role
+		],
+		issues
+	})]));
+	const preview = chat.preview === void 0 ? void 0 : modelId({
+		value: chat.preview,
+		fallback,
+		path: [...path, "preview"],
+		issues
+	});
+	return {
+		default: defaultModel,
+		...byRole === void 0 ? {} : { byRole: roles },
+		...preview === void 0 ? {} : { preview }
+	};
+}
 function validateConfig(input) {
 	const issues = [];
 	const root = section({
@@ -93,7 +145,11 @@ function validateConfig(input) {
 	const models = section({
 		value: root?.models,
 		path: ["models"],
-		allowed: ["stt", "decision"],
+		allowed: [
+			"chat",
+			"stt",
+			"decision"
+		],
 		issues
 	});
 	const ontology = section({
@@ -103,6 +159,7 @@ function validateConfig(input) {
 		issues
 	});
 	const telegram = telegramSettings(channels?.telegram, issues);
+	const chat = chatModelChoice(models?.chat, issues);
 	const stt = models?.stt === false ? false : modelId({
 		value: models?.stt,
 		fallback: DEFAULT_STT_MODEL,
@@ -124,6 +181,7 @@ function validateConfig(input) {
 	return { value: {
 		channels: { telegram },
 		models: {
+			chat,
 			stt,
 			decision
 		},

package/dist/extension/extension.d.ts

@@ -1,5 +1,5 @@
 import { manifestOf } from "./config.js";
-import { model } from "./model.js";
+import { type DynamicModel, type ModelChoice } from "./model.js";
 export declare const segmentstream: import("eve/extension").ExtensionHandle<{
     readonly "~standard": {
         readonly version: 1;
@@ -11,9 +11,9 @@ export declare const segmentstream: import("eve/extension").ExtensionHandle<{
         };
     };
 }> & {
-    model: typeof model;
+    model: (choice?: ModelChoice) => DynamicModel;
     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 { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, manifestOf, type ChatModelChoice, 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

@@ -9,7 +9,7 @@ import { chooseModel, model } from "./model.mjs";
 import { defineExtension } from "eve/extension";
 const extension = defineExtension({ config: configSchema });
 const segmentstream = Object.assign(extension, {
-	model,
+	model: (choice) => model(choice ?? (() => extension.config.models.chat)),
 	manifestOf
 });
 export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, chooseModel, segmentstream as default, segmentstream, manifestOf, model };

package/dist/extension/model.d.ts

@@ -1,18 +1,9 @@
 import { type AgentModelDefinition, type AgentStaticModelDefinition } from "eve";
 import type { SessionAuthContext } from "eve/context";
+import type { ChatModelChoice } from "./config.js";
 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;
-}
+export type ModelChoice = ChatModelChoice;
 /** 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`. */
@@ -24,6 +15,8 @@ export declare function chooseModel(input: {
 /**
  * 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.
+ * full price. The choice is given here, or read when the session starts, from `models.chat` of
+ * `agent/segmentstream.json` through the mounted extension; a session without either fails to
+ * start with a message naming the missing setting.
  */
-export declare function model(choice: ModelChoice): DynamicModel;
+export declare function model(choice: ModelChoice | (() => ModelChoice | null)): DynamicModel;

package/dist/extension/model.mjs

@@ -15,9 +15,13 @@ function chooseModel(input) {
 	return choice.default;
 }
 function model(choice) {
-	return defineDynamic({ events: { "session.started": (_event, context) => chooseModel({
-		choice,
-		principal: context.session.auth.current ?? context.session.auth.initiator
-	}) } });
+	return defineDynamic({ events: { "session.started": (_event, context) => {
+		const chosen = typeof choice === "function" ? choice() : choice;
+		if (chosen === null) throw new Error("segmentstream.model() has no model to choose from: set models.chat in agent/segmentstream.json or pass the choice to segmentstream.model().");
+		return chooseModel({
+			choice: chosen,
+			principal: context.session.auth.current ?? context.session.auth.initiator
+		});
+	} } });
 }
 export { chooseModel, model };

package/package.json

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