@itaila/archetype 0.3.30

package/dist/builder/browser.js

@@ -0,0 +1,232 @@
+/**
+ * BrowserHarness — live-browser primitive for coder personas that
+ * build browser-rendered artifacts (games, forms, dashboards). Lets the
+ * model actually see the page and interact with it instead of inferring
+ * behavior from code alone.
+ *
+ * Contract:
+ * — `open` navigate to a path under the allowed origin
+ * — `click` click by visible text (primary) or CSS selector (fallback)
+ * — `type` type literal text into the focused element
+ * — `key`  press one named key (ArrowUp, Enter, etc) once
+ * — `screenshot` capture a PNG (bytes + base64)
+ * — `getConsoleEntries` read captured console output
+ * — `close` terminate the browser + clean up the profile dir
+ *
+ * What belongs here (archetype layer):
+ * — `BrowserHarness` interface + all result types
+ * — `PlaywrightBrowser` default impl using playwright chromium
+ * — Origin-allowlist enforcement (route blocker + navigation check)
+ * — Ephemeral profile directory lifecycle
+ *
+ * What does NOT belong here:
+ * — Evidence-file persistence. `screenshot()` returns bytes and base64;
+ *   the host app decides whether to write a PNG file, upload, attach
+ *   the bytes to the next prompt turn, etc.
+ * — Tool-action wiring (archetype/builder/actions.ts owns the action
+ *   contracts; the executor dispatch maps them to BrowserHarness calls).
+ *
+ * Node-only. Playwright is a runtime dep of the *host app* (not
+ * archetype) — we dynamically import `playwright` inside the default
+ * impl, so archetype ships without pulling chromium binaries.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export class PlaywrightBrowser {
+    allowedOrigin;
+    profileDir;
+    ownsProfileDir;
+    viewport;
+    context = null;
+    page = null;
+    consoleEntries = [];
+    constructor(options) {
+        this.allowedOrigin = normalizeOrigin(options.allowedOrigin);
+        if (options.profileDir) {
+            this.profileDir = path.resolve(options.profileDir);
+            this.ownsProfileDir = false;
+            fs.mkdirSync(this.profileDir, { recursive: true });
+        }
+        else {
+            this.profileDir = fs.mkdtempSync(path.join(os.tmpdir(), 'archetype-browser-profile-'));
+            this.ownsProfileDir = true;
+        }
+        this.viewport = {
+            width: options.viewportWidth ?? 1440,
+            height: options.viewportHeight ?? 960,
+        };
+    }
+    async open(relativePath = '/') {
+        const page = await this.ensurePage();
+        const targetUrl = new URL(relativePath, `${this.allowedOrigin}/`).toString();
+        enforceAllowedUrl(targetUrl, this.allowedOrigin);
+        this.consoleEntries.length = 0;
+        const response = await page.goto(targetUrl, { waitUntil: 'networkidle' });
+        if (!response) {
+            throw new Error(`Browser failed to load ${targetUrl}`);
+        }
+        return {
+            ok: response.ok(),
+            url: page.url(),
+            title: await page.title(),
+        };
+    }
+    async screenshot(_label = 'page') {
+        const page = await this.ensurePage();
+        const bytes = await page.screenshot({ fullPage: true });
+        return { ok: true, bytes, base64: bytes.toString('base64') };
+    }
+    /**
+     * Type literal text into the focused element (or a specified selector).
+     * Mirrors playwright's `keyboard.type` — sends key-by-key so form/game
+     * handlers fire. If `selector` is given, focus it first.
+     */
+    async type(input) {
+        const page = await this.ensurePage();
+        if (!input.text || input.text.length === 0) {
+            return { ok: false, detail: 'browserType requires a non-empty `text` param.' };
+        }
+        try {
+            if (input.selector && input.selector.trim().length > 0) {
+                await page.focus(input.selector, { timeout: 3000 });
+            }
+            await page.keyboard.type(input.text);
+            const scope = input.selector ? ` into "${input.selector}"` : '';
+            return { ok: true, detail: `typed ${JSON.stringify(input.text)}${scope}` };
+        }
+        catch (err) {
+            return { ok: false, detail: firstLineOf(err) };
+        }
+    }
+    /**
+     * Press a single named key (ArrowUp, Enter, Escape, Tab, Space, a-z,
+     * 0-9, etc). Mirrors playwright's `keyboard.press` — one keydown +
+     * keyup so game handlers fire once.
+     */
+    async key(input) {
+        const page = await this.ensurePage();
+        if (!input.key || input.key.length === 0) {
+            return { ok: false, detail: 'browserKey requires a non-empty `key` param.' };
+        }
+        try {
+            if (input.selector && input.selector.trim().length > 0) {
+                await page.focus(input.selector, { timeout: 3000 });
+            }
+            await page.keyboard.press(input.key);
+            const scope = input.selector ? ` (focus "${input.selector}")` : '';
+            return { ok: true, detail: `pressed ${JSON.stringify(input.key)}${scope}` };
+        }
+        catch (err) {
+            return { ok: false, detail: firstLineOf(err) };
+        }
+    }
+    /**
+     * Click an element. Primary: visible text match (matches how the model
+     * thinks about UI). Fallback: CSS selector. Returns the match mode
+     * + detail so the executor can render a truthful outcome note.
+     */
+    async click(input) {
+        const page = await this.ensurePage();
+        if (input.text && input.text.trim().length > 0) {
+            const locator = page.getByText(input.text, { exact: false }).first();
+            try {
+                await locator.click({ timeout: 3000 });
+                return { ok: true, matched: 'text', detail: `clicked element with text matching "${input.text}"` };
+            }
+            catch (err) {
+                if (!input.selector) {
+                    return { ok: false, matched: 'none', detail: `no element with visible text "${input.text}" within 3s — ${firstLineOf(err)}` };
+                }
+                // text miss; fall through to selector fallback
+            }
+        }
+        if (input.selector && input.selector.trim().length > 0) {
+            try {
+                await page.click(input.selector, { timeout: 3000 });
+                return { ok: true, matched: 'selector', detail: `clicked element matching selector "${input.selector}"` };
+            }
+            catch (err) {
+                return { ok: false, matched: 'none', detail: `selector "${input.selector}" did not match a clickable element within 3s — ${firstLineOf(err)}` };
+            }
+        }
+        return { ok: false, matched: 'none', detail: 'browserClick requires at least one of `text` or `selector` to be provided' };
+    }
+    getConsoleEntries() {
+        return [...this.consoleEntries];
+    }
+    async close() {
+        await this.context?.close();
+        this.context = null;
+        this.page = null;
+        if (this.ownsProfileDir) {
+            fs.rmSync(this.profileDir, { recursive: true, force: true });
+        }
+    }
+    async ensurePage() {
+        if (this.page)
+            return this.page;
+        const { chromium } = await loadPlaywright();
+        this.context = await chromium.launchPersistentContext(this.profileDir, {
+            headless: true,
+            viewport: this.viewport,
+            acceptDownloads: false,
+        });
+        await this.context.route('**/*', async (route) => {
+            const requestUrl = route.request().url();
+            if (requestUrl.startsWith(this.allowedOrigin)) {
+                await route.continue();
+                return;
+            }
+            await route.abort();
+        });
+        const pages = this.context.pages();
+        this.page = pages[0] ?? await this.context.newPage();
+        this.page.on('console', (message) => {
+            this.consoleEntries.push(formatConsoleEntry(message));
+        });
+        return this.page;
+    }
+}
+// ─── Internals ───────────────────────────────────────────────────────
+async function loadPlaywright() {
+    try {
+        // Dynamic import keeps archetype free of a hard playwright dep. The
+        // `as never` cast prevents the TS compiler from requiring playwright
+        // type declarations at archetype build time — consumers still get
+        // correct types via our locally-declared PlaywrightChromium.
+        const mod = await import('playwright');
+        return mod;
+    }
+    catch (err) {
+        throw new Error(`PlaywrightBrowser requires the 'playwright' package installed in the host app. Install with: npm install playwright. Underlying error: ${firstLineOf(err)}`);
+    }
+}
+function formatConsoleEntry(message) {
+    const location = message.location();
+    return {
+        type: message.type(),
+        text: message.text(),
+        location: {
+            url: location.url,
+            lineNumber: location.lineNumber,
+            columnNumber: location.columnNumber,
+        },
+    };
+}
+function normalizeOrigin(origin) {
+    const url = new URL(origin);
+    return `${url.protocol}//${url.host}`;
+}
+function enforceAllowedUrl(candidate, allowedOrigin) {
+    const url = new URL(candidate);
+    const normalized = `${url.protocol}//${url.host}`;
+    if (normalized !== allowedOrigin) {
+        throw new Error(`Browser navigation blocked outside allowed origin: ${candidate}`);
+    }
+}
+function firstLineOf(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.split('\n')[0];
+}
+//# sourceMappingURL=browser.js.map

