@pcamarajr/scout 0.6.0 → 0.7.0

package/dist/runner/engines/ai-sdk.js

@@ -0,0 +1,144 @@
+import { anthropic } from "@ai-sdk/anthropic";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createVertex } from "@ai-sdk/google-vertex";
+import { openai } from "@ai-sdk/openai";
+import { generateText, stepCountIs, tool, } from "ai";
+import { detectAiCredentials } from "../../credentials.js";
+/**
+ * Maps a provider + model id onto the matching AI SDK `LanguageModel`.
+ *
+ *   anthropic → @ai-sdk/anthropic
+ *   openai    → @ai-sdk/openai
+ *   google    → @ai-sdk/google when a Gemini/Generative-AI API key is present;
+ *               otherwise @ai-sdk/google-vertex (keyless, via Application Default
+ *               Credentials). The split is driven by the same credential ladder
+ *               `detectAiCredentials("google")` reports, so the engine and
+ *               `scout doctor` agree on which sub-provider runs.
+ *
+ * For Vertex we pass `project` from GOOGLE_CLOUD_PROJECT when set (the provider
+ * otherwise reads GOOGLE_VERTEX_PROJECT) and default `location` to
+ * GOOGLE_VERTEX_LOCATION or "us-central1" — the Vertex provider requires a
+ * location eagerly at model construction, so we supply a sensible default to
+ * keep the keyless path zero-config. ADC itself comes from google-auth-library.
+ */
+export function resolveModel(provider, modelId) {
+    switch (provider) {
+        case "anthropic":
+            return anthropic(modelId);
+        case "openai":
+            return openai(modelId);
+        case "google": {
+            const status = detectAiCredentials("google");
+            const usesApiKey = status.ok && status.source !== undefined && /API_KEY$/.test(status.source);
+            if (usesApiKey)
+                return createGoogleGenerativeAI()(modelId);
+            const project = process.env.GOOGLE_CLOUD_PROJECT?.trim();
+            const location = process.env.GOOGLE_VERTEX_LOCATION?.trim() || "us-central1";
+            return createVertex({ location, ...(project ? { project } : {}) })(modelId);
+        }
+    }
+}
+/**
+ * Second engine, built on the Vercel AI SDK. It runs the SAME engine-neutral
+ * ScoutTool set through `generateText`'s tool-calling loop, against Anthropic,
+ * Google (Gemini API key or Vertex ADC) or OpenAI — selected per the spec's
+ * provider via {@link resolveModel}. The shared orchestrator owns prompts,
+ * verdict capture and the forced-verdict rescue — this class only drives the SDK
+ * loop and maps the SDK's `finishReason` into the QueryEndInfo vocabulary the
+ * rescue understands.
+ */
+export class AiSdkEngine {
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async run(spec) {
+        const model = this.opts.model ?? resolveModel(spec.provider, spec.model);
+        const tools = buildAiSdkTools(spec.tools);
+        const transcript = [];
+        // Running conversation so resume() can append the rescue prompt and
+        // continue from where the agent left off.
+        const messages = [{ role: "user", content: spec.userPrompt }];
+        const abortController = new AbortController();
+        const step = async (maxTurns) => {
+            try {
+                const result = await generateText({
+                    model,
+                    system: spec.systemPrompt,
+                    messages,
+                    tools,
+                    stopWhen: stepCountIs(maxTurns),
+                    abortSignal: abortController.signal,
+                });
+                // Collect assistant text across every step in order.
+                for (const s of result.steps) {
+                    if (s.text && s.text.trim())
+                        transcript.push(s.text.trim());
+                }
+                // Persist the full assistant/tool exchange so the next step continues it.
+                messages.push(...result.response.messages);
+                return toEndInfo(result.finishReason, result.steps.length);
+            }
+            catch (error) {
+                return {
+                    subtype: "error_during_execution",
+                    errors: [error instanceof Error ? error.message : String(error)],
+                };
+            }
+        };
+        const end = await step(spec.maxTurns);
+        const resume = async (prompt, maxTurns) => {
+            const before = transcript.length;
+            messages.push({ role: "user", content: prompt });
+            const resumeEnd = await step(maxTurns);
+            return { end: resumeEnd, transcript: transcript.slice(before) };
+        };
+        return { end, transcript, resume };
+    }
+}
+/**
+ * Maps the AI SDK `finishReason` onto the QueryEndInfo.subtype vocabulary that
+ * {@link describeNoVerdict} and the forced-verdict rescue already speak.
+ *
+ *   tool-calls / length  → "error_max_turns"        (hit the step budget mid-flight)
+ *   stop                 → "success"                 (model ended its turn cleanly)
+ *   error / content-filter / other → "error_during_execution"
+ *
+ * Rationale: when the loop stops on `tool-calls` it means `stopWhen` cut it off
+ * with a tool call still pending — i.e. it would have kept going, the budget ran
+ * out (exactly the Agent SDK's `error_max_turns`). `length` is the token-budget
+ * analog. Only a clean `stop` means the model chose to end its turn.
+ */
+export function toEndInfo(finishReason, numTurns) {
+    switch (finishReason) {
+        case "tool-calls":
+        case "length":
+            return { subtype: "error_max_turns", numTurns };
+        case "stop":
+            return { subtype: "success", numTurns };
+        default:
+            return { subtype: "error_during_execution", numTurns, errors: [`finishReason=${finishReason}`] };
+    }
+}
+/**
+ * Adapts the engine-neutral ScoutTool set into AI SDK tools. `execute` returns
+ * the tool text; on a tool error we return the error string (prefixed "ERRO:",
+ * same as the handler produces) rather than throwing. Returning a string keeps
+ * the model in the loop with the failure visible — the same recovery affordance
+ * the Agent SDK gives via an isError tool result — instead of aborting the run.
+ */
+function buildAiSdkTools(scoutTools) {
+    const entries = scoutTools.map((scoutTool) => [
+        scoutTool.name,
+        tool({
+            description: scoutTool.description,
+            inputSchema: scoutTool.schema,
+            execute: async (args) => {
+                const result = await scoutTool.handler(args);
+                return result.text;
+            },
+        }),
+    ]);
+    return Object.fromEntries(entries);
+}
+//# sourceMappingURL=ai-sdk.js.map

