@ego-z/contracts 0.15.14 → 0.15.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ego-z/contracts",
3
- "version": "0.15.14",
3
+ "version": "0.15.16",
4
4
  "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
5
5
  "types": "./src/index.d.ts",
6
6
  "exports": {
package/src/ask.d.ts CHANGED
@@ -91,18 +91,21 @@ export interface AskRequestBody {
91
91
  externalUserId?: string;
92
92
 
93
93
  /**
94
- * Run THIS turn on a specific chat model, instead of the project's
95
- * configured default.
94
+ * Run THIS turn on a specific chat model, or on Auto, instead of the
95
+ * project's default.
96
96
  *
97
97
  * Only honoured on a project whose owner has turned model switching on and
98
98
  * curated a menu (Console → LLM Settings). Read the menu from
99
- * `GET /egoz/models`, which returns every model this project offers along
100
- * with which one is the default, and echo an `id` back here verbatim.
99
+ * `GET /egoz/models`, which returns every model this project offers, what
100
+ * the default is and whether Auto is available, and echo an `id` back here
101
+ * verbatim.
101
102
  *
102
- * - omitted → the project's default model, exactly as before.
103
+ * - omitted → the project's default: a model, exactly as before,
104
+ * or Auto when the owner has made Auto the default.
103
105
  * - `"openai:gpt-4o-mini"` → the canonical, always-unambiguous form.
104
106
  * - `"gpt-4o-mini"` → accepted while that id is offered by only
105
107
  * one provider on this project.
108
+ * - `"auto"` → EgoZ routes the turn; see below.
106
109
  *
107
110
  * A model this project does not offer — and ANY value at all on a project
108
111
  * where switching is off — is rejected with `ModelNotAllowed` (400). It is
@@ -110,13 +113,48 @@ export interface AskRequestBody {
110
113
  * believes it took effect, and the only trace of the truth is a model
111
114
  * field on a usage row nobody reads until the invoice arrives.
112
115
  *
113
- * Scope, and what it does NOT change:
116
+ * ── `"auto"`: let EgoZ choose ────────────────────────────────────────
117
+ *
118
+ * EgoZ decides how much reasoning the turn gets. Today the turn runs on the
119
+ * project's configured model; choosing among other models the owner has
120
+ * approved (always on the owner's keys) is planned, not yet live.
121
+ * The choice belongs to the conversation, not to each message on its own:
122
+ * switching models mid-conversation changes the agent's tone and defeats
123
+ * prompt caching. A `completion` has no conversation to belong to, so each
124
+ * one is routed by itself.
125
+ *
126
+ * Accepted only when the owner offers Auto AND model switching is on —
127
+ * exactly when `GET /egoz/models` reports `auto.available: true`.
128
+ * Otherwise it is `ModelNotAllowed` (400), by the rule above: with Auto
129
+ * off, a caller who asked for it and silently got the default model would
130
+ * believe a router had picked it; with switching off, `model` takes no
131
+ * value at all — `"auto"` included, even where Auto is the default.
132
+ *
133
+ * `"auto"` always means Auto, never a model of that name: a model or
134
+ * deployment really named `auto` is reached by its canonical id (e.g.
135
+ * `"azure:auto"`).
136
+ *
137
+ * `AskResponseData.model` names the model that actually answered, as on
138
+ * any other turn.
139
+ *
140
+ * ── An explicit pick beats an Auto default ───────────────────────────
141
+ *
142
+ * With Auto as the project default, an omitted `model` runs Auto, but a
143
+ * model id still runs exactly that model — the project's configured model
144
+ * included, which stays on the menu. Auto is the owner's answer for a
145
+ * caller with no preference; a caller who names a model has one, and
146
+ * re-routing it would be the silent override this field refuses to make.
147
+ *
148
+ * ── Scope, and what it does NOT change ───────────────────────────────
149
+ *
114
150
  * - Embeddings are pinned to the project. The knowledge base's vectors
115
151
  * were written in one embedding space, and retrieving against another
116
152
  * returns confident nonsense — so RAG is unaffected by this field.
117
- * - A voice call ignores it. A call is a latency budget; the tenant's
118
- * `voiceModel` still wins there. The value is still validated, so a
119
- * bad one is a 400 rather than a surprise.
153
+ * - A voice call ignores it, and ignores Auto the same way, whether
154
+ * `"auto"` was sent or Auto is the project default. A call is a
155
+ * latency budget; the tenant's `voiceModel` still wins there. The
156
+ * value is still validated, so a bad one is a 400 rather than a
157
+ * surprise.
120
158
  */
121
159
  model?: string;
122
160
 
@@ -301,6 +339,49 @@ export interface AskRequestBody {
301
339
  * Optional and additive: omit it and nothing changes.
302
340
  */
303
341
  machineOutput?: AskMachineOutput[];
342
+
343
+ /**
344
+ * A one-shot COMPLETION: `message` is the whole instruction, and EgoZ adds
345
+ * nothing from the project around it.
346
+ *
347
+ * ── What it switches off ─────────────────────────────────────────────
348
+ *
349
+ * The project's prompt, personality, session context, greeting, knowledge
350
+ * base, tools, memory and conversation title. Nothing is stored either:
351
+ * `true` implies `noStore`. The project still supplies the provider key,
352
+ * the quota and the model menu, so `model` works as usual.
353
+ *
354
+ * What remains is what you put on this request for a program to read:
355
+ * with `responseFormat: 'json_object'`, the `jsonSchema` instructions; and
356
+ * any `machineOutput`.
357
+ *
358
+ * ── Why it exists ────────────────────────────────────────────────────
359
+ *
360
+ * A project that serves a chat agent also answers one-off program calls
361
+ * (a classifier, a planner). Without this, such a call runs AS the agent —
362
+ * its persona, every enabled tool, a knowledge-base lookup and the
363
+ * project's conversation temperature — which is slower, costlier and less
364
+ * predictable than the call needs.
365
+ *
366
+ * ── Why it is explicit ───────────────────────────────────────────────
367
+ *
368
+ * A JSON turn is not implicitly a completion, stored or not: testing the
369
+ * agent itself answering in JSON is a real use. Only `true` changes
370
+ * anything.
371
+ *
372
+ * Optional and additive: omit it and nothing changes.
373
+ */
374
+ completion?: boolean;
375
+
376
+ /**
377
+ * The sampling temperature for a `completion`, from 0 to 2. Omit it to use
378
+ * the project's own.
379
+ *
380
+ * Accepted ONLY together with `completion: true`; on any other turn it is a
381
+ * 400. It is not a general per-call override: a conversation's temperature
382
+ * belongs to the project.
383
+ */
384
+ temperature?: number;
304
385
  }
305
386
 
306
387
  /**
package/src/model.d.ts CHANGED
@@ -43,7 +43,12 @@ export interface SwitchableModelWire {
43
43
  * private to the tenant — do not assume it matches a public model name.
44
44
  */
45
45
  model: string;
46
- /** True for the model used when `AskRequestBody.model` is omitted. Exactly one entry has it. */
46
+ /**
47
+ * True for the model used when `AskRequestBody.model` is omitted. At most
48
+ * one entry has it, and none when Auto is the project default
49
+ * (`defaultId: "auto"`): an omitted `model` then runs Auto, not any one
50
+ * entry.
51
+ */
47
52
  isDefault: boolean;
48
53
  }
49
54
 
@@ -51,14 +56,54 @@ export interface SwitchableModelWire {
51
56
  export interface SwitchableModelsResponseData {
52
57
  /**
53
58
  * Whether `AskRequestBody.model` will be honoured. When `false`, `models`
54
- * still holds exactly one entry — the project default — so a picker can
55
- * render the same way either way and simply has nothing to switch to.
59
+ * still holds exactly one entry — the project's configured model — so a
60
+ * picker can render the same way either way and simply has nothing to
61
+ * switch to.
56
62
  *
57
63
  * Sending `model` while this is `false` is an error, not a no-op.
58
64
  */
59
65
  switchable: boolean;
60
- /** `id` of the default entry. Convenience — it is also the entry with `isDefault: true`. */
66
+ /**
67
+ * `id` of the default entry — or `"auto"` when the owner has made Auto the
68
+ * project default, and then no entry in `models` has `isDefault: true`.
69
+ * Otherwise a convenience: it is also the entry with `isDefault: true`.
70
+ *
71
+ * `"auto"` rather than the configured model's id, because with Auto as the
72
+ * default an omitted `model` runs Auto, not that model; naming the model
73
+ * here would tell a picker's "Default" option something untrue. It is also
74
+ * the value `AskRequestBody.model` takes for Auto.
75
+ *
76
+ * ⚠️ `"auto"` is never an entry in `models`. Code that looks `defaultId` up
77
+ * there must handle finding nothing.
78
+ */
61
79
  defaultId: string;
62
- /** The default first, then the owner's curated alternatives. Never empty. */
80
+ /**
81
+ * The project's configured model first (the default, unless Auto is), then
82
+ * the owner's curated alternatives. Never empty.
83
+ */
63
84
  models: SwitchableModelWire[];
85
+ /**
86
+ * Whether this project lets callers pick Auto, where EgoZ decides, per
87
+ * conversation, how much reasoning a turn gets (on the project's
88
+ * configured model today; choosing among the owner's approved models is
89
+ * planned).
90
+ *
91
+ * `available` is true when a caller may send `model: "auto"` — the owner
92
+ * offers Auto AND `switchable` is true. List Auto in a picker only then.
93
+ * It can be `false` while `defaultId` is `"auto"`: with switching off,
94
+ * every turn runs Auto and there is nothing for a caller to pick.
95
+ *
96
+ * ── A field of its own, not a menu entry ─────────────────────────────
97
+ *
98
+ * Every entry in `models` names the provider and the model that serve a
99
+ * turn when it is picked. Auto is neither — it chooses among the owner's
100
+ * models — so a row for it would have to make up both.
101
+ *
102
+ * ── Absent means unavailable ─────────────────────────────────────────
103
+ *
104
+ * Optional only because a backend that predates Auto does not send it.
105
+ * Treat a missing `auto` exactly like `available: false`, and never infer
106
+ * availability from `defaultId`.
107
+ */
108
+ auto?: { available: boolean };
64
109
  }
package/src/stream.d.ts CHANGED
@@ -209,6 +209,14 @@ export interface AskStreamToolResultEvent {
209
209
  name: string;
210
210
  success: boolean;
211
211
  durationMs: number;
212
+ /**
213
+ * The value a client renders beside the answer — e.g. product cards — lifted out of the
214
+ * tool's response by the tool's `displayPath`. Present only on a successful call to a tool
215
+ * that declares one and whose value resolved; read from the redacted result and dropped
216
+ * whole above a size cap. Its shape is the tool's own: a consumer that renders it knows
217
+ * which tool it asked for. The model's answer never depends on it.
218
+ */
219
+ display?: unknown;
212
220
  }
213
221
 
214
222
  /**