@ego-z/contracts 0.15.28 → 0.15.30

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.28",
3
+ "version": "0.15.30",
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
@@ -687,6 +687,60 @@ export interface AskRouting {
687
687
  applied: boolean;
688
688
  }
689
689
 
690
+ /**
691
+ * Tokens by part of the prompt, as `AskContextUsage.byPart` estimates them.
692
+ * The keys match the trace's `context` step. Later releases add `summary`
693
+ * (conversation summaries) and `digests` (tool-result digests).
694
+ */
695
+ export interface AskContextParts {
696
+ /** The system prompt, every policy segment included. */
697
+ system: number;
698
+ /** The tool definitions offered on the first call. */
699
+ tools: number;
700
+ /** The end user's approved facts (Learning). */
701
+ facts: number;
702
+ /** Knowledge-base passages. */
703
+ kb: number;
704
+ /** Earlier messages of the conversation that were sent. */
705
+ history: number;
706
+ /** This turn's message. */
707
+ current: number;
708
+ }
709
+
710
+ /**
711
+ * How much of the answering model's context the turn's first call used:
712
+ * `AskResponseData.context` and the stream's `done` event.
713
+ *
714
+ * Every number but `reported` is EgoZ's own ESTIMATE, made before the call
715
+ * with the model's tokenizer where EgoZ has it and a character ratio where it
716
+ * doesn't. Show it as an estimate ("≈ 34k"). `reported` is the provider's own
717
+ * count, once it gives one.
718
+ */
719
+ export interface AskContextUsage {
720
+ /** The model that answered — after Auto, never the one routing started from. */
721
+ model: string;
722
+ /** That model's context window in tokens. 128,000 when EgoZ doesn't know it. */
723
+ window: number;
724
+ /**
725
+ * Tokens EgoZ lets the prompt use: the window less room for the reply
726
+ * and a safety margin, or the project's `contextBudgetTokens` when lower.
727
+ */
728
+ budget: number;
729
+ /** Estimated tokens of the prompt that was sent. */
730
+ estimated: number;
731
+ /** The provider's `promptTokens` for the same call. `null` when it reported none. */
732
+ reported: number | null;
733
+ byPart: AskContextParts;
734
+ /** Earlier messages left out to fit the budget. `0` when all of them fit. */
735
+ historyDropped: number;
736
+ /**
737
+ * `true` when the provider refused a prompt as too long and EgoZ sent a
738
+ * smaller one. It retries once; a second refusal ends the turn with
739
+ * `ContextBudgetExceeded` (`EGX_ERR-LLM04`).
740
+ */
741
+ retried: boolean;
742
+ }
743
+
690
744
  export interface AskResponseData {
691
745
  /** Thread the message was appended to (new or existing). */
692
746
  threadId: string;
@@ -709,6 +763,11 @@ export interface AskResponseData {
709
763
  model: string;
710
764
  /** How Auto routed this turn. Absent on turns Auto didn't decide. */
711
765
  routing?: AskRouting;
766
+ /**
767
+ * How much of the answering model's context the turn used. Present on
768
+ * every turn that called a model. Additive — older consumers ignore it.
769
+ */
770
+ context?: AskContextUsage;
712
771
  /** Echo of `AskRequestBody.metadata`, unchanged. */
713
772
  metadata?: Record<string, unknown>;
714
773
  /**
@@ -139,7 +139,15 @@ export interface ProjectFileConfig {
139
139
  temperature: number;
140
140
  maxTokens: number | null;
141
141
  responseFormat: 'text' | 'json_object';
142
+ /** The most earlier messages a turn may send. Fewer go when they don't fit the context budget. */
142
143
  historyLength: number;
144
+ /**
145
+ * The project's cap on the tokens one model call's prompt may use,
146
+ * 1,000..2,000,000. `null` = no cap: the answering model's window sets
147
+ * the budget. Absent from files made before it existed; an import then
148
+ * gives the project a new project's value, no cap.
149
+ */
150
+ contextBudgetTokens?: number | null;
143
151
  orchestrationMode: OrchestrationMode;
144
152
  assistModel: string | null;
145
153
  verifyMode: VerifyMode;
package/src/stream.d.ts CHANGED
@@ -11,7 +11,7 @@
11
11
  * because it inherits from `AskRequestBody`.
12
12
  */
13
13
 
14
- import type { AskRouting } from './ask';
14
+ import type { AskContextUsage, AskRouting } from './ask';
15
15
  import type { Intent, TokenUsage } from './envelope';
16
16
  import type { AskQuestionSet } from './questions';
17
17
  import type { GeneratedImage } from './images';
@@ -364,6 +364,9 @@ export interface AskStreamDoneEvent {
364
364
  /** How Auto routed this turn. Same semantics as `AskResponseData.routing`;
365
365
  * absent on turns Auto didn't decide. */
366
366
  routing?: AskRouting;
367
+ /** How much of the answering model's context the turn used. Same
368
+ * semantics as `AskResponseData.context`. */
369
+ context?: AskContextUsage;
367
370
  usage: TokenUsage;
368
371
  /**
369
372
  * Auto-generated conversation title (SPI_202). Same semantics as
package/src/thread.d.ts CHANGED
@@ -18,6 +18,7 @@
18
18
  * `formatThread` and `formatMessage` now emit ISO to match.
19
19
  */
20
20
 
21
+ import type { AskContextUsage } from './ask';
21
22
  import type { Intent } from './envelope';
22
23
 
23
24
  // ============================================================================
@@ -38,7 +39,12 @@ export type MessageFailureReason =
38
39
  | 'tool_retry_storm'
39
40
  | 'iteration_cap'
40
41
  | 'max_calls_per_turn'
41
- | 'unrecoverable_error';
42
+ | 'unrecoverable_error'
43
+ /** The turn ran out of room in the answering model's context, so EgoZ
44
+ * stopped offering tools and the model answered from what it had
45
+ * (migration 074). A prompt that can't be sent at all is not stored:
46
+ * the turn fails with `ContextBudgetExceeded` (`EGX_ERR-LLM04`). */
47
+ | 'context_budget';
42
48
 
43
49
  /**
44
50
  * Conversation lifecycle state. Mirrors the CHECK constraint on
@@ -184,6 +190,13 @@ export interface MessageWire {
184
190
  model: string | null;
185
191
  /** Echo of `AskRequestBody.metadata` for audit. */
186
192
  metadata: Record<string, unknown> | null;
193
+ /**
194
+ * On an assistant row, how much of the answering model's context the
195
+ * turn used: the same value as that turn's `AskResponseData.context`
196
+ * (migration 074). `null` on other rows and on turns made before it
197
+ * existed. Absent from servers that predate it.
198
+ */
199
+ context?: AskContextUsage | null;
187
200
  /**
188
201
  * `true` when this row's `content` was deliberately dropped under
189
202
  * no-store (metadata-only) persistence — see