package/dist/runner/engines/ai-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../../../src/runner/engines/ai-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,WAAW,EACX,IAAI,GAIL,MAAM,IAAI,CAAC;AAEZ,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAoB3D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAAC,QAAoB,EAAE,OAAe;IAChE,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,WAAW;YACd,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5B,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YAC7C,MAAM,UAAU,GAAG,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC9F,IAAI,UAAU;gBAAE,OAAO,wBAAwB,EAAE,CAAC,OAAO,CAAC,CAAC;YAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,CAAC;YACzD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,IAAI,EAAE,IAAI,aAAa,CAAC;YAC7E,OAAO,YAAY,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,OAA2B,EAAE;QAA7B,SAAI,GAAJ,IAAI,CAAyB;IAAG,CAAC;IAE9D,KAAK,CAAC,GAAG,CAAC,IAAmB;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACzE,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE1C,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,oEAAoE;QACpE,0CAA0C;QAC1C,MAAM,QAAQ,GAAmB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9E,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAE9C,MAAM,IAAI,GAAG,KAAK,EAAE,QAAgB,EAAyB,EAAE;YAC7D,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;oBAChC,KAAK;oBACL,MAAM,EAAE,IAAI,CAAC,YAAY;oBACzB,QAAQ;oBACR,KAAK;oBACL,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC;oBAC/B,WAAW,EAAE,eAAe,CAAC,MAAM;iBACpC,CAAC,CAAC;gBACH,qDAAqD;gBACrD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;oBAC7B,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE;wBAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC9D,CAAC;gBACD,0EAA0E;gBAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBAC3C,OAAO,SAAS,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO;oBACL,OAAO,EAAE,wBAAwB;oBACjC,MAAM,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;iBACjE,CAAC;YACJ,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEtC,MAAM,MAAM,GAAG,KAAK,EAAE,MAAc,EAAE,QAAgB,EAA+B,EAAE;YACrF,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;YACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YACjD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAClE,CAAC,CAAC;QAEF,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrC,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,YAA0B,EAAE,QAAgB;IACpE,QAAQ,YAAY,EAAE,CAAC;QACrB,KAAK,YAAY,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC;QAClD,KAAK,MAAM;YACT,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;QAC1C;YACE,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,gBAAgB,YAAY,EAAE,CAAC,EAAE,CAAC;IACrG,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,UAAuB;IAC9C,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC;QAC5C,SAAS,CAAC,IAAI;QACd,IAAI,CAAC;YACH,WAAW,EAAE,SAAS,CAAC,WAAW;YAClC,WAAW,EAAE,SAAS,CAAC,MAAM;YAC7B,OAAO,EAAE,KAAK,EAAE,IAAa,EAAE,EAAE;gBAC/B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC7C,OAAO,MAAM,CAAC,IAAI,CAAC;YACrB,CAAC;SACF,CAAC;KACH,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC"}

