@ego-z/contracts 0.15.7 → 0.15.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.7",
+  "version": "0.15.9",
   "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 { InitContextUi } from './draft-conv';
+import type { InitContextItem, InitContextUi } from './draft-conv';
 
 // ============================================================================
 // /ask — request
@@ -189,6 +189,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[];
 }
 
 /**

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 {
     /**
@@ -93,8 +135,43 @@ export interface InitContextOpenWindow {
      * Human-readable window label, e.g. `"Blue Hoodie"`. Safe to render
      * verbatim — unlike the window KEY, which embeds entity ids and is
      * rendered only for the focused window.
+     *
+     * OMIT IT when `withheld` is true — see below.
      */
     title?: string;
+
+    /**
+     * The user removed this window from the chat's context chips: it is on
+     * their screen, but they have asked that it NOT be sent to the agent.
+     *
+     * ── Send the id and the flag. Never the title. ───────────────────────
+     *
+     * The agent needs the ID so it can stay quiet: EgoZ derives "what changed
+     * since your last message" by diffing window ids, and a window that
+     * simply vanishes from the payload is indistinguishable from one the user
+     * CLOSED — so the agent would tell them a window is gone while they are
+     * looking at it.
+     *
+     * The TITLE is the part the user was removing. It is the field that
+     * carries `"Acme Corp — Overdue Invoice #4471"` into a prompt and into
+     * storage. Send it anyway and the control is theatre: the gesture would
+     * change nothing about what leaves the browser. Ids are structural
+     * (`ecommerce:productDetail:prod-4471`) and leak a record id, not a
+     * person's name.
+     *
+     * ── What it does and does not do ─────────────────────────────────────
+     *
+     * A withheld window is not rendered anywhere: not in the open-window
+     * list, not as the focused window, not in the change summary, and it
+     * never anchors a greeting.
+     *
+     * It stops FUTURE transmission only. A title sent on an earlier turn is
+     * already stored, and anything the agent has already SAID about that
+     * window remains in the transcript. Withdrawing a window does not
+     * withdraw the conversation about it — so describe this to users as
+     * "not shared from now on", never as though it were erased.
+     */
+    withheld?: boolean;
     isFocused?: boolean;
 }