@nikelyh/offscript 0.0.0-stage → 1.1.0

package/dist/packages/application/delete-configured-simulation.js

@@ -0,0 +1,11 @@
+import { simulationId } from "../domain/index.js";
+import { ApplicationError } from "./errors.js";
+export async function executeDeleteConfiguredSimulation(id, store) {
+    simulationId(id);
+    try {
+        return await store.deleteConfiguredSimulation(id);
+    }
+    catch (cause) {
+        throw new ApplicationError("DELETE_FAILED", "Could not delete the saved simulation.", { cause });
+    }
+}

package/dist/packages/application/errors.js

@@ -0,0 +1,8 @@
+export class ApplicationError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "ApplicationError";
+        this.code = code;
+    }
+}

package/dist/packages/application/index.js

@@ -0,0 +1,11 @@
+export { ApplicationError } from "./errors.js";
+export { executeDeleteConfiguredSimulation } from "./delete-configured-simulation.js";
+export { executeCheckTarget } from "./check-target.js";
+export { executeRequestInvestigation } from "./request-investigation/execute.js";
+export { executeAssignInvestigation } from "./assign-investigation/execute.js";
+export { executeCompleteInvestigation } from "./complete-investigation/execute.js";
+export { dispatchOutboxBatch } from "./outbox/dispatch.js";
+export { validateClaim, validateDispatch } from "./outbox/ports.js";
+export { executeConfigureSimulation } from "./configure-simulation/execute.js";
+export { configuredSimulation } from "./configure-simulation/profiles.js";
+export { executeRecoverSimulation } from "./recover-simulation/execute.js";

package/dist/packages/application/outbox/dispatch.js

@@ -0,0 +1,48 @@
+import { deserializeSemanticEvent } from "../../contracts/index.js";
+import { validateDispatch } from "./ports.js";
+export async function dispatchOutboxBatch(dependencies, options) {
+    validateDispatch(options);
+    const leases = await dependencies.store.claim({
+        now: dependencies.now(), leaseMs: options.leaseMs, limit: options.batchSize,
+        maxAttempts: options.maxAttempts, token: dependencies.token(),
+    });
+    const stats = { claimed: leases.length, accepted: 0, deferred: 0, rejected: 0, stale: 0 };
+    for (const lease of leases) {
+        if (dependencies.now() >= lease.leaseUntil) {
+            stats.stale++;
+            continue;
+        }
+        let event;
+        try {
+            const parsed = deserializeSemanticEvent(lease.eventJson);
+            if ((parsed.type !== "investigation.requested" && parsed.type !== "investigation.assigned" && parsed.type !== "investigation.completed") ||
+                parsed.eventId !== lease.eventId || parsed.simulationId !== lease.simulationId ||
+                parsed.payload.investigation.id !== lease.investigationId ||
+                (parsed.type === "investigation.requested" ? lease.revision !== 0 : lease.revision < 1))
+                throw new Error("Outbox event identity mismatch.");
+            event = parsed;
+        }
+        catch {
+            const updated = await dependencies.store.reject(lease.eventId, lease.leaseToken, dependencies.now(), "INVALID_EVENT", null);
+            stats[updated ? "rejected" : "stale"]++;
+            continue;
+        }
+        let outcome;
+        try {
+            outcome = await dependencies.publisher.publish(event);
+        }
+        catch {
+            const now = dependencies.now();
+            const backoff = Math.min(options.retryMaxMs, options.retryBaseMs * 2 ** Math.min(lease.attempts - 1, 30));
+            const updated = await dependencies.store.reject(lease.eventId, lease.leaseToken, now, "PUBLISH_REJECTED", lease.attempts >= options.maxAttempts ? null : now + backoff);
+            stats[updated ? "rejected" : "stale"]++;
+            continue;
+        }
+        const now = dependencies.now();
+        const updated = outcome === "deferred"
+            ? await dependencies.store.defer(lease.eventId, lease.leaseToken, now, now + options.deferMs)
+            : await dependencies.store.accept(lease.eventId, lease.leaseToken, now);
+        stats[updated ? outcome : "stale"]++;
+    }
+    return Object.freeze(stats);
+}

