@theoremjs/react 0.0.0-stage → 0.3.0

package/server/session-store.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Server-held session state for `createTheoremHandler`.
+ *
+ * Everything that grants authority lives here, never in the request body:
+ * which tools the user allowed for the session, which paused tool calls may be
+ * resumed (and with exactly what input), and which provider interactions this
+ * session may continue.
+ *
+ * @module
+ */
+import type { ToolGateAuth } from '@theoremjs/agents/interface';
+import type { ToolGate, ToolId, TurnEventOf, TurnInput, TurnToolSnapshot } from '@theoremjs/agents/kernel';
+/** A tool call the kernel paused on a gate, as the server saw it. */
+export type PendingToolGate = {
+    name: string;
+    /** The model's arguments; an approval runs the call with exactly these. */
+    arguments: Record<string, unknown>;
+    /** The gate, and for a sign-in gate the credential slot and kind it waits for. */
+    gate: Pick<ToolGate, 'kind' | 'permission'> & {
+        auth?: ToolGateAuth;
+    };
+    snapshot?: TurnToolSnapshot;
+    promoted: ToolId[];
+    turnInput: TurnInput;
+    model?: string;
+    createdAt: number;
+};
+/**
+ * A paused call the server answered, and the event that settled it. A client
+ * the stream never reached still shows the call waiting; a message that walks
+ * away from it gets this answer again, not a refusal.
+ */
+export type SettledToolGate = {
+    event: TurnEventOf<'tool'>;
+    /** When the call paused: a settled call is kept as long as its gate would have waited. */
+    createdAt: number;
+};
+export type TheoremSessionState = {
+    /** Tool ids the user allowed for the rest of this session. */
+    permissions: string[];
+    /** Paused tool calls by call id — the only calls `/invoke` will run. */
+    gates: Record<string, PendingToolGate>;
+    /** Paused calls the server answered and settled, by call id. */
+    settled: Record<string, SettledToolGate>;
+    /** Provider interaction ids this session produced, newest last. */
+    interactions: string[];
+};
+/**
+ * Where session state lives. The default is process memory — use a shared
+ * store (KV, Redis, a database row) when requests can reach different instances.
+ */
+export interface TheoremSessionStore {
+    load(sessionId: string): TheoremSessionState | undefined | Promise<TheoremSessionState | undefined>;
+    save(sessionId: string, state: TheoremSessionState): void | Promise<void>;
+}
+export declare function emptySessionState(): TheoremSessionState;
+/** Drop gates (waiting or settled) older than `ttlMs`. */
+export declare function pruneGates<Gate extends {
+    createdAt: number;
+}>(gates: Record<string, Gate>, now: number, ttlMs: number): Record<string, Gate>;
+export type MemorySessionStoreOptions = {
+    /** Idle sessions are forgotten after this long. Default 24h. */
+    ttlMs?: number;
+    /** Oldest sessions are evicted past this count. Default 10 000. */
+    maxSessions?: number;
+};
+/** A value kept per session id; the shape of every store the handler takes. */
+export type PerSessionStore<T> = {
+    load(sessionId: string): T | undefined | Promise<T | undefined>;
+    save(sessionId: string, value: T): void | Promise<void>;
+};
+/** A per-session value kept in process memory: forgotten when idle, oldest evicted first. */
+export declare function createMemorySessionMap<T>(options?: MemorySessionStoreOptions): PerSessionStore<T>;
+export declare function createMemorySessionStore(options?: MemorySessionStoreOptions): TheoremSessionStore;

package/server/session-store.js