package/dist/runner/engines/claude-agent-sdk.d.ts

@@ -0,0 +1,11 @@
+import type { AgentEngine, EngineRunSpec, EngineSession } from "./types.js";
+/**
+ * The original, trusted engine: runs the verification through the
+ * `@anthropic-ai/claude-agent-sdk` subprocess. Behavior here is intentionally
+ * IDENTICAL to the pre-refactor ai-runner: bypassPermissions, empty
+ * settingSources, allowedTools scoped to the in-process MCP browser server, the
+ * query()+drain() loop, and an abort-in-finally so no subprocess outlives a run.
+ */
+export declare class ClaudeAgentSdkEngine implements AgentEngine {
+    run(spec: EngineRunSpec): Promise<EngineSession>;
+}

package/dist/runner/engines/claude-agent-sdk.js

@@ -0,0 +1,117 @@
+import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * The original, trusted engine: runs the verification through the
+ * `@anthropic-ai/claude-agent-sdk` subprocess. Behavior here is intentionally
+ * IDENTICAL to the pre-refactor ai-runner: bypassPermissions, empty
+ * settingSources, allowedTools scoped to the in-process MCP browser server, the
+ * query()+drain() loop, and an abort-in-finally so no subprocess outlives a run.
+ */
+export class ClaudeAgentSdkEngine {
+    async run(spec) {
+        const browserServer = createSdkMcpServer({
+            name: "browser",
+            version: "1.0.0",
+            tools: spec.tools.map(toAgentSdkTool),
+        });
+        const baseOptions = {
+            model: spec.model,
+            systemPrompt: spec.systemPrompt,
+            mcpServers: { browser: browserServer },
+            allowedTools: ["mcp__browser__*"],
+            tools: [],
+            settingSources: [],
+            permissionMode: "bypassPermissions",
+        };
+        const transcript = [];
+        let sessionId;
+        let endInfo;
+        // Drains a query, collecting transcript/session/end info. Always aborts at
+        // the end so no claude-agent-sdk subprocess outlives the run.
+        const drain = async (q, controller) => {
+            try {
+                for await (const message of q) {
+                    if ("session_id" in message && message.session_id)
+                        sessionId = message.session_id;
+                    if (message.type === "assistant") {
+                        for (const block of message.message.content) {
+                            if (block.type === "text" && block.text.trim())
+                                transcript.push(block.text.trim());
+                        }
+                    }
+                    if (message.type === "result") {
+                        endInfo = {
+                            subtype: message.subtype,
+                            numTurns: message.num_turns,
+                            errors: "errors" in message ? message.errors : undefined,
+                        };
+                        break;
+                    }
+                }
+            }
+            finally {
+                controller.abort();
+            }
+        };
+        const mainController = new AbortController();
+        try {
+            await drain(query({
+                prompt: spec.userPrompt,
+                options: { ...baseOptions, maxTurns: spec.maxTurns, abortController: mainController },
+            }), mainController);
+        }
+        catch (error) {
+            endInfo = {
+                subtype: "sdk_error",
+                errors: [error instanceof Error ? error.message : String(error)],
+            };
+        }
+        const resume = async (prompt, maxTurns) => {
+            const resumeTranscript = [];
+            let resumeEnd;
+            if (!sessionId) {
+                return { end: { subtype: "no_session" }, transcript: resumeTranscript };
+            }
+            const rescueController = new AbortController();
+            // Reuse drain() so transcript/session/end semantics stay identical, then
+            // split off only what the rescue produced for the resume result.
+            const beforeLen = transcript.length;
+            try {
+                await drain(query({
+                    prompt,
+                    options: { ...baseOptions, maxTurns, resume: sessionId, abortController: rescueController },
+                }), rescueController);
+                resumeEnd = endInfo;
+            }
+            catch (error) {
+                resumeEnd = {
+                    subtype: "sdk_error",
+                    errors: [error instanceof Error ? error.message : String(error)],
+                };
+            }
+            resumeTranscript.push(...transcript.slice(beforeLen));
+            return { end: resumeEnd ?? { subtype: "no_session" }, transcript: resumeTranscript };
+        };
+        return {
+            get end() {
+                return endInfo ?? { subtype: "sdk_error" };
+            },
+            transcript,
+            resume,
+        };
+    }
+}
+/**
+ * Adapts an engine-neutral ScoutTool into the Agent SDK `tool()` shape. The
+ * Agent SDK's tool() wants a raw Zod shape, so we hand it `schema.shape`, and we
+ * map our normalized {text, isError} result back into a CallToolResult.
+ */
+function toAgentSdkTool(scoutTool) {
+    return tool(scoutTool.name, scoutTool.description, scoutTool.schema.shape, async (args) => {
+        const result = await scoutTool.handler(args);
+        return {
+            content: [{ type: "text", text: result.text }],
+            ...(result.isError ? { isError: true } : {}),
+        };
+    });
+}
+//# sourceMappingURL=claude-agent-sdk.js.map

