aiden-runtime 4.0.2 → 4.1.1

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 };
+}