@zenera/server 0.0.0-stage → 1.2.0

package/dist/status.d.ts

@@ -0,0 +1,56 @@
+import { type ProcMode } from '@zenera/sandbox';
+import { type ServerSettings } from './config.ts';
+export interface ServerStatus {
+    server: string;
+    zen: {
+        engine?: string;
+        neo?: string;
+        sandbox?: string;
+    };
+    node: string;
+    project: {
+        id: string;
+        dir: string;
+    };
+    /** jwt: the host's signed tokens; insecure: read, not checked */
+    auth: ServerSettings['auth']['mode'];
+    /** where it listens, host:port; unset before it does */
+    listen?: string;
+    debug: boolean;
+    sandbox: {
+        provider: string;
+        /** bwrap: how commands get /proc, or why they cannot be isolated */
+        proc?: ProcMode;
+        ok: boolean;
+        error?: string;
+        hint?: string;
+    };
+    image: {
+        /** what this container was built from (ZEN_IMAGE_BUILD / ZEN_IMAGE_BASE) */
+        build?: string;
+        base?: string;
+        release?: string;
+        /** what the project's sandbox config asks for */
+        wants: {
+            build?: string;
+            image?: string;
+        };
+        matches?: boolean;
+        error?: string;
+    };
+    /** where every user's things are: users/<user>/{sessions,memory} */
+    root: {
+        dir: string;
+        version?: number;
+        supported: number;
+        error?: string;
+    };
+    /** what each user's memory starts as, when there is anything */
+    memorySeed?: string;
+}
+/** Where the server listens, for the report. */
+export declare function setListening(where: string | undefined): void;
+export declare function serverStatus(env?: NodeJS.ProcessEnv): Promise<ServerStatus>;
+/** Why the server must not start, if anything. An image that was never labelled is not one. */
+export declare function startupErrors(status: ServerStatus): string[];
+//# sourceMappingURL=status.d.ts.map

package/dist/status.js

