@segmentstream/agent 0.1.1 → 0.1.3

package/README.md

@@ -18,31 +18,32 @@ npm install @segmentstream/agent eve@0.76.3
 
 ## Set up
 
-The workspace's `agent/` directory is an eve app in eve's flat layout, a package of its own like
-`ontology/`:
+The workspace's `agent/` directory is an eve app in eve's documented layout, a package of its own
+like `ontology/`: the package files at the root, the authored files under `agent/agent/`:
 
 ```text
 agent/
 ├── package.json            # eve and @segmentstream/agent, both pinned; "build": "eve build"
 ├── segmentstream.json      # what the extension mounts, and what the platform reads at deploy
-├── agent.ts                # model, reasoning, limits
-├── instructions.md         # who the company is, how the agent behaves
-└── extensions/
-    └── segmentstream.ts    # mounts this package with segmentstream.json
+└── agent/                  # eve's agent directory
+    ├── agent.ts            # model, reasoning, limits
+    ├── instructions.md     # who the company is, how the agent behaves
+    └── extensions/
+        └── segmentstream.ts  # mounts this package with segmentstream.json
 ```
 
-**`extensions/segmentstream.ts`** mounts the extension. The file name is the mount's namespace, so
+**`agent/agent/extensions/segmentstream.ts`** mounts the extension. The file name is the mount's namespace, so
 every contribution is named `segmentstream__…`:
 
 ```ts
 import { segmentstream } from "@segmentstream/agent/extension";
 
-import config from "../segmentstream.json";
+import config from "../../segmentstream.json";
 
 export default segmentstream(config);
 ```
 
-**`agent.ts`** chooses the model once per session:
+**`agent/agent/agent.ts`** chooses the model once per session:
 
 ```ts
 import { defineAgent } from "eve";
@@ -50,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.
@@ -117,14 +116,16 @@ 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
   looked up with the ontology service on every message, so a revocation stops at once. An unknown
-  sender who writes privately gets a link to `/agent/connect?code=…`, valid for ten minutes. In a
-  group, the agent only asks an unknown sender to message it privately, because anyone in the group
-  could open a link posted there. A revoked pairing or an inactive member gets a short refusal.
+  sender who writes privately gets a message with a **Connect account** button that opens
+  `/agent/connect?code=…`, valid for ten minutes. In a group, the agent only asks an unknown sender to
+  message it privately, with a button to the bot's chat, because anyone in the group could open a
+  pairing link posted there. A revoked pairing or an inactive member gets a short refusal.
 - **Who the agent is.** A paired sender's turn runs with the principal id `telegram:<user>`
   (`telegram:<chat>:<user>` in groups) and the attributes `memberId`, `memberName`, `roles`,
   `chatId`, `chatType` and `username`.

package/dist/extension/config.d.ts

@@ -1,6 +1,6 @@
 /**
  * The extension's configuration: `agent/segmentstream.json`, mounted by
- * `agent/extensions/segmentstream.ts` and read by the platform at deploy.
+ * `agent/agent/extensions/segmentstream.ts` and read by the platform at deploy.
  *
  * eve validates a mount's configuration with a Standard Schema. The schema below is written by
  * hand, so the package adds no second schema library next to the Effect Schema the rest of the
@@ -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/lib/telegram/inbound.d.ts

@@ -10,7 +10,7 @@ import { type Transcriber } from "./voice.js";
  * eve's Telegram `onMessage` hook, in the order `agent-design.md` gives:
  *
  * 1. The hard gate, with no model: bots, channel posts and senders without a live pairing never
- *    start a turn. An unknown sender who writes to the bot privately gets a pairing link.
+ *    start a turn. An unknown sender who writes to the bot privately gets a pairing button.
  * 2. Voice becomes text, so the router and the agent read what was said.
  * 3. The router answers or observes. An observed message goes to the chat's ring and stops here.
  * 4. An answered message dispatches as the paired member, with the ring ahead of it as context.

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

@@ -8,8 +8,15 @@ import { telegramPrincipal } from "./principal.mjs";
 import { observedChatKey, observedContext } from "./observed.mjs";
 import { isAddressed, routeMessage } from "./router.mjs";
 import { voiceNote, voiceOf, voiceText } from "./voice.mjs";
-const UNKNOWN_PRIVATE = "I don't know who you are yet. Open this link and sign in to connect your Telegram account; it works for ten minutes:";
+const UNKNOWN_PRIVATE = "Hi, I don't know you yet. Connect your Telegram account to the workspace and I'll act as you. The button works for ten minutes.";
+const UNKNOWN_IN_GROUP = "I don't know you yet. Message me privately to connect your account.";
 const REFUSED = "Your access to this agent was revoked, or your membership is inactive. Ask a workspace administrator.";
+function buttonTo(text, url) {
+	return { inline_keyboard: [[{
+		text,
+		url
+	}]] };
+}
 function display(user) {
 	if (user.username !== void 0) return `@${user.username}`;
 	const name = [user.firstName, user.lastName].filter((part) => part !== void 0 && part !== "").join(" ");
@@ -27,7 +34,10 @@ function observedMessage(message, text) {
 	};
 }
 function unknownInGroup(bot) {
-	return `I don't know who you are yet. Message me privately to connect your account.${bot?.username === void 0 ? "" : ` https://t.me/${bot.username}`}`;
+	return bot?.username === void 0 ? { text: UNKNOWN_IN_GROUP } : {
+		text: UNKNOWN_IN_GROUP,
+		reply_markup: buttonTo("Message me", `https://t.me/${bot.username}`)
+	};
 }
 async function answerUnpaired(input) {
 	const { context, message, lookup, dependencies } = input;
@@ -45,7 +55,10 @@ async function answerUnpaired(input) {
 		externalId: message.from.id,
 		...sender === void 0 ? {} : { display: sender }
 	});
-	await context.telegram.post(`${UNKNOWN_PRIVATE}\n${dependencies.connectUrl(pairing.code)}`);
+	await context.telegram.post({
+		text: UNKNOWN_PRIVATE,
+		reply_markup: buttonTo("Connect account", dependencies.connectUrl(pairing.code))
+	});
 }
 async function handleInboundMessage(input) {
 	const { context, dependencies } = input;

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.1",
+  "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",