Code Mode は 6 つのパッケージエントリポイントを公開します。フレームワーク固有の API は、対応するエントリポイントからインポートします。
| エントリポイント | 用途 |
|---|---|
@cloudflare/codemode |
ランタイム、コネクタ、Workers エグゼキュータ、フレームワーク非依存のユーティリティ |
@cloudflare/codemode/ai |
AI SDK のツールとコネクタアダプタ |
@cloudflare/codemode/mcp |
Model Context Protocol (MCP) サーバーラッパー |
@cloudflare/codemode/tanstack-ai |
TanStack AI のツールとアダプタ |
@cloudflare/codemode/browser |
ブラウザー向けツール記述子と iframe エグゼキュータ |
@cloudflare/codemode/vite |
コネクタ検出と Worker エクスポート向けの Vite プラグイン |
メインのエントリポイントは、任意の AI SDK、TanStack AI、Zod の peer dependencies のインストールを要求しません。
function createCodemodeRuntime(
options: CreateCodemodeRuntimeOptions,
): CodemodeRuntimeHandle;名前付き Code Mode ランタイム向けの、ホスト側コントロールプレーンを作成します。
CreateCodemodeRuntimeOptions のフィールドは次のとおりです。
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
ctx |
DurableObjectState |
はい | ランタイム facet をホストする Durable Object の状態です。 |
connectors |
CodemodeConnector[] |
はい | サンドボックスのグローバルとして公開するコネクタです。コネクタ名は一意である必要があり、codemode は予約されています。 |
executor |
Executor |
はい | 生成コードを実行するサンドボックスです。 |
name |
string |
いいえ | 耐久ランタイムの ID です。デフォルトは "default" です。使える文字は英字、数字、_、-、. です。 |
maxExecutions |
number |
いいえ | 新しい実行が始まるときに残す終端レコード数です。デフォルトは 50 です。実行中および一時停止中の実行は刈り込みません。 |
transformResult |
TransformResult |
いいえ | モデルへ返す完了結果を整形します。監査証跡は未変更の結果を保持します。 |
interface CodemodeRuntimeHandle {
tool(
options?: CodemodeRuntimeToolOptions,
): Tool<ProxyToolInput, ProxyToolOutput>;
execute(input: ProxyToolInput): Promise<ProxyToolOutput>;
search(query: string): Promise<SearchOutput>;
describe(target: string): Promise<DescribeOutput>;
approve(options: CodemodeApproveOptions): Promise<ProxyToolOutput>;
reject(options: CodemodeRejectOptions): Promise<boolean>;
rollback(options: CodemodeRollbackOptions): Promise<void>;
pending(executionId?: string): Promise<PendingAction[]>;
expirePaused(options?: CodemodeExpireOptions): Promise<string[]>;
executions(limit?: number): Promise<ExecutionState[]>;
deleteExecution(id: string): Promise<boolean>;
pruneExecutions(keep?: number): Promise<number>;
saveSnippet(name: string, options: SaveSnippetOptions): Promise<Snippet>;
snippets(): Promise<Snippet[]>;
deleteSnippet(name: string): Promise<boolean>;
}ハンドルメソッドの効果は次のとおりです。
| メソッド | 効果 |
|---|---|
tool(options?) |
モデルへ渡す AI SDK ツールを返します。description はデフォルトの説明を置き換えます。connectorHints は、デフォルト説明を使うときに各コネクタへ 1 行のヒントを足します。 |
execute({ code }) |
ランタイムを AI SDK ツールへ適応せず、コードを直接実行します。結果は完了、承認待ちの一時停止、またはエラーステータスのいずれかです。 |
search(query) |
サンドボックスコードを実行せず、コネクタメソッドと保存済みスニペットを検索します。 |
describe(target) |
コネクタ、メソッド、または保存済みスニペット向けの、オンデマンド TypeScript ドキュメントを返します。 |
approve({ executionId }) |
リプレイ経由で一時停止中の実行を再開します。結果は完了、再一時停止、またはエラーステータスのいずれかです。一時停止以外の実行は復活しません。 |
reject({ seq, executionId }) |
保留中のアクション 1 件を拒否し、実行を終了します。アクションがすでに保留でなければ false を返します。それより前のアクションはロールバックしません。 |
rollback({ executionId }) |
利用可能な revert 関数を呼び出しの逆順で呼びます。コネクタ欠損と revert のないメソッドは適用済みのままです。失敗後も後続の revert を試みます。 |
pending(executionId?) |
保留中のアクションを一覧します。ID なしでは、一時停止中の全実行のアクションをまとめます。 |
expirePaused({ maxAgeMs? }) |
古い一時停止中または実行中の実行を終了し、その ID を返します。デフォルトの経過時間は 24 時間です。 |
executions(limit?) |
監査レコードを新しい順で返します。 |
deleteExecution(id) |
監査レコードを 1 件削除します。非終端の実行のリソースも破棄します。レコードが存在したかどうかを返します。 |
pruneExecutions(keep?) |
古い終端レコードを削除し、削除件数を返します。デフォルトは 50 件残します。 |
saveSnippet(name, options) |
options.executionId のコードを再利用可能なスニペットとして保存します。任意の実行ステータスを受け付けるので、アプリケーション側で先に成功完了を確認してください。同じ名前は置き換えます。 |
snippets() |
保存済みスニペットを名前順で返します。 |
deleteSnippet(name) |
スニペットを削除し、存在したかどうかを返します。 |
メソッドオプションの型は次のとおりです。
type CodemodeRuntimeToolOptions = {
description?: string;
connectorHints?: Record<string, string>;
};
type CodemodeApproveOptions = { executionId: string };
type CodemodeRejectOptions = { seq: number; executionId: string };
type CodemodeRollbackOptions = { executionId: string };
type CodemodeExpireOptions = { maxAgeMs?: number };class CodemodeRuntime extends DurableObject<unknown> {
constructor(ctx: DurableObjectState, env: unknown);
}CodemodeRuntime は、ランタイムハンドル背後の耐久 facet です。Vite プラグインはこのクラスを Worker エントリモジュールからエクスポートします。アプリケーションコードでは facet を直接構築せず、createCodemodeRuntime() を使います。
メインのエントリポイントは、次のランタイム定数もエクスポートします。
| 定数 | 値 | 用途 |
|---|---|---|
DEFAULT_MAX_EXECUTIONS |
50 |
終端実行のデフォルト保持件数 |
DEFAULT_PAUSED_TTL_MS |
86400000 |
古い実行のデフォルト経過時間（ミリ秒、24 時間） |
MAX_DURABLE_VALUE_BYTES |
1000000 |
1 つの耐久値に対する、シリアライズ済み JavaScript 文字列長の上限 |
type ProxyToolInput = { code: string };
type ProxyToolOutput =
| {
status: "completed";
executionId: string;
result: unknown;
logs?: string[];
}
| {
status: "paused";
executionId: string;
pending: PendingAction[];
}
| {
status: "error";
executionId: string;
error: string;
logs?: string[];
};
type TransformResult = (result: unknown) => unknown | Promise<unknown>;サンドボックスとリプレイのエラーは error 出力バリアントを使います。モデルのツール呼び出しを通じて例外は投げません。
type ExecutionStatus =
| "running"
| "paused"
| "completed"
| "error"
| "rejected"
| "rolled_back";
type ExecutionState = {
id: string;
code: string;
status: ExecutionStatus;
log: ToolLogEntry[];
result?: unknown;
error?: string;
logs?: string[];
connectors?: string[];
createdAt: number;
updatedAt: number;
};
type ToolLogEntry = {
seq: number;
connector: string;
method: string;
args: unknown;
result?: unknown;
requiresApproval: boolean;
ephemeral?: boolean;
state: "executing" | "applied" | "pending" | "reverted" | "error";
};
type PendingAction = {
executionId: string;
seq: number;
connector: string;
method: string;
args: unknown;
};createdAt と updatedAt はエポックミリ秒です。一時的なログエントリは、replay: "reexecute" のコネクタツールから来ます。結果は保存されず、リプレイ時に呼び出しが再実行されます。
ランタイムの決定型は次のとおりです。
type ToolDecision =
| { kind: "replay"; result: unknown }
| { kind: "execute"; seq: number }
| { kind: "pause"; seq: number };runtime.tool() は、生成されたサンドボックスコードへ codemode グローバルを注入します。
declare const codemode: {
search(query: string): Promise<SearchOutput>;
describe(target: string): Promise<DescribeOutput>;
step<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
run(name: string, input?: unknown): Promise<unknown>;
};サンドボックスメソッドの挙動は次のとおりです。
| メソッド | 説明 |
|---|---|
search(query) |
コネクタメソッドと保存済みスニペットを検索します。結果は順位付けされ、上限は 50 件です。 |
describe(target) |
コネクタ、connector.method、またはスニペット名向けに生成した TypeScript を返します。 |
step(name, fn) |
クロージャを 1 回実行し、結果を記録します。リプレイでは記録済み結果を返し、クロージャは再実行しません。 |
run(name, input?) |
保存済みスニペットを実行します。スニペット欠損または記録済みコネクタは、error プロパティ付きオブジェクトに解決します。 |
コネクタを使わない、非決定的または副作用のあるサンドボックス作業は step() で囲みます。実行が一時停止しうるときは、コネクタ呼び出しを順次発行してください。並行呼び出しは、リプレイカーソルに別の順で到達することがあります。
検出出力の型は次のとおりです。
type SearchResult = {
path: string;
connector: string;
method: string;
description?: string;
requiresApproval?: boolean;
kind: "method" | "snippet";
score: number;
};
type SearchOutput = {
results: SearchResult[];
total: number;
truncated: boolean;
};
type DescribeOutput = {
path: string;
description?: string;
requiresApproval?: boolean;
types: string;
kind: "connector" | "method" | "snippet";
};コネクタメソッドが実行前に一時停止する場合、requiresApproval は true です。承認不要のメソッドとスニペットでは省略されます。
interface SaveSnippetOptions {
description?: string;
inputSchema?: unknown;
executionId: string;
}
interface Snippet {
name: string;
description: string;
code: string;
savedAt: number;
inputSchema?: unknown;
connectors?: string[];
}connectors は、元の実行開始時に設定されていたすべての名前空間を記録します。savedAt はエポックミリ秒です。saveSnippet() を呼ぶ前に、元の ExecutionState.status が completed であることを確認してください。
interface Executor {
execute(
code: string,
providersOrFns:
| ResolvedProvider[]
| Record<string, (...args: unknown[]) => Promise<unknown>>,
options?: ExecuteOptions,
): Promise<ExecuteResult>;
}カスタムエグゼキュータは、例外を投げる代わりに失敗を ExecuteResult.error で報告してください。
interface ExecuteResult {
result: unknown;
error?: string;
logs?: string[];
}
interface ResolvedProvider {
name: string;
fns: Record<string, (...args: unknown[]) => Promise<unknown>>;
prelude?: string;
}
interface ConnectorBinding {
name: string;
binding: {
callTool(method: string, args: unknown): Promise<unknown>;
};
}
interface ExecuteOptions {
connectors?: ConnectorBinding[];
}ResolvedProvider[] の代わりに関数レコードを渡すのは非推奨です。codemode という名前のプロバイダーが 1 つ作られます。
class DynamicWorkerExecutor implements Executor {
constructor(options: DynamicWorkerExecutorOptions);
execute(
code: string,
providersOrFns:
| ResolvedProvider[]
| Record<string, (...args: unknown[]) => Promise<unknown>>,
options?: ExecuteOptions,
): Promise<ExecuteResult>;
}DynamicWorkerExecutorOptions のフィールドは次のとおりです。
| フィールド | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
loader |
WorkerLoader |
はい | — | 隔離された Workers の作成に使う Worker Loader バインディングです。 |
timeout |
number |
いいえ | 60000 |
実行タイムアウト（ミリ秒）です。 |
globalOutbound |
Fetcher | null |
いいえ | null |
送信ネットワークポリシーです。null はアクセスを遮断します。Fetcher はすべての送信リクエストを受け取ります。 |
modules |
Record<string, string> |
いいえ | {} |
import specifier をキーにしたモジュールソースです。予約済みの executor.js キーは無視されます。 |
bindings |
Record<string, unknown> |
いいえ | {} |
各サンドボックス Worker へ注入する追加の環境バインディングです。 |
エグゼキュータはプロバイダーとコネクタの名前空間を検証します。名前は有効な JavaScript 識別子で、一意であり、エグゼキュータのグローバルをシャドウしてはいけません。
class ToolDispatcher extends RpcTarget {
constructor(fns: Record<string, (...args: unknown[]) => Promise<unknown>>);
call(name: string, argsJson?: string): Promise<string>;
}ToolDispatcher は DynamicWorkerExecutor が使う Workers RPC ブリッジです。call() はシリアライズされた位置引数を受け取り、シリアライズされた結果またはエラーエンベロープを返します。
function runCode(options: {
code: string;
executor: Executor;
providers: ResolvedProvider[];
connectors?: ConnectorBinding[];
}): Promise<{ result: unknown; logs?: string[] }>;コードを正規化して実行します。ExecuteResult.error があると、runCode() はキャプチャした console 出力を含む Error を投げます。
interface ToolProvider {
name?: string;
tools: ToolDescriptors | ToolSet | SimpleToolRecord;
types?: string;
}ツールプロバイダーのフィールドは次のとおりです。
| フィールド | 説明 |
|---|---|
name |
サンドボックスの名前空間です。デフォルトは codemode です。 |
tools |
ツール記述子、AI SDK の ToolSet、または execute を含むレコードです。 |
types |
モデルへ示す TypeScript 宣言です。省略時は Code Mode が生成します。 |
function resolveProvider(provider: ToolProvider): ResolvedProvider;メインエントリの実装は、入力をスキーマに対して検証しません。needsApproval が true または関数であるツールは除外します。耐久的な承認フローにはランタイムコネクタを使います。
abstract class CodemodeConnector<
Env = unknown,
Props = unknown,
> extends WorkerEntrypoint<Env, Props> {
constructor(ctx: DurableObjectState | ExecutionContext, env: Env);
abstract name(): string;
protected instructions(): string | undefined;
protected abstract tools(): ConnectorTools | Promise<ConnectorTools>;
protected tool(name: string, tool: ConnectorTool): ConnectorTool;
describe(): Promise<ConnectorDescription>;
executeTool(
method: string,
args: unknown,
ctx?: ToolExecuteContext,
): Promise<unknown>;
revertAction(
method: string,
args: unknown,
result: unknown,
ctx?: ToolExecuteContext,
): Promise<boolean>;
onPassEnd(executionId: string, status: PassEndStatus): Promise<void>;
disposeExecution(
executionId: string,
status: ExecutionEndStatus,
): Promise<void>;
getTypeScriptTypes(): Promise<string>;
}コネクタ作者は、次のフックを実装またはオーバーライドします。
| フック | 必須 | 説明 |
|---|---|---|
name() |
はい | 一意のサンドボックス名前空間を返します。 |
instructions() |
いいえ | describe() に含めるコネクタ案内を返します。 |
tools() |
はい | コネクタのツールレコードを返します。派生コネクタはこのフックを実装します。 |
tool(name, tool) |
いいえ | 解決済みツールを装飾します。派生ツールへ承認、リプレイ、revert の挙動を足すときに使います。 |
onPassEnd(executionId, status) |
いいえ | パス単位のリソースを解放します。一時停止パスを含め、すべてのパスのあとに実行されます。 |
disposeExecution(executionId, status) |
いいえ | 終端遷移のあと、実行単位のリソースを解放します。一時停止では実行されません。 |
ライフサイクルフックは冪等であるべきで、インスタンスメモリに依存すべきではなく、例外を投げるべきではありません。終端パスでは、onPassEnd() が disposeExecution() より先に実行されます。
基底クラスはツールレコードから describe()、executeTool()、revertAction()、getTypeScriptTypes() を導出します。コネクタ作者がこれらのメソッドを実装する必要はありません。
type ConnectorTool = {
description?: string;
inputSchema?: JSONSchema7;
outputSchema?: JSONSchema7;
requiresApproval?: boolean;
replay?: "log" | "reexecute";
execute: (
args: unknown,
ctx?: ToolExecuteContext,
) => Promise<unknown> | unknown;
revert?: (
args: unknown,
result: unknown,
ctx?: ToolExecuteContext,
) => Promise<void> | void;
};
type ConnectorTools = Record<string, ConnectorTool>;
type ToolExecuteContext = { executionId: string };inputSchema のデフォルトは開いたオブジェクトです。requiresApproval: true は実行前に一時停止します。replay: "reexecute" は耐久的な結果保存をスキップし、再開のたびに呼び出しを再実行します。この 2 つのオプションは同時に使えません。
revert は runtime.rollback() 向けの補償を提供します。承認の要否に関係なく、任意のツールに適用できます。
abstract class McpConnector<
Env = unknown,
Props = unknown,
> extends CodemodeConnector<Env, Props> {
protected abstract createConnection():
| McpConnectionLike
| Promise<McpConnectionLike>;
protected toolName(tool: McpTool): string;
}McpConnector は各 MCP ツールをコネクタメソッドへ変換します。toolName() のデフォルトは sanitizeToolName(tool.name) です。名前衝突を解消するにはオーバーライドします。
interface McpConnectionLike {
name?: string;
client: Pick<Client, "callTool">;
instructions?: string;
tools?: McpTool[];
fetchTools?: () => Promise<McpTool[]>;
}コネクタは、その配列が空でなければ tools を使います。そうでなければ、提供されていれば fetchTools() を呼びます。MCP のエラー結果は、投げられるコネクタエラーになります。構造化コンテンツはテキストコンテンツより先に返されます。
abstract class OpenApiConnector<
Env = unknown,
Props = unknown,
> extends CodemodeConnector<Env, Props> {
protected abstract spec():
| Record<string, unknown>
| Promise<Record<string, unknown>>;
protected abstract request(options: OpenApiRequestOptions): Promise<unknown>;
protected exposeSpec(): boolean;
}OpenApiConnector は OpenAPI オペレーションごとに 1 メソッドを作ります。ある場合はサニタイズした operationId を使い、なければ HTTP メソッドとパスに基づく名前へフォールバックします。重複オペレーションと、request または spec 向けに予約された名前はスキップされます。
すべての OpenAPI コネクタは低レベルの request メソッドを公開します。exposeSpec() のデフォルトは false です。spec も公開するには true を返します。
type OpenApiRequestOptions = {
path: string;
method?: string;
params?: Record<string, unknown>;
body?: unknown;
headers?: Record<string, string>;
};派生オペレーションツールはパスパラメータを置換します。クエリ値は params、ヘッダー値は headers、JSON リクエストデータは body として渡します。
type ExecutionEndStatus = "completed" | "error" | "rejected" | "rolled_back";
type PassEndStatus = ExecutionEndStatus | "paused";
type ToolAnnotations = {
requiresApproval?: boolean;
replay?: "log" | "reexecute";
};
type ConnectorDescription = {
name: string;
instructions?: string;
descriptors: JsonSchemaToolDescriptors;
annotations?: Record<string, ToolAnnotations>;
};interface JsonSchemaToolDescriptor {
description?: string;
inputSchema: JSONSchema7;
outputSchema?: JSONSchema7;
}
type JsonSchemaToolDescriptors = Record<string, JsonSchemaToolDescriptor>;
function generateTypesFromJsonSchema(tools: JsonSchemaToolDescriptors): string;
function jsonSchemaToType(schema: JSONSchema7, typeName: string): string;generateTypesFromJsonSchema() は codemode 名前空間向けの宣言を返します。宣言生成前にツール名はサニタイズされます。未対応スキーマは生成失敗ではなく unknown へ劣化します。
メインのエントリポイントは、次のコードおよび結果ユーティリティを提供します。
| 関数 | シグネチャ | 挙動 |
|---|---|---|
sanitizeToolName |
(name: string) => string |
よくある区切りを置換し、無効な文字を除き、数字始まりの名前に接頭辞を付け、JavaScript 予約語に接尾辞を付けます。 |
normalizeCode |
(code: string) => string |
よくあるモデル出力形式を async アロー関数へ変換します。対応する Markdown フェンスも取り除きます。 |
truncateResponse |
(text: string, options?: TruncateOptions) => string |
文字バジェットまでテキストを切り詰め、サイズマーカーを付けます。 |
truncateResult |
(value: unknown, options?: TruncateOptions) => unknown |
小さな構造化値は保持します。大きすぎるシリアライズ可能値は切り詰めた JSON テキストになります。 |
type TruncateOptions = {
maxChars?: number;
maxTokens?: number;
};デフォルトのバジェットは、トークンあたり 4 文字で推定トークン 6000 です。maxChars は導出された文字バジェットを上書きします。
このエントリポイントは ai と zod の peer dependencies を要求します。
function createCodeTool(
options: CreateCodeToolOptions,
): Tool<CodeInput, CodeOutput>;
interface CreateCodeToolOptions {
tools: ToolProviderTools | ToolProvider[];
executor: Executor;
description?: string;
}
type CodeInput = { code: string };
type CodeOutput = { result: unknown; logs?: string[] };description には {{types}} を含められます。Code Mode はそのトークンを生成した宣言で置き換えます。生のツールレコードは codemode という名前のプロバイダー 1 つになります。配列なら複数のプロバイダー名前空間を受け付けます。
needsApproval が true または関数であるツールは除外されます。この API は一時停止しません。耐久的な承認処理には createCodemodeRuntime() とコネクタを使います。
AI SDK エントリポイントは、次のツールプロバイダーユーティリティを提供します。
| エクスポート | シグネチャ | 説明 |
|---|---|---|
aiTools |
(tools: ToolDescriptors | ToolSet) => ToolProvider |
AI SDK ツールをデフォルトプロバイダーでラップします。 |
generateTypes |
(tools: ToolDescriptors | ToolSet, namespace?: string) => string |
AI SDK または Zod スキーマから宣言を生成します。名前空間のデフォルトは codemode です。 |
resolveProvider |
(provider: ToolProvider) => ResolvedProvider |
承認ゲート付きツールを除外し、利用可能なら AI SDK の asSchema() で入力を検証し、実行可能な関数を取り出します。 |
interface ToolDescriptor {
description?: string;
inputSchema: ZodType;
outputSchema?: ZodType;
execute?: (args: unknown) => Promise<unknown>;
}
type ToolDescriptors = Record<string, ToolDescriptor>;class ToolSetConnector extends CodemodeConnector {
constructor(
ctx: DurableObjectState | ExecutionContext,
options: ToolSetConnectorOptions,
);
}
function toolSetConnector(
ctx: DurableObjectState | ExecutionContext,
options: ToolSetConnectorOptions,
): ToolSetConnector;
interface ToolSetConnectorOptions {
name?: string;
instructions?: string;
tools: ToolSet;
}名前空間のデフォルトは tools です。コネクタは execute 関数のないツールを除外します。needsApproval: true と関数値の needsApproval は、耐久コネクタ承認へ対応付けます。needsApproval: false は承認なしで実行します。実行前に AI SDK スキーマが入力を検証します。
このエントリポイントは MCP SDK と Zod の peer dependencies を要求します。
interface CodeMcpServerOptions {
server: McpServer;
executor: Executor;
description?: string;
}
function codeMcpServer(options: CodeMcpServerOptions): Promise<McpServer>;既存の MCP サーバーを、1 つの code ツールでラップします。ラッパーはインメモリトランスポートでソースサーバーへ接続し、ツールを発見し、それらのツールをエグゼキュータ内の codemode 上のメソッドとして公開します。
カスタム説明には {{types}} を含められ、ラッパーが生成した TypeScript 宣言で置き換えます。{{example}} も含められ、ラッパーが最初の上流 MCP ツールに基づく呼び出し例で置き換えます。返される MCP 値は次の順でアンラップされます。互換の toolResult、MCP エラー、structuredContent、すべてテキストのコンテンツ、元の混合コンテンツ結果。
interface OpenApiMcpServerOptions {
spec: Record<string, unknown>;
executor: Executor;
request: (options: RequestOptions) => Promise<unknown>;
name?: string;
version?: string;
description?: string;
}
interface RequestOptions {
method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
path: string;
query?: Record<string, string | number | boolean | undefined>;
body?: unknown;
contentType?: string;
rawBody?: boolean;
}
function openApiMcpServer(options: OpenApiMcpServerOptions): McpServer;次の 2 ツールを持つ MCP サーバーを作成します。
| MCP ツール | サンドボックス API | 用途 |
|---|---|---|
search |
codemode.spec() |
OpenAPI ドキュメントに対してコードを実行します。ローカルの $ref 値は、コードがドキュメントを受け取る前に解決されます。 |
execute |
codemode.spec() と codemode.request(options) |
ドキュメントを検査し、ホスト提供の request 関数を呼べるコードを実行します。 |
name のデフォルトは openapi です。version のデフォルトは 1.0.0 です。ホストの request 関数が認証情報をサンドボックスの外に保ちます。テキスト応答はおおよそ 6,000 トークンに制限され、切り詰めたときは切り詰めマーカーが付きます。
search と execute のツール説明は固定の例スニペットを使います。codeMcpServer() と違い、この関数は {{types}} や {{example}} プレースホルダをサポートしません。任意の description は execute ツールの説明へ追記されます。
このエントリポイントは @tanstack/ai と zod の peer dependencies を要求します。
function createCodeTool(options: CreateCodeToolOptions): ServerTool;オプション、CodeInput、CodeOutput は /ai エントリポイントと同じです。返される ServerTool は TanStack AI の chat() へ渡せます。
TanStack AI エントリポイントは、次のツールプロバイダーユーティリティを提供します。
| エクスポート | シグネチャ | 説明 |
|---|---|---|
tanstackTools |
(tools: TanStackTool[], name?: string) => ToolProvider |
TanStack AI ツールをプロバイダーでラップします。execute 関数があるツールだけが呼び出せます。名前空間のデフォルトは codemode です。 |
generateTypes |
(tools: TanStackTool[], namespace?: string) => string |
対応する TanStack AI スキーマを JSON Schema へ変換し、宣言を生成します。 |
resolveProvider |
(provider: ToolProvider) => ResolvedProvider |
スキーマ検証なしで、フレームワーク非依存のプロバイダーを解決します。 |
normalizeProviders |
(tools: ToolProviderTools | ToolProvider[]) => ToolProvider[] |
生のツールを 1 要素のプロバイダー配列へ変換します。 |
このエントリポイントは DEFAULT_DESCRIPTION もエクスポートします。tanstackTools() は needsApproval: true または関数値の needsApproval を持つツールを除外します。needsApproval: false のツールは呼び出せたままです。
ブラウザーエントリポイントはブラウザー API とプレーンな JSON Schema を使います。AI SDK や Zod は不要です。
function createBrowserCodeTool(
options: CreateBrowserCodeToolOptions,
): BrowserCodeToolDescriptor;
interface CreateBrowserCodeToolOptions {
tools:
| JsonSchemaExecutableToolDescriptor[]
| JsonSchemaExecutableToolDescriptors;
executor?: Executor;
description?: string;
}配列形式のツールには name が必要です。オブジェクト形式のツールは、各レコードキーを名前として使います。エグゼキュータのデフォルトは新しい IframeSandboxExecutor です。
tools オプションは needsApproval?: boolean | ((...args: unknown[]) => unknown) 付きの記述子も受け付けます。needsApproval: true または関数値の needsApproval を持つツールは除外されます。needsApproval: false のツールは呼び出せたままです。JSON Schema はモデル向け宣言に寄与しますが、実行時検証は行いません。
interface JsonSchemaExecutableToolDescriptor extends JsonSchemaToolDescriptor {
name?: string;
execute: (args: Record<string, unknown>) => Promise<unknown>;
}
type JsonSchemaExecutableToolDescriptors = Record<
string,
JsonSchemaExecutableToolDescriptor
>;返される記述子の形は次のとおりです。
interface BrowserCodeToolDescriptor {
name: string;
description: string;
inputSchema: {
type: "object";
properties: {
code: { type: "string"; description: string };
};
required: ["code"];
};
outputSchema: {
type: "object";
properties: {
result: { description: string };
logs: {
type: "array";
items: { type: "string" };
description: string;
};
};
required: ["result"];
};
execute(args: CodeInput): Promise<CodeOutput>;
}class IframeSandboxExecutor implements Executor {
constructor(options?: IframeSandboxExecutorOptions);
execute(
code: string,
providersOrFns:
| ResolvedProvider[]
| Record<string, (...args: unknown[]) => Promise<unknown>>,
): Promise<ExecuteResult>;
}
interface IframeSandboxExecutorOptions {
timeout?: number;
csp?: string;
}iframe エグゼキュータが受け付けるオプションは次のとおりです。
| フィールド | デフォルト | 説明 |
|---|---|---|
timeout |
30000 |
最大実行時間（ミリ秒）です。ブラウザーのイベントループを塞ぐ同期ループは先取りできません。 |
csp |
default-src 'none'; script-src 'unsafe-inline' 'unsafe-eval'; |
サンドボックス iframe ドキュメントに適用する Content Security Policy です。 |
各実行は sandbox="allow-scripts" の隠し iframe を作ります。ツール呼び出しは nonce スコープの postMessage で iframe 境界を越えます。iframe は成功、エラー、またはタイムアウトのあとに削除されます。
このエントリポイントは、フレームワーク非依存の Executor、ExecuteResult、ResolvedProvider 型もエクスポートします。JsonSchemaToolDescriptor と JsonSchemaToolDescriptors を再エクスポートします。
Vite エントリポイントのデフォルトエクスポートは 1 つです。
function codemodeVitePlugin(): Plugin;プラグインは Worker エントリモジュール（src/server.ts、src/index.ts、または src/worker.ts）へ export { CodemodeRuntime } from "@cloudflare/codemode" を追記します。これによりランタイム facet が ctx.exports.CodemodeRuntime として使え、createCodemodeRuntime() がそれを要求します。
エントリモジュールがすでに CodemodeRuntime をエクスポートしている場合、プラグインはモジュールを変更しません。コネクタクラスに特別なファイル名や import 構文は不要です。通常どおりインポートし、インスタンスをランタイムへ渡します。
プラグインなしでは、エクスポートを手動で足します。
export { CodemodeRuntime } from "@cloudflare/codemode";コネクタの import は、1 つのコネクタファイルまたはディレクトリを対象にできます。ディレクトリ import は、その配下の一致するコネクタファイルをすべて再エクスポートします。