theokit 0.26.0 → 0.28.0

package/dist/client/index.js

@@ -386,10 +386,20 @@ function createAppClient(baseUrlOrOptions, legacyFetchImpl) {
 
 // src/client/consume-ui-message-stream.ts
 async function consumeUIMessageStream(response, onMessage) {
-  if (response.body === null) return;
-  const { parseJsonEventStream, readUIMessageStream, uiMessageChunkSchema } = await import("ai");
+  const chunkStream = await responseToChunkStream(response);
+  await consumeChunkStream(chunkStream, onMessage);
+}
+async function responseToChunkStream(response) {
+  if (response.body === null) {
+    return new ReadableStream({
+      start(controller) {
+        controller.close();
+      }
+    });
+  }
+  const { parseJsonEventStream, uiMessageChunkSchema } = await import("ai");
   const parsed = parseJsonEventStream({ stream: response.body, schema: uiMessageChunkSchema });
-  const chunkStream = new ReadableStream({
+  return new ReadableStream({
     async start(controller) {
       for await (const result of parsed) {
         if (result.success) controller.enqueue(result.value);
@@ -397,77 +407,401 @@ async function consumeUIMessageStream(response, onMessage) {
       controller.close();
     }
   });
-  for await (const message of readUIMessageStream({ stream: chunkStream })) {
+}
+async function consumeChunkStream(stream, onMessage) {
+  const { readUIMessageStream } = await import("ai");
+  for await (const message of readUIMessageStream({ stream })) {
     onMessage(message);
   }
 }
 
 // src/client/use-agent.ts
-import { useCallback, useRef, useState } from "react";
-function useAgent(path, options = {}) {
-  const [messages, setMessages] = useState([]);
-  const [status, setStatus] = useState("idle");
-  const [error, setError] = useState(void 0);
-  const controllerRef = useRef(null);
-  const abort = useCallback(() => {
-    controllerRef.current?.abort();
-    controllerRef.current = null;
-  }, []);
-  const reset = useCallback(() => {
-    abort();
-    setMessages([]);
-    setError(void 0);
-    setStatus("idle");
-  }, [abort]);
-  const send = useCallback(
-    (input) => {
-      abort();
-      const controller = new AbortController();
-      controllerRef.current = controller;
-      setMessages([]);
-      setError(void 0);
-      setStatus("streaming");
-      const fetchImpl = options.fetch ?? globalThis.fetch;
-      void (async () => {
-        try {
-          const response = await fetchImpl(path, {
-            method: "POST",
-            headers: {
-              "content-type": "application/json",
-              accept: "text/event-stream",
-              "X-Theo-Action": "1",
-              ...options.headers
-            },
-            body: JSON.stringify(input),
-            signal: controller.signal
-          });
-          await consumeUIMessageStream(response, (message) => {
-            setMessages((prev) => {
-              const next = [...prev];
-              const idx = next.findIndex((m) => m.id === message.id);
-              if (idx >= 0) next[idx] = message;
-              else next.push(message);
-              return next;
-            });
-          });
-          setStatus("done");
-        } catch (err) {
-          if (controller.signal.aborted) return;
-          setError(err instanceof Error ? err : new Error(String(err)));
-          setStatus("error");
+import { useMemo, useRef, useSyncExternalStore } from "react";
+
+// src/client/agent-client.ts
+function inputToText(input) {
+  if (typeof input === "object" && input !== null && typeof input.message === "string") {
+    return input.message;
+  }
+  if (typeof input === "string") return input;
+  return JSON.stringify(input);
+}
+function buildUserMessage(input) {
+  return {
+    id: crypto.randomUUID(),
+    role: "user",
+    parts: [{ type: "text", text: inputToText(input) }]
+  };
+}
+var AgentClient = class {
+  #transport;
+  #chatId = crypto.randomUUID();
+  #listeners = /* @__PURE__ */ new Set();
+  #messages = [];
+  #status = "idle";
+  #error;
+  #controller = null;
+  #snapshot = { messages: [], status: "idle", error: void 0 };
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  /** Subscribe to state changes; returns an unsubscribe fn. */
+  subscribe = (listener) => {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  };
+  /** The current immutable snapshot (stable reference until the next emit). */
+  getSnapshot = () => this.#snapshot;
+  #emit() {
+    this.#snapshot = { messages: this.#messages, status: this.#status, error: this.#error };
+    for (const listener of this.#listeners) listener();
+  }
+  #upsert(message) {
+    const next = [...this.#messages];
+    const idx = next.findIndex((existing) => existing.id === message.id);
+    if (idx >= 0) next[idx] = message;
+    else next.push(message);
+    this.#messages = next;
+  }
+  async #drive(open, controller) {
+    const aborted = () => controller.signal.aborted;
+    try {
+      const stream = await open();
+      if (aborted()) return;
+      if (stream === null) {
+        this.#status = this.#messages.length > 0 ? "done" : "idle";
+        this.#emit();
+        return;
+      }
+      await consumeChunkStream(stream, (message) => {
+        if (aborted()) return;
+        this.#upsert(message);
+        this.#emit();
+      });
+      if (aborted()) return;
+      this.#status = "done";
+      this.#emit();
+    } catch (err) {
+      if (aborted()) return;
+      this.#error = err instanceof Error ? err : new Error(String(err));
+      this.#status = "error";
+      this.#emit();
+    }
+  }
+  /** Send a typed input; opens a fresh stream (replaces prior messages). */
+  send = (input) => {
+    this.abort();
+    const controller = new AbortController();
+    this.#controller = controller;
+    this.#messages = [];
+    this.#error = void 0;
+    this.#status = "streaming";
+    this.#emit();
+    void this.#drive(
+      () => this.#transport.sendMessages({
+        trigger: "submit-message",
+        chatId: this.#chatId,
+        messageId: void 0,
+        messages: [buildUserMessage(input)],
+        abortSignal: controller.signal,
+        // Only object inputs flow as the request `body` (the turn text is always in `messages`);
+        // a primitive input is carried by the user message, never spread into the body.
+        body: typeof input === "object" && input !== null ? input : void 0
+      }),
+      controller
+    );
+  };
+  /** Resume an interrupted stream via the transport's `reconnectToStream` (no-op when unavailable). */
+  reconnect = () => {
+    const controller = new AbortController();
+    this.#controller = controller;
+    this.#status = "streaming";
+    this.#emit();
+    void this.#drive(() => this.#transport.reconnectToStream({ chatId: this.#chatId }), controller);
+  };
+  /** Abort an in-flight stream (not an error — leaves messages as-is). */
+  abort = () => {
+    this.#controller?.abort();
+    this.#controller = null;
+  };
+  /** Clear messages + error, back to idle. */
+  reset = () => {
+    this.abort();
+    this.#messages = [];
+    this.#error = void 0;
+    this.#status = "idle";
+    this.#emit();
+  };
+  /** Settle a paused HITL approval via the transport's HITL path (HTTP POST or inline callback). */
+  approve = async (approvalId, decision) => {
+    await this.#transport.approve?.(approvalId, decision);
+  };
+};
+
+// src/client/http-transport.ts
+function toRecord(headers) {
+  if (headers === void 0) return {};
+  if (headers instanceof Headers) return Object.fromEntries(headers.entries());
+  return headers;
+}
+var HttpTransport = class {
+  #api;
+  #headers;
+  #fetch;
+  /** Server-minted id of the last run (from `x-theokit-run-id`) — the reconnect key. */
+  #lastRunId;
+  constructor(options) {
+    this.#api = options.api;
+    this.#headers = options.headers ?? {};
+    this.#fetch = options.fetch ?? globalThis.fetch;
+  }
+  /** Resolve the configured headers per request (a resolver evaluates now — dynamic auth is never stale). */
+  #resolveHeaders() {
+    return (typeof this.#headers === "function" ? this.#headers() : this.#headers) ?? {};
+  }
+  async sendMessages(options) {
+    const { messages, abortSignal, headers, body } = options;
+    const extra = typeof body === "object" ? body : void 0;
+    const response = await this.#fetch(this.#api, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "text/event-stream",
+        "X-Theo-Action": "1",
+        ...this.#resolveHeaders(),
+        ...toRecord(headers)
+      },
+      body: JSON.stringify({ ...extra, messages }),
+      signal: abortSignal
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Agent request to ${this.#api} failed: ${response.status} ${response.statusText}`
+      );
+    }
+    this.#lastRunId = response.headers.get("x-theokit-run-id") ?? void 0;
+    return responseToChunkStream(response);
+  }
+  async reconnectToStream(options) {
+    if (this.#lastRunId === void 0) return null;
+    const response = await this.#fetch(`${this.#api}/runs/${this.#lastRunId}/stream`, {
+      method: "GET",
+      headers: { ...this.#resolveHeaders(), ...toRecord(options.headers) }
+    });
+    if (response.status === 404) return null;
+    if (!response.ok) {
+      throw new Error(
+        `Agent reconnect to run ${this.#lastRunId} failed: ${response.status} ${response.statusText}`
+      );
+    }
+    return responseToChunkStream(response);
+  }
+  async approve(approvalId, decision) {
+    const response = await this.#fetch(`${this.#api}/approve/${approvalId}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "X-Theo-Action": "1",
+        ...this.#resolveHeaders()
+      },
+      body: JSON.stringify(decision)
+    });
+    if (!response.ok) {
+      throw new Error(`Approve ${approvalId} failed: ${response.status} ${response.statusText}`);
+    }
+  }
+};
+
+// src/client/use-agent.ts
+function useAgent(pathOrTransport, options = {}) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const client = useMemo(
+    () => new AgentClient(
+      typeof pathOrTransport === "string" ? new HttpTransport({
+        api: pathOrTransport,
+        headers: () => optionsRef.current.headers,
+        fetch: optionsRef.current.fetch
+      }) : pathOrTransport
+    ),
+    // Identity is the binding; headers are resolved live via optionsRef, fetch captured at creation.
+    [pathOrTransport]
+  );
+  const state = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
+  return {
+    messages: state.messages,
+    status: state.status,
+    error: state.error,
+    send: client.send,
+    abort: client.abort,
+    reset: client.reset,
+    approve: client.approve,
+    reconnect: client.reconnect
+  };
+}
+
+// src/client/last-user-text.ts
+function extractLastUserText(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role !== "user") continue;
+    const text = message.parts.filter((part) => part.type === "text").map((part) => part.text).join("");
+    if (text.length > 0) return text;
+  }
+  return "";
+}
+
+// src/client/in-process-transport.ts
+function generatorToStream(gen) {
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const result = await gen.next();
+        if (result.done === true) {
+          controller.close();
+          return;
         }
-      })();
+        controller.enqueue(result.value);
+      } catch (err) {
+        controller.error(err);
+      }
     },
