@msm-core/mini 0.5.2 → 0.9.0

package/dist/core/types.d.ts

@@ -4,6 +4,8 @@
  * All contracts for the lite agent runtime. Brain-agnostic, zero embedded
  * databases. Application layer owns persistence; agent owns the loop.
  */
+import type { SessionLogPort } from "@msm-core/session";
+import type { ContextBudget } from "./context-builder.js";
 /**
  * A single memory entry — assembled by msm-context or by the app directly.
  * The agent injects these into every brain call in priority order.
@@ -114,12 +116,104 @@ export interface BrainRunInput {
      * safe — the loop still stops waiting via its timeout race.
      */
     signal?: AbortSignal;
+    /**
+     * Present ONLY when a consumer asked to see the answer as it is produced
+     * (ب١). Its absence is the normal case and means "do not stream" — every
+     * built-in brain then walks the exact non-streaming path it always walked.
+     *
+     * **Display, not truth.** What the loop records, gates, returns and replays
+     * is still the completed `BrainPayload`. A chunk is never logged as an event,
+     * never enters a `replay` fingerprint, and never changes the session-log
+     * invariant. Drop every chunk on the floor and the run is bit-identical.
+     *
+     * A brain that ignores this field is CORRECT, not broken — it simply does not
+     * stream. Third-party brains written before ب١ keep working untouched.
+     */
+    onChunk?: (chunk: BrainChunk) => void;
+}
+/**
+ * One piece of a model answer as it arrives.
+ *
+ * **Text only in v1.** Streaming tool CALLS is deliberately out of scope: the
+ * brain still accumulates them and returns them in the payload exactly as it
+ * does today, so a half-arrived tool call is never observable and never
+ * executable. The type is an object rather than a bare `string` so that day —
+ * if it comes — adds a field instead of breaking every consumer's signature.
+ */
+export interface BrainChunk {
+    text: string;
+}
+/**
+ * One tool invocation a model asked for, in the model's own order.
+ *
+ * The unit is the CALL, not the step: modern models emit several in one
+ * response, and a step-shaped type would force the loop back into one
+ * round-trip per tool — the cost this exists to remove.
+ */
+export interface BrainToolCall {
+    name: string;
+    params: Record<string, unknown>;
 }
+/**
+ * Every action the loop DISPATCHES ON — declared as data, and the only list.
+ *
+ * ── Why this is a `const` array and not an inline union (ر٢) ────────────────
+ *
+ * There were two lists. This union, and a second copy in `bridge/pipeline.ts`
+ * that normalises whatever a duck-typed pipeline hands back. Both carried a
+ * fifth member the loop never dispatched on — a routing action that was
+ * declared at the beginning, implemented nowhere, and used by nobody (measured:
+ * zero occurrences in the live consumer). It survived precisely because
+ * deleting it meant finding and agreeing two places, and س١'s lesson is that
+ * two lists of the same thing drift apart silently and are only noticed by the
+ * damage.
+ *
+ * So there is now one list. The union below is derived from it and the bridge
+ * validates against it, which means a member cannot be added to one and
+ * forgotten in the other, and a member cannot be REMOVED from one and left
+ * standing in the other. `BrainActionsAreTheFourLiveOnes` then makes growing
+ * this array a decision someone has to write down rather than one that happens
+ * by omission.
+ *
+ * **What the loop actually does with each** (`core/loop.ts`):
+ *   - `use_tool`  → the step's tool calls run, then back to the model.
+ *   - `clarify` / `escalate` → terminal, and the outcome carries that type.
+ *   - `respond`   → terminal, the text is delivered.
+ *
+ * And an action that is NONE of these — a rogue model emitting a string at
+ * runtime, where no type can stop it — takes the `respond` path: terminal,
+ * one iteration, whatever text the payload carried. That is the existing
+ * behaviour, it is fail-safe (a nonsense action never loops and never runs a
+ * tool), and it is pinned by a guard in `tests/delegate.test.ts` rather than
+ * left as an accident. The bridge's `respond` fallback for an unrecognised
+ * string is the same rule stated one layer earlier.
+ */
+export declare const BRAIN_ACTIONS: readonly ["use_tool", "respond", "clarify", "escalate"];
+/** What a model may ask the loop to do. Derived from `BRAIN_ACTIONS`. */
+export type BrainAction = (typeof BRAIN_ACTIONS)[number];
 export interface BrainOrchestration {
-    action: "use_tool" | "respond" | "clarify" | "escalate" | "delegate";
+    action: BrainAction;
     confidence: number;
+    /**
+     * The FIRST call of the step. Always filled whenever `tool_calls` is —
+     * never left behind as `tool_calls` grows. Every consumer written against
+     * one-tool-per-step keeps reading exactly what it always read.
+     */
     tool_name?: string;
+    /** The first call's arguments. Same covenant as `tool_name`. */
     tool_params?: Record<string, unknown>;
+    /**
+     * ALL the calls of this step, in the order the model emitted them.
+     *
+     * **A pure addition.** A brain that fills only `tool_name`/`tool_params`
+     * (every third-party brain written before this field existed, and every
+     * scripted brain in the suite) is normalized to a single-call step and takes
+     * the path it always took, character for character. A brain that fills this
+     * field fills the two above with `tool_calls[0]` as well — the covenant is
+     * one-directional: new readers may read the array, old readers never see a
+     * hole where the first call used to be.
+     */
+    tool_calls?: BrainToolCall[];
     reasoning?: string;
     [key: string]: unknown;
 }
