aiden-runtime 4.0.1 → 4.1.0

package/dist/core/v4/skillMining/traceFingerprint.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/traceFingerprint.ts — Phase v4.1-skill-mining
+ *
+ * Deterministic content-addressing for tool-call traces.
+ *
+ * The fingerprint is the sha256 hex of the normalized
+ * (toolName, sorted-arg-keys) sequence joined by `|`.
+ *
+ * Properties (verified by smoke):
+ *   - identical traces produce identical hashes
+ *   - traces that differ only in arg *values* (same arg keys)
+ *     produce identical hashes — this is the desired behavior:
+ *     "search github for X" and "search github for Y" should
+ *     dedup to one candidate
+ *   - traces with different tool sequences or arg keys produce
+ *     different hashes
+ *   - deterministic across runs (no salt, no time)
+ *
+ * The candidateStore + skillMiner use this to dedup proposals;
+ * the rejected list also tracks fingerprints so a user-rejected
+ * workflow doesn't get re-proposed on the next run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceFingerprint = traceFingerprint;
+const node_crypto_1 = require("node:crypto");
+/** Normalize a single trace entry to its fingerprint contribution. */
+function normalizeEntry(entry) {
+    const name = String(entry.name ?? '').trim().toLowerCase();
+    let argKeys = [];
+    if (entry.args && typeof entry.args === 'object' && !Array.isArray(entry.args)) {
+        argKeys = Object.keys(entry.args).sort();
+    }
+    return `${name}(${argKeys.join(',')})`;
+}
+/**
+ * Fingerprint a trace. Returns a 64-char lowercase sha256 hex.
+ * Empty trace is a valid input (returns the hash of the empty
+ * normalized string) — callers should reject empty traces before
+ * fingerprinting to keep the pending queue free of useless entries.
+ */
+function traceFingerprint(trace) {
+    const normalized = trace.map(normalizeEntry).join('|');
+    return (0, node_crypto_1.createHash)('sha256').update(normalized, 'utf8').digest('hex');
+}

