@ego-z/contracts 0.15.26 → 0.15.28
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 +43 -2
- package/src/stream.d.ts +41 -0
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
|
*
|
|
@@ -550,6 +574,8 @@ export interface AskMachineOutput {
|
|
|
550
574
|
* - `true` (default when omitted) → full thinking timeline (intent, rag.*,
|
|
551
575
|
* tool.*, delta, done).
|
|
552
576
|
* - `'minimal'` → only intent, delta, done, error.
|
|
577
|
+
*
|
|
578
|
+
* Either way, `reasoning` events come only when `reasoning: true` asks for them.
|
|
553
579
|
*/
|
|
554
580
|
export interface AskStreamRequestBody extends AskRequestBody {
|
|
555
581
|
stream?: true | 'minimal';
|
|
@@ -576,6 +602,21 @@ export interface AskStreamRequestBody extends AskRequestBody {
|
|
|
576
602
|
*/
|
|
577
603
|
phaseMode?: 'buffered' | 'live';
|
|
578
604
|
|
|
605
|
+
/**
|
|
606
|
+
* Ask for the model's reasoning as `reasoning` events (see
|
|
607
|
+
* `AskStreamReasoningEvent`). Omit it and the wire is byte-identical to
|
|
608
|
+
* before: this flag is the only thing that can introduce them.
|
|
609
|
+
*
|
|
610
|
+
* It shows reasoning the model does anyway and never switches thinking on,
|
|
611
|
+
* so it adds nothing to what a turn costs. A model that doesn't think by
|
|
612
|
+
* itself, or that keeps its reasoning to itself (OpenAI today), sends none.
|
|
613
|
+
*
|
|
614
|
+
* Prefer the SDK's `askStream(request, { reasoning: true })` over setting
|
|
615
|
+
* it by hand, for the reason given on `phaseMode`: an SDK too old to have
|
|
616
|
+
* the option is too old to fold the event into its timeline.
|
|
617
|
+
*/
|
|
618
|
+
reasoning?: boolean;
|
|
619
|
+
|
|
579
620
|
/**
|
|
580
621
|
* Opt-in deep-execution trace for the Console "Your Agent" playground.
|
|
581
622
|
*
|
package/src/stream.d.ts
CHANGED
|
@@ -25,6 +25,7 @@ import type { InitContextItemAccepted } from './draft-conv';
|
|
|
25
25
|
* - `start` is always the FIRST frame, in every mode including
|
|
26
26
|
* `'minimal'`. It carries the conversation id.
|
|
27
27
|
* - `stream: 'minimal'` requests omit `rag.*` and `tool.*` events.
|
|
28
|
+
* - `reasoning` events appear only when the request set `reasoning: true`.
|
|
28
29
|
* - `done` is always the terminal success frame.
|
|
29
30
|
* - `error` may appear at any point and is also terminal.
|
|
30
31
|
*/
|
|
@@ -35,6 +36,7 @@ export type AskStreamEvent =
|
|
|
35
36
|
| AskStreamRagRetrievedEvent
|
|
36
37
|
| AskStreamDeltaEvent
|
|
37
38
|
| AskStreamIterationEndEvent
|
|
39
|
+
| AskStreamReasoningEvent
|
|
38
40
|
| AskStreamToolCallingEvent
|
|
39
41
|
| AskStreamToolResultEvent
|
|
40
42
|
| AskStreamLLMDebugEvent
|
|
@@ -201,6 +203,45 @@ export interface AskStreamIterationEndEvent {
|
|
|
201
203
|
durationMs: number;
|
|
202
204
|
}
|
|
203
205
|
|
|
206
|
+
/**
|
|
207
|
+
* The model's reasoning, as the readable summary its provider returns, while
|
|
208
|
+
* it works. **Only on a request that opted in with
|
|
209
|
+
* `AskStreamRequestBody.reasoning: true`**, so a consumer that never asked
|
|
210
|
+
* sees a byte-identical wire.
|
|
211
|
+
*
|
|
212
|
+
* Never part of the answer. `delta` carries the answer and the narration
|
|
213
|
+
* around tool calls; this carries what the model thought before writing
|
|
214
|
+
* either. It is not stored with the conversation: the thread keeps the answer.
|
|
215
|
+
*
|
|
216
|
+
* Arrives in fragments, like `delta`: concatenate the `content` of consecutive
|
|
217
|
+
* events with the same `iteration`. Within an iteration it comes before that
|
|
218
|
+
* iteration's text and tool calls, because the model reasons first. It streams
|
|
219
|
+
* as it arrives in both phase modes; `phaseMode` only governs `delta`.
|
|
220
|
+
*
|
|
221
|
+
* Sent only when the model reasons AND hands back a readable summary: today,
|
|
222
|
+
* Anthropic models that think by default (Claude 5.x and later). The opt-in
|
|
223
|
+
* never switches thinking on for a model that doesn't think by itself, and
|
|
224
|
+
* OpenAI models send none, since their reasoning stays inside the model. So a
|
|
225
|
+
* turn without these events has nothing to show; it is never an error.
|
|
226
|
+
*
|
|
227
|
+
* ⚠️ It can restate what tools returned (a customer's email, an order), so
|
|
228
|
+
* show it only to an audience that may see the turn's tool results.
|
|
229
|
+
*
|
|
230
|
+
* ── Why an event of its own and not a `delta` phase ──────────────────────
|
|
231
|
+
*
|
|
232
|
+
* A consumer on an SDK that predates it reads a `delta` with an unknown phase
|
|
233
|
+
* as `'final'` (the legacy rule for an absent phase), so a reasoning phase
|
|
234
|
+
* would show the reasoning as the answer, and persist it as one. An event
|
|
235
|
+
* type it does not know it ignores.
|
|
236
|
+
*/
|
|
237
|
+
export interface AskStreamReasoningEvent {
|
|
238
|
+
type: 'reasoning';
|
|
239
|
+
/** A fragment of the reasoning summary. */
|
|
240
|
+
content: string;
|
|
241
|
+
/** Zero-based index in the orchestrator's tool loop, as on `iteration.end`. */
|
|
242
|
+
iteration: number;
|
|
243
|
+
}
|
|
244
|
+
|
|
204
245
|
export interface AskStreamToolCallingEvent {
|
|
205
246
|
type: 'tool.calling';
|
|
206
247
|
name: string;
|