theokit 0.51.0 → 0.52.0

package/dist/{chunk-75MWRZDP.js → chunk-I4ELCXNV.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-SSYDEKWF.js";
 import {
   dispatchControllerRequest
-} from "./chunk-IQRL5KZL.js";
+} from "./chunk-VGE6AKEJ.js";
 import {
   broadcastToDevtools
 } from "./chunk-OIGJOYX6.js";
@@ -53,7 +53,7 @@ import {
   incomingMessageToHandlerRequest,
   sendError,
   writeWebResponseToServerResponse
-} from "./chunk-5K7WIT3Z.js";
+} from "./chunk-5BOKW3GX.js";
 import {
   findSuggestion
 } from "./chunk-NTDN54XO.js";
@@ -3476,19 +3476,19 @@ async function theoPluginAsync(rootOrOptions) {
       })
     );
   }
-  const { appTypedClientPlugin } = await import("./app-typed-client-XPYFYUPN.js");
+  const { appTypedClientPlugin } = await import("./app-typed-client-ZZIASI4A.js");
   const appClientPlugin = appTypedClientPlugin({
     cwd: projectRoot,
     serverDir: serverDirAbs,
     distDir: resolve10(projectRoot, ".theokit")
   });
-  const { actionsVirtualModule } = await import("./actions-virtual-module-D52G2ACL.js");
+  const { actionsVirtualModule } = await import("./actions-virtual-module-VJYKUIXE.js");
   const actionsPlugin = actionsVirtualModule({
     serverDir: serverDirAbs,
     distDir: resolve10(projectRoot, ".theokit")
   });
   const { agentsTypedClientPlugin } = await import("./agents-typed-client-INR2E7B3.js");