package/dist/core/v4/subagent/budget.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/budget.ts — Phase v4.1-subagent
+ *
+ * Per-subagent timeouts and iteration caps. Two budgets layered:
+ *
+ *   - `perSubagentTimeoutMs` — hard wall-clock cap on a single
+ *     subagent. Fired via AbortController; AidenAgent's provider
+ *     adapter receives the abort and the in-flight HTTP call is
+ *     cancelled (the v3 lesson — flag-only cancellation leaks
+ *     tokens, AbortController plumbed through is the v4 fix).
+ *
+ *   - `wallClockCapMs` — outer cap on the whole fanout. Defaults
+ *     to 5× the per-subagent timeout because parallel subagents
+ *     should finish faster than 5× one-at-a-time, but variance
+ *     (provider rate limits, retry backoff) can extend the tail.
+ *
+ *   - `maxIterations` — fresh per subagent. v3 starved nested
+ *     spawns by dividing a global budget; v4 hands each subagent a
+ *     full fresh budget and relies on the wall-clock cap for the
+ *     outer bound.
+ *
+ * Read at fanout start. Each subagent gets its own AbortSignal
+ * derived from the timeout; abort propagates from parent down via
+ * `parentAbort.aborted`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FANOUT_N = exports.MAX_FANOUT_N = exports.WALL_CLOCK_CAP_MULT = exports.DEFAULT_SUBAGENT_MAX_ITERATIONS = exports.DEFAULT_SUBAGENT_TIMEOUT_MS = void 0;
+exports.resolveBudget = resolveBudget;
+exports.validateN = validateN;
+/** Default per-subagent timeout (ms). Override via env
+ *  `AIDEN_SUBAGENT_TIMEOUT_MS` or `timeoutMs` argument on the tool. */
+exports.DEFAULT_SUBAGENT_TIMEOUT_MS = 90000;
+/** Default per-subagent iteration cap. Fresh per subagent. */
+exports.DEFAULT_SUBAGENT_MAX_ITERATIONS = 20;
+/** Wall-clock cap multiplier — outer cap = `perSubagentTimeoutMs * MULT`. */
+exports.WALL_CLOCK_CAP_MULT = 5;
+/** Max N — hard refuse beyond. */
+exports.MAX_FANOUT_N = 5;
+/** Default N when the caller doesn't specify. */
+exports.DEFAULT_FANOUT_N = 3;
+/** Resolve the live budget. Tool-call argument > env > module default. */
+function resolveBudget(opts = {}) {
+    const env = opts.env ?? process.env;
+    const envTimeoutRaw = env.AIDEN_SUBAGENT_TIMEOUT_MS;
+    const envTimeout = envTimeoutRaw && /^\d+$/.test(envTimeoutRaw)
+        ? Number.parseInt(envTimeoutRaw, 10)
+        : null;
+    const perSubagentTimeoutMs = opts.timeoutMs ?? envTimeout ?? exports.DEFAULT_SUBAGENT_TIMEOUT_MS;
+    return {
+        perSubagentTimeoutMs,
+        wallClockCapMs: perSubagentTimeoutMs * exports.WALL_CLOCK_CAP_MULT,
+        maxIterations: exports.DEFAULT_SUBAGENT_MAX_ITERATIONS,
+    };
+}
+/** Validate the requested N — throws with a clear message when out of
+ *  bounds. Caller surfaces the error as a tool-result error string. */
+function validateN(n) {
+    if (!Number.isFinite(n) || !Number.isInteger(n)) {
+        throw new Error(`subagent_fanout: n must be an integer, got ${n}`);
+    }
+    if (n < 1) {
+        throw new Error(`subagent_fanout: n must be >= 1, got ${n}`);
+    }
+    if (n > exports.MAX_FANOUT_N) {
+        throw new Error(`subagent_fanout: n=${n} exceeds hard cap ${exports.MAX_FANOUT_N}. ` +
+            `Higher concurrency hits provider RPM limits and increases tail latency variance.`);
+    }
+    return n;
+}

package/dist/core/v4/subagent/diagnostics.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/diagnostics.ts — Phase v4.1-subagent
+ *
+ * Build fingerprint + counts surfaced by `aiden subagent status` and
+ * the per-fanout result envelope. The fingerprint follows the same
+ * convention every Aiden phase since v4.1-3.2 has used: a constant
+ * string the user can grep for to verify the running build matches
+ * the phase they expected. Bump on every shipped phase. Format:
+ * `v4.1-subagent[+suffix]`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIDEN_SUBAGENT_BUILD = void 0;
+/** Build fingerprint — bump per phase. Surfaced in `aiden subagent
+ *  status` and the post-fanout summary line. */
+exports.AIDEN_SUBAGENT_BUILD = 'v4.1-subagent.2';

