theokit 0.15.2 → 0.17.0

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-import { RouteConfig } from './define/index.js';
-export { ActionAccept, ActionConfig, ChannelHandler, CustomTool, DefineAgentToolSpec, MiddlewareHandler, WebChannelHandler, defineAction, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel, uiMessageStreamResponse } from './define/index.js';
+import { RouteConfig, CustomTool } from './define/index.js';
+export { ActionAccept, ActionConfig, ChannelHandler, DefineAgentToolSpec, MiddlewareHandler, ToolTransform, WebChannelHandler, applyTransform, defineAction, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel, uiMessageStreamResponse } from './define/index.js';
 export { W as WebSocketHandler, a as WebSocketHandlerWeb, b as WebSocketLike, d as defineWebSocket, c as defineWebSocketWeb } from '../define-websocket-CdK94O-D.js';
 export { H as HEALTH_PATH, a as HealthRouteConfig, b as READY_PATH, c as ReadyRouteConfig, d as ReservedResponse, R as ReservedRoutes, e as defineHealthRoute, f as defineReadyRoute, s as serveReservedRoute } from '../health-route-C0hk64_U.js';
 export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, N as NotFoundError, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoError, r as TheoTransformer, _ as _resetMiddlewareCacheForTests, s as appendCookieToHeaders, t as appendDeleteCookieToHeaders, u as createCorsHandler, v as createCorsWebHandler, w as deleteCookie, x as envelopeCodeToStatus, y as executeAction, z as executeRoute, A as extractTraceId, D as extractTraceIdFromRequest, F as fromUnknown, G as getCookie, I as getCookieFromRequest, J as handleBatchRequest, K as handleRequestError, L as handleWebRequestError, O as jsonTransformer, P as loadCustomErrorPages, Q as matchesOrigin, R as parseCookieHeader, U as parseTraceparent, V as resolveTransformer, W as runMiddlewareAndContext, X as sendError, Y as sendJson, Z as serializeCookie, $ as serveStaticFile, a0 as serverErrorToEnvelope, a1 as setCookie, a2 as superjsonTransformer } from '../index-B40qUSrQ.js';
