@theokit/agents 4.23.0 → 4.24.0

package/dist/client-react.d.ts

@@ -0,0 +1,57 @@
+import { UIMessage } from 'ai';
+import { R as RequestContext, U as UseAgentStatus, A as ApprovalDecision, a as AgentHandle, b as AgentTransport } from './agent-handle-DNbFlkrw.js';
+
+interface UseAgentReturn<TInput = unknown, TToolNames extends string = string> {
+    /** The CURRENT turn's assistant messages (per-turn; reset each `send`). Back-compat since M41. */
+    messages: UIMessage[];
+    /**
+     * M46 — the full conversation to render: committed turns + the current turn's user + in-flight
+     * assistant, accumulated across sends with stable ids. Prefer this over hand-rolling a transcript
+     * from `messages`. Same shape on every surface (web/desktop/TUI) — it lives in the core store.
+     */
+    thread: UIMessage[];
+    status: UseAgentStatus;
+    /** The last error, or `undefined`. */
+    error: Error | undefined;
+    /** Send a request; opens a new stream. Typed to the agent's `input` schema. */
+    send: (input: TInput) => void;
+    /** Abort an in-flight stream. */
+    abort: () => void;
+    /** Clear messages + error, back to idle. */
+    reset: () => void;
+    /** Settle a paused HITL approval (HTTP `POST /approve/<id>` for web; the inline callback in-process). */
+    approve: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
+    /** Resume an interrupted stream (M37 durable transport for web; a no-op in-process). */
+    reconnect: () => void;
+    /**
+     * The union of tool names this agent can emit (M8), carried end-to-end from the `agent()` builder's
+     * accumulated tool-name type through the generated `@theo/agents` client. Type-only witness (never
+     * populated at runtime). Resolves to the literal union for builder agents, `string` otherwise.
+     */
+    readonly __toolNames?: TToolNames;
+}
+interface UseAgentOptions {
+    /**
+     * Extra request headers (e.g., auth) — applied when a string path builds an `HttpTransport`. Read on
+     * EVERY request, so a value that changes across renders (a rotating JWT) is never sent stale.
+     */
+    headers?: Record<string, string>;
+    /** Override fetch (primarily for tests) — captured when a string path builds an `HttpTransport`. */
+    fetch?: typeof fetch;
+    /**
+     * M43 — per-request context attached uniformly to EVERY transport (`headers` → HTTP request headers;
+     * `metadata` → the in-process runner / Tauri invoke). A value OR a resolver evaluated on every
+     * send/reconnect, so a rotating token/tenant is never stale.
+     */
+    context?: RequestContext | (() => RequestContext | undefined);
+}
+/**
+ * Bind to an agent by endpoint path (`/api/agents/<name>`), by a typed {@link AgentHandle} (M47 — the
+ * generated `chat` handle; kills the magic string + duplicated input type), or by an explicit
+ * {@link AgentTransport}. Prefer the generated `useAgent` from `@theo/agents` (typed by agent name or
+ * handle); this base accepts all three. The store is created once per binding identity — memoize a
+ * transport before passing it.
+ */
+declare function useAgent<TInput = unknown>(binding: string | AgentHandle<TInput> | AgentTransport, options?: UseAgentOptions): UseAgentReturn<TInput>;
+
+export { type UseAgentOptions, type UseAgentReturn, UseAgentStatus, useAgent };

package/dist/client-react.js

@@ -0,0 +1,55 @@
+import {
+  AgentClient,
+  HttpTransport,
+  isAgentHandle
+} from "./chunk-M2JFE6IM.js";
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/client/use-agent.ts
+import { useMemo, useRef, useSyncExternalStore } from "react";
+function useAgent(binding, options = {}) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  let api;
+  if (typeof binding === "string") api = binding;
+  else if (isAgentHandle(binding)) api = binding.path;
+  const bindingIdentity = api ?? binding;
+  const client = useMemo(
+    () => new AgentClient(
+      api !== void 0 ? new HttpTransport({
+        api,
+        headers: /* @__PURE__ */ __name(() => optionsRef.current.headers, "headers"),
+        fetch: optionsRef.current.fetch
+      }) : binding,
+      // M43 — resolve context live from the ref each send/reconnect (never stale). A value or a resolver.
+      () => {
+        const ctx = optionsRef.current.context;
+        return typeof ctx === "function" ? ctx() : ctx;
+      }
+    ),
+    // bindingIdentity captures api/binding; options resolve live via optionsRef (rebuild would drop messages).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      bindingIdentity
+    ]
+  );
+  const state = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
+  return {
+    messages: state.messages,
+    thread: state.thread,
+    status: state.status,
+    error: state.error,
+    send: client.send,
+    abort: client.abort,
+    reset: client.reset,
+    approve: client.approve,
+    reconnect: client.reconnect
+  };
+}
+__name(useAgent, "useAgent");
+export {
+  useAgent
+};
+//# sourceMappingURL=client-react.js.map

