@ego-z/contracts 0.15.15 → 0.15.17

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.15",
3
+ "version": "0.15.17",
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,50 @@ 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 judges how demanding the turn is and answers accordingly: with more
119
+ * or less reasoning and, when the owner has picked them, on a lighter or a
120
+ * stronger model from this project's menu — always one the owner approved,
121
+ * on the owner's keys.
122
+ * The choice belongs to the conversation, not to each message on its own:
123
+ * a conversation can move up (a hard question after a "hi" gets more care)
124
+ * but never back down, because switching back and forth would change the
125
+ * agent's tone and defeat prompt caching. A `completion` has no
126
+ * conversation to belong to, so each one is routed by itself.
127
+ *
128
+ * Accepted only when the owner offers Auto AND model switching is on —
129
+ * exactly when `GET /egoz/models` reports `auto.available: true`.
130
+ * Otherwise it is `ModelNotAllowed` (400), by the rule above: with Auto
131
+ * off, a caller who asked for it and silently got the default model would
132
+ * believe a router had picked it; with switching off, `model` takes no
133
+ * value at all — `"auto"` included, even where Auto is the default.
134
+ *
135
+ * `"auto"` always means Auto, never a model of that name: a model or
136
+ * deployment really named `auto` is reached by its canonical id (e.g.
137
+ * `"azure:auto"`).
138
+ *
139
+ * `AskResponseData.model` names the model that actually answered, as on
140
+ * any other turn.
141
+ *
142
+ * ── An explicit pick beats an Auto default ───────────────────────────
143
+ *
144
+ * With Auto as the project default, an omitted `model` runs Auto, but a
145
+ * model id still runs exactly that model — the project's configured model
146
+ * included, which stays on the menu. Auto is the owner's answer for a
147
+ * caller with no preference; a caller who names a model has one, and
148
+ * re-routing it would be the silent override this field refuses to make.
149
+ *
150
+ * ── Scope, and what it does NOT change ───────────────────────────────
151
+ *
114
152
  * - Embeddings are pinned to the project. The knowledge base's vectors
115
153
  * were written in one embedding space, and retrieving against another
116
154
  * 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.
155
+ * - A voice call ignores it, and ignores Auto the same way, whether
156
+ * `"auto"` was sent or Auto is the project default. A call is a
157
+ * latency budget; the tenant's `voiceModel` still wins there. The
158
+ * value is still validated, so a bad one is a 400 rather than a
159
+ * surprise.
120
160
  */
121
161
  model?: string;
122
162
 
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 demanding a turn is: how much reasoning it gets and,
88
+ * when the owner picked them, whether it runs on a lighter or a stronger
89
+ * model from this project's menu.
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
  /**