@theokit/agents 10.1.0 → 11.0.0

package/CHANGELOG.md

@@ -1,5 +1,317 @@
 # @theokit/agents
 
+## 11.0.0
+
+### Major Changes
+
+- bbdfc15: The server's raw error text no longer reaches the browser by default.
+
+  Every failure the framework reported to a browser carried the server's own words: a tool handler's
+  stderr verbatim in `tool-output-error.errorText`, a run failure's message verbatim in
+  `error.errorText` — whatever a driver, an HTTP client or a filesystem call put in the exception.
+  `ai@7`, speaking the same UIMessage protocol, masks by default and says why in its own comment:
+  "prevent leaking server error details to the client by default". There was no equivalent here, and
+  no seam to add one.
+
+  Both are masked now, through one `onError` hook on the serving boundary
+  (`streamAgentUIMessages`, `streamAgentTurnInProcess`, and `mountAgent` by pass-through), defaulting
+  to a fixed string. The full text is not lost: it still reaches the server's logs and the
+  `agent.run` span, and the hook receives it — what stops is it reaching a browser unless the host
+  decides otherwise.
+
+  **A tool's error text masks by the same default as a run's**, which the report that raised this
+  deliberately left open. The deciding fact is that masking costs the model nothing: the presenter is
+  downstream of the SDK loop, observing events the model has already consumed, so the copy being
+  masked is the browser's and only the browser's. Two different defaults for "server text reaching a
+  browser" would be a rule nobody could hold.
+
+  The failure `code` keeps travelling on its own data part, so consumers still distinguish failures
+  without matching on text — masking that removed the discriminator would push them back into the
+  habit that part exists to have removed.
+
+  **Breaking** for `@theokit/agents`: an application that read the server's message out of
+  `errorText` now reads `'An error occurred.'`. Pass `onError: (e) => e.message` to restore the old
+  behaviour explicitly, which is the point — it becomes a decision instead of a default.
+
+- d4da51b: The agent route `generateAgentRoutes` mounts now speaks the wire this framework's clients read.
+
+  There were TWO SSE encoders for agent runs and they did not agree. The durable one writes
+  `data: <UIMessageChunk>` and a terminal `data: [DONE]`; this one wrote
+  `event: <type>` + `data: <framework StreamEvent>` — snake_case agent events rather than kebab-case
+  wire chunks — and no terminator at all.
+
+  `parseWireStream` validates each `data:` payload against `wireChunkSchema` and drops what fails
+  through a `warn` whose default sink is a no-op. So a `TheoApp` app mounted with `agentRuntime`
+  served `POST {route}/chat` in a format none of its own clients could read: zero chunks, no
+  assistant message, and a run reporting success with an empty answer — silent at every layer.
+
+  The events go through `presentUIMessageStream` now, the same translator `mountAgent` uses, so there
+  is one wire and one place that produces it. It also terminates: the missing `finish` chunk is what
+  a client keys "completed" on, so without it a finished run and a dropped connection were
+  indistinguishable there too.
+
+  **Breaking** for anyone who built their own reader against the old framework-event format on this
+  route. That is the trade the fix makes: a wire only a bespoke consumer could read, for the one every
+  client in this framework already speaks.
+
+### Minor Changes
+
+- a896e4a: A conversation survives a reload: `chatId` can be supplied and read.
+
+  `AgentClient` drew `#chatId` in its field declaration and offered no way to supply one or to read
+  the one it drew. The id is not decorative — the HTTP transport sends it as the top-level `id`, which
+  the server reads as the session id — so every `new AgentClient(...)` started a new conversation, and
+  reloading the page silently abandoned the thread the server still held.
+
+  ```ts
+  const client = new AgentClient(transport, undefined, {
+    chatId: localStorage.getItem('chat') ?? undefined,
+  })
+  localStorage.setItem('chat', client.chatId)
+  ```
+
+  Both halves matter. Reading without supplying lets an application persist an id it can never
+  restore; supplying without reading leaves it nothing to persist.
+
+  The default is unchanged and deliberately so: two clients built with no id are still two
+  conversations. Sharing one by default would let two unrelated tabs write into the same thread, which
+  is the opposite defect and the more dangerous one.
+
+- d9e98e0: A model that takes no credential can delegate.
+
+  `createDelegateTool` refused to construct when any target was a `SubAgentSpec` and
+  `defaults.apiKey` was empty, and `delegate()` refused the same way deeper in its own call stack.
+  Both read "non-empty string" as the definition of authenticated — a safe reading while every
+  provider held a key, and no longer one now that a keyless provider (a model on the developer's own
+  machine) is reachable.
+
+  `apiKey: null` says the provider takes no credential. It is a distinct value from `''` on purpose:
+  an empty string is also what an unset environment variable produces, so accepting THAT would turn a
+  typo into an unauthenticated run. `undefined` still means the caller supplied nothing and is still
+  refused — at startup rather than at the model's first call, which is what the guard was for.
+
+  The refusal now names the option, so a reader who hits it is not left choosing between a fabricated
+  value and giving up.
+
+- da4db56: A run the server still holds can be reached after a page reload.
+
+  The whole durable-reconnect machinery — sequence ids on every frame, the `RunEventCache`, the
+  `Last-Event-ID` replay, the `x-theokit-run-id` header — was built and reachable, and one link made
+  it unusable in the case with the highest user cost. The reconnect key lived in a private in-memory
+  field, so a reloaded page built a fresh transport with an empty cell and `reconnectToStream`
+  returned `null` before it reached the network. The run was alive, cached, replayable, and
+  unreachable; the user got an empty thread instead of the answer the server had already finished.
+
+  `HttpTransport` takes a `runIdStore` now — `{ get(): string | undefined; set(id): void }` —
+  defaulting to an in-memory cell, which is exactly what the private field was. Nothing changes for a
+  caller who passes nothing, including the reconnect-within-one-page-lifetime case that already
+  worked.
+
+  The MEDIUM is deliberately the consumer's decision. `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.
+
+  Deliberately NOT included: reconnecting automatically on load. This makes a cached run _reachable_;
+  reaching for it is a product decision nobody has asked for.
+
+- 3762c7d: An agent can declare a ceiling on the tool-calling turns of a single run, and the served agent obeys
+  it. `AgentBuilder.create().maxIterations(5)` and `defineAgent({ maxIterations: 5 })` are new; the
+  ceiling `@Agent({ maxIterations })` and `@MainLoop({ maxIterations })` already accepted now reaches
+  the runtime as well.
+
+  The number was written by every authoring path and read by none of them once the agent was served:
+  the only code enforcing a ceiling was the reflective loop, which no served path calls. The adapter
+  now lowers `CompiledAgentOptions.maxIterations` to the SDK's `SendOptions.maxIterations` — its
+  documented per-send ceiling — on both the streaming path and the handle `toAgentFactory` serves,
+  where a caller's own value still wins for that turn.
+
+  An agent that declares no ceiling is untouched: the key is omitted entirely, so the SDK's own default
+  still applies and nothing about that run changes. A value that is not a positive integer is refused
+  where it was written rather than at the first send.
+
+- 5f90ddd: A run that was cut short says so. The terminal `done` frame and the turn metadata a client reads off
+  `UIMessage.metadata` now carry an optional `stopReason` — `'step_limit'` when the loop ran out of
+  tool-calling turns while the model still wanted more, `'no_progress'` when the doom-loop guard
+  stopped it repeating identical tool calls. The observability span `agent.run` records the same value
+  as `stop.reason`.
+
+  Both outcomes reached the caller as an ordinary `done` before this, identical in every field to a run
+  that finished on its own, so a surface could not tell "the agent answered" from "the agent was cut off
+  with a tool call still pending". The SDK reported both on its `RunResult`; the adapter's locally-typed
+  `wait()` declared no field to read them from, so nothing read them.
+
+  This is not the rare case it looks like: the SDK's iteration budget defaults to 8, so every served run
+  needing a ninth tool-calling turn was being truncated and reported as finished — including runs of
+  agents that never declared a ceiling.
+
+  Two reasons rather than a `truncated` flag, because they demand opposite reactions: `step_limit` means
+  re-sending continues the work, `no_progress` means re-sending repeats the loop that was just cut.
+  Nothing here re-sends — the SDK owns continuation; this reports the outcome.
+
+  A run that finishes on its own is unchanged: the field is absent, not `undefined`, so absence keeps
+  meaning "the agent finished" and a consumer that has never heard of `stopReason` receives exactly what
+  it received before.
+
+- c131170: A run whose connection drops mid-answer is reported as interrupted instead of finished. The agent
+  client used to settle a dropped stream in `status: 'done'` with `error` undefined and half a sentence
+  on screen — the spinner stopped, the error surface stayed empty, and the truncated turn was committed
+  to the thread as a completed one. `reconnect()` and the durable replay route were fully built and
+  unreachable, because the only trigger a consumer has for them is a status that never arrived.
+
+  `consumeChunkStream` (and `consumeUIMessageStream`) now return a `ChunkStreamOutcome` saying whether
+  the stream carried its terminal `finish` chunk and how many chunks crossed. When it did not,
+  `AgentClient` settles `status: 'error'` with an `AgentStreamInterruptedError` — a `TheokitAgentError`
+  with `code: 'AGENT_STREAM_INTERRUPTED'` and `isRetryable: true`, so `isTransientError` sees it and a
+  consumer decides on the type instead of on message text. The text already received stays on screen,
+  and `send()`'s existing rule keeps the truncated turn out of history.
+
+  The status is `'error'` rather than a new `'interrupted'` member on purpose: a new member fixes the
+  lie only for consumers who update their switch, while every other surface keeps rendering a finished
+  turn. Reusing `'error'` fixes it for all of them at once, and the reason for it lives in the typed
+  error where this framework already puts error discrimination.
+
+  This is a different axis from `stopReason` (#379), not another member of it. `stopReason` says why the
+  RUN stopped and rides the terminal frame's metadata; an interruption is the absence of that frame,
+  where the client cannot know why the run stopped because it never heard.
+
+  A stream that ends on its terminal `finish` chunk is unchanged, down to the fields on the snapshot.
+  A custom transport that never emitted `finish` — which no framework producer does, since
+  `presentUIMessageStream` emits it on every path including the error one — will now be reported as
+  interrupted, which is what it always was.
+
+- e29e22e: `mcpInventory()`, from `@theokit/agents/mcp-health`: the per-server status of the agent's MCP
+  servers — `loaded`, `failed` or `ignored`, each with its reason.
+
+  `loadMcpJson` reads the configuration file; this reads what was observed. A server that failed its
+  handshake and a server the loader refused both appear, which is what a `/mcp`-style command needs and
+  what a configuration read cannot give.
+
+  Tool-level enumeration is not included and is not planned here: the resolved tool table lives inside
+  `@theokit/sdk`'s agent loop and no run event carries it.
+
+- a5c6353: `readThreadHistory()` from `@theokit/agents/session`: read one thread's stored history with three
+  answers — `present`, `absent`, or `unreadable` with the reason.
+
+  Applications had two. Catching for a brand-new thread (which has no transcript yet) is mandatory, and
+  that catch also swallowed parse and permission failures, so a damaged conversation rendered as an
+  empty successful one.
+
+  `absent` still does not distinguish a lost conversation from a new one, and the type says so: the
+  thread id is minted client-side and nothing records that it was issued. That distinction belongs to
+  the caller who knows whether the id was restored from storage or freshly minted.
+
+### Patch Changes
+
+- c8022db: Four separate defects the SAST gate was reporting, each fixed at its cause.
+
+  **A generated property key could not contain a backslash.** The typed app-client emits a route
+  segment that is not a plain identifier as a quoted key, escaping the quote but not the escape
+  character — so a segment ending in `\` produced `'trail\'`, whose trailing backslash escapes the
+  closing quote and swallows the rest of the emitted line. A backslash is a legal POSIX filename
+  character, so it reaches this code from `server/routes/`.
+
+  **An internal error could forge log entries.** `sendError` logs an `INTERNAL_ERROR` with its
+  message and request id, and an exception message can be built from request data. A newline inside
+  it reached the log verbatim, which is enough to append lines of one's own — a fabricated entry
+  sitting in the log looking exactly like a real one. Both values are now rendered as one line.
+
+  **Stripping TOTP padding was quadratic.** `base32Decode` removed trailing `=` with an anchored
+  `/=+$/`, which retries from every start position, so a long run of `=` followed by anything else
+  costs O(n²) — on an authentication path. The comment defending it argued the input was short
+  enough ("10..50 chars typical"), which is an expectation rather than a bound. A scan back from the
+  end is linear and needs no such argument.
+
+  **The hook-output fence escaped only the first `<`.** `fenceHookOutput` neutralises an early
+  fence-close by escaping its `<`, using a form of `replace` that stops at the first occurrence. The
+  fence contains exactly one today, so nothing was wrong — and nothing said so, which made the
+  correctness of a prompt-injection guard depend on a property of a string literal several lines
+  away. `replaceAll` removes the dependency.
+
+  Behaviour is otherwise unchanged: an identifier-safe key, a message without newlines, a normal
+  base32 secret and a well-formed hook output all produce exactly what they produced before.
+
+- 0e9e6dc: A human-in-the-loop tool call is one call on the wire again. A `@HumanInTheLoop` tool used to cross
+  as TWO `tool-input-available` chunks under two different `toolCallId`s — the approval id the HITL
+  plugin mints for its `approve/${approvalId}` callback, and the runtime tool-call id the SDK mints
+  when it dispatches the tool. Neither producer can adopt the other's id: the SDK's `pre_tool_call`
+  context carries `name`, `args`, `agentId` and `runId` and no call id at all, so the plugin has
+  nothing to key on, and the approval has to be published before the tool exists.
+
+  The translator correlates them now, so one logical call is announced once and its result carries the
+  same id. `tool-approval-request` keeps the plugin's id in `approvalId` — the callback URL is
+  unchanged and the same value still resolves the pause — and names the call it gates in `toolCallId`,
+  which is what that field was always for.
+
+  What this was costing: a consumer counting tool calls counted two, a UI grouping blocks by
+  `toolCallId` rendered two cards for one call and left a permanently pending approval part next to the
+  completed one, and the `agent.hitl` observability span opened on the approval id was never closed by
+  a result arriving under the runtime id — so its duration approximated the whole run instead of the
+  human's wait. That span now closes at the resume and carries `hitl.resume_observed: true`; the
+  end-of-run sweep that marks the opposite is back to being the exceptional path it describes, reached
+  when a pause genuinely never resumes (the client disconnected, the run failed mid-pause).
+
+  Ungated tools are untouched — the correlation is identity for a call no approval ever claims.
+
+- 4411a59: A web application can now render a human-in-the-loop approval prompt. `useAgent` returns
+  `pendingApprovals` — one entry per decision the run is parked on, carrying the `approvalId` that
+  `approve()` takes, the gated tool's name, the arguments it is about to run with, the question
+  declared on the gate, and the window before it settles itself.
+
+  Before this the hook exposed the settle half of the gate and no way to reach the other half. The
+  store dropped the `tool-approval-request` frame on the way in, so its whole snapshot while a human
+  was deciding was `messages`, `thread`, `status: 'streaming'` and `error` — and the paused tool sat in
+  `state: 'input-available'`, which is exactly what an ungated tool looks like while it runs. An
+  application could not tell "working" from "waiting for you", and could not have named the decision if
+  it could. The only path left was polling `GET /api/agents/<name>/approvals` out of band.
+
+  The transcript carries it too: the gated call's own part moves to `state: 'approval-requested'` with
+  the id under `approval.id` while the decision is outstanding, and leaves that state when it is
+  settled. That is the ai-sdk reader's own vocabulary, not a new one — the differential oracle compares
+  the two readers on the paused run and the denied run and they reconstruct identically.
+
+  What the gate is asking travels as a transient `data-approval` part rather than on the approval frame
+  itself. The frame is shared vocabulary and `ai`'s validator for it is strict: a `question` added
+  there would not give an ai-sdk client a poorer prompt, it would delete the whole approval frame for
+  that client and re-create this defect on the other side of the wire. The tool's name and its
+  resolved input are not repeated anywhere — the `tool-input-available` frame already announces both
+  under the same call id, and both readers fold the frames into one part.
+
+  `approve(approvalId, decision)` is unchanged; what changes is that the store now hands the id over.
+  A tool with no gate produces exactly the same frames and exactly the same snapshot as before, with
+  `pendingApprovals` empty.
+
+- 3126e58: A tool that failed reaches the caller as a tool that failed.
+
+  A tool whose handler threw — including one that threw on every attempt until its retries ran out —
+  crossed the wire as `tool-output-available`, the SUCCESS part of the UIMessage protocol, with the
+  error message sitting in the field a UI renders as the tool's answer, on a run that terminated with
+  an ordinary `done`. Nothing on the wire told a failed call from a call that worked, so a consumer
+  watching for a failure never fired, and a UI printed the failure as the result.
+
+  The failure signal was in hand the whole time. `@theokit/sdk` catches whatever a handler throws and
+  reports the call with `{stdout, stderr, exitCode}` — a non-zero code for a throw, a hook block, a
+  human denial, a timeout or an unknown tool — under `status: 'completed'`, which is the SDK's word
+  for "the call is over", not for "the call worked". Both translation sites read the status and
+  hardcoded `isError: false`, and the timeline dedup then dropped the only report carrying the exit
+  code as a duplicate of the report that structurally cannot carry one: the completion delta's payload
+  is a rendered string, and the message carrying the code always arrives second.
+
+  The exit code now travels. A failed call reaches the wire as `tool-output-error` with the message in
+  `errorText` — the presenter branch that emits it already existed and was never reachable from a
+  served run. A completion is held for one report rather than emitted immediately, so the second report
+  can contribute its exit code to the first instead of being discarded; exactly one result per call
+  still reaches the wire, and one that ends the run is flushed rather than held forever.
+
+  A call that succeeded is unchanged, chunk for chunk: it emits `tool-output-available` with the same
+  rendered output, under the same id, exactly once. A completion nobody reported an exit code for is
+  not called a failure — the `[stderr]` prefix in the rendered text is a string convention, and
+  classifying failures by matching error text is a mistake this codebase has already paid for once.
+
+- Updated dependencies [bbdfc15]
+- Updated dependencies [4411a59]
+  - @theokit/presenter@0.8.0
+
 ## 10.1.0
 
 ### Minor Changes

package/LICENSE

@@ -137,8 +137,8 @@
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each

package/README.md

@@ -14,7 +14,7 @@ there is state or orchestration to hold, and forwarding the rest unchanged.
 > **Enriching never reduces.** A symbol the SDK exposes and this layer does not forward is
 > unreachable to whoever consumes the layer — and the only legal way out for them is to reimplement
 > it. That happened: when `./auth` exported one value against the SDK's nineteen, a downstream
-> product rewrote ~120 lines of credential mechanics. `scripts/check-surface-parity.mjs` in the
+> product rewrote ~120 lines of credential mechanics in the
 > repository root now requires a written decision per SDK symbol, so the next gap breaks CI instead
 > of quietly costing someone a week.
 
@@ -29,11 +29,11 @@ you mount HTTP surfaces).
 
 ## Subpath map
 
