@theoremjs/react 0.0.0-stage → 0.3.1

package/client/transcript-schema.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The transcript's blocks as the wire carries them: the host stores them, and
+ * the browser reads the host's conversation back through this schema.
+ *
+ * @module
+ */
+import { z } from '@theoremjs/agents';
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+/** One transcript block, as a host stores it and the browser reads it back. */
+export declare const transcriptBlockSchema: z.ZodType<TranscriptBlock>;

package/client/transcript-schema.js

@@ -0,0 +1,120 @@
+/**
+ * The transcript's blocks as the wire carries them: the host stores them, and
+ * the browser reads the host's conversation back through this schema.
+ *
+ * @module
+ */
+import { reasoningPartSchema, TURN_STOP_KINDS, turnEventSchema, z, } from '@theoremjs/agents';
+import { guardrailEventSchema } from '@theoremjs/agents/guardrails';
+// why: The block shapes' event parts have one schema, the turn event's; a probe event reuses it.
+function eventPart(probe) {
+    return z.custom((value) => turnEventSchema.safeParse(probe(value)).success);
+}
+const TOOL_CALL_STATE_PHASES = [
+    'running',
+    'gate',
+    'complete',
+    'error',
+    'cancel',
+];
+const toolCallState = z.custom((value) => {
+    const parsed = turnEventSchema.safeParse({ type: 'tool', tool: value });
+    if (!parsed.success || parsed.data.type !== 'tool' || !('phase' in parsed.data.tool)) {
+        return false;
+    }
+    const { phase } = parsed.data.tool;
+    return TOOL_CALL_STATE_PHASES.some((statePhase) => statePhase === phase);
+});
+const argumentsRecord = z.record(z.string(), z.unknown());
+const toolCall = z.object({
+    operationId: z.string().optional(),
+    name: z.string(),
+    callId: z.string(),
+    arguments: argumentsRecord,
+    draft: z.string().optional(),
+    reasoning: z.array(reasoningPartSchema).optional(),
+    stepId: z.string().optional(),
+    edited: z.object({ from: argumentsRecord, to: argumentsRecord }).optional(),
+    activity: z.string().optional(),
+    activityPast: z.string().optional(),
+    outputDraft: z.string().optional(),
+    state: toolCallState.optional(),
+    startedAt: z.number().optional(),
+    endedAt: z.number().optional(),
+    artifacts: z.array(z.unknown()),
+});
+true;
+const turnStop = z.object({ kind: z.enum(TURN_STOP_KINDS), native: z.string().optional() });
+true;
+const blockId = { id: z.string() };
+const transcriptBlock = z.discriminatedUnion('kind', [
+    z.object({ ...blockId, kind: z.literal('user-text'), text: z.string() }),
+    z.object({
+        ...blockId,
+        kind: z.enum(['user-attachment', 'user-voice']),
+        name: z.string(),
+        mimeType: z.string(),
+        sizeBytes: z.number(),
+        data: z.string().optional(),
+    }),
+    z.object({ ...blockId, kind: z.literal('thought'), text: z.string() }),
+    z.object({ ...blockId, kind: z.literal('text'), text: z.string() }),
+    z.object({ ...blockId, kind: z.literal('tool'), tool: toolCall }),
+    z.object({
+        ...blockId,
+        kind: z.literal('structured'),
+        value: z.unknown(),
+        draft: z.string().optional(),
+    }),
+    z.object({
+        ...blockId,
+        kind: z.literal('media'),
+        mimeType: z.string(),
+        data: z.string().optional(),
+        url: z.string().optional(),
+        previewUrl: z.string().optional(),
+    }),
+    z.object({
+        ...blockId,
+        kind: z.literal('grounding'),
+        grounding: eventPart((grounding) => ({
+            type: 'grounding',
+            grounding,
+        })),
+    }),
+    z.object({
+        ...blockId,
+        kind: z.literal('citation'),
+        sources: eventPart((sources) => ({
+            type: 'citation',
+            sources,
+        })),
+        callId: z.string().optional(),
+    }),
+    z.object({
+        ...blockId,
+        kind: z.literal('evidence'),
+        evidence: eventPart((evidence) => ({
+            type: 'evidence',
+            evidence,
+        })),
+    }),
+    z.object({ ...blockId, kind: z.literal('guardrail'), guardrail: guardrailEventSchema }),
+    z.object({ ...blockId, kind: z.literal('error'), message: z.string() }),
+    z.object({
+        ...blockId,
+        kind: z.literal('turn-done'),
+        stop: turnStop.optional(),
+        tokens: eventPart((tokens) => ({
+            type: 'tokens',
+            tokens,
+        })).optional(),
+        interactionId: z.string().optional(),
+        compaction: z.boolean().optional(),
+        workedMs: z.number().optional(),
+        endedAt: z.number().optional(),
+    }),
+]);
+true;
+/** One transcript block, as a host stores it and the browser reads it back. */
+export const transcriptBlockSchema = transcriptBlock;

