@msm-core/mini 0.8.0 → 0.14.0

package/dist/definition/skills.js

@@ -0,0 +1,119 @@
+/**
+ * Skills — reusable instruction packs an agent loads, "files all the way down."
+ *
+ * Drop markdown into a folder and each file becomes part of the agent's
+ * definition, so the model gains that know-how with no rebuild and no code
+ * change. Two shapes are read, and they are the shapes Claude-style skill packs
+ * already use:
+ *
+ *   skills/
+ *     summarizing/SKILL.md      ← a folder pack
+ *     tone-of-voice.md          ← a single-file skill
+ *
+ * `loadSkills(dir)` returns ONE markdown block (`## Skills`), or `""` when
+ * there is nothing to load. **Composition stays with the host**: this module
+ * reads files and concatenates them; appending the block to a definition is the
+ * caller's line of code. The loop is not involved and does not know skills
+ * exist — `parseDefinition` has always *stripped* a `## Skills` section as
+ * "owned by the app layer", and that stays true.
+ *
+ * ── Lifted from `nisus/runtime/skills/loader.ts`, hardened where it mattered ──
+ *
+ * The pattern was right, so it was carried over rather than reinvented. Three
+ * things changed, each for a failure mode, and each pinned by a guard in
+ * `tests/skills.test.ts` — including a differential test against a verbatim
+ * transcription of the original, so any divergence beyond these is a bug:
+ *
+ *   1. **The order is deterministic.** The original iterated `readdirSync`
+ *      directly, and that order is filesystem- and platform-dependent (APFS
+ *      hands back roughly hash order; ext4 differs again). Two machines with
+ *      the same two skills therefore built two different definitions — the same
+ *      agent with two fingerprints, which is the enemy of replay
+ *      (`@msm-core/replay` fingerprints `system_context`) and of any diff a
+ *      human tries to read. Entries are now sorted by code unit before they are
+ *      read. **Not** `localeCompare`: that depends on ICU data and the ambient
+ *      locale, which would reintroduce exactly the nondeterminism being
+ *      removed.
+ *
+ *   2. **Diagnostics go to an injected port, never to `console`.** Same reason
+ *      as `@msm-core/mcp`'s `McpLogPort`: a library that prints is a library you
+ *      cannot embed. Absent a port, the loader is silent.
+ *
+ *   3. **An empty skill file contributes nothing instead of a bare separator.**
+ *      The original pushed `readFileSync(...).trim()` unconditionally, so an
+ *      empty (or whitespace-only) `.md` injected `"\n\n---\n\n\n\n---\n\n"`
+ *      into the text the model reads — a horizontal rule with no section under
+ *      it, mid-definition. It is now skipped, with a warning naming the file,
+ *      because a file someone left empty is a mistake worth hearing about.
+ *
+ * What deliberately did NOT change: a folder without a `SKILL.md` is skipped in
+ * silence (it is a plain folder, not a failure); a non-`.md` file is ignored;
+ * an entry that throws is reported and its siblings still load; and a folder
+ * pack and a single-file skill sitting side by side are BOTH read — the folder
+ * from its `SKILL.md`, the file from itself. That last one is the precedence
+ * rule, and it is a rule rather than an accident because a guard says so.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+/** The pack marker inside a skill folder. */
+const PACK_FILE = "SKILL.md";
+/** The heading the block is published under. */
+const BLOCK_HEADING = "## Skills";
+/** What sits between two skills inside the block. */
+const SEPARATOR = "\n\n---\n\n";
+/**
+ * Code-unit order: total, locale-independent, and identical on every platform.
+ * `Array.prototype.sort()`'s default is also code-unit order, but it gets there
+ * by stringifying — spelling it out states the intent that the guard tests.
+ */
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Read every skill under `dir` and return them as one markdown block, or `""`
+ * when the directory is missing, is not a directory, or holds no skills.
+ *
+ * Never throws for a skill it cannot read: the failure is reported on `log` and
+ * the remaining skills still load. A definition missing one section is worth
+ * more than an agent that will not start.
+ */
+export function loadSkills(dir, log = {}) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return "";
+    // Sorted BEFORE anything is read: the order of this array is the order of the
+    // block, and the block is part of what the model is asked.
+    const entries = [...readdirSync(dir)].sort(byCodeUnit);
+    const parts = [];
+    for (const entry of entries) {
+        const path = join(dir, entry);
+        let text;
+        try {
+            const stat = statSync(path);
+            if (stat.isDirectory()) {
+                const pack = join(path, PACK_FILE);
+                if (!existsSync(pack))
+                    continue; // a plain folder, not a skill pack
+                text = readFileSync(pack, "utf-8").trim();
+            }
+            else if (extname(entry).toLowerCase() === ".md") {
+                text = readFileSync(path, "utf-8").trim();
+            }
+            else {
+                continue; // not a skill in either shape
+            }
+        }
+        catch (err) {
+            log.warn?.(`[skills] failed to load ${entry}: ${err.message}`);
+            continue; // one unreadable skill must not cost the others
+        }
+        if (text === "") {
+            log.warn?.(`[skills] skipped empty "${entry}"`);
+            continue;
+        }
+        parts.push(text);
+        log.info?.(`[skills] loaded "${entry}"`);
+    }
+    if (parts.length === 0)
+        return "";
+    return `${BLOCK_HEADING}\n\n${parts.join(SEPARATOR)}`;
+}