-Nineteen entry points. Import the one you need — the barrel is not the API.
+Twenty entry points. Import the one you need — the barrel is not the API.
 
 | Subpath | What lives there |
 |---|---|
-| `.` | The fluent `agent()` / `tool()` builders, the error hierarchy, shared types |
+| `.` | `AgentBuilder.create()` — the authoring surface — plus the error hierarchy and shared types |
 | `./bridge` | The SDK seam — `createSdkAgentStream`, event translation, the agent builder internals |
 | `./testing` | Test seams: compiled-agent inspection, mock streams |
 | `./sandbox` | Sandbox backends, postures, `sandboxWritePolicy` |
@@ -41,6 +41,7 @@ Nineteen entry points. Import the one you need — the barrel is not the API.
 | `./interactive` | The interactive-shell backend contract |
 | `./pty` | The node-pty implementation of that contract |
 | `./auth` | Credential store, OAuth/device flow, `resolveCredential`, `assertSecureModes` |
+| `./config` | Agent configuration, trust posture, and the instruction tree (`loadInstructionTree`) |
 | `./tools` | Built-in tool factories (read, list, grep, git, patch, edit, shell, …) |
 | `./client` | Transports for driving an agent from a client |
 | `./client/react` | `useAgent` and the React bindings |
@@ -78,8 +79,8 @@ data, and a user cannot tell an explicit choice from a precedence fallback.
 See [`CHANGELOG.md`](./CHANGELOG.md) — shipped inside this package, so `node_modules` answers the
 question without a round trip to the repository.
 
