@theokit/sdk-handoff 0.1.2 → 0.1.3

package/dist/handoff-D7malWe_.d.ts

@@ -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 };

package/dist/index.cjs

@@ -20,6 +20,17 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/internal/slugify-agent-name.ts
+function slugifyAgentName(candidate) {
+  return candidate.slice(0, MAX_INPUT_LENGTH).replace(/^agent-/i, "").replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64) || "anonymous";
+}
+var MAX_INPUT_LENGTH;
+var init_slugify_agent_name = __esm({
+  "src/internal/slugify-agent-name.ts"() {
+    MAX_INPUT_LENGTH = 1024;
+  }
+});
+
 // src/types/handoff.ts
 exports.HandoffLoopError = void 0; exports.HandoffPairLoopError = void 0; exports.HandoffSelfReferenceError = void 0; exports.HandoffReceiverDisposedError = void 0; exports.HandoffNameCollisionError = void 0;
 var init_handoff = __esm({
@@ -233,11 +244,15 @@ function extractUserText(content) {
   const text = content.filter((c) => c?.type === "text").map((c) => c.text).join("\n");
   return text.length > 0 ? text : void 0;
 }
+function userTextOf(entry) {
+  const m = entry;
+  if (m?.type === "user" && m.message?.role === "user") return extractUserText(m.message.content);
+  if (m?.role === "user") return extractUserText(m.content);
+  return void 0;
+}
 function extractLastUserMessage(history, senderAgentId) {
   for (let i = history.messages.length - 1; i >= 0; i -= 1) {
-    const m = history.messages[i];
-    if (m?.type !== "user" || m.message?.role !== "user") continue;
-    const text = extractUserText(m.message.content);
+    const text = userTextOf(history.messages[i]);
     if (text !== void 0) return text;
   }
   return `(Handoff from ${senderAgentId} \u2014 no prior user message in history.)`;
@@ -270,7 +285,11 @@ async function dispatchHandoff(args) {
     toolName: descriptor.resolvedToolName
   });
   try {
-    const run = await receiver.send(lastUserMessage);
+    const toolAllowlist = descriptor.options.tools;
+    const run = await receiver.send(
+      lastUserMessage,
+      toolAllowlist !== void 0 ? { activeTools: [...toolAllowlist] } : {}
+    );
     const result = await run.wait();
     const reply = buildReply(result, receiver.agentId);
     return {
@@ -349,10 +368,7 @@ function autoWrap(agent) {
 }
 function resolveTargetName(agent) {
   const candidate = agent.name ?? agent.agentId ?? "anonymous";
-  return slugify(candidate);
-}
-function slugify(input) {
-  return input.replace(/^agent-/i, "").replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64) || "anonymous";
+  return slugifyAgentName(candidate);
 }
 function buildHandoffTool(parentAgentId, descriptor, maxHandoffDepth) {
   const description = descriptor.options.toolDescription ?? `Transfer the conversation to the ${descriptor.target.agentId} agent. Use this when the user's request matches their specialty.`;
@@ -364,7 +380,7 @@ function buildHandoffTool(parentAgentId, descriptor, maxHandoffDepth) {
     name: descriptor.resolvedToolName,
     description,
     inputSchema,
-    handler: async (input) => {
+    handler: async (input, ctx) => {
       const chainState = createChainState(parentAgentId, maxHandoffDepth);
       try {
         const { reply, result } = await dispatchHandoff({
@@ -372,8 +388,12 @@ function buildHandoffTool(parentAgentId, descriptor, maxHandoffDepth) {
           senderAgentId: parentAgentId,
           chainState,
           rawInputJson: input,
-          history: { messages: [] }
-          // v1: history replay deferred
+          // #354 — the supervisor's transcript, which the SDK hands every tool handler as
+          // `ctx.messages`. This used to be `{ messages: [] }` with the note "v1: history replay
+          // deferred", so the dispatcher found no user message and sent the receiver the
+          // placeholder instead of the question — and `inputFilter`, the documented redaction
+          // hook, was handed an empty transcript to redact.
+          history: { messages: ctx?.messages ?? [] }
         });
         return JSON.stringify({
           ok: true,
@@ -396,9 +416,13 @@ var init_tool_injector = __esm({
     init_handoff();
     init_dispatcher();
     init_registry();
+    init_slugify_agent_name();
     init_to_json_schema();
   }
 });
+
+// src/handoff.ts
+init_slugify_agent_name();
 var RECOMMENDED_HANDOFF_PROMPT_PREFIX = `
 You can transfer the conversation to other specialist agents when their
 expertise matches the user's request. Invoke the appropriate
@@ -409,19 +433,39 @@ var Handoff = class {
   constructor() {
   }
   /**
-   * Build a `HandoffDescriptor` for a target agent. Wrap with custom options
-   * (filter / inputType / callback / whitelist / etc); pass to
-   * `Agent.create({ handoffs: [...] })`.
+   * Describe one handoff target. Pass the result inside `Handoff.asPlugin({ targets })` or
+   * `Agent.create({ handoffs })`.
    *
-   * Raw `SDKAgent` instances in `handoffs[]` are auto-wrapped by the runtime
-   * — call `Handoff.create()` explicitly only when you need to customize.
+   * ```ts
+   * Handoff.create(billing, { toolName: "escalate_billing" })
+   * ```
+   *
+   * A bare `SDKAgent` in either array is auto-wrapped with empty options, so call this explicitly
+   * only to customise — see {@link HandoffOptions}, and note that `tools` there is currently
+   * ignored.
+   *
+   * The tool the model sees is named `transfer_to_<slug>`, where the slug comes from the target's
+   * `name` (falling back to its `agentId`, then to `"anonymous"`) with a leading `agent-` stripped,
+   * every run of characters OUTSIDE `[A-Za-z0-9_-]` folded to a single `_`, leading and trailing
+   * `_` trimmed, and a 64-char truncation. Hyphens and underscores are preserved, so `"billing EU"`
+   * and `"billing (EU)"` both become `billing_EU` while `"billing-EU"` stays distinct. Two targets
+   * whose names collapse to the same slug are NOT caught here — the collision is raised later, when
+   * the set is normalised.
+   *
+   * Throws `ConfigurationError` with `code: "handoff_target_required"` for a null/undefined target,
+   * and `code: "handoff_target_invalid"` for anything without a `send` method. It validates the
+   * target only, never the options.
    */
   static create(target, options = {}) {
     if (target === void 0 || target === null) {
-      throw new Error("Handoff.create: target agent is required");
+      throw new sdk.ConfigurationError("Handoff.create: target agent is required", {
+        code: "handoff_target_required"
+      });
     }
     if (typeof target.send !== "function") {
-      throw new Error("Handoff.create: target must be an SDKAgent instance");
+      throw new sdk.ConfigurationError("Handoff.create: target must be an SDKAgent instance", {
+        code: "handoff_target_invalid"
+      });
     }
     const resolvedToolName = options.toolName ?? `transfer_to_${slugifyName(target)}`;
     return {
@@ -431,19 +475,47 @@ var Handoff = class {
     };
   }
   /**
-   * Plugin-based wiring (SDK 2.x preferred). Wraps `targets` in synthetic
-   * `transfer_to_<receiver>` tools and registers them via `ctx.registerTool`
-   * at agent init time.
+   * Expose each target as a `transfer_to_<receiver>` tool on the host agent — the SDK 2.x way to
+   * wire handoffs.
+   *
+   * ```ts
+   * const support = await Agent.create({
+   *   name: "support",
+   *   systemPrompt: `${RECOMMENDED_HANDOFF_PROMPT_PREFIX}\n\nYou answer support requests.`,
+   *   plugins: [Handoff.asPlugin({ parentAgentId: "support", targets: [billing] })],
+   * });
+   * ```
+   *
+   * Pass `parentAgentId` — it defaults to `"anonymous"`, and it is what self-reference detection
+   * and the chain trace compare against, so leaving it out weakens both. `maxHandoffDepth` defaults
+   * to 5.
+   *
+   * Four behaviours that are easy to be surprised by:
    *
-   * Replaces the legacy `Agent.create({ handoffs: [...] })` option (which is
-   * still supported as a transitional convenience while sdk-handoff is
-   * installed — the framework lazy-imports the tool-injector at runtime).
+   * - **`maxHandoffDepth: 0`, or an empty `targets`, registers NOTHING** and returns a plugin that
+   *   silently does nothing. There is no error and no warning; the model simply never sees a
+   *   transfer tool.
+   * - **Registration is awaited.** `register()` returns a promise that settles once the tools are
+   *   registered, and the plugin manager awaits it — so the transfer tools exist before the first
+   *   `send()`, and a failure in the lazy import or in target validation reaches the caller.
+   *   Before #355 it returned immediately and both of those were untrue.
+   * - **The receiver gets the user's LAST message, not the whole conversation.** The tool handler
+   *   forwards the supervisor's transcript, from which the dispatcher takes the most recent user
+   *   turn (#354 — before that it forwarded nothing, and the receiver was sent the literal string
+   *   `` `(Handoff from <sender> — no prior user message in history.)` ``). That placeholder is
+   *   still what a receiver gets when there genuinely is no prior user turn. Anything beyond the
+   *   last question has to be in the target's own system prompt, or you drive the handoff yourself
+   *   with {@link handoffTo}, which passes an explicit message through.
+   * - **The handoff tool never throws at the caller.** Every failure — loop detected, depth
+   *   exceeded, disposed receiver, `isEnabled` false, input that fails `inputType` — is caught
+   *   inside the tool handler and returned to the MODEL as
+   *   `{"ok":false,"error":"<ErrorName>","message":"…"}`. The exported error classes are real, but
+   *   in this wiring they never reach your `try`/`catch`; watch the tool results instead.
    *
-   * @example
-   *   const support = await Agent.create({
-   *     name: "support",
-   *     plugins: [Handoff.asPlugin({ parentAgentId: "support", targets: [billing] })],
-   *   });
+   * A self-referencing target and two targets resolving to the same tool name are both rejected —
+   * from `register`, which the plugin manager awaits — so `HandoffSelfReferenceError` and
+   * `HandoffNameCollisionError` reject the `Agent.create` you can `catch` around (#355; they used
+   * to arrive as an unhandled rejection instead, leaving an agent silently without handoff tools).
    */
   static asPlugin(opts) {
     const parent = opts.parentAgentId ?? "anonymous";
@@ -453,22 +525,29 @@ var Handoff = class {
       name: `handoff-${parent}`,
       version: "1.0.0",
       kind: "general",
-      register(ctx) {
+      // #355 — `async`, and the promise is RETURNED. The plugin contract types `register` as
+      // `(ctx) => void | Promise<void>` and the manager awaits it, so returning it is all this
+      // needed. It used to run an unawaited async IIFE and return immediately: the tools appeared a
+      // module-load later, so whether they existed for the first `send()` depended on timing no
+      // caller controls, and `normalizeHandoffs`' validation errors became unhandled rejections
+      // that could not be caught around `Agent.create`.
+      //
+      // The import stays lazy — deferring it until `register` runs is what keeps the cold path
+      // lean, and that never required leaving it unawaited INSIDE `register`.
+      async register(ctx) {
         if (maxDepth === 0 || targets.length === 0) return;
-        void (async () => {
-          const { normalizeHandoffs: normalizeHandoffs2, buildHandoffTool: buildHandoffTool2 } = await Promise.resolve().then(() => (init_tool_injector(), tool_injector_exports));
-          const normalized = normalizeHandoffs2(parent, targets);
-          for (const { descriptor } of normalized) {
-            ctx.registerTool(buildHandoffTool2(parent, descriptor, maxDepth));
-          }
-        })();
+        const { normalizeHandoffs: normalizeHandoffs2, buildHandoffTool: buildHandoffTool2 } = await Promise.resolve().then(() => (init_tool_injector(), tool_injector_exports));
+        const normalized = normalizeHandoffs2(parent, targets);
+        for (const { descriptor } of normalized) {
+          ctx.registerTool(buildHandoffTool2(parent, descriptor, maxDepth));
+        }
       }
     });
   }
 };
 function slugifyName(agent) {
   const candidate = agent.name ?? agent.agentId ?? "anonymous";
-  return candidate.replace(/^agent-/i, "").replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64) || "anonymous";
+  return slugifyAgentName(candidate);
 }
 async function handoffTo(sender, target, message, options = {}) {
   const descriptor = Handoff.create(target, options);