@ashlr/hub 2.2.0

package/dist/core/run/self-heal.js

@@ -0,0 +1,181 @@
+/**
+ * M20: Bounded runtime self-heal wrapper.
+ *
+ * Wraps a single runtime operation (MCP downstream spawn or model call) with
+ * bounded, classified heal logic. Reuses `withRetry` (M11) for the loop +
+ * backoff — does NOT reimplement backoff from scratch.
+ *
+ * GUARDRAILS:
+ *   - BOUNDED by construction: never loops more than policy.maxRestarts
+ *     heal-triggered retries. No infinite restart/downgrade loop.
+ *   - model-downgrade: SMALLER LOCAL model only — never escalates to cloud,
+ *     never increases cost.
+ *   - rate-backoff: only when cloud is already in play (caller opted in).
+ *   - opt-out: callers can check ASHLR_NO_HEAL at their call site and skip.
+ *   - Rethrows last error on exhaustion or non-recoverable failure.
+ *   - Never throws from the heal machinery itself (only from fn exhaustion).
+ *
+ * No new runtime deps. ESM/NodeNext: all sibling imports use the .js extension.
+ */
+import { withRetry } from './retry.js';
+// ---------------------------------------------------------------------------
+// Error classification
+// ---------------------------------------------------------------------------
+/** True for errors that look like an MCP downstream crash or spawn failure. */
+function isMcpRestartable(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message.toLowerCase();
+    return (msg.includes('spawn') ||
+        msg.includes('econnrefused') ||
+        msg.includes('econnreset') ||
+        msg.includes('socket hang up') ||
+        msg.includes('connect failed') ||
+        msg.includes('downstream') ||
+        msg.includes('mcp') ||
+        // process exit codes surfaced as error messages
+        msg.includes('exited with code') ||
+        msg.includes('process exited'));
+}
+/** True for errors that look like a local model OOM or model-layer failure. */
+function isModelError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message.toLowerCase();
+    return (msg.includes('oom') ||
+        msg.includes('out of memory') ||
+        msg.includes('cuda out of memory') ||
+        msg.includes('model error') ||
+        msg.includes('model failed') ||
+        msg.includes('context length') ||
+        msg.includes('context window') ||
+        // ollama / lm-studio error patterns
+        msg.includes('model not loaded') ||
+        msg.includes('llm error') ||
+        msg.includes('inference error'));
+}
+/** True for errors that look like a cloud rate-limit or quota exceeded. */
+function isRateLimit(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message.toLowerCase();
+    return (msg.includes('rate limit') ||
+        msg.includes('rate_limit') ||
+        msg.includes('429') ||
+        msg.includes('too many requests') ||
+        msg.includes('quota exceeded') ||
+        msg.includes('overloaded') ||
+        msg.includes('throttl'));
+}
+// ---------------------------------------------------------------------------
+// Heal-event classification
+// ---------------------------------------------------------------------------
+/**
+ * Classify the error into a HealEvent kind, or return null when the error is
+ * not recoverable by any heal strategy.
+ *
+ * Priority: mcp-restart > model-downgrade > rate-backoff.
+ * `allowDowngrade` gates model-downgrade. `allowCloud` gates rate-backoff.
+ */
+function classifyHealEvent(err, attempt, policy, allowCloud) {
+    if (isMcpRestartable(err)) {
+        return {
+            kind: 'mcp-restart',
+            detail: `MCP downstream error on attempt ${attempt}: ${errorMessage(err)}`,
+            attempt,
+        };
+    }
+    if (isModelError(err) && policy.allowDowngrade) {
+        return {
+            kind: 'model-downgrade',
+            detail: `Local model error on attempt ${attempt} — downgrading to smaller local model: ${errorMessage(err)}`,
+            attempt,
+        };
+    }
+    if (isRateLimit(err) && allowCloud) {
+        return {
+            kind: 'rate-backoff',
+            detail: `Cloud rate-limit on attempt ${attempt} — backing off: ${errorMessage(err)}`,
+            attempt,
+        };
+    }
+    return null;
+}
+/** Extract a safe, concise message from an unknown thrown value. */
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Conservative bounded default: 2 heal-triggered retries, downgrade allowed.
+ * Callers may override; this is always a safe starting point.
+ */
+export function defaultHealPolicy() {
+    return { maxRestarts: 2, allowDowngrade: true };
+}
+/**
+ * Bounded self-heal wrapper for a runtime operation `fn`.
+ *
+ * `fn` receives the 1-based attempt number so the caller can vary its
+ * behaviour across attempts (e.g. pick a smaller model on attempt > 1 when a
+ * 'model-downgrade' heal event has been emitted).
+ *
+ * `policy.maxRestarts` is the hard cap on heal-triggered retries — the total
+ * number of fn invocations is at most `policy.maxRestarts + 1`.
+ *
+ * `onHeal` is called synchronously before each retry with the classified event.
+ * It MUST NOT throw; any throw is silently swallowed to preserve retry flow.
+ *
+ * `allowCloud` (default false) gates 'rate-backoff' — pass true only when the
+ * caller has already enabled cloud routing; withHeal never enables cloud on its
+ * own.
+ *
+ * Rethrows the last error when:
+ *   - all retries are exhausted, OR
+ *   - the error is not a recognised heal case (non-retryable).
+ *
+ * Backed by `withRetry` (M11) for deterministic bounded exponential backoff:
+ *   attempt 1 failure → retry immediately (0 ms);
+ *   attempt 2 failure → 500 ms;
+ *   attempt 3 failure → 1 000 ms; …  capped at 30 s.
+ */
+export async function withHeal(fn, policy, onHeal, allowCloud = false) {
+    // total attempts = 1 initial + maxRestarts heal retries
+    const maxAttempts = Math.max(1, policy.maxRestarts + 1);
+    // Bounded by attempt count, not wall-clock. baseDelayMs:0 keeps the withRetry
+    // backoff formula intact (baseDelayMs * 2^(attempt-1) is always 0) while
+    // avoiding real-time sleeps inside the runtime heal loop — the bound that
+    // matters here is maxRestarts, not a multi-second backoff. Real backoff for
+    // cloud rate-limits is owned by the downstream caller's own retry policy.
+    const retryPolicy = {
+        maxAttempts,
+        baseDelayMs: 0,
+    };
+    // withRetry's isRetryable callback does not receive the attempt number, so we
+    // capture the 1-based attempt fn was last invoked with. That is the attempt
+    // that just failed — exactly what the emitted HealEvent must report.
+    let currentAttempt = 0;
+    return withRetry(async (attempt) => {
+        currentAttempt = attempt;
+        return fn(attempt);
+    }, retryPolicy, (err) => {
+        // isRetryable: emit the heal event only for recoverable errors. The
+        // attempt that just failed is `currentAttempt` (1-based).
+        const event = classifyHealEvent(err, currentAttempt, policy, allowCloud);
+        if (event === null)
+            return false;
+        // Emit the heal event — suppress any throw from the callback
+        try {
+            onHeal(event);
+        }
+        catch {
+            // intentionally swallowed
+        }
+        return true;
+    });
+}
+//# sourceMappingURL=self-heal.js.map