@@ -0,0 +1,49 @@
+/**
+ * Server-held session state for `createTheoremHandler`.
+ *
+ * Everything that grants authority lives here, never in the request body:
+ * which tools the user allowed for the session, which paused tool calls may be
+ * resumed (and with exactly what input), and which provider interactions this
+ * session may continue.
+ *
+ * @module
+ */
+import { gateExpired } from '@theoremjs/agents/kernel';
+export function emptySessionState() {
+    return { permissions: [], gates: {}, settled: {}, interactions: [] };
+}
+/** Drop gates (waiting or settled) older than `ttlMs`. */
+export function pruneGates(gates, now, ttlMs) {
+    return Object.fromEntries(Object.entries(gates).filter(([, gate]) => !gateExpired(gate.createdAt, now, ttlMs)));
+}
+/** A per-session value kept in process memory: forgotten when idle, oldest evicted first. */
+export function createMemorySessionMap(options = {}) {
+    const ttlMs = options.ttlMs ?? 24 * 60 * 60 * 1000;
+    const maxSessions = options.maxSessions ?? 10_000;
+    const sessions = new Map();
+    return {
+        load(sessionId) {
+            const entry = sessions.get(sessionId);
+            if (!entry)
+                return undefined;
+            if (Date.now() - entry.touched > ttlMs) {
+                sessions.delete(sessionId);
+                return undefined;
+            }
+            return structuredClone(entry.value);
+        },
+        save(sessionId, value) {
+            sessions.delete(sessionId);
+            sessions.set(sessionId, { value: structuredClone(value), touched: Date.now() });
+            while (sessions.size > maxSessions) {
+                const oldest = sessions.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                sessions.delete(oldest);
+            }
+        },
+    };
+}
+export function createMemorySessionStore(options = {}) {
+    return createMemorySessionMap(options);
+}

package/server/steer-inbox.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Mid-turn steer inbox — the client posts user messages while a turn streams;
+ * the turn's stage handler drains one unit per inject-capable stage.
+ *
+ * @module
+ */
+import { type StageHandler, type TurnHistoryMessage } from '@theoremjs/agents';
+import type { TheoremSteerRequest } from '../client/transport.ts';
+/** One steer: the client's id for it, reported back in `stage.injected` once it lands. */
+export type SteerUnit = {
+    id: string;
+    messages: TurnHistoryMessage[];
+};
+/**
+ * A steer as a client posts it (a checked `TheoremSteerRequest`): its user
+ * messages. Other roles are dropped — a client never injects system,
+ * assistant or tool turns — and a steer with no user message is refused.
+ */
+export declare function steerUnitOf(steer: Pick<TheoremSteerRequest, 'id' | 'inject'>): SteerUnit;
+/** Lands the inbox's next steer, one per steerable stage, named by its id. */
+export declare function steerStage(inbox: SteerInbox, key: string): StageHandler;
+/**
+ * Keyed by client turn id. The default lives in process memory, which is only
+ * correct when steer POSTs reach the same process as the turn — swap in a
+ * shared store (KV, Redis, Durable Object) for multi-instance hosts.
+ */
+export interface SteerInbox {
+    open(turnId: string): void | Promise<void>;
+    /** Returns `false` when no turn with this id is open. */
+    enqueue(turnId: string, unit: SteerUnit): boolean | Promise<boolean>;
+    /** Next unit, FIFO, or `undefined`. */
+    consume(turnId: string): SteerUnit | undefined | Promise<SteerUnit | undefined>;
+    close(turnId: string): void | Promise<void>;
+}
+export declare function createMemorySteerInbox(): SteerInbox;

package/server/steer-inbox.js

@@ -0,0 +1,52 @@
+/**
+ * Mid-turn steer inbox — the client posts user messages while a turn streams;
+ * the turn's stage handler drains one unit per inject-capable stage.
+ *
+ * @module
+ */
+import { TheoremError } from '@theoremjs/agents';
+/** The stages a steer can land at. */
+const STEER_STAGES = new Set(['pre_turn', 'post_tool', 'before_end']);
+/**
+ * A steer as a client posts it (a checked `TheoremSteerRequest`): its user
+ * messages. Other roles are dropped — a client never injects system,
+ * assistant or tool turns — and a steer with no user message is refused.
+ */
+export function steerUnitOf(steer) {
+    const messages = steer.inject.filter((message) => message.role === 'user');
+    // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+    if (!messages.length)
+        throw new TheoremError('request', 'inject must contain user messages');
+    return { id: steer.id, messages };
+}
+/** Lands the inbox's next steer, one per steerable stage, named by its id. */
+export function steerStage(inbox, key) {
+    return async ({ stage }) => {
+        if (!STEER_STAGES.has(stage))
+            return;
+        const unit = await inbox.consume(key);
+        return unit ? { inject: unit.messages, injectId: unit.id } : undefined;
+    };
+}
+export function createMemorySteerInbox() {
+    const queues = new Map();
+    return {
+        open(turnId) {
+            if (!queues.has(turnId))
+                queues.set(turnId, []);
+        },
+        enqueue(turnId, unit) {
+            const queue = queues.get(turnId);
+            if (!queue)
+                return false;
+            queue.push(structuredClone(unit));
+            return true;
+        },
+        consume(turnId) {
+            return queues.get(turnId)?.shift();
+        },
+        close(turnId) {
+            queues.delete(turnId);
+        },
+    };
+}

