@dyx9/rosetta 0.0.0-stage → 0.0.1

package/build/server/http/routes.js

@@ -0,0 +1,231 @@
+import { existsSync } from "node:fs";
+import sirv from "sirv";
+import { SESSION_NOT_FOUND } from "../agent/sessions.js";
+import { validTurnId } from "../agent/turn.js";
+import { isAdmin, isUser } from "./auth.js";
+import { handleChat } from "./chat.js";
+import { handleFeedback } from "./feedback.js";
+import { bodyOr400, json } from "./util.js";
+/** Every API route, by method and path. */
+const ROUTES = new Map([
+    ["GET /api/privacy", { access: "public", handle: privacy }],
+    ["GET /api/health", { access: "public", handle: health }],
+    ["GET /api/admin/status", { access: "admin", handle: adminStatus }],
+    ["GET /api/admin/questions", { access: "admin", handle: adminQuestions }],
+    ["POST /api/session", { access: "user", handle: createSession }],
+    ["DELETE /api/session", { access: "user", handle: closeSession }],
+    ["POST /api/heartbeat", { access: "user", handle: heartbeat }],
+    ["POST /api/abort", { access: "user", handle: stopTurn }],
+    ["POST /api/feedback", { access: "user", handle: feedback }],
+    ["POST /api/chat", { access: "user", handle: chat }],
+]);
+export function createRequestHandler(context) {
+    const { tokens, operations } = context;
+    const assets = createAssetHandler(context.clientDir);
+    const handleRequest = async (req, res) => {
+        res.setHeader("Referrer-Policy", "no-referrer");
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        res.setHeader("X-Frame-Options", "DENY");
+        // Only the path and query are used, so the client's Host header is not trusted to parse.
+        let url;
+        try {
+            url = new URL(req.url || "/", "http://localhost");
+        }
+        catch {
+            return json(res, 400, { error: "Bad request" });
+        }
+        if (!url.pathname.startsWith("/api/")) {
+            const notFound = () => json(res, 404, { error: "Not found" });
+            return assets ? assets(req, res, notFound) : notFound();
+        }
+        const route = ROUTES.get(`${req.method || "GET"} ${url.pathname}`);
+        // A path that is not a route is gated like the area it is in, so a caller
+        // without the code cannot find out which routes exist.
+        const access = route?.access ??
+            (url.pathname.startsWith("/api/admin/") ? "admin" : "user");
+        if (!mayCall(access, req, tokens))
+            return json(res, 401, { error: "Unauthorized" });
+        if (!route)
+            return json(res, 404, { error: "Not found" });
+        return route.handle(context, req, res, url);
+    };
+    /**
+     * Node does not catch a rejection from an async request handler: it becomes an
+     * unhandled rejection, which exits the process — and since every session runs in this
+     * one process, that takes every other session down too, along with conversations that
+     * exist nowhere else.
+     *
+     * Each route handles the failures it expects. This is the net under the ones it
+     * does not, so an unforeseen error costs one request rather than the server.
+     */
+    return (req, res) => {
+        void handleRequest(req, res).catch((error) => {
+            // A stack is what an admin needs here: unlike a bad stone, this is a bug
+            // rather than something they can fix by editing a file.
+            operations.reportError("request", "Unexpected request failure. See the server log for details.");
+            console.error(`Unhandled error in ${req.method} ${req.url}:`, error);
+            // Once the body has started there is no status left to send. Destroying the
+            // socket surfaces it as a dropped connection, which the client already
+            // reports; ending cleanly would truncate the answer and say nothing.
+            if (res.headersSent)
+                res.destroy();
+            else
+                json(res, 500, {
+                    error: "Rosetta hit an unexpected error. Check the server log.",
+                });
+        });
+    };
+}
+function mayCall(access, req, tokens) {
+    if (access === "public")
+        return true;
+    return access === "admin" ? isAdmin(req, tokens) : isUser(req, tokens);
+}
+function privacy({ config, recordings, harness }, _req, res) {
+    res.setHeader("Cache-Control", "no-store");
+    const body = {
+        ...config.privacy,
+        recording: recordings.enabled,
+        retentionDays: config.recordings.retentionDays,
+        model: harness.model,
+    };
+    json(res, 200, body);
+}
+function health({ harness, sessions }, _req, res) {
+    json(res, 200, {
+        ok: true,
+        stone: harness.stone.languageName,
+        sessions: sessions.size,
+    });
+}
+function adminStatus({ config, harness, sessions, operations, recordings }, _req, res) {
+    // Sessions past their limit are ended first, so the page never lists one.
+    sessions.sweep();
+    const body = {
+        stone: summariseStone(harness),
+        model: harness.model,
+        tools: harness.tools,
+        sessions: sessions.size,
+        maxSessions: config.maxSessions,
+        operations: { ...operations.totals, ...sessions.summary },
+        questionLog: {
+            enabled: recordings.enabled,
+            path: recordings.path ?? null,
+            ...recordings.health,
+        },
+    };
+    json(res, 200, body);
+}
+function adminQuestions({ recordings }, _req, res, url) {
+    const limit = Math.min(Number.parseInt(url.searchParams.get("limit") ?? "100", 10) || 100, 500);
+    const body = {
+        enabled: recordings.enabled,
+        path: recordings.path ?? null,
+        entries: recordings.recentQuestions(limit),
+    };
+    json(res, 200, body);
+}
+async function createSession({ config, harness, sessions, recordings }, _req, res) {
+    const session = await sessions.create();
+    if (!session) {
+        return json(res, 503, {
+            error: "Rosetta is at its session limit. Try again shortly.",
+        });
+    }
+    const { stone } = harness;
+    const info = {
+        sessionId: session.id,
+        title: stone.agentName,
+        welcome: stone.welcomeMessage,
+        suggestions: stone.suggestedQuestions,
+        language: stone.syntaxHighlighting,
+        recording: recordings.enabled,
+        turnTimeoutMs: config.turnLimits.timeoutMs,
+        abortGraceMs: config.turnLimits.abortGraceMs,
+    };
+    json(res, 201, info);
+}
+function closeSession({ sessions }, req, res) {
+    sessions.destroy(sessionIdOf(req));
+    json(res, 200, { ok: true });
+}
+function heartbeat({ sessions }, req, res) {
+    const session = sessions.find(sessionIdOf(req));
+    if (!session)
+        return json(res, 404, { error: SESSION_NOT_FOUND });
+    json(res, 200, {
+        ok: true,
+        inactivityRemainingMs: session.inactivityRemainingMs(),
+    });
+}
+async function stopTurn({ sessions }, req, res) {
+    const sessionId = sessionIdOf(req);
+    if (!sessions.find(sessionId))
+        return json(res, 404, { error: SESSION_NOT_FOUND });
+    const body = await bodyOr400(req, res);
+    if (!body)
+        return;
+    if (!validTurnId(body.turnId))
+        return json(res, 400, { error: "A valid turnId is required" });
+    json(res, 200, { ok: true, stopped: sessions.stop(sessionId, body.turnId) });
+}
+function feedback({ sessions, recordings }, req, res) {
+    return handleFeedback(req, res, sessionIdOf(req), sessions, recordings.enabled);
+}
+function chat({ conversations }, req, res) {
+    return handleChat(req, res, sessionIdOf(req), conversations);
+}
+/** The session a request is for. The header is absent on the first request of a conversation. */
+function sessionIdOf(req) {
+    return req.headers["x-rosetta-session"] ?? "";
+}
+/**
+ * The stone as the admin page shows it, typed against the shared StoneSummary
+ * so a manifest rename is a compile error rather than a blank field on the page.
+ */
+function summariseStone(harness) {
+    const { stone } = harness;
+    return {
+        agentName: stone.agentName,
+        languageName: stone.languageName,
+        path: stone.path,
+        context: stone.context.map((file) => file.path),
+        skills: harness.skills,
+        checks: harness.checks,
+        warnings: stone.warnings,
+    };
+}
+/**
+ * Serves the built client. In development Vite serves it and proxies /api here,
+ * so dist/ may legitimately not exist yet.
+ *
+ * sirv rather than a hand-rolled reader: it gets content types, conditional
+ * requests and — the reason it matters — containment right. A prefix check like
+ * `join(dist, req).startsWith(dist)` passes for a sibling directory named
+ * `dist-backup`, which is a real escape.
+ */
+function createAssetHandler(clientDir) {
+    if (!existsSync(clientDir))
+        return undefined;
+    return sirv(clientDir, {
+        // /admin is a client-side route with no file behind it.
+        single: true,
+        // sirv precomputes its file index at startup unless told otherwise, so a
+        // rebuild while the server runs would 404 the new hashed assets. At this
+        // scale a stat per request costs nothing and removes the footgun.
+        dev: true,
+        etag: true,
+        // dev mode revalidates everything and ignores sirv's own cache options,
+        // so the two cases that matter are set here.
+        setHeaders(res, pathname) {
+            // The entry document must never be cached, or a redeploy is invisible.
+            if (pathname === "/" || pathname.endsWith("/index.html")) {
+                res.setHeader("Cache-Control", "no-store");
+            }
+            else if (/^\/assets\/.+\.\w+$/.test(pathname)) {
+                // Vite names these by content hash, so a given URL never changes.
+                res.setHeader("Cache-Control", "public,max-age=31536000,immutable");
+            }
+        },
+    });
+}