package/dist/runner/engines/claude-agent-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-agent-sdk.js","sourceRoot":"","sources":["../../../src/runner/engines/claude-agent-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gCAAgC,CAAC;AAUjF;;;;;;GAMG;AACH,MAAM,OAAO,oBAAoB;IAC/B,KAAK,CAAC,GAAG,CAAC,IAAmB;QAC3B,MAAM,aAAa,GAAG,kBAAkB,CAAC;YACvC,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC;SACtC,CAAC,CAAC;QAEH,MAAM,WAAW,GAAG;YAClB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,UAAU,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE;YACtC,YAAY,EAAE,CAAC,iBAAiB,CAAC;YACjC,KAAK,EAAE,EAAQ;YACf,cAAc,EAAE,EAAQ;YACxB,cAAc,EAAE,mBAA4B;SAC7C,CAAC;QAEF,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,IAAI,SAA6B,CAAC;QAClC,IAAI,OAAiC,CAAC;QAEtC,2EAA2E;QAC3E,8DAA8D;QAC9D,MAAM,KAAK,GAAG,KAAK,EACjB,CAA2B,EAC3B,UAA2B,EACZ,EAAE;YACjB,IAAI,CAAC;gBACH,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,CAAC,EAAE,CAAC;oBAC9B,IAAI,YAAY,IAAI,OAAO,IAAI,OAAO,CAAC,UAAU;wBAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;oBAClF,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;wBACjC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;4BAC5C,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE;gCAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;wBACrF,CAAC;oBACH,CAAC;oBACD,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;wBAC9B,OAAO,GAAG;4BACR,OAAO,EAAE,OAAO,CAAC,OAAO;4BACxB,QAAQ,EAAE,OAAO,CAAC,SAAS;4BAC3B,MAAM,EAAE,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;yBACzD,CAAC;wBACF,MAAM;oBACR,CAAC;gBACH,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,cAAc,GAAG,IAAI,eAAe,EAAE,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,KAAK,CACT,KAAK,CAAC;gBACJ,MAAM,EAAE,IAAI,CAAC,UAAU;gBACvB,OAAO,EAAE,EAAE,GAAG,WAAW,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE;aACtF,CAAC,EACF,cAAc,CACf,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,GAAG;gBACR,OAAO,EAAE,WAAW;gBACpB,MAAM,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aACjE,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,EAAE,MAAc,EAAE,QAAgB,EAA+B,EAAE;YACrF,MAAM,gBAAgB,GAAa,EAAE,CAAC;YACtC,IAAI,SAAmC,CAAC;YACxC,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC;YAC1E,CAAC;YACD,MAAM,gBAAgB,GAAG,IAAI,eAAe,EAAE,CAAC;YAC/C,yEAAyE;YACzE,iEAAiE;YACjE,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC;YACpC,IAAI,CAAC;gBACH,MAAM,KAAK,CACT,KAAK,CAAC;oBACJ,MAAM;oBACN,OAAO,EAAE,EAAE,GAAG,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE;iBAC5F,CAAC,EACF,gBAAgB,CACjB,CAAC;gBACF,SAAS,GAAG,OAAO,CAAC;YACtB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS,GAAG;oBACV,OAAO,EAAE,WAAW;oBACpB,MAAM,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;iBACjE,CAAC;YACJ,CAAC;YACD,gBAAgB,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YACtD,OAAO,EAAE,GAAG,EAAE,SAAS,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC;QACvF,CAAC,CAAC;QAEF,OAAO;YACL,IAAI,GAAG;gBACL,OAAO,OAAO,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;YAC7C,CAAC;YACD,UAAU;YACV,MAAM;SACP,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,SAAoB;IAC1C,OAAO,IAAI,CACT,SAAS,CAAC,IAAI,EACd,SAAS,CAAC,WAAW,EACrB,SAAS,CAAC,MAAM,CAAC,KAAK,EACtB,KAAK,EAAE,IAAa,EAAE,EAAE;QACtB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7C,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YACvD,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/runner/engines/index.d.ts