package/dist/packages/application/outbox/ports.js

@@ -0,0 +1,16 @@
+export function validateDispatch(options) {
+    for (const value of Object.values(options)) {
+        if (!Number.isSafeInteger(value) || value <= 0 || value > 2_147_483_647)
+            throw new Error("Outbox options must be bounded positive integers.");
+    }
+    if (options.batchSize > 100 || options.maxAttempts > 100 || options.retryBaseMs > options.retryMaxMs)
+        throw new Error("Invalid outbox limits.");
+}
+export function validateClaim(options) {
+    if (!Number.isSafeInteger(options.now) || options.now < 0 || !options.token.trim())
+        throw new Error("Invalid outbox claim identity/time.");
+    if (!Number.isSafeInteger(options.leaseMs) || options.leaseMs <= 0 || !Number.isSafeInteger(options.now + options.leaseMs))
+        throw new Error("Invalid lease duration.");
+    if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100 || !Number.isInteger(options.maxAttempts) || options.maxAttempts < 1 || options.maxAttempts > 100)
+        throw new Error("Invalid claim limits.");
+}

package/dist/packages/application/recover-simulation/execute.js

@@ -0,0 +1,31 @@
+import { simulationId, transitionSimulation } from "../../domain/index.js";
+import { ApplicationError } from "../errors.js";
+export async function executeRecoverSimulation(command, store) {
+    simulationId(command.simulationId);
+    const sim = await store.findSimulation(command.simulationId);
+    if (!sim) {
+        throw new ApplicationError("SIMULATION_NOT_FOUND", "Simulation not found.");
+    }
+    if (sim.lifecycle.status !== "running") {
+        throw new ApplicationError("INVALID_EXECUTION_STATE", `Only running simulations can be recovered; current status is ${sim.lifecycle.status}.`);
+    }
+    const action = command.action ?? "fail";
+    const reason = (command.reason && command.reason.trim())
+        ? command.reason
+        : "INTERRUPTED_BY_HOST_RESTART";
+    const nextSim = action === "cancel"
+        ? transitionSimulation(sim, { status: "cancelled" })
+        : transitionSimulation(sim, { status: "failed", reason });
+    const commit = await store.updateSimulationAggregate(nextSim, { status: "running" });
+    if (commit === "conflict") {
+        throw new ApplicationError("EXECUTION_ALREADY_ACTIVE", "Simulation state changed concurrently.");
+    }
+    if (commit === "not-found") {
+        throw new ApplicationError("SIMULATION_NOT_FOUND", "Simulation not found.");
+    }
+    return Object.freeze({
+        simulation: nextSim,
+        action,
+        recoveredAt: new Date().toISOString(),
+    });
+}

package/dist/packages/application/recover-simulation/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/application/request-investigation/execute.js