package/build/server/http/stream.js

@@ -0,0 +1,39 @@
+/** Well under the idle limits of common proxies, such as nginx's 60-second default. */
+const KEEP_ALIVE_MS = 15_000;
+/**
+ * Writes RosettaEvents as NDJSON on an open response.
+ */
+export function openStream(res) {
+    res.writeHead(200, {
+        "Content-Type": "application/x-ndjson; charset=utf-8",
+        "Cache-Control": "no-store, no-transform",
+        // Stops reverse proxies buffering the stream into one delayed blob.
+        "X-Accel-Buffering": "no",
+    });
+    let closed = false;
+    // A reverse proxy may drop a response that stays silent while the model thinks or a
+    // checker runs. A blank line keeps it open; NDJSON readers skip blank lines.
+    const keepAlive = setInterval(() => {
+        if (res.destroyed)
+            clearInterval(keepAlive);
+        else
+            res.write("\n");
+    }, KEEP_ALIVE_MS);
+    keepAlive.unref();
+    return {
+        send(event) {
+            if (closed || res.destroyed)
+                return;
+            res.write(`${JSON.stringify(event)}\n`);
+        },
+        close(final) {
+            if (closed)
+                return;
+            clearInterval(keepAlive);
+            if (final && !res.destroyed)
+                res.write(`${JSON.stringify(final)}\n`);
+            closed = true;
+            res.end();
+        },
+    };
+}

