@egox/contracts 0.5.0

package/src/tenant.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @egox/contracts — `/egox/tenants/*` wire types (project CRUD).
+ *
+ * `Tenant` is what the Console calls "Project" — same row, two names.
+ * The wire shape preserves `snake_case` field names because that's the
+ * actual JSON the backend has always emitted and the console has always
+ * consumed. Renaming to camelCase here would be a breaking wire change
+ * (every API caller would need to update) and is deliberately out of
+ * scope for the additive Phase 9 sweep. If/when we ever do that
+ * migration, this is the file the major-version bump touches.
+ *
+ * Drift cleaned up:
+ *   - Backend `Tenant` used `Date` for `created_at` / `updated_at` /
+ *     `attestation_signed_at`; wire and console already used ISO
+ *     strings. Backend `formatTenant` now emits ISO via the same
+ *     pattern as Tools and RAG.
+ */
+
+// ============================================================================
+// Locked vocabularies (mirror DB CHECK constraints)
+// ============================================================================
+
+/**
+ * Compliance tier (mirrors `egox_tenants.compliance_tier` CHECK
+ * constraint, migration 010). Phase 1 services `'standard'` only;
+ * the rest are forward-compat for Phase 2.
+ */
+export type ComplianceTier =
+    | 'standard'
+    | 'pending_review'
+    | 'gdpr'
+    | 'hipaa'
+    | 'enterprise'
+    | 'pending_upgrade';
+
+/**
+ * Data residency region (mirrors `egox_tenants.data_residency_region`
+ * CHECK constraint, migration 010). Phase 1 deploys only to
+ * `'eu-west'`; the rest are forward-compat.
+ */
+export type DataResidencyRegion =
+    | 'us-east'
+    | 'us-west'
+    | 'eu-west'
+    | 'eu-central'
+    | 'ap-south'
+    | 'ap-east';
+
+/**
+ * Operational tenant status (mirrors `egox_tenants.status` CHECK
+ * constraint). The legacy `is_active` boolean still exists in
+ * Phase 1 and is NOT auto-synced with `status` — both fields are
+ * independent until Phase 1.5 deprecates `is_active`.
+ */
+export type TenantStatus =
+    | 'active'
+    | 'pending_review'
+    | 'flagged'
+    | 'suspended'
+    | 'terminated';
+
+/**
+ * Billing plan (Phase 1.5, two-plan model — migration 035). Drives usage
+ * quotas (e.g. monthly /ask limit).
+ *
+ *   - `id_ego`   — "Id Ego": free, pay-as-you-go via BYOK, capped limits.
+ *                  Default for self-service signup.
+ *   - `superego` — "Superego": $20/mo, higher (but still capped) limits.
+ */
+export type TenantPlan = 'id_ego' | 'superego';
+
+/**
+ * Industry classification driving the signup gate (Phase 1.5+).
+ * The regulated entries (`'healthcare'`, `'finance'`, `'insurance'`,
+ * `'government'`, `'legal'`) auto-route new tenants to
+ * `status: 'pending_review'`.
+ */
+export type TenantIndustry =
+    | 'saas'
+    | 'ecommerce'
+    | 'marketing'
+    | 'education'
+    | 'media'
+    | 'travel'
+    | 'real_estate'
+    | 'productivity'
+    | 'other'
+    | 'healthcare'
+    | 'finance'
+    | 'insurance'
+    | 'government'
+    | 'legal';
+
+// ============================================================================
+// TenantWire — the canonical row shape (snake_case on the wire)
+// ============================================================================
+
+/**
+ * Wire-format tenant row. Returned by every `/egox/tenants/*` response.
+ *
+ * **Field naming.** This is the only wire shape in the contracts
+ * package that uses `snake_case`. It's preserved verbatim from the
+ * legacy backend → JSON path because the Console already consumes
+ * `snake_case` here too. Treat the inconsistency as fixed-by-history,
+ * not a goal — net change would be breaking, with zero behavioural
+ * value.
+ */
+export interface TenantWire {
+    id: string;
+    name: string;
+    /** URL-safe slug, unique per parent (when `parent_tenant_id` is set). */
+    slug: string;
+    description?: string;
+    is_active: boolean;
+    /** ISO 8601 timestamp. */
+    created_at: string;
+    /** ISO 8601 timestamp. */
+    updated_at: string;
+
+    // Phase 1 compliance posture (migration 010) ----------------------
+    compliance_tier: ComplianceTier;
+    data_residency_region: DataResidencyRegion;
+    /**
+     * UUID of the parent tenant when this row is a sub-project. `null`
+     * for top-level tenants. Sub-projects share their parent's
+     * `compliance_tier` for billing purposes (enforced at the service
+     * layer, not the DB).
+     */
+    parent_tenant_id: string | null;
+    industry: TenantIndustry | null;
+    /** ISO 8601 timestamp. `null` until the operator signs an attestation. */
+    attestation_signed_at: string | null;
+    attestation_version: string | null;
+    status: TenantStatus;
+    /** Billing plan (migrations 023/035). Drives usage quotas. Default 'id_ego'. */
+    plan: TenantPlan;
+}
+
+// ============================================================================
+// Request bodies (what the client SENDS)
+// ============================================================================
+
+/**
+ * Wire body of `POST /egox/tenants`.
+ *
+ * Notable absences:
+ *   - `compliance_tier`, `status`     — server-derived from `industry`
+ *                                       at signup (Phase 1C / Strategy A).
+ *                                       Non-regulated industry →
+ *                                       `'standard'` + `'active'`;
+ *                                       regulated industry (healthcare,
+ *                                       finance, insurance, government,
+ *                                       legal) → `'pending_review'` on
+ *                                       both. Manual tier moves stay an
+ *                                       admin operation via
+ *                                       `TenantUpdateBody`.
+ *   - `is_active`, timestamps         — server-managed.
+ */
+export interface TenantCreateBody {
+    name: string;
+    slug?: string;
+    description?: string;
+
+    industry?: TenantIndustry;
+    data_residency_region?: DataResidencyRegion;
+    parent_tenant_id?: string | null;
+    /** ISO 8601 timestamp string the operator submits at signup. */
+    attestation_signed_at?: string;
+    attestation_version?: string;
+}
+
+/**
+ * Wire body of `PUT /egox/tenants/:tenantId`. Every field is optional —
+ * the backend applies `COALESCE`-style partial updates. `tenantId` is
+ * the URL param, not the body.
+ *
+ * `compliance_tier` and `status` are admin operations; Phase 1 has no
+ * role gating on these — Phase 1.5 will introduce admin-only
+ * enforcement.
+ */
+export interface TenantUpdateBody {
+    name?: string;
+    description?: string;
+    is_active?: boolean;
+
+    industry?: TenantIndustry;
+    data_residency_region?: DataResidencyRegion;
+    parent_tenant_id?: string | null;
+    compliance_tier?: ComplianceTier;
+    status?: TenantStatus;
+    attestation_signed_at?: string;
+    attestation_version?: string;
+}
+
+// ============================================================================
+// Response data shapes (carried inside `EgoxApiResponse.data`)
+// ============================================================================
+
+export interface TenantListResponseData {
+    tenants: TenantWire[];
+}
+
+export interface TenantGetResponseData {
+    tenant: TenantWire;
+}
+
+/**
+ * Returned by `POST /egox/tenants`. Wrapping the row in `tenant`
+ * (rather than returning it raw) matches the rest of the create
+ * surfaces and keeps room for additive metadata (creation source,
+ * downstream side effects, …) without a major version bump.
+ */
+export interface TenantCreatedResponseData {
+    tenant: TenantWire;
+}