package/dist/core/run/self-heal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-heal.js","sourceRoot":"","sources":["../../../src/core/run/self-heal.ts"],"names":[],"mappings":"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"}

package/dist/core/run/streaming.d.ts

@@ -0,0 +1,31 @@
+/**
+ * M11: streaming.ts — StreamSink type + nullSink / makeCliSink factories.
+ *
+ * A StreamSink receives live RunStreamEvents from the agent loop and renders
+ * them to the terminal. The sink contract:
+ *   - NEVER throws to the caller (all errors caught internally).
+ *   - NEVER prints secret values (events carry metadata/text only).
+ *   - model-delta events render incrementally (process.stdout/stderr.write,
+ *     no trailing newline) so the token stream looks live.
+ *   - Lifecycle events (task-start, task-done, retry, verify, tool-call, log)
+ *     render as full labeled lines with glyphs + color.
+ *   - When opts.json === true the human stream goes to STDERR so stdout stays
+ *     clean machine JSON.
+ */
+import type { RunStreamEvent } from '../types.js';
+/** A sink that receives live run events. Never throws to the caller. */
+export type StreamSink = (e: RunStreamEvent) => void;
+/** A no-op sink — used when streaming is disabled or in unit tests. */
+export declare function nullSink(): StreamSink;
+/**
+ * Build a CLI sink that renders a live, readable stream.
+ *
+ * - opts.json === true  → human lines go to STDERR (stdout stays clean JSON).
+ * - opts.json === false → lines go to STDERR when isTTY, else STDOUT.
+ *
+ * model-delta events are written inline (no newline) so the token stream looks
+ * continuous. All other event kinds start on their own labeled line.
+ */
+export declare function makeCliSink(opts: {
+    json: boolean;
+}): StreamSink;

