@0xgeorgemathew/zcode 0.3.1 → 0.4.0

package/lib/store.js

@@ -0,0 +1,276 @@
+'use strict';
+// Session store: one directory per zcode session under <root>/sessions/<id>.
+//
+//   session.json   lifecycle record (atomic tmp+rename writes; the owning
+//                  process is the only writer while it is alive)
+//   events.ndjson  bounded activity log (phases, tools, checks — no deltas)
+//   result.json    the final handback of the latest invocation
+//   home/          the session's own engine HOME (engine DB, subagent dirs)
+//   pending.json   a detached invocation waiting for its worker
+//   stdout.ndjson / stderr.log   output of detached workers
+//
+// Lifecycle: queued → running → finished (status: completed | unverified |
+// partial | blocked | failed | cancelled). A record that says queued/running
+// whose pid is gone reads as "interrupted" — resumable, never silently
+// "running" forever.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { rootDir } = require('./isolation.js');
+
+const RECORD_SCHEMA = 'zcode.session/1';
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_EVENTS = 2000;
+const ACTIVE_STATES = new Set(['queued', 'running']);
+
+class SessionExistsError extends Error {
+  constructor(id) {
+    super(
+      `session "${id}" already exists. Inspect it with "zcode status ${id}" ` +
+        `or continue it with "zcode resume ${id}".`
+    );
+    this.code = 'ZCODE_SESSION_EXISTS';
+  }
+}
+
+function sessionsDir(env = process.env) {
+  return path.join(rootDir(env), 'sessions');
+}
+
+function sessionDir(id, env = process.env) {
+  return path.join(sessionsDir(env), id);
+}
+
+function validId(id) {
+  return typeof id === 'string' && ID_RE.test(id);
+}
+
+function newId() {
+  return `zc-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+function writeJsonAtomic(file, value) {
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(3).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Claims the id atomically (mkdir fails if it exists) and writes the first
+// record. Throws SessionExistsError on collision — an orchestrator retrying
+// a start with the same --id never runs the work twice.
+function createSession(id, fields, env = process.env) {
+  fs.mkdirSync(sessionsDir(env), { recursive: true, mode: 0o700 });
+  const dir = sessionDir(id, env);
+  try {
+    fs.mkdirSync(dir, { mode: 0o700 });
+  } catch (err) {
+    if (err.code === 'EEXIST') throw new SessionExistsError(id);
+    throw err;
+  }
+  const now = new Date().toISOString();
+  const record = {
+    schema: RECORD_SCHEMA,
+    id,
+    createdAt: now,
+    updatedAt: now,
+    state: 'queued',
+    status: null,
+    phase: 'queued',
+    pid: process.pid,
+    turns: 0,
+    activity: { toolCalls: 0, subagentsStarted: 0, lastTool: null, lastEventAt: now },
+    ...fields,
+  };
+  writeJsonAtomic(path.join(dir, 'session.json'), record);
+  return record;
+}
+
+function readSession(id, env = process.env) {
+  if (!validId(id)) return null;
+  return readJson(path.join(sessionDir(id, env), 'session.json'));
+}
+
+// Read-modify-write; `patch` is an object or (record) => object.
+function updateSession(id, patch, env = process.env) {
+  const file = path.join(sessionDir(id, env), 'session.json');
+  const current = readJson(file);
+  if (!current) throw new Error(`session "${id}" has no record`);
+  const delta = typeof patch === 'function' ? patch(current) : patch;
+  const next = { ...current, ...delta, updatedAt: new Date().toISOString() };
+  writeJsonAtomic(file, next);
+  return next;
+}
+
+function deleteSession(id, env = process.env) {
+  if (!validId(id)) return;
+  fs.rmSync(sessionDir(id, env), { recursive: true, force: true });
+}
+
+function writeResult(id, result, env = process.env) {
+  writeJsonAtomic(path.join(sessionDir(id, env), 'result.json'), result);
+}
+
+function readResult(id, env = process.env) {
+  if (!validId(id)) return null;
+  return readJson(path.join(sessionDir(id, env), 'result.json'));
+}
+
+// Bounded append-only activity log. Counting lines once per process keeps
+// appends O(1).
+const eventCounts = new Map();
+function appendEvent(id, event, env = process.env) {
+  const file = path.join(sessionDir(id, env), 'events.ndjson');
+  let count = eventCounts.get(file);
+  if (count === undefined) {
+    try {
+      count = fs.readFileSync(file, 'utf8').split('\n').length - 1;
+    } catch {
+      count = 0;
+    }
+  }
+  if (count >= MAX_EVENTS && event.type !== 'phase' && event.type !== 'result') return;
+  fs.appendFileSync(file, JSON.stringify({ t: new Date().toISOString(), ...event }) + '\n', {
+    mode: 0o600,
+  });
+  eventCounts.set(file, count + 1);
+}
+
+function readEvents(id, { tail = 20 } = {}, env = process.env) {
+  try {
+    const lines = fs
+      .readFileSync(path.join(sessionDir(id, env), 'events.ndjson'), 'utf8')
+      .split('\n')
+      .filter(Boolean);
+    return lines.slice(-tail).map((l) => JSON.parse(l));
+  } catch {
+    return [];
+  }
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+// The record as callers should see it: an active state whose owner process
+// is gone is reported as "interrupted".
+function viewSession(record) {
+  if (!record) return null;
+  if (ACTIVE_STATES.has(record.state) && !pidAlive(record.pid)) {
+    return { ...record, state: 'interrupted', live: false };
+  }
+  return { ...record, live: ACTIVE_STATES.has(record.state) };
+}
+
+function listSessions(env = process.env) {
+  let names = [];
+  try {
+    names = fs.readdirSync(sessionsDir(env));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    const record = readSession(name, env);
+    if (record) out.push(viewSession(record));
+  }
+  return out.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+}
+
+// Accepts a zcode id or an engine session id (sess_…, as printed by 0.3.x
+// and still reported as result.sessionId). Returns the zcode id or null.
+function resolveSessionId(ref, env = process.env) {
+  if (validId(ref) && readSession(ref, env)) return ref;
+  for (const record of listSessions(env)) {
+    if (record.engineSessionId === ref) return record.id;
+  }
+  return null;
+}
+
+// Exclusive pid lock (O_EXCL create). A lock whose pid is dead is stale and
+// reclaimed; the content is re-read just before removal so a fresh lock
+// taken by a racing reclaimer is not deleted. Returns release() or null.
+function claimLockFile(file) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      fs.writeFileSync(file, String(process.pid), { flag: 'wx', mode: 0o600 });
+      return () => {
+        try {
+          if (fs.readFileSync(file, 'utf8') === String(process.pid)) fs.rmSync(file, { force: true });
+        } catch {
+          /* already gone */
+        }
+      };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+    }
+    let holder;
+    try {
+      holder = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue; // released in between: retry the create
+    }
+    if (pidAlive(Number(holder))) return null;
+    try {
+      if (fs.readFileSync(file, 'utf8') === holder) fs.rmSync(file, { force: true });
+    } catch {
+      /* someone else reclaimed it */
+    }
+  }
+  return null;
+}
+
+// One live process drives a session at a time (two racing `resume`s, or a
+// resume racing a detached worker, cannot both run it).
+function claimSession(id, env = process.env) {
+  return claimLockFile(path.join(sessionDir(id, env), 'owner.lock'));
+}
+
+// Machine-wide soft cap on running sessions (ZAI_CODE_MAX_ACTIVE): N slot
+// lock files; a session holds one while it runs.
+function claimSlot(max, env = process.env) {
+  const dir = path.join(rootDir(env), 'slots');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  for (let n = 0; n < max; n++) {
+    const release = claimLockFile(path.join(dir, `${n}.lock`));
+    if (release) return release;
+  }
+  return null;
+}
+
+module.exports = {
+  RECORD_SCHEMA,
+  SessionExistsError,
+  sessionsDir,
+  sessionDir,
+  validId,
+  newId,
+  createSession,
+  readSession,
+  updateSession,
+  deleteSession,
+  writeResult,
+  readResult,
+  appendEvent,
+  readEvents,
+  pidAlive,
+  viewSession,
+  listSessions,
+  resolveSessionId,
+  claimSession,
+  claimSlot,
+  writeJsonAtomic,
+};

package/lib/ui.js

@@ -1,105 +1,234 @@
 'use strict';
-// Plain-mode terminal UI (lib/ui.js): one place for the "live feed" an
-// operator watches on stderr while stdout carries only the answer.
+// Plain-mode terminal UI. stdout carries the RESULT (the answer for run,
+// the handback summary for task); stderr carries the live feed. Nothing
+// here writes ANSI unless stderr/stdout is a TTY and NO_COLOR / TERM=dumb
+// are unset, and nothing animates — the feed is append-only lines, so a
+// non-interactive log reads exactly like the terminal did.
 //
-// Visual contract (deliberate, terminal-native):
-//   thinking   │ dimmed, every line prefixed "│ " - a quote block, clearly
-//               not the answer
-//   tool calls → started / ✓ ok / ✗ error, dimmed, one line each
-//   mcp status ◇ connected / ✗ failed, dimmed
-//   footer     one dimmed status line (model, effort, tool calls, time,
-//               session) - the session id is there so a plain-mode caller
-//               can pass it to --session without re-running with --json
-//
-// stdout is NEVER touched here. --quiet silences the whole feed.
+//   ▸ zcode zc-1a2b3c4d  task  GLM-5.3-Flash · effort max   session header
+//   ● executing                                             phase
+//   → Edit · ✓ Edit · ✗ Bash                                tools (dim)
+//   ⇢ subagent started / returned                           subagents
+//   ✓ npm test  3.2s · ✗ npm run lint  exit 1  1.1s         checks
+//   │ thinking …                                            reasoning (opt-in)
 
-function makePlainReporter({ quiet = false } = {}) {
-  const tty = process.stderr.isTTY;
-  const dim = (t) => (tty ? `\x1b[2m${t}\x1b[0m` : t);
+function useColor(stream, env = process.env) {
+  return Boolean(stream && stream.isTTY) && !('NO_COLOR' in env) && env.TERM !== 'dumb';
+}
 
-  let thinkingOpen = false; // a thinking block is being streamed
-  let atLineStart = true; // no "│ " written for this line yet
+function painter(enabled) {
+  const wrap = (code) => (t) => (enabled ? `\x1b[${code}m${t}\x1b[0m` : String(t));
+  return { dim: wrap(2), bold: wrap(1), red: wrap(31), green: wrap(32), yellow: wrap(33), cyan: wrap(36) };
+}
+
+const secs = (ms) => `${(ms / 1000).toFixed(1)}s`;
+
+function makeReporter({ quiet = false, thinking = true, stream = process.stderr, env = process.env } = {}) {
+  const c = painter(useColor(stream, env));
+  const out = (s) => {
+    if (!quiet) stream.write(s);
+  };
+  let thinkingOpen = false;
+  let atLineStart = true;
 
   const closeThinking = () => {
     if (thinkingOpen) {
       thinkingOpen = false;
+      if (!atLineStart) out('\n');
       atLineStart = true;
-      process.stderr.write('\n');
     }
   };
 
+  // One write per delta (not per character): prefix each new line with the
+  // quote bar, dim the whole chunk once.
   const writeThinking = (delta) => {
-    if (!thinkingOpen) {
-      thinkingOpen = true;
-      atLineStart = true;
-    }
-    for (const ch of delta) {
-      if (atLineStart) {
-        process.stderr.write(dim('│ '));
-        atLineStart = false;
-      }
-      if (ch === '\n') {
-        process.stderr.write('\n');
+    thinkingOpen = true;
+    let text = '';
+    for (const line of delta.split(/(\n)/)) {
+      if (line === '\n') {
+        text += '\n';
         atLineStart = true;
-      } else {
-        process.stderr.write(dim(ch));
+      } else if (line) {
+        text += (atLineStart ? '│ ' : '') + line;
+        atLineStart = false;
       }
     }
+    out(c.dim(text));
   };
 
-  const toolLine = (name, phase) => {
-    if (phase === 'started' || phase === 'scheduled') {
-      process.stderr.write(dim(`→ ${name} started\n`));
-    } else if (phase === 'result') {
-      process.stderr.write(dim(`✓ ${name} ok\n`));
-    } else if (phase === 'error') {
-      process.stderr.write(dim(`✗ ${name} error\n`));
-    }
-  };
-
-  const mcpLine = (ev) => {
-    if (ev.status === 'connected') {
-      process.stderr.write(dim(`◇ mcp ${ev.name} connected\n`));
-    } else if (ev.status === 'failed' || ev.status === 'timeout') {
-      process.stderr.write(
-        dim(`✗ mcp ${ev.name} ${ev.status}${ev.error ? ` (${ev.error})` : ''}\n`)
-      );
-    }
+  const line = (s) => {
+    closeThinking();
+    out(`${s}\n`);
   };
 
   const onEvent = (ev) => {
     if (quiet) return;
-    if (ev.type === 'stream' && ev.kind === 'reasoning_delta' && ev.delta) {
-      writeThinking(ev.delta);
-      return;
-    }
-    closeThinking();
-    if (ev.type === 'stream' && ev.kind === 'text_delta' && ev.delta) {
-      return; // the answer streams to stdout, not here
-    }
-    if (ev.type === 'tool' && ev.name) {
-      toolLine(ev.name, ev.phase);
-      return;
-    }
-    if (ev.type === 'mcp') {
-      mcpLine(ev);
+    switch (ev.type) {
+      case 'stream':
+        if (ev.kind === 'reasoning_delta' && ev.delta && thinking) writeThinking(ev.delta);
+        return;
+      case 'session': {
+        const head = `${c.bold('▸ zcode')} ${c.cyan(ev.id)}  ${ev.kind}${ev.resumed ? ' (resumed)' : ''}  ${c.dim(`${ev.model} · effort ${ev.effort}`)}`;
+        const scope = [
+          `  cwd ${ev.cwd}`,
+          ev.owns && ev.owns.length ? `owns ${ev.owns.join(', ')}` : null,
+          ev.checks && ev.checks.length ? `${ev.checks.length} check${ev.checks.length === 1 ? '' : 's'}` : null,
+        ].filter(Boolean);
+        line(head);
+        line(c.dim(scope.join('  ·  ')));
+        return;
+      }
+      case 'phase': {
+        const extra =
+          ev.phase === 'repairing' ? ` ${ev.attempt}/${ev.of}`
+            : ev.phase === 'checking' ? ` ${ev.count}`
+              : ev.reason ? ` (${ev.reason})` : '';
+        line(`${c.cyan('●')} ${ev.phase}${extra}`);
+        return;
+      }
+      case 'tool':
+        if (ev.phase === 'started' && ev.name) line(c.dim(`  → ${ev.name}`));
+        else if (ev.phase === 'error' && ev.name) line(c.dim(`  ✗ ${ev.name} error`));
+        return;
+      case 'subagent':
+        line(c.dim(`  ⇢ subagent ${ev.phase}`));
+        return;
+      case 'check':
+        if (ev.phase !== 'finished') return;
+        if (ev.ok) line(`  ${c.green('✓')} ${ev.command}  ${c.dim(secs(ev.durationMs))}`);
+        else line(`  ${c.red('✗')} ${ev.command}  ${c.dim(`${ev.timedOut ? 'timed out' : `exit ${ev.exitCode}`}  ${secs(ev.durationMs)}`)}`);
+        return;
+      case 'mcp':
+        if (ev.status === 'connected') line(c.dim(`  ◇ mcp ${ev.name} connected`));
+        else if (ev.status === 'failed' || ev.status === 'timeout') {
+          line(c.dim(`  ✗ mcp ${ev.name} ${ev.status}${ev.error ? ` (${ev.error})` : ''}`));
+        }
+        return;
+      case 'retry':
+        line(c.yellow(`  ↻ retrying ${ev.phase}: ${ev.reason}`));
+        return;
+      default:
     }
   };
 
-  const footer = ({ model, effort, toolCalls, durationMs, sessionId }) => {
+  // run-mode footer: one dim status line after the answer.
+  const footer = (r) => {
     if (quiet) return;
     closeThinking();
     const parts = [
-      model,
-      `effort ${effort}`,
-      typeof toolCalls === 'number' ? `${toolCalls} tool call${toolCalls === 1 ? '' : 's'}` : null,
-      `${(durationMs / 1000).toFixed(1)}s`,
-      sessionId ? sessionId.slice(0, 16) : null,
+      r.model,
+      `effort ${r.effort}`,
+      typeof r.toolCalls === 'number' ? `${r.toolCalls} tool call${r.toolCalls === 1 ? '' : 's'}` : null,
+      secs(r.durationMs),
+      r.id,
     ].filter(Boolean);
-    process.stderr.write(dim(`  ${parts.join('  ·  ')}\n`));
+    out(c.dim(`  ${parts.join('  ·  ')}\n`));
   };
 
   return { onEvent, closeThinking, footer };
 }
 
-module.exports = { makePlainReporter };
+const STATUS_MARK = {
+  completed: '✓',
+  unverified: '?',
+  partial: '◐',
+  blocked: '■',
+  failed: '✗',
+  cancelled: '■',
+};
+
+function statusColor(c, status) {
+  if (status === 'completed') return c.green;
+  if (status === 'failed') return c.red;
+  return c.yellow;
+}
+
+// The handback as a human reads it (task results, wait, resume). Ordered by
+// what an orchestrator scans for: status, what changed, what was checked,
+// what is wrong, how to continue.
+function formatResult(r, { color = false } = {}) {
+  const c = painter(color);
+  const L = [];
+  const st = statusColor(c, r.status);
+  L.push(`${st(`${STATUS_MARK[r.status] || '•'} ${r.status}`)}  ${c.bold(r.id)}${r.label ? `  ${r.label}` : ''}  ${c.dim(secs(r.durationMs || 0))}`);
+  if (r.summary) L.push(`  ${r.summary}`);
+  const files = (r.changes && r.changes.files) || [];
+  if (files.length) {
+    L.push(`changed  ${files.length} file${files.length === 1 ? '' : 's'}`);
+    for (const f of files.slice(0, 30)) {
+      const mark = f.change === 'added' ? 'A' : f.change === 'deleted' ? 'D' : 'M';
+      const note = f.concurrentSession ? c.dim(`  (session ${f.concurrentSession})`) : !f.owned ? c.red('  outside owned scope') : '';
+      L.push(`  ${mark} ${f.path}${note}`);
+    }
+    if (files.length > 30) L.push(c.dim(`  … ${files.length - 30} more`));
+  } else if (r.changes) {
+    L.push(`changed  ${r.changes.tracking === 'unavailable' ? 'not tracked' : 'nothing'}`);
+  }
+  if (r.checks && r.checks.length) {
+    const passed = r.checks.filter((x) => x.ok).length;
+    L.push(`checks   ${passed}/${r.checks.length} passed${r.repairs ? `  ·  ${r.repairs} repair turn${r.repairs === 1 ? '' : 's'}` : ''}`);
+    for (const x of r.checks) {
+      L.push(`  ${x.ok ? c.green('✓') : c.red('✗')} ${x.command}${x.ok ? '' : c.dim(`  ${x.timedOut ? 'timed out' : `exit ${x.exitCode}`}`)}`);
+    }
+  } else if (r.kind === 'task') {
+    L.push('checks   none declared');
+  }
+  if (r.subagents && r.subagents.length) {
+    L.push(`subagents ${r.subagents.length}`);
+    for (const s of r.subagents) {
+      L.push(c.dim(`  ${s.status === 'success' ? '✓' : '✗'} ${s.profileId || 'agent'}${s.title ? `  ${s.title}` : ''}${typeof s.durationMs === 'number' ? `  ${secs(s.durationMs)}` : ''}`));
+    }
+  }
+  for (const [label, items] of [
+    ['issues', r.issues],
+    ['questions', r.questions],
+    ['unresolved', r.unresolved],
+    ['not verified', r.notVerified],
+  ]) {
+    if (items && items.length) {
+      L.push(`${label}`);
+      for (const i of items) L.push(`  - ${i}`);
+    }
+  }
+  if (r.error && r.error.message && !(r.issues || []).includes(r.error.message)) {
+    L.push(`error    ${r.error.kind}: ${r.error.message.split('\n')[0]}`);
+  }
+  if (r.status !== 'completed' && r.status !== 'cancelled') {
+    L.push(c.dim(`next     zcode resume ${r.id} "<message>"`));
+  }
+  return L.join('\n') + '\n';
+}
+
+// One line per session for `zcode status` without an id.
+function formatSessionRow(s) {
+  const when = s.updatedAt ? s.updatedAt.replace('T', ' ').slice(0, 19) : '';
+  const state = s.state === 'finished' ? s.status || 'finished' : s.state;
+  return `${s.id.padEnd(18)} ${String(state).padEnd(11)} ${String(s.kind || '').padEnd(5)} ${when}  ${s.label || s.cwd || ''}`;
+}
+
+function formatSessionView(v, { events = [] } = {}) {
+  const L = [];
+  const state = v.state === 'finished' ? `finished (${v.status})` : v.state;
+  L.push(`${v.id}  ${v.kind}${v.label ? `  ${v.label}` : ''}`);
+  L.push(`  state    ${state}${v.live ? `  ·  phase ${v.phase}  ·  pid ${v.pid}` : ''}`);
+  L.push(`  cwd      ${v.cwd}`);
+  if (v.owns && v.owns.length) L.push(`  owns     ${v.owns.join(', ')}`);
+  L.push(`  model    ${v.model} · effort ${v.effort}  ·  turns ${v.turns || 0}`);
+  if (v.activity) {
+    L.push(`  activity ${v.activity.toolCalls || 0} tool calls · ${v.activity.subagentsStarted || 0} subagents${v.activity.lastTool ? ` · last ${v.activity.lastTool}` : ''} · ${v.activity.lastEventAt || ''}`);
+  }
+  if (v.state === 'interrupted') L.push(`  the owning process is gone; continue with: zcode resume ${v.id}`);
+  if (events.length) {
+    L.push('  recent');
+    for (const e of events) {
+      const what = e.type === 'phase' ? `● ${e.phase}`
+        : e.type === 'tool' ? `${e.phase} ${e.name}`
+          : e.type === 'check' ? `check ${e.command}${e.phase === 'finished' ? (e.ok ? ' ok' : ' failed') : ''}`
+            : e.type;
+      L.push(`    ${String(e.t || '').slice(11, 19)}  ${what}`);
+    }
+  }
+  return L.join('\n') + '\n';
+}
+
+module.exports = { makeReporter, formatResult, formatSessionRow, formatSessionView, useColor };