@ego-z/contracts 0.15.9 → 0.15.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.9",
+  "version": "0.15.11",
   "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 { InitContextItem, InitContextUi } from './draft-conv';
+import type { InitContextItem, InitContextItemAccepted, 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
@@ -330,4 +346,23 @@ export interface AskResponseData {
      */
     memoryInjected?: boolean;
     memoryProposed?: boolean;
+    /**
+     * What EgoZ actually accepted from `AskRequestBody.contextItems` this
+     * turn, in the order the agent saw them.
+     *
+     * Present whenever the request carried `contextItems` — including as an
+     * empty array, meaning "you sent a list and nothing in it was accepted".
+     *
+     * ⚠️ ABSENT MEANS THE REQUEST CARRIED NO `contextItems`. It never means
+     * "none were accepted". A consumer that reads absence as rejection
+     * reports a failure that did not happen; one that reads an empty array as
+     * absence reports a success that did not either.
+     *
+     * Render this — not the list you sent — anywhere you show the user what
+     * was shared with the agent. See `InitContextItemAccepted` for why the
+     * two can differ and how to join them.
+     *
+     * Additive: consumers that ignore it are unaffected.
+     */
+    contextItemsAccepted?: InitContextItemAccepted[];
 }

package/src/draft-conv.d.ts

@@ -93,13 +93,74 @@ export interface InitContextItem {
     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.
+     * A short description of the item. Optional — but keep it to what the
+     * thing IS, not its full record. Everything here displaces conversation
+     * from the context window.
+     *
+     * ⚠️ AN OVER-LONG EXCERPT IS DROPPED, NOT TRUNCATED, and the item still
+     * rides without it. Unlike every other cap here, which truncates or
+     * rejects.
+     *
+     * Because you resolve the item yourself, this is sometimes prose
+     * (`"£45, in stock"`) and sometimes an ADDRESS the agent will act on
+     * (`"projects/api/deploy.sh"`). Shortening prose loses a few words;
+     * shortening an address does not produce an invalid address, it produces
+     * a **different valid one**, which the agent then reads and reports on
+     * with no error anywhere. Nothing server-side can tell the two apart —
+     * `kind` is opaque and never resolved — so one behaviour covers both and
+     * it is the safe one.
+     *
+     * `contextItemsAccepted` on the response tells you when it happened.
      */
     excerpt?: string;
 }
 
+/**
+ * One entry in the response's `contextItemsAccepted` receipt — what EgoZ
+ * actually took from a `contextItems` you sent.
+ *
+ * ── Why a receipt exists at all ──────────────────────────────────────────
+ *
+ * Acceptance is LOSSY BY DESIGN, in three ways you cannot observe from the
+ * caller: an over-long list is truncated from the end, an item with no
+ * `label` is dropped individually, and an over-long `excerpt` is dropped
+ * while its item rides on. Each is the right behaviour — none of them should
+ * fail a user's turn — but each means the list you sent is not necessarily
+ * the list the agent saw.
+ *
+ * So if you display "what was shared with the agent" anywhere, render THIS,
+ * not the list you sent. Rendering your own list produces a display that is
+ * confident and wrong in exactly the cases that matter.
+ *
+ * ⚠️ AN ITEM MISSING FROM THE RECEIPT WAS NOT ACCEPTED. Absence is the only
+ * channel that reports the list truncation and the labelless drop, so a
+ * consumer that treats this as best-effort or partially populated silently
+ * goes back to claiming delivery it cannot verify.
+ *
+ * Match entries to your own items on `kind` + `id`. Do NOT fall back to
+ * matching on `label` — labels are deliberately not unique, so that join is
+ * usually right, and "usually right" is the failure this field exists to
+ * remove. Render an unmatched entry as unmatched instead.
+ */
+export interface InitContextItemAccepted {
+    /** Echo of the item's `kind`. Still never rendered into the prompt. */
+    kind?: string;
+    /** Echo of the item's `id`. */
+    id?: string;
+    /** The label the agent saw. Always present — a labelless item is dropped. */
+    label: string;
+    /**
+     * The item was accepted but its `excerpt` was not — it exceeded the cap
+     * and was dropped rather than truncated (see `InitContextItem.excerpt`).
+     *
+     * Absent means the excerpt survived, or there was never one to carry.
+     * Distinguishing those two is not what this flag is for: it exists so a
+     * "shared with the agent" display can say the agent got a NAME and no
+     * detail, instead of implying it got both.
+     */
+    excerptOmitted?: boolean;
+}
+
 /** 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,8 @@
  */
 
 import type { Intent, TokenUsage } from './envelope';
+import type { AskQuestionSet } from './questions';
+import type { InitContextItemAccepted } from './draft-conv';
 
 /**
  * Discriminated union of every event the streaming `/ask` endpoint emits.
@@ -323,6 +325,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
@@ -331,6 +353,21 @@ export interface AskStreamDoneEvent {
      */
     memoryInjected?: boolean;
     memoryProposed?: boolean;
+    /**
+     * What EgoZ accepted from this turn's `contextItems`. Same semantics +
+     * shape as `AskResponseData.contextItemsAccepted` — surfaced on the
+     * terminal event so streaming consumers can render "what was shared"
+     * without parsing the final payload separately.
+     *
+     * On the terminal frame rather than mid-stream for the same reason as
+     * `questionSet`: it describes the settled turn, and a consumer would
+     * discard every earlier variant anyway.
+     *
+     * ⚠️ Absent means the request carried no `contextItems` — never that none
+     * were accepted. An empty array is the second thing, and they must not be
+     * collapsed by anything relaying this frame.
+     */
+    contextItemsAccepted?: InitContextItemAccepted[];
 }
 
 export interface AskStreamErrorEvent {