-    [abort, options.fetch, options.headers, path]
-  );
-  return { messages, status, error, send, abort, reset };
+    async cancel() {
+      await gen.return(void 0);
+    }
+  });
 }
+var InProcessTransport = class {
+  #run;
+  /** Pending inline approvals: approvalId → resolver of the parked `awaitApproval` promise. */
+  #pending = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.#run = options.run;
+  }
+  #awaitApproval = (req) => new Promise((resolve, reject) => {
+    if (this.#pending.has(req.approvalId)) {
+      reject(new Error(`Duplicate pending approval id '${req.approvalId}' \u2014 ids must be unique.`));
+      return;
+    }
+    this.#pending.set(req.approvalId, resolve);
+  });
+  sendMessages(options) {
+    const { messages, abortSignal } = options;
+    const generator = this.#run({
+      message: extractLastUserText(messages),
+      signal: abortSignal ?? void 0,
+      awaitApproval: this.#awaitApproval
+    });
+    return Promise.resolve(generatorToStream(generator));
+  }
+  reconnectToStream() {
+    return Promise.resolve(null);
+  }
+  approve(approvalId, decision) {
+    const resolve = this.#pending.get(approvalId);
+    if (resolve === void 0) {
+      return Promise.reject(
+        new Error(`No pending approval '${approvalId}' (unknown or already settled).`)
+      );
+    }
+    this.#pending.delete(approvalId);
+    resolve(decision);
+    return Promise.resolve();
+  }
+};
+
+// src/client/channel-transport.ts
+var ChannelTransport = class {
+  #source;
+  constructor(options) {
+    this.#source = options.source;
+  }
+  sendMessages(options) {
+    const { messages, abortSignal } = options;
+    const message = extractLastUserText(messages);
+    const source = this.#source;
+    let closed = false;
+    let teardown = () => void 0;
+    let detachAbort = () => void 0;
+    const stream = new ReadableStream({
+      start(controller) {
+        const finish = (settle) => {
+          if (closed) return;
+          closed = true;
+          detachAbort();
+          settle();
+        };
+        teardown = source.start(
+          { message },
+          {
+            onLine: (line) => {
+              if (closed) return;
+              let parsed;
+              try {
+                parsed = JSON.parse(line);
+              } catch {
+                return;
+              }
+              if (typeof parsed !== "object" || parsed === null || typeof parsed.type !== "string") {
+                return;
+              }
+              controller.enqueue(parsed);
+            },
+            onClose: () => {
+              finish(() => {
+                controller.close();
+              });
+            },
+            onError: (err) => {
+              finish(() => {
+                controller.error(err);
+              });
+            }
+          }
+        );
+        if (abortSignal !== void 0) {
+          const onAbort = () => {
+            finish(() => {
+              teardown();
+              controller.close();
+            });
+          };
+          if (abortSignal.aborted) onAbort();
+          else {
+            abortSignal.addEventListener("abort", onAbort);
+            detachAbort = () => {
+              abortSignal.removeEventListener("abort", onAbort);
+            };
+          }
+        }
+      },
+      cancel() {
+        if (closed) return;
+        closed = true;
+        detachAbort();
+        teardown();
+      }
+    });
+    return Promise.resolve(stream);
+  }
+  reconnectToStream() {
+    return Promise.resolve(null);
+  }
+  async approve(approvalId, decision) {
+    if (this.#source.settle === void 0) {
+      throw new Error(`This channel source has no HITL settle \u2014 cannot approve '${approvalId}'.`);
+    }
+    await this.#source.settle(approvalId, decision);
+  }
+};
 
 // src/client/link.tsx
 import {
   Link as RouterLink
 } from "react-router";
