@ego-z/contracts 0.15.8 → 0.15.10

package/package.json

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

@@ -6,7 +6,8 @@
  */
 
 import type { Intent, JsonSchemaDefinition, ResponseFormat, TokenUsage } from './envelope';
-import type { InitContextUi } from './draft-conv';
+import type { InitContextItem, InitContextUi } from './draft-conv';
+import type { AskQuestionSet } from './questions';
 
 // ============================================================================
 // /ask — request
@@ -189,6 +190,27 @@ export interface AskRequestBody {
      * with the stored `initContext` used for the whole conversation.
      */
     ui?: InitContextUi;
+
+    /**
+     * What the USER explicitly attached to this turn's context.
+     *
+     * ── A sibling of `ui`, never a part of it ────────────────────────────
+     *
+     * `ui` is a FACT about the screen; `contextItems` is an INTENTION. The
+     * user never edits `ui` — express "don't look at this" or "also consider
+     * this" here instead. Editing the fact to carry the intention is how a
+     * window the user merely hid ends up reported as one they closed.
+     *
+     * It is also strictly wider: the user can attach something that was never
+     * a window at all, which no amount of flagging inside `ui` could express.
+     *
+     * Send the full current list every turn, not a delta — a client-computed
+     * delta needs a client-held baseline, and that baseline is wrong after a
+     * reload, a retry or a reconnect.
+     *
+     * Optional and additive: omit it and nothing changes.
+     */
+    contextItems?: InitContextItem[];
 }
 
 /**
@@ -299,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/draft-conv.d.ts

@@ -58,6 +58,48 @@ export type InitContextViewport = 'mobile' | 'desktop';
  */
 export type InitContextAudience = 'operator' | 'customer';
 
+/**
+ * One thing the user explicitly put into the chat's context.
+ *
+ * ── The caller resolves it; EgoZ never fetches ───────────────────────────
+ *
+ * You look the item up and send what it IS. EgoZ never resolves `kind + id`
+ * against your data model — doing so would put one integration's vocabulary
+ * into a shared contract, and "you can attach anything" would stop being
+ * true the day you invented a type we hadn't shipped. **A new `kind` costs
+ * zero EgoZ changes**, which is the test of whether this is genuinely
+ * open-ended rather than a list we happen to support.
+ */
+export interface InitContextItem {
+    /**
+     * Your own type name — `"product"`, `"invoice"`, anything you like.
+     *
+     * ⚠️ Free-form, and **never rendered into the prompt**. Both halves go
+     * together: free-form so a new kind needs no change at either end, and
+     * unrendered because free-form text reaching the instruction block is an
+     * injection surface — a `kind` of "ignore previous instructions" would
+     * otherwise be printed into a system prompt. Used only to group items.
+     */
+    kind?: string;
+
+    /** Your own id for the item. Structural; also never rendered. */
+    id?: string;
+
+    /**
+     * Human-readable name — `"Official Chelsea Home Shirt"`. **Required in
+     * practice**: it is the only part the model reads, so an item without one
+     * is dropped rather than rendered as an id.
+     */
+    label?: string;
+
+    /**
+     * A short description of the item. Optional, and truncated rather than
+     * rejected if long — but keep it to what the thing IS, not its full
+     * record. Everything here displaces conversation from the context window.
+     */
+    excerpt?: string;
+}
+
 /** One open window in the caller's UI. */
 export interface InitContextOpenWindow {
     /**

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