@@ -0,0 +1,38 @@
+import { agentId, investigationId, observationId, requestInvestigation, simulationId } from "../../domain/index.js";
+import { parseInvestigationEvent } from "../../contracts/index.js";
+import { ApplicationError } from "../errors.js";
+import { resolveContext } from "./resolve-context.js";
+export async function executeRequestInvestigation(input, dependencies) {
+    // Snapshot caller-owned data before awaiting adapters.
+    const command = Object.freeze({
+        ...input, investigationId: investigationId(input.investigationId), simulationId: simulationId(input.simulationId),
+        requestedBy: agentId(input.requestedBy), observationIds: Object.freeze(input.observationIds.map(observationId)),
+    });
+    const observations = await resolveContext(command, dependencies);
+    const investigation = requestInvestigation({
+        id: command.investigationId, simulationId: command.simulationId, requestedBy: command.requestedBy,
+        hypothesis: command.hypothesis, requestedAt: command.requestedAt,
+    }, observations);
+    const event = parseInvestigationEvent({
+        eventId: command.eventId, type: "investigation.requested", schemaVersion: 1,
+        occurredAt: command.requestedAt, simulationId: command.simulationId,
+        origin: { kind: "agent", agentId: command.requestedBy }, correlationId: command.correlationId,
+        payload: { investigation },
+    });
+    if (event.type !== "investigation.requested") {
+        throw new ApplicationError("INVALID_REFERENCE", "Unexpected event type returned by the contract parser.");
+    }
+    let saved;
+    try {
+        saved = await dependencies.investigations.commitRequest(event);
+    }
+    catch (cause) {
+        throw new ApplicationError("SAVE_FAILED", "Investigation save failed; its commit outcome may be unknown.", { cause });
+    }
+    if (saved === "already-exists") {
+        throw new ApplicationError("INVESTIGATION_ALREADY_EXISTS", "An investigation with this identity already exists.");
+    }
+    if (saved === "event-conflict")
+        throw new ApplicationError("EVENT_ID_CONFLICT", "Event identity already has different content.");
+    return Object.freeze({ investigation, event, publication: Object.freeze({ status: saved === "duplicate" ? "already-recorded" : "queued" }) });
+}

package/dist/packages/application/request-investigation/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/application/request-investigation/resolve-context.js

@@ -0,0 +1,41 @@
+import { ApplicationError } from "../errors.js";
+async function read(operation) {
+    try {
+        return await operation();
+    }
+    catch (cause) {
+        throw new ApplicationError("READ_FAILED", "Could not read investigation context.", { cause });
+    }
+}
+export async function resolveContext(command, dependencies) {
+    const simulation = await read(() => dependencies.simulations.findSimulation(command.simulationId));
+    if (!simulation)
+        throw new ApplicationError("SIMULATION_NOT_FOUND", "Simulation does not exist.");
+    validateSimulation(simulation, command);
+    const observations = [];
+    for (const id of command.observationIds) {
+        const observation = await read(() => dependencies.observations.findObservation(id));
+        if (!observation)
+            throw new ApplicationError("OBSERVATION_NOT_FOUND", `Observation does not exist: ${id}`);
+        if (observation.id !== id || observation.simulationId !== simulation.id ||
+            !simulation.agents.some((agent) => agent.id === observation.agentId)) {
+            throw new ApplicationError("INVALID_REFERENCE", "Observation identity, simulation, or author is inconsistent.");
+        }
+        observations.push(observation);
+    }
+    return observations;
+}
+function validateSimulation(simulation, command) {
+    if (simulation.id !== command.simulationId) {
+        throw new ApplicationError("INVALID_REFERENCE", "Simulation reader returned a different identity.");
+    }
+    if (simulation.lifecycle.status !== "running") {
+        throw new ApplicationError("SIMULATION_NOT_RUNNING", "Investigation requests require a running simulation.");
+    }
+    const requester = simulation.agents.find((agent) => agent.id === command.requestedBy);
+    if (!requester)
+        throw new ApplicationError("REQUESTER_NOT_FOUND", "Requesting agent is not a simulation member.");
+    if (requester.lifecycle.status !== "running") {
+        throw new ApplicationError("REQUESTER_NOT_RUNNING", "Requesting agent must have active participation.");
+    }
+}

package/dist/packages/browser/browser-manager.js

