@theokit/agents 10.1.0 → 11.1.0

package/dist/client-react.d.ts

@@ -1,5 +1,5 @@
 import { WireMessage } from '@theokit/presenter/wire';
-import { R as RequestContext, U as UseAgentStatus, A as ApprovalDecision, a as AgentHandle, b as AgentTransport } from './agent-handle-Dgi4ZGbg.js';
+import { R as RequestContext, U as UseAgentStatus, P as PendingApproval, A as ApprovalDecision, a as AgentHandle, b as AgentTransport } from './agent-handle-rEWdERuv.js';
 import '@theokit/sdk/errors';
 
 interface UseAgentReturn<TInput = unknown, TToolNames extends string = string> {
@@ -20,6 +20,28 @@ interface UseAgentReturn<TInput = unknown, TToolNames extends string = string> {
     abort: () => void;
     /** Clear messages + error, back to idle. */
     reset: () => void;
+    /**
+     * The HITL decisions this turn is parked on — empty whenever nothing is outstanding
+     * (usetheokit/theokit#392).
+     *
+     * Each entry carries the id `approve` takes plus what a prompt needs to name the action: the
+     * tool, its resolved input, the declared question and the window. Render it directly:
+     *
+     * ```tsx
+     * {pendingApprovals.map((a) => (
+     *   <div key={a.approvalId}>
+     *     {a.question ?? `Run ${a.toolName}?`}
+     *     <button onClick={() => void approve(a.approvalId, { approved: true })}>Approve</button>
+     *     <button onClick={() => void approve(a.approvalId, { approved: false })}>Deny</button>
+     *   </div>
+     * ))}
+     * ```
+     *
+     * The same decision is on the transcript too — the gated tool's part sits in
+     * `state: 'approval-requested'` with the id under `approval.id` — so a surface that renders tool
+     * parts inline can read it there instead. This field exists so one does not have to.
+     */
+    pendingApprovals: PendingApproval[];
     /** 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). */
@@ -55,4 +77,4 @@ interface UseAgentOptions {
  */
 declare function useAgent<TInput = unknown>(binding: string | AgentHandle<TInput> | AgentTransport, options?: UseAgentOptions): UseAgentReturn<TInput>;
 
-export { type UseAgentOptions, type UseAgentReturn, UseAgentStatus, useAgent };
+export { PendingApproval, type UseAgentOptions, type UseAgentReturn, UseAgentStatus, useAgent };

package/dist/client-react.js

@@ -2,7 +2,7 @@ import {
   AgentClient,
   HttpTransport,
   isAgentHandle
-} from "./chunk-M6HMASZC.js";
+} from "./chunk-7PNUTDBQ.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -41,6 +41,7 @@ function useAgent(binding, options = {}) {
     thread: state.thread,
     status: state.status,
     error: state.error,
+    pendingApprovals: state.pendingApprovals,
     send: client.send,
     abort: client.abort,
     reset: client.reset,

package/dist/client-react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client/use-agent.ts"],"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"]}
+{"version":3,"sources":["../src/client/use-agent.ts"],"mappings":";;;;;;;;;;AACA,SAASA,SAASC,QAAQC,4BAA4B;AA+F/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,kBAAkBR,MAAMQ;IACxBC,MAAMlB,OAAOkB;IACbC,OAAOnB,OAAOmB;IACdC,OAAOpB,OAAOoB;IACdC,SAASrB,OAAOqB;IAChBC,WAAWtB,OAAOsB;EACpB;AACF;AApDgBhC;","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","pendingApprovals","send","abort","reset","approve","reconnect"]}

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { b as AgentTransport, A as ApprovalDecision } from './agent-handle-Dgi4ZGbg.js';
-export { c as AgentClient, d as AgentClientOptions, e as AgentClientState, a as AgentHandle, f as ApprovalAbortedError, C as ChannelPushSource, g as ChannelTransport, h as ChannelTransportOptions, i as ChannelTurnHandlers, I as InProcessApprovalRequestLike, j as InProcessAwaitApproval, k as InProcessRunInput, l as InProcessRunner, m as InProcessTransport, n as InProcessTransportOptions, R as RequestContext, U as UseAgentStatus, o as agentHandle, p as isAgentHandle } from './agent-handle-Dgi4ZGbg.js';
+import { b as AgentTransport, A as ApprovalDecision } from './agent-handle-rEWdERuv.js';
+export { c as AgentClient, d as AgentClientOptions, e as AgentClientState, a as AgentHandle, f as AgentStreamInterruptedError, g as ApprovalAbortedError, C as ChannelPushSource, h as ChannelTransport, i as ChannelTransportOptions, j as ChannelTurnHandlers, I as InProcessApprovalRequestLike, k as InProcessAwaitApproval, l as InProcessRunInput, m as InProcessRunner, n as InProcessTransport, o as InProcessTransportOptions, P as PendingApproval, R as RequestContext, U as UseAgentStatus, p as agentHandle, q as isAgentHandle } from './agent-handle-rEWdERuv.js';
 import { WireTransport, WireChunk, WireMessage } from '@theokit/presenter/wire';
 import '@theokit/sdk/errors';
 
@@ -16,6 +16,48 @@ interface HttpTransportOptions {
     headers?: HeadersResolver;
     /** Override fetch (primarily for tests / non-browser hosts) — static; resolved once at construction. */
     fetch?: typeof fetch;
+    /**
+     * Where the server-minted run id lives between requests — the key `reconnectToStream` needs
+     * (usetheokit/theokit#387).
+     *
+     * Defaults to an in-memory cell, which is what this transport always did and what keeps a
+     * reconnect working within one page lifetime. That default is also why a RELOAD could not
+     * reconnect: the new page builds a fresh transport with an empty cell, so `reconnectToStream`
+     * returns `null` before it reaches the network — while the server still holds the run in its
+     * cache and would replay it.
+     *
+     * The medium is the CONSUMER's decision, not this package's. `sessionStorage` matches a run's
+     * lifetime better than `localStorage`, and either would be a client library writing to browser
+     * storage nobody asked it to write to, with privacy and SSR consequences. So the seam is injected
+     * and the package stores nothing it was not handed a place for:
+     *
+     * ```ts
+     * new HttpTransport({
+     *   api: '/api/agents/support',
+     *   runIdStore: {
+     *     get: () => sessionStorage.getItem('theo.runId') ?? undefined,
+     *     set: (id) => {
+     *       if (id === undefined) sessionStorage.removeItem('theo.runId')
+     *       else sessionStorage.setItem('theo.runId', id)
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * Deliberately NOT included: reconnecting automatically on load. This makes a cached run
+     * REACHABLE; reaching for it is a product decision nobody has asked for.
+     */
+    runIdStore?: RunIdStore;
+}
+/**
+ * Where the reconnect key is kept.
+ *
+ * Two methods rather than a storage object, so a consumer can back it with `sessionStorage`, a
+ * cookie, a router param, or a test double — the transport never learns which.
+ */
+interface RunIdStore {
+    get: () => string | undefined;
+    set: (runId: string | undefined) => void;
 }
 /**
  * M41 (ADR-0050 D3) — `ChatTransport` over the web agent path.
@@ -68,13 +110,55 @@ type UIMessageChunk = WireChunk;
  * `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>;
+declare function consumeUIMessageStream(response: Response, onMessage: (message: UIMessage) => void): Promise<ChunkStreamOutcome>;
 /**
  * A UIMessageStream SSE `Response` → `ReadableStream<UIMessageChunk>`. This is precisely what a
  * `ChatTransport.sendMessages` returns, so `HttpTransport` builds on it directly. A body-less
  * response yields an empty stream.
  */
 declare function responseToChunkStream(response: Response): Promise<ReadableStream<UIMessageChunk>>;
+/**
+ * How a chunk stream ENDED — theokit#384.
+ *
+ * ## Why this exists at all
+ *
+ * The reader used to return `void`, which left its caller exactly two outcomes to choose between:
+ * it threw, or it did not. A stream that simply STOPS — a socket closed mid-run — throws nothing,
+ * so `AgentClient` read "did not throw" as "the agent finished" and settled a truncated answer in
+ * `status: 'done'` with no error. The information needed to tell the two apart was on the wire and
+ * nothing carried it out of the reader.
+ *
+ * ## What counts as an ending, and what does not
+ *
+ * The stream's own terminal chunk, `finish`, is the marker — NOT the SSE `[DONE]` sentinel:
+ *
+ *  - `finish` is emitted by `presentUIMessageStream` on EVERY framework path, including the error
+ *    path, so it is the one terminator that exists on all three transports. `[DONE]` is written
+ *    only by the durable SSE encoder, so an in-process or channel stream has none to look for.
+ *  - `[DONE]` is also the WEAKER claim of the two. `durableUiMessageStreamResponse` flushes it from
+ *    a `finally` even when the source aborted mid-run, so a run cut on the SERVER carries `[DONE]`
+ *    and no `finish`. Keying on `finish` reports that case too; keying on `[DONE]` would miss it.
+ *
+ * `finish` also cannot lie in the other direction: nothing can truncate a run after its terminal
+ * chunk has been written, so a stream that carried one carried a complete turn even if the socket
+ * died a byte later.
+ */
+interface ChunkStreamOutcome {
+    /**
+     * `true` iff the terminal `finish` chunk crossed before the stream ended.
+     *
+     * `false` means the producer stopped talking mid-run: a dropped connection, a killed server, a
+     * proxy timeout. It does NOT mean the run failed — a failure arrives as an `error` chunk, which
+     * the reader raises instead of returning.
+     */
+    readonly terminated: boolean;
+    /**
+     * How many chunks crossed. Diagnostic only, and it earns its place: it separates "the server
+     * accepted the request and then said nothing" (`0`) from "the answer was cut mid-sentence"
+     * (`n > 0`), which are different failures with different first suspects.
+     */
+    readonly chunksReceived: number;
+}
 /**
  * Read a `ReadableStream<UIMessageChunk>` into reconstructed assistant messages. Shared by
  * {@link consumeUIMessageStream} (Response path) and the framework-agnostic `AgentClient` store
@@ -84,8 +168,18 @@ declare function responseToChunkStream(response: Response): Promise<ReadableStre
  * A provider failure (401/429/5xx) arrives as a `{ type: 'error', errorText }` chunk rather than a
  * thrown rejection — both the in-process runner and the SSE path emit it as data. The reader
  * rejects on it, so `AgentClient.#drive`'s existing catch surfaces it (`status='error'`).
+ *
+ * theokit#384 — it also RETURNS how the stream ended. See {@link ChunkStreamOutcome}.
+ *
+ * The observation happens in a `TransformStream` rather than inside `readMessageStream`, because a
+ * bare `finish` reconstructs to nothing: the reader yields a snapshot for it only when it carries
+ * `messageMetadata`, so the terminal chunk is invisible at the message level by design (measured
+ * against the ai-sdk oracle — see `read-message-stream.ts`). Watching the CHUNKS is the only place
+ * the terminator is observable without changing what the reader emits. The cost is one queue hop
+ * per chunk on a path that already spends 3.274 ms per emit deriving the timeline (M86) — real,
+ * and three orders of magnitude below the work it sits next to.
  */
-declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMessage: (message: UIMessage) => void): Promise<void>;
+declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMessage: (message: UIMessage) => void): Promise<ChunkStreamOutcome>;
 
 /**
  * M41/M42 — extract the turn text from the last user message's text parts. Shared by the transports
@@ -94,4 +188,4 @@ declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMe
  */
 declare function extractLastUserText(messages: readonly WireMessage[]): string;
 