@@ -0,0 +1,20 @@
+import type { AiProvider } from "../../credentials.js";
+import { AiSdkEngine } from "./ai-sdk.js";
+import { ClaudeAgentSdkEngine } from "./claude-agent-sdk.js";
+import type { AgentEngine } from "./types.js";
+/** The two engines Scout can run an AI verification through. */
+export type EngineKind = "agent-sdk" | "ai-sdk";
+/**
+ * Resolves which engine to use. Explicit preference (SCOUT_ENGINE / config
+ * `engine`) wins. Otherwise the default is forward-looking: the trusted Agent
+ * SDK for Anthropic, the AI SDK for non-Anthropic providers (which is the only
+ * engine that can reach them — still gated by credential detection until those
+ * providers are wired up).
+ */
+export declare function resolveEngineKind(provider: AiProvider, enginePref: EngineKind | undefined): EngineKind;
+/** Instantiates the engine for a provider + explicit preference. */
+export declare function selectEngine(provider: AiProvider, enginePref: EngineKind | undefined): AgentEngine;
+/** Parses a raw SCOUT_ENGINE / config value, ignoring unknown strings. */
+export declare function parseEngineKind(value: string | undefined): EngineKind | undefined;
+export { AiSdkEngine, ClaudeAgentSdkEngine };
+export type { AgentEngine };

package/dist/runner/engines/index.js

