@ego-z/contracts 0.15.0 → 0.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.0",
+  "version": "0.15.3",
   "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/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;
 }
 
 /**
@@ -247,6 +295,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;