@zenera/server 1.2.0 → 1.2.2

package/dist/plugins.js

@@ -7,6 +7,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { pathToFileURL } from 'node:url';
+import { DEFAULTS } from "./config.js";
+import { USER_LAYOUT } from "./userState.js";
 export function envRunPlugins(env = process.env) {
     const plugin = (env.ZEN_PLUGINS ?? '')
         .split(',')
@@ -26,4 +28,49 @@ export function envRunPlugins(env = process.env) {
         return mcpPlugin ? [mcpPlugin({ brokerUrl, token: mcpToken })] : [];
     };
 }
+/** The store `ZEN_STATE_STORE` names, made and checked; a broken one stops the server starting. */
+export async function envStateStore(env, at) {
+    const path = env.ZEN_STATE_STORE?.trim();
+    if (!path)
+        return undefined;
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+    if (typeof mod.userStateStore !== 'function') {
+        throw new Error(`${path} exports no userStateStore(options)`);
+    }
+    const store = await mod.userStateStore({
+        ...at,
+        layout: USER_LAYOUT,
+        env,
+        log: {
+            info: (message) => console.log(`[state] ${message}`),
+            warn: (message) => console.warn(`[state] ${message}`),
+        },
+    });
+    const ok = store &&
+        typeof store.name === 'string' &&
+        typeof store.durable === 'boolean' &&
+        typeof store.load === 'function' &&
+        typeof store.checkpoint === 'function';
+    if (!ok)
+        throw new Error(`${path}: userStateStore() did not return a store`);
+    return store;
+}
+function whole(text, fallback, max = Number.MAX_SAFE_INTEGER) {
+    const n = Number(text?.trim());
+    return text?.trim() && Number.isInteger(n) && n >= 0 ? Math.min(n, max) : fallback;
+}
+const MB = 2 ** 20;
+export function envServerLimits(env) {
+    const limits = DEFAULTS.commandLimits;
+    return {
+        checkpointSeconds: whole(env.ZEN_STATE_CHECKPOINT_SECONDS, DEFAULTS.checkpointSeconds),
+        systemSubject: env.ZEN_SERVER_SYSTEM_SUBJECT?.trim() || DEFAULTS.systemSubject,
+        userDiskQuotaBytes: whole(env.ZEN_RUNTIME_USER_DISK_MB, 0) * MB,
+        commandLimits: {
+            nice: whole(env.ZEN_RUNTIME_NICE, limits.nice ?? 0, 19),
+            fileSizeBytes: whole(env.ZEN_RUNTIME_MAX_FILE_MB, 0) * MB,
+            tmpBytes: whole(env.ZEN_RUNTIME_TMP_MB, 0) * MB,
+        },
+    };
+}
 //# sourceMappingURL=plugins.js.map

package/dist/runs.d.ts

@@ -4,6 +4,14 @@ export declare function activeRuns(): number;
 export declare function currentRun(t: ChatThread): {
     runId: string;
 } | null;
+/** One owner's runs going now, with the thread each is on and when it ends. */
+export declare function ownerRuns(owner: string): {
+    threadId: string;
+    runId: string;
+    done: Promise<void>;
+}[];
+/** Ends one owner's runs as interrupted, saying why; resolves once they have saved. */
+export declare function stopOwnerRuns(owner: string, message: string): Promise<void>;
 /** Runs may start again: a new server in a process whose previous one stopped. */
 export declare function acceptRuns(): void;
 export declare function stopAllRuns(timeoutMs: number): Promise<void>;

package/dist/runs.js

@@ -32,6 +32,19 @@ export function currentRun(t) {
     const run = runs.get(t.id);
     return run && run.owner === t.owner ? { runId: run.runId } : null;
 }
