@msm-core/mini 0.5.2 → 0.9.0

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)}`);
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msm-core/mini",
-  "version": "0.5.2",
+  "version": "0.9.0",
   "description": "Portable AI agent execution loop — brain-agnostic, zero embedded databases",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,13 +31,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run build && npm test"
-  },
   "peerDependencies": {
     "openai": ">=4.0.0",
     "@anthropic-ai/sdk": ">=0.20.0",
@@ -55,7 +48,8 @@
     }
   },
   "dependencies": {
-    "ioredis": "^5.3.2"
+    "ioredis": "^5.3.2",
+    "@msm-core/session": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -71,5 +65,11 @@
     "portable"
   ],
   "author": "Emad Jumaah",
-  "license": "UNLICENSED"
-}
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}