@dyx9/rosetta 0.0.0-stage → 0.0.1

package/build/server/agent/sessions.js

@@ -0,0 +1,222 @@
+import { randomBytes } from "node:crypto";
+import { Turn } from "./turn.js";
+import { Recordings } from "../records/recording.js";
+/** One conversation: an agent, its recording, and at most one running turn. */
+export class Session {
+    id = randomBytes(18).toString("hex");
+    /** Process-local label for admin tracking; not a session credential. */
+    number;
+    agent;
+    recording;
+    createdAt = Date.now();
+    /** Any contact, heartbeats included. Shown to admin; it does not delay expiry. */
+    lastSeen = this.createdAt;
+    /** Session creation or last finished turn; heartbeats must not update this. */
+    lastConversationActivity = this.createdAt;
+    /** When the last question was admitted. Shown to admin. */
+    lastUserActivity = null;
+    turns = 0;
+    contextPercent = null;
+    /**
+     * Every admitted turn's recording, by turn ID. It finds the answer a feedback
+     * request refers to and shows which IDs are used. It stays in memory; IDs are
+     * never written to recordings.
+     */
+    turnRecordings = new Map();
+    /** Set when the session has left the registry. It is disposed once no turn holds it. */
+    closing;
+    activeTurn;
+    #inactivityMs;
+    #reportError;
+    constructor(options) {
+        this.number = options.number;
+        this.agent = options.agent;
+        this.recording = options.recording;
+        this.#inactivityMs = options.inactivityMs;
+        this.#reportError = options.reportError;
+    }
+    /** One question at a time per session. */
+    get busy() {
+        return this.activeTurn !== undefined;
+    }
+    /** Time left before the session expires, or null while it is answering. */
+    inactivityRemainingMs(now = Date.now()) {
+        return this.busy
+            ? null
+            : Math.max(0, this.lastConversationActivity + this.#inactivityMs - now);
+    }
+    /** A busy session never expires: its remaining time is null, not zero. */
+    isExpired(now) {
+        return this.inactivityRemainingMs(now) === 0;
+    }
+    /** Takes the session for one turn. Undefined when it is answering or closing. */
+    beginTurn(id) {
+        if (this.busy || this.closing)
+            return undefined;
+        const turn = new Turn(id);
+        this.activeTurn = turn;
+        this.lastUserActivity = Date.now();
+        this.turns++;
+        return turn;
+    }
+    /** Releases the session for its next turn. A stale owner cannot release or alter a newer turn. */
+    endTurn(turn) {
+        if (this.activeTurn === turn) {
+            this.activeTurn = undefined;
+            this.lastSeen = Date.now();
+            this.lastConversationActivity = this.lastSeen;
+        }
+        // A session closed during its turn is disposed once that turn lets go of it.
+        if (!this.activeTurn)
+            this.#dispose();
+        turn.end();
+    }
+    /** Ends the session. A running turn is cancelled, and disposal waits for it to let go. */
+    close(reason) {
+        this.closing = reason;
+        if (this.activeTurn)
+            this.activeTurn.cancel(reason);
+        else
+            this.#dispose();
+    }
+    #dispose() {
+        if (!this.closing)
+            return;
+        this.recording.end(this.closing);
+        try {
+            this.agent.dispose();
+        }
+        catch (error) {
+            this.#reportError?.("cleanup", "Session disposal failed. See the server log.");
+            console.error("Session disposal failed", error);
+        }
+    }
+}
+export const DEFAULT_INACTIVITY_MS = 30 * 60_000;
+/** What every interface tells a caller whose session is unknown, closed, or expired. */
+export const SESSION_NOT_FOUND = "Session not found or expired";
+/** The sessions that are open: how many there may be, and when each one ends. */
+export class SessionRegistry {
+    #sessions = new Map();
+    #timer;
+    #harness;
+    #options;
+    #inactivityMs;
+    #recordings;
+    #pending = 0;
+    #closed = false;
+    #totalSessions = 0;
+    get summary() {
+        const now = Date.now();
+        const current = [...this.#sessions.values()];
+        return {
+            totalSessions: this.#totalSessions,
+            pendingSessions: this.#pending,
+            busySessions: current.filter((session) => session.busy).length,
+            currentSessions: current.map((session) => {
+                const remainingMs = session.inactivityRemainingMs(now);
+                return {
+                    number: session.number,
+                    lastContact: new Date(session.lastSeen).toISOString(),
+                    expiresInSeconds: remainingMs === null ? null : Math.ceil(remainingMs / 1000),
+                    startedAt: new Date(session.createdAt).toISOString(),
+                    lastUserActivity: session.lastUserActivity === null
+                        ? null
+                        : new Date(session.lastUserActivity).toISOString(),
+                    turns: session.turns,
+                    busy: session.busy,
+                    contextPercent: session.contextPercent,
+                };
+            }),
+        };
+    }
+    constructor(harness, options, recordings) {
+        this.#harness = harness;
+        this.#recordings = recordings;
+        this.#options = options;
+        this.#inactivityMs = options.inactivityMs ?? DEFAULT_INACTIVITY_MS;
+        const interval = Math.min(15_000, Math.max(1_000, Math.floor(this.#inactivityMs / 2)));
+        this.#timer = setInterval(() => this.sweep(), interval);
+        this.#timer.unref();
+    }
+    get size() {
+        return this.#sessions.size;
+    }
+    get #atCapacity() {
+        return (this.#closed ||
+            this.#sessions.size + this.#pending >= this.#options.maxSessions);
+    }
+    async create() {
+        if (this.#atCapacity)
+            return undefined;
+        this.#pending++;
+        try {
+            const agent = await this.#harness.create();
+            if (this.#closed) {
+                agent.dispose();
+                return undefined;
+            }
+            const session = new Session({
+                number: this.#totalSessions + 1,
+                agent,
+                recording: this.#recordings.startSession(agent.metadata ?? {}),
+                inactivityMs: this.#inactivityMs,
+                reportError: this.#options.reportError,
+            });
+            this.#sessions.set(session.id, session);
+            this.#totalSessions++;
+            return session;
+        }
+        finally {
+            this.#pending--;
+        }
+    }
+    /**
+     * The open session with this ID, noting the contact. An overdue session is
+     * ended here instead of returned: after the host sleeps, a request can arrive
+     * before the sweep does. Contact does not renew a session; only a turn does.
+     */
+    find(id) {
+        const session = id ? this.#sessions.get(id) : undefined;
+        if (!session)
+            return undefined;
+        const now = Date.now();
+        if (session.isExpired(now)) {
+            this.destroy(session.id, "inactivity_expired");
+            return undefined;
+        }
+        session.lastSeen = now;
+        return session;
+    }
+    destroy(id, reason = "client_closed") {
+        const session = this.#sessions.get(id);
+        if (!session)
+            return false;
+        this.#sessions.delete(id);
+        session.close(reason);
+        return true;
+    }
+    /** Ends every session whose inactivity limit has passed. */
+    sweep() {
+        const now = Date.now();
+        for (const session of this.#sessions.values()) {
+            if (session.isExpired(now))
+                this.destroy(session.id, "inactivity_expired");
+        }
+    }
+    stop(id, turnId, reason = "user_stop") {
+        const session = this.#sessions.get(id);
+        if (!session?.activeTurn || session.activeTurn.id !== turnId)
+            return false;
+        session.activeTurn.cancel(reason);
+        return true;
+    }
+    async shutdown() {
+        this.#closed = true;
+        clearInterval(this.#timer);
+        const running = [...this.#sessions.values()].flatMap((session) => session.activeTurn ? [session.activeTurn.ended] : []);
+        for (const id of [...this.#sessions.keys()])
+            this.destroy(id, "server_shutdown");
+        await Promise.all(running);
+    }
+}

package/build/server/agent/turn.js

@@ -0,0 +1,56 @@
+export class TurnError extends Error {
+    outcome;
+    constructor(outcome, message) {
+        super(message);
+        this.outcome = outcome;
+    }
+}
+export function validTurnId(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(value);
+}
+const STOP_MESSAGES = {
+    timeout: "The response took too long and was stopped. You can try again.",
+    user_stop: "Stopped.",
+    server_shutdown: "The server is restarting. This response is incomplete.",
+};
+/** What a stopped turn reports. Only the user's own Stop counts as stopped; the rest are incomplete. */
+export const stopResult = (reason) => ({
+    outcome: reason === "user_stop" ? "stopped" : "incomplete",
+    message: STOP_MESSAGES[reason] ??
+        "The connection closed before the response finished.",
+});
+/** A session's running turn: which one it is, and the one way to stop it. */
+export class Turn {
+    id;
+    /** Resolves when the turn is cancelled, and never if it completes. */
+    cancelled;
+    /** Resolves once the session has let go of this turn. Shutdown waits for it. */
+    ended;
+    #stopReason;
+    #resolveCancelled;
+    #resolveEnded;
+    constructor(id) {
+        this.id = id;
+        this.cancelled = new Promise((resolve) => {
+            this.#resolveCancelled = resolve;
+        });
+        this.ended = new Promise((resolve) => {
+            this.#resolveEnded = resolve;
+        });
+    }
+    /** Why the turn was cancelled, or undefined while it has not been. */
+    get stopReason() {
+        return this.#stopReason;
+    }
+    /** Cancels the turn. The first reason is kept; later calls change nothing. */
+    cancel(reason) {
+        if (this.#stopReason !== undefined)
+            return;
+        this.#stopReason = reason;
+        this.#resolveCancelled();
+    }
+    /** Called by the session when it lets go of this turn. */
+    end() {
+        this.#resolveEnded();
+    }
+}

package/build/server/config.js

@@ -0,0 +1,92 @@
+/**
+ * Deployment settings, read once at startup from the environment (.env).
+ *
+ * Stones hold domain content; everything specific to one deployment is here.
+ * Access codes are read by http/auth.ts. See .env.example for every setting.
+ */
+import { join } from "node:path";
+import { DEFAULT_TURN_LIMITS } from "./agent/conversation.js";
+import { DEFAULT_INACTIVITY_MS } from "./agent/sessions.js";
+/** Every problem at once, so an operator can fix .env in one pass. */
+export class ConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join("; "));
+        this.name = "ConfigError";
+        this.problems = problems;
+    }
+}
+/** Reject partial parses, NaN, zero, and values that overflow Node timers. */
+export function positiveInteger(name, value, fallback, max = 2_147_483_647) {
+    const input = value ?? String(fallback);
+    const number = Number(input);
+    if (!/^\d+$/.test(input) ||
+        !Number.isSafeInteger(number) ||
+        number < 1 ||
+        number > max) {
+        throw new Error(`${name} must be an integer between 1 and ${max}`);
+    }
+    return number;
+}
+export const PRIVACY_VARIABLES = {
+    contact: "ROSETTA_PRIVACY_CONTACT",
+    controller: "ROSETTA_PRIVACY_CONTROLLER",
+    lawfulBasis: "ROSETTA_PRIVACY_LAWFUL_BASIS",
+    providerProcessing: "ROSETTA_PRIVACY_PROVIDER_PROCESSING",
+    additionalInformation: "ROSETTA_PRIVACY_ADDITIONAL_INFORMATION",
+    privacyUpdated: "ROSETTA_PRIVACY_UPDATED",
+};
+/**
+ * `root` is the repository root, for the default stone. `args` are the command's arguments:
+ * at most a stone directory, which wins over ROSETTA_STONE.
+ */
+export function loadConfig(env, root, args = []) {
+    const problems = [];
+    const [stoneArgument, ...extra] = args;
+    if (extra.length || stoneArgument?.startsWith("-"))
+        problems.push(`Usage: rosetta [stone directory] (got: ${args.join(" ")})`);
+    const integer = (name, fallback, max) => {
+        try {
+            return positiveInteger(name, env[name], fallback, max);
+        }
+        catch (error) {
+            problems.push(error.message);
+            return fallback;
+        }
+    };
+    const recordingSetting = env.ROSETTA_RECORDINGS;
+    const { ROSETTA_TLS_CERT: certPath, ROSETTA_TLS_KEY: keyPath } = env;
+    // Half-configured TLS is refused rather than silently serving plain HTTP.
+    if (Boolean(certPath) !== Boolean(keyPath))
+        problems.push("ROSETTA_TLS_CERT and ROSETTA_TLS_KEY must both be set, or neither");
+    const privacy = Object.fromEntries(Object.entries(PRIVACY_VARIABLES).map(([field, name]) => [
+        field,
+        env[name]?.trim() || null,
+    ]));
+    if ((privacy.contact?.length ?? 0) > 500)
+        problems.push("ROSETTA_PRIVACY_CONTACT must be at most 500 characters");
+    const config = {
+        // This computer only, unless HOST shares it on the network.
+        host: env.HOST || "127.0.0.1",
+        port: integer("PORT", 3000, 65535),
+        stonePath: stoneArgument || env.ROSETTA_STONE || join(root, "stones/example"),
+        model: env.ROSETTA_MODEL || undefined,
+        maxSessions: integer("ROSETTA_MAX_SESSIONS", 12),
+        inactivityMs: integer("ROSETTA_INACTIVITY_MS", DEFAULT_INACTIVITY_MS),
+        turnLimits: {
+            timeoutMs: integer("ROSETTA_TURN_TIMEOUT_MS", DEFAULT_TURN_LIMITS.timeoutMs),
+            abortGraceMs: integer("ROSETTA_ABORT_GRACE_MS", DEFAULT_TURN_LIMITS.abortGraceMs),
+        },
+        recordings: {
+            directory: recordingSetting === "0" || recordingSetting === "false"
+                ? false
+                : recordingSetting || "data/sessions",
+            retentionDays: integer("ROSETTA_RECORDING_RETENTION_DAYS", 30),
+        },
+        tls: certPath && keyPath ? { certPath, keyPath } : undefined,
+        privacy,
+    };
+    if (problems.length)
+        throw new ConfigError(problems);
+    return config;
+}

package/build/server/http/auth.js

@@ -0,0 +1,31 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+export function createTokens(env = process.env) {
+    const requireToken = env.ROSETTA_REQUIRE_TOKEN ?? "true";
+    if (requireToken !== "true" && requireToken !== "false") {
+        throw new Error("ROSETTA_REQUIRE_TOKEN must be true or false");
+    }
+    return {
+        user: requireToken === "false"
+            ? null
+            : env.ROSETTA_TOKEN || randomBytes(18).toString("base64url"),
+        admin: env.ROSETTA_ADMIN_TOKEN || randomBytes(18).toString("base64url"),
+    };
+}
+function bearer(req) {
+    return req.headers.authorization?.match(/^Bearer (.+)$/)?.[1] ?? "";
+}
+/** Constant-time comparison, so a wrong token cannot be discovered by timing. */
+export function matches(supplied, expected) {
+    const a = Buffer.from(supplied);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export function isUser(req, tokens) {
+    if (tokens.user === null)
+        return true;
+    const token = bearer(req);
+    return matches(token, tokens.user) || matches(token, tokens.admin);
+}
+export function isAdmin(req, tokens) {
+    return matches(bearer(req), tokens.admin);
+}

package/build/server/http/chat.js

@@ -0,0 +1,67 @@
+import { openStream } from "./stream.js";
+import { bodyOr400, json } from "./util.js";
+const STATUS = {
+    invalid_message: 400,
+    invalid_turn_id: 400,
+    session_not_found: 404,
+    session_busy: 409,
+    turn_id_reused: 409,
+};
+const reject = (res, rejection) => json(res, STATUS[rejection.reason], { error: rejection.message });
+/** Read and admit a chat request, then stream the accepted turn. */
+export async function handleChat(req, res, sessionId, conversations) {
+    const request = await readChatRequest(req, res, sessionId, conversations);
+    if (!request)
+        return;
+    const admission = conversations.admit(request);
+    if (!admission.accepted)
+        return reject(res, admission.rejection);
+    await streamChatTurn(res, admission.turn);
+}
+/** Returns a request, or sends an error response without reserving a turn. */
+async function readChatRequest(req, res, sessionId, conversations) {
+    // Turn ownership is not held while the body arrives; admission rechecks the session afterwards.
+    const ineligible = conversations.eligibility(sessionId);
+    if (ineligible) {
+        reject(res, ineligible);
+        return;
+    }
+    const body = await bodyOr400(req, res);
+    if (!body)
+        return;
+    return {
+        sessionId,
+        turnId: body.turnId,
+        message: body.message,
+    };
+}
+/** Streams progress and the terminal result, cancelling the turn if delivery cannot start or the client leaves. */
+async function streamChatTurn(res, turn) {
+    const onClose = () => {
+        if (!res.writableEnded)
+            turn.cancel("disconnected");
+    };
+    res.on("close", onClose);
+    let stream;
+    let setupError;
+    try {
+        stream = openStream(res);
+    }
+    catch (error) {
+        setupError = error;
+    }
+    // A connection that is already closed, or cannot stream, is cancelled before agent work begins.
+    if (!stream || res.destroyed)
+        turn.cancel("disconnected");
+    let result;
+    try {
+        result = await turn.run((event) => stream?.send(event));
+    }
+    finally {
+        res.off("close", onClose);
+    }
+    if (!stream)
+        throw setupError;
+    // A terminal result never discards text already sent to the browser.
+    stream.close({ t: "terminal", ...result });
+}

package/build/server/http/feedback.js

@@ -0,0 +1,30 @@
+import { SESSION_NOT_FOUND } from "../agent/sessions.js";
+import { validTurnId } from "../agent/turn.js";
+import { bodyOr400, json } from "./util.js";
+export async function handleFeedback(req, res, sessionId, sessions, recordingEnabled) {
+    const session = sessions.find(sessionId);
+    if (!session)
+        return json(res, 404, { error: SESSION_NOT_FOUND });
+    if (!recordingEnabled)
+        return json(res, 409, {
+            error: "Feedback is unavailable while recording is disabled",
+        });
+    const body = await bodyOr400(req, res);
+    if (!body)
+        return;
+    if (!validTurnId(body.turnId) ||
+        !(body.userFoundHelpful === null ||
+            typeof body.userFoundHelpful === "boolean")) {
+        return json(res, 400, {
+            error: "A valid turnId and boolean or null userFoundHelpful are required",
+        });
+    }
+    if (sessions.find(sessionId) !== session)
+        return json(res, 404, { error: SESSION_NOT_FOUND });
+    const recording = session.turnRecordings.get(body.turnId);
+    if (!recording)
+        return json(res, 404, { error: "Answer not found in this session" });
+    if (!recording.setFeedback(body.userFoundHelpful))
+        return json(res, 409, { error: "Wait until this answer has finished" });
+    return json(res, 200, { userFoundHelpful: body.userFoundHelpful });
+}