+/** One owner's runs going now, with the thread each is on and when it ends. */
+export function ownerRuns(owner) {
+    return [...runs.entries()]
+        .filter(([, run]) => run.owner === owner)
+        .map(([threadId, run]) => ({ threadId, runId: run.runId, done: run.done }));
+}
+/** Ends one owner's runs as interrupted, saying why; resolves once they have saved. */
+export async function stopOwnerRuns(owner, message) {
+    const mine = [...runs.values()].filter((run) => run.owner === owner);
+    for (const run of mine)
+        run.controller.abort(new RunStop('interrupted', message));
+    await Promise.all(mine.map((run) => run.done));
+}
 // 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;
@@ -236,6 +249,7 @@ async function execute(store, t, run, turn, memory, user, mcpToken) {
         }
         await log.end().catch((err) => console.error(`run ${runId}: saving its log:`, err));
         runs.delete(t.id);
+        store.changed?.(t, 'run-end');
     }
 }
 /** Runs may start again: a new server in a process whose previous one stopped. */
@@ -260,6 +274,8 @@ export function runsRouter(store) {
         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();
+        // Over its storage quota, a user gets no new run (checked before the slot is taken).
+        await store.admit?.(t);
         if (stopping) {
             res.set('Retry-After', '5');
             throw new HttpError(503, 'the server is stopping, try again shortly');
@@ -345,6 +361,7 @@ export function runsRouter(store) {
             await run.done;
         }
         await store.removeThread(t);
+        store.changed?.(t, 'changed');
         res.status(204).end();
     });
     return router;

package/dist/server.d.ts