@@ -0,0 +1,91 @@
+import { chromium } from "playwright";
+import { BrowserUserSession } from "./session.js";
+export class BrowserManager {
+    browser = null;
+    pendingLaunch = null;
+    headless;
+    sessions = new Set();
+    closed = false;
+    constructor(options = {}) {
+        this.headless = options.headless ?? true;
+    }
+    async ensureBrowser() {
+        if (this.closed)
+            throw new Error("BrowserManager is closed.");
+        if (this.browser && this.browser.isConnected()) {
+            return this.browser;
+        }
+        if (this.pendingLaunch) {
+            return this.pendingLaunch;
+        }
+        this.pendingLaunch = (async () => {
+            try {
+                const browser = await chromium.launch({
+                    headless: this.headless,
+                });
+                if (this.closed) {
+                    await browser.close().catch(() => { });
+                    throw new Error("BrowserManager was closed during launch.");
+                }
+                this.browser = browser;
+                return browser;
+            }
+            catch (cause) {
+                if (cause instanceof Error && cause.message.includes("Executable doesn't exist")) {
+                    throw new Error("Chromium executable is not installed. Run 'npx playwright install chromium' before launching browser sessions.", { cause });
+                }
+                throw cause;
+            }
+            finally {
+                this.pendingLaunch = null;
+            }
+        })();
+        return this.pendingLaunch;
+    }
+    async createSession(options) {
+        if (this.closed)
+            throw new Error("BrowserManager is closed.");
+        const browser = await this.ensureBrowser();
+        const contextOptions = {};
+        if (options.storageState) {
+            contextOptions.storageState = options.storageState;
+        }
+        const context = await browser.newContext(contextOptions);
+        const session = await BrowserUserSession.create(context, options);
+        this.sessions.add(session);
+        return session;
+    }
+    async closeSession(session) {
+        this.sessions.delete(session);
+        await session.close();
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const session of this.sessions) {
+            await session.close().catch(() => { });
+        }
+        this.sessions.clear();
+        if (this.pendingLaunch) {
+            try {
+                const browser = await this.pendingLaunch;
+                await browser.close().catch(() => { });
+            }
+            catch {
+                // Ignore launch error during close
+            }
+            this.pendingLaunch = null;
+        }
+        if (this.browser) {
+            await this.browser.close().catch(() => { });
+            this.browser = null;
+        }
+    }
+    isClosed() {
+        return this.closed;
+    }
+}
+export function createBrowserManager(options = {}) {
+    return new BrowserManager(options);
+}

package/dist/packages/browser/dom-snapshot.js