package/dist/index.d.ts

@@ -15,8 +15,14 @@ export { createAnthropicBrain } from "./brain/anthropic.js";
 export { createOllamaBrain } from "./brain/ollama.js";
 export { buildBrain } from "./brain/factory.js";
 export { parseDefinition } from "./definition/parser.js";
-export type { Agent, AgentConfig, AgentEvent, AgentContext, AgentDefinition, AgentHooks, BeforeToolHookResult, Brain, BrainChunk, BrainOrchestration, BrainPayload, BrainRunInput, BrainToolCall, ChunkInfo, CompactionDecision, CompactionPort, DocumentState, GateConfig, GuardConfig, GuardSignal, GuardSignalType, IterationInfo, LoopOutcome, MemoryEntry, Message, OutcomeType, OutputValidation, OutputValidator, RedisConfig, RunState, SectionInfo, SessionMetadata, SessionStore, TenantContext, Tool, ToolCallInfo, ToolDefinition, ToolMeta, ToolParameter, ToolResult, } from "./core/types.js";
+export { loadSkills } from "./definition/skills.js";
+export type { SkillsLogPort } from "./definition/skills.js";
+export { createDelegateTool, DELEGATE_TOOL_NAME } from "./tools/delegate.js";
+export type { DelegateTool, DelegateToolOptions } from "./tools/delegate.js";
+export type { Agent, AgentConfig, AgentEvent, AgentContext, AgentDefinition, AgentHooks, BeforeToolHookResult, Brain, BrainChunk, BrainOrchestration, BrainPayload, BrainRunInput, BrainToolCall, ChunkInfo, CompactionDecision, CompactionPort, ControlBusPort, DedupPort, DocumentState, GateConfig, GuardConfig, GuardSignal, GuardSignalType, IterationInfo, LockHandle, LoopOutcome, MemoryEntry, Message, OutcomeType, OutputValidation, OutputValidator, RedisConfig, ResetAwareChunkHook, ResetAwareChunkSink, RunLockPort, RunState, SectionInfo, SessionMetadata, SessionStore, TenantContext, Tool, ToolCallInfo, ToolDefinition, ToolMeta, ToolParameter, ToolResult, } from "./core/types.js";
 export type { ContextBudget } from "./core/context-builder.js";
+export { acceptResets, isResetAware, acceptChunkResets, isResetAwareHook, } from "./core/types.js";
+export { respondingModel } from "./core/types.js";
 export { resolveGuards, DEFAULT_GUARDS } from "./core/guards.js";
 export { scoreOutcome } from "./quality/scorer.js";
 export type { QualityScore, QualityFlag } from "./quality/scorer.js";

package/dist/index.js

@@ -18,6 +18,36 @@ export { createOllamaBrain } from "./brain/ollama.js";
 export { buildBrain } from "./brain/factory.js";
 // ── Definition parser ───────────────────────────────────────────────────────
 export { parseDefinition } from "./definition/parser.js";