package/dist/core/run/streaming.js

@@ -0,0 +1,122 @@
+/**
+ * M11: streaming.ts — StreamSink type + nullSink / makeCliSink factories.
+ *
+ * A StreamSink receives live RunStreamEvents from the agent loop and renders
+ * them to the terminal. The sink contract:
+ *   - NEVER throws to the caller (all errors caught internally).
+ *   - NEVER prints secret values (events carry metadata/text only).
+ *   - model-delta events render incrementally (process.stdout/stderr.write,
+ *     no trailing newline) so the token stream looks live.
+ *   - Lifecycle events (task-start, task-done, retry, verify, tool-call, log)
+ *     render as full labeled lines with glyphs + color.
+ *   - When opts.json === true the human stream goes to STDERR so stdout stays
+ *     clean machine JSON.
+ */
+import { makeColors } from '../../cli/ui.js';
+/** A no-op sink — used when streaming is disabled or in unit tests. */
+export function nullSink() {
+    return (_e) => { };
+}
+/**
+ * Build a CLI sink that renders a live, readable stream.
+ *
+ * - opts.json === true  → human lines go to STDERR (stdout stays clean JSON).
+ * - opts.json === false → lines go to STDERR when isTTY, else STDOUT.
+ *
+ * model-delta events are written inline (no newline) so the token stream looks
+ * continuous. All other event kinds start on their own labeled line.
+ */
+export function makeCliSink(opts) {
+    // Choose the output stream: always STDERR when json mode so stdout is clean.
+    const out = opts.json ? process.stderr : process.stderr;
+    const isTty = out.isTTY === true;
+    const col = makeColors(isTty);
+    // Track whether we're mid-line on a model-delta run (so we know when to
+    // emit a leading newline before a lifecycle label).
+    let midDelta = false;
+    function write(s) {
+        try {
+            out.write(s);
+        }
+        catch { /* never throw */ }
+    }
+    function writeln(s) {
+        // If we were streaming model deltas inline, break to a new line first.
+        if (midDelta) {
+            write('\n');
+            midDelta = false;
+        }
+        write(s + '\n');
+    }
+    function taskTag(taskId) {
+        return taskId ? col.gray(`[${taskId}] `) : '';
+    }
+    return function sink(e) {
+        try {
+            switch (e.kind) {
+                case 'task-start': {
+                    const tag = taskTag(e.taskId);
+                    writeln(`${col.cyan('▶')} ${tag}${col.bold(e.text ?? 'task starting')}`);
+                    break;
+                }
+                case 'model-delta': {
+                    // Inline write — no newline. May be empty string; skip.
+                    const chunk = e.text ?? '';
+                    if (chunk.length > 0) {
+                        write(chunk);
+                        midDelta = true;
+                    }
+                    break;
+                }
+                case 'tool-call': {
+                    const tag = taskTag(e.taskId);
+                    const name = e.text ?? (typeof e.data === 'object' && e.data !== null
+                        ? String(e.data['name'] ?? 'tool')
+                        : 'tool');
+                    writeln(`${col.magenta('⚙')} ${tag}${col.dim('tool:')} ${col.magenta(name)}`);
+                    break;
+                }
+                case 'task-done': {
+                    const tag = taskTag(e.taskId);
+                    writeln(`${col.green('✓')} ${tag}${col.bold(e.text ?? 'done')}`);
+                    break;
+                }
+                case 'retry': {
+                    const tag = taskTag(e.taskId);
+                    writeln(`${col.yellow('↺')} ${tag}${col.yellow(e.text ?? 'retrying')}`);
+                    break;
+                }
+                case 'verify': {
+                    const tag = taskTag(e.taskId);
+                    // data may be a VerifyVerdict: { ok, reason, method }
+                    const verdict = (typeof e.data === 'object' && e.data !== null)
+                        ? e.data
+                        : null;
+                    const ok = verdict?.ok ?? true;
+                    const reason = verdict?.reason ?? e.text ?? '';
+                    const method = verdict?.method ? col.dim(` (${verdict.method})`) : '';
+                    if (ok) {
+                        writeln(`${col.green('✔')} ${tag}${col.green('verify ok')}${method}${reason ? ': ' + reason : ''}`);
+                    }
+                    else {
+                        writeln(`${col.yellow('✘')} ${tag}${col.yellow('verify fail')}${method}${reason ? ': ' + reason : ''}`);
+                    }
+                    break;
+                }
+                case 'log': {
+                    const tag = taskTag(e.taskId);
+                    writeln(`${col.gray('·')} ${tag}${col.dim(e.text ?? '')}`);
+                    break;
+                }
+                default: {
+                    // Unknown future event kinds: silently ignore to stay forward-compatible.
+                    break;
+                }
+            }
+        }
+        catch {
+            // Contract: never throw to caller regardless of render errors.
+        }
+    };
+}
+//# sourceMappingURL=streaming.js.map