package/dist/builder/browser.js.map

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

package/dist/builder/executor.d.ts

@@ -0,0 +1,228 @@
+import type { BrowserHarness } from './browser.js';
+import type { ChatAttachment, ParsedAction, TurnLedgerActionOutcome } from '../types.js';
+import type { SandboxExecResult, SandboxSpawnResult } from './sandbox.js';
+import { type WorkspaceMount } from './workspace-files.js';
+/**
+ * The minimum sandbox surface the executor needs. Hosts can implement
+ * this directly over archetype's `Sandbox` (via SrtSandbox.exec) or
+ * wrap it with their own preset layer (foundry's BenchmarkSandboxExecutor).
+ */
+export interface CoderSandbox {
+    /**
+     * Execute an arbitrary argv inside the sandbox. Maps to the model's
+     * `runCommand` action.
+     */
+    runCommand(input: {
+        command: string[];
+        timeoutMs?: number;
+        /** Optional command cwd. Mounted workspaces use a canonical visible cwd. */
+        cwd?: string;
+        /** Additional readable paths needed by the command cwd. */
+        extraReadPaths?: string[];
+        /** Additional writable paths needed by the command cwd. */
+        extraWritePaths?: string[];
+    }): Promise<SandboxExecResult>;
+    /**
+     * Execute a named preset tool (runInstall, runBuild, runTests, runLint,
+     * runStart). The host owns what each preset means; this module just
+     * forwards the name it received from the model. runStart resolves with
+     * `origin` so the host knows the live URL.
+     */
+    runTool(name: CoderSandboxToolName, input?: {
+        /** Optional command cwd. Mounted workspaces use a canonical visible cwd. */
+        cwd?: string;
+        /** Additional readable paths needed by the command cwd. */
+        extraReadPaths?: string[];
+        /** Additional writable paths needed by the command cwd. */
+        extraWritePaths?: string[];
+    }): Promise<CoderSandboxToolResult>;
+}
+export type CoderSandboxToolName = 'runInstall' | 'runBuild' | 'runTests' | 'runLint' | 'runStart';
+export interface CoderSandboxToolDocumentation {
+    /**
+     * Human-facing command equivalent for docs/handoffs. Hosts should provide
+     * this when a preset wraps hidden setup, absolute trusted binaries, or
+     * sandbox-only paths that would otherwise make artifact instructions stale.
+     */
+    userFacingCommand?: string;
+    /**
+     * Compact factual note about hidden preset setup that affects whether the
+     * userFacingCommand is replayable outside the harness.
+     */
+    userFacingNote?: string;
+}
+export type CoderSandboxToolResult = (SandboxExecResult & CoderSandboxToolDocumentation) | (SandboxSpawnResult & {
+    origin: string;
+} & CoderSandboxToolDocumentation);
+export interface CoderExecutorContext {
+    /** Absolute path to the workspace root the persona operates in. */
+    workspaceRoot: string;
+    /**
+     * Optional virtual roots exposed to the persona, e.g.
+     * [{prefix:"spec", root:"/tmp/spec", writable:false},
+     *  {prefix:"artifact", root:"/tmp/artifact", writable:true}].
+     * File actions understand these prefixes and report outcomes using the
+     * same visible path, so hosts don't need to hand-roll spec/artifact routing.
+     */
+    workspaceMounts?: readonly WorkspaceMount[];
+    /** Default mount for unprefixed file writes. Defaults to workspaceRoot. */
+    defaultMountPrefix?: string;
+    /**
+     * Visible mount that corresponds to the live browser document root.
+     * Defaults to defaultMountPrefix when omitted. This stays separate from
+     * defaultMountPrefix because a reviewer persona may write spec files by
+     * default while opening a mounted artifact in the browser.
+     */
+    browserMountPrefix?: string;
+    /** Sandbox adapter the persona routes sandbox-tool calls through. */
+    sandbox: CoderSandbox;
+    /** Live browser harness, or null if no local server is running yet. */
+    browser: BrowserHarness | null;
+}
+export interface CoderActionAttachment {
+    type: 'image';
+    mimeType: string;
+    data: string;
+}
+export interface CoderActionContinuity {
+    /**
+     * Full result text shown on the immediately following turn.
+     */
+    resultText: string;
+    /**
+     * How many future turns should continue seeing resultText before continuity
+     * decays into staleText. Defaults to 1.
+     */
+    resultTurns?: number;
+    /**
+     * What later turns should see after resultText ages out. If omitted,
+     * resultText remains the durable outcome note.
+     */
+    staleText?: string;
+    /**
+     * Short concrete anchors that should remain visible if the host audits or
+     * trims the continuity payload.
+     */
+    auditAnchors?: string[];
+}
+export interface CoderActionResult {
+    /** Text for the next turn's user-input message. */
+    historyNote: string;
+    /**
+     * Canonical trace line for the host's run log (TURNS.md, etc). Block
+     * shape already indented; host can embed directly.
+     */
+    log: string;
+    /** Hint: did the action mutate the artifact's shippable state? */
+    mutatedArtifact?: boolean;
+    /** Hint: did the action produce a browser screenshot? */
+    capturedScreenshot?: boolean;
+    /** Hint: runStart returned an origin. Host spins up its browser harness. */
+    liveOrigin?: string;
+    /** Hint: this action was a sandbox-tool or runCommand call. */
+    sandboxToolCall?: boolean;
+    /**
+     * Raw exit code from sandbox-tool / runCommand calls. Set only when
+     * `sandboxToolCall` is true. Hosts can use this to drive their own
+     * pass/fail tracking without parsing the log string.
+     */
+    toolExitCode?: number;
+    /** Multimodal attachments (screenshot PNG). */
+    attachments?: CoderActionAttachment[];
+    /** First-class continuity payload for the next turn. */
+    continuity?: CoderActionContinuity;
+    /** Mechanical outcome of the action. This is not quality judgment. */
+    ok?: boolean;
+    /** Broad executor family for batch semantics and host telemetry. */
+    kind?: CoderActionKind;
+    /** True when a same-turn action was not run because an earlier action failed. */
+    skipped?: boolean;
+}
+export type CoderActionKind = 'fileMutation' | 'read' | 'sandbox' | 'browser' | 'unhandled';
+export interface CoderActionExecution<TAction extends {
+    name: string;
+    params: Record<string, unknown>;
+} = {
+    name: string;
+    params: Record<string, unknown>;
+}> {
+    action: TAction;
+    result: CoderActionResult | null;
+}
+/**
+ * Return the text a host should carry into the immediately following
+ * continuity surface for a coder action.
+ *
+ * Use this instead of reading `continuity.staleText` directly. `staleText`
+ * is intentionally a later-turn tombstone; showing it immediately makes a
+ * successful read/search look as if the result was already unavailable.
+ */
+export declare function immediateCoderActionOutcome(result: Pick<CoderActionResult, 'historyNote' | 'continuity'>): string;
+/**
+ * Return the compact factual note safe to share beyond the actor's private
+ * workset. This preserves the important truth ("file X was written",
+ * "edit failed", "console was read") without carrying large read/search
+ * payloads into another participant's history.
+ */
+export declare function compactCoderActionOutcome(result: Pick<CoderActionResult, 'historyNote' | 'continuity' | 'toolExitCode'>): string;
+/**
+ * Return an outcome note suitable for stored chat history. Small factual
+ * results stay attached to the narrative that caused them ("I will list" is
+ * followed by the actual list result); large results decay to their compact
+ * recovery note so history does not become a file-content cache.
+ */
+export declare function historyCoderActionOutcome(result: Pick<CoderActionResult, 'historyNote' | 'continuity'>, options?: {
+    maxBytes?: number;
+}): string;
+export declare function coderActionOutcomeForLedger(action: Pick<ParsedAction, 'name' | 'params'>, result: Pick<CoderActionResult, 'historyNote' | 'continuity'>, options?: {
+    maxBytes?: number;
+}): TurnLedgerActionOutcome;
+/**
+ * Execute one parsed coder action. Returns the structured result if the
+ * name matches a coder primitive, or `null` if the host should dispatch
+ * it (benchmark-specific actions like markMilestone).
+ *
+ * Never throws on user input — every failure is surfaced through the
+ * `historyNote` + `log` strings so the model sees what went wrong.
+ */
+export declare function executeCoderAction(input: {
+    action: {
+        name: string;
+        params: Record<string, unknown>;
+    };
+    context: CoderExecutorContext;
+}): Promise<CoderActionResult | null>;
+/**
+ * Execute a same-turn batch of coder actions with truthful continuity.
+ *
+ * The model chose every action in the batch before seeing any tool result
+ * from that same batch. Successful actions remain durable facts; the model
+ * chose a sequence, not one hidden turn-wide transaction. After any failure,
+ * runTests and finishAttempt are skipped because their result would claim
+ * verification/completion for a turn where some intended tool work failed.
+ *
+ * Unknown actions return `null` so hosts can dispatch them normally.
+ */
+export declare function executeCoderActions<TAction extends {
+    name: string;
+    params: Record<string, unknown>;
+}>(input: {
+    actions: readonly TAction[];
+    context: CoderExecutorContext;
+    onActionResult?(execution: CoderActionExecution<TAction>, context: CoderExecutorContext): Promise<void> | void;
+}): Promise<Array<CoderActionExecution<TAction>>>;
+export declare function collectCoderActionAttachmentsForNextTurn(results: readonly CoderActionResult[]): ChatAttachment[];
+/**
+ * Resolve a model-supplied relative path against the workspace root,
+ * refusing any path that escapes the workspace. Throws — the model
+ * should never see a path-traversal attempt succeed.
+ */
+export declare function resolveWorkspacePath(root: string, relativePath: string): string;
+/**
+ * Read a workspace file safely: returns a sentinel string for missing
+ * / oversized / binary files instead of throwing. No silent truncation
+ * for text files — if the model called readFile, it needs the full
+ * content to form editFile.oldText correctly.
+ */
+export declare function safeReadWorkspaceText(filePath: string): string;
+//# sourceMappingURL=executor.d.ts.map

package/dist/builder/executor.d.ts.map

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