crewforth 3.2.0-rc.1 → 3.2.0-rc.10

package/kit/studio/server/lib/owned-stream.js

@@ -0,0 +1,56 @@
+// owned-stream.js — the conversations of several owned sessions, replayed then followed, on ONE connection.
+//
+// A browser holds six connections to one host over HTTP/1.1, and a pane per stream reached them at five panes
+// beside the page's own: the panel kept painting, but a message sent and every request the page made itself waited
+// until a pane was closed (measured on Windows, Claude Code 2.1.301: a send did not arrive in 35 s, then in 8 s once
+// two panes closed). Each event and state carries the session id it belongs to.
+//   ids=a,b,c          the sessions (at most MAX_STREAM_IDS; an unknown id is answered with `gone`)
+//   after=a:12,b:3     resume each where the client last was, so a reconnect neither replays nor drops
+
+export const MAX_STREAM_IDS = 32;
+
+/** Read `ids` and `after` from a URL: the ids, de-duplicated and capped, and each one's resume point. */
+export function parseOwnedQuery(url) {
+  const ids = [...new Set((url.searchParams.get('ids') ?? '').split(',').filter(Boolean))].slice(0, MAX_STREAM_IDS);
+  const after = new Map();
+  for (const part of (url.searchParams.get('after') ?? '').split(',')) {
+    const at = part.lastIndexOf(':');
+    if (at > 0) after.set(part.slice(0, at), Number(part.slice(at + 1)) || 0);
+  }
+  return { ids, after };
+}
+
+/**
+ * @param getSession  id -> an owned session ({ summary(), subscribe(fn, after) }) or null
+ * @param stateAfter  the record types after which a session's summary is sent again
+ * @param beatMs      how often every summary is sent regardless
+ */
+export function streamOwned(req, res, url, { getSession, stateAfter = new Set(), beatMs = 15000 }) {
+  const { ids, after } = parseOwnedQuery(url);
+  res.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-store',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+  });
+  const write = (event, data) => {
+    try { res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); } catch { /* client gone */ }
+  };
+  const unsubscribes = [];
+  for (const id of ids) {
+    const s = getSession(id);
+    if (!s) { write('gone', { id }); continue; }
+    write('state', { id, session: s.summary() });
+    unsubscribes.push(s.subscribe((ev) => {
+      write('event', { id, ev });
+      if (stateAfter.has(ev.rec?.type)) write('state', { id, session: s.summary() });
+    }, after.get(id) ?? 0));
+  }
+  const beat = setInterval(() => {
+    for (const id of ids) { const s = getSession(id); if (s) write('state', { id, session: s.summary() }); }
+  }, beatMs);
+  const stop = () => { clearInterval(beat); for (const u of unsubscribes) u(); try { res.end(); } catch { /* gone */ } };
+  req.on('close', stop);
+  req.on('error', stop);
+  return stop;
+}

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

