@ego-z/contracts 0.15.27 → 0.15.29

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.27",
3
+ "version": "0.15.29",
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
@@ -279,8 +279,8 @@ export interface AskRequestBody {
279
279
  * built-in its config leaves off, stays off. An unknown name is ignored
280
280
  * rather than refused, because a tool can be disabled after the caller
281
281
  * was written. A classic project's pre-fetched knowledge-base context is
282
- * not a tool and is unaffected; memory the project already injects is
283
- * still read.
282
+ * not a tool and is unaffected (`knowledge: false` turns it off); memory
283
+ * the project already injects is still read.
284
284
  *
285
285
  * An array of non-empty strings, at most 64; anything else is a 400, and
286
286
  * so is `tools` together with `completion: true` (a completion offers no
@@ -290,6 +290,30 @@ export interface AskRequestBody {
290
290
  */
291
291
  tools?: string[];
292
292
 
293
+ /**
294
+ * `false`: this turn reads no knowledge base — no pre-fetched chunks on a
295
+ * classic project, no `search_knowledge_base` tool on an agentic one. The
296
+ * rest of the agent stays: the project's prompt, personality, session
297
+ * context, tools, memory and the conversation. A turn that has no tools
298
+ * then gets the project's base prompt, where it would have defaulted to
299
+ * the RAG one.
300
+ *
301
+ * ── Why it exists ────────────────────────────────────────────────────
302
+ *
303
+ * A program that writes the agent's words for it (AppNA's onboarding:
304
+ * Ana's greeting and the note after the setup) hands the turn everything
305
+ * it needs to say. With no tools and no question in it, such a turn
306
+ * classified as RAG: it got the RAG prompt ("answer using ONLY the
307
+ * provided context") and a knowledge-base passage unrelated to the
308
+ * message, and paid for an embedding and a search on every turn.
309
+ * `completion: true` turns the knowledge base off too, but also the
310
+ * persona, the conversation and storage, which such a turn needs.
311
+ *
312
+ * Only `false` changes anything; `true` and omitted keep the project's
313
+ * setting. Not a boolean: 400.
314
+ */
315
+ knowledge?: boolean;
316
+
293
317
  /**
294
318
  * Tools a turn narrowed by `tools` may still load, by group.
295
319
  *
@@ -663,6 +687,60 @@ export interface AskRouting {
663
687
  applied: boolean;
664
688
  }
665
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
+
666
744
  export interface AskResponseData {
667
745
  /** Thread the message was appended to (new or existing). */
668
746
  threadId: string;
@@ -685,6 +763,11 @@ export interface AskResponseData {
685
763
  model: string;
686
764
  /** How Auto routed this turn. Absent on turns Auto didn't decide. */
687
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;
688
771
  /** Echo of `AskRequestBody.metadata`, unchanged. */
689
772
  metadata?: Record<string, unknown>;
690
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
+ * keeps the project's own.
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
@@ -38,7 +38,10 @@ export type MessageFailureReason =
38
38
  | 'tool_retry_storm'
39
39
  | 'iteration_cap'
40
40
  | 'max_calls_per_turn'
41
- | 'unrecoverable_error';
41
+ | 'unrecoverable_error'
42
+ /** The prompt didn't fit the answering model's context, even after
43
+ * EgoZ shortened it and retried once (migration 074). */
44
+ | 'context_budget';
42
45
 
43
46
  /**
44
47
  * Conversation lifecycle state. Mirrors the CHECK constraint on