package/server/walk-away.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A message that walks away from the calls its reply paused on, the same on
+ * every host (`createTheoremHandler`, the playground). The message's history
+ * leaves exactly those calls open; each settles cancelled, its events stream
+ * ahead of the reply, and the model reads each answer before the message.
+ *
+ * @module
+ */
+import { type TurnEvent, type TurnInput } from '@theoremjs/agents';
+/** Refuses a walk-away its history does not match, before any gate is answered. */
+export declare function checkWalkAway(input: TurnInput, abandon: readonly string[]): void;
+/** One walked-away call: its id, and the run that settles it (`invokeTool` with the abandoned resume). */
+export type WalkedAwayCall = {
+    callId: string;
+    events: AsyncIterable<TurnEvent>;
+};
+/**
+ * Streams each call's tool events as it settles; each run's `done` stays with
+ * that run. Returns `input` with every call answered in its history, or
+ * undefined when a run failed: its `error` event went out and ends the reply.
+ */
+export declare function walkAway(input: TurnInput, calls: readonly WalkedAwayCall[]): AsyncGenerator<TurnEvent, TurnInput | undefined>;

package/server/walk-away.js

@@ -0,0 +1,41 @@
+/**
+ * A message that walks away from the calls its reply paused on, the same on
+ * every host (`createTheoremHandler`, the playground). The message's history
+ * leaves exactly those calls open; each settles cancelled, its events stream
+ * ahead of the reply, and the model reads each answer before the message.
+ *
+ * @module
+ */
+import { TheoremError } from '@theoremjs/agents';
+import { answerOpenToolCalls, assertOpenToolCalls, settlesToolCall, } from '@theoremjs/agents/interface';
+/** Refuses a walk-away its history does not match, before any gate is answered. */
+export function checkWalkAway(input, abandon) {
+    assertOpenToolCalls(input.history ?? [], abandon);
+}
+/**
+ * Streams each call's tool events as it settles; each run's `done` stays with
+ * that run. Returns `input` with every call answered in its history, or
+ * undefined when a run failed: its `error` event went out and ends the reply.
+ */
+export async function* walkAway(input, calls) {
+    const answers = new Map();
+    for (const call of calls) {
+        for await (const event of call.events) {
+            if (event.type === 'error') {
+                yield event;
+                return undefined;
+            }
+            if (event.type !== 'tool')
+                continue;
+            yield event;
+            const readBack = settlesToolCall(event, call.callId) ? event.tool.readBack : undefined;
+            if (readBack !== undefined)
+                answers.set(call.callId, readBack);
+        }
+        if (!answers.has(call.callId)) {
+            // lexicon-exempt: internal diagnostic; the user reads error.internal
+            throw new TheoremError('internal', `walked-away call ${call.callId} ended without settling`);
+        }
+    }
+    return { ...input, history: answerOpenToolCalls(input.history ?? [], answers) };
+}

package/styles/ink-controls.css