@@ -0,0 +1,28 @@
+import { AiSdkEngine } from "./ai-sdk.js";
+import { ClaudeAgentSdkEngine } from "./claude-agent-sdk.js";
+/**
+ * Resolves which engine to use. Explicit preference (SCOUT_ENGINE / config
+ * `engine`) wins. Otherwise the default is forward-looking: the trusted Agent
+ * SDK for Anthropic, the AI SDK for non-Anthropic providers (which is the only
+ * engine that can reach them — still gated by credential detection until those
+ * providers are wired up).
+ */
+export function resolveEngineKind(provider, enginePref) {
+    if (enginePref)
+        return enginePref;
+    return provider === "anthropic" ? "agent-sdk" : "ai-sdk";
+}
+/** Instantiates the engine for a provider + explicit preference. */
+export function selectEngine(provider, enginePref) {
+    return resolveEngineKind(provider, enginePref) === "ai-sdk"
+        ? new AiSdkEngine()
+        : new ClaudeAgentSdkEngine();
+}
+/** Parses a raw SCOUT_ENGINE / config value, ignoring unknown strings. */
+export function parseEngineKind(value) {
+    if (value === "agent-sdk" || value === "ai-sdk")
+        return value;
+    return undefined;
+}
+export { AiSdkEngine, ClaudeAgentSdkEngine };
+//# sourceMappingURL=index.js.map

package/dist/runner/engines/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runner/engines/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAM7D;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAoB,EACpB,UAAkC;IAElC,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAClC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3D,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAC1B,QAAoB,EACpB,UAAkC;IAElC,OAAO,iBAAiB,CAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,QAAQ;QACzD,CAAC,CAAC,IAAI,WAAW,EAAE;QACnB,CAAC,CAAC,IAAI,oBAAoB,EAAE,CAAC;AACjC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,KAAyB;IACvD,IAAI,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/runner/engines/types.d.ts

@@ -0,0 +1,68 @@
+import type { AiProvider } from "../../credentials.js";
+import type { Step, Verdict } from "../../types.js";
+import type { ScoutTool } from "../agent-tools.js";
+export interface AiRunOutcome {
+    verdict: Verdict;
+    reason: string;
+    steps: Step[];
+    transcript: string[];
+    /**
+     * Set when the runner itself failed to produce a verdict (agent never called
+     * scout_verdict) — NOT a UI judgment. Callers may retry and must report it
+     * as an infrastructure failure, never as "the scenario is blocked by the UI".
+     */
+    runnerFailure?: string;
+}
+/**
+ * How an engine run ended, for no-verdict diagnostics. The Agent SDK fills this
+ * from the SDK `result` message; the AI SDK engine maps its `finishReason` into
+ * the same `subtype` vocabulary so {@link describeNoVerdict} works unchanged.
+ */
+export interface QueryEndInfo {
+    subtype: string;
+    numTurns?: number;
+    errors?: string[];
+}
+/**
+ * Human-readable cause for a run that ended without scout_verdict.
+ * Distinguishes runner-infrastructure causes (turn budget, SDK errors) from
+ * an agent that simply stopped talking.
+ */
+export declare function describeNoVerdict(end: QueryEndInfo | undefined, maxTurns: number): string;
+/**
+ * Records navigation relative to the configured baseUrl so cached scripts
+ * survive --base-url / SCOUT_BASE_URL pointing at another server. URLs that
+ * merely share the prefix (http://localhost:3000x) or live on other hosts
+ * stay absolute.
+ */
+export declare function relativizeUrl(url: string, baseUrl: string): string;
+/** Everything an engine needs to drive one agent run. */
+export interface EngineRunSpec {
+    /** Inferred from the model id; selects the AI SDK provider in the AI SDK engine. */
+    provider: AiProvider;
+    model: string;
+    systemPrompt: string;
+    userPrompt: string;
+    tools: ScoutTool[];
+    maxTurns: number;
+}
+/** The result of resuming a session (the forced-verdict rescue). */
+export interface EngineResumeResult {
+    end: QueryEndInfo;
+    transcript: string[];
+}
+/**
+ * A live (or just-finished) engine session. The shared orchestrator reads
+ * `end`/`transcript`, and — if no verdict was captured — calls `resume()` to
+ * run the forced-verdict rescue with a small turn budget.
+ */
+export interface EngineSession {
+    end: QueryEndInfo;
+    /** Assistant text collected during the run, in order. */
+    transcript: string[];
+    resume(prompt: string, maxTurns: number): Promise<EngineResumeResult>;
+}
+/** A pluggable agent engine. `run` performs the initial verification pass. */
+export interface AgentEngine {
+    run(spec: EngineRunSpec): Promise<EngineSession>;
+}

