@ego-z/contracts 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
   "types": "./src/index.d.ts",
   "exports": {

package/src/ask.d.ts

@@ -157,6 +157,28 @@ export interface AskRequestBody {
 export interface AskStreamRequestBody extends AskRequestBody {
     stream?: true | 'minimal';
 
+    /**
+     * How `delta.phase` is decided — orthogonal to `stream`, which controls
+     * *which* events are emitted rather than *when* text is released.
+     *
+     *   - `'buffered'` (default when omitted) → an iteration's text is held
+     *     until its phase is known, so every delta lands correctly labelled.
+     *     The terminal answer arrives as a single delta.
+     *   - `'live'`     → text streams token-by-token as `phase: 'pending'`,
+     *     and an `iteration.end` event classifies the block once the
+     *     iteration closes.
+     *
+     * Omit it and the wire is byte-identical to a pre-0.14.0 backend — this
+     * flag is the only thing that can introduce `'pending'` deltas or
+     * `iteration.end` events, so existing consumers cannot encounter either.
+     *
+     * Prefer the SDK's `askStream(request, { live: true })` option over
+     * setting this by hand: an SDK old enough to lack the option is also
+     * old enough to lack the reducer support, and routing it through the
+     * option makes that version skew impossible to express.
+     */
+    phaseMode?: 'buffered' | 'live';
+
     /**
      * Opt-in deep-execution trace for the Console "Your Agent" playground.
      *

package/src/stream.d.ts

@@ -26,6 +26,7 @@ export type AskStreamEvent =
     | AskStreamRagSearchingEvent
     | AskStreamRagRetrievedEvent
     | AskStreamDeltaEvent
+    | AskStreamIterationEndEvent
     | AskStreamToolCallingEvent
     | AskStreamToolResultEvent
     | AskStreamLLMDebugEvent
@@ -62,17 +63,60 @@ export interface AskStreamDeltaEvent {
      * text, no further tool calls follow).
      *
      * Consumers can use this to render two channels: a secondary
-     * "thinking out loud" strip and the primary answer body. A single
-     * 'thinking' iteration streams live token-by-token; the 'final'
-     * delta is flushed as one event at iteration end so its label is
-     * known when it lands (the alternative would be a post-hoc
-     * correction event, which was rejected).
+     * "thinking out loud" strip and the primary answer body.
+     *
+     * **Buffered mode (default).** An iteration's text is held until its
+     * nature is known, so the label is always correct when it lands: a
+     * 'thinking' iteration streams live token-by-token once its first
+     * tool_call arrives, and the 'final' delta is flushed as one event at
+     * iteration end. The trade is that the terminal answer arrives whole
+     * rather than typing out.
+     *
+     * **Live mode** (`AskStreamRequestBody.phaseMode: 'live'`). Every text
+     * delta streams immediately as `'pending'` and the enclosing block is
+     * classified by the `iteration.end` event that closes it. No delta is
+     * ever re-labelled — the text a reader has seen never changes, only
+     * the container around it resolves. This is materially different from
+     * the post-hoc *correction* design that was rejected: that one asserted
+     * a phase and later retracted it; this one asserts nothing until it
+     * knows.
      *
      * Optional so a consumer pinned to an older contract version still
-     * parses the frame. Absent only on the pre-phase emit sites that
-     * predate the field.
+     * parses the frame. **Absent means `'final'`** — that is the legacy
+     * reading for a backend predating this field, and it is why an
+     * undecided delta must carry `'pending'` explicitly rather than
+     * omitting the field: `askStreamReducer` is pure and never sees the
+     * request, so it cannot otherwise tell "old backend" from "not yet
+     * decided".
      */
-    phase?: 'thinking' | 'final';
+    phase?: 'thinking' | 'final' | 'pending';
+}
+
+/**
+ * Closes one orchestrator iteration and classifies the block of `'pending'`
+ * deltas it produced. **Live mode only** — buffered streams never emit it,
+ * so a consumer that does not opt in sees a byte-identical wire.
+ *
+ * Emitted at iteration end, *before* any `tool.calling` for that iteration,
+ * so a consumer's timeline always settles before the next thing moves.
+ *
+ * `phase` is authoritative: it reports whether the orchestrator is actually
+ * going on to dispatch tools (`'thinking'`) or this was the terminal answer
+ * (`'final'`). It is derived from the same condition that drives the loop,
+ * not from a guess made while the text was still arriving.
+ */
+export interface AskStreamIterationEndEvent {
+    type: 'iteration.end';
+    /** Zero-based index in the orchestrator's tool loop. */
+    iteration: number;
+    /** What the just-closed block of `'pending'` deltas turned out to be. */
+    phase: 'thinking' | 'final';
+    /**
+     * Wall-clock duration of this iteration's LLM call, measured server-side.
+     * Lets a consumer render "Thought for 1.2s" from the real number rather
+     * than timing arrival, which would include transport and buffering.
+     */
+    durationMs: number;
 }
 
 export interface AskStreamToolCallingEvent {