@@ -24,10 +24,17 @@ import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-// Overridable so a second instance can be pointed at a different transcript
-// store — which is also the only way to exercise the peer relay on one machine.
-export const PROJECTS_ROOT = process.env.CREW_STUDIO_PROJECTS_ROOT
-  || path.join(os.homedir(), '.claude', 'projects');
+// Where Claude Code writes its transcripts: <config dir>/projects, the config dir being CLAUDE_CONFIG_DIR when it is
+// set and ~/.claude otherwise. Reading ~/.claude alone, sessions started under a moved config dir (Studio's own
+// included) were not listed and read a cost of 0 (measured on Windows). The studio gate hook reads it the same way.
+// CREW_STUDIO_PROJECTS_ROOT still wins: a second instance pointed at a different store, which is also the only way to
+// exercise the peer relay on one machine.
+export function projectsRoot(env = process.env, home = os.homedir()) {
+  if (env.CREW_STUDIO_PROJECTS_ROOT) return env.CREW_STUDIO_PROJECTS_ROOT;
+  const config = env.CLAUDE_CONFIG_DIR ? path.resolve(env.CLAUDE_CONFIG_DIR) : path.join(home, '.claude');
+  return path.join(config, 'projects');
+}
+export const PROJECTS_ROOT = projectsRoot();
 
 /** Fold a working directory into the directory name Claude Code uses. */
 export function encodeCwd(cwd) {

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

@@ -0,0 +1,60 @@
+// redact.js — what a viewer whose link hides transcripts is sent.
+//
+// Text that came from a transcript (a prompt, a reply, a tool's input or output, the short task an agent was given,
+// a session's title) is not sent to such a viewer at all. Hiding it in the page would not do: it would still be on
+// the wire and in the phone's memory.
+//
+// AN ALLOW-LIST, NOT A DENY-LIST. Transcript text only ever travels as a string, so every string in an answer is
+// dropped unless its key is one of the few below, which name things that do not come from a transcript: ids,
+// states, model and agent-type names, tool names, times as text. A field added to an answer tomorrow is therefore
+// hidden until someone decides it is safe and adds its key here. Numbers, booleans and the shape of an answer pass,
+// so the viewer still sees the agents, their states, their timing and what they cost.
+//
+// A few routes are nothing but transcript (a conversation, an agent's detail, the live conversation of a session
+// the panel runs): those are refused outright rather than sent empty.
+
+/** Keys whose string values are not transcript text. Checked by key name, wherever in the answer they are. */
+export const SAFE_STRING_KEYS = new Set([
+  // identity and links between things
+  'id', 'sessionId', 'agentId', 'parentId', 'toolUseId', 'workflowId', 'workflow', 'source', 'target', 'origin',
+  // kinds and states
+  'kind', 'status', 'launchStatus', 'trigger', 'role', 'reason',
+  // which model and which kind of agent, and which tool (a tool's NAME, never its input)
+  'model', 'modelAsked', 'models', 'unpriced', 'agentType', 'toolName', 'lastTool', 'version',
+  // where, as the machine knows it rather than as anybody wrote it
+  'cwd', 'gitBranch', 'dir', 'url', 'read', 'at',
+]);
+
+// `label` is safe only where the server writes it from one of the safe things above (a session's short id, an agent
+// type, 'workflow'); measured in lib/graph.js. Anywhere else it is dropped like any other string.
+const LABEL_SAFE_KINDS = new Set(['session', 'agent', 'workflow']);
+
+/** Routes that are nothing but transcript: refused for a viewer whose link hides transcripts. */
+export function transcriptOnly(pathname) {
+  return /^\/api\/session\/[^/]+\/(conversation|agent\/[^/]+)$/.test(pathname)
+    || pathname === '/api/owned' || pathname === '/api/owned-events' || /^\/api\/owned\/[^/]+(\/.*)?$/.test(pathname);
+}
+
+/** The answer with every string that may be transcript text removed. A new object; the input is not touched. */
+export function redact(value, key = null, parent = null) {
+  if (typeof value === 'string') {
+    if (SAFE_STRING_KEYS.has(key)) return value;
+    if (key === 'label' && parent && LABEL_SAFE_KINDS.has(parent.kind)) return value;
+    // A machine's name (an origin: no sessionId of its own). A session's `name` is its title, written from its
+    // first prompt, and is dropped.
+    if (key === 'name' && parent && parent.sessionId === undefined && typeof parent.local === 'boolean') return value;
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value.map((x) => redact(x, key, parent)).filter((x) => x !== undefined);
+  }
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      const r = redact(v, k, value);
+      if (r !== undefined) out[k] = r;
+    }
+    return out;
+  }
+  return value;
+}

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

@@ -1,60 +1,129 @@
 // remote.js — read-only viewers.
 //
-// The panel's own token can start a session and answer a tool call. Handing that token to a phone, over
-// whatever tunnel reaches this machine, hands the phone all of it. A viewer token is the smaller thing: it
-// reads what the panel reads and can change nothing. The server decides that, not the page — a viewer's
-// request is refused here before any handler sees it.
+// The panel's own token can start a session and answer a tool call. Handing that token to a phone hands the phone
+// all of it. A viewer token is the smaller thing: it reads what the panel reads and can change nothing. The server
+// decides that, not the page — a viewer's request is refused here before any handler sees it.
 //
-// THE SERVER STILL LISTENS ON LOOPBACK ONLY. A viewer does not widen that. The way in from another device is a
-// tunnel the user runs (an ssh forward, a tailnet), and this module knows nothing about it.
+// THE WAY IN FROM ANOTHER DEVICE IS THE SAME WI-FI. While at least one viewer is live, the server also listens on
+// this machine's Wi-Fi address (index.js), and there it answers a viewer's token and nothing else: the panel's own
+// token is not accepted from the network at all. With no viewer, nothing listens beyond 127.0.0.1.
 //
