@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/src/memory/episodic-rrf.ts

@@ -0,0 +1,224 @@
+/**
+ * Episodic memory recall — weighted score combination (cosine + recency + importance).
+ *
+ * Despite the file name (RRF — Reciprocal Rank Fusion), the algorithm used
+ * for CC v3.1 is a **linear combination of normalized components**:
+ *
+ *   score(e) = α · cosine_sim(q, e.embedding)
+ *            + β · exp(-Δt / τ)               // recency decay
+ *            + γ · importance(e)               // [0,1]
+ *
+ *   defaults: α=0.5, β=0.3, γ=0.2, τ=14 days
+ *
+ * This shape was chosen over pure RRF because the three signals are
+ * heterogeneous (similarity, time, salience) and combining them via rank
+ * fusion would erase the magnitude information that callers care about
+ * (e.g. "near-perfect cosine match" vs "loosely related").
+ *
+ * Pluggable scorers — callers provide functions mapping an entry to each
+ * component so the algorithm is decoupled from storage details (embedding
+ * column, importance field name, etc.).
+ *
+ * @see ../ports/brain.ts — EpisodicMemoryEntry
+ * @see ADR-ECO-034 §"AgentPersona via Brain Tier 3 semantic" (companion)
+ * @public
+ */
+
+import type { EpisodicMemoryEntry } from "../ports/brain.js";
+
+/** Default weights — sum to 1.0. */
+export const DEFAULT_RRF_WEIGHTS = {
+  cosine: 0.5,
+  recency: 0.3,
+  importance: 0.2,
+} as const;
+
+/** Default recency half-life (14 days in ms). */
+export const DEFAULT_RECENCY_HALFLIFE_MS = 14 * 24 * 60 * 60 * 1000;
+
+export interface RrfWeights {
+  cosine: number;
+  recency: number;
+  importance: number;
+}
+
+export interface RrfOptions {
+  weights?: Partial<RrfWeights>;
+  /** Half-life for recency decay (default: 14 days). */
+  recencyHalflifeMs?: number;
+  /** Cap on returned entries (default: unbounded). */
+  topK?: number;
+  /** Override "now" for deterministic tests. */
+  now?: () => number;
+}
+
+export interface ScoreComponents {
+  cosine: number;
+  recency: number;
+  importance: number;
+}
+
+export interface ScoredEntry<T> {
+  entry: T;
+  score: number;
+  components: ScoreComponents;
+}
+
+export interface RrfScorers<T> {
+  /** Cosine similarity ∈ [-1, 1] — non-finite values clamped to 0. */
+  cosine: (entry: T) => number;
+  /** Timestamp (ms epoch) used for recency decay. Negative → drop the entry. */
+  timestamp: (entry: T) => number;
+  /** Salience ∈ [0, 1]. Out-of-range values clamped. */
+  importance: (entry: T) => number;
+}
+
+// ─── Pure helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Cosine similarity between two equal-length numeric vectors.
+ *
+ * Returns 0 if either vector is empty / zero-norm / mismatched length —
+ * never throws. This makes the function safe to compose into scorers that
+ * may receive partial entries.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length === 0 || a.length !== b.length) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    const ai = a[i]!;
+    const bi = b[i]!;
+    dot += ai * bi;
+    na += ai * ai;
+    nb += bi * bi;
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+
+/**
+ * Recency score in [0, 1]: exp(-ln(2) · Δt / halflife).
+ *   - 1.0 at Δt = 0
+ *   - 0.5 at Δt = halflife
+ *   - approaches 0 as Δt → ∞
+ *
+ * `nowMs` and `timestampMs` are epoch ms. Future timestamps (Δt < 0) clamp
+ * to 1.0 (treated as "right now").
+ */
+export function recencyScore(
+  nowMs: number,
+  timestampMs: number,
+  halflifeMs: number
+): number {
+  if (halflifeMs <= 0) return 0;
+  const dt = Math.max(0, nowMs - timestampMs);
+  return Math.exp((-Math.LN2 * dt) / halflifeMs);
+}
+
+/** Clamp to [0, 1]; NaN / non-finite → 0. */
+function clamp01(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+/** Clamp cosine output (−1..1) to ≥0 to avoid negative contributions. */
+function clampCosineToPos(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return value < 0 ? 0 : value;
+}
+
+// ─── Generic scorer ───────────────────────────────────────────────────────────
+
+/**
+ * Score a batch of entries via the weighted combination. The result is sorted
+ * by descending score and trimmed to `topK` when set.
+ *
+ * Negative timestamps (per `scorers.timestamp`) cause the entry to be dropped
+ * entirely — this is the cheap way for a scorer to signal "skip" (e.g. row
+ * lacks the field).
+ */
+export function scoreEntries<T>(
+  entries: T[],
+  scorers: RrfScorers<T>,
+  opts: RrfOptions = {}
+): ScoredEntry<T>[] {
+  const weights: RrfWeights = {
+    cosine: opts.weights?.cosine ?? DEFAULT_RRF_WEIGHTS.cosine,
+    recency: opts.weights?.recency ?? DEFAULT_RRF_WEIGHTS.recency,
+    importance: opts.weights?.importance ?? DEFAULT_RRF_WEIGHTS.importance,
+  };
+  const halflifeMs = opts.recencyHalflifeMs ?? DEFAULT_RECENCY_HALFLIFE_MS;
+  const nowMs = (opts.now ?? Date.now)();
+
+  const scored: ScoredEntry<T>[] = [];
+  for (const entry of entries) {
+    const ts = scorers.timestamp(entry);
+    if (ts < 0) continue;
+    const cosine = clampCosineToPos(scorers.cosine(entry));
+    const recency = recencyScore(nowMs, ts, halflifeMs);
+    const importance = clamp01(scorers.importance(entry));
+    const score =
+      weights.cosine * cosine +
+      weights.recency * recency +
+      weights.importance * importance;
+    scored.push({
+      entry,
+      score,
+      components: { cosine, recency, importance },
+    });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  if (opts.topK !== undefined && opts.topK >= 0) {
+    return scored.slice(0, opts.topK);
+  }
+  return scored;
+}
+
+// ─── Concrete recall over EpisodicMemoryEntry ────────────────────────────────
+
+/**
+ * The agent-sdk EpisodicMemoryEntry does NOT carry an embedding column —
+ * embeddings live in the storage layer (Postgres pgvector). To enable
+ * pluggable cosine scoring, the caller may attach an embedding via the
+ * `embedding` field on `metadata`, or supply a custom resolver.
+ */
+export type EpisodicCosineFn = (entry: EpisodicMemoryEntry) => number;
+
+/** Default cosine: 0 (no embedding available — relies on recency + importance only). */
+const ZERO_COSINE: EpisodicCosineFn = () => 0;
+
+export interface RecallRrfOptions extends RrfOptions {
+  /**
+   * Cosine scorer — defaults to 0 (no embedding). Provide when you have a
+   * pre-computed (entry × query) similarity for each entry.
+   */
+  cosine?: EpisodicCosineFn;
+}
+
+/**
+ * Rank EpisodicMemoryEntry[] by weighted score. Convenience over scoreEntries
+ * with the standard projection (timestamp = entry.timestamp,
+ * importance = metadata.importance ?? 0.5).
+ */
+export function recallEpisodicRrf(
+  entries: EpisodicMemoryEntry[],
+  opts: RecallRrfOptions = {}
+): ScoredEntry<EpisodicMemoryEntry>[] {
+  const cosineFn = opts.cosine ?? ZERO_COSINE;
+  return scoreEntries(
+    entries,
+    {
+      cosine: cosineFn,
+      timestamp: (e) => e.timestamp,
+      importance: (e) => {
+        const raw = (e.metadata?.importance as unknown) ?? 0.5;
+        return typeof raw === "number" ? raw : 0.5;
+      },
+    },
+    opts
+  );
+}

package/src/mesh/attenuation.ts

@@ -0,0 +1,190 @@
+/**
+ * src/mesh/attenuation.ts
+ *
+ * Biscuit-style capability attenuation for mesh.delegate().
+ *
+ * @experimental — sprint-585. Public API may change before v1.x freeze.
+ *
+ * Implements capability INTERSECTION (child ⊆ parent) without the actual
+ * Biscuit token format — keeps the SDK dependency-free. Production deployments
+ * should swap `buildToken` / `parseToken` for a real Biscuit issuer in CC.
+ *
+ * Invariants:
+ *  - Child actions = INTERSECTION(parent.actions, requested.actions)
+ *  - Child budget  = MIN(parent.budgetEur, requested.budgetEur)
+ *  - Child expiry  = MIN(parent.expiresAt, requested.expiresAt) when both present
+ *  - Wildcard support: "*" or "ns:*" in parent grants any matching action.
+ *
+ * No `any` — strict types per craft-standards.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * MeshCapabilityScope — bounded capability declaration for mesh dispatch.
+ *
+ * Renamed from `CapabilityScope` to avoid clash with `ports/delegation.ts`
+ * which models a different (DelegationClaim) shape.
+ */
+export interface MeshCapabilityScope {
+  /** Actions permitted, e.g. ["brain:read", "vault:read", "hitl:trigger"]. */
+  readonly actions: ReadonlyArray<string>;
+  /** Max EUR the holder may spend under this scope. */
+  readonly budgetEur: number;
+  /** Hard expiry — past this date, scope MUST be rejected by callers. */
+  readonly expiresAt?: Date;
+}
+
+/** Backwards-compatible alias for the spec name `CapabilityScope`. */
+export type CapabilityScope = MeshCapabilityScope;
+
+/**
+ * AttenuatedToken — opaque transport for a scope across an agent boundary.
+ *
+ * Phase MVP : plain object (no signature). Phase 2+ : swap with Biscuit token
+ * (the encoded `token` field becomes the Biscuit hex / base64 form).
+ */
+export interface AttenuatedToken {
+  /** Allowed actions (post-attenuation). */
+  readonly scope: ReadonlyArray<string>;
+  /** Remaining EUR allowance. */
+  readonly budgetEur: number;
+  /** Parent agent identifier — caller of the delegation step. */
+  readonly parentId: string;
+  /** Optional expiry, ISO 8601 — propagated from MeshCapabilityScope.expiresAt. */
+  readonly expiresAt?: string;
+}
+
+// ─── Wildcard match ──────────────────────────────────────────────────────────
+
+/**
+ * Match an action against a parent permission entry.
+ *
+ *  - Exact match (case-sensitive).
+ *  - `"*"` grants everything.
+ *  - `"ns:*"` grants any action whose namespace prefix matches `ns:`.
+ */
+function permissionMatches(parentPerm: string, requested: string): boolean {
+  if (parentPerm === "*" || parentPerm === requested) return true;
+  if (parentPerm.endsWith(":*")) {
+    const prefix = parentPerm.slice(0, -1); // keep trailing colon
+    return requested.startsWith(prefix);
+  }
+  return false;
+}
+
+/**
+ * Intersect a parent action set with a requested set.
+ * Output: only requested actions that the parent allows (preserving order).
+ */
+function intersectActions(
+  parent: ReadonlyArray<string>,
+  requested: ReadonlyArray<string>,
+): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const req of requested) {
+    if (seen.has(req)) continue;
+    for (const p of parent) {
+      if (permissionMatches(p, req)) {
+        out.push(req);
+        seen.add(req);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Attenuate a parent scope by a requested scope.
+ *
+ * Returns a NEW scope (immutable input semantics).
+ * Guarantees `child ⊆ parent` (capability intersection invariant).
+ */
+export function attenuateScope(
+  parent: MeshCapabilityScope,
+  requested: MeshCapabilityScope,
+): MeshCapabilityScope {
+  if (!Number.isFinite(parent.budgetEur) || parent.budgetEur < 0) {
+    throw new RangeError(`attenuateScope: parent.budgetEur must be ≥ 0, got ${parent.budgetEur}`);
+  }
+  if (!Number.isFinite(requested.budgetEur) || requested.budgetEur < 0) {
+    throw new RangeError(
+      `attenuateScope: requested.budgetEur must be ≥ 0, got ${requested.budgetEur}`,
+    );
+  }
+
+  const childActions = intersectActions(parent.actions, requested.actions);
+  const childBudget = Math.min(parent.budgetEur, requested.budgetEur);
+
+  let childExpiresAt: Date | undefined;
+  if (parent.expiresAt && requested.expiresAt) {
+    childExpiresAt = new Date(Math.min(parent.expiresAt.getTime(), requested.expiresAt.getTime()));
+  } else if (parent.expiresAt) {
+    childExpiresAt = new Date(parent.expiresAt.getTime());
+  } else if (requested.expiresAt) {
+    childExpiresAt = new Date(requested.expiresAt.getTime());
+  }
+
+  const out: MeshCapabilityScope = childExpiresAt
+    ? {
+        actions: childActions,
+        budgetEur: childBudget,
+        expiresAt: childExpiresAt,
+      }
+    : { actions: childActions, budgetEur: childBudget };
+  return out;
+}
+
+/**
+ * Check whether a scope permits a specific action.
+ * Supports wildcards (`"*"`, `"ns:*"`). Returns false if scope is expired.
+ */
+export function scopeAllows(scope: MeshCapabilityScope, action: string): boolean {
+  if (scope.expiresAt && scope.expiresAt.getTime() <= Date.now()) return false;
+  for (const perm of scope.actions) {
+    if (permissionMatches(perm, action)) return true;
+  }
+  return false;
+}
+
+/**
+ * Encode a scope as an opaque token bound to a parent identifier.
+ *
+ * Phase MVP : plain structural copy. Phase 2+ : replace with Biscuit-signed token
+ * (the `parentId` becomes the issuer public key, `scope`/`budgetEur` become
+ * Biscuit facts, `expiresAt` becomes a Biscuit check).
+ */
+export function buildToken(scope: MeshCapabilityScope, parentId: string): AttenuatedToken {
+  if (!parentId || typeof parentId !== "string") {
+    throw new TypeError("buildToken: parentId must be a non-empty string");
+  }
+  const out: AttenuatedToken = scope.expiresAt
+    ? {
+        scope: [...scope.actions],
+        budgetEur: scope.budgetEur,
+        parentId,
+        expiresAt: scope.expiresAt.toISOString(),
+      }
+    : { scope: [...scope.actions], budgetEur: scope.budgetEur, parentId };
+  return out;
+}
+
+/**
+ * Decode a token back to a MeshCapabilityScope.
+ *
+ * Inverse of `buildToken` modulo identity loss (parentId not part of scope).
+ */
+export function parseToken(token: AttenuatedToken): MeshCapabilityScope {
+  const out: MeshCapabilityScope = token.expiresAt
+    ? {
+        actions: [...token.scope],
+        budgetEur: token.budgetEur,
+        expiresAt: new Date(token.expiresAt),
+      }
+    : { actions: [...token.scope], budgetEur: token.budgetEur };
+  return out;
+}

package/src/mesh/delegate.ts

@@ -0,0 +1,254 @@
+/**
+ * src/mesh/delegate.ts
+ *
+ * `mesh.delegate()` — intent-based dispatch to the best available agent.
+ *
+ * @experimental — sprint-585. Public API may change before v1.x freeze.
+ *
+ * Replaces manual `withCompute()` boilerplate with a one-liner:
+ *
+ *     const r = await meshDelegate({ need: "summarize the spec" }, dispatcher);
+ *
+ * Responsibilities:
+ *   1. Classify need → AgentKind (via dispatcher.classify or injected hint).
+ *   2. Apply capability attenuation if a parent token is present.
+ *   3. Forward to dispatcher with budget/deadline guards.
+ *   4. Build a delegation chain link for audit.
+ *
+ * Streaming (`onChunk`) is a best-effort surface — the dispatcher must opt-in
+ * by exposing a `dispatchStream` (not part of base contract). When unavailable,
+ * the final result is delivered as a single chunk after completion.
+ */
+
+import {
+  type AttenuatedToken,
+  type MeshCapabilityScope,
+  attenuateScope,
+  buildToken,
+} from "./attenuation.js";
+import { DefaultMeshDispatcher, type DispatchIntent, type MeshDispatcher } from "./dispatcher.js";
+import type { DelegationLink, MeshAgentKind } from "./types.js";
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export interface DelegateChunk {
+  readonly text: string;
+  readonly done: boolean;
+  readonly agentKind?: MeshAgentKind;
+}
+
+export interface DelegateOptions {
+  /** Natural language description of the need. */
+  readonly need: string;
+  /** Optional structured or free-form context. Serialized to JSON if object. */
+  readonly context?: string | Record<string, unknown>;
+  /** Caller-requested capabilities (subject to attenuation if parentToken present). */
+  readonly capabilities?: ReadonlyArray<string>;
+  /** Wall-clock budget in ms. Default 30 000. */
+  readonly deadline_ms?: number;
+  /** Cost cap in EUR. Default 0.01. */
+  readonly max_cost_eur?: number;
+  /** Parent token — when present, child scope = parent ∩ requested capabilities. */
+  readonly parentToken?: AttenuatedToken;
+  /** Optional streaming callback. */
+  readonly onChunk?: (chunk: DelegateChunk) => void;
+  /** Optional pre-resolved kind — skips classifier. */
+  readonly kind?: MeshAgentKind;
+  /** Stable child agent identifier (for delegation chain audit). Default: random. */
+  readonly childId?: string;
+  /** MCP tool name (only when kind === "mcp-tool"). */
+  readonly toolName?: string;
+  /** MCP tool args (only when kind === "mcp-tool"). */
+  readonly toolArgs?: unknown;
+}
+
+export interface DelegateResult<T = string> {
+  readonly output: T;
+  readonly agentKind: MeshAgentKind;
+  readonly delegationChain: ReadonlyArray<DelegationLink>;
+  readonly costEur: number;
+  readonly durationMs: number;
+  readonly truncated: boolean;
+  /** Token issued to the child — empty when no parentToken given. */
+  readonly childToken?: AttenuatedToken;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+const DEFAULT_DEADLINE_MS = 30_000;
+const DEFAULT_MAX_COST_EUR = 0.01;
+const SELF_ID = "mesh:caller";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function stringifyContext(ctx?: string | Record<string, unknown>): string | undefined {
+  if (ctx === undefined) return undefined;
+  if (typeof ctx === "string") return ctx;
+  try {
+    return JSON.stringify(ctx);
+  } catch {
+    return String(ctx);
+  }
+}
+
+function isDispatcherWithClassify(
+  d: MeshDispatcher,
+): d is MeshDispatcher & { classify(need: string): MeshAgentKind } {
+  return typeof (d as { classify?: unknown }).classify === "function";
+}
+
+function generateChildId(): string {
+  // Tiny non-cryptographic id — child-id is for audit, not auth.
+  // Production: replace with ULID/UUID from caller env.
+  return `mesh-child-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e6).toString(36)}`;
+}
+
+/**
+ * Compute child scope from parent token + caller-requested capabilities.
+ * Returns the issued child token (parented to caller's parentId) and the
+ * effective MeshCapabilityScope (post-intersection).
+ */
+function issueChildToken(
+  parentToken: AttenuatedToken,
+  requestedCapabilities: ReadonlyArray<string> | undefined,
+  requestedBudgetEur: number,
+  childId: string,
+): { token: AttenuatedToken; scope: MeshCapabilityScope } {
+  const parentScope: MeshCapabilityScope = {
+    actions: parentToken.scope,
+    budgetEur: parentToken.budgetEur,
+    expiresAt: parentToken.expiresAt ? new Date(parentToken.expiresAt) : undefined,
+  };
+  const requestedScope: MeshCapabilityScope = {
+    actions: requestedCapabilities ?? parentToken.scope,
+    budgetEur: requestedBudgetEur,
+  };
+  const childScope = attenuateScope(parentScope, requestedScope);
+  const token = buildToken(childScope, childId);
+  return { token, scope: childScope };
+}
+
+// ─── Errors ──────────────────────────────────────────────────────────────────
+
+export class DelegateAttenuationError extends Error {
+  override readonly name = "DelegateAttenuationError";
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Delegate a need to the best available agent.
+ *
+ * Routing priority (when `kind` not pre-set):
+ *  1. Dispatcher's `classify(need)` hook if present.
+ *  2. Heuristic — see `defaultClassifier`.
+ *
+ * Capability attenuation:
+ *  - If `parentToken` is provided, child scope = parent ∩ requested.
+ *  - Empty intersection raises {@link DelegateAttenuationError}.
+ *
+ * Budget guards:
+ *  - When `parentToken.budgetEur < max_cost_eur`, the effective max is parent's.
+ *  - Negative budget or deadline → RangeError.
+ */
+export async function meshDelegate<T = string>(
+  options: DelegateOptions,
+  dispatcher: MeshDispatcher,
+): Promise<DelegateResult<T>> {
+  if (!options || typeof options.need !== "string" || options.need.length === 0) {
+    throw new TypeError("meshDelegate: `need` is required and must be a non-empty string");
+  }
+  if (!dispatcher || typeof dispatcher.dispatch !== "function") {
+    throw new TypeError("meshDelegate: `dispatcher` must implement MeshDispatcher");
+  }
+
+  const deadlineMs = options.deadline_ms ?? DEFAULT_DEADLINE_MS;
+  if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+    throw new RangeError(`meshDelegate: deadline_ms must be > 0, got ${deadlineMs}`);
+  }
+  let maxCostEur = options.max_cost_eur ?? DEFAULT_MAX_COST_EUR;
+  if (!Number.isFinite(maxCostEur) || maxCostEur < 0) {
+    throw new RangeError(`meshDelegate: max_cost_eur must be ≥ 0, got ${maxCostEur}`);
+  }
+
+  // ── 1. Classify ──────────────────────────────────────────────────────────
+  const kind: MeshAgentKind =
+    options.kind ??
+    (isDispatcherWithClassify(dispatcher) ? dispatcher.classify(options.need) : "llm-router");
+
+  // ── 2. Attenuation (if parent token given) ───────────────────────────────
+  const childId = options.childId ?? generateChildId();
+  let childToken: AttenuatedToken | undefined;
+  let effectiveScope: ReadonlyArray<string> | undefined;
+  if (options.parentToken) {
+    const issued = issueChildToken(options.parentToken, options.capabilities, maxCostEur, childId);
+    if (issued.scope.actions.length === 0 && (options.capabilities?.length ?? 0) > 0) {
+      throw new DelegateAttenuationError(
+        "meshDelegate: requested capabilities are not granted by parent scope",
+      );
+    }
+    childToken = issued.token;
+    effectiveScope = issued.scope.actions;
+    // Enforce parent budget cap.
+    maxCostEur = Math.min(maxCostEur, issued.scope.budgetEur);
+  } else if (options.capabilities) {
+    effectiveScope = options.capabilities;
+  }
+
+  // ── 3. Dispatch ──────────────────────────────────────────────────────────
+  const intent: DispatchIntent = {
+    kind,
+    need: options.need,
+    context: stringifyContext(options.context),
+    deadline_ms: deadlineMs,
+    max_cost_eur: maxCostEur,
+    toolName: options.toolName,
+    toolArgs: options.toolArgs,
+  };
+
+  const dispatched = await dispatcher.dispatch(intent);
+
+  // ── 4. Audit chain ───────────────────────────────────────────────────────
+  const parentIdForLink = options.parentToken?.parentId ?? SELF_ID;
+  const link: DelegationLink = {
+    from: parentIdForLink,
+    to: childId,
+    scope: effectiveScope ?? [],
+    budget: maxCostEur,
+  };
+
+  // ── 5. Stream (best-effort, single-shot when streaming not supported) ────
+  if (options.onChunk) {
+    options.onChunk({ text: dispatched.output, done: true, agentKind: kind });
+  }
+
+  const result: DelegateResult<T> = {
+    output: dispatched.output as unknown as T,
+    agentKind: kind,
+    delegationChain: [link],
+    costEur: dispatched.costEur,
+    durationMs: dispatched.durationMs,
+    truncated: dispatched.truncated,
+    childToken,
+  };
+  return result;
+}
+
+/**
+ * Factory variant — binds a dispatcher so callers can call `delegate(opts)`
+ * without re-passing the dispatcher every time.
+ *
+ * Useful for DI in long-lived services.
+ */
+export function createMeshDelegate(
+  dispatcher: MeshDispatcher,
+): <T = string>(options: DelegateOptions) => Promise<DelegateResult<T>> {
+  return <T = string>(options: DelegateOptions) => meshDelegate<T>(options, dispatcher);
+}
+
+/**
+ * Re-export DefaultMeshDispatcher as a convenience so callers can do:
+ *
+ *     import { meshDelegate, DefaultMeshDispatcher } from "@vauban-org/agent-sdk";
+ */
+export { DefaultMeshDispatcher };