crewforth 3.1.0-rc.5 → 3.1.0-rc.7

package/kit/studio/server/hooks/studio-host.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// The permission host of a session Studio starts: an MCP server over stdio with one tool, `approve`, named to
+// Claude Code with --permission-prompt-tool.
+//
+// WHY IT EXISTS. In a `-p` run Claude Code offers the two tools that need a person, AskUserQuestion and
+// ExitPlanMode, only when the run has a permission host. Measured on Claude Code 2.1.294: with no host neither
+// is in the session's tool list; with this one both are. A session without them asked its question as prose and
+// could not leave plan mode at all.
+//
+// WHAT IT ANSWERS. Nothing, with one exception. Every prompt that reaches it is DENIED: the place a call is
+// allowed in Studio is the dock, through the PreToolUse hook (studio-gate.sh), before the call gets here. A call
+// that reaches this host is one the hook said nothing about, and before there was a host Claude Code refused
+// those itself, because nobody could answer. Denying here keeps that exactly.
+//
+// The exception is a plan the viewer approved WITH a change of mode. The hook cannot change the mode; the
+// permission host can, in its answer (measured: `updatedPermissions: [{ type: "setMode", … }]` moved a session
+// from plan to acceptEdits). So for that one case the hook stays silent, and this host finds what the viewer
+// decided in the spool — `host/<tool_use_id>.json`, written by the server when the answer was given — and
+// answers with it. The mode is one of two words, checked here as well as where it was written.
+//
+// No dependency: the protocol is three JSON-RPC methods on newline-delimited stdio.
+//
+// Usage: studio-host.mjs <spool-dir>
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const SPOOL = process.argv[2] ?? '';
+const MODES = ['acceptEdits', 'default'];
+const DENIED = 'Crewforth Studio: nobody answers this prompt here. A call is allowed in the Studio dock before it runs, or it is refused.';
+
+const send = (o) => process.stdout.write(`${JSON.stringify(o)}\n`);
+const text = (o) => ({ content: [{ type: 'text', text: JSON.stringify(o) }] });
+
+/** What the viewer decided for this call, when the decision is one only the host can deliver. Read once. */
+export function decisionFor(spool, toolName, toolUseId) {
+  if (toolName !== 'ExitPlanMode' || typeof toolUseId !== 'string' || !/^[A-Za-z0-9_-]+$/.test(toolUseId) || !spool) return null;
+  const file = path.join(spool, 'host', `${toolUseId}.json`);
+  let said;
+  try { said = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+  try { fs.rmSync(file); } catch { /* answered once either way: the hook asks again for a new call */ }
+  return MODES.includes(said?.mode) ? said.mode : null;
+}
+
+export function answer(spool, args) {
+  const mode = decisionFor(spool, args?.tool_name, args?.tool_use_id);
+  if (!mode) return { behavior: 'deny', message: DENIED };
+  return {
+    behavior: 'allow',
+    updatedInput: args.input ?? {},
+    updatedPermissions: [{ type: 'setMode', mode, destination: 'session' }],
+  };
+}
+
+function serve() {
+  let buf = '';
+  process.stdin.on('data', (d) => {
+    buf += d;
+    let i;
+    while ((i = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, i).trim();
+      buf = buf.slice(i + 1);
+      if (!line) continue;
+      let m;
+      try { m = JSON.parse(line); } catch { continue; }
+      if (m.method === 'initialize') {
+        send({ jsonrpc: '2.0', id: m.id, result: { protocolVersion: m.params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'crew-studio-host', version: '1' } } });
+      } else if (m.method === 'tools/list') {
+        send({
+          jsonrpc: '2.0',
+          id: m.id,
+          result: { tools: [{
+            name: 'approve',
+            description: 'Answers a permission prompt of a session Crewforth Studio started.',
+            inputSchema: { type: 'object', properties: { tool_name: { type: 'string' }, input: { type: 'object' }, tool_use_id: { type: 'string' } }, required: ['tool_name', 'input'] },
+          }] },
+        });
+      } else if (m.method === 'tools/call') {
+        send({ jsonrpc: '2.0', id: m.id, result: text(answer(SPOOL, m.params?.arguments)) });
+      } else if (m.id !== undefined) {
+        // Anything else that expects an answer gets an empty one; a notification gets none.
+        send({ jsonrpc: '2.0', id: m.id, result: {} });
+      }
+    }
+  });
+}
+
+// Imported by the selfcheck for `answer`; run by Claude Code as the server.
+// Node names the main module by its real path, so the path it was started with is resolved the same way.
+let main = false;
+try { main = pathToFileURL(fs.realpathSync(process.argv[1])).href === import.meta.url; } catch { /* not started as a script */ }
+if (main) serve();

