@nikelyh/offscript 0.0.0-stage → 1.0.0

package/dist/packages/projects/suggest-target.js

@@ -0,0 +1,34 @@
+/** Recognize only simple Vite scripts; never evaluate project configuration. */
+export function suggestTarget(manifest) {
+    const scripts = "scripts" in manifest ? manifest.scripts : undefined;
+    if (!scripts || typeof scripts !== "object" || Array.isArray(scripts))
+        return;
+    for (const scriptName of ["dev", "start"]) {
+        const script = scriptName in scripts ? Reflect.get(scripts, scriptName) : undefined;
+        if (typeof script !== "string" || !/^vite(?:\s|$)/.test(script) || /[^\w\s.=:/-]/.test(script))
+            continue;
+        const args = script.trim().split(/\s+/).slice(1);
+        let port = "5173";
+        let valid = true;
+        let explicitPort = false;
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (arg === "--port" || arg?.startsWith("--port=")) {
+                port = arg === "--port" ? args[++i] ?? "" : arg.slice(7);
+                explicitPort = true;
+                if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535)
+                    valid = false;
+            }
+            else if (arg === "--host" || arg?.startsWith("--host=")) {
+                const host = arg === "--host" && args[i + 1] && !args[i + 1]?.startsWith("--") ? args[++i] : arg?.slice(7);
+                if (host && !["localhost", "127.0.0.1", "0.0.0.0"].includes(host))
+                    valid = false;
+            }
+            else if (arg !== "--strictPort")
+                valid = false;
+        }
+        if (valid)
+            return Object.freeze({ url: `http://localhost:${Number(port)}/`, source: explicitPort ? "vite-script" : "vite-default", scriptName });
+    }
+    return;
+}

package/dist/packages/projects/target-probe.js

@@ -0,0 +1,61 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { parseLocalTargetUrl } from "../contracts/index.js";
+/** Explicit, bounded checks; no DNS, redirects, cookies, or response bodies. */
+export function createTargetProbe() {
+    let active = 0;
+    return { async check(input, signal) {
+            const url = parseLocalTargetUrl(input);
+            signal?.throwIfAborted();
+            if (active >= 2)
+                return Object.freeze({ url, kind: "busy" });
+            active++;
+            try {
+                return await new Promise((resolve, reject) => {
+                    const target = new URL(url);
+                    const controller = new AbortController();
+                    let timedOut = false;
+                    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, 2500);
+                    const abort = () => controller.abort();
+                    signal?.addEventListener("abort", abort, { once: true });
+                    const done = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); };
+                    let settled = false;
+                    function send(hostname) {
+                        const request = (target.protocol === "https:" ? httpsRequest : httpRequest)({
+                            protocol: target.protocol, hostname,
+                            port: target.port || (target.protocol === "https:" ? 443 : 80), method: "GET",
+                            path: target.pathname + target.search, headers: { Host: target.host, Accept: "text/html" },
+                            ...(target.protocol === "https:" && target.hostname === "localhost" ? { servername: "localhost" } : {}),
+                            agent: false, maxHeaderSize: 8192, signal: controller.signal,
+                        }, response => {
+                            settled = true;
+                            done();
+                            resolve(Object.freeze({ url, kind: "response", statusCode: response.statusCode ?? 500 }));
+                            response.destroy();
+                        });
+                        request.on("error", (error) => {
+                            if (settled)
+                                return;
+                            if (target.hostname === "localhost" && hostname === "127.0.0.1" && error.code === "ECONNREFUSED" && !controller.signal.aborted) {
+                                send("::1");
+                                return;
+                            }
+                            settled = true;
+                            done();
+                            if (signal?.aborted) {
+                                reject(signal.reason);
+                                return;
+                            }
+                            const tls = /CERT|TLS|SSL|SELF_SIGNED|UNABLE_TO_VERIFY/.test(error.code ?? "");
+                            resolve(Object.freeze({ url, kind: timedOut ? "timeout" : tls ? "tls-error" : "unreachable" }));
+                        });
+                        request.end();
+                    }
+                    send(target.hostname === "[::1]" ? "::1" : "127.0.0.1");
+                });
+            }
+            finally {
+                active--;
+            }
+        } };
+}

