crewforth 3.0.3 → 3.1.0-rc.1

package/kit/studio/web/convo.js

@@ -0,0 +1,174 @@
+// What a conversation is made of, worked out from records with no page in it.
+//
+// The same shapes come from two places: the server's reading of a transcript (history, and sessions Studio only
+// watches) and the live stream of a session started here. Both go through these functions, so a tool row reads
+// the same whichever way it arrived.
+
+// How much of a tool's output the page keeps for a live result: the same tail the server keeps for history.
+const RESULT_TAIL = 4096;
+const SUMMARY_MAX = 80;
+
+const DELEGATION_TOOLS = new Set(['Agent', 'Task']);
+
+/** A `tool_use` content item as the block the panel draws. */
+export function toolBlock(c) {
+  const i = c?.input ?? {};
+  return {
+    kind: 'tool',
+    name: c?.name ?? 'tool',
+    label: i.description ?? i.file_path ?? i.command ?? i.pattern ?? i.query ?? null,
+    id: typeof c?.id === 'string' ? c.id : null,
+    subagentType: typeof i.subagent_type === 'string' ? i.subagent_type : null,
+    result: null,
+  };
+}
+
+/** A `tool_result` content item, cut to its tail, with the cut said. */
+export function resultFrom(c) {
+  const raw = typeof c?.content === 'string'
+    ? c.content
+    : Array.isArray(c?.content) ? c.content.filter((x) => x?.type === 'text').map((x) => x.text).join('\n') : '';
+  const truncated = raw.length > RESULT_TAIL;
+  return { error: c?.is_error === true, text: truncated ? raw.slice(-RESULT_TAIL) : raw, truncated, length: raw.length };
+}
+
+/** The tool results in one `user` record: [[toolUseId, result], …]. */
+export function resultsIn(content) {
+  if (!Array.isArray(content)) return [];
+  return content
+    .filter((c) => c?.type === 'tool_result' && typeof c.tool_use_id === 'string')
+    .map((c) => [c.tool_use_id, resultFrom(c)]);
+}
+
+/** Is this call the session handing work to an agent? */
+export function isDelegation(block) {
+  return block?.kind === 'tool' && DELEGATION_TOOLS.has(block.name);
+}
+
+/**
+ * What a tool row says after the tool's name and what it was run on.
+ *
+ * The output's own last line, and nothing made from it: "42 passed" is there because the test runner printed
+ * it. A call that has not come back says so, and so does one whose result was not read; neither is drawn as a
+ * call that returned nothing.
+ */
+export function summaryOf(block) {
+  const r = block?.result;
+  if (!r) return { state: 'pending', text: null };
+  const lines = r.text.split('\n').map((l) => l.trim()).filter(Boolean);
+  const last = lines.length ? lines[lines.length - 1] : null;
+  const text = last == null ? 'no output' : (last.length > SUMMARY_MAX ? `${last.slice(0, SUMMARY_MAX - 1)}…` : last);
+  return { state: r.error ? 'error' : 'ok', text };
+}
+
+/** The output as it is shown when a row is opened, with what was left out said first. */
+export function outputOf(block) {
+  const r = block?.result;
+  if (!r) return null;
+  if (!r.text) return '(no output)';
+  return r.truncated ? `… ${(r.length - r.text.length).toLocaleString('en-US')} earlier characters not shown\n${r.text}` : r.text;
+}
+
+/**
+ * The card a delegation is drawn as: the agent's type, its task, and — when the graph knows the agent that call
+ * became — its status. An agent the graph has not seen yet has no status here; none is guessed.
+ */
+export function delegationCard(block, nodes) {
+  const node = block.id ? (nodes ?? []).find((n) => n.kind === 'agent' && n.toolUseId === block.id) ?? null : null;
+  return {
+    type: block.subagentType ?? node?.agentType ?? 'agent',
+    task: block.label ?? node?.description ?? '',
+    agentId: node?.id ?? null,
+    status: node?.status ?? null,
+  };
+}
+
+/**
+ * The calls the viewer allowed and Claude Code refused anyway.
+ *
+ * An answer given in the dock is not the last word: the harness has its own checks after the hook, and a
+ * headless session has nobody to ask when one of them wants a person. The session's `result` record lists every
+ * call that was refused, by id; the ones this page allowed are the ones worth a line, because without it the
+ * dock said "allowed" and nothing happened. A tool that ran and failed is not in that list, and is not called
+ * a refusal here.
+ *
+ * @param denials     `permission_denials` of a result record
+ * @param wasAllowed  (toolUseId, toolName) => did this page allow it
+ * @param resultOf    toolUseId => the result on screen for that call, if there is one
+ */
+export function refusals(denials, wasAllowed, resultOf = () => null) {
+  const out = [];
+  for (const d of Array.isArray(denials) ? denials : []) {
+    if (typeof d?.tool_use_id !== 'string' || !wasAllowed(d.tool_use_id, d.tool_name ?? null)) continue;
+    const i = d.tool_input ?? {};
+    const what = i.command ?? i.file_path ?? i.description ?? null;
+    const reason = resultOf(d.tool_use_id)?.text?.split('\n').map((l) => l.trim()).filter(Boolean)[0] ?? null;
+    // Who refused is in the result's own words. Another PreToolUse hook that blocked the call is reported by
+    // the harness as a hook error; anything else is the harness's own check. With no result on screen the line
+    // says only what is known: it was allowed here and did not run.
+    const by = reason == null ? 'it did not run'
+      : /^PreToolUse:\S* hook error/.test(reason) ? 'another gate blocked it' : 'Claude Code refused it';
+    out.push({
+      id: d.tool_use_id,
+      text: `Allowed here, but ${by}: ${d.tool_name ?? 'tool'}${what ? ` · ${String(what).slice(0, 120)}` : ''}`
+        + (reason ? ` — ${reason.slice(0, 200)}` : ''),
+    });
+  }
+  return out;
+}
+
+/** The line that says a request is waiting, for the session a pane shows. Null when none is. */
+export function reminderOf(waiting) {
+  const list = waiting ?? [];
+  if (!list.length) return null;
+  const who = list[0].agentType ?? 'This session';
+  const more = list.length - 1;
+  return `${who} is waiting for approval${more > 0 ? `, and ${more} more ${more === 1 ? 'request is' : 'requests are'}` : ''}`;
+}
+
+/** The strip above a conversation: what kind of session this is, in the order the design has it. */
+export function headerOf(session, { readOnly = false, contextTokens = null } = {}) {
+  if (readOnly) return { badge: 'Read only', tone: 'none', parts: [] };
+  const parts = [];
+  if (session?.permissionMode) parts.push(`mode: ${session.permissionMode}`);
+  const facts = [];
+  if (typeof session?.turns === 'number') facts.push(`${session.turns} ${session.turns === 1 ? 'turn' : 'turns'}`);
+  if (contextTokens != null) facts.push(`${fmtK(contextTokens)} ctx`);
+  if (facts.length) parts.push(facts.join(' · '));
+  return {
+    badge: 'Started here',
+    tone: 'good',
+    parts,
+    // A session started here without the gate is running unguarded, and that is said in the strip itself.
+    ungated: session ? session.gated === false : false,
+  };
+}
+
+function fmtK(t) {
+  if (t < 1000) return `${t}`;
+  if (t < 1_000_000) return `${(t / 1000).toFixed(t < 10_000 ? 1 : 0)}k`;
+  return `${(t / 1_000_000).toFixed(2)}M`;
+}
+
+/**
+ * Run `fn` at most once per arming.
+ *
+ * A guard that only refuses while a request is in flight lets a second click through the moment the first
+ * answer lands: two clicks, two sessions. This one is spent by its first call and stays spent — a later call
+ * gets the first call's answer — until `arm()` says a new attempt is meant. A call that failed re-arms itself,
+ * so a refusal can be retried without reopening anything.
+ */
+export function oneShot(fn) {
+  let spent = null;
+  const run = (...args) => {
+    if (spent) return spent;
+    spent = Promise.resolve().then(() => fn(...args)).then(
+      (out) => { if (out && out.ok === false) spent = null; return out; },
+      (err) => { spent = null; throw err; },
+    );
+    return spent;
+  };
+  run.arm = () => { spent = null; };
+  run.spent = () => spent !== null;
+  return run;
+}