-import { useRef as useRef2, useCallback as useCallback2, useEffect } from "react";
+import { useRef as useRef2, useCallback, useEffect } from "react";
 import { jsx } from "react/jsx-runtime";
 var prefetched = /* @__PURE__ */ new Set();
 function injectPrefetch(href) {
@@ -485,7 +819,7 @@ function resolveTo(to) {
 }
 function Link({ prefetch = "intent", to, onMouseEnter, onFocus, ...rest }) {
   const ref = useRef2(null);
-  const handleIntent = useCallback2(
+  const handleIntent = useCallback(
     (event) => {
       if (prefetch === "intent") {
         injectPrefetch(resolveTo(to));
@@ -601,17 +935,23 @@ function mountMcpApp(container, resource, opts) {
   };
 }
 export {
+  AgentClient,
+  ChannelTransport,
+  HttpTransport,
   Image,
+  InProcessTransport,
   Link,
   MCP_APP_SANDBOX,
   Metadata,
   TheoFetchError,
   buildUseTheoQueryConfig,
+  consumeChunkStream,
   consumeUIMessageStream,
   createAppClient,
   createBatcher,
   createGuestMessageHandler,
   mountMcpApp,
+  responseToChunkStream,
   stableQueryKey,
   theoFetch,
   useAgent