package/dist/packages/runtime/deadline.js

@@ -0,0 +1,11 @@
+export async function withinDeadline(pending, durationMs) {
+    let timer;
+    try {
+        return await Promise.race([pending, new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Host shutdown timed out; cleanup continues without force-closing storage.")), durationMs);
+            })]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/packages/runtime/evidence-store.js

@@ -0,0 +1,76 @@
+import { mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync, existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+function assertSafeId(id, label) {
+    if (!id || !/^[a-zA-Z0-9_-]+$/.test(id)) {
+        throw new Error(`Invalid ${label}: identifiers must only contain alphanumeric characters, hyphens, and underscores.`);
+    }
+    return id;
+}
+export function createEvidenceStore(baseDir, maxScreenshotsPerSimulation = 50) {
+    const root = resolve(baseDir, "evidence");
+    function getSimDir(simId) {
+        const safeId = assertSafeId(simId, "simulationId");
+        const dir = resolve(root, safeId);
+        if (!dir.startsWith(root)) {
+            throw new Error("Path traversal violation: simulation directory outside evidence root.");
+        }
+        return dir;
+    }
+    function getFilePath(simId, evId) {
+        const dir = getSimDir(simId);
+        const safeEvId = assertSafeId(evId, "evidenceId");
+        const filePath = resolve(dir, `${safeEvId}.png`);
+        if (!filePath.startsWith(dir)) {
+            throw new Error("Path traversal violation: evidence file path outside simulation directory.");
+        }
+        return filePath;
+    }
+    return Object.freeze({
+        async saveEvidence(simulationId, evidenceId, data, contentType = "image/png") {
+            void contentType;
+            const dir = getSimDir(simulationId);
+            mkdirSync(dir, { recursive: true });
+            const files = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".png")) : [];
+            if (files.length >= maxScreenshotsPerSimulation) {
+                const filesWithMtime = files.map((fileName) => {
+                    const fullPath = join(dir, fileName);
+                    try {
+                        return { fullPath, mtimeMs: statSync(fullPath).mtimeMs };
+                    }
+                    catch {
+                        return { fullPath, mtimeMs: 0 };
+                    }
+                });
+                filesWithMtime.sort((a, b) => a.mtimeMs - b.mtimeMs);
+                const oldest = filesWithMtime[0];
+                if (oldest)
+                    rmSync(oldest.fullPath, { force: true });
+            }
+            const filePath = getFilePath(simulationId, evidenceId);
+            writeFileSync(filePath, data);
+        },
+        async getEvidence(simulationId, evidenceId) {
+            try {
+                const filePath = getFilePath(simulationId, evidenceId);
+                if (!existsSync(filePath))
+                    return undefined;
+                const data = readFileSync(filePath);
+                return { data, contentType: "image/png" };
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async deleteSimulationEvidence(simulationId) {
+            try {
+                const dir = getSimDir(simulationId);
+                if (existsSync(dir)) {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+            }
+            catch {
+                // Safe fallback on invalid simulation identity
+            }
+        },
+    });
+}

package/dist/packages/runtime/execution-coordinator.js

@@ -0,0 +1,223 @@
+import { simulationId, transitionSimulation, updateSimulationAgent } from "../domain/index.js";
+import { ApplicationError } from "../application/index.js";
+import { inspectExecutionFailures, settleSimulationAggregate } from "./execution-settlement.js";
+export function executionCoordinator(dependencies) {
+    const { storage, prepareSession, factory, evidenceStore } = dependencies;
+    const active = new Map();
+    let closed = false;
+    function toStatus(record) {
+        let turnsCount = record.turnsCount;
+        let recentActivity;
+        let activeAgents = (record.phase === "starting" || record.phase === "running") ? record.activeAgents : [];
+        if (record.session?.snapshot) {
+            const snap = record.session.snapshot();
+            if (snap.turns)
+                turnsCount = snap.turns.reduce((sum, item) => sum + item.count, 0);
+            if (snap.recentActivity)
+                recentActivity = snap.recentActivity;
+            if ((record.phase === "starting" || record.phase === "running") && snap.activeAgents) {
+                activeAgents = snap.activeAgents;
+            }
+        }
+        return Object.freeze({
+            simulationId: record.simulationId, phase: record.phase, mode: record.mode,
+            turnsCount, activeAgents,
+            ...(record.failureReason ? { failureReason: record.failureReason } : {}),
+            startedAt: record.startedAt,
+            ...(record.stoppedAt ? { stoppedAt: record.stoppedAt } : {}),
+            ...(recentActivity ? { recentActivity } : {}),
+        });
+    }
+    async function finalizeExecution(record, outcome, reason) {
+        record.phase = "stopping";
+        if (record.timer)
+            clearTimeout(record.timer);
+        const result = await settleSimulationAggregate(storage, record.simulationId, outcome, reason);
+        let closeError;
+        try {
+            await record.session?.close();
+        }
+        catch (err) {
+            closeError = err;
+        }
+        record.stoppedAt = new Date().toISOString();
+        if (closeError) {
+            record.phase = "failed";
+            record.failureReason = "SESSION_CLOSE_FAILED";
+        }
+        else if (!result.settled && (result.reason === "storage-error" || result.reason === "conflict")) {
+            record.phase = "failed";
+            record.failureReason = result.reason === "conflict" ? "SETTLEMENT_CONFLICT" : "SETTLEMENT_STORAGE_FAILED";
+        }
+        else {
+            record.phase = outcome;
+            if (reason)
+                record.failureReason = reason;
+        }
+    }
+    async function handleBudgetExpiry(id) {
+        const record = active.get(id);
+        if (!record || record.phase !== "running")
+            return;
+        await finalizeExecution(record, "cancelled", "SESSION_BUDGET_EXHAUSTED");
+    }
+    function monitorSettlement(id, session, durationMs) {
+        if (!session.waitForIdle)
+            return;
+        void session.waitForIdle(durationMs).then(async (snap) => {
+            const record = active.get(id);
+            if (!record || record.phase !== "running")
+                return;
+            const failureCheck = inspectExecutionFailures(snap ?? record.session?.snapshot?.());
+            if (failureCheck.hasFailures) {
+                await finalizeExecution(record, "failed", failureCheck.reason ?? "SESSION_EXECUTION_FAILED");
+            }
+            else {
+                await finalizeExecution(record, "completed");
+            }
+        }).catch(async (cause) => {
+            const record = active.get(id);
+            if (!record || record.phase !== "running")
+                return;
+            const isTimeout = cause instanceof Error && cause.message.includes("timed out");
+            const reason = isTimeout ? "SESSION_BUDGET_EXHAUSTED" : "SESSION_EXECUTION_FAILED";
+            const outcome = isTimeout ? "cancelled" : "failed";
+            await finalizeExecution(record, outcome, reason);
+        });
+    }
+    async function start(id, mode) {
+        if (closed)
+            throw new ApplicationError("EXECUTION_START_FAILED", "Host is closing.");
+        if (!factory)
+            throw new ApplicationError("EXECUTION_START_FAILED", "No execution session factory configured on this host.");
+        if (mode !== "controlled-demo" && mode !== "browser-exploration") {
+            throw new ApplicationError("INVALID_EXECUTION_STATE", `Unsupported execution mode: ${mode}`);
+        }
+        const existing = active.get(id);
+        if (existing && (existing.phase === "starting" || existing.phase === "running" || existing.phase === "stopping")) {
+            throw new ApplicationError("EXECUTION_ALREADY_ACTIVE", "Simulation is already executing.");
+        }
+        const [config, sim] = await Promise.all([
+            storage.configurations.findConfiguration(id),
+            storage.simulations.findSimulation(id),
+        ]);
+        if (!config || !sim)
+            throw new ApplicationError("SIMULATION_NOT_FOUND", "Simulation configuration not found.");
+        if (sim.lifecycle.status !== "created") {
+            throw new ApplicationError("INVALID_EXECUTION_STATE", `Simulation cannot start from status ${sim.lifecycle.status}.`);
+        }
+        if (sim.agents.some((agent) => agent.lifecycle.status !== "ready")) {
+            throw new ApplicationError("INVALID_EXECUTION_STATE", "All agents must be ready to start.");
+        }
+        let runningSim = transitionSimulation(sim, { status: "running" });
+        for (const agent of sim.agents) {
+            runningSim = updateSimulationAgent(runningSim, agent.id, { status: "running" });
+        }
+        const expectedAgentStatuses = new Map(sim.agents.map((agent) => [agent.id, "ready"]));
+        const commit = await storage.simulations.updateSimulationAggregate(runningSim, {
+            status: "created",
+            agentStatuses: expectedAgentStatuses,
+        });
+        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.");
+        const startedAt = new Date().toISOString();
+        const record = {
+            simulationId: id, phase: "starting", mode, turnsCount: 0,
+            activeAgents: sim.agents.map((agent) => agent.id), startedAt,
+        };
+        active.set(id, record);
+        try {
+            const session = prepareSession(id, () => factory(runningSim, config.limits, storage, {
+                mode,
+                targetUrl: config.targetUrl,
+                evidenceStore,
+            }));
+            record.session = session;
+            record.phase = "running";
+            record.timer = setTimeout(() => { void handleBudgetExpiry(id); }, config.limits.durationMs);
+            monitorSettlement(id, session, config.limits.durationMs);
+            for (const agent of sim.agents) {
+                const initialPrompt = mode === "browser-exploration"
+                    ? `Explore the application at ${config.targetUrl}. Pursue the goal: ${config.goal}`
+                    : "Explore the local cart and check items.";
+                session.startTurn(agent.id, initialPrompt);
+            }
+            return toStatus(record);
+        }
+        catch (cause) {
+            if (record.session) {
+                try {
+                    await record.session.close();
+                }
+                catch { /* Safe cleanup */ }
+            }
+            try {
+                const failedSim = transitionSimulation(runningSim, { status: "failed", reason: "RUNTIME_INITIALIZATION_FAILED" });
+                await storage.simulations.updateSimulationAggregate(failedSim, { status: "running" });
+            }
+            catch { /* Best-effort aggregate update */ }
+            record.phase = "failed";
+            record.failureReason = "RUNTIME_INITIALIZATION_FAILED";
+            record.stoppedAt = new Date().toISOString();
+            throw new ApplicationError("EXECUTION_START_FAILED", "Failed to initialize runtime session.", { cause });
+        }
+    }
+    async function stop(id) {
+        simulationId(id);
+        const record = active.get(id);
+        if (record && (record.phase === "starting" || record.phase === "running")) {
+            await finalizeExecution(record, "cancelled");
+            return toStatus(record);
+        }
+        const current = await storage.simulations.findSimulation(id);
+        if (!current)
+            throw new ApplicationError("SIMULATION_NOT_FOUND", "Simulation not found.");
+        if (current.lifecycle.status === "running") {
+            await settleSimulationAggregate(storage, id, "cancelled");
+            return Object.freeze({
+                simulationId: id, phase: "cancelled",
+                turnsCount: 0, activeAgents: [],
+            });
+        }
+        return inspect(id);
+    }
+    async function inspect(id) {
+        simulationId(id);
+        const record = active.get(id);
+        if (record)
+            return toStatus(record);
+        const sim = await storage.simulations.findSimulation(id);
+        if (!sim)
+            throw new ApplicationError("SIMULATION_NOT_FOUND", "Simulation not found.");
+        if (sim.lifecycle.status === "created") {
+            return Object.freeze({
+                simulationId: id, phase: "idle", turnsCount: 0, activeAgents: [],
+            });
+        }
+        if (sim.lifecycle.status === "running") {
+            return Object.freeze({
+                simulationId: id, phase: "interrupted",
+                turnsCount: 0, activeAgents: [],
+                failureReason: "INTERRUPTED_BY_HOST_RESTART",
+            });
+        }
+        return Object.freeze({
+            simulationId: id, phase: sim.lifecycle.status,
+            turnsCount: 0, activeAgents: [],
+            ...(sim.lifecycle.status === "failed" ? { failureReason: sim.lifecycle.reason } : {}),
+        });
+    }
+    async function close() {
+        closed = true;
+        const items = Array.from(active.values());
+        for (const record of items) {
+            if (record.phase === "starting" || record.phase === "running") {
+                await finalizeExecution(record, "cancelled");
+            }
+        }
+        active.clear();
+    }
+    return Object.freeze({ start, stop, inspect, close, hasActive: (id) => active.has(id) });
+}

package/dist/packages/runtime/execution-settlement.js

@@ -0,0 +1,50 @@
+import { transitionSimulation, updateSimulationAgent } from "../domain/index.js";
+export async function settleSimulationAggregate(storage, id, outcome, reason) {
+    try {
+        const currentSim = await storage.simulations.findSimulation(id);
+        if (!currentSim)
+            return { settled: false, reason: "not-found" };
+        if (currentSim.lifecycle.status !== "running")
+            return { settled: false, reason: "not-running" };
+        let targetSim;
+        if (outcome === "completed") {
+            let updatedSim = currentSim;
+            for (const agent of currentSim.agents) {
+                if (agent.lifecycle.status === "running") {
+                    updatedSim = updateSimulationAgent(updatedSim, agent.id, { status: "completed" });
+                }
+                else if (agent.lifecycle.status === "ready") {
+                    updatedSim = updateSimulationAgent(updatedSim, agent.id, { status: "cancelled" });
+                }
+            }
+            targetSim = transitionSimulation(updatedSim, { status: "completed" });
+        }
+        else if (outcome === "cancelled") {
+            targetSim = transitionSimulation(currentSim, { status: "cancelled" });
+        }
+        else {
+            targetSim = transitionSimulation(currentSim, {
+                status: "failed",
+                reason: reason ?? "EXECUTION_FAILED",
+            });
+        }
+        const commit = await storage.simulations.updateSimulationAggregate(targetSim, { status: "running" });
+        if (commit === "conflict" || commit === "not-found") {
+            return { settled: false, reason: commit };
+        }
+        return { settled: true, outcome, simulation: targetSim };
+    }
+    catch (error) {
+        return { settled: false, reason: "storage-error", error };
+    }
+}
+export function inspectExecutionFailures(snapshot) {
+    if (!snapshot || typeof snapshot !== "object")
+        return { hasFailures: false };
+    const failures = snapshot.failures;
+    if (!Array.isArray(failures) || failures.length === 0)
+        return { hasFailures: false };
+    const first = failures[0];
+    const stage = first?.stage ? `_${first.stage.toUpperCase().replace(/[^A-Z0-9]/g, "_")}` : "";
+    return { hasFailures: true, reason: `SESSION_EXECUTION_FAILED${stage}` };
+}

package/dist/packages/runtime/execution-types.js

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

package/dist/packages/runtime/host-config.js

@@ -0,0 +1,26 @@
+import { realpathSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+export function localHostConfig(options) {
+    if (!options.projectRoot.trim())
+        throw new Error("An explicit project root is required.");
+    const projectRoot = realpathSync(resolve(options.projectRoot));
+    if (!statSync(projectRoot).isDirectory())
+        throw new Error("Project root must be a directory.");
+    if (options.dataDirectory !== undefined && !options.dataDirectory.trim())
+        throw new Error("Data directory must not be blank.");
+    const port = options.port ?? 0;
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error("Invalid host port.");
+    const shutdownTimeoutMs = options.shutdownTimeoutMs ?? 15_000;
+    if (!Number.isInteger(shutdownTimeoutMs) || shutdownTimeoutMs < 1 || shutdownTimeoutMs > 60_000)
+        throw new Error("Invalid shutdown timeout.");
+    const allowedOrigins = [...options.allowedOrigins ?? []];
+    for (const origin of allowedOrigins) {
+        const url = new URL(origin);
+        if (!["http:", "https:"].includes(url.protocol) || url.origin !== origin || url.username || url.password)
+            throw new Error("Expected a canonical HTTP origin.");
+    }
+    return Object.freeze({ projectRoot, dataDirectory: resolve(projectRoot, options.dataDirectory ?? ".offscript"),
+        ...(options.studioDirectory === undefined ? {} : { studioDirectory: realpathSync(resolve(options.studioDirectory)) }),
+        port, allowedOrigins: Object.freeze(allowedOrigins), shutdownTimeoutMs });
+}

package/dist/packages/runtime/host-storage.js

@@ -0,0 +1,46 @@
+export function hostStorage(source) {
+    let accepting = true;
+    const pending = new Set();
+    function guard(operation) {
+        return (...args) => {
+            if (!accepting)
+                return Promise.reject(new Error("Host storage is closed to new operations."));
+            const result = Promise.resolve().then(() => operation(...args));
+            pending.add(result);
+            void result.then(() => pending.delete(result), () => pending.delete(result));
+            return result;
+        };
+    }
+    const storage = Object.freeze({
+        configurations: Object.freeze({
+            deleteConfiguredSimulation: guard(source.configurations.deleteConfiguredSimulation),
+            createConfiguredSimulation: guard(source.configurations.createConfiguredSimulation),
+            findConfiguration: guard(source.configurations.findConfiguration),
+            listConfigurations: guard(source.configurations.listConfigurations),
+        }),
+        simulations: Object.freeze({
+            createSimulation: guard(source.simulations.createSimulation),
+            findSimulation: guard(source.simulations.findSimulation),
+            updateSimulationAggregate: guard(source.simulations.updateSimulationAggregate),
+        }),
+        observations: Object.freeze({
+            createObservation: guard(source.observations.createObservation),
+            findObservation: guard(source.observations.findObservation),
+            listObservations: guard(source.observations.listObservations),
+        }),
+        investigations: Object.freeze({
+            findInvestigation: guard(source.investigations.findInvestigation),
+            listInvestigations: guard(source.investigations.listInvestigations),
+            commitRequest: guard(source.investigations.commitRequest),
+            commitAssignment: guard(source.investigations.commitAssignment),
+            commitCompletion: guard(source.investigations.commitCompletion),
+        }),
+        outbox: Object.freeze({
+            claim: guard(source.outbox.claim), accept: guard(source.outbox.accept), defer: guard(source.outbox.defer),
+            reject: guard(source.outbox.reject), inspect: guard(source.outbox.inspect), hasPending: guard(source.outbox.hasPending),
+        }),
+    });
+    return { storage,
+        async drain() { accepting = false; await Promise.allSettled(pending); },
+    };
+}

package/dist/packages/runtime/host.js

@@ -0,0 +1,2 @@
+export { createLocalHost } from "./local-host.js";
+export { createEvidenceStore } from "./evidence-store.js";

package/dist/packages/runtime/index.js

@@ -0,0 +1 @@
+export { createOutboxDispatcher } from "./outbox-dispatcher.js";