@firstlovecenter/ai-chat 0.1.0

package/dist/server/index.d.cts

@@ -0,0 +1,487 @@
+import { S as SystemBlock, T as ToolSchema, a as ToolContext, b as ToolDefinition, P as PresentPayload, c as PersistencePort, A as AuthPort, d as ScopePort, e as ToolsPort, V as VertexPort, L as LoggerPort } from '../types-DNwFvL-C.cjs';
+export { f as AiSettings, g as AiSettingsPatch, h as AppendMessageInput, i as AuthFail, j as AuthOk, k as AuthResult, B as Block, C as ChartSpec, l as ChatMessage, m as ChatMessageRole, n as ChatSession, o as CreateSessionInput, p as ListSessionsOpts, q as TERMINAL_TOOL_NAME, r as ToolResult, s as err, t as ok } from '../types-DNwFvL-C.cjs';
+import { GoogleAuth } from 'google-auth-library';
+export { GoogleAuth } from 'google-auth-library';
+
+/**
+ * Provider-agnostic tool-calling abstraction.
+ *
+ * The agent loop is written against `ToolProvider`, not against any one
+ * vendor SDK. Two adapters live alongside this file — `claude.ts`
+ * (Anthropic Messages on Vertex) and `gemini.ts` (Google Gemini on
+ * Vertex) — and they translate between this normalized shape and each
+ * vendor's wire format.
+ *
+ * Design notes:
+ *
+ *  - `NormalizedMessage` carries the full conversation turn-by-turn:
+ *    user prompts, assistant replies (text + tool calls), and the
+ *    matching tool results. Storing both `id` and `name` on every tool
+ *    call lets us survive Gemini's name-keyed function responses (no
+ *    IDs) and Anthropic's id-keyed `tool_result` blocks with one shape.
+ *
+ *  - `SystemBlock.cached` is advisory: Anthropic uses it to mark
+ *    `cache_control: ephemeral`, Gemini ignores it (Vertex Gemini
+ *    auto-caches stable prefixes). Both still see the same text, in
+ *    the same order — semantics are preserved across the swap.
+ *
+ *  - The schema we accept here is the JSON Schema declared on each
+ *    tool. The Gemini-side adapter calls `toGeminiSchema()` to
+ *    translate `oneOf` → `anyOf`, `const` → enum, etc.
+ *
+ *  - `SystemBlock` and `ToolSchema` are owned by `../tools/types` so the
+ *    package has a single source of truth. We re-export them from this
+ *    module so callers can keep `import { SystemBlock } from './types'`.
+ */
+
+type ToolProviderId = 'claude' | 'gemini';
+/** A single tool invocation requested by the model. */
+type NormalizedToolCall = {
+    /** Stable per-turn id we generate or echo from the provider. */
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+/** A single tool result fed back to the model on the next turn. */
+type NormalizedToolResult = {
+    /** Matches the corresponding NormalizedToolCall.id from the prior turn. */
+    toolCallId: string;
+    toolName: string;
+    isError: boolean;
+    /** JSON-stringified result body. */
+    content: string;
+};
+type NormalizedMessage = {
+    role: 'user';
+    text: string;
+} | {
+    role: 'assistant';
+    /** Free text the model emitted (zero-or-more text blocks joined as-is). */
+    text: string;
+    toolCalls: NormalizedToolCall[];
+    /**
+     * Vendor-opaque blob the producing adapter wants echoed back on
+     * the next turn. Used by the Gemini adapter to preserve the raw
+     * response parts (incl. `thoughtSignature` + `thought` summaries)
+     * which Gemini 2.5+/3.x thinking mode REQUIRES round-tripped, or
+     * the next request fails with `INVALID_ARGUMENT: missing
+     * thought_signature`. Other adapters can ignore.
+     */
+    providerData?: unknown;
+} | {
+    role: 'tool';
+    results: NormalizedToolResult[];
+};
+type AgentTurnInput = {
+    system: SystemBlock[];
+    tools: ToolSchema[];
+    messages: NormalizedMessage[];
+    maxOutputTokens: number;
+};
+type AgentTurn = {
+    /** Concatenated text the model emitted in this turn (may be empty). */
+    text: string;
+    /** Tool calls the model wants run. Empty means the model ended its turn. */
+    toolCalls: NormalizedToolCall[];
+    /** Vendor stop reason, normalized loosely. */
+    stopReason: 'tool_use' | 'end_turn' | 'max_tokens' | 'other';
+    /** Opaque vendor data the agent loop should attach to the assistant message and replay on the next turn. See `NormalizedMessage.providerData`. */
+    providerData?: unknown;
+};
+interface ToolProvider {
+    readonly id: ToolProviderId;
+    /** Run one model turn. Adapters MUST NOT throw on tool errors — those are passed back as `tool` results on the next call. */
+    runTurn(input: AgentTurnInput): Promise<AgentTurn>;
+}
+
+/**
+ * Agent tool loop.
+ *
+ * Drives an injected `ToolProvider` (Claude on Vertex, Gemini on Vertex,
+ * or any future adapter that satisfies the contract) with a host-supplied
+ * tool catalogue until the model invokes the terminal `present` tool (or
+ * hits a hard stop without calling it). Returns the structured
+ * `PresentPayload`; the prose narrator pass happens in the route handler.
+ *
+ * Caching: the system prompt blocks are passed through as the host built
+ * them. Blocks marked `cached: true` become Anthropic ephemeral cache
+ * markers; Gemini ignores the flag and relies on Vertex's automatic prefix
+ * caching. Either way a follow-up question within the cache TTL only pays
+ * for the question + tool turns.
+ *
+ * This package's loop is project-agnostic: tools, prompts, and the
+ * provider instance are all injected via `AgentInput`. The host owns the
+ * registry (`ToolsPort.tools`), the system blocks (`ToolsPort.buildSystemBlocks`),
+ * and the constructed provider (resolved through `toolProviders[id].createProvider`).
+ */
+
+declare const DEFAULT_MAX_TOOL_TURNS = 12;
+declare const DEFAULT_MAX_OUTPUT_TOKENS = 4096;
+type AgentResult = {
+    ok: true;
+    structured: PresentPayload;
+    toolCallCount: number;
+    transcript: TranscriptEntry[];
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    transcript: TranscriptEntry[];
+};
+type TranscriptEntry = {
+    kind: 'user';
+    text: string;
+} | {
+    kind: 'assistant_text';
+    text: string;
+} | {
+    kind: 'tool_use';
+    name: string;
+    input: unknown;
+} | {
+    kind: 'tool_result';
+    name: string;
+    result: unknown;
+};
+type AgentInput<S = unknown> = {
+    question: string;
+    ctx: ToolContext<S>;
+    /** Injected tool registry (host-supplied via ToolsPort). MUST include the terminal `present` tool. */
+    tools: Record<string, ToolDefinition<unknown, S>>;
+    /** Pre-built system blocks (host-supplied via ToolsPort.buildSystemBlocks). */
+    systemBlocks: SystemBlock[];
+    /** Constructed ToolProvider — caller resolves the right one via toolProviders[id].createProvider({...}). */
+    provider: ToolProvider;
+    /** Optional caps. Default both. */
+    maxToolTurns?: number;
+    maxOutputTokens?: number;
+};
+declare function runAgent<S = unknown>(input: AgentInput<S>): Promise<AgentResult>;
+
+/**
+ * Tool-calling provider registry.
+ *
+ * The agent loop and the routes layer drive providers through this
+ * factory; vendor specifics stay inside `claude.ts` / `gemini.ts`.
+ * Adding a third provider would slot in alongside without further
+ * changes to the agent loop.
+ *
+ * The host injects credentials (a `GoogleAuth` instance), the GCP
+ * project id, the default region, and the pinned model ids via
+ * `VertexPort`. A per-request region override flows in as
+ * `ProviderInitOpts.location` so admin-managed `aiSettings.gcpLocation`
+ * can flip Vertex regions without rebuilding the registry.
+ */
+
+type ProviderInitOpts = {
+    /** Pre-built GoogleAuth instance (host-supplied). */
+    auth: GoogleAuth;
+    /** GCP project id. */
+    projectId: string;
+    /** Default Vertex region used when `location` is omitted. */
+    defaultLocation: string;
+    /** Vertex model ids pinned by the host. */
+    modelIds: {
+        claude: string;
+        gemini: string;
+    };
+    /** Per-request override for `aiSettings.gcpLocation`. Falls back to defaultLocation. */
+    location?: string;
+};
+type ToolProviderDef = {
+    id: ToolProviderId;
+    label: string;
+    description: string;
+    createProvider(opts: ProviderInitOpts): ToolProvider;
+};
+declare const toolProviders: ToolProviderDef[];
+declare function getToolProvider(id: string): ToolProviderDef | undefined;
+
+/**
+ * Narrators — the prose pass that turns a structured answer into the
+ * paragraph_brief block's flowing text. The agent's tool loop decides
+ * WHAT to say (key_facts); the narrator decides HOW to say it.
+ *
+ * Three implementations:
+ *   - streamClaudeNarration  — Anthropic Messages on GCP Vertex
+ *   - streamGrokNarration    — xAI Grok via Vertex's OpenAI-compatible endpoint
+ *   - streamGeminiNarration  — Google Gemini on GCP Vertex
+ *
+ * All three expose the same shape: an async generator yielding raw text
+ * deltas. The route layer is responsible for any SSE framing on top — the
+ * package keeps the streaming primitive provider-agnostic.
+ *
+ * Lifted from the host's `src/ai/narrators/`. The host's class-based
+ * `NarrativeProvider` interface and `createNarrativeProvider` factory are
+ * replaced with plain streaming functions plus a `getNarrator(id)` lookup.
+ * Every credential field comes in as an explicit argument; no `@/...`
+ * imports remain.
+ */
+
+type NarratorId = 'claude' | 'gemini' | 'grok';
+
+/**
+ * Common lifecycle hooks shared across every route factory. Hooks return
+ * `Response | null`: a non-null Response short-circuits the request (the
+ * factory returns it untouched), `null` continues the normal flow.
+ */
+type RouteHooks$1<S> = {
+    /** Runs before auth. Return a Response to short-circuit (e.g. 503 during shutdown). */
+    onRequest?(req: Request): Promise<Response | null>;
+    /** Runs after successful auth. Return a Response to short-circuit (e.g. 429 rate-limited). */
+    onAuthenticated?(args: {
+        req: Request;
+        scope: S;
+        userId: number;
+    }): Promise<Response | null>;
+};
+/**
+ * Streaming-route hooks. Adds three lifecycle points specific to the SSE
+ * `agent-custom` path so consumers can plumb in per-request resources
+ * (e.g. SQL view creation/cleanup keyed off a fresh sessionId).
+ */
+type AgentCustomHooks$1<S> = RouteHooks$1<S> & {
+    /**
+     * Generate the per-request session id used in ToolContext (and any
+     * project-specific resources keyed off it, e.g. SQL view names).
+     * Defaults to a random URL-safe id (16 hex chars from a UUID).
+     */
+    generateSessionId?(args: {
+        scope: S;
+        userId: number;
+        chatSessionId: number | null;
+    }): string | Promise<string>;
+    /**
+     * Runs once after the session id is resolved, before the agent loop.
+     * Throw to abort the request (the route catches and surfaces the error
+     * via the SSE error frame + persistence).
+     */
+    onSessionStart?(args: {
+        scope: S;
+        sessionId: string;
+        userId: number;
+    }): Promise<void>;
+    /**
+     * Always runs in `finally`, regardless of how the stream ended.
+     * The route never throws out of this hook — its errors are logged via
+     * ctx.logger but don't surface to the client.
+     */
+    onSessionEnd?(args: {
+        scope: S;
+        sessionId: string;
+        userId: number;
+        cause: 'complete' | 'error' | 'abort';
+    }): Promise<void>;
+};
+type AgentCustomRouteCtx<S> = {
+    persistence: PersistencePort;
+    auth: AuthPort<S>;
+    scope: ScopePort<S>;
+    tools: ToolsPort;
+    vertex: VertexPort;
+    logger?: LoggerPort;
+    /**
+     * Resolve which narrator to use for prose generation. Default:
+     * `() => aiSettings.toolProvider` (which is only ever `claude` or
+     * `gemini` from the registry). Hosts that surface a per-user
+     * `narrative_provider` (e.g. allowing `grok`) wire their existing
+     * lookup here.
+     */
+    resolveNarratorId?: (scope: S) => Promise<NarratorId>;
+    /**
+     * Optional lifecycle hooks. See `AgentCustomHooks` for the available
+     * extension points (shutdown gating, rate limiting, per-request
+     * resource setup/teardown).
+     */
+    hooks?: AgentCustomHooks$1<S>;
+};
+declare function createAgentCustomRoutes<S>(ctx: AgentCustomRouteCtx<S>): {
+    /** Next.js-compatible POST handler. */
+    POST: (req: Request) => Promise<Response>;
+};
+
+/**
+ * `chat-sessions` route factory — host-agnostic CRUD for chat sessions.
+ *
+ * Mounts at `/api/chat/sessions` (list+create) and `/api/chat/sessions/[id]`
+ * (get one with messages, rename, delete). Auth and persistence cross the
+ * boundary as ports; the package never touches a DB or session adapter.
+ *
+ * Wire format mirrors the host's pre-extraction Next route handlers so the
+ * existing UI keeps working unchanged when the host swaps to these factories.
+ */
+
+type ChatSessionsRouteCtx<S> = {
+    persistence: PersistencePort;
+    auth: AuthPort<S>;
+    logger?: LoggerPort;
+    /**
+     * Optional pre-auth / post-auth hooks (e.g. shutdown gate, rate
+     * limiting). The streaming-specific hooks on `AgentCustomHooks` are
+     * ignored here — only `onRequest` and `onAuthenticated` apply.
+     */
+    hooks?: RouteHooks$1<S>;
+};
+declare function createChatSessionsRoutes<S>(ctx: ChatSessionsRouteCtx<S>): {
+    list: {
+        /**
+         * `GET /api/chat/sessions` — caller's recent sessions, newest first,
+         * capped at 100. Response: `{ sessions: [{ id, title, createdAt, updatedAt }] }`.
+         */
+        GET: (req: Request) => Promise<Response>;
+        /**
+         * `POST /api/chat/sessions` — body `{ title?: string }`. Trims and caps
+         * title at 200 chars; defaults to "New chat" when blank.
+         * Response: `{ session: { id, title, createdAt, updatedAt } }`.
+         */
+        POST: (req: Request) => Promise<Response>;
+    };
+    detail: {
+        /**
+         * `GET /api/chat/sessions/[id]` — session metadata + ordered messages.
+         * 404 when the id doesn't exist or doesn't belong to the caller (we never
+         * differentiate the two, to avoid leaking the id space).
+         * Response: `{ session: { id, title, createdAt, updatedAt },
+         *             messages: [{ id, role, question, blocks, prose, errorJson, createdAt }] }`.
+         */
+        GET: (req: Request, params: {
+            id: string;
+        }) => Promise<Response>;
+        /**
+         * `PATCH /api/chat/sessions/[id]` — rename. Body `{ title: string }`,
+         * trimmed and capped at 200 chars. Response: `{ ok: true }`.
+         */
+        PATCH: (req: Request, params: {
+            id: string;
+        }) => Promise<Response>;
+        /**
+         * `DELETE /api/chat/sessions/[id]` — drop session and its messages.
+         * Response: `{ ok: true }`.
+         */
+        DELETE: (req: Request, params: {
+            id: string;
+        }) => Promise<Response>;
+    };
+};
+
+/**
+ * `/api/admin/ai-settings` route factory — global AI configuration (super_admin only).
+ *
+ * Three patchable fields on the singleton settings row:
+ *   - `tool_provider` — vendor that drives the agent tool loop. Validated
+ *     against the registered `toolProviders` registry passed in via ctx.
+ *   - `gcp_location` — the Vertex region every provider call hits. Stays
+ *     a fixed list ('us-east5', 'global') because those are the only
+ *     regions Claude/Gemini are published in on Vertex.
+ *   - `chat_interface` — which chat UI module renders globally. Validated
+ *     against the `chatInterfaces` registry passed in via ctx (the actual
+ *     registry lives in `@firstlovecenter/ai-chat/ui` so the host wires it through;
+ *     the route stays free of UI imports).
+ *
+ * Wire format is snake_case to preserve byte-for-byte parity with the
+ * host route the package replaces — existing host UIs keep working
+ * unmodified.
+ */
+
+type AdminSettingsRouteCtx<S> = {
+    persistence: PersistencePort;
+    auth: AuthPort<S>;
+    /** Registered tool providers (default: built-in toolProviders array). */
+    toolProviders: {
+        id: string;
+        label?: string;
+        description?: string;
+    }[];
+    /** Registered chat interface ids (host or UI module supplies the list). */
+    chatInterfaces: {
+        id: string;
+    }[];
+    logger?: LoggerPort;
+    /**
+     * Optional pre-auth / post-auth hooks (e.g. shutdown gate, rate
+     * limiting). Streaming-specific hooks are not applicable here.
+     */
+    hooks?: RouteHooks$1<S>;
+};
+declare function createAdminSettingsRoutes<S>(ctx: AdminSettingsRouteCtx<S>): {
+    GET: (req: Request) => Promise<Response>;
+    PATCH: (req: Request) => Promise<Response>;
+};
+
+/** Default ids that match the components shipped in `@firstlovecenter/ai-chat/ui`. */
+declare const BUILTIN_CHAT_INTERFACE_IDS: readonly ["custom", "vercel"];
+type ChatInterfaceRegistryEntry = {
+    id: string;
+};
+type ConfigureAiChatOpts<S = unknown> = {
+    persistence: PersistencePort;
+    auth: AuthPort<S>;
+    scope: ScopePort<S>;
+    tools: ToolsPort;
+    vertex: VertexPort;
+    logger?: LoggerPort;
+    /**
+     * Resolve which narrator drives the prose pass. Defaults to the
+     * current `aiSettings.toolProvider` (claude → claude narrator, gemini →
+     * gemini narrator). Override when the host stores a per-user choice.
+     */
+    resolveNarratorId?: (scope: S) => Promise<'claude' | 'gemini' | 'grok'>;
+    /**
+     * Chat-interface ids the admin route accepts. Defaults to
+     * BUILTIN_CHAT_INTERFACE_IDS (custom, vercel). Hosts that ship only one
+     * UI can subset; hosts that register a new one extend.
+     */
+    chatInterfaces?: ChatInterfaceRegistryEntry[];
+    /**
+     * Additional tool-calling providers beyond the built-in claude/gemini.
+     * Merged into the registry the admin route validates against.
+     */
+    extraToolProviders?: ToolProviderDef[];
+    /**
+     * Optional lifecycle hooks shared across all three route factories.
+     * The full superset (`AgentCustomHooks`) covers the SSE chat route;
+     * `chatSessions` and `adminSettings` only consume the
+     * `onRequest` / `onAuthenticated` subset.
+     *
+     * Common host plumbing this enables (without forking the package):
+     *   - `onRequest`        — shutdown gating (503 + Retry-After).
+     *   - `onAuthenticated`  — per-user rate limiting (429 + Retry-After).
+     *   - `generateSessionId`— project-specific session ids (e.g. SQL view names).
+     *   - `onSessionStart`   — per-request resource setup (e.g. CREATE VIEW).
+     *   - `onSessionEnd`     — cleanup (always-runs, never throws out).
+     */
+    hooks?: AgentCustomHooks$1<S>;
+};
+type AiChatRuntime<S = unknown> = {
+    /**
+     * Pre-bound agent loop. Most hosts call routes instead — but the bound
+     * runner is exposed for non-HTTP entry points (jobs, eval harnesses).
+     */
+    runAgent: (input: {
+        question: string;
+        ctx: ToolContext<S>;
+        /** Override the provider id picked from `aiSettings.toolProvider`. */
+        providerId?: string;
+        /** Override the location picked from `aiSettings.gcpLocation`. */
+        location?: string;
+        maxToolTurns?: number;
+        maxOutputTokens?: number;
+    }) => Promise<AgentResult>;
+    routes: {
+        agentCustom: ReturnType<typeof createAgentCustomRoutes<S>>;
+        chatSessions: ReturnType<typeof createChatSessionsRoutes<S>>;
+        adminSettings: ReturnType<typeof createAdminSettingsRoutes<S>>;
+    };
+    registries: {
+        toolProviders: ToolProviderDef[];
+        chatInterfaces: ChatInterfaceRegistryEntry[];
+    };
+};
+declare function configureAiChat<S = unknown>(opts: ConfigureAiChatOpts<S>): AiChatRuntime<S>;
+
+type RouteHooks<S> = RouteHooks$1<S>;
+type AgentCustomHooks<S> = AgentCustomHooks$1<S>;
+
+export { type AgentCustomHooks, type AgentInput, type AgentResult, type AiChatRuntime, AuthPort, BUILTIN_CHAT_INTERFACE_IDS, type ChatInterfaceRegistryEntry, type ConfigureAiChatOpts, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_MAX_TOOL_TURNS, LoggerPort, PersistencePort, PresentPayload, type ProviderInitOpts, type RouteHooks, ScopePort, SystemBlock, ToolContext, ToolDefinition, type ToolProviderDef, ToolSchema, ToolsPort, type TranscriptEntry, VertexPort, configureAiChat, getToolProvider, runAgent, toolProviders };