@@ -14,8 +14,11 @@ 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>;
+    /**
+     * Stops taking runs, ends the running ones as interrupted (they save), saves every user
+     * (within `saveMs`), closes the listener.
+     */
+    stop(graceMs?: number, saveMs?: 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. */

package/dist/server.js

@@ -11,7 +11,11 @@
 //   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
+//   /api/admin/{users,users/:sub/release,drain,undrain} - the host's view of this server's users
+// Every /api/sessions request first has the caller's data loaded (userState.ts): a store plugin
+// may keep users elsewhere and move them between servers; the token's `gen` is their lease.
+//   createServer  - the app, configured; `listen` recovers users and starts it, `stop` ends runs,
+//                   saves every user and closes it
 import express, {} from 'express';
 import { configure, DEFAULTS } from "./config.js";
 import { historyRouter } from "./history.js";
@@ -26,6 +30,7 @@ import { serverStatus, setListening } from "./status.js";
 import { privateStore } from "./store.js";
 import { sessionsRouter } from "./sessions.js";
 import { traceRouter } from "./trace.js";
+import { loadCaller, loadThread, userStateRouter, userStates } from "./userState.js";
 export function createServer(opts) {
     const { chatPage, ...runtime } = opts;
     const settings = { ...DEFAULTS, ...runtime, hidden: [...(opts.hidden ?? [])] };
@@ -58,6 +63,9 @@ export function createServer(opts) {
     app.get('/api/activity', (_req, res) => {
         res.json({ busy: activeRuns() > 0, runs: activeRuns() });
     });
+    app.use('/api/admin', userStateRouter());
+    app.use('/api/sessions', loadCaller);
+    app.use('/api/sessions/:tid', loadThread);
     app.use('/api/sessions', sessionsRouter());
     app.use('/api/sessions', runsRouter(privateStore));
     app.use('/api/sessions', historyRouter(privateStore));
@@ -72,19 +80,23 @@ export function createServer(opts) {
     return {
         app,
         settings,
-        listen: ({ port, host = '127.0.0.1' }) => new Promise((resolve, reject) => {
+        listen: async ({ port, host = '127.0.0.1' }) => {
             if (settings.auth.mode === 'insecure' && !LOOPBACK.has(host) && !insecureHere()) {
-                reject(new Error(`an insecure server listens on loopback only, not ${host}`));
-                return;
+                throw new Error(`an insecure server listens on loopback only, not ${host}`);
             }
-            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) => {
+            // Users whose folders survived a restart are known (and saved) before anyone calls.
+            await userStates.start();
+            return new Promise((resolve, reject) => {
+                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, saveMs = 60_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);
+            await userStates.shutdown(saveMs);
             // Followers of runs that have ended, idle keep-alives: nothing left to answer.
             server?.closeAllConnections();
             await closed;

package/dist/status.d.ts

@@ -47,6 +47,13 @@ export interface ServerStatus {
     };
     /** what each user's memory starts as, when there is anything */
     memorySeed?: string;
+    /** where users' data is kept, and how many are on this server now */
+    state: {
+        store: string;
+        durable: boolean;
+        users: number;
+        draining: boolean;
+    };
 }
 /** Where the server listens, for the report. */
 export declare function setListening(where: string | undefined): void;

package/dist/status.js

@@ -11,6 +11,7 @@ import { createRequire } from 'node:module';
 import { settings } from "./config.js";
 import { LAYOUT_VERSION, openLayout } from "./layout.js";
 import { memorySeed } from "./store.js";
+import { userStates } from "./userState.js";
 const require = createRequire(import.meta.url);
 function versionOf(pkg) {
     try {
@@ -105,6 +106,12 @@ export async function serverStatus(env = process.env) {
         image,
         root,
         ...(memorySeed() ? { memorySeed: memorySeed() } : {}),
+        state: {
+            store: s.stateStore?.name ?? 'local',
+            durable: s.stateStore?.durable ?? false,
+            users: userStates.size,
+            draining: userStates.draining,
+        },
     };
 }
 /** Why the server must not start, if anything. An image that was never labelled is not one. */

package/dist/store.d.ts

@@ -25,6 +25,10 @@ export interface ChatStore {
     maxOwnerRuns: number;
     /** Why a run is refused when the owner has that many going. */
     ownerBusy: string;
+    /** Before a run takes its slot: throw an HttpError to refuse it (e.g. storage over quota). */
+    admit?(t: ChatThread): Promise<void>;
+    /** After a run ended or the thread was deleted: the owner's data changed. */
+    changed?(t: ChatThread, reason: 'run-end' | 'changed'): void;
 }
 /** Where one user's things are. */
 export declare function userDir(user: string): string;

package/dist/store.js

@@ -28,6 +28,7 @@ import { settings } from "./config.js";
 import { HttpError } from "./http.js";
 import { identify } from "./identity.js";
 import { applyProjectEnv } from "./projectEnv.js";
+import { userStates } from "./userState.js";
 /** Where one user's things are. */
 export function userDir(user) {
     return join(settings().root, 'users', user);
@@ -112,6 +113,8 @@ export const privateStore = {
         return settings().maxUserRuns;
     },
     ownerBusy: 'your other chats are still answering',
+    admit: (t) => userStates.admit(t.owner),
+    changed: (t, reason) => userStates.changed(t.owner, reason),
 };
 export function usesMemory() {
     try {
@@ -153,7 +156,7 @@ function sandboxFactory(s) {
         ...(existsSync(AGENT_APP_DIR) ? [AGENT_APP_DIR] : []),
         ...s.hidden,
     ];
-    return (opts) => new BwrapSandbox(opts, { hidden });
+    return (opts) => new BwrapSandbox(opts, { hidden, limits: s.commandLimits });
 }
 export async function openEngineFor(session, memoryDir, 
 // Who the run acts for; null is nobody, and stops the engine reading ZEN_USER_* from this process.

package/dist/userState.d.ts

@@ -0,0 +1,99 @@
+import { Router, type NextFunction, type Request, type Response } from 'express';
+/** Where things are in a user's folder, for stores that cannot import this package. */
+export declare const USER_LAYOUT: {
+    /** the user's memory graph; checkpoints carry a consistent copy instead (`memoryDir`) */
+    readonly memory: "memory";
+    /** one folder per chat thread */
+    readonly sessions: "sessions";
+    /** inside a session folder: its metadata, which the session list reads */
+    readonly sessionMeta: ".data/session.json";
+    /** the server's own record of the user's lease; never a store's to save */
+    readonly marker: ".zen-user.json";
+};
+export interface UserRef {
+    /** the user's folder name under `<root>/users/` */
+    id: string;
+    /** that folder: everything of theirs on this server */
+    dir: string;
+    /** the host's lease generation (the token's `gen`); undefined when the host does not lease */
+    generation?: number;
+}
+export type CheckpointReason = 'run-end' | 'changed' | 'periodic' | 'release' | 'shutdown' | 'recover';
+export interface UserSnapshot {
+    /** a consistent copy of the user's memory made for this call, removed after it; none: no memory */
+    memoryDir?: string;
+    /** threads with a run going: their files may change while they are read */
+    activeThreads: string[];
+}
+export interface UserStateStore {
+    readonly name: string;
+    /** true: the store keeps users elsewhere, so a released user's local copy is deleted */
+    readonly durable: boolean;
+    /** Before the user's first request here: fetch what they need into `user.dir`. */
+    load(user: UserRef): Promise<void>;
+    /** Before a request names one thread: fetch it if `load` left it for later. */
+    loadSession?(user: UserRef, threadId: string): Promise<void>;
+    /** Save the user's folder as it is now (memory from `snapshot.memoryDir`). */
+    checkpoint(user: UserRef, reason: CheckpointReason, snapshot: UserSnapshot): Promise<void>;
+    /** After the final checkpoint, before the local copy goes. */
+    release?(user: UserRef): Promise<void>;
+    /** On start, for users whose folders survived a restart of this process. */
+    recover?(users: UserRef[]): Promise<void>;
+    close?(): Promise<void>;
+}
+/** Thrown by a store when a newer lease generation owns the user: this copy must go. */
+export declare class StaleGenerationError extends Error {
+    readonly code = "stale_generation";
+}
+export declare const localStore: UserStateStore;
+type Status = 'loading' | 'ready' | 'releasing';
+export interface UserInfo {
+    id: string;
+    generation?: number;
+    status: Status;
+    activeRuns: number;
+    unsaved: boolean;
+    lastUsed: string;
+    lastCheckpointAt?: string;
+    lastError?: string;
+    usageBytes?: number;
+}
+declare class UserStates {
+    #private;
+    get draining(): boolean;
+    get size(): number;
+    /** The user's data, ready; their folder is theirs to use once this resolves. */
+    acquire(id: string, generation?: number): Promise<void>;
+    /** Before a request names a thread: the store fetches it if it left it for later. */
+    session(id: string, threadId: string): Promise<void>;
+    /** Something of the user's changed (a run ended, a thread went): save it. */
+    changed(id: string, reason?: CheckpointReason): void;
+    /** Saves the user now, after any save already queued; one at a time per user. */
+    checkpoint(id: string, reason: CheckpointReason): Promise<void>;
+    /** Saves the user for the last time and lets them go; refused while their runs go on. */
+    release(id: string): Promise<'released' | 'absent'>;
+    /** No new users; each one here released once their runs end. */
+    drain(timeoutMs: number): Promise<{
+        released: string[];
+        failed: Record<string, string>;
+    }>;
+    /** Takes users again: a drain that was called off. */
+    undrain(): void;
+    list(withUsage?: boolean): Promise<UserInfo[]>;
+    /** Over the soft quota: refuse new runs (checked before one starts). */
+    admit(id: string): Promise<void>;
+    /** Recovers users whose folders survived a restart, and starts the timers. */
+    start(): Promise<void>;
+    /** After the runs stopped: everyone saved once more, as far as the time allows. */
+    shutdown(timeoutMs: number): Promise<void>;
+}
+export declare const userStates: UserStates;
+/** Every user-scoped route: the caller's data loaded first, and their thread when one is named. */
+export declare function loadCaller(req: Request, _res: Response, next: NextFunction): Promise<void>;
+export declare function loadThread(req: Request, _res: Response, next: NextFunction): Promise<void>;
+/** /api/admin: only for the host's own calls (its system subject, never a user's thread token). */
+export declare function userStateRouter(): Router;
+/** Bytes under a user's folder, links not followed. */
+export declare function userUsageBytes(id: string): Promise<number>;
+export {};
+//# sourceMappingURL=userState.d.ts.map