@ego-z/contracts 0.15.9 → 0.15.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.9",
+  "version": "0.15.10",
   "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

@@ -7,6 +7,7 @@
 
 import type { Intent, JsonSchemaDefinition, ResponseFormat, TokenUsage } from './envelope';
 import type { InitContextItem, InitContextUi } from './draft-conv';
+import type { AskQuestionSet } from './questions';
 
 // ============================================================================
 // /ask — request
@@ -320,6 +321,21 @@ export interface AskResponseData {
      * consumers that ignore it are unaffected (Path-B native-approvals path).
      */
     pendingActions?: Array<{ approvalId: string; toolName: string; summary: string }>;
+    /**
+     * A structured set of questions the agent is asking this turn, for the
+     * consumer to render as a picker instead of leaving the user to re-type a
+     * choice from a numbered list in `answer`.
+     *
+     * Present only on a turn that actually asked; at most one set per turn.
+     * Same species as `pendingActions` — an out-of-band card the consumer
+     * renders and resolves separately — and, like it, additive: a consumer
+     * that ignores this field still gets a coherent `answer`, because the
+     * questions are also stated in the reply text.
+     *
+     * The answer comes back as an ordinary `AskRequestBody.message`; there is
+     * no structured answer channel. See `questions.d.ts` for why.
+     */
+    questionSet?: AskQuestionSet;
     /**
      * Per-end-user learning observability (Phase 15 / exURM). Present only when
      * learning was ACTIVE for the turn (tenant opt-in + `externalUserId` present

package/src/index.d.ts

@@ -26,6 +26,9 @@
  *                        `AskResponseData`.
  *   - `stream.d.ts`   — full `AskStreamEvent` discriminated union +
  *                        every variant.
+ *   - `questions.d.ts` — the structured question set a turn can carry on
+ *                        `AskResponseData` / `AskStreamDoneEvent`:
+ *                        `AskQuestionSet`, `AskQuestion`, `AskAnswer`.
  *   - `tool.d.ts`     — `ToolWire`, `ToolCreateBody`, `ToolUpdateBody`,
  *                        `ToolListResponseData`, `ToolGetResponseData`,
  *                        `ToolPreview`, vocabularies (`ToolType`,
@@ -91,6 +94,7 @@
 export * from './envelope';
 export * from './ask';
 export * from './stream';
+export * from './questions';
 export * from './tool';
 export * from './rag';
 export * from './api-key';

package/src/questions.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @ego-z/contracts — the structured question set a turn can put on the wire.
+ *
+ * When the agent needs the user to CHOOSE rather than to read, it emits one of
+ * these instead of a numbered list in prose. The consumer renders a picker and
+ * feeds the selection back as the next turn's `message`.
+ *
+ * ── Why this is a wire type and not a prompt convention ──────────────────
+ *
+ * The obvious implementation is a markup token the model is taught to emit
+ * (`<Questions>…`) and the consumer parses. That works exactly as long as one
+ * provider's prompt keeps honouring it — it is an AUTHORING shape, and it
+ * dies on a provider move, silently, in the consumer.
+ *
+ * So the parse belongs to EgoZ and the wire carries the result. However a
+ * provider expresses the intent — a tool call today, a JSON mode response
+ * tomorrow — it is normalised here before it leaves the backend, and no
+ * consumer ever sees provider-shaped output. Moving providers rewrites one
+ * adapter rather than every renderer.
+ *
+ * ── Ids are minted by the emitter, never derived from labels ─────────────
+ *
+ * A consumer that keys an answer by its label breaks the first time a
+ * provider emits `**#b49c54**` where it used to emit `#b49c54`. Every id here
+ * comes from the emission side: a tool's own domain ids where a tool supplied
+ * the options, EgoZ-minted otherwise. The model never supplies one — a
+ * model-minted id looks stable and isn't.
+ *
+ * ── The answer does NOT come back through this type ──────────────────────
+ *
+ * There is no answer field on `AskRequestBody`, deliberately. The model has to
+ * READ the pick, and only `message` reaches the prompt, so the answer travels
+ * as ordinary message text; the ids ride on `metadata` for the consumer's own
+ * correlation. That split is why a question set stays answerable long after
+ * the turn that produced it — the text means the same thing tomorrow.
+ */
+
+/**
+ * One set of questions the agent is asking this turn — the whole card.
+ *
+ * At most one per turn. A turn that would produce a second set is refused at
+ * emission rather than overwriting the first, so a consumer can treat "a set
+ * arrived" and "the set for this turn" as the same thing.
+ */
+export interface AskQuestionSet {
+    /**
+     * Correlates an answer back to the turn that asked.
+     *
+     * **Opaque.** No ordering, no derivability from content, and NOT stable
+     * across turns: a retried turn produces a different set with different
+     * ids, because it is a different emission. A consumer that persists a set
+     * keys on this and never assumes two turns share it.
+     */
+    id: string;
+    /** Heading for the whole set, e.g. "A few details before I book that". */
+    title?: string;
+    /**
+     * The language EgoZ actually resolved for this turn — not the one the
+     * caller requested.
+     *
+     * REQUIRED, and it is doing more work than it looks like: it is the only
+     * thing that can set text direction. `dir="auto"` infers direction from
+     * the first strong character and therefore gets a Hebrew question whose
+     * answers are hex colours exactly backwards. Optionality here would mean
+     * "guess the direction", which is the bug rather than the fallback.
+     */
+    locale: string;
+    /** At least one. Rendered in order. */
+    questions: AskQuestion[];
+}
+
+/** One question within a set. */
+export interface AskQuestion {
+    /** Opaque, emitter-minted — see `AskQuestionSet.id`. */
+    id: string;
+    /**
+     * What is being asked, e.g. "Which shade?".
+     *
+     * Must stand alone. It is the only context an answer's `label` gets, both
+     * in the UI and in the sentence the consumer composes when the user picks.
+     */
+    title: string;
+    /**
+     * The offered answers, in display order. Never empty — a question with
+     * nothing to choose between is asked in prose, not in a card, and is
+     * rejected at emission.
+     */
+    answers: AskAnswer[];
+    /**
+     * Whether this question also accepts a free-text answer — the "something
+     * else" slot. Per-question, not per-set: a set can mix a chip question
+     * with one that invites a note.
+     *
+     * It EXTENDS `answers`, never replaces it. Absent means chips only.
+     */
+    allowCustom?: boolean;
+    /**
+     * Whether more than one answer may be selected. Absent means single-select.
+     *
+     * Set by whoever holds the options and knows if they compose — never
+     * inferred by a consumer from how the question is phrased.
+     */
+    multi?: boolean;
+}
+
+/** One selectable answer. */
+export interface AskAnswer {
+    /** Opaque, emitter-minted — see `AskQuestionSet.id`. */
+    id: string;
+    /**
+     * What the user sees, already in `AskQuestionSet.locale`.
+     *
+     * Must be meaningful on its own, because it is what ends up in the next
+     * turn's message text: `#b49c54` reads fine, `"Option 2"` does not — that
+     * one only means anything against a rendered list the model never sees.
+     */
+    label: string;
+    /** Optional secondary line, e.g. a price or a duration. */
+    description?: string;
+}

package/src/stream.d.ts

@@ -12,6 +12,7 @@
  */
 
 import type { Intent, TokenUsage } from './envelope';
+import type { AskQuestionSet } from './questions';
 
 /**
  * Discriminated union of every event the streaming `/ask` endpoint emits.
@@ -323,6 +324,26 @@ export interface AskStreamDoneEvent {
      * Approve/Reject card without parsing the final `data` payload separately.
      */
     pendingActions?: Array<{ approvalId: string; toolName: string; summary: string }>;
+    /**
+     * A structured set of questions the agent asked this turn. Same semantics
+     * + shape as `AskResponseData.questionSet` — surfaced on the terminal
+     * event so streaming consumers can render the picker without parsing the
+     * final `data` payload separately.
+     *
+     * ── Why the terminal frame and not a mid-stream event ────────────────
+     *
+     * A card that offers choices is only actionable once the turn is settled,
+     * and consumers already gate it that way — the Console suppresses its
+     * choice row until the stream completes. A dedicated mid-stream variant
+     * would be a channel every consumer discards until `done` anyway, bought
+     * at the price of a new member of this union (non-breaking for producers,
+     * breaking for consumers that exhaustively switch on `event.type`).
+     *
+     * The cost, chosen rather than overlooked: a turn that terminates with
+     * `error` after producing a set loses the card. `pendingActions` carries
+     * the identical hole; the retry re-runs the turn.
+     */
+    questionSet?: AskQuestionSet;
     /**
      * Per-end-user learning observability (Phase 15 / exURM). Same semantics as
      * `AskResponseData.{memoryInjected,memoryProposed}` — surfaced on the