@ego-z/contracts 0.15.10 → 0.15.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.10",
+  "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,7 @@
  */
 
 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';
 
 // ============================================================================
@@ -346,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/stream.d.ts

@@ -13,6 +13,7 @@
 
 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.
@@ -352,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 {