-// Kept in memory, like the owner's token: a viewer lasts as long as the server that made it. A link that
-// survived a restart would be a credential nobody remembers handing out.
+// A viewer lasts EIGHT HOURS, or until it is revoked, or until the server stops — whichever comes first. Kept in
+// memory, like the owner's token: a link that survived a restart would be a credential nobody remembers handing out.
+// An expired token is remembered as expired (not as unknown) so the phone can say "Session expired" rather than
+// "no access", and only for as long as the server runs.
+//
+// TRANSCRIPTS ARE HIDDEN by default: a viewer made without `transcripts` is answered with no text that came from a
+// transcript (lib/redact.js does that on the server; the page hiding it would not be enough).
 import { randomUUID } from 'node:crypto';
 
 export const MAX_VIEWERS = 8;
+export const VIEWER_TTL_MS = 8 * 60 * 60 * 1000;
 const LABEL_MAX = 40;
+const LOG_MAX = 200;
 
 const viewers = new Map();          // id -> viewer
 const byToken = new Map();          // token -> viewer
+const expired = new Map();          // token -> label, for "Session expired"
+const log = [];                     // what happened to viewers' links, newest last
+
+let clock = () => Date.now();
+let onChange = () => {};
+let note = () => {};
+
+/** For the self-check: a clock it can move (eight hours are not waited for). */
+export function _setClock(fn) { clock = fn ?? (() => Date.now()); }
+/** index.js opens and closes the Wi-Fi listener when the number of live viewers changes. */
+export function onViewersChange(fn) { onChange = fn ?? (() => {}); }
+/** Where a log line also goes (the server's own output). */
+export function onLog(fn) { note = fn ?? (() => {}); }
+
+function record(entry) {
+  const e = { at: clock(), ...entry };
+  log.push(e);
+  if (log.length > LOG_MAX) log.splice(0, log.length - LOG_MAX);
+  note(e);
+}
 
 const publicOf = (v) => ({
   id: v.id,
   label: v.label,
   createdAt: v.createdAt,
+  expiresAt: v.expiresAt,
+  transcripts: v.transcripts,
   lastSeenAt: v.lastSeenAt,
   requests: v.requests,
   agent: v.agent,
   open: v.conns.size,
+  addresses: [...v.addresses],
 });
 
 /** Make a viewer. The token is in this answer and in no later one. */
-export function addViewer(label) {
+export function addViewer(label, { transcripts = false } = {}) {
+  sweep();
   if (viewers.size >= MAX_VIEWERS) {
     return { ok: false, reason: `${MAX_VIEWERS} viewers already; revoke one first` };
   }
   const named = typeof label === 'string' ? label.replace(/\s+/g, ' ').trim().slice(0, LABEL_MAX) : '';
+  const now = clock();
   const v = {
     id: randomUUID().slice(0, 8),
     label: named || `Viewer ${viewers.size + 1}`,
     token: randomUUID(),
-    createdAt: Date.now(),
+    createdAt: now,
+    expiresAt: now + VIEWER_TTL_MS,
+    transcripts: transcripts === true,
     lastSeenAt: null,
     requests: 0,
     agent: null,
     conns: new Set(),
+    addresses: new Set(),
   };
   viewers.set(v.id, v);
   byToken.set(v.token, v);
+  record({ event: 'added', viewer: v.label, transcripts: v.transcripts });
+  onChange(viewers.size);
   return { ok: true, viewer: { ...publicOf(v), token: v.token } };
 }
 
 export function listViewers() {
+  sweep();
   return [...viewers.values()].map(publicOf);
 }
 
+export function liveCount() {
+  sweep();
+  return viewers.size;
+}
+
+export function remoteLog(n = 50) {
+  return log.slice(-n);
+}
+
+/** The viewer this token belongs to, if it is live; `{ expired: label }` if it was one and its eight hours are up. */
 export function viewerByToken(token) {
-  return (typeof token === 'string' && byToken.get(token)) || null;
+  if (typeof token !== 'string') return null;
+  const v = byToken.get(token);
+  if (v && clock() >= v.expiresAt) { end(v, 'expired'); return { expired: v.label }; }
+  if (v) return v;
+  if (expired.has(token)) return { expired: expired.get(token) };
+  return null;
+}
+
+function end(v, why) {
+  viewers.delete(v.id);
+  byToken.delete(v.token);
+  if (why === 'expired') expired.set(v.token, v.label);
+  for (const res of v.conns) { try { res.destroy(); } catch { /* already gone */ } }
+  v.conns.clear();
+  record({ event: why, viewer: v.label });
+  onChange(viewers.size);
+}
+
+/** End every viewer whose eight hours are up. Called on every read of the list and by index.js's timer. */
+export function sweep() {
+  const now = clock();
+  for (const v of [...viewers.values()]) if (now >= v.expiresAt) end(v, 'expired');
 }
 
 /**
@@ -64,23 +133,38 @@ export function viewerByToken(token) {
 export function revokeViewer(id) {
   const v = viewers.get(id);
   if (!v) return { ok: true, revoked: false };
-  viewers.delete(id);
-  byToken.delete(v.token);
-  for (const res of v.conns) { try { res.destroy(); } catch { /* already gone */ } }
-  v.conns.clear();
+  end(v, 'revoked');
   return { ok: true, revoked: true };
 }
 
