@zenera/server 0.0.0-stage → 1.2.1

package/dist/config.d.ts

@@ -0,0 +1,71 @@
+import type { SandboxSetup, ZenPlugin } from '@zenera/engine';
+import { type SandboxFactory } from '@zenera/sandbox';
+export type ServerAuth = 
+/** EdDSA tokens signed per request by the host (zenera-app), checked with its public key */
+{
+    mode: 'jwt';
+    publicKey: string;
+    issuer: string;
+    audience: string;
+}
+/** the same tokens, their signature, issuer, audience, age and binding not checked */
+ | {
+    mode: 'insecure';
+};
+export interface ServerSettings {
+    /** the project the agents come from; read-only to the server */
+    projectDir: string;
+    projectId: string;
+    /** everything the server writes: `<root>/users/<user>/{sessions,memory}`, `<root>/server.json` */
+    root: string;
+    /**
+     * The graph each user's memory starts as, copied the first time they need one. Unset: the
+     * project's own (`memory:` in agents.yaml); `null`: none, every user starts empty.
+     */
+    memorySeed?: string | null;
+    auth: ServerAuth;
+    /** the Test tab's routes: recorded runs, traces, the memory graph */
+    debug: boolean;
+    /**
+     * Where commands run: `'podman'` as `zen run` has it, a container per session on this
+     * machine; `'bwrap'` in the agent image, with `hidden`, the root and the seed kept from
+     * them; or a factory. `defaultSandbox()` picks between the first two.
+     */
+    sandbox: 'bwrap' | 'podman' | SandboxFactory;
+    /** what to call it, for `/api/status` */
+    sandboxProvider: string;
+    /**
+     * Readies a turn's sandbox before it runs. Unset: its image must already be there
+     * (`imageReady`) — the agent image's, or one built ahead of time.
+     */
+    preflight?: (setup: SandboxSetup) => Promise<void>;
+    /** more paths bwrap commands never see (the root, the seed, the zen home and the project always) */
+    hidden: string[];
+    /** this run's own plugins (the MCP tools for its user), given the token its caller sent */
+    plugins: (run: {
+        mcpToken: string | null;
+    }) => Promise<ZenPlugin[]>;
+    maxRuns: number;
+    /** how many runs one user may have going at once */
+    maxUserRuns: number;
+    maxRunMinutes: number;
+    runLogMaxBytes: number;
+}
+/**
+ * bwrap inside the agent image, which ships it at /opt/zenera/bin/bwrap; podman anywhere else,
+ * as `zen run`. The image is the container, so podman has nothing to run there.
+ */
+export declare function defaultSandbox(): 'bwrap' | 'podman';
+/** Inside the agent image: where `--insecure` is refused unless the host that runs it says so. */
+export declare function inAgentImage(): boolean;
+export declare const SANDBOX_PROVIDERS: {
+    readonly bwrap: "bwrap (this container)";
+    readonly podman: "podman (this machine)";
+};
+/** What zenera-app's tokens say today. */
+export declare const DEFAULT_ISSUER = "zenera-app";
+export declare const DEFAULT_AUDIENCE = "zenera-runtime";
+export declare const DEFAULTS: Omit<ServerSettings, 'projectId' | 'auth' | 'root'>;
+export declare function configure(settings: ServerSettings): void;
+export declare function settings(): ServerSettings;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,44 @@
+import { ZENERA_BWRAP } from '@zenera/sandbox';
+import { existsSync } from 'node:fs';
+/**
+ * bwrap inside the agent image, which ships it at /opt/zenera/bin/bwrap; podman anywhere else,
+ * as `zen run`. The image is the container, so podman has nothing to run there.
+ */
+export function defaultSandbox() {
+    return existsSync(ZENERA_BWRAP) ? 'bwrap' : 'podman';
+}
+/** Inside the agent image: where `--insecure` is refused unless the host that runs it says so. */
+export function inAgentImage() {
+    return existsSync(ZENERA_BWRAP);
+}
+export const SANDBOX_PROVIDERS = {
+    bwrap: 'bwrap (this container)',
+    podman: 'podman (this machine)',
+};
+/** What zenera-app's tokens say today. */
+export const DEFAULT_ISSUER = 'zenera-app';
+export const DEFAULT_AUDIENCE = 'zenera-runtime';
+const sandbox = defaultSandbox();
+export const DEFAULTS = {
+    projectDir: '/project',
+    debug: false,
+    sandbox,
+    sandboxProvider: SANDBOX_PROVIDERS[sandbox],
+    hidden: [],
+    plugins: async () => [],
+    maxRuns: 4,
+    maxUserRuns: 2,
+    maxRunMinutes: 120,
+    runLogMaxBytes: 50 * 1024 * 1024,
+};
+let current;
+export function configure(settings) {
+    current = settings;
+}
+export function settings() {
+    if (!current) {
+        throw new Error('the server is not configured: call createServer() first');
+    }
+    return current;
+}
+//# sourceMappingURL=config.js.map