package/build/server/http/util.js

@@ -0,0 +1,40 @@
+/**
+ * Small HTTP helpers with no domain knowledge.
+ *
+ * Nothing here should know what a stone or a session is; anything that does
+ * belongs in the file named for it.
+ */
+/** A request body larger than this is refused rather than buffered. */
+const MAX_BODY_BYTES = 64 * 1024;
+export function json(res, status, body) {
+    res.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+    });
+    res.end(JSON.stringify(body));
+}
+export async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error("Request body is too large");
+        chunks.push(chunk);
+    }
+    const text = Buffer.concat(chunks).toString("utf8");
+    const body = text ? JSON.parse(text) : {};
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        throw new Error("Request body must be a JSON object");
+    return body;
+}
+/** The JSON body, or undefined once a 400 has been sent for one that cannot be read. */
+export async function bodyOr400(req, res) {
+    try {
+        return await readBody(req);
+    }
+    catch (error) {
+        json(res, 400, { error: error.message });
+        return undefined;
+    }
+}

package/build/server/index.js

@@ -0,0 +1,112 @@
+import { readFileSync } from "node:fs";
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { networkInterfaces } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Conversations } from "./agent/conversation.js";
+import { createHarness } from "./agent/harness.js";
+import { SessionRegistry } from "./agent/sessions.js";
+import { ConfigError, loadConfig } from "./config.js";
+import { createTokens } from "./http/auth.js";
+import { createRequestHandler } from "./http/routes.js";
+import { Operations } from "./records/operations.js";
+import { Recordings } from "./records/recording.js";
+import { assertRecordingsOutsideStone } from "./stone/file-boundary.js";
+import { loadStone, StoneError } from "./stone/stone.js";
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+/** Configuration problems are the admin's to fix, so report them without a stack trace. */
+async function boot() {
+    try {
+        const config = loadConfig(process.env, root, process.argv.slice(2));
+        const tokens = createTokens();
+        const tls = config.tls && {
+            cert: readFileSync(config.tls.certPath),
+            key: readFileSync(config.tls.keyPath),
+        };
+        const stone = await loadStone(config.stonePath);
+        await assertRecordingsOutsideStone(stone.path, config.recordings.directory);
+        const harness = await createHarness(stone, config.model);
+        return { config, tokens, tls, harness };
+    }
+    catch (error) {
+        const problems = error instanceof StoneError || error instanceof ConfigError
+            ? error.problems
+            : [error.message];
+        console.error("\nRosetta could not start.\n");
+        for (const problem of problems)
+            console.error(`  ${problem}`);
+        console.error("");
+        process.exit(1);
+    }
+}
+const { config, tokens, tls, harness } = await boot();
+const operations = new Operations();
+const recordings = new Recordings(config.recordings);
+const sessions = new SessionRegistry(harness, {
+    maxSessions: config.maxSessions,
+    inactivityMs: config.inactivityMs,
+    reportError: (source, message) => operations.reportError(source, message),
+}, recordings);
+const conversations = new Conversations(sessions, recordings, operations, config.turnLimits);
+const handler = createRequestHandler({
+    config,
+    tokens,
+    harness,
+    recordings,
+    sessions,
+    conversations,
+    operations,
+    clientDir: join(root, "dist"),
+});
+const server = tls
+    ? createHttpsServer(tls, handler)
+    : createHttpServer(handler);
+server.listen(config.port, config.host, printBanner);
+/** What is running and how to reach it. The access codes are shown nowhere else. */
+function printBanner() {
+    const urls = lanUrls(config.host, config.port, tls ? "https" : "http");
+    const current = harness.stone;
+    console.log(`\nRosetta — ${current.agentName}`);
+    console.log(`Stone:   ${current.path}`);
+    console.log(`Context: ${current.context.map((file) => file.path).join(", ") || "(none)"}`);
+    console.log(`Skills:  ${harness.skills.join(", ") || "(none)"}`);
+    console.log(`Checks:  ${harness.checks.join(" → ") || "(none)"}`);
+    console.log(`Model:   ${harness.model}`);
+    console.log(`Tools:   ${harness.tools.join(", ")}`);
+    console.log(`Session recordings: ${recordings.enabled ? recordings.path : "disabled"}`);
+    for (const warning of current.warnings)
+        console.log(`Warning: ${warning}`);
+    console.log(`Open:    ${urls.join(" or ")}`);
+    console.log(`Token:   ${tokens.user ?? "not required (public access)"}`);
+    console.log(`Admin:   ${tokens.admin}\n`);
+}
+/** Addresses this server can be reached on. */
+function lanUrls(host, port, scheme = "http") {
+    if (host !== "0.0.0.0" && host !== "::")
+        return [`${scheme}://${host}:${port}`];
+    const urls = [];
+    for (const addresses of Object.values(networkInterfaces())) {
+        for (const address of addresses ?? []) {
+            if (address.family === "IPv4" && !address.internal) {
+                urls.push(`${scheme}://${address.address}:${port}`);
+            }
+        }
+    }
+    return urls.length ? urls : [`${scheme}://localhost:${port}`];
+}
+let shuttingDown = false;
+async function shutdown() {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    server.close();
+    const forceClose = setTimeout(() => server.closeAllConnections(), config.turnLimits.abortGraceMs + 1000);
+    forceClose.unref();
+    await sessions.shutdown();
+    await recordings.close();
+    server.closeAllConnections();
+    clearTimeout(forceClose);
+}
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);

