@egox/contracts 0.5.0

package/src/personality.d.ts

@@ -0,0 +1,275 @@
+/**
+ * @egox/contracts — `/egox/personality/*` and
+ * `/egox/tenants/:tenantId/personality/*` wire types.
+ *
+ * Two related but distinct surfaces share this file:
+ *
+ *   - **User-level templates** (`/egox/personality/*`). A library of
+ *     personality profiles a console user authors and later clones
+ *     into specific projects. NOT used at `/ask` resolution time.
+ *   - **Project-scoped profiles** (`/egox/tenants/:tenantId/personality/*`,
+ *     Item #6 refactor). The single ACTIVE row per tenant drives the
+ *     LLM's persona on every `/ask`. Cloned from a template or
+ *     authored fresh in the project.
+ *
+ * Both shapes share `PersonalityTraitsWire` and `PresetType` —
+ * cloning a template is a structural copy plus a `templateSourceUserId`
+ * / `templateSourceProfileId` pointer.
+ *
+ * Drift cleaned up:
+ *   - Backend `PersonalityProfile` and `TenantPersonalityProfile`
+ *     used `Date` for timestamps; wire and console already used ISO.
+ *     Backend formatters now match.
+ */
+
+// ============================================================================
+// Locked vocabularies
+// ============================================================================
+
+/**
+ * Preset personality archetypes the console offers as starting points.
+ * Mirrors the keys of the backend's preset registry. Adding a preset
+ * is a one-edit change here + a new entry in the registry; the union
+ * fails the build on any consumer that hard-codes the old set.
+ */
+export type PresetType =
+    | 'balanced'
+    | 'professional'
+    | 'friendly'
+    | 'casual'
+    | 'expert'
+    | 'playful'
+    | 'empathetic'
+    | 'concise';
+
+// ============================================================================
+// Supporting shapes
+// ============================================================================
+
+/**
+ * The eight personality dials (0-100 each). Used as the active
+ * configuration on both user templates and project profiles, and as
+ * the slider values the console renders.
+ *
+ * Each axis is documented relative to its low / high pole — that
+ * documentation belongs in the contracts package because it's part
+ * of what consumers (the SDK exposing it, future MCP tools surfacing
+ * it) need to render the control correctly.
+ */
+export interface PersonalityTraitsWire {
+    /** 0 = serious, 100 = playful. */
+    senseOfHumor: number;
+    /** 0 = casual, 100 = formal/grave. */
+    seriousness: number;
+    /** 0 = diplomatic, 100 = blunt. */
+    directness: number;
+    /** 0 = conventional, 100 = creative. */
+    creativity: number;
+    /** 0 = neutral, 100 = caring. */
+    empathy: number;
+    /** 0 = casual, 100 = formal. */
+    formality: number;
+    /** 0 = brief, 100 = detailed. */
+    verbosity: number;
+    /** 0 = calm, 100 = energetic. */
+    enthusiasm: number;
+}
+
+// ============================================================================
+// User-level personality template (the templates library)
+// ============================================================================
+
+/**
+ * Wire-format user-level personality profile. Returned by
+ * `/egox/personality/*` endpoints. Owned by a console user and
+ * intended to be cloned INTO projects via the tenant-personality
+ * clone endpoint.
+ *
+ * `isActive` here is a per-template "currently authoring this one"
+ * flag, NOT the `/ask` resolution flag (that's
+ * `TenantPersonalityProfileWire.isActive`).
+ */
+export interface PersonalityProfileWire {
+    id: string;
+    userId: string;
+    name: string;
+    traits: PersonalityTraitsWire;
+
+    customInstructions: string | null;
+    exampleResponses: string[];
+    avoidPhrases: string[];
+    preferredPhrases: string[];
+
+    agentName: string | null;
+    agentRole: string | null;
+    agentTone: string | null;
+
+    isActive: boolean;
+    /** `true` for the immutable seed templates the backend ships with. */
+    isPreset: boolean;
+    presetType: PresetType | null;
+
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+}
+
+/**
+ * Definition of one immutable seed preset. Returned by the
+ * "list presets" endpoint so the console can render the picker
+ * without hard-coding the catalogue.
+ */
+export interface PresetDefinitionWire {
+    type: PresetType;
+    name: string;
+    description: string;
+    traits: PersonalityTraitsWire;
+    /** Optional emoji / lucide icon name; console-renderer-defined. */
+    icon?: string;
+}
+
+/**
+ * Wire body of `POST /egox/personality/profiles`. `userId` is derived
+ * from the console JWT, not the body.
+ */
+export interface PersonalityProfileCreateBody {
+    name: string;
+    traits?: Partial<PersonalityTraitsWire>;
+    customInstructions?: string;
+    exampleResponses?: string[];
+    avoidPhrases?: string[];
+    preferredPhrases?: string[];
+    agentName?: string;
+    agentRole?: string;
+    agentTone?: string;
+}
+
+/**
+ * Wire body of `PUT /egox/personality/profiles/:profileId`. Every
+ * field is optional; `null` is a meaningful value for the nullable
+ * string columns (clears them), `undefined` means "leave alone". The
+ * service distinguishes between the two.
+ */
+export interface PersonalityProfileUpdateBody {
+    name?: string;
+    traits?: Partial<PersonalityTraitsWire>;
+    customInstructions?: string | null;
+    exampleResponses?: string[];
+    avoidPhrases?: string[];
+    preferredPhrases?: string[];
+    agentName?: string | null;
+    agentRole?: string | null;
+    agentTone?: string | null;
+}
+
+// ============================================================================
+// Project-scoped personality (Item #6 — drives /ask)
+// ============================================================================
+
+/**
+ * Wire-format project-scoped personality profile. Returned by
+ * `/egox/tenants/:tenantId/personality/*`. The single row with
+ * `isActive: true` per tenant is what the orchestrator resolves for
+ * `/ask`.
+ *
+ * `templateSourceUserId` and `templateSourceProfileId` are nullable
+ * provenance pointers — preserved as `SET NULL` if the source
+ * template or its owner is deleted. They power the future "compare
+ * against template" UX without coupling project profile lifetime to
+ * template lifetime.
+ */
+export interface TenantPersonalityProfileWire {
+    id: string;
+    tenantId: string;
+    name: string;
+    traits: PersonalityTraitsWire;
+
+    customInstructions: string | null;
+    exampleResponses: string[];
+    avoidPhrases: string[];
+    preferredPhrases: string[];
+
+    agentName: string | null;
+    agentRole: string | null;
+    agentTone: string | null;
+
+    isActive: boolean;
+
+    templateSourceUserId: string | null;
+    templateSourceProfileId: string | null;
+
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+}
+
+/**
+ * Wire body of `POST /egox/tenants/:tenantId/personality/profiles`
+ * (fresh, no template lineage). `tenantId` is the URL param, not the
+ * body.
+ */
+export interface TenantPersonalityCreateBody {
+    name: string;
+    traits?: Partial<PersonalityTraitsWire>;
+    customInstructions?: string;
+    exampleResponses?: string[];
+    avoidPhrases?: string[];
+    preferredPhrases?: string[];
+    agentName?: string;
+    agentRole?: string;
+    agentTone?: string;
+}
+
+/**
+ * Wire body of `PUT /egox/tenants/:tenantId/personality/profiles/:profileId`.
+ * Same null-vs-undefined semantics as `PersonalityProfileUpdateBody`.
+ */
+export interface TenantPersonalityUpdateBody {
+    name?: string;
+    traits?: Partial<PersonalityTraitsWire>;
+    customInstructions?: string | null;
+    exampleResponses?: string[];
+    avoidPhrases?: string[];
+    preferredPhrases?: string[];
+    agentName?: string | null;
+    agentRole?: string | null;
+    agentTone?: string | null;
+}
+
+/**
+ * Wire body of the clone endpoint. `sourceUserId` MUST be the
+ * requesting console user (validated server-side); a stolen
+ * `sourceProfileId` therefore can't be cloned across user boundaries.
+ */
+export interface TenantPersonalityCloneBody {
+    sourceUserId: string;
+    sourceProfileId: string;
+    /** Defaults to `${source.name} (cloned)` server-side. */
+    name?: string;
+}
+
+// ============================================================================
+// Resolution envelopes (returned by the "what's active?" endpoints)
+// ============================================================================
+
+/**
+ * Response of `GET /egox/personality/active`. `isDefault: true`
+ * means no user-level profile is selected and the future caller
+ * should treat the user as having no template-level preference.
+ */
+export interface ActivePersonalityWire {
+    profile: PersonalityProfileWire | null;
+    isDefault: boolean;
+}
+
+/**
+ * Response of `GET /egox/tenants/:tenantId/personality/active`.
+ * `isDefault: true` means no project-level profile is active —
+ * `/ask` falls back to the orchestrator's built-in baseline prompt.
+ */
+export interface ActiveTenantPersonalityWire {
+    profile: TenantPersonalityProfileWire | null;
+    isDefault: boolean;
+}