package/dist/client-react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client/use-agent.ts"],"sourcesContent":["import type { UIMessage } from 'ai'\nimport { useMemo, useRef, useSyncExternalStore } from 'react'\n\nimport { AgentClient, type UseAgentStatus } from './agent-client.js'\nimport { type AgentHandle, isAgentHandle } from './agent-handle.js'\nimport { HttpTransport } from './http-transport.js'\nimport type { AgentTransport, ApprovalDecision, RequestContext } from './transport.js'\n\n/**\n * M2 (theokit-ai-first) / M41 (ADR-0050) — `useAgent`, the ONE typed client hook for the\n * `agents/*.ts` convention, unified across surfaces.\n *\n * Pass an endpoint path (web) OR an {@link AgentTransport} (terminal/desktop). A string is wrapped in\n * an {@link HttpTransport} (exact back-compat with the pre-M41 fetch+SSE hook); an `InProcessTransport`\n * drives the SAME hook in a single process. The hook is a thin binding over the framework-agnostic\n * {@link AgentClient} store via React's native `useSyncExternalStore` (no test-DOM dependency). The\n * generated `@theo/agents` module types `send` to the agent's `input` schema — inferred end-to-end\n * from the server `defineAgent({ input })` with ZERO manual wiring.\n */\nexport type { UseAgentStatus }\n\nexport interface UseAgentReturn<TInput = unknown, TToolNames extends string = string> {\n  /** The CURRENT turn's assistant messages (per-turn; reset each `send`). Back-compat since M41. */\n  messages: UIMessage[]\n  /**\n   * M46 — the full conversation to render: committed turns + the current turn's user + in-flight\n   * assistant, accumulated across sends with stable ids. Prefer this over hand-rolling a transcript\n   * from `messages`. Same shape on every surface (web/desktop/TUI) — it lives in the core store.\n   */\n  thread: UIMessage[]\n  status: UseAgentStatus\n  /** The last error, or `undefined`. */\n  error: Error | undefined\n  /** Send a request; opens a new stream. Typed to the agent's `input` schema. */\n  send: (input: TInput) => void\n  /** Abort an in-flight stream. */\n  abort: () => void\n  /** Clear messages + error, back to idle. */\n  reset: () => void\n  /** Settle a paused HITL approval (HTTP `POST /approve/<id>` for web; the inline callback in-process). */\n  approve: (approvalId: string, decision: ApprovalDecision) => Promise<void>\n  /** Resume an interrupted stream (M37 durable transport for web; a no-op in-process). */\n  reconnect: () => void\n  /**\n   * The union of tool names this agent can emit (M8), carried end-to-end from the `agent()` builder's\n   * accumulated tool-name type through the generated `@theo/agents` client. Type-only witness (never\n   * populated at runtime). Resolves to the literal union for builder agents, `string` otherwise.\n   */\n  readonly __toolNames?: TToolNames\n}\n\nexport interface UseAgentOptions {\n  /**\n   * Extra request headers (e.g., auth) — applied when a string path builds an `HttpTransport`. Read on\n   * EVERY request, so a value that changes across renders (a rotating JWT) is never sent stale.\n   */\n  headers?: Record<string, string>\n  /** Override fetch (primarily for tests) — captured when a string path builds an `HttpTransport`. */\n  fetch?: typeof fetch\n  /**\n   * M43 — per-request context attached uniformly to EVERY transport (`headers` → HTTP request headers;\n   * `metadata` → the in-process runner / Tauri invoke). A value OR a resolver evaluated on every\n   * send/reconnect, so a rotating token/tenant is never stale.\n   */\n  context?: RequestContext | (() => RequestContext | undefined)\n}\n\n/**\n * Bind to an agent by endpoint path (`/api/agents/<name>`), by a typed {@link AgentHandle} (M47 — the\n * generated `chat` handle; kills the magic string + duplicated input type), or by an explicit\n * {@link AgentTransport}. Prefer the generated `useAgent` from `@theo/agents` (typed by agent name or\n * handle); this base accepts all three. The store is created once per binding identity — memoize a\n * transport before passing it.\n */\nexport function useAgent<TInput = unknown>(\n  binding: string | AgentHandle<TInput> | AgentTransport,\n  options: UseAgentOptions = {},\n): UseAgentReturn<TInput> {\n  // Track the latest options so the built HttpTransport reads current headers per request (dynamic\n  // auth is never stale) without rebuilding the store — which would drop in-flight messages.\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n\n  // A handle resolves to its HTTP path; a string is already a path — both build an HttpTransport. A\n  // transport is used as-is. `api` is undefined only for a transport binding.\n  let api: string | undefined\n  if (typeof binding === 'string') api = binding\n  else if (isAgentHandle(binding)) api = binding.path\n  // Identity is the binding (a handle's path OR a transport instance) — a stable key for the memo.\n  const bindingIdentity = api ?? binding\n\n  const client = useMemo(\n    () =>\n      new AgentClient<TInput>(\n        api !== undefined\n          ? new HttpTransport({\n              api,\n              headers: () => optionsRef.current.headers,\n              fetch: optionsRef.current.fetch,\n            })\n          : (binding as AgentTransport),\n        // M43 — resolve context live from the ref each send/reconnect (never stale). A value or a resolver.\n        () => {\n          const ctx = optionsRef.current.context\n          return typeof ctx === 'function' ? ctx() : ctx\n        },\n      ),\n    // bindingIdentity captures api/binding; options resolve live via optionsRef (rebuild would drop messages).\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [bindingIdentity],\n  )\n\n  const state = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot)\n\n  return {\n    messages: state.messages,\n    thread: state.thread,\n    status: state.status,\n    error: state.error,\n    send: client.send,\n    abort: client.abort,\n    reset: client.reset,\n    approve: client.approve,\n    reconnect: client.reconnect,\n  }\n}\n"],"mappings":";;;;;;;;;;AACA,SAASA,SAASC,QAAQC,4BAA4B;AAyE/C,SAASC,SACdC,SACAC,UAA2B,CAAC,GAAC;AAI7B,QAAMC,aAAaC,OAAOF,OAAAA;AAC1BC,aAAWE,UAAUH;AAIrB,MAAII;AACJ,MAAI,OAAOL,YAAY,SAAUK,OAAML;WAC9BM,cAAcN,OAAAA,EAAUK,OAAML,QAAQO;AAE/C,QAAMC,kBAAkBH,OAAOL;AAE/B,QAAMS,SAASC;IACb,MACE,IAAIC;MACFN,QAAQO,SACJ,IAAIC,cAAc;QAChBR;QACAS,SAAS,6BAAMZ,WAAWE,QAAQU,SAAzB;QACTC,OAAOb,WAAWE,QAAQW;MAC5B,CAAA,IACCf;;MAEL,MAAA;AACE,cAAMgB,MAAMd,WAAWE,QAAQa;AAC/B,eAAO,OAAOD,QAAQ,aAAaA,IAAAA,IAAQA;MAC7C;IAAA;;;IAIJ;MAACR;;EAAgB;AAGnB,QAAMU,QAAQC,qBAAqBV,OAAOW,WAAWX,OAAOY,aAAaZ,OAAOY,WAAW;AAE3F,SAAO;IACLC,UAAUJ,MAAMI;IAChBC,QAAQL,MAAMK;IACdC,QAAQN,MAAMM;IACdC,OAAOP,MAAMO;IACbC,MAAMjB,OAAOiB;IACbC,OAAOlB,OAAOkB;IACdC,OAAOnB,OAAOmB;IACdC,SAASpB,OAAOoB;IAChBC,WAAWrB,OAAOqB;EACpB;AACF;AAnDgB/B;","names":["useMemo","useRef","useSyncExternalStore","useAgent","binding","options","optionsRef","useRef","current","api","isAgentHandle","path","bindingIdentity","client","useMemo","AgentClient","undefined","HttpTransport","headers","fetch","ctx","context","state","useSyncExternalStore","subscribe","getSnapshot","messages","thread","status","error","send","abort","reset","approve","reconnect"]}

package/dist/client.d.ts

@@ -0,0 +1,81 @@
+import { b as AgentTransport, A as ApprovalDecision } from './agent-handle-DNbFlkrw.js';
+export { c as AgentClient, d as AgentClientState, a as AgentHandle, C as ChannelPushSource, e as ChannelTransport, f as ChannelTransportOptions, g as ChannelTurnHandlers, I as InProcessApprovalRequestLike, h as InProcessAwaitApproval, i as InProcessRunInput, j as InProcessRunner, k as InProcessTransport, l as InProcessTransportOptions, R as RequestContext, U as UseAgentStatus, m as agentHandle, n as isAgentHandle } from './agent-handle-DNbFlkrw.js';
+import { ChatTransport, UIMessage, UIMessageChunk } from 'ai';
+
+/** Extra request headers — a static record OR a resolver called per request (for dynamic auth). */
+type HeadersResolver = Record<string, string> | (() => Record<string, string> | undefined);
+interface HttpTransportOptions {
+    /** Agent endpoint path or URL, e.g. `/api/agents/support`. */
+    api: string;
+    /**
+     * Extra request headers (e.g. auth). Static record OR a resolver evaluated on EVERY request — pass a
+     * resolver when the value is dynamic (a rotating JWT), so a stale header is never sent. Merged UNDER
+     * per-request headers.
+     */
+    headers?: HeadersResolver;
+    /** Override fetch (primarily for tests / non-browser hosts) — static; resolved once at construction. */
+    fetch?: typeof fetch;
+}
+/**
+ * M41 (ADR-0050 D3) — `ChatTransport` over the web agent path.
+ *
+ * - `sendMessages`: `POST <api>` with the UIMessageStream `accept` + the `X-Theo-Action` CSRF header
+ *   (HTTP method + headers are identical to the pre-M41 `useAgent` fetch; the body shape is a superset —
+ *   `{ ...input, messages: [UIMessage] }` — which the server's dual-path parser accepts, so no
+ *   regression), captures the server-minted `x-theokit-run-id`, and returns `ReadableStream<UIMessageChunk>`
+ *   via `ai`'s own SSE parser (`responseToChunkStream`).
+ * - `reconnectToStream`: `GET <api>/runs/<runId>/stream` (M37 durable transport); 404 → `null` (the run
+ *   completed / was evicted). A caller may pass a `Last-Event-ID` header to resume only the tail; by
+ *   default the server replays the run from the start and the client upserts by message id (idempotent).
+ * - `approve`: `POST <api>/approve/<id>` (out-of-band HITL settle).
+ *
+ * Implemented directly (not by subclassing `DefaultChatTransport`) because reconnect keys on our
+ * server-minted `runId` captured from a response header, which the base class does not expose — see
+ * ADR-0050 D3.
+ */
+declare class HttpTransport implements AgentTransport {
+    #private;
+    constructor(options: HttpTransportOptions);
+    sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
+    reconnectToStream(options: Parameters<ChatTransport<UIMessage>['reconnectToStream']>[0]): Promise<ReadableStream<UIMessageChunk> | null>;
+    approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
+}
+
+/**
+ * M2 (theokit-ai-first) — read a TheoKit agent endpoint's `UIMessageStream` SSE `Response`
+ * into reconstructed assistant `UIMessage`s, reusing the `ai` package's own consumer
+ * primitives (`parseJsonEventStream` + `readUIMessageStream`) — the exact path
+ * `@ai-sdk/react`'s `useChat` runs internally. No reinvented wire parser (Rule 9).
+ *
+ * `ai` is an OPTIONAL peer dependency, so it is imported dynamically: an app that never
+ * calls an agent never pays for it, and importing `theokit/client` does not hard-require
+ * `ai` (mirrors how the agent runtime dynamically imports `@theokit/sdk`). An agent app
+ * always has `ai` installed (it is the UIMessageStream consumer).
+ *
+ * `onMessage` is invoked on every reconstruction step with the latest snapshot of the
+ * assistant message, so a caller (the `useAgent` hook) can render streaming updates.
+ */
+declare function consumeUIMessageStream(response: Response, onMessage: (message: UIMessage) => void): Promise<void>;
+/**
+ * M41 (ADR-0050 D3) — the reusable middle piece: a UIMessageStream SSE `Response` →
+ * `ReadableStream<UIMessageChunk>`, reusing `ai`'s own `parseJsonEventStream` (the exact primitive
+ * `useChat` runs). This is precisely what a `ChatTransport.sendMessages` returns, so `HttpTransport`
+ * builds on it directly (no reinvented wire parser — Rule 9). A body-less response yields an empty stream.
+ */
+declare function responseToChunkStream(response: Response): Promise<ReadableStream<UIMessageChunk>>;
+/**
+ * M41 (ADR-0050 D6) — read a `ReadableStream<UIMessageChunk>` into reconstructed assistant
+ * `UIMessage`s via `ai`'s `readUIMessageStream`. Shared by `consumeUIMessageStream` (Response path)
+ * and the framework-agnostic `AgentClient` store (transport path). `onMessage` fires on every
+ * reconstruction step so a caller can render streaming updates.
+ */
+declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMessage: (message: UIMessage) => void): Promise<void>;
+
+/**
+ * M41/M42 — extract the turn text from the last user message's text parts. Shared by the transports
+ * that hand a plain `message` string to an in-process/push runner (`InProcessTransport`,
+ * `ChannelTransport`) rather than POSTing the `messages[]` array (`HttpTransport`). One definition (G12).
+ */
+declare function extractLastUserText(messages: readonly UIMessage[]): string;
+
+export { AgentTransport, ApprovalDecision, type HeadersResolver, HttpTransport, type HttpTransportOptions, consumeChunkStream, consumeUIMessageStream, extractLastUserText, responseToChunkStream };