package/build/server/records/operations.js

@@ -0,0 +1,53 @@
+import { addTokenUsage } from "./turn-recording.js";
+/**
+ * Process-local outcome, usage, cost, and error totals for admin. Kept whether or
+ * not conversations are recorded; nothing here contains credentials or conversation text.
+ */
+export class Operations {
+    #startedAt = new Date().toISOString();
+    #started = performance.now();
+    #outcomes = { completed: 0, failed: 0, stopped: 0, incomplete: 0 };
+    #tokens = null;
+    #measuredTurns = 0;
+    #estimatedCostUsd = null;
+    #incompleteCostTurns = 0;
+    #incompleteUsageTurns = 0;
+    #errors = [];
+    reportError(source, message) {
+        this.#errors.unshift({
+            at: new Date().toISOString(),
+            source,
+            message: message.slice(0, 500),
+        });
+        this.#errors.length = Math.min(this.#errors.length, 30);
+    }
+    recordTurn(outcome, measurement, error) {
+        this.#outcomes[outcome]++;
+        if (measurement.tokens) {
+            this.#tokens = addTokenUsage(this.#tokens, measurement.tokens);
+            this.#measuredTurns++;
+        }
+        if (measurement.estimatedCostUsd !== null)
+            this.#estimatedCostUsd =
+                (this.#estimatedCostUsd ?? 0) + measurement.estimatedCostUsd;
+        if (!measurement.costComplete)
+            this.#incompleteCostTurns++;
+        if (!measurement.usageComplete)
+            this.#incompleteUsageTurns++;
+        if (outcome === "failed" || outcome === "incomplete")
+            this.reportError("turn", error ?? outcome);
+    }
+    get totals() {
+        return {
+            startedAt: this.#startedAt,
+            uptimeSeconds: Math.floor((performance.now() - this.#started) / 1000),
+            outcomes: { ...this.#outcomes },
+            tokens: this.#tokens ? { ...this.#tokens } : null,
+            estimatedCostUsd: this.#estimatedCostUsd,
+            incompleteCostTurns: this.#incompleteCostTurns,
+            measuredTurns: this.#measuredTurns,
+            incompleteUsageTurns: this.#incompleteUsageTurns,
+            errors: this.#errors.map((error) => ({ ...error })),
+        };
+    }
+}

package/build/server/records/recording.js

@@ -0,0 +1,186 @@
+/** One readable conversation per file. API session credentials never enter the archive. */
+import { mkdir, readdir, rename, stat, unlink, writeFile, } from "node:fs/promises";
+import { join, resolve } from "node:path";
+/**
+ * What the server keeps about conversations while recording is on: a transcript
+ * file per session, and a short in-memory list of recent questions for admin.
+ */
+export class Recordings {
+    path;
+    enabled;
+    #pending = new Set();
+    #active = new Set();
+    #recent = [];
+    #error = null;
+    #failedWrites = 0;
+    #retentionDays;
+    #ready;
+    #timer;
+    constructor(options = {}) {
+        this.path =
+            options.directory === false
+                ? undefined
+                : resolve(options.directory ?? "data/sessions");
+        this.enabled = Boolean(this.path);
+        this.#retentionDays = options.retentionDays ?? 30;
+        if (!Number.isFinite(this.#retentionDays) || this.#retentionDays <= 0)
+            throw new Error("Invalid recording retentionDays");
+        this.#ready = this.path
+            ? mkdir(this.path, { recursive: true, mode: 0o700 })
+                .then(() => this.prune())
+                .catch((error) => this.#fail(error))
+            : Promise.resolve();
+        if (this.enabled) {
+            this.#timer = setInterval(() => {
+                void this.prune().catch((error) => this.#fail(error));
+            }, 3_600_000);
+            this.#timer.unref();
+        }
+    }
+    get health() {
+        return { error: this.#error, failedWrites: this.#failedWrites };
+    }
+    #fail(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message !== this.#error)
+            console.error(`Session recording: ${message}`);
+        this.#error = message;
+        this.#failedWrites++;
+    }
+    /** Starts a session's transcript. Every change is saved as a whole new snapshot of the file. */
+    startSession(metadata) {
+        const startedAt = new Date().toISOString();
+        const basename = startedAt.replace("T", "_").replaceAll(":", "-");
+        const conversation = {
+            startedAt,
+            endedAt: null,
+            endReason: null,
+            model: metadata.model ?? null,
+            stone: metadata.stone ?? null,
+            alwaysInContext: metadata.alwaysInContext ?? [],
+            messages: [],
+        };
+        /** Chosen by the first write. */
+        let filename;
+        /** The newest snapshot not yet written; one write runs at a time. */
+        let latest;
+        let writing = false;
+        let ended = false;
+        const save = () => {
+            if (!this.enabled)
+                return;
+            latest = JSON.stringify(conversation, null, 2) + "\n";
+            if (writing)
+                return; // Keep only the newest pending snapshot while disk catches up.
+            writing = true;
+            const pending = this.#ready
+                .then(async () => {
+                while (latest !== undefined) {
+                    const snapshot = latest;
+                    latest = undefined;
+                    if (filename)
+                        await this.#replaceFile(filename, snapshot);
+                    else
+                        filename = await this.#createFile(basename, snapshot);
+                }
+            })
+                .catch((error) => {
+                latest = undefined;
+                this.#fail(error);
+            })
+                .finally(() => {
+                writing = false;
+                this.#pending.delete(pending);
+                if (latest !== undefined)
+                    save();
+                else if (ended && filename)
+                    this.#active.delete(filename);
+            });
+            this.#pending.add(pending);
+        };
+        save();
+        return {
+            add(message) {
+                if (!ended) {
+                    conversation.messages.push(message);
+                    save();
+                }
+            },
+            save() {
+                if (!ended)
+                    save();
+            },
+            end(reason) {
+                if (ended)
+                    return;
+                conversation.endedAt = new Date().toISOString();
+                conversation.endReason = reason;
+                ended = true;
+                save();
+            },
+        };
+    }
+    /** Creates a session's file under a name no other session has, and returns that name. */
+    async #createFile(basename, snapshot) {
+        // Exclusive creation also handles same-millisecond starts across processes/restarts.
+        for (let suffix = 0;; suffix++) {
+            const candidate = `${basename}${suffix ? `-${suffix + 1}` : ""}.json`;
+            try {
+                await writeFile(join(this.path, candidate), snapshot, {
+                    flag: "wx",
+                    mode: 0o600,
+                });
+                this.#active.add(candidate);
+                return candidate;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+    }
+    /** Replaces a session's file in one step, so a reader never sees half a snapshot. */
+    async #replaceFile(filename, snapshot) {
+        const target = join(this.path, filename);
+        await writeFile(`${target}.tmp`, snapshot, { mode: 0o600 });
+        await rename(`${target}.tmp`, target);
+    }
+    /**
+     * Adds a finished question to the recent list admin sees. The list stays in
+     * memory, holds the last 100, and is not kept at all while recording is off.
+     */
+    logQuestion(entry) {
+        if (!this.enabled)
+            return;
+        this.#recent.push(entry);
+        if (this.#recent.length > 100)
+            this.#recent.shift();
+    }
+    /** The most recent questions, newest first. */
+    recentQuestions(limit) {
+        return this.#recent.slice(-Math.max(1, Math.min(100, limit))).reverse();
+    }
+    async prune() {
+        if (!this.path)
+            return;
+        const cutoff = Date.now() - this.#retentionDays * 86_400_000;
+        for (const name of await readdir(this.path)) {
+            if (!/^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}\.\d{3}Z(?:-\d+)?\.json$/.test(name) ||
+                this.#active.has(name))
+                continue;
+            const file = join(this.path, name);
+            const info = await stat(file);
+            if (info.isFile() && info.mtimeMs < cutoff)
+                await unlink(file);
+        }
+    }
+    async flush() {
+        await this.#ready;
+        while (this.#pending.size)
+            await Promise.all(this.#pending);
+    }
+    async close() {
+        clearInterval(this.#timer);
+        await this.flush();
+    }
+}