@kernel.chat/kbot 4.0.0 → 4.1.0

package/dist/futures/forecast/projection.js

@@ -0,0 +1,177 @@
+// futures/forecast/projection — project Signal arrays forward in time.
+// Pure functions, no IO. Three model families (linear, exponential, flat)
+// + a `bestProjection` selector that picks the highest r² with bias toward
+// flat when neither model fits well.
+import { HORIZON_MS } from './types.js';
+/**
+ * Least-squares fit of y = a + b*x. Returns intercept, slope, r², and
+ * residual stddev (sqrt of mean squared residual). Assumes points.length >= 2.
+ */
+function leastSquares(xs, ys) {
+    const n = xs.length;
+    let sumX = 0;
+    let sumY = 0;
+    for (let i = 0; i < n; i++) {
+        sumX += xs[i];
+        sumY += ys[i];
+    }
+    const meanX = sumX / n;
+    const meanY = sumY / n;
+    let num = 0;
+    let den = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = xs[i] - meanX;
+        num += dx * (ys[i] - meanY);
+        den += dx * dx;
+    }
+    const slope = den === 0 ? 0 : num / den;
+    const intercept = meanY - slope * meanX;
+    // r²: 1 - SS_res / SS_tot
+    let ssRes = 0;
+    let ssTot = 0;
+    for (let i = 0; i < n; i++) {
+        const yhat = intercept + slope * xs[i];
+        const resid = ys[i] - yhat;
+        ssRes += resid * resid;
+        ssTot += (ys[i] - meanY) ** 2;
+    }
+    const r2 = ssTot === 0 ? (ssRes === 0 ? 1 : 0) : 1 - ssRes / ssTot;
+    const residualStd = Math.sqrt(ssRes / Math.max(1, n - 1));
+    return { intercept, slope, r2, residualStd };
+}
+/** Sort signal values ascending by timestamp; drops empty signals safely. */
+function sortedValues(signal) {
+    return [...signal.values].sort((a, b) => a.ts - b.ts);
+}
+/** Map r² + sample size to a 0..1 confidence score. */
+function confidenceFrom(r2, n) {
+    if (n < 2)
+        return 0;
+    // Linearly bonus more samples up to 12; r² floor at 0 (negatives clamp).
+    const sizeFactor = Math.min(1, n / 12);
+    const r2Clamped = Math.max(0, Math.min(1, r2));
+    return Math.max(0, Math.min(1, r2Clamped * 0.7 + sizeFactor * 0.3));
+}
+function flatForecast(signal, horizon, method = 'flat-mean') {
+    const pts = sortedValues(signal);
+    const mean = pts.length === 0 ? 0 : pts.reduce((s, p) => s + p.value, 0) / pts.length;
+    let std = 0;
+    if (pts.length > 1) {
+        const sq = pts.reduce((s, p) => s + (p.value - mean) ** 2, 0);
+        std = Math.sqrt(sq / (pts.length - 1));
+    }
+    const trend = { kind: 'flat', slope: 0, r2: 0 };
+    return {
+        signal: signal.name,
+        horizon,
+        trend,
+        pointEstimate: mean,
+        lowerBound: mean - 2 * std,
+        upperBound: mean + 2 * std,
+        confidence: pts.length >= 3 ? 0.4 : 0.1,
+        method,
+    };
+}
+/**
+ * Linear projection: value ~ a + b*t. Bounds = point ± 2 * residual stddev.
+ * Falls back to flat for fewer than 2 distinct timestamps.
+ */
+export function linearProjection(signal, horizon) {
+    const pts = sortedValues(signal);
+    if (pts.length < 2)
+        return flatForecast(signal, horizon, 'flat-too-few');
+    const xs = pts.map((p) => p.ts);
+    const ys = pts.map((p) => p.value);
+    const fit = leastSquares(xs, ys);
+    const lastTs = xs[xs.length - 1];
+    const targetTs = lastTs + HORIZON_MS[horizon];
+    const point = fit.intercept + fit.slope * targetTs;
+    const trend = { kind: 'linear', slope: fit.slope, r2: fit.r2 };
+    return {
+        signal: signal.name,
+        horizon,
+        trend,
+        pointEstimate: point,
+        lowerBound: point - 2 * fit.residualStd,
+        upperBound: point + 2 * fit.residualStd,
+        confidence: confidenceFrom(fit.r2, pts.length),
+        method: 'linear-lsq',
+    };
+}
+/**
+ * Exponential projection: log-transform, fit linear, exp back.
+ * Drops non-positive values (log undefined). Falls back to flat if too few
+ * positive points remain.
+ */
+export function exponentialProjection(signal, horizon) {
+    const pts = sortedValues(signal).filter((p) => p.value > 0);
+    if (pts.length < 2)
+        return flatForecast(signal, horizon, 'flat-nonpositive');
+    const xs = pts.map((p) => p.ts);
+    const ys = pts.map((p) => Math.log(p.value));
+    const fit = leastSquares(xs, ys);
+    const lastTs = xs[xs.length - 1];
+    const targetTs = lastTs + HORIZON_MS[horizon];
+    const logPoint = fit.intercept + fit.slope * targetTs;
+    const point = Math.exp(logPoint);
+    // Bounds in log space, then exp back (asymmetric in raw space — correct).
+    const lower = Math.exp(logPoint - 2 * fit.residualStd);
+    const upper = Math.exp(logPoint + 2 * fit.residualStd);
+    const trend = { kind: 'exponential', slope: fit.slope, r2: fit.r2 };
+    return {
+        signal: signal.name,
+        horizon,
+        trend,
+        pointEstimate: point,
+        lowerBound: lower,
+        upperBound: upper,
+        confidence: confidenceFrom(fit.r2, pts.length),
+        method: 'exp-loglin',
+    };
+}
+/** Public flat projection (callers may prefer to force this). */
+export function flatProjection(signal, horizon) {
+    return flatForecast(signal, horizon);
+}
+/**
+ * Pick the model with the best r². If both linear and exponential fit
+ * poorly (r² < 0.4 in both), return flat — low-variance signals shouldn't
+ * generate over-confident projections.
+ */
+export function bestProjection(signal, horizon) {
+    const pts = sortedValues(signal);
+    if (pts.length < 2)
+        return flatProjection(signal, horizon);
+    const lin = linearProjection(signal, horizon);
+    // Exponential only meaningful when all values positive.
+    const allPositive = pts.every((p) => p.value > 0);
+    const exp = allPositive ? exponentialProjection(signal, horizon) : null;
+    const linR2 = lin.trend.r2;
+    const expR2 = exp ? exp.trend.r2 : -Infinity;
+    if (linR2 < 0.4 && expR2 < 0.4) {
+        return flatProjection(signal, horizon);
+    }
+    if (exp && expR2 > linR2)
+        return exp;
+    return lin;
+}
+/**
+ * Guard against projecting absurdly far past available history.
+ * Returns true if the horizon is acceptable given the timespan covered.
+ * Rule: horizon must not exceed history span * 3.
+ *
+ * `history` is the timespan in ms from earliest to latest observation.
+ */
+export function clampHorizon(h, history) {
+    if (history <= 0)
+        return false;
+    return HORIZON_MS[h] <= history * 3;
+}
+/** Helper for tests/synthesize: compute the timespan of a Signal in ms. */
+export function signalHistory(signal) {
+    if (signal.values.length < 2)
+        return 0;
+    const sorted = sortedValues(signal);
+    return sorted[sorted.length - 1].ts - sorted[0].ts;
+}
+//# sourceMappingURL=projection.js.map

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

@@ -0,0 +1,19 @@
+import type { Forecast, Horizon, Signal } from './types.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 declare function synthesizeForecasts(signals: Signal[], horizon: Horizon): Forecast[];
+/**
+ * Markdown one-liner for a forecast.
+ * Example: `📈 npm downloads → 14.2k (in 30 days, linear, r²=0.78, ±890)`
+ */
+export declare function formatForecast(f: Forecast): string;
+/**
+ * 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 declare function narrative(forecasts: Forecast[]): string;
+//# sourceMappingURL=synthesize.d.ts.map

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