-/** Count a viewer's request and remember its response for as long as it is open. */
+/** Count a viewer's request and remember its response for as long as it is open. A new address is logged once. */
 export function noteRequest(v, req, res) {
   v.requests += 1;
-  v.lastSeenAt = Date.now();
+  v.lastSeenAt = clock();
   const ua = req.headers['user-agent'];
   v.agent = typeof ua === 'string' ? ua.slice(0, 160) : null;
+  const ip = req.socket?.remoteAddress ?? null;
+  if (ip && !v.addresses.has(ip)) {
+    v.addresses.add(ip);
+    record({ event: 'connected', viewer: v.label, ip, over: req.crewLan ? 'wifi' : 'loopback', result: 'ok' });
+  }
   v.conns.add(res);
   res.on('close', () => v.conns.delete(res));
 }
 
+/**
+ * A request that was turned away: logged with who it claimed to be, from where, and why. The same refusal again
+ * (same viewer, address, path and answer) is counted on its entry rather than written again, so a page that keeps
+ * asking cannot push everything else out of the log.
+ */
+export function noteRefusal(req, { viewer = null, status, reason }) {
+  const e = { event: 'refused', viewer, ip: req.socket?.remoteAddress ?? null, over: req.crewLan ? 'wifi' : 'loopback',
+    result: `${status} ${reason}`, path: String(req.url ?? '').split('?')[0].slice(0, 120) };
+  const same = log.findLast((x) => x.event === 'refused' && x.viewer === e.viewer && x.ip === e.ip && x.path === e.path && x.result === e.result);
+  if (same) { same.count = (same.count ?? 1) + 1; same.lastAt = clock(); return; }
+  record(e);
+}
+
 /**
  * What a viewer may ask for: a GET of anything the panel reads, and nothing about viewers themselves.
  * The list of viewers is the owner's; a viewer that could read it could count who else is watching.
@@ -95,5 +179,7 @@ export function viewerMay(method, pathname) {
 
 /** For the self-check: start from nothing. */
 export function _reset() {
-  for (const id of [...viewers.keys()]) revokeViewer(id);
+  for (const v of [...viewers.values()]) end(v, 'revoked');
+  expired.clear();
+  log.length = 0;
 }

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