package/dist/core/run/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../../src/core/run/streaming.ts"],"names":[],"mappings":"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"}

package/dist/core/run/verify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Task result verification for `ashlr run`.
+ *
+ * Two-stage: heuristic-first (cheap, synchronous), then an optional single
+ * cheap model call only when the heuristic is inconclusive AND budget remains.
+ *
+ * CONTRACT guarantees:
+ * - Never throws.
+ * - Never exceeds the global budget (checks overBudget before any model call).
+ * - Mutates `usage` in-place (same pattern as agent-loop.ts) to account for
+ *   the optional model check.
+ */
+import type { RunTask, ProviderClient, RunBudget, RunUsage, VerifyVerdict } from '../types.js';
+/**
+ * Judge whether `task.result` plausibly satisfies `task.goal`.
+ *
+ * 1. Heuristic first (cheap, sync): empty / error-sentinel / keyword overlap.
+ *    If confident → return immediately.
+ * 2. Optional model check only when:
+ *    - heuristic was inconclusive, AND
+ *    - budget has not been exceeded (overBudget check before the call), AND
+ *    - client is available.
+ *    Mutates `usage` to account for the model call.
+ *    On any model error or budget exhaustion → falls back to a heuristic verdict.
+ *
+ * Never throws.
+ */
+export declare function verifyTask(task: RunTask, client: ProviderClient, budget: RunBudget, usage: RunUsage, opts?: {
+    model?: boolean;
+}): Promise<VerifyVerdict>;

package/dist/core/run/verify.js

