theokit 0.22.1 → 0.23.0

package/dist/server/index.d.ts

@@ -28,13 +28,13 @@ export { G as GenericFactory, a as PoolLike, P as PostgresDatabaseConfig, c as R
 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 { AcpTransport, HumanInTheLoopOptions, HitlDecision, streamAgentUIMessages } from '@theokit/agents';
 import { CustomTool as CustomTool$1 } from '@theokit/sdk';
+import { UIMessageChunk } from 'ai';
 import { IncomingMessage } from 'node:http';
 import { W as WebOnRequestHook, b as WebPreHandlerHook, c as WebOnResponseHook, d as WebOnErrorHook } from '../plugin-types-L49QYMb5.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 } from '../plugin-types-L49QYMb5.js';
 export { a as ServiceDefinition, S as ServicesConfig, b as ServicesConfigInput, c as ServicesConfigOutput } from '../schema-BpH6ivDY.js';
-import 'ai';
 import 'vite';
 
 /**
@@ -869,6 +869,70 @@ interface ChannelWebhookConfig {
  */
 declare function handleChannelWebhook(request: Request, urlPath: string, config: ChannelWebhookConfig): Promise<Response>;
 
+/**
+ * M35 (multi-surface) — the in-process agent-turn seam (Model A).
+ *
+ * The FRAMEWORK-owned sibling of the HTTP `mountAgent` and the stdout `runAgentInTerminal`: it runs a
+ * compiled agent with the SAME `compileAgentModule` + SAME `streamAgentUIMessages` (G2 — reuses the
+ * SDK runtime, reimplements nothing), but returns the raw `UIMessageChunk` generator so ANY consumer
+ * drives it directly — the Ink TUI (M35), a Tauri window (M36), or a test — in a SINGLE process with
+ * NO HTTP loopback, NO port, and NO CSRF (there is no network boundary to defend).
+ *
+ * The ONLY difference from the HTTP mount is HITL resolution: the mount pauses the run and resolves
+ * the approval via a SECOND HTTP request to `/approve/:id` (the approval registry). In-process there
+ * is no second request — the caller resolves the approval INLINE via `awaitApproval` (e.g. the Ink
+ * TUI's y/n prompt). The gated-tool map is `compiled.hitl` verbatim, so the pause semantics are
+ * byte-identical to the HTTP path; only the resolver differs. Parity with the mount is by
+ * construction: both compile the module, resolve function-form skills, and call `streamAgentUIMessages`
+ * with the same `{ message, sessionId, hitl }`.
+ *
+ * Consumers WILL still receive `tool-approval-request` chunks from the returned generator — they are
+ * INFORMATIONAL (render them or ignore them). The authoritative human gate is `awaitApproval`, which
+ * the SDK awaits BEFORE the gated tool runs; the chunk is not the gate.
+ */
+
+/** An inline approval request handed to the caller's `awaitApproval` (the Ink/Tauri prompt). */
+interface InProcessApprovalRequest {
+    approvalId: string;
+    toolName: string;
+    opts: HumanInTheLoopOptions;
+}
+/** Resolve one gated-tool approval inline (approve/deny, or a structured {@link HitlDecision}). */
+type InProcessAwaitApproval = (req: InProcessApprovalRequest) => Promise<boolean | HitlDecision>;
+interface StreamAgentTurnInProcessInput {
+    message: string;
+    /** Resume key; a fresh id per run when omitted. */
+    sessionId?: string;
+    /**
+     * Inline HITL resolver — required IFF the agent has `@HumanInTheLoop`-gated tools. Omitting it for a
+     * gated agent is a fail-fast error, never a silent bypass (Rule 8, the #99 lesson).
+     */
+    awaitApproval?: InProcessAwaitApproval;
+    /** Labels a fail-fast `AgentDefinitionError` (the file path). */
+    source?: string;
+    /** Abort signal forwarded to the SDK stream (client disconnect / window close). */
+    signal?: AbortSignal;
+}
+/** Injectable stream fn (defaults to the real SDK bridge) — lets tests drive a deterministic stream. */
+interface StreamAgentTurnDeps {
+    stream: typeof streamAgentUIMessages;
+}
+/**
+ * Thrown when a gated agent is run in-process without an `awaitApproval` resolver. Refusing loudly is
+ * the correct posture: silently running a `@HumanInTheLoop`-gated tool with no human gate is exactly
+ * the #99 class of bug. Typed so callers can catch it distinctly.
+ */
+declare class InProcessApprovalRequiredError extends Error {
+    constructor(toolNames: readonly string[]);
+}
+/**
+ * Run a compiled agent in-process and return its `UIMessageChunk` stream. `apiKey` is resolved by the
+ * caller (same contract as the HTTP mount). Validation + compile happen SYNCHRONOUSLY (so a gated
+ * agent without a resolver throws at call time, not lazily on first iteration); the returned value is
+ * the SDK's `streamAgentUIMessages` generator.
+ */
+declare function streamAgentTurnInProcess(mod: unknown, apiKey: string, input: StreamAgentTurnInProcessInput, deps?: StreamAgentTurnDeps): AsyncGenerator<UIMessageChunk>;
+
 /**
  * M30 (ADR-0041) — MCP Apps: `ui://` HTML resources for the MCP server (M16).
  *
@@ -1317,4 +1381,4 @@ interface LoadEnvResult {
 declare function _resetEnvCache(): void;
 declare function loadEnv(options?: LoadEnvOptions): LoadEnvResult;
 
-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, CTX_WRITERS, 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, type ContextValue, CustomTool, DEFAULT_EXCLUDED_QUERY_PARAMS, type DefineCachedFunctionOptions, FileTooLargeError, type GetOrComputeOptions, InMemoryCacheAdapter, type InMemoryCacheAdapterOptions, type JobsAugmentedCtx, type KeyDerivationOptions, type LoadEnvOptions, type LoadEnvResult, type McpResourceContents, type McpResourceDescriptor, NodeAcpTransport, type NormalizedCacheConfig, type OpenApiDocsOptions, type ParsedBody, type ProcedureInput, ProcedureInputError, ProcedureOutputError, type QueueClientLike, type RawRouteInput, type RevalidateResult, type RouteCacheOptions, RouteConfig, type RouteInputChannel, type RouteInputSchemas, type RouteInputValidation, type RouteRule, type RouteRules, type Sandbox, type SerializedActionResult, type SerializedResponse, type StdioStreams, THEO_T_PREFIX, type UniversalZodIssue, type UploadedFile, type VendorAgentClient, type VendorAgentToolConfig, VerifyFn, type WorkflowLike, type WorkflowToolConfig, _resetCacheEngine, _resetEnvCache, buildResourceDescriptors, callProcedure, compileRouteRules, createACPTool, createCacheEngine, createCodeMode, createOpenApiHandler, createVendorAgentTool, createWorkflowTool, defineAppResource, defineCachedFunction, defineCachedRoute, deriveKey as deriveCacheKey, deserializeResponse, executeWebRequest, extractAppResources, extractUniversalIssues, getCacheControlHeader, getCacheEngine, handleChannelWebhook, handleMcpStdioLine, initCacheEngine, isActionError, isChannelPath, isInputError, loadEnv, parseChannelPath, parseRequestBody, readAppResource, resolveRouteRule, revalidatePath, revalidateTag, serializeResponse, serveMcpStdio, updateTag, validateExpire as validateCacheExpire, validateMaxAge as validateCacheMaxAge, validateTags as validateCacheTags, validateRouteInput };
+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, CTX_WRITERS, 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, type ContextValue, CustomTool, DEFAULT_EXCLUDED_QUERY_PARAMS, type DefineCachedFunctionOptions, FileTooLargeError, type GetOrComputeOptions, InMemoryCacheAdapter, type InMemoryCacheAdapterOptions, type InProcessApprovalRequest, InProcessApprovalRequiredError, type InProcessAwaitApproval, type JobsAugmentedCtx, type KeyDerivationOptions, type LoadEnvOptions, type LoadEnvResult, type McpResourceContents, type McpResourceDescriptor, NodeAcpTransport, type NormalizedCacheConfig, type OpenApiDocsOptions, type ParsedBody, type ProcedureInput, ProcedureInputError, ProcedureOutputError, type QueueClientLike, type RawRouteInput, type RevalidateResult, type RouteCacheOptions, RouteConfig, type RouteInputChannel, type RouteInputSchemas, type RouteInputValidation, type RouteRule, type RouteRules, type Sandbox, type SerializedActionResult, type SerializedResponse, type StdioStreams, type StreamAgentTurnDeps, type StreamAgentTurnInProcessInput, THEO_T_PREFIX, type UniversalZodIssue, type UploadedFile, type VendorAgentClient, type VendorAgentToolConfig, VerifyFn, type WorkflowLike, type WorkflowToolConfig, _resetCacheEngine, _resetEnvCache, buildResourceDescriptors, callProcedure, compileRouteRules, createACPTool, createCacheEngine, createCodeMode, createOpenApiHandler, createVendorAgentTool, createWorkflowTool, defineAppResource, defineCachedFunction, defineCachedRoute, deriveKey as deriveCacheKey, deserializeResponse, executeWebRequest, extractAppResources, extractUniversalIssues, getCacheControlHeader, getCacheEngine, handleChannelWebhook, handleMcpStdioLine, initCacheEngine, isActionError, isChannelPath, isInputError, loadEnv, parseChannelPath, parseRequestBody, readAppResource, resolveRouteRule, revalidatePath, revalidateTag, serializeResponse, serveMcpStdio, streamAgentTurnInProcess, updateTag, validateExpire as validateCacheExpire, validateMaxAge as validateCacheMaxAge, validateTags as validateCacheTags, validateRouteInput };

package/dist/server/index.js

@@ -1315,6 +1315,46 @@ async function handleChannelWebhook(request, urlPath, config) {
   });
 }
 
+// src/server/agent/stream-agent-turn-in-process.ts
+import {
+  compileAgentModule,
+  resolveEnabledSkills,
+  streamAgentUIMessages
+} from "@theokit/agents";
+var InProcessApprovalRequiredError = class extends Error {
+  constructor(toolNames) {
+    super(
+      `Agent has HITL-gated tool(s) [${toolNames.join(", ")}] but no \`awaitApproval\` resolver was supplied to streamAgentTurnInProcess. In-process runs must resolve approvals inline \u2014 pass awaitApproval, or remove the gate. Refused (fail-closed).`
+    );
+    this.name = "InProcessApprovalRequiredError";
+  }
+};
+function streamAgentTurnInProcess(mod, apiKey, input, deps = { stream: streamAgentUIMessages }) {
+  const compiled = compileAgentModule(mod, input.source);
+  const gated = compiled.hitl;
+  if (gated && gated.size > 0 && !input.awaitApproval) {
+    throw new InProcessApprovalRequiredError([...gated.keys()]);
+  }
+  const resolve2 = input.awaitApproval;
+  const hitl = gated && gated.size > 0 && resolve2 ? {
+    gated,
+    awaitApproval: (approvalId, opts, toolName) => resolve2({ approvalId, toolName, opts })
+  } : void 0;
+  const sessionId = input.sessionId ?? crypto.randomUUID();
+  return (async function* () {
+    if (compiled.skillsResolver) {
+      const enabled = await resolveEnabledSkills(compiled.skillsResolver, compiled.runContext ?? {});
+      if (enabled !== void 0) compiled.skills = { enabled, autoInject: true };
+    }
+    yield* deps.stream(compiled, apiKey, {
+      message: input.message,
+      sessionId,
+      hitl,
+      signal: input.signal
+    });
+  })();
+}
+
 // src/server/agent/mcp-stdio.ts
 async function handleMcpStdioLine(line, mod, name, appResources = []) {
   const trimmed = line.trim();
@@ -1452,6 +1492,7 @@ export {
   InMemoryJobBackend,
   InMemoryStore,
   InMemoryUsageStorage,
+  InProcessApprovalRequiredError,
   InvalidPluginShapeError,
   JOB_MANIFEST_SCHEMA_VERSION,
   JsonStdoutSink,
@@ -1626,6 +1667,7 @@ export {
   serveStaticFile,
   serverErrorToEnvelope,
   setCookie,
+  streamAgentTurnInProcess,
   superjsonTransformer,
   timingSafeEqual,
   tool,