@tea-agent/loop-agent 0.16.26 → 0.17.1

package/dist/worker/console/routes.js

@@ -0,0 +1,368 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { dispatchOperatorAction } from "./operator-actions.js";
+import { openSseResponse, parseLastEventId, writeSseEvent, } from "./operation-sse.js";
+import { repoFingerprintV1 } from "./repo-fingerprint.js";
+import { evaluateMutationGate, injectConfirmationTokenScript, isMutationMethod, } from "./security.js";
+export function sendJson(res, status, body, extraHeaders) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Content-Length": Buffer.byteLength(payload),
+        ...extraHeaders,
+    });
+    res.end(payload);
+}
+function contentTypeFor(pathname) {
+    const lower = pathname.toLowerCase();
+    if (lower.endsWith(".html"))
+        return "text/html; charset=utf-8";
+    if (lower.endsWith(".js") || lower.endsWith(".mjs")) {
+        return "text/javascript; charset=utf-8";
+    }
+    if (lower.endsWith(".css"))
+        return "text/css; charset=utf-8";
+    if (lower.endsWith(".json"))
+        return "application/json; charset=utf-8";
+    if (lower.endsWith(".svg"))
+        return "image/svg+xml";
+    if (lower.endsWith(".png"))
+        return "image/png";
+    if (lower.endsWith(".ico"))
+        return "image/x-icon";
+    if (lower.endsWith(".woff2"))
+        return "font/woff2";
+    return "application/octet-stream";
+}
+async function readJsonBody(req, maxBytes = 10 * 1024 * 1024) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes) {
+            throw new Error(`request body exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(buf);
+    }
+    if (chunks.length === 0)
+        return {};
+    const raw = Buffer.concat(chunks).toString("utf8");
+    if (!raw.trim())
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`invalid JSON body: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function handleHealth(_req, res, ctx) {
+    let fingerprint;
+    try {
+        fingerprint = repoFingerprintV1(ctx.repoRoot);
+    }
+    catch {
+        fingerprint = "unavailable";
+    }
+    const readiness = ctx.operator?.getReadiness();
+    sendJson(res, 200, {
+        ok: true,
+        product: "loop-operator-console",
+        productName: "Loop Operator Console",
+        repoRoot: ctx.repoRoot,
+        repoFingerprint: fingerprint,
+        piReadiness: readiness?.state ?? "setup-required",
+        generatedAt: new Date().toISOString(),
+    });
+}
+async function handleReadiness(_req, res, ctx) {
+    const report = ctx.operator?.getReadiness();
+    if (!report) {
+        sendJson(res, 200, {
+            state: "setup-required",
+            message: "operator runtime not configured",
+        });
+        return;
+    }
+    sendJson(res, 200, report);
+}
+async function handleSessionPing(req, res, ctx) {
+    const failure = evaluateMutationGate(req, {
+        bootToken: ctx.bootToken.value,
+        confirmationToken: ctx.bootToken.confirmationToken,
+        consoleOrigin: ctx.getConsoleOrigin(),
+    });
+    if (failure) {
+        sendJson(res, failure.status, {
+            ok: false,
+            error: { code: failure.code, message: failure.message },
+        });
+        return;
+    }
+    sendJson(res, 200, { ok: true, pong: true });
+}
+async function handleCreateOperation(req, res, ctx) {
+    if (!ctx.operator) {
+        sendJson(res, 503, {
+            ok: false,
+            error: {
+                code: "INTERNAL_ERROR",
+                message: "operator runtime unavailable",
+            },
+        });
+        return;
+    }
+    const failure = evaluateMutationGate(req, {
+        bootToken: ctx.bootToken.value,
+        confirmationToken: ctx.bootToken.confirmationToken,
+        consoleOrigin: ctx.getConsoleOrigin(),
+    });
+    if (failure) {
+        sendJson(res, failure.status, {
+            ok: false,
+            error: { code: failure.code, message: failure.message },
+        });
+        return;
+    }
+    let body;
+    try {
+        body = (await readJsonBody(req));
+    }
+    catch (error) {
+        sendJson(res, 400, {
+            ok: false,
+            error: {
+                code: "INVALID_INPUT",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return;
+    }
+    const action = typeof body.action === "string" ? body.action : "";
+    const actionParams = body.actionParams && typeof body.actionParams === "object"
+        ? body.actionParams
+        : {};
+    const clientRequestId = typeof body.clientRequestId === "string" ? body.clientRequestId : undefined;
+    const result = await dispatchOperatorAction(ctx.operator.actionContext, {
+        action,
+        actionParams,
+        clientRequestId,
+    });
+    sendJson(res, result.status, result.body);
+}
+async function handleGetOperation(_req, res, ctx, operationId) {
+    if (!ctx.operator) {
+        sendJson(res, 503, {
+            ok: false,
+            error: {
+                code: "INTERNAL_ERROR",
+                message: "operator runtime unavailable",
+            },
+        });
+        return;
+    }
+    const op = await ctx.operator.operations.get(operationId);
+    if (!op) {
+        sendJson(res, 404, {
+            ok: false,
+            error: {
+                code: "NOT_FOUND",
+                message: `operation not found: ${operationId}`,
+            },
+        });
+        return;
+    }
+    sendJson(res, 200, { ok: true, operation: op });
+}
+async function handleOperationEvents(req, res, ctx, operationId) {
+    if (!ctx.operator) {
+        sendJson(res, 503, {
+            ok: false,
+            error: {
+                code: "INTERNAL_ERROR",
+                message: "operator runtime unavailable",
+            },
+        });
+        return;
+    }
+    const op = await ctx.operator.operations.get(operationId);
+    if (!op) {
+        sendJson(res, 404, {
+            ok: false,
+            error: {
+                code: "NOT_FOUND",
+                message: `operation not found: ${operationId}`,
+            },
+        });
+        return;
+    }
+    const lastEventId = parseLastEventId(typeof req.headers["last-event-id"] === "string"
+        ? req.headers["last-event-id"]
+        : undefined);
+    const listed = ctx.operator.events.listFrom(operationId, lastEventId);
+    if ("error" in listed) {
+        sendJson(res, 410, {
+            ok: false,
+            error: {
+                code: "EVENT_CURSOR_EXPIRED",
+                message: "event cursor expired; re-read operation snapshot",
+            },
+        });
+        return;
+    }
+    openSseResponse(res);
+    for (const event of listed.events) {
+        writeSseEvent(res, event);
+    }
+    // Keep connection briefly for live events; poll store
+    let closed = false;
+    req.on("close", () => {
+        closed = true;
+    });
+    const started = Date.now();
+    const maxMs = 30_000;
+    let cursor = listed.events.length > 0
+        ? listed.events[listed.events.length - 1].seq
+        : lastEventId;
+    while (!closed && Date.now() - started < maxMs) {
+        await new Promise((r) => setTimeout(r, 200));
+        const more = ctx.operator.events.listFrom(operationId, cursor);
+        if ("error" in more) {
+            res.write(`event: error\ndata: ${JSON.stringify({ code: "EVENT_CURSOR_EXPIRED" })}\n\n`);
+            break;
+        }
+        for (const event of more.events) {
+            writeSseEvent(res, event);
+            cursor = event.seq;
+        }
+        const current = await ctx.operator.operations.get(operationId);
+        if (current &&
+            (current.state === "succeeded" ||
+                current.state === "failed" ||
+                current.state === "timed-out" ||
+                current.state === "needs-reconcile")) {
+            // flush any final events then end
+            const final = ctx.operator.events.listFrom(operationId, cursor);
+            if (!("error" in final)) {
+                for (const event of final.events) {
+                    writeSseEvent(res, event);
+                }
+            }
+            break;
+        }
+    }
+    res.end();
+}
+/**
+ * Path-escape-safe static file serve for Console SPA.
+ * Sets boot capability cookie on HTML responses.
+ */
+export async function serveConsoleStatic(req, res, ctx) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    let pathname = decodeURIComponent(url.pathname);
+    if (pathname === "/") {
+        pathname = "/index.html";
+    }
+    const filePath = path.join(ctx.staticDir, pathname);
+    const resolvedStatic = path.resolve(ctx.staticDir);
+    const resolvedFile = path.resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedStatic + path.sep) &&
+        resolvedFile !== resolvedStatic) {
+        sendJson(res, 404, { error: "Not found" });
+        return;
+    }
+    if (!existsSync(resolvedFile)) {
+        // SPA fallback for non-file routes
+        const indexPath = path.join(resolvedStatic, "index.html");
+        if (existsSync(indexPath) && !pathname.includes(".")) {
+            const html = injectConfirmationTokenScript(await readFile(indexPath), ctx.bootToken.confirmationToken);
+            res.writeHead(200, {
+                "Content-Type": "text/html; charset=utf-8",
+                "Content-Length": html.byteLength,
+                "Set-Cookie": ctx.bootToken.setCookieHeader,
+            });
+            res.end(html);
+            return;
+        }
+        sendJson(res, 404, { error: "Not found" });
+        return;
+    }
+    const raw = await readFile(resolvedFile);
+    const contentType = contentTypeFor(pathname);
+    const content = contentType.startsWith("text/html")
+        ? injectConfirmationTokenScript(raw, ctx.bootToken.confirmationToken)
+        : raw;
+    const headers = {
+        "Content-Type": contentType,
+        "Content-Length": content.byteLength,
+    };
+    if (contentType.startsWith("text/html")) {
+        headers["Set-Cookie"] = ctx.bootToken.setCookieHeader;
+    }
+    res.writeHead(200, headers);
+    res.end(content);
+}
+export async function handleConsoleRequest(req, res, ctx) {
+    const method = (req.method ?? "GET").toUpperCase();
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const pathname = decodeURIComponent(url.pathname);
+    if (method === "GET" && pathname === "/api/health") {
+        await handleHealth(req, res, ctx);
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/operator/v1/readiness") {
+        await handleReadiness(req, res, ctx);
+        return true;
+    }
+    // Phase 1 mutation stub for security tests
+    if (method === "POST" && pathname === "/api/session/ping") {
+        await handleSessionPing(req, res, ctx);
+        return true;
+    }
+    if (method === "POST" && pathname === "/api/operator/v1/operations") {
+        await handleCreateOperation(req, res, ctx);
+        return true;
+    }
+    const opMatch = pathname.match(/^\/api\/operator\/v1\/operations\/([^/]+)(?:\/(events))?$/);
+    if (opMatch) {
+        const operationId = decodeURIComponent(opMatch[1]);
+        if (method === "GET" && opMatch[2] === "events") {
+            await handleOperationEvents(req, res, ctx, operationId);
+            return true;
+        }
+        if (method === "GET") {
+            await handleGetOperation(req, res, ctx, operationId);
+            return true;
+        }
+    }
+    if (isMutationMethod(method)) {
+        const failure = evaluateMutationGate(req, {
+            bootToken: ctx.bootToken.value,
+            confirmationToken: ctx.bootToken.confirmationToken,
+            consoleOrigin: ctx.getConsoleOrigin(),
+        });
+        if (failure) {
+            sendJson(res, failure.status, {
+                ok: false,
+                error: { code: failure.code, message: failure.message },
+            });
+            return true;
+        }
+        // Allow other operator POSTs only under known routes; unknown → 404
+        sendJson(res, 404, {
+            ok: false,
+            error: {
+                code: "NOT_FOUND",
+                message: `unknown mutation route: ${pathname}`,
+            },
+        });
+        return true;
+    }
+    if (pathname.startsWith("/api/")) {
+        sendJson(res, 404, { error: "Not found" });
+        return true;
+    }
+    return false;
+}

package/dist/worker/console/security.js

@@ -0,0 +1,126 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { isLoopbackHost } from "./loopback.js";
+export const BOOT_CAPABILITY_COOKIE = "loop_console_capability";
+/** Custom mutation confirmation header (design §9). JS-readable; not the HttpOnly boot cookie. */
+export const CONFIRMATION_TOKEN_HEADER = "x-loop-console-confirmation";
+/** Issue per-process unguessable boot capability + confirmation tokens. */
+export function issueBootCapabilityToken() {
+    const value = randomBytes(32).toString("base64url");
+    const confirmationToken = randomBytes(32).toString("base64url");
+    const setCookieHeader = [
+        `${BOOT_CAPABILITY_COOKIE}=${value}`,
+        "HttpOnly",
+        "SameSite=Strict",
+        "Path=/",
+    ].join("; ");
+    return { value, setCookieHeader, confirmationToken };
+}
+/** Inject confirmation token into HTML so the SPA can send the mutation header. */
+export function injectConfirmationTokenScript(html, confirmationToken) {
+    const source = typeof html === "string" ? html : html.toString("utf8");
+    const script = `<script>window.__CONSOLE_CONFIRMATION_TOKEN__=${JSON.stringify(confirmationToken)};</script>`;
+    if (source.includes("</head>")) {
+        return Buffer.from(source.replace("</head>", `${script}</head>`), "utf8");
+    }
+    if (source.includes("</body>")) {
+        return Buffer.from(source.replace("</body>", `${script}</body>`), "utf8");
+    }
+    return Buffer.from(`${source}\n${script}`, "utf8");
+}
+export function parseCookieHeader(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(";")) {
+        const trimmed = part.trim();
+        const eq = trimmed.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        if (key === name) {
+            return trimmed.slice(eq + 1).trim();
+        }
+    }
+    return undefined;
+}
+function safeEqualToken(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+/**
+ * Minimum mutation challenge (design §9):
+ * cookie boot token AND custom confirmation header/token + Host loopback +
+ * Origin matches Console + Sec-Fetch-Site not cross-site.
+ */
+export function evaluateMutationGate(req, ctx) {
+    const cookieToken = parseCookieHeader(req.headers.cookie, BOOT_CAPABILITY_COOKIE);
+    if (!cookieToken) {
+        return {
+            status: 403,
+            code: "missing-capability-token",
+            message: "mutation requires boot capability cookie",
+        };
+    }
+    if (!safeEqualToken(cookieToken, ctx.bootToken)) {
+        return {
+            status: 403,
+            code: "invalid-capability-token",
+            message: "invalid boot capability token",
+        };
+    }
+    const headerRaw = req.headers[CONFIRMATION_TOKEN_HEADER];
+    const confirmationHeader = typeof headerRaw === "string"
+        ? headerRaw.trim()
+        : Array.isArray(headerRaw)
+            ? (headerRaw[0] ?? "").trim()
+            : "";
+    if (!confirmationHeader) {
+        return {
+            status: 403,
+            code: "missing-confirmation-token",
+            message: "mutation requires confirmation header token",
+        };
+    }
+    if (!safeEqualToken(confirmationHeader, ctx.confirmationToken)) {
+        return {
+            status: 403,
+            code: "invalid-confirmation-token",
+            message: "invalid confirmation header token",
+        };
+    }
+    const hostHeader = req.headers.host ?? "";
+    const hostOnly = hostHeader.split(":")[0] ?? "";
+    if (!isLoopbackHost(hostOnly)) {
+        return {
+            status: 403,
+            code: "host-not-loopback",
+            message: `Host is not loopback: ${hostHeader}`,
+        };
+    }
+    const origin = req.headers.origin;
+    if (typeof origin !== "string" ||
+        origin.length === 0 ||
+        origin !== ctx.consoleOrigin) {
+        return {
+            status: 403,
+            code: "origin-mismatch",
+            message: "Origin does not match Console origin",
+        };
+    }
+    const secFetchSite = req.headers["sec-fetch-site"];
+    if (typeof secFetchSite === "string" &&
+        secFetchSite.toLowerCase() === "cross-site") {
+        return {
+            status: 403,
+            code: "cross-site-fetch",
+            message: "Sec-Fetch-Site cross-site is not allowed for mutations",
+        };
+    }
+    return undefined;
+}
+export function isMutationMethod(method) {
+    const m = (method ?? "GET").toUpperCase();
+    return m === "POST" || m === "PUT" || m === "PATCH" || m === "DELETE";
+}

package/dist/worker/console/server.js

@@ -0,0 +1,149 @@
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { LoopAgentClient } from "../loop-agent/loop-agent-client.js";
+import { openConsoleAppData } from "./app-data.js";
+import { DagConfirmationStore } from "./dag-confirmation.js";
+import { DraftStore } from "./draft-store.js";
+import { AssessmentStore } from "./interview/assessment.js";
+import { InterviewSessionStore } from "./interview/session.js";
+import { isLoopbackHost } from "./loopback.js";
+import { createOperationEventStore, } from "./operation-sse.js";
+import { OperationStore } from "./operation-store.js";
+import { probePiReadiness, } from "./pi-readiness.js";
+import { handleConsoleRequest, serveConsoleStatic, } from "./routes.js";
+import { issueBootCapabilityToken } from "./security.js";
+import { resolveSiblingLoopAgentBin } from "./sibling-controller.js";
+/** Built static assets live next to the compiled server under dist/worker/console/static. */
+export function defaultConsoleStaticDir(fromFileUrl = import.meta.url) {
+    return path.join(path.dirname(fileURLToPath(fromFileUrl)), "static");
+}
+/**
+ * Create Loop Operator Console HTTP server.
+ * Non-loopback host throws before listen (fail closed).
+ */
+export async function createConsoleServer(options) {
+    const host = options.host ?? "127.0.0.1";
+    if (!isLoopbackHost(host)) {
+        throw new Error(`console serve: non-loopback host "${host}" is not allowed (fail closed; use 127.0.0.1 or localhost)`);
+    }
+    const repoRoot = path.resolve(options.repoRoot);
+    const port = options.port ?? 8790;
+    const staticDir = options.staticDir ?? defaultConsoleStaticDir();
+    const bootToken = issueBootCapabilityToken();
+    const operatorSessionId = `sess_${randomBytes(16).toString("hex")}`;
+    const appData = openConsoleAppData({
+        repoRoot,
+        appDataRoot: options.appDataRoot,
+    });
+    const operations = new OperationStore(appData);
+    const events = createOperationEventStore({
+        persistenceDir: path.join(appData.operations, "events"),
+    });
+    const drafts = new DraftStore(appData);
+    const confirmations = new DagConfirmationStore(appData);
+    const interviews = new InterviewSessionStore(appData);
+    const assessments = new AssessmentStore(appData);
+    const readiness = await probePiReadiness({
+        override: options.piReadinessProbe,
+    });
+    const artifactRoot = path.join(appData.root, "client-artifacts", appData.fingerprint);
+    const client = options.createClient?.(artifactRoot) ??
+        new LoopAgentClient({
+            loopAgentBin: resolveSiblingLoopAgentBin(),
+            artifactRoot,
+            resolveIdentity: true,
+        });
+    if (!options.skipReconcile) {
+        await operations.reconcileOnBoot();
+    }
+    const getReadiness = () => readiness;
+    const actionContext = {
+        repoRoot,
+        appData,
+        operatorSessionId,
+        client,
+        operations,
+        events,
+        drafts,
+        confirmations,
+        interviews,
+        assessments,
+        readiness,
+        getReadiness,
+        observeBaseUrl: options.observeBaseUrl,
+        fetchImpl: options.fetchImpl,
+    };
+    let boundHost = host;
+    let boundPort = port;
+    const getConsoleOrigin = () => `http://${boundHost}:${boundPort}`;
+    const routeContext = {
+        repoRoot,
+        staticDir,
+        bootToken,
+        getConsoleOrigin,
+        operator: {
+            actionContext,
+            operations,
+            events,
+            getReadiness,
+        },
+    };
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            void dispatch(req, res).catch((error) => {
+                if (!res.headersSent) {
+                    const payload = JSON.stringify({
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    res.writeHead(500, {
+                        "Content-Type": "application/json",
+                        "Content-Length": Buffer.byteLength(payload),
+                    });
+                    res.end(payload);
+                }
+            });
+        });
+        async function dispatch(req, res) {
+            // Refresh readiness pointer on each request surface
+            actionContext.readiness = getReadiness();
+            const handled = await handleConsoleRequest(req, res, routeContext);
+            if (!handled) {
+                await serveConsoleStatic(req, res, routeContext);
+            }
+        }
+        server.on("error", reject);
+        server.listen(port, host, () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                reject(new Error("Failed to get console server address"));
+                return;
+            }
+            boundHost = host;
+            boundPort = addr.port;
+            const url = `http://${host}:${addr.port}`;
+            process.stderr.write(`[console] Loop Operator Console listening on ${url} (loopback only)\n`);
+            resolve({
+                url,
+                host,
+                port: addr.port,
+                appData,
+                operations,
+                events,
+                getReadiness,
+                operatorSessionId,
+                close: () => new Promise((closeResolve, closeReject) => {
+                    server.close((err) => (err ? closeReject(err) : closeResolve()));
+                }),
+            });
+        });
+    });
+}
+/** Test helper: replace readiness report in-process. */
+export function setConsoleReadinessForTests(server, report) {
+    if (!server.getReadiness)
+        return;
+    // Mutate via closure replacement is not available; tests should inject probe at create.
+    void report;
+}

package/dist/worker/console/sibling-controller.js

@@ -0,0 +1,28 @@
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findPackageRoot } from "../../shared/package-metadata.js";
+/**
+ * Resolve the absolute sibling `bin/loop-agent.js` for this package install.
+ * Never selects a controller via PATH.
+ */
+export function resolveSiblingLoopAgentBin(fromFileUrl = import.meta.url) {
+    const startDir = path.dirname(fileURLToPath(fromFileUrl));
+    const packageRoot = findPackageRoot(startDir);
+    if (!packageRoot) {
+        throw new Error("console sibling controller: cannot locate package root from console module");
+    }
+    const candidate = path.join(packageRoot, "bin", "loop-agent.js");
+    if (!existsSync(candidate)) {
+        throw new Error(`console sibling controller: missing sibling bin at ${candidate}`);
+    }
+    return realpathSync(candidate);
+}
+export function resolvePackageRootFromConsole(fromFileUrl = import.meta.url) {
+    const startDir = path.dirname(fileURLToPath(fromFileUrl));
+    const packageRoot = findPackageRoot(startDir);
+    if (!packageRoot) {
+        throw new Error("console: cannot locate package root");
+    }
+    return packageRoot;
+}