@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 +1 -1
- package/src/ask.d.ts +85 -2
- package/src/project-file.d.ts +8 -0
- package/src/stream.d.ts +4 -1
- package/src/thread.d.ts +4 -1
package/package.json
CHANGED
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
|
|
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
|
/**
|
package/src/project-file.d.ts
CHANGED
|
@@ -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
|