-export { AgentTransport, ApprovalDecision, type HeadersResolver, HttpTransport, type HttpTransportOptions, consumeChunkStream, consumeUIMessageStream, extractLastUserText, responseToChunkStream };
+export { AgentTransport, ApprovalDecision, type ChunkStreamOutcome, type HeadersResolver, HttpTransport, type HttpTransportOptions, consumeChunkStream, consumeUIMessageStream, extractLastUserText, responseToChunkStream };

package/dist/client.js

@@ -1,5 +1,6 @@
 import {
   AgentClient,
+  AgentStreamInterruptedError,
   ApprovalAbortedError,
   ChannelTransport,
   HttpTransport,
@@ -10,10 +11,11 @@ import {
   extractLastUserText,
   isAgentHandle,
   responseToChunkStream
-} from "./chunk-M6HMASZC.js";
+} from "./chunk-7PNUTDBQ.js";
 import "./chunk-Z4QWC7IK.js";
 export {
   AgentClient,
+  AgentStreamInterruptedError,
   ApprovalAbortedError,
   ChannelTransport,
   HttpTransport,

package/dist/config.d.ts

@@ -191,7 +191,7 @@ declare class TrustStore {
      * draft called them synchronously and `trust()` returned before the bytes landed, so an immediate
      * `read()` saw an empty store. Same shape as the M71 pointer bug, and same cause — the SDK's
      * `.d.ts` does not declare these, so nothing at compile time says they return a Promise
-     * (usetheodev/theokit-sdk#280).
+     * (usetheokit/theokit-sdk#280).
      */
     trust(record: TrustRecord): Promise<void>;
     /**
@@ -310,7 +310,7 @@ interface LoadInstructionTreeInput {
      * Which files to load. Defaults to the conventional two.
      *
      * A list matches basenames exactly; a predicate answers the question a list cannot. A rules
-     * DIRECTORY — `.claude/rules/`, `.cursor/rules/`, `.theokit/rules/` — holds files the caller
+     * DIRECTORY —, `.cursor/rules/`, `.theokit/rules/` — holds files the caller
      * cannot name in advance, because the user chooses the names. With only a list on offer, the
      * closest consumer wrote its own 112-line walk (budget, depth ceiling, cycle guard and all) to
      * ask `entry.endsWith('.md')`. The walk was ours; only the question was theirs.

package/dist/config.js

@@ -1,6 +1,6 @@
 import {
   ensureSecureDir
-} from "./chunk-QXGSF6WX.js";
+} from "./chunk-D2EFYZBV.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -154,7 +154,7 @@ var TrustStore = class {
   * draft called them synchronously and `trust()` returned before the bytes landed, so an immediate
   * `read()` saw an empty store. Same shape as the M71 pointer bug, and same cause — the SDK's
   * `.d.ts` does not declare these, so nothing at compile time says they return a Promise
-  * (usetheodev/theokit-sdk#280).
+  * (usetheokit/theokit-sdk#280).
   */
   async trust(record) {
     ensureSecureDir(this.file);

package/dist/{define-agent-BO5QSjV8.d.ts → define-agent-BnH1MBxs.d.ts}

@@ -1,6 +1,7 @@
 import { TrustPosture, SettingSource, CustomTool, MemorySettings } from '@theokit/sdk';
 import { z } from 'zod';
-import { R as ReasoningEffort, G as Guardrail, H as HumanInTheLoopOptions, S as SkillsSelection, M as McpServersMap, C as CompiledAgentOptions } from './agent-compiler-CIPQkehU.js';
+import { G as Guardrail, S as SkillsSelection, C as CompiledAgentOptions } from './agent-compiler-tetgj6zR.js';
+import { R as ReasoningEffort, H as HumanInTheLoopOptions, M as McpServersMap } from './types-C16Wuh9E.js';
 import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
 import { TheokitAgentError } from '@theokit/sdk/errors';
 
@@ -127,6 +128,20 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
     system?: string;
     /** Extended-thinking effort. */
     reasoningEffort?: ReasoningEffort;
+    /**
+     * theokit#363 — hard ceiling on the agent's tool-calling turns within ONE run. Reaching it ends
+     * the turn instead of letting the model keep calling tools; absent ⇒ the SDK's own ceiling (8).
+     *
+     * Named `maxIterations`, not `maxSteps`, because the concept already has exactly one name here —
+     * `@Agent({ maxIterations })`, `@MainLoop({ maxIterations })`, `AgentRunner.stream({ maxIterations })`,
+     * `delegate({ maxIterations })` — and one name in the SDK it lowers to (`SendOptions.maxIterations`).
+     * A second name would be the only place needing translation, and the translation is invisible where
+     * it costs most: the SDK rejects an invalid value with a message naming `SendOptions.maxIterations`,
+     * which an author who typed `.maxSteps()` has no way to connect to what they wrote. Familiarity
+     * argues for the ai-sdk spelling, but ai-sdk's own name is `stopWhen: stepCountIs(n)` — borrowing
+     * "steps" would buy recognition of a word, not of an API.
+     */
+    maxIterations?: number;
     /**
      * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
      * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are