@tangle-network/browser-agent-driver 0.30.0 → 0.32.0

package/dist/jobs/cost-estimate.js

@@ -0,0 +1,21 @@
+/**
+ * Pre-flight cost estimate — refuses to silently spend $1k.
+ *
+ * The numbers here are deliberately conservative and based on observed
+ * production telemetry for `claude-code` provider with sonnet at the time of
+ * writing. If the assumptions drift, only one constant changes.
+ */
+/** Average USD per single-page audit. Tuned for sonnet via claude-code provider, 1 audit pass. */
+export const DEFAULT_PER_AUDIT_USD = 0.4;
+export function estimateCost(spec, targetCount, perAuditUSD = DEFAULT_PER_AUDIT_USD) {
+    const pages = Math.max(spec.audit?.pages ?? 1, 1);
+    const estimatedTotalUSD = targetCount * pages * perAuditUSD;
+    const exceedsCap = typeof spec.maxCostUSD === 'number' && estimatedTotalUSD > spec.maxCostUSD;
+    return {
+        targetCount,
+        perAuditUSD: perAuditUSD * pages,
+        estimatedTotalUSD,
+        exceedsCap,
+    };
+}
+//# sourceMappingURL=cost-estimate.js.map

package/dist/jobs/cost-estimate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-estimate.js","sourceRoot":"","sources":["../../src/jobs/cost-estimate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,kGAAkG;AAClG,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAA;AAExC,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,WAAmB,EAAE,WAAW,GAAG,qBAAqB;IAClG,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;IACjD,MAAM,iBAAiB,GAAG,WAAW,GAAG,KAAK,GAAG,WAAW,CAAA;IAC3D,MAAM,UAAU,GAAG,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,IAAI,iBAAiB,GAAG,IAAI,CAAC,UAAU,CAAA;IAC7F,OAAO;QACL,WAAW;QACX,WAAW,EAAE,WAAW,GAAG,KAAK;QAChC,iBAAiB;QACjB,UAAU;KACX,CAAA;AACH,CAAC"}

package/dist/jobs/cost-history.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Adaptive cost estimate from historical jobs. The default flat
+ * `DEFAULT_PER_AUDIT_USD` is still a fine starting point for a fresh user,
+ * but once 3+ jobs have completed we can do better: averaging the actual
+ * per-target cost across recent jobs is closer to ground truth, especially
+ * once ethics / first-principles modes start firing differently per target.
+ *
+ * Pure function of `~/.bad/jobs/` records — no telemetry endpoint required.
+ */
+export interface AdaptiveCostStats {
+    perAuditUSD: number;
+    source: 'history' | 'default';
+    /** Number of historical job records the estimate was averaged over. */
+    jobsObserved: number;
+    /** Number of audited targets the estimate was averaged over. */
+    targetsObserved: number;
+}
+export declare function computePerAuditFromHistory(dir?: string): AdaptiveCostStats;
+//# sourceMappingURL=cost-history.d.ts.map

package/dist/jobs/cost-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-history.d.ts","sourceRoot":"","sources":["../../src/jobs/cost-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;IAC7B,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,0BAA0B,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAyB1E"}

package/dist/jobs/cost-history.js

