@adhd/agent-mcp 0.0.9 → 1.0.0

package/src/__tests__/integration/harness.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Integration test harness.
+ *
+ * Builds a fully-wired real system against a fresh temp sqlite database.
+ * Runs the same drizzle migrations used by the production server.
+ * Constructs real stores/queue/PolicyEngine/orchestrator/DagEngine with
+ * the same dispatchFn wiring as index.ts.
+ *
+ * The only scripted/stubbed components are:
+ *  - LLMProvider (ScriptedProvider from scripted-provider.ts)
+ *  - External MCP tool clients (in-process stubs at the registry boundary)
+ */
+import http from "node:http";
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import * as schema from "../../db/schema.js";
+import { AgentStore } from "../../store/agent-store.js";
+import { SessionStore } from "../../store/session-store.js";
+import { TaskStore } from "../../store/task-store.js";
+import { BackgroundQueue } from "../../engine/queue.js";
+import { DagEngine } from "../../engine/dag-engine.js";
+import { Orchestrator } from "../../engine/orchestrator.js";
+import { HookRegistry } from "../../engine/hooks.js";
+import { PolicyEngine } from "../../engine/policy.js";
+import { taskTool, taskCancel, taskResume } from "../../tools/task.js";
+import type { TaskDeps } from "../../tools/task.js";
+import type { AgentCreateInput } from "../../validation/index.js";
+import type { LLMProvider } from "../../providers/types.js";
+export type TestDb = ReturnType<typeof drizzle<typeof schema>>;
+export interface Harness {
+    db: TestDb;
+    rawSqlite: InstanceType<typeof Database>;
+    agentStore: AgentStore;
+    sessionStore: SessionStore;
+    taskStore: TaskStore;
+    queue: BackgroundQueue;
+    orchestrator: Orchestrator;
+    policy: PolicyEngine;
+    dagEngine: DagEngine;
+    taskDeps: TaskDeps;
+    hooks: HookRegistry;
+    /** Tear down: close DB, stop SSE server if started */
+    teardown: () => Promise<void>;
+    /** The file path of the temp DB (for restart tests) */
+    dbPath: string;
+    /** SSE server (if started) */
+    sseServer?: http.Server;
+    /** Ephemeral port the SSE server is bound to (if started) */
+    ssePort?: number;
+}
+export interface HarnessOptions {
+    /** Start an SSE server on an ephemeral port */
+    withSse?: boolean;
+    /** Override server-max-tool-loops */
+    serverMaxToolLoops?: number;
+    /** Use an explicit DB path (for restart tests) */
+    dbPath?: string;
+    /**
+     * Skip the automatic orphan-scan re-enqueue on build.
+     * Prefer `defaultProvider` over this flag: that keeps the real scan
+     * exercised while avoiding the external-provider race.
+     */
+    skipOrphanScan?: boolean;
+    /**
+     * Inject a scripted LLMProvider into the harness orchestrator so every
+     * task dispatched through taskDeps (including the startup orphan scan)
+     * uses it instead of the real provider built from agentDefinition.provider.
+     *
+     * This mirrors the pattern used for per-task provider injection but applies
+     * it at harness construction time — so the orphan scan that fires during
+     * buildHarness already has the right provider, with no race against a
+     * parallel bad-provider run.
+     */
+    defaultProvider?: LLMProvider;
+}
+/**
+ * Build a fully-wired harness. Call teardown() when done.
+ */
+export declare function buildHarness(opts?: HarnessOptions): Promise<Harness>;
+/**
+ * Rebuild a harness against the SAME DB file (for restart/persistence tests).
+ * Does NOT re-run migrations (they're already applied).
+ * DOES run the orphan scan.
+ */
+export declare function rebuildHarness(dbPath: string, opts?: Omit<HarnessOptions, "dbPath">): Promise<Harness>;
+/**
+ * Wait for the queue to drain (all enqueued tasks finished).
+ * Uses p-queue's onIdle() with a bounded deadline, which is more reliable
+ * than polling pending+size (which can momentarily read zero between batches).
+ */
+export declare function drainQueue(queue: BackgroundQueue, timeoutMs?: number): Promise<void>;
+/**
+ * Create a minimal test agent + open a session. Returns { agentName, sessionId }.
+ */
+export declare function createSessionAndAgent(harness: Harness, provider: LLMProvider, agentOverrides?: Partial<AgentCreateInput>): Promise<{
+    agentName: string;
+    sessionId: string;
+}>;
+/**
+ * Run a task synchronously via the real taskTool, injecting the given provider
+ * into the orchestrator for this task only.
+ *
+ * We achieve provider injection by temporarily monkey-patching the registry
+ * to use the scripted provider — the cleanest approach without modifying
+ * production source. The provider is captured in a closure inside the harness
+ * task runner below.
+ */
+export declare function runTaskViaToolWithProvider(harness: Harness, sessionId: string, prompt: string, provider: LLMProvider, extraInput?: Record<string, unknown>): Promise<{
+    task_id: string;
+    status: "pending" | "running" | "completed" | "failed" | "cancelled" | "waiting" | "awaiting_input";
+    result?: string | undefined;
+    stream_url?: string | undefined;
+    usage?: {
+        direct: {
+            inputTokens: number;
+            outputTokens: number;
+            modelCalls: number;
+            toolCallCount: number;
+            latencyMs: number;
+            stopReason?: string | undefined;
+        };
+        subtree: {
+            inputTokens: number;
+            outputTokens: number;
+            modelCalls: number;
+            toolCallCount: number;
+            latencyMs: number;
+            stopReason?: string | undefined;
+        };
+        taskCount: number;
+    } | undefined;
+}>;
+/**
+ * Background version — enqueues and returns immediately; use drainQueue to wait.
+ */
+export declare function enqueueTaskWithProvider(harness: Harness, sessionId: string, prompt: string, provider: LLMProvider, extraInput?: Record<string, unknown>): Promise<{
+    task_id: string;
+    status: "pending" | "running" | "completed" | "failed" | "cancelled" | "waiting" | "awaiting_input";
+    result?: string | undefined;
+    stream_url?: string | undefined;
+    usage?: {
+        direct: {
+            inputTokens: number;
+            outputTokens: number;
+            modelCalls: number;
+            toolCallCount: number;
+            latencyMs: number;
+            stopReason?: string | undefined;
+        };
+        subtree: {
+            inputTokens: number;
+            outputTokens: number;
+            modelCalls: number;
+            toolCallCount: number;
+            latencyMs: number;
+            stopReason?: string | undefined;
+        };
+        taskCount: number;
+    } | undefined;
+}>;
+/**
+ * A binary latch. One side waits; the other releases.
+ * Used for proving concurrency without sleeps.
+ */
+export declare class Latch {
+    private _resolve;
+    private _reject;
+    readonly promise: Promise<void>;
+    constructor();
+    release(): void;
+    fail(err: Error): void;
+    /** Await with a bounded deadline. Rejects if deadline exceeded. */
+    wait(timeoutMs?: number): Promise<void>;
+}
+export interface SseFrame {
+    type: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Connect to the real SSE server and collect frames until "done" or timeout.
+ * Returns collected frames in order.
+ *
+ * @param port - Ephemeral port from harness.ssePort
+ * @param taskId - Task UUID
+ * @param timeoutMs - Bounded deadline (default 8s)
+ * @param onConnected - Optional callback fired when the HTTP 200 response
+ *   headers are received (i.e. the SSE connection is established and the
+ *   server has accepted the request). Use this to release a latch that
+ *   unblocks a background task, guaranteeing the SSE subscription is active
+ *   before any events are emitted.
+ */
+export declare function collectSseFrames(port: number, taskId: string, timeoutMs?: number, onConnected?: () => void): Promise<SseFrame[]>;
+export { taskTool, taskCancel, taskResume };
+export type { TaskDeps };
+//# sourceMappingURL=harness.d.ts.map

package/src/__tests__/integration/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../../../../../../packages/ai/agent-mcp/src/__tests__/integration/harness.ts"],"names":[],"mappings":"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"}

package/src/__tests__/integration/harness.js

@@ -0,0 +1,396 @@
+/**
+ * Integration test harness.
+ *
+ * Builds a fully-wired real system against a fresh temp sqlite database.
+ * Runs the same drizzle migrations used by the production server.
+ * Constructs real stores/queue/PolicyEngine/orchestrator/DagEngine with
+ * the same dispatchFn wiring as index.ts.
+ *
+ * The only scripted/stubbed components are:
+ *  - LLMProvider (ScriptedProvider from scripted-provider.ts)
+ *  - External MCP tool clients (in-process stubs at the registry boundary)
+ */
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import http from "node:http";
+import crypto from "node:crypto";
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { fileURLToPath } from "node:url";
+import * as schema from "../../db/schema.js";
+import { AgentStore } from "../../store/agent-store.js";
+import { SessionStore } from "../../store/session-store.js";
+import { TaskStore } from "../../store/task-store.js";
+import { BackgroundQueue } from "../../engine/queue.js";
+import { DagEngine } from "../../engine/dag-engine.js";
+import { Orchestrator } from "../../engine/orchestrator.js";
+import { HookRegistry } from "../../engine/hooks.js";
+import { PolicyEngine } from "../../engine/policy.js";
+import { startSseServer } from "../../streaming/sse-server.js";
+import { enqueueExistingTask } from "../../tools/task.js";
+import { runMigrationsOn } from "../../db/migrate-runner.js";
+import { taskTool, taskCancel, taskResume } from "../../tools/task.js";
+import { tasksTable } from "../../db/schema.js";
+import { eq } from "drizzle-orm";
+import { generateId } from "../../utils/ids.js";
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const MIGRATIONS_FOLDER = path.resolve(__dirname, "../../../drizzle");
+/**
+ * Build a fully-wired harness. Call teardown() when done.
+ */
+export async function buildHarness(opts = {}) {
+    const dbPath = opts.dbPath ??
+        path.join(os.tmpdir(), `agent-mcp-test-${crypto.randomUUID()}.db`);
+    const rawSqlite = new Database(dbPath);
+    rawSqlite.pragma("journal_mode = WAL");
+    rawSqlite.pragma("foreign_keys = ON");
+    const db = drizzle(rawSqlite, { schema });
+    // Run migrations — same folder + FK-safe runner as production
+    runMigrationsOn(rawSqlite, db, MIGRATIONS_FOLDER);
+    const hooks = new HookRegistry();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const dbAny = db;
+    const agentStore = new AgentStore(dbAny, hooks);
+    const sessionStore = new SessionStore(dbAny, hooks);
+    const taskStore = new TaskStore(dbAny);
+    const queue = new BackgroundQueue(5);
+    const orchestrator = new Orchestrator();
+    const policy = new PolicyEngine({
+        serverMaxDepth: 5,
+        serverMaxToolLoops: opts.serverMaxToolLoops ?? 50,
+    });
+    // Mirror dispatchFn wiring from index.ts
+    let taskDeps;
+    const dispatchFn = async (taskId) => {
+        if (!taskDeps)
+            throw new Error("dispatchFn called before harness initialized");
+        await enqueueExistingTask(taskId, taskDeps);
+    };
+    const dagEngine = new DagEngine(dbAny, queue, taskStore, dispatchFn);
+    // SSE server (optional)
+    let sseServer;
+    let ssePort;
+    if (opts.withSse) {
+        sseServer = startSseServer(taskStore);
+        // Override SSE_PORT to the ephemeral port after listen
+        await new Promise((resolve) => {
+            sseServer.listen(0, "127.0.0.1", () => {
+                const addr = sseServer.address();
+                ssePort = addr.port;
+                resolve();
+            });
+        });
+    }
+    // Build taskDeps — same shape as index.ts.
+    // When defaultProvider is supplied, wrap the orchestrator so every run
+    // that goes through taskDeps (including the startup orphan scan) uses it
+    // instead of the real provider built from agentDefinition.provider.
+    const effectiveOrchestrator = opts.defaultProvider
+        ? {
+            run: (input) => orchestrator.run({ ...input, provider: opts.defaultProvider }),
+        }
+        : orchestrator;
+    taskDeps = {
+        agentStore,
+        sessionStore,
+        taskStore,
+        orchestrator: effectiveOrchestrator,
+        queue,
+        policy,
+        hooks,
+        selfUrl: undefined,
+        inProcessDescriptors: [],
+        inProcessHandler: async () => {
+            throw new Error("in-process tools not configured in test harness");
+        },
+        db: dbAny,
+        dagEngine,
+    };
+    // Re-enqueue orphaned pending tasks (mirrors startup scan in index.ts).
+    // Skipped when opts.skipOrphanScan is true — callers that need custom
+    // (patched) deps can trigger enqueueExistingTask manually.
+    if (!opts.skipOrphanScan) {
+        const orphanedPending = dbAny
+            .select()
+            .from(tasksTable)
+            .where(eq(tasksTable.status, "pending"))
+            .all();
+        for (const row of orphanedPending) {
+            try {
+                await enqueueExistingTask(row.id, taskDeps);
+            }
+            catch {
+                // ignore failures in teardown
+            }
+        }
+    }
+    const teardown = async () => {
+        // 1. Close the SSE server first so no new HTTP responses write to the DB.
+        if (sseServer) {
+            await new Promise((resolve) => sseServer.close(() => resolve()));
+        }
+        // 2. Drain the queue fully via p-queue's onIdle() — more reliable than
+        //    polling pending+size, which can momentarily read zero between tasks.
+        //    Race against a 15s deadline to avoid hanging test suite.
+        await Promise.race([
+            queue.onIdle(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("teardown: queue.onIdle() timed out after 15s")), 15_000)),
+        ]).catch(() => {
+            // Log but don't rethrow — we still need to close the DB.
+        });
+        // 3. One event-loop tick so the last task's finally-block DB writes settle.
+        await new Promise((r) => setImmediate(r));
+        // 4. Close the connection cleanly BEFORE unlinking the file.
+        //
+        //    The previous strategy (leak the handle, unlink the open file) caused
+        //    the intermittent teardown SIGSEGV (exit 139): in WAL mode, at process
+        //    exit better-sqlite3's destructor checkpoints the WAL — but the backing
+        //    file had already been unlinked, so the checkpoint operates on a deleted
+        //    file and crashes the native addon. Leaking also let connections
+        //    accumulate across the suite, multiplying the destructor work at exit.
+        //
+        //    Closing here, after onIdle()+setImmediate have settled all statements,
+        //    is race-free: TRUNCATE-checkpoint the WAL into the still-present file,
+        //    then close(). better-sqlite3 finalizes drizzle's cached statements on
+        //    close. Only then do we unlink the (now fully released) files.
+        if (rawSqlite.open) {
+            try {
+                rawSqlite.pragma("wal_checkpoint(TRUNCATE)");
+            }
+            catch {
+                // checkpoint is best-effort
+            }
+            try {
+                rawSqlite.close();
+            }
+            catch {
+                // already closed (e.g. a test closed it explicitly)
+            }
+        }
+        for (const suffix of ["", "-wal", "-shm"]) {
+            try {
+                fs.unlinkSync(`${dbPath}${suffix}`);
+            }
+            catch {
+                // ignore — file may not exist (e.g. -wal after TRUNCATE close)
+            }
+        }
+    };
+    return {
+        db,
+        rawSqlite,
+        agentStore,
+        sessionStore,
+        taskStore,
+        queue,
+        // Expose the effective orchestrator (wrapped when defaultProvider is set)
+        // so per-test overrides in runTaskViaToolWithProvider compose correctly.
+        orchestrator: effectiveOrchestrator,
+        policy,
+        dagEngine,
+        taskDeps: taskDeps,
+        hooks,
+        teardown,
+        dbPath,
+        sseServer,
+        ssePort,
+    };
+}
+/**
+ * Rebuild a harness against the SAME DB file (for restart/persistence tests).
+ * Does NOT re-run migrations (they're already applied).
+ * DOES run the orphan scan.
+ */
+export async function rebuildHarness(dbPath, opts = {}) {
+    return buildHarness({ ...opts, dbPath });
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Wait for the queue to drain (all enqueued tasks finished).
+ * Uses p-queue's onIdle() with a bounded deadline, which is more reliable
+ * than polling pending+size (which can momentarily read zero between batches).
+ */
+export async function drainQueue(queue, timeoutMs = 10_000) {
+    await Promise.race([
+        queue.onIdle(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error(`drainQueue timed out after ${timeoutMs}ms`)), timeoutMs)),
+    ]);
+    // One extra tick to let the last task's finally-block DB writes settle.
+    await new Promise((r) => setImmediate(r));
+}
+/**
+ * Create a minimal test agent + open a session. Returns { agentName, sessionId }.
+ */
+export async function createSessionAndAgent(harness, provider, agentOverrides = {}) {
+    const agentName = `test-agent-${generateId()}`;
+    // Inject the provider into the factory by using a special "stub" type
+    // The provider is passed via the harness task runner helper
+    harness.agentStore.create({
+        name: agentName,
+        provider: { type: "openai", model: "test-model" },
+        systemPrompt: "You are a test assistant.",
+        mcpServers: {},
+        permissions: {},
+        ...agentOverrides,
+    });
+    const agentDef = harness.agentStore.read(agentName);
+    const session = harness.sessionStore.create({
+        agentName,
+        agentDefinition: agentDef,
+    });
+    return { agentName, sessionId: session.id };
+}
+/**
+ * Run a task synchronously via the real taskTool, injecting the given provider
+ * into the orchestrator for this task only.
+ *
+ * We achieve provider injection by temporarily monkey-patching the registry
+ * to use the scripted provider — the cleanest approach without modifying
+ * production source. The provider is captured in a closure inside the harness
+ * task runner below.
+ */
+export async function runTaskViaToolWithProvider(harness, sessionId, prompt, provider, extraInput = {}) {
+    // Wrap the orchestrator to inject the scripted provider for this one run
+    const realOrchestrator = harness.orchestrator;
+    const originalRun = realOrchestrator.run.bind(realOrchestrator);
+    const patchedDeps = {
+        ...harness.taskDeps,
+        orchestrator: {
+            run: (input) => originalRun({ ...input, provider }),
+        },
+    };
+    return taskTool({ session_id: sessionId, prompt, background: false, ...extraInput }, patchedDeps);
+}
+/**
+ * Background version — enqueues and returns immediately; use drainQueue to wait.
+ */
+export async function enqueueTaskWithProvider(harness, sessionId, prompt, provider, extraInput = {}) {
+    const realOrchestrator = harness.orchestrator;
+    const originalRun = realOrchestrator.run.bind(realOrchestrator);
+    const patchedDeps = {
+        ...harness.taskDeps,
+        orchestrator: {
+            run: (input) => originalRun({ ...input, provider }),
+        },
+    };
+    return taskTool({ session_id: sessionId, prompt, background: true, ...extraInput }, patchedDeps);
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Latch utility
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * A binary latch. One side waits; the other releases.
+ * Used for proving concurrency without sleeps.
+ */
+export class Latch {
+    _resolve;
+    _reject;
+    promise;
+    constructor() {
+        this.promise = new Promise((res, rej) => {
+            this._resolve = res;
+            this._reject = rej;
+        });
+    }
+    release() {
+        this._resolve();
+    }
+    fail(err) {
+        this._reject(err);
+    }
+    /** Await with a bounded deadline. Rejects if deadline exceeded. */
+    async wait(timeoutMs = 5_000) {
+        return Promise.race([
+            this.promise,
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Latch.wait timed out after ${timeoutMs}ms`)), timeoutMs)),
+        ]);
+    }
+}
+/**
+ * Connect to the real SSE server and collect frames until "done" or timeout.
+ * Returns collected frames in order.
+ *
+ * @param port - Ephemeral port from harness.ssePort
+ * @param taskId - Task UUID
+ * @param timeoutMs - Bounded deadline (default 8s)
+ * @param onConnected - Optional callback fired when the HTTP 200 response
+ *   headers are received (i.e. the SSE connection is established and the
+ *   server has accepted the request). Use this to release a latch that
+ *   unblocks a background task, guaranteeing the SSE subscription is active
+ *   before any events are emitted.
+ */
+export async function collectSseFrames(port, taskId, timeoutMs = 8_000, onConnected) {
+    return new Promise((resolve, reject) => {
+        const frames = [];
+        const timer = setTimeout(() => {
+            reject(new Error(`collectSseFrames timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        const req = http.get(`http://127.0.0.1:${port}/tasks/${taskId}/stream`, { headers: { Accept: "text/event-stream" } }, (res) => {
+            // Fire the onConnected callback as soon as the HTTP response
+            // headers arrive — this confirms the SSE endpoint has accepted
+            // the request and the subscription is active on the server.
+            onConnected?.();
+            let buf = "";
+            let currentEventType = "";
+            res.on("data", (chunk) => {
+                buf += chunk.toString();
+                const lines = buf.split("\n");
+                buf = lines.pop() ?? "";
+                for (const line of lines) {
+                    if (line.startsWith("event: ")) {
+                        currentEventType = line.slice("event: ".length).trim();
+                    }
+                    else if (line.startsWith("data: ")) {
+                        const raw = line.slice("data: ".length).trim();
+                        try {
+                            const data = JSON.parse(raw);
+                            frames.push({ type: currentEventType, data });
+                            if (currentEventType === "done") {
+                                clearTimeout(timer);
+                                req.destroy();
+                                resolve(frames);
+                            }
+                        }
+                        catch {
+                            // ignore parse errors (e.g. ping lines)
+                        }
+                    }
+                    // reset event type on blank line (SSE spec)
+                    if (line === "") {
+                        currentEventType = "";
+                    }
+                }
+            });
+            res.on("error", (err) => {
+                clearTimeout(timer);
+                // If connection was destroyed after done frame, that's fine
+                if (frames.some((f) => f.type === "done")) {
+                    resolve(frames);
+                }
+                else {
+                    reject(err);
+                }
+            });
+            res.on("end", () => {
+                clearTimeout(timer);
+                resolve(frames);
+            });
+        });
+        req.on("error", (err) => {
+            clearTimeout(timer);
+            // Destroyed connections after done frame are fine
+            if (frames.some((f) => f.type === "done")) {
+                resolve(frames);
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+}
+// Re-export tools for convenience
+export { taskTool, taskCancel, taskResume };
+//# sourceMappingURL=harness.js.map

package/src/__tests__/integration/harness.js.map

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

package/src/__tests__/integration/scripted-provider.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ScriptedProvider — deterministic LLM provider for integration tests.
+ *
+ * Implements the real LLMProvider interface.
+ * Returns programmable responses per chat() call in sequence.
+ * After all scripted turns are exhausted, defaults to a "completed" response.
+ *
+ * Supported turn types:
+ *  - "completed"    → returns stopReason "completed" with given content
+ *  - "tool_calls"   → returns stopReason "tool_calls" with given tool calls
+ *  - "hitl"         → returns a single request_human_input tool call
+ *
+ * Supports a beforeCall hook so tool stubs can coordinate with Latches.
+ */
+import type { LLMProvider, ProviderChatResponse } from "../../providers/types.js";
+export interface ToolCallSpec {
+    server: string;
+    tool: string;
+    arguments: unknown;
+    /** Override the generated call ID */
+    id?: string;
+}
+export type ScriptedTurn = {
+    type: "completed";
+    content: string;
+} | {
+    type: "tool_calls";
+    toolCalls: ToolCallSpec[];
+} | {
+    type: "hitl";
+    prompt: string;
+};
+export declare class ScriptedProvider implements LLMProvider {
+    private readonly turns;
+    private callIndex;
+    /**
+     * Optional hook invoked at the START of each chat() call (before returning).
+     * Receives the call index (0-based) so tests can key on specific turns.
+     */
+    beforeCall?: (callIndex: number) => Promise<void>;
+    constructor(turns: ScriptedTurn[]);
+    chat(): Promise<ProviderChatResponse>;
+}
+//# sourceMappingURL=scripted-provider.d.ts.map

package/src/__tests__/integration/scripted-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripted-provider.d.ts","sourceRoot":"","sources":["../../../../../../../packages/ai/agent-mcp/src/__tests__/integration/scripted-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAKlF,MAAM,WAAW,YAAY;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,qCAAqC;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GAClB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,YAAY,EAAE,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,qBAAa,gBAAiB,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;gBAEtC,KAAK,EAAE,YAAY,EAAE;IAI3B,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC;CA6D9C"}