@@ -0,0 +1,186 @@
+const INTERACTIVE_SELECTOR = [
+    "button",
+    "a[href]",
+    "input:not([type='hidden'])",
+    "select",
+    "textarea",
+    "details summary",
+    "[role='button']",
+    "[role='link']",
+    "[role='checkbox']",
+    "[role='radio']",
+    "[role='textbox']",
+    "[role='combobox']",
+    "[role='tab']",
+    "[role='menuitem']",
+].join(", ");
+export async function capturePageSnapshot(page, epoch) {
+    const url = page.url();
+    const title = await page.title().catch(() => "");
+    // Temporarily mask password values so they never appear in the accessibility tree
+    const originalPasswords = await page
+        .evaluate(() => {
+        const saved = [];
+        const pwElements = document.querySelectorAll("input[type='password']");
+        for (const el of pwElements) {
+            saved.push(el.value);
+            el.value = "";
+        }
+        return saved;
+    })
+        .catch(() => []);
+    let ariaSnapshot;
+    try {
+        ariaSnapshot = await page.locator(":root").ariaSnapshot();
+    }
+    catch {
+        ariaSnapshot = undefined;
+    }
+    // Restore password values if necessary for form state
+    if (originalPasswords.length > 0) {
+        await page
+            .evaluate((vals) => {
+            const pwElements = document.querySelectorAll("input[type='password']");
+            for (let i = 0; i < pwElements.length && i < vals.length; i++) {
+                const val = vals[i];
+                if (val !== undefined && pwElements[i])
+                    pwElements[i].value = val;
+            }
+        }, originalPasswords)
+            .catch(() => { });
+    }
+    const { elements, textSummary } = await page.evaluate(({ selector, epochNumber }) => {
+        // Clear any previous references
+        for (const el of document.querySelectorAll("[data-offscript-ref]")) {
+            el.removeAttribute("data-offscript-ref");
+            el.removeAttribute("data-offscript-epoch");
+        }
+        function isVisible(el) {
+            const htmlEl = el;
+            if (!htmlEl)
+                return false;
+            const rect = htmlEl.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0)
+                return false;
+            const style = window.getComputedStyle(htmlEl);
+            if (style.visibility === "hidden" || style.display === "none")
+                return false;
+            return true;
+        }
+        function computeName(el) {
+            const ariaLabel = el.getAttribute("aria-label");
+            if (ariaLabel && ariaLabel.trim())
+                return ariaLabel.trim();
+            const labelledBy = el.getAttribute("aria-labelledby");
+            if (labelledBy) {
+                const labelEl = document.getElementById(labelledBy);
+                if (labelEl?.textContent)
+                    return labelEl.textContent.trim();
+            }
+            const inputEl = el;
+            if (inputEl.labels && inputEl.labels.length > 0) {
+                const label = inputEl.labels[0]?.textContent?.trim();
+                if (label)
+                    return label;
+            }
+            if (inputEl.placeholder)
+                return inputEl.placeholder.trim();
+            const textContent = el.textContent?.trim() || "";
+            return textContent.slice(0, 100);
+        }
+        function computeRole(el) {
+            const explicitRole = el.getAttribute("role");
+            if (explicitRole)
+                return explicitRole.toLowerCase();
+            const tag = el.tagName.toLowerCase();
+            if (tag === "a")
+                return "link";
+            if (tag === "button")
+                return "button";
+            if (tag === "select")
+                return "combobox";
+            if (tag === "textarea")
+                return "textbox";
+            if (tag === "input") {
+                const type = el.type.toLowerCase();
+                if (type === "button" || type === "submit" || type === "reset")
+                    return "button";
+                if (type === "checkbox")
+                    return "checkbox";
+                if (type === "radio")
+                    return "radio";
+                return "textbox";
+            }
+            return tag;
+        }
+        const found = [];
+        const candidates = document.querySelectorAll(selector);
+        let counter = 1;
+        for (const candidate of candidates) {
+            if (!isVisible(candidate))
+                continue;
+            const ref = `elem_${counter}`;
+            candidate.setAttribute("data-offscript-ref", ref);
+            candidate.setAttribute("data-offscript-epoch", String(epochNumber));
+            const role = computeRole(candidate);
+            const name = computeName(candidate);
+            const inputEl = candidate;
+            const typeAttr = inputEl.type ? inputEl.type.toLowerCase() : undefined;
+            const isPassword = typeAttr === "password";
+            const text = isPassword ? "" : (candidate.textContent?.trim().slice(0, 80) || "");
+            const disabled = candidate.disabled === true ||
+                candidate.getAttribute("aria-disabled") === "true";
+            let checked;
+            if (inputEl.checked !== undefined && (inputEl.type === "checkbox" || inputEl.type === "radio")) {
+                checked = inputEl.checked;
+            }
+            else if (candidate.getAttribute("aria-checked") !== null) {
+                checked = candidate.getAttribute("aria-checked") === "true";
+            }
+            let expanded;
+            const ariaExpanded = candidate.getAttribute("aria-expanded");
+            if (ariaExpanded === "true")
+                expanded = true;
+            else if (ariaExpanded === "false")
+                expanded = false;
+            const placeholder = !isPassword && inputEl.placeholder ? inputEl.placeholder : undefined;
+            found.push({
+                ref,
+                role,
+                name,
+                tagName: candidate.tagName,
+                text,
+                disabled,
+                ...(typeAttr ? { type: typeAttr } : {}),
+                ...(checked !== undefined ? { checked } : {}),
+                ...(expanded !== undefined ? { expanded } : {}),
+                ...(placeholder ? { placeholder } : {}),
+            });
+            counter++;
+        }
+        // Collect bounded visible text summary
+        const textNodes = [];
+        const contentElements = document.querySelectorAll("h1, h2, h3, h4, p, label, pre, [role='status'], [role='alert'], div[id], span[id], li");
+        let totalLength = 0;
+        for (const h of contentElements) {
+            if (!isVisible(h))
+                continue;
+            const t = h.textContent?.trim();
+            if (t && t.length > 0) {
+                textNodes.push(`${h.tagName.toLowerCase()}: ${t}`);
+                totalLength += t.length;
+                if (totalLength > 3000)
+                    break;
+            }
+        }
+        return { elements: found, textSummary: textNodes.join("\n") };
+    }, { selector: INTERACTIVE_SELECTOR, epochNumber: epoch });
+    return Object.freeze({
+        url,
+        title,
+        textSummary,
+        elements: Object.freeze(elements),
+        snapshotEpoch: epoch,
+        ...(ariaSnapshot ? { ariaSnapshot } : {}),
+    });
+}

