@kernel.chat/kbot 4.0.1 → 4.1.1

package/dist/futures/forecast/synthesize.js

@@ -0,0 +1,89 @@
+// futures/forecast/synthesize — fan a list of Signals into Forecasts and
+// produce human-readable summaries. Pure formatting; no IO.
+import { bestProjection, clampHorizon, signalHistory } from './projection.js';
+/**
+ * Project every signal forward at the given horizon. Skips signals whose
+ * history is too short for the horizon (clampHorizon = false). Returns
+ * forecasts sorted by absolute slope descending so the most-moving signals
+ * surface first.
+ */
+export function synthesizeForecasts(signals, horizon) {
+    const out = [];
+    for (const sig of signals) {
+        if (!clampHorizon(horizon, signalHistory(sig)))
+            continue;
+        out.push(bestProjection(sig, horizon));
+    }
+    out.sort((a, b) => Math.abs(b.trend.slope) - Math.abs(a.trend.slope));
+    return out;
+}
+function formatNumber(n) {
+    if (!Number.isFinite(n))
+        return '—';
+    const abs = Math.abs(n);
+    if (abs >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (abs >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`.replace('.0k', 'k');
+    if (abs >= 10)
+        return n.toFixed(0);
+    if (abs >= 1)
+        return n.toFixed(1);
+    return n.toFixed(2);
+}
+const HORIZON_LABEL = {
+    '1d': 'in 1 day',
+    '7d': 'in 7 days',
+    '30d': 'in 30 days',
+    '90d': 'in 90 days',
+};
+const ARROW = {
+    up: '📈',
+    down: '📉',
+    flat: '➖',
+};
+function arrowFor(slope, kind) {
+    if (kind === 'flat')
+        return ARROW.flat;
+    if (slope > 0)
+        return ARROW.up;
+    if (slope < 0)
+        return ARROW.down;
+    return ARROW.flat;
+}
+/**
+ * Markdown one-liner for a forecast.
+ * Example: `📈 npm downloads → 14.2k (in 30 days, linear, r²=0.78, ±890)`
+ */
+export function formatForecast(f) {
+    const arrow = arrowFor(f.trend.slope, f.trend.kind);
+    const point = formatNumber(f.pointEstimate);
+    const halfWidth = (f.upperBound - f.lowerBound) / 2;
+    const interval = Number.isFinite(halfWidth) ? `±${formatNumber(halfWidth)}` : '±?';
+    const r2Str = f.trend.kind === 'flat' ? 'flat' : `${f.trend.kind}, r²=${f.trend.r2.toFixed(2)}`;
+    return `${arrow} ${f.signal} → ${point} (${HORIZON_LABEL[f.horizon]}, ${r2Str}, ${interval})`;
+}
+/**
+ * Take a list of forecasts and produce a short paragraph naming the top-3
+ * by absolute slope. If empty, returns a polite no-data sentence.
+ */
+export function narrative(forecasts) {
+    if (forecasts.length === 0) {
+        return 'No forecasts available — not enough signal history to project.';
+    }
+    const top = forecasts.slice(0, 3);
+    const phrases = [];
+    for (const f of top) {
+        const direction = f.trend.kind === 'flat'
+            ? 'is holding flat'
+            : f.trend.slope > 0
+                ? 'is trending up'
+                : 'is trending down';
+        const point = formatNumber(f.pointEstimate);
+        const conf = `${(f.confidence * 100).toFixed(0)}% conf`;
+        phrases.push(`${f.signal} ${direction} toward ${point} ${HORIZON_LABEL[f.horizon]} (${conf})`);
+    }
+    const head = phrases.length === 1 ? phrases[0] : phrases.slice(0, -1).join('; ') + '; and ' + phrases[phrases.length - 1];
+    return `Top movers: ${head}.`;
+}
+//# sourceMappingURL=synthesize.js.map

package/dist/futures/forecast/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A time series. Timestamps are ms since epoch (matches Date.now()).
+ * Values are arbitrary scalars (counts, percentages, etc.).
+ * Order is not required; projection.ts sorts internally.
+ */
+export interface Signal {
+    name: string;
+    values: Array<{
+        ts: number;
+        value: number;
+    }>;
+}
+/**
+ * Trend describes the shape of the fit chosen for a Signal.
+ * - 'linear'      : value ~ a + b*t            (slope = b in value/ms)
+ * - 'exponential' : value ~ exp(a + b*t)       (slope = b in log(value)/ms)
+ * - 'flat'        : low-variance fallback; slope == 0, r2 == 0
+ *
+ * r2 is the coefficient of determination on whatever space was fit
+ * (raw values for linear, log(values) for exponential).
+ */
+export interface Trend {
+    kind: 'linear' | 'exponential' | 'flat';
+    slope: number;
+    r2: number;
+}
+/**
+ * Projection horizon. Always relative to the last observed timestamp.
+ * 1d/7d/30d/90d cover the practical surface (daily through quarterly).
+ */
+export type Horizon = '1d' | '7d' | '30d' | '90d';
+/**
+ * A single forecast for a single signal at a single horizon.
+ *
+ * - pointEstimate is the model's expected value at horizon end
+ * - lowerBound / upperBound is roughly a 95% interval
+ *   (point ± 2 * residual stddev, exp-transformed for exponential fits)
+ * - confidence is a 0..1 score derived from r2 and history length;
+ *   higher means "trust this projection more"
+ * - method is a short human-readable tag, e.g. "linear-lsq", "exp-loglin",
+ *   "flat-mean"
+ */
+export interface Forecast {
+    signal: string;
+    horizon: Horizon;
+    trend: Trend;
+    pointEstimate: number;
+    lowerBound: number;
+    upperBound: number;
+    confidence: number;
+    method: string;
+}
+/**
+ * Number of milliseconds in each horizon. Exported as a const for use by
+ * projection.ts and synthesize.ts; not exported as a value-typed enum so
+ * callers can keep using string literals.
+ */
+export declare const HORIZON_MS: Record<Horizon, number>;
+//# sourceMappingURL=types.d.ts.map

package/dist/futures/forecast/types.js

@@ -0,0 +1,15 @@
+// futures/forecast — type definitions for projecting growth/research signals
+// forward in time. Pure types: no runtime, no IO. Consumers (synthesize.ts,
+// projection.ts) build Forecasts from raw Signal arrays.
+/**
+ * Number of milliseconds in each horizon. Exported as a const for use by
+ * projection.ts and synthesize.ts; not exported as a value-typed enum so
+ * callers can keep using string literals.
+ */
+export const HORIZON_MS = {
+    '1d': 24 * 60 * 60 * 1000,
+    '7d': 7 * 24 * 60 * 60 * 1000,
+    '30d': 30 * 24 * 60 * 60 * 1000,
+    '90d': 90 * 24 * 60 * 60 * 1000,
+};
+//# sourceMappingURL=types.js.map

package/dist/futures/harness/critic-evaluator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * CriticEvaluator — adapts `critic-gate.ts` to the harness `Evaluator`
+ * interface from `types.ts`.
+ *
+ * critic-gate.ts gates a single tool result. The harness Evaluator grades
+ * an entire trace against a Task's acceptance criteria. This adapter
+ * walks the trace's tool steps, runs each through `gateToolResult`, and
+ * aggregates the per-step verdicts into a single EvaluationReport:
+ *
+ *   - `pass`    = every acceptance criterion satisfied AND no critic rejected
+ *                 a tool step
+ *   - `score`   = (criteriaPassRate * 0.7) + (toolAcceptRate * 0.3),
+ *                 efficiency-tiebroken by total step time
+ *   - failureModes derived from critic verdicts' `failure_class` (RF-NN-*)
+ *
+ * Acceptance criteria are matched via case-insensitive substring against
+ * the trace's flattened `output | error | finalState | action` text.
+ * That keeps the adapter dependency-free; richer matchers can subclass.
+ *
+ * critic-gate.ts is NOT modified — this is a pure consumer.
+ */
+import type { EvaluationReport, Evaluator, ExecutionTrace, Task } from './types.js';
+import type { CriticVerdict, GateOpts } from '../../critic-gate.js';
+export interface CriticEvaluatorOpts {
+    /** Forwarded to `gateToolResult` — strictness, provider, llmClient stub. */
+    gate?: GateOpts;
+    /**
+     * If set, replaces `gateToolResult`. Lets tests inject a fully synchronous
+     * decision function and skip the critic-gate provider plumbing entirely.
+     */
+    gateFn?: (tool: string, args: Record<string, unknown>, result: unknown) => Promise<CriticVerdict> | CriticVerdict;
+}
+export declare class CriticEvaluator implements Evaluator {
+    private readonly opts;
+    constructor(opts?: CriticEvaluatorOpts);
+    evaluate(trace: ExecutionTrace, task: Task): Promise<EvaluationReport>;
+}
+export declare function createCriticEvaluator(opts?: CriticEvaluatorOpts): Evaluator;
+//# sourceMappingURL=critic-evaluator.d.ts.map

package/dist/futures/harness/critic-evaluator.js

@@ -0,0 +1,131 @@
+/**
+ * CriticEvaluator — adapts `critic-gate.ts` to the harness `Evaluator`
+ * interface from `types.ts`.
+ *
+ * critic-gate.ts gates a single tool result. The harness Evaluator grades
+ * an entire trace against a Task's acceptance criteria. This adapter
+ * walks the trace's tool steps, runs each through `gateToolResult`, and
+ * aggregates the per-step verdicts into a single EvaluationReport:
+ *
+ *   - `pass`    = every acceptance criterion satisfied AND no critic rejected
+ *                 a tool step
+ *   - `score`   = (criteriaPassRate * 0.7) + (toolAcceptRate * 0.3),
+ *                 efficiency-tiebroken by total step time
+ *   - failureModes derived from critic verdicts' `failure_class` (RF-NN-*)
+ *
+ * Acceptance criteria are matched via case-insensitive substring against
+ * the trace's flattened `output | error | finalState | action` text.
+ * That keeps the adapter dependency-free; richer matchers can subclass.
+ *
+ * critic-gate.ts is NOT modified — this is a pure consumer.
+ */
+import { gateToolResult } from '../../critic-gate.js';
+/** Map RF taxonomy classes onto harness FailureMode kinds. */
+function rfToFailureKind(rf) {
+    switch (rf) {
+        case 'RF-01-fabricated-evidence':
+        case 'RF-10-simulation-role-confusion':
+            return 'hallucinated-state';
+        case 'RF-02-metric-interpretation':
+        case 'RF-03-confused-provenance':
+        case 'RF-04-temporal-misordering':
+            return 'misinterpreted-state';
+        case 'RF-12-repetition-failure-to-resume':
+            return 'reasoning-loop';
+        case 'RF-08-evidential-insufficiency':
+        case 'RF-11-excessive-speculation':
+            return 'missing-capability';
+        case 'RF-16-arithmetic-error':
+        case 'RF-14-invalid-inference-pattern':
+        case 'RF-15-internal-contradiction':
+            return 'incorrect-tool-usage';
+        default:
+            return 'other';
+    }
+}
+function flattenTrace(trace) {
+    const parts = [];
+    for (const s of trace.steps) {
+        if (s.action)
+            parts.push(s.action);
+        if (s.output)
+            parts.push(s.output);
+        if (s.error)
+            parts.push(s.error);
+    }
+    try {
+        parts.push(JSON.stringify(trace.finalState));
+    }
+    catch {
+        /* ignore unserializable */
+    }
+    return parts.join('\n');
+}
+export class CriticEvaluator {
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async evaluate(trace, task) {
+        const haystack = flattenTrace(trace).toLowerCase();
+        const criteriaResults = task.acceptance.map((criterion) => {
+            const passed = haystack.includes(criterion.toLowerCase());
+            return {
+                criterion,
+                passed,
+                evidence: passed ? 'substring match in trace' : 'no match in flattened trace',
+            };
+        });
+        const criteriaPassRate = criteriaResults.length === 0
+            ? 1
+            : criteriaResults.filter((c) => c.passed).length / criteriaResults.length;
+        // Run critic on each tool step. Missing tools / responses are skipped.
+        const toolSteps = trace.steps.filter((s) => s.phase === 'tool');
+        const failureModes = [];
+        let toolAccepts = 0;
+        for (const step of toolSteps) {
+            const verdict = this.opts.gateFn
+                ? await this.opts.gateFn(step.action, {}, step.output ?? step.error ?? '')
+                : await gateToolResult(step.action, {}, step.output ?? step.error ?? '', this.opts.gate);
+            if (verdict.accept) {
+                toolAccepts++;
+            }
+            else if (verdict.failure_class) {
+                failureModes.push({
+                    kind: rfToFailureKind(verdict.failure_class),
+                    detail: `${verdict.failure_class}: ${verdict.reason || 'critic rejected'}`,
+                });
+            }
+            else {
+                failureModes.push({
+                    kind: 'other',
+                    detail: verdict.reason || 'critic rejected without failure class',
+                });
+            }
+        }
+        const toolAcceptRate = toolSteps.length === 0 ? 1 : toolAccepts / toolSteps.length;
+        const baseScore = criteriaPassRate * 0.7 + toolAcceptRate * 0.3;
+        // Efficiency tiebreaker: small bonus inversely proportional to time.
+        const totalMs = trace.llmTimeMs + trace.toolTimeMs;
+        const efficiency = totalMs > 0 ? Math.min(0.05, 1000 / (totalMs + 1000) * 0.05) : 0.05;
+        const score = Math.max(0, Math.min(1, baseScore + efficiency));
+        const allCriteriaPass = criteriaResults.every((c) => c.passed);
+        const noToolRejections = failureModes.length === 0;
+        const pass = allCriteriaPass && noToolRejections;
+        return {
+            taskId: task.id,
+            harnessId: trace.harnessId,
+            pass,
+            score,
+            criteriaResults,
+            failureModes,
+            notes: pass
+                ? 'all criteria passed; critic accepted every tool step'
+                : `pass=${pass} criteria=${criteriaPassRate.toFixed(2)} tools=${toolAcceptRate.toFixed(2)}`,
+        };
+    }
+}
+export function createCriticEvaluator(opts = {}) {
+    return new CriticEvaluator(opts);
+}
+//# sourceMappingURL=critic-evaluator.js.map

package/dist/futures/harness/evolution-loop.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Harness Evolution Loop — inner loop (Algorithm 1 from Sylph).
+ *
+ *   for i in 1..maxIterations:
+ *     trace   = Worker.execute(task, harness)
+ *     report  = Evaluator.evaluate(trace, task)
+ *     record  = { iteration, harness, trace, report, verdict }
+ *     history.push(record)
+ *     if report.score > bestScore: best = harness
+ *     if earlyStopScore reached on consecutive iterations: stop
+ *     if regression > revertThreshold: revert harness to best
+ *     harness = EvolutionAgent.evolve(history, best)
+ *
+ * Pure orchestration — Worker / Evaluator / EvolutionAgent are injected,
+ * which makes the whole loop deterministic and testable with stub
+ * implementations. No LLM calls happen here directly.
+ */
+import type { EvolutionProtocol, EvolutionRecord, EvolutionResult, Task } from './types.js';
+/** Optional hooks the caller can plug in to observe / persist each step. */
+export interface RunOptions {
+    /** Called after each record is appended to in-memory history. */
+    onRecord?: (record: EvolutionRecord) => void | Promise<void>;
+    /** When set, `appendTrace` is invoked under this state dir for every record. */
+    persistDir?: string;
+    /** When false, skip filesystem persistence even if `persistDir` is set. Default true. */
+    persist?: boolean;
+    /**
+     * How many consecutive iterations must hit `earlyStopScore` to stop.
+     * Defaults to 1 — first hit ends the loop.
+     */
+    earlyStopStreak?: number;
+}
+/**
+ * Run the inner Harness Evolution Loop against a single task.
+ *
+ * Always returns an `EvolutionResult` — never throws on Worker / Evaluator
+ * exceptions; instead, records a failure step and continues. (The
+ * Evaluator is supposed to score failures, not the loop itself.)
+ */
+export declare function runEvolutionLoop(protocol: EvolutionProtocol, task: Task, options?: RunOptions): Promise<EvolutionResult>;
+//# sourceMappingURL=evolution-loop.d.ts.map

package/dist/futures/harness/evolution-loop.js

@@ -0,0 +1,168 @@
+/**
+ * Harness Evolution Loop — inner loop (Algorithm 1 from Sylph).
+ *
+ *   for i in 1..maxIterations:
+ *     trace   = Worker.execute(task, harness)
+ *     report  = Evaluator.evaluate(trace, task)
+ *     record  = { iteration, harness, trace, report, verdict }
+ *     history.push(record)
+ *     if report.score > bestScore: best = harness
+ *     if earlyStopScore reached on consecutive iterations: stop
+ *     if regression > revertThreshold: revert harness to best
+ *     harness = EvolutionAgent.evolve(history, best)
+ *
+ * Pure orchestration — Worker / Evaluator / EvolutionAgent are injected,
+ * which makes the whole loop deterministic and testable with stub
+ * implementations. No LLM calls happen here directly.
+ */
+import { appendTrace } from './persistence.js';
+function compareVerdict(prev, current, revertThreshold) {
+    if (current > prev)
+        return 'improved';
+    if (current === prev)
+        return 'no-op';
+    if (revertThreshold !== undefined && (prev - current) >= revertThreshold) {
+        // A "regressed" verdict signals the loop should revert to best harness.
+        return 'regressed';
+    }
+    return 'regressed';
+}
+/**
+ * Run the inner Harness Evolution Loop against a single task.
+ *
+ * Always returns an `EvolutionResult` — never throws on Worker / Evaluator
+ * exceptions; instead, records a failure step and continues. (The
+ * Evaluator is supposed to score failures, not the loop itself.)
+ */
+export async function runEvolutionLoop(protocol, task, options = {}) {
+    const { worker, evaluator, evolution, initialHarness, hyperparams } = protocol;
+    const maxIterations = Math.max(1, hyperparams.maxIterations | 0);
+    const earlyStopScore = hyperparams.earlyStopScore;
+    const revertThreshold = hyperparams.revertThreshold;
+    const earlyStopStreak = Math.max(1, options.earlyStopStreak ?? 1);
+    const shouldPersist = options.persist !== false && !!options.persistDir;
+    const history = [];
+    let harness = initialHarness;
+    let bestHarness = initialHarness;
+    let bestScore = -Infinity;
+    let prevScore = -Infinity;
+    let earlyHits = 0;
+    for (let iteration = 1; iteration <= maxIterations; iteration++) {
+        let trace;
+        try {
+            trace = await worker.execute(task, harness);
+        }
+        catch (err) {
+            // Synthesize a minimal failure trace so the evaluator can still grade.
+            trace = {
+                taskId: task.id,
+                harnessId: harness.id,
+                steps: [
+                    {
+                        index: 0,
+                        phase: 'observe',
+                        action: 'worker-error',
+                        error: err instanceof Error ? err.message : String(err),
+                        durationMs: 0,
+                    },
+                ],
+                finalState: {},
+                llmTimeMs: 0,
+                toolTimeMs: 0,
+            };
+        }
+        let report;
+        try {
+            report = await evaluator.evaluate(trace, task);
+        }
+        catch (err) {
+            report = {
+                taskId: task.id,
+                harnessId: harness.id,
+                pass: false,
+                score: 0,
+                criteriaResults: task.acceptance.map((c) => ({
+                    criterion: c,
+                    passed: false,
+                    evidence: 'evaluator-error',
+                })),
+                failureModes: [
+                    {
+                        kind: 'other',
+                        detail: err instanceof Error ? err.message : String(err),
+                    },
+                ],
+                notes: 'evaluator threw; auto-fail',
+            };
+        }
+        const verdict = compareVerdict(prevScore, report.score, revertThreshold);
+        const record = {
+            iteration,
+            harness,
+            trace,
+            report,
+            verdict,
+        };
+        history.push(record);
+        if (options.onRecord) {
+            await options.onRecord(record);
+        }
+        if (shouldPersist) {
+            try {
+                await appendTrace(task.id, record, options.persistDir);
+            }
+            catch {
+                // persistence is best-effort; never block evolution on disk failure
+            }
+        }
+        // Track best harness.
+        if (report.score > bestScore) {
+            bestScore = report.score;
+            bestHarness = harness;
+        }
+        // Early-stop check.
+        if (earlyStopScore !== undefined && report.score >= earlyStopScore) {
+            earlyHits++;
+            if (earlyHits >= earlyStopStreak) {
+                break;
+            }
+        }
+        else {
+            earlyHits = 0;
+        }
+        // Revert on regression past threshold.
+        if (revertThreshold !== undefined &&
+            bestScore - report.score >= revertThreshold) {
+            harness = bestHarness;
+        }
+        prevScore = report.score;
+        // Short-circuit before the final evolve call — no point mutating on the
+        // last iteration since we'll never execute the new harness.
+        if (iteration === maxIterations)
+            break;
+        try {
+            harness = await evolution.evolve(history, bestHarness);
+        }
+        catch {
+            // EvolutionAgent failed — keep current harness, keep going.
+            harness = bestHarness;
+        }
+    }
+    // If nothing ran (shouldn't happen with maxIterations >= 1) make sure
+    // bestHarness is still defined.
+    if (history.length === 0) {
+        return {
+            taskId: task.id,
+            bestHarness: initialHarness,
+            bestScore: 0,
+            history,
+        };
+    }
+    return {
+        taskId: task.id,
+        bestHarness,
+        bestScore: bestScore === -Infinity ? 0 : bestScore,
+        history,
+    };
+}
+//# sourceMappingURL=evolution-loop.js.map

package/dist/futures/harness/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Harness Evolution Loop — public surface.
+ *
+ * See `./README.md` for the high-level overview and `./types.ts` for the
+ * contract every other file in this directory targets.
+ */
+export * from './types.js';
+export { runEvolutionLoop } from './evolution-loop.js';
+export type { RunOptions } from './evolution-loop.js';
+export { runMetaEvolution } from './meta-evolution.js';
+export type { MetaOptions } from './meta-evolution.js';
+export { CriticEvaluator, createCriticEvaluator, } from './critic-evaluator.js';
+export type { CriticEvaluatorOpts } from './critic-evaluator.js';
+export { NoopEvolutionAgent, createNoopEvolutionAgent, } from './noop-evolution.js';
+export { appendTrace, readHistory, pruneOlderThan, defaultStateDir, } from './persistence.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/futures/harness/index.js

@@ -0,0 +1,13 @@
+/**
+ * Harness Evolution Loop — public surface.
+ *
+ * See `./README.md` for the high-level overview and `./types.ts` for the
+ * contract every other file in this directory targets.
+ */
+export * from './types.js';
+export { runEvolutionLoop } from './evolution-loop.js';
+export { runMetaEvolution } from './meta-evolution.js';
+export { CriticEvaluator, createCriticEvaluator, } from './critic-evaluator.js';
+export { NoopEvolutionAgent, createNoopEvolutionAgent, } from './noop-evolution.js';
+export { appendTrace, readHistory, pruneOlderThan, defaultStateDir, } from './persistence.js';
+//# sourceMappingURL=index.js.map

package/dist/futures/harness/meta-evolution.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Harness Meta-Evolution — outer loop (Algorithm 2 from Sylph).
+ *
+ * The inner loop optimizes one harness against one task. The outer loop
+ * runs the inner loop across a portfolio of tasks, aggregating per-task
+ * results and selecting the best protocol overall. Currently the
+ * "selection" step is averaging — when a real MetaEvolutionAgent ships,
+ * it'll consume the perTask EvolutionResult[] and propose protocol
+ * mutations.
+ *
+ * Pure orchestration. Tasks are run sequentially to keep the trace
+ * ordering deterministic; parallelism is a future concern.
+ */
+import type { EvolutionProtocol, EvolutionResult, MetaResult, Task } from './types.js';
+import { type RunOptions } from './evolution-loop.js';
+export interface MetaOptions extends RunOptions {
+    /** Called after each task's inner loop completes. */
+    onTaskComplete?: (result: EvolutionResult) => void | Promise<void>;
+    /**
+     * When `true`, abort the outer loop on the first task whose best score
+     * is below `failBelow`. Default false — always run the full portfolio.
+     */
+    abortOnFailure?: boolean;
+    failBelow?: number;
+}
+/**
+ * Run the inner Evolution Loop across a portfolio of tasks, returning
+ * the best protocol (currently always the input protocol — there is no
+ * MetaEvolutionAgent yet) plus per-task results and the aggregate score.
+ */
+export declare function runMetaEvolution(protocol: EvolutionProtocol, tasks: Task[], options?: MetaOptions): Promise<MetaResult>;
+//# sourceMappingURL=meta-evolution.d.ts.map

package/dist/futures/harness/meta-evolution.js

@@ -0,0 +1,52 @@
+/**
+ * Harness Meta-Evolution — outer loop (Algorithm 2 from Sylph).
+ *
+ * The inner loop optimizes one harness against one task. The outer loop
+ * runs the inner loop across a portfolio of tasks, aggregating per-task
+ * results and selecting the best protocol overall. Currently the
+ * "selection" step is averaging — when a real MetaEvolutionAgent ships,
+ * it'll consume the perTask EvolutionResult[] and propose protocol
+ * mutations.
+ *
+ * Pure orchestration. Tasks are run sequentially to keep the trace
+ * ordering deterministic; parallelism is a future concern.
+ */
+import { runEvolutionLoop } from './evolution-loop.js';
+/**
+ * Run the inner Evolution Loop across a portfolio of tasks, returning
+ * the best protocol (currently always the input protocol — there is no
+ * MetaEvolutionAgent yet) plus per-task results and the aggregate score.
+ */
+export async function runMetaEvolution(protocol, tasks, options = {}) {
+    if (tasks.length === 0) {
+        return {
+            bestProtocol: protocol,
+            bestMetaScore: 0,
+            perTask: [],
+        };
+    }
+    const perTask = [];
+    let scoreSum = 0;
+    for (const task of tasks) {
+        const result = await runEvolutionLoop(protocol, task, options);
+        perTask.push(result);
+        scoreSum += result.bestScore;
+        if (options.onTaskComplete) {
+            await options.onTaskComplete(result);
+        }
+        if (options.abortOnFailure &&
+            options.failBelow !== undefined &&
+            result.bestScore < options.failBelow) {
+            break;
+        }
+    }
+    // Aggregate score: mean of per-task best scores. Cheap, defensible, and
+    // matches the "average across tasks" framing in the Sylph outer loop.
+    const meanScore = perTask.length > 0 ? scoreSum / perTask.length : 0;
+    return {
+        bestProtocol: protocol,
+        bestMetaScore: meanScore,
+        perTask,
+    };
+}
+//# sourceMappingURL=meta-evolution.js.map