@agenit/cli 2.1.0 → 2.1.2

package/control/panels/Debug.mjs

@@ -0,0 +1,681 @@
+// Debug Mode panel — LangSmith-style trace tree.
+//
+// Three columns: trace list (left), tree of selected trace (middle),
+// run detail (right). All reads come from /api/debug/state on mount
+// + per-trace `/api/debug/traces/<id>` on selection. Pending gates
+// surface in a banner at the top with Release/Skip/Abort buttons.
+//
+// When debug mode is OFF the panel shows a single "Turn on" call-to-
+// action that POSTs `/api/debug/config` `{enabled: true}`.
+import { h } from "preact";
+import { useEffect, useMemo, useState } from "preact/hooks";
+import htm from "htm";
+
+const html = htm.bind(h);
+
+const POLL_MS = 1500;
+
+function tokenFromUrl() {
+  try {
+    const u = new URL(window.location.href);
+    return u.searchParams.get("token");
+  } catch {
+    return null;
+  }
+}
+
+function authHeaders() {
+  const t = tokenFromUrl();
+  return t ? { "x-control-token": t } : {};
+}
+
+async function getJson(path) {
+  const res = await fetch(path, {
+    headers: { Accept: "application/json", ...authHeaders() },
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`${res.status} ${res.statusText} ${body}`);
+  }
+  return await res.json();
+}
+
+async function postJson(path, body) {
+  const res = await fetch(path, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...authHeaders(),
+    },
+    body: JSON.stringify(body ?? {}),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`${res.status} ${res.statusText} ${text}`);
+  }
+  return await res.json();
+}
+
+function statusGlyph(status) {
+  switch (status) {
+    case "ok":
+      return "✓";
+    case "error":
+      return "⨯";
+    case "running":
+      return "●";
+    case "aborted":
+      return "⏹";
+    case "skipped":
+      return "⊝";
+    default:
+      return "○";
+  }
+}
+
+function statusClass(status) {
+  return `debug-status debug-status-${status || "unknown"}`;
+}
+
+function formatDuration(ms) {
+  if (ms === null || ms === undefined) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+function flattenTree(runs) {
+  const byParent = new Map();
+  for (const r of runs) {
+    const arr = byParent.get(r.parentRunId);
+    if (arr) arr.push(r);
+    else byParent.set(r.parentRunId, [r]);
+  }
+  const out = [];
+  const walk = (parentId, depth) => {
+    const kids = byParent.get(parentId) ?? [];
+    for (const r of kids) {
+      out.push({ run: r, depth });
+      walk(r.id, depth + 1);
+    }
+  };
+  walk(null, 0);
+  return out;
+}
+
+function OffState({ onEnable, busy }) {
+  return html`
+    <div class="panel">
+      <h2 class="panel-title">Debug</h2>
+      <p class="placeholder">
+        Debug mode is <strong>OFF</strong>. Turn it on to start capturing
+        a tree of every chat turn, LLM call, tool dispatch, and agent
+        run. You can also flip it on from the REPL with
+        <code>/debug on</code> or <kbd>Ctrl+D</kbd>.
+      </p>
+      <button
+        type="button"
+        class="primary-button"
+        onClick=${onEnable}
+        disabled=${busy}
+      >
+        ${busy ? "enabling…" : "Turn on debug mode"}
+      </button>
+    </div>
+  `;
+}
+
+function PendingGatesBanner({ gates, onRelease, onSkip, onAbort }) {
+  if (gates.length === 0) return null;
+  return html`
+    <div class="debug-gates-banner" role="alert">
+      <div class="debug-gates-title">
+        ${gates.length} pending gate${gates.length === 1 ? "" : "s"} —
+        awaiting your decision
+      </div>
+      <ul class="debug-gates-list">
+        ${gates.map(
+          (g) => html`
+            <li key=${g.runId}>
+              <div class="debug-gate-row">
+                <span class="debug-gate-kind">${g.kind}</span>
+                <span class="debug-gate-desc">${g.description}</span>
+                <div class="debug-gate-actions">
+                  <button
+                    type="button"
+                    onClick=${() => onRelease(g.runId)}
+                  >
+                    release
+                  </button>
+                  <button
+                    type="button"
+                    onClick=${() => onSkip(g.runId)}
+                  >
+                    skip
+                  </button>
+                  <button
+                    type="button"
+                    class="danger"
+                    onClick=${() => onAbort(g.runId)}
+                  >
+                    abort
+                  </button>
+                </div>
+              </div>
+            </li>
+          `,
+        )}
+      </ul>
+    </div>
+  `;
+}
+
+function TraceList({ traces, selectedTraceId, onSelect }) {
+  if (traces.length === 0) {
+    return html`<div class="debug-empty">(no traces yet)</div>`;
+  }
+  return html`
+    <ul class="debug-trace-list">
+      ${traces.map((t) => {
+        const active = t.traceId === selectedTraceId;
+        return html`
+          <li key=${t.traceId}>
+            <button
+              type="button"
+              class=${"debug-trace-row " + (active ? "active" : "")}
+              onClick=${() => onSelect(t.traceId)}
+            >
+              <span class=${statusClass(t.status)}>${statusGlyph(t.status)}</span>
+              <span class="debug-trace-name">${t.name}</span>
+              <span class="debug-trace-meta">
+                ${formatDuration(t.durationMs)}
+                ${t.totalTokens ? html` · ${t.totalTokens} tok` : null}
+                ${t.totalCostUsd
+                  ? html` · $${t.totalCostUsd.toFixed(4)}`
+                  : null}
+              </span>
+            </button>
+          </li>
+        `;
+      })}
+    </ul>
+  `;
+}
+
+function TraceTree({ runs, selectedRunId, onSelect }) {
+  const flat = useMemo(() => flattenTree(runs), [runs]);
+  if (flat.length === 0) {
+    return html`<div class="debug-empty">(empty trace)</div>`;
+  }
+  return html`
+    <ul class="debug-tree">
+      ${flat.map(({ run, depth }) => {
+        const active = run.id === selectedRunId;
+        return html`
+          <li key=${run.id} style=${`padding-left: ${depth * 16}px`}>
+            <button
+              type="button"
+              class=${"debug-tree-row " + (active ? "active" : "")}
+              onClick=${() => onSelect(run.id)}
+            >
+              <span class=${statusClass(run.status)}>${statusGlyph(run.status)}</span>
+              <span class="debug-kind">[${run.kind}]</span>
+              <span class="debug-name">${run.name}</span>
+              <span class="debug-meta">
+                ${formatDuration(run.durationMs)}
+                ${run.tokens?.total ? html` · ${run.tokens.total}tk` : null}
+                ${run.costUsd ? html` · $${run.costUsd.toFixed(4)}` : null}
+              </span>
+            </button>
+          </li>
+        `;
+      })}
+    </ul>
+  `;
+}
+
+function RunDetail({ run, onAddTag, onReplay }) {
+  const [tagInput, setTagInput] = useState("");
+  const [replayArgs, setReplayArgs] = useState("");
+  const [replayBusy, setReplayBusy] = useState(false);
+  const [replayResult, setReplayResult] = useState(null);
+  if (!run) {
+    return html`<div class="debug-empty">select a run to see its inputs / outputs</div>`;
+  }
+  const submitTag = (ev) => {
+    ev.preventDefault();
+    const v = tagInput.trim();
+    if (!v) return;
+    onAddTag(run.id, v);
+    setTagInput("");
+  };
+  const isTool = run.kind === "tool";
+  const originalArgs = (run.inputs && run.inputs.args) || {};
+  const initialReplayBody = useMemo(
+    () => (isTool ? JSON.stringify(originalArgs, null, 2) : ""),
+    [isTool, JSON.stringify(originalArgs)],
+  );
+  // Initialise replayArgs from initialReplayBody when the selected run
+  // changes — preact useMemo above gives us a stable string per run.
+  useEffect(() => {
+    setReplayArgs(initialReplayBody);
+    setReplayResult(null);
+  }, [run.id]);
+
+  const doReplay = async () => {
+    let parsed = null;
+    try {
+      parsed = JSON.parse(replayArgs || "{}");
+    } catch (e) {
+      setReplayResult({ ok: false, output: `invalid JSON: ${e.message}` });
+      return;
+    }
+    setReplayBusy(true);
+    try {
+      const res = await onReplay(run.id, parsed);
+      setReplayResult({
+        ok: !res.isError,
+        output: res.output,
+        runId: res.runId,
+      });
+    } catch (e) {
+      setReplayResult({ ok: false, output: e.message });
+    } finally {
+      setReplayBusy(false);
+    }
+  };
+  return html`
+    <div class="debug-detail">
+      <div class="debug-detail-header">
+        <span class=${statusClass(run.status)}>${statusGlyph(run.status)}</span>
+        <span class="debug-kind">[${run.kind}]</span>
+        <span class="debug-name">${run.name}</span>
+      </div>
+      <div class="debug-detail-meta">
+        <span>id: ${run.id.slice(0, 8)}</span>
+        <span>${formatDuration(run.durationMs)}</span>
+        ${run.tokens?.total
+          ? html`<span>${run.tokens.total} tok</span>`
+          : null}
+        ${run.costUsd
+          ? html`<span>$${run.costUsd.toFixed(4)}</span>`
+          : null}
+        ${run.model ? html`<span>model: ${run.model}</span>` : null}
+        ${run.tier ? html`<span>tier: ${run.tier}</span>` : null}
+      </div>
+      ${run.error
+        ? html`<div class="debug-error">error: ${run.error}</div>`
+        : null}
+
+      <details open class="debug-section">
+        <summary>INPUTS</summary>
+        <pre class="debug-json">${JSON.stringify(run.inputs, null, 2)}</pre>
+      </details>
+
+      <details open class="debug-section">
+        <summary>OUTPUTS</summary>
+        <pre class="debug-json">${JSON.stringify(run.outputs, null, 2)}</pre>
+      </details>
+
+      ${run.events && run.events.length > 0
+        ? html`
+            <details class="debug-section">
+              <summary>EVENTS (${run.events.length})</summary>
+              <pre class="debug-json">
+${run.events.map((e) => JSON.stringify(e)).join("\n")}</pre>
+            </details>
+          `
+        : null}
+
+      <div class="debug-tags-row">
+        <span class="debug-tags-label">tags:</span>
+        ${run.tags && run.tags.length > 0
+          ? run.tags.map(
+              (t) => html`<span key=${t} class="debug-tag">${t}</span>`,
+            )
+          : html`<span class="debug-empty-inline">(none)</span>`}
+        <form onSubmit=${submitTag} class="debug-tag-form">
+          <input
+            type="text"
+            value=${tagInput}
+            placeholder="add tag…"
+            onInput=${(e) => setTagInput(e.currentTarget.value)}
+          />
+          <button type="submit">add</button>
+        </form>
+      </div>
+
+      ${isTool
+        ? html`
+            <details class="debug-section debug-replay">
+              <summary>REPLAY — re-fire this tool with the same or edited args</summary>
+              <div class="debug-replay-body">
+                <textarea
+                  class="debug-replay-input"
+                  rows="6"
+                  value=${replayArgs}
+                  onInput=${(e) => setReplayArgs(e.currentTarget.value)}
+                  spellcheck="false"
+                />
+                <div class="debug-replay-actions">
+                  <button
+                    type="button"
+                    class="primary-button"
+                    onClick=${doReplay}
+                    disabled=${replayBusy}
+                  >
+                    ${replayBusy ? "running…" : "Try call again"}
+                  </button>
+                  <button
+                    type="button"
+                    onClick=${() => setReplayArgs(initialReplayBody)}
+                    disabled=${replayBusy}
+                  >
+                    reset
+                  </button>
+                </div>
+                ${replayResult
+                  ? html`
+                      <div class=${"debug-replay-result " + (replayResult.ok ? "ok" : "error")}>
+                        ${replayResult.runId
+                          ? html`<div>new run: <code>${replayResult.runId.slice(0, 8)}</code></div>`
+                          : null}
+                        <pre>${replayResult.output}</pre>
+                      </div>
+                    `
+                  : null}
+              </div>
+            </details>
+          `
+        : null}
+    </div>
+  `;
+}
+
+function ConfigDrawer({ mode, onToggle, onSetKind, onSetFlag }) {
+  if (!mode) return null;
+  const pause = new Set(mode.pauseBeforeKinds);
+  return html`
+    <details class="debug-config">
+      <summary>Config</summary>
+      <div class="debug-config-body">
+        <label>
+          <input
+            type="checkbox"
+            checked=${mode.enabled}
+            onChange=${(e) => onToggle(e.currentTarget.checked)}
+          />
+          enabled
+        </label>
+        <label>
+          <input
+            type="checkbox"
+            checked=${mode.persistDeltas}
+            onChange=${(e) =>
+              onSetFlag("persistDeltas", e.currentTarget.checked)}
+          />
+          persistDeltas
+        </label>
+        <label>
+          <input
+            type="checkbox"
+            checked=${mode.persistThinking}
+            onChange=${(e) =>
+              onSetFlag("persistThinking", e.currentTarget.checked)}
+          />
+          persistThinking
+        </label>
+        <label>
+          <input
+            type="checkbox"
+            checked=${mode.noRedaction}
+            onChange=${(e) =>
+              onSetFlag("noRedaction", e.currentTarget.checked)}
+          />
+          noRedaction (⚠ secrets persisted verbatim)
+        </label>
+        <div class="debug-config-kinds">
+          <span>pause-before:</span>
+          ${["llm", "tool", "agent"].map(
+            (k) => html`
+              <label key=${k}>
+                <input
+                  type="checkbox"
+                  checked=${pause.has(k)}
+                  onChange=${(e) => onSetKind(k, e.currentTarget.checked)}
+                />
+                ${k}
+              </label>
+            `,
+          )}
+        </div>
+      </div>
+    </details>
+  `;
+}
+
+export function Debug() {
+  const [mode, setMode] = useState(null);
+  const [traces, setTraces] = useState([]);
+  const [gates, setGates] = useState([]);
+  const [selectedTraceId, setSelectedTraceId] = useState(null);
+  const [traceRuns, setTraceRuns] = useState([]);
+  const [selectedRunId, setSelectedRunId] = useState(null);
+  const [selectedRun, setSelectedRun] = useState(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+
+  const refreshState = async () => {
+    try {
+      const data = await getJson("/api/debug/state");
+      setMode(data.mode);
+      setTraces(data.recentTraces || []);
+      setGates(data.pendingGates || []);
+      setError(null);
+      if (
+        data.recentTraces.length > 0 &&
+        !data.recentTraces.find((t) => t.traceId === selectedTraceId)
+      ) {
+        setSelectedTraceId(data.recentTraces[0].traceId);
+      }
+    } catch (e) {
+      setError(e.message);
+    }
+  };
+
+  useEffect(() => {
+    refreshState();
+    const id = setInterval(refreshState, POLL_MS);
+    return () => clearInterval(id);
+  }, []);
+
+  // Load the selected trace's tree.
+  useEffect(() => {
+    if (!selectedTraceId) {
+      setTraceRuns([]);
+      setSelectedRunId(null);
+      return;
+    }
+    getJson(`/api/debug/traces/${encodeURIComponent(selectedTraceId)}`)
+      .then((d) => {
+        setTraceRuns(d.runs || []);
+        if (d.runs.length > 0) setSelectedRunId(d.runs[0].id);
+        else setSelectedRunId(null);
+      })
+      .catch((e) => setError(e.message));
+  }, [selectedTraceId]);
+
+  // Load full run detail when selection changes.
+  useEffect(() => {
+    if (!selectedRunId) {
+      setSelectedRun(null);
+      return;
+    }
+    getJson(`/api/debug/runs/${encodeURIComponent(selectedRunId)}`)
+      .then((d) => setSelectedRun(d.run))
+      .catch((e) => setError(e.message));
+  }, [selectedRunId]);
+
+  const turnOn = async () => {
+    setBusy(true);
+    try {
+      await postJson("/api/debug/config", { enabled: true });
+      await refreshState();
+    } catch (e) {
+      setError(e.message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const onToggleEnabled = async (on) => {
+    try {
+      await postJson("/api/debug/config", { enabled: on });
+      await refreshState();
+    } catch (e) {
+      setError(e.message);
+    }
+  };
+
+  const onSetFlag = async (field, value) => {
+    try {
+      await postJson("/api/debug/config", { [field]: value });
+      await refreshState();
+    } catch (e) {
+      setError(e.message);
+    }
+  };
+
+  const onSetKind = async (kind, on) => {
+    const cur = new Set(mode?.pauseBeforeKinds ?? []);
+    if (on) cur.add(kind);
+    else cur.delete(kind);
+    try {
+      await postJson("/api/debug/config", {
+        pauseBeforeKinds: Array.from(cur),
+      });
+      await refreshState();
+    } catch (e) {
+      setError(e.message);
+    }
+  };
+
+  const onGateAction = async (action, runId) => {
+    try {
+      await postJson(`/api/debug/gate/${encodeURIComponent(runId)}`, {
+        action,
+      });
+      await refreshState();
+    } catch (e) {
+      setError(e.message);
+    }
+  };
+
+  const onReplay = async (runId, argsOverride) => {
+    const res = await postJson(`/api/debug/replay/${encodeURIComponent(runId)}`, {
+      args: argsOverride,
+    });
+    // Refresh trace tree so the new sibling run appears.
+    if (selectedTraceId) {
+      const d = await getJson(
+        `/api/debug/traces/${encodeURIComponent(selectedTraceId)}`,
+      );
+      setTraceRuns(d.runs || []);
+    }
+    return res;
+  };
+
+  const onAddTag = async (runId, tag) => {
+    const merged = Array.from(new Set([...(selectedRun?.tags ?? []), tag]));
+    try {
+      await postJson(
+        `/api/debug/runs/${encodeURIComponent(runId)}/tags`,
+        { tags: merged },
+      );
+      const data = await getJson(
+        `/api/debug/runs/${encodeURIComponent(runId)}`,
+      );
+      setSelectedRun(data.run);
+    } catch (e) {
+      setError(e.message);
+    }
+  };
+
+  if (!mode) {
+    return html`
+      <div class="panel">
+        <h2 class="panel-title">Debug</h2>
+        <p class="placeholder">
+          ${error ? `error: ${error}` : "loading…"}
+        </p>
+      </div>
+    `;
+  }
+
+  if (!mode.enabled) {
+    return html`<${OffState} onEnable=${turnOn} busy=${busy} />`;
+  }
+
+  return html`
+    <div class="panel debug-panel">
+      <header class="debug-header">
+        <h2 class="panel-title">Debug</h2>
+        <div class="debug-header-meta">
+          <span>${traces.length} trace${traces.length === 1 ? "" : "s"}</span>
+          ${gates.length > 0
+            ? html`<span class="debug-header-pending">
+                · ${gates.length} pending gate${gates.length === 1 ? "" : "s"}
+              </span>`
+            : null}
+          ${mode.pauseBeforeKinds.length > 0
+            ? html`<span>· pause-before: ${mode.pauseBeforeKinds.join(", ")}</span>`
+            : null}
+        </div>
+        <${ConfigDrawer}
+          mode=${mode}
+          onToggle=${onToggleEnabled}
+          onSetKind=${onSetKind}
+          onSetFlag=${onSetFlag}
+        />
+      </header>
+
+      ${error ? html`<div class="debug-error">error: ${error}</div>` : null}
+
+      <${PendingGatesBanner}
+        gates=${gates}
+        onRelease=${(id) => onGateAction("release", id)}
+        onSkip=${(id) => onGateAction("skip", id)}
+        onAbort=${(id) => onGateAction("abort", id)}
+      />
+
+      <div class="debug-3pane">
+        <aside class="debug-traces">
+          <div class="debug-pane-title">Traces</div>
+          <${TraceList}
+            traces=${traces}
+            selectedTraceId=${selectedTraceId}
+            onSelect=${setSelectedTraceId}
+          />
+        </aside>
+
+        <section class="debug-tree-pane">
+          <div class="debug-pane-title">Tree</div>
+          <${TraceTree}
+            runs=${traceRuns}
+            selectedRunId=${selectedRunId}
+            onSelect=${setSelectedRunId}
+          />
+        </section>
+
+        <section class="debug-detail-pane">
+          <div class="debug-pane-title">Detail</div>
+          <${RunDetail}
+            run=${selectedRun}
+            onAddTag=${onAddTag}
+            onReplay=${onReplay}
+          />
+        </section>
+      </div>
+    </div>
+  `;
+}

package/control/shell/LeftNav.mjs

@@ -13,6 +13,7 @@ export const PANELS = [
   { id: "design", label: "Design" },
   { id: "memory", label: "Memory" },
   { id: "jobs", label: "Jobs" },
+  { id: "debug", label: "Debug" },
 ];
 
 export function LeftNav({ active, onSelect }) {