@ego-z/contracts 0.11.0

package/src/tool.d.ts

@@ -0,0 +1,269 @@
+/**
+ * @ego-z/contracts — `/egoz/tools/*` + `/egoz/mcp-admin/tools/*` wire types.
+ *
+ * Three independent consumers used to hand-mirror these shapes:
+ *   - the backend (`modules/tool/interfaces.ts`)
+ *   - the MCP server (`egoz-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'` — EgoZ 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 EgoZ'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 `/egoz/tools/*` and
+ * `/egoz/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 /egoz/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 /egoz/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 `EgozApiResponse.data`)
+// ============================================================================
+
+export interface ToolListResponseData {
+    tools: ToolWire[];
+}
+
+export interface ToolGetResponseData {
+    tool: ToolWire;
+}
+
+// ============================================================================
+// MCP-admin tool preview (`POST /egoz/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[];
+}

package/src/user-memory.d.ts

@@ -0,0 +1,226 @@
+/**
+ * @ego-z/contracts — `/egoz/tenants/:tenantId/learning/*` wire types
+ * (Phase 15 / exURM — per-end-user learning).
+ *
+ * The Console calls this surface **Learning**; the backend domain is
+ * `user-memory` (table `egoz_user_memory`). One HYBRID row shape covers both
+ * kinds via a `kind` discriminator:
+ *   - `profile` — a structured attribute (`attrKey` = `content`, e.g.
+ *     `size` = `38`). Always injected when approved.
+ *   - `memory`  — a free-text snippet (`attrKey` null), embedded server-side
+ *     and similarity-retrieved. The `embedding` itself NEVER crosses the wire.
+ *
+ * GOVERNANCE (locked): review-before-use. Rows land `status: 'pending'`; only
+ * `'approved'` rows are ever injected into an `/ask` prompt. Opt-in per tenant
+ * (`learning_enabled`, default false); no capture under no-store.
+ *
+ * ── Admin routes (all guarded by tenant-owner auth) ─────────────────────────
+ *   GET    /egoz/tenants/:tenantId/learning/users
+ *            → LearningUsersResponseData   (roster + pending badge total + flag)
+ *   GET    /egoz/tenants/:tenantId/learning/users/:externalUserId?status=
+ *            → LearningUserFactsResponseData  (profile + memories, one flat list)
+ *   PATCH  /egoz/tenants/:tenantId/learning/facts/:factId
+ *            body UpdateUserMemoryFactBody  → UserMemoryFactResponseData
+ *   POST   /egoz/tenants/:tenantId/learning/facts/:factId/approve
+ *            → UserMemoryFactResponseData
+ *   POST   /egoz/tenants/:tenantId/learning/facts/:factId/reject
+ *            → UserMemoryFactResponseData
+ *   DELETE /egoz/tenants/:tenantId/learning/facts/:factId
+ *            → UserMemoryFactResponseData   (the deleted row, for optimistic UI)
+ *   DELETE /egoz/tenants/:tenantId/learning/users/:externalUserId
+ *            → ForgetUserResponseData       (right-to-be-forgotten)
+ *   GET    /egoz/tenants/:tenantId/learning/analytics
+ *            → LearningAnalyticsResponseData (per-tenant adoption summary)
+ *   (the on/off toggle reuses the existing tenant-config update with
+ *    `learningEnabled` — no dedicated route here.)
+ *
+ * **Versioning.** Additive new family → minor bump (0.5.3 → 0.6.0).
+ */
+
+// ============================================================================
+// Locked vocabularies (mirror DB CHECK constraints — migration 042)
+// ============================================================================
+
+/**
+ * Hybrid discriminator (mirrors `egoz_user_memory.kind` CHECK, migration 042).
+ *   - `profile` — structured attribute, always injected when approved.
+ *   - `memory`  — free-text snippet, embedded + similarity-retrieved.
+ * Adding a value requires a migration + this type in lockstep.
+ */
+export type UserMemoryKind = 'profile' | 'memory';
+
+/**
+ * Review lifecycle (mirrors `egoz_user_memory.status` CHECK, migration 042).
+ * Only `'approved'` is ever read on the `/ask` path.
+ */
+export type UserMemoryStatus = 'pending' | 'approved' | 'rejected';
+
+/**
+ * Provenance (mirrors `egoz_user_memory.source` CHECK, migration 042).
+ * `'agent_tool'` = proposed by the built-in `remember_fact` tool (MVP; the
+ * only source until a manual-add path lands).
+ */
+export type UserMemorySource = 'agent_tool';
+
+// ============================================================================
+// UserMemoryWire — the canonical row shape
+// ============================================================================
+
+/**
+ * Wire-format learned-fact row. Returned by the learning detail + mutation
+ * endpoints. The `embedding` column is intentionally omitted — it never
+ * crosses the wire.
+ */
+export interface UserMemoryWire {
+    id: string;
+    tenantId: string;
+    /** The opaque end-user scope key from `/ask` (`externalUserId`). */
+    externalUserId: string;
+    kind: UserMemoryKind;
+    /**
+     * The attribute name for `kind: 'profile'` (e.g. `'size'`); `null` for
+     * `kind: 'memory'`.
+     */
+    attrKey: string | null;
+    /** The attribute value (`profile`) or the memory snippet (`memory`). */
+    content: string;
+    status: UserMemoryStatus;
+    source: UserMemorySource;
+    /** Thread that produced this fact (audit); `null` when unknown / no-store. */
+    originThreadId: string | null;
+    /** Message that produced this fact (audit); `null` when unknown / no-store. */
+    originMessageId: string | null;
+    /** Optional model-reported confidence in `[0, 1]`; `null` when not given. */
+    confidence: number | null;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+    /** ISO 8601 timestamp; `null` until reviewed (approved/rejected/edited). */
+    reviewedAt: string | null;
+    /** User id who reviewed; `null` while pending. */
+    reviewedBy: string | null;
+    /**
+     * Whether the Presidio pass flagged any PII/PHI in this fact's text at
+     * propose time (Phase C). The review UI shows an amber "possible PII" chip
+     * when true so the owner scrutinises before approving. Absent/false when
+     * none found or Presidio isn't configured. Additive — older consumers ignore it.
+     */
+    piiFlagged?: boolean;
+    /**
+     * The distinct PII/PHI entity TYPES Presidio flagged (e.g. `'PERSON'`,
+     * `'EMAIL_ADDRESS'`, `'US_SSN'`), strongest-confidence first. Types only —
+     * never the matched text. Empty/absent when `piiFlagged` is false. Shown in
+     * the chip's tooltip. Additive.
+     */
+    piiEntities?: string[];
+}
+
+// ============================================================================
+// Roster summary — one row per external user
+// ============================================================================
+
+/**
+ * Per-end-user roster entry for the Learning list screen. Aggregated over that
+ * user's `egoz_user_memory` rows — no per-fact fetch needed for the table.
+ */
+export interface UserMemoryUserSummaryWire {
+    externalUserId: string;
+    /** Count of `status: 'approved'` facts (profile + memory). */
+    approvedCount: number;
+    /** Count of `status: 'pending'` facts — drives the review badge. */
+    pendingCount: number;
+    /**
+     * Most recent learning activity for this user (max `created_at` across
+     * their facts), ISO 8601; `null` if somehow empty. Labelled "Last activity"
+     * in the UI — it is fact activity, not a true last-seen from threads.
+     */
+    lastActivityAt: string | null;
+}
+
+// ============================================================================
+// Request bodies (what the client SENDS)
+// ============================================================================
+
+/**
+ * Body of `PATCH …/learning/facts/:factId`. Owner edits a proposed/approved
+ * fact before or after approving it. Both fields optional (partial update);
+ * `attrKey` only meaningful for `kind: 'profile'`.
+ */
+export interface UpdateUserMemoryFactBody {
+    content?: string;
+    attrKey?: string | null;
+}
+
+// ============================================================================
+// Response data shapes (carried inside `EgozApiResponse.data`)
+// ============================================================================
+
+/**
+ * `GET …/learning/users`. The roster plus the flag state (so the list screen
+ * can render the on/off Switch without a second call) and the tenant-wide
+ * pending total for the sidebar badge.
+ */
+export interface LearningUsersResponseData {
+    /** Current per-tenant opt-in state (`egoz_tenant_configs.learning_enabled`). */
+    learningEnabled: boolean;
+    /** Sum of `pendingCount` across all users — the sidebar/nav badge. */
+    totalPending: number;
+    users: UserMemoryUserSummaryWire[];
+}
+
+/**
+ * `GET …/learning/users/:externalUserId`. All of the user's facts as one flat
+ * list — partition client-side: review queue = `status === 'pending'`;
+ * approved profile = `kind === 'profile' && status === 'approved'`; approved
+ * memories = `kind === 'memory' && status === 'approved'`. When the request
+ * carried `?status=`, `facts` is pre-filtered to that status.
+ */
+export interface LearningUserFactsResponseData {
+    externalUserId: string;
+    facts: UserMemoryWire[];
+}
+
+/**
+ * Returned by every single-fact mutation (`PATCH`, `approve`, `reject`,
+ * `DELETE …/facts/:factId`) — the affected row for optimistic UI reconciliation.
+ * On delete this is the row as it was just before removal.
+ */
+export interface UserMemoryFactResponseData {
+    fact: UserMemoryWire;
+}
+
+/**
+ * `DELETE …/learning/users/:externalUserId` (right-to-be-forgotten). Reports
+ * how many facts were purged so the UI can confirm.
+ */
+export interface ForgetUserResponseData {
+    externalUserId: string;
+    deletedCount: number;
+}
+
+/**
+ * `GET …/learning/analytics` (Phase C). Per-tenant learning adoption summary —
+ * single-query aggregates over `egoz_user_memory`, scoped to the tenant. Powers
+ * the Console analytics stat tiles.
+ */
+export interface LearningAnalyticsResponseData {
+    /** Current per-tenant opt-in state (`egoz_tenant_configs.learning_enabled`). */
+    learningEnabled: boolean;
+    /** Distinct external users that have ≥1 learned fact. */
+    totalUsers: number;
+    /** Fact counts by review status. */
+    facts: {
+        total: number;
+        pending: number;
+        approved: number;
+        rejected: number;
+    };
+    /** Fact counts by kind (profile vs semantic memory). */
+    byKind: {
+        profile: number;
+        memory: number;
+    };
+    /** Facts whose text the Presidio pass flagged for possible PII/PHI. */
+    piiFlaggedCount: number;
+}