@ego-z/contracts 0.15.11 → 0.15.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.11",
+  "version": "0.15.13",
   "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

@@ -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;
 
@@ -211,6 +241,102 @@ export interface AskRequestBody {
      * Optional and additive: omit it and nothing changes.
      */
     contextItems?: InitContextItem[];
+
+    /**
+     * Output a MACHINE produced for this turn — the result of something the
+     * user asked to have run, not anything the user said.
+     *
+     * ── Why this needs a channel of its own ──────────────────────────────
+     *
+     * Before this field there were exactly two ways in, and both are wrong
+     * for a machine:
+     *
+     * - `message` persists as `role: 'user'`. A script that prints a
+     *   customer's CSV row arrives labelled as the account owner speaking,
+     *   and **every protection that keys off who is speaking is bypassed by
+     *   a program printing a sentence.**
+     * - `contextItems` is worse, because it does not merely keep the user's
+     *   voice — it upgrades it. Those items are rendered as things the user
+     *   *chose deliberately* and *likely referents for anything they mention*,
+     *   so routing `stderr` there promotes program output to something
+     *   adjacent to instruction.
+     *
+     * `role: 'tool'` exists internally, but only EgoZ mints those and only
+     * from its own executions; nothing on the wire can produce one. So this
+     * is the channel: it is rendered to the agent as **quoted data with an
+     * explicit statement that a machine produced it**, never as speech and
+     * never as instruction.
+     *
+     * ⚠️ **You are asserting provenance when you send this.** Put here only
+     * what your own system produced. Anything a person typed belongs in
+     * `message`, whatever it is about — mislabelling user text as machine
+     * output is the same failure as the reverse, pointed the other way.
+     *
+     * Optional and additive: omit it and nothing changes.
+     */
+    machineOutput?: AskMachineOutput[];
+}
+
+/**
+ * One piece of output a machine produced for this turn.
+ *
+ * ── Truncated, never dropped — the opposite of `InitContextItem` ─────────
+ *
+ * An over-long `excerpt` on a context item is DROPPED, because a shortened
+ * address is a different valid address and acting on it is worse than not
+ * having it. Output is the other case entirely: **a clipped `stderr` is
+ * still evidence, and a missing one is a lie.** So this is capped by
+ * truncation and the truncation is declared — the agent is told the text was
+ * cut rather than left to conclude a command printed nothing.
+ *
+ * That asymmetry is deliberate and it is the reason these are two shapes
+ * rather than one generous one.
+ *
+ * ── No acceptance receipt, unlike `contextItems` ─────────────────────────
+ *
+ * `contextItemsAccepted` exists because acceptance there is lossy in ways
+ * the caller cannot observe — items vanish, excerpts disappear — so a
+ * "shared with the agent" display would otherwise be confidently wrong.
+ * Nothing here vanishes: an entry is either rendered or the request is
+ * rejected, and the one lossy case declares itself **to the reader who
+ * matters**, in-band, where the agent is told the text was cut. Adding a
+ * receipt would be a second copy of that fact, for a caller that already
+ * holds the full output it just sent.
+ */
+export interface AskMachineOutput {
+    /**
+     * Your own name for whatever produced this — `"terminal"`, `"build"`.
+     *
+     * ⚠️ Free-form, and **never rendered into the prompt**, exactly like
+     * `InitContextItem.kind` and for the same reason: free-form caller text
+     * in the instruction block is an injection surface. Used for grouping
+     * and for your own logs.
+     */
+    source?: string;
+
+    /**
+     * What was run, in the user's terms — a command line, a job name.
+     * Rendered, because output with no statement of what produced it invites
+     * the agent to guess which of its own suggestions ran.
+     */
+    invocation?: string;
+
+    /**
+     * The text the machine produced. Required — an entry with nothing in it
+     * says a program ran and reported nothing, which is a claim, not an
+     * omission. Truncated to a server cap if long; see the header.
+     */
+    output: string;
+
+    /**
+     * The producer's own result status, when it has one — a process exit
+     * code, conventionally 0 for success.
+     *
+     * Worth sending even when `output` is empty, and especially then: it is
+     * the difference between *"it worked and printed nothing"* and *"it
+     * failed silently"*, which no amount of text can express.
+     */
+    exitCode?: number;
 }
 
 /**

package/src/draft-conv.d.ts

@@ -113,6 +113,46 @@ export interface InitContextItem {
      * `contextItemsAccepted` on the response tells you when it happened.
      */
     excerpt?: string;
+
+    /**
+     * The exact string a tool needs to act on this item — a file path, a
+     * record id, whatever your tools take. Optional.
+     *
+     * ── Why this is not just an `excerpt` ────────────────────────────────
+     *
+     * Because the two are read differently and fail differently, and until
+     * this field existed they shared one. An excerpt is prose ABOUT the
+     * thing; an address is a HANDLE TO it, and the agent is expected to
+     * carry it verbatim into a tool call. Shortening prose loses a few
+     * words. Shortening an address produces a **different valid address** —
+     * so the caps differ, and so does what a consumer may do with the value.
+     *
+     * ⚠️ AN OVER-LONG ADDRESS IS DROPPED, NOT TRUNCATED, and the item still
+     * rides without it, exactly like `excerpt`. `addressOmitted` on the
+     * receipt tells you it happened — worth reading, because the agent then
+     * has the item's NAME and no way to act on it, which usually reads to a
+     * user as the agent being unable rather than under-informed.
+     *
+     * ── Send the address, or the agent will construct one ────────────────
+     *
+     * Measured, twice, on live traffic: given an item it can name but not
+     * address, an agent does not stop — it produces a plausible-looking
+     * identifier from the meaning it has. A product slug built from the
+     * product's name, a window key passed where a record id was wanted.
+     * Both fail at the tool, and the failure reads as a broken feature.
+     *
+     * So an absent address is not neutral. It is the condition under which
+     * an agent invents one.
+     *
+     * ── It is rendered, and that is a deliberate exception ───────────────
+     *
+     * `kind` and `id` never reach the prompt: free-form caller text in the
+     * instruction block is an injection surface. `address` does reach it,
+     * for the same reason `label` does — a handle nobody can read is not a
+     * handle. Send an identifier or a path, never a sentence, and never
+     * anything a user typed and you did not resolve.
+     */
+    address?: string;
 }
 
 /**
@@ -159,6 +199,19 @@ export interface InitContextItemAccepted {
      * detail, instead of implying it got both.
      */
     excerptOmitted?: boolean;
+
+    /**
+     * The item was accepted but its `address` was not — it exceeded the cap
+     * and was dropped rather than truncated (see `InitContextItem.address`).
+     *
+     * ⚠️ Worth surfacing more loudly than `excerptOmitted`. A lost excerpt
+     * costs detail; a lost address costs the agent the only way to ACT on
+     * the item, and what a user sees is not "it knew less about this" but
+     * "it couldn't do it" — or, worse, an invented identifier that fails at
+     * the tool. If you show a "shared with the agent" display at all, this
+     * is the flag that changes what the user should expect.
+     */
+    addressOmitted?: boolean;
 }
 
 /** One open window in the caller's UI. */

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[];
+}