@zenera/engine 0.0.0-stage → 1.1.39

package/dist/session.d.ts

@@ -0,0 +1,118 @@
+export interface SessionPaths {
+    id: string;
+    dir: string;
+    /** what the agent can see and write */
+    workspace: string;
+    data: string;
+    /** the live, resumable state — rewritten after every run */
+    state: string;
+    blobs: string;
+    runs: string;
+    lock: string;
+    meta: string;
+}
+export declare function sessionPaths(projectDir: string, id: string): SessionPaths;
+/**
+ * The same layout, rooted wherever a host keeps its sessions and named however
+ * it names them: a server stores one per user and thread, not per project.
+ */
+export declare function sessionPathsAt(dir: string): SessionPaths;
+export interface SessionMeta {
+    version: 1;
+    id: string;
+    createdAt: string;
+    /**
+     * Absolute path the agent's file tools are rooted at. Recorded so resuming
+     * never re-asks and never silently moves — a session that quietly changed
+     * what "the workspace" meant between turns would be unexplainable.
+     */
+    workspace: string;
+    lastRunAt?: string;
+    title?: string;
+}
+export declare function createSession(projectDir: string, id: string, workspace: string): SessionPaths;
+export declare function createSessionAt(dir: string, workspace: string): SessionPaths;
+export declare function readSessionMeta(p: SessionPaths): Promise<SessionMeta>;
+export declare function writeSessionMeta(p: SessionPaths, meta: SessionMeta): void;
+export interface SessionSummary {
+    id: string;
+    createdAt?: string;
+    runs: number;
+    lastRunAt?: string;
+    busy: boolean;
+    title?: string;
+}
+/** Newest first — the order a picker wants. */
+export declare function listSessions(projectDir: string): Promise<SessionSummary[]>;
+export declare function newestSession(projectDir: string): string | undefined;
+export declare function requireSession(projectDir: string, id: string): SessionPaths;
+export interface Held {
+    release(): void;
+}
+export declare function acquire(p: SessionPaths): Held;
+export interface RunPaths {
+    id: string;
+    dir: string;
+    input: string;
+    output: string;
+    state: string;
+    report: string;
+    /** the same run as one Mermaid flowchart, for a model to read */
+    graph: string;
+    meta: string;
+}
+export declare function runPaths(session: SessionPaths, id: string): RunPaths;
+export declare function createRun(session: SessionPaths): RunPaths;
+/**
+ * The same paths, reached from a directory instead of from a pair of ids.
+ *
+ * `zen run --json` hands back a run directory, and a caller holding one has no
+ * reason to take it apart again to ask a second question about the same run.
+ * The layout is fixed, so the ids can be read back out of the path — and both
+ * still go through `isStamp`, so a path from anywhere cannot name a directory
+ * this layout would never have produced.
+ *
+ * The session comes back too, not only the run: blobs are stored per session,
+ * so anything that resolves a payload needs both halves — and the project, so
+ * a command reached this way can still read the project's config.
+ */
+export declare function runPathsAt(dir: string): {
+    project: string;
+    session: SessionPaths;
+    run: RunPaths;
+};
+export interface RunMeta {
+    version: 1;
+    id: string;
+    session: string;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    agent: string;
+    stopReason: string;
+    turns: number;
+    usage: unknown;
+    workspace: string;
+    memory?: string;
+    error?: string;
+}
+export declare function writeRunMeta(p: RunPaths, meta: RunMeta): void;
+/**
+ * Partial, because a run killed before it recorded anything still has a
+ * directory, and every field here is worth having on its own.
+ */
+export declare function readRunMeta(p: RunPaths): Promise<Partial<RunMeta>>;
+export interface RunSummary {
+    id: string;
+    startedAt?: string;
+    finishedAt?: string;
+    agent?: string;
+    stopReason?: string;
+    error?: string;
+}
+/** Newest first — the order a picker wants. */
+export declare function listRuns(session: SessionPaths): Promise<RunSummary[]>;
+export declare function newestRun(session: SessionPaths): string | undefined;
+/** A path to show a human: relative when that is shorter, absolute otherwise. */
+export declare function display(path: string, from?: string): string;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.js