@@ -0,0 +1,127 @@
+// What the server can say about itself without being asked anything: `/api/status`, and the
+// checks `zen server start` makes before it listens (`zen server check` prints them).
+//   serverStatus  - versions, auth, sandbox, image identity, where users' things and the seed are
+//   startupErrors - the reasons not to start: nowhere to run commands, the wrong image, a root
+//                   that is not this server's
+import { resolveBuild } from '@zenera/engine';
+import { readProjectConfig } from '@zenera/neo';
+import { IMAGE_BASE_ENV, IMAGE_BUILD_ENV, probeBwrap, runProcess, } from '@zenera/sandbox';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { settings } from "./config.js";
+import { LAYOUT_VERSION, openLayout } from "./layout.js";
+import { memorySeed } from "./store.js";
+const require = createRequire(import.meta.url);
+function versionOf(pkg) {
+    try {
+        const at = require.resolve(`${pkg}/package.json`);
+        return JSON.parse(readFileSync(at, 'utf8')).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+let listening;
+/** Where the server listens, for the report. */
+export function setListening(where) {
+    listening = where;
+}
+/** Whether podman answers: the machine running, on the platforms that have one. */
+async function probePodman() {
+    try {
+        const info = await runProcess('podman', ['info', '--format', '{{.Host.OS}}'], {
+            timeoutMs: 30_000,
+        });
+        if (info.code === 0)
+            return { ok: true };
+        return {
+            ok: false,
+            error: `podman is not responding: ${(info.stderr.trim() || `exit ${info.code}`).split('\n')[0]}`,
+            hint: process.platform === 'linux' ? undefined : 'podman machine start',
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+            hint: 'install podman, or run the server in the agent image (bwrap)',
+        };
+    }
+}
+export async function serverStatus(env = process.env) {
+    const s = settings();
+    const sandbox = { provider: s.sandboxProvider, ok: true };
+    if (s.sandbox === 'podman') {
+        Object.assign(sandbox, await probePodman());
+    }
+    else if (s.sandbox === 'bwrap') {
+        const probe = await probeBwrap();
+        Object.assign(sandbox, {
+            ok: probe.ok,
+            proc: probe.proc,
+            error: probe.error,
+            hint: probe.hint,
+        });
+    }
+    const image = {
+        build: env[IMAGE_BUILD_ENV]?.trim() || undefined,
+        base: env[IMAGE_BASE_ENV]?.trim() || undefined,
+        release: env.ZEN_RELEASE?.trim() || undefined,
+        wants: {},
+    };
+    try {
+        const { root, config } = readProjectConfig(s.projectDir);
+        const build = resolveBuild(root, config.sandbox);
+        image.wants = build ? { build: build.hash } : { image: config.sandbox?.image };
+        if (image.build || image.base) {
+            image.matches = build
+                ? image.build === build.hash
+                : image.base === (config.sandbox?.image ?? image.base);
+        }
+    }
+    catch (err) {
+        image.error = err instanceof Error ? err.message : String(err);
+    }
+    const root = { dir: s.root, supported: LAYOUT_VERSION };
+    try {
+        root.version = openLayout(s.root, s.projectId, { create: false })?.version;
+    }
+    catch (err) {
+        root.error = err instanceof Error ? err.message : String(err);
+    }
+    return {
+        server: versionOf('@zenera/server') ?? 'unknown',
+        zen: {
+            engine: versionOf('@zenera/engine'),
+            neo: versionOf('@zenera/neo'),
+            sandbox: versionOf('@zenera/sandbox'),
+        },
+        node: process.versions.node,
+        project: { id: s.projectId, dir: s.projectDir },
+        auth: s.auth.mode,
+        ...(listening ? { listen: listening } : {}),
+        debug: s.debug,
+        sandbox,
+        image,
+        root,
+        ...(memorySeed() ? { memorySeed: memorySeed() } : {}),
+    };
+}
+/** Why the server must not start, if anything. An image that was never labelled is not one. */
+export function startupErrors(status) {
+    const errors = [];
+    if (!status.sandbox.ok) {
+        errors.push(`commands have nowhere to run: ${status.sandbox.error}` +
+            (status.sandbox.hint ? ` (${status.sandbox.hint})` : ''));
+    }
+    if (status.image.error)
+        errors.push(`the project cannot be read: ${status.image.error}`);
+    if (status.root.error)
+        errors.push(status.root.error);
+    if (status.image.matches === false) {
+        errors.push(`the image was built for another project environment: ${status.image.build ?? status.image.base}, ` +
+            `the project asks for ${status.image.wants.build ?? status.image.wants.image} (rebuild it: zen image build)`);
+    }
+    return errors;
+}
+//# sourceMappingURL=status.js.map

package/dist/store.d.ts

@@ -0,0 +1,52 @@
+import { type Engine, type RunIdentity, type SandboxSetup, type SessionPaths } from '@zenera/engine';
+import type { Request } from 'express';
+export interface ChatThread {
+    id: string;
+    /** who the thread's runs count against: a user, or the project for shared chats */
+    owner: string;
+}
+export interface ChatStore {
+    /** The thread a request names, checked to be the caller's; throws an HttpError otherwise. */
+    thread(req: Request): ChatThread;
+    existingSession(t: ChatThread): SessionPaths | null;
+    /** The session, created on the thread's first turn. */
+    sessionFor(t: ChatThread): SessionPaths;
+    /** The thread's run logs and run records. */
+    runsDir(t: ChatThread): string;
+    /** The graph the memory explorer reads; undefined when the project declares none. */
+    memoryDir(t: ChatThread): string | undefined;
+    /** The graph a run remembers into, ready; undefined lets the engine use the project's. */
+    engineMemoryDir(t: ChatThread): Promise<string | undefined>;
+    removeThread(t: ChatThread): Promise<void>;
+    /**
+     * How many runs one owner may have going at once. Memory does not lower it: the graph is a
+     * SQLite database that several runs remember into at the same time.
+     */
+    maxOwnerRuns: number;
+    /** Why a run is refused when the owner has that many going. */
+    ownerBusy: string;
+}
+/** Where one user's things are. */
+export declare function userDir(user: string): string;
+/** The user's graph, whether or not it has been made yet. */
+export declare function memoryDir(user: string): string;
+/** What a user's memory starts as: the server's seed, else the project's own graph. */
+export declare function memorySeed(): string | undefined;
+/**
+ * The user's graph, made first from the seed when they have none: a consistent copy of it
+ * (`copyMemory`, the seed opened read-only) into a directory of its own, renamed into place, so
+ * a crash never leaves half a graph and two first runs at once make one. No seed, or one not made
+ * yet: the user starts with nothing, and their first run makes their graph.
+ */
+export declare function userMemory(user: string): Promise<string>;
+/** Beside a user's graph: which seed it was copied from, and when. */
+export declare const SEED_FILE = "seed.json";
+export declare const privateStore: ChatStore;
+export declare function usesMemory(): boolean;
+export declare function imageReady(setup: SandboxSetup): Promise<void>;
+export declare function openEngineFor(session: SessionPaths, memoryDir: string | undefined, user: RunIdentity | null, mcpToken?: string | null): Promise<Engine>;
+/** The HTTP status for a zen exit code or EngineError code. */
+export declare function statusFor(code: number): number;
+export declare function errorMessage(err: unknown): string;
+export declare function asHttpError(err: unknown): unknown;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.js

@@ -0,0 +1,203 @@
+// Where a chat's session, run logs and memory live, and the engine opened on one for a turn.
+// The chat code (runs.ts, history.ts, trace.ts, memory.ts) is the same for every kind of chat; a
+// ChatStore says where a thread's things are and who it belongs to.
+//   privateStore - each user's chats, under that user's own folder:
+//     <root>/users/<user>/sessions/<thread id>/  - one zen session per chat thread, as `zen run`
+//                                                  keeps one: .data/ (state), runs/ (the engine's
+//                                                  records), workspace/, and agui/ (its runs'
+//                                                  AG-UI events, runLog.ts — never in the
+//                                                  sandbox's view)
+//     <root>/users/<user>/memory/                - the user's graph: a copy of the seed, made the
+//                                                  first time a run of theirs remembers, shared by
+//                                                  all their sessions and nobody else's
+//     A thread id is only ever looked up under its caller's own folder, so another user's
+//     thread is simply not there.
+//   userMemory                  - the user's graph, copied from the seed first if it has to be
+//   ChatStore, ChatThread       - the contract (a host may serve other chats with it: the Test tab)
+//   usesMemory                  - whether any agent remembers, so the memory explorer has a graph
+//   openEngineFor               - the project wired to a session, memory and the user the run acts
+//                                 for, its env file applied
+//   errorMessage, asHttpError   - what an EngineError says, and means to an HTTP caller
+import { createSessionAt, home, EngineError, EXIT, openEngine, sessionPathsAt, } from '@zenera/engine';
+import { copyMemory, isMemory, LEGACY_GRAPH_FILE, memoryDir as projectMemoryDir, readProjectConfig, } from '@zenera/neo';
+import { existsSync } from 'node:fs';
+import { rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BwrapSandbox } from '@zenera/sandbox';
+import { settings } from "./config.js";
+import { HttpError } from "./http.js";
+import { identify } from "./identity.js";
+import { applyProjectEnv } from "./projectEnv.js";
+/** Where one user's things are. */
+export function userDir(user) {
+    return join(settings().root, 'users', user);
+}
+const sessionDir = (t) => join(userDir(t.owner), 'sessions', t.id);
+/** The user's graph, whether or not it has been made yet. */
+export function memoryDir(user) {
+    return join(userDir(user), 'memory');
+}
+/** What a user's memory starts as: the server's seed, else the project's own graph. */
+export function memorySeed() {
+    const s = settings();
+    if (s.memorySeed === null)
+        return undefined;
+    if (s.memorySeed)
+        return s.memorySeed;
+    try {
+        const { root, config } = readProjectConfig(s.projectDir);
+        return projectMemoryDir(root, config);
+    }
+    catch {
+        return undefined;
+    }
+}
+const copying = new Map();
+/**
+ * The user's graph, made first from the seed when they have none: a consistent copy of it
+ * (`copyMemory`, the seed opened read-only) into a directory of its own, renamed into place, so
+ * a crash never leaves half a graph and two first runs at once make one. No seed, or one not made
+ * yet: the user starts with nothing, and their first run makes their graph.
+ */
+export function userMemory(user) {
+    const dir = memoryDir(user);
+    const pending = copying.get(dir);
+    if (pending)
+        return pending;
+    const made = (async () => {
+        if (existsSync(dir))
+            return dir;
+        const seed = memorySeed();
+        if (seed && !isMemory(seed) && existsSync(join(seed, LEGACY_GRAPH_FILE))) {
+            throw new EngineError(`the memory seed ${seed} holds a version 1 memory`, EXIT.invalid, `convert it first: zen memory migrate --dir ${seed}`);
+        }
+        if (!seed || !isMemory(seed))
+            return dir;
+        const tmp = `${dir}.copy-${process.pid}-${Date.now()}`;
+        try {
+            await copyMemory(seed, tmp);
+            await writeFile(join(tmp, SEED_FILE), `${JSON.stringify({ seed, copiedAt: new Date().toISOString() }, null, 2)}\n`);
+            await rename(tmp, dir);
+        }
+        finally {
+            await rm(tmp, { recursive: true, force: true });
+        }
+        return dir;
+    })().finally(() => copying.delete(dir));
+    copying.set(dir, made);
+    return made;
+}
+/** Beside a user's graph: which seed it was copied from, and when. */
+export const SEED_FILE = 'seed.json';
+export const privateStore = {
+    thread(req) {
+        const id = identify(req);
+        return { id: id.threadId, owner: id.userId };
+    },
+    existingSession(t) {
+        const p = sessionPathsAt(sessionDir(t));
+        return existsSync(p.meta) ? p : null;
+    },
+    sessionFor(t) {
+        const dir = sessionDir(t);
+        return this.existingSession(t) ?? createSessionAt(dir, join(dir, 'workspace'));
+    },
+    runsDir: (t) => join(sessionDir(t), 'agui'),
+    memoryDir: (t) => memoryDir(t.owner),
+    engineMemoryDir: (t) => userMemory(t.owner),
+    async removeThread(t) {
+        await rm(sessionDir(t), { recursive: true, force: true });
+    },
+    get maxOwnerRuns() {
+        return settings().maxUserRuns;
+    },
+    ownerBusy: 'your other chats are still answering',
+};
+export function usesMemory() {
+    try {
+        return readProjectConfig(settings().projectDir).config.agents.some((a) => Boolean(a.memory));
+    }
+    catch (err) {
+        throw new EngineError(err instanceof Error ? err.message : String(err), EXIT.invalid);
+    }
+}
+// A turn must not start a build of its own: the image is built ahead (the editor, `zen image
+// build`). Whichever sandbox the run gets, it says how its image is made ready.
+export async function imageReady(setup) {
+    try {
+        await setup.sandbox.prepare({ allowBuild: false });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const notBuilt = /is not built/.test(message);
+        throw new EngineError(notBuilt
+            ? `the sandbox image ${setup.image} is not built`
+            : `the sandbox image is not ready: ${message}`, EXIT.sandbox, notBuilt ? 'rebuild it from the project editor' : err.hint);
+    }
+}
+/** Where the agent image installs zen and the server. */
+const AGENT_APP_DIR = '/opt/zenera/app';
+/** The factory a run's engine opens its sandbox with. */
+function sandboxFactory(s) {
+    if (s.sandbox !== 'bwrap')
+        return s.sandbox;
+    // Every user's chats and graphs, the seed (the server's to read and write, through its
+    // tools), the zen home (its keyring), the project (its .env) and, in the agent image, the
+    // server's own install are not the command's; its own workspace and home are bound back in.
+    const seed = memorySeed();
+    const hidden = [
+        s.root,
+        ...(seed ? [seed] : []),
+        home(),
+        s.projectDir,
+        ...(existsSync(AGENT_APP_DIR) ? [AGENT_APP_DIR] : []),
+        ...s.hidden,
+    ];
+    return (opts) => new BwrapSandbox(opts, { hidden });
+}
+export async function openEngineFor(session, memoryDir, 
+// Who the run acts for; null is nobody, and stops the engine reading ZEN_USER_* from this process.
+user, 
+// The run's MCP broker token from zenera-app, if it gave one.
+mcpToken = null) {
+    const s = settings();
+    applyProjectEnv();
+    const plugins = await s.plugins({ mcpToken });
+    return openEngine({
+        project: { dir: s.projectDir, name: s.projectId },
+        session,
+        memoryDir,
+        user,
+        quiet: true,
+        yes: true,
+        // Each turn's sandbox goes away; the sandbox HOME is in the session folder and stays.
+        disposable: true,
+        logger: { warn: (message) => console.warn(`[engine] ${message}`) },
+        preflight: s.preflight ?? imageReady,
+        // The sandbox is the server's to choose: a plugin in ZEN_PLUGINS does not get to replace it.
+        sandboxPlugins: false,
+        ...(s.sandbox === 'podman' ? {} : { newSandbox: sandboxFactory(s) }),
+        ...(plugins.length ? { plugins } : {}),
+    });
+}
+const STATUS = {
+    [EXIT.usage]: 400,
+    [EXIT.invalid]: 422,
+    [EXIT.credentials]: 503,
+    [EXIT.sandbox]: 503,
+};
+/** The HTTP status for a zen exit code or EngineError code. */
+export function statusFor(code) {
+    return STATUS[code] ?? 500;
+}
+export function errorMessage(err) {
+    if (err instanceof EngineError)
+        return err.hint ? `${err.message} (${err.hint})` : err.message;
+    return err instanceof Error ? err.message : String(err);
+}
+export function asHttpError(err) {
+    if (!(err instanceof EngineError))
+        return err;
+    return new HttpError(statusFor(err.code), errorMessage(err));
+}
+//# sourceMappingURL=store.js.map

package/dist/token.d.ts

@@ -0,0 +1,14 @@
+export declare const TOKEN_ENV = "ZEN_SERVER_TOKEN";
+export declare const MIN_TOKEN_LENGTH = 32;
+export interface ServerToken {
+    token: string;
+    /** where it came from: the environment, or the file */
+    from: 'env' | string;
+}
+/** Where a project's server for a user keeps its token. Both are single path segments here. */
+export declare function tokenFile(project: string, user: string): string;
+export declare function serverToken(file: string, opts?: {
+    create?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): ServerToken | undefined;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.js

@@ -0,0 +1,30 @@
+// The server's bearer token, when its host gave none: one per project and user, in the zen home
+// (which no sandboxed command can see), readable by its owner only.
+//   tokenFile    - <zen home>/servers/<project>/<user>.token
+//   serverToken  - $ZEN_SERVER_TOKEN, else the file, else a new one written there (`create`)
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { home } from '@zenera/engine';
+import { dirname, join } from 'node:path';
+export const TOKEN_ENV = 'ZEN_SERVER_TOKEN';
+export const MIN_TOKEN_LENGTH = 32;
+/** Where a project's server for a user keeps its token. Both are single path segments here. */
+export function tokenFile(project, user) {
+    const segment = (s) => s.replace(/[^\w.@-]/g, '_');
+    return join(home(), 'servers', segment(project), `${segment(user)}.token`);
+}
+export function serverToken(file, opts = {}) {
+    const given = (opts.env ?? process.env)[TOKEN_ENV]?.trim();
+    if (given)
+        return { token: given, from: 'env' };
+    if (existsSync(file))
+        return { token: readFileSync(file, 'utf8').trim(), from: file };
+    if (!opts.create)
+        return undefined;
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const token = randomBytes(32).toString('base64url');
+    writeFileSync(file, `${token}\n`, { mode: 0o600, flag: 'wx' });
+    chmodSync(file, 0o600);
+    return { token, from: file };
+}
+//# sourceMappingURL=token.js.map

package/dist/trace.d.ts

@@ -0,0 +1,84 @@
+import { PayloadResolver, type AgentState, type TokenUsage, type TrajectoryNode } from '@zenera/neo';
+import { Router, type Request } from 'express';
+import type { ChatStore } from './store.ts';
+export declare const MAX_PART_CHARS: number;
+export declare const MAX_REQUEST_CHARS: number;
+export interface TraceStep {
+    /** position in the whole session, flattened; the address of the step */
+    index: number;
+    id: string;
+    type: TrajectoryNode['type'];
+    agent: string;
+    ts: string;
+    /** 0 on the trunk, one more per fork */
+    depth: number;
+    /** fork branch path, e.g. `research › web` */
+    branch?: string;
+    /** the step's id in `zen inspect graph|node|ask` */
+    node: string;
+    title: string;
+    model?: string;
+    tools?: string[];
+    usage?: TokenUsage;
+    stopReason?: string;
+    isError?: boolean;
+    durationMs?: number;
+    synthetic?: boolean;
+}
+export interface TracePage {
+    runId: string;
+    engineRunId: string;
+    scope: 'turn' | 'session';
+    /** false for runs recorded before turn boundaries were kept: only the session can be shown */
+    turnAvailable: boolean;
+    total: number;
+    offset: number;
+    limit: number;
+    counts: Partial<Record<TrajectoryNode['type'], number>>;
+    steps: TraceStep[];
+}
+export interface TracePart {
+    key: string;
+    label: string;
+    kind: 'text' | 'json';
+    text?: string;
+    json?: unknown;
+    /** recorded size, for a payload */
+    bytes?: number;
+    truncated?: boolean;
+    /** too large to send with the step: fetch it with ?part=<key> */
+    deferred?: boolean;
+    error?: string;
+}
+export interface TraceStepDetail {
+    step: TraceStep;
+    parts: TracePart[];
+}
+interface Flat {
+    node: TrajectoryNode;
+    depth: number;
+    branch?: string;
+    /** index of the trunk node it belongs to */
+    top: number;
+    /** `zen inspect` id */
+    key: string;
+}
+export declare function flatten(trajectory: TrajectoryNode[]): Flat[];
+export declare function toStep(f: Flat, index: number): TraceStep;
+export declare function openTrace(store: ChatStore, req: Request): Promise<{
+    thread: import("./store.ts").ChatThread;
+    record: import("./runRecords.ts").RunRecord;
+    runDir: string;
+    state: AgentState;
+    payloads: PayloadResolver;
+    flat: Flat[];
+}>;
+/** The step a route names by its index, or 404. */
+export declare function stepParam(flat: Flat[], raw: string): {
+    f: Flat;
+    index: number;
+};
+export declare function stepParts(n: TrajectoryNode, payloads: PayloadResolver): Promise<TracePart[]>;
+export declare function traceRouter(store: ChatStore): Router;
+export {};
+//# sourceMappingURL=trace.d.ts.map