package/src/thread.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @egox/contracts — `/egox/threads/*` and
+ * `/egox/tenants/:tenantId/threads/*` wire types.
+ *
+ * The conversation memory surface. `Thread` rows are produced by every
+ * `/ask` turn (via `ThreadService.getOrCreateThread`) and read back
+ * via the admin threads list / detail routes.
+ *
+ * Phase 6's `externalThreadId` already lives in `AskRequestBody` /
+ * `AskResponseData` / `AskStreamDoneEvent` (in `ask.d.ts` /
+ * `stream.d.ts`). This file lifts the FULL `Thread` and `Message`
+ * row shapes — what the threads-admin endpoints return — into the
+ * contracts package so the console mirror can't drift.
+ *
+ * Drift cleaned up:
+ *   - Backend `Thread` and `Message` used `Date` for `createdAt` /
+ *     `updatedAt`; wire and console already used ISO strings.
+ *     `formatThread` and `formatMessage` now emit ISO to match.
+ */
+
+import type { Intent } from './envelope';
+
+// ============================================================================
+// Locked vocabularies
+// ============================================================================
+
+/** Role of a message in the conversation turn. */
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+/**
+ * Why a turn was stamped with `failedRecovery: true` by the
+ * orchestrator. Mirrors the CHECK constraint on
+ * `egox_messages.failure_reason` (migration 014, Phase 5 / Layer 5).
+ * Adding a new entry requires a migration + orchestrator change in
+ * lockstep — the audit field exists to be queryable, not free-form.
+ */
+export type MessageFailureReason =
+    | 'tool_retry_storm'
+    | 'iteration_cap'
+    | 'max_calls_per_turn'
+    | 'unrecoverable_error';
+
+// ============================================================================
+// Supporting shapes
+// ============================================================================
+
+/**
+ * Tool-call request emitted by an `assistant` message. Shape matches
+ * the OpenAI Chat Completions tool-call envelope verbatim — that's
+ * what the orchestrator persists. `arguments` is a JSON string the
+ * caller must `JSON.parse` if they want the structured value;
+ * EgoX doesn't decode it on the wire because it's already
+ * round-tripped through the LLM as text.
+ */
+export interface ToolCallWire {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+
+// ============================================================================
+// ThreadWire — the canonical row shape
+// ============================================================================
+
+/**
+ * Wire-format thread row. Returned by every threads-admin response and
+ * embedded in `ThreadWithMessagesWire`.
+ *
+ * `externalThreadId` is populated when the caller supplied one on the
+ * `/ask` that minted the row (Phase 6); `null` for legacy threads and
+ * for any caller that uses only the EgoX UUID path.
+ */
+export interface ThreadWire {
+    id: string;
+    tenantId: string;
+    externalUserId: string | null;
+    /**
+     * Consumer-supplied conversation identifier (Phase 6). `null` for
+     * threads created before the column existed and for any caller
+     * that didn't supply one. Uniqueness is enforced per
+     * `(tenantId, externalThreadId)` among non-NULL rows by the
+     * `idx_egox_threads_tenant_ext` partial unique index — see
+     * migration 017.
+     */
+    externalThreadId: string | null;
+    title: string | null;
+    metadata: Record<string, unknown>;
+    isActive: boolean;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+}
+
+/**
+ * Thread row plus aggregate stats. Returned by the admin threads list
+ * endpoint so the operator-facing table can sort by activity without
+ * an N+1 fetch.
+ */
+export interface ThreadWithStatsWire extends ThreadWire {
+    messageCount: number;
+    totalTokens: number;
+}
+
+// ============================================================================
+// MessageWire — the canonical message-row shape
+// ============================================================================
+
+/**
+ * Wire-format message row. Carries the full per-turn audit trail —
+ * the LLM iteration's prompt/completion token split, the model id,
+ * the intent classification, the RAG context that was injected, and
+ * the Phase 5 failure-recovery flags.
+ *
+ * `toolCalls` is populated only on `role: 'assistant'` rows that
+ * requested a tool. `toolCallId` + `toolName` are populated only on
+ * `role: 'tool'` result rows.
+ */
+export interface MessageWire {
+    id: string;
+    threadId: string;
+    tenantId: string;
+    role: MessageRole;
+    content: string | null;
+    toolCalls: ToolCallWire[] | null;
+    toolCallId: string | null;
+    toolName: string | null;
+    intent: Intent | null;
+    ragContext: Record<string, unknown> | null;
+    promptTokens: number | null;
+    completionTokens: number | null;
+    totalTokens: number | null;
+    model: string | null;
+    /** Echo of `AskRequestBody.metadata` for audit. */
+    metadata: Record<string, unknown> | null;
+    /**
+     * `true` when this row's `content` was deliberately dropped under
+     * no-store (metadata-only) persistence — see
+     * `AskRequestBody.noStore` and the tenant's `persistMessageContent`
+     * setting (#5). Distinguishes an intentional NULL (the conversation
+     * text was never stored) from an incidental empty turn. Always
+     * `false` for tenants that persist content normally.
+     */
+    contentRedacted: boolean;
+    /**
+     * `true` when this turn triggered a Phase 5 tool-retry-storm
+     * backstop (dedup ≥ MAX_DUPLICATE_CALLS_BEFORE_FLAG / per-tool
+     * cap / outer iteration cap) or ended on an unrecoverable error
+     * class. Always `false` for non-assistant rows. Phase 5 /
+     * Layer 5 — drives the Tool Health "bad turns" filter.
+     */
+    failedRecovery: boolean;
+    /**
+     * Dominant cause when `failedRecovery === true`. `null`
+     * otherwise. See `MessageFailureReason` for the locked
+     * vocabulary.
+     */
+    failureReason: MessageFailureReason | null;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+}
+
+/**
+ * Returned by the thread-detail endpoint. The full conversation —
+ * row + every message in chronological order.
+ */
+export interface ThreadWithMessagesWire {
+    thread: ThreadWire;
+    messages: MessageWire[];
+}
+
+// ============================================================================
+// Response data shapes (carried inside `EgoxApiResponse.data`)
+// ============================================================================
+
+export interface ThreadListResponseData {
+    threads: ThreadWithStatsWire[];
+}
+
+export interface ThreadGetResponseData extends ThreadWithMessagesWire {}

package/src/tool.d.ts

@@ -0,0 +1,269 @@
+/**
+ * @egox/contracts — `/egox/tools/*` + `/egox/mcp-admin/tools/*` wire types.
+ *
+ * Three independent consumers used to hand-mirror these shapes:
+ *   - the backend (`modules/tool/interfaces.ts`)
+ *   - the MCP server (`egox-mcp/src/backend-client.ts` — `BackendTool`)
+ *   - the console (`console/src/types/models.ts` — `Tool`)
+ * Each drift was one rename away from a silent runtime bug — the same
+ * shape of failure that produced the `answer === undefined` regression
+ * on `/ask`. Phase 9.1 unifies them under `ToolWire`.
+ *
+ * **Wire shape vs. backend in-process shape.** Timestamps are typed as
+ * `string` here because that's what JSON serialization produces (Fastify
+ * calls `Date.prototype.toJSON()` on the way out). The backend's
+ * in-process `Tool` type re-exports `ToolWire` and its formatter now
+ * emits ISO strings to match — no consumer of `tool.createdAt` in the
+ * backend treats it as a `Date`, so there's no plumbing cost.
+ */
+
+// ============================================================================
+// Locked vocabularies
+// ============================================================================
+
+/**
+ * What kind of upstream API this tool wraps. Locked because the
+ * orchestrator branches on it (REST → fetch, GRAPHQL → POST gql_query).
+ * Adding a value is a one-edit change across backend + MCP + console
+ * because they all reference `ToolType` from this file.
+ */
+export type ToolType = 'REST' | 'GRAPHQL';
+
+/** HTTP method for REST tools. Locked — the backend allows only these. */
+export type ToolHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * How the tool authenticates upstream.
+ *   - `'FORWARD'` — EgoX injects the caller's `authToken` into the
+ *     outbound request as `Authorization: Bearer …`.
+ *   - `'NONE'`    — no auth header is injected; tool-static `headers`
+ *     are still applied.
+ */
+export type ToolAuthType = 'FORWARD' | 'NONE';
+
+/**
+ * Provenance of the tool definition.
+ *   - `'manual'` — created in the Console.
+ *   - `'mcp'`    — created via the MCP server (Cursor / 3rd-party MCP
+ *                  client). Mutating an `mcp` tool from the Console
+ *                  requires an explicit override.
+ */
+export type ToolSource = 'manual' | 'mcp';
+
+// ============================================================================
+// JSON Schema (recursive, for tool input/output shapes)
+// ============================================================================
+
+/**
+ * Recursive JSON Schema fragment used by tool `inputSchema` /
+ * `outputSchema`. Distinct from `JsonSchemaDefinition` in `envelope.d.ts`
+ * (which is the narrow root-must-be-object shape used for `/ask`'s
+ * `responseFormat: 'json_object'`).
+ *
+ * Intentionally narrow vs. the full JSON Schema 2020-12 surface — only
+ * what EgoX's LLM-side adapter actually consumes. Adding a field here
+ * requires updating the adapter in `modules/tool/index.ts` in the
+ * same PR.
+ */
+export interface JsonSchemaWire {
+    type: string;
+    properties?: Record<string, JsonSchemaPropertyWire>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: JsonSchemaWire;
+    description?: string;
+}
+
+export interface JsonSchemaPropertyWire {
+    type: string;
+    description?: string;
+    enum?: string[];
+    items?: JsonSchemaPropertyWire;
+    properties?: Record<string, JsonSchemaPropertyWire>;
+    required?: string[];
+}
+
+// ============================================================================
+// ToolWire — the canonical row shape
+// ============================================================================
+
+/**
+ * Wire-format Tool row. Returned by every `/egox/tools/*` and
+ * `/egox/mcp-admin/tools/*` response that produces a Tool.
+ *
+ * Backend in-process `Tool` is an alias of this type — including the
+ * `tenantId` field, which is on the row even though the API caller
+ * never sends it (it's derived from API key / JWT context on the
+ * request side, but echoed on responses for audit).
+ */
+export interface ToolWire {
+    id: string;
+    /**
+     * Owning tenant. Present on every response for audit; the request
+     * side never carries it (the backend derives tenant from the API
+     * key context).
+     */
+    tenantId: string;
+    toolName: string;
+    toolDescription: string;
+    apiEndpoint: string;
+    toolType: ToolType;
+    httpMethod: ToolHttpMethod;
+    inputSchema: JsonSchemaWire;
+    outputSchema: JsonSchemaWire;
+    headers: Record<string, string>;
+    authType: ToolAuthType;
+    retryAttempts: number;
+    retryDelayMs: number;
+    enabled: boolean;
+    /** GraphQL query/mutation string. Required when `toolType === 'GRAPHQL'`. */
+    gqlQuery: string | null;
+    /** Example input values for LLM reference. */
+    exampleInput: Record<string, unknown> | null;
+    /** Example output values for LLM reference. */
+    exampleOutput: Record<string, unknown> | null;
+    /** Total LLM-initiated invocations (denormalized counter). */
+    callCount: number;
+    successCount: number;
+    failureCount: number;
+    /**
+     * ISO 8601 timestamp of the most recent invocation. `null` when the
+     * tool has never been called. The backend in-process formatter
+     * emits ISO strings here so wire and runtime shapes agree.
+     */
+    lastCalledAt: string | null;
+    source: ToolSource;
+    /**
+     * Lowercase header-name allowlist. Headers from the inbound `/ask`
+     * request whose name matches an entry are forwarded verbatim to
+     * the tool endpoint. Empty array (default) = no inbound header is
+     * forwarded — preserves the original safe behavior.
+     *
+     * Forbidden names (`Cookie`, `Host`, `Authorization`, …) are
+     * stripped defensively at execution time even if accidentally
+     * listed here.
+     */
+    forwardHeaders: string[];
+    /**
+     * Hard cap on how many times this tool may be EXECUTED inside a
+     * single `/ask` turn. Dedup cache hits don't count — only real
+     * upstream calls. When exceeded, the orchestrator returns a
+     * synthetic refusal message to the LLM. Range 1-50, default 5
+     * (Phase 5 / Layer 2).
+     */
+    maxCallsPerTurn: number;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+}
+
+// ============================================================================
+// Request bodies (what the client SENDS)
+// ============================================================================
+
+/**
+ * Wire body of `POST /egox/tools`. Notable absences:
+ *   - `tenantId` — derived from API key context / JWT.
+ *   - `enabled` — new tools are always created `enabled: true`.
+ *   - counters / `lastCalledAt` — server-managed.
+ *   - timestamps                 — server-managed.
+ */
+export interface ToolCreateBody {
+    toolName: string;
+    toolDescription: string;
+    apiEndpoint: string;
+    toolType?: ToolType;
+    httpMethod?: ToolHttpMethod;
+    inputSchema: JsonSchemaWire;
+    outputSchema?: JsonSchemaWire;
+    headers?: Record<string, string>;
+    authType?: ToolAuthType;
+    retryAttempts?: number;
+    retryDelayMs?: number;
+    /** GraphQL query/mutation. Required when `toolType === 'GRAPHQL'`. */
+    gqlQuery?: string;
+    exampleInput?: Record<string, unknown>;
+    exampleOutput?: Record<string, unknown>;
+    /** Provenance. Defaults to `'manual'`. */
+    source?: ToolSource;
+    forwardHeaders?: string[];
+    /** Per-turn execution cap (1-50, default 5). */
+    maxCallsPerTurn?: number;
+}
+
+/**
+ * Wire body of `PUT /egox/tools/:toolId`. Every field is optional —
+ * unspecified fields are left untouched (`COALESCE` semantics).
+ * `toolId` lives in the URL, not the body; `tenantId` is derived
+ * from the auth context.
+ */
+export interface ToolUpdateBody {
+    toolName?: string;
+    toolDescription?: string;
+    apiEndpoint?: string;
+    toolType?: ToolType;
+    httpMethod?: ToolHttpMethod;
+    inputSchema?: JsonSchemaWire;
+    outputSchema?: JsonSchemaWire;
+    headers?: Record<string, string>;
+    authType?: ToolAuthType;
+    retryAttempts?: number;
+    retryDelayMs?: number;
+    enabled?: boolean;
+    gqlQuery?: string;
+    exampleInput?: Record<string, unknown>;
+    exampleOutput?: Record<string, unknown>;
+    source?: ToolSource;
+    forwardHeaders?: string[];
+    maxCallsPerTurn?: number;
+}
+
+// ============================================================================
+// Response data shapes (carried inside `EgoxApiResponse.data`)
+// ============================================================================
+
+export interface ToolListResponseData {
+    tools: ToolWire[];
+}
+
+export interface ToolGetResponseData {
+    tool: ToolWire;
+}
+
+// ============================================================================
+// MCP-admin tool preview (`POST /egox/mcp-admin/tools/:name/preview`)
+// ============================================================================
+
+/**
+ * Single field diff entry for a tool-upsert preview. `oldValue` is
+ * `undefined` on a fresh create.
+ */
+export interface ToolPreviewDiffEntry {
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+}
+
+/**
+ * Response payload of the MCP "preview before upsert" endpoint.
+ *
+ *   - `action`           — what an unforced PUT would do.
+ *   - `requiresForce`    — true when overwriting a `'manual'` tool
+ *                          from MCP; the upsert refuses without
+ *                          `force: true`.
+ *   - `existingSource`   — provenance of the row that would be
+ *                          overwritten; null on a fresh create.
+ *   - `validationErrors` — flat strings; empty array means the body
+ *                          is valid as-is.
+ *   - `diff`             — only the fields that would change.
+ */
+export interface ToolPreview {
+    toolName: string;
+    action: 'create' | 'update' | 'noop';
+    exists: boolean;
+    requiresForce: boolean;
+    existingSource: ToolSource | null;
+    validationErrors: string[];
+    diff: ToolPreviewDiffEntry[];
+}