@ego-z/contracts 0.15.25 → 0.15.27

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.25",
3
+ "version": "0.15.27",
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/agents.d.ts CHANGED
@@ -69,15 +69,17 @@
69
69
  * started, queue time included, so a run still waiting at `deadlineAt` ends
70
70
  * `failed: timeout` without having run.
71
71
  *
72
- * ── The note on the main agent's conversation ───────────────────────────
72
+ * ── What the main agent is told ──────────────────────────────────────────
73
73
  *
74
- * When a run ends, EgoZ adds a short note to the conversation that started
75
- * it, so the main agent's next turn knows — e.g.
76
- * `[translator finished. It reported: «…»]`, `[translator failed: budget]`,
77
- * `[translator needs your input: «…» — ask the user]`. The reported text is
78
- * cut to 500 characters and quoted as data, never as instructions: a
79
- * sub-agent may have read pages written by anyone. The full result is on the
80
- * run. EgoZ starts no turn by itself: to have the main agent tell the user
74
+ * The main agent's next turn on the conversation that started a run is told
75
+ * how it went, in a "Sub-agent runs" block of that turn's prompt — e.g.
76
+ * `translator (run …): finished. It reported: «…»`, `…: failed (budget): …`,
77
+ * `…: needs the user's input: «…» — ask the user …` — and runs still going are
78
+ * listed too, so it doesn't start them again. An ended run is shown once. The
79
+ * reported text is cut to 500 characters and quoted as data, never as
80
+ * instructions: a sub-agent may have read pages written by anyone. The full
81
+ * result is on the run. Nothing is added to the conversation's messages.
82
+ * EgoZ starts no turn by itself: to have the main agent tell the user
81
83
  * unprompted, send the next /ask yourself when the webhook arrives.
82
84
  */
83
85
 
package/src/ask.d.ts CHANGED
@@ -550,6 +550,8 @@ export interface AskMachineOutput {
550
550
  * - `true` (default when omitted) → full thinking timeline (intent, rag.*,
551
551
  * tool.*, delta, done).
552
552
  * - `'minimal'` → only intent, delta, done, error.
553
+ *
554
+ * Either way, `reasoning` events come only when `reasoning: true` asks for them.
553
555
  */
554
556
  export interface AskStreamRequestBody extends AskRequestBody {
555
557
  stream?: true | 'minimal';
@@ -576,6 +578,21 @@ export interface AskStreamRequestBody extends AskRequestBody {
576
578
  */
577
579
  phaseMode?: 'buffered' | 'live';
578
580
 
581
+ /**
582
+ * Ask for the model's reasoning as `reasoning` events (see
583
+ * `AskStreamReasoningEvent`). Omit it and the wire is byte-identical to
584
+ * before: this flag is the only thing that can introduce them.
585
+ *
586
+ * It shows reasoning the model does anyway and never switches thinking on,
587
+ * so it adds nothing to what a turn costs. A model that doesn't think by
588
+ * itself, or that keeps its reasoning to itself (OpenAI today), sends none.
589
+ *
590
+ * Prefer the SDK's `askStream(request, { reasoning: true })` over setting
591
+ * it by hand, for the reason given on `phaseMode`: an SDK too old to have
592
+ * the option is too old to fold the event into its timeline.
593
+ */
594
+ reasoning?: boolean;
595
+
579
596
  /**
580
597
  * Opt-in deep-execution trace for the Console "Your Agent" playground.
581
598
  *
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;