@@ -0,0 +1,42 @@
+/**
+ * Adaptive cost estimate from historical jobs. The default flat
+ * `DEFAULT_PER_AUDIT_USD` is still a fine starting point for a fresh user,
+ * but once 3+ jobs have completed we can do better: averaging the actual
+ * per-target cost across recent jobs is closer to ground truth, especially
+ * once ethics / first-principles modes start firing differently per target.
+ *
+ * Pure function of `~/.bad/jobs/` records — no telemetry endpoint required.
+ */
+import { listJobs, loadJob } from './store.js';
+import { DEFAULT_PER_AUDIT_USD } from './cost-estimate.js';
+/** Min number of completed jobs before we trust history over the static default. */
+const MIN_HISTORY = 3;
+export function computePerAuditFromHistory(dir) {
+    const entries = listJobs(dir);
+    // Only count completed/partial jobs — failed ones have skewed cost.
+    const usable = entries.filter((e) => e.status === 'completed' || e.status === 'partial').slice(0, 20);
+    if (usable.length < MIN_HISTORY) {
+        return { perAuditUSD: DEFAULT_PER_AUDIT_USD, source: 'default', jobsObserved: usable.length, targetsObserved: 0 };
+    }
+    let totalCost = 0;
+    let totalTargets = 0;
+    for (const entry of usable) {
+        const job = loadJob(entry.jobId, dir);
+        if (!job)
+            continue;
+        const okCount = job.results.filter(r => r.status === 'ok' && typeof r.costUSD === 'number').length;
+        if (okCount === 0)
+            continue;
+        totalCost += job.totalCostUSD;
+        totalTargets += okCount;
+    }
+    if (totalTargets === 0) {
+        return { perAuditUSD: DEFAULT_PER_AUDIT_USD, source: 'default', jobsObserved: usable.length, targetsObserved: 0 };
+    }
+    const perAudit = totalCost / totalTargets;
+    // Floor at half the static default to prevent runaway optimism on a stretch
+    // of zero-cost jobs (which can happen with the claude-code provider).
+    const floored = Math.max(perAudit, DEFAULT_PER_AUDIT_USD * 0.5);
+    return { perAuditUSD: floored, source: 'history', jobsObserved: usable.length, targetsObserved: totalTargets };
+}
+//# sourceMappingURL=cost-history.js.map

package/dist/jobs/cost-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-history.js","sourceRoot":"","sources":["../../src/jobs/cost-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAE1D,oFAAoF;AACpF,MAAM,WAAW,GAAG,CAAC,CAAA;AAWrB,MAAM,UAAU,0BAA0B,CAAC,GAAY;IACrD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC7B,oEAAoE;IACpE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAgB,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACpH,IAAI,MAAM,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QAChC,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,EAAE,CAAA;IACnH,CAAC;IACD,IAAI,SAAS,GAAG,CAAC,CAAA;IACjB,IAAI,YAAY,GAAG,CAAC,CAAA;IACpB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QACrC,IAAI,CAAC,GAAG;YAAE,SAAQ;QAClB,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,MAAM,CAAA;QAClG,IAAI,OAAO,KAAK,CAAC;YAAE,SAAQ;QAC3B,SAAS,IAAI,GAAG,CAAC,YAAY,CAAA;QAC7B,YAAY,IAAI,OAAO,CAAA;IACzB,CAAC;IACD,IAAI,YAAY,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,EAAE,CAAA;IACnH,CAAC;IACD,MAAM,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAA;IACzC,4EAA4E;IAC5E,sEAAsE;IACtE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,qBAAqB,GAAG,GAAG,CAAC,CAAA;IAC/D,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,CAAA;AAChH,CAAC"}

package/dist/jobs/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Jobs — declarative comparative-audit jobs.
+ *
+ * Public surface:
+ *   createJob(spec) → Job (queued, persisted, ready to run)
+ *   runJob(job, opts) → Job (executes the fan-out, returns final state)
+ *   loadJob / listJobs / saveJob — store accessors
+ *   estimateCost — pre-flight cost guard
+ */
+export type { Job, JobSpec, JobStatus, JobKind, JobTarget, JobResultEntry, JobResultStatus, DiscoverSpec, DiscoverSource, AuditOptions, CostEstimate, } from './types.js';
+export { newJobId, saveJob, loadJob, listJobs, appendIndexEntry, jobsDir, jobPath, updateJobStatus } from './store.js';
+export type { JobIndexEntry } from './store.js';
+export { estimateCost, DEFAULT_PER_AUDIT_USD } from './cost-estimate.js';
+export { runJob } from './queue.js';
+export type { AuditFn, RunJobOptions } from './queue.js';
+export { withRetry, isRetryableDefault, DEFAULT_RETRY_POLICY } from './retry.js';
+export type { RetryPolicy } from './retry.js';
+export { detectBlock, reasonFor } from './anti-bot.js';
+export type { BlockSignals } from './anti-bot.js';
+export { computePerAuditFromHistory } from './cost-history.js';
+export type { AdaptiveCostStats } from './cost-history.js';
+export { orchestrateJob, needsIntervention } from './orchestrator.js';
+export type { OrchestrateJobOptions } from './orchestrator.js';
+import type { Job, JobSpec, JobTarget } from './types.js';
+/**
+ * Mint a fresh `queued` job from a spec. Targets are seeded from the spec
+ * (snapshot expansion, if any, must be done by the caller via the
+ * `discover` module before runJob).
+ */
+export declare function createJob(spec: JobSpec, targets: JobTarget[], dir?: string): Job;
+//# sourceMappingURL=index.d.ts.map