package/dist/packages/browser/index.js

@@ -0,0 +1,5 @@
+export { BrowserManager, createBrowserManager } from "./browser-manager.js";
+export { BrowserUserSession } from "./session.js";
+export { ScopeViolationError, assertInScope, isAllowedSubresource, isUrlInScope, normalizeTargetUrl, } from "./scope-guard.js";
+export { capturePageSnapshot } from "./dom-snapshot.js";
+export { createBrowserTools } from "./tools/browser-tools.js";

package/dist/packages/browser/scope-guard.js

@@ -0,0 +1,73 @@
+export class ScopeViolationError extends Error {
+    attemptedUrl;
+    constructor(message, attemptedUrl) {
+        super(message);
+        this.name = "ScopeViolationError";
+        this.attemptedUrl = attemptedUrl;
+    }
+}
+export function normalizeTargetUrl(input) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0 || trimmed.length > 2048) {
+        throw new ScopeViolationError("Target URL is missing or exceeds maximum length.", trimmed);
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new ScopeViolationError("Target URL is not a valid URL.", trimmed);
+    }
+    if (!/^https?:$/i.test(parsed.protocol)) {
+        throw new ScopeViolationError("Target URL must use http or https protocol.", trimmed);
+    }
+    if (parsed.username || parsed.password) {
+        throw new ScopeViolationError("Target URL must not contain credentials.", trimmed);
+    }
+    parsed.hash = "";
+    return parsed.href;
+}
+export function isUrlInScope(candidate, targetBaseUrl) {
+    try {
+        const base = new URL(normalizeTargetUrl(targetBaseUrl));
+        const target = new URL(candidate, base);
+        if (target.protocol !== base.protocol)
+            return false;
+        if (target.hostname !== base.hostname)
+            return false;
+        if (target.port !== base.port)
+            return false;
+        if (target.username || target.password)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function assertInScope(candidate, targetBaseUrl) {
+    const base = new URL(normalizeTargetUrl(targetBaseUrl));
+    let resolved;
+    try {
+        resolved = new URL(candidate, base);
+    }
+    catch {
+        throw new ScopeViolationError(`Cannot resolve URL "${candidate}" against target.`, candidate);
+    }
+    if (!/^https?:$/i.test(resolved.protocol)) {
+        throw new ScopeViolationError(`Disallowed protocol "${resolved.protocol}" for "${candidate}".`, candidate);
+    }
+    if (resolved.username || resolved.password) {
+        throw new ScopeViolationError("Target URL must not contain credentials.", candidate);
+    }
+    if (resolved.origin !== base.origin) {
+        throw new ScopeViolationError(`Navigation to origin "${resolved.origin}" is out of authorized target scope "${base.origin}".`, resolved.href);
+    }
+    resolved.hash = "";
+    return resolved.href;
+}
+export function isAllowedSubresource(url, targetBaseUrl) {
+    if (url.startsWith("data:") || url.startsWith("blob:"))
+        return true;
+    return isUrlInScope(url, targetBaseUrl);
+}