crewforth 0.0.1 → 3.0.0-rc.2

package/kit/studio/server/lib/session.js

@@ -0,0 +1,309 @@
+// Sessions the panel owns.
+//
+// An owned session is a `claude -p` child driven over stdin/stdout in
+// stream-json. It is given a session id up front, which means it writes its
+// transcript to the same place every other session does — so the canvas needs
+// no special case: the existing file-watched graph reads it like any other.
+// Only the conversation itself comes from the child's stdout, because that is
+// the one thing the file does not carry live.
+//
+// Permission modes are allow-listed, never deny-listed. A list of forbidden
+// modes would have to name them, and a panel that names a bypass is one
+// grep away from offering it.
+
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+
+import { prepare, pending, watch, cleanup } from './permissions.js';
+import { getFleet } from './fleet.js';
+
+export const ALLOWED_MODES = ['plan', 'acceptEdits', 'default'];
+const DEFAULT_MODE = 'plan';
+const MAX_EVENTS = 4000;        // ring buffer per session
+const MAX_MESSAGE_BYTES = 512 * 1024;
+
+const sessions = new Map();     // sessionId -> OwnedSession
+
+class OwnedSession {
+  constructor({ cwd, model, permissionMode, sessionId, resume, forked = false }) {
+    this.id = sessionId;
+    this.resumedFrom = resume ?? null;
+    // Whether this is a copy or the session itself. A copy is not a defeat but
+    // it is not the same thing either, and the UI has to be able to say which.
+    this.forked = forked;
+    this.cwd = cwd;
+    this.model = model ?? null;
+    this.permissionMode = permissionMode;
+    this.startedAt = Date.now();
+    this.state = 'starting';    // starting | idle | working | exited | failed
+    this.events = [];
+    this.seq = 0;
+    this.subscribers = new Set();
+    this.carry = '';
+    this.exit = null;
+    this.lastError = null;
+    this.turns = 0;
+    this.costUsd = 0;
+
+    // The gate is prepared before the child exists, so its very first tool call
+    // is already covered. A missing hook is reported, never worked around: a
+    // panel that silently ran ungated would be worse than one that cannot run.
+    this.gate = prepare(this.id);
+    this.pendingPermissions = [];
+    this.gateEvents = [];      // hook lifecycle, newest last
+    this.unwatch = this.gate
+      ? watch(this.id, (reqs) => {
+        this.pendingPermissions = reqs;
+        this.#emit({ type: 'permissions', pending: reqs });
+      })
+      : null;
+
+    const args = [
+      '-p', '--verbose',
+      '--input-format', 'stream-json',
+      '--output-format', 'stream-json',
+      '--include-partial-messages',
+      '--replay-user-messages',
+      '--forward-subagent-text',
+      // Gate decisions with the moment they happened. gate-log.tsv records the
+      // same decisions but carries no timestamp, so for a session we own this
+      // is the difference between "this happened at 13:42" and "this was in
+      // the log when we looked".
+      '--include-hook-events',
+      '--permission-mode', this.permissionMode,
+    ];
+
+    // Three shapes, and the difference matters to whoever is typing.
+    //
+    // A terminal continues a session by resuming it outright, and so can we:
+    // measured, a bare --resume kept the session_id, appended to the same
+    // transcript (13 lines became 20), opened no second file and answered from
+    // the earlier context. The panel used to fork every time, which is why
+    // continuing a session felt like being moved to a stranger.
+    //
+    // The one case that must fork is a session another process still holds.
+    // Two writers on one transcript is the corruption this guard exists for,
+    // and liveness is asked of `claude agents --json`, not assumed.
+    if (this.resumedFrom && !this.forked) {
+      // No --session-id here: it asks for a new session, which is the opposite
+      // of resuming one.
+      args.push('--resume', this.resumedFrom);
+    } else {
+      args.push('--session-id', this.id);
+      if (this.resumedFrom) args.push('--resume', this.resumedFrom, '--fork-session');
+    }
+    if (this.model) args.push('--model', this.model);
+    // Our own settings file in our own directory. The user's settings are never
+    // read, written or merged.
+    if (this.gate) args.push('--settings', this.gate.settingsPath);
+
+    this.child = spawn('claude', args, {
+      cwd: this.cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: process.env,
+    });
+
+    this.child.stdout.setEncoding('utf8');
+    this.child.stdout.on('data', (chunk) => this.#ingest(chunk));
+
+    this.child.stderr.setEncoding('utf8');
+    this.child.stderr.on('data', (t) => {
+      this.lastError = String(t).slice(0, 2000);
+      this.#emit({ type: 'stderr', text: this.lastError });
+    });
+
+    this.child.on('error', (e) => {
+      this.state = 'failed';
+      this.lastError = String(e?.message ?? e);
+      this.#emit({ type: 'fault', reason: this.lastError });
+    });
+
+    this.child.on('exit', (code, signal) => {
+      this.state = 'exited';
+      this.exit = { code, signal };
+      if (this.unwatch) { this.unwatch(); this.unwatch = null; }
+      this.#emit({ type: 'exit', code, signal });
+      // A spool outliving its session would leave stale requests behind for a
+      // hook that will never run again.
+      cleanup(this.id);
+    });
+  }
+
+  #ingest(chunk) {
+    const text = this.carry + chunk;
+    const lines = text.split('\n');
+    this.carry = lines.pop() ?? '';
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let rec;
+      try { rec = JSON.parse(line); } catch { continue; }
+      this.#absorb(rec);
+      this.#emit(rec);
+    }
+  }
+
+  // State the UI needs but the raw stream only implies.
+  #absorb(rec) {
+    if (rec?.type === 'system' && (rec.subtype === 'hook_started' || rec.subtype === 'hook_response')) {
+      // The bridge's own hook is noise here: the panel already shows those as
+      // permission cards, and listing them again would double every decision.
+      const ours = typeof rec.hook_name === 'string' && this.gate;
+      const ev = {
+        at: Date.now(),
+        phase: rec.subtype === 'hook_started' ? 'started' : 'finished',
+        hookId: rec.hook_id ?? null,
+        name: rec.hook_name ?? null,
+        event: rec.hook_event ?? null,
+        exitCode: rec.exit_code ?? null,
+        outcome: rec.outcome ?? null,
+        stderr: (rec.stderr ?? '').slice(0, 300) || null,
+        ours,
+      };
+      this.gateEvents.push(ev);
+      if (this.gateEvents.length > 500) this.gateEvents.shift();
+    }
+    if (rec?.type === 'system' && rec.subtype === 'init') this.state = 'idle';
+    else if (rec?.type === 'stream_event' && rec.event?.type === 'message_start') this.state = 'working';
+    else if (rec?.type === 'result') {
+      this.state = 'idle';
+      this.turns = rec.num_turns ?? this.turns;
+      if (typeof rec.total_cost_usd === 'number') this.costUsd = rec.total_cost_usd;
+    }
+  }
+
+  #emit(rec) {
+    const ev = { seq: (this.seq += 1), at: Date.now(), rec };
+    this.events.push(ev);
+    if (this.events.length > MAX_EVENTS) this.events.splice(0, this.events.length - MAX_EVENTS);
+    for (const fn of this.subscribers) {
+      try { fn(ev); } catch { /* a dead subscriber must not stall the stream */ }
+    }
+  }
+
+  /** Replay from `after`, then follow. Returns an unsubscribe function. */
+  subscribe(fn, after = 0) {
+    for (const ev of this.events) if (ev.seq > after) fn(ev);
+    this.subscribers.add(fn);
+    return () => this.subscribers.delete(fn);
+  }
+
+  send(text) {
+    if (this.state === 'exited' || this.state === 'failed') {
+      return { ok: false, reason: `session has ${this.state}` };
+    }
+    const body = String(text ?? '');
+    if (!body.trim()) return { ok: false, reason: 'empty message' };
+    if (Buffer.byteLength(body, 'utf8') > MAX_MESSAGE_BYTES) {
+      return { ok: false, reason: 'message too large' };
+    }
+    const line = `${JSON.stringify({ type: 'user', message: { role: 'user', content: body } })}\n`;
+    try {
+      this.child.stdin.write(line);
+    } catch (e) {
+      return { ok: false, reason: String(e?.message ?? e) };
+    }
+    this.state = 'working';
+    return { ok: true };
+  }
+
+  stop() {
+    try { this.child.stdin.end(); } catch { /* already closed */ }
+    try { this.child.kill('SIGTERM'); } catch { /* already gone */ }
+    // A child that ignores SIGTERM still has to go; the panel promised to stop it.
+    setTimeout(() => { try { this.child.kill('SIGKILL'); } catch { /* gone */ } }, 4000).unref();
+    return { ok: true };
+  }
+
+  summary() {
+    return {
+      sessionId: this.id,
+      cwd: this.cwd,
+      model: this.model,
+      permissionMode: this.permissionMode,
+      resumedFrom: this.resumedFrom,
+      // A copy, or the session itself continued. The UI must not blur these.
+      forked: this.forked,
+      state: this.state,
+      startedAt: this.startedAt,
+      turns: this.turns,
+      costUsd: this.costUsd,
+      exit: this.exit,
+      lastError: this.lastError,
+      events: this.seq,
+      // Stated rather than implied: a session without a gate must say so.
+      gated: Boolean(this.gate),
+      gateWaitSeconds: this.gate?.waitSeconds ?? null,
+      pendingPermissions: this.pendingPermissions,
+      gateEvents: this.gateEvents.slice(-40),
+    };
+  }
+}
+
+/**
+ * Is this session still held by a running process?
+ *
+ * Answered by the fleet, never guessed. When the fleet cannot be read the
+ * answer is "yes": an unreadable fleet must not be the reason two processes
+ * end up writing one transcript.
+ */
+async function isHeldOpen(id) {
+  try {
+    const fleet = await getFleet();
+    const rows = fleet?.sessions ?? fleet ?? [];
+    if (!Array.isArray(rows)) return true;
+    if (fleet && fleet.measured === false) return true;
+    return rows.some((r) => r.sessionId === id);
+  } catch {
+    return true;
+  }
+}
+
+export async function createSession({ cwd, model, permissionMode, resume } = {}) {
+  const dir = cwd || process.cwd();
+  if (!fs.existsSync(dir)) return { ok: false, reason: `no such directory: ${dir}` };
+
+  const mode = permissionMode ?? DEFAULT_MODE;
+  if (!ALLOWED_MODES.includes(mode)) {
+    // Allow-list, not deny-list: unknown modes are refused without this file
+    // ever having to write down the dangerous ones.
+    return { ok: false, reason: `permission mode not offered here: ${mode}` };
+  }
+
+  if (resume != null && !/^[A-Za-z0-9-]+$/.test(String(resume))) {
+    return { ok: false, reason: 'the session to resume is not an identifier' };
+  }
+
+  // Fork only when something else still has the session open.
+  const forked = resume ? await isHeldOpen(String(resume)) : false;
+  const sessionId = resume && !forked ? String(resume) : randomUUID();
+  if (sessions.has(sessionId)) {
+    return { ok: false, reason: 'the panel is already running that session' };
+  }
+  const s = new OwnedSession({
+    cwd: dir, model: model || null, permissionMode: mode, sessionId, resume: resume || null, forked,
+  });
+  sessions.set(sessionId, s);
+  return { ok: true, session: s };
+}
+
+export function getSession(id) { return sessions.get(id) ?? null; }
+
+export function listSessionsOwned() {
+  return [...sessions.values()].map((s) => s.summary());
+}
+
+/** Drop finished sessions that nobody is watching, so the map does not grow. */
+export function reap(maxAgeMs = 30 * 60 * 1000) {
+  const now = Date.now();
+  for (const [id, s] of sessions) {
+    const dead = s.state === 'exited' || s.state === 'failed';
+    if (dead && !s.subscribers.size && now - s.startedAt > maxAgeMs) sessions.delete(id);
+  }
+}
+
+export function stopAll() {
+  for (const s of sessions.values()) {
+    if (s.state !== 'exited' && s.state !== 'failed') s.stop();
+  }
+}