package/dist/runner/engines/types.js

@@ -0,0 +1,37 @@
+/**
+ * Human-readable cause for a run that ended without scout_verdict.
+ * Distinguishes runner-infrastructure causes (turn budget, SDK errors) from
+ * an agent that simply stopped talking.
+ */
+export function describeNoVerdict(end, maxTurns) {
+    if (!end)
+        return "a sessão do agente terminou sem emitir resultado (subprocesso morreu?)";
+    switch (end.subtype) {
+        case "error_max_turns":
+            return `o agente estourou o limite de ${maxTurns} turns sem chamar scout_verdict`;
+        case "error_during_execution":
+            return `erro durante a execução do agente${end.errors?.length ? `: ${end.errors.join("; ")}` : ""}`;
+        case "success":
+            return "o agente encerrou normalmente sem chamar scout_verdict";
+        default:
+            return `a sessão do agente terminou com "${end.subtype}"${end.errors?.length ? `: ${end.errors.join("; ")}` : ""}`;
+    }
+}
+/**
+ * Records navigation relative to the configured baseUrl so cached scripts
+ * survive --base-url / SCOUT_BASE_URL pointing at another server. URLs that
+ * merely share the prefix (http://localhost:3000x) or live on other hosts
+ * stay absolute.
+ */
+export function relativizeUrl(url, baseUrl) {
+    const base = baseUrl.replace(/\/+$/, "");
+    if (url === base || url === `${base}/`)
+        return "/";
+    if (url.startsWith(base)) {
+        const rest = url.slice(base.length);
+        if (rest.startsWith("/") || rest.startsWith("?") || rest.startsWith("#"))
+            return rest;
+    }
+    return url;
+}
+//# sourceMappingURL=types.js.map

package/dist/runner/engines/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/runner/engines/types.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAA6B,EAAE,QAAgB;IAC/E,IAAI,CAAC,GAAG;QAAE,OAAO,wEAAwE,CAAC;IAC1F,QAAQ,GAAG,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,iBAAiB;YACpB,OAAO,iCAAiC,QAAQ,iCAAiC,CAAC;QACpF,KAAK,wBAAwB;YAC3B,OAAO,oCAAoC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACtG,KAAK,SAAS;YACZ,OAAO,wDAAwD,CAAC;QAClE;YACE,OAAO,oCAAoC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACvH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,OAAe;IACxD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACnD,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACxF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcamarajr/scout",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Self-healing browser QA: natural-language scenarios verified by an AI agent, replayed deterministically in CI",
   "type": "module",
   "license": "MIT",
@@ -43,12 +43,18 @@
     "dev": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test tests/*.test.ts",
+    "smoke": "node scripts/smoke.mjs",
     "prepublishOnly": "npm run build",
     "prepare": "husky"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.85",
+    "@ai-sdk/google": "^3.0.83",
+    "@ai-sdk/google-vertex": "^4.0.147",
+    "@ai-sdk/openai": "^3.0.73",
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "ai": "^6.0.208",
     "commander": "^13.1.0",
     "gray-matter": "^4.0.3",
     "playwright": "^1.52.0",