@@ -25,8 +25,11 @@ export { a as CsrfReadinessRouteSummary, C as CsrfReadinessStore, b as CsrfReadi
 export { P as PostgresFactory, R as RedisFactory, S as StorageManager, g as getStorageManager } from '../storage-manager-C4jsO0Tp.js';
 export { Db0Database, UnstorageInstance, useDatabase, useUnstorage } from './storage/index.js';
 export { G as GenericFactory, a as PoolLike, P as PostgresDatabaseConfig, c as RedisLike, R as RedisServerConfig, S as ServerConfig, d as StorageAdapter, b as StorageConfig, T as TlsConfig } from '../storage-types-DsDTCPbp.js';
-export { BodyTooLargeError, DEFAULT_MAX_BODY_BYTES, DefineWebhookOptions, RawBodyResult, ReadRawBodyOptions, VerifyFn, VerifyResult, WebhookContext, WebhookDefinition, defineWebhook, dispatchWebhook, readRawBody, timingSafeEqual } from './webhook/index.js';
+import { VerifyFn } from './webhook/index.js';
+export { BodyTooLargeError, DEFAULT_MAX_BODY_BYTES, DefineWebhookOptions, RawBodyResult, ReadRawBodyOptions, VerifyResult, WebhookContext, WebhookDefinition, defineWebhook, dispatchWebhook, readRawBody, timingSafeEqual } from './webhook/index.js';
 import { z } from 'zod';
+import { AcpTransport } from '@theokit/agents';
+import { CustomTool as CustomTool$1 } from '@theokit/sdk';
 import { IncomingMessage } from 'node:http';
 import { W as WebOnRequestHook, b as WebPreHandlerHook, c as WebOnResponseHook, d as WebOnErrorHook } from '../plugin-types-DNJGxr4Z.js';
 export { e as HookName, H as HookResult, O as OnErrorHook, f as OnRequestHook, g as OnResponseHook, P as PluginContext, h as PluginErrorContext, i as PreHandlerHook, R as RunHookOptions, a as TheoApp, T as TheoPlugin, j as definePlugin } from '../plugin-types-DNJGxr4Z.js';
@@ -647,6 +650,277 @@ declare const THEO_T_PREFIX = "_THEO_T_";
 declare const DEFAULT_MAX_AGE = 1;
 declare const DEFAULT_SWR_MULTIPLIER = 60;
 
+/**
+ * M26 (ADR-0041) — `createWorkflowTool`: wrap an SDK `Workflow` as a `CustomTool`.
+ *
+ * THIN adapter. `packages/workflows/` stays G13-forbidden — the workflow ENGINE is the SDK's
+ * (`Workflow.create(...).run(input)`). This exposes an already-built `Workflow` to an agent as one
+ * callable tool: it validates the tool input, delegates to `workflow.run(input)`, and shapes the
+ * result for the model. It calls no LLM, dispatches no tool, and runs no orchestration of its own —
+ * the SDK owns all of that (sdk-runtime.md / G2).
+ */
+
+/**
+ * Structural stand-in for the SDK `Workflow` (the adapter never imports the SDK type — keeps the
+ * SDK an optional peer). Any object with a `run(input)` resolving to `{ status, output }` matches.
+ */
+interface WorkflowLike {
+    run(input: unknown): Promise<{
+        status: string;
+        output: unknown;
+        runId?: string;
+    }>;
+}
+/** Config for {@link createWorkflowTool}. `inputSchema` defaults to an open object. */
+interface WorkflowToolConfig {
+    /** Tool name surfaced to the LLM. */
+    name: string;
+    /** Tool description surfaced to the LLM. */
+    description: string;
+    /** Zod schema for the workflow input (defaults to `z.object({}).passthrough()`). */
+    inputSchema?: z.ZodType;
+}
+/**
+ * Wrap an SDK `Workflow` as a {@link CustomTool}. Fails fast if `workflow` does not expose a
+ * `run()` method (the SDK Workflow contract), so a mis-wired call is caught at definition time, not
+ * at the first invocation (error-handling.md).
+ */
+declare function createWorkflowTool(workflow: WorkflowLike, config: WorkflowToolConfig): CustomTool;
+
+/** Stdio transport backed by a spawned subprocess (the default for {@link createACPTool}). */
+declare class NodeAcpTransport implements AcpTransport {
+    private readonly proc;
+    constructor(command: string, args?: string[], cwd?: string);
+    send(line: string): void;
+    subscribe(onData: (chunk: string) => void): void;
+    close(): void;
+}
+interface AcpToolConfig {
+    /** Executable for the coding agent (e.g. `claude`, `amp`, `codex`). */
+    command: string;
+    /** Command-line arguments. */
+    args?: string[];
+    /** Working directory for the spawned agent. */
+    cwd?: string;
+    /** Tool name the model calls. */
+    name: string;
+    /** Tool description surfaced to the model. */
+    description: string;
+    /**
+     * REQUIRED — decide file/shell permission requests from the coding agent. Security by default:
+     * there is NO default-allow. Return `{ granted: boolean }` (may be async).
+     */
+    onPermissionRequest: (params: unknown) => {
+        granted: boolean;
+    } | Promise<{
+        granted: boolean;
+    }>;
+    /** Injected transport factory (defaults to spawning via {@link NodeAcpTransport}) — for tests. */
+    transportFactory?: (config: AcpToolConfig) => AcpTransport;
+}
+/** Wrap a coding agent as a `CustomTool`. Fails fast if `onPermissionRequest` is missing. */
+declare function createACPTool(config: AcpToolConfig): CustomTool$1;
+
+/**
+ * M28 (ADR-0041) — `createVendorAgentTool`: expose a third-party agent SDK (Claude Agent SDK,
+ * OpenAI, Cursor) behind a uniform `CustomTool`, mirroring the M17 ACP pattern.
+ *
+ * The vendor RUNTIME stays theirs — TheoKit only wires. The vendor client is INJECTED (the real
+ * vendor SDK client in prod, a fake in tests), so no vendor dependency enters core; vendor-specific
+ * client packages belong under `@theokit/agent-*`, never here. This calls no LLM of its own and runs
+ * no loop — it delegates each prompt to `client.query(...)` (sdk-runtime.md / G2). Resume is threaded
+ * via the vendor's own session id.
+ */
+
+/**
+ * Structural contract a vendor agent client must satisfy (the adapter never imports a vendor type).
+ * `query` runs one turn; `resumeSessionId` continues a prior vendor session; the returned
+ * `sessionId` identifies the session to resume next.
+ */
+interface VendorAgentClient {
+    query(prompt: string, opts?: {
+        resumeSessionId?: string;
+    }): Promise<{
+        text: string;
+        sessionId?: string;
+    }>;
+}
+/** Config for {@link createVendorAgentTool}. */
+interface VendorAgentToolConfig {
+    /** Vendor label (e.g. `claude`, `openai`, `cursor`). Drives the default tool name. */
+    vendor: string;
+    /** The injected vendor client (real SDK client in prod, a fake in tests). */
+    client: VendorAgentClient;
+    /** Tool name the model calls (defaults to `<vendor>_agent`). */
+    name?: string;
+    /** Tool description surfaced to the model (defaults to a one-line delegate hint). */
+    description?: string;
+    /**
+     * Side-channel callback invoked with the vendor session id after each turn — lets the app capture
+     * it for a later resume WITHOUT leaking session bookkeeping into the model's view of the result.
+     */
+    onSession?: (sessionId: string) => void;
+}
+/**
+ * Wrap a vendor agent SDK as a {@link CustomTool}. Fails fast if `vendor` is empty or the client
+ * does not expose `query()` (error-handling.md) — a mis-wired call is caught at definition time.
+ */
+declare function createVendorAgentTool(config: VendorAgentToolConfig): CustomTool;
+
+/**
+ * M29 (ADR-0041) — `createCodeMode`: expose a set of tools to agent-authored code run inside an
+ * ISOLATION boundary, so the agent composes tools programmatically instead of one call at a time.
+ *
+ * Security posture (the whole point of this feature):
+ *  - The isolation boundary (`sandbox`) is **injected**, never hand-rolled here (Top-risk 1). The app
+ *    supplies a vetted sandbox — isolated-vm, QuickJS-WASM, or a locked-down worker. TheoKit core
+ *    ships no VM and adds no sandbox dependency (same posture as the injected deploy adapter / the
+ *    M17 transport). `node:vm` is NOT a security boundary and MUST NOT be used as the sandbox.
+ *  - TheoKit owns the **restricted API** (only the declared tools are reachable from the code — no
+ *    `fs`, `process`, `require`, or network unless a declared, permission-gated tool provides it) and
+ *    the **mandatory permission gate**: every tool call from the code passes `onPermissionRequest`
+ *    first, and there is NO default-allow (mirrors M17 `onPermissionRequest`).
+ *
+ * Threat model (summary): a malicious model could author code that (a) calls a dangerous tool, or
+ * (b) tries to reach a host capability. (a) is stopped by the permission gate (deny → the API call
+ * throws). (b) is stopped by the injected sandbox (the restricted API is the ONLY surface the code
+ * sees). If the app injects a weak sandbox, (b) is on the app — hence the vetted-sandbox requirement.
+ */
+
+/** The restricted API handed to sandboxed code: declared tool names → permission-gated callables. */
+type CodeModeApi = Record<string, (args: unknown) => Promise<unknown>>;
+/** The injected isolation boundary. The app supplies a vetted implementation. */
+interface Sandbox {
+    /** Run `code` with access to ONLY `api` (the restricted tool surface). Resolve the code's result. */
+    run(code: string, api: CodeModeApi): Promise<unknown>;
+}
+/** A permission decision for one tool call from sandboxed code. */
+interface CodeModePermission {
+    granted: boolean;
+    /** Optional reason surfaced to the model on denial. */
+    reason?: string;
+}
+interface CodeModeConfig {
+    /** The tools reachable from the code (the restricted API). */
+    tools: CustomTool[];
+    /** The injected isolation boundary (vetted sandbox — NEVER node:vm). */
+    sandbox: Sandbox;
+    /**
+     * REQUIRED — decide each tool call the code attempts. Security by default: NO default-allow.
+     * Return `{ granted }` (may be async). Mirrors M17 `onPermissionRequest`.
+     */
+    onPermissionRequest: (req: {
+        tool: string;
+        args: unknown;
+    }) => CodeModePermission | Promise<CodeModePermission>;
+    /** Tool name the model calls (default `run_code`). */
+    name?: string;
+    /** Tool description surfaced to the model. */
+    description?: string;
+}
+/** Thrown when the permission gate denies a tool call from sandboxed code. */
+declare class CodeModePermissionDeniedError extends Error {
+    constructor(tool: string, reason?: string);
+}
+/**
+ * Build a code-mode `CustomTool`. Fails fast if `onPermissionRequest` or `sandbox` is missing
+ * (security by default). The returned tool takes `{ code }`, assembles the permission-gated restricted
+ * API from `tools`, runs the code in the injected sandbox, and returns the code's result.
+ */
+declare function createCodeMode(config: CodeModeConfig): CustomTool;
+
+/**
+ * M27 (ADR-0041) — channel webhook routes: `POST /api/agents/<name>/channels/<platform>/webhook`.
+ *
+ * Auto-generates a per-platform inbound webhook endpoint that VALIDATES the platform signature
+ * (reusing the existing webhook `VerifyFn` providers — Slack/Telegram/Discord — never a hand-rolled
+ * scheme) and hands the parsed payload to an injected `onMessage` seam. The seam is where an app
+ * wires the SDK gateway package (`@theokit/gateway-*`) that translates the payload into an agent
+ * turn — TheoKit provides the route + signature gate, NOT the gateway's parsing (G2 / it does not
+ * reimplement the gateway).
+ */
+
+/** Parsed `{ agent, platform }` from a channel webhook path, or `null` when it doesn't match. */
+declare function parseChannelPath(urlPath: string): {
+    agent: string;
+    platform: string;
+} | null;
+/** True when `urlPath` targets a channel webhook (dev/prod routing branches on this). */
+declare function isChannelPath(urlPath: string): boolean;
+/** The inbound message handed to the app after signature validation passes. */
+interface ChannelMessage {
+    agent: string;
+    platform: string;
+    /** The parsed JSON payload from the platform (the gateway translates this to an agent turn). */
+    payload: unknown;
+}
+interface ChannelWebhookConfig {
+    /** Per-platform signature validators (e.g. `{ slack: slack({...}), telegram: telegram({...}) }`). */
+    validators: Record<string, VerifyFn>;
+    /** Handoff seam — wire the SDK gateway / agent here. Invoked only after signature validation. */
+    onMessage: (message: ChannelMessage) => void | Promise<void>;
+}
+/**
+ * Handle one channel webhook request. Returns:
+ *   404 UNKNOWN_PLATFORM — no validator configured for `<platform>`
+ *   400 BAD_REQUEST      — path is not a channel webhook, or the body is not JSON
+ *   401 INVALID_SIGNATURE — the platform signature check failed (negative case)
+ *   200 { ok: true }     — validated + handed to `onMessage`
+ */
+declare function handleChannelWebhook(request: Request, urlPath: string, config: ChannelWebhookConfig): Promise<Response>;
+
+/**
+ * M30 (ADR-0041) — MCP Apps: `ui://` HTML resources for the MCP server (M16).
+ *
+ * A tool can declare a `ui://` HTML resource; the MCP server advertises it via `resources/list` and
+ * serves the HTML via `resources/read`. The client renders it in a SANDBOXED iframe (see
+ * `mcp-app-host.ts`). Pure data transforms here — no LLM, no runtime (ADR-0040 § D2 home concern).
+ *
+ * Security: only the `ui://` scheme is accepted (an app UI resource), never `http(s)://` — the HTML
+ * is rendered sandboxed on the client, and the scheme gate keeps a tool from smuggling a remote URL
+ * into the app surface.
+ */
+/** A declared `ui://` app resource. */
+interface AppResource {
+    uri: string;
+    name: string;
+    mimeType: 'text/html';
+    html: string;
+    description?: string;
+}
+/** Input to {@link defineAppResource}. */
+interface AppResourceInput {
+    /** MUST start with `ui://`. */
+    uri: string;
+    name: string;
+    html: string;
+    description?: string;
+}
+/** An MCP `resources/list` descriptor (no HTML body — that comes from `resources/read`). */
+interface McpResourceDescriptor {
+    uri: string;
+    name: string;
+    mimeType: 'text/html';
+    description?: string;
+}
+/** An MCP `resources/read` result. */
+interface McpResourceContents {
+    contents: {
+        uri: string;
+        mimeType: 'text/html';
+        text: string;
+    }[];
+}
+/**
+ * Declare a `ui://` HTML app resource. Fails fast if the uri is not a `ui://` scheme or the HTML is
+ * empty (error-handling.md) — a misconfigured resource is caught at definition time.
+ */
+declare function defineAppResource(input: AppResourceInput): AppResource;
+/** Map app resources to MCP `resources/list` descriptors (the HTML body is omitted from the list). */
+declare function buildResourceDescriptors(resources: readonly AppResource[]): McpResourceDescriptor[];
+/** Serve the HTML for `uri` as an MCP `resources/read` result, or `null` when unknown. */
+declare function readAppResource(resources: readonly AppResource[], uri: string): McpResourceContents | null;
+
 interface UploadedFile {
     fieldname: string;
     filename: string;
@@ -843,4 +1117,4 @@ interface LoadEnvResult {
 declare function _resetEnvCache(): void;
 declare function loadEnv(options?: LoadEnvOptions): LoadEnvResult;
 
-export { ActionError, type ActionErrorCode, ActionInputError, type ActionManifestEntry, type ActionResult, type BodyParserOptions, DEFAULT_MAX_AGE as CACHE_DEFAULT_MAX_AGE, DEFAULT_MAX_ENTRY_SIZE as CACHE_DEFAULT_MAX_ENTRY_SIZE, DEFAULT_SWR_MULTIPLIER as CACHE_DEFAULT_SWR_MULTIPLIER, CACHE_TAG_MAX_ITEMS, CACHE_TAG_MAX_LENGTH, type CacheControlInput, type CacheEngine, type CacheEngineOptions, type CacheEntry, type CacheStatus, type CacheStorageAdapter, type CacheStore, type CacheStoreAdmin, type ValidationResult as CacheValidationResult, type CachedFunction, type CachedRouteConfig, type CompiledRouteRule, DEFAULT_EXCLUDED_QUERY_PARAMS, type DefineCachedFunctionOptions, FileTooLargeError, type GetOrComputeOptions, InMemoryCacheAdapter, type InMemoryCacheAdapterOptions, type KeyDerivationOptions, type LoadEnvOptions, type LoadEnvResult, type NormalizedCacheConfig, type OpenApiDocsOptions, type ParsedBody, type RevalidateResult, type RouteCacheOptions, RouteConfig, type RouteRule, type RouteRules, type SerializedActionResult, type SerializedResponse, THEO_T_PREFIX, type UniversalZodIssue, type UploadedFile, _resetCacheEngine, _resetEnvCache, compileRouteRules, createCacheEngine, createOpenApiHandler, defineCachedFunction, defineCachedRoute, deriveKey as deriveCacheKey, deserializeResponse, executeWebRequest, extractUniversalIssues, getCacheControlHeader, getCacheEngine, initCacheEngine, isActionError, isInputError, loadEnv, parseRequestBody, resolveRouteRule, revalidatePath, revalidateTag, serializeResponse, updateTag, validateExpire as validateCacheExpire, validateMaxAge as validateCacheMaxAge, validateTags as validateCacheTags };
+export { type AcpToolConfig, ActionError, type ActionErrorCode, ActionInputError, type ActionManifestEntry, type ActionResult, type AppResource, type AppResourceInput, type BodyParserOptions, DEFAULT_MAX_AGE as CACHE_DEFAULT_MAX_AGE, DEFAULT_MAX_ENTRY_SIZE as CACHE_DEFAULT_MAX_ENTRY_SIZE, DEFAULT_SWR_MULTIPLIER as CACHE_DEFAULT_SWR_MULTIPLIER, CACHE_TAG_MAX_ITEMS, CACHE_TAG_MAX_LENGTH, type CacheControlInput, type CacheEngine, type CacheEngineOptions, type CacheEntry, type CacheStatus, type CacheStorageAdapter, type CacheStore, type CacheStoreAdmin, type ValidationResult as CacheValidationResult, type CachedFunction, type CachedRouteConfig, type ChannelMessage, type ChannelWebhookConfig, type CodeModeApi, type CodeModeConfig, type CodeModePermission, CodeModePermissionDeniedError, type CompiledRouteRule, CustomTool, DEFAULT_EXCLUDED_QUERY_PARAMS, type DefineCachedFunctionOptions, FileTooLargeError, type GetOrComputeOptions, InMemoryCacheAdapter, type InMemoryCacheAdapterOptions, type KeyDerivationOptions, type LoadEnvOptions, type LoadEnvResult, type McpResourceContents, type McpResourceDescriptor, NodeAcpTransport, type NormalizedCacheConfig, type OpenApiDocsOptions, type ParsedBody, type RevalidateResult, type RouteCacheOptions, RouteConfig, type RouteRule, type RouteRules, type Sandbox, type SerializedActionResult, type SerializedResponse, THEO_T_PREFIX, type UniversalZodIssue, type UploadedFile, type VendorAgentClient, type VendorAgentToolConfig, VerifyFn, type WorkflowLike, type WorkflowToolConfig, _resetCacheEngine, _resetEnvCache, buildResourceDescriptors, compileRouteRules, createACPTool, createCacheEngine, createCodeMode, createOpenApiHandler, createVendorAgentTool, createWorkflowTool, defineAppResource, defineCachedFunction, defineCachedRoute, deriveKey as deriveCacheKey, deserializeResponse, executeWebRequest, extractUniversalIssues, getCacheControlHeader, getCacheEngine, handleChannelWebhook, initCacheEngine, isActionError, isChannelPath, isInputError, loadEnv, parseChannelPath, parseRequestBody, readAppResource, resolveRouteRule, revalidatePath, revalidateTag, serializeResponse, updateTag, validateExpire as validateCacheExpire, validateMaxAge as validateCacheMaxAge, validateTags as validateCacheTags };

package/dist/server/index.js

@@ -50,12 +50,15 @@ import {
 } from "../chunk-ESC54TAK.js";
 import {
   _resetEnvCache,
+  buildResourceDescriptors,
+  defineAppResource,
   executeWebRequest,
   jsonTransformer,
   loadEnv,
+  readAppResource,
   resolveTransformer,
   superjsonTransformer
-} from "../chunk-5UUOGAJH.js";
+} from "../chunk-3FNZG6Q3.js";
 import {
   findSuggestion,
   levenshtein
@@ -160,6 +163,7 @@ import "../chunk-6NEXVBPY.js";
 import "../chunk-7MQOHNHE.js";
 import "../chunk-X2VVCJ4V.js";
 import {
+  applyTransform,
   defineAction,
   defineAgentTool,
   defineChannel,
@@ -169,7 +173,7 @@ import {
   defineWebChannel,
   defineWebSocket,
   defineWebSocketWeb
-} from "../chunk-KGFNWIMS.js";
+} from "../chunk-CWVBDUDC.js";
 import {
   uiMessageStreamResponse
 } from "../chunk-JZHT3LW7.js";
@@ -1095,6 +1099,219 @@ function resolveRouteRule(path, compiled) {
   return void 0;
 }
 
+// src/server/agent/workflow-tool.ts
+import { z } from "zod";
+var FAILURE_STATUSES = /* @__PURE__ */ new Set(["failed", "error", "cancelled", "canceled"]);
+function createWorkflowTool(workflow, config) {
+  const runFn = workflow?.run;
+  if (typeof runFn !== "function") {
+    throw new Error(
+      "createWorkflowTool: the SDK does not expose a Workflow (expected an object with a run() method). Pass a `Workflow.create(...).\u2026build()` instance from @theokit/sdk."
+    );
+  }
+  const inputSchema = config.inputSchema ?? z.looseObject({});
+  return defineAgentTool({
+    name: config.name,
+    description: config.description,
+    inputSchema,
+    handler: async (input) => {
+      const run = await workflow.run(input);
+      if (FAILURE_STATUSES.has(run.status)) {
+        throw new Error(
+          `createWorkflowTool(${JSON.stringify(config.name)}): workflow run ${run.runId ? `'${run.runId}' ` : ""}failed with status '${run.status}'.`
+        );
+      }
+      return typeof run.output === "string" ? run.output : JSON.stringify(run.output);
+    }
+  });
+}
+
+// src/server/agent/acp-tool.ts
+import { spawn } from "child_process";
+import { AcpClient } from "@theokit/agents";
+import { encodeAcpMessage } from "@theokit/agents";
+var NodeAcpTransport = class {
+  // stdin=pipe, stdout=pipe, stderr=inherit → the third stream is null.
+  proc;
+  constructor(command, args = [], cwd) {
+    this.proc = spawn(command, args, { cwd, stdio: ["pipe", "pipe", "inherit"] });
+  }
+  send(line) {
+    this.proc.stdin.write(line);
+  }
+  subscribe(onData) {
+    this.proc.stdout.on("data", (buf) => {
+      onData(buf.toString("utf8"));
+    });
+  }
+  close() {
+    this.proc.kill();
+  }
+};
+function defaultTransport(config) {
+  return new NodeAcpTransport(config.command, config.args, config.cwd);
+}
+function createACPTool(config) {
+  if (typeof config.onPermissionRequest !== "function") {
+    throw new Error("[theokit] createACPTool requires onPermissionRequest (security by default \u2014 no default-allow)");
+  }
+  const makeTransport = config.transportFactory ?? defaultTransport;
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: {
+      type: "object",
+      properties: { message: { type: "string", description: "The task/prompt for the coding agent." } },
+      required: ["message"]
+    },
+    handler: async (input) => {
+      const message = typeof input.message === "string" ? input.message : "";
+      const client = new AcpClient(makeTransport(config));
+      client.onRequest("session/request_permission", (params) => config.onPermissionRequest(params));
+      const result = await client.request("session/prompt", { message });
+      return result.text ?? "";
+    }
+  };
+}
+
+// src/server/agent/vendor-agent-tool.ts
+function createVendorAgentTool(config) {
+  if (!config.vendor || config.vendor.length === 0) {
+    throw new Error('createVendorAgentTool: `vendor` is required (e.g. "claude", "openai").');
+  }
+  const queryFn = config.client?.query;
+  if (typeof queryFn !== "function") {
+    throw new Error(
+      `createVendorAgentTool(${JSON.stringify(config.vendor)}): the vendor client does not expose a query() method. Pass the vendor SDK client (or a @theokit/agent-* wrapper).`
+    );
+  }
+  const name = config.name ?? `${config.vendor}_agent`;
+  const description = config.description ?? `Delegate a task to the ${config.vendor} agent and return its answer.`;
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "The task/prompt for the vendor agent." },
+        resumeSessionId: {
+          type: "string",
+          description: "Optional vendor session id to resume a prior conversation."
+        }
+      },
+      required: ["prompt"]
+    },
+    handler: async (input) => {
+      const prompt = typeof input.prompt === "string" ? input.prompt : "";
+      const resumeSessionId = typeof input.resumeSessionId === "string" ? input.resumeSessionId : void 0;
+      const result = await config.client.query(
+        prompt,
+        resumeSessionId !== void 0 ? { resumeSessionId } : void 0
+      );
+      if (result.sessionId !== void 0 && config.onSession) config.onSession(result.sessionId);
+      return result.text;
+    }
+  };
+}
+
+// src/server/agent/code-mode.ts
+var CodeModePermissionDeniedError = class extends Error {
+  constructor(tool, reason) {
+    const suffix = reason ? `: ${reason}` : "";
+    super(`code-mode: tool '${tool}' denied by permission gate${suffix}`);
+    this.name = "CodeModePermissionDeniedError";
+  }
+};
+function createCodeMode(config) {
+  if (typeof config.onPermissionRequest !== "function") {
+    throw new Error(
+      "createCodeMode requires onPermissionRequest (security by default \u2014 no default-allow for any tool)."
+    );
+  }
+  const sandboxRun = config.sandbox?.run;
+  if (typeof sandboxRun !== "function") {
+    throw new Error(
+      "createCodeMode requires an injected `sandbox` with a run() method (a vetted isolation boundary \u2014 never node:vm)."
+    );
+  }
+  const api = {};
+  for (const tool of config.tools) {
+    api[tool.name] = async (args) => {
+      const decision = await config.onPermissionRequest({ tool: tool.name, args });
+      if (!decision.granted) throw new CodeModePermissionDeniedError(tool.name, decision.reason);
+      return tool.handler(args);
+    };
+  }
+  return {
+    name: config.name ?? "run_code",
+    description: config.description ?? "Run code that composes the available tools. Only the declared tools are callable.",
+    inputSchema: {
+      type: "object",
+      properties: { code: { type: "string", description: "The code to run in the sandbox." } },
+      required: ["code"]
+    },
+    handler: async (input) => {
+      const code = typeof input.code === "string" ? input.code : "";
+      const result = await config.sandbox.run(code, api);
+      return typeof result === "string" ? result : JSON.stringify(result);
+    }
+  };
+}
+
+// src/server/agent/channel-webhook.ts
+var CHANNEL_PATH = /^\/api\/agents\/([^/]+)\/channels\/([^/]+)\/webhook$/;
+function parseChannelPath(urlPath) {
+  const match = CHANNEL_PATH.exec(urlPath);
+  if (!match) return null;
+  return { agent: decodeURIComponent(match[1]), platform: decodeURIComponent(match[2]) };
+}
+function isChannelPath(urlPath) {
+  return CHANNEL_PATH.test(urlPath);
+}
+function jsonError(status, code, message) {
+  return new Response(JSON.stringify({ error: { code, message } }), {
+    status,
+    headers: { "content-type": "application/json" }
+  });
+}
+async function handleChannelWebhook(request, urlPath, config) {
+  const parsed = parseChannelPath(urlPath);
+  if (parsed === null) {
+    return jsonError(
+      400,
+      "BAD_REQUEST",
+      "Path must be /api/agents/<name>/channels/<platform>/webhook."
+    );
+  }
+  if (!Object.hasOwn(config.validators, parsed.platform)) {
+    return jsonError(
+      404,
+      "UNKNOWN_PLATFORM",
+      `No validator configured for platform '${parsed.platform}'.`
+    );
+  }
+  const verify = config.validators[parsed.platform];
+  const verifyResult = await verify(request.clone());
+  if (!verifyResult.ok) {
+    return jsonError(
+      401,
+      "INVALID_SIGNATURE",
+      `Signature validation failed: ${verifyResult.reason}`
+    );
+  }
+  let payload;
+  try {
+    payload = await request.json();
+  } catch {
+    return jsonError(400, "BAD_REQUEST", "Request body must be JSON.");
+  }
+  await config.onMessage({ agent: parsed.agent, platform: parsed.platform, payload });
+  return new Response(JSON.stringify({ ok: true }), {
+    status: 200,
+    headers: { "content-type": "application/json" }
+  });
+}
+
 // src/server/serialization.ts
 import superjson from "superjson";
 function serializeResponse(data) {
@@ -1140,6 +1357,7 @@ export {
   CSRF_WARN_CODE,
   CSRF_WARN_DOCS_URL,
   ChannelManager,
+  CodeModePermissionDeniedError,
   ConsoleObservabilityAdapter,
   CsrfReadinessStore,
   DEFAULT_CSP,
@@ -1162,6 +1380,7 @@ export {
   JOB_MANIFEST_SCHEMA_VERSION,
   JsonStdoutSink,
   MAX_ERROR_HTML_BYTES,
+  NodeAcpTransport,
   NonRetryableError,
   NoopObservabilityAdapter,
   NoopSpan,
@@ -1185,16 +1404,20 @@ export {
   appendCookieToHeaders,
   appendDeleteCookieToHeaders,
   applySecurityHeaders,
+  applyTransform,
   assertProductionSecret,
   buildCronManifest,
   buildJobManifest,
+  buildResourceDescriptors,
   buildSecurityHeaders,
   checkThrottle,
   clearOidcCache,
   compilePattern,
   compileRouteRules,
   convertToAwsCron,
+  createACPTool,
   createCacheEngine,
+  createCodeMode,
   createCorsHandler,
   createCorsWebHandler,
   createCronScheduler,
@@ -1214,10 +1437,13 @@ export {
   createRouteRateLimiterWeb,
   createSessionManager,
   createSessionManagerWeb,
+  createVendorAgentTool,
   createViteLoader,
+  createWorkflowTool,
   decrypt,
   defineAction,
   defineAgentTool,
+  defineAppResource,
   defineCachedFunction,
   defineCachedRoute,
   defineChannel,
@@ -1265,6 +1491,7 @@ export {
   getCookieFromRequest,
   getStorageManager,
   handleBatchRequest,
+  handleChannelWebhook,
   handleCspReport,
   handleCspReportRequest,
   handleCsrfReadiness,
@@ -1273,6 +1500,7 @@ export {
   handleWebRequestError,
   initCacheEngine,
   isActionError,
+  isChannelPath,
   isInputError,
   jsonTransformer,
   levenshtein,
@@ -1286,10 +1514,12 @@ export {
   matchesOrigin,
   normalizeLegacy,
   normalizeNew,
+  parseChannelPath,
   parseCookieHeader,
   parseRequestBody,
   parseTraceparent,
   pkceChallengeFromVerifier,
+  readAppResource,
   readRawBody,
   recordAttempt,
   requireAuth,