@@ -253,6 +347,89 @@ export interface DocumentState {
     startedAt: number;
     updatedAt: number;
 }
+/**
+ * Final run metadata persisted after every handle() — for ops dashboards.
+ *
+ * Declared here, with the port it belongs to, rather than inside one adapter:
+ * it is part of the contract every store implements, not a Redis detail. The
+ * Redis adapter re-exports it, so existing imports keep working unchanged.
+ */
+export interface SessionMetadata {
+    iterationCount: number;
+    startedAt: number;
+    totalCostUsd: number;
+    status: "running" | "completed" | "failed" | "killed";
+}
+/**
+ * The session-memory PORT — conversation history, run metadata, document state.
+ *
+ * The loop talks to this interface and never to a concrete store. Inject an
+ * implementation via `AgentConfig.memory`; when it is omitted the loop builds
+ * the bundled `RedisMemory` from `AgentConfig.redis` exactly as it always has.
+ *
+ * Six functions — the surface `RedisMemory` already had, at its current
+ * signatures. Nothing is added speculatively: an append-only event log is a
+ * different contract and does not belong here.
+ */
+export interface SessionStore {
+    /** Append one message to this session's conversation history. */
+    appendHistory(sessionId: string, entry: Message): Promise<void>;
+    /** The last `limit` messages, oldest-first. Default limit: 50. */
+    getHistory(sessionId: string, limit?: number): Promise<Message[]>;
+    getMetadata(sessionId: string): Promise<SessionMetadata | null>;
+    setMetadata(sessionId: string, meta: SessionMetadata): Promise<void>;
+    getDocumentState(sessionId: string): Promise<DocumentState | null>;
+    setDocumentState(sessionId: string, state: DocumentState): Promise<void>;
+}
+/**
+ * What a compactor decides when it decides to compact.
+ *
+ * `keepTurns` is a REQUEST, not a command: the loop hands it to
+ * `compactionBoundary`, which cuts only at whole turns and refuses to sever a
+ * tool call from its result. A compactor asking to keep zero turns of a session
+ * whose last turn is still unpaired gets a smaller range than it asked for, or
+ * none at all. That is the point of having two defences.
+ */
+export interface CompactionDecision {
+    /** The text the compacted range will read as. Empty means "no compaction". */
+    summary: string;
+    /** How many trailing turns to leave verbatim. Clamped to what is safe. */
+    keepTurns: number;
+}
+/**
+ * The compaction seat: a port the loop consults before it derives the
+ * conversation, and never a trick it plays on the history array.
+ *
+ * Today a long session is trimmed by `history.slice(-maxHistoryMessages)`. That
+ * cut lands wherever it lands — through the middle of a tool call and its
+ * result, through the middle of a turn — and it is silent. A long legal case in
+ * nisus loses its own beginning and nothing anywhere says so. This port is the
+ * seat where that stops being true.
+ *
+ * Three properties are contractual:
+ *
+ *  1. **It only works with `sessionLog`.** Compaction records a `compaction`
+ *     event; without a log there is nowhere to record it, and a summary that is
+ *     not recorded is exactly the silent rewrite this replaces. With `memory`
+ *     alone the port is inert and the old `slice` path runs untouched — declared,
+ *     not an oversight.
+ *
+ *  2. **`null` means no compaction.** The overwhelmingly common answer. A port
+ *     that returns `null` costs one call and changes nothing.
+ *
+ *  3. **A throwing port fails the turn.** It is not swallowed. A compactor that
+ *     has quietly been failing for a month is a session that has quietly been
+ *     losing its head for a month — the failure this exists to end, wearing a
+ *     different hat.
+ *
+ * @param messages the conversation DERIVED from the log so far, in order.
+ * @param budget   the budget the derived history will actually be trimmed to —
+ *                 `maxHistoryMessages` is the effective cap, already reconciled
+ *                 with the agent's iteration-derived history limit.
+ */
+export interface CompactionPort {
+    maybeCompact(messages: readonly Message[], budget: ContextBudget): Promise<CompactionDecision | null>;
+}
 export interface RedisConfig {
     /**
      * Redis connection URL — mini creates its own connection.
@@ -304,6 +481,68 @@ export interface AgentConfig {
     definition: string | AgentDefinition;
     brain: Brain;
     redis: RedisConfig;
+    /**
+     * Optional session-memory port. When injected, the loop routes ALL history /
+     * metadata / document-state access through it and never constructs a
+     * Redis-backed store. When omitted, the loop builds `RedisMemory` from
+     * `redis` exactly as before — same prefix, same TTLs, same tenant scoping —
+     * so every existing consumer is unaffected.
+     *
+     * `redis` stays required either way: the control bus, the session lock and
+     * tool dedup are separate ports and still ride on it.
+     */
+    memory?: SessionStore;
+    /**
+     * Optional session **event log** (`@msm-core/session`). Injecting it inverts
+     * where conversation context comes from:
+     *
+     *   - **Omitted (default)** — nothing changes. Not one event is written, the
+     *     history handed to the brain is `memory.getHistory()` exactly as before,
+     *     and the invariant below never runs. Every existing consumer is
+     *     bit-for-bit unaffected.
+     *   - **Injected** — the loop writes every event as it happens (the user
+     *     message, each step, each model request/response, every tool call and
+     *     its result, guards, the delivered reply), and the conversation handed
+     *     to the model is DERIVED from the log (`deriveMessages`) instead of read
+     *     from the history array. `memory.appendHistory` keeps being written too:
+     *     one transitional phase of dual writing, log as truth, array as
+     *     compatibility.
+     *
+     * Two consequences worth knowing before you inject one:
+     *
+     *   1. **The derived conversation is richer.** It carries the
+     *      `assistant`/`tool` pairs of previous turns, which the history array
+     *      never held. That is the point of the log, not a side effect — but it
+     *      is a real change in what the model sees.
+     *   2. **It is the truth, so its failures are loud.** A rejected append
+     *      (e.g. `SeqGapError`) fails the turn rather than being swallowed: a log
+     *      with a hole in it cannot back an audit, a resume or a replay.
+     *
+     * Isolation is the injector's, exactly as with `memory`: this port takes a
+     * `sessionId` and knows nothing of tenants. Whoever injects a log injects its
+     * tenant scoping with it.
+     */
+    sessionLog?: SessionLogPort;
+    /**
+     * Optional **compaction port** (ض١). Consulted once per turn, right before
+     * the conversation is derived, and only when `sessionLog` is also injected.
+     *
+     *   - **Omitted (default)** — not one extra call, not one extra event. The
+     *     conversation is derived and trimmed exactly as it was before.
+     *   - **Omitted `sessionLog`** — the seat is inert even when this is set:
+     *     compaction records an event, and without a log there is nothing to
+     *     record it in. The legacy history path keeps its `slice`. Declared.
+     *   - **Both injected** — when the port returns a summary, the loop writes a
+     *     `compaction` event covering a safe range (`compactionBoundary`) and
+     *     re-derives. The model then reads one summary plus the recent turns
+     *     verbatim, and the invariant still proves that what it read came out of
+     *     the log — because the compaction is IN the log.
+     *
+     * `createBrainCompactor` is a reference implementation that summarises with an
+     * injected `Brain`. The port does not require it; anything with a
+     * `maybeCompact` will do, including one that never calls a model at all.
+     */
+    compaction?: CompactionPort;
     /** App-provided tools — agent can only call tools listed here */
     tools: Tool[];
     guards?: GuardConfig;
@@ -343,6 +582,15 @@ export interface GuardFiredInfo {
     signal: GuardSignal;
     iteration: number;
 }
+/** One streamed piece of the model's answer, with the step it belongs to (ب١). */
+export interface ChunkInfo {
+    sessionId: string;
+    /** The loop iteration whose brain call produced this text. */
+    iteration: number;
+    /** The delta — not the running total. Concatenating every chunk of a step
+     *  yields the text that step's payload carries. */
+    text: string;
+}
 /**
  * Return value from onBeforeTool hook:
  *   "proceed"            — execute the tool normally
@@ -365,6 +613,18 @@ export interface AgentHooks {
     onToolCall?: (info: ToolCallInfo) => void;
     onGuard?: (info: GuardFiredInfo) => void;
     onFatalError?: (error: Error, sessionId: string) => void;
+    /**
+     * Called for each piece of model text as it arrives (ب١). Wire it to an SSE
+     * channel and the user stops watching a silent screen.
+     *
+     * **Setting this is what turns streaming on.** The loop passes `onChunk` down
+     * to the brain only when this hook exists; with no hook, `BrainRunInput`
+     * carries no `onChunk` and every brain takes its ordinary non-streaming path.
+     *
+     * Fire-and-forget like its siblings: a throwing hook is swallowed and the
+     * stream continues — a broken display must not break the run.
+     */
+    onChunk?: (info: ChunkInfo) => void;
     /**
      * Called before every tool execution (BEFORE the dedup check, so cached
      * results can never bypass the gate). Return "proceed" to execute normally,

package/dist/core/types.js

@@ -4,4 +4,43 @@
  * All contracts for the lite agent runtime. Brain-agnostic, zero embedded
  * databases. Application layer owns persistence; agent owns the loop.
  */
-export {};
+/**
+ * Every action the loop DISPATCHES ON — declared as data, and the only list.
+ *
+ * ── Why this is a `const` array and not an inline union (ر٢) ────────────────
+ *
+ * There were two lists. This union, and a second copy in `bridge/pipeline.ts`
+ * that normalises whatever a duck-typed pipeline hands back. Both carried a
+ * fifth member the loop never dispatched on — a routing action that was
+ * declared at the beginning, implemented nowhere, and used by nobody (measured:
+ * zero occurrences in the live consumer). It survived precisely because
+ * deleting it meant finding and agreeing two places, and س١'s lesson is that
+ * two lists of the same thing drift apart silently and are only noticed by the
+ * damage.
+ *
+ * So there is now one list. The union below is derived from it and the bridge
+ * validates against it, which means a member cannot be added to one and
+ * forgotten in the other, and a member cannot be REMOVED from one and left
+ * standing in the other. `BrainActionsAreTheFourLiveOnes` then makes growing
+ * this array a decision someone has to write down rather than one that happens
+ * by omission.
+ *
+ * **What the loop actually does with each** (`core/loop.ts`):
+ *   - `use_tool`  → the step's tool calls run, then back to the model.
+ *   - `clarify` / `escalate` → terminal, and the outcome carries that type.
+ *   - `respond`   → terminal, the text is delivered.
+ *
+ * And an action that is NONE of these — a rogue model emitting a string at
+ * runtime, where no type can stop it — takes the `respond` path: terminal,
+ * one iteration, whatever text the payload carried. That is the existing
+ * behaviour, it is fail-safe (a nonsense action never loops and never runs a
+ * tool), and it is pinned by a guard in `tests/delegate.test.ts` rather than
+ * left as an accident. The bridge's `respond` fallback for an unrecognised
+ * string is the same rule stated one layer earlier.
+ */
+export const BRAIN_ACTIONS = [
+    "use_tool",
+    "respond",
+    "clarify",
+    "escalate",
+];

package/dist/index.d.ts

@@ -7,13 +7,18 @@
  * import { RedisMemory, RedisControlBus } from 'msm-mini/adapters'
  */
 export { createAgent } from "./core/loop.js";
+export { createBrainCompactor } from "./core/loop.js";
+export type { BrainCompactorOptions } from "./core/loop.js";
 export { createGeminiBrain } from "./brain/gemini.js";
 export { createOpenAIBrain } from "./brain/openai.js";
 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, BrainPayload, BrainRunInput, DocumentState, GateConfig, GuardConfig, GuardSignal, GuardSignalType, IterationInfo, LoopOutcome, MemoryEntry, Message, OutcomeType, OutputValidation, OutputValidator, RedisConfig, RunState, SectionInfo, TenantContext, Tool, ToolCallInfo, ToolDefinition, ToolMeta, ToolParameter, ToolResult, } from "./core/types.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, 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 type { ContextBudget } from "./core/context-builder.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

@@ -8,6 +8,8 @@
  */
 // ── Main factory ────────────────────────────────────────────────────────────
 export { createAgent } from "./core/loop.js";
+// ── Compaction (ض١) — the seat, and one reference occupant ──────────────────
+export { createBrainCompactor } from "./core/loop.js";
 // ── Brain factories ─────────────────────────────────────────────────────────
 export { createGeminiBrain } from "./brain/gemini.js";
 export { createOpenAIBrain } from "./brain/openai.js";
@@ -16,6 +18,8 @@ export { createOllamaBrain } from "./brain/ollama.js";
 export { buildBrain } from "./brain/factory.js";
 // ── Definition parser ───────────────────────────────────────────────────────
 export { parseDefinition } from "./definition/parser.js";
+// ── Delegation (ر٢) — one agent asks another, as an ordinary tool ───────────
+export { createDelegateTool, DELEGATE_TOOL_NAME } from "./tools/delegate.js";
 // ── Guard utilities ─────────────────────────────────────────────────────────
 export { resolveGuards, DEFAULT_GUARDS } from "./core/guards.js";
 // ── Quality scorer ──────────────────────────────────────────────────────────

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;