@ego-z/contracts 0.15.0 → 0.15.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.0",
+  "version": "0.15.5",
   "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,5 +44,8 @@
   },
   "devDependencies": {
     "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@ego-z/contracts": "^0.15.0"
   }
 }

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

@@ -44,6 +44,20 @@ export type InitContextTheme = 'light' | 'dark';
 /** Viewport class. Deliberately not "device" — see `InitContextUi.viewport`. */
 export type InitContextViewport = 'mobile' | 'desktop';
 
+/**
+ * Which population a user belongs to — see `InitContextUser.audience`.
+ *
+ * - `'operator'` — runs the tenant's product. Admins, owners, staff,
+ *   specialists, back-office users: whatever the deployment calls them.
+ * - `'customer'` — uses it. End users, buyers, patients, guests.
+ *
+ * Two values, not a list of job titles: the distinction that changes how an
+ * agent should speak is "do you run this, or do you use it". Finer-grained
+ * distinctions belong in `roles`, which is free-form precisely because that
+ * vocabulary is the deployment's, not EgoZ's.
+ */
+export type InitContextAudience = 'operator' | 'customer';
+
 /** One open window in the caller's UI. */
 export interface InitContextOpenWindow {
     /** Epoch millis the window was opened. */
@@ -141,6 +155,40 @@ export interface InitContextUi {
 export interface InitContextUser {
     name?: string | null;
     roles?: string[];
+    /**
+     * WHICH POPULATION this person belongs to — the people who RUN the
+     * tenant's product, or the people who USE it.
+     *
+     * Every EgoZ deployment serves one or both, and the agent should not
+     * speak to them the same way: an operator wants "I can help you manage
+     * your catalogue", a customer wants "I can help you track your order".
+     * Offering the first to the second is wrong in the opening sentence, and
+     * it reads as the product not knowing who it is talking to.
+     *
+     * Deliberately NOT a boolean, and deliberately not named after any one
+     * product's org chart. A boolean forces every deployment to express its
+     * populations as "staff / not-staff", which is one integration's
+     * vocabulary; and a boolean has no way to say "I did not resolve this",
+     * so absent and false become indistinguishable at exactly the moment the
+     * difference matters.
+     *
+     * ── The one signal allowed to NARROW ─────────────────────────────────
+     *
+     * `roles` may only widen, because its source generally cannot tell
+     * "false" from "not recorded". This field is different: it is the
+     * caller's own answer to a question they authoritatively know, so it may
+     * gate — it is the only field here that can.
+     *
+     * ── ABSENT MEANS `'customer'`. Fail closed. ──────────────────────────
+     *
+     * Read a missing value as the LESS privileged population, never as
+     * "unknown, assume operator". Callers that serve both populations often
+     * cannot distinguish them on every path, and the failure directions are
+     * not symmetric: greeting an operator as a customer is a smaller,
+     * self-correcting mistake than offering a customer administrative
+     * actions they will then fail to perform.
+     */
+    audience?: InitContextAudience;
 }
 
 /**
@@ -194,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.
@@ -203,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;
     /**
@@ -247,6 +344,21 @@ export interface StartDraftRequestBody {
     /** The end user this conversation is for, as the caller identifies them. */
     externalUserId?: string;
     initContext?: InitContext;
+    /**
+     * The END TENANT this conversation belongs to, in the caller's own id
+     * space — required on a `gateway` integration, meaningless on a
+     * dedicated one.
+     *
+     * ON THE WIRE, not derived from request metadata: it is a scoping key,
+     * and a scoping key inferred from a caller-specific metadata field would
+     * make EgoZ's privacy boundary depend on one integration's vocabulary.
+     * The next gateway would either have to adopt that field name or earn a
+     * second branch.
+     *
+     * Without it, `(tenantId, externalUserId)` spans every one of the
+     * gateway's tenants the user belongs to — see `TenantScope`.
+     */
+    externalTenantId?: string;
 }
 
 /**

package/src/index.d.ts

@@ -62,7 +62,8 @@
  *                        `InitContextVisitedTab`),
  *                        `StartDraftRequestBody`, `StartDraftResponseData`,
  *                        `SuggestedPromptWire`, vocabularies
- *                        (`InitContextTheme`, `InitContextViewport`).
+ *                        (`InitContextTheme`, `InitContextViewport`,
+ *                        `InitContextAudience`).
  *   - `personality.d.ts` — Both surfaces share this file. User-level:
  *                        `PersonalityProfileWire`, `PresetDefinitionWire`,
  *                        create / update bodies, `ActivePersonalityWire`.

package/src/stream.d.ts

@@ -17,11 +17,14 @@ import type { Intent, TokenUsage } from './envelope';
  * Discriminated union of every event the streaming `/ask` endpoint emits.
  *
  * Notes on subset behaviour:
+ *   - `start` is always the FIRST frame, in every mode including
+ *     `'minimal'`. It carries the conversation id.
  *   - `stream: 'minimal'` requests omit `rag.*` and `tool.*` events.
  *   - `done` is always the terminal success frame.
  *   - `error` may appear at any point and is also terminal.
  */
 export type AskStreamEvent =
+    | AskStreamStartEvent
     | AskStreamIntentEvent
     | AskStreamRagSearchingEvent
     | AskStreamRagRetrievedEvent
@@ -34,6 +37,51 @@ export type AskStreamEvent =
     | AskStreamDoneEvent
     | AskStreamErrorEvent;
 
+/**
+ * The opening frame — emitted before any work begins, on every stream.
+ *
+ * ── Why the id cannot wait for `done` ────────────────────────────────────
+ *
+ * The conversation id is known the moment the thread is resolved, which is
+ * before the first token. Withholding it until the terminal frame forces
+ * every downstream consumer to either buffer the whole turn or guess, and
+ * guessing is what silently broke consumers that select a thread id on each
+ * event: they read `undefined` on every frame until the last one, so the
+ * selection simply never happened and nothing errored.
+ *
+ * A consumer that renders a transcript needs to know WHICH conversation it
+ * is rendering while the tokens are arriving, not after.
+ *
+ * ── Why a distinct event rather than a field on every frame ──────────────
+ *
+ * Repeating the id on `delta` would put it on the highest-frequency frame in
+ * the protocol for a value that never changes within a stream. One frame at
+ * the start says it once, and says it at the only moment a consumer needs to
+ * act on it: before anything is rendered.
+ *
+ * ADDITIVE. Consumers that don't know this variant ignore it — the same way
+ * they already ignore any event type they don't handle — and keep reading
+ * the id off `done` as before.
+ */
+export interface AskStreamStartEvent {
+    type: 'start';
+    /**
+     * The canonical conversation id, EgoZ-minted. Identical to the
+     * `threadId` that will arrive on `done`; a turn NEVER changes id
+     * mid-stream, so a consumer can commit to this value immediately.
+     */
+    threadId: string;
+    /** Echo of the supplied `externalThreadId`, when one was sent. */
+    externalThreadId?: string;
+    /**
+     * Whether this turn PROMOTED a ghosted draft — i.e. it is the first real
+     * message in a conversation that already had an id. Lets a consumer tell
+     * "this id is new to me" from "this id was pre-seeded at chat-open", which
+     * are different UI states even though both are a first turn.
+     */
+    promotedFromDraft?: boolean;
+}
+
 export interface AskStreamIntentEvent {
     type: 'intent';
     intent: Intent;

package/src/tenant.d.ts

@@ -123,6 +123,27 @@ export type TenantIndustry =
  * not a goal — net change would be breaking, with zero behavioural
  * value.
  */
+/**
+ * Whether an EgoZ project serves ONE customer or fronts MANY of a caller's
+ * own tenants. Mirrors the `egoz_tenants.tenant_scope` CHECK (migration 055).
+ *
+ * This is a fact about the INTEGRATION, declared once, not something inferred
+ * per request — inferring it from a caller-specific field would bake one
+ * integration's vocabulary into EgoZ's core scoping logic.
+ *
+ * - `'dedicated'` (default) — one project, one customer. `(tenantId,
+ *   externalUserId)` is a privacy boundary, which is what every per-end-user
+ *   feature assumes.
+ * - `'gateway'` — one project fronts many of the caller's tenants, and the
+ *   real tenant travels inside each request. **`(tenantId, externalUserId)`
+ *   is NOT a privacy boundary here**: the caller's end-user id is the same
+ *   value across every one of their tenants that person belongs to, so one
+ *   identity spans all of them. Per-end-user memory retrieval is gated for
+ *   these projects until per-tenant scoping lands, because that data is read
+ *   into the system prompt on every turn.
+ */
+export type TenantScope = 'dedicated' | 'gateway';
+
 export interface TenantWire {
     id: string;
     name: string;
@@ -152,6 +173,16 @@ export interface TenantWire {
     status: TenantStatus;
     /** Billing plan (migrations 023/035). Drives usage quotas. Default 'id_ego'. */
     plan: TenantPlan;
+    /**
+     * Whether this project serves one customer or fronts many of a caller's
+     * own tenants. See `TenantScope`. Default `'dedicated'` (migration 055).
+     *
+     * OPTIONAL on the wire deliberately: the backend has enforced it since
+     * 055, but it rides here additively so an older deployment in front of a
+     * newer consumer doesn't strand anyone. Read it as `'dedicated'` when
+     * absent — that is what a project that has never declared itself is.
+     */
+    tenant_scope?: TenantScope;
 
     // Time-boxed debug mode (migration 037). Populated on the LIST response
     // (joined from tenant_configs); omitted where the query does not join it.
@@ -207,6 +238,19 @@ export interface TenantUpdateBody {
     name?: string;
     description?: string;
     is_active?: boolean;
+    /**
+     * Whether this project serves one customer or fronts many of a caller's
+     * own tenants. See `TenantScope` (migration 055).
+     *
+     * ⚠️ ONE DIRECTION IS DESTRUCTIVE, and it is not the obvious one.
+     * `dedicated → gateway` is safe: it turns a privacy boundary ON.
+     * `gateway → dedicated` **re-enables per-end-user memory retrieval over
+     * rows that are still cross-tenant** — it does not undo anything, it
+     * re-opens the exposure the gateway setting was closing. A surface
+     * offering this field must confirm that direction and name what it
+     * re-enables; the reverse needs no confirmation.
+     */
+    tenant_scope?: TenantScope;
 
     industry?: TenantIndustry;
     data_residency_region?: DataResidencyRegion;

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;