package/dist/history.d.ts

@@ -0,0 +1,8 @@
+import type { Message } from '@ag-ui/core';
+import { type TrajectoryNode } from '@zenera/neo';
+import { Router } from 'express';
+import { type Resolve } from './agui.ts';
+import type { ChatStore } from './store.ts';
+export declare function toMessages(trajectory: TrajectoryNode[], resolve: Resolve): Promise<Message[]>;
+export declare function historyRouter(store: ChatStore): Router;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.js

@@ -0,0 +1,73 @@
+import { FilePayloadStore, PayloadResolver, } from '@zenera/neo';
+import { Router } from 'express';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { clip } from "./agui.js";
+import { readRunLog, threadRunLogs } from "./runLog.js";
+import { currentRun } from "./runs.js";
+export async function toMessages(trajectory, resolve) {
+    const out = [];
+    for (const node of trajectory) {
+        if (node.type === 'user_input' && !node.synthetic) {
+            const texts = await Promise.all(node.content.flatMap((part) => (part.type === 'text' ? [resolve(part.text)] : [])));
+            const content = texts.join('\n');
+            if (content)
+                out.push({ id: node.id, role: 'user', content });
+        }
+        else if (node.type === 'llm_call') {
+            const text = await resolve(node.text);
+            const toolCalls = await Promise.all(node.toolCalls.map(async (call) => ({
+                id: call.callId,
+                type: 'function',
+                function: { name: call.name, arguments: await resolve(call.args) },
+            })));
+            if (!text.trim() && toolCalls.length === 0)
+                continue;
+            out.push({
+                id: node.id,
+                role: 'assistant',
+                name: node.agent,
+                ...(text.trim() ? { content: text } : {}),
+                ...(toolCalls.length ? { toolCalls } : {}),
+            });
+        }
+        else if (node.type === 'tool_result') {
+            out.push({
+                id: node.id,
+                role: 'tool',
+                toolCallId: node.callId,
+                content: clip(await resolve(node.result)),
+                ...(node.isError ? { error: 'the tool reported an error' } : {}),
+            });
+        }
+    }
+    return out;
+}
+export function historyRouter(store) {
+    const router = Router();
+    router.get('/:tid', async (req, res) => {
+        const t = store.thread(req);
+        const running = currentRun(t);
+        const logs = await threadRunLogs(store.runsDir(t));
+        if (logs.length > 0) {
+            const events = [];
+            for (const log of logs) {
+                if (log.runId !== running?.runId)
+                    events.push(...(await readRunLog(log.file)));
+            }
+            res.json({ threadId: t.id, messages: [], events, running });
+            return;
+        }
+        const session = store.existingSession(t);
+        if (!session || !existsSync(session.state)) {
+            res.json({ threadId: t.id, messages: [], events: [], running });
+            return;
+        }
+        const state = JSON.parse(await readFile(session.state, 'utf8'));
+        const payloads = new PayloadResolver(new FilePayloadStore({ dir: session.blobs, id: 'file' }));
+        const messages = await toMessages(state.trajectory, (p) => payloads.get(p));
+        res.json({ threadId: t.id, messages, events: [], running });
+    });
+    return router;
+}
+//# sourceMappingURL=history.js.map

package/dist/http.d.ts

@@ -0,0 +1,9 @@
+import type { NextFunction, Request, Response } from 'express';
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function errorMessage(err: unknown): string;
+export declare function notFound(_req: Request, res: Response): void;
+export declare function errorHandler(err: unknown, req: Request, res: Response, _next: NextFunction): void;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -0,0 +1,26 @@
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export function errorMessage(err) {
+    const e = err;
+    return (e?.stderr || e?.message || String(err)).trim();
+}
+export function notFound(_req, res) {
+    res.status(404).json({ error: 'Not found' });
+}
+// Express 5 forwards rejected async handlers here, so routes just throw.
+export function errorHandler(err, req, res, _next) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    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) });
+}
+//# sourceMappingURL=http.js.map

package/dist/identity.d.ts