package/dist/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,GAAG,EACH,OAAO,EACP,SAAS,EACT,OAAO,EACP,SAAS,EACT,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACtH,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACnC,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAChF,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAA;AAC9D,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrE,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAE9D,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAGzD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAahF"}

package/dist/jobs/index.js

@@ -0,0 +1,37 @@
+/**
+ * Jobs — declarative comparative-audit jobs.
+ *
+ * Public surface:
+ *   createJob(spec) → Job (queued, persisted, ready to run)
+ *   runJob(job, opts) → Job (executes the fan-out, returns final state)
+ *   loadJob / listJobs / saveJob — store accessors
+ *   estimateCost — pre-flight cost guard
+ */
+export { newJobId, saveJob, loadJob, listJobs, appendIndexEntry, jobsDir, jobPath, updateJobStatus } from './store.js';
+export { estimateCost, DEFAULT_PER_AUDIT_USD } from './cost-estimate.js';
+export { runJob } from './queue.js';
+export { withRetry, isRetryableDefault, DEFAULT_RETRY_POLICY } from './retry.js';
+export { detectBlock, reasonFor } from './anti-bot.js';
+export { computePerAuditFromHistory } from './cost-history.js';
+export { orchestrateJob, needsIntervention } from './orchestrator.js';
+import { newJobId, saveJob, appendIndexEntry } from './store.js';
+/**
+ * Mint a fresh `queued` job from a spec. Targets are seeded from the spec
+ * (snapshot expansion, if any, must be done by the caller via the
+ * `discover` module before runJob).
+ */
+export function createJob(spec, targets, dir) {
+    const job = {
+        jobId: newJobId(),
+        spec,
+        status: 'queued',
+        createdAt: new Date().toISOString(),
+        targets,
+        results: [],
+        totalCostUSD: 0,
+    };
+    saveJob(job, dir);
+    appendIndexEntry(job, dir);
+    return job;
+}
+//# sourceMappingURL=index.js.map

