@itmetsam/samurai-framework 0.22.2 → 0.22.4

package/dist/agent/run.js

@@ -0,0 +1,209 @@
+import { loadRawConfig, projectDir } from "../config/config.js";
+import { maskDeep, maskText } from "../config/mask.js";
+import { launchRecordingBrowser, prepareRecordingBrowser, } from "../recorder/session-browser.js";
+import { resultSecrets } from "../recorder/session-secrets.js";
+import { fixtureCatalog } from "../runner/fixture-registry.js";
+import { withProject } from "../runner/project.js";
+import { loadInstructions } from "./instructions.js";
+import { resolveLimits } from "./limits.js";
+import { runLoop } from "./loop.js";
+import { assertModelObject } from "./model.js";
+import { buildSystemPrompt } from "./prompt.js";
+import { StepRecorder } from "./recording.js";
+import { toSdkTools } from "./sdk-tools.js";
+import { AgentController } from "./session.js";
+import { Snapshotter } from "./snapshot.js";
+import { createTools } from "./tools/index.js";
+import { OriginPolicy } from "./tools/origins.js";
+import { personRecording } from "./take-over.js";
+const ACTION_TIMEOUT = 5000;
+async function loadAi(deps) {
+    try {
+        return await (deps.importAi ?? (() => import("ai")))();
+    }
+    catch (error) {
+        const missing = error.code;
+        throw new Error(missing === "ERR_MODULE_NOT_FOUND" || deps.importAi
+            ? 'agent(): the "ai" package is not installed. Install it, and a provider package for your model, with: npm install ai zod @ai-sdk/anthropic'
+            : `agent(): could not load the "ai" package: ${error.message}`);
+    }
+}
+/** The fixtures of the project's config, for the prompt; the agent works without them */
+async function fixturesOf(options) {
+    try {
+        const config = options.config ?? (await loadRawConfig());
+        return fixtureCatalog(config.fixtures ?? []);
+    }
+    catch {
+        return [];
+    }
+}
+function endReason(controller, tally, limit, failed) {
+    const stopped = controller.stopReason;
+    if (stopped)
+        return stopped;
+    if (failed)
+        return "error";
+    if (tally.finished)
+        return "finished";
+    return limit ?? "finished";
+}
+/** Starts a run; its work goes on in the background and `result` settles when it ends */
+export function startAgent(options, deps = {}) {
+    assertModelObject(options.model);
+    const limits = resolveLimits(options.limits);
+    const person = {};
+    const controller = new AgentController({
+        begin: () => person.hooks?.begin() ?? Promise.resolve(),
+        end: () => person.hooks?.end() ?? Promise.resolve(""),
+    }, options.onEvent);
+    options.signal?.addEventListener("abort", () => controller.stop(), {
+        once: true,
+    });
+    if (options.signal?.aborted)
+        controller.stop();
+    const tally = { modelCalls: 0, tokens: 0, finished: false };
+    const done = { text: "" };
+    const work = async () => {
+        const ai = await loadAi(deps);
+        await withProject(options, async (run) => {
+            const { settings } = run;
+            const instructions = loadInstructions(projectDir());
+            const startUrl = options.url ?? settings.baseURL;
+            const prepared = await prepareRecordingBrowser({
+                ...(options.browser && { browser: options.browser }),
+                ...(options.port !== undefined && { port: options.port }),
+                signal: controller.signal,
+            });
+            const steps = new StepRecorder({
+                file: options.file,
+                create: options.create,
+                test: options.test,
+                baseURL: settings.baseURL,
+                onStep: (event, code, source) => controller.emit({
+                    type: "step",
+                    event,
+                    ...(code !== undefined && { code }),
+                    source,
+                }),
+            });
+            done.steps = steps;
+            const { browser, page } = await launchRecordingBrowser(prepared, {
+                ...(options.port !== undefined && { port: options.port }),
+                signal: controller.signal,
+                headless: options.headless ?? false,
+            });
+            try {
+                deps.onPage?.(page);
+                if (options.url !== undefined)
+                    await page.goto(options.url);
+                else if (settings.baseURL !== undefined)
+                    await page.navigateTo(settings.baseURL);
+                const current = await page.url();
+                const onWeb = /^https?:/.test(current);
+                const snapshots = new Snapshotter(page, {
+                    secretFields: options.secretFields ?? [],
+                });
+                if (onWeb && steps.count === 0)
+                    steps.observe({ type: "goto", url: current });
+                const origins = new OriginPolicy([
+                    ...(options.allowedOrigins ?? []),
+                    ...(onWeb ? [current] : startUrl ? [startUrl] : []),
+                ]);
+                person.hooks = personRecording({
+                    page,
+                    steps,
+                    snapshots,
+                    ...(settings.baseURL !== undefined && { baseURL: settings.baseURL }),
+                });
+                const context = {
+                    page,
+                    snapshots,
+                    steps,
+                    origins,
+                    secrets: {
+                        allowed: options.secrets ?? [],
+                        get: (name) => run.secrets.get(name),
+                    },
+                    vision: options.vision === true,
+                    actionTimeout: ACTION_TIMEOUT,
+                    ask: (question, choices) => controller.ask(question, choices),
+                    finish: (summary) => {
+                        done.summary = summary;
+                        tally.finished = true;
+                    },
+                    emit: (event) => controller.emit(event),
+                    secretOnScreen: false,
+                };
+                const system = buildSystemPrompt({
+                    instructions: instructions.text,
+                    fixtures: await fixturesOf(options),
+                    secrets: options.secrets ?? [],
+                    origins: origins.list(),
+                    vision: options.vision === true,
+                });
+                const first = onWeb
+                    ? `The browser is open on ${current}. This is the page now:\n\n${maskText((await snapshots.take()).text)}`
+                    : "No page is open yet: start with navigate.";
+                const tools = toSdkTools(ai, createTools(context), {
+                    wait: () => controller.gate(),
+                    note: async () => controller.takeNote(),
+                });
+                const outcome = await runLoop({
+                    ai,
+                    model: options.model,
+                    system,
+                    prompt: `Goal: ${options.goal}\n\n${first}`,
+                    tools,
+                    controller,
+                    limits,
+                    tally,
+                });
+                done.text = outcome.text;
+                if (outcome.limit)
+                    done.limit = outcome.limit;
+            }
+            finally {
+                await person.hooks?.dispose().catch(() => undefined);
+                await browser.close().catch(() => undefined);
+            }
+        });
+    };
+    const stopTimer = controller.watchTime(limits.timeoutMs);
+    const result = work()
+        .then(() => false)
+        .catch((error) => {
+        done.error = maskText(error instanceof Error ? error.message : String(error));
+        return true;
+    })
+        .then(async (failed) => {
+        stopTimer();
+        await controller.settle();
+        const steps = done.steps;
+        const reason = endReason(controller, tally, done.limit, failed);
+        const summary = done.summary ?? (done.text.trim() || undefined);
+        const ended = maskDeep({
+            reason,
+            ...(reason === "finished" && summary !== undefined && { summary }),
+            ...(reason === "error" &&
+                done.error !== undefined && { error: done.error }),
+            file: steps?.file ?? options.file,
+            test: steps?.testName ?? "",
+            steps: steps?.count ?? 0,
+            secrets: steps ? resultSecrets(steps.events, []) : [],
+            tokens: tally.tokens,
+        });
+        controller.end(ended);
+        return ended;
+    });
+    return {
+        events: controller.events,
+        result,
+        answer: (id, text) => controller.answer(id, text),
+        pause: () => controller.pause(),
+        resume: () => controller.resume(),
+        takeOver: () => controller.takeOver(),
+        handBack: () => controller.handBack(),
+        stop: () => controller.stop(),
+    };
+}

