@theoremjs/react 0.0.0-stage → 0.3.0

package/hooks/use-theorem-host.js

@@ -0,0 +1,117 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { toolCallsOf, toolSnapshotFromEvents } from '@theoremjs/agents/interface';
+import { clientFailure } from "../client/failure.js";
+import { continueGatedToolInvocation } from "../client/tool-resume.js";
+import { useDescribed } from "./use-described.js";
+function callId() {
+    return typeof crypto !== 'undefined' && 'randomUUID' in crypto
+        ? crypto.randomUUID()
+        : `call-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function withEvent(call, event) {
+    const events = [...call.events, event];
+    const progress = event.type === 'tool' && event.tool.phase === 'progress' ? event.tool.data : call.progress;
+    return { ...call, events, call: toolCallsOf(events)[0] ?? null, progress };
+}
+/**
+ * One host profile: describe it once, then `run(name, input)` any of its tools
+ * as often as needed, and answer the gates a call pauses on. `run` returns the
+ * call's id at once; calls run side by side, and `cancel` stops one.
+ */
+export function useTheoremHost(transport) {
+    const { iface, describeFailure } = useDescribed(transport);
+    const [calls, setCalls] = useState([]);
+    const running = useRef(new Map());
+    // Tools the user allowed for the rest of the page, for a host that replays paused calls.
+    const permissions = useRef([]);
+    const latest = useRef(calls);
+    latest.current = calls;
+    useEffect(() => {
+        const open = running.current;
+        return () => {
+            for (const controller of open.values())
+                controller.abort();
+        };
+    }, []);
+    const update = useCallback((id, change) => {
+        setCalls((previous) => previous.map((call) => (call.id === id ? change(call) : call)));
+    }, []);
+    /** Streams one request's events into the call, then marks it settled or failed. */
+    const stream = useCallback(async (id, send) => {
+        const controller = new AbortController();
+        running.current.set(id, controller);
+        const started = performance.now();
+        update(id, (call) => ({ ...call, isRunning: true, failure: null }));
+        try {
+            await send((event) => {
+                if (event.type === 'unsupported' || event.type === 'malformed')
+                    return;
+                update(id, (call) => withEvent(call, event));
+            }, controller.signal);
+            update(id, (call) => ({ ...call, isRunning: false, answering: null, elapsedMs: performance.now() - started }));
+        }
+        catch (err) {
+            const failure = controller.signal.aborted ? null : clientFailure(err);
+            update(id, (call) => ({ ...call, isRunning: false, answering: null, failure, elapsedMs: performance.now() - started }));
+        }
+        finally {
+            if (running.current.get(id) === controller)
+                running.current.delete(id);
+        }
+    }, [update]);
+    const run = useCallback((name, input) => {
+        const id = callId();
+        setCalls((previous) => [
+            {
+                id,
+                name,
+                input,
+                events: [],
+                call: null,
+                progress: undefined,
+                isRunning: true,
+                failure: null,
+                answering: null,
+                startedAt: Date.now(),
+                elapsedMs: null,
+            },
+            ...previous,
+        ]);
+        void stream(id, (onEvent, signal) => transport.call({ name, input }, onEvent, signal));
+        return id;
+    }, [stream, transport]);
+    const answer = useCallback(async (id, resolution) => {
+        const held = latest.current.find((call) => call.id === id);
+        const state = held?.call?.state;
+        if (!held?.call || state?.phase !== 'gate')
+            return;
+        const gateId = held.call.callId;
+        const reply = continueGatedToolInvocation({
+            toolName: held.name,
+            gate: state.gate,
+            sessionPermissions: permissions.current,
+            resolution,
+        });
+        if (reply.decision === 'approve')
+            permissions.current = reply.sessionPermissions;
+        const snapshot = toolSnapshotFromEvents(held.events);
+        update(id, (call) => ({ ...call, answering: resolution.action }));
+        await stream(id, (onEvent, signal) => transport.invoke({
+            gateId,
+            decision: reply.decision,
+            ...(reply.decision === 'approve' && reply.secret !== undefined ? { secret: reply.secret } : {}),
+            // A host without sessions (the playground) replays the paused call; others ignore it.
+            replay: {
+                name: held.name,
+                input: held.input,
+                sessionPermissions: permissions.current,
+                ...(snapshot ? { snapshot } : {}),
+            },
+        }, onEvent, signal));
+    }, [stream, transport, update]);
+    const cancel = useCallback((id) => {
+        running.current.get(id)?.abort();
+        running.current.delete(id);
+    }, []);
+    return { iface, describeFailure, calls, run, answer, cancel };
+}

package/hooks/use-theorem-interface.d.ts

@@ -0,0 +1,19 @@
+import type { ProfileInterface } from '@theoremjs/agents/interface';
+import { type ClientFailure } from '../client/failure.ts';
+import type { TheoremTransport } from '../client/transport.ts';
+/** `failure` is worded with the default lexicon: the profile's is not known until it loads. */
+export type TheoremInterfaceState = {
+    status: 'loading';
+    iface: null;
+    failure: null;
+} | {
+    status: 'ready';
+    iface: ProfileInterface;
+    failure: null;
+} | {
+    status: 'error';
+    iface: null;
+    failure: ClientFailure;
+};
+/** Ask the transport for the host profile's client-safe interface. */
+export declare function useTheoremInterface(transport: TheoremTransport): TheoremInterfaceState;

package/hooks/use-theorem-interface.js

@@ -0,0 +1,25 @@
+import { useEffect, useState } from 'react';
+import { clientFailure } from "../client/failure.js";
+const LOADING = { status: 'loading', iface: null, failure: null };
+/** Ask the transport for the host profile's client-safe interface. */
+export function useTheoremInterface(transport) {
+    const [state, setState] = useState(LOADING);
+    useEffect(() => {
+        const controller = new AbortController();
+        // A new transport keeps the last interface up until it describes itself, so swapping one
+        // in (a recompiled playground profile) doesn't blank the chat to a spinner.
+        setState((previous) => (previous.status === 'ready' ? previous : LOADING));
+        transport.describe(controller.signal).then((iface) => {
+            if (!controller.signal.aborted)
+                setState({ status: 'ready', iface, failure: null });
+        }, (err) => {
+            if (controller.signal.aborted)
+                return;
+            setState({ status: 'error', iface: null, failure: clientFailure(err) });
+        });
+        return () => {
+            controller.abort();
+        };
+    }, [transport]);
+    return state;
+}

package/hooks/use-trace-records.d.ts

@@ -0,0 +1,4 @@
+import type { TraceRecord } from '@theoremjs/agents';
+import type { TraceFeed } from '../client/trace-feed.ts';
+/** The records a feed has delivered so far; none without a feed. */
+export declare function useTraceRecords(feed: TraceFeed | undefined): readonly TraceRecord[];

package/hooks/use-trace-records.js

@@ -0,0 +1,7 @@
+import { useSyncExternalStore } from 'react';
+const NONE = [];
+const noSubscription = () => () => { };
+/** The records a feed has delivered so far; none without a feed. */
+export function useTraceRecords(feed) {
+    return useSyncExternalStore(feed?.subscribe ?? noSubscription, feed?.records ?? (() => NONE));
+}

package/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Headless React bindings for Theorem — hooks and a transport, no styling.
+ *
+ * - `@theoremjs/react`         hooks + transport (this entry)
+ * - `@theoremjs/react/ui`      Astryx chat UI built on these hooks
+ * - `@theoremjs/react/server`  `createTheoremHandler` (and `createTheoremDecisionHandler`, `createTheoremHostHandler`) for the host side
+ *
+ * @module
+ */
+export * from './client/index.ts';
+export { type ChatSnapshot, type SentTurn, type UseTheoremChatOptions, useTheoremChat, } from './hooks/use-theorem-chat.ts';
+export { type TheoremDecisionState, useTheoremDecision } from './hooks/use-theorem-decision.ts';
+export { type TheoremHostCall, type TheoremHostState, useTheoremHost } from './hooks/use-theorem-host.ts';
+export { type TheoremInterfaceState, useTheoremInterface } from './hooks/use-theorem-interface.ts';

package/index.js

@@ -0,0 +1,14 @@
+/**
+ * Headless React bindings for Theorem — hooks and a transport, no styling.
+ *
+ * - `@theoremjs/react`         hooks + transport (this entry)
+ * - `@theoremjs/react/ui`      Astryx chat UI built on these hooks
+ * - `@theoremjs/react/server`  `createTheoremHandler` (and `createTheoremDecisionHandler`, `createTheoremHostHandler`) for the host side
+ *
+ * @module
+ */
+export * from "./client/index.js";
+export { useTheoremChat, } from "./hooks/use-theorem-chat.js";
+export { useTheoremDecision } from "./hooks/use-theorem-decision.js";
+export { useTheoremHost } from "./hooks/use-theorem-host.js";
+export { useTheoremInterface } from "./hooks/use-theorem-interface.js";

package/live.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Live (voice / video) runner, on the Astryx UI in the Theorem theme.
+ *
+ * @module
+ */
+export type { LiveConnection } from './client/live-client.ts';
+export type { LiveRunnerProps } from './ui/LiveRunner.tsx';
+export { LiveRunner } from './ui/LiveRunner.tsx';

package/live.js

@@ -0,0 +1,10 @@
+/**
+ * Live (voice / video) runner, on the Astryx UI in the Theorem theme.
+ *
+ * @module
+ */
+// Astryx's documented order: reset → components → theme.
+import '@astryxdesign/core/reset.css';
+import '@astryxdesign/core/astryx.css';
+import './ui/built/theme.css';
+export { LiveRunner } from "./ui/LiveRunner.js";

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/masudl-hub/theoremai",
+    "directory": "react"
+  },
+  "sideEffects": [
+    "**/*.css",
+    "./live.js",
+    "./ui/index.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./ui": {
+      "types": "./ui/index.d.ts",
+      "default": "./ui/index.js"
+    },
+    "./ui/theme": {
+      "types": "./ui/theorem-theme.d.ts",
+      "default": "./ui/theorem-theme.js"
+    },
+    "./ui/icons": {
+      "types": "./ui/icons.d.ts",
+      "default": "./ui/icons.js"
+    },
+    "./server": {
+      "types": "./server/mod.d.ts",
+      "default": "./server/mod.js"
+    },
+    "./live": {
+      "types": "./live.d.ts",
+      "default": "./live.js"
+    },
+    "./client": {
+      "types": "./client/index.d.ts",
+      "default": "./client/index.js"
+    },
+    "./styles/*": "./styles/*"
+  },
+  "dependencies": {
+    "@tabler/icons-react": "^3.46.0",
+    "intl-messageformat": "^11.2.9",
+    "recharts": "^3.10.1"
+  },
+  "peerDependencies": {
+    "@astryxdesign/core": "0.6.3",
+    "@astryxdesign/theme-neutral": "0.6.3",
+    "@stylexjs/stylex": "0.19.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@theoremjs/agents": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@astryxdesign/core": {
+      "optional": true
+    },
+    "@astryxdesign/theme-neutral": {
+      "optional": true
+    },
+    "@stylexjs/stylex": {
+      "optional": true
+    }
+  }
+}

package/server/credential-store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tool credentials for `createTheoremHandler`, held on the server by session.
+ *
+ * The browser never holds a credential: the host's OAuth callback route saves
+ * a token here, a key the user types at a gate is saved here as it arrives,
+ * and every turn reads a slot from here only when a tool that signs in runs. A
+ * refreshed OAuth token is saved here before the call goes on.
+ *
+ * @module
+ */
+import type { ToolCredential } from '@theoremjs/agents/kernel';
+import { type MemorySessionStoreOptions } from './session-store.ts';
+/** A session's credentials, keyed by the tools' auth slot. */
+export type TheoremCredentials = Record<string, ToolCredential>;
+/**
+ * Where tool credentials live. The default is process memory: use a vault or
+ * an encrypted row when requests can reach different instances, and so the
+ * credentials outlive the process.
+ */
+export interface TheoremCredentialStore {
+    load(sessionId: string): TheoremCredentials | undefined | Promise<TheoremCredentials | undefined>;
+    save(sessionId: string, credentials: TheoremCredentials): void | Promise<void>;
+}
+export declare function createMemoryCredentialStore(options?: MemorySessionStoreOptions): TheoremCredentialStore;

package/server/credential-store.js

@@ -0,0 +1,14 @@
+/**
+ * Tool credentials for `createTheoremHandler`, held on the server by session.
+ *
+ * The browser never holds a credential: the host's OAuth callback route saves
+ * a token here, a key the user types at a gate is saved here as it arrives,
+ * and every turn reads a slot from here only when a tool that signs in runs. A
+ * refreshed OAuth token is saved here before the call goes on.
+ *
+ * @module
+ */
+import { createMemorySessionMap } from "./session-store.js";
+export function createMemoryCredentialStore(options = {}) {
+    return createMemorySessionMap(options);
+}

package/server/decision-handler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One Web-standard handler that serves a decision profile to `<TheoremDecision />`.
+ *
+ * - `GET  <base>`        → `{ interface }` the profile's handle, contract, and questions
+ * - `POST <base>/decide` → `{ result }` the answers for the posted `{ state }`
+ *
+ * The host owns the questions: the browser sends only the state, so a visitor
+ * can't spend the host's key asking questions of their own.
+ *
+ * @module
+ */
+import { type DecisionProfile, type DecisionQuestion, type KeyVault, type TraceSink } from '@theoremjs/agents';
+import type { DecisionProfileDefinition } from '@theoremjs/agents/kernel';
+export type TheoremDecisionHandlerOptions = {
+    /** Decision profile to serve. Registered with the kernel when the handler is created. */
+    profile: DecisionProfile | DecisionProfileDefinition;
+    /** The questions every decision asks, by id. */
+    questions: Record<string, DecisionQuestion>;
+    /** The host's keys by slot; the profile's key slot reads from it. */
+    vault?: KeyVault;
+    fetch?: typeof globalThis.fetch;
+    /** Replaces the profile's `observability.writeTo` for every decision. */
+    sink?: TraceSink;
+    /** Host metadata kept on each decision's trace record, e.g. the signed-in user. */
+    metadata?: (request: Request) => Record<string, unknown> | undefined;
+    /**
+     * 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.
+     */
+    onError?: (err: unknown, ctx: {
+        request: Request;
+    }) => void;
+};
+export declare function createTheoremDecisionHandler(options: TheoremDecisionHandlerOptions): (request: Request) => Promise<Response>;

package/server/decision-handler.js

@@ -0,0 +1,55 @@
+/**
+ * One Web-standard handler that serves a decision profile to `<TheoremDecision />`.
+ *
+ * - `GET  <base>`        → `{ interface }` the profile's handle, contract, and questions
+ * - `POST <base>/decide` → `{ result }` the answers for the posted `{ state }`
+ *
+ * The host owns the questions: the browser sends only the state, so a visitor
+ * can't spend the host's key asking questions of their own.
+ *
+ * @module
+ */
+import { defineProfile, errorKind, lexiconText, publicError, registerProfile, runDecision, z, } from '@theoremjs/agents';
+import { caughtStatus, HTTP_METHOD } from '@theoremjs/agents/host';
+import { decisionInterface } from "../client/decision-transport.js";
+import { readBody } from "./handler.js";
+import { jsonResponse } from "./json-response.js";
+const decideBodySchema = z.object({ state: z.unknown() });
+function isDecide(request) {
+    return new URL(request.url).pathname.split('/').filter(Boolean).at(-1) === 'decide';
+}
+export function createTheoremDecisionHandler(options) {
+    const profile = defineProfile(options.profile);
+    if (profile.type !== 'decision') {
+        // lexicon-exempt: builder config error at setup; no user sees it
+        throw new Error(`createTheoremDecisionHandler serves type 'decision'; got type '${profile.type}'.`);
+    }
+    registerProfile(profile);
+    const iface = decisionInterface(profile, options.questions);
+    return async (request) => {
+        try {
+            if (request.method === 'GET' && !isDecide(request))
+                return jsonResponse(200, { interface: iface });
+            if (request.method !== 'POST' || !isDecide(request)) {
+                return jsonResponse(HTTP_METHOD, {
+                    error: lexiconText('error.request', {}, profile.lexicon),
+                    errorKind: 'request',
+                });
+            }
+            const body = await readBody(request, decideBodySchema);
+            const result = await runDecision({
+                profile: profile.id,
+                // The kernel checks the state is non-null JSON within the profile's size.
+                state: body.state,
+                questions: options.questions,
+                signal: request.signal,
+                metadata: options.metadata?.(request),
+            }, { vault: options.vault, fetch: options.fetch, sink: options.sink });
+            return jsonResponse(200, { result });
+        }
+        catch (err) {
+            options.onError?.(err, { request });
+            return jsonResponse(caughtStatus(err), { error: publicError(err, profile.lexicon), errorKind: errorKind(err) });
+        }
+    };
+}

package/server/handler.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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
+ *
+ * `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
+ *
+ * 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.
+ * 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 ClientTurnOptions } from '@theoremjs/agents/host';
+import type { z } from '@theoremjs/agents';
+import { type TheoremCredentialStore } from './credential-store.ts';
+import { 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;
+    /**
+     * Provider credentials passed to `createProvider`, 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. */
+    host?: (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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Forwarded to `forClient` when projecting events for the browser. */
+    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.
+     */
+    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'> & {
+    /** 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>): 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 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>;