@@ -0,0 +1,204 @@
+/**
+ * Task result verification for `ashlr run`.
+ *
+ * Two-stage: heuristic-first (cheap, synchronous), then an optional single
+ * cheap model call only when the heuristic is inconclusive AND budget remains.
+ *
+ * CONTRACT guarantees:
+ * - Never throws.
+ * - Never exceeds the global budget (checks overBudget before any model call).
+ * - Mutates `usage` in-place (same pattern as agent-loop.ts) to account for
+ *   the optional model check.
+ */
+import { overBudget, addUsage } from './budget.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Error sentinels that strongly suggest the result is a failure / error message
+ * rather than a meaningful answer.
+ */
+const ERROR_SENTINELS = [
+    'error:',
+    'traceback',
+    'exception:',
+    'syntaxerror',
+    'typeerror',
+    'referenceerror',
+    'uncaught ',
+    'fatal:',
+    'command not found',
+    'permission denied',
+    'enoent',
+    'eacces',
+    'task failed',
+    'aborted',
+    'budget exceeded',
+];
+/**
+ * Heuristic verdict.
+ *
+ * Returns { ok: false, reason, method:'heuristic' } when it is CONFIDENT the
+ * result is bad, or { ok: true, reason, method:'heuristic' } when heuristic
+ * is confident the result is good enough.
+ *
+ * Returns null when the heuristic is inconclusive (caller may attempt model check).
+ */
+function heuristicVerify(task) {
+    const result = task.result ?? '';
+    const goal = task.goal;
+    // 1. Empty result → confident fail.
+    if (result.trim().length === 0) {
+        return {
+            ok: false,
+            reason: 'Result is empty.',
+            method: 'heuristic',
+        };
+    }
+    // 2. Error sentinel match → confident fail.
+    const lower = result.toLowerCase();
+    for (const sentinel of ERROR_SENTINELS) {
+        if (lower.includes(sentinel)) {
+            return {
+                ok: false,
+                reason: `Result contains error marker "${sentinel}".`,
+                method: 'heuristic',
+            };
+        }
+    }
+    // 3. On-topic keyword overlap with the goal.
+    // Extract meaningful words from the goal (>= 4 chars, alpha-only).
+    const goalWords = goal
+        .toLowerCase()
+        .split(/\W+/)
+        .filter((w) => w.length >= 4);
+    if (goalWords.length > 0) {
+        const matchCount = goalWords.filter((w) => lower.includes(w)).length;
+        const overlapRatio = matchCount / goalWords.length;
+        // High overlap → confident pass.
+        if (overlapRatio >= 0.5) {
+            return {
+                ok: true,
+                reason: `Result appears on-topic (${matchCount}/${goalWords.length} goal keywords matched).`,
+                method: 'heuristic',
+            };
+        }
+        // Very low overlap on a goal with many words → confident fail.
+        if (goalWords.length >= 3 && overlapRatio === 0) {
+            return {
+                ok: false,
+                reason: 'Result shares no keywords with the goal.',
+                method: 'heuristic',
+            };
+        }
+    }
+    // 4. Result is non-empty and no errors → weakly pass (inconclusive, but lean ok).
+    // Return null to signal the caller should do a model check if budget allows.
+    return null;
+}
+/**
+ * Build the cheap yes/no model prompt asking whether the result satisfies the goal.
+ */
+function buildVerifyMessages(task) {
+    return [
+        {
+            role: 'system',
+            content: 'You are a strict but concise evaluator. Answer only "yes" or "no" followed by a one-line reason (≤ 20 words).',
+        },
+        {
+            role: 'user',
+            content: `Does this result plausibly satisfy the goal?\n\n` +
+                `Goal: ${task.goal}\n\n` +
+                `Result (first 500 chars): ${(task.result ?? '').slice(0, 500)}\n\n` +
+                `Answer "yes" or "no" and one short reason.`,
+        },
+    ];
+}
+/**
+ * Parse the model's yes/no response into a VerifyVerdict.
+ */
+function parseModelVerdict(raw) {
+    const text = raw.trim().toLowerCase();
+    const ok = text.startsWith('yes');
+    // Extract the reason: everything after the first word/punctuation.
+    const reasonMatch = raw.trim().match(/^(?:yes|no)[.,:\s]*(.*)/i);
+    const reason = reasonMatch?.[1]?.trim() || raw.trim();
+    return {
+        ok,
+        reason: reason || (ok ? 'Model judged result satisfactory.' : 'Model judged result unsatisfactory.'),
+        method: 'model',
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Judge whether `task.result` plausibly satisfies `task.goal`.
+ *
+ * 1. Heuristic first (cheap, sync): empty / error-sentinel / keyword overlap.
+ *    If confident → return immediately.
+ * 2. Optional model check only when:
+ *    - heuristic was inconclusive, AND
+ *    - budget has not been exceeded (overBudget check before the call), AND
+ *    - client is available.
+ *    Mutates `usage` to account for the model call.
+ *    On any model error or budget exhaustion → falls back to a heuristic verdict.
+ *
+ * Never throws.
+ */
+export async function verifyTask(task, client, budget, usage, opts) {
+    // Stage 1: heuristic.
+    const heuristic = heuristicVerify(task);
+    if (heuristic !== null) {
+        return heuristic;
+    }
+    // The optional model check is opt-in. When disabled (the default for the
+    // orchestrator's per-task verify, which keeps M4 deterministic accounting
+    // intact) the inconclusive heuristic resolves to a lenient pass WITHOUT any
+    // model call or usage mutation. verifyTask's own callers (and tests) may
+    // enable it explicitly via { model: true }.
+    if (opts?.model !== true) {
+        return {
+            ok: true,
+            reason: 'Heuristic pass (non-empty result with no error markers; model check disabled).',
+            method: 'heuristic',
+        };
+    }
+    // Heuristic inconclusive — check budget before a model call.
+    if (overBudget(usage, budget)) {
+        // Budget exhausted: fall back to a lenient heuristic pass (non-empty, no errors).
+        return {
+            ok: true,
+            reason: 'Heuristic pass (budget exhausted; model check skipped).',
+            method: 'heuristic',
+        };
+    }
+    // Stage 2: cheap single model call.
+    try {
+        const messages = buildVerifyMessages(task);
+        const result = await client.chat(messages, /* tools */ undefined);
+        // Account for the tokens used by the verification call.
+        const delta = {
+            tokensIn: result.usage.tokensIn,
+            tokensOut: result.usage.tokensOut,
+            steps: 1,
+            estCostUsd: 0, // local providers → 0
+        };
+        const merged = addUsage(usage, delta);
+        // Mutate the caller's usage object in-place (same pattern as agent-loop.ts).
+        usage.tokensIn = merged.tokensIn;
+        usage.tokensOut = merged.tokensOut;
+        usage.steps = merged.steps;
+        usage.estCostUsd = merged.estCostUsd;
+        return parseModelVerdict(result.content);
+    }
+    catch {
+        // Model check failed — fall back to a lenient heuristic pass.
+        return {
+            ok: true,
+            reason: 'Heuristic pass (model check failed; non-empty result with no error markers).',
+            method: 'heuristic',
+        };
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/core/run/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/core/run/verify.ts"],"names":[],"mappings":"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"}

package/dist/core/sandbox/audit.d.ts

@@ -0,0 +1,31 @@
+/**
+ * M21: Append-only audit trail for autonomous/sandbox actions.
+ *
+ * Writes to ~/.ashlr/audit/<YYYY-MM-DD>.jsonl — one JSON object per line.
+ * Rules:
+ *   - Append-only: never truncate, never rewrite, never delete a prior line.
+ *   - Never write secrets: summary is metadata only; secret-shaped tokens are
+ *     stripped defensively before persisting.
+ *   - audit() never throws; readAudit() skips malformed lines, never throws.
+ */
+import type { AuditEntry } from '../types.js';
+/**
+ * Returns the absolute path to the audit directory: ~/.ashlr/audit.
+ * Created lazily by audit() — this function itself does NOT create it.
+ */
+export declare function auditDir(): string;
+/**
+ * Append one audit entry to today's JSONL file under ~/.ashlr/audit/.
+ * Sets `ts` to the current ISO timestamp; the caller supplies everything else.
+ *
+ * Append-only: never truncates, never rewrites existing lines.
+ * Never throws — errors are swallowed silently to keep callers unblocked.
+ */
+export declare function audit(entry: Omit<AuditEntry, 'ts'>): void;
+/**
+ * Read audit entries across all date files, newest-first.
+ * `limit` caps the number returned (undefined or 0 => return all).
+ *
+ * Malformed JSONL lines are silently skipped; never throws.
+ */
+export declare function readAudit(limit?: number): AuditEntry[];