@theoremjs/react 0.3.0 → 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

@@ -1,3 +1,4 @@
+import { type PageToolBroker } from './page-dispatch.ts';
 /**
  * One Web-standard handler that serves a Theorem chat UI for a single profile.
  *
@@ -9,27 +10,35 @@
  *                            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 browser owns the conversation text; the server owns every
- * decision that grants authority. Tool permissions, which paused calls may run
- * (and with what input), and which provider interactions may be continued are
- * kept in a server-side session — request bodies can't grant any of them.
+ * 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 CreateProviderOptions, type ModelProvider, type Profile, type ProfileDefinition, type ToolGate } from '@theoremjs/agents';
+import { type Profile, type ProfileDefinition, type ProviderHostOptions, type ToolGate, type z } from '@theoremjs/agents';
 import { type ClientTurnOptions } from '@theoremjs/agents/host';
-import type { z } from '@theoremjs/agents';
+import { type TheoremConversationStore } from './conversation-store.ts';
 import { type TheoremCredentialStore } from './credential-store.ts';
-import { type TheoremSessionStore } from './session-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;
@@ -40,12 +49,21 @@ export type TheoremHandlerOptions = {
     /** Profile to serve. Registered with the kernel when the handler is created. */
     profile: Profile | ProfileDefinition;
     /**
-     * Provider credentials passed to `createProvider`, or a factory for hosts that
+     * 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: CreateProviderOptions | ((ctx: TheoremRequestContext) => ModelProvider | Promise<ModelProvider>);
-    /** Opaque app context for tool handlers (`ctx.host`) — e.g. the signed-in user. */
+    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
@@ -54,12 +72,35 @@ export type TheoremHandlerOptions = {
     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
@@ -79,18 +120,21 @@ export type TheoremHandlerOptions = {
     }) => string | Promise<string>;
     /** Default: in-process memory. Use a shared store when turns and steers can land on different instances. */
     steerInbox?: SteerInbox;
-    /** Forwarded to `forClient` when projecting events for the browser. */
+    /**
+     * 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 lexicon wording for the error's kind, never the error itself.
+     * 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'> & {
+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';
@@ -99,13 +143,7 @@ export type TheoremHostHandlerOptions = Omit<TheoremHandlerOptions, 'profile' |
     }>;
 };
 /** 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>): Promise<T>;
-/**
- * The session id the handler issued in its cookie, for a host route outside the
- * handler (an OAuth callback) that saves credentials under it. Hosts that pass
- * a `session` resolver use their own id instead.
- */
-export declare function theoremSessionId(request: Request): string | undefined;
+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