@pseolint/core 0.4.3 → 0.5.3

package/dist/ai/orchestrator/runner.js

@@ -0,0 +1,223 @@
+import { generateText } from "ai";
+import { estimateCostUsd } from "../cost.js";
+import { orchestratorTools } from "../tools/index.js";
+import { finishAuditTool, manifestSchema } from "./finish-tool.js";
+import { PageCache, withPageCache } from "./page-cache.js";
+import { buildSystemPrompt } from "./prompt.js";
+import { SessionState } from "./session.js";
+const FINISH_TOOL_NAME = "finish_audit";
+/**
+ * Run a single orchestrator session end-to-end. Returns the final
+ * `SessionResult` once the LLM calls `finish_audit`, the budget is
+ * exhausted, the abort signal fires, or the model errors out.
+ *
+ * No streaming yet — uses `generateText` for simpler test ergonomics with
+ * the existing `MockModel` (which only implements `doGenerate`). Phase 2
+ * follow-up swaps to `streamText` once we have a stream-capable mock and a
+ * web-app SSE endpoint to wire up.
+ */
+export async function runOrchestrator(opts) {
+    const session = new SessionState({
+        domain: opts.domain,
+        userId: opts.userId,
+        providerId: opts.providerId,
+        modelId: opts.modelId,
+        budget: opts.budget,
+        ndjsonPath: opts.ndjsonPath,
+        onEvent: opts.onEvent,
+    });
+    await session.start();
+    const baseTools = opts.tools ?? orchestratorTools;
+    const aiTools = {};
+    for (const [name, tool] of Object.entries(baseTools)) {
+        aiTools[name] = tool.toAiTool();
+    }
+    // The runner detects finish_audit by name and pulls the manifest from
+    // its tool-call input — the AI SDK ferries the rest through normally.
+    aiTools[FINISH_TOOL_NAME] = finishAuditTool.toAiTool();
+    const systemPrompt = buildSystemPrompt(session.caps);
+    let stopReason = "no_finish_called";
+    let modelError;
+    // Closure for per-step timing. prepareStep records start; onStepFinish
+    // reads + emits duration. generateText is sequential so the
+    // single-cell pattern is race-free.
+    let currentStepStartedAt = 0;
+    // Last tool-call count at which we injected a watchdog message. Used to
+    // suppress duplicate firings within the same multiple-of-N window when
+    // the orchestrator emits multiple tool calls per step.
+    let lastWatchdogAtToolCount = 0;
+    // Per-session page cache. `fetch_page` writes HTML here keyed by pageId;
+    // page-content-consuming tools read by pageId. AsyncLocalStorage threads
+    // it through the AI SDK's tool loop without expanding the tool API.
+    const pageCache = new PageCache();
+    try {
+        await withPageCache(pageCache, () => generateText({
+            model: opts.model,
+            system: systemPrompt,
+            tools: aiTools,
+            messages: [
+                {
+                    role: "user",
+                    content: `Audit ${opts.domain}. Produce a fix manifest covering integrity, discoverability, citation, and data per the methodology in the system prompt. Call finish_audit when done.`,
+                },
+            ],
+            stopWhen: ({ steps }) => {
+                if (session.isFinished())
+                    return true;
+                if (opts.signal?.aborted)
+                    return true;
+                if (session.budget.nextStopReason() !== null)
+                    return true;
+                // Pre-flight: refuse the next step if it would breach the USD or
+                // input-token cap based on the max-observed per-step cost so far.
+                // Reactive enforcement (nextStopReason) above catches breaches *after*
+                // they happen; this catches them *before*. Both fences exist because
+                // pre-flight is conservative (uses max-observed, not avg) and may
+                // miss anomalous future steps the average wouldn't predict.
+                if (session.budget.projectedNextStopReason() !== null)
+                    return true;
+                // Hard fallback against runaway loops; budget caps are the real guard.
+                return steps.length >= session.caps.maxToolCalls + 5;
+            },
+            prepareStep: async ({ messages }) => {
+                currentStepStartedAt = Date.now();
+                const interval = session.caps.watchdogIntervalCalls;
+                const toolCount = session.budget.snapshot().toolCallCount;
+                // Fire watchdog when we've crossed a multiple-of-interval boundary
+                // since the last firing. `lastWatchdogAtToolCount` rises monotonically
+                // so we never re-inject for the same window.
+                const lastBoundary = Math.floor(lastWatchdogAtToolCount / interval);
+                const currentBoundary = Math.floor(toolCount / interval);
+                if (interval > 0 && toolCount > 0 && currentBoundary > lastBoundary) {
+                    lastWatchdogAtToolCount = toolCount;
+                    await session.emit({ kind: "watchdog_injected", toolCallCount: toolCount });
+                    // Inject as a `user` role message, not `system`. Anthropic's API
+                    // rejects multiple system messages interspersed with user/assistant
+                    // turns ("Multiple system messages that are separated by user/
+                    // assistant messages functionality not supported"), and other
+                    // providers vary in tolerance. A user-role nudge is universally
+                    // accepted and reads natural ("hey, are you converging?").
+                    return {
+                        messages: [
+                            ...messages,
+                            {
+                                role: "user",
+                                content: `[watchdog] You've made ${toolCount} tool calls. ` +
+                                    `Hard cap is ${session.caps.maxToolCalls}. ` +
+                                    `Are you converging on a manifest? If not, summarize remaining gaps now and call finish_audit. ` +
+                                    `Partial manifests are still useful — prefer breadth over depth.`,
+                            },
+                        ],
+                    };
+                }
+                return undefined;
+            },
+            onStepFinish: async ({ toolCalls, toolResults, text, usage }) => {
+                const stepDurationMs = currentStepStartedAt > 0 ? Date.now() - currentStepStartedAt : undefined;
+                if (text) {
+                    await session.emit({ kind: "thought", text });
+                }
+                for (const c of toolCalls) {
+                    await session.emit({
+                        kind: "tool_call",
+                        toolName: c.toolName,
+                        input: c.input,
+                    });
+                }
+                for (const r of toolResults) {
+                    await session.emit({
+                        kind: "tool_result",
+                        toolName: r.toolName,
+                        result: r.output,
+                    });
+                    // External-probe cost ingestion. Tools that hit billable APIs
+                    // (query_serp, ask_ai_engine) include `apiCostUsd` in their data
+                    // payload. The orchestrator's USD cap would otherwise be fiction
+                    // for sessions that lean on probes — this is the only place where
+                    // non-LLM costs get folded into the session budget.
+                    const probeCost = extractProbeCost(r.output);
+                    if (probeCost > 0)
+                        session.budget.recordExternalCost(probeCost);
+                    if (r.toolName === FINISH_TOOL_NAME) {
+                        const call = toolCalls.find((c) => c.toolCallId === r.toolCallId);
+                        // The AI SDK validates input via the tool's Zod schema before
+                        // dispatching to execute(), so by the time the result fires the
+                        // manifest shape is already known-good. Re-validating here gives
+                        // us the typed shape and a defensive guard against weird SDK
+                        // edge cases (missing call, unexpected input shape) without
+                        // assuming the cast.
+                        const parsed = call ? manifestSchema.safeParse(call.input?.manifest) : null;
+                        session.markFinished(parsed?.success ? parsed.data : null);
+                    }
+                }
+                session.budget.recordToolCalls(toolCalls.length);
+                const stepInputTokens = usage.inputTokens ?? 0;
+                const stepOutputTokens = usage.outputTokens ?? 0;
+                session.budget.recordStepUsage({
+                    inputTokens: stepInputTokens,
+                    outputTokens: stepOutputTokens,
+                });
+                await session.emit({
+                    kind: "step_usage",
+                    inputTokens: stepInputTokens,
+                    outputTokens: stepOutputTokens,
+                    estimatedUsd: estimateCostUsd(opts.providerId, opts.modelId, {
+                        input: stepInputTokens,
+                        output: stepOutputTokens,
+                    }) ?? 0,
+                    durationMs: stepDurationMs,
+                });
+                const breach = session.budget.nextStopReason();
+                if (breach !== null) {
+                    stopReason = breach;
+                    await session.emit({
+                        kind: "budget_warning",
+                        reason: breach,
+                        usage: session.budget.snapshot(),
+                    });
+                }
+            },
+            abortSignal: opts.signal,
+            maxRetries: opts.maxRetries ?? 5,
+        }));
+    }
+    catch (e) {
+        modelError = e instanceof Error ? e.message : String(e);
+        stopReason = opts.signal?.aborted ? "aborted" : "model_error";
+    }
+    if (session.isFinished()) {
+        stopReason = "completed";
+    }
+    else if (stopReason === "no_finish_called" && opts.signal?.aborted) {
+        stopReason = "aborted";
+    }
+    const usage = session.budget.snapshot();
+    await session.emit({ kind: "session_finished", reason: stopReason, usage });
+    return {
+        sessionId: session.id,
+        domain: session.domain,
+        reason: stopReason,
+        manifest: session.getManifest(),
+        usage,
+        events: session.events(),
+        error: modelError,
+    };
+}
+/**
+ * Best-effort extraction of `apiCostUsd` from a tool result. Tool outputs
+ * are wrapped as `{ ok: true, data }` or `{ ok: false, error }` by
+ * `defineTool`. We only bill for ok results carrying a non-negative
+ * numeric `apiCostUsd` field — every other shape returns 0.
+ */
+function extractProbeCost(output) {
+    if (output === null || typeof output !== "object")
+        return 0;
+    const o = output;
+    if (o.ok !== true || o.data === null || typeof o.data !== "object")
+        return 0;
+    const usd = o.data.apiCostUsd;
+    if (typeof usd !== "number" || !Number.isFinite(usd) || usd < 0)
+        return 0;
+    return usd;
+}
+//# sourceMappingURL=runner.js.map

