@reforma/types 1.4.0 → 1.6.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.4.0",
+    "version": "1.6.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,8 @@ 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`. */

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/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/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/ui-message.ts

@@ -4,8 +4,6 @@ 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,
@@ -48,7 +46,6 @@ import type {
     RegisterLocalFontUITool,
     RemoveFileUITool,
     SkillUITool,
-    ThreadBackgroundJob,
     TodoWriteUITool,
     WaitingUITool,
     WriteUITool,
@@ -129,6 +126,9 @@ export type ReformaUserMessageMetadata = {
     optPlugins?: string[];
 };
 
+/** A run that did not complete its turn. Resume continues the turn. */
+export type ReformaStopReason = 'cancelled' | 'max_turns_exceeded' | 'provider_error' | 'internal_error';
+
 /**
  * Metadata on assistant Reforma chat UI messages (`UIMessage.metadata`), stream finish snapshots,
  * and persisted threads.
@@ -159,8 +159,14 @@ export type ReformaChatMessageMetadata = {
     runId?: string;
     /** Reforma credits billed for this run. Stamped after settle; denormalized from the API. */
     creditsCharged?: number;
-    /** User stopped this assistant turn. Persisted with the message. */
-    stopReason?: 'cancelled';
+    /** Why this assistant turn ended early: the user stopped it, or the run failed. Absent once a run completes it. */
+    stopReason?: ReformaStopReason;
+
+    /**
+     * 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;
@@ -182,7 +188,6 @@ export type RunCreditsSyncEntry = {
  */
 
 export type ThreadUpdateData = {
-    title?: string;
     /** Emitted when the server assigns a new thread id (draft first message). */
     threadId?: string;
 };
@@ -213,21 +218,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.
@@ -238,6 +228,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;
 
@@ -308,15 +308,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;
@@ -324,6 +335,7 @@ export type ReformaChatDataTypes = {
     'redacted-reasoning': ReformaChatDataRedactedReasoningPayload;
     'context-compaction': ReformaChatDataContextCompactionPayload;
     'subagent-status': SubagentStatusUpdateData;
+    'payer-failure': PayerFailure;
 };
 
 // --- Tool UI parts (third `UIMessage` generic) ---

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('-');
+}