@@ -0,0 +1,18 @@
+import type { RunIdentity } from '@zenera/engine';
+import type { Request } from 'express';
+import type { CallerClaims } from './auth.ts';
+export interface Identity {
+    /** the folder under <root>/users/ */
+    userId: string;
+    threadId: string;
+}
+export declare function isThreadId(id: string): boolean;
+/**
+ * Where a user's things are: their id when it is one safe path segment (a UUID lower-cased, as
+ * zenera-app's are), else `u-` and a hash of it — so no id is ever a path of its own.
+ */
+export declare function userFolder(sub: string): string;
+export declare function caller(req: Request): CallerClaims;
+export declare function identify(req: Request): Identity;
+export declare function runUser(req: Request): RunIdentity | null;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { settings } from "./config.js";
+import { HttpError } from "./http.js";
+const SAFE_ID = /^[A-Za-z0-9][\w.@-]{0,99}$/;
+const THREAD_ID = /^[A-Za-z0-9][\w-]{0,79}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ROLES = new Set(['owner', 'editor', 'viewer', 'admin']);
+// An email goes into an environment variable, so it is held to the shape of one.
+const EMAIL = /^[^\s@]{1,200}@[^\s@]{1,200}$/;
+const NAME = /^[^\n\r\0]{1,200}$/;
+export function isThreadId(id) {
+    return THREAD_ID.test(id);
+}
+/**
+ * Where a user's things are: their id when it is one safe path segment (a UUID lower-cased, as
+ * zenera-app's are), else `u-` and a hash of it — so no id is ever a path of its own.
+ */
+export function userFolder(sub) {
+    if (UUID.test(sub))
+        return sub.toLowerCase();
+    if (SAFE_ID.test(sub))
+        return sub;
+    return `u-${createHash('sha256').update(sub).digest('hex').slice(0, 32)}`;
+}
+export function caller(req) {
+    const claims = req.res?.locals.caller;
+    if (!claims)
+        throw new HttpError(401, 'no verified caller');
+    return claims;
+}
+export function identify(req) {
+    const claims = caller(req);
+    const threadId = String(req.params.tid ?? '');
+    if (!isThreadId(threadId))
+        throw new HttpError(400, 'not a thread id');
+    if (claims.thr !== undefined && String(claims.thr).toLowerCase() !== threadId.toLowerCase()) {
+        throw new HttpError(403, 'the token is for another thread');
+    }
+    return { userId: userFolder(claims.sub), threadId };
+}
+export function runUser(req) {
+    const claims = caller(req);
+    const role = typeof claims.role === 'string' && ROLES.has(claims.role) ? claims.role : undefined;
+    const email = typeof claims.email === 'string' && EMAIL.test(claims.email) ? claims.email : undefined;
+    const name = typeof claims.name === 'string' && NAME.test(claims.name) ? claims.name : undefined;
+    return {
+        id: UUID.test(claims.sub) ? claims.sub.toLowerCase() : claims.sub,
+        ...(role ? { role } : {}),
+        ...(email ? { email } : {}),
+        ...(name ? { name } : {}),
+        // An unsigned token is only someone's say-so.
+        source: settings().auth.mode === 'jwt' ? 'host' : 'local',
+    };
+}
+//# sourceMappingURL=identity.js.map

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { createServer, insecureHere, INSECURE_LOCAL_ENV, type AgentServer, type ListenOn, type ServerOptions, } from './server.ts';
+export { configure, settings, DEFAULTS, defaultSandbox, inAgentImage, DEFAULT_AUDIENCE, DEFAULT_ISSUER, SANDBOX_PROVIDERS, type ServerAuth, type ServerSettings, } from './config.ts';
+export { requireCaller, unsignedToken, verifyCaller, type CallerClaims } from './auth.ts';
+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 { historyRouter, toMessages } from './history.ts';
+export { traceRouter, openTrace, stepParam } from './trace.ts';
+export { memoryRouter } from './memory.ts';
+export { AguiTranslator, clip } from './agui.ts';
+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 { serverStatus, startupErrors, type ServerStatus } from './status.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,20 @@
+// @zenera/server: a project's chats over HTTP — the server in the agent image, and the pieces a
+// host builds its own chat routes from (the ZeneraLite editor's Test tab).
+export { createServer, insecureHere, INSECURE_LOCAL_ENV, } from "./server.js";
+export { configure, settings, DEFAULTS, defaultSandbox, inAgentImage, DEFAULT_AUDIENCE, DEFAULT_ISSUER, SANDBOX_PROVIDERS, } from "./config.js";
+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 { historyRouter, toMessages } from "./history.js";
+export { traceRouter, openTrace, stepParam } from "./trace.js";
+export { memoryRouter } from "./memory.js";
+export { AguiTranslator, clip } from "./agui.js";
+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 { serverStatus, startupErrors } from "./status.js";
+//# sourceMappingURL=index.js.map

package/dist/layout.d.ts

@@ -0,0 +1,15 @@
+/** 1: users/<user>/{sessions/<thread>/, memory/}. */
+export declare const LAYOUT_VERSION = 1;
+export interface Layout {
+    version: number;
+    projectId: string;
+    createdAt: string;
+}
+export declare class LayoutError extends Error {
+    name: string;
+}
+/** `create: false` only reads (a check must not claim a directory): missing is `undefined`. */
+export declare function openLayout(root: string, projectId: string, opts?: {
+    create?: boolean;
+}): Layout | undefined;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.js

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

