@theoremjs/react 0.0.0-stage → 0.3.1

package/server/embedding-handler.d.ts

@@ -0,0 +1,33 @@
+import { type EmbeddingInput, type EmbeddingProfile, type EmbeddingProfileDefinition, type KeyVault, type ProviderHostOptions, type TraceSink, z } from '@theoremjs/agents';
+import type { ClientTurnOptions } from '@theoremjs/agents/host';
+export type TheoremEmbeddingHandlerOptions = {
+    profile: EmbeddingProfile | EmbeddingProfileDefinition;
+    vault?: KeyVault;
+    fetch?: typeof globalThis.fetch;
+    provider?: ProviderHostOptions | ((ctx: {
+        request: Request;
+        model?: string;
+    }) => ProviderHostOptions | Promise<ProviderHostOptions>);
+    sink?: TraceSink;
+    metadata?: (request: Request) => Record<string, unknown> | undefined;
+    clientEvents?: ClientTurnOptions;
+    onError?: (err: unknown, ctx: {
+        request: Request;
+    }) => void;
+};
+/** The body an embedding request posts: the input, and optionally the model and the task. */
+export declare const embedBodySchema: z.ZodObject<{
+    input: z.ZodUnknown;
+    model: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodEnum<{
+        document: "document";
+        query: "query";
+    }>>;
+}, z.core.$strip>;
+/** The body as the embedding request `runEmbedding` takes, less its profile. */
+export declare function embedRequest(body: z.infer<typeof embedBodySchema>): {
+    task?: "document" | "query" | undefined;
+    model?: string | undefined;
+    input: EmbeddingInput | readonly EmbeddingInput[];
+};
+export declare function createTheoremEmbeddingHandler(options: TheoremEmbeddingHandlerOptions): (request: Request) => Promise<Response>;

package/server/embedding-handler.js

@@ -0,0 +1,45 @@
+import { defineProfile, registerProfile, runEmbedding, z, } from '@theoremjs/agents';
+import { embeddingInterface } from "../client/embedding-transport.js";
+import { readBody } from "./handler.js";
+import { singleActionHandler } from "./single-action.js";
+/** The body an embedding request posts: the input, and optionally the model and the task. */
+export const embedBodySchema = z.object({
+    input: z.unknown(),
+    model: z.string().min(1).optional(),
+    task: z.enum(['query', 'document']).optional(),
+});
+/** The body as the embedding request `runEmbedding` takes, less its profile. */
+export function embedRequest(body) {
+    return {
+        input: body.input,
+        ...(body.model === undefined ? {} : { model: body.model }),
+        ...(body.task === undefined ? {} : { task: body.task }),
+    };
+}
+export function createTheoremEmbeddingHandler(options) {
+    const profile = defineProfile(options.profile);
+    if (profile.type !== 'embedding') {
+        throw new Error(`createTheoremEmbeddingHandler serves type 'embedding'; got type '${profile.type}'.`);
+    }
+    registerProfile(profile);
+    return singleActionHandler({
+        action: 'embed',
+        iface: embeddingInterface(profile),
+        labels: profile.labels,
+        clientEvents: options.clientEvents,
+        onError: options.onError,
+    }, async (request) => {
+        const body = await readBody(request, embedBodySchema);
+        const provider = typeof options.provider === 'function'
+            ? await options.provider({ request, model: body.model })
+            : options.provider;
+        return runEmbedding({
+            profile: profile.id,
+            ...embedRequest(body),
+            signal: request.signal,
+            metadata: options.metadata?.(request),
+        }, provider
+            ? { ...provider, ...(options.sink ? { sink: options.sink } : {}) }
+            : { vault: options.vault, fetch: options.fetch, sink: options.sink });
+    });
+}

package/server/handler.d.ts