package/src/rag.d.ts

@@ -0,0 +1,188 @@
+/**
+ * @egox/contracts — `/egox/tenants/:tenantId/rag/documents/*` +
+ * `/egox/mcp-admin/rag-documents/*` wire types.
+ *
+ * Three independent consumers used to hand-mirror these shapes:
+ *   - the backend (`modules/rag/interfaces.ts`)
+ *   - the MCP server (`egox-mcp/src/backend-client.ts` — `BackendRagDoc`)
+ *   - the console (`console/src/types/models.ts` — `RagDocument`)
+ * Each mirror had its own subtle drift:
+ *   - MCP's `sourceType` / `processingStatus` were typed as bare `string`
+ *     (no `'file'|'url'|'manual'` lock), and `sourceUrl` was missing entirely.
+ *   - Console's `RagDocument` had no `source` (provenance) field at all,
+ *     so the manual-vs-MCP distinction was invisible in the UI.
+ *   - Backend timestamps were `Date` in-process but ISO strings on the
+ *     wire — same wire/runtime mismatch we removed for Tools in P1.
+ * Phase 9.2 unifies all three under `RagDocumentWire`.
+ *
+ * Mirrors the pattern locked in P1 (`tool.d.ts`):
+ *   - locked vocabularies prefixed `Rag*` to avoid collisions with
+ *     future families that have their own "source type" concept;
+ *   - timestamps as ISO 8601 `string` (backend `formatDocument` now
+ *     emits ISO via the same `toIso` helper Tools uses);
+ *   - request bodies omit context fields the route layer attaches
+ *     (`tenantId`, identifying URL params).
+ *
+ * **Backend-only.** `RagChunk`, `RetrievedChunk`, `RetrievalRequest`,
+ * `RetrievalResponse`, and `ChunkOptions` are NOT wire types — they're
+ * orchestrator-internal retrieval shapes. The only chunk info that
+ * crosses the wire is the minimal `{ documentTitle, score }` pair
+ * already on `AskStreamRagRetrievedEvent` in `stream.d.ts`.
+ */
+
+// ============================================================================
+// Locked vocabularies
+// ============================================================================
+
+/**
+ * How a RAG document entered the system.
+ *   - `'file'`   — uploaded via Console.
+ *   - `'url'`    — fetched from a URL the user provided.
+ *   - `'manual'` — pasted as text in the Console editor.
+ *
+ * Distinct from `RagDocumentSource` (provenance: which user surface
+ * created the row, `'manual'` console vs `'mcp'` Cursor flow).
+ */
+export type RagDocumentSourceType = 'file' | 'url' | 'manual';
+
+/**
+ * Async ingestion state. Documents start `'pending'`, advance to
+ * `'processing'` while chunking + embedding run, then settle at
+ * `'completed'` or `'failed'`. Console surfaces these as badge colors.
+ */
+export type RagProcessingStatus = 'pending' | 'processing' | 'completed' | 'failed';
+
+/**
+ * Provenance of the document.
+ *   - `'manual'` — created in the Console.
+ *   - `'mcp'`    — created via the MCP server (Cursor / 3rd-party MCP
+ *                  client). Overwriting a `'manual'` document from MCP
+ *                  requires `force: true` (see `RagDocumentUpsertByTitleBody`).
+ *
+ * Structurally identical to `ToolSource` from `tool.d.ts` but kept as a
+ * distinct nominal type so a function expecting one can't be passed the
+ * other by mistake — each family owns its own source-of-truth vocab.
+ */
+export type RagDocumentSource = 'manual' | 'mcp';
+
+// ============================================================================
+// RagDocumentWire — the canonical row shape
+// ============================================================================
+
+/**
+ * Wire-format RAG document row. Returned by every
+ * `/egox/tenants/:tenantId/rag/documents/*` and
+ * `/egox/mcp-admin/rag-documents/*` response that produces a document.
+ *
+ * Backend in-process `RagDocument` is an alias of this type. Timestamps
+ * are typed as `string` (ISO 8601) because that's what Fastify
+ * serialises Date values to; the backend's `formatDocument` emits ISO
+ * strings to match so wire and in-process shapes never disagree.
+ *
+ * The body of the document and its chunked content live in different
+ * places — this row carries the raw `content` (so consumers can
+ * display the source text) but does NOT include the derived chunks.
+ * Chunks are an orchestrator-internal concept; only the `chunkCount`
+ * is exposed.
+ */
+export interface RagDocumentWire {
+    id: string;
+    /**
+     * Owning tenant. Present on every response for audit; the request
+     * side never carries it (the backend derives tenant from the API
+     * key / JWT context).
+     */
+    tenantId: string;
+    /**
+     * Display title. Also the natural key for the MCP upsert path
+     * (`PUT /egox/mcp-admin/rag-documents/:title`) — uniqueness is
+     * enforced per tenant.
+     */
+    title: string;
+    sourceType: RagDocumentSourceType;
+    /** Origin URL when `sourceType === 'url'`; `null` otherwise. */
+    sourceUrl: string | null;
+    /** Raw text content. May be large — Console truncates in list views. */
+    content: string;
+    /** Tenant-supplied tags. Used for retrieval filtering (`tags?: string[]` on `/ask`). */
+    tags: string[];
+    /** Free-form per-document metadata (provenance hints, authoring info, etc.). */
+    metadata: Record<string, unknown>;
+    processingStatus: RagProcessingStatus;
+    /** Number of chunks the document was split into. `0` until processing completes. */
+    chunkCount: number;
+    source: RagDocumentSource;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+}
+
+// ============================================================================
+// Request bodies (what the client SENDS)
+// ============================================================================
+
+/**
+ * Wire body of `POST /egox/tenants/:tenantId/rag/documents` (the
+ * Console admin path). Notable absences:
+ *   - `tenantId`         — URL param, not body.
+ *   - `processingStatus` — server-managed, starts at `'pending'`.
+ *   - `chunkCount`       — server-managed, populated by the chunker.
+ *   - `source`           — admin route hardcodes `'manual'`; the MCP
+ *                          path uses `RagDocumentUpsertByTitleBody`
+ *                          and hardcodes `'mcp'`.
+ *   - timestamps         — server-managed.
+ */
+export interface RagDocumentCreateBody {
+    title: string;
+    content: string;
+    sourceType?: RagDocumentSourceType;
+    sourceUrl?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Wire body of `PUT /egox/mcp-admin/rag-documents/:title` (the MCP
+ * idempotent upsert path). Differs from `RagDocumentCreateBody`:
+ *   - `title`     — URL param, not body.
+ *   - `sourceType`/`sourceUrl` — not accepted; MCP-created docs are
+ *                                 always `sourceType: 'manual'`,
+ *                                 `sourceUrl: null`, `source: 'mcp'`.
+ *   - `force`     — opt-in escape hatch to overwrite a `'manual'`
+ *                   document of the same title. Without it the
+ *                   backend returns `McpManualOverrideRequired`.
+ */
+export interface RagDocumentUpsertByTitleBody {
+    content: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    /** Set to `true` to overwrite a `'manual'`-source document of the same title. */
+    force?: boolean;
+}
+
+// ============================================================================
+// Response data shapes (carried inside `EgoxApiResponse.data`)
+// ============================================================================
+
+export interface RagDocumentListResponseData {
+    documents: RagDocumentWire[];
+}
+
+export interface RagDocumentGetResponseData {
+    document: RagDocumentWire;
+}
+
+/**
+ * Response payload of the MCP upsert endpoint
+ * (`PUT /egox/mcp-admin/rag-documents/:title`).
+ *   - `action: 'created'`  — there was no prior row for this title.
+ *   - `action: 'replaced'` — the old row was deleted and a fresh one
+ *     created; chunks are recomputed asynchronously.
+ *   - `message`            — operator-facing hint about async processing.
+ */
+export interface RagDocumentUpsertResponseData {
+    document: RagDocumentWire;
+    action: 'created' | 'replaced';
+    message: string;
+}

package/src/search.d.ts

@@ -0,0 +1,23 @@
+/**
+ * search.d.ts — unified tenant search (`GET /egox/tenants/:tenantId/search`).
+ *
+ * Powers the console command-palette's dynamic fallback: when the static page
+ * matrix has no match, the palette searches this tenant's tools/endpoints and
+ * KB documents by keyword (min 3 chars) and indexes the results client-side.
+ */
+
+/** A single searchable entity (tool/endpoint or KB document). */
+export interface SearchResultItem {
+    type: 'tool' | 'document';
+    id: string;
+    /** Display name — tool `toolName` or document `title`. */
+    title: string;
+    /** Secondary line — tool `toolDescription` or document processing status. */
+    subtitle?: string;
+    tenantId: string;
+}
+
+/** Response of `GET /egox/tenants/:tenantId/search?q=<keyword>&limit=<n>`. */
+export interface TenantSearchResponseData {
+    results: SearchResultItem[];
+}

package/src/stream.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @egox/contracts — `/ask/stream` SSE event union.
+ *
+ * Each event is JSON-serialized and framed as a single `data: …\n\n`
+ * Server-Sent Event. Backend writes these; SDK + Console parse them.
+ * The discriminated union is the single source of truth for both sides
+ * so adding a new event variant is a single-edit, type-checked change
+ * across the stack.
+ *
+ * `AskStreamRequestBody` (the wire request shape) lives in `ask.d.ts`
+ * because it inherits from `AskRequestBody`.
+ */
+
+import type { Intent, TokenUsage } from './envelope';
+
+/**
+ * Discriminated union of every event the streaming `/ask` endpoint emits.
+ *
+ * Notes on subset behaviour:
+ *   - `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 =
+    | AskStreamIntentEvent
+    | AskStreamRagSearchingEvent
+    | AskStreamRagRetrievedEvent
+    | AskStreamDeltaEvent
+    | AskStreamToolCallingEvent
+    | AskStreamToolResultEvent
+    | AskStreamLLMDebugEvent
+    | AskStreamToolDebugEvent
+    | AskStreamDoneEvent
+    | AskStreamErrorEvent;
+
+export interface AskStreamIntentEvent {
+    type: 'intent';
+    intent: Intent;
+}
+
+export interface AskStreamRagSearchingEvent {
+    type: 'rag.searching';
+    query: string;
+}
+
+export interface AskStreamRagRetrievedEvent {
+    type: 'rag.retrieved';
+    chunks: Array<{
+        documentTitle: string;
+        score: number;
+    }>;
+}
+
+export interface AskStreamDeltaEvent {
+    type: 'delta';
+    /** Token (or token-like fragment) appended to the running answer. */
+    content: string;
+}
+
+export interface AskStreamToolCallingEvent {
+    type: 'tool.calling';
+    name: string;
+    args: Record<string, unknown>;
+}
+
+export interface AskStreamToolResultEvent {
+    type: 'tool.result';
+    name: string;
+    success: boolean;
+    durationMs: number;
+}
+
+/**
+ * Debug-only message frame describing one LLM chat-completion iteration.
+ *
+ * Emitted only when the request was made with `debug: true` AND the
+ * caller is authenticated as a console JWT user. Safe to ignore from
+ * non-debug consumers — the field never appears outside that path.
+ */
+export interface AskStreamLLMDebugEvent {
+    type: 'llm.debug';
+    /** Zero-based index in the orchestrator's tool loop. */
+    iteration: number;
+    /** Resolved model id, e.g. `gpt-4.1-mini-2025-04-14`. */
+    model: string;
+    /** Snapshot of the messages array sent INTO this iteration. */
+    messages: Array<{
+        role: 'system' | 'user' | 'assistant' | 'tool';
+        content: string | null;
+        name?: string;
+        toolCallId?: string;
+        toolCalls?: Array<{
+            id: string;
+            type: 'function';
+            function: { name: string; arguments: string };
+        }>;
+    }>;
+    /** What the LLM emitted this iteration (text + tool-call requests). */
+    response: {
+        content: string;
+        finishReason: string;
+        toolCalls?: Array<{
+            id: string;
+            type: 'function';
+            function: { name: string; arguments: string };
+        }>;
+    };
+    usage: TokenUsage;
+}
+
+/**
+ * Debug-only frame describing one tool HTTP execution — the actual
+ * request EgoX sent to the tenant server and the response it received.
+ *
+ * Emitted only when the request was made with `debug: true` AND the
+ * caller is authenticated as a console JWT user.
+ *
+ * Sensitive header values (Authorization, X-Egox-Signature,
+ * X-Egox-Timestamp, and anything matching /token|secret|key|auth/i) are
+ * already redacted to `***` server-side before this frame is written.
+ */
+export interface AskStreamToolDebugEvent {
+    type: 'tool.debug';
+    name: string;
+    durationMs: number;
+    success: boolean;
+    /** What EgoX sent to the tenant server. */
+    request: {
+        method: string;
+        url: string;
+        headers: Record<string, string>;
+        body: unknown;
+    };
+    /** What came back. `statusCode` is null on a network exception. */
+    response: {
+        statusCode: number | null;
+        headers: Record<string, string>;
+        body: unknown;
+        error?: string;
+    };
+    /** Total number of attempts including the final one (1 + retries). */
+    attempts: number;
+    /**
+     * Provenance map of which tool-allowlisted headers were actually
+     * forwarded and from which source (`'body'` =
+     * `AskRequestBody.toolHeaders`, `'inbound'` = inbound HTTP
+     * forwarded by `tool.forwardHeaders` allowlist). Header VALUES
+     * are NOT included — they're already in `request.headers`
+     * (redacted there). Useful for debugging "why did/didn't my
+     * header get forwarded?" without leaking secrets a second time.
+     * Omitted when no headers were forwarded.
+     */
+    forwardedHeaderSources?: Record<string, 'body' | 'inbound'>;
+}
+
+export interface AskStreamDoneEvent {
+    type: 'done';
+    threadId: string;
+    /**
+     * Echo of `AskStreamRequestBody.externalThreadId` when one was
+     * supplied — same semantics as `AskResponseData.externalThreadId`.
+     * Lets streaming consumers correlate the SSE result back to their
+     * own conversation id without parsing the final `data` payload
+     * separately (Phase 6).
+     */
+    externalThreadId?: string;
+    intent: Intent;
+    toolUsed: string | null;
+    ragChunksUsed: number;
+    model: string;
+    usage: TokenUsage;
+    /**
+     * Pending high-impact actions awaiting user approval (Path-A, DotCollab #8).
+     * Same semantics + shape as `AskResponseData.pendingActions` — surfaced on
+     * the stream's terminal event so streaming consumers can render the
+     * Approve/Reject card without parsing the final `data` payload separately.
+     */
+    pendingActions?: Array<{ approvalId: string; toolName: string; summary: string }>;
+}
+
+export interface AskStreamErrorEvent {
+    type: 'error';
+    message: string;
+    /** Machine-readable error code, e.g. `INVALID_INPUT`, `INTERNAL_SERVER_ERROR`. */
+    code?: string;
+}