Referenční dokumentace API Code Mode

function createCodemodeRuntime(
	options: CreateCodemodeRuntimeOptions,
): CodemodeRuntimeHandle;

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>;
}

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);
}

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>;

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;
};

type ToolDecision =
	| { kind: "replay"; result: unknown }
	| { kind: "execute"; seq: number }
	| { kind: "pause"; seq: number };

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>;
};

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";
};

interface SaveSnippetOptions {
	description?: string;
	inputSchema?: unknown;
	executionId: string;
}

interface Snippet {
	name: string;
	description: string;
	code: string;
	savedAt: number;
	inputSchema?: unknown;
	connectors?: string[];
}

interface Executor {
	execute(
		code: string,
		providersOrFns:
			| ResolvedProvider[]
			| Record<string, (...args: unknown[]) => Promise<unknown>>,
		options?: ExecuteOptions,
	): Promise<ExecuteResult>;
}

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[];
}

class DynamicWorkerExecutor implements Executor {
	constructor(options: DynamicWorkerExecutorOptions);
	execute(
		code: string,
		providersOrFns:
			| ResolvedProvider[]
			| Record<string, (...args: unknown[]) => Promise<unknown>>,
		options?: ExecuteOptions,
	): Promise<ExecuteResult>;
}

class ToolDispatcher extends RpcTarget {
	constructor(fns: Record<string, (...args: unknown[]) => Promise<unknown>>);
	call(name: string, argsJson?: string): Promise<string>;
}

function runCode(options: {
	code: string;
	executor: Executor;
	providers: ResolvedProvider[];
	connectors?: ConnectorBinding[];
}): Promise<{ result: unknown; logs?: string[] }>;

interface ToolProvider {
	name?: string;
	tools: ToolDescriptors | ToolSet | SimpleToolRecord;
	types?: string;
}

function resolveProvider(provider: ToolProvider): ResolvedProvider;

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>;
}

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 };

abstract class McpConnector<
	Env = unknown,
	Props = unknown,
> extends CodemodeConnector<Env, Props> {
	protected abstract createConnection():
		| McpConnectionLike
		| Promise<McpConnectionLike>;
	protected toolName(tool: McpTool): string;
}

interface McpConnectionLike {
	name?: string;
	client: Pick<Client, "callTool">;
	instructions?: string;
	tools?: McpTool[];
	fetchTools?: () => Promise<McpTool[]>;
}

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;
}

type OpenApiRequestOptions = {
	path: string;
	method?: string;
	params?: Record<string, unknown>;
	body?: unknown;
	headers?: Record<string, string>;
};

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;

type TruncateOptions = {
	maxChars?: number;
	maxTokens?: number;
};

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[] };

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;
}

interface CodeMcpServerOptions {
	server: McpServer;
	executor: Executor;
	description?: string;
}

function codeMcpServer(options: CodeMcpServerOptions): Promise<McpServer>;

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;

function createCodeTool(options: CreateCodeToolOptions): ServerTool;

function createBrowserCodeTool(
	options: CreateBrowserCodeToolOptions,
): BrowserCodeToolDescriptor;

interface CreateBrowserCodeToolOptions {
	tools:
		| JsonSchemaExecutableToolDescriptor[]
		| JsonSchemaExecutableToolDescriptors;
	executor?: Executor;
	description?: string;
}

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;
}

function codemodeVitePlugin(): Plugin;

export { CodemodeRuntime } from "@cloudflare/codemode";