@ego-z/contracts 0.15.16 → 0.15.18

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.16",
3
+ "version": "0.15.18",
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
@@ -115,13 +115,15 @@ export interface AskRequestBody {
115
115
  *
116
116
  * ── `"auto"`: let EgoZ choose ────────────────────────────────────────
117
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.
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.
121
122
  * 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.
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.
125
127
  *
126
128
  * Accepted only when the owner offers Auto AND model switching is on —
127
129
  * exactly when `GET /egoz/models` reports `auto.available: true`.
@@ -135,7 +137,7 @@ export interface AskRequestBody {
135
137
  * `"azure:auto"`).
136
138
  *
137
139
  * `AskResponseData.model` names the model that actually answered, as on
138
- * any other turn.
140
+ * any other turn, and `AskResponseData.routing` the tier Auto picked.
139
141
  *
140
142
  * ── An explicit pick beats an Auto default ───────────────────────────
141
143
  *
@@ -514,6 +516,40 @@ export interface AskStreamRequestBody extends AskRequestBody {
514
516
  * orchestrator's return type and the SDK's decoder reference this interface,
515
517
  * which is the structural guard against the two of them ever drifting again.
516
518
  */
519
+ /**
520
+ * Auto's tiers: `light` turns get less reasoning (and, when the owner picked
521
+ * one, a lighter model), `heavy` turns more (and a stronger model), and
522
+ * `default` turns run as the project is configured.
523
+ */
524
+ export type AutoTier = 'light' | 'default' | 'heavy';
525
+
526
+ /**
527
+ * How Auto routed a turn — `AskResponseData.routing` and the stream's `done`
528
+ * event. Present only on turns Auto decided: a turn that ran Auto, or, while
529
+ * the owner tries Auto without applying it, a turn that picked no model.
530
+ */
531
+ export interface AskRouting {
532
+ /**
533
+ * The tier Auto picked. A conversation keeps the highest tier it has
534
+ * reached, so a later turn never gets a lower one.
535
+ */
536
+ tier: AutoTier;
537
+ /**
538
+ * How the tier was picked:
539
+ * - `classifier`: Auto judged this turn;
540
+ * - `sticky`: the conversation was already at a higher tier, and the turn
541
+ * kept it (at `heavy`, Auto stops judging);
542
+ * - `fallback`: Auto couldn't judge this turn in time, so it ran at
543
+ * `default`.
544
+ */
545
+ source: 'classifier' | 'sticky' | 'fallback';
546
+ /**
547
+ * `false` while the owner is only trying Auto: the tier was recorded, and
548
+ * the project's default model answered as usual.
549
+ */
550
+ applied: boolean;
551
+ }
552
+
517
553
  export interface AskResponseData {
518
554
  /** Thread the message was appended to (new or existing). */
519
555
  threadId: string;
@@ -534,6 +570,8 @@ export interface AskResponseData {
534
570
  usage: TokenUsage;
535
571
  /** Resolved model id, e.g. `gpt-4.1-mini-2025-04-14`. */
536
572
  model: string;
573
+ /** How Auto routed this turn. Absent on turns Auto didn't decide. */
574
+ routing?: AskRouting;
537
575
  /** Echo of `AskRequestBody.metadata`, unchanged. */
538
576
  metadata?: Record<string, unknown>;
539
577
  /**
package/src/model.d.ts CHANGED
@@ -84,9 +84,9 @@ export interface SwitchableModelsResponseData {
84
84
  models: SwitchableModelWire[];
85
85
  /**
86
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).
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
90
  *
91
91
  * `available` is true when a caller may send `model: "auto"` — the owner
92
92
  * offers Auto AND `switchable` is true. List Auto in a picker only then.
package/src/stream.d.ts CHANGED
@@ -11,6 +11,7 @@
11
11
  * because it inherits from `AskRequestBody`.
12
12
  */
13
13
 
14
+ import type { AskRouting } from './ask';
14
15
  import type { Intent, TokenUsage } from './envelope';
15
16
  import type { AskQuestionSet } from './questions';
16
17
  import type { InitContextItemAccepted } from './draft-conv';
@@ -317,6 +318,9 @@ export interface AskStreamDoneEvent {
317
318
  toolUsed: string | null;
318
319
  ragChunksUsed: number;
319
320
  model: string;
321
+ /** How Auto routed this turn. Same semantics as `AskResponseData.routing`;
322
+ * absent on turns Auto didn't decide. */
323
+ routing?: AskRouting;
320
324
  usage: TokenUsage;
321
325
  /**
322
326
  * Auto-generated conversation title (SPI_202). Same semantics as