package/dist/agent/sdk-tools.d.ts

@@ -0,0 +1,15 @@
+import type { AgentTool } from "./tools/context.js";
+/** The AI SDK, loaded when a run starts: it is an optional peer dependency */
+export type AiModule = typeof import("ai");
+/** What stands between the model's call and the tool: waiting while paused, and the note after a hand back */
+export interface ToolGate {
+    /** Resolves when the agent may act; rejects when the run ended */
+    wait(): Promise<void>;
+    /** Text to give the model instead of running its call, once, after the person used the browser */
+    note(): Promise<string | undefined>;
+}
+/**
+ * The tools in the AI SDK's shape. The SDK is given the JSON schema only: it would answer a wrong call with a
+ * dump of the validation library's issues, so the tools validate themselves and answer in a sentence.
+ */
+export declare function toSdkTools(ai: AiModule, tools: readonly AgentTool[], gate: ToolGate): Record<string, unknown>;

package/dist/agent/sdk-tools.js

@@ -0,0 +1,44 @@
+function modelOutput(result) {
+    if (!result.ok)
+        return { type: "error-text", value: result.error };
+    if (!result.image)
+        return { type: "text", value: result.message };
+    return {
+        type: "content",
+        value: [
+            { type: "text", text: result.message },
+            {
+                type: "file",
+                data: { type: "data", data: result.image.data },
+                mediaType: result.image.mediaType,
+            },
+        ],
+    };
+}
+/**
+ * The tools in the AI SDK's shape. The SDK is given the JSON schema only: it would answer a wrong call with a
+ * dump of the validation library's issues, so the tools validate themselves and answer in a sentence.
+ */
+export function toSdkTools(ai, tools, gate) {
+    const entries = tools.map((agentTool) => {
+        const schema = ai.jsonSchema(() => ai.zodSchema(agentTool.inputSchema).jsonSchema, {
+            validate: (value) => ({ success: true, value }),
+        });
+        return [
+            agentTool.name,
+            ai.tool({
+                description: agentTool.description,
+                inputSchema: schema,
+                execute: async (input) => {
+                    await gate.wait();
+                    const note = await gate.note();
+                    if (note !== undefined)
+                        return { ok: false, error: note };
+                    return agentTool.run(input);
+                },
+                toModelOutput: ({ output }) => modelOutput(output),
+            }),
+        ];
+    });
+    return Object.fromEntries(entries);
+}