+// ── Skills (م١) — instruction packs read from disk, composed by the host ─────
+//
+// `loadSkills(dir)` returns one `## Skills` markdown block; appending it to a
+// definition is the composition root's line of code, not the loop's.
+export { loadSkills } from "./definition/skills.js";
+// ── Delegation (ر٢) — one agent asks another, as an ordinary tool ───────────
+export { createDelegateTool, DELEGATE_TOOL_NAME } from "./tools/delegate.js";
+// ── Streaming: opting in to a reset (ص٢/٢ · ص٣/٢) ───────────────────────────
+//
+// Two doors onto the same opt-in, one per altitude.
+//
+//   • A consumer that drives a brain DIRECTLY wraps its chunk sink in
+//     `acceptResets` (ص٢/٢) and stops losing the tail of a retried answer.
+//   • A consumer that runs an AGENT wraps its `AgentHooks.onChunk` in
+//     `acceptChunkResets` (ص٣/٢), and the loop declares to the brain on its
+//     behalf; `ChunkInfo.reset` then arrives on the first chunk of a retried
+//     attempt. This is the door most people want — `onChunk` is where an SSE
+//     channel is actually wired.
+//
+// Without a wrapper nothing changes anywhere: no reset is produced, and the
+// object delivered to `onChunk` keeps the exact three keys it has always had.
+export { acceptResets, isResetAware, acceptChunkResets, isResetAwareHook, } from "./core/types.js";
+// ── Who answered (س٦/٤) ─────────────────────────────────────────────────────
+//
+// The reading the four bundled brains use to fill `BrainPayload.model` from
+// their provider's reply — exported so a custom brain fills it the same way
+// instead of inventing a second reading that drifts. Hand it whatever the
+// provider returned; it yields `{ model }` when the reply named one and `{}`
+// when it did not, ready to spread into the payload.
+export { respondingModel } from "./core/types.js";
 // ── Guard utilities ─────────────────────────────────────────────────────────
 export { resolveGuards, DEFAULT_GUARDS } from "./core/guards.js";
 // ── Quality scorer ──────────────────────────────────────────────────────────

package/dist/tools/dedup.d.ts

@@ -5,12 +5,33 @@
  * Stored in Redis as: {prefix}:session:{id}:tools:dedup hash field
  * TTL: 5 minutes (configurable)
  */
-import type { ToolResult } from "../core/types.js";
+import type { DedupPort, ToolResult } from "../core/types.js";
 type RedisLike = {
     hget(key: string, field: string): Promise<string | null>;
     hset(key: string, field: string, value: string): Promise<unknown>;
     expire(key: string, seconds: number): Promise<unknown>;
 };
+/**
+ * The bundled Redis-backed `DedupPort` — the three functions below, behind the
+ * port the executor now takes.
+ *
+ * It adds nothing: `check`/`store` are `checkDedup`/`storeDedup` with the key
+ * built by `toolDedupKey` from the prefix this was constructed with, which is
+ * precisely what the executor used to do inline with a raw client. The class
+ * exists so that the executor talks to ONE thing whether the dedup came from a
+ * config or from Redis, and so the Redis path keeps its exact key shape and TTL
+ * behaviour while doing so.
+ *
+ * The prefix is the tenant-scoped one when the loop builds this
+ * (`{prefix}:{companyId}:{agentType}`); an injected port scopes itself.
+ */
+export declare class RedisToolDedup implements DedupPort {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: RedisLike, prefix: string);
+    check(sessionId: string, hash: string): Promise<ToolResult | null>;
+    store(sessionId: string, hash: string, result: ToolResult, ttlSeconds: number): Promise<void>;
+}
 export declare function toolDedupKey(prefix: string, sessionId: string): string;
 export declare function checkDedup(redis: RedisLike, dedupKey: string, hash: string): Promise<ToolResult | null>;
 export declare function storeDedup(redis: RedisLike, dedupKey: string, hash: string, result: ToolResult, ttlSeconds: number): Promise<void>;

package/dist/tools/dedup.js

@@ -6,6 +6,34 @@
  * TTL: 5 minutes (configurable)
  */
 import { createHash } from "node:crypto";
