wotann 0.5.0 → 0.5.39

package/dist/autopilot/run-manifest.js

@@ -0,0 +1,261 @@
+/**
+ * Overnight-run manifest — produces a human-reviewable summary of a
+ * long-running autopilot session. Inspired by 1jehuang/jcode's
+ * "morning report" pattern: when an agent runs unattended for hours,
+ * the operator wakes up to a curated digest instead of trawling raw
+ * logs.
+ *
+ * Pure derivation from a {@link Trajectory}: pass in the trajectory
+ * captured by `TrajectoryRecorder`, get back a manifest object plus
+ * renderers (markdown / JSON) the surface of your choice can persist.
+ *
+ *   const manifest = buildManifest(trajectory, { taskTitle, costUsd });
+ *   const md       = renderManifestMarkdown(manifest);
+ *   await fs.writeFile(`runs/${manifest.id}.md`, md);
+ *
+ * QUALITY BARS
+ *   - QB#1 No vendor bias — operates on plain Trajectory frames.
+ *   - QB#3 Honest stub — when frames are missing, sections render
+ *     as "(none)" instead of inventing content.
+ *   - QB#7 Per-call state — pure function of (trajectory, options).
+ */
+// ── Build ──────────────────────────────────────────────────────
+const FILE_TOOLS = new Set([
+    "Write",
+    "Edit",
+    "MultiEdit",
+    "create_text_file",
+    "edit_memory",
+    "replace_content",
+]);
+const BASH_TOOLS = new Set(["Bash", "execute_shell_command", "shell"]);
+/**
+ * Build a manifest from a finished trajectory. Pure: never mutates
+ * input. Frames without `endedAt` (still running) are summarised with
+ * `status: "in-progress"`.
+ */
+export function buildManifest(trajectory, opts = {}) {
+    const startedAt = trajectory.startedAt;
+    const endedAt = trajectory.endedAt ?? Date.now();
+    const durationMs = Math.max(0, endedAt - startedAt);
+    const frameCounts = {};
+    const toolHits = new Map();
+    const fileMap = new Map();
+    const bash = [];
+    const errors = [];
+    const prompts = [];
+    let finalAnswer = null;
+    for (const f of trajectory.frames) {
+        frameCounts[f.kind] = (frameCounts[f.kind] ?? 0) + 1;
+        if (f.kind === "prompt") {
+            prompts.push(f.content);
+        }
+        else if (f.kind === "response") {
+            finalAnswer = f.content;
+        }
+        else if (f.kind === "tool_call") {
+            const tool = inferToolName(f);
+            toolHits.set(tool, (toolHits.get(tool) ?? 0) + 1);
+            if (FILE_TOOLS.has(tool)) {
+                const path = inferFilePath(f);
+                if (path) {
+                    const existing = fileMap.get(path);
+                    if (existing) {
+                        fileMap.set(path, { ...existing, count: existing.count + 1 });
+                    }
+                    else {
+                        fileMap.set(path, { tool, path, count: 1, firstSeq: f.seq });
+                    }
+                }
+            }
+            if (BASH_TOOLS.has(tool)) {
+                bash.push({
+                    cmd: inferBashCommand(f),
+                    seq: f.seq,
+                    success: true, // updated below if a matching tool_result indicates failure
+                    output: null,
+                });
+            }
+        }
+        else if (f.kind === "tool_result") {
+            const lower = f.content.toLowerCase();
+            if (lower.includes("error") || lower.includes("failed") || lower.includes("exit code")) {
+                errors.push({ seq: f.seq, content: clip(f.content, 240), source: "tool_result" });
+                // Attach failure to the most recent bash entry (best-effort heuristic).
+                const last = bash[bash.length - 1];
+                if (last && f.seq - last.seq <= 2) {
+                    bash[bash.length - 1] = { ...last, success: false, output: clip(f.content, 240) };
+                }
+            }
+            else {
+                const last = bash[bash.length - 1];
+                if (last && f.seq - last.seq <= 2 && last.output === null) {
+                    bash[bash.length - 1] = { ...last, output: clip(f.content, 240) };
+                }
+            }
+        }
+        else if (f.kind === "error") {
+            errors.push({ seq: f.seq, content: clip(f.content, 240), source: "trajectory" });
+        }
+    }
+    const status = inferStatus(trajectory.frames, errors, trajectory.endedAt !== undefined);
+    const promptLimit = typeof opts.promptCount === "number" ? opts.promptCount : 5;
+    return {
+        id: trajectory.id,
+        taskTitle: opts.taskTitle ?? deriveTaskTitle(prompts) ?? "(untitled run)",
+        startedAt,
+        endedAt,
+        durationMs,
+        costUsd: typeof opts.costUsd === "number" ? opts.costUsd : null,
+        frameCounts: Object.freeze({ ...frameCounts }),
+        fileChanges: Object.freeze([...fileMap.values()].sort((a, b) => a.firstSeq - b.firstSeq)),
+        bashCommands: Object.freeze(bash),
+        errors: Object.freeze(errors),
+        toolUsage: Object.freeze([...toolHits.entries()]
+            .map(([tool, count]) => ({ tool, count }))
+            .sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool))),
+        prompts: Object.freeze(prompts.slice(0, promptLimit)),
+        finalAnswer,
+        status,
+    };
+}
+function inferStatus(frames, errors, ended) {
+    if (!ended)
+        return "in-progress";
+    if (frames.length === 0)
+        return "in-progress";
+    // Look only at the tail — earlier errors that were recovered from
+    // shouldn't doom the whole run.
+    const tail = frames.slice(-5);
+    const tailHasError = tail.some((f) => f.kind === "error" || (f.kind === "tool_result" && /error|fail/i.test(f.content)));
+    if (errors.length > 0 && tailHasError)
+        return "failed";
+    return "completed";
+}
+function inferToolName(frame) {
+    if (frame.metadata && typeof frame.metadata["tool"] === "string") {
+        return frame.metadata["tool"];
+    }
+    // Fall back to the first word of the content (e.g. "Write /tmp/x.txt …")
+    const head = frame.content.split(/\s|[(]/, 1)[0] ?? frame.content;
+    return head || "unknown";
+}
+function inferFilePath(frame) {
+    if (frame.metadata && typeof frame.metadata["path"] === "string") {
+        return frame.metadata["path"];
+    }
+    if (frame.metadata && typeof frame.metadata["filePath"] === "string") {
+        return frame.metadata["filePath"];
+    }
+    // Try to pull a path from the content.
+    const m = frame.content.match(/(?:^|\s)(\/[^\s]+|\.[\\/][^\s]+|[^\s]+\.[a-zA-Z0-9]+)/);
+    return m && m[1] ? m[1] : null;
+}
+function inferBashCommand(frame) {
+    if (frame.metadata && typeof frame.metadata["cmd"] === "string") {
+        return frame.metadata["cmd"];
+    }
+    if (frame.metadata && typeof frame.metadata["command"] === "string") {
+        return frame.metadata["command"];
+    }
+    return clip(frame.content, 200);
+}
+function deriveTaskTitle(prompts) {
+    if (prompts.length === 0)
+        return null;
+    const first = (prompts[0] ?? "").trim();
+    if (first.length === 0)
+        return null;
+    return first.slice(0, 80);
+}
+function clip(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max - 1) + "…";
+}
+// ── Renderers ──────────────────────────────────────────────────
+/**
+ * Render the manifest as Markdown suitable for a morning email or
+ * checked-in run-log.md.
+ */
+export function renderManifestMarkdown(manifest) {
+    const lines = [];
+    const startISO = new Date(manifest.startedAt).toISOString();
+    const endISO = new Date(manifest.endedAt).toISOString();
+    const durMin = Math.round(manifest.durationMs / 60_000);
+    lines.push(`# Run ${manifest.id} — ${statusBadge(manifest.status)}`);
+    lines.push("");
+    lines.push(`**Task:** ${manifest.taskTitle}`);
+    lines.push(`**Started:** ${startISO}`);
+    lines.push(`**Ended:** ${endISO}`);
+    lines.push(`**Duration:** ${durMin} min`);
+    if (manifest.costUsd !== null) {
+        lines.push(`**Cost:** $${manifest.costUsd.toFixed(4)}`);
+    }
+    lines.push("");
+    if (manifest.prompts.length > 0) {
+        lines.push("## Prompts");
+        for (const p of manifest.prompts)
+            lines.push(`- ${clip(p.replace(/\n/g, " "), 200)}`);
+        lines.push("");
+    }
+    lines.push("## Tool usage");
+    if (manifest.toolUsage.length === 0) {
+        lines.push("(none)");
+    }
+    else {
+        for (const t of manifest.toolUsage)
+            lines.push(`- \`${t.tool}\` × ${t.count}`);
+    }
+    lines.push("");
+    lines.push("## File changes");
+    if (manifest.fileChanges.length === 0) {
+        lines.push("(none)");
+    }
+    else {
+        for (const fc of manifest.fileChanges) {
+            lines.push(`- \`${fc.path}\` (${fc.tool}, ${fc.count} edit${fc.count === 1 ? "" : "s"})`);
+        }
+    }
+    lines.push("");
+    lines.push("## Bash commands");
+    if (manifest.bashCommands.length === 0) {
+        lines.push("(none)");
+    }
+    else {
+        for (const b of manifest.bashCommands) {
+            const tag = b.success ? "✓" : "✗";
+            lines.push(`- ${tag} \`${clip(b.cmd, 120)}\``);
+        }
+    }
+    lines.push("");
+    if (manifest.errors.length > 0) {
+        lines.push("## Errors");
+        for (const e of manifest.errors) {
+            lines.push(`- (#${e.seq}, ${e.source}) ${clip(e.content, 200)}`);
+        }
+        lines.push("");
+    }
+    if (manifest.finalAnswer) {
+        lines.push("## Final answer");
+        lines.push("```");
+        lines.push(clip(manifest.finalAnswer, 4000));
+        lines.push("```");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function statusBadge(status) {
+    if (status === "completed")
+        return "✓ completed";
+    if (status === "failed")
+        return "✗ failed";
+    return "… in-progress";
+}
+/**
+ * Render a JSON form of the manifest (compact representation).
+ */
+export function renderManifestJson(manifest) {
+    return JSON.stringify(manifest, null, 2);
+}
+//# sourceMappingURL=run-manifest.js.map

package/dist/autopilot/run-manifest.js.map

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

package/dist/browser/adaptive-selectors.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Adaptive selectors — selectors that survive DOM redesigns by tracking
+ * element fingerprints and auto-relocating via fuzzy match.
+ *
+ * Modeled on D4Vinci/Scrapling's adaptive-selector pattern: a CSS / XPath
+ * selector usually breaks when a site redesigns. Adaptive selectors store
+ * enough metadata about the element (text, position-in-tree, sibling
+ * context, attributes) that the lookup can FALL BACK to fuzzy matching
+ * when the original selector misses.
+ *
+ * Pure data layer — accepts a typed `ElementShape` (a plain object), NOT
+ * a real DOM node. The driver (chrome-bridge / camoufox-backend / agentic-
+ * browser) is responsible for projecting real elements into ElementShape
+ * before calling buildFingerprint / score / findBestMatch. This keeps the
+ * module DOM-free, deterministic, and trivially unit-testable.
+ *
+ * QUALITY BARS
+ *   - QB#1 immutable: every fingerprint, selector, and result type is
+ *     `readonly`. mergeFingerprints returns a NEW fingerprint; it never
+ *     mutates either input.
+ *   - QB#3 honest tagged results: findBestMatch returns
+ *     { ok: true, element, score } | { ok: false, reason } so callers
+ *     can branch without throwing or guessing. score() returns a clamped
+ *     [0,1] number — never NaN, never out of range.
+ *   - QB#7 stateless: zero module-level mutable state. All inputs are
+ *     parameters; outputs are pure functions of inputs. Threshold and
+ *     scoring weights are exported `const`s callers can introspect.
+ *   - QB#11 sibling-site: this module ONLY scores plain shapes — it does
+ *     not touch DOM, CDP, or Playwright. The shape projection lives
+ *     centrally in chrome-bridge / camoufox-backend (see those files).
+ *   - QB#19 zombie-free: every exported symbol is referenced by tests
+ *     and intended for the agentic-browser caller. No dead instances.
+ */
+/**
+ * A serialized snapshot of a DOM element. The driver projects a real
+ * DOM node into this shape before handing it to the scorer.
+ *
+ * `prevSiblingText` / `nextSiblingText` are optional because root /
+ * detached elements have no siblings. `attrs` excludes `id` and `class`
+ * (those live in their own fields) to keep the attr-set comparison
+ * focused on stable hooks like `data-testid`, `aria-label`, `name`,
+ * `role`, `type`, `href`, `name`, etc.
+ */
+export interface ElementShape {
+    readonly tag: string;
+    readonly id?: string;
+    readonly classNames: readonly string[];
+    readonly textContent: string;
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly prevSiblingText?: string;
+    readonly nextSiblingText?: string;
+    readonly cssPath: string;
+    readonly xpath: string;
+}
+/**
+ * The persisted fingerprint of an element. Computed once at capture
+ * time, then re-scored against live candidates whenever the original
+ * selector misses.
+ *
+ * `textContent` is bounded to 200 chars so fingerprints stay small in
+ * storage and scoring stays O(1) per candidate.
+ *
+ * `siblingContext` is a single summarized string ("prev<<X>>next<<Y>>")
+ * to make equality / similarity checks cheap.
+ */
+export interface ElementFingerprint {
+    readonly tag: string;
+    readonly id?: string;
+    readonly classNames: readonly string[];
+    readonly textContent: string;
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly siblingContext: string;
+    readonly cssPath: string;
+    readonly xpath: string;
+}
+/**
+ * The bundle the agentic browser persists per logical selector.
+ *
+ * `originalSelector` is what the user / planner asked for. When a fresh
+ * `document.querySelector(originalSelector)` returns null, the caller
+ * walks `fallbackStrategies` and rescores against `fingerprint` to
+ * relocate the drifted element.
+ */
+export interface AdaptiveSelector {
+    readonly originalSelector: string;
+    readonly fingerprint: ElementFingerprint;
+    readonly fallbackStrategies: readonly string[];
+}
+export declare const SCORE_WEIGHTS: {
+    readonly tag: 0.2;
+    readonly id: 0.3;
+    readonly classOverlap: 0.2;
+    readonly textJaccard: 0.2;
+    readonly attrSetOverlap: 0.1;
+};
+/**
+ * Default minimum score for findBestMatch to consider a candidate a
+ * match. Below this, callers receive { ok: false, reason: "below_threshold" }.
+ */
+export declare const DEFAULT_MATCH_THRESHOLD = 0.6;
+/**
+ * Build a fingerprint from an element shape. Pure. Input is not
+ * mutated; output is fully frozen.
+ */
+export declare function buildFingerprint(element: ElementShape): ElementFingerprint;
+/**
+ * Wrap a selector + element into a persistable AdaptiveSelector with
+ * a built-in ordered list of fallback strategies. The strategies are
+ * NAMES of approaches, not executable code — the caller's lookup
+ * engine picks each one up and executes it against a live DOM.
+ */
+export declare function buildAdaptiveSelector(args: {
+    readonly selector: string;
+    readonly element: ElementShape;
+}): AdaptiveSelector;
+/**
+ * Score a candidate element against a fingerprint. Returns a number
+ * in [0,1]. Pure — never throws, never returns NaN.
+ *
+ * Components (weights from SCORE_WEIGHTS):
+ *   - tag match           : 1 if exact, else 0
+ *   - id match            : 1 if both have an id and they match, else
+ *                           0. If neither has an id, the weight is
+ *                           redistributed proportionally to other
+ *                           components (we don't penalize id-less elts).
+ *   - class overlap       : Jaccard of class name sets
+ *   - text Jaccard        : Jaccard of top-K tokens, dampened when
+ *                           total token count is below LOW_INFO threshold
+ *   - attr set overlap    : Jaccard of "k=v" pairs
+ */
+export declare function score(candidate: ElementShape, fingerprint: ElementFingerprint): number;
+export interface MatchOk {
+    readonly ok: true;
+    readonly element: ElementShape;
+    readonly score: number;
+}
+export interface MatchFail {
+    readonly ok: false;
+    readonly reason: "no_candidates" | "below_threshold" | "invalid_fingerprint";
+    readonly bestScore?: number;
+}
+export type MatchResult = MatchOk | MatchFail;
+export interface FindBestMatchOptions {
+    readonly threshold?: number;
+}
+/**
+ * Pick the highest-scoring candidate >= threshold (default 0.6).
+ * Returns a tagged union — never throws.
+ */
+export declare function findBestMatch(candidates: readonly ElementShape[], fingerprint: ElementFingerprint, options?: FindBestMatchOptions): MatchResult;
+/**
+ * Merge a previously stored fingerprint with a freshly observed one.
+ * Used to "drift" the stored snapshot as a site evolves so we don't
+ * keep re-matching against stale state.
+ *
+ * Strategy:
+ *   - Tag: prefer prior (tags rarely change; if they do the selector is
+ *     probably wrong anyway)
+ *   - id: prefer observed (ids that come and go are rare; observed wins)
+ *   - classNames: union (a redesign typically ADDS classes; rarely
+ *     removes the originals immediately)
+ *   - textContent: prefer observed (text is the most volatile)
+ *   - attrs: per-key prefer observed; keep prior keys not present in
+ *     observed (so transient render gaps don't drop a stable data-id)
+ *   - siblingContext / cssPath / xpath: prefer observed
+ *
+ * Pure: neither input is mutated.
+ */
+export declare function mergeFingerprints(prior: ElementFingerprint, observed: ElementFingerprint): ElementFingerprint;
+//# sourceMappingURL=adaptive-selectors.d.ts.map

package/dist/browser/adaptive-selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-selectors.d.ts","sourceRoot":"","sources":["../../src/browser/adaptive-selectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AAID,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAsF3C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,kBAAkB,CAY1E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;CAChC,GAAG,gBAAgB,CAcnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,kBAAkB,GAAG,MAAM,CAyDtF;AAID,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,GAAG,qBAAqB,CAAC;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,SAAS,YAAY,EAAE,EACnC,WAAW,EAAE,kBAAkB,EAC/B,OAAO,GAAE,oBAAyB,GACjC,WAAW,CA2Cb;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,kBAAkB,GAC3B,kBAAkB,CA2BpB"}