@reforma/types 1.3.0 → 1.5.0

package/dist/index.js

@@ -342,6 +342,8 @@ let SandboxClusterNodeStatusEnum = /* @__PURE__ */ function(SandboxClusterNodeSt
 // src/api/sandbox-clusters/sandbox-cluster-provider.enum.ts
 let SandboxClusterProviderEnum = /* @__PURE__ */ function(SandboxClusterProviderEnum) {
 	SandboxClusterProviderEnum["rke2"] = "rke2";
+	/** Vercel Sandbox microVMs; overflow when no `rke2` cluster can take a sandbox. */
+	SandboxClusterProviderEnum["vercel"] = "vercel";
 	return SandboxClusterProviderEnum;
 }({});
 // src/api/sandbox-clusters/sandbox-cluster-status.enum.ts
@@ -546,6 +548,35 @@ let McpRuntimeStatus = /* @__PURE__ */ function(McpRuntimeStatus) {
 	McpRuntimeStatus["error"] = "error";
 	return McpRuntimeStatus;
 }({});
+// src/sandbox/ui-parts.ts
+/** Whether the part is a data part (`data-*`). */
+function isDataUIPart(part) {
+	return part.type.startsWith("data-");
+}
+/** Whether the part is a text part. */
+function isTextUIPart(part) {
+	return part.type === "text";
+}
+/** Whether the part is a file part. */
+function isFileUIPart(part) {
+	return part.type === "file";
+}
+/** Whether the part is a reasoning part. */
+function isReasoningUIPart(part) {
+	return part.type === "reasoning";
+}
+/** Whether the part is a statically typed tool part (`tool-*`). */
+function isStaticToolUIPart(part) {
+	return part.type.startsWith("tool-");
+}
+/** Whether the part is a static or dynamic tool part. */
+function isToolUIPart(part) {
+	return isStaticToolUIPart(part) || part.type === "dynamic-tool";
+}
+/** Tool name of a static (`tool-<name>`) or dynamic tool part. */
+function getToolName(part) {
+	return part.type === "dynamic-tool" ? part.toolName : part.type.split("-").slice(1).join("-");
+}
 // src/sandbox/usage-metadata.ts
 /** Prompt-window buckets. Tool calls/results live in `conversation`, not `tools`. */
 const CONTEXT_USAGE_BUCKET_IDS = [
@@ -613,7 +644,14 @@ exports.allocLayerCite = allocLayerCite;
 exports.attachedLayerRefKey = attachedLayerRefKey;
 exports.codeEditorStateKey = codeEditorStateKey;
 exports.formatLayerCite = formatLayerCite;
+exports.getToolName = getToolName;
+exports.isDataUIPart = isDataUIPart;
+exports.isFileUIPart = isFileUIPart;
+exports.isReasoningUIPart = isReasoningUIPart;
 exports.isScreenshotTool = isScreenshotTool;
+exports.isStaticToolUIPart = isStaticToolUIPart;
+exports.isTextUIPart = isTextUIPart;
+exports.isToolUIPart = isToolUIPart;
 exports.layerCiteBase = layerCiteBase;
 exports.normalizeAttachedLayerRef = normalizeAttachedLayerRef;
 exports.normalizeLayerSource = normalizeLayerSource;

package/package.json

@@ -2,7 +2,7 @@
     "name": "@reforma/types",
     "author": "Reforma, Inc. <dev@reforma.ai>",
     "description": "Shared types between Reforma apps/packages",
-    "version": "1.3.0",
+    "version": "1.5.0",
     "license": "UNLICENSED",
     "repository": {
         "type": "git",

package/src/api/billing/contracts.ts

@@ -81,6 +81,11 @@ export interface LlmUsageWebhookEvent {
     id?: string;
     litellm_call_id?: string;
     call_type?: string;
+    /**
+     * LiteLLM session id: `x-litellm-trace-id`, or `litellm_session_id` on the
+     * Gemini pass-through, which drops `spend_logs_metadata`. Client-controlled.
+     */
+    trace_id?: string | null;
     status?: string;
     /** Gateway-computed cost in USD for this request. */
     response_cost?: number;

package/src/api/billing/credit-ledger-entry.ts

@@ -33,6 +33,21 @@ export interface CreditOperation {
     /** Who spent the credits when this row is usage-linked; null for grants/purchases. */
     userName: string | null;
     userEmail: string | null;
+    /** The agent run behind a usage row; null for grants/purchases. */
+    usage: CreditUsageDetails | null;
+}
+
+/** The agent run a usage charge settled: where it ran and what the gateway saw. */
+export interface CreditUsageDetails {
+    projectName: string | null;
+    threadTitle: string | null;
+    /** Gateway requests (model calls) in the run. */
+    requests: number;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    models: string[];
 }
 
 /** Paged customer ledger. */

package/src/api/sandbox-clusters/create-sandbox-cluster.ts

@@ -8,8 +8,10 @@ export interface CreateSandboxCluster {
     region: string;
     apiUrl: string;
     ingressDomain: string;
-    /** Plaintext kubeconfig YAML; encrypted at rest by the API. */
-    kubeconfig: string;
+    /** Plaintext kubeconfig YAML; encrypted at rest by the API. Required for `rke2`. */
+    kubeconfig?: string;
     status?: SandboxClusterStatusEnum;
     maxSandboxes?: number;
+    /** Kubelet `Localhost` seccomp profile path for sandbox pods; omit for `Unconfined`. */
+    seccompProfile?: string | null;
 }

package/src/api/sandbox-clusters/sandbox-cluster-provider.enum.ts

@@ -1,3 +1,5 @@
 export enum SandboxClusterProviderEnum {
-rke2 = 'rke2'
+rke2 = 'rke2',
+/** Vercel Sandbox microVMs; overflow when no `rke2` cluster can take a sandbox. */
+vercel = 'vercel'
 }

package/src/api/sandbox-clusters/sandbox-cluster.ts

@@ -12,6 +12,12 @@ export interface SandboxCluster {
     version: string | null;
     status: SandboxClusterStatusEnum;
     maxSandboxes: number;
+    /**
+     * Path of the kubelet `Localhost` seccomp profile the cluster's nodes carry,
+     * relative to the kubelet seccomp root. `null` runs sandbox pods
+     * `Unconfined`, for clusters where no profile is installed.
+     */
+    seccompProfile: string | null;
     lastHealthCheckAt: Date | null;
     healthCheckError: string | null;
     createdByUserId: number;

package/src/api/sandbox-clusters/update-sandbox-cluster.ts

@@ -12,4 +12,6 @@ export interface UpdateSandboxCluster {
     kubeconfig?: string;
     status?: SandboxClusterStatusEnum;
     maxSandboxes?: number;
+    /** Kubelet `Localhost` seccomp profile path for sandbox pods; `null` for `Unconfined`. */
+    seccompProfile?: string | null;
 }

package/src/api/screenshot/screenshot.ts

@@ -40,3 +40,27 @@ export interface ScreenshotUploadResponse {
     mediaType: 'image/png' | 'image/jpeg';
     size: number;
 }
+
+/** Open a page without capturing it. Same URL rules and viewport defaults as a screenshot. */
+export interface PageInspectRequest {
+    url: string;
+    headers?: Record<string, string>;
+    width?: number;
+    height?: number;
+    waitUntil?: ScreenshotWaitUntil;
+    /** Milliseconds to wait after the page loads. Default 500. Capped at 10000. */
+    delayMs?: number;
+}
+
+/** What the browser reported while the page loaded and settled. Each list keeps the first 20 entries. */
+export interface PageInspection {
+    /** HTTP status of the document. Omitted when navigation failed. */
+    status?: number;
+    /** Navigation failure, such as a timeout. */
+    error?: string;
+    /** Uncaught exceptions thrown in the page. */
+    pageErrors: string[];
+    console: { type: 'error' | 'warn'; text: string }[];
+    /** Subresources that failed or answered 4xx/5xx. */
+    failedRequests: { url: string; status?: number; error?: string }[];
+}

package/src/sandbox/ai.ts

@@ -1,7 +1,7 @@
 import type { ThreadPlan } from './plans';
 import type { ThreadTodo } from './todos';
 import type { ThreadBackgroundJob } from './tools/get-background-result';
-import type { ReformaUIMessage } from './ui-message';
+import type { ReformaUIMessage, ReformaUserUIMessage } from './ui-message';
 import type { ReformaContextUsage } from './usage-metadata';
 
 export type ChatThreadSummaryDto = {
@@ -52,6 +52,63 @@ export type ChatRequestBody = {
     /** Keep messages up to and including this id; drop the tail before merge. */
     afterMessageId?: string;
     runConfig?: ChatRunConfig;
+    /** "Send now" on a queued item: the item leaves the queue once this turn is accepted. */
+    queueItemId?: string;
+};
+
+/** `steer` reaches the running agent at its next step; `next-turn` starts the next run. */
+export type ChatQueueItemMode = 'steer' | 'next-turn';
+
+/** User input waiting on a thread run. Owned by the sandbox, in memory only. */
+export type ChatQueueItem = {
+    /** Client-chosen id; adding the same id twice is a no-op. */
+    id: string;
+    mode: ChatQueueItemMode;
+    /** Ready-to-send user message. */
+    message: ReformaUserUIMessage;
+    runConfig?: ChatRunConfig;
+    /** Opaque composer state the client needs to reopen the item for editing. */
+    draft?: unknown;
+    /** Open in an editor. A locked steer is not taken, and a locked head holds the queue. */
+    editing: boolean;
+    createdAt: number;
+};
+
+/** Why the queue stopped draining. Only "Send now" on an item clears it. */
+export type ChatQueuePause = {
+    reason: 'stopped' | 'failed';
+    error?: string;
+};
+
+/** Steers first, then next turns, each in send order. */
+export type ChatQueueState = {
+    items: ChatQueueItem[];
+    paused?: ChatQueuePause;
+};
+
+/**
+ * Sandbox sync value `chat-thread:<threadId>`: thread state without messages.
+ * A missing meta field means "unchanged": the idle snapshot of a thread the sandbox has not loaded carries none.
+ */
+export type ChatThreadStateSnapshot = {
+    /** Set while a run is in flight, including a run parked on the user. */
+    runId?: string;
+    queue: ChatQueueState;
+    title?: string;
+    todos?: ThreadTodo[];
+    /** `null`: the thread has no plan. */
+    plan?: ThreadPlan | null;
+    /** Running background jobs. */
+    backgroundJobs?: ThreadBackgroundJob[];
+    contextUsage?: ReformaContextUsage;
+};
+
+/** POST `/ai/threads/:threadId/queue` */
+export type ChatQueueAddRequest = Pick<ChatQueueItem, 'id' | 'mode' | 'message' | 'runConfig' | 'draft'>;
+
+/** PATCH `/ai/threads/:threadId/queue/:itemId`. `index` is the position inside the item's mode section. */
+export type ChatQueuePatchRequest = Partial<Pick<ChatQueueItem, 'mode' | 'message' | 'draft' | 'editing'>> & {
+    index?: number;
 };
 
 /**
@@ -69,6 +126,8 @@ export type ChatThreadDetailDto = {
      * The client may attempt stream resume (`GET …/chat/:threadId/stream`) only when this is true.
      */
     hasActiveStream: boolean;
+    /** In-flight run, including one parked on the user. */
+    runId?: string;
     /** Active todo list for this thread (empty when none). */
     todos: ThreadTodo[];
     /** Thread plan, when one exists. */
@@ -78,11 +137,3 @@ export type ChatThreadDetailDto = {
     /** Latest prompt-window breakdown; omitted before the first model step. */
     contextUsage?: ReformaContextUsage;
 };
-
-/** WS `thread-status` payload when a chat run starts or ends. */
-export type ThreadStatusEvent = {
-    threadId: string;
-    isActive: boolean;
-    /** Set on subagent children so the client can ignore list refresh. */
-    parentThreadId?: string;
-};

package/src/sandbox/index.ts

@@ -12,6 +12,7 @@ export * from './skills';
 export * from './todos';
 export * from './tools';
 export * from './ui-message';
+export * from './ui-parts';
 export * from './usage-metadata';
 export * from './websocket';
 export * from './workspace';

package/src/sandbox/tools/agent.ts

@@ -7,6 +7,8 @@ export type AgentToolInput = {
     message: string;
     /** `new` starts a child. `resume` continues the latest of this name. Omit for the agent default. */
     resume?: 'new' | 'resume';
+    /** Run as a background job: a receipt now, the report as a notification later. Root agent only. */
+    background?: boolean;
 };
 
 export type AgentToolOutput = {
@@ -17,6 +19,8 @@ export type AgentToolOutput = {
     /** Present when the subagent profile used structured output. */
     data?: unknown;
     error?: string;
+    /** Set when the subagent runs in the background: the receipt's job id. The report arrives later. */
+    jobId?: string;
 };
 
 export type AgentUITool = {

package/src/sandbox/tools/check-page.ts

@@ -0,0 +1,29 @@
+/** Matches sandbox `CheckPage` tool schemas. */
+
+export type CheckPageToolInput = {
+    /** Preview paths, such as `/` or `/reforma/stories/ui/button?variant=outline`. */
+    paths: string[];
+    delayMs?: number;
+};
+
+/** One visited path. Empty fields are omitted. */
+export type CheckPageReport = {
+    path: string;
+    status?: number;
+    error?: string;
+    pageErrors?: string[];
+    console?: { type: 'error' | 'warn'; text: string }[];
+    failedRequests?: { url: string; status?: number; error?: string }[];
+    /** Dev server output written while the page loaded. */
+    serverLog?: string;
+};
+
+export type CheckPageToolOutput = {
+    pages?: CheckPageReport[];
+    error?: string;
+};
+
+export type CheckPageUITool = {
+    input: CheckPageToolInput;
+    output: CheckPageToolOutput;
+};

package/src/sandbox/tools/get-background-result.ts

@@ -6,12 +6,21 @@ export type BackgroundResult = {
     error?: string;
 };
 
+/** A background subagent's job: which agent runs, in which child thread, and whether it waits on the user. */
+export type ThreadBackgroundAgent = {
+    name: string;
+    childThreadId: string;
+    waitingForUser?: boolean;
+};
+
 /** A background job on this thread. `output` / `error` appear when it finishes. */
 export type ThreadBackgroundJob = {
     id: string;
     description: string;
     output?: unknown;
     error?: string;
+    /** Set when the job is a subagent; commands and other work leave it out. */
+    agent?: ThreadBackgroundAgent;
 };
 
 /** Matches sandbox `GetBackgroundResult` tool schemas. */

package/src/sandbox/tools/index.ts

@@ -3,6 +3,7 @@ export * from './ask-user-question';
 export * from './bash';
 export * from './build';
 export * from './capture-screenshot';
+export * from './check-page';
 export * from './choose-design-direction';
 export * from './commit';
 export * from './commit-design-read';

package/src/sandbox/tools/read-lints.ts

@@ -10,7 +10,7 @@ export type ReadLintsDiagnostic = {
     endColumn?: number;
     severity: LintSeverity;
     message: string;
-    source: 'biome' | 'typescript' | 'tokens';
+    source: 'biome' | 'typescript' | 'tokens' | 'stories';
     code?: string;
 };
 

package/src/sandbox/ui-message.ts

@@ -4,14 +4,13 @@ import type { SelectedLayerContext } from '../layers';
 import type { CodeEditorState } from '../theia/bridge';
 import type { ReformaTurnGitCommit } from './git/commit';
 import type { VersionStatus } from './git/version';
-import type { ThreadPlan } from './plans';
-import type { ThreadTodo } from './todos';
 import type {
     AgentUITool,
     AskUserQuestionUITool,
     BashUITool,
     BuildUITool,
     CallDynamicToolUITool,
+    CheckPageUITool,
     ChooseDesignDirectionUITool,
     CommitDesignReadUITool,
     CommitUITool,
@@ -47,7 +46,6 @@ import type {
     RegisterLocalFontUITool,
     RemoveFileUITool,
     SkillUITool,
-    ThreadBackgroundJob,
     TodoWriteUITool,
     WaitingUITool,
     WriteUITool,
@@ -161,6 +159,12 @@ export type ReformaChatMessageMetadata = {
     /** User stopped this assistant turn. Persisted with the message. */
     stopReason?: 'cancelled';
 
+    /**
+     * The user's ChatGPT plan or API key could not pay for this turn.
+     * The composer shows a limit plate instead of the generic error row.
+     */
+    payerFailure?: PayerFailure;
+
     /** Pre/Post/Stop hook context frozen for this assistant turn (server-tagged before persist). */
     turnHookContext?: string;
 };
@@ -181,7 +185,6 @@ export type RunCreditsSyncEntry = {
  */
 
 export type ThreadUpdateData = {
-    title?: string;
     /** Emitted when the server assigns a new thread id (draft first message). */
     threadId?: string;
 };
@@ -212,21 +215,6 @@ export type ProjectUpdateData = {
     screenshotUrl?: string | null;
 };
 
-/** Transient UI stream payload (`data-thread-todos`); not stored on messages */
-export type ThreadTodosUpdateData = {
-    todos: ThreadTodo[];
-};
-
-/** Transient UI stream payload (`data-thread-plan`); not stored on messages */
-export type ThreadPlanUpdateData = {
-    plan: ThreadPlan;
-};
-
-/** Transient UI stream payload (`data-thread-background-jobs`); not stored on messages */
-export type ThreadBackgroundJobsUpdateData = {
-    backgroundJobs: ThreadBackgroundJob[];
-};
-
 /**
  * Finished background commands, stored on the assistant message (`data-background-result`).
  * `text` is the model note frozen at delivery time.
@@ -237,6 +225,16 @@ export type BackgroundResultNoticeData = {
     text: string;
 };
 
+/**
+ * A user message the running agent took between steps (`data-user-steer`), stored on the
+ * assistant message at that position. The model sees it as a user turn there.
+ */
+export type UserSteerData = {
+    message: ReformaUserUIMessage;
+    /** Unix ms when the agent took the steer. Missing on parts stored before it was recorded. */
+    takenAt?: number;
+};
+
 /** Transient UI stream payload (`data-version-status`); mirrors WS `version-status`. */
 export type VersionStatusData = VersionStatus;
 
@@ -307,15 +305,26 @@ export interface ReformaChatDataContextCompactionPayload {
     resumeMessageId?: string;
 }
 
+/**
+ * ChatGPT plan or a user API key could not pay.
+ * Streamed as transient `data-payer-failure`, and saved on the assistant message.
+ */
+export type PayerFailure = {
+    kind: 'limit' | 'access';
+    /** `chatgpt` is an OAuth plan. `api_key` is the user's provider key. */
+    payer: 'chatgpt' | 'api_key';
+    providerId: 'openai' | 'anthropic' | 'google';
+    /** Calendar day (`YYYY-MM-DD`) the provider named. Absent when they did not. */
+    resetAt?: string;
+};
+
 /** Maps `data-*` suffix keys to payload shapes for {@link ReformaUIMessage}. */
 export type ReformaChatDataTypes = {
     'thread-update': ThreadUpdateData;
     'project-update': ProjectUpdateData;
     'version-status': VersionStatusData;
-    'thread-todos': ThreadTodosUpdateData;
-    'thread-plan': ThreadPlanUpdateData;
-    'thread-background-jobs': ThreadBackgroundJobsUpdateData;
     'background-result': BackgroundResultNoticeData;
+    'user-steer': UserSteerData;
     'tool-metadata': ToolMetadataUpdateData;
     'client-tool': ClientToolRequestData;
     'tool-execution-progress': ReformaChatDataToolExecutionProgressPayload;
@@ -323,6 +332,7 @@ export type ReformaChatDataTypes = {
     'redacted-reasoning': ReformaChatDataRedactedReasoningPayload;
     'context-compaction': ReformaChatDataContextCompactionPayload;
     'subagent-status': SubagentStatusUpdateData;
+    'payer-failure': PayerFailure;
 };
 
 // --- Tool UI parts (third `UIMessage` generic) ---
@@ -359,6 +369,7 @@ export type ReformaChatUITools = {
     MoveFile: MoveFileUITool;
     Navigate: NavigateUITool;
     PageScreenshot: PageScreenshotUITool;
+    CheckPage: CheckPageUITool;
     ReadPlan: ReadPlanUITool;
     ReadTodo: ReadTodoUITool;
     TodoWrite: TodoWriteUITool;

package/src/sandbox/ui-parts.ts

@@ -0,0 +1,49 @@
+import type {
+    DataUIPart,
+    DynamicToolUIPart,
+    FileUIPart,
+    ReasoningUIPart,
+    TextUIPart,
+    ToolUIPart,
+    UIDataTypes,
+    UIMessagePart,
+    UITools,
+} from 'ai' with { 'resolution-mode': 'import' };
+
+// Same contracts as the `ai` part guards. Importing them from `ai` evaluates the whole
+// SDK and its zod schemas, which chat UI outside the editor does not need.
+
+/** Whether the part is a data part (`data-*`). */
+export function isDataUIPart<DATA_TYPES extends UIDataTypes>(part: UIMessagePart<DATA_TYPES, UITools>): part is DataUIPart<DATA_TYPES> {
+    return part.type.startsWith('data-');
+}
+
+/** Whether the part is a text part. */
+export function isTextUIPart(part: UIMessagePart<UIDataTypes, UITools>): part is TextUIPart {
+    return part.type === 'text';
+}
+
+/** Whether the part is a file part. */
+export function isFileUIPart(part: UIMessagePart<UIDataTypes, UITools>): part is FileUIPart {
+    return part.type === 'file';
+}
+
+/** Whether the part is a reasoning part. */
+export function isReasoningUIPart(part: UIMessagePart<UIDataTypes, UITools>): part is ReasoningUIPart {
+    return part.type === 'reasoning';
+}
+
+/** Whether the part is a statically typed tool part (`tool-*`). */
+export function isStaticToolUIPart<TOOLS extends UITools>(part: UIMessagePart<UIDataTypes, TOOLS>): part is ToolUIPart<TOOLS> {
+    return part.type.startsWith('tool-');
+}
+
+/** Whether the part is a static or dynamic tool part. */
+export function isToolUIPart<TOOLS extends UITools>(part: UIMessagePart<UIDataTypes, TOOLS>): part is ToolUIPart<TOOLS> | DynamicToolUIPart {
+    return isStaticToolUIPart(part) || part.type === 'dynamic-tool';
+}
+
+/** Tool name of a static (`tool-<name>`) or dynamic tool part. */
+export function getToolName(part: ToolUIPart<UITools> | DynamicToolUIPart): string {
+    return part.type === 'dynamic-tool' ? part.toolName : part.type.split('-').slice(1).join('-');
+}

package/src/theia/bridge.ts

@@ -34,7 +34,7 @@ export type TheiaHostMethods = {
     onAttachFiles: (files: readonly CodeEditorState[]) => void;
     /** Switch the parent shell/canvas mode, or activate commenting, while Theia holds keyboard focus. */
     setViewMode: (mode: TheiaHostViewMode) => void;
-    /** Flip Code ↔ last persisted canvas mode (`exitCodeMode` / enter Code). */
+    /** Cycle Editor → Design → Code. Preview counts as Editor. */
     toggleCodeShell: () => void;
 };