-For "which symbol delivers capability X, and in which version did it land", the repository publishes
-a capability index at `wiki/capability-index.md`.
+For "which symbol delivers capability X, and in which version did it land", the CHANGELOG entry that
+shipped the symbol is the answer — every entry names the version it landed in.
 
 ## Boundaries this package keeps
 

package/dist/{agent-compiler-CIPQkehU.d.ts → agent-compiler-tetgj6zR.d.ts}

@@ -1,175 +1,6 @@
-import { McpServerConfig, SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings } from '@theokit/sdk';
+import { InlineSkill, SystemPromptResolver, SettingSource, MemorySettings, SkillsSettings, ContextSettings } from '@theokit/sdk';
 import { TheokitAgentError } from '@theokit/sdk/errors';
-import { z } from 'zod';
-
-/**
- * Provider-agnostic extended-thinking knob (M1 reasoning-visibility). The common set autocompletes;
- * `(string & {})` accepts provider-specific values forward-compat (mirrors `AgentRunErrorCode`) — the
- * SDK validates the value against the model's catalog. Defined in this leaf module so every layer
- * (`@Agent` config, compiler, runner, sdk-adapter) imports it without an import cycle.
- */
-type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | (string & {});
-/** Scalar agent configuration. */
-interface AgentOptions {
-    /** Unique agent name (kebab-case). */
-    name: string;
-    /** HTTP route prefix (e.g., '/api/agents/support'). */
-    route: string;
-    /** LLM model identifier (e.g., 'claude-sonnet-4-5-20250929'). */
-    model?: string;
-    /** Extended-thinking effort; mapped to the SDK `ModelSelection.params` so the provider reasons. */
-    reasoningEffort?: ReasoningEffort;
-    /**
-     * Opt-in (default false): convert inline `<think>…</think>` in the text stream into `thinking`
-     * events (M2) — for models that emit reasoning as inline tags (qwen/deepseek) rather than via a
-     * native reasoning param. Off by default since a code assistant may emit literal `<think>` in text.
-     */
-    parseThinkTags?: boolean;
-    /**
-     * Opt-in (default false): strip a leaked Hermes `<function=…></tool_call>` tool-call dialect out of
-     * the visible text (theocode#32) — for models (qwen/qwen3-coder) that intermittently emit tool calls
-     * as text instead of native `tool_calls`. Off by default since a code assistant may emit a literal
-     * `<function=` in answer/code text. Sibling of {@link parseThinkTags}.
-     */
-    stripToolDialect?: boolean;
-    /**
-     * Opt-in (default false): recover a leaked Hermes `<function=…></tool_call>` tool-call dialect so the
-     * call actually EXECUTES (theokit#58 follow-up). Where {@link stripToolDialect} only hides the leaked
-     * block from the visible text, this enables the SDK's `extractToolCallsFromContent` on the chat route,
-     * so a `chat_completions` finish with ZERO native `tool_calls` has its text scanned for the dialect and
-     * any recovered calls are dispatched by the loop. For models (qwen/qwen3-coder via OpenRouter) that
-     * leak tool calls as text. Off by default (a code assistant may print a literal `<function=`); fail-open.
-     * Has effect only when {@link AgentOptions} routes a provider via `providers.routes`. Sibling of
-     * {@link stripToolDialect} — typically enabled together.
-     */
-    recoverLeakedToolCalls?: boolean;
-    /** Enable SSE streaming (default: true). */
-    stream?: boolean;
-    /** Maximum loop iterations before forcing a terminal response. */
-    maxIterations?: number;
-    /** Timeout in milliseconds for the entire agent run. */
-    timeoutMs?: number;
-    /**
-     * System prompt for the agent. Either a static string OR a
-     * {@link SystemPromptResolver} computed per request (V4-L.1, Axis-B) — the SDK
-     * invokes the resolver each send with the run's `SystemPromptContext` (cwd, etc.).
-     */
-    systemPrompt?: string | SystemPromptResolver;
-}
-/** Configuration stored by @MainLoop() decorator. */
-interface MainLoopOptions {
-    /** Execution strategy. */
-    strategy?: 'simple-chat' | 'plan-act-reflect' | 'react';
-    /** Maximum iterations for this loop. */
-    maxIterations?: number;
-    /** Timeout in milliseconds. */
-    timeoutMs?: number;
-}
-/** Internal representation of a resolved @MainLoop. */
-interface MainLoopMeta {
-    propertyKey: string | symbol;
-    strategy: 'simple-chat' | 'plan-act-reflect' | 'react';
-    maxIterations?: number;
-    timeoutMs?: number;
-}
-/** Configuration stored by @Toolbox() decorator. */
-interface ToolboxOptions {
-    /** Namespace prefix for all tools in this toolbox (e.g., 'support'). */
-    namespace?: string;
-}
-/** Configuration stored by @Tool() decorator. */
-interface ToolOptions {
-    /** Tool name (surfaced to LLM). */
-    name: string;
-    /** LLM-facing description. */
-    description: string;
-    /** Zod input schema — compiled to JSON Schema via defineTool(). */
-    input: z.ZodType;
-    /** Risk level (informational — feeds manifest + UI). */
-    risk?: 'low' | 'medium' | 'high';
-}
-/** Budget configuration for @Budget() decorator. */
-interface BudgetOptions {
-    /** Maximum cost in USD for this scope. */
-    maxCostUsd: number;
-    /** Rolling window for budget tracking. */
-    window?: 'daily' | 'monthly';
-}
-/** Approval configuration for @RequiresApproval() decorator. */
-interface ApprovalOptions {
-    /** Reason shown to the approver. */
-    reason: string;
-}
-/** Policy handler function type. */
-type PolicyHandler = (user: {
-    roles: string[];
-}) => boolean;
-/**
- * M53 — moved here from the `@HumanInTheLoop` decorator, which is being deleted: the type is
- * consumed by `compileHitlGates` and the toolbox capability, not by the decorator alone.
- */
-type TimeoutAction = 'abort' | 'proceed' | 'retry';
-interface HumanInTheLoopOptions {
-    /** Question shown to the human approver. */
-    question: string;
-    /** Timeout in milliseconds before onTimeout fires (default: 300_000 = 5 min). */
-    timeout?: number;
-    /** Action when timeout expires (default: 'abort'). */
-    onTimeout?: TimeoutAction;
-    /** Show the tool input to the approver (default: true). */
-    showInput?: boolean;
-    /**
-     * M20 — an optional JSON-schema descriptor of the custom payload the approver may attach (edited
-     * args, a review note). Carried into the `approval_required` event + `GET /approvals` so the UI
-     * knows what to collect. A plain JSON object, not a live Zod schema (keeps the wire serializable).
-     */
-    payloadSchema?: Record<string, unknown>;
-}
-
-type McpServersMap = Record<string, McpServerConfig>;
-/** M53 — moved from the `@ProjectContext` decorator being deleted; read by the compiler. */
-type IndexStrategy = 'tree-sitter' | 'regex' | 'none';
-type RelevanceStrategy = 'git-history' | 'import-graph' | 'semantic' | 'manual';
-interface ProjectContextOptions {
-    /** Files that mark the project root (searched upward from cwd). */
-    rootMarkers?: string[];
-    /** How to index the codebase for structural understanding. */
-    indexStrategy?: IndexStrategy;
-    /** Maximum files to include in context per request. */
-    maxFilesInContext?: number;
-    /** How to rank file relevance when selecting context. */
-    relevanceStrategy?: RelevanceStrategy;
-    /** Glob patterns to exclude from indexing and context. */
-    ignorePatterns?: string[];
-    /** File extensions to include in indexing (default: all text files). */
-    includeExtensions?: string[];
-}
-type CheckpointStrategy = 'after-tool-call' | 'after-iteration' | 'manual';
-type CheckpointStorage = 'memory' | 'filesystem' | 'drizzle' | 'redis';
-interface CheckpointOptions {
-    /** Where to persist checkpoints. */
-    storage?: CheckpointStorage;
-    /** When to auto-checkpoint (default: 'after-tool-call'). */
-    strategy?: CheckpointStrategy;
-    /** Maximum checkpoints to retain per run (rolling window). */
-    maxCheckpoints?: number;
-    /** Time-to-live in ms before checkpoints expire (default: 3_600_000 = 1h). */
-    ttl?: number;
-}
-type MemoryProvider = 'built-in' | 'honcho' | 'supermemory' | 'mem0';
-type MemoryScope = 'per-user' | 'per-agent' | 'per-tenant' | 'global';
-interface MemoryOptions {
-    /** Memory provider backend. */
-    provider?: MemoryProvider;
-    /** Enable semantic search via embeddings. */
-    embeddings?: boolean;
-    /** Enable full-text search (FTS5). */
-    fts?: boolean;
-    /** Memory isolation scope (default: 'per-user'). */
-    scope?: MemoryScope;
-    /** Maximum facts to retain per scope (0 = unlimited). */
-    maxFacts?: number;
-}
+import { R as ReasoningEffort, a as MemoryOptions, P as ProjectContextOptions, M as McpServersMap, H as HumanInTheLoopOptions, C as CheckpointOptions, T as ToolOptions, A as ApprovalOptions, B as BudgetOptions } from './types-C16Wuh9E.js';
 
 /**
  * M9 (theokit-ai-first) — guardrail contract + typed errors.
@@ -400,4 +231,4 @@ interface CompiledAgentOptions {
     skillsResolver?: SkillsSelection;
 }
 
-export { type ApprovalOptions as A, type BudgetOptions as B, type CompiledAgentOptions as C, type Guardrail as G, type HumanInTheLoopOptions as H, type McpServersMap as M, type PolicyHandler as P, type ReasoningEffort as R, type SkillsSelection as S, type ToolOptions as T, type MainLoopMeta as a, type CompiledTool as b, type AgentOptions as c, CostBudgetExceededError as d, type GuardrailAction as e, type GuardrailPhase as f, type GuardrailResult as g, GuardrailViolationError as h, type MainLoopOptions as i, type SkillsRequestContext as j, type TimeoutAction as k, type ToolWalkResult as l, type ToolboxOptions as m, type ToolboxWalkResult as n, compileTools as o, type ProjectContextOptions as p, resolveEnabledSkills as r };
+export { type CompiledAgentOptions as C, type Guardrail as G, type SkillsSelection as S, type ToolWalkResult as T, type CompiledTool as a, CostBudgetExceededError as b, type GuardrailAction as c, type GuardrailPhase as d, type GuardrailResult as e, GuardrailViolationError as f, type SkillsRequestContext as g, type ToolboxWalkResult as h, compileTools as i, resolveEnabledSkills as r };