@ego-z/contracts 0.14.4 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "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

@@ -0,0 +1,310 @@
+/**
+ * @ego-z/contracts — `POST /egoz/conversations/draft` wire types.
+ *
+ * The GHOSTED CONVERSATION START. When a tenant surface opens a new chat
+ * panel, it calls this before the user has typed anything. EgoZ mints a
+ * conversation id, stores the caller's init context against it as a draft,
+ * and returns quick suggested prompts — so the panel opens with a real id
+ * and something to click, rather than acquiring both mid-stream on the first
+ * message.
+ *
+ * No LLM turn is billed. Nothing is persisted as a user message: the init
+ * context is rendered into the system prompt as context, never as something
+ * the model answers.
+ *
+ * ── Two ids, and only one of them is an identity ─────────────────────────
+ *
+ * `conversationId` is EgoZ-minted and canonical — the only id a follow-up
+ * `/ask` ever carries. `draftKey` is a caller-generated dedupe token for one
+ * chat panel. They are deliberately separate: the thing that needs
+ * uniqueness (a panel's attempt to start a draft) is not the thing that
+ * needs identity (a conversation), and conflating them would change which id
+ * is canonical for every existing caller.
+ *
+ * ── Evolution ────────────────────────────────────────────────────────────
+ *
+ * Additive only. Every `initContext` field is optional, so a caller that
+ * hasn't implemented a field yet degrades one feature rather than failing a
+ * request. Unknown fields are TOLERATED, not rejected — but they are also
+ * not forwarded: the server keeps only what it models, because everything
+ * here is rendered into a system prompt and arbitrary caller JSON reaching
+ * that position is an injection surface, not a convenience. Callers with
+ * something unmodelled to say use `notes`.
+ */
+
+import type { ThreadStatus } from './thread';
+
+// ============================================================================
+// Init context — the snapshot that accompanies a start
+// ============================================================================
+
+/** Resolved colour scheme. Never a preference — see `InitContextUi.theme`. */
+export type InitContextTheme = 'light' | 'dark';
+
+/** Viewport class. Deliberately not "device" — see `InitContextUi.viewport`. */
+export type InitContextViewport = 'mobile' | 'desktop';
+
+/** One open window in the caller's UI. */
+export interface InitContextOpenWindow {
+    /** Epoch millis the window was opened. */
+    openedAt?: number;
+    /**
+     * 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.
+     */
+    title?: string;
+    isFocused?: boolean;
+}
+
+/** One visited tab. `visitedAt` gives suggestion ranking a recency tiebreak. */
+export interface InitContextVisitedTab {
+    /** Epoch millis the tab was last visited. */
+    visitedAt?: number;
+    isCurrent?: boolean;
+}
+
+/**
+ * What the user is looking at.
+ *
+ * The first four fields are structurally identical to the AppNa console's
+ * `UserContext`, so a caller that already models an OS-style window system
+ * passes its context straight through with no mapper. They are declared here
+ * as EgoZ's own type rather than imported: EgoZ serves callers that are not
+ * window systems, and a public contract that mirrors one client's internal
+ * type makes every refactor of that client a breaking change here.
+ *
+ * RANKING USES FOCUS, NOT THE SET. "Has Orders open" is weak signal; "is
+ * looking at a product detail" is strong. `openWindows` is a secondary
+ * signal and `visitedTabs[].visitedAt` a tiebreak.
+ */
+export interface InitContextUi {
+    /** Coarse screen the user is on, e.g. `"ecommerce"`, `"orders"`. */
+    currentRouteId?: string | null;
+    /** Key of the focused window, e.g. `"ecommerce:productDetail:abc"`. */
+    focusedWindowId?: string | null;
+    openWindows?: Record<string, InitContextOpenWindow>;
+    visitedTabs?: Record<string, InitContextVisitedTab>;
+    /**
+     * The RESOLVED colour scheme — never a preference. A caller whose stored
+     * setting is "system" MUST resolve it against `prefers-color-scheme`
+     * before sending: `'system'` is a state EgoZ cannot evaluate and has
+     * nothing useful to say about, and it would be the value for a large
+     * share of users.
+     */
+    theme?: InitContextTheme | null;
+    /**
+     * Viewport class — NOT a device. Callers derive it from a width
+     * breakpoint, so a narrowed desktop browser window reports `'mobile'`.
+     * Named for what it measures on purpose: `device` would invite the agent
+     * to say "since you're on your phone…" to someone who dragged their
+     * window narrow. A real device signal (touch capability, UA) would be a
+     * separate field with a separate source.
+     */
+    viewport?: InitContextViewport | null;
+}
+
+/**
+ * Who the user is.
+ *
+ * `name` is nullable: a phone-only signup genuinely has none, and the
+ * greeting has a no-name path rather than producing "Hello, null".
+ *
+ * ── `roles` is a SET, and it is ADDITIVE-ONLY ────────────────────────────
+ *
+ * A role gates which actions the agent offers, which makes a client-asserted
+ * role a client-asserted permission. It MUST be resolved by whoever
+ * authenticated the user; a gateway fills it from the verified session and
+ * ignores whatever the browser sent. The vocabulary belongs to the caller's
+ * product, so entries are free-form strings.
+ *
+ * It is an ARRAY, not a single value, because the underlying fact is a set
+ * and collapsing a set needs a precedence rule — a precedence rule absent
+ * from the contract is one each implementer invents privately, and an owner
+ * who also takes appointments then never sees the specialist suggestions.
+ *
+ * It may only ever WIDEN what the agent offers — add to the capability
+ * summary, boost ranking — and may never narrow either. The reason is a
+ * property of the source: on a permissions node where present means true
+ * and ABSENT MEANS UNKNOWN, `['Specialist']` does not mean "not an owner",
+ * it means "specialist is true and the rest is unknown". Every inference of
+ * the form *only a specialist, so hide X* is unsound on that data.
+ *
+ * The asymmetry also matters because the failure is invisible: a wrongly
+ * SHOWN suggestion gets reported, a wrongly HIDDEN one never does — the user
+ * just sees a less useful assistant and assumes that's what it is. Hard
+ * filtering belongs to `tenant.features`, which genuinely can say no.
+ *
+ * There is no `id` field: the end user is already identified at request
+ * level by `externalUserId`. One id, one place.
+ */
+export interface InitContextUser {
+    name?: string | null;
+    roles?: string[];
+}
+
+/**
+ * Language.
+ *
+ * TWO DIFFERENT FACTS ABOUT TWO DIFFERENT SUBJECTS — the distinction is
+ * load-bearing and was got wrong once already:
+ *
+ * - `selected` is **which language this person reads**. It is the only input
+ *   to which language EgoZ replies in. The response echoes the RESOLVED
+ *   value, so the caller and EgoZ cannot silently disagree about it.
+ * - `supported` is **which languages the tenant's CONTENT exists in** — a
+ *   catalogue of the store's translations, not a list of languages the user
+ *   understands. It is NEVER consulted when resolving the reply language:
+ *   doing so gives a French-reading admin at an Arabic-only store Arabic
+ *   chips, which is the resolver faithfully answering the wrong question.
+ *
+ * `supported` is still worth sending — it belongs in the prompt, where it
+ * makes "translate this product into Hebrew" a sensible suggestion for one
+ * tenant and a dead end for another.
+ */
+export interface InitContextLocale {
+    /** The language the USER reads, e.g. `"ar"`. Drives the reply language. */
+    selected?: string | null;
+    /**
+     * The languages the TENANT'S CONTENT exists in, e.g. `["en","ar","he"]`.
+     * Context for the agent; never used to resolve the reply language.
+     */
+    supported?: string[];
+}
+
+/**
+ * The END TENANT this conversation belongs to.
+ *
+ * NOT necessarily the EgoZ tenant. On a gateway integration one EgoZ project
+ * fronts many of the gateway's tenants, so EgoZ's own tenant record
+ * describes the DEPLOYMENT and knows nothing about tenant "ABC". Which side
+ * is authoritative is declared once per EgoZ tenant (`tenantScope`), not
+ * inferred per request.
+ *
+ * `features` is the highest-value field here for suggestion quality: a
+ * per-tenant flag set EgoZ has no way to see. Without it the ranker either
+ * offers an action the tenant has switched off, or falls back to generic
+ * chips — the exact failure the ranking exists to avoid.
+ */
+export interface InitContextTenant {
+    name?: string | null;
+    description?: string | null;
+    category?: string | null;
+    /** Enabled-feature flags, e.g. `{ products: true, booking: false }`. */
+    features?: Record<string, boolean>;
+}
+
+/**
+ * The full init context. Every field optional — see the file header on
+ * additive evolution.
+ */
+export interface InitContext {
+    user?: InitContextUser;
+    locale?: InitContextLocale;
+    ui?: InitContextUi;
+    tenant?: InitContextTenant;
+    /** Anything the contract doesn't model yet. Rendered as untrusted data. */
+    notes?: string | null;
+    /**
+     * Epoch millis the caller took the snapshot. Optional; EgoZ stamps it on
+     * arrival when absent.
+     *
+     * It governs how long the `ui` half may still be rendered into a prompt,
+     * which is a SHORTER clock than the draft's own lifetime. A draft resumed
+     * after lunch is still the user's conversation, but "you have the
+     * Products window open" is by then a confident claim about a screen they
+     * closed — so past the snapshot window the UI half is dropped while
+     * `user` / `locale` / `tenant` still render.
+     */
+    capturedAt?: number;
+}
+
+// ============================================================================
+// Request / response
+// ============================================================================
+
+/** Body of `POST /egoz/conversations/draft`. */
+export interface StartDraftRequestBody {
+    /**
+     * Idempotency token for ONE chat panel — opaque, caller-generated, stable
+     * across remounts of that panel and fresh only for a genuinely new one.
+     * A good source is the panel's own window key plus a per-open nonce.
+     *
+     * Repeating a call with the same key refreshes that draft's init context
+     * and returns the SAME `conversationId` rather than minting another row.
+     * Callers SHOULD send one: a double-mounting panel that sends none leaks
+     * an orphan draft per mount.
+     *
+     * It is NOT a thread id and can never be used as one — its uniqueness
+     * index covers drafts only, and promotion drops it.
+     */
+    draftKey?: string;
+    /**
+     * Consumer-supplied conversation id, for callers that already mint their
+     * own (Phase 6). Unrelated to idempotency — that is `draftKey`'s job.
+     */
+    externalThreadId?: string;
+    /** The end user this conversation is for, as the caller identifies them. */
+    externalUserId?: string;
+    initContext?: InitContext;
+}
+
+/**
+ * Where a suggested prompt came from. Surfaced because the two have
+ * different quality and latency characteristics, and a caller measuring chip
+ * performance needs to tell an instant catalog hit from a model-generated
+ * fallback rather than averaging them together.
+ */
+export type SuggestedPromptSource = 'template' | 'llm';
+
+/** One suggested prompt chip, ready to render. */
+export interface SuggestedPromptWire {
+    /** Stable catalog id — for the caller's own analytics, not for display. */
+    id: string;
+    /** The prompt text, already in the resolved locale. */
+    text: string;
+    source: SuggestedPromptSource;
+}
+
+/** `data` payload of a successful `POST /egoz/conversations/draft`. */
+export interface StartDraftResponseData {
+    /**
+     * The canonical conversation id. This is what a follow-up `/ask` carries
+     * as `threadId`. A turn carrying it MUST come back with the same id —
+     * EgoZ never mints a replacement for a supplied id, and a lapsed draft
+     * fails with `DraftExpired` rather than quietly becoming a new
+     * conversation.
+     */
+    conversationId: string;
+    /** Always `'draft'` on a successful start; present so callers can assert. */
+    status: ThreadStatus;
+    /**
+     * ISO 8601. When the conversation id stops resolving — the row TTL.
+     *
+     * One of TWO CLOCKS, deliberately not collapsed into one number: this
+     * one governs how long the caller may still resume the conversation.
+     */
+    expiresAt: string;
+    /**
+     * ISO 8601, and much sooner than `expiresAt`. When the `ui` half of the
+     * init context stops being rendered into the prompt.
+     *
+     * The second clock. A draft resumed after lunch is still the user's
+     * conversation, but "you have the Products window open" is by then a
+     * confident claim about a screen they closed. Past this instant the UI
+     * half is dropped while `user` / `locale` / `tenant` keep rendering —
+     * those don't go stale.
+     */
+    contextExpiresAt: string;
+    /**
+     * Quick prompts for the panel to render, in `locale`. May be empty when
+     * nothing in the catalog fits and the fallback produced nothing — an
+     * empty list is a normal outcome, not an error.
+     */
+    suggestedPrompts: SuggestedPromptWire[];
+    /**
+     * The RESOLVED language — what EgoZ actually used — not the requested
+     * one. Render the chips in this.
+     */
+    locale: string;
+}

