@ego-z/contracts 0.15.12 → 0.15.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.12",
+  "version": "0.15.14",
   "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
   "types": "./src/index.d.ts",
   "exports": {

package/src/ask.d.ts

@@ -6,7 +6,7 @@
  */
 
 import type { Intent, JsonSchemaDefinition, ResponseFormat, TokenUsage } from './envelope';
-import type { InitContextItem, InitContextItemAccepted, InitContextUi } from './draft-conv';
+import type { InitContextItem, InitContextItemAccepted, InitContextTenant, InitContextUi } from './draft-conv';
 import type { AskQuestionSet } from './questions';
 
 // ============================================================================
@@ -90,6 +90,36 @@ export interface AskRequestBody {
      */
     externalUserId?: string;
 
+    /**
+     * Run THIS turn on a specific chat model, instead of the project's
+     * configured default.
+     *
+     * Only honoured on a project whose owner has turned model switching on and
+     * curated a menu (Console → LLM Settings). Read the menu from
+     * `GET /egoz/models`, which returns every model this project offers along
+     * with which one is the default, and echo an `id` back here verbatim.
+     *
+     *   - omitted        → the project's default model, exactly as before.
+     *   - `"openai:gpt-4o-mini"` → the canonical, always-unambiguous form.
+     *   - `"gpt-4o-mini"`        → accepted while that id is offered by only
+     *                             one provider on this project.
+     *
+     * A model this project does not offer — and ANY value at all on a project
+     * where switching is off — is rejected with `ModelNotAllowed` (400). It is
+     * deliberately not ignored: a caller whose override is silently dropped
+     * believes it took effect, and the only trace of the truth is a model
+     * field on a usage row nobody reads until the invoice arrives.
+     *
+     * Scope, and what it does NOT change:
+     *   - Embeddings are pinned to the project. The knowledge base's vectors
+     *     were written in one embedding space, and retrieving against another
+     *     returns confident nonsense — so RAG is unaffected by this field.
+     *   - A voice call ignores it. A call is a latency budget; the tenant's
+     *     `voiceModel` still wins there. The value is still validated, so a
+     *     bad one is a 400 rather than a surprise.
+     */
+    model?: string;
+
     /** Override the tenant's default response format for this single call. */
     responseFormat?: ResponseFormat;
 
@@ -212,6 +242,32 @@ export interface AskRequestBody {
      */
     contextItems?: InitContextItem[];
 
+    /**
+     * The tenant AS IT IS NOW — sent when it may have changed since the
+     * conversation began.
+     *
+     * ── Why per-turn ─────────────────────────────────────────────────────
+     *
+     * The draft's `initContext.tenant` is captured once, and its `features`
+     * are rendered to the agent as a hard rule on every turn: disabled means
+     * "never offer". A tenant whose features change mid-conversation — a setup
+     * flow switching bookings on — would otherwise be told, turn after turn,
+     * that the thing it just enabled is off.
+     *
+     * ── Merged, and kept ─────────────────────────────────────────────────
+     *
+     * The keys you SEND replace the stored ones; keys you omit keep their
+     * stored value, and `null` clears one. `features` is replaced as a whole
+     * map — send the complete current set, not a delta. The merged block is
+     * kept on the conversation (except for a no-store tenant), so a later
+     * turn that omits this field still sees it.
+     *
+     * Validated exactly like `initContext.tenant`: an invalid block is a 400.
+     *
+     * Optional and additive: omit it and nothing changes.
+     */
+    tenant?: InitContextTenant;
+
     /**
      * Output a MACHINE produced for this turn — the result of something the
      * user asked to have run, not anything the user said.

package/src/draft-conv.d.ts

@@ -456,6 +456,8 @@ export interface InitContextTenant {
     name?: string | null;
     description?: string | null;
     category?: string | null;
+    /** What the business is, in the caller's words — finer than `category` ("barbershop"). */
+    niche?: string | null;
     /** Enabled-feature flags, e.g. `{ products: true, booking: false }`. */
     features?: Record<string, boolean>;
 }

package/src/index.d.ts

@@ -74,6 +74,10 @@
  *                        create / update / clone bodies,
  *                        `ActiveTenantPersonalityWire`. Shared:
  *                        `PersonalityTraitsWire`, `PresetType`.
+ *   - `model.d.ts`    — `GET /egoz/models`: the menu of chat models a
+ *                        project offers for `AskRequestBody.model`.
+ *                        `SwitchableModelWire`,
+ *                        `SwitchableModelsResponseData`.
  *   - `user-memory.d.ts` — Per-end-user learning (Phase 15 / exURM).
  *                        `UserMemoryWire`, `UserMemoryUserSummaryWire`,
  *                        `UpdateUserMemoryFactBody`, list / detail / fact /
@@ -93,6 +97,7 @@
 
 export * from './envelope';
 export * from './ask';
+export * from './model';
 export * from './stream';
 export * from './questions';
 export * from './tool';

package/src/model.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @ego-z/contracts — `GET /egoz/models` wire types.
+ *
+ * The menu of chat models a project offers for `AskRequestBody.model`. Read
+ * this to build a model picker; echo an entry's `id` back verbatim.
+ *
+ * ── Why this endpoint exists at all ──────────────────────────────────────
+ *
+ * The alternative was for integrators to hardcode the model ids their picker
+ * offers. That list is a copy of one a project owner edits in the Console,
+ * with nothing connecting the two: the day the owner drops a model, every
+ * caller's picker keeps offering it and every pick 400s, in someone else's
+ * deployment, with no signal on the Console side that anything broke.
+ *
+ * ── Authentication ───────────────────────────────────────────────────────
+ *
+ * Same trusted-server pattern as `/ask`: the tenant API key in `X-API-Key`
+ * (plus `X-Tenant-Id`). It is deliberately NOT anonymous — the menu names a
+ * project's providers and model tiers, which is commercial detail, not public
+ * information.
+ *
+ * ── What it is not ───────────────────────────────────────────────────────
+ *
+ * Not a provider catalogue. It returns exactly what the owner curated, and
+ * makes no call to OpenAI/Anthropic/Azure to do so — a hot path on every chat
+ * panel open must not fan out to third parties. The Console's model dropdowns
+ * are the surface that browses live catalogues
+ * (`GET /egoz/tenants/:tenantId/models`); this one publishes the decision.
+ */
+
+/** One model this project will run. */
+export interface SwitchableModelWire {
+    /**
+     * Canonical handle, `"<provider>:<model>"` (e.g. `"openai:gpt-4o-mini"`).
+     * Send this back as `AskRequestBody.model`. Stable for as long as the
+     * owner keeps the entry on the menu.
+     */
+    id: string;
+    /** BYOK provider that will serve the turn — `"openai"`, `"anthropic"`, … */
+    provider: string;
+    /**
+     * Provider-side model id. On Azure this is the DEPLOYMENT name, which is
+     * private to the tenant — do not assume it matches a public model name.
+     */
+    model: string;
+    /** True for the model used when `AskRequestBody.model` is omitted. Exactly one entry has it. */
+    isDefault: boolean;
+}
+
+/** `data` payload of `GET /egoz/models`. */
+export interface SwitchableModelsResponseData {
+    /**
+     * Whether `AskRequestBody.model` will be honoured. When `false`, `models`
+     * still holds exactly one entry — the project default — so a picker can
+     * render the same way either way and simply has nothing to switch to.
+     *
+     * Sending `model` while this is `false` is an error, not a no-op.
+     */
+    switchable: boolean;
+    /** `id` of the default entry. Convenience — it is also the entry with `isDefault: true`. */
+    defaultId: string;
+    /** The default first, then the owner's curated alternatives. Never empty. */
+    models: SwitchableModelWire[];
+}