package/kit/studio/server/index.js

@@ -17,18 +17,20 @@ import os from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { getFleet, measureSpawnCost } from './lib/fleet.js';
-import { projectDir, listSessions, findSession, listProjects, sessionCwd } from './lib/projects.js';
+import { projectDir, listSessions, findSession, listProjects, sessionCwd, agentMetaFiles } from './lib/projects.js';
+import { agentOrigins } from './lib/agent-origin.js';
 import { buildGraph, agentDetail, conversation, STALE_MS } from './lib/graph.js';
 import { cachedUsage } from './lib/usage.js';
+import { readModels, readRecord, readCosts } from './lib/model-outcomes.js';
 
 const USAGE_BATCH = 12;
 import { palette } from './lib/palette.js';
 import { latestVersion, latestVersionCached, kitStatus } from './lib/kit.js';
 import { parsePeers, askAll, ask } from './lib/peers.js';
 import {
-  createSession, getSession, listSessionsOwned, reap, stopAll, ALLOWED_MODES,
+  createSession, getSession, listSessionsOwned, reap, stopAll, dropSpools, ALLOWED_MODES,
 } from './lib/session.js';
-import { decide, pending, alwaysList, revoke } from './lib/permissions.js';
+import { decide, pending, alwaysList, revoke, sweepLeft } from './lib/permissions.js';
 import { open as openTerminal, plan as terminalPlan } from './lib/terminal.js';
 import { gateLog, gateReport, sessionStats, board } from './lib/kit-telemetry.js';
 import { writeState, clearStateSync, findRunning } from './lib/instance.js';
@@ -138,8 +140,45 @@ export function writeAllowed(req) {
   return { ok: true };
 }
 
+/**
+ * The record of outcomes for a project, with each agent's cost where it can be read. Only the sessions written
+ * since the record began are opened, and each is read once and kept until it grows (usage.js).
+ */
+/** The ids of the agents of one session, from the files it left: the only lines of the record a page of it needs. */
+async function agentIdsOf(session) {
+  if (!session?.subagentsDir) return [];
+  return (await agentMetaFiles(session.subagentsDir)).map((m) => path.basename(m).replace(/^agent-/, '').replace(/\.meta\.json$/, ''));
+}
+
+/**
+ * What the classes of a project cost: each agent's tokens at list price, from the transcripts of the project's
+ * sessions that are on this machine. Reading those is the expensive part of the Models view, so it is asked for
+ * apart from the record and less often, and a session whose transcript has not changed is not read again
+ * (`cachedUsage`).
+ */
+async function modelCosts(cwd) {
+  const rec = readRecord(cwd);
+  if (!rec.measured) return { measured: false, reason: rec.reason, costs: {}, sessionsRead: 0 };
+  const per = new Map();
+  const dir = await projectDir(cwd);
+  let read = 0;
+  if (dir) {
+    const since = (rec.firstAt ?? 0) - 3600_000;
+    for (const s of (await listSessions(dir)).filter((x) => x.modifiedAt >= since).slice(0, MODELS_SESSIONS_MAX)) {
+      const u = await cachedUsage(s);
+      read += 1;
+      for (const [id, a] of Object.entries(u.agents ?? {})) per.set(id, a.cost);
+    }
+  }
+  return { measured: true, costs: readCosts(cwd, (id) => (per.has(id) ? per.get(id) : null)), sessionsRead: read };
+}
+const MODELS_SESSIONS_MAX = 60;
+
 const MAX_BODY_BYTES = 1024 * 1024;
 