package/dist/agent/session.d.ts

@@ -0,0 +1,62 @@
+import type { AgentEvent, AgentResult } from "./types.js";
+export type AbortReason = "stopped" | "time-limit" | "token-limit";
+/** What taking the browser over starts and ends: the recording of what the person does */
+export interface TakeOverHooks {
+    begin(): Promise<void>;
+    /** Ends the recording; the text tells the agent what the person did */
+    end(): Promise<string>;
+}
+/**
+ * The state of one run that the person controls: the event stream, pause and take over, the open questions, stop,
+ * and the active time. Time spent paused, taken over or waiting for an answer does not count against the time
+ * limit: it is the person's time, not the agent's.
+ */
+export declare class AgentController {
+    private readonly hooks;
+    private readonly onEvent?;
+    private readonly log;
+    private readonly readers;
+    private closed;
+    private mode;
+    private transition;
+    private readonly gateWaiters;
+    private readonly aborter;
+    private abortReason;
+    private readonly questions;
+    private asked;
+    private note;
+    private readonly startedAt;
+    private idleSince;
+    private idleTotal;
+    constructor(hooks: TakeOverHooks, onEvent?: ((event: AgentEvent) => void) | undefined);
+    /** Aborts when the run is stopped or a limit is reached */
+    get signal(): AbortSignal;
+    get stopReason(): AbortReason | undefined;
+    get events(): AsyncIterable<AgentEvent>;
+    private read;
+    emit(event: AgentEvent): void;
+    /** Emits `ended` once; later calls change nothing */
+    end(result: AgentResult): void;
+    /** Time the agent has been working, in ms */
+    activeMs(now?: number): number;
+    private touch;
+    private wake;
+    /** Resolves when the agent may act; rejects when the run was stopped or hit a limit */
+    gate(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    takeOver(): void;
+    handBack(): void;
+    /** The note for the agent about what the person did, once, after a hand back */
+    takeNote(): string | undefined;
+    /** Waits for a hand back that is still ending the person's recording (the run is ending anyway) */
+    settle(): Promise<void>;
+    /** Asks the person; waits without counting against the time limit. Rejects when the run stops */
+    ask(question: string, options?: string[]): Promise<string>;
+    answer(id: string, text: string): void;
+    /** Ends the run early: `stop()` from the person, or a limit */
+    abort(reason: AbortReason): void;
+    stop(): void;
+    /** Aborts with `time-limit` once the active time passes `timeoutMs`. Returns the function that stops the check */
+    watchTime(timeoutMs: number): () => void;
+}

package/dist/agent/session.js

@@ -0,0 +1,196 @@
+import { maskDeep } from "../config/mask.js";
+/**
+ * The state of one run that the person controls: the event stream, pause and take over, the open questions, stop,
+ * and the active time. Time spent paused, taken over or waiting for an answer does not count against the time
+ * limit: it is the person's time, not the agent's.
+ */
+export class AgentController {
+    constructor(hooks, onEvent) {
+        this.hooks = hooks;
+        this.onEvent = onEvent;
+        this.log = [];
+        this.readers = new Set();
+        this.closed = false;
+        this.mode = "running";
+        this.transition = Promise.resolve();
+        this.gateWaiters = new Set();
+        this.aborter = new AbortController();
+        this.questions = new Map();
+        this.asked = 0;
+        this.startedAt = Date.now();
+        this.idleTotal = 0;
+    }
+    /** Aborts when the run is stopped or a limit is reached */
+    get signal() {
+        return this.aborter.signal;
+    }
+    get stopReason() {
+        return this.abortReason;
+    }
+    get events() {
+        return { [Symbol.asyncIterator]: () => this.read() };
+    }
+    async *read() {
+        for (let index = 0;;) {
+            while (index < this.log.length)
+                yield this.log[index++];
+            if (this.closed)
+                return;
+            await new Promise((resolve) => {
+                const wake = () => {
+                    this.readers.delete(wake);
+                    resolve();
+                };
+                this.readers.add(wake);
+            });
+        }
+    }
+    emit(event) {
+        if (this.closed)
+            return;
+        const safe = maskDeep(event);
+        this.log.push(safe);
+        try {
+            this.onEvent?.(safe);
+        }
+        catch {
+            // a failing listener must not stop the run
+        }
+        for (const wake of [...this.readers])
+            wake();
+    }
+    /** Emits `ended` once; later calls change nothing */
+    end(result) {
+        if (this.closed)
+            return;
+        this.emit({ type: "ended", result });
+        this.closed = true;
+        for (const wake of [...this.readers])
+            wake();
+    }
+    /** Time the agent has been working, in ms */
+    activeMs(now = Date.now()) {
+        const idle = this.idleSince === undefined ? 0 : now - this.idleSince;
+        return now - this.startedAt - this.idleTotal - idle;
+    }
+    touch() {
+        const idle = this.mode !== "running" || this.questions.size > 0;
+        const now = Date.now();
+        if (idle && this.idleSince === undefined)
+            this.idleSince = now;
+        if (!idle && this.idleSince !== undefined) {
+            this.idleTotal += now - this.idleSince;
+            this.idleSince = undefined;
+        }
+    }
+    wake() {
+        for (const resume of [...this.gateWaiters])
+            resume();
+        this.gateWaiters.clear();
+    }
+    /** Resolves when the agent may act; rejects when the run was stopped or hit a limit */
+    async gate() {
+        for (;;) {
+            this.signal.throwIfAborted();
+            await this.transition;
+            this.signal.throwIfAborted();
+            if (this.mode === "running")
+                return;
+            await new Promise((resolve) => this.gateWaiters.add(resolve));
+        }
+    }
+    pause() {
+        if (this.mode !== "running")
+            return;
+        this.mode = "paused";
+        this.touch();
+    }
+    resume() {
+        if (this.mode !== "paused")
+            return;
+        this.mode = "running";
+        this.touch();
+        this.wake();
+    }
+    takeOver() {
+        if (this.mode === "taken-over")
+            return;
+        this.mode = "taken-over";
+        this.touch();
+        this.transition = this.transition
+            .then(() => this.hooks.begin())
+            .catch(() => undefined);
+    }
+    handBack() {
+        if (this.mode !== "taken-over")
+            return;
+        this.transition = this.transition
+            .then(async () => {
+            this.note = await this.hooks.end();
+        })
+            .catch(() => undefined)
+            .then(() => {
+            this.mode = "running";
+            this.touch();
+            this.wake();
+        });
+    }
+    /** The note for the agent about what the person did, once, after a hand back */
+    takeNote() {
+        const note = this.note;
+        this.note = undefined;
+        return note;
+    }
+    /** Waits for a hand back that is still ending the person's recording (the run is ending anyway) */
+    settle() {
+        return this.transition;
+    }
+    /** Asks the person; waits without counting against the time limit. Rejects when the run stops */
+    ask(question, options) {
+        const id = `q${++this.asked}`;
+        return new Promise((resolve, reject) => {
+            this.questions.set(id, {
+                answer: (text) => resolve(text),
+                fail: reject,
+            });
+            this.touch();
+            this.emit({
+                type: "question",
+                id,
+                question,
+                ...(options && options.length > 0 && { options }),
+            });
+        }).finally(() => {
+            this.questions.delete(id);
+            this.touch();
+        });
+    }
+    answer(id, text) {
+        const open = this.questions.get(id);
+        if (!open)
+            throw new Error(`agent(): there is no open question ${id}`);
+        open.answer(text);
+    }
+    /** Ends the run early: `stop()` from the person, or a limit */
+    abort(reason) {
+        if (this.abortReason)
+            return;
+        this.abortReason = reason;
+        this.aborter.abort(new Error(`agent run ended: ${reason}`));
+        for (const open of this.questions.values())
+            open.fail(new Error("agent run ended"));
+        this.wake();
+    }
+    stop() {
+        this.abort("stopped");
+    }
+    /** Aborts with `time-limit` once the active time passes `timeoutMs`. Returns the function that stops the check */
+    watchTime(timeoutMs) {
+        const timer = setInterval(() => {
+            if (this.activeMs() >= timeoutMs)
+                this.abort("time-limit");
+        }, Math.min(250, Math.max(10, timeoutMs / 4)));
+        timer.unref();
+        return () => clearInterval(timer);
+    }
+}

package/dist/agent/snapshot-script.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Function declaration, called as `(options)` with `{ maxChars, secretFields }`. Writes the page as text (see
+ * `Snapshotter.take`) and remembers the elements it numbered, so `RESOLVE_SCRIPT` can find them again. Secret
+ * values are replaced here, in the page: they never reach the framework.
+ */
+export declare const SNAPSHOT_SCRIPT: string;
+/**
+ * Function declaration, called as `({ ref, focused, secretFields })` with the number of a reference, or `focused`
+ * for the element that has focus. Answers `{ status: "ok", target, candidates, secret, dotted, role, name }`, or a status
+ * that says why the reference does not resolve: `none` (no snapshot in this document), `unknown`, `older` (it was
+ * in an earlier snapshot), `gone` (removed since), `nofocus`.
+ */
+export declare const RESOLVE_SCRIPT: string;
+/**
+ * Function declaration, called as `({ secretFields })`. Answers the first of the caller's selectors that matches a
+ * visible field showing a value in plain text (a password input draws dots and does not count), else "".
+ */
+export declare const SECRET_ON_SCREEN_SCRIPT: string;