package/dist/jobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEtH,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAEnC,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEhF,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAEtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAA;AAE9D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAIrE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEhE;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAa,EAAE,OAAoB,EAAE,GAAY;IACzE,MAAM,GAAG,GAAQ;QACf,KAAK,EAAE,QAAQ,EAAE;QACjB,IAAI;QACJ,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO;QACP,OAAO,EAAE,EAAE;QACX,YAAY,EAAE,CAAC;KAChB,CAAA;IACD,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACjB,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC1B,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/jobs/orchestrator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Agentic orchestrator — wraps `runJob` with a control loop that handles
+ * strategic decisions (re-sample broken wayback snapshots, retry vs skip,
+ * widen the window when too many fail, conclude) via LLM tool calls.
+ *
+ * Design: protocols are deterministic (retry/backoff lives in `retry.ts`,
+ * anti-bot detection lives in `anti-bot.ts`). The orchestrator only steps
+ * in for *judgment* calls where a hand-tuned heuristic would break the
+ * moment the world changes. Cost ceiling: hard-capped at spec.maxCostUSD,
+ * and each control-loop iteration is a single LLM call (~1.5s, ~$0.005).
+ *
+ * Tool surface (LLM-callable):
+ *   getJobState()        — what's done, what failed, current cost
+ *   resampleWayback(...) — replace targets for a URL with a new sample
+ *   retryTarget(...)     — re-attempt a single failed/skipped target
+ *   markSkipped(...)     — terminal skip with reason
+ *   concludeJob()        — exit the loop
+ *
+ * The orchestrator runs the initial fan-out via `runJob` first (so the
+ * deterministic happy path doesn't pay LLM tax), then enters the loop only
+ * if the result needs intervention.
+ */
+import { Brain } from '../brain/index.js';
+import { type AuditFn } from './queue.js';
+import type { Job } from './types.js';
+export interface OrchestrateJobOptions {
+    auditFn: AuditFn;
+    /** Persistence dir override (tests). */
+    dir?: string;
+    /** Cap on agent control-loop iterations. Default 8. */
+    maxIterations?: number;
+    /** Override the LLM provider (tests). Defaults to the default Brain. */
+    brain?: Brain;
+    /** When true, log every tool call. */
+    verbose?: boolean;
+}
+export declare function orchestrateJob(job: Job, opts: OrchestrateJobOptions): Promise<Job>;
+/** Cheap deterministic check: did the fan-out leave anything worth fixing? */
+declare function needsIntervention(job: Job): boolean;
+/** Re-export for tests / callers that want to inspect what would have run. */
+export { needsIntervention };
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/jobs/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/jobs/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAEzC,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,YAAY,CAAA;AAGjD,OAAO,KAAK,EAAE,GAAG,EAA6B,MAAM,YAAY,CAAA;AAEhE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,wEAAwE;IACxE,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAkCD,wBAAsB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,GAAG,CAAC,CAmDxF;AAED,8EAA8E;AAC9E,iBAAS,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAa5C;AA+JD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/jobs/orchestrator.js

@@ -0,0 +1,282 @@
+/**
+ * Agentic orchestrator — wraps `runJob` with a control loop that handles
+ * strategic decisions (re-sample broken wayback snapshots, retry vs skip,
+ * widen the window when too many fail, conclude) via LLM tool calls.
+ *
+ * Design: protocols are deterministic (retry/backoff lives in `retry.ts`,
+ * anti-bot detection lives in `anti-bot.ts`). The orchestrator only steps
+ * in for *judgment* calls where a hand-tuned heuristic would break the
+ * moment the world changes. Cost ceiling: hard-capped at spec.maxCostUSD,
+ * and each control-loop iteration is a single LLM call (~1.5s, ~$0.005).
+ *
+ * Tool surface (LLM-callable):
+ *   getJobState()        — what's done, what failed, current cost
+ *   resampleWayback(...) — replace targets for a URL with a new sample
+ *   retryTarget(...)     — re-attempt a single failed/skipped target
+ *   markSkipped(...)     — terminal skip with reason
+ *   concludeJob()        — exit the loop
+ *
+ * The orchestrator runs the initial fan-out via `runJob` first (so the
+ * deterministic happy path doesn't pay LLM tax), then enters the loop only
+ * if the result needs intervention.
+ */
+import { generateText, tool, jsonSchema, stepCountIs } from 'ai';
+import { Brain } from '../brain/index.js';
+import { resolveProviderApiKey, resolveProviderModelName } from '../provider-defaults.js';
+import { runJob } from './queue.js';
+import { saveJob, appendIndexEntry } from './store.js';
+import { discoverWaybackSnapshots } from '../discover/wayback.js';
+const SYSTEM_PROMPT = `You are an audit-job orchestrator.
+
+Your job: bring this audit job to a high-quality completion. After the initial fan-out has run, decide whether and how to fix gaps:
+  - If multiple wayback snapshots for the same URL came back blocked or scored 0, the snapshots are likely broken archive captures. Re-sample more snapshots in the same window using the resampleWayback tool.
+  - If a single target failed with a transient error, retry it.
+  - If a target is structurally unfixable (anti-bot, persistent 4xx, total content failure), mark it skipped with a clear reason.
+  - When the job is in good shape OR you've hit diminishing returns OR cost is approaching the cap, call concludeJob.
+
+Rules:
+  - You MUST stay under spec.maxCostUSD when set.
+  - Do not retry the same target more than twice.
+  - Do not resample the same URL more than once.
+  - When in doubt, conclude. A clean partial job is better than an over-fitted one.
+  - Reply only with tool calls until you call concludeJob.
+`;
+export async function orchestrateJob(job, opts) {
+    const verbose = opts.verbose ?? false;
+    // Phase 1: deterministic fan-out (no LLM in the loop).
+    await runJob(job, { auditFn: opts.auditFn, dir: opts.dir });
+    const state = {
+        job,
+        resamples: new Map(),
+        retries: new Map(),
+        concluded: false,
+        reason: '',
+    };
+    // Phase 2: only invoke the agent if the run needs intervention.
+    if (!needsIntervention(job)) {
+        if (verbose)
+            console.log('  [orchestrator] no intervention needed');
+        return job;
+    }
+    if (verbose) {
+        const failed = job.results.filter(r => r.status === 'failed').length;
+        const skipped = job.results.filter(r => r.status === 'skipped').length;
+        console.log(`  [orchestrator] entering loop · failed=${failed} · skipped=${skipped} · cost=$${job.totalCostUSD.toFixed(2)}`);
+    }
+    // Default to the same provider as the audit pipeline (claude-code via
+    // subscription, no API key required). If the operator already supplied a
+    // brain, respect that.
+    const brain = opts.brain ?? defaultBrain();
+    const tools = buildTools(state, opts, verbose);
+    const model = await brain.getLanguageModel({ provider: 'claude-code' });
+    const result = await generateText({
+        model,
+        system: SYSTEM_PROMPT,
+        prompt: 'The fan-out has completed. Call getJobState first to see what happened, then take corrective actions, then call concludeJob.',
+        tools,
+        stopWhen: stepCountIs(opts.maxIterations ?? 8),
+    });
+    if (verbose) {
+        console.log(`  [orchestrator] finishReason=${result.finishReason}  steps=${result.steps.length}  toolCalls=${result.steps.reduce((acc, s) => acc + s.toolCalls.length, 0)}`);
+        if (result.text)
+            console.log(`  [orchestrator] final-text: ${result.text.slice(0, 200)}`);
+    }
+    if (!state.concluded) {
+        state.reason = 'orchestrator: max iterations reached without explicit conclude';
+    }
+    // Persist final state.
+    saveJob(state.job, opts.dir);
+    appendIndexEntry(state.job, opts.dir);
+    return state.job;
+}
+/** Cheap deterministic check: did the fan-out leave anything worth fixing? */
+function needsIntervention(job) {
+    const failed = job.results.filter(r => r.status === 'failed').length;
+    const ok = job.results.filter(r => r.status === 'ok');
+    const skipped = job.results.filter(r => r.status === 'skipped').length;
+    // Coverage: anything missing or failed is an intervention candidate.
+    if (failed > 0)
+        return true;
+    if (ok.length + skipped < job.targets.length)
+        return true;
+    // Quality: zero-scored ok results from wayback snapshots almost always
+    // indicate a broken archive capture (anti-bot got past detection, or the
+    // archived page is truncated). Treat as intervention-worthy.
+    const zeroScored = ok.filter(r => r.snapshotUrl && (r.rollupScore ?? -1) === 0).length;
+    if (zeroScored > 0)
+        return true;
+    return false;
+}
+function buildTools(state, opts, verbose) {
+    return {
+        getJobState: tool({
+            description: 'Return the current job state — targets, results, totalCostUSD, maxCostUSD, recent failures, and which URLs already have re-sampled targets.',
+            inputSchema: jsonSchema({ type: 'object', properties: {} }),
+            execute: async () => {
+                const j = state.job;
+                const groupedByUrl = new Map();
+                for (const r of j.results) {
+                    const k = r.url;
+                    if (!groupedByUrl.has(k))
+                        groupedByUrl.set(k, []);
+                    groupedByUrl.get(k).push(r);
+                }
+                const summary = {
+                    jobId: j.jobId,
+                    status: j.status,
+                    totalCostUSD: j.totalCostUSD,
+                    maxCostUSD: j.spec.maxCostUSD ?? null,
+                    targets: j.targets.length,
+                    ok: j.results.filter(r => r.status === 'ok').length,
+                    failed: j.results.filter(r => r.status === 'failed').length,
+                    skipped: j.results.filter(r => r.status === 'skipped').length,
+                    retriesUsed: Array.from(state.retries.entries()).map(([k, n]) => ({ key: k, retries: n })),
+                    resamplesUsed: Array.from(state.resamples.values()).filter(r => r.attempted).map(r => r.url),
+                    byUrl: Array.from(groupedByUrl.entries()).map(([url, rows]) => ({
+                        url,
+                        snapshots: rows.length,
+                        ok: rows.filter(r => r.status === 'ok').length,
+                        failed: rows.filter(r => r.status === 'failed').length,
+                        skipped: rows.filter(r => r.status === 'skipped').length,
+                        zeroScored: rows.filter(r => r.status === 'ok' && (r.rollupScore ?? 0) === 0).length,
+                    })),
+                    failureSamples: j.results.filter(r => r.status === 'failed').slice(0, 5).map(r => ({
+                        url: r.url, snapshotUrl: r.snapshotUrl, error: r.error,
+                    })),
+                    skippedSamples: j.results.filter(r => r.status === 'skipped').slice(0, 5).map(r => ({
+                        url: r.url, snapshotUrl: r.snapshotUrl, reason: r.error,
+                    })),
+                };
+                if (verbose)
+                    console.log('  [orchestrator] getJobState');
+                return summary;
+            },
+        }),
+        resampleWayback: tool({
+            description: 'Discover N additional wayback snapshots for a URL and audit them. Use when several existing snapshots for that URL came back blocked or zero-scored — broken archive captures cluster, so re-sampling a different month often produces good ones. Each URL can only be resampled once per orchestrator run.',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: {
+                    url: { type: 'string' },
+                    count: { type: 'integer', minimum: 1, maximum: 8 },
+                    since: { type: 'string', description: 'ISO date lower bound' },
+                    until: { type: 'string', description: 'ISO date upper bound' },
+                },
+                required: ['url', 'count'],
+            }),
+            execute: async ({ url, count, since, until }) => {
+                if (state.resamples.has(url)) {
+                    return { error: `already resampled ${url} — skip and conclude or retry individual targets instead` };
+                }
+                if (overBudget(state))
+                    return { error: 'cost cap reached — conclude job' };
+                const action = { url, count, since, until, attempted: true };
+                state.resamples.set(url, action);
+                if (verbose)
+                    console.log(`  [orchestrator] resampleWayback ${url} count=${count}`);
+                try {
+                    const targets = await discoverWaybackSnapshots(url, { count, since, until });
+                    if (targets.length === 0)
+                        return { added: 0, error: 'CDX returned zero captures for that window' };
+                    // De-dupe against snapshots we already audited.
+                    const existing = new Set(state.job.results.map(r => r.snapshotUrl ?? r.url));
+                    const fresh = targets.filter(t => !existing.has(t.snapshotUrl ?? t.url));
+                    if (fresh.length === 0)
+                        return { added: 0, note: 'all sampled snapshots were already audited; widen the window or pick a different URL' };
+                    state.job.targets.push(...fresh);
+                    // Run only the new targets through the queue with resume=true.
+                    await runJob(state.job, { auditFn: opts.auditFn, dir: opts.dir, resume: true });
+                    const newOk = fresh.filter(t => state.job.results.some(r => (r.snapshotUrl ?? r.url) === (t.snapshotUrl ?? t.url) && r.status === 'ok')).length;
+                    return { added: fresh.length, newlyOk: newOk, totalCostUSD: state.job.totalCostUSD };
+                }
+                catch (err) {
+                    return { error: err.message };
+                }
+            },
+        }),
+        retryTarget: tool({
+            description: 'Re-attempt a single failed or skipped target. Use only for transient failures. Hard cap: 2 retries per target per orchestrator run.',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: {
+                    url: { type: 'string' },
+                    snapshotUrl: { type: 'string' },
+                },
+                required: ['url'],
+            }),
+            execute: async ({ url, snapshotUrl }) => {
+                const key = snapshotUrl ?? url;
+                const used = state.retries.get(key) ?? 0;
+                if (used >= 2)
+                    return { error: `retry budget for ${key} exhausted (2 used)` };
+                if (overBudget(state))
+                    return { error: 'cost cap reached — conclude job' };
+                state.retries.set(key, used + 1);
+                if (verbose)
+                    console.log(`  [orchestrator] retryTarget ${key} attempt=${used + 1}`);
+                // Drop the existing failed/skipped entry, then resume — the queue will pick the missing target up.
+                state.job.results = state.job.results.filter(r => (r.snapshotUrl ?? r.url) !== key);
+                await runJob(state.job, { auditFn: opts.auditFn, dir: opts.dir, resume: true });
+                const newEntry = state.job.results.find(r => (r.snapshotUrl ?? r.url) === key);
+                return { status: newEntry?.status ?? 'unknown', error: newEntry?.error, totalCostUSD: state.job.totalCostUSD };
+            },
+        }),
+        markSkipped: tool({
+            description: 'Terminally mark a target as skipped (no further retries). Use for structurally unfixable failures — persistent 4xx, anti-bot, dead URL.',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: {
+                    url: { type: 'string' },
+                    snapshotUrl: { type: 'string' },
+                    reason: { type: 'string' },
+                },
+                required: ['url', 'reason'],
+            }),
+            execute: async ({ url, snapshotUrl, reason }) => {
+                const key = snapshotUrl ?? url;
+                const idx = state.job.results.findIndex(r => (r.snapshotUrl ?? r.url) === key);
+                if (idx >= 0) {
+                    state.job.results[idx] = { ...state.job.results[idx], status: 'skipped', error: reason };
+                }
+                else {
+                    state.job.results.push({ url, snapshotUrl, status: 'skipped', error: reason });
+                }
+                saveJob(state.job, opts.dir);
+                if (verbose)
+                    console.log(`  [orchestrator] markSkipped ${key}: ${reason}`);
+                return { ok: true };
+            },
+        }),
+        concludeJob: tool({
+            description: 'End the orchestrator loop. Provide a one-sentence reason summarizing the final state.',
+            inputSchema: jsonSchema({
+                type: 'object',
+                properties: { reason: { type: 'string' } },
+                required: ['reason'],
+            }),
+            execute: async ({ reason }) => {
+                state.concluded = true;
+                state.reason = reason;
+                if (verbose)
+                    console.log(`  [orchestrator] concludeJob: ${reason}`);
+                return { concluded: true };
+            },
+        }),
+    };
+}
+function overBudget(state) {
+    const cap = state.job.spec.maxCostUSD;
+    if (typeof cap !== 'number')
+        return false;
+    // Leave 10% headroom so the next single audit doesn't push us over.
+    return state.job.totalCostUSD >= cap * 0.9;
+}
+/** Re-export for tests / callers that want to inspect what would have run. */
+export { needsIntervention };
+function defaultBrain() {
+    const provider = 'claude-code';
+    const model = resolveProviderModelName(provider);
+    const apiKey = resolveProviderApiKey(provider);
+    return new Brain({ provider, model, apiKey, vision: false, llmTimeoutMs: 60_000 });
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/jobs/orchestrator.js.map

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

package/dist/jobs/queue.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Job runner — bounded-concurrency fan-out over the audit pipeline.
+ *
+ * Synchronous in the sense that `runJob()` returns when every target has been
+ * processed (ok, failed, or skipped). Crash safety: every individual result
+ * is persisted to disk as soon as it lands, so killing the process leaves a
+ * resumable record (resume is a future addition; today the partial state
+ * is just observable).
+ *
+ * `auditFn` is injected so tests can run the queue without touching
+ * Playwright/LLMs.
+ */
+import type { Job, JobTarget } from './types.js';
+import { type RetryPolicy } from './retry.js';
+export interface AuditFn {
+    (target: JobTarget, opts: Job['spec']['audit']): Promise<{
+        runId: string;
+        resultPath: string;
+        rollupScore?: number;
+        pageType?: string;
+        costUSD?: number;
+        tokensPath?: string;
+        /**
+         * When set, the result was deterministically classified as blocked /
+         * anti-bot — the queue records `status: 'skipped'` with this reason
+         * instead of `'ok'`, so leaderboards don't include a misleading score.
+         */
+        blockedReason?: string;
+    }>;
+}
+export interface RunJobOptions {
+    auditFn: AuditFn;
+    /** Persistence dir override (tests). */
+    dir?: string;
+    /** Concurrency override; falls back to spec.concurrency, then 2. */
+    concurrency?: number;
+    /** Per-target failure swallower — defaults to recording the error and continuing. */
+    onError?: (target: JobTarget, error: Error) => 'continue' | 'abort';
+    /** Retry policy applied around each `auditFn` call. Pass `null` to disable retry. */
+    retryPolicy?: RetryPolicy | null;
+    /** When true, skip targets that already have a non-failed result on the job (used by `bad jobs resume`). */
+    resume?: boolean;
+}
+export declare function runJob(job: Job, opts: RunJobOptions): Promise<Job>;
+//# sourceMappingURL=queue.d.ts.map

package/dist/jobs/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/jobs/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAkB,SAAS,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,EAAmC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAE9E,MAAM,WAAW,OAAO;IACtB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;QACvD,KAAK,EAAE,MAAM,CAAA;QACb,UAAU,EAAE,MAAM,CAAA;QAClB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB;;;;WAIG;QACH,aAAa,CAAC,EAAE,MAAM,CAAA;KACvB,CAAC,CAAA;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,KAAK,UAAU,GAAG,OAAO,CAAA;IACnE,qFAAqF;IACrF,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;IAChC,4GAA4G;IAC5G,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAID,wBAAsB,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAwCxE"}