package/dist/core/v4/subagent/fanout.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/fanout.ts — Phase v4.1-subagent
+ *
+ * Parallel-agent orchestrator. Spawn N children against the same
+ * problem (or a partition), enforce per-child timeouts and an outer
+ * wall-clock cap, then merge results via the chosen strategy.
+ *
+ * Design constraints (locked from recon):
+ *
+ *   - In-process `Promise.all` over N children. No child processes,
+ *     no MCP-spawn (Aiden's MCP server is for external clients).
+ *   - Per-child AbortSignal derived from a parent signal + timeout.
+ *     Aborts cascade — parent abort kills every child mid-flight via
+ *     the provider's own HTTP AbortController.
+ *   - Each child gets:
+ *       * own session ID (UUID) — sessions never collide
+ *       * own provider rotation slot
+ *       * own cloned FallbackAdapter when applicable (mutable rate-
+ *         limit state isolated per child)
+ *       * fresh max_iterations (no v3-style budget halving)
+ *   - Shared (read-only) across children:
+ *       * tool registry, skill loader, paths, memoryManager
+ *
+ * Hot blockers from the recon are addressed by the caller:
+ *   - browser bridge: caller wraps browser tool dispatch in
+ *     `withPwLock` (see core/playwrightBridge.ts)
+ *   - approval engine: caller passes a ToolContext with
+ *     `approvalEngine` undefined (no prompts in subagents)
+ *   - destructive tool exposure: caller filters the schemas array
+ *     based on `AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE`
+ *
+ * The orchestrator itself is INTENTIONALLY decoupled from
+ * AidenAgent — it takes a `runChild` callback that knows how to run
+ * one subagent. The tool wrapper at tools/v4/subagent/subagentFanout
+ * supplies the production callback (which constructs an AidenAgent);
+ * tests inject a stub that returns canned strings without any
+ * provider plumbing. This is what made the offline smoke tractable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFanout = runFanout;
+const node_crypto_1 = require("node:crypto");
+const factory_1 = require("../logger/factory");
+const budget_1 = require("./budget");
+const providerRotation_1 = require("./providerRotation");
+const merger_1 = require("./merger");
+const diagnostics_1 = require("./diagnostics");
+// ── Orchestrator ─────────────────────────────────────────────────────────
+async function runFanout(opts) {
+    const logger = (opts.logger ?? (0, factory_1.noopLogger)()).child('subagent');
+    const now = opts.now ?? Date.now;
+    // ── Pre-flight validation ─────────────────────────────────────
+    (0, budget_1.validateN)(opts.n);
+    if (opts.mode === 'ensemble' && !opts.query) {
+        throw new Error('subagent_fanout: ensemble mode requires a `query`');
+    }
+    if (opts.mode === 'partition') {
+        if (!opts.tasks || opts.tasks.length === 0) {
+            throw new Error('subagent_fanout: partition mode requires `tasks[]`');
+        }
+        if (opts.tasks.length !== opts.n) {
+            throw new Error(`subagent_fanout: partition tasks.length (${opts.tasks.length}) ` +
+                `must equal n (${opts.n})`);
+        }
+    }
+    if (opts.providers.length === 0) {
+        throw new Error('subagent_fanout: no providers available — cannot fan out');
+    }
+    const budget = (0, budget_1.resolveBudget)({ timeoutMs: opts.timeoutMs });
+    const rotation = (0, providerRotation_1.rotateProviders)(opts.n, opts.providers);
+    if (rotation.singleProviderWarning) {
+        logger.warn('subagent_fanout: single-provider fanout — diversity ≈ temperature variation', {
+            providers: opts.providers.length,
+            n: opts.n,
+        });
+    }
+    logger.info('subagent_fanout: launching', {
+        build: diagnostics_1.AIDEN_SUBAGENT_BUILD,
+        mode: opts.mode,
+        n: opts.n,
+        merge: opts.merge,
+        perSubagentTimeoutMs: budget.perSubagentTimeoutMs,
+        wallClockCapMs: budget.wallClockCapMs,
+    });
+    // ── Spawn ─────────────────────────────────────────────────────
+    const startedAt = now();
+    const wallController = new AbortController();
+    const wallTimer = setTimeout(() => wallController.abort(), budget.wallClockCapMs);
+    // Forward parent abort to the wall controller so it cascades.
+    const parentAbortHandler = () => wallController.abort();
+    if (opts.parentAbort) {
+        if (opts.parentAbort.aborted)
+            wallController.abort();
+        else
+            opts.parentAbort.addEventListener('abort', parentAbortHandler, { once: true });
+    }
+    const children = [];
+    for (let i = 0; i < opts.n; i += 1) {
+        const provider = rotation.assignments[i];
+        const prompt = opts.mode === 'ensemble'
+            ? opts.query
+            : buildPartitionPrompt(opts.tasks[i]);
+        const role = opts.mode === 'partition' ? opts.tasks[i].role : undefined;
+        children.push(spawnOne({
+            index: i,
+            prompt,
+            role,
+            provider,
+            maxIterations: budget.maxIterations,
+            perTimeoutMs: budget.perSubagentTimeoutMs,
+            wallSignal: wallController.signal,
+            runChild: opts.runChild,
+            logger: logger.child(`#${i}:${provider.providerId}`),
+            now,
+        }));
+    }
+    const results = await Promise.all(children);
+    clearTimeout(wallTimer);
+    if (opts.parentAbort) {
+        opts.parentAbort.removeEventListener('abort', parentAbortHandler);
+    }
+    const totalMs = now() - startedAt;
+    // ── Merge ─────────────────────────────────────────────────────
+    const merge = await (0, merger_1.mergeResults)(results, {
+        strategy: opts.merge,
+        aggregatorAdapter: opts.aggregatorAdapter,
+        aggregatorModel: opts.aggregatorModel,
+        userQuery: opts.mode === 'ensemble'
+            ? opts.query
+            : opts.tasks.map((t, i) => `(${i + 1}) ${t.goal}`).join('\n'),
+        logger,
+        signal: wallController.signal,
+    });
+    // ── Diagnostics ───────────────────────────────────────────────
+    const diagnostics = {
+        build: diagnostics_1.AIDEN_SUBAGENT_BUILD,
+        launched: opts.n,
+        succeeded: results.filter((r) => !r.error && r.output.length > 0).length,
+        failed: results.filter((r) => !!r.error || r.output.length === 0).length,
+        totalMs,
+        perSubagentMs: results.map((r) => r.elapsedMs),
+        providerDistribution: results.map((r) => r.providerId),
+        singleProviderWarning: rotation.singleProviderWarning,
+        aggregator: merge.aggregator,
+    };
+    logger.info('subagent_fanout: complete', {
+        succeeded: diagnostics.succeeded,
+        failed: diagnostics.failed,
+        totalMs,
+        aggregator: merge.aggregator || '(none)',
+    });
+    return { results, merged: merge.merged, diagnostics };
+}
+async function spawnOne(args) {
+    const startedAt = args.now();
+    // Per-child controller, aborted on wall-cap OR per-child timeout.
+    const childController = new AbortController();
+    const timer = setTimeout(() => childController.abort(), args.perTimeoutMs);
+    const wallHandler = () => childController.abort();
+    if (args.wallSignal.aborted)
+        childController.abort();
+    else
+        args.wallSignal.addEventListener('abort', wallHandler, { once: true });
+    const id = (0, node_crypto_1.randomUUID)();
+    args.logger.info('child: spawned', {
+        id,
+        provider: `${args.provider.providerId}:${args.provider.modelId}`,
+        role: args.role,
+        timeoutMs: args.perTimeoutMs,
+    });
+    let output = '';
+    let error;
+    try {
+        output = await args.runChild({
+            index: args.index,
+            prompt: args.prompt,
+            role: args.role,
+            provider: args.provider,
+            signal: childController.signal,
+            maxIterations: args.maxIterations,
+            logger: args.logger,
+        });
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+        if (childController.signal.aborted) {
+            error = `aborted (timeout=${args.perTimeoutMs}ms or parent abort): ${error}`;
+        }
+        args.logger.warn('child: errored', { error });
+    }
+    finally {
+        clearTimeout(timer);
+        args.wallSignal.removeEventListener('abort', wallHandler);
+    }
+    const elapsedMs = args.now() - startedAt;
+    args.logger.info('child: done', { elapsedMs, ok: !error && output.length > 0 });
+    return {
+        index: args.index,
+        providerId: args.provider.providerId,
+        modelId: args.provider.modelId,
+        output: error ? '' : output,
+        error,
+        elapsedMs,
+    };
+}
+function buildPartitionPrompt(task) {
+    const role = task.role ? `Role: ${task.role}\n` : '';
+    const context = task.context ? `\nContext:\n${task.context}\n` : '';
+    return `${role}Goal: ${task.goal}${context}`;
+}

package/dist/core/v4/subagent/merger.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/merger.ts — Phase v4.1-subagent
+ *
+ * Combine N subagent outputs into one (or zero) aggregator response.
+ * Four strategies, each with a different cost shape — the tool's
+ * description surfaces this so the calling LLM picks knowingly:
+ *
+ *   - 'all'        — return raw N results, no aggregator call. FREE.
+ *                    Caller's parent agent reads them in its own
+ *                    next turn (the partition pattern).
+ *   - 'vote'       — LLM judge picks ONE result verbatim. +1 call.
+ *   - 'pick-best'  — LLM judge picks one with reasoning. +1 call.
+ *                    Same wire shape as 'vote', different prompt.
+ *   - 'combine'    — LLM synthesizes N results into one answer.
+ *                    +1 call (the ensemble pattern).
+ *
+ * The aggregator uses the parent's active provider+model by default,
+ * env override `AIDEN_SUBAGENT_AGGREGATOR_MODEL` (provider:model
+ * format, e.g. `groq:llama-3.3-70b-versatile`) when the user wants
+ * to control aggregator cost without affecting subagent fanout.
+ *
+ * The aggregator call is intentionally THIN — single-shot, no tools,
+ * no agent loop. It's a text-in / text-out pass over the N results
+ * with a strategy-specific system prompt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAggregatorOverride = resolveAggregatorOverride;
+exports.mergeResults = mergeResults;
+const factory_1 = require("../logger/factory");
+/** Resolve env override for aggregator model. Returns null when unset
+ *  or malformed; caller falls back to parent's active model. */
+function resolveAggregatorOverride(env = process.env) {
+    const raw = env.AIDEN_SUBAGENT_AGGREGATOR_MODEL?.trim();
+    if (!raw)
+        return null;
+    const colon = raw.indexOf(':');
+    if (colon < 1 || colon === raw.length - 1)
+        return null;
+    const providerId = raw.slice(0, colon).trim();
+    const modelId = raw.slice(colon + 1).trim();
+    if (!providerId || !modelId)
+        return null;
+    return { providerId, modelId };
+}
+/** Apply the strategy. Logs every aggregator call for observability. */
+async function mergeResults(results, opts) {
+    const logger = opts.logger ?? (0, factory_1.noopLogger)();
+    if (opts.strategy === 'all') {
+        return { merged: null, aggregator: '' };
+    }
+    // Filter out failures — aggregator only sees usable outputs.
+    const usable = results.filter((r) => !r.error && r.output.length > 0);
+    if (usable.length === 0) {
+        return {
+            merged: '[Aggregator: every subagent failed — no output to merge]',
+            aggregator: '',
+        };
+    }
+    const aggregatorLabel = `${opts.aggregatorModel.providerId}:${opts.aggregatorModel.modelId}`;
+    const systemPrompt = buildSystemPrompt(opts.strategy);
+    const userPrompt = buildUserPrompt(opts.strategy, usable, opts.userQuery);
+    const messages = [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt },
+    ];
+    logger.info('subagent merge: aggregator dispatching', {
+        scope: 'subagent',
+        strategy: opts.strategy,
+        aggregator: aggregatorLabel,
+        sources: usable.length,
+    });
+    try {
+        const out = await opts.aggregatorAdapter.call({
+            messages,
+            tools: [],
+            stream: false,
+        });
+        const text = extractFinalText(out);
+        return { merged: text, aggregator: aggregatorLabel };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn('subagent merge: aggregator failed', {
+            scope: 'subagent',
+            strategy: opts.strategy,
+            error: message,
+        });
+        // Graceful degrade: return the first usable subagent output rather
+        // than crash the whole fanout. Caller sees `aggregator === ''`
+        // and a synthetic merged note.
+        return {
+            merged: `[Aggregator failed: ${message}]\n\n${usable[0].output}`,
+            aggregator: '',
+        };
+    }
+}
+function buildSystemPrompt(strategy) {
+    switch (strategy) {
+        case 'vote':
+            return [
+                'You are an answer-selection judge. You will be shown a user query and N candidate answers from independent agents.',
+                'Pick exactly ONE candidate that best answers the query and return ITS TEXT VERBATIM with no preamble, no commentary, no formatting changes.',
+                'Choose the answer that is most factually accurate, complete, and directly addresses the query.',
+            ].join(' ');
+        case 'pick-best':
+            return [
+                'You are an answer-selection judge. You will be shown a user query and N candidate answers from independent agents.',
+                'Pick the BEST candidate. Output a one-sentence reason on the first line, then a blank line, then the chosen candidate text verbatim.',
+                'Format:\nReason: <one sentence>\n\n<chosen candidate verbatim>',
+            ].join(' ');
+        case 'combine':
+            return [
+                'You are a synthesis aggregator. You will be shown a user query and N candidate answers from independent agents.',
+                'Produce ONE unified answer that integrates the strongest points from each candidate.',
+                'Resolve disagreements by stating both positions when sources diverge factually; collapse redundancy where they agree.',
+                'Do not name the candidates. Speak directly. No meta-commentary about being an aggregator.',
+            ].join(' ');
+        default:
+            return 'You are a helpful assistant.';
+    }
+}
+function buildUserPrompt(strategy, results, query) {
+    const blocks = results.map((r, i) => `--- CANDIDATE ${i + 1} (${r.providerId}:${r.modelId}) ---\n${r.output.trim()}`).join('\n\n');
+    const action = strategy === 'combine'
+        ? 'Synthesize these into one unified answer.'
+        : strategy === 'pick-best'
+            ? 'Pick the best candidate.'
+            : 'Pick the best candidate verbatim.';
+    return `USER QUERY:\n${query}\n\n${blocks}\n\n${action}`;
+}
+function extractFinalText(out) {
+    // ProviderCallOutput.content is `string | null` per providers/v4/types.ts.
+    // For a single-shot non-streaming aggregator call we expect the model
+    // to return text directly with `finishReason: 'stop'`.
+    if (out && typeof out === 'object') {
+        const o = out;
+        if (typeof o.content === 'string' && o.content.length > 0)
+            return o.content;
+    }
+    return '';
+}

