@ego-z/contracts 0.15.3 → 0.15.6

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.3",
+  "version": "0.15.6",
   "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

@@ -25,6 +25,21 @@ import type { Intent, JsonSchemaDefinition, ResponseFormat, TokenUsage } from '.
  *   These are intentionally NOT body fields — they live where HTTP puts them.
  */
 export interface AskRequestBody {
+    /**
+     * The CALLER'S own tenant for this turn, in their id space — required on
+     * a `gateway` integration (see `TenantScope`), meaningless otherwise.
+     *
+     * Scopes every per-user read on the turn and guards the resume: a
+     * conversation belonging to a different one of the caller's tenants
+     * fails as `ThreadMismatch` (409) rather than `NotFound`, because a
+     * gateway that hears "not found" for a real conversation bootstraps its
+     * own record under the wrong tenant and forks the transcript.
+     *
+     * On the wire rather than derived from `metadata`: a scoping key
+     * inferred from one caller's metadata field name would make EgoZ's
+     * privacy boundary depend on that caller's vocabulary.
+     */
+    externalTenantId?: string;
     /** End-user's message for this turn. Required, non-empty. */
     message: string;
 

package/src/draft-conv.d.ts

@@ -242,6 +242,53 @@ export interface InitContextTenant {
     features?: Record<string, boolean>;
 }
 
+/**
+ * A short recap of the user's PREVIOUS conversation, so the agent can open
+ * with continuity instead of as though it has never met them.
+ *
+ * ── Supplied by the caller, deliberately ─────────────────────────────────
+ *
+ * EgoZ stores conversations too, so it looks like EgoZ should resolve this
+ * itself — but on a gateway integration EgoZ's own copy is keyed by
+ * `(tenantId, externalUserId)`, which spans every one of the caller's
+ * tenants a person belongs to. Sourcing it there would recap store B's
+ * conversation into store A's prompt. The caller's store is per-tenant by
+ * construction, so it can answer the question safely, and a conversation the
+ * user deleted stops being quotable immediately with no propagation chain.
+ *
+ * ── Keep it SHORT ────────────────────────────────────────────────────────
+ *
+ * `lastMessage` is a truncated snippet, not a transcript. It rides in the
+ * system prompt on every turn of the new conversation, so a long one buys
+ * a little continuity at the cost of crowding out the context that makes
+ * the agent useful. Cap it at the sender.
+ *
+ * ── Recency matters more than it looks ───────────────────────────────────
+ *
+ * "Last time we spoke…" about a conversation from three months ago reads as
+ * the assistant having lost the plot, not as continuity. Callers should omit
+ * this entirely past a sensible window rather than send something stale.
+ */
+export interface InitContextLastConversation {
+    /** The previous conversation's title, if it has one. */
+    title?: string | null;
+    /** ISO 8601 — when it was last active. Lets the agent judge recency. */
+    updatedAt?: string | null;
+    /**
+     * A TRUNCATED snippet of the last message in it. Not a transcript —
+     * see the type docs on why the cap belongs at the sender.
+     */
+    lastMessage?: string | null;
+    /**
+     * Whether the agent replied to that last message.
+     *
+     * `false` is the interesting value: the user said something and never
+     * got an answer, which is worth opening on. Distinguishing it from
+     * "unknown" is why this is optional rather than defaulting to `true`.
+     */
+    answered?: boolean;
+}
+
 /**
  * The full init context. Every field optional — see the file header on
  * additive evolution.
@@ -251,6 +298,8 @@ export interface InitContext {
     locale?: InitContextLocale;
     ui?: InitContextUi;
     tenant?: InitContextTenant;
+    /** A short recap of the user's previous conversation, if there is one. */
+    lastConversation?: InitContextLastConversation;
     /** Anything the contract doesn't model yet. Rendered as untrusted data. */
     notes?: string | null;
     /**

package/src/thread.d.ts

@@ -115,6 +115,18 @@ export interface ThreadWire {
      * migration 017.
      */
     externalThreadId: string | null;
+    /**
+     * The CALLER'S own tenant this conversation belongs to, in their id
+     * space (migration 056). Populated on `gateway` projects — where one
+     * EgoZ project fronts many of the caller's tenants — and `null`
+     * otherwise, including for every row predating the column.
+     *
+     * It supplies the third part of the per-user scoping key. Without it,
+     * `(tenantId, externalUserId)` spans every one of the caller's tenants
+     * a person belongs to, because their end-user id is identical across
+     * all of them. See `TenantScope`.
+     */
+    externalTenantId?: string | null;
     title: string | null;
     metadata: Record<string, unknown>;
     isActive: boolean;