@zenera/cli 1.1.23 → 1.1.25

package/dist/session.d.ts

@@ -6,7 +6,6 @@ export interface SessionPaths {
     data: string;
     /** the live, resumable state — rewritten after every run */
     state: string;
-    memory: string;
     blobs: string;
     runs: string;
     lock: string;
@@ -52,10 +51,30 @@ export interface RunPaths {
     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;
@@ -68,9 +87,15 @@ export interface RunMeta {
     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;

package/dist/session.js

@@ -1,9 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { hostname } from 'node:os';
-import { join, relative, resolve } from 'node:path';
+import { claimLock, ownLock } from '@zenera/neo';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { readJson, writeJson } from "./home.js";
 import { isStamp, stamp, stampInstant } from "./ids.js";
-import { alive, isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
+import { isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
 import { CliError, EXIT, invalidError, usageError } from "./term.js";
 export function sessionPaths(projectDir, id) {
     if (!isStamp(id)) {
@@ -17,7 +17,6 @@ export function sessionPaths(projectDir, id) {
         workspace: join(dir, 'workspace'),
         data,
         state: join(data, 'state.json'),
-        memory: join(data, 'memory'),
         blobs: join(data, 'blobs'),
         runs: join(dir, 'runs'),
         lock: join(dir, '.lock'),
@@ -86,24 +85,7 @@ export function requireSession(projectDir, id) {
     return p;
 }
 export function acquire(p) {
-    const lock = { pid: process.pid, host: hostname(), startedAt: new Date().toISOString() };
-    const body = `${JSON.stringify(lock, null, 2)}\n`;
-    try {
-        // 'wx' fails when the file exists — the create and the check are one
-        // operation, so two `zen run`s racing cannot both win.
-        writeFileSync(p.lock, body, { flag: 'wx' });
-    }
-    catch (err) {
-        if (err.code !== 'EEXIST') {
-            throw err;
-        }
-        const held = current(p);
-        if (held && alive(held.pid) && held.host === hostname()) {
-            throw new CliError(`session ${p.id} is already running (pid ${held.pid})`, EXIT.failed, 'wait for it, or start another with --new');
-        }
-        // Stale, or from another machine's run that cannot be verified here.
-        writeFileSync(p.lock, body);
-    }
+    claimLock(p.lock, ownLock(), (held) => new CliError(`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) {
@@ -114,14 +96,6 @@ export function acquire(p) {
     };
     return { release };
 }
-function current(p) {
-    try {
-        return JSON.parse(readFileSync(p.lock, 'utf8'));
-    }
-    catch {
-        return undefined;
-    }
-}
 export function runPaths(session, id) {
     if (!isStamp(id)) {
         throw usageError(`"${id}" is not a run id`);
@@ -134,6 +108,7 @@ export function runPaths(session, id) {
         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'),
     };
 }
@@ -142,16 +117,55 @@ export function createRun(session) {
     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 readJson(runPaths(session, id).meta, {});
+        const meta = await readRunMeta(runPaths(session, id));
         out.push({
             id,
             startedAt: meta.startedAt ?? stampInstant(id),

package/dist/term.d.ts

@@ -56,6 +56,8 @@ export declare function write(line?: string): void;
 export declare function writeAll(lines: readonly string[]): void;
 /** Machine-readable output. Pretty-printed: it is read by people too. */
 export declare function json(value: unknown): void;
+/** The same bytes, for a caller sending them somewhere other than stdout. */
+export declare function jsonText(value: unknown): string;
 export declare function note(line?: string): void;
 /**
  * One line of narration that rewrites itself while work is in flight, so a
@@ -71,7 +73,10 @@ export declare function warn(message: string): void;
 /** What this run calls itself, in the process table and on the terminal's tab. */
 export declare function title(text: string): void;
 export declare function fail(message: string, hint?: string): void;
+/** An agent's terminal can be a real pty (VS Code Copilot's is), so TTY checks alone miss it. */
+export declare function drivenByAgent(): boolean;
 export declare function isInteractive(): boolean;
+export declare function deferBanner(print: () => void): void;
 export declare function ask(question: string, fallback?: string): Promise<string>;
 /**
  * Reads without echoing. `readline` writes what you type through its `output`

package/dist/term.js

@@ -154,7 +154,11 @@ export function writeAll(lines) {
 }
 /** Machine-readable output. Pretty-printed: it is read by people too. */
 export function json(value) {
-    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    process.stdout.write(jsonText(value));
+}
+/** The same bytes, for a caller sending them somewhere other than stdout. */
+export function jsonText(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
 }
 export function note(line = '') {
     process.stderr.write(`${line}\n`);
@@ -226,13 +230,34 @@ export function fail(message, hint) {
 // a stdin that will never answer. A CLI that hangs in CI is worse than one that
 // fails in CI, because only one of the two tells you which flag you forgot.
 // ---------------------------------------------------------------------------
+/** An agent's terminal can be a real pty (VS Code Copilot's is), so TTY checks alone miss it. */
+export function drivenByAgent() {
+    const own = process.env['ZENERA_AGENT'];
+    if (own !== undefined) {
+        return own !== '' && own !== '0';
+    }
+    return Boolean(process.env['AI_AGENT'] || process.env['COPILOT_AGENT']);
+}
 export function isInteractive() {
-    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY) && !drivenByAgent();
+}
+// A banner is for whoever is sitting there, and the only proof that anyone is
+// sitting there is that we are about to ask them something. Commands whose
+// stdout is the answer hand theirs over here instead of printing it, and it
+// appears if — and only if — the run turns out to need a person. Held as a
+// thunk so this module stays below the banner, which is drawn with its colours.
+let pending;
+export function deferBanner(print) {
+    pending = print;
 }
 function requireTty(what, flag) {
     if (!isInteractive()) {
-        throw usageError(`cannot ask for ${what} without a terminal`, `pass ${flag} instead`);
+        const why = drivenByAgent() ? 'when an agent is running zen' : 'without a terminal';
+        throw usageError(`cannot ask for ${what} ${why}`, `pass ${flag} instead`);
     }
+    const banner = pending;
+    pending = undefined;
+    banner?.();
 }
 export async function ask(question, fallback) {
     requireTty(question, '--yes or the matching flag');

package/dist/trace.d.ts

@@ -0,0 +1,84 @@
+import { type AgentState, type PayloadResolver, type TrajectoryNode } from '@zenera/neo';
+export interface TraceEntry {
+    /** diagram id — `n1`, `n2`, …, in the order the run appended nodes */
+    key: string;
+    node: TrajectoryNode;
+    depth: number;
+    /** the branch this ran in, or null on the trunk */
+    branch: string | null;
+    /** hidden from the model's context by a later compaction */
+    covered: boolean;
+    /** the id of the compaction that hid it, when it is on the same level */
+    coveredBy?: string;
+    children: TraceBranch[];
+    turnStart: number | null;
+    startMs: number | null;
+    endMs: number | null;
+}
+export interface TraceBranch {
+    name: string;
+    agent: string;
+    status: string;
+    entries: TraceEntry[];
+    startMs: number | null;
+    endMs: number | null;
+    turnStart: number | null;
+    /** the one branch the join actually waited for */
+    slowest: boolean;
+}
+export interface Trace {
+    root: TraceEntry[];
+    /** every entry, branches included, in key order */
+    entries: TraceEntry[];
+    byKey: Map<string, TraceEntry>;
+}
+export declare function traceOf(state: AgentState): Trace;
+export declare function safe(text: string, max?: number): string;
+export interface TraceOptions {
+    /** the run id to name in the header, when it differs from `state.runId` */
+    runId?: string;
+    /** the run directory, so the header can spell the command that opens a node */
+    dir?: string;
+    /** the files the run worked on */
+    workspace?: string;
+    /** the memory graph the run read, when it had one */
+    memory?: string;
+    timing?: boolean;
+    usage?: boolean;
+    /** false drops the palette: a model reads the labels, not the colours */
+    style?: boolean;
+}
+export declare function traceMermaid(state: AgentState, opts?: TraceOptions): string;
+/** The node list on its own, for `--json`. */
+export declare function traceIndex(trace: Trace): {
+    id: string;
+    nodeId: string;
+    kind: string;
+    agent: string;
+    branch: string | null;
+    ts: string;
+    label: string;
+}[];
+export interface NodePart {
+    name: string;
+    text: string;
+}
+export interface NodeDetail {
+    id: string;
+    nodeId: string;
+    kind: string;
+    agent: string;
+    branch: string | null;
+    ts: string;
+    label: string;
+    parts: NodePart[];
+    /** fields worth reading that are not payloads */
+    facts: Record<string, string>;
+}
+/**
+ * `n5`, or `n5..n9`. A range is how a reader asks about a stretch, which is
+ * the shape of the question the diagram provokes ("what are n14 to n38 doing").
+ */
+export declare function parseNodeIds(words: readonly string[], known: Map<string, unknown>): string[];
+export declare function nodeDetail(trace: Trace, ids: readonly string[], payloads: PayloadResolver): Promise<NodeDetail[]>;
+//# sourceMappingURL=trace.d.ts.map