@@ -0,0 +1,152 @@
+import { type PageToolBroker } from './page-dispatch.ts';
+/**
+ * One Web-standard handler that serves a Theorem chat UI for a single profile.
+ *
+ * Mount it on any framework that speaks `Request` → `Response` (Deno.serve,
+ * Hono, Next route handlers, SvelteKit, Workers) under a catch-all route:
+ *
+ * - `GET  <base>`         → `{ interface }` client-safe profile interface
+ * - `POST <base>/turn`    → NDJSON turn events; a message sent while the reply
+ *                            waits on gates walks away from them first (`abandon`)
+ * - `POST <base>/invoke`  → NDJSON events for the user's answer to a paused tool call
+ * - `POST <base>/steer`   → inject messages into a running turn
+ * - `POST <base>/conversation` → the transcript and the paused reply, to draw
+ * - `POST <base>/rewind`  → `{ conversation, view }` the conversation cut after one block, and its new ref
+ *
+ * `createTheoremHostHandler` serves a host profile the same way, with no model:
+ *
+ * - `GET  <base>`         → `{ interface }` the tools the page may call, with their schemas
+ * - `POST <base>/call`    → NDJSON events for one call of one of those tools
+ * - `POST <base>/invoke`  → NDJSON events for the user's answer to a paused call
+ * - `POST <base>/page-result` → grant-correlated browser result receipt
+ *
+ * Trust boundary: the host owns the conversation and every decision that grants
+ * authority. Two stores keep them. The `conversationStore` owns the transcript,
+ * the history the model reads and the paused reply; the browser sends only what
+ * the person did now, with the opaque ref the store issued. The session store
+ * owns which paused calls may run (and with what input) and the tool
+ * permissions — request bodies can't grant any of them. A profile whose `providerContinuation.history` is
+ * `'stateless'` keeps no conversation, and takes no store.
+ * Tool credentials are held on the server too: a key the user types at a gate
+ * is sent once and saved, and no credential is ever sent back to the browser.
+ *
+ * @module
+ */
+import { type Profile, type ProfileDefinition, type ProviderHostOptions, type ToolGate, type z } from '@theoremjs/agents';
+import { type ClientTurnOptions } from '@theoremjs/agents/host';
+import { type TheoremConversationStore } from './conversation-store.ts';
+import { type TheoremCredentialStore } from './credential-store.ts';
+export { theoremSession, theoremSessionId } from './session-identity.ts';
+import { type TheoremSessionLimits } from './session-limits.ts';
+import { type SessionToolOperation, type TheoremSessionStore } from './session-store.ts';
+import { type SteerInbox } from './steer-inbox.ts';
+export type TheoremRequestContext = {
+    request: Request;
+    /** Selected model id, when the client picked one. */
+    model?: string;
+};
+export type TheoremHandlerOptions = {
+    /** Profile to serve. Registered with the kernel when the handler is created. */
+    profile: Profile | ProfileDefinition;
+    /**
+     * Host options for registered providers, or a factory for hosts that
+     * pick keys per request (BYOK, tenant vaults). Tools are registered by the host.
+     */
+    provider: ProviderHostOptions | ((ctx: TheoremRequestContext) => ProviderHostOptions | Promise<ProviderHostOptions>);
+    /**
+     * Opaque app context for tool handlers (`ctx.host`) — e.g. the signed-in user. A promise is
+     * awaited before the run starts, so the tools read what it settles to.
+     */
+    host?: (request: Request) => unknown;
+    /**
+     * What the host wants the agent to know on each turn: any JSON. The profile's
+     * `inputs.context.from` must list `server`. The page's own context arrives in the
+     * request and is read as untrusted; this one is the host's.
+     */
+    context?: (request: Request) => unknown;
+    /**
+     * Resolve the caller's session id — e.g. `${userId}:${conversationId}` from your
+     * auth. Return `undefined` to refuse the request (401). Default: an opaque id
+     * in an HttpOnly, SameSite=Lax cookie the handler issues on first contact.
+     */
+    session?: (request: Request) => string | undefined | Promise<string | undefined>;
+    /** Default: in-process memory. Use a shared store when requests can reach different instances. */
+    sessionStore?: TheoremSessionStore;
+    /**
+     * Where the chat's conversation lives: the transcript, the history the model
+     * reads and a reply paused on gates. Required unless the profile's
+     * `providerContinuation.history` is `'stateless'`, which keeps none and takes
+     * no store. `createMemoryConversationStore` for one instance,
+     * `createSealedConversationStore` to keep nothing on the server, or your
+     * own database.
+     */
+    conversationStore?: TheoremConversationStore;
+    /**
+     * How long a gate (permission, confirmation, sign-in) waits for its answer, in
+     * milliseconds. An answer after that is refused with `session.gate_expired`.
+     * Default: 30 minutes.
+     */
+    gateTtlMs?: number;
+    /** Retain settled tool results in milliseconds. Default: 24 hours. */
+    operationRetentionMs?: number;
+    /** Finite per-session bounds. Unresolved authority is never evicted to satisfy them. */
+    sessionLimits?: Partial<TheoremSessionLimits>;
+    /** Maximum UTF-8 request body bytes before JSON parsing. Default: 16 MiB. */
+    maxRequestBytes?: number;
+    pageToolBroker?: PageToolBroker;
+    /** Check current resource access before disclosing a saved tool result. This callback must be read-only. */
+    authorizeToolReplay?: (context: {
+        request: Request;
+        operation: Extract<SessionToolOperation, {
+            status: 'settled';
+        }>;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Tool credentials by session. Your OAuth callback route saves the token here
+     * under the same session id; every turn reads from here. Default: in-process
+     * memory — pass the same instance to your callback route.
+     */
+    credentialStore?: TheoremCredentialStore;
+    /**
+     * The sign-in URL for an OAuth gate: begin the flow with `createOAuthPkceFlow`,
+     * binding it to `sessionId`, and return its `authorizationUrl`. Without it an
+     * OAuth gate carries no sign-in URL.
+     */
+    authorizationUrl?: (challenge: Extract<ToolGate, {
+        kind: 'auth';
+    }>['authChallenge'], ctx: {
+        request: Request;
+        sessionId: string;
+    }) => string | Promise<string>;
+    /** Default: in-process memory. Use a shared store when turns and steers can land on different instances. */
+    steerInbox?: SteerInbox;
+    /**
+     * Who reads this host's replies, and what an event keeps for them: forwarded to `forClient`
+     * for each event and to `clientError` for a failure the handler catches.
+     */
+    clientEvents?: ClientTurnOptions;
+    /**
+     * Called with any error the handler catches, for reporting. Users read the
+     * profile's labels wording for the error's kind, never the error itself.
+     */
+    onError?: (err: unknown, ctx: {
+        request: Request;
+    }) => void;
+};
+/** A host profile runs no model, and takes no turns to steer. */
+export type TheoremHostHandlerOptions = Omit<TheoremHandlerOptions, 'profile' | 'provider' | 'steerInbox' | 'conversationStore'> & {
+    /** Host profile to serve. Registered with the kernel when the handler is created. */
+    profile: Extract<Profile, {
+        type: 'host';
+    }> | Extract<ProfileDefinition, {
+        type: 'host';
+    }>;
+};
+/** A JSON body checked against `schema`; a missing or malformed field is a `request` error (400). */
+export declare function readBody<T>(request: Request, schema: z.ZodType<T>, maxBytes?: number): Promise<T>;
+export declare function createTheoremHandler(options: TheoremHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * Serves a host profile to `<TheoremHost />`: the page calls the profile's tools
+ * directly, and every call runs through the kernel's gates and guardrails.
+ */
+export declare function createTheoremHostHandler(options: TheoremHostHandlerOptions): (request: Request) => Promise<Response>;