@ego-z/contracts 0.15.5 → 0.15.7

package/README.md

@@ -58,6 +58,30 @@ import type { AskRequestBody, AskResponseData, AskStreamEvent } from '@ego-z/con
 their generated `.d.ts` automatically — end users see the types as if
 they were declared in the SDK itself.
 
+## ⚠️ Do not pin `0.15.5`
+
+`0.15.5` was published with a `dependencies` entry naming **itself**
+(`"@ego-z/contracts": "^0.15.0"`). It is harmless while 0.15.5 is the newest
+0.15.x — npm resolves that range back to the same copy and dedupes it:
+
+```
+`-- @ego-z/contracts@0.15.5
+  `-- @ego-z/contracts@0.15.5 deduped
+```
+
+**It stops being harmless the moment a newer 0.15.x exists.** That range can
+then resolve a *different* version nested underneath 0.15.5, putting two
+copies of the same types in one tree — the classic "these two identical
+interfaces are not assignable" failure, from a cause nobody would think to
+look for.
+
+So: **when the next patch ships, move off 0.15.5 rather than staying on it.**
+Don't pin it, and don't leave a lockfile resolving to it.
+
+The source is already fixed — the package declares no runtime dependencies at
+all — so the next publish for any reason clears it. It was not worth a
+version bump on its own mid-integration.
+
 ## When to bump
 
 - **Adding** an optional field — non-breaking, no version bump required

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
   "types": "./src/index.d.ts",
   "exports": {
@@ -44,8 +44,5 @@
   },
   "devDependencies": {
     "typescript": "^5.0.0"
-  },
-  "dependencies": {
-    "@ego-z/contracts": "^0.15.0"
   }
 }

package/src/ask.d.ts

@@ -6,6 +6,7 @@
  */
 
 import type { Intent, JsonSchemaDefinition, ResponseFormat, TokenUsage } from './envelope';
+import type { InitContextUi } from './draft-conv';
 
 // ============================================================================
 // /ask — request
@@ -158,6 +159,36 @@ export interface AskRequestBody {
      *   4. `Authorization` injected by `authType: 'FORWARD'`
      */
     toolHeaders?: Record<string, string>;
+
+    /**
+     * What the user has on screen RIGHT NOW — sent on every turn, not just
+     * when the conversation started.
+     *
+     * ── Why per-turn ─────────────────────────────────────────────────────
+     *
+     * `POST /conversations/draft` captures an `initContext` once, when the
+     * chat panel opens. That snapshot is frozen for the life of the
+     * conversation, so a window the user opens mid-chat is invisible to the
+     * agent by construction — "do that one as well" has no referent to
+     * resolve, and it reads as the model being obtuse when in fact it was
+     * never told.
+     *
+     * Send the CURRENT snapshot here and EgoZ works out what changed since
+     * the user's previous message. Deixis — "as well", "this one too", "the
+     * other one", "go back to the first" — then resolves from ordering and
+     * recency, with no phrase anyone has to enumerate.
+     *
+     * ── Send the full snapshot, never a delta ────────────────────────────
+     *
+     * Do not compute "what's new" client-side. A client delta needs a
+     * client-held baseline, and that baseline is wrong after a reload, a
+     * retry, or a reconnect. EgoZ holds the previous turn, so it can diff
+     * reliably; the client's job is only to report what it sees.
+     *
+     * Optional and additive: omit it and behaviour is exactly as before,
+     * with the stored `initContext` used for the whole conversation.
+     */
+    ui?: InitContextUi;
 }
 
 /**

package/src/draft-conv.d.ts

@@ -60,7 +60,34 @@ export type InitContextAudience = 'operator' | 'customer';
 
 /** One open window in the caller's UI. */
 export interface InitContextOpenWindow {
-    /** Epoch millis the window was opened. */
+    /**
+     * Epoch millis this window was FIRST SEEN by the client, on the CLIENT'S
+     * clock. Not when it was opened — most window systems have no true open
+     * time, and this is the honest name for what is actually knowable.
+     *
+     * ⚠️ Valid ONLY for ordering windows against each other **within a single
+     * snapshot**, where the values share one clock and one instant.
+     *
+     * It is NOT valid across snapshots and NOT valid against server time:
+     *   - It is a browser clock. Comparing it to a server timestamp compares
+     *     two clocks, so a client a few minutes off gets a silently wrong
+     *     answer that differs per end user.
+     *   - It is memory-only and RESETS ON PAGE RELOAD. After a refresh every
+     *     open window carries the moment of boot, so a "what's new" rule
+     *     built on it doesn't weaken — it inverts, and the window the user
+     *     has been discussing since turn one becomes the newest.
+     *
+     * To detect what changed between turns, diff window IDS instead. That
+     * asks only "was this seen before", which no clock can corrupt.
+     */
+    firstSeenAt?: number;
+
+    /**
+     * @deprecated Use `firstSeenAt`. Same value, honest name — this one
+     * asserts an open time that the client cannot know, and that reading
+     * caused a real design error. Emitted alongside `firstSeenAt` for one
+     * minor; readers should prefer `firstSeenAt` and fall back to this.
+     */
     openedAt?: number;
     /**
      * Human-readable window label, e.g. `"Blue Hoodie"`. Safe to render