package/kit/studio/server/lib/terminal.js

@@ -0,0 +1,91 @@
+// Handing a session back to a real terminal.
+//
+// The panel cannot drive a session it did not start — measured: no command
+// enumerates or writes to another session, and Remote Control controls your own
+// session from elsewhere rather than the other way round. So for an observed
+// session the honest offer is not a disabled input box, it is a button that
+// opens the session where it can actually be driven.
+//
+// What gets run is returned to the caller verbatim. A panel that launches a
+// terminal window should be able to show exactly what it launched.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+/** Shell-quote for the command line the terminal will interpret. */
+function q(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+/** AppleScript string literal: backslashes and quotes, nothing else. */
+function osaQuote(s) {
+  return `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Build the launch for this platform.
+ * Returns null when nothing here knows how to open a terminal, so the caller
+ * can say so rather than fail silently.
+ */
+export function plan({ cwd, sessionId, command }) {
+  const inner = command ?? `claude --resume ${q(sessionId)}`;
+  const line = `cd ${q(cwd)} && ${inner}`;
+
+  if (process.platform === 'darwin') {
+    return {
+      platform: 'darwin',
+      via: 'Terminal.app',
+      line,
+      argv: ['osascript', '-e', `tell application "Terminal" to do script ${osaQuote(line)}`,
+        '-e', 'tell application "Terminal" to activate'],
+    };
+  }
+
+  if (process.platform === 'win32') {
+    // Windows Terminal when present, the console host otherwise.
+    const wt = ['wt.exe', '-d', cwd, 'cmd.exe', '/k', inner];
+    return { platform: 'win32', via: 'wt.exe', line, argv: wt };
+  }
+
+  // Linux and the rest: whichever emulator is actually installed. Names are
+  // tried by running them, not by resolving them — a name on PATH that fails
+  // to start is the failure mode this ordering exists for.
+  const candidates = [
+    ['x-terminal-emulator', ['-e', 'bash', '-lc', line]],
+    ['gnome-terminal', ['--working-directory', cwd, '--', 'bash', '-lc', line]],
+    ['konsole', ['--workdir', cwd, '-e', 'bash', '-lc', line]],
+    ['xfce4-terminal', ['--working-directory', cwd, '-e', `bash -lc ${q(line)}`]],
+    ['xterm', ['-e', 'bash', '-lc', line]],
+  ];
+  return { platform: process.platform, via: 'candidates', line, candidates };
+}
+
+/** Launch it, detached, and report what was run. */
+export function open({ cwd, sessionId, command }) {
+  if (!cwd || !fs.existsSync(cwd)) return { ok: false, reason: `no such directory: ${cwd}` };
+
+  const p = plan({ cwd, sessionId, command });
+  if (!p) return { ok: false, reason: `no terminal launcher known for ${process.platform}` };
+
+  const attempts = p.argv ? [p.argv] : p.candidates.map(([bin, args]) => [bin, ...args]);
+  const tried = [];
+
+  for (const argv of attempts) {
+    const [bin, ...args] = argv;
+    try {
+      const child = spawn(bin, args, { cwd, detached: true, stdio: 'ignore' });
+      child.unref();
+      // A spawn that fails asynchronously (ENOENT) reports through 'error';
+      // by then this call has returned, so the caller is told what was tried
+      // rather than promised that it worked.
+      let failed = null;
+      child.on('error', (e) => { failed = e; });
+      tried.push(bin);
+      return { ok: true, via: p.via, ran: argv, line: p.line, tried, asyncError: failed };
+    } catch (e) {
+      tried.push(`${bin} (${e?.code ?? 'failed'})`);
+    }
+  }
+
+  return { ok: false, reason: 'no terminal emulator could be started', tried };
+}

package/kit/studio/server/lib/transcript.js

@@ -0,0 +1,100 @@
+// Incremental JSONL reading.
+//
+// Transcripts are append-only and grow to megabytes, so re-parsing from byte
+// zero on every change is not an option. Each reader keeps a byte offset and
+// consumes only what was appended.
+//
+// A single record can itself be enormous (a pasted payload), so lines are
+// assembled from a carry buffer rather than assumed to fit in one read.
+
+import fsp from 'node:fs/promises';
+
+export class JsonlReader {
+  constructor(file) {
+    this.file = file;
+    this.offset = 0;
+    this.carry = '';
+    this.malformed = 0; // counted, never silently swallowed
+  }
+
+  /** Read everything appended since the last call. Returns parsed records.
+   *
+   * Async because a transcript read has stalled for tens of seconds on a Windows
+   * machine, and this sits under the stream tick — see the note at the top of
+   * projects.js. The read is no faster; it just no longer stops the loop.
+   */
+  async read() {
+    let st;
+    try { st = await fsp.stat(this.file); } catch { return []; }
+
+    // A shrunk file means it was replaced, not appended to. Start over rather
+    // than reading from a stale offset into the middle of a record.
+    if (st.size < this.offset) {
+      this.offset = 0;
+      this.carry = '';
+    }
+    if (st.size === this.offset) return [];
+
+    let chunk;
+    let fh;
+    try {
+      fh = await fsp.open(this.file, 'r');
+      const len = st.size - this.offset;
+      const buf = Buffer.allocUnsafe(len);
+      const { bytesRead } = await fh.read(buf, 0, len, this.offset);
+      chunk = buf.subarray(0, bytesRead).toString('utf8');
+      this.offset += bytesRead;
+    } catch {
+      return [];
+    } finally {
+      if (fh !== undefined) try { await fh.close(); } catch { /* already gone */ }
+    }
+
+    const text = this.carry + chunk;
+    const lines = text.split('\n');
+    // The last element is either '' (clean boundary) or a partial record.
+    this.carry = lines.pop() ?? '';
+
+    const out = [];
+    for (const line of lines) {
+      if (!line) continue;
+      try {
+        out.push(JSON.parse(line));
+      } catch {
+        this.malformed += 1;
+      }
+    }
+    return out;
+  }
+}
+
+/** One-shot full read. Used for files we do not intend to follow. */
+export async function readAll(file) {
+  const r = new JsonlReader(file);
+  const records = await r.read();
+  return { records, malformed: r.malformed };
+}
+
+/**
+ * Session context fill, measured the way Crewforth measures it.
+ *
+ * The trap this avoids cost Crewforth a 92%-full context reported as 0.9%: when
+ * a subagent returns, its tool_result lands in the MAIN transcript as a
+ * `type:"user"` record carrying `toolUseResult.usage`. That is the SUBAGENT's
+ * spend, not the session's. Only `.message.usage` on a non-sidechain assistant
+ * record counts.
+ */
+export function contextFill(records) {
+  let total = null;
+  for (const r of records) {
+    if (r?.isSidechain === true) continue;
+    if (r?.type !== 'assistant') continue;
+    const u = r?.message?.usage;
+    if (!u || u.cache_read_input_tokens == null) continue;
+    total =
+      (u.input_tokens ?? 0) +
+      (u.cache_read_input_tokens ?? 0) +
+      (u.cache_creation_input_tokens ?? 0);
+  }
+  return total;
+}