package/kit/studio/web/dock.js

@@ -0,0 +1,221 @@
+// The approval dock: a strip under the canvas that exists only while a tool call is waiting.
+//
+// Not a dialog. It takes no focus and covers nothing, so the graph stays usable while a request waits — and the
+// request is not forgotten either, because its clock is on screen and counting. What it says and when comes from
+// approvals.js; this file draws it and hands the three answers back.
+import { remaining, asker, allowSessionLabel, VERDICTS, OUTCOME_WORD } from './approvals.js';
+
+const SVG = 'http://www.w3.org/2000/svg';
+const RING = 2 * Math.PI * 15;      // the countdown ring's circumference, r = 15
+// How long "Denied" or "Timed out — denied" stays up. Shorter when another request is waiting behind it: its
+// clock is running while the word is on screen.
+const FLASH_MS = { alone: 2600, queued: 1400 };
+
+function mk(tag, cls, text) {
+  const n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text != null) n.textContent = text;
+  return n;
+}
+
+export class Dock {
+  /**
+   * @param root      the element the dock lives in
+   * @param onDecide  (item, verdict) => void — verdict is 'allow', 'always' or 'deny'
+   * @param onLocate  (item) => void — show the agent that asked
+   * @param where     (item) => the session's name when the request is not in the one on screen, else null
+   * @param now       () => the server's clock, in ms
+   */
+  constructor(root, { onDecide, onLocate, where, now } = {}) {
+    this.root = root;
+    this.onDecide = onDecide ?? (() => {});
+    this.onLocate = onLocate ?? (() => {});
+    this.where = where ?? (() => null);
+    this.now = now ?? (() => Date.now());
+    this.items = [];
+    this.at = 0;
+    this.open = false;        // the command shown in full
+    this.busy = new Set();    // requests an answer has been sent for
+    this.flash = null;        // { word, outcome, until }
+    this.flashTimer = null;
+    this.suppressed = false;  // another surface is showing the requests with their answers
+    this.#build();
+  }
+
+  #build() {
+    this.root.classList.add('dock');
+    this.root.tabIndex = -1;
+
+    const timer = mk('div', 'dock-timer');
+    timer.setAttribute('role', 'timer');
+    const svg = document.createElementNS(SVG, 'svg');
+    svg.setAttribute('viewBox', '0 0 36 36');
+    svg.setAttribute('aria-hidden', 'true');
+    const track = document.createElementNS(SVG, 'circle');
+    const ring = document.createElementNS(SVG, 'circle');
+    for (const c of [track, ring]) { c.setAttribute('cx', '18'); c.setAttribute('cy', '18'); c.setAttribute('r', '15'); }
+    track.setAttribute('class', 'dock-ring-track');
+    ring.setAttribute('class', 'dock-ring');
+    svg.append(track, ring);
+    const secs = mk('span', 'dock-secs');
+    timer.append(svg, secs);
+
+    const text = mk('div', 'dock-text');
+    const head = mk('div', 'dock-head');
+    const word = mk('span', 'dock-word', 'Needs you');
+    // Who asked is the way to them: it brings that agent's card into view.
+    const who = mk('button', 'dock-who');
+    who.type = 'button';
+    who.title = 'Show on the canvas';
+    who.addEventListener('click', () => { if (this.current) this.onLocate(this.current); });
+    const tool = mk('span', 'dock-tool');
+    const where = mk('span', 'dock-where');
+    head.append(word, who, tool, where);
+    // The command is a control: one line until it is asked for in full.
+    const cmd = mk('button', 'dock-cmd');
+    cmd.type = 'button';
+    cmd.addEventListener('click', () => { this.open = !this.open; this.paint(); });
+    const note = mk('div', 'dock-note');
+    text.append(head, cmd, note);
+
+    const nav = mk('div', 'dock-nav');
+    const prev = mk('button', 'btn icon sm ghost dock-step');
+    prev.type = 'button';
+    prev.setAttribute('aria-label', 'Previous request');
+    prev.innerHTML = '<svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M10 4l-4 4 4 4"/></svg>';
+    const count = mk('span', 'dock-count');
+    const next = mk('button', 'btn icon sm ghost dock-step');
+    next.type = 'button';
+    next.setAttribute('aria-label', 'Next request');
+    next.innerHTML = '<svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M6 4l4 4-4 4"/></svg>';
+    prev.addEventListener('click', () => this.step(-1));
+    next.addEventListener('click', () => this.step(1));
+    nav.append(prev, count, next);
+
+    const acts = mk('div', 'dock-acts');
+    const deny = mk('button', 'btn sm', VERDICTS.deny.label);
+    const always = mk('button', 'btn sm');
+    const allow = mk('button', 'btn sm primary', VERDICTS.allow.label);
+    for (const b of [deny, always, allow]) b.type = 'button';
+    deny.addEventListener('click', () => this.decide('deny'));
+    always.addEventListener('click', () => this.decide('always'));
+    allow.addEventListener('click', () => this.decide('allow'));
+    acts.append(deny, always, allow);
+
+    // a / s / d, and only while the dock itself has the focus: a letter typed anywhere else is a letter.
+    this.root.addEventListener('keydown', (e) => {
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      const verdict = { a: 'allow', s: 'always', d: 'deny' }[e.key];
+      if (!verdict) return;
+      e.preventDefault();
+      this.decide(verdict);
+    });
+
+    this.parts = { timer, ring, secs, word, who, tool, where, cmd, note, nav, prev, next, count, acts, deny, always, allow };
+    this.root.replaceChildren(timer, text, nav, acts);
+  }
+
+  get current() { return this.items[this.at] ?? null; }
+
+  /** The queue changed. The request being looked at stays the one being looked at, if it is still waiting. */
+  render(items) {
+    const was = this.current?.key ?? null;
+    this.items = items ?? [];
+    const keep = this.items.findIndex((r) => r.key === was);
+    this.at = keep === -1 ? Math.min(this.at, Math.max(0, this.items.length - 1)) : keep;
+    if (keep === -1) this.open = false;
+    for (const key of [...this.busy]) if (!this.items.some((r) => r.key === key)) this.busy.delete(key);
+    this.paint();
+  }
+
+  step(by) {
+    if (this.items.length < 2) return;
+    this.at = (this.at + by + this.items.length) % this.items.length;
+    this.open = false;
+    this.paint();
+  }
+
+  decide(verdict) {
+    const item = this.current;
+    // While the dock is saying what became of the last request, the next one is not on screen yet, and a key
+    // pressed then must not answer something nobody has read.
+    if (!item || this.busy.has(item.key) || this.flashing) return;
+    this.busy.add(item.key);
+    this.paint();
+    this.onDecide(item, verdict);
+  }
+
+  /** An answer could not be delivered: the buttons come back. */
+  release(key) { this.busy.delete(key); this.paint(); }
+
+  /** Say what became of a request for a moment: "Denied", "Timed out — denied". */
+  say(outcome, queued = false) {
+    const ms = queued ? FLASH_MS.queued : FLASH_MS.alone;
+    this.flash = { word: OUTCOME_WORD[outcome] ?? outcome, outcome, until: Date.now() + ms };
+    clearTimeout(this.flashTimer);
+    this.flashTimer = setTimeout(() => { this.flash = null; this.paint(); }, ms);
+    this.paint();
+  }
+
+  get flashing() { return Boolean(this.flash) && Date.now() < this.flash.until; }
+
+  /** The List view shows each request as a card with its own answers; the dock stands down while it does. */
+  setSuppressed(on) { this.suppressed = Boolean(on); this.paint(); }
+
+  /** Called once a second by the page, so the clock moves on its own. */
+  tick() { if (this.items.length || this.flash) this.paint(); }
+
+  paint() {
+    const p = this.parts;
+    const item = this.current;
+    const flashing = this.flashing;
+    this.root.hidden = this.suppressed || (!item && !flashing);
+    if (this.root.hidden) return;
+
+    // What became of the last request is said in the place it was, before the next one takes it.
+    for (const part of [p.timer, p.who, p.tool, p.where, p.cmd, p.note, p.nav, p.acts]) part.hidden = flashing;
+    if (flashing) {
+      this.root.dataset.state = this.flash.outcome;
+      p.word.textContent = this.flash.word;
+      this.root.setAttribute('aria-label', this.flash.word);
+      return;
+    }
+    this.root.dataset.state = 'waiting';
+    p.word.textContent = 'Needs you';
+
+    p.who.textContent = asker(item);
+    p.tool.textContent = item.toolName;
+    const where = this.where(item);
+    p.where.hidden = !where;
+    p.where.textContent = where ? `in ${where}` : '';
+    p.cmd.hidden = !item.detail;
+    p.cmd.textContent = item.detail ?? '';
+    p.cmd.classList.toggle('open', this.open);
+    p.cmd.setAttribute('aria-expanded', String(this.open));
+    p.cmd.title = this.open ? 'Show on one line' : 'Show the whole command';
+
+    const r = remaining(item, this.now());
+    if (r.known) {
+      p.ring.style.strokeDasharray = `${(r.fraction * RING).toFixed(1)} ${RING.toFixed(1)}`;
+      p.secs.textContent = `${r.left}s`;
+      p.timer.setAttribute('aria-label', `Auto-deny in ${r.left} seconds`);
+      p.note.textContent = `Auto-deny in ${r.left}s if nobody answers`;
+    } else {
+      // The server did not say how long the hook waits. No clock is better than an invented one.
+      p.ring.style.strokeDasharray = `0 ${RING.toFixed(1)}`;
+      p.secs.textContent = '?';
+      p.timer.setAttribute('aria-label', 'Time left not measured');
+      p.note.textContent = 'Time left not measured — it is denied if nobody answers';
+    }
+
+    p.nav.hidden = this.items.length < 2;
+    p.count.textContent = `${this.at + 1} of ${this.items.length}`;
+    p.nav.setAttribute('aria-label', `Request ${this.at + 1} of ${this.items.length}`);
+
+    const sent = this.busy.has(item.key);
+    p.always.textContent = allowSessionLabel(item.toolName);
+    p.always.title = `Allow this call, and stop asking here about ${item.toolName} for the rest of the session. Later calls are not approved for Claude Code: it still applies its own checks to them.`;
+    for (const b of [p.deny, p.always, p.allow]) b.disabled = sent;
+    this.root.setAttribute('aria-label', `Waiting for approval: ${asker(item)} wants to run ${item.toolName}`);
+  }
+}