@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ego-z/contracts",
3
- "version": "0.15.26",
3
+ "version": "0.15.28",
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
  *
@@ -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;