@zenera/server 0.0.0-stage → 1.2.0

package/dist/runs.js

@@ -0,0 +1,376 @@
+import * as engineLib from '@zenera/engine';
+import { runEngine } from '@zenera/engine';
+import { turns } from '@zenera/neo';
+import { Router } from 'express';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { AguiTranslator } from "./agui.js";
+import { settings } from "./config.js";
+import { HttpError } from "./http.js";
+import { runUser } from "./identity.js";
+import { readRunLog, RunLog, threadRunLogs } from "./runLog.js";
+import { listRunRecords, recordedReport, recordOutcome, saveRecord, startRecord, } from "./runRecords.js";
+import { asHttpError, errorMessage, openEngineFor, usesMemory, } from "./store.js";
+const MAX_INPUT_CHARS = 100_000;
+const ID = /^[\w-]{1,80}$/;
+// Why a run was stopped: a cancel ends it as cancelled, the others as a RUN_ERROR saying why.
+class RunStop extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+// By thread id.
+const runs = new Map();
+// Set by stopAllRuns: a run started after it would be cut off mid-turn by the exit that follows.
+let stopping = false;
+export function activeRuns() {
+    return runs.size;
+}
+export function currentRun(t) {
+    const run = runs.get(t.id);
+    return run && run.owner === t.owner ? { runId: run.runId } : null;
+}
+// The newest user message of an AG-UI RunAgentInput; the thread's history is the runtime's own.
+function inputOf(body) {
+    const messages = body?.messages;
+    const last = Array.isArray(messages) ? messages.at(-1) : undefined;
+    if (!last || last.role !== 'user') {
+        throw new HttpError(400, 'the last message must be the user message to answer');
+    }
+    const parts = typeof last.content === 'string' ? [{ type: 'text', text: last.content }] : last.content;
+    if (!Array.isArray(parts))
+        throw new HttpError(400, 'message content must be text');
+    const text = parts
+        .map((p) => {
+        const part = p;
+        if (part?.type !== 'text' || typeof part.text !== 'string') {
+            throw new HttpError(400, 'only text messages are supported');
+        }
+        return part.text;
+    })
+        .join('\n')
+        .trim();
+    if (!text)
+        throw new HttpError(400, 'the message is empty');
+    if (text.length > MAX_INPUT_CHARS) {
+        throw new HttpError(413, `the message is longer than ${MAX_INPUT_CHARS} characters`);
+    }
+    return { id: typeof last.id === 'string' && ID.test(last.id) ? last.id : randomUUID(), text };
+}
+// The answers zenera-app sends to resume a suspended run (AG-UI ResumeEntry), checked.
+function resumeOf(body) {
+    const resume = body?.resume;
+    if (resume === undefined)
+        return null;
+    if (!Array.isArray(resume) || !resume.length) {
+        throw new HttpError(400, 'resume must be a non-empty list of answers');
+    }
+    return resume.map((r) => {
+        const e = r;
+        if (typeof e?.interruptId !== 'string' ||
+            (e.status !== 'resolved' && e.status !== 'cancelled')) {
+            throw new HttpError(400, 'each resume entry needs an interruptId and a status');
+        }
+        return { interruptId: e.interruptId, status: e.status, payload: e.payload };
+    });
+}
+// Resume entries name interrupts; the engine answers calls. A suspension's data carries the
+// interrupt id zenera-app gave it. resolved without a payload: what was needed is done, run the
+// call again; with one: the payload is the call's result.
+function answersFor(state, entries) {
+    const suspended = state?.suspended ?? [];
+    const answers = {};
+    for (const e of entries) {
+        const s = suspended.find((x) => (x.data?.interruptId ?? x.callId) === e.interruptId);
+        if (!s)
+            continue;
+        const payload = e.payload;
+        answers[s.callId] =
+            e.status === 'cancelled'
+                ? {
+                    status: 'cancelled',
+                    message: typeof payload?.message === 'string' ? payload.message : undefined,
+                }
+                : e.payload === undefined
+                    ? { status: 'resolved', rerun: true }
+                    : { status: 'resolved', payload: e.payload };
+    }
+    return answers;
+}
+// The interrupt ids a thread's saved state waits on; none when it is not suspended.
+function waitingOn(store, t) {
+    const session = store.existingSession(t);
+    if (!session || !existsSync(session.state))
+        return new Set();
+    try {
+        const state = JSON.parse(readFileSync(session.state, 'utf8'));
+        return new Set((state.suspended ?? []).map((s) => typeof s.data?.interruptId === 'string' ? s.data.interruptId : s.callId));
+    }
+    catch {
+        return new Set();
+    }
+}
+// Read at call time: an older @zenera/engine without it still loads, and says so on resume.
+function resumeEngineFn() {
+    const fn = engineLib.resumeEngine;
+    if (!fn)
+        throw new Error('this zen version cannot resume a suspended run; update zen');
+    return fn;
+}
+function startStream(res) {
+    res.status(200).set({
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no',
+    });
+    res.flushHeaders();
+    res.socket?.setNoDelay(true);
+    return (events) => {
+        for (const e of events) {
+            if (!res.writableEnded)
+                res.write(`data: ${JSON.stringify(e)}\n\n`);
+        }
+    };
+}
+// Follows a run to its end, or until the browser leaves; leaving does not stop the run.
+function follow(res, log) {
+    const send = startStream(res);
+    const heartbeat = setInterval(() => {
+        if (!res.writableEnded)
+            res.write(': ping\n\n');
+    }, 15_000);
+    const unfollow = log.follow({
+        events: send,
+        end: () => {
+            clearInterval(heartbeat);
+            res.end();
+        },
+    });
+    res.on('close', () => {
+        clearInterval(heartbeat);
+        unfollow();
+    });
+}
+// Never throws: whatever ends the run is written to its log as the run's last event.
+async function execute(store, t, run, turn, memory, user, mcpToken) {
+    const { runId, log, controller } = run;
+    let engine;
+    const translator = new AguiTranslator({
+        threadId: t.id,
+        runId,
+        resolve: async (p) => (engine ? engine.runner.services.payloads.get(p) : ''),
+    });
+    const input = {
+        threadId: t.id,
+        runId,
+        messages: 'message' in turn
+            ? [{ id: turn.message.id, role: 'user', content: turn.message.text }]
+            : [],
+        ...('resume' in turn ? { resume: turn.resume } : {}),
+        tools: [],
+        context: [],
+        forwardedProps: {},
+    };
+    log.append(translator.started(input));
+    const maxMinutes = settings().maxRunMinutes;
+    const timer = setTimeout(() => controller.abort(new RunStop('timeout', `the run took longer than ${maxMinutes} minutes`)), maxMinutes * 60_000);
+    const stopped = () => controller.signal.reason instanceof RunStop ? controller.signal.reason : undefined;
+    // runEngine calls back synchronously; translating may await payloads, so keep the order here.
+    let chain = Promise.resolve();
+    const onEvent = (ev) => {
+        chain = chain
+            .then(async () => {
+            const why = stopped();
+            // Stopped for anything but a cancel: the run did not finish, say why instead.
+            if (ev.type === 'run_finished' && !ev.branch && why && why.code !== 'cancelled') {
+                log.append(translator.fail(why, why.code));
+            }
+            else {
+                log.append(await translator.translate(ev));
+            }
+        })
+            .catch((err) => console.error(`run ${runId}: translating ${ev.type}:`, err));
+    };
+    try {
+        engine = await openEngineFor(store.sessionFor(t), memory ? await store.engineMemoryDir(t) : undefined, user, mcpToken);
+        const before = {
+            usage: engine.state?.usage,
+            modelCalls: engine.state ? turns(engine.state) : 0,
+            trajectoryLength: engine.state?.trajectory.length ?? 0,
+        };
+        const outcome = 'message' in turn
+            ? await runEngine(engine, turn.message.text, onEvent, controller.signal)
+            : await resumeEngineFn()(engine, answersFor(engine.state, turn.resume), onEvent, controller.signal);
+        recordOutcome(run.record, outcome, before);
+        const why = stopped();
+        if (why) {
+            run.record.status = why.code;
+            run.record.error = why.message;
+        }
+        saveRecord(store.runsDir(t), run.record);
+    }
+    catch (err) {
+        await chain;
+        const why = stopped();
+        if (!why)
+            console.error(`run ${runId}:`, err);
+        run.record.status = why?.code ?? 'error';
+        run.record.error = why?.message ?? errorMessage(err);
+        log.append(translator.fail(why ?? new Error(errorMessage(err)), why?.code ?? 'error'));
+    }
+    finally {
+        clearTimeout(timer);
+        await chain;
+        log.append(translator.fail(new Error('the run ended without a result')));
+        await engine?.close().catch((err) => console.error(`run ${runId}: closing:`, err));
+        run.record.finishedAt = new Date().toISOString();
+        run.record.durationMs ??= Date.now() - Date.parse(run.record.startedAt);
+        try {
+            saveRecord(store.runsDir(t), run.record);
+        }
+        catch (err) {
+            console.error(`run ${runId}: saving diagnostics:`, err);
+        }
+        await log.end().catch((err) => console.error(`run ${runId}: saving its log:`, err));
+        runs.delete(t.id);
+    }
+}
+/** Runs may start again: a new server in a process whose previous one stopped. */
+export function acceptRuns() {
+    stopping = false;
+}
+export async function stopAllRuns(timeoutMs) {
+    stopping = true;
+    const all = [...runs.values()];
+    for (const run of all) {
+        run.controller.abort(new RunStop('interrupted', 'the run was interrupted: the server is stopping'));
+    }
+    await Promise.race([
+        Promise.all(all.map((run) => run.done)),
+        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+}
+export function runsRouter(store) {
+    const router = Router();
+    router.post('/:tid/runs', async (req, res) => {
+        const t = store.thread(req);
+        const resume = resumeOf(req.body);
+        const turn = resume ? { resume } : { message: inputOf(req.body) };
+        const runId = ID.test(req.body?.runId ?? '') ? String(req.body.runId) : randomUUID();
+        if (stopping) {
+            res.set('Retry-After', '5');
+            throw new HttpError(503, 'the server is stopping, try again shortly');
+        }
+        const running = runs.get(t.id);
+        // Answers to what the chat no longer waits on (a new message went first): nothing to run.
+        if (!running && resume) {
+            const waiting = waitingOn(store, t);
+            if (!resume.some((e) => waiting.has(e.interruptId))) {
+                res.status(409).json({
+                    error: 'this chat is not waiting on those interrupts',
+                    code: 'not_waiting',
+                });
+                return;
+            }
+        }
+        if (running) {
+            res.status(409).json({ error: 'this chat is still answering', runId: running.runId });
+            return;
+        }
+        if (runs.size >= settings().maxRuns) {
+            res.set('Retry-After', '10');
+            throw new HttpError(429, 'too many chats are answering in this project, try again shortly');
+        }
+        // Whether the run gets the owner's memory; it no longer limits how many run at once.
+        let memory;
+        try {
+            memory = usesMemory();
+        }
+        catch (err) {
+            throw asHttpError(err);
+        }
+        const mine = [...runs.values()].filter((r) => r.owner === t.owner).length;
+        if (mine >= store.maxOwnerRuns)
+            throw new HttpError(409, store.ownerBusy);
+        // Nothing awaited from the checks above to here: the thread's slot is taken at once.
+        const dir = store.runsDir(t);
+        const record = startRecord(dir, runId);
+        const run = {
+            runId,
+            owner: t.owner,
+            controller: new AbortController(),
+            log: RunLog.open(dir, runId, settings().runLogMaxBytes),
+            done: Promise.resolve(),
+            record,
+        };
+        runs.set(t.id, run);
+        // The caller's token for this run's MCP tools (zenera-app's broker, mcp/broker.ts there);
+        // whatever stands in front of the server decides who may send one.
+        const mcpToken = req.get('x-zenera-mcp-token') || null;
+        run.done = execute(store, t, run, turn, memory, runUser(req), mcpToken);
+        follow(res, run.log);
+    });
+    router.get('/:tid/runs/:runId/events', async (req, res) => {
+        const t = store.thread(req);
+        const runId = String(req.params.runId);
+        const run = runs.get(t.id);
+        if (run && run.runId === runId && run.owner === t.owner) {
+            follow(res, run.log);
+            return;
+        }
+        const ended = (await threadRunLogs(store.runsDir(t))).find((r) => r.runId === runId);
+        if (!ended)
+            throw new HttpError(404, 'no such run');
+        const events = await readRunLog(ended.file);
+        startStream(res)(events);
+        res.end();
+    });
+    router.post('/:tid/runs/:runId/cancel', (req, res) => {
+        const t = store.thread(req);
+        const run = runs.get(t.id);
+        if (!run || run.runId !== req.params.runId || run.owner !== t.owner) {
+            throw new HttpError(404, 'no such run');
+        }
+        run.controller.abort(new RunStop('cancelled', 'cancelled'));
+        res.status(202).json({ ok: true });
+    });
+    router.delete('/:tid', async (req, res) => {
+        const t = store.thread(req);
+        const run = runs.get(t.id);
+        if (run && run.owner === t.owner) {
+            run.controller.abort(new RunStop('cancelled', 'the chat was deleted'));
+            await run.done;
+        }
+        await store.removeThread(t);
+        res.status(204).end();
+    });
+    return router;
+}
+export function runDebugRouter(store) {
+    const router = Router();
+    const records = (t) => listRunRecords(store.runsDir(t), store.existingSession(t), currentRun(t)?.runId);
+    router.get('/:tid/runs', async (req, res) => {
+        const t = store.thread(req);
+        res.setHeader('Cache-Control', 'no-store');
+        res.json({ runs: await records(t) });
+    });
+    router.get('/:tid/runs/:runId', async (req, res) => {
+        const t = store.thread(req);
+        const run = (await records(t)).find((r) => r.runId === req.params.runId);
+        if (!run)
+            throw new HttpError(404, 'no such run');
+        res.setHeader('Cache-Control', 'no-store');
+        res.json({ run });
+    });
+    router.get('/:tid/runs/:runId/report', async (req, res) => {
+        const t = store.thread(req);
+        const html = await recordedReport(store.runsDir(t), store.existingSession(t), String(req.params.runId));
+        res.setHeader('Cache-Control', 'no-store');
+        res.json({ html });
+    });
+    return router;
+}
+//# sourceMappingURL=runs.js.map

package/dist/server.d.ts

@@ -0,0 +1,28 @@
+import { type Express } from 'express';
+import type { Server } from 'node:http';
+import { type ServerSettings } from './config.ts';
+export type ServerOptions = Partial<ServerSettings> & Pick<ServerSettings, 'projectId' | 'auth' | 'root'> & {
+    /** Absolute path to the CLI's compiled page; served publicly only in insecure mode. */
+    chatPage?: string;
+};
+/** TCP; loopback unless a host is named. */
+export interface ListenOn {
+    port: number;
+    host?: string;
+}
+export interface AgentServer {
+    app: Express;
+    settings: ServerSettings;
+    listen(on: ListenOn): Promise<Server>;
+    /** stops taking runs, ends the running ones as interrupted (they save), closes the listener */
+    stop(graceMs?: number): Promise<void>;
+}
+export declare function createServer(opts: ServerOptions): AgentServer;
+/** The env `zen server start --container` sets on the container it runs, port on loopback. */
+export declare const INSECURE_LOCAL_ENV = "ZEN_SERVER_INSECURE_LOCAL";
+/**
+ * Inside the agent image an insecure server listens on 0.0.0.0 for the port to be published; only
+ * the host that runs it on this machine, its port on loopback, says that is all right.
+ */
+export declare function insecureHere(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,105 @@
+// HTTP runtime assembled for `zen server start`, directly or inside the agent image.
+// createServer configures Express and its routes, returning listen/stop lifecycle methods;
+// insecureHere permits the CLI's loopback-published local test container.
+// Every API request carries a JWT whose `sub` selects the user's private store (store.ts).
+// Secure mode verifies a host signature bound to that request; insecure mode only decodes it.
+// A sandboxed command can reach the port but cannot mint a valid JWT in secure mode.
+//   GET  /healthz                         - for probes
+//   GET  /chat                            - bundled test page, insecure mode only
+//   GET  /api/status                      - versions, auth, sandbox, image identity, root, seed
+//   GET  /api/activity                    - whether a run is going (idle stop asks this)
+//   GET  /api/sessions                    - the caller's sessions, newest activity first
+//   /api/sessions/:tid...                 - history, runs (start, follow, replay, cancel), delete
+//   /api/sessions/:tid/{runs,trace,memory}... with `debug` - the Test tab's views of a chat
+//   createServer  - the app, configured; `listen` starts it, `stop` ends runs and closes it
+import express, {} from 'express';
+import { configure, DEFAULTS } from "./config.js";
+import { historyRouter } from "./history.js";
+import { errorHandler, notFound } from "./http.js";
+import { requireCaller } from "./auth.js";
+import { inAgentImage } from "./config.js";
+import { openLayout } from "./layout.js";
+import { localFileCors } from "./localFileCors.js";
+import { memoryRouter } from "./memory.js";
+import { acceptRuns, activeRuns, runDebugRouter, runsRouter, stopAllRuns } from "./runs.js";
+import { serverStatus, setListening } from "./status.js";
+import { privateStore } from "./store.js";
+import { sessionsRouter } from "./sessions.js";
+import { traceRouter } from "./trace.js";
+export function createServer(opts) {
+    const { chatPage, ...runtime } = opts;
+    const settings = { ...DEFAULTS, ...runtime, hidden: [...(opts.hidden ?? [])] };
+    if (settings.auth.mode === 'jwt' && !settings.auth.publicKey.trim()) {
+        throw new Error('a jwt server needs the public key its tokens are signed for');
+    }
+    configure(settings);
+    openLayout(settings.root, settings.projectId);
+    acceptRuns();
+    const app = express();
+    app.disable('x-powered-by');
+    app.use(localFileCors);
+    if (settings.auth.mode === 'insecure' && chatPage) {
+        app.get('/chat', (_req, res, next) => {
+            res.set('Cache-Control', 'no-store');
+            res.sendFile(chatPage, (err) => {
+                if (err)
+                    next(err);
+            });
+        });
+    }
+    app.use(requireCaller());
+    app.use(express.json({ limit: '1mb' }));
+    app.get('/healthz', (_req, res) => {
+        res.type('text/plain').send('ok');
+    });
+    app.get('/api/status', async (_req, res) => {
+        res.json(await serverStatus());
+    });
+    app.get('/api/activity', (_req, res) => {
+        res.json({ busy: activeRuns() > 0, runs: activeRuns() });
+    });
+    app.use('/api/sessions', sessionsRouter());
+    app.use('/api/sessions', runsRouter(privateStore));
+    app.use('/api/sessions', historyRouter(privateStore));
+    if (settings.debug) {
+        app.use('/api/sessions', runDebugRouter(privateStore));
+        app.use('/api/sessions', traceRouter(privateStore));
+        app.use('/api/sessions', memoryRouter(privateStore));
+    }
+    app.use(notFound);
+    app.use(errorHandler);
+    let server;
+    return {
+        app,
+        settings,
+        listen: ({ port, host = '127.0.0.1' }) => new Promise((resolve, reject) => {
+            if (settings.auth.mode === 'insecure' && !LOOPBACK.has(host) && !insecureHere()) {
+                reject(new Error(`an insecure server listens on loopback only, not ${host}`));
+                return;
+            }
+            setListening(`${host}:${port}`);
+            // Express 5 hands a listen error (EADDRINUSE) to this callback instead of throwing it.
+            server = app.listen(port, host, (err) => err ? reject(err) : resolve(server));
+        }),
+        stop: async (graceMs = 20_000) => {
+            // No new connections, and no new runs on the ones still open, before the drain.
+            const closed = new Promise((resolve) => server ? server.close(() => resolve()) : resolve());
+            await stopAllRuns(graceMs);
+            // Followers of runs that have ended, idle keep-alives: nothing left to answer.
+            server?.closeAllConnections();
+            await closed;
+            setListening(undefined);
+        },
+    };
+}
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+/** The env `zen server start --container` sets on the container it runs, port on loopback. */
+export const INSECURE_LOCAL_ENV = 'ZEN_SERVER_INSECURE_LOCAL';
+/**
+ * Inside the agent image an insecure server listens on 0.0.0.0 for the port to be published; only
+ * the host that runs it on this machine, its port on loopback, says that is all right.
+ */
+export function insecureHere(env = process.env) {
+    return inAgentImage() && env[INSECURE_LOCAL_ENV] === '1';
+}
+//# sourceMappingURL=server.js.map

package/dist/sessions.d.ts

@@ -0,0 +1,13 @@
+import { Router } from 'express';
+export interface SessionInfo {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    running: {
+        runId: string;
+    } | null;
+}
+/** A user's real sessions, without opening engines or creating memory. */
+export declare function sessionsRouter(): Router;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.js

@@ -0,0 +1,61 @@
+/**
+ * Per-user session-list endpoint mounted by server.ts at GET /api/sessions.
+ * sessionsRouter reads engine metadata under the authenticated JWT subject's folder,
+ * honors thread-scoped claims, adds current run ids and sorts by latest activity.
+ * The standalone chat uses this list without opening engines or creating user memory.
+ */
+import { readSessionMeta, sessionPathsAt } from '@zenera/engine';
+import { Router } from 'express';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { caller, isThreadId, userFolder } from "./identity.js";
+import { currentRun } from "./runs.js";
+import { userDir } from "./store.js";
+/** A user's real sessions, without opening engines or creating memory. */
+export function sessionsRouter() {
+    const router = Router();
+    router.get('/', async (req, res) => {
+        const claims = caller(req);
+        const owner = userFolder(claims.sub);
+        const dir = join(userDir(owner), 'sessions');
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            res.json({ sessions: [] });
+            return;
+        }
+        const sessions = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !isThreadId(entry.name))
+                continue;
+            if (claims.thr !== undefined &&
+                String(claims.thr).toLowerCase() !== entry.name.toLowerCase())
+                continue;
+            const paths = sessionPathsAt(join(dir, entry.name));
+            try {
+                await stat(paths.meta);
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    continue;
+                throw err;
+            }
+            const meta = await readSessionMeta(paths);
+            sessions.push({
+                id: entry.name,
+                title: meta.title || entry.name,
+                createdAt: meta.createdAt,
+                updatedAt: meta.lastRunAt ?? meta.createdAt,
+                running: currentRun({ id: entry.name, owner }),
+            });
+        }
+        sessions.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+        res.json({ sessions });
+    });
+    return router;
+}
+//# sourceMappingURL=sessions.js.map