package/client/transcript-scroll.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Transcript scroll geometry — pure helpers.
+ */
+export declare function resolveScrollToBottomScrollTop(args: {
+    scrollHeight: number;
+    clientHeight: number;
+}): number;

package/client/transcript-scroll.js

@@ -0,0 +1,6 @@
+/**
+ * Transcript scroll geometry — pure helpers.
+ */
+export function resolveScrollToBottomScrollTop(args) {
+    return Math.max(0, args.scrollHeight - args.clientHeight);
+}

package/client/transport.d.ts

@@ -0,0 +1,264 @@
+import { type GateReference, type ToolGate } from '@theoremjs/agents';
+import type { PageDispatchResult } from './page-dispatch.ts';
+/**
+ * Transport contract between a Theorem chat UI and the host that runs turns.
+ *
+ * The browser never holds the profile: it asks the transport to `describe` the
+ * profile's client-safe interface, then streams turns / tool invokes through it.
+ * `createHttpTransport` speaks to `createTheoremHandler` (`@theoremjs/react/server`);
+ * hosts with their own wire format implement {@link TheoremTransport} directly.
+ *
+ * @module
+ */
+import { type ErrorKind, type TurnEvent, type TurnHistoryMessage, type TurnToolSnapshot, z } from '@theoremjs/agents';
+import { type ErrorCopies } from '@theoremjs/agents/guardrails';
+import { type ProfileInterface, type TranscriptBlock } from '@theoremjs/agents/interface';
+import type { PagePart } from './tool-resume.ts';
+import type { TraceFeed } from './trace-feed.ts';
+import { type MalformedEvent, type UnsupportedEvent, type WireLines } from './wire-line.ts';
+export type { MalformedEvent, UnsupportedEvent, WireLines } from './wire-line.ts';
+export type EncodedBlob = {
+    name: string;
+    mimeType: string;
+    data: string;
+};
+/** Turn input as sent over the wire (media is base64-encoded). */
+export type TheoremTurnInput = {
+    text?: string;
+    attachments?: EncodedBlob[];
+    voice?: EncodedBlob[];
+    /** The value chosen for each of the profile's `inputs.slots`. */
+    slots?: Record<string, string>;
+    /** What the page wants the agent to know: any JSON. The host reads it as untrusted. */
+    context?: unknown;
+};
+/**
+ * State only the client holds, for hosts whose profile also lives in the browser
+ * (the studio). `createHttpTransport` never sends it: `createTheoremHandler`
+ * keeps permissions, paused calls, and tool snapshots in its own session.
+ */
+export type TheoremReplay = {
+    gateKind?: ToolGate['kind'];
+    sessionPermissions?: string[];
+    name?: string;
+    input?: unknown;
+    snapshot?: TurnToolSnapshot;
+    promoted?: string[];
+    model?: string;
+    effort?: string;
+};
+/** For a host that reads the studio's client-held state. */
+export declare const theoremReplaySchema: z.ZodType<TheoremReplay>;
+/**
+ * One message. The host resolves the profile and owns the conversation: the
+ * client sends only the message and the ref of the conversation it continues.
+ *
+ * A message sent while the reply waits on gates walks away from them: `abandon`
+ * names the waiting calls. The host settles each one cancelled, streams those
+ * events first, and gives the model each call's answer before the message.
+ */
+export type TheoremTurnRequest = {
+    input: TheoremTurnInput;
+    /** The ref of the conversation this message continues; none starts one. */
+    conversation?: string;
+    model?: string;
+    effort?: string;
+    /** Client-generated id so mid-turn steers can find this turn's inbox. */
+    turnId?: string;
+    /** invariant: Both issued IDs identify each paused action that this message abandons. */
+    abandon?: GateReference[];
+    /** The tools the person allowed for the page, for a host without a session (the studio). */
+    replay?: Pick<TheoremReplay, 'sessionPermissions'>;
+    /**
+     * The page's transcript before this message, sent only after the host answered that it can no
+     * longer open `conversation` (`session.conversation_unknown`). A host that restores from it (the
+     * studio) goes on from it under a new ref; `createTheoremHandler` keeps the conversation its own
+     * and does not.
+     */
+    transcript?: TranscriptBlock[];
+};
+/** A `/turn` body as `createTheoremHandler` reads it. */
+export declare const theoremTurnRequestSchema: z.ZodType<TheoremTurnRequest>;
+/** What the user answers a gate with; walking away rides on the next message (`TheoremTurnRequest.abandon`). */
+declare const INVOKE_DECISIONS: readonly ["approve", "deny"];
+/**
+ * The user's answer to a tool call the host paused on a gate. `approve` runs it
+ * (with `input` when the user edited it); `deny` refuses it. The host settles
+ * each one, so the model and the trace read what the user chose. The tool's
+ * registered permission decides how long an approval lasts, not the client.
+ */
+export type TheoremInvokeRequest = {
+    /** Call id of the paused tool call (`tool.callId` on its gate event). */
+    gateId: string;
+    operationId: string;
+    decision: (typeof INVOKE_DECISIONS)[number];
+    /** The user's edit of the model's input; only with `approve`. */
+    input?: unknown;
+    /**
+     * The key or token the user typed at a bearer or API-key sign-in gate, only
+     * with `approve`. The server saves it for the session and never sends it
+     * back; an OAuth gate resumes with the gate id alone, once the host's
+     * callback saved the token.
+     */
+    secret?: string;
+    /** The page's answer to a `page` gate, only with `approve`: the tool's output schema checks it. */
+    page?: PagePart;
+    /** The ref of the conversation whose reply waits on the gate. */
+    conversation?: string;
+    /** Client-generated id so steers sent while the reply goes on find its inbox. */
+    turnId?: string;
+    replay?: TheoremReplay;
+};
+/** An `/invoke` body as `createTheoremHandler` reads it. */
+export declare const theoremInvokeRequestSchema: z.ZodType<TheoremInvokeRequest>;
+/** Inject user messages into an in-flight turn. */
+export type TheoremSteerRequest = {
+    turnId: string;
+    /** The client's id for this steer; the turn's `stage` event names it in `injected` once it lands. */
+    id: string;
+    inject: TurnHistoryMessage[];
+};
+/** A `/steer` body as `createTheoremHandler` reads it. */
+export declare const theoremSteerRequestSchema: z.ZodType<TheoremSteerRequest>;
+/**
+ * The ref the store issued for the conversation a run wrote: the client sends
+ * it with its next request. It comes before the run's error, which ends the stream.
+ * `posted` marks the write that holds the person's new message: a run that
+ * fails before it leaves the message unsent.
+ */
+export type ConversationLine = {
+    type: 'conversation';
+    ref: string;
+    posted?: true;
+};
+/** The lines a chat's reply streams: turn events, and the conversation's ref. */
+export declare const CHAT_LINES: WireLines<TurnEvent | ConversationLine>;
+/** What the browser draws: the transcript, and the reply that waits on gates. */
+export type ConversationView = {
+    transcript: TranscriptBlock[];
+    /** The reply that waits on gates: its events, and its blocks as the transcript will keep them. */
+    paused?: {
+        events: TurnEvent[];
+        blocks: TranscriptBlock[];
+    };
+};
+/** Read a conversation: a `/conversation` body. */
+export type TheoremConversationRequest = {
+    conversation: string;
+};
+/** A `/conversation` body as `createTheoremHandler` reads it. */
+export declare const theoremConversationRequestSchema: z.ZodType<TheoremConversationRequest>;
+/**
+ * Cut the conversation after transcript block `at` (-1 empties it): a
+ * `/rewind` body. A reply waiting on gates is walked away from first.
+ */
+export type TheoremRewindRequest = {
+    conversation: string;
+    at: number;
+};
+/** A `/rewind` body as `createTheoremHandler` reads it. */
+export declare const theoremRewindRequestSchema: z.ZodType<TheoremRewindRequest>;
+/** A rewound conversation: its new ref, and what the browser draws. */
+export type TheoremRewound = {
+    conversation: string;
+    view: ConversationView;
+};
+/** A turn event, one of a kind this client does not know (`unsupported`), or one that failed its check (`malformed`). */
+export type ClientTurnEvent = TurnEvent | UnsupportedEvent | MalformedEvent;
+export type TurnEventSink = (event: ClientTurnEvent) => void;
+/** A line of a chat's reply: a turn event, or the ref of the conversation it wrote. */
+export type ChatLine = ClientTurnEvent | ConversationLine;
+export type ChatLineSink = (line: ChatLine) => void;
+export interface TheoremTransport {
+    /** Client-safe interface for the host's profile (inputs, models, guardrail view). */
+    describe(signal?: AbortSignal): Promise<ProfileInterface>;
+    turn(request: TheoremTurnRequest, onLine: ChatLineSink, signal?: AbortSignal): Promise<void>;
+    invoke(request: TheoremInvokeRequest, onLine: ChatLineSink, signal?: AbortSignal): Promise<void>;
+    steer(request: TheoremSteerRequest): Promise<void>;
+    /** The conversation under `ref`, as the host shows it. */
+    conversation(request: TheoremConversationRequest, signal?: AbortSignal): Promise<ConversationView>;
+    /** The conversation cut after a transcript block, under the ref the host issued for it. */
+    rewind(request: TheoremRewindRequest, signal?: AbortSignal): Promise<TheoremRewound>;
+    pageResult?(result: PageDispatchResult, signal?: AbortSignal): Promise<void>;
+    /** Trace records the host sends back, when it delivers them (the studio does). */
+    traces?: TraceFeed;
+}
+/**
+ * A failure the host reported: its kind, the host's wording when it sent one
+ * (the profile's labels, applied on the host), and raw detail when the host
+ * exposes it. `clientFailure` words it for the user.
+ */
+export declare class TheoremStreamError extends Error {
+    readonly kind: ErrorKind;
+    readonly publicMessage?: string;
+    readonly internalMessage?: string;
+    /** The labels key behind `publicMessage`, when the host gave one: what failed, more exactly than `kind`. */
+    readonly copy?: ErrorCopies;
+    constructor(kind: ErrorKind, publicMessage?: string, internalMessage?: string, copy?: ErrorCopies);
+}
+export declare function isTheoremStreamError(err: unknown): err is TheoremStreamError;
+/** A host error reply's body (JSON reply or `{ type: 'error' }` stream line). */
+export type HostErrorBody = {
+    error?: string;
+    errorKind?: ErrorKind;
+    /** The labels key behind `error`, when more specific than the kind's. */
+    errorCopy?: ErrorCopies;
+    errorInternal?: string;
+};
+/** A host's error body, as the transport and the live client read it. */
+export declare const hostErrorBodySchema: z.ZodType<HostErrorBody>;
+/** A host's error body as a failure: its kind (else `fallbackKind`), wording, and detail. */
+export declare function hostError(body: HostErrorBody, fallbackKind: ErrorKind): TheoremStreamError;
+/** The host could not open the message's conversation (`session.conversation_unknown`). */
+export declare function isUnknownConversation(err: unknown): boolean;
+/**
+ * Read an NDJSON reply, checking each line against `lines`: a kind it doesn't
+ * list reaches `onLine` as `unsupported`, and a line that fails its check as
+ * `malformed`; the stream goes on. An `error` line ends it.
+ */
+export declare function readNdjsonStream<Line extends {
+    type: string;
+}>(response: Response, lines: WireLines<Line>, onLine: (line: Line | UnsupportedEvent | MalformedEvent) => void, signal?: AbortSignal): Promise<void>;
+export type HttpOptions = {
+    fetch?: typeof fetch;
+    /** Extra request headers (auth tokens, CSRF). A function is re-read per request. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Cookie policy. Default `same-origin`; use `include` when the handler is on another origin. */
+    credentials?: RequestCredentials;
+};
+/**
+ * POST JSON and stream NDJSON lines back, each checked against `lines`: turn
+ * events ({@link TURN_EVENT_SCHEMAS}), or a host's own schema beside them.
+ */
+export declare function postNdjson<Line extends {
+    type: string;
+}>(url: string, body: unknown, lines: WireLines<Line>, onLine: (line: Line | UnsupportedEvent | MalformedEvent) => void, options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<void>;
+/** POST JSON; a non-OK reply throws its failure. The OK reply's body is not read. */
+export declare function postJson(url: string, body: unknown, options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * GET, or POST `body` as JSON, and read the JSON reply; a non-OK reply throws its failure, after
+ * `failed` has read whatever else its JSON body carries.
+ */
+export declare function fetchJson(url: string, init: {
+    body?: unknown;
+    signal?: AbortSignal;
+    failed?: (body: unknown) => void;
+}, options?: HttpOptions): Promise<unknown>;
+/** POST a conversation's read to `url`, and check the view the host answers. */
+export declare function fetchConversation(url: string, body: unknown, options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<ConversationView>;
+/** POST a rewind to `url`, and check the rewound conversation the host answers. */
+export declare function fetchRewound(url: string, body: unknown, options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<TheoremRewound>;
+export type HttpTransportOptions = HttpOptions & {
+    /** Base URL where `createTheoremHandler` is mounted. Default `/api/theorem`. */
+    endpoint?: string;
+};
+/** Transport for a host mounted with `createTheoremHandler`. */
+export declare function createHttpTransport(options?: HttpTransportOptions): TheoremTransport;