package/dist/client.js

@@ -0,0 +1,26 @@
+import {
+  AgentClient,
+  ChannelTransport,
+  HttpTransport,
+  InProcessTransport,
+  agentHandle,
+  consumeChunkStream,
+  consumeUIMessageStream,
+  extractLastUserText,
+  isAgentHandle,
+  responseToChunkStream
+} from "./chunk-M2JFE6IM.js";
+import "./chunk-7QVYU63E.js";
+export {
+  AgentClient,
+  ChannelTransport,
+  HttpTransport,
+  InProcessTransport,
+  agentHandle,
+  consumeChunkStream,
+  consumeUIMessageStream,
+  extractLastUserText,
+  isAgentHandle,
+  responseToChunkStream
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { G as Guardrail, L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, M as MainLoopMeta, a as CompiledTool, b as ReasoningEffort, c as RoundStreamFactory, S as StreamEvent, D as DelegationResult, d as ContextWindowOptions, e as SkillsOptions, T as ToolOptions, A as ApprovalOptions, H as HumanInTheLoopOptions, f as AgentManifestEntry } from './bridge-entry-DMh--RZ5.js';
-export { g as AGENT_BRAND, h as AfterToolCallContext, i as AgentBuilder, j as AgentDefinition, k as AgentDefinitionError, l as AgentExecutionContext, m as AgentManifest, n as AgentManifestSource, o as AgentManifestTool, p as AgentOptions, q as AgentRoute, r as AgentRouteContext, s as AgentRunInfo, t as AgentStreamEvent, u as AgentTurnMetadata, v as AgentsPluginOptions, w as ApiErrorContext, x as ApiErrorDecision, y as ApiErrorPolicy, z as ApprovalRequiredEvent, B as ArtifactChunkEvent, E as ArtifactStartEvent, F as BackgroundDelegation, I as BeforeToolCallContext, J as BudgetExceededError, K as BudgetOptions, N as CheckpointSavedEvent, O as CompiledContextWindow, P as ContextualTool, Q as CostBudgetExceededError, U as DEFAULT_MAX_ITERATIONS, V as DefineAgentConfig, W as DelegateFn, X as DelegateOptions, Y as DelegationError, Z as DoneEvent, _ as ErrorEvent, $ as FileEditEvent, a0 as GuardrailAction, a1 as GuardrailPhase, a2 as GuardrailResult, a3 as GuardrailViolationError, a4 as HitlDecision, a5 as HookHandlers, a6 as InferAgentInput, a7 as InferAgentToolNames, a8 as IterationEvent, a9 as LLMCallContext, aa as LoopFinishReason, ab as LoopOutcome, ac as LoopStrategyConfig, ad as MainLoopOptions, ae as McpApprovalSpec, af as McpRegistryConfig, ag as McpRequestContext, ah as McpSelection, ai as PartialToolCallEvent, aj as PolicyHandler, ak as ProcessInputContext, al as ReflectionContext, am as ReflectionResult, an as ReflectionStrategyConfig, ao as RunStartedEvent, ap as ScoreVerdict, aq as ScoredDelegation, ar as Scorer, as as SdkAgentHandle, at as SdkMessage, au as Segment, av as SkillsRequestContext, aw as SkillsSelection, ax as StateUpdateEvent, ay as TextDeltaEvent, az as ThinkingEvent, aA as TimeoutAction, aB as ToolCallEvent, aC as ToolCallVeto, aD as ToolHooks, aE as ToolHooksPlugin, aF as ToolResultEvent, aG as ToolWalkResult, aH as ToolboxOptions, aI as ToolboxWalkResult, aJ as agentsPlugin, aK as buildModelSelection, aL as compileAgentDefinition, aM as compileAgentModule, aN as compileContextWindow, aO as compileProjectContext, aP as compileSkills, aQ as compileTools, aR as createAgentExecutionContext, aS as createApiErrorHandler, aT as createSdkAgentStream, aU as createThinkTagExtractor, aV as createToolHooksPlugin, aW as delegate, aX as delegateBackground, aY as delegateWithScoring, aZ as extractThinkTagStream, a_ as generateAgentManifest, a$ as generateAgentRoutes, b0 as isAgentContext, b1 as isAgentDefinition, b2 as isApprovalRequired, b3 as isDone, b4 as isError, b5 as isPartialToolCall, b6 as isTextDelta, b7 as isToolCall, b8 as isToolResult, b9 as ladderReflectionStrategy, ba as loopStrategyConfigSchema, bb as mcpRegistry, bc as mcpToolApprovals, bd as noopReflectionStrategy, be as presentUIMessageStream, bf as projectContextMetadataOnlyKnobs, bg as reflectionStrategyConfigSchema, bh as resolveEnabledSkills, bi as resolveLoopStrategy, bj as resolveMcpServers, bk as runWithApiErrorHandling, bl as streamAgentResponse, bm as streamAgentUIMessages, bn as toAgentFactory, bo as translateSdkEvent } from './bridge-entry-DMh--RZ5.js';
+import { G as Guardrail, L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, M as MainLoopMeta, a as CompiledTool, b as ReasoningEffort, c as RoundStreamFactory, S as StreamEvent, D as DelegationResult, d as ContextWindowOptions, e as SkillsOptions, T as ToolOptions, A as ApprovalOptions, H as HumanInTheLoopOptions, f as AgentManifestEntry, g as HitlDecision, s as streamAgentUIMessages } from './bridge-entry-Cq1aVJ_c.js';
+export { h as AGENT_BRAND, i as AfterToolCallContext, j as AgentBuilder, k as AgentDefinition, l as AgentDefinitionError, m as AgentExecutionContext, n as AgentManifest, o as AgentManifestSource, p as AgentManifestTool, q as AgentOptions, r as AgentRoute, t as AgentRouteContext, u as AgentRunInfo, v as AgentStreamEvent, w as AgentTurnMetadata, x as AgentsPluginOptions, y as ApiErrorContext, z as ApiErrorDecision, B as ApiErrorPolicy, E as ApprovalRequiredEvent, F as ArtifactChunkEvent, I as ArtifactStartEvent, J as BackgroundDelegation, K as BeforeToolCallContext, N as BudgetExceededError, O as BudgetOptions, P as CheckpointSavedEvent, Q as CompiledContextWindow, U as ContextualTool, V as CostBudgetExceededError, W as DEFAULT_MAX_ITERATIONS, X as DefineAgentConfig, Y as DelegateFn, Z as DelegateOptions, _ as DelegationError, $ as DoneEvent, a0 as ErrorEvent, a1 as FileEditEvent, a2 as GuardrailAction, a3 as GuardrailPhase, a4 as GuardrailResult, a5 as GuardrailViolationError, a6 as HookHandlers, a7 as InferAgentInput, a8 as InferAgentToolNames, a9 as IterationEvent, aa as LLMCallContext, ab as LoopFinishReason, ac as LoopOutcome, ad as LoopStrategyConfig, ae as MainLoopOptions, af as McpApprovalSpec, ag as McpRegistryConfig, ah as McpRequestContext, ai as McpSelection, aj as PartialToolCallEvent, ak as PolicyHandler, al as ProcessInputContext, am as ReflectionContext, an as ReflectionResult, ao as ReflectionStrategyConfig, ap as RunStartedEvent, aq as ScoreVerdict, ar as ScoredDelegation, as as Scorer, at as SdkAgentHandle, au as SdkMessage, av as Segment, aw as SkillsRequestContext, ax as SkillsSelection, ay as StateUpdateEvent, az as TextDeltaEvent, aA as ThinkingEvent, aB as TimeoutAction, aC as ToolCallEvent, aD as ToolCallVeto, aE as ToolHooks, aF as ToolHooksPlugin, aG as ToolResultEvent, aH as ToolWalkResult, aI as ToolboxOptions, aJ as ToolboxWalkResult, aK as agentsPlugin, aL as buildModelSelection, aM as compileAgentDefinition, aN as compileAgentModule, aO as compileContextWindow, aP as compileProjectContext, aQ as compileSkills, aR as compileTools, aS as createAgentExecutionContext, aT as createApiErrorHandler, aU as createSdkAgentStream, aV as createThinkTagExtractor, aW as createToolHooksPlugin, aX as delegate, aY as delegateBackground, aZ as delegateWithScoring, a_ as extractThinkTagStream, a$ as generateAgentManifest, b0 as generateAgentRoutes, b1 as isAgentContext, b2 as isAgentDefinition, b3 as isApprovalRequired, b4 as isDone, b5 as isError, b6 as isPartialToolCall, b7 as isTextDelta, b8 as isToolCall, b9 as isToolResult, ba as ladderReflectionStrategy, bb as loopStrategyConfigSchema, bc as mcpRegistry, bd as mcpToolApprovals, be as noopReflectionStrategy, bf as presentUIMessageStream, bg as projectContextMetadataOnlyKnobs, bh as reflectionStrategyConfigSchema, bi as resolveEnabledSkills, bj as resolveLoopStrategy, bk as resolveMcpServers, bl as runWithApiErrorHandling, bm as streamAgentResponse, bn as toAgentFactory, bo as translateSdkEvent } from './bridge-entry-Cq1aVJ_c.js';
 export * from '@theokit/sdk/errors';
 export { ConfigurationError } from '@theokit/sdk/errors';
 import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool, GoalLoopAgent, GoalOptions, runGoalLoop, GoalEvent, GoalResult, InlineSkill } from '@theokit/sdk';