+/**
+ * The bundled Redis-backed `DedupPort` — the three functions below, behind the
+ * port the executor now takes.
+ *
+ * It adds nothing: `check`/`store` are `checkDedup`/`storeDedup` with the key
+ * built by `toolDedupKey` from the prefix this was constructed with, which is
+ * precisely what the executor used to do inline with a raw client. The class
+ * exists so that the executor talks to ONE thing whether the dedup came from a
+ * config or from Redis, and so the Redis path keeps its exact key shape and TTL
+ * behaviour while doing so.
+ *
+ * The prefix is the tenant-scoped one when the loop builds this
+ * (`{prefix}:{companyId}:{agentType}`); an injected port scopes itself.
+ */
+export class RedisToolDedup {
+    redis;
+    prefix;
+    constructor(redis, prefix) {
+        this.redis = redis;
+        this.prefix = prefix;
+    }
+    async check(sessionId, hash) {
+        return checkDedup(this.redis, toolDedupKey(this.prefix, sessionId), hash);
+    }
+    async store(sessionId, hash, result, ttlSeconds) {
+        await storeDedup(this.redis, toolDedupKey(this.prefix, sessionId), hash, result, ttlSeconds);
+    }
+}
 export function toolDedupKey(prefix, sessionId) {
     return `${prefix}:session:${sessionId}:tools:dedup`;
 }

package/dist/tools/delegate.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Delegation — one agent asks another, as an ORDINARY TOOL (ر٢).
+ *
+ * ── Why a tool and not a loop action ────────────────────────────────────────
+ *
+ * `BrainOrchestration.action` used to carry a fifth member for routing work to
+ * another agent. It was declared at the beginning, dispatched on by nothing,
+ * and used by nobody — measured, not assumed: zero occurrences in the live
+ * consumer. Meanwhile that same consumer HAS been delegating in production for
+ * months, and it does it the other way round: a `call_agent` tool over an
+ * injected handle. The measurement settled the design argument, so the action
+ * was buried (`core/types.ts`) and this is the thing that replaces it.
+ *
+ * The consequence is the point of the whole exercise: **there is not one line
+ * of loop code here.** A delegation is a tool call, so it already goes through
+ * the parameter validation, the `onBeforeTool` approval gate, the dedup cache,
+ * the control-bus disable, the per-call `tool_call`/`tool_result` pair in the
+ * session log, the tool-call budget and the consecutive-failure counter —
+ * every one of them, for free, because it is not special. An action in the loop
+ * would have had to re-earn each of those, one `if` at a time, in the file
+ * every agent rides on.
+ *
+ * ── What this improves on the lifted original ───────────────────────────────
+ *
+ * Three things, each of them a rule this repo already pays for elsewhere:
+ *
+ *   1. **The child's session id is DERIVED, not random.** `parent.d.child`,
+ *      built from the parent's own id. The original minted a fresh UUID per
+ *      delegation, which is exactly the thing س٥ named the enemy of replay: an
+ *      arbitrary identifier kills every comparison that crosses a run — a tape
+ *      fingerprint, a golden log, a diff of two sessions that should be
+ *      identical. Derived, the same delegation twice is the same id twice, the
+ *      log reads `s-42.d.researcher` and says what it is, and the depth is
+ *      legible in the id instead of held in a side channel.
+ *
+ *   2. **The agent name is an `enum`, so the model cannot invent one.** The
+ *      brains forward `enum` into the provider schema (`toolParamsToJsonSchema`),
+ *      so this is a real constraint at the provider and not a hint. It is still
+ *      checked at execution — `validateParams` enforces presence and type, never
+ *      membership — and an unknown name is a NAMED failure the model can read
+ *      and correct, not a crash.
+ *
+ *   3. **The cost is visible.** The original returned the child's text and threw
+ *      the rest away, so a delegating agent's real spend was invisible to
+ *      everything that watched it. `totalCostUsd` rides back in the result.
+ *
+ * ── What is deliberately NOT here ───────────────────────────────────────────
+ *
+ *   • **The child's cost is not added to the parent's `totalCostUsd`.** It is
+ *     reported and left there. Both agents run their own budgets, and a number
+ *     counted in two places is worse than a number counted in one: it would
+ *     make the parent's cost cap fire on spend the child already paid for, and
+ *     the pair would then disagree about what the run cost. Raised for
+ *     management, not decided here.
+ *
+ *   • **No parent context is forwarded.** The child gets the message and its
+ *     tenant, and assembles its own persona, memories and tools. Handing it the
+ *     parent's `AgentContext` would make it a continuation of the parent rather
+ *     than a second agent — and `ToolMeta` does not carry one anyway.
+ */
+import type { Agent, Tool } from "../core/types.js";
+/**
+ * The tool's name, exported because consumers dispatch on it.
+ *
+ * An approval hook, an audit trail or a UI badge all need to recognise a
+ * delegation by name, and a hand-typed string in each of them is the drift س١
+ * was paid for. It is `call_agent` and not something new so that the consumer
+ * already running this pattern in production can swap its hand-rolled tool for
+ * this factory without changing a prompt, a manifest, or an approval rule.
+ */
+export declare const DELEGATE_TOOL_NAME = "call_agent";
+/** Tuning for `createDelegateTool`. Every field has a working default. */
+export interface DelegateToolOptions {
+    /**
+     * How many hops deep delegation may go. Default **1**: the agent you build
+     * may ask a delegate, and that delegate may not ask anyone.
+     *
+     * Measured off the CALLER's session id (`.d.` counted), not off a counter
+     * threaded through the call — so it cannot be lost, reset or lied about by a
+     * path that forgot to pass it on.
+     *
+     * `0` is a legitimate value and means "wired but switched off". Anything that
+     * is not a finite number ≥ 0 falls back to the default, in the spirit of
+     * `resolveGuards`: a typo must not silently remove a cap.
+     */
+    maxDepth?: number;
+    /**
+     * Stamped onto the tool, exactly as the MCP adapter stamps an MCP tool (ر١).
+     *
+     * That is the entire mechanism — there is no delegation-specific approval
+     * code, because `requiresApproval` is already a contract the executor fails
+     * closed on: set it with no `onBeforeTool` hook configured and the call is
+     * blocked before `execute` runs, which means blocked before the child agent
+     * is reached at all.
+     */
+    requiresApproval?: boolean;
+    /** Advisory metadata, mirroring `ToolDefinition`. See the note on `DelegateTool`. */
+    destructive?: boolean;
+    /** Advisory metadata, mirroring `ToolDefinition`. See the note on `DelegateTool`. */
+    category?: string;
+}
+/**
+ * A `Tool`, plus the two advisory fields mini's `Tool` does not carry.
+ *
+ * Shaped exactly like `McpTool` (ر١) and for the same reason: `ToolDefinition`
+ * declares `destructive` and `category`, `Tool` does not, and
+ * `toToolDefinitions` copies neither — so today they are carried and not yet
+ * read. That gap is already raised for management as the `toToolDefinitions`
+ * debt; this type is written to mirror the MCP stamp so that the day the debt
+ * is paid, both stamps start being read by the same change.
+ */
+export interface DelegateTool extends Tool {
+    destructive?: boolean;
+    category?: string;
+}
+/**
+ * Build the delegation tool for a set of named agents.
+ *
+ * ```ts
+ * const agent = createAgent({
+ *   definition, brain, redis,
+ *   tools: [searchTool, createDelegateTool({ researcher, drafter })],
+ * });
+ * ```
+ *
+ * The delegates are `mini` agents themselves — whatever `createAgent` returned,
+ * or anything else satisfying `Agent`. Nothing is constructed here and no
+ * connection is opened: this is a port like every other in the package, handed
+ * in at composition time.
+ *
+ * @param delegates agents this tool may call, by the name the model will use.
+ * @param opts      depth cap and the approval/metadata stamp.
+ */
+export declare function createDelegateTool(delegates: Record<string, Agent>, opts?: DelegateToolOptions): DelegateTool;