@@ -0,0 +1,134 @@
+/* Shared ink waveform + borderless controls (live shell and turn voice composer). */
+
+:root {
+	--ink-ease: cubic-bezier(0.22, 1, 0.36, 1);
+	--ink-duration: 0.3s;
+}
+
+.ink-state {
+	margin: 0;
+	font-size: 0.75rem;
+	font-weight: 700;
+	letter-spacing: 0.06em;
+	text-transform: lowercase;
+	color: var(--color-ink);
+}
+
+.ink-wave-slot {
+	flex: 1 1 auto;
+	display: flex;
+	align-items: flex-end;
+	justify-content: center;
+	min-height: min(52vh, 22rem);
+	margin-bottom: 1.5rem;
+	padding: 0 0.5rem;
+}
+
+.ink-wave {
+	display: block;
+	width: min(100%, 36rem);
+	height: min(52vh, 22rem);
+	color: var(--color-ink);
+}
+
+.ink-wave--hero {
+	width: min(100%, 56rem);
+	height: 100%;
+	min-height: 40dvh;
+	max-height: 80dvh;
+}
+
+.ink-wave__bar {
+	stroke: currentcolor;
+	stroke-linecap: square;
+}
+
+.ink-divider {
+	flex-shrink: 0;
+	width: 100%;
+	height: 0;
+	margin: 0 0 1.5rem;
+	border: none;
+	border-top: 1px solid rgba(0, 0, 0, 0.14);
+}
+
+.ink-controls {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 1rem;
+	flex-shrink: 0;
+}
+
+.ink-controls__left,
+.ink-controls__right {
+	display: flex;
+	align-items: center;
+	gap: 0.65rem;
+}
+
+.ink-control {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 2.5rem;
+	height: 2.5rem;
+	padding: 0;
+	color: var(--color-ink);
+	background: transparent;
+	border: none;
+	cursor: pointer;
+	opacity: 0.55;
+	transition: opacity var(--ink-duration) var(--ink-ease);
+}
+
+.ink-control:not(:disabled):hover {
+	opacity: 1;
+}
+
+.ink-control:disabled {
+	opacity: 0.22;
+	cursor: default;
+}
+
+.ink-control--active {
+	opacity: 0.9;
+}
+
+.ink-tooltip {
+	position: relative;
+	display: inline-flex;
+}
+
+.ink-tooltip__label {
+	position: absolute;
+	left: 50%;
+	z-index: 6;
+	padding: 0.28rem 0.45rem;
+	font-family: var(--font-mono, ui-monospace, monospace);
+	font-size: 0.62rem;
+	font-weight: 700;
+	letter-spacing: 0.08em;
+	line-height: 1.2;
+	text-transform: lowercase;
+	white-space: nowrap;
+	color: var(--color-paper, #f4f1ea);
+	background: var(--color-ink, #111);
+	border-radius: 0;
+	pointer-events: none;
+	transform: translateX(-50%);
+}
+
+.ink-tooltip__label--top {
+	bottom: calc(100% + 0.45rem);
+}
+
+.ink-tooltip__label--bottom {
+	top: calc(100% + 0.45rem);
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.ink-control {
+		transition: none;
+	}
+}

package/ui/ChatComposerBar.d.ts

@@ -0,0 +1,39 @@
+import { type ChatComposerInputHandle } from '@astryxdesign/core/Chat';
+import { type AttachmentValidationIssue, type ComposerMenuAction, type ComposerPendingMessage, type ComposerProfileInterface, type ComposerRunPhase } from '@theoremjs/agents/interface';
+import type { ClientFailure } from '../client/failure.ts';
+export declare const NO_FOCUS_RING: React.CSSProperties;
+export type ChatComposerBarProps = {
+    iface: ComposerProfileInterface;
+    draftText: string;
+    pendingFiles: readonly File[];
+    pendingVoice: readonly File[];
+    pendingMessages: readonly ComposerPendingMessage[];
+    /** Files the last send refused, one per reason; worded with the profile's lexicon. */
+    issues: readonly AttachmentValidationIssue[];
+    phase: ComposerRunPhase;
+    failure: ClientFailure | null;
+    selectedModel?: string;
+    selectedEffort?: string;
+    placeholder?: string;
+    /** Imperative handle for the editor (focus, insert). */
+    inputRef?: React.Ref<ChatComposerInputHandle>;
+    onDraftTextChange: (text: string) => void;
+    onFilesSelected: (files: File[]) => void;
+    onAttachmentRemove: (index: number) => void;
+    onVoiceStaged: (file: File) => void;
+    onVoiceClear: () => void;
+    onSubmit: () => void;
+    onStop: () => void;
+    onMenuAction: (action: ComposerMenuAction) => void;
+    onGenerationChange: (next: {
+        modelId: string;
+        effort?: string;
+    }) => void;
+    onPendingMove: (id: string, direction: 'up' | 'down') => void;
+    onPendingRemove: (id: string) => void;
+    onPendingQueue: (id: string) => void;
+    onPendingRestore: (id: string) => void;
+    onPendingSendNow: (id: string) => void;
+};
+/** Astryx composer wired to Theorem's send / stop / queue / steer / stash matrix. */
+export declare function ChatComposerBar(props: ChatComposerBarProps): import("react").JSX.Element;