package/dist/state.d.ts

@@ -0,0 +1,24 @@
+/** 1: data/{sessions,runs,memory}, one user's. */
+export declare const STATE_VERSION = 1;
+export interface StateInfo {
+    version: number;
+    createdAt: string;
+    /** whose state it is */
+    userId: string;
+    projectId: string;
+}
+export declare class StateError extends Error {
+    name: string;
+}
+/**
+ * The state directory's description, checked against who opens it: the same project and the
+ * same user. `create: false` only reads (a check must not claim a directory): a missing file
+ * is then `undefined`.
+ */
+export declare function openState(dir: string, owner: {
+    userId: string;
+    projectId: string;
+}, opts?: {
+    create?: boolean;
+}): StateInfo | undefined;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.js

@@ -0,0 +1,55 @@
+// The state directory's own description: which layout it is in, so a server never reads (or
+// writes over) a layout it does not know. Written on first start; a newer one is refused.
+//   STATE_VERSION   - the layout this server writes
+//   openState       - create or check <state>/state.json, answering what it says
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** 1: data/{sessions,runs,memory}, one user's. */
+export const STATE_VERSION = 1;
+export class StateError extends Error {
+    name = 'StateError';
+}
+/**
+ * The state directory's description, checked against who opens it: the same project and the
+ * same user. `create: false` only reads (a check must not claim a directory): a missing file
+ * is then `undefined`.
+ */
+export function openState(dir, owner, opts = {}) {
+    const file = join(dir, 'state.json');
+    if (!existsSync(file)) {
+        if (opts.create === false)
+            return undefined;
+        // The user's chats: nobody else on the machine reads them.
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const info = {
+            version: STATE_VERSION,
+            createdAt: new Date().toISOString(),
+            userId: owner.userId,
+            projectId: owner.projectId,
+        };
+        writeFileSync(`${file}.tmp`, `${JSON.stringify(info, null, 2)}\n`);
+        renameSync(`${file}.tmp`, file);
+        return info;
+    }
+    let info;
+    try {
+        info = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new StateError(`${file} is not readable: ${err instanceof Error ? err.message : err}`);
+    }
+    if (!Number.isInteger(info.version) || info.version < 1) {
+        throw new StateError(`${file} names no layout version`);
+    }
+    if (info.version > STATE_VERSION) {
+        throw new StateError(`${dir} is in layout ${info.version}, written by a newer server; this one knows ${STATE_VERSION}`);
+    }
+    if (info.projectId !== owner.projectId) {
+        throw new StateError(`${dir} belongs to project ${info.projectId}, not ${owner.projectId}`);
+    }
+    if (info.userId !== owner.userId) {
+        throw new StateError(`${dir} belongs to user ${info.userId}, not ${owner.userId}`);
+    }
+    return info;
+}
+//# sourceMappingURL=state.js.map