@@ -15,8 +15,8 @@ export * from '@theokit/sdk/concurrency';
 export * from '@theokit/sdk/messages';
 export * from '@theokit/sdk/models';
 export { discoverSubagents, loadSubagentDefinition } from '@theokit/sdk/subagents-loader';
+import { UIMessageChunk } from 'ai';
 import '@theokit/http';
-import 'ai';
 
 /**
  * M9 (theokit-ai-first) — built-in guardrail detectors.
@@ -981,4 +981,73 @@ declare class AcpClient {
     private handleServerRequest;
 }
 
-export { type A2AAuth, type A2ACapabilities, type A2ASkill, type A2AToolConfig, AcpClient, AcpMessageDecoder, type AcpTransport, type AgentCard, type AgentConfig, AgentConfigCapability, AgentManifestEntry, AgentRunner, AgentRunnerBuilder, type AgentRunnerRunOptions, ApprovalOptions, type BuildAgentCardOptions, type Capability, CapabilityConflictError, CapabilityPreset, CapabilityRegistry, CheckpointCapability, type CompactionCallOptions, type CompactionStrategyConfig, CompiledAgentOptions, type CompiledAgentOptionsDraft, CompiledTool, ContextWindowCapability, type CostGuardOptions, DEFAULT_KEEP_TOKENS, DelegationResult, FieldCapability, type FinalizedDraft, GoalRunner, type GoalRunnerDeps, Guardrail, GuardrailsCapability, HumanInTheLoopCapability, HumanInTheLoopOptions, LoopStrategy, MCP_PROTOCOL_VERSION, MainLoopCapability, MainLoopMeta, type McpJsonSchema, type McpServerInfo, McpServersCapability, type McpToolDescriptor, MemoryCapability, ModelCapability, type OutputModerationOptions, type PiiOptions, PluginsCapability, ProjectContextCapability, type PromptInjectionOptions, type ProvenanceEntry, ReasoningEffort, ReflectionStrategy, RoundStreamFactory, RunContextCapability, SettingSourcesCapability, SkillsCapability, SkillsOptionsCapability, SkillsResolverCapability, StreamEvent, SubAgentsCapability, type Summarize, type ToolDeclaration, ToolOptions, ToolboxCapability, type ToolboxSource, ToolsCapability, type TranscriptCompactionStrategy, UnknownCapabilityError, applyCapabilities, buildAgentCard, buildMcpToolDescriptors, compactionStrategyConfigSchema, costGuard, createA2ATool, createDraft, deriveConversationId, encodeAcpMessage, estimateTokens, mcpServerInfo, moderateOutputStream, outputModeration, parseConversationId, piiDetector, promptInjectionDetector, resolveCompactionStrategy, runInputGuards, runOutputGuards, setOnce, tokenBudgetCompactionStrategy, unicodeNormalizer, wellKnownCardPath };
+/**
+ * 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;
+    /**
+     * M35 (multimodal) — images to send alongside the text. Threaded to the SDK's structured
+     * `SDKUserMessage { text, images }` send form. Absent ⇒ the string send path is byte-unchanged.
+     */
+    images?: Parameters<typeof streamAgentUIMessages>[2]['images'];
+    /** 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>;
+
+export { type A2AAuth, type A2ACapabilities, type A2ASkill, type A2AToolConfig, AcpClient, AcpMessageDecoder, type AcpTransport, type AgentCard, type AgentConfig, AgentConfigCapability, AgentManifestEntry, AgentRunner, AgentRunnerBuilder, type AgentRunnerRunOptions, ApprovalOptions, type BuildAgentCardOptions, type Capability, CapabilityConflictError, CapabilityPreset, CapabilityRegistry, CheckpointCapability, type CompactionCallOptions, type CompactionStrategyConfig, CompiledAgentOptions, type CompiledAgentOptionsDraft, CompiledTool, ContextWindowCapability, type CostGuardOptions, DEFAULT_KEEP_TOKENS, DelegationResult, FieldCapability, type FinalizedDraft, GoalRunner, type GoalRunnerDeps, Guardrail, GuardrailsCapability, HitlDecision, HumanInTheLoopCapability, HumanInTheLoopOptions, type InProcessApprovalRequest, InProcessApprovalRequiredError, type InProcessAwaitApproval, LoopStrategy, MCP_PROTOCOL_VERSION, MainLoopCapability, MainLoopMeta, type McpJsonSchema, type McpServerInfo, McpServersCapability, type McpToolDescriptor, MemoryCapability, ModelCapability, type OutputModerationOptions, type PiiOptions, PluginsCapability, ProjectContextCapability, type PromptInjectionOptions, type ProvenanceEntry, ReasoningEffort, ReflectionStrategy, RoundStreamFactory, RunContextCapability, SettingSourcesCapability, SkillsCapability, SkillsOptionsCapability, SkillsResolverCapability, type StreamAgentTurnDeps, type StreamAgentTurnInProcessInput, StreamEvent, SubAgentsCapability, type Summarize, type ToolDeclaration, ToolOptions, ToolboxCapability, type ToolboxSource, ToolsCapability, type TranscriptCompactionStrategy, UnknownCapabilityError, applyCapabilities, buildAgentCard, buildMcpToolDescriptors, compactionStrategyConfigSchema, costGuard, createA2ATool, createDraft, deriveConversationId, encodeAcpMessage, estimateTokens, mcpServerInfo, moderateOutputStream, outputModeration, parseConversationId, piiDetector, promptInjectionDetector, resolveCompactionStrategy, runInputGuards, runOutputGuards, setOnce, streamAgentTurnInProcess, streamAgentUIMessages, tokenBudgetCompactionStrategy, unicodeNormalizer, wellKnownCardPath };

package/dist/index.js

@@ -72,7 +72,7 @@ import {
   toolRuntimeName,
   translateSdkEvent,
   unicodeNormalizer
-} from "./chunk-IB7I44PO.js";
+} from "./chunk-2L5DI75P.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
@@ -873,6 +873,58 @@ export * from "@theokit/sdk/concurrency";
 export * from "@theokit/sdk/messages";
 export * from "@theokit/sdk/models";
 import { discoverSubagents, loadSubagentDefinition } from "@theokit/sdk/subagents-loader";
+
+// src/in-process-turn.ts
+var InProcessApprovalRequiredError = class extends Error {
+  static {
+    __name(this, "InProcessApprovalRequiredError");
+  }
+  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 resolve = input.awaitApproval;
+  const hitl = gated && gated.size > 0 && resolve ? {
+    gated,
+    awaitApproval: /* @__PURE__ */ __name((approvalId, opts, toolName) => resolve({
+      approvalId,
+      toolName,
+      opts
+    }), "awaitApproval")
+  } : 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,
+      // M35 — pass images through so the SDK send uses the structured `{ text, images }` form.
+      ...input.images !== void 0 ? {
+        images: input.images
+      } : {},
+      sessionId,
+      hitl,
+      signal: input.signal
+    });
+  })();
+}
+__name(streamAgentTurnInProcess, "streamAgentTurnInProcess");
 export {
   AGENT_BRAND,
   AcpClient,
@@ -903,6 +955,7 @@ export {
   GuardrailViolationError,
   GuardrailsCapability,
   HumanInTheLoopCapability,
+  InProcessApprovalRequiredError,
   JudgeCredentialError,
   MCP_PROTOCOL_VERSION,
   MainLoopCapability,
@@ -991,6 +1044,7 @@ export {
   safePathJoin,
   setOnce,
   streamAgentResponse,
+  streamAgentTurnInProcess,
   streamAgentUIMessages,
   toAgentFactory,
   tokenBudgetCompactionStrategy,