package/dist/tools/delegate.js

@@ -0,0 +1,223 @@
+/**
+ * Delegation — one agent asks another, as an ORDINARY TOOL (ر٢).
+ *
+ * ── Why a tool and not a loop action ────────────────────────────────────────
+ *
+ * `BrainOrchestration.action` used to carry a fifth member for routing work to
+ * another agent. It was declared at the beginning, dispatched on by nothing,
+ * and used by nobody — measured, not assumed: zero occurrences in the live
+ * consumer. Meanwhile that same consumer HAS been delegating in production for
+ * months, and it does it the other way round: a `call_agent` tool over an
+ * injected handle. The measurement settled the design argument, so the action
+ * was buried (`core/types.ts`) and this is the thing that replaces it.
+ *
+ * The consequence is the point of the whole exercise: **there is not one line
+ * of loop code here.** A delegation is a tool call, so it already goes through
+ * the parameter validation, the `onBeforeTool` approval gate, the dedup cache,
+ * the control-bus disable, the per-call `tool_call`/`tool_result` pair in the
+ * session log, the tool-call budget and the consecutive-failure counter —
+ * every one of them, for free, because it is not special. An action in the loop
+ * would have had to re-earn each of those, one `if` at a time, in the file
+ * every agent rides on.
+ *
+ * ── What this improves on the lifted original ───────────────────────────────
+ *
+ * Three things, each of them a rule this repo already pays for elsewhere:
+ *
+ *   1. **The child's session id is DERIVED, not random.** `parent.d.child`,
+ *      built from the parent's own id. The original minted a fresh UUID per
+ *      delegation, which is exactly the thing س٥ named the enemy of replay: an
+ *      arbitrary identifier kills every comparison that crosses a run — a tape
+ *      fingerprint, a golden log, a diff of two sessions that should be
+ *      identical. Derived, the same delegation twice is the same id twice, the
+ *      log reads `s-42.d.researcher` and says what it is, and the depth is
+ *      legible in the id instead of held in a side channel.
+ *
+ *   2. **The agent name is an `enum`, so the model cannot invent one.** The
+ *      brains forward `enum` into the provider schema (`toolParamsToJsonSchema`),
+ *      so this is a real constraint at the provider and not a hint. It is still
+ *      checked at execution — `validateParams` enforces presence and type, never
+ *      membership — and an unknown name is a NAMED failure the model can read
+ *      and correct, not a crash.
+ *
+ *   3. **The cost is visible.** The original returned the child's text and threw
+ *      the rest away, so a delegating agent's real spend was invisible to
+ *      everything that watched it. `totalCostUsd` rides back in the result.
+ *
+ * ── What is deliberately NOT here ───────────────────────────────────────────
+ *
+ *   • **The child's cost is not added to the parent's `totalCostUsd`.** It is
+ *     reported and left there. Both agents run their own budgets, and a number
+ *     counted in two places is worse than a number counted in one: it would
+ *     make the parent's cost cap fire on spend the child already paid for, and
+ *     the pair would then disagree about what the run cost. Raised for
+ *     management, not decided here.
+ *
+ *   • **No parent context is forwarded.** The child gets the message and its
+ *     tenant, and assembles its own persona, memories and tools. Handing it the
+ *     parent's `AgentContext` would make it a continuation of the parent rather
+ *     than a second agent — and `ToolMeta` does not carry one anyway.
+ */
+/**
+ * The tool's name, exported because consumers dispatch on it.
+ *
+ * An approval hook, an audit trail or a UI badge all need to recognise a
+ * delegation by name, and a hand-typed string in each of them is the drift س١
+ * was paid for. It is `call_agent` and not something new so that the consumer
+ * already running this pattern in production can swap its hand-rolled tool for
+ * this factory without changing a prompt, a manifest, or an approval rule.
+ */
+export const DELEGATE_TOOL_NAME = "call_agent";
+/**
+ * The marker that makes a delegated session id readable and countable.
+ *
+ * `parent.d.child` — one segment per hop, so the depth is `.d.` counted. It is
+ * `.d.` and not a bare `.` because a session id may legitimately contain dots,
+ * and a separator that ordinary ids collide with would count hops that never
+ * happened.
+ */
+const DEPTH_MARKER = ".d.";
+/** Delegation hops already taken to reach this session. A plain session is 0. */
+function delegationDepth(sessionId) {
+    return sessionId.split(DEPTH_MARKER).length - 1;
+}
+/** The child's session id: derived from the parent's, one hop deeper. */
+function childSessionId(parentSessionId, agentName) {
+    return `${parentSessionId}${DEPTH_MARKER}${agentName}`;
+}
+/** `maxDepth`, coerced. Non-finite or negative garbage falls back to the default. */
+function resolveMaxDepth(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return 1;
+    return Math.floor(value);
+}
+/**
+ * Build the delegation tool for a set of named agents.
+ *
+ * ```ts
+ * const agent = createAgent({
+ *   definition, brain, redis,
+ *   tools: [searchTool, createDelegateTool({ researcher, drafter })],
+ * });
+ * ```
+ *
+ * The delegates are `mini` agents themselves — whatever `createAgent` returned,
+ * or anything else satisfying `Agent`. Nothing is constructed here and no
+ * connection is opened: this is a port like every other in the package, handed
+ * in at composition time.
+ *
+ * @param delegates agents this tool may call, by the name the model will use.
+ * @param opts      depth cap and the approval/metadata stamp.
+ */
+export function createDelegateTool(delegates, opts = {}) {
+    const names = Object.keys(delegates);
+    const maxDepth = resolveMaxDepth(opts.maxDepth);
+    const fail = (error) => ({
+        tool: DELEGATE_TOOL_NAME,
+        status: "failed",
+        error,
+    });
+    return {
+        name: DELEGATE_TOOL_NAME,
+        description: `Hand a subtask to another agent and get its answer back. ` +
+            `Available agents: ${names.join(", ") || "(none)"}.`,
+        parameters: {
+            agent: {
+                type: "string",
+                description: `Which agent to ask. One of: ${names.join(", ") || "(none)"}.`,
+                required: true,
+                // The list the provider itself enforces. It is also re-checked below:
+                // `validateParams` checks presence and type, never membership.
+                enum: names,
+            },
+            message: {
+                type: "string",
+                description: "The task to hand over, stated in full — the other agent sees none of this conversation.",
+                required: true,
+            },
+        },
+        ...(opts.requiresApproval !== undefined
+            ? { requiresApproval: opts.requiresApproval }
+            : {}),
+        ...(opts.destructive !== undefined ? { destructive: opts.destructive } : {}),
+        ...(opts.category !== undefined ? { category: opts.category } : {}),
+        async execute(args, meta) {
+            const agentName = String(args["agent"] ?? "");
+            const message = String(args["message"] ?? "");
+            // ── The depth cap, and it fails CLOSED ───────────────────────────────
+            //
+            // Checked before the name is even resolved, because the cheapest place to
+            // stop a runaway recursion is before it can name its next victim. The
+            // answer is a named `failed` result and not a thrown exception: a throw
+            // ends the step, while a result is something the model reads, understands
+            // and can act on — the same reasoning that makes an MCP `isError` a
+            // failed result rather than a throw.
+            //
+            // Two ways the count can read HIGH — an app whose own session ids contain
+            // `.d.`, or a delegate registered under a name containing it — and both
+            // err toward refusing to delegate. There is no input that makes it read
+            // low, which is the only direction that would matter.
+            const depth = delegationDepth(meta.sessionId);
+            if (depth >= maxDepth) {
+                return fail(`delegation depth exceeded: "${meta.sessionId}" is already ${depth} ` +
+                    `hop(s) deep and maxDepth is ${maxDepth}`);
+            }
+            // ── The name, re-checked here and not only in the schema ─────────────
+            const child = Object.prototype.hasOwnProperty.call(delegates, agentName)
+                ? delegates[agentName]
+                : undefined;
+            if (!child) {
+                return fail(`unknown agent "${agentName}" — available: ${names.join(", ") || "(none)"}`);
+            }
+            const sessionId = childSessionId(meta.sessionId, agentName);
+            // ── The child's event ────────────────────────────────────────────────
+            //
+            // The tenant rides across unchanged. "Whoever injects a store injects its
+            // isolation with it" (س١'s ruling) has a corollary here: a delegation
+            // that dropped the tenant would run the child UNSCOPED — writing to the
+            // bare prefix — and the isolation covenant would be broken by a tool
+            // rather than by a store. It is passed through exactly as received; this
+            // tool neither invents a tenant nor widens one.
+            const childEvent = {
+                sessionId,
+                message,
+                ...(meta.tenantContext ? { tenantContext: meta.tenantContext } : {}),
+            };
+            try {
+                const outcome = await child.handle(childEvent);
+                // `error` is the only outcome type that is a FAILURE of the delegation.
+                // `clarify`, `escalate` and a suppressed answer are all things the child
+                // successfully decided, and the model needs to see which one it got —
+                // hence `outcome` in the payload rather than a flattened string.
+                const failed = outcome.type === "error";
+                const result = {
+                    agent: agentName,
+                    sessionId,
+                    outcome: outcome.type,
+                    text: outcome.text ?? "",
+                    // Reported, never folded into the parent's total. See the header.
+                    totalCostUsd: outcome.metrics.totalCostUsd,
+                };
+                return {
+                    tool: DELEGATE_TOOL_NAME,
+                    status: failed ? "failed" : "ok",
+                    result,
+                    ...(failed
+                        ? {
+                            error: outcome.error ??
+                                outcome.text ??
+                                `agent "${agentName}" failed`,
+                        }
+                        : {}),
+                };
+            }
+            catch (err) {
+                // `handle` does its own catching and normally returns an error outcome
+                // rather than throwing — but it can still throw before its try block
+                // (resolving Redis, acquiring the session lock). One agent failing to
+                // start is this tool's failure, not the parent step's.
+                return fail(`agent "${agentName}" threw: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    };
+}