package/dist/core/v4/subagent/providerRotation.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/providerRotation.ts — Phase v4.1-subagent
+ *
+ * Round-robin provider selection across N subagents. v3's lesson —
+ * "N samples from one provider is `temperature` with extra steps" —
+ * makes provider diversity load-bearing for fanout. This module
+ * decides which provider each subagent uses.
+ *
+ * Two layers:
+ *
+ *   1. If multiple providers are configured (i.e. multiple keys
+ *      across distinct providerIds), round-robin across them.
+ *   2. If only one provider is configured, fall back to round-robin
+ *      across the slots WITHIN that provider (Groq slot 1/2/3/4,
+ *      Together primary/fallback). Diversity reduces to temperature
+ *      variation; the diagnostics flag this with
+ *      `singleProviderWarning: true`.
+ *
+ * The module does NOT build adapters — it picks PROVIDER IDS and
+ * leaves adapter construction to the caller (which knows how to
+ * resolve a credential / clone a FallbackAdapter / etc).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rotateProviders = rotateProviders;
+/**
+ * Pick a provider for each of `n` subagents. `available` is the list
+ * of configured options the caller has resolved; ordering matters
+ * (the first becomes the primary fallback when round-robin wraps).
+ *
+ * The function is deterministic given the same inputs — useful for
+ * tests and for users debugging "why did subagent 3 hit Together?".
+ */
+function rotateProviders(n, available) {
+    if (available.length === 0) {
+        throw new Error('subagent_fanout: no providers available for rotation');
+    }
+    if (n < 1) {
+        throw new Error(`subagent_fanout: n must be >= 1, got ${n}`);
+    }
+    const distinct = new Set(available.map((o) => o.providerId));
+    const singleProviderWarning = distinct.size < 2;
+    const assignments = [];
+    for (let i = 0; i < n; i += 1) {
+        assignments.push(available[i % available.length]);
+    }
+    return { assignments, singleProviderWarning };
+}