@@ -0,0 +1,197 @@
+import { claimLock, ownLock } from '@zenera/neo';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { EngineError, EXIT, invalidError, usageError } from "./errors.js";
+import { readJson, writeJson } from "./home.js";
+import { isStamp, stamp, stampInstant } from "./ids.js";
+import { isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
+export function sessionPaths(projectDir, id) {
+    if (!isStamp(id)) {
+        throw usageError(`"${id}" is not a session id`, 'ids look like 20260825-143012-a7f3');
+    }
+    return sessionPathsAt(join(sessionsDir(projectDir), id));
+}
+/**
+ * The same layout, rooted wherever a host keeps its sessions and named however
+ * it names them: a server stores one per user and thread, not per project.
+ */
+export function sessionPathsAt(dir) {
+    const data = join(dir, '.data');
+    return {
+        id: basename(dir),
+        dir,
+        workspace: join(dir, 'workspace'),
+        data,
+        state: join(data, 'state.json'),
+        blobs: join(data, 'blobs'),
+        runs: join(dir, 'runs'),
+        lock: join(dir, '.lock'),
+        meta: join(data, 'session.json'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Creating and finding
+// ---------------------------------------------------------------------------
+export function createSession(projectDir, id, workspace) {
+    return createSessionAt(sessionPaths(projectDir, id).dir, workspace);
+}
+export function createSessionAt(dir, workspace) {
+    const p = sessionPathsAt(dir);
+    mkdirSync(p.data, { recursive: true });
+    mkdirSync(p.runs, { recursive: true });
+    mkdirSync(resolve(workspace), { recursive: true });
+    const meta = {
+        version: 1,
+        id: p.id,
+        createdAt: new Date().toISOString(),
+        workspace: resolve(workspace),
+    };
+    writeJson(p.meta, meta, 0o644);
+    return p;
+}
+export async function readSessionMeta(p) {
+    const meta = await readJson(p.meta, {});
+    return {
+        version: 1,
+        id: p.id,
+        createdAt: meta.createdAt ?? new Date().toISOString(),
+        // Sessions from before the workspace was recorded fall back to their
+        // own directory, which is where it would have been.
+        workspace: meta.workspace ?? p.workspace,
+        lastRunAt: meta.lastRunAt,
+        title: meta.title,
+    };
+}
+export function writeSessionMeta(p, meta) {
+    writeJson(p.meta, meta, 0o644);
+}
+/** Newest first — the order a picker wants. */
+export async function listSessions(projectDir) {
+    const out = [];
+    for (const id of sessionIds(projectDir).reverse()) {
+        const p = sessionPaths(projectDir, id);
+        const meta = await readSessionMeta(p);
+        const ids = runIds(p.dir);
+        out.push({
+            id,
+            createdAt: meta.createdAt,
+            runs: ids.length,
+            lastRunAt: meta.lastRunAt,
+            busy: isBusy(p.dir),
+            title: meta.title,
+        });
+    }
+    return out;
+}
+export function newestSession(projectDir) {
+    return sessionIds(projectDir).at(-1);
+}
+export function requireSession(projectDir, id) {
+    const p = sessionPaths(projectDir, id);
+    if (!existsSync(p.dir)) {
+        throw invalidError(`no session ${id}`, 'see: zen list --sessions');
+    }
+    return p;
+}
+export function acquire(p) {
+    claimLock(p.lock, ownLock(), (held) => new EngineError(`session ${p.id} is already running (pid ${held.pid})`, EXIT.failed, 'wait for it, or start another with --new'), 2);
+    let released = false;
+    const release = () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        rmSync(p.lock, { force: true });
+    };
+    return { release };
+}
+export function runPaths(session, id) {
+    if (!isStamp(id)) {
+        throw usageError(`"${id}" is not a run id`);
+    }
+    const dir = join(session.runs, id);
+    return {
+        id,
+        dir,
+        input: join(dir, 'input.md'),
+        output: join(dir, 'output.md'),
+        state: join(dir, 'state.json'),
+        report: join(dir, 'report.html'),
+        graph: join(dir, 'graph.mmd'),
+        meta: join(dir, 'meta.json'),
+    };
+}
+export function createRun(session) {
+    const p = runPaths(session, stamp());
+    mkdirSync(p.dir, { recursive: true });
+    return p;
+}
+/**
+ * The same paths, reached from a directory instead of from a pair of ids.
+ *
+ * `zen run --json` hands back a run directory, and a caller holding one has no
+ * reason to take it apart again to ask a second question about the same run.
+ * The layout is fixed, so the ids can be read back out of the path — and both
+ * still go through `isStamp`, so a path from anywhere cannot name a directory
+ * this layout would never have produced.
+ *
+ * The session comes back too, not only the run: blobs are stored per session,
+ * so anything that resolves a payload needs both halves — and the project, so
+ * a command reached this way can still read the project's config.
+ */
+export function runPathsAt(dir) {
+    const full = resolve(dir);
+    const runId = basename(full);
+    const sessionDir = dirname(dirname(full));
+    const wrong = () => usageError(`${display(full)} is not a run directory`, 'runs live at <project>/sessions/<session>/runs/<run>');
+    if (!isStamp(runId) || !isStamp(basename(sessionDir)) || basename(dirname(full)) !== 'runs') {
+        throw wrong();
+    }
+    const project = dirname(dirname(sessionDir));
+    const session = sessionPaths(project, basename(sessionDir));
+    const run = runPaths(session, runId);
+    if (resolve(run.dir) !== full) {
+        throw wrong();
+    }
+    if (!existsSync(run.state)) {
+        throw invalidError(`run ${runId} has no state.json`, 'only a run that got far enough to save state can be inspected');
+    }
+    return { project, session, run };
+}
+export function writeRunMeta(p, meta) {
+    writeJson(p.meta, meta, 0o644);
+}
+/**
+ * Partial, because a run killed before it recorded anything still has a
+ * directory, and every field here is worth having on its own.
+ */
+export async function readRunMeta(p) {
+    return await readJson(p.meta, {});
+}
+/** Newest first — the order a picker wants. */
+export async function listRuns(session) {
+    const out = [];
+    for (const id of runIds(session.dir).reverse()) {
+        // A run killed before it recorded anything still has an id, and the id
+        // says when it started, so it is listable without its meta.
+        const meta = await readRunMeta(runPaths(session, id));
+        out.push({
+            id,
+            startedAt: meta.startedAt ?? stampInstant(id),
+            finishedAt: meta.finishedAt,
+            agent: meta.agent,
+            stopReason: meta.stopReason,
+            error: meta.error,
+        });
+    }
+    return out;
+}
+export function newestRun(session) {
+    return runIds(session.dir).at(-1);
+}
+/** A path to show a human: relative when that is shorter, absolute otherwise. */
+export function display(path, from = process.cwd()) {
+    const rel = relative(from, path);
+    return !rel.startsWith('..') && rel.length < path.length ? rel || '.' : path;
+}
+//# sourceMappingURL=session.js.map

package/package.json

@@ -1,6 +1,49 @@
 {
-  "name": "@zenera/engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@zenera/engine",
+    "version": "1.1.39",
+    "description": "Runs a @zenera/neo project on this machine: keyring, sandbox, sessions and the record each turn leaves behind.",
+    "keywords": [
+        "agents",
+        "ai-agents",
+        "agent-runtime",
+        "sandbox",
+        "llm"
+    ],
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": "Andrey Ryabov",
+    "homepage": "https://github.com/zenera-ai/ZeneraNeo#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/zenera-ai/ZeneraNeo.git",
+        "directory": "packages/engine"
+    },
+    "bugs": "https://github.com/zenera-ai/ZeneraNeo/issues",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "!dist/**/*.map"
+    ],
+    "engines": {
+        "node": ">=24"
+    },
+    "scripts": {
+        "build": "tsc -b",
+        "clean": "tsc -b --clean && rm -rf dist",
+        "prepack": "tsc -b"
+    },
+    "dependencies": {
+        "@zenera/neo": "^1.1.39"
+    }
+}