package/src/index.d.ts

@@ -53,8 +53,16 @@
  *   - `thread.d.ts`   — `ThreadWire`, `MessageWire`,
  *                        `ThreadWithStatsWire`, `ThreadWithMessagesWire`,
  *                        `ToolCallWire`, list / get response data,
- *                        vocabularies (`MessageRole`,
+ *                        vocabularies (`MessageRole`, `ThreadStatus`,
  *                        `MessageFailureReason`).
+ *   - `draft-conv.d.ts` — the ghosted conversation start:
+ *                        `InitContext` (+ `InitContextUser`,
+ *                        `InitContextLocale`, `InitContextUi`,
+ *                        `InitContextTenant`, `InitContextOpenWindow`,
+ *                        `InitContextVisitedTab`),
+ *                        `StartDraftRequestBody`, `StartDraftResponseData`,
+ *                        `SuggestedPromptWire`, vocabularies
+ *                        (`InitContextTheme`, `InitContextViewport`).
  *   - `personality.d.ts` — Both surfaces share this file. User-level:
  *                        `PersonalityProfileWire`, `PresetDefinitionWire`,
  *                        create / update bodies, `ActivePersonalityWire`.
@@ -89,6 +97,7 @@ export * from './mcp-token';
 export * from './mcp-connection';
 export * from './tenant';
 export * from './thread';
+export * from './draft-conv';
 export * from './personality';
 export * from './user-memory';
 export * from './search';

package/src/thread.d.ts

@@ -44,13 +44,22 @@ export type MessageFailureReason =
  * Conversation lifecycle state. Mirrors the CHECK constraint on
  * `egoz_threads.status` (migration 054).
  *
- * - `'draft'`  — minted by the ghosted start (`POST /egoz/conversations/draft`)
- *                before the user has typed anything. Carries the caller's
- *                init context, holds a conversation id the caller can keep,
- *                and is swept after the draft TTL if it never promotes.
- * - `'active'` — a real conversation. Every thread created by `/ask` is born
- *                active, and a draft becomes active on its first user
- *                message. An active thread is never swept.
+ * - `'draft'`   — minted by the ghosted start
+ *                 (`POST /egoz/conversations/draft`) before the user has
+ *                 typed anything. Carries the caller's init context, holds a
+ *                 conversation id the caller can keep, and lapses after the
+ *                 draft TTL if it never promotes.
+ * - `'active'`  — a real conversation. Every thread created by `/ask` is born
+ *                 active, and a draft becomes active on its first user
+ *                 message. An active thread is never swept.
+ * - `'expired'` — a lapsed draft. A TOMBSTONE, not a conversation: it cannot
+ *                 be resumed and holds no messages. It exists so that a
+ *                 caller returning with a held draft id gets a distinct
+ *                 `DraftExpired` (410) rather than a `NotFound` it cannot
+ *                 tell apart from a garbage id — the contract requires a
+ *                 lapsed draft to fail loudly and specifically, never to
+ *                 silently become a new conversation. Hard-deleted after a
+ *                 grace window.
  *
  * ORTHOGONAL TO `isActive`, which means *archived* and predates this field.
  * A draft is not an archived thread and an archived thread was never a draft;
@@ -58,7 +67,7 @@ export type MessageFailureReason =
  * draft sweeper's delete predicate would then also match archived user
  * conversations.
  */
-export type ThreadStatus = 'draft' | 'active';
+export type ThreadStatus = 'draft' | 'active' | 'expired';
 
 // ============================================================================
 // Supporting shapes