browxai 0.7.0

package/dist/util/deadline.js

@@ -0,0 +1,62 @@
+// anti-wedge deadline.
+//
+// Several inner paths have no Playwright/CDP timeout (`page.evaluate`,
+// CDP `send`, a wedged renderer). `withDeadline` races the operation against
+// a timer so the *tool always returns* within the deadline. It cannot cancel
+// a hung CDP send (the orphaned op settles/errors in the background) — but the
+// agent is unblocked with a structured error instead of stalling forever.
+export const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+export const MIN_ACTION_TIMEOUT_MS = 1;
+export const MAX_ACTION_TIMEOUT_MS = 3_600_000; // 1h hard ceiling
+export class DeadlineError extends Error {
+    label;
+    ms;
+    constructor(label, ms) {
+        super(`anti-wedge timeout: "${label}" did not complete within ${ms}ms. ` +
+            `This is a RECOVERABLE signal, not a fatal error — the tool returned ` +
+            `instead of stalling. Decide which case applies: (a) a transient ` +
+            `hiccup — retry the call ONCE; (b) repeated timeouts on this session ` +
+            `(snapshot / navigate / screenshot all timing out) — the session is ` +
+            `WEDGED: discard it with \`close_session\`, then \`open_session\` a ` +
+            `fresh one; retrying or re-navigating in place will NOT recover it; ` +
+            `(c) one genuinely slow call — raise \`timeoutMs\` for THAT call only. ` +
+            `Raising \`timeoutMs\` never fixes a wedged session, and values near ` +
+            `the 1h ceiling are essentially always a mistake.`);
+        this.label = label;
+        this.ms = ms;
+        this.name = "DeadlineError";
+    }
+}
+/**
+ * Clamp a requested timeout into [MIN, MAX]. Returns the effective value plus
+ * an optional warning when the request was out of range (so the tool can
+ * surface "you asked for an insane timeout; clamped").
+ */
+export function clampTimeout(requested, fallback) {
+    const raw = requested ?? fallback;
+    if (raw > MAX_ACTION_TIMEOUT_MS) {
+        return {
+            ms: MAX_ACTION_TIMEOUT_MS,
+            warning: `timeoutMs=${raw} exceeds the 1h hard ceiling — clamped to ${MAX_ACTION_TIMEOUT_MS}ms. ` +
+                `A multi-minute action timeout is essentially always a mistake (a real ` +
+                `op completes in well under 5s; longer means a no-op/wedge).`,
+        };
+    }
+    if (raw < MIN_ACTION_TIMEOUT_MS)
+        return { ms: MIN_ACTION_TIMEOUT_MS };
+    return { ms: raw };
+}
+/**
+ * Race `p` against `ms`. Rejects with `DeadlineError` on expiry. The timer is
+ * always cleared (no leaked handles) whichever side wins.
+ */
+export function withDeadline(p, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new DeadlineError(label, ms)), ms);
+    });
+    return Promise.race([p, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}

package/dist/util/diagnostics.d.ts

@@ -0,0 +1,161 @@
+import type { SecretRegistry } from "./secrets.js";
+/** Categories a `diagnostics_note` insight can carry. Default `other`. */
+export type NoteCategory = "missing-primitive" | "workaround" | "perf-concern" | "ergonomic-friction" | "other";
+/** Severity a `diagnostics_note` can carry. Default `info`. */
+export type NoteSeverity = "info" | "warn" | "blocker";
+/** Eval-expression taxonomy buckets — heuristic substring-match classifier. */
+export type EvalTaxonomy = "dom-query" | "storage-access" | "computed-style" | "callback-trigger" | "feature-detect" | "custom";
+/** Structural redaction of a tool call's args. Keeps key names + types +
+ *  sizes; drops raw values for known large / sensitive payload fields. */
+export type RedactedArgs = Record<string, unknown>;
+export interface CallRecord {
+    kind: "call";
+    ts: string;
+    tool: string;
+    sessionId: string;
+    argsRedacted: RedactedArgs;
+    resultMeta: {
+        ok: boolean;
+        sizeBytes: number;
+        warningsCount: number;
+        failureKind?: string;
+    };
+    durationMs: number;
+    capabilityDenials: number;
+    agentId?: string;
+    evalJs?: {
+        exprSha: string;
+        exprHead: string;
+        returnType: string;
+        returnSizeBytes: number;
+        taxonomy: EvalTaxonomy;
+    };
+}
+export interface NoteRecord {
+    kind: "note";
+    ts: string;
+    sessionId: string;
+    insight: string;
+    category: NoteCategory;
+    severity: NoteSeverity;
+    ref?: string;
+    agentId?: string;
+}
+export type DiagnosticsRecord = CallRecord | NoteRecord;
+/** Default retention window in days. Mirrors the standing rule that
+ *  diagnostics is a development-time aid, not a long-term log archive. */
+export declare const DEFAULT_RETENTION_DAYS = 30;
+/** Args fields the recorder rewrites to the `<NAME>` alias before writing,
+ *  using the same `applyMaskDeep` the egress sinks do — so a secret echoed in
+ *  args never reaches the JSONL raw. (The masking layer at egress catches it
+ *  on result side; this catches it on args side.) */
+declare function maskedArgs(args: unknown, secrets: SecretRegistry | null): unknown;
+/** Resolve the diagnostics root path under the workspace. Rejects any
+ *  session id that escapes the diagnostics subdir (`../escape`,
+ *  absolute paths). The thrown error carries a stable prefix the dispatch
+ *  wrapper recognises to fall back to no-op. */
+export declare function resolveDiagnosticsPath(workspaceRoot: string, sessionId: string, serverStartIso: string): string;
+/** Returns the diagnostics root dir (creating it if needed). The path is
+ *  workspace.root-rooted by construction — caller passes `workspace.root`
+ *  from `resolveWorkspace()`. */
+export declare function ensureDiagnosticsRoot(workspaceRoot: string): string;
+/** Resolve retention window from env. Defaults to 30 days; negative /
+ *  non-numeric falls back to the default with no error. `0` disables the
+ *  sweep (everything is kept). */
+export declare function resolveRetentionDays(env?: NodeJS.ProcessEnv): number;
+/** Remove session directories whose newest JSONL file is older than the
+ *  retention window. `0` disables the sweep entirely. Best-effort: a
+ *  permission error on one session doesn't block the rest. */
+export declare function sweepRetention(workspaceRoot: string, retentionDays: number, now?: number): {
+    removed: string[];
+    kept: string[];
+};
+/** Remove a single session's diagnostics directory. Used on session close. */
+export declare function removeSessionDiagnostics(workspaceRoot: string, sessionId: string): boolean;
+/**
+ * The recorder. One instance per server. The capability gate is captured at
+ * construction; `enabled` is the public hot-path flag the dispatch wrapper
+ * checks BEFORE allocating anything (zero-overhead off-path).
+ */
+export declare class DiagnosticsRecorder {
+    /** Hot-path gate — checked at the dispatch boundary. When false, every
+     *  recorder method short-circuits to a no-op AND the dispatch wrapper
+     *  is expected to NOT enter the recorder code path at all. */
+    readonly enabled: boolean;
+    readonly serverStartIso: string;
+    readonly workspaceRoot: string;
+    readonly retentionDays: number;
+    /** Capability denials accumulator (process-wide). Mirrors the snapshot the
+     *  session-metrics module tracks per-session; diagnostics tracks it across
+     *  every session to surface a single "how many gate hits did this server
+     *  see" rollup in `diagnostics_report`. */
+    private denials;
+    constructor(opts: {
+        enabled: boolean;
+        workspaceRoot: string;
+        serverStartIso?: string;
+        retentionDays?: number;
+    });
+    /** Write one record. No-op when the recorder is disabled or the path
+     *  resolution fails (workspace escape — the call still runs, only the
+     *  recording is skipped). */
+    write(record: DiagnosticsRecord): void;
+    /** Increment the capability-denials counter — surfaced on
+     *  `diagnostics_report` so the agent's "tried to use a gated tool"
+     *  pattern is one read. */
+    noteDenial(): void;
+    /** Read-back: enumerate every record in the workspace's diagnostics
+     *  store. Order: by session id, then by file mtime (oldest first), then
+     *  by line order within a file. Used by the read-side query tools.
+     *  Best-effort — unreadable files are skipped. */
+    readAll(): DiagnosticsRecord[];
+    /** Snapshot the cumulative capability-denials counter. */
+    denialsCount(): number;
+}
+/** Structural redaction — keep keys + types + sizes, drop raw values for
+ *  known large / sensitive fields. Bounded depth. The output is small,
+ *  diff-friendly, and never includes a registered secret value (the
+ *  recorder applies the secrets mask on top of this before writing). */
+export declare function redactArgs(args: unknown, depth?: number): RedactedArgs;
+/** Heuristic substring classifier over the first 80 chars of an `eval_js`
+ *  expression. Drives the "what curated primitive is missing?" inference
+ *  downstream (high-count non-custom buckets → propose a primitive). */
+export declare function classifyEvalExpr(exprHead: string): EvalTaxonomy;
+export declare function failureKindOf(parsed: {
+    ok: false;
+    [k: string]: unknown;
+}): string;
+/** Build the `resultMeta` field for a recorded tool call. `firstJsonObj` is
+ *  the parsed first text item (when applicable); `sizeBytes` is the
+ *  JSON-string length of the entire content envelope; `warningsCount` is
+ *  pulled from the parsed object's `warnings` field when it's an array. */
+export declare function buildResultMeta(firstJsonObj: Record<string, unknown> | null, sizeBytes: number): CallRecord["resultMeta"];
+/** Build the eval_js-specific deep-capture envelope from a tool call's
+ *  args + result. Returns undefined when the tool isn't eval_js. */
+export declare function buildEvalJsCapture(toolName: string, args: unknown, firstJsonObj: Record<string, unknown> | null): CallRecord["evalJs"] | undefined;
+export interface ReportSummary {
+    perTool: Record<string, {
+        count: number;
+        failureCount: number;
+        p50Duration: number;
+        p95Duration: number;
+    }>;
+    topEvalJsPatterns: Array<{
+        exprSha: string;
+        exprHead: string;
+        count: number;
+        taxonomy: EvalTaxonomy;
+    }>;
+    capabilityDenials: Record<string, number>;
+    notesByCategory: Record<string, number>;
+    missingPrimitiveHypotheses: Array<{
+        taxonomy: EvalTaxonomy;
+        sampleHead: string;
+        count: number;
+    }>;
+}
+export declare function buildReportSummary(records: DiagnosticsRecord[], opts?: {
+    since?: string;
+    session?: string;
+}): ReportSummary;
+export { maskedArgs };