@@ -290,7 +290,7 @@ class OwnedSession {
  * answer is "yes": an unreadable fleet must not be the reason two processes
  * end up writing one transcript.
  */
-async function isHeldOpen(id) {
+export async function isHeldOpen(id) {
   try {
     const fleet = await getFleet();
     const rows = fleet?.sessions ?? fleet ?? [];

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

@@ -17,21 +17,60 @@ function q(s) {
   return `'${String(s).replace(/'/g, `'\\''`)}'`;
 }
 
+/** PowerShell literal string: a quote is doubled, nothing else is special inside one. */
+function psq(s) {
+  return `'${String(s).replace(/'/g, "''")}'`;
+}
+
+/**
+ * A session id is a UUID. It comes from the URL, and on Windows it ends up in a line cmd.exe interprets, where a
+ * quote is not a quote (cmd hands `'` to the program as part of the id) and `&` starts a second command. So
+ * nothing is built for anything else, and an id that passes needs no quoting in any shell.
+ */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isSessionId(s) {
+  return typeof s === 'string' && SESSION_ID.test(s);
+}
+
 /** AppleScript string literal: backslashes and quotes, nothing else. */
 function osaQuote(s) {
   return `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
 
+/**
+ * The command that opens the session in the Claude Desktop app again (`claude --desktop`, CLI 2.1.299), from its
+ * own directory: `--resume <id>` looks for the session among that directory's. On Windows it is a PowerShell line
+ * (5.1 and 7; Windows Terminal opens PowerShell): cmd needs `&&` and does not take single quotes, PowerShell 5.1
+ * rejects `&&`, and no one line works in both. `shell` says which, so the panel can say so.
+ */
+export function desktopLine({ cwd, sessionId, platform = process.platform }) {
+  if (!isSessionId(sessionId)) return null;
+  if (platform === 'win32') {
+    return { shell: 'PowerShell', line: `Set-Location -LiteralPath ${psq(cwd)}; claude --desktop --resume ${sessionId}` };
+  }
+  return { shell: 'sh', line: `cd ${q(cwd)} && claude --desktop --resume ${q(sessionId)}` };
+}
+
 /**
  * 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)}`;
+export function plan({ cwd, sessionId, platform = process.platform }) {
+  if (!isSessionId(sessionId)) return null;
+
+  if (platform === 'win32') {
+    // Windows Terminal when present, the console host otherwise. wt sets the directory itself; what runs inside is
+    // cmd.exe, so the line shown is a cmd line: double quotes, `cd /d` for another drive, and the id bare (a UUID).
+    const inner = `claude --resume ${sessionId}`;
+    const wt = ['wt.exe', '-d', cwd, 'cmd.exe', '/k', inner];
+    return { platform: 'win32', via: 'wt.exe', shell: 'cmd', line: `cd /d "${cwd}" && ${inner}`, argv: wt };
+  }
+
+  const inner = `claude --resume ${q(sessionId)}`;
   const line = `cd ${q(cwd)} && ${inner}`;
 
-  if (process.platform === 'darwin') {
+  if (platform === 'darwin') {
     return {
       platform: 'darwin',
       via: 'Terminal.app',
@@ -41,12 +80,6 @@ export function plan({ cwd, sessionId, command }) {
     };
   }
 
-  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.
@@ -57,14 +90,19 @@ export function plan({ cwd, sessionId, command }) {
     ['xfce4-terminal', ['--working-directory', cwd, '-e', `bash -lc ${q(line)}`]],
     ['xterm', ['-e', 'bash', '-lc', line]],
   ];
-  return { platform: process.platform, via: 'candidates', line, candidates };
+  return { platform, via: 'candidates', line, candidates };
 }
 
-/** Launch it, detached, and report what was run. */
-export function open({ cwd, sessionId, command }) {
+/**
+ * Launch it, detached, and report what was run. What runs is always `claude --resume <id>`: the route used to take a
+ * `command` from the request body and run it in place of that, with no id check, and the panel never sent one. An
+ * unused way to run anything in a terminal, behind a token that remote access puts on the network, was removed.
+ */
+export function open({ cwd, sessionId }) {
   if (!cwd || !fs.existsSync(cwd)) return { ok: false, reason: `no such directory: ${cwd}` };
 
-  const p = plan({ cwd, sessionId, command });
+  if (!isSessionId(sessionId)) return { ok: false, reason: `not a session id: ${sessionId}` };
+  const p = plan({ cwd, sessionId });
   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]);

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

@@ -98,3 +98,35 @@ export function contextFill(records) {
   }
   return total;
 }
+
+/**
+ * What the context is made of since the last compaction: the share of its text that is tool output, and how many
+ * times the session was compacted, with the last one's tokens before and after. Measured in characters of the main
+ * session's records (text, a tool call's input, a tool's result), not tokens: the transcript keeps no per-block
+ * token count. A compaction is the transcript's own `compact_boundary` record.
+ */
+export function contextMix(records) {
+  let start = 0; let compactions = 0; let last = null;
+  records.forEach((r, i) => {
+    if (r?.isSidechain !== true && r?.type === 'system' && r?.subtype === 'compact_boundary') { start = i + 1; compactions += 1; last = r.compactMetadata ?? null; }
+  });
+  const size = (b) => {
+    if (typeof b === 'string') return b.length;
+    if (b?.type === 'text') return String(b.text ?? '').length;
+    if (b?.type === 'tool_use') return JSON.stringify(b.input ?? {}).length;
+    if (b?.type === 'tool_result') return typeof b.content === 'string' ? b.content.length : (Array.isArray(b.content) ? b.content.reduce((n, x) => n + (x?.type === 'text' ? String(x.text ?? '').length : 0), 0) : 0);
+    return 0;
+  };
+  let tool = 0; let all = 0;
+  for (let i = start; i < records.length; i += 1) {
+    const r = records[i];
+    if (r?.isSidechain === true || (r?.type !== 'user' && r?.type !== 'assistant')) continue;
+    const c = r?.message?.content;
+    for (const b of Array.isArray(c) ? c : [c]) { const n = size(b); all += n; if (b?.type === 'tool_result') tool += n; }
+  }
+  return {
+    toolShare: all ? Math.round((100 * tool) / all) : null,
+    compactions,
+    lastCompact: last ? { trigger: last.trigger ?? null, before: last.preTokens ?? null, after: last.postTokens ?? null } : null,
+  };
+}