-  const { generateManifest } = await import("./internal-api-PYWIJTLF.js");
+  const { generateManifest } = await import("./internal-api-S6BGJCZP.js");
   const agentsClientPlugin = agentsTypedClientPlugin({
     projectRoot,
     agentsDir: agentsDirName,
@@ -3505,7 +3505,7 @@ async function theoPluginAsync(rootOrOptions) {
   const controllerTransformPlugin = controllerSwcTransformPlugin({
     serverDir: serverDirAbs
   });
-  const { serverOnlyImportBoundary } = await import("./server-boundary-ITRJTWT4.js");
+  const { serverOnlyImportBoundary } = await import("./server-boundary-XRXVVUMO.js");
   const serverBoundaryPlugin = serverOnlyImportBoundary({
     projectRoot,
     serverDir: serverDirAbs
@@ -3688,4 +3688,4 @@ export {
   theoPluginAsync,
   theoPlugin
 };
-//# sourceMappingURL=chunk-75MWRZDP.js.map
+//# sourceMappingURL=chunk-I4ELCXNV.js.map

package/dist/{chunk-MTWZ54OI.js → chunk-MBFD6NHB.js}

@@ -12,7 +12,7 @@ import {
   serveMatchedAuxRoute,
   serveThroughPluginLifecycle,
   setupSsrDevMiddleware
-} from "./chunk-DY5W5OWQ.js";
+} from "./chunk-2E7JLV7L.js";
 import {
   resolveTheoRootDir
 } from "./chunk-FDOOBTXJ.js";
@@ -38,7 +38,7 @@ import {
   mountAgent,
   readAgentPolicy,
   writeWebResponseToServerResponse
-} from "./chunk-575RV3CD.js";
+} from "./chunk-E53UIFH6.js";
 import {
   getApprovalRegistry,
   resolveProvider
@@ -2179,19 +2179,19 @@ async function theoPluginAsync(rootOrOptions) {
       })
     );
   }
-  const { appTypedClientPlugin } = await import("./app-typed-client-MPQDKS35.js");
+  const { appTypedClientPlugin } = await import("./app-typed-client-FQVMEG4Z.js");
   const appClientPlugin = appTypedClientPlugin({
     cwd: projectRoot,
     serverDir: serverDirAbs,
     distDir: resolve5(projectRoot, ".theokit")
   });
-  const { actionsVirtualModule } = await import("./actions-virtual-module-FJIFAQUA.js");
+  const { actionsVirtualModule } = await import("./actions-virtual-module-SNG4JC35.js");
   const actionsPlugin = actionsVirtualModule({
     serverDir: serverDirAbs,
     distDir: resolve5(projectRoot, ".theokit")
   });
   const { agentsTypedClientPlugin } = await import("./agents-typed-client-D4OA2TXB.js");
-  const { generateManifest } = await import("./internal-api-OOJT7L6I.js");
+  const { generateManifest } = await import("./internal-api-EL25ADPR.js");
   const agentsClientPlugin = agentsTypedClientPlugin({
     projectRoot,
     agentsDir: agentsDirName,
@@ -2208,7 +2208,7 @@ async function theoPluginAsync(rootOrOptions) {
   const controllerTransformPlugin = controllerSwcTransformPlugin({
     serverDir: serverDirAbs
   });
-  const { serverOnlyImportBoundary } = await import("./server-boundary-YIRMIYAS.js");
+  const { serverOnlyImportBoundary } = await import("./server-boundary-RNM25WWD.js");
   const serverBoundaryPlugin = serverOnlyImportBoundary({
     projectRoot,
     serverDir: serverDirAbs
@@ -2383,4 +2383,4 @@ export {
   theoPluginAsync,
   theoPlugin
 };
-//# sourceMappingURL=chunk-MTWZ54OI.js.map
+//# sourceMappingURL=chunk-MBFD6NHB.js.map

package/dist/{chunk-YJDWSM4D.js → chunk-PFAVZL4F.js}

@@ -178,7 +178,7 @@ async function agentCommand(name, message, deps = {}) {
 async function createAgentSsrLoader(projectRoot) {
   const { createServer } = await import("vite");
   const react = (await import("@vitejs/plugin-react")).default;
-  const { theoPluginAsync } = await import("./vite-plugin-6KDMU3E2.js");
+  const { theoPluginAsync } = await import("./vite-plugin-2XM35VNV.js");
   const { loadConfig } = await import("./load-config-4ATXQUN3.js");
   const config = await loadConfig(projectRoot);
   const theoPlugins = await theoPluginAsync({
@@ -212,4 +212,4 @@ export {
   agentCommand,
   createAgentSsrLoader
 };
-//# sourceMappingURL=chunk-YJDWSM4D.js.map
+//# sourceMappingURL=chunk-PFAVZL4F.js.map

package/dist/{chunk-IQRL5KZL.js → chunk-VGE6AKEJ.js}

@@ -2,7 +2,7 @@ import {
   dispatchCsrfWarn,
   incomingMessageToWebRequest,
   sendError
-} from "./chunk-5K7WIT3Z.js";
+} from "./chunk-5BOKW3GX.js";
 import {
   enforceCsrf
 } from "./chunk-P6OS7652.js";
@@ -108,4 +108,4 @@ export {
   scanControllerModules,
   dispatchControllerRequest
 };
-//# sourceMappingURL=chunk-IQRL5KZL.js.map
+//# sourceMappingURL=chunk-VGE6AKEJ.js.map

package/dist/{chunk-DVYILYM6.js → chunk-YZCD3DWE.js}

@@ -1,6 +1,6 @@
 import {
   validateRouteInput
-} from "./chunk-5K7WIT3Z.js";
+} from "./chunk-5BOKW3GX.js";
 import {
   evaluateRoutePolicy,
   subjectFromContext
@@ -270,4 +270,4 @@ export {
   callProcedure,
   createOpenApiHandler
 };
-//# sourceMappingURL=chunk-DVYILYM6.js.map
+//# sourceMappingURL=chunk-YZCD3DWE.js.map

package/dist/chunk-ZDUO4IYN.js

@@ -0,0 +1,174 @@
+// src/core/contracts/action-protocol.ts
+var CODE_TO_STATUS = {
+  VALIDATION_ERROR: 422,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  CONTENT_TOO_LARGE: 413,
+  PAYLOAD_TOO_LARGE: 413,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500
+};
+var STATUS_TO_CODE = {
+  400: "BAD_REQUEST",
+  401: "UNAUTHORIZED",
+  403: "FORBIDDEN",
+  404: "NOT_FOUND",
+  405: "METHOD_NOT_ALLOWED",
+  409: "CONFLICT",
+  413: "PAYLOAD_TOO_LARGE",
+  415: "UNSUPPORTED_MEDIA_TYPE",
+  422: "VALIDATION_ERROR",
+  429: "TOO_MANY_REQUESTS",
+  500: "INTERNAL_SERVER_ERROR"
+};
+var ActionError = class _ActionError extends Error {
+  // Discriminator widened to the full union so subclasses can narrow to their
+  // specific literal (TypeScript would otherwise reject the override). Concrete
+  // values are still always exact literals at runtime.
+  type = "TheoActionError";
+  code;
+  status;
+  constructor(params) {
+    super(params.message ?? params.code);
+    this.code = params.code;
+    this.status = _ActionError.codeToStatus(params.code);
+    if (params.stack) {
+      this.stack = params.stack;
+    }
+  }
+  /**
+   * G5 T2.4 — canonical envelope view of the action error. Maps the G3
+   * ActionErrorCode to a canonical TheoErrorCode (VALIDATION_ERROR ↔
+   * UNPROCESSABLE_ENTITY, CONTENT_TOO_LARGE ↔ PAYLOAD_TOO_LARGE) so consumer
+   * UI / SDK code can switch on the unified envelope.
+   *
+   * Subclasses override to populate `ext` (see `ActionInputError.envelope`).
+   */
+  get envelope() {
+    return {
+      code: _ActionError.toTheoErrorCode(this.code),
+      message: this.message
+    };
+  }
+  /**
+   * Translate G3 ActionErrorCode → canonical TheoErrorCode (blueprint
+   * Recommendations § "G3 ActionError becomes inaugural envelope user").
+   */
+  static toTheoErrorCode(code) {
+    if (code === "VALIDATION_ERROR") return "UNPROCESSABLE_ENTITY";
+    if (code === "CONTENT_TOO_LARGE") return "PAYLOAD_TOO_LARGE";
+    return code;
+  }
+  static codeToStatus(code) {
+    return CODE_TO_STATUS[code];
+  }
+  static statusToCode(status) {
+    return STATUS_TO_CODE[status] ?? "INTERNAL_SERVER_ERROR";
+  }
+  /**
+   * Parse a serialized error JSON back into the typed class hierarchy.
+   * Distinguishes `TheoActionInputError` (with `issues` array) from
+   * `TheoActionError` via the `type` discriminator. Falls back to
+   * `INTERNAL_SERVER_ERROR` for malformed bodies (non-object, missing
+   * `type`, unknown `code`).
+   */
+  static fromJson(body) {
+    if (typeof body !== "object" || body === null) {
+      return new _ActionError({ code: "INTERNAL_SERVER_ERROR" });
+    }
+    const obj = body;
+    if (obj.type === "TheoActionInputError" && Array.isArray(obj.issues)) {
+      return new ActionInputError(obj.issues);
+    }
+    if (obj.type === "TheoActionError" && typeof obj.code === "string" && obj.code in CODE_TO_STATUS) {
+      return new _ActionError({
+        code: obj.code,
+        message: typeof obj.message === "string" ? obj.message : void 0
+      });
+    }
+    return new _ActionError({ code: "INTERNAL_SERVER_ERROR" });
+  }
+};
+var ActionInputError = class extends ActionError {
+  type = "TheoActionInputError";
+  issues;
+  fields;
+  constructor(rawIssues) {
+    super({ code: "VALIDATION_ERROR", message: "Validation failed" });
+    this.issues = extractUniversalIssues(rawIssues);
+    this.fields = buildFieldsMap(this.issues);
+  }
+  /**
+   * G5 T2.4 — envelope view with ValidationFieldsExt populated from .fields.
+   * UI consumers can `switch (env.code)` on `UNPROCESSABLE_ENTITY` and read
+   * `(env.ext as ValidationFieldsExt).fields` for field-level rendering.
+   */
+  get envelope() {
+    return {
+      code: "UNPROCESSABLE_ENTITY",
+      message: this.message,
+      ext: { fields: this.fields }
+    };
+  }
+};
+function buildFieldsMap(issues) {
+  const fields = {};
+  const seen = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    const key = issue.path.length === 0 ? "" : issue.path.join(".");
+    const dedupeKey = `${key}\0${issue.message}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    const bucket = fields[key] ?? [];
+    bucket.push(issue.message);
+    fields[key] = bucket;
+  }
+  return fields;
+}
+function extractUniversalIssues(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const obj = entry;
+    if (!Array.isArray(obj.path)) continue;
+    if (typeof obj.message !== "string") continue;
+    const path = [];
+    let pathValid = true;
+    for (const seg of obj.path) {
+      if (typeof seg === "string" || typeof seg === "number") {
+        path.push(seg);
+      } else {
+        pathValid = false;
+        break;
+      }
+    }
+    if (!pathValid) continue;
+    out.push({
+      path,
+      message: obj.message,
+      code: typeof obj.code === "string" ? obj.code : void 0
+    });
+  }
+  return out;
+}
+function isActionError(value) {
+  return value instanceof ActionError;
+}
+function isInputError(value) {
+  return value instanceof ActionInputError;
+}
+
+export {
+  ActionError,
+  ActionInputError,
+  extractUniversalIssues,
+  isActionError,
+  isInputError
+};
+//# sourceMappingURL=chunk-ZDUO4IYN.js.map

package/dist/chunk-ZDUO4IYN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/contracts/action-protocol.ts"],"mappings":"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","names":[]}

package/dist/cli/index.js

@@ -15,12 +15,12 @@ function cliVersion() {
 // src/cli/index.ts
 var cli = cac("theokit");
 cli.command("dev", "Start development server").option("--port <port>", "Port number").action(async (options) => {
-  const { devCommand } = await import("../dev-2NEKDLEY.js");
+  const { devCommand } = await import("../dev-W7OXHMSP.js");
   await devCommand({ port: options.port ? Number(options.port) : void 0 });
 });
 cli.command("build", "Build for production").option("--target <target>", "Deploy target (node, vercel, cloudflare)").action(async (options) => {
   try {
-    const { buildCommand } = await import("../build-MGNDNTXH.js");
+    const { buildCommand } = await import("../build-3AYYQZGQ.js");
     await buildCommand({ target: options.target });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -32,7 +32,7 @@ cli.command("build", "Build for production").option("--target <target>", "Deploy
 });
 cli.command("start", "Start production server").option("--port <port>", "Port number").action(async (options) => {
   try {
-    const { startCommand } = await import("../start-DMOVSFBL.js");
+    const { startCommand } = await import("../start-WILEDDW2.js");
     await startCommand({ port: options.port ? Number(options.port) : void 0 });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -44,7 +44,7 @@ cli.command("start", "Start production server").option("--port <port>", "Port nu
 });
 cli.command("preview", "Build for production, then serve it \u2014 one step (B-030)").option("--port <port>", "Port number").option("--target <target>", "Deploy target (node, vercel, cloudflare)").action(async (options) => {
   try {
-    const { previewCommand } = await import("../preview-D2RKY5ZA.js");
+    const { previewCommand } = await import("../preview-4ZTFJG2D.js");
     await previewCommand({
       port: options.port ? Number(options.port) : void 0,
       target: options.target
@@ -77,7 +77,7 @@ cli.command(
   "Run an agent in the terminal (stream + tool calls + approval)"
 ).action(async (name, message) => {
   try {
-    const { agentCommand } = await import("../agent-PLEYEX37.js");
+    const { agentCommand } = await import("../agent-AHGYRVQX.js");
     const { sawError } = await agentCommand(name, message);
     if (sawError) process.exit(1);
   } catch (err) {
@@ -108,7 +108,7 @@ cli.command("agent sessions gc", "Collect old transcripts for this project (dry
 });
 cli.command("mcp <agent>", "Serve an agent as an MCP server over stdio (for desktop MCP clients)").action(async (agent) => {
   try {
-    const { mcpCommand } = await import("../mcp-5AWKPETM.js");
+    const { mcpCommand } = await import("../mcp-7BXBN7PD.js");
     await mcpCommand(agent);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);

package/dist/client/index.d.ts

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { T as TheoErrorEnvelope } from '../error-envelope-DG47lt8E.js';
 export { FetchOptionsLike, Fetcher, QueryKey, UseTheoQueryConfig, buildUseTheoQueryConfig, stableQueryKey } from '../react-query/index.js';
 export { AgentClient, AgentClientState, AgentHandle, AgentStreamInterruptedError, AgentTransport, ApprovalDecision, ChannelPushSource, ChannelTransport, ChannelTransportOptions, ChannelTurnHandlers, HttpTransport, HttpTransportOptions, InProcessApprovalRequestLike, InProcessAwaitApproval, InProcessRunInput, InProcessRunner, InProcessTransport, InProcessTransportOptions, RequestContext, agentHandle, consumeChunkStream, consumeUIMessageStream, isAgentHandle, responseToChunkStream } from '@theokit/agents/client';
+import { A as ActionError } from '../action-protocol-tGm3NKRg.js';
+export { a as ActionErrorCode, b as ActionInputError, c as ActionResult, i as isActionError, d as isInputError } from '../action-protocol-tGm3NKRg.js';
 export { PendingApproval, UseAgentOptions, UseAgentReturn, UseAgentStatus, useAgent } from '@theokit/agents/client/react';
 export { AgentClientHandle, CreateAgentClientOptions, createAgentClient } from './core.js';
 import * as react from 'react';
@@ -118,6 +120,120 @@ interface Batcher {
 }
 declare function createBatcher(options: BatcherOptions): Batcher;
 
+/**
+ * usetheokit/theokit#453 — the framework-agnostic store behind {@link useAction}.
+ *
+ * `core/contracts/action-protocol.ts` opens by describing itself as the "cross-boundary contract
+ * for `defineAction` + `useAction`" and points the client half at `@theokit/react/useAction` — a
+ * package outside this repository, with one version, no `repository` field, and a
+ * `@theokit/sdk ^1.1.0` peer against a published 4.x. The server half of that contract has always
+ * lived here; this is the client half arriving.
+ *
+ * The state machine lives in a store rather than in the hook, following `useAgent`: it is testable
+ * with no DOM, and a non-React surface can subscribe to it directly. The hook in `use-action.ts` is
+ * a `useSyncExternalStore` binding over it.
+ */
+/**
+ * What a generated callable resolves.
+ *
+ * Deliberately NOT `ActionResult`, whose `error` is an `ActionError` instance: the envelope crosses
+ * the wire as JSON, so what arrives is a plain object, and a callable typed against the class would
+ * be one no honest implementation can satisfy. `error` is `unknown` here and normalized on the way
+ * into the state.
+ *
+ * Both keys are present — the generated facade always emits both — which is also what tells an
+ * envelope apart from a payload that merely has a field named `data` or `error`.
+ */
+interface ActionEnvelope<TData = unknown> {
+    readonly data: TData | undefined;
+    readonly error: unknown;
+}
+/**
+ * A callable shaped like the ones `@theo/actions` generates. They resolve an
+ * {@link ActionEnvelope} rather than throwing — including for network failure — but a hand-written
+ * callable that resolves a bare value or throws is handled too, since consumers pass both.
+ */
+type ActionCallable<TInput = unknown, TData = unknown> = (input: TInput) => Promise<ActionEnvelope<TData> | TData>;
+type ActionStatus = 'idle' | 'pending' | 'error' | 'success';
+/** The observable state, one frozen object per transition (`useSyncExternalStore` contract). */
+interface ActionState<TInput = unknown, TData = unknown> {
+    readonly status: ActionStatus;
+    readonly data: TData | undefined;
+    readonly error: ActionError | undefined;
+    /** The input of the most recent call — what a retry button replays. */
+    readonly variables: TInput | undefined;
+}
+/**
+ * Holds `{status, data, error, variables}` for one action callable and notifies subscribers on each
+ * transition.
+ */
+declare class ActionClient<TInput = unknown, TData = unknown> {
+    #private;
+    constructor(action: ActionCallable<TInput, TData>);
+    /** Subscribe to state changes; returns an unsubscribe fn. */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * The current snapshot, stable by reference until the next transition. Allocating here instead
+     * would re-render a React consumer forever.
+     */
+    getSnapshot: () => ActionState<TInput, TData>;
+    /** Invoke the action, resolving its data or rejecting with a typed {@link ActionError}. */
+    mutateAsync: (input: TInput) => Promise<TData>;
+    /**
+     * Fire-and-forget: the outcome lands in the state, and the returned promise is consumed here so a
+     * failure does not surface as an unhandled rejection in a component that only reads `isError`.
+     */
+    mutate: (input: TInput) => void;
+    /** Back to idle, discarding whatever is in flight. */
+    reset: () => void;
+}
+
+/**
+ * usetheokit/theokit#453 — call a server action from a component and track its state.
+ *
+ * The framework already generates the typed callable (`@theo/actions`), serves it at
+ * `/api/__actions/`, and defines the error hierarchy it answers with. This is the last piece:
+ *
+ * ```tsx
+ * import { actions } from '@theo/actions'
+ * import { useAction } from 'theokit/client'
+ *
+ * function SaveButton() {
+ *   const save = useAction(actions.saveMemory)
+ *   return (
+ *     <button disabled={save.isPending} onClick={() => save.mutate({ content: 'hi' })}>
+ *       {save.isPending ? 'Saving…' : 'Save'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * A failure lands in `error` as the protocol's own {@link ActionError} — so a validation failure is
+ * an `ActionInputError` with its `fields` map intact, which is what a form library binds to.
+ *
+ * The state machine lives in {@link ActionClient}; this is a `useSyncExternalStore` binding over it,
+ * the same shape as `useAgent`.
+ */
+interface UseActionResult<TInput = unknown, TData = unknown> {
+    /** The data of the most recent successful call. */
+    data: TData | undefined;
+    /** The typed error of the most recent failed call. */
+    error: ActionError | undefined;
+    isIdle: boolean;
+    isPending: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    /** The input of the most recent call — what a retry button replays. */
+    variables: TInput | undefined;
+    /** Fire and forget; read the outcome off `isPending` / `error`. */
+    mutate: (input: TInput) => void;
+    /** Await the data, or catch the typed {@link ActionError}. */
+    mutateAsync: (input: TInput) => Promise<TData>;
+    /** Back to idle, discarding whatever is in flight. */
+    reset: () => void;
+}
+declare function useAction<TInput = unknown, TData = unknown>(action: ActionCallable<TInput, TData>): UseActionResult<TInput, TData>;
+
 type PrefetchBehavior = 'none' | 'intent' | 'viewport';
 interface LinkProps extends LinkProps$1 {
     /** Prefetch strategy. Default: 'intent' (on hover + focus). */
@@ -299,4 +415,4 @@ declare function mountMcpApp(container: HTMLElement, resource: {
     html: string;
 }, opts: McpAppHostOptions): McpAppHandle;
 
-export { type BatchRequest, type BatchResponse, type BatchTransport, type Batcher, type BatcherOptions, type CreateAppClientOptions, type GuestMessage, Image, type ImageProps, type InferBody, type InferQuery, type InferResponse, Link, type LinkProps, MCP_APP_SANDBOX, type McpAppHandle, type McpAppHostOptions, Metadata, type MetadataProps, type PrefetchBehavior, TheoFetchError, type TheoFetchOptions, createAppClient, createBatcher, createGuestMessageHandler, mountMcpApp, theoFetch };
+export { type ActionCallable, ActionClient, type ActionEnvelope, ActionError, type ActionState, type ActionStatus, type BatchRequest, type BatchResponse, type BatchTransport, type Batcher, type BatcherOptions, type CreateAppClientOptions, type GuestMessage, Image, type ImageProps, type InferBody, type InferQuery, type InferResponse, Link, type LinkProps, MCP_APP_SANDBOX, type McpAppHandle, type McpAppHostOptions, Metadata, type MetadataProps, type PrefetchBehavior, TheoFetchError, type TheoFetchOptions, type UseActionResult, createAppClient, createBatcher, createGuestMessageHandler, mountMcpApp, theoFetch, useAction };