@zenera/server 1.2.0 → 1.2.2

package/README.md

@@ -1,246 +1,219 @@
-# @zenera/server
+<div align="center">
+  <img
+    src="https://raw.githubusercontent.com/zenera-ai/ZeneraNeo/main/docs/imgs/zenera-logo-with-media-queries.svg"
+    alt="Zenera"
+    width="24"
+  />
+  <div>Powered By Zenera</div>
+  <br>
+  <img
+    src="https://raw.githubusercontent.com/zenera-ai/ZeneraNeo/main/docs/imgs/banner-server-with-media-queries.svg"
+    alt="ZENERA SERVER"
+    width="918"
+  />
 
-A project's chats over HTTP, for every user its host vouches for: the server
-the agent image runs. Each turn opens the project with
-[`@zenera/engine`](../engine), streams its events as
-[AG-UI](https://docs.ag-ui.com), and runs the agents' commands in a sandbox —
-under bubblewrap inside the agent image, with podman anywhere else, as `zen run`.
+[![npm](https://img.shields.io/npm/v/@zenera/server.svg)](https://www.npmjs.com/package/@zenera/server)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/zenera-ai/ZeneraNeo/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
+
+[Quickstart](#quickstart) · [Secure setup](#secure-setup) · [Commands](#commands) · [Options](#common-options) · [HTTP API](#http-api)
+
+</div>
+
+# `@zenera/server`
+
+Serve a ZeneraNeo project's chats over HTTP. Each user has private sessions and
+memory; agent commands run in Podman sandboxes, or under bwrap in an agent container.
+Requires Node.js 24+ and the [Zenera CLI](../cli/README.md).
+
+## Quickstart
+
+For local testing, run the server in the configured project's agent container:
 
 ```sh
-zen server start --insecure                            # try it here: tokens read, not checked
-zen server token --user ann                            # a token such a server takes
-zen server start --jwt-public-key app.pub.pem          # behind zenera-app
-zen server start --container --insecure                # in the project's agent image, under bwrap
-zen server check                                       # could it start here?
-zen server status                                      # a running one's report
+zen server start --insecure --container --user andrey
 ```
 
-With `--insecure`, startup prints a ready-to-open HTTP link to the bundled
-React chat page served at `/chat`. It includes the server address and an unsigned JWT in the
-fragment (not a query parameter); the page removes the fragment and keeps the
-token only in memory. The default browser user is `local`; use `--user ann` to
-test another user's sessions. The same works with `--container`: the outer CLI
-prints the host's published address and port. HTTP links preserve the fragment
-when opened from a terminal on macOS, unlike file-document links.
-The fragment ends with `&open=1` so terminal link detection preserves the unsigned
-JWT's trailing dot.
-The page route is public only in insecure mode; API requests still require a JWT.
-Secure mode does not expose the page. It remains a single compiled HTML asset,
-with no frontend dependencies or separate UI server needed at runtime.
-
-Startup uses an aligned, colored summary for the project, HTTP address, auth,
-sandbox, state directory, image and browser user. Container builds show one
-updating, width-limited line with a spinner and elapsed build time by default,
-even during quiet steps; piped logs retain only the final
-progress line. Warnings and errors remain visible in both cases.
-Use `zen server start --container --verbose` for every build line, grouped by
-stage and colored by severity. This applies to both the sandbox base image and
-the agent image. Colors honor `NO_COLOR` and normal terminal detection.
-The image reports listener readiness without repeating the host's summary or
-insecure warning; container startup and HTTP readiness are distinct messages.
-
-The HTML contains its JavaScript, React components and CSS; it needs no frontend
-server or CDN. It reuses ZeneraLite's chat messages, composer, tool cards and
-AG-UI reducer. It lists sessions, loads history, streams turns, follows active
-runs, cancels runs and deletes sessions. Connected-account actions still need
-zenera-app. Reopen the printed link after a page reload, or paste a dev JWT into
-the connection form: tokens are deliberately not saved in browser storage.
-
-Local files send `Origin: null`. Only insecure servers allow that origin and
-its GET/POST/DELETE preflights with Authorization and JSON headers; actual API
-requests still require a token. Secure servers do not enable this CORS access.
-A browser may ask you to allow local-network access.
-
-```ts
-import { createServer } from '@zenera/server';
-
-const server = createServer({
-    projectId: 'p1',
-    projectDir: '/project',
-    root: '/state',
-    auth: {
-        mode: 'jwt',
-        publicKey: process.env.ZEN_SERVER_JWT_PUBLIC_KEY!,
-        issuer: 'zenera-app',
-        audience: 'zenera-runtime',
-    },
-});
-await server.listen({ port: 3000, host: '0.0.0.0' });
+Open the printed HTTP `/chat` link to list sessions, send messages, follow active
+runs, cancel them, or delete a session. `--user` selects the development JWT's
+subject, not a server-wide user. The default is `local`.
+
+**Insecure mode is for local testing only:** anyone who can reach the server can
+impersonate any user. API requests still need a JWT, but signatures are not checked.
+The test page is available only in this mode. Its token stays in memory; after a
+reload, reopen the printed link or enter a development token again.
+
+To show full image build logs:
+
+```sh
+zen server start --insecure --container --user andrey --verbose
 ```
 
-## Who is calling: a JWT per request
-
-Every request but `/healthz` carries `Authorization: Bearer <jwt>`, signed by the
-host (zenera-app) for that one request with its Ed25519 key. The server holds
-only the public key (`--jwt-public-key <file>` or `$ZEN_SERVER_JWT_PUBLIC_KEY`),
-so neither it nor a sandboxed command that reaches its port can make one.
-
-| Claim                   | Checked                                                                     |
-| ----------------------- | --------------------------------------------------------------------------- |
-| alg                     | `EdDSA` only                                                                |
-| `iss`                   | `zenera-app` (`--jwt-issuer`)                                               |
-| `aud`                   | `zenera-runtime` (`--jwt-audience`)                                         |
-| `iat`                   | at most 2 minutes old, 30 s of clock skew                                   |
-| `prj`                   | this server's project id                                                    |
-| `req`                   | `"<METHOD> <url>"` of this very request: a token seen in transit is no good |
-| `sub`                   | the user, required                                                          |
-| `thr`                   | when there, must be the thread in the URL                                   |
-| `role`, `email`, `name` | when there, handed to the run as the user's (`zenera` library)              |
-
-Logging people in and deciding who may use which project stay in front of the
-server (zenera-app); the server only trusts what it signed.
-
-**`--insecure`** is for trying a server on your machine: tokens are read, not
-checked (any signature or none, any age, any project or request), but `sub` is
-still required — `zen server token --user ann` prints one. It listens on
-loopback only, and is refused inside the agent image unless whoever runs the
-container says so (`ZEN_SERVER_INSECURE_LOCAL=1`, which `--container` sets while
-publishing the port on loopback only).
-
-## Root: every user in a folder of their own
+Podman builds and caches the image. Default build output shows a spinner, elapsed
+time, and the latest line; warnings remain visible. Use `--rebuild` to rebuild.
+Press Ctrl+C to stop gracefully and save active runs.
+
+To run the server directly on the host instead, omit `--container`:
 
+```sh
+zen server start --insecure --user andrey
 ```
-<root>/server.json                                  {version, projectId}: this server's
-<root>/users/<user>/memory/                         the user's graph, shared by their chats
-<root>/users/<user>/sessions/<thread>/.data/        the session's state (its conversation)
-<root>/users/<user>/sessions/<thread>/runs/         the engine's record of each run
-<root>/users/<user>/sessions/<thread>/workspace/    what the agent reads and writes
-<root>/users/<user>/sessions/<thread>/agui/         each run's AG-UI events
+
+## Secure setup
+
+A trusted caller, usually Zenera-app, authenticates users, checks project access,
+and signs a short-lived JWT for each runtime request. The runtime holds **only
+the public key**.
+
+For a standalone caller, generate an Ed25519 pair outside the project directory:
+
+```sh
+zen server keygen --out "$HOME/runtime-auth"
+zen server start --jwt-public-key "$HOME/runtime-auth.public.pem"
+```
+
+`keygen` creates `<prefix>.private.pem` (PKCS#8, owner-only `0600` permissions)
+and `<prefix>.public.pem` (SPKI). The parent directory must already exist.
+Existing files are never overwritten; a failed write removes newly created files.
+Keep the private key with the trusted caller, out of source control and runtime
+containers. Zenera-app already manages its own signing identity; it does not need
+this command.
+
+Generating keys does **not** sign requests. Secure callers send an
+`Authorization: Bearer <jwt>` header containing an EdDSA-signed token with:
+
+- `iss` / `aud`: defaults `zenera-app` / `zenera-runtime`.
+- `sub`: the authenticated user; `prj`: this server's project ID.
+- `req`: the exact `"<METHOD> <path-and-query>"` of the request.
+- `iat` / `exp`: issue time and expiry; maximum age 2 minutes, 30 seconds clock tolerance.
+
+Use HTTPS at the ingress or a protected internal connection. A token cannot
+authorize a different endpoint, but can be replayed for the same request until
+it expires. The server does not perform user login or project-membership checks.
+
+## Commands
+
+| Command                            | Use                                                             |
+| ---------------------------------- | --------------------------------------------------------------- |
+| `zen server start`                 | Start a project's runtime.                                      |
+| `zen server check`                 | Check whether it can start in the current environment.          |
+| `zen server status`                | Inspect a running runtime; use `--token <jwt>` for secure mode. |
+| `zen server keygen --out <prefix>` | Generate private/public signing keys.                           |
+| `zen server token --user <id>`     | Print an **unsigned** development JWT for insecure mode.        |
+| `zen server build`                 | Build (and push) a release image; see below.                    |
+
+Test an API without the browser:
+
+```sh
+TOKEN=$(zen server token --user ann)
+curl http://127.0.0.1:3000/api/sessions \
+  -H "Authorization: Bearer $TOKEN"
 ```
 
-- `--root` / `$ZEN_SERVER_ROOT`, else `~/.zenera/neo/servers/<project>`; `/state`
-  in the agent image. `server.json` makes it one project's: a root of another
-  project, or of a newer layout, is refused.
-- `<user>` is `sub` as it is when it is a safe path segment (a UUID lower-cased),
-  else `u-<sha256>`. A thread is one path segment (letters, digits, `_`, `-`).
-- **Memory seed**: the first time a user needs a memory, it is copied from the
-  seed — the project's own (`memory:` in agents.yaml), `--memory-seed <dir>`, or
-  none (`--no-memory-seed`, everyone starts empty). From then on it is theirs:
-  their chats share it, other users never see it, and the seed is not read again.
-  The host CLI captures the initial seed at startup, including committed SQLite
-  WAL data and attached files. Later seed changes only affect the next server
-  start; existing user memories are never replaced.
-  With `--container`, this snapshot is mounted at `/seed:ro` in rollback-journal
-  mode, so SQLite can read it without creating WAL/SHM files on the read-only
-  project mount. The temporary snapshot is removed after the server stops
-  (also on failed startup); private user memories remain in the server root.
-  Snapshot file permissions allow image UID 10001 to read it even with rootful
-  podman; the private server root still controls host access.
-  If the container cannot be stopped, the CLI reports that error and retains
-  its snapshot rather than removing memory that the container may still need.
-
-## Routes
-
-| Route                                            | What                                                         |
-| ------------------------------------------------ | ------------------------------------------------------------ |
-| `GET /healthz`                                   | For probes; no token                                         |
-| `GET /api/status`                                | Versions, auth, sandbox (and why not), image identity, root  |
-| `GET /api/activity`                              | Whether a run is going, for idle stop                        |
-| `GET /api/sessions`                              | The caller's sessions, newest activity first                 |
-| `GET /api/sessions/:tid`                         | The chat so far, as AG-UI events                             |
-| `POST /api/sessions/:tid/runs`                   | A turn (or AG-UI `resume` entries), streamed as SSE          |
-| `GET /api/sessions/:tid/runs/:runId/events`      | Follow a run, or replay one that ended                       |
-| `POST /api/sessions/:tid/runs/:runId/cancel`     | Stop it                                                      |
-| `DELETE /api/sessions/:tid`                      | The thread and its files                                     |
-| `/api/sessions/:tid/{runs,…/trace,memory}` debug | With `debug: true` only: recorded runs, traces, memory graph |
-
-Every session route is the caller's own: `:tid` is looked up under their folder.
-The list returns `{ sessions: [{ id, title, createdAt, updatedAt, running }] }`;
-`running` is `{ runId }` or `null`, and titles come from the engine's session
-metadata (falling back to the ID). A thread-scoped token lists only its thread.
-Listing does not create sessions or memory. A new session is still created on
-its first turn.
-
-A run belongs to the server, not the request: it goes on when the caller leaves
-and can be followed again. At most `maxRuns` (`ZEN_RUNTIME_MAX_RUNS`, 4) run at
-once, `maxUserRuns` (`ZEN_RUNTIME_MAX_USER_RUNS`, 2) per user. An
-`x-zenera-mcp-token` header on a run is handed to the run's MCP plugin
-(`ZEN_PLUGINS`, `ZEN_MCP_BROKER_URL`).
-
-## Sandbox
-
-Chosen once, at start:
-
-- **podman** — anywhere but the agent image, as `zen run`: a container per
-  session on this machine. `zen server start` readies podman as `zen run` does,
-  and a turn pulls or builds the image it needs.
-- **bwrap** — inside the agent image, which ships `/opt/zenera/bin/bwrap` and is
-  itself the container: each command under bubblewrap. Commands see the image
-  (what the project's `sandbox/Dockerfile` installed, with its `ENV`), their own
-  workspace and home, and the `zenera` library; never the root (other chats,
-  other users, memories), the seed, the zen home, the project (its `.env`), the
-  server's install, `/state` or `/run/secrets`.
-
-`--sandbox` or `$ZEN_SERVER_SANDBOX` overrides the choice; `createServer` takes
-`sandbox: 'podman' | 'bwrap' | factory` and an optional `preflight`. A sandbox
-plugin in `ZEN_PLUGINS` never replaces it.
-
-The `zenera` library (Python and Node: `identity()`, `require_identity()`) is one
-shared read-only directory mounted at `/opt/zenera/runtime` for every session —
-built into the agent image, or written once per content under the zen home.
-
-`zen server start` refuses to listen when commands have nowhere to run (podman
-not answering, bwrap unable to isolate), when the image was built for another
-project environment (`ZEN_IMAGE_BUILD` / `ZEN_IMAGE_BASE`), or when the root is
-another project's.
-
-## `--container`
-
-`zen server start --container` runs the server in the project's agent image on
-this machine, with podman:
-
-1. The project's sandbox image is readied as for `zen run` (`sandbox/Dockerfile`).
-2. The agent image is built on it: this zen's packages (`npm pack` of the ones
-   installed), Node in `/opt/zenera`, a static bwrap, the `zenera` library, the
-   sandbox image's `ENV` (so commands get it under bwrap). Tagged
-   `localhost/zenera-agent:<hash>`; built again only when something changed, or
-   with `--rebuild`.
-3. `podman run`: the project read-only at `/project`, the root at `/state`, the
-   port published on `--host` (loopback by default), the auth flags and model
-   keys and provider settings passed through by environment name, credential files
-   mounted as private Podman secrets, logs followed;
-   Ctrl-C stops it.
-
-The server runs as numeric UID/GID **10001**, with `HOME=/home/zenera`, not
-as root or as the sandbox base image's `USER`. Commands inherit that UID unless
-the project's sandbox config explicitly selects another user. Rootless podman
-uses `--userns keep-id:uid=10001,gid=10001`: existing host-owned state stays
-writable, without changing its ownership. With rootful podman, the host must
-provide a state directory writable by UID/GID 10001; ownership is not changed
-automatically. Project and seed mounts must also be readable by that user.
-The container drops all capabilities and disables privilege escalation;
-bwrap uses unprivileged user namespaces.
-
-For Kubernetes, set `runAsNonRoot: true`, `runAsUser: 10001`,
-`runAsGroup: 10001`, `fsGroup: 10001` for the state PVC, and
-`allowPrivilegeEscalation: false` with all capabilities dropped. The node's
-security policy must allow bwrap's unprivileged user namespaces; startup
-reports a failed probe rather than running commands without isolation.
-
-Model keys come from the keyring (`zen key …`) and the environment, as for any
-run, including the project's `.env`; in the agent image, the environment.
-Vertex project, location and quota project, and the Bifrost endpoint, are forwarded
-alongside keys. Explicit `GOOGLE_APPLICATION_CREDENTIALS` takes precedence over
-ambient gcloud application-default credentials.
-
-File credentials use ephemeral Podman secrets readable only by UID 10001. The
-server stages them in its private container home before opening engines, allowing
-bwrap to bind container-owned files when the project's keys policy permits it.
-They are not embedded in the image, argv, workspaces or persistent user state.
-Secrets are removed after confirmed shutdown or failed startup; a failed stop
-retains them and the memory seed until the container can be stopped. Failed secret
-cleanup is reported with a manual removal command.
-
-## Rebuilding the standalone page
-
-The source and build live in ZeneraLite's `services/zenera-app`. Run there:
+`token` also accepts `--email`, `--role`, `--name`, and `--thread`. It neither
+creates an account nor signs a secure token.
+
+## Common options
+
+| Option                            | Use / default                                                          |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `--project <name-or-dir>`         | Select a project; otherwise use the current project.                   |
+| `--port <n>` / `--host <addr>`    | `3000` / `127.0.0.1`. Insecure mode is loopback-only.                  |
+| `--root <dir>`                    | Persistent user state; `~/.zenera/neo/servers/<project>` on the host.  |
+| `--memory-seed <dir>`             | Initial memory for new users; defaults to project memory.              |
+| `--no-memory-seed`                | Start new users with empty memory.                                     |
+| `--jwt-public-key <file>`         | Public PEM for secure mode; alternatively `ZEN_SERVER_JWT_PUBLIC_KEY`. |
+| `--jwt-issuer` / `--jwt-audience` | Override the expected signer / audience.                               |
+| `--container`                     | Run the server in the project image; commands use bwrap.               |
+| `--verbose` / `--rebuild`         | Full container build logs / rebuild images.                            |
+| `--debug`                         | Enable run, trace, and memory inspection routes.                       |
+
+Run `zen server --help` for all options. Sessions and memory live under
+`<root>/users/<user>/`; memory is private per user and shared across their sessions.
+New users receive the memory seed captured at startup. Existing user memory is
+never replaced by a restart.
+
+Model credentials come from `zen key`, the environment, and the project's `.env`.
+Container mode forwards provider settings, including Vertex and Bifrost, and
+credential files. The gateway must be reachable from the container; host
+`localhost` is not container `localhost`.
+Set `sandbox.keys: false` to withhold credentials from agent-written commands,
+while allowing the engine to use them for model calls.
+
+## Release images
+
+`zen server build` bakes a project into an immutable image for Kubernetes and
+prints its digest (or the local tag when not pushed):
 
 ```sh
-npm run build:chat -- --output /path/to/ZeneraNeo/packages/cli/assets/chat.html
+zen server build --project p1 --release r42 \
+  --push registry.local:5000/agent-p1:r42 [--authfile auth.json] [--insecure-registry]
 ```
 
-Without `--output`, the result is `dist/chat.html`. If a sibling `../ZeneraNeo`
-checkout exists next to ZeneraLite, the build also copies the result into its
-`packages/cli/assets/chat.html` automatically, including when `--output` is used.
-Without that sibling, only the requested output is written. The CLI package includes
-the compiled asset; ZeneraNeo needs no frontend build dependencies.
+The image is the agent image plus the project at `/project`, its memory seed at
+`/seed` (`--memory-seed <dir>` / `--no-memory-seed`), `ZEN_RELEASE` and
+`ZEN_PROJECT_ID`. The release id defaults to `r-<content hash>`; `--json` prints
+`{release, image, agentImage, base, built, ref, digest}`.
+
+Never baked in: `.env*` (except `.env.example`), `sessions/`, `.git`,
+`node_modules`, `.tmp/`, or the live memory directory. Deployment settings (JWT public key, MCP
+plugin, Bifrost URL/key, storage) are passed at deploy time via environment
+variables or a ConfigMap. Use `--add <src>:<dest>` (repeatable) to add large
+content such as plugins, e.g. `--add ./plugins:/opt/zenera/plugins`.
+
+## Many servers per project
+
+Several servers can serve one project when users' data lives in a store rather
+than on one disk. Name a store module with `ZEN_STATE_STORE` (ZeneraLite ships an
+S3 store as `state.mjs`). The server then:
+
+- loads a user's data before their first request, and a chat's files when it is opened;
+- saves them after every run, after deletions, every `ZEN_STATE_CHECKPOINT_SECONDS`
+  (300) while runs go on, when released, and on shutdown;
+- refuses a token whose `gen` (lease generation) is older than the one it holds,
+  and drops its copy when the store reports that a newer lease saved the user.
+
+The host manages users through `/api/admin` with tokens for its own subject
+(`ZEN_SERVER_SYSTEM_SUBJECT`, default `zenera-app`):
+
+| Route                                 | Use                                                       |
+| ------------------------------------- | --------------------------------------------------------- |
+| `GET /api/admin/users[?usage=1]`      | Users here: lease, runs, unsaved changes, disk use.       |
+| `POST /api/admin/users/:sub/release`  | Save and let go of one user; `409 busy` while runs go on. |
+| `POST /api/admin/drain[?timeout=600]` | No new users; release each one as their runs end.         |
+| `POST /api/admin/undrain`             | Take new users again.                                     |
+
+Soft limits for many users per pod:
+
+| Variable                   | Limit                                                      |
+| -------------------------- | ---------------------------------------------------------- |
+| `ZEN_RUNTIME_USER_DISK_MB` | Per-user disk; over it, no new runs and running ones stop. |
+| `ZEN_RUNTIME_NICE`         | Lower CPU priority for commands (default 10).              |
+| `ZEN_RUNTIME_MAX_FILE_MB`  | Largest file a command may write.                          |
+| `ZEN_RUNTIME_TMP_MB`       | Size of each command's `/tmp` (it uses memory).            |
+
+These are soft. Hard limits come from the pod: CPU, memory, and a fixed-size
+volume for `/state`.
+
+## HTTP API
+
+Session routes operate only on the JWT subject's own sessions.
+
+| Route                                          | Use                                            |
+| ---------------------------------------------- | ---------------------------------------------- |
+| `GET /healthz`                                 | Public health probe.                           |
+| `GET /chat`                                    | Public test page, insecure mode only.          |
+| `GET /api/status` / `GET /api/activity`        | Runtime status / active runs.                  |
+| `GET /api/sessions` / `GET /api/sessions/:tid` | List sessions / load history.                  |
+| `POST /api/sessions/:tid/runs`                 | Start a turn, streaming AG-UI events over SSE. |
+| `GET /api/sessions/:tid/runs/:runId/events`    | Follow or replay a run.                        |
+| `POST /api/sessions/:tid/runs/:runId/cancel`   | Cancel a run.                                  |
+| `DELETE /api/sessions/:tid`                    | Delete a session and its files.                |
+
+Runs continue after a client disconnects and can be followed again. Defaults:
+4 concurrent runs total, 2 per user (`ZEN_RUNTIME_MAX_RUNS`,
+`ZEN_RUNTIME_MAX_USER_RUNS`).
+
+For deployment and sandbox details, see [agent-image architecture](../../docs/agent-image.md).
+To rebuild the bundled test page, run `npm run build:chat` from ZeneraLite's root;
+it automatically copies the page into a sibling ZeneraNeo checkout when present.

package/dist/auth.d.ts

@@ -8,6 +8,8 @@ export interface CallerClaims extends JWTPayload {
     role?: string;
     email?: string;
     name?: string;
+    /** the host's lease generation for this user on this server (userState.ts) */
+    gen?: number;
 }
 export declare function verifyCaller(req: Request): Promise<CallerClaims>;
 export declare function requireCaller(): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { SandboxSetup, ZenPlugin } from '@zenera/engine';
-import { type SandboxFactory } from '@zenera/sandbox';
+import { type CommandLimits, type SandboxFactory } from '@zenera/sandbox';
+import type { UserStateStore } from './userState.ts';
 export type ServerAuth = 
 /** EdDSA tokens signed per request by the host (zenera-app), checked with its public key */
 {
@@ -50,6 +51,19 @@ export interface ServerSettings {
     maxUserRuns: number;
     maxRunMinutes: number;
     runLogMaxBytes: number;
+    /**
+     * Where users' data lives beyond this disk (userState.ts): loaded before their first request,
+     * saved at safe points, released on the host's word. Unset: only here (`localStore`).
+     */
+    stateStore?: UserStateStore;
+    /** how often users with runs going (or a failed save) are saved again; 0: never */
+    checkpointSeconds: number;
+    /** the `sub` of the host's own calls, the only one /api/admin answers */
+    systemSubject: string;
+    /** soft limit on one user's folder; over it, no new runs and running ones stop; 0: none */
+    userDiskQuotaBytes: number;
+    /** what each bwrap command is held to: priority, largest file, size of its /tmp; 0: none */
+    commandLimits: CommandLimits;
 }
 /**
  * bwrap inside the agent image, which ships it at /opt/zenera/bin/bwrap; podman anywhere else,

package/dist/config.js

@@ -30,6 +30,10 @@ export const DEFAULTS = {
     maxUserRuns: 2,
     maxRunMinutes: 120,
     runLogMaxBytes: 50 * 1024 * 1024,
+    checkpointSeconds: 300,
+    systemSubject: DEFAULT_ISSUER,
+    userDiskQuotaBytes: 0,
+    commandLimits: { nice: 10, fileSizeBytes: 0, tmpBytes: 0 },
 };
 let current;
 export function configure(settings) {

package/dist/http.js

@@ -21,6 +21,10 @@ export function errorHandler(err, req, res, _next) {
     const status = err instanceof HttpError ? err.status : (err?.status ?? 500);
     if (status >= 500)
         console.error(`${req.method} ${req.originalUrl}:`, err);
-    res.status(status).json({ error: errorMessage(err) });
+    const code = err?.code;
+    res.status(status).json({
+        error: errorMessage(err),
+        ...(err instanceof HttpError && typeof code === 'string' ? { code } : {}),
+    });
 }
 //# sourceMappingURL=http.js.map

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { requireCaller, unsignedToken, verifyCaller, type CallerClaims } from '.
 export { identify, runUser, userFolder, type Identity } from './identity.ts';
 export { LAYOUT_VERSION, LayoutError, openLayout, type Layout } from './layout.ts';
 export { privateStore, memoryDir, memorySeed, userDir, userMemory, SEED_FILE, usesMemory, imageReady, openEngineFor, statusFor, errorMessage, asHttpError, type ChatStore, type ChatThread, } from './store.ts';
-export { runsRouter, runDebugRouter, activeRuns, currentRun, stopAllRuns } from './runs.ts';
+export { runsRouter, runDebugRouter, activeRuns, currentRun, ownerRuns, stopAllRuns, stopOwnerRuns, } from './runs.ts';
 export { historyRouter, toMessages } from './history.ts';
 export { traceRouter, openTrace, stepParam } from './trace.ts';
 export { memoryRouter } from './memory.ts';
@@ -13,6 +13,7 @@ export { RunLog, compact, readRunLog, threadRunLogs } from './runLog.ts';
 export * from './runRecords.ts';
 export { applyProjectEnv, withoutProjectEnv } from './projectEnv.ts';
 export { HttpError, errorHandler, notFound } from './http.ts';
-export { envRunPlugins } from './plugins.ts';
+export { envRunPlugins, envServerLimits, envStateStore, type StateStoreOptions, } from './plugins.ts';
+export { localStore, StaleGenerationError, USER_LAYOUT, userStates, userUsageBytes, type CheckpointReason, type UserInfo, type UserRef, type UserSnapshot, type UserStateStore, } from './userState.ts';
 export { serverStatus, startupErrors, type ServerStatus } from './status.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -6,7 +6,7 @@ export { requireCaller, unsignedToken, verifyCaller } from "./auth.js";
 export { identify, runUser, userFolder } from "./identity.js";
 export { LAYOUT_VERSION, LayoutError, openLayout } from "./layout.js";
 export { privateStore, memoryDir, memorySeed, userDir, userMemory, SEED_FILE, usesMemory, imageReady, openEngineFor, statusFor, errorMessage, asHttpError, } from "./store.js";
-export { runsRouter, runDebugRouter, activeRuns, currentRun, stopAllRuns } from "./runs.js";
+export { runsRouter, runDebugRouter, activeRuns, currentRun, ownerRuns, stopAllRuns, stopOwnerRuns, } from "./runs.js";
 export { historyRouter, toMessages } from "./history.js";
 export { traceRouter, openTrace, stepParam } from "./trace.js";
 export { memoryRouter } from "./memory.js";
@@ -15,6 +15,7 @@ export { RunLog, compact, readRunLog, threadRunLogs } from "./runLog.js";
 export * from "./runRecords.js";
 export { applyProjectEnv, withoutProjectEnv } from "./projectEnv.js";
 export { HttpError, errorHandler, notFound } from "./http.js";
-export { envRunPlugins } from "./plugins.js";
+export { envRunPlugins, envServerLimits, envStateStore, } from "./plugins.js";
+export { localStore, StaleGenerationError, USER_LAYOUT, userStates, userUsageBytes, } from "./userState.js";
 export { serverStatus, startupErrors } from "./status.js";
 //# sourceMappingURL=index.js.map

package/dist/plugins.d.ts

@@ -1,5 +1,24 @@
 import type { ZenPlugin } from '@zenera/engine';
+import { type ServerSettings } from './config.ts';
+import { USER_LAYOUT, type UserStateStore } from './userState.ts';
 export declare function envRunPlugins(env?: NodeJS.ProcessEnv): (run: {
     mcpToken: string | null;
 }) => Promise<ZenPlugin[]>;
+/** What a state store module is given: who it serves, and the user folder's layout. */
+export interface StateStoreOptions {
+    projectId: string;
+    root: string;
+    layout: typeof USER_LAYOUT;
+    env: NodeJS.ProcessEnv;
+    log: {
+        info(message: string): void;
+        warn(message: string): void;
+    };
+}
+/** The store `ZEN_STATE_STORE` names, made and checked; a broken one stops the server starting. */
+export declare function envStateStore(env: NodeJS.ProcessEnv, at: {
+    projectId: string;
+    root: string;
+}): Promise<UserStateStore | undefined>;
+export declare function envServerLimits(env: NodeJS.ProcessEnv): Pick<ServerSettings, 'checkpointSeconds' | 'systemSubject' | 'userDiskQuotaBytes' | 'commandLimits'>;
 //# sourceMappingURL=plugins.d.ts.map