@theokit/agents 11.0.0 → 12.0.0

package/CHANGELOG.md

@@ -1,5 +1,107 @@
 # @theokit/agents
 
+## 12.0.0
+
+### Major Changes
+
+- 8691f5c: `@theokit/agents/pty` is gone. The PTY backend now lives in `@theokit/agents-pty`, and installing `@theokit/agents` no longer compiles a terminal.
+
+  `@theokit/sdk-pty` declares `"install": "node scripts/prebuild.js || node-gyp rebuild"` — a native step that downloads a prebuild or falls back to a C++ compile. As a hard dependency of this package, **every consumer paid it**, including every web application that will never open a terminal. Measured: installing `@theokit/agents` alone took **6.7 s** with it and **1.4 s** without, and in a scaffolded app that was most of the gap in time to first green run (30.40 ± 7.50 s against Next.js's 14.93 ± 0.91 s) — with our build faster and our dependency tree smaller.
+
+  **To upgrade**, if you import the subpath:
+
+  ```diff
+  -import { PtyInteractiveBackend } from '@theokit/agents/pty'
+  +import { PtyInteractiveBackend } from '@theokit/agents-pty'
+  ```
+
+  plus `npm install @theokit/agents-pty`.
+
+  You do not have to find this note to know: `@theokit/agents/pty` still resolves, and using anything from it throws with the two lines above. It imports nothing, so keeping it costs no dependency and no native build — the failure is a sentence rather than an `ERR_MODULE_NOT_FOUND` you have to diagnose.
+
+  The surface is identical — the same six symbols, and the new package's test asserts they are the upstream identities rather than a wrapper. Nothing else changes.
+
+  If you do not import it, you install 5.3 s faster and there is nothing to do.
+
+  **Why a package and not an optional peer.** That was tried and reverted: a peer means _the host provides it_, and the M63 boundary forbids an application from importing `@theokit/sdk*` at all — so it would ask a consumer to declare exactly what it may not use. A sibling package is something the consumer genuinely does import, with no inversion. Recorded in `docs/adr/0004-the-terminal-is-a-separate-package.md`, along with the two alternatives rejected (a lazy `import()`, which defers nothing that is being measured, and documenting the cost, which is read after the decision it would inform).
+
+### Minor Changes
+
+- ed68f9f: A configuration error now reaches the browser with its own message, instead of the generic mask.
+
+  `missing_api_key` and `malformed_api_key` are the operator's own input — the person reading the blank error is the person who forgot to set the variable. Masking them cost that person the first ten minutes of every misconfiguration, and did it next to a `transient: true` that means _do not persist in history_ on this protocol and _retry may help_ everywhere else a developer has met the word. Together they read as a network hiccup.
+
+  Everything else is unchanged. #390's default stands: a driver's message, an HTTP client's, a filesystem call's — anything that could name a host, a path, a query or a credential — still reaches the browser as `An error occurred.`, with the failure code travelling separately so consumers never go back to matching on text.
+
+  The hole is keyed on **codes**, not on the error class. `ConfigurationError` is a large surface and parts of it do describe internals, so an allowlist keyed on the parent would widen by accident the first time something new subclassed it. Adding a code to the list is a decision about what a browser may read, and the bar is written beside it.
+
+  A host that passes its own `onError` is unaffected — the allowlist is the default's behaviour, not a rule imposed above the hook.
+
+- bf623e4: A paused run can reach its owner off the stream. `HitlWiring.onApprovalRequired` is the opt-in seam.
+
+  The framework's asynchronous promise — _the agent works and comes back when it needs your approval_ — held only while a client was attached. `ApprovalRequiredEvent` went into the run's own event stream and nowhere else, so a caller not consuming that stream never learned the run was waiting, and it stayed parked until someone opened the surface and looked (#458).
+
+  ```ts
+  createHitlPlugin({
+    gated,
+    emit,
+    awaitApproval,
+    onApprovalRequired: async ({ toolName, question, callbackUrl, timeoutMs }) => {
+      await myDelivery.send({ text: `${question} — ${toolName}`, url: `${BASE}/${callbackUrl}` })
+    },
+  })
+  ```
+
+  It receives the same facts the stream carries and does whatever the **application** does. Deliberately not a `@theokit/gateway` dependency: this package must not import from it, and choosing a channel is a policy decision the framework does not get to make. `@theokit/gateway`'s `DeliveryRouter` is the obvious thing to hand it, and that stays the app's decision.
+
+  **Fire-and-forget by contract, and both halves of that are tested.** The run does not wait for it, so a slow dispatch cannot hold a gated tool open; and it does not fail on it, so a Slack outage cannot decide whether a gated tool runs. A rejected promise is swallowed — the outcome belongs to the human, not to the channel.
+
+  Optional: a wiring without the hook behaves exactly as before.
+
+## 11.1.0
+
+### Minor Changes
+
+- e01c3c2: The in-process turn can be told to retry, and a tool can read the run's real token usage.
+
+  **`retry` on the in-process turn (#474).** `streamAgentTurnInProcess` — the entry point an embedded
+  surface uses, and the one both surfaces of a terminal agent come through — accepts `retry?:
+RetryOptions`. A transient provider failure that kills the turn before it produced anything is
+  recovered instead of ending it. `streamAgentUIMessages` accepts the same field, so the HTTP path
+  gains it too.
+
+  This is not the forwarded field the issue expected, and the difference is the whole fix.
+  `AgentRunnerRunOptions.retry` belongs to the reflective loop, whose round factory is allowed to
+  throw; this path runs one SDK turn, and — measured against the shipped `@theokit/sdk@4.52.1` —
+  the SDK never rejects on a provider failure. `agent.send()` resolves before the model is called, and
+  the loop's failure comes back as the run's terminal `status: "ERROR"` **event**. A `Retry` wrapper
+  around the stream's creation, which is what "thread the option through" would have produced, would
+  have compiled, shipped, and never fired. What ships instead treats that first `error` event as the
+  throw the SDK declined to make.
+
+  The retry window closes on the first event, so nothing has reached the caller and no tool has run —
+  a recovered failure can never re-apply an edit. Whether a failure is worth retrying is read from the
+  run's own typed error (`RunResult.error.cause` → `isTransientError`), never from the message text: a
+  rate limit retries, a bad key does not. Absent ⇒ a single attempt, byte-identical to before.
+
+  **`ctx.usage` for tool handlers (#475).** With `exposeUsageToTools: true`, every tool handler
+  receives the run's provider-reported token usage, read with `readRunUsage(ctx)` from
+  `@theokit/agents/usage`. This is what a `get_context_remaining` tool needs; before it, the only
+  figure reachable from inside a handler was a character-count estimate over `ctx.messages`.
+
+  The numbers come from the SDK's own `BudgetTracker`, which the agent loop calls after each LLM
+  completion with the provider's counts — so they are measurements, never projections. Until the first
+  report arrives the snapshot is `undefined`, not `0`: "not known yet" and "zero tokens used" are
+  different facts and only one is ever true. The context window travels with it when the model
+  **declared** one (`ModelSelection.contextWindow`), along with the `remainingTokens` that needs both
+  halves; for a bare model id both are absent rather than guessed from the model catalog, which
+  answers an unknown model with a conservative default and no way to tell that apart from a real
+  entry. A `budgetTracker` the caller already supplied is wrapped, not replaced, so an existing spend
+  gate keeps gating.
+
+  Both options are additive: omitting them leaves the stream, the SDK call, and the tool ctx exactly as
+  they were.
+
 ## 11.0.0
 
 ### Major Changes

package/dist/{bridge-entry-DRAzQ7UA.d.ts → bridge-entry-Cv6kXSZe.d.ts}

@@ -3,6 +3,7 @@ import { c as AgentOptions, T as ToolOptions, P as ProjectContextOptions, H as H
 import { C as CompiledAgentOptions, a as CompiledTool, G as Guardrail, S as SkillsSelection } from './agent-compiler-tetgj6zR.js';
 import { SkillsSettings, ContextSettings, SystemPromptResolver, ModelSelection, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, RunEventSink, MemorySettings } from '@theokit/sdk';
 import { S as StreamEvent, f as ApprovalRequiredEvent, a4 as MaskError } from './delegation-scoring-CQtF2Zaf.js';
+import { RetryOptions } from '@theokit/sdk/retry';
 import { SandboxPosture } from '@theokit/sdk/sandbox';
 import { A as AgentDefinition, S as SettingSourcesSelection } from './define-agent-BnH1MBxs.js';
 import { z } from 'zod';
@@ -200,6 +201,31 @@ interface HitlWiring {
      * a bare boolean (legacy) OR a {@link HitlDecision} carrying an approver `reason` + `payload`.
      */
     awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) => Promise<boolean | HitlDecision>;
+    /**
+     * OPTIONAL — reach the owner off the stream (usetheokit/theokit#458).
+     *
+     * `emit` above puts the pause into the run's own event stream, and that was the only egress: a
+     * caller not currently consuming it never learned the run was waiting, so the framework's
+     * asynchronous promise held exactly as long as someone was watching.
+     *
+     * This receives the same facts the stream carries and does whatever the APPLICATION does — Slack,
+     * email, a row in a table. Deliberately not a `@theokit/gateway` dependency: this package must not
+     * import from it, and picking a channel is a policy decision the framework does not get to make.
+     *
+     * Fire-and-forget by contract. The run does not wait for it and does not fail on it: a dispatch
+     * outage must not decide whether a gated tool runs, and must not delay the pause it announces.
+     */
+    onApprovalRequired?: (request: ApprovalRequest) => void | Promise<void>;
+}
+/** What an application is told when a gated tool pauses. The stream's facts, off the stream. */
+interface ApprovalRequest {
+    approvalId: string;
+    toolName: string;
+    question: string;
+    input: unknown;
+    /** Relative, exactly as the stream carries it — the app knows its own base URL; this does not. */
+    callbackUrl: string;
+    timeoutMs: number;
 }
 
 /**
@@ -408,6 +434,32 @@ interface RuntimeOverrides {
      * why the key is omitted entirely rather than set to `undefined` when absent.
      */
     onRunEvent?: RunEventSink;
+    /**
+     * theokit#474 — per-turn transient retry, opt-in.
+     *
+     * When set, the START of the turn (the SDK handshake plus its first event, before anything is
+     * yielded) is wrapped in the SDK `Retry`, so a 429/5xx/network blip that kills the turn before it
+     * produced anything is recovered instead of ending it. Absent ⇒ a single attempt, and the key is
+     * omitted from every downstream call, so the stream is byte-identical to before.
+     *
+     * See `turn-retry.ts` for why a rejection-shaped retry would have been inert on this path, and
+     * for the invariant that closes the retry window on the first event.
+     */
+    retry?: RetryOptions;
+    /**
+     * theokit#475 — expose the run's REAL token usage to tool handlers as `ctx.usage`, opt-in.
+     *
+     * When true, the adapter installs a {@link RunUsageMeter} as the run's `budgetTracker` (wrapping
+     * the caller's own, when there is one) and hands every tool handler a snapshot of what the
+     * provider has reported so far. A tool can then answer "how much context is left?" from a
+     * measurement instead of a character-count estimate. See `usage/run-usage.ts`.
+     *
+     * Opt-in rather than always-on because installing a `budgetTracker` changes what `Agent.create`
+     * receives for every run that never asked for it, and the back-compat floor here is a floor, not
+     * a preference. Absent ⇒ handlers are wrapped exactly as before (`ctx.usage` does not exist) and
+     * the SDK receives no tracker it was not already given.
+     */
+    exposeUsageToTools?: boolean;
 }
 declare function createSdkAgentStream(compiled: CompiledAgentOptions, compiledTools: CompiledTool[], apiKey: string | (() => string | Promise<string>), overrides?: RuntimeOverrides): ((message: string, sessionId: string, factoryOpts?: {
     disableTools?: boolean;
@@ -978,6 +1030,30 @@ interface StreamAgentOptions {
      * the stream is byte-identical to before.
      */
     onRunEvent?: RuntimeOverrides['onRunEvent'];
+    /**
+     * theokit#474 — per-turn transient retry.
+     *
+     * `AgentRunnerRunOptions.retry` has existed since V4-P, and it belongs to the OTHER runtime: the
+     * reflective loop, whose round factory is allowed to throw. This entry point runs one SDK turn,
+     * and the SDK reports a provider failure as the run's terminal `error` EVENT rather than as a
+     * rejection — so the option could not simply be forwarded, and a wrapper that only caught throws
+     * would have been inert. See `turn-retry.ts`.
+     *
+     * Absent ⇒ the key is omitted from the SDK call entirely and the turn is a single attempt, exactly
+     * as before.
+     */
+    retry?: RuntimeOverrides['retry'];
+    /**
+     * theokit#475 — expose the run's REAL token usage to tool handlers as `ctx.usage`.
+     *
+     * The seam a `get_context_remaining`-style tool needs: without it the only figure reachable from
+     * inside a handler is a character-count estimate over `ctx.messages`. Read it with `readRunUsage`
+     * from `@theokit/agents/usage`.
+     *
+     * Absent ⇒ handlers receive exactly the ctx they did before and the SDK receives no tracker it
+     * was not already given.
+     */
+    exposeUsageToTools?: RuntimeOverrides['exposeUsageToTools'];
 }
 /**
  * Run a compiled agent and yield the M0/M1 `UIMessageStream` chunks. `apiKey` is resolved by the
@@ -1426,4 +1502,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { createApiErrorHandler as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type ContextWindowOptions as C, type DefinitionOrThunk as D, type EphemeralAgent as E, type SdkMessage as F, type SdkSendOptions as G, type HitlDecision as H, type SdkTurnHandle as I, type Segment as J, type ShouldAutoApproveOptions as K, type LLMCallContext as L, type McpApprovalSpec as M, type ToolHooks as N, type ToolHooksPlugin as O, type ProcessInputContext as P, agentsPlugin as Q, applyPosture as R, type SkillsOptions as S, type ToolCallVeto as T, buildModelSelection as U, compileAgentModule as V, WRITE_SCOPED_TOOLS as W, compileContextWindow as X, compileProjectContext as Y, compileSkills as Z, createAgentExecutionContext as _, type ApprovalPosture as a, createSdkAgentStream as a0, createThinkTagExtractor as a1, createToolHooksPlugin as a2, extractThinkTagStream as a3, generateAgentManifest as a4, generateAgentRoutes as a5, isAgentContext as a6, loadMcpJson as a7, mcpRegistry as a8, mcpToolApprovals as a9, projectContextMetadataOnlyKnobs as aa, reasoningEffortOf as ab, resolveMcpServers as ac, runWithApiErrorHandling as ad, shouldAutoApprove as ae, toAgentFactory as af, translateSdkEvent as ag, withClockCap as ah, withEphemeralAgent as ai, APPROVAL_MODES as b, type AfterToolCallContext as c, AgentBuilder as d, AgentDefinitionError as e, type AgentExecutionContext as f, type AgentManifest as g, type AgentManifestSource as h, type AgentManifestTool as i, type AgentRoute as j, type AgentRouteContext as k, type AgentRunInfo as l, type AgentsPluginOptions as m, type ApiErrorContext as n, type ApiErrorDecision as o, type ApiErrorPolicy as p, type ApprovalMode as q, type CompiledContextWindow as r, streamAgentUIMessages as s, ContextualTool as t, DelegationTimeoutError as u, McpFileError as v, type McpRegistryConfig as w, type McpRequestContext as x, type McpSelection as y, type SdkAgentHandle as z };
+export { createAgentExecutionContext as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type ContextWindowOptions as C, type DefinitionOrThunk as D, type EphemeralAgent as E, type SdkAgentHandle as F, type SdkMessage as G, type HitlDecision as H, type SdkSendOptions as I, type SdkTurnHandle as J, type Segment as K, type LLMCallContext as L, type McpApprovalSpec as M, type ShouldAutoApproveOptions as N, type ToolHooks as O, type ProcessInputContext as P, type ToolHooksPlugin as Q, agentsPlugin as R, type SkillsOptions as S, type ToolCallVeto as T, applyPosture as U, buildModelSelection as V, WRITE_SCOPED_TOOLS as W, compileAgentModule as X, compileContextWindow as Y, compileProjectContext as Z, compileSkills as _, type ApprovalPosture as a, createApiErrorHandler as a0, createSdkAgentStream as a1, createThinkTagExtractor as a2, createToolHooksPlugin as a3, extractThinkTagStream as a4, generateAgentManifest as a5, generateAgentRoutes as a6, isAgentContext as a7, loadMcpJson as a8, mcpRegistry as a9, mcpToolApprovals as aa, projectContextMetadataOnlyKnobs as ab, reasoningEffortOf as ac, resolveMcpServers as ad, runWithApiErrorHandling as ae, shouldAutoApprove as af, toAgentFactory as ag, translateSdkEvent as ah, withClockCap as ai, withEphemeralAgent as aj, APPROVAL_MODES as b, type AfterToolCallContext as c, AgentBuilder as d, AgentDefinitionError as e, type AgentExecutionContext as f, type AgentManifest as g, type AgentManifestSource as h, type AgentManifestTool as i, type AgentRoute as j, type AgentRouteContext as k, type AgentRunInfo as l, type AgentsPluginOptions as m, type ApiErrorContext as n, type ApiErrorDecision as o, type ApiErrorPolicy as p, type ApprovalMode as q, type ApprovalRequest as r, streamAgentUIMessages as s, type CompiledContextWindow as t, ContextualTool as u, DelegationTimeoutError as v, McpFileError as w, type McpRegistryConfig as x, type McpRequestContext as y, type McpSelection as z };

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-export { b as APPROVAL_MODES, c as AfterToolCallContext, d as AgentBuilder, e as AgentDefinitionError, f as AgentExecutionContext, g as AgentManifest, A as AgentManifestEntry, h as AgentManifestSource, i as AgentManifestTool, j as AgentRoute, k as AgentRouteContext, l as AgentRunInfo, m as AgentsPluginOptions, n as ApiErrorContext, o as ApiErrorDecision, p as ApiErrorPolicy, q as ApprovalMode, a as ApprovalPosture, B as BeforeToolCallContext, r as CompiledContextWindow, t as ContextualTool, D as DefinitionOrThunk, u as DelegationTimeoutError, E as EphemeralAgent, L as LLMCallContext, M as McpApprovalSpec, v as McpFileError, w as McpRegistryConfig, x as McpRequestContext, y as McpSelection, P as ProcessInputContext, z as SdkAgentHandle, F as SdkMessage, G as SdkSendOptions, I as SdkTurnHandle, J as Segment, K as ShouldAutoApproveOptions, T as ToolCallVeto, N as ToolHooks, O as ToolHooksPlugin, W as WRITE_SCOPED_TOOLS, Q as agentsPlugin, R as applyPosture, U as buildModelSelection, V as compileAgentModule, X as compileContextWindow, Y as compileProjectContext, Z as compileSkills, _ as createAgentExecutionContext, $ as createApiErrorHandler, a0 as createSdkAgentStream, a1 as createThinkTagExtractor, a2 as createToolHooksPlugin, a3 as extractThinkTagStream, a4 as generateAgentManifest, a5 as generateAgentRoutes, a6 as isAgentContext, a7 as loadMcpJson, a8 as mcpRegistry, a9 as mcpToolApprovals, aa as projectContextMetadataOnlyKnobs, ab as reasoningEffortOf, ac as resolveMcpServers, ad as runWithApiErrorHandling, ae as shouldAutoApprove, s as streamAgentUIMessages, af as toAgentFactory, ag as translateSdkEvent, ah as withClockCap, ai as withEphemeralAgent } from './bridge-entry-DRAzQ7UA.js';
+export { b as APPROVAL_MODES, c as AfterToolCallContext, d as AgentBuilder, e as AgentDefinitionError, f as AgentExecutionContext, g as AgentManifest, A as AgentManifestEntry, h as AgentManifestSource, i as AgentManifestTool, j as AgentRoute, k as AgentRouteContext, l as AgentRunInfo, m as AgentsPluginOptions, n as ApiErrorContext, o as ApiErrorDecision, p as ApiErrorPolicy, q as ApprovalMode, a as ApprovalPosture, B as BeforeToolCallContext, t as CompiledContextWindow, u as ContextualTool, D as DefinitionOrThunk, v as DelegationTimeoutError, E as EphemeralAgent, L as LLMCallContext, M as McpApprovalSpec, w as McpFileError, x as McpRegistryConfig, y as McpRequestContext, z as McpSelection, P as ProcessInputContext, F as SdkAgentHandle, G as SdkMessage, I as SdkSendOptions, J as SdkTurnHandle, K as Segment, N as ShouldAutoApproveOptions, T as ToolCallVeto, O as ToolHooks, Q as ToolHooksPlugin, W as WRITE_SCOPED_TOOLS, R as agentsPlugin, U as applyPosture, V as buildModelSelection, X as compileAgentModule, Y as compileContextWindow, Z as compileProjectContext, _ as compileSkills, $ as createAgentExecutionContext, a0 as createApiErrorHandler, a1 as createSdkAgentStream, a2 as createThinkTagExtractor, a3 as createToolHooksPlugin, a4 as extractThinkTagStream, a5 as generateAgentManifest, a6 as generateAgentRoutes, a7 as isAgentContext, a8 as loadMcpJson, a9 as mcpRegistry, aa as mcpToolApprovals, ab as projectContextMetadataOnlyKnobs, ac as reasoningEffortOf, ad as resolveMcpServers, ae as runWithApiErrorHandling, af as shouldAutoApprove, s as streamAgentUIMessages, ag as toAgentFactory, ah as translateSdkEvent, ai as withClockCap, aj as withEphemeralAgent } from './bridge-entry-Cv6kXSZe.js';
 export { C as CompiledAgentOptions, a as CompiledTool, T as ToolWalkResult, h as ToolboxWalkResult, i as compileTools } from './agent-compiler-tetgj6zR.js';
 export { A as AgentStopReason, d as AgentStreamEvent, e as AgentTurnMetadata, f as ApprovalRequiredEvent, g as ArtifactChunkEvent, h as ArtifactStartEvent, B as BackgroundDelegation, i as BudgetExceededError, C as CheckpointSavedEvent, k as DelegateFn, a as DelegateOptions, l as DelegationBudgetExceededError, m as DelegationError, n as DelegationPort, c as DelegationResult, D as DelegationTarget, o as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as IterationEvent, P as PartialToolCallEvent, v as RunStartedEvent, w as ScoreVerdict, x as ScoredDelegation, y as Scorer, z as StateUpdateEvent, S as StreamEvent, T as TextDeltaEvent, G as ThinkingEvent, H as ToolCallEvent, J as ToolResultEvent, K as delegate, M as delegateBackground, N as delegateWithScoring, O as isApprovalRequired, Q as isDone, U as isError, V as isPartialToolCall, W as isTextDelta, X as isToolCall, Y as isToolResult, a0 as presentUIMessageStream, a3 as streamAgentResponse } from './delegation-scoring-CQtF2Zaf.js';
 export { a as AGENT_BRAND, A as AgentDefinition, D as DefineAgentConfig, I as InferAgentInput, b as InferAgentToolNames, P as ProjectSettingsGrant, c as SettingSourceCapability, S as SettingSourcesSelection, U as UntrustedSettingSourceError, d as compileAgentDefinition, i as isAgentDefinition, r as resolveSettingSources } from './define-agent-BnH1MBxs.js';
@@ -6,8 +6,8 @@ import '@theokit/http';
 import './types-C16Wuh9E.js';
 import '@theokit/sdk';
 import 'zod';
+import '@theokit/sdk/retry';
 import '@theokit/sdk/sandbox';
 import './hook-handlers-Cw2FsnE5.js';
 import '@theokit/presenter/wire';
 import '@theokit/sdk/errors';
-import '@theokit/sdk/retry';

package/dist/bridge.js

@@ -28,7 +28,7 @@ import {
   runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages
-} from "./chunk-T5MBTKA2.js";
+} from "./chunk-OHTXQMR2.js";
 import {
   APPROVAL_MODES,
   BudgetExceededError,
@@ -53,7 +53,7 @@ import {
   translateSdkEvent,
   withClockCap,
   withEphemeralAgent
-} from "./chunk-4EHZG6KN.js";
+} from "./chunk-GQ3XVROU.js";
 import "./chunk-RKWCXVYG.js";
 import {
   AGENT_BRAND,
@@ -62,6 +62,7 @@ import {
   isAgentDefinition,
   resolveSettingSources
 } from "./chunk-LLIERPF3.js";
+import "./chunk-OXNDJSAJ.js";
 import "./chunk-Z4QWC7IK.js";
 export {
   AGENT_BRAND,

package/dist/{chunk-4EHZG6KN.js → chunk-GQ3XVROU.js}

@@ -5,6 +5,9 @@ import {
 import {
   compileAgentDefinition
 } from "./chunk-LLIERPF3.js";
+import {
+  createRunUsageMeter
+} from "./chunk-OXNDJSAJ.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -377,6 +380,21 @@ function createHitlPlugin(wiring) {
             payloadSchema: opts.payloadSchema
           } : {}
         });
+        if (wiring.onApprovalRequired !== void 0) {
+          void (async () => {
+            try {
+              await wiring.onApprovalRequired?.({
+                approvalId,
+                toolName: c.name,
+                question: opts.question,
+                input: c.args,
+                callbackUrl: `approve/${approvalId}`,
+                timeoutMs: opts.timeout ?? 3e5
+              });
+            } catch {
+            }
+          })();
+        }
         const raw = await wiring.awaitApproval(approvalId, opts, c.name);
         const decision = typeof raw === "boolean" ? {
           approved: raw
@@ -489,6 +507,10 @@ function modelIdOf(model) {
   return typeof model === "string" ? model : model.id;
 }
 __name(modelIdOf, "modelIdOf");
+function contextWindowOf(model) {
+  return typeof model === "string" ? void 0 : model.contextWindow;
+}
+__name(contextWindowOf, "contextWindowOf");
 function reasoningEffortOf(model) {
   const params = typeof model === "string" ? void 0 : model.params;
   return params?.find((p) => p.id === PARAM_THINKING)?.value;
@@ -1074,6 +1096,20 @@ function translateTimelineEvent(ev, runId, seen) {
 }
 __name(translateTimelineEvent, "translateTimelineEvent");
 
+// src/bridge/tool-context-injection.ts
+function withInjectedToolContext(handler, injection) {
+  return (input, ctx) => handler(input, {
+    ...ctx,
+    ...injection.runContext !== void 0 ? {
+      context: injection.runContext.value
+    } : {},
+    ...injection.meter !== void 0 ? {
+      usage: injection.meter.snapshot()
+    } : {}
+  });
+}
+__name(withInjectedToolContext, "withInjectedToolContext");
+
 // src/bridge/tool-dialect-stripper.ts
 var OPEN2 = "<function=";
 var CLOSE2 = "</tool_call>";
@@ -1172,6 +1208,61 @@ async function* stripToolDialectStream(source) {
 }
 __name(stripToolDialectStream, "stripToolDialectStream");
 
+// src/bridge/turn-retry.ts
+import { TheokitAgentError as TheokitAgentError2 } from "@theokit/sdk/errors";
+function asText(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+__name(asText, "asText");
+function startFailure(event, outcome) {
+  if (outcome.failure !== void 0) return outcome.failure;
+  return new TheokitAgentError2(asText(event.message) ?? "The turn failed before producing any output.", {
+    code: asText(event.code) ?? "TURN_START_FAILED",
+    isRetryable: event.retryable === true
+  });
+}
+__name(startFailure, "startFailure");
+async function startTurn(open, retry) {
+  const attempt = /* @__PURE__ */ __name(async () => {
+    const { stream, outcome } = open();
+    const it = stream[Symbol.asyncIterator]();
+    try {
+      const first = await it.next();
+      if (!first.done && first.value.type === "error") throw startFailure(first.value, outcome);
+      return {
+        it,
+        first
+      };
+    } catch (err) {
+      await it.return?.(void 0);
+      throw err;
+    }
+  }, "attempt");
+  const { Retry } = await import("@theokit/sdk/retry");
+  return Retry.create(attempt, retry);
+}
+__name(startTurn, "startTurn");
+async function* withTurnStartRetry(open, retry) {
+  const { it, first } = await startTurn(open, retry);
+  let next = first;
+  while (!next.done) {
+    yield next.value;
+    next = await it.next();
+  }
+}
+__name(withTurnStartRetry, "withTurnStartRetry");
+function runTurnWithRetry(open, retry) {
+  if (retry === void 0) return open();
+  return withTurnStartRetry(() => {
+    const outcome = {};
+    return {
+      stream: open(outcome),
+      outcome
+    };
+  }, retry);
+}
+__name(runTurnWithRetry, "runTurnWithRetry");
+
 // src/bridge/sdk-adapter.ts
 function withLeakedDialectRecovery(providers) {
   return {
@@ -1243,15 +1334,19 @@ function hasZodInputSchema(schema) {
   return typeof schema?.parse === "function";
 }
 __name(hasZodInputSchema, "hasZodInputSchema");
-function withRunContext(handler, runContext) {
-  return (input, ctx) => handler(input, {
-    ...ctx,
-    context: runContext
-  });
-}
-__name(withRunContext, "withRunContext");
-function buildSdkTools(compiledTools, defineTool, extraSdkTools = [], runContext) {
-  const has = runContext !== void 0;
+function buildSdkTools(compiledTools, defineTool, extraSdkTools = [], runContext, meter) {
+  const injection = {
+    ...runContext !== void 0 ? {
+      runContext: {
+        value: runContext
+      }
+    } : {},
+    ...meter !== void 0 ? {
+      meter
+    } : {}
+  };
+  const has = injection.runContext !== void 0 || injection.meter !== void 0;
+  const inject = /* @__PURE__ */ __name((h) => has ? withInjectedToolContext(h, injection) : h, "inject");
   return [
     ...compiledTools.map((t) => {
       if (hasZodInputSchema(t.inputSchema)) {
@@ -1259,17 +1354,17 @@ function buildSdkTools(compiledTools, defineTool, extraSdkTools = [], runContext
           name: t.name,
           description: t.description,
           inputSchema: t.inputSchema,
-          handler: has ? withRunContext(t.handler, runContext) : t.handler
+          handler: inject(t.handler)
         });
       }
       return has ? {
         ...t,
-        handler: withRunContext(t.handler, runContext)
+        handler: inject(t.handler)
       } : t;
     }),
     ...extraSdkTools.map((t) => has ? {
       ...t,
-      handler: withRunContext(t.handler, runContext)
+      handler: inject(t.handler)
     } : t)
   ];
 }
@@ -1294,7 +1389,11 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         };
         return;
       }
-      const sdkTools = buildSdkTools(compiledTools, rt.defineTool, overrides.sdkTools, runContext);
+      const usageMeter = overrides.exposeUsageToTools === true ? createRunUsageMeter({
+        contextWindowTokens: contextWindowOf(model),
+        delegate: overrides.budgetTracker
+      }) : void 0;
+      const sdkTools = buildSdkTools(compiledTools, rt.defineTool, overrides.sdkTools, runContext, usageMeter);
       const inlineSkills = compiled.skills?.inline;
       if (inlineSkills !== void 0 && inlineSkills.length > 0 && rt.defineSkillReadTool !== void 0 && !compiledTools.some((t) => t.name === "skill_read")) {
         sdkTools.push(rt.defineSkillReadTool(inlineSkills));
@@ -1311,20 +1410,27 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         source: runContextSource,
         keys: runContext !== void 0 ? Object.keys(runContext) : []
       });
+      const turnOpts = {
+        apiKey: await resolverApiKey(apiKey),
+        model,
+        reasoningEffort,
+        overrides,
+        parseThinkTags,
+        stripToolDialect,
+        sessionId,
+        message,
+        factoryOpts,
+        runId,
+        t0,
+        ...usageMeter !== void 0 ? {
+          usageMeter
+        } : {}
+      };
       try {
-        yield* streamSdkAgent(rt, compiled, sdkTools, {
-          apiKey: await resolverApiKey(apiKey),
-          model,
-          reasoningEffort,
-          overrides,
-          parseThinkTags,
-          stripToolDialect,
-          sessionId,
-          message,
-          factoryOpts,
-          runId,
-          t0
-        });
+        yield* runTurnWithRetry((outcome) => streamSdkAgent(rt, compiled, sdkTools, outcome === void 0 ? turnOpts : {
+          ...turnOpts,
+          outcome
+        }), overrides.retry);
       } catch (err) {
         yield sdkErrorEvent(err);
       }
@@ -1348,6 +1454,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
     baseDir: overrides.baseDir
   };
   const extra = buildExtraCreateOptions(overrides, compiled);
+  if (opts.usageMeter !== void 0) extra.budgetTracker = opts.usageMeter.tracker;
   if (applied.length > 0) {
     debugLog("[THEO_AGENT_M8_RUNTIME_APPLIED]", {
       skills: applied.includes("skills"),
@@ -1388,7 +1495,11 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
         }
       }, "emit");
       for await (const ev of run.events()) {
-        yield* emit(translateTimelineEvent(ev, runId, seen));
+        const translated = translateTimelineEvent(ev, runId, seen);
+        if (opts.outcome !== void 0 && state.lastEventType === "" && translated.some((e) => e.type === "error")) {
+          opts.outcome.failure = (await (await sendPromise).wait()).error?.cause;
+        }
+        yield* emit(translated);
       }
       yield* emit(flushPendingToolResults(seen));
     }, "timeline");
@@ -1596,8 +1707,8 @@ var noopReflectionStrategy = {
 };
 
 // src/bridge/delegation-types.ts
-import { TheokitAgentError as TheokitAgentError2 } from "@theokit/sdk/errors";
-var DelegationBudgetExceededError = class extends TheokitAgentError2 {
+import { TheokitAgentError as TheokitAgentError3 } from "@theokit/sdk/errors";
+var DelegationBudgetExceededError = class extends TheokitAgentError3 {
   static {
     __name(this, "DelegationBudgetExceededError");
   }
@@ -1614,7 +1725,7 @@ var DelegationBudgetExceededError = class extends TheokitAgentError2 {
   }
 };
 var BudgetExceededError = DelegationBudgetExceededError;
-var DelegationError = class extends TheokitAgentError2 {
+var DelegationError = class extends TheokitAgentError3 {
   static {
     __name(this, "DelegationError");
   }
@@ -2204,8 +2315,8 @@ async function delegate(spec, message, opts = {}) {
 __name(delegate, "delegate");
 
 // src/bridge/delegation-lifecycle.ts
-import { TheokitAgentError as TheokitAgentError3 } from "@theokit/sdk/errors";
-var DelegationTimeoutError = class extends TheokitAgentError3 {
+import { TheokitAgentError as TheokitAgentError4 } from "@theokit/sdk/errors";
+var DelegationTimeoutError = class extends TheokitAgentError4 {
   static {
     __name(this, "DelegationTimeoutError");
   }
@@ -2368,4 +2479,4 @@ export {
   delegateBackground,
   delegateWithScoring
 };
-//# sourceMappingURL=chunk-4EHZG6KN.js.map
+//# sourceMappingURL=chunk-GQ3XVROU.js.map