@theokit/sdk-handoff 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,273 @@
 # Changelog
 
+## 0.1.4
+
+### Patch Changes
+
+- 1a4bbcf: The declared `@theokit/sdk` peer ranges stop promising versions the packages do not compile against.
+
+  All three declared `>=4.0.0`. `4.0.1` is the lowest published version that range admits — what a
+  consumer pinning conservatively, or resolving under an older transitive constraint, lands on. npm
+  resolves the combination with no `ERESOLVE` and no peer warning, and the build then fails on
+  `TS2552: Cannot find name` and `TS2305: has no exported member`.
+
+  The floors were measured by bisecting the 116 stable 4.x releases with a real build as the oracle.
+  Each one has its immediately preceding version failing, so these are exact versions rather than
+  intervals:
+
+  | package                | floor      | evidence                        |
+  | ---------------------- | ---------- | ------------------------------- |
+  | `@theokit/sdk-budget`  | `>=4.54.0` | `4.53.1` fails, `4.54.0` passes |
+  | `@theokit/sdk-handoff` | `>=4.54.0` | `4.53.1` fails, `4.54.0` passes |
+  | `@theokit/sdk-memory`  | `>=4.53.1` | `4.53.0` fails, `4.53.1` passes |
+
+  `sdk-memory` sits one release below the other two: this is not one shared migration, it is three
+  packages that each drifted past their own declared floor.
+
+  The oracle deletes every `dist/` before building. Without that the build reads a sibling's output
+  compiled against a different version, which is how a package "passes" against an SDK missing its
+  symbols — the failure mode that made the earlier measurement disagree with CI
+  (usetheokit/theokit-sdk#423).
+
+## 0.1.3
+
+### Patch Changes
+
+- e3f2a82: Public-API documentation reviewed file by file, and corrected wherever it disagreed
+  with the code. The docblocks ship in the `.d.ts`, so these read as behaviour changes
+  in an editor even though no behaviour changed.
+
+  The corrections that change what a caller would do:
+
+  - **`sdk-cache` documented its own premise backwards.** The header example labelled a
+    semantic hit as if it avoided the provider call. `asPlugin()` returns the cached
+    answer as `recalledContext`, which the agent loop injects as a `<memory-context>`
+    block _before_ the prompt — the request still goes to the provider. The two modes
+    are now labelled separately, with a table saying which one short-circuits and which
+    one seeds.
+  - **`sdk-handoff`'s five error classes said "throw".** Under the plugin wiring the
+    handler never throws; every failure becomes a tool result `{"ok":false,…}` handed
+    back to the model. Each class now says where it is actually observable. The header
+    also told readers to `import { Handoff } from "@theokit/sdk"`, from which it was
+    extracted.
+  - **`sdk-budget`'s `charge()` claimed idempotency across concurrent calls.** The mutex
+    serialises, it does not deduplicate: two identical calls record twice. Related, and
+    newly documented: with `maxUsd` set, a model missing from the pricing table denies
+    every request rather than passing it — and the table matches by exact string, so
+    `"openai/gpt-4o"` does not match `"gpt-4o"`.
+  - **The three `memory-*` adapters advertised an env-var fallback they do not read**,
+    and their peer dependencies are required rather than optional. Their behavioural
+    differences are now stated where they break the "interchangeable adapter"
+    assumption — honcho ignores `k` and always throws on `delete`; mem0 recalls across
+    sessions by design; supermemory ignores `sessionId` entirely.
+  - **`sdk-memory`'s `truncated` flag was documented as its own inverse**, and its
+    dreaming sweep claimed a mutex it never takes against the writer it names.
+  - **`sdk-tools`** corrected `run_vitest`'s unreachable `no_vitest` code, `truncation`'s
+    replacement-character claim, and two return shapes missing a live error code.
+  - **`acp`/`cli`** corrected sixteen statements including a named error class that is
+    not the one raised, a handler documented as calling `fork()` that refuses
+    unconditionally, handlers described as pure that mint ids and mutate a store, a
+    config loader credited to Zod in a package that does not import it, and a `--force`
+    scaffold described as atomic that deletes the destination before the rename.
+
+  Undocumented public symbols were documented across every package, with each claim
+  checked against the implementation rather than inferred from the name.
+
+- e368fc1: Every published declaration file now compiles without `skipLibCheck` (#345). The
+  DTS rollup emitted symbols as a re-export from a chunk while omitting them from
+  that chunk's `import`, and dropped type-only imports from external packages —
+  leaving 51 unresolved references across ten of the twelve packages. Nothing broke
+  at runtime, and `tsc` stayed green for anyone with `skipLibCheck` on, but a
+  consumer running type-aware lint saw every type reached through one degrade to
+  `error`.
+
+  The declarations are repaired at build time from the compiler's own diagnostics.
+  No source or API change.
+
+- 5742ab2: `Handoff.asPlugin(...).register()` now returns a promise that settles once the transfer tools are
+  registered.
+
+  It used to start an unawaited async IIFE and return, so the tools appeared a module-load later —
+  whether they existed for the first `send()` depended on timing no caller controlled — and
+  `HandoffSelfReferenceError` / `HandoffNameCollisionError` became unhandled rejections that could not
+  be caught around `Agent.create`, leaving an agent silently without handoff tools. The plugin
+  contract already typed `register` as returning `void | Promise<void>` and the manager already
+  awaited it. The import stays lazy.
+
+- 33524a5: A handoff now tells the receiving agent what the user asked.
+
+  Both wirings built the transfer tool through a handler that dispatched with an empty transcript, so
+  the receiver was sent the literal string `(Handoff from <sender> — no prior user message in
+history.)` and answered from that plus its own system prompt. The handler now forwards the
+  supervisor's transcript, which the SDK hands every tool handler, and the dispatcher takes the last
+  user turn from it.
+
+  `HandoffOptions.inputFilter` was dead in the same way — invoked, always with nothing to filter, so a
+  caller who wired a redactor believed the transcript was being scrubbed. It now receives the real
+  transcript, and dropping a message there does keep it from the receiver.
+
+- 9f0362c: `Handoff.create()` refusals now carry an error class and a stable code.
+
+  Both of its guards raised a bare error, so a caller wanting to distinguish "no target given" from
+  "the target is not an agent" had only the message text to match on — and message text is not a
+  contract. It changes whenever someone improves the wording, and nothing tells the consumer their
+  check stopped working.
+
+  Each refusal is now a `ConfigurationError` with its own code. The change is additive rather than
+  breaking: the error class extends `Error`, so anything catching `Error` still catches it, and both
+  messages are unchanged.
+
+- 1484293: The schema converter that decides what a model is shown now has tests.
+
+  It converts a handoff's input schema into the JSON Schema the model receives, and it had no coverage
+  at all. A defect there is not a crash — the model is shown the wrong contract, then fails to satisfy
+  it for reasons no error message explains.
+
+  Eleven tests now pin the emitted schema rather than the fact that a call returned: the required and
+  optional split, nested objects and arrays, enums, the primitive type mapping, and both behaviours for
+  inputs JSON Schema cannot represent.
+
+  That last pair is the wrapper's actual reason to exist, and it was verified against the schema library
+  rather than taken from the comment describing it: by default an unrepresentable input degrades to an
+  empty schema instead of throwing, which is the opposite of what the underlying library does on its
+  own. Callers who ask for the strict behaviour still get the library's own error, message included.
+
+- c5e78c1: `HandoffOptions.tools` now restricts the receiving agent, as its name always implied.
+
+  Nothing in the package read it. A caller passing `{ tools: ["read_file"] }` — the option was
+  presented as an allowlist — got no restriction and no warning, which is worse than an absent option
+  because it gives false assurance. It is wired to `SendOptions.activeTools`, the same
+  `withToolWhitelist` path `Agent.fork`'s `allowedTools` uses: exact name matching, an empty list
+  means the empty set (fail-closed), and omitting the option imposes no restriction.
+
+  Local runtime only — a cloud agent ignores `activeTools`, and the docblock now says so.
+
+- aadc9dd: Seventeen more negative-case tests now identify which failure they caught, and a registry test suite
+  stops sleeping to make timestamps differ.
+
+  Most of those assertions turned out to be under-asserting rather than untestable: twelve of them sat
+  on errors that were **already typed**, and simply checked that something threw. They now name the
+  class, the stable code and a message fragment — which means a change that swaps one failure for
+  another is caught, where before any error at all satisfied the test.
+
+  Four remain matched on a message fragment because the underlying error genuinely has no type yet, and
+  one of those is filed separately: a public entry point throwing a plain error gives callers nothing to
+  branch on but a string that changes whenever someone improves the wording.
+
+  Four more were reclassified out of scope after reading the source rather than the name: they raise
+  errors owned by Node, by the schema library, or by a database driver, and pinning a third-party class
+  buys little.
+
+  Separately, the live-agent-registry tests slept thirteen times — some to force last-used timestamps
+  apart so eviction ordering could be asserted, others to let fire-and-forget cleanup finish. Both are
+  now driven by the test clock, a mechanism this same file already used elsewhere and which needed no
+  production change. The file runs in a fraction of the time and no longer depends on how busy the
+  machine is.
+
+- 3724b43: The rule that turns an agent's name into a tool-safe slug existed twice — once in `handoff.ts`,
+  once in `tool-injector.ts` — byte-identical apart from a parameter name, and covered by no test at
+  all. Two copies of one rule drift the moment either is adjusted, and nothing would have reported
+  it: a handoff tool named one way and a dispatcher expecting another.
+
+  It is now one function with tests describing the behaviour it already had: the `agent-` prefix
+  stripped case-insensitively, runs of unsafe characters collapsed to one underscore, underscores
+  trimmed from both ends, `"anonymous"` when nothing survives, and a 64-character cap. No result
+  changes.
+
+  The input is now bounded before the slug rules run. CodeQL flags one of those expressions as
+  polynomial backtracking; stated plainly, the quadratic cost **could not be reproduced** — V8
+  resolves 100,000 characters of the worst-case shape in under a millisecond. The bound is defence
+  in depth against an engine that does not optimise it, not a fix for a demonstrated exploit, and
+  nothing beyond the bound could have reached the 64-character result anyway.
+
+- e699569: **The repository moved to the official `usetheokit` organization.** Every `repository`, `bugs` and `homepage` field now points there, along with the README, `CONTRIBUTING.md`, `SECURITY.md` and the issue templates. Existing clones and any URL already published keep working — GitHub redirects a transferred repository permanently — so this is a correctness fix for the metadata npm renders, not a break.
+
+  **The Apache-2.0 text every package ships was replaced with the official one.** The copy distributed until now had paragraph 4(d) truncated: it read "except as required for describing the origin of the Work and reproducing the content of the NOTICE file", dropping "reasonable and customary use" from the licensed clause. §4(d) governs what a redistributor must do with attribution notices, and the omission narrowed it.
+
+  That matters more than a typo would. The manifests declare the SPDX identifier `Apache-2.0`, which is an assertion that the terms are _the_ Apache-2.0 terms — a licence scanner resolves the identifier and never reads the file. A consumer's compliance review, which does read the file, would find a body that no longer matches the identifier and has no name of its own. Every `LICENSE` in this repository is now byte-identical to the canonical text, with the appendix filled in.
+
+  Nothing else about the terms changed: the licence is the same licence it has always been meant to be, and no package changes what it grants.
+
+- e3f2a82: `@opentelemetry/api` is now declared as an optional peer dependency, so the spans these two
+  packages emit can actually reach a collector.
+
+  Both lazily `require("@opentelemetry/api")` from their own directory, but neither manifest
+  declared it in any dependency field. Under an isolated `node_modules` layout the specifier is
+  therefore not linked under the package, the require throws, the loader caches a `null` tracer,
+  and every span degrades to a no-op — silently, with no warning, unlike `@theokit/sdk`, which
+  prints one when telemetry is enabled and OTel is absent. For `sdk-cache` that covered both of
+  its main paths (`cache.lookup` on every send, `cache.store` on every reply), so an operator
+  reading a trace saw no cache activity at all and had no way to tell that from a cache that was
+  never consulted.
+
+  The declaration matches `@theokit/sdk`'s: `peerDependencies` plus `peerDependenciesMeta.optional`,
+  so nothing is installed for anyone who does not want OTel, and users who do want it get their
+  copy linked where the require can find it.
+
+- e3f2a82: Every symbol these packages declare in `exports` now reaches the `.d.ts` they publish.
+
+  Sixty-six declarations across twenty-three published files did not compile, and four entry
+  points silently omitted names their own barrel exports — `@theokit/sdk/internal/security`
+  dropped seven at once. Runtime was never affected; this is types-only. A consumer with
+  `skipLibCheck` on saw nothing, and a consumer running type-aware lint saw every type reached
+  through one of them degrade to `error`.
+
+  The cause was `stripInternal`, which deletes a declaration when the literal `@internal`
+  appears in ANY leading comment range of it. The tag was being used here to mean "outside the
+  semver contract" — `internal/persistence/sqlite-open.ts` said so in those words, on a subpath
+  the manifest publishes and a back-compat test pins. The compiler reads it as "erase this", and
+  the two meanings only diverge in the published artifact. It now says the semver exemption in
+  prose, and the tag is gone from the symbols that are published.
+
+  Two further mechanisms had the same cause and a wider blast radius. A tag in a BARREL header
+  deleted the first `export … from` beneath it; a tag in a MODULE header deleted the following
+  `import`, so `import { z } from "zod"` vanished and every type it bound became
+  `Cannot find name`. Nothing was added to any `exports` map and no `export` line changed — a
+  deleted import was never privacy, only a broken declaration.
+
+  `@theokit/sdk-handoff`'s `./internal` entry left `SDKAgent` and `CustomTool` unbound, from a
+  different defect: the declaration repair only ever looked at `exports["."]`, so it fixed each
+  package's main entry and shipped the rest unrepaired. It now covers every declared subpath, and
+  binds the side-effect import form (`import '@theokit/sdk';`) the rollup emits with the names
+  stripped out.
+
+  Three gates were widened or added so this cannot return silently: the declaration typecheck
+  now covers all 45 published entries rather than 12, a new export-parity check fails when a
+  source barrel exports a name the emit omits, and public-API documentation coverage is gated at
+  100%.
+
+  Two consequences worth naming rather than discovering. `coerceToKnownAgentRunErrorCode` — the
+  boundary helper the 4.x release notes point at as the migration path off the open
+  `AgentRunErrorCode` union — was tagged internal and therefore absent from the published types; it
+  is now exported and documented, which is a small addition to the public surface. And
+  `packages/sdk/typedoc.json` sets `excludeInternal: true`, so the generated API reference gains the
+  ~57 symbols whose tags were removed. That is the intended direction: those symbols are published,
+  and the reference now says so.
+
+- c7385d2: Test runs no longer claim every core on the host.
+
+  None of the package configs capped `maxWorkers`, so vitest's default applied: `os.availableParallelism()`,
+  one fork per core, each booting a full test environment. The repo's `test` script is
+  `turbo run test --filter='./packages/*'`, so that default is paid once per package _concurrently_ —
+  nproc forks times turbo's concurrency, on nproc cores. Measured on a 12-thread machine during an
+  unrelated investigation, two vitest pools alone were enough to reach load average 33.89 with the
+  desktop unusable; a full fan-out is several times that.
+
+  `@theokit/sdk` is the interesting case. B-104 recorded on 2026-08-19 that the `poolOptions.forks.*`
+  block was 100% dead in Vitest 4, deleted it, and noted that `fileParallelism: false` was forcing
+  `maxWorkers` to 1 unconditionally, so a fork-count knob could not act. B-059 then flipped
+  `fileParallelism` to `true` on 2026-08-20, which made the knob able to act again — and nothing
+  reintroduced one, so the package silently went back to the uncapped default. That comment has been
+  corrected along with the config; it claimed no knob existed, which is no longer true.
+
+  The cap leaves 4 cores free (`Math.max(2, cpus().length - 4)`), scaling with the runner rather than
+  hard-coding one machine's core count. It costs no wall-clock: measured in `theokit-ui`, the full
+  suite ran 73.96s at 4 workers against 74.36s at 12, so the parallelism above the cap was already
+  noise. Verified as resolved config rather than as file contents — `createVitest` reports
+  `maxWorkers: 8` on a 12-thread host, which is the formula, not the default.
+
+  This changes no published behaviour; it is test tooling only. Refs usetheokit/theokit-ui#51.
+
 ## 0.1.2
 
 ### Patch 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

@@ -91,6 +91,19 @@ const support = await Agent.create({
 
 See the monorepo `CHANGELOG.md` for the 1.x → 2.0 package-split migration notes.
 
+## API reference
+
+Every symbol this package exports, with the exact specifier to import it from, is in the generated
+capability map that ships inside `@theokit/sdk`:
+
+```
+node_modules/@theokit/sdk/docs/harness-capability-map.md   # symbol -> import specifier
+node_modules/@theokit/sdk/docs/error-codes.md              # every `code` an error can carry
+```
+
+Both are generated from the built type declarations, so they describe the version you installed
+rather than the version someone wrote a page about.
+
 ## License
 
 Apache-2.0.

package/dist/handoff-D7malWe_.d.cts

@@ -0,0 +1,255 @@
+import { SDKAgent } from '@theokit/sdk';
+import { ZodType } from 'zod';
+
+/**
+ * Type-leaf — `HandoffDescriptor` extracted as a generic over `TAgent` so
+ * neither `agent.ts` nor `handoff.ts` need to import the other for type
+ * resolution. Closes the audit's last LOW type-only cycle #4
+ * (`types/agent.ts ↔ types/handoff.ts`) per plan
+ * arch-review-fixes-2026-06-06 § Phase 4 / T4.1 follow-up.
+ *
+ * BREAKING (per user direction "sem retro compat"): `HandoffDescriptor`
+ * gained a second generic parameter `TAgent` for the target shape. Existing
+ * consumers using `HandoffDescriptor<MyInput>` now resolve to
+ * `HandoffDescriptor<MyInput, SDKAgent>` via the back-compat default in
+ * `handoff.ts`'s re-export.
+ *
+ * @public
+ */
+
+/**
+ * Read-only snapshot of a handoff about to happen, passed to `onHandoff` and `isEnabled`.
+ *
+ * @public
+ */
+interface HandoffContext {
+    /** The `parentAgentId` the wiring was built with — `"anonymous"` when it was left unset. */
+    readonly senderAgentId: string;
+    /** `agentId` of the target about to receive the conversation. */
+    readonly receiverAgentId: string;
+    /**
+     * Hops recorded so far in this dispatch. Because chain state is rebuilt per tool invocation, it
+     * is `1` for essentially every real handoff — it is not a running total across a `send()`.
+     */
+    readonly currentDepth: number;
+    /**
+     * Agent ids traversed, ending with the receiver this context describes. Same caveat as
+     * `currentDepth`: it covers this dispatch, not the whole conversation.
+     */
+    readonly chain: ReadonlyArray<string>;
+}
+/**
+ * The transcript wrapper passed to `inputFilter`. `messages` is widened to
+ * `unknown[]` so this type doesn't import from `messages.ts` (avoids cycle
+ * — implementations cast to `SDKMessage[]` internally).
+ *
+ * Always arrives EMPTY today — see {@link HandoffOptions.inputFilter}.
+ *
+ * @public
+ */
+interface HandoffHistory {
+    readonly messages: ReadonlyArray<unknown>;
+}
+/**
+ * Options accepted by `Handoff.create(target, opts?)`.
+ *
+ * @public
+ */
+interface HandoffOptions<TInput extends ZodType = ZodType> {
+    /**
+     * Name of the synthetic tool, replacing the derived `transfer_to_<slug>`.
+     *
+     * Taken verbatim — it is not validated against the provider's tool-name rules, and it is what the
+     * collision check compares, so two targets sharing an explicit name still collide.
+     */
+    readonly toolName?: string;
+    /**
+     * Description shown to the model, replacing the generic "Transfer the conversation to the
+     * `<agentId>` agent." This is the ONLY thing telling the model when to pick this target over its
+     * siblings, so a default description in a multi-target setup routes badly.
+     */
+    readonly toolDescription?: string;
+    /**
+     * Called after the input is parsed and BEFORE the receiver is invoked. `parsed` is whatever
+     * `inputType` produced, or `undefined` when no `inputType` was set.
+     *
+     * Awaited, and NOT isolated: throwing from here aborts the handoff, which is the supported way to
+     * veto one after inspecting the arguments. Use it for logging and audit; the transfer has not
+     * happened yet.
+     */
+    readonly onHandoff?: (ctx: HandoffContext, parsed: TInput extends ZodType ? unknown : undefined) => void | Promise<void>;
+    /**
+     * Zod schema for the arguments the model must supply, replacing the default
+     * `{ reason?: string }`. It becomes the tool's JSON Schema, so it is also how you ask the model
+     * for structured routing data.
+     *
+     * Parsed with `.parse()`, so a rejection aborts the handoff. Note the parsed value is used ONLY
+     * for `onHandoff` and for lifting a `reason` field into telemetry — it is NOT forwarded to the
+     * receiver, which sees only the message text.
+     */
+    readonly inputType?: TInput;
+    /**
+     * Hook to rewrite the transcript before the receiver sees it — the intended place for redaction.
+     *
+     * It receives the supervisor's transcript as the tool handler saw it, and the receiver is sent
+     * the last user turn SURVIVING this filter — so dropping a message here does keep it from the
+     * receiver. Until #354 both wirings passed `{ messages: [] }`, which made this hook a no-op that
+     * looked like redaction.
+     *
+     * Failures are swallowed: a throw falls back to the unfiltered history with one warning on
+     * stderr per process — so a broken redactor fails OPEN, not closed.
+     */
+    readonly inputFilter?: (history: HandoffHistory) => HandoffHistory | Promise<HandoffHistory>;
+    /**
+     * Restrict the receiving agent, for THIS handoff only, to the tools named here.
+     *
+     * Wired to `SendOptions.activeTools`: names match EXACTLY against the receiver's registered tool
+     * names, an empty list restricts to the empty set (fail-closed), and omitting the option imposes
+     * no restriction. It narrows what the receiver may call; it never grants a tool the receiver
+     * does not have.
+     *
+     * LOCAL RUNTIME ONLY — a cloud agent ignores `activeTools`, so this cannot restrict one. Before
+     * #356 nothing read this field at all, in either runtime.
+     */
+    readonly tools?: ReadonlyArray<string>;
+    /**
+     * Gate on this handoff, as a boolean or a predicate evaluated at dispatch time with the same
+     * `ctx` that `onHandoff` receives.
+     *
+     * `false` does NOT hide the tool from the model — the tool is still registered and still
+     * offered; the dispatch simply fails with `Handoff to <id> is disabled (isEnabled returned
+     * false)`, which the tool wiring hands back as a failed tool result. To remove a target from the
+     * model's view, leave it out of `targets`.
+     */
+    readonly isEnabled?: boolean | ((ctx: HandoffContext) => boolean | Promise<boolean>);
+}
+/**
+ * Public `Handoff` shape — what `Handoff.create()` returns. Read-only
+ * accessors only; behavior lives in the engine.
+ *
+ * Generic over `TAgent` so this leaf has no dependency on a concrete
+ * agent type. Consumers typically import the convenience alias
+ * `HandoffDescriptor<TInput>` from `@theokit/sdk` which fixes `TAgent`
+ * to `SDKAgent`.
+ *
+ * @public
+ */
+interface HandoffDescriptor$1<TInput extends ZodType = ZodType, TAgent = unknown> {
+    readonly target: TAgent;
+    readonly options: HandoffOptions<TInput>;
+    /** Resolved tool name (after applying toolName override or default `transfer_to_<receiver>`). */
+    readonly resolvedToolName: string;
+}
+
+/**
+ * Public types for `Agent.create({ handoffs })` + `Handoff.create()` +
+ * `Agent.handoffTo()` (Adoption Roadmap #4; ADRs D214-D229).
+ *
+ * Pattern: handoff-as-tool. Each handoff destination becomes a synthetic
+ * `transfer_to_<receiver>` function tool exposed to the LLM. Runtime
+ * intercepts the tool call and routes the next turn to the receiver.
+ *
+ * T4.1 follow-up (cycle #4 closed): `HandoffDescriptor` + its leaf-friendly
+ * sibling types now live in `./handoff-descriptor.ts` (generic over
+ * `TAgent`). This module re-exports the leaf types pinned to `SDKAgent`,
+ * keeps the runtime error classes, and removes the back-edge to `agent.ts`.
+ *
+ * @public
+ */
+
+/**
+ * What `Handoff.create` returns: a target plus its options plus the resolved tool name.
+ *
+ * Pinned to `SDKAgent` — the back-compat shape for callers who imported
+ * `import type { HandoffDescriptor } from "@theokit/sdk"` before the T4.1 follow-up. It is a plain
+ * data record: constructing one by hand works, and skips the target validation `Handoff.create`
+ * performs.
+ *
+ * @public
+ */
+type HandoffDescriptor<TInput extends ZodType = ZodType> = HandoffDescriptor$1<TInput, SDKAgent>;
+/**
+ * Thrown when a chain exceeds `maxHandoffDepth` (default 5). `depth` is the CAP that was exceeded,
+ * not the depth reached; `chain` is the full path of agent ids.
+ *
+ * Rare in practice: chain state is rebuilt per dispatch, so depth restarts at 1 on every tool call.
+ * Repeated ping-pong surfaces as {@link HandoffPairLoopError} instead. *
+ * WHERE YOU SEE IT: only when you drive a handoff yourself, via `handoffTo(...)`. In the
+ * tool-based wirings (`Handoff.asPlugin` / `Agent.create({ handoffs })`) the handler catches every
+ * error and hands the MODEL a `{"ok":false,"error":"<name>","message":"…"}` tool result, so this
+ * class is observable there only as that `error` string.
+ */
+declare class HandoffLoopError extends Error {
+    readonly name = "HandoffLoopError";
+    readonly depth: number;
+    readonly chain: ReadonlyArray<string>;
+    constructor(depth: number, chain: ReadonlyArray<string>);
+}
+/**
+ * Thrown when the same `sender -> receiver` pair fires twice inside one dispatch — the ping-pong
+ * guard, and the loop protection that actually fires in practice.
+ *
+ * A -> B -> A is allowed by this check (different pairs); a repeated A -> B is not. *
+ * WHERE YOU SEE IT: only when you drive a handoff yourself, via `handoffTo(...)`. In the
+ * tool-based wirings (`Handoff.asPlugin` / `Agent.create({ handoffs })`) the handler catches every
+ * error and hands the MODEL a `{"ok":false,"error":"<name>","message":"…"}` tool result, so this
+ * class is observable there only as that `error` string.
+ */
+declare class HandoffPairLoopError extends Error {
+    readonly name = "HandoffPairLoopError";
+    readonly senderAgentId: string;
+    readonly receiverAgentId: string;
+    constructor(senderAgentId: string, receiverAgentId: string);
+}
+/**
+ * Thrown when a target's `agentId` equals the parent's — self-handoff, which recurses forever.
+ *
+ * Compared against `parentAgentId` as a STRING, which defaults to `"anonymous"` in
+ * `Handoff.asPlugin`: leave it unset and a genuine self-reference goes undetected.
+ *
+ * Raised while the target list is normalised, which in `Handoff.asPlugin` happens inside an
+ * unawaited async registration — it arrives as an unhandled rejection there, not as a throw from
+ * `Agent.create`.
+ */
+declare class HandoffSelfReferenceError extends Error {
+    readonly name = "HandoffSelfReferenceError";
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+/**
+ * Thrown when the target agent was disposed before the handoff reached it — detected at dispatch
+ * time, since nothing unregisters the tool when an agent is disposed.
+ *
+ * Typical cause: the receiver was created in a narrower scope than the sender and cleaned up first. *
+ * WHERE YOU SEE IT: only when you drive a handoff yourself, via `handoffTo(...)`. In the
+ * tool-based wirings (`Handoff.asPlugin` / `Agent.create({ handoffs })`) the handler catches every
+ * error and hands the MODEL a `{"ok":false,"error":"<name>","message":"…"}` tool result, so this
+ * class is observable there only as that `error` string.
+ */
+declare class HandoffReceiverDisposedError extends Error {
+    readonly name = "HandoffReceiverDisposedError";
+    readonly receiverAgentId: string;
+    constructor(receiverAgentId: string);
+}
+/**
+ * Thrown when two targets of the same parent resolve to the same `transfer_to_*` name — the model
+ * would have no way to pick between them.
+ *
+ * Easy to hit without duplicate agents, but not in the way the folding rule suggests: `-` and `_`
+ * SURVIVE the slug, and only runs of other characters fold to a single `_`, which is then trimmed
+ * at both ends. So `"billing EU"`, `"billing_EU"`, `"billing.EU"` and `"billing (EU)"` all resolve
+ * to `transfer_to_billing_EU` and collide — the last one because the `_` left by the closing paren
+ * is trimmed off the end. `"billing-EU"` keeps its hyphen, resolves to `transfer_to_billing-EU`,
+ * and collides with none of them. Set `toolName` on one of the colliding pair.
+ *
+ * Raised while the target list is normalised, which in `Handoff.asPlugin` happens inside an
+ * unawaited async registration — it arrives as an unhandled rejection there, not as a throw from
+ * `Agent.create`.
+ */
+declare class HandoffNameCollisionError extends Error {
+    readonly name = "HandoffNameCollisionError";
+    readonly conflictingName: string;
+    constructor(conflictingName: string);
+}
+
+export { type HandoffDescriptor as H, type HandoffOptions as a, HandoffLoopError as b, HandoffNameCollisionError as c, HandoffPairLoopError as d, HandoffReceiverDisposedError as e, HandoffSelfReferenceError as f };