+/** The session events after which a subscriber is sent the session's summary again. */
+export const STATE_AFTER = new Set(['result', 'exit', 'mode']);
+
 function readBody(req) {
   return new Promise((resolve) => {
     let size = 0;
@@ -294,6 +333,24 @@ async function handle(req, res) {
   }
 
   // What Crewforth already measures about itself, reported as Crewforth reports it.
+  // Which model did which class of work in this project, and how it went: Crewforth's own record of outcomes,
+  // and the lines of it that belong to the session on screen. What the classes cost is the next route.
+  if (url.pathname === '/api/models') {
+    const sid = url.searchParams.get('session');
+    const session = sid ? await findSession(sid) : null;
+    const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
+    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', classes: [], suggestions: [], byAgent: {} });
+    return sendJson(res, 200, readModels(cwd, { agents: await agentIdsOf(session) }));
+  }
+
+  if (url.pathname === '/api/models/cost') {
+    const sid = url.searchParams.get('session');
+    const session = sid ? await findSession(sid) : null;
+    const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
+    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', costs: {}, sessionsRead: 0 });
+    return sendJson(res, 200, await modelCosts(cwd));
+  }
+
   if (url.pathname === '/api/kit') {
     const cwd = url.searchParams.get('cwd') || process.cwd();
     const sid = url.searchParams.get('session');
@@ -310,6 +367,14 @@ async function handle(req, res) {
     return sendJson(res, 200, palette());
   }
 
+  // Where the agents of a session's project are defined: the project's own files and the user's.
+  if (url.pathname === '/api/agents') {
+    const sid = url.searchParams.get('session');
+    const session = sid ? await findSession(sid) : null;
+    const cwd = session ? await sessionCwd(session.file, session.bytes) : null;
+    return sendJson(res, 200, { measured: true, ...agentOrigins(cwd) });
+  }
+
   if (url.pathname === '/api/sessions') {
     const cwd = url.searchParams.get('cwd') || process.cwd();
     const dir = await projectDir(cwd);
@@ -455,12 +520,12 @@ async function handle(req, res) {
     const body = await readBody(req);
     if (!body) return sendJson(res, 400, { ok: false, reason: 'body was not JSON' });
     const toolUseId = decodeURIComponent(permMatch[2]);
-    const out = decide(s.id, toolUseId, body.verdict);
+    const out = decide(s.id, toolUseId, body.verdict, { answers: body.answers, mode: body.mode });
     if (out.ok) s.noteDecision(toolUseId, body.verdict);
     return sendJson(res, out.ok ? 200 : 400, out);
   }
 
-  const ownedMatch = url.pathname.match(/^\/api\/owned\/([^/]+)(?:\/(message|stop|events))?$/);
+  const ownedMatch = url.pathname.match(/^\/api\/owned\/([^/]+)(?:\/(message|stop|events|mode))?$/);
   if (ownedMatch) {
     const s = getSession(decodeURIComponent(ownedMatch[1]));
     if (!s) return sendJson(res, 404, { ok: false, reason: 'no such owned session' });
@@ -476,6 +541,13 @@ async function handle(req, res) {
 
     if (verb === 'stop') return sendJson(res, 200, { ...s.stop(), session: s.summary() });
 
+    // The viewer chose another mode for the session, from the three a session may be started in.
+    if (verb === 'mode') {
+      const asked = await readBody(req);
+      const out = s.requestMode(asked?.mode);
+      return sendJson(res, out.ok ? 200 : 400, { ...out, session: s.summary() });
+    }
+
     const body = await readBody(req);
     if (!body) return sendJson(res, 400, { ok: false, reason: 'body was not JSON' });
     const sent = s.send(body.text);
@@ -728,7 +800,9 @@ function ownedStream(req, res, url, session) {
 
   const unsubscribe = session.subscribe((ev) => {
     write('event', ev);
-    if (ev.rec?.type === 'result' || ev.rec?.type === 'exit') write('state', session.summary());
+    // The summary is what a pane paints its strip from. It follows what changes it: a turn ending, the session
+    // going, and the mode Claude Code reports. Without the last, the strip waited for the beat below.
+    if (STATE_AFTER.has(ev.rec?.type)) write('state', session.summary());
   }, after);
 
   const beat = setInterval(() => write('state', session.summary()), 15000);
@@ -815,6 +889,10 @@ async function main() {
     process.exit(await selftest());
   }
 
+  // What an earlier server left under the temp directory when it was killed: gone before this one makes its own.
+  // Only a server that is about to run does this; asking for --help or --selftest removes nothing.
+  sweepLeft();
+
   const server = http.createServer((req, res) => {
     handle(req, res).catch((e) => {
       process.stderr.write(`crewforth-studio: unhandled: ${e?.stack ?? e}\n`);
@@ -900,6 +978,7 @@ async function main() {
       // Children outlive their parent unless told otherwise, and a panel that
       // leaks running sessions is worse than one that never started them.
       stopAll();
+      dropSpools();
       server.close(() => process.exit(0));
       setTimeout(() => process.exit(0), 2000).unref();
     });

package/kit/studio/server/lib/agent-origin.js

@@ -0,0 +1,44 @@
+// Where a Claude Code agent is defined, as far as that can be read from disk.
+//
+// Claude Code takes an agent that is not built in from a Markdown file whose frontmatter names it: in the project
+// (`.claude/agents/`), in the user's own directory (`~/.claude/agents/`), or in a plugin. This file reads the first
+// two and nothing else. It keeps no list of built-in types: an agent found in neither place is reported as not
+// found, which is all that is known about it.
+//
+// Not read: a plugin's files (a plugin agent is told by its name, `plugin:agent`, in web/names.js), agents given
+// on the command line, managed settings, and files in a directory under `agents/`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { PROJECTS_ROOT } from './projects.js';
+
+/** The agents one directory defines: { name: file name }. Null when the directory is not there or cannot be read. */
+export function agentsIn(dir) {
+  let files;
+  try { files = fs.readdirSync(dir); } catch { return null; }
+  const out = {};
+  for (const f of files.sort()) {
+    if (!f.endsWith('.md')) continue;
+    let src;
+    try { src = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+    // Frontmatter only, as the palette reads it: a "name:" in the body is not the agent's name.
+    const fm = src.replace(/\r\n/g, '\n').split(/^---$/m)[1] ?? '';
+    const name = fm.match(/^name:\s*(.+)$/m)?.[1]?.trim().replace(/^["']|["']$/g, '');
+    if (name && out[name] === undefined) out[name] = f;
+  }
+  return out;
+}
+
+/** Claude Code's own directory is the parent of its projects directory; the user's agents sit beside the projects. */
+export const USER_AGENTS_DIR = path.join(path.dirname(PROJECTS_ROOT), 'agents');
+
+/**
+ * @returns { project, user } — each { name: file name }, or null where that directory was not read. A project's
+ *          definition is the one Claude Code uses when both name the same agent, and it is listed in both here.
+ */
+export function agentOrigins(cwd, userDir = USER_AGENTS_DIR) {
+  return {
+    project: cwd ? agentsIn(path.join(cwd, '.claude', 'agents')) : null,
+    user: agentsIn(userDir),
+  };
+}

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

@@ -85,6 +85,41 @@ export function modelRank(model) {
   return i === -1 ? null : i;
 }
 
+// The tool a subagent hands its result back with. The report is the call's `message`; the agent often says
+// nothing after it, so a transcript with a handback and no closing text still holds a report.
+const HANDBACK = 'SubagentHandback';
+
+/**
+ * What an agent reported, from its own transcript, and where that was read from.
+ *
+ *   `closing`  — text the agent wrote after its last handback: its own last word, and it wins;
+ *   `handback` — the message of its last handback call, when nothing was written after it;
+ *   `text`     — with no handback at all, the last text it wrote (what came before is narration).
+ *
+ * Text written BEFORE a handback is narration on the way to it and is never the report.
+ * @returns { text, from } — text is null when the transcript holds none of the three
+ */
+export function reportIn(records) {
+  let lastText = null;       // the last text block of all
+  let afterHandback = null;  // the last text block since the last handback
+  let handback = null;
+  for (const r of records ?? []) {
+    if (r?.type !== 'assistant' || !Array.isArray(r.message?.content)) continue;
+    for (const c of r.message.content) {
+      if (c?.type === 'text' && typeof c.text === 'string' && c.text.trim()) {
+        lastText = c.text;
+        if (handback !== null) afterHandback = c.text;
+      } else if (c?.type === 'tool_use' && c.name === HANDBACK && typeof c.input?.message === 'string' && c.input.message.trim()) {
+        handback = c.input.message;
+        afterHandback = null;
+      }
+    }
+  }
+  if (afterHandback !== null) return { text: afterHandback, from: 'closing' };
+  if (handback !== null) return { text: handback, from: 'handback' };
+  return { text: lastText, from: lastText === null ? null : 'text' };
+}
+
 /** How a report says it ended: the `confidence: high|low` line a crew agent closes with, or null. */
 export function confidenceOf(text) {
   const m = typeof text === 'string' ? text.trimEnd().match(/(?:^|\n)\W*confidence:\s*(high|low)\W*$/i) : null;
@@ -287,7 +322,7 @@ async function scanAgent(file, usage = null, agentId = null) {
   const stats = {
     tools: {}, toolCount: 0, lastTool: null, errors: 0,
     model: null,      // the model its own transcript names: what it actually ran on
-    lastText: null,   // the end of the last thing it said, for the line a report closes with
+    lastText: null,   // the end of its report, for the line a report closes with
     tokens: null, startedAt: null, endedAt: null, turns: 0,
     owns: [], // tool_use ids this agent emitted — how nesting is resolved
   };
@@ -304,8 +339,6 @@ async function scanAgent(file, usage = null, agentId = null) {
       stats.turns += 1;
       const mdl = r.message?.model;
       if (typeof mdl === 'string' && mdl && mdl !== '<synthetic>') stats.model = mdl;
-      const said = textOf(r.message?.content);
-      if (said.trim()) stats.lastText = said.slice(-400);
       const u = r.message?.usage;
       if (u && u.cache_read_input_tokens != null) {
         stats.tokens = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
@@ -333,6 +366,8 @@ async function scanAgent(file, usage = null, agentId = null) {
   stats.durationMs = stats.startedAt !== null && stats.endedAt !== null
     ? stats.endedAt - stats.startedAt
     : null;
+  // The report, wherever the agent put it: the confidence line is its last line, handback included.
+  stats.lastText = reportIn(records).text?.slice(-400) ?? null;
   stats.midTurn = midTurn(records);
   stats.open = openCalls(records);
   return stats;
@@ -692,9 +727,10 @@ export async function agentDetail(session, agentId) {
     }
   }
 
-  // The report is the last text block the agent produced. Earlier blocks are
-  // narration between tool calls, which is progress rather than conclusion.
-  const report = texts.length ? texts[texts.length - 1].text : null;
+  // The report: what the agent wrote last, or what it handed back when it wrote nothing after that. Earlier
+  // blocks are narration between tool calls, which is progress rather than conclusion.
+  const reported = reportIn(records);
+  const report = reported.text;
 
   return {
     agentId,
@@ -705,9 +741,11 @@ export async function agentDetail(session, agentId) {
     spawnDepth: meta.spawnDepth ?? null,
     prompt,
     report,
+    // Where the report was read from: 'closing', 'handback' or 'text' (see reportIn); null when there is none.
+    reportFrom: reported.from,
     // Kept apart so the UI can show progress for an agent that has not
     // reported yet, without pretending the narration is a conclusion.
-    narration: texts.slice(0, -1).map((t) => t.text),
+    narration: texts.filter((t) => t.text !== report).map((t) => t.text),
     thinking: lastThinking,
     timeline,
     lastError,