tablewalk 0.0.1

package/dist/client/agent.js

@@ -0,0 +1,262 @@
+/**
+ * The agent console: the MCP tools, driven by hand.
+ *
+ * MCP is invisible by design — newline-delimited JSON between two programs —
+ * which leaves nowhere to *watch* it. This is that place: the tool list an
+ * agent's client would receive, a form for each tool's arguments, and the
+ * answer exactly as an agent gets it, stats and all. The claim is structural
+ * rather than aspirational: the endpoint underneath calls the same runTool
+ * the stdio loop calls.
+ *
+ * What it is for: tuning tool descriptions by reading them the way a model
+ * would, checking what a call costs before an agent pays it on every step,
+ * and debugging "why did the agent do that" by replaying its calls.
+ */
+import { api, el, state, toast, trapFocus } from './core.js';
+
+let panel = null;
+/** Undoes the focus trap, and hands the keyboard back where it came from. */
+let release = null;
+let tools = [];
+/** Calls made while the console has been open, newest first. */
+let transcript = [];
+
+export function openAgentConsole() {
+  if (panel) return;
+  panel = el('div', { class: 'conn-manager agent-console', role: 'dialog', 'aria-modal': 'true', 'aria-label': 'Agent console' });
+  document.body.append(panel);
+  release = trapFocus(panel);
+  document.addEventListener('keydown', onKey, true);
+  panel.replaceChildren(el('div', { class: 'conn-inner' }, [el('p', { class: 'loading', text: 'Reading the tools…' })]));
+  void load();
+}
+
+function close() {
+  release?.();
+  release = null;
+  panel?.remove();
+  panel = null;
+  transcript = [];
+  document.removeEventListener('keydown', onKey, true);
+}
+
+function onKey(e) {
+  if (e.key !== 'Escape') return;
+  const tag = document.activeElement?.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') { document.activeElement.blur(); return; }
+  e.preventDefault();
+  close();
+}
+
+async function load() {
+  try {
+    tools = (await api('/api/agent/tools')).tools ?? [];
+  } catch (err) {
+    toast(err.message, 'error');
+    close();
+    return;
+  }
+  paint(tools[0]?.name);
+}
+
+/** ~4 characters per token is the rule of thumb the readout says it is. */
+const cost = (text) => `${text.length.toLocaleString()} chars · ~${Math.ceil(text.length / 4).toLocaleString()} tokens`;
+
+function badges(tool) {
+  const a = tool.annotations ?? {};
+  const badge = (text, tone) => el('span', { class: `agent-badge tone-${tone}`, text });
+  if (a.readOnlyHint) return [badge('read-only', 'ok')];
+  return [
+    badge('writes', 'warn'),
+    a.destructiveHint ? badge('destructive', 'bad') : null,
+  ].filter(Boolean);
+}
+
+function paint(selectedName) {
+  const tool = tools.find((t) => t.name === selectedName) ?? tools[0];
+  const result = el('div', { class: 'agent-result' });
+
+  const list = el('div', { class: 'agent-tools', role: 'listbox', 'aria-label': 'Tools' }, tools.map((t) =>
+    el('button', {
+      type: 'button',
+      class: `agent-tool${t.name === tool?.name ? ' active' : ''}`,
+      role: 'option',
+      'aria-selected': String(t.name === tool?.name),
+      onclick: () => paint(t.name),
+    }, [
+      el('span', { class: 'agent-tool-name', text: t.name }),
+      el('span', { class: 'agent-tool-badges' }, badges(t)),
+    ])));
+
+  panel.replaceChildren(el('div', { class: 'conn-inner' }, [
+    el('div', { class: 'conn-head' }, [
+      el('div', { class: 'conn-head-titles' }, [
+        el('div', { class: 'conn-brand', 'aria-hidden': 'true' }, [
+          el('span', { class: 'brand-mark' }),
+          el('span', { class: 'conn-brand-name', text: 'tablewalk' }),
+        ]),
+        el('h2', { text: 'Agent console' }),
+        el('p', {
+          class: 'conn-lede',
+          text: 'The MCP tools, driven by hand. Answers are exactly what an agent receives — same code path, stats and all.',
+        }),
+      ]),
+      el('div', { class: 'conn-head-actions' }, [
+        el('button', { type: 'button', text: 'Done', onclick: close }),
+      ]),
+    ]),
+    el('div', { class: 'agent-body' }, [
+      list,
+      el('div', { class: 'agent-main' }, tool ? [
+        toolForm(tool, result),
+        result,
+        transcriptPanel(),
+      ] : [el('p', { class: 'note', text: 'No tools. Is the server running?' })]),
+    ]),
+  ]));
+}
+
+function toolForm(tool, result) {
+  const inputs = new Map();
+  const properties = tool.inputSchema?.properties ?? {};
+  const required = new Set(tool.inputSchema?.required ?? []);
+
+  const field = (name, spec) => {
+    const types = Array.isArray(spec.type) ? spec.type : [spec.type];
+    /* Objects arrive as JSON, because a key or a set of values is a shape
+       the caller composes — a form that flattened it would be guessing. */
+    const isObject = types.includes('object');
+    const input = isObject
+      ? el('textarea', {
+          class: 'agent-input agent-json', rows: '2', spellcheck: 'false',
+          placeholder: spec.description ?? '{ }',
+          'aria-label': `${name} (json)`,
+        })
+      : el('input', {
+          type: 'text', class: 'agent-input', autocomplete: 'off', spellcheck: 'false',
+          placeholder: name === 'connection'
+            ? `${state.activeConnection ?? 'active'} (active)`
+            : spec.description ?? '',
+          'aria-label': name,
+        });
+    inputs.set(name, { input, spec, isObject });
+    return el('div', { class: 'agent-field' }, [
+      el('label', {}, [
+        document.createTextNode(name),
+        required.has(name) ? el('span', { class: 'req', text: 'required' }) : null,
+      ].filter(Boolean)),
+      input,
+    ]);
+  };
+
+  const run = async () => {
+    const args = {};
+    for (const [name, { input, spec, isObject }] of inputs) {
+      const raw = input.value.trim();
+      if (!raw) continue;
+      if (isObject) {
+        try {
+          args[name] = JSON.parse(raw);
+        } catch {
+          result.replaceChildren(el('p', { class: 'agent-error', text: `"${name}" is not JSON: ${raw.slice(0, 60)}` }));
+          return;
+        }
+      } else if ((Array.isArray(spec.type) ? spec.type : [spec.type]).includes('number') && raw !== '' && !Number.isNaN(Number(raw))) {
+        args[name] = Number(raw);
+      } else if (spec.type === 'boolean') {
+        args[name] = raw === 'true' || raw === '1' || raw === 'yes';
+      } else {
+        args[name] = raw;
+      }
+    }
+
+    result.replaceChildren(el('p', { class: 'loading', text: `Calling ${tool.name}…` }));
+    let answer;
+    try {
+      answer = await api('/api/agent/call', { name: tool.name, arguments: args });
+    } catch (err) {
+      result.replaceChildren(el('p', { class: 'agent-error', text: err.message }));
+      return;
+    }
+    transcript.unshift({ tool: tool.name, args, answer });
+    renderAnswer(result, answer);
+  };
+
+  return el('div', { class: 'agent-form' }, [
+    el('div', { class: 'agent-desc-row' }, [
+      el('h3', { text: tool.annotations?.title ?? tool.name }),
+      ...badges(tool),
+    ]),
+    /* The description, shown whole: this text is the tool's entire pitch to
+       a model deciding whether to call it, and reading it here is how it
+       gets tuned. */
+    el('p', { class: 'agent-desc', text: tool.description }),
+    ...Object.entries(properties).map(([name, spec]) => field(name, spec)),
+    el('div', { class: 'agent-run-row' }, [
+      el('button', { type: 'button', class: 'primary', text: 'Call tool', onclick: () => void run() }),
+    ]),
+  ]);
+}
+
+function renderAnswer(result, answer) {
+  const text = answer.structuredContent
+    ? JSON.stringify(answer.structuredContent, null, 2)
+    : (answer.content?.[0]?.text ?? '');
+  const stats = answer.structuredContent?.stats ?? {};
+
+  /* Every deep link in the answer, surfaced as a real door: the console and
+     the browser are the same app, and "see that row" should cost one click. */
+  const links = [];
+  const walk = (value) => {
+    if (typeof value === 'string' && /^[#/]\/?\w/.test(value) && !value.startsWith('//')) links.push(value);
+    else if (Array.isArray(value)) value.forEach(walk);
+    else if (value && typeof value === 'object') Object.values(value).forEach(walk);
+  };
+  walk(answer.structuredContent ?? {});
+
+  result.replaceChildren(
+    el('div', { class: 'agent-stats' }, [
+      answer.isError ? el('span', { class: 'agent-badge tone-bad', text: 'isError' }) : null,
+      ...Object.entries(stats).map(([k, v]) => el('span', { class: 'stat', text: `${k} ${v}` })),
+      el('span', { class: 'stat', text: cost(text) }),
+    ].filter(Boolean)),
+    el('pre', { class: `agent-answer${answer.isError ? ' agent-answer-error' : ''}`, text }),
+    links.length
+      ? el('div', { class: 'agent-links' }, links.slice(0, 8).map((hash) =>
+          el('button', {
+            type: 'button', class: 'ghost', text: `open ${decodeURIComponent(hash).slice(0, 60)}`,
+            onclick: () => {
+              close();
+              /* A path is navigated, not assigned to `location.hash`. Written
+                 with pushState so the console's own history entry survives. */
+              window.history.pushState(null, '', hash.replace(/^#/, ''));
+              window.dispatchEvent(new window.PopStateEvent('popstate'));
+            },
+          })))
+      : null,
+  );
+}
+
+function transcriptPanel() {
+  if (!transcript.length) return el('div');
+  return el('div', { class: 'agent-transcript' }, [
+    el('h4', {
+      text: `This session — ${transcript.length} call${transcript.length === 1 ? '' : 's'} · `
+        + `${transcript.reduce((n, e) => n + (e.answer.structuredContent?.stats?.rowsRead ?? 0), 0).toLocaleString()} rows read`,
+    }),
+    ...transcript.slice(0, 12).map((entry) => {
+      const size = entry.answer.content?.[0]?.text?.length ?? 0;
+      return el('button', {
+        type: 'button', class: 'agent-past',
+        onclick: () => {
+          const result = panel?.querySelector('.agent-result');
+          if (result) renderAnswer(result, entry.answer);
+        },
+      }, [
+        el('span', { class: 'agent-past-tool', text: entry.tool }),
+        el('span', { class: 'agent-past-args', text: JSON.stringify(entry.args).slice(0, 60) }),
+        el('span', { class: 'agent-past-cost', text: `${entry.answer.structuredContent?.stats?.ms ?? '–'} ms · ${size.toLocaleString()} ch` }),
+      ]);
+    }),
+  ]);
+}