package/dist/localFileCors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Express middleware allowing the standalone file:// chat to reach an insecure runtime.
+ * localFileCors handles Origin: null responses and restricted preflight methods/headers;
+ * server.ts installs it before requireCaller so preflights work without bypassing
+ * authentication on actual API requests. Secure servers do not enable this CORS policy.
+ */
+import type { NextFunction, Request, Response } from 'express';
+/** Local HTML has an opaque origin. This opt-in exists only for insecure dev servers. */
+export declare function localFileCors(req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=localFileCors.d.ts.map

package/dist/localFileCors.js

@@ -0,0 +1,34 @@
+import { settings } from "./config.js";
+import { HttpError } from "./http.js";
+const METHODS = new Set(['GET', 'POST', 'DELETE']);
+const HEADERS = new Set(['authorization', 'content-type', 'accept']);
+/** Local HTML has an opaque origin. This opt-in exists only for insecure dev servers. */
+export function localFileCors(req, res, next) {
+    if (settings().auth.mode !== 'insecure' || req.get('origin') !== 'null') {
+        next();
+        return;
+    }
+    res.vary('Origin');
+    res.set('Access-Control-Allow-Origin', 'null');
+    if (req.method !== 'OPTIONS') {
+        next();
+        return;
+    }
+    const method = req.get('access-control-request-method');
+    const headers = (req.get('access-control-request-headers') ?? '')
+        .split(',')
+        .map((header) => header.trim().toLowerCase())
+        .filter(Boolean);
+    if (!method || !METHODS.has(method) || headers.some((header) => !HEADERS.has(header))) {
+        next(new HttpError(403, 'local-file request method or headers are not allowed'));
+        return;
+    }
+    res.set('Access-Control-Allow-Methods', [...METHODS].join(', '));
+    res.set('Access-Control-Allow-Headers', [...HEADERS].join(', '));
+    // Older Chromium versions request this for a local-network preflight.
+    if (req.get('access-control-request-private-network') === 'true') {
+        res.set('Access-Control-Allow-Private-Network', 'true');
+    }
+    res.sendStatus(204);
+}
+//# sourceMappingURL=localFileCors.js.map

package/dist/memory.d.ts

@@ -0,0 +1,81 @@
+import { type Embedder, type MemoryEdge, type MemoryGrepResult, type MemoryNode, type NodeVia, type ProjectConfig, type ReportNode } from '@zenera/neo';
+import { Router } from 'express';
+import { type ChatStore } from './store.ts';
+export type MemoryStatus = 'disabled' | 'not-created' | 'ready';
+export interface MemoryStats {
+    nodes: number;
+    edges: number;
+    superseded: number;
+    files: number;
+    embedding?: {
+        model: string;
+        dimensions: number;
+    };
+    vectors?: {
+        rows: number;
+        dims: number;
+        bytes: number;
+    };
+}
+export interface MemoryOverview {
+    status: MemoryStatus;
+    stats: MemoryStats;
+    kinds: string[];
+    audiences: string[];
+}
+export interface MemoryNodesPage {
+    status: MemoryStatus;
+    nodes: ReportNode[];
+    found: number;
+    offset: number;
+    limit: number;
+    truncated: boolean;
+    kinds: string[];
+    audiences: string[];
+}
+export interface MemoryNodeDetails {
+    status: 'ready';
+    node: ReportNode;
+    edges: MemoryEdge[];
+}
+export interface MemoryGrepResponse extends MemoryGrepResult {
+    status: MemoryStatus;
+}
+export interface MemoryRecallNode {
+    node: MemoryNode;
+    score: number;
+    seed: boolean;
+    via?: NodeVia;
+    stale: boolean;
+}
+export interface MemoryRecallResponse {
+    status: MemoryStatus;
+    ranking: {
+        by: 'meaning' | 'term overlap';
+        model?: string;
+        reason?: string;
+    };
+    sees: string[];
+    query: {
+        text: string;
+        kind?: string;
+        limit: number;
+        hops: number;
+        nodes: number;
+        minScore?: number;
+    };
+    seeds: string[];
+    truncated: boolean;
+    nodes: MemoryRecallNode[];
+    edges: MemoryEdge[];
+    block: string;
+}
+export interface MemoryReportResponse {
+    html: string;
+}
+type EmbedderFactory = (config: ProjectConfig) => Embedder | undefined;
+/** Test-only seam: replaces credential and model resolution for recall. */
+export declare function setRecallEmbedderFactory(factory: EmbedderFactory | undefined): void;
+export declare function memoryRouter(chats: ChatStore): Router;
+export {};
+//# sourceMappingURL=memory.d.ts.map