package/dist/ai/orchestrator/runner.js.map

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

package/dist/ai/orchestrator/session.d.ts

@@ -0,0 +1,44 @@
+import { BudgetTracker } from "./budget.js";
+import type { FixManifest } from "./finish-tool.js";
+import { SessionLog, type EventSink } from "./log.js";
+import { type BudgetCaps, type SessionEvent } from "./types.js";
+export interface SessionStateOptions {
+    domain: string;
+    userId: string;
+    providerId: string;
+    modelId: string;
+    budget?: Partial<BudgetCaps>;
+    ndjsonPath?: string;
+    onEvent?: EventSink;
+}
+/**
+ * Bundles the per-session pieces (budget + log + identity) so the runner has
+ * a single object to thread through `streamText` callbacks. Keeps the runner
+ * itself focused on the AI-SDK glue.
+ */
+export declare class SessionState {
+    readonly id: string;
+    readonly domain: string;
+    readonly userId: string;
+    readonly budget: BudgetTracker;
+    readonly log: SessionLog;
+    readonly caps: BudgetCaps;
+    private finished;
+    private finishedManifest;
+    constructor(opts: SessionStateOptions);
+    start(): Promise<void>;
+    /**
+     * Mark `finish_audit` was called and capture its manifest. The runner
+     * reads this to detect completion. `manifest` may be null only in the
+     * pathological case where the AI SDK fired a finish_audit tool_result
+     * event but the matching tool_call's input couldn't be located — keep
+     * the session as "finished" so the loop terminates, but the result will
+     * carry a null manifest and the caller can detect the partial state.
+     */
+    markFinished(manifest: FixManifest | null): void;
+    isFinished(): boolean;
+    getManifest(): FixManifest | null;
+    emit(event: SessionEvent): Promise<void>;
+    events(): SessionEvent[];
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/ai/orchestrator/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/ai/orchestrator/session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,gBAAgB,CAA4B;gBAExC,IAAI,EAAE,mBAAmB;IAY/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B;;;;;;;OAOG;IACH,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAKhD,UAAU,IAAI,OAAO;IAIrB,WAAW,IAAI,WAAW,GAAG,IAAI;IAI3B,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,MAAM,IAAI,YAAY,EAAE;CAGzB"}

package/dist/ai/orchestrator/session.js

@@ -0,0 +1,64 @@
+import { randomUUID } from "node:crypto";
+import { BudgetTracker } from "./budget.js";
+import { SessionLog } from "./log.js";
+import { DEFAULT_BUDGET } from "./types.js";
+/**
+ * Bundles the per-session pieces (budget + log + identity) so the runner has
+ * a single object to thread through `streamText` callbacks. Keeps the runner
+ * itself focused on the AI-SDK glue.
+ */
+export class SessionState {
+    id;
+    domain;
+    userId;
+    budget;
+    log;
+    caps;
+    finished = false;
+    finishedManifest = null;
+    constructor(opts) {
+        this.id = randomUUID();
+        this.domain = opts.domain;
+        this.userId = opts.userId;
+        this.caps = { ...DEFAULT_BUDGET, ...opts.budget };
+        this.budget = new BudgetTracker(this.caps, opts.providerId, opts.modelId);
+        this.log = new SessionLog({
+            ndjsonPath: opts.ndjsonPath,
+            onEvent: opts.onEvent,
+        });
+    }
+    async start() {
+        this.budget.start();
+        await this.log.emit({
+            kind: "session_started",
+            sessionId: this.id,
+            domain: this.domain,
+            startedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * Mark `finish_audit` was called and capture its manifest. The runner
+     * reads this to detect completion. `manifest` may be null only in the
+     * pathological case where the AI SDK fired a finish_audit tool_result
+     * event but the matching tool_call's input couldn't be located — keep
+     * the session as "finished" so the loop terminates, but the result will
+     * carry a null manifest and the caller can detect the partial state.
+     */
+    markFinished(manifest) {
+        this.finished = true;
+        this.finishedManifest = manifest;
+    }
+    isFinished() {
+        return this.finished;
+    }
+    getManifest() {
+        return this.finishedManifest;
+    }
+    async emit(event) {
+        await this.log.emit(event);
+    }
+    events() {
+        return this.log.events();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/ai/orchestrator/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/ai/orchestrator/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAkB,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,cAAc,EAAsC,MAAM,YAAY,CAAC;AAYhF;;;;GAIG;AACH,MAAM,OAAO,YAAY;IACd,EAAE,CAAS;IACX,MAAM,CAAS;IACf,MAAM,CAAS;IACf,MAAM,CAAgB;IACtB,GAAG,CAAa;IAChB,IAAI,CAAa;IAElB,QAAQ,GAAG,KAAK,CAAC;IACjB,gBAAgB,GAAuB,IAAI,CAAC;IAEpD,YAAY,IAAyB;QACnC,IAAI,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1E,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC;YACxB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAClB,IAAI,EAAE,iBAAiB;YACvB,SAAS,EAAE,IAAI,CAAC,EAAE;YAClB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,YAAY,CAAC,QAA4B;QACvC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC;IACnC,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAmB;QAC5B,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/ai/orchestrator/types.d.ts

@@ -0,0 +1,99 @@
+import type { OrchestratorToolName } from "../tools/index.js";
+import type { FixManifest } from "./finish-tool.js";
+/**
+ * Hard caps on a single orchestrator session. Pre-flight checks against these
+ * happen on every step boundary; exceeding any cap aborts the session and
+ * returns the partial manifest accumulated so far.
+ */
+export interface BudgetCaps {
+    /** Max number of tool calls before forced termination. Default 100. */
+    maxToolCalls: number;
+    /** Max cumulative input tokens across all LLM calls. Default 500_000. */
+    maxInputTokensTotal: number;
+    /** Max estimated USD spend for this session. Default $5. */
+    maxSessionUsd: number;
+    /** Max wall-clock seconds before forced termination. Default 300 (5 min). */
+    maxWallSeconds: number;
+    /**
+     * Inject a watchdog system message every N tool calls reminding the model
+     * to converge on a manifest. Defaults to 20 — i.e. on calls 20, 40, 60,
+     * 80, the model gets a "are you converging?" nudge. Set to 0 to disable.
+     */
+    watchdogIntervalCalls: number;
+}
+export declare const DEFAULT_BUDGET: BudgetCaps;
+/** Cumulative usage so far in a session. */
+export interface UsageSnapshot {
+    inputTokens: number;
+    outputTokens: number;
+    estimatedUsd: number;
+    toolCallCount: number;
+    elapsedMs: number;
+}
+/** Reason a session terminated, present on every SessionResult. */
+export type StopReason = "completed" | "tool_call_limit" | "input_token_limit" | "usd_limit" | "wall_time_limit" | "model_error" | "aborted" | "no_finish_called";
+/**
+ * Discriminated event union streamed during a session. Consumers (web app's
+ * SSE channel, R2 log writer, vitest assertions) subscribe via the
+ * orchestrator's `onEvent` callback. The same events end up in the durable
+ * NDJSON log so the session can be replayed offline.
+ */
+export type SessionEvent = {
+    kind: "session_started";
+    sessionId: string;
+    domain: string;
+    startedAt: string;
+} | {
+    kind: "tool_call";
+    toolName: OrchestratorToolName | "finish_audit";
+    input: unknown;
+} | {
+    kind: "tool_result";
+    toolName: OrchestratorToolName | "finish_audit";
+    result: unknown;
+} | {
+    kind: "thought";
+    text: string;
+}
+/**
+ * Per-step delta. inputTokens/outputTokens are this step alone (not
+ * cumulative); estimatedUsd is the per-step cost (sum these to get total).
+ * `durationMs` is wall-clock time from the start of this step to when
+ * its onStepFinish fired — undefined when prepareStep didn't run for the
+ * very first step. Cumulative state lives in `session_finished.usage`.
+ */
+ | {
+    kind: "step_usage";
+    inputTokens: number;
+    outputTokens: number;
+    estimatedUsd: number;
+    durationMs?: number;
+} | {
+    kind: "watchdog_injected";
+    toolCallCount: number;
+} | {
+    kind: "budget_warning";
+    reason: string;
+    usage: UsageSnapshot;
+} | {
+    kind: "session_finished";
+    reason: StopReason;
+    usage: UsageSnapshot;
+};
+/**
+ * Final result returned by `runOrchestrator`. `manifest` is whatever
+ * `finish_audit` was called with — null when the session terminated for any
+ * reason other than the model calling finish_audit.
+ */
+export interface SessionResult {
+    sessionId: string;
+    domain: string;
+    reason: StopReason;
+    manifest: FixManifest | null;
+    usage: UsageSnapshot;
+    /** Full event log from the session, in order. */
+    events: SessionEvent[];
+    /** Error message when reason indicates failure. */
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ai/orchestrator/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/ai/orchestrator/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,cAAc,EAAE,UAM5B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,iBAAiB,GACjB,mBAAmB,GACnB,WAAW,GACX,iBAAiB,GACjB,aAAa,GACb,SAAS,GACT,kBAAkB,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,oBAAoB,GAAG,cAAc,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,oBAAoB,GAAG,cAAc,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACzF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACnC;;;;;;GAMG;GACD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5G;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,iDAAiD;IACjD,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/ai/orchestrator/types.js

@@ -0,0 +1,8 @@
+export const DEFAULT_BUDGET = {
+    maxToolCalls: 100,
+    maxInputTokensTotal: 500_000,
+    maxSessionUsd: 5,
+    maxWallSeconds: 300,
+    watchdogIntervalCalls: 20,
+};
+//# sourceMappingURL=types.js.map

package/dist/ai/orchestrator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/ai/orchestrator/types.ts"],"names":[],"mappings":"AAyBA,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC,YAAY,EAAE,GAAG;IACjB,mBAAmB,EAAE,OAAO;IAC5B,aAAa,EAAE,CAAC;IAChB,cAAc,EAAE,GAAG;IACnB,qBAAqB,EAAE,EAAE;CAC1B,CAAC"}

package/dist/ai/probes/cache.d.ts

@@ -0,0 +1,12 @@
+export declare function probeCacheKey(...parts: string[]): string;
+/**
+ * Lightweight content-addressable cache for external probe responses
+ * (SerpAPI, ask_ai_engine). Simpler than the cachedFetch HTTP cache —
+ * no ETag/Last-Modified, no negative cache, just key → JSON with TTL.
+ *
+ * Misses (file absent, malformed, expired) all return null silently —
+ * the caller fetches fresh and writes back.
+ */
+export declare function readProbeCache<T>(dir: string, key: string, ttlMs: number): Promise<T | null>;
+export declare function writeProbeCache<T>(dir: string, key: string, data: T): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/ai/probes/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/ai/probes/cache.ts"],"names":[],"mappings":"AASA,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAExD;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAkBlG;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzF"}

package/dist/ai/probes/cache.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export function probeCacheKey(...parts) {
+    return createHash("sha256").update(parts.join("|")).digest("hex");
+}
+/**
+ * Lightweight content-addressable cache for external probe responses
+ * (SerpAPI, ask_ai_engine). Simpler than the cachedFetch HTTP cache —
+ * no ETag/Last-Modified, no negative cache, just key → JSON with TTL.
+ *
+ * Misses (file absent, malformed, expired) all return null silently —
+ * the caller fetches fresh and writes back.
+ */
+export async function readProbeCache(dir, key, ttlMs) {
+    const path = join(dir, `${key}.json`);
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let entry;
+    try {
+        entry = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof entry.cachedAt !== "string")
+        return null;
+    const ageMs = Date.now() - new Date(entry.cachedAt).getTime();
+    if (Number.isNaN(ageMs) || ageMs > ttlMs)
+        return null;
+    return entry.data;
+}
+export async function writeProbeCache(dir, key, data) {
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `${key}.json`);
+    const tmp = `${path}.tmp`;
+    const entry = { cachedAt: new Date().toISOString(), data };
+    await writeFile(tmp, JSON.stringify(entry), "utf8");
+    await rename(tmp, path);
+}
+//# sourceMappingURL=cache.js.map

package/dist/ai/probes/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/ai/probes/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAOjC,MAAM,UAAU,aAAa,CAAC,GAAG,KAAe;IAC9C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,GAAW,EAAE,GAAW,EAAE,KAAa;IAC7E,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;IACtC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,KAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9D,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,KAAK;QAAE,OAAO,IAAI,CAAC;IACtD,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAI,GAAW,EAAE,GAAW,EAAE,IAAO;IACxE,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,GAAG,IAAI,MAAM,CAAC;IAC1B,MAAM,KAAK,GAAmB,EAAE,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC;IAC3E,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/ai/tools/ask-ai-engine.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/**
+ * Probe an AI answer engine with a query. The whole point of this tool —
+ * the AEO citability check — is to ask the same engines users will ask
+ * and see whether they cite the page being audited. No proxies, no
+ * heuristics. The cited-URLs list comes back, and if `candidateUrl` is
+ * provided we report whether it (by hostname) appears.
+ *
+ * Provider key resolution: explicit `apiKey` arg → engine-specific env
+ * var. Cached for 24h on `engine + query` — same query against the same
+ * engine reliably hits the same answer for the cache window.
+ */
+export declare const askAiEngineTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType<{
+        engine: "anthropic" | "perplexity" | "gemini";
+        query: string;
+        candidateUrl?: string | undefined;
+        apiKey?: string | undefined;
+        cacheDir?: string | undefined;
+    }, unknown, z.core.$ZodTypeInternals<{
+        engine: "anthropic" | "perplexity" | "gemini";
+        query: string;
+        candidateUrl?: string | undefined;
+        apiKey?: string | undefined;
+        cacheDir?: string | undefined;
+    }, unknown>>;
+    outputSchema: z.ZodType<{
+        engine: "anthropic" | "perplexity" | "gemini";
+        query: string;
+        answer: string;
+        citedUrls: string[];
+        candidateCited: boolean | null;
+        fromCache: boolean;
+        apiCostUsd: number;
+    }, unknown, z.core.$ZodTypeInternals<{
+        engine: "anthropic" | "perplexity" | "gemini";
+        query: string;
+        answer: string;
+        citedUrls: string[];
+        candidateCited: boolean | null;
+        fromCache: boolean;
+        apiCostUsd: number;
+    }, unknown>>;
+    toAiTool(): import("ai").Tool<{
+        engine: "anthropic" | "perplexity" | "gemini";
+        query: string;
+        candidateUrl?: string | undefined;
+        apiKey?: string | undefined;
+        cacheDir?: string | undefined;
+    }, import("./types.js").ToolResult<{
+        engine: "anthropic" | "perplexity" | "gemini";
+        query: string;
+        answer: string;
+        citedUrls: string[];
+        candidateCited: boolean | null;
+        fromCache: boolean;
+        apiCostUsd: number;
+    }>>;
+    run(input: {
+        engine: "anthropic" | "perplexity" | "gemini";
+        query: string;
+        candidateUrl?: string | undefined;
+        apiKey?: string | undefined;
+        cacheDir?: string | undefined;
+    }, ctx?: import("./types.js").ToolExecuteContext): Promise<import("./types.js").ToolResult<{
+        engine: "anthropic" | "perplexity" | "gemini";
+        query: string;
+        answer: string;
+        citedUrls: string[];
+        candidateCited: boolean | null;
+        fromCache: boolean;
+        apiCostUsd: number;
+    }>>;
+};
+//# sourceMappingURL=ask-ai-engine.d.ts.map

package/dist/ai/tools/ask-ai-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-ai-engine.d.ts","sourceRoot":"","sources":["../../../src/ai/tools/ask-ai-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiOxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoE1B,CAAC"}