@theoremjs/studio 0.3.4-next.474.gdb1d5d7 → 0.3.4-next.482.g7e608f2

package/ui/lib/tree-map-layout.js

@@ -7,27 +7,24 @@
  * stands where it is.
  */
 import { workspaceTree } from "../../mod.js";
-/** A row's height closed, and grown. */
+/** A row's height closed; grown, the least and the most it stretches to, to fill the box it fits. */
 const ROW = 32;
 const GROWN_ROW = 28;
+const TALLEST_ROW = 40;
 /** How far in each level of the tree starts. */
 export const INDENT = 28;
 /** A token's half height. */
 export const HALF = 11;
 export const PAD = 16;
-/** Between the tree's widest row and the feeds. */
+/** Closed, between the tree's widest row and the feeds; grown, the least and most between columns. */
 const GAP = 72;
-/** How many of the registry's tools sit under it closed: one of each type first. */
-const SHOWN_TOOLS = 4;
+const LEAST_GAP = 56;
+const MOST_GAP = 160;
+/** The tools beside a Tools row: the first of each type. */
 const TOOL_TYPES = ['function', 'http', 'mcp', 'agent'];
-/** Grown, between one agent's zone and the next. */
-const AGENT_GAP = 16;
-/** Grown, a turn's steps in rows under its runner, so many to a row. */
-const STEPS_ACROSS = 3;
-const STEP_SLOT = 160;
-/** Grown, the registry's tools in columns this tall. */
-const TOOLS_DOWN = 8;
-const TOOL_SLOT = 210;
+/** Grown, the runner's steps two across, down one column and then the next. */
+const STEPS_DOWN = 4;
+const STEP_GAP = 24;
 /** By how far grown every node has reached its zone; the rest is for drawing in. */
 const MOVE_TO = 0.7;
 /** Over what stretch of growing the added nodes draw, and how long each takes of it. */
@@ -38,25 +35,33 @@ const DRAW_SPAN = 0.1;
 const SAMPLES = 100;
 /** Space kept clear round a token. */
 const CLEAR = 2;
-export const REGISTRY = 'tool-registry';
+export const RUNNER = 'runner';
+export const TOOL_RUNNER = 'tool-runner';
 /**
- * What a turn runner does in one turn, in order.
- * why: The kernel contract's turn lifecycle (docs/contracts/kernel.md, "Turn lifecycle"), step for
- * step; a decision and a session have no such list there, so their runners open into nothing.
+ * What the runner does in a turn, in order: the steps of the kernel contract's turn lifecycle
+ * (docs/contracts/kernel.md, "Turn lifecycle") that do work.
+ * why: The canary bind runs only while a canary detector is on, and pre_turn, before_end and
+ * post_turn are hooks for the host's stages, so the map leaves those four out.
  */
 export const TURN_STEPS = [
     { id: 'resolve', label: 'Resolve' },
     { id: 'sanitize', label: 'Sanitize' },
     { id: 'compaction', label: 'Compaction' },
-    { id: 'canary', label: 'Canary bind' },
-    { id: 'pre_turn', label: 'pre_turn' },
     { id: 'stream', label: 'Provider stream' },
     { id: 'tools', label: 'Tool loop' },
-    { id: 'before_end', label: 'before_end' },
     { id: 'validation', label: 'Validation' },
     { id: 'egress', label: 'Egress' },
     { id: 'trace', label: 'Trace' },
-    { id: 'post_turn', label: 'post_turn' },
+];
+/**
+ * What the tool runner checks of every call, in order (`executeRegisteredTool`): its permission,
+ * its sign-in, the network a remote call reaches, and the guard on its result.
+ */
+export const TOOL_CHECKS = [
+    { id: 'permission', label: 'Permission gate' },
+    { id: 'sign-in', label: 'Sign-in' },
+    { id: 'network', label: 'Network check' },
+    { id: 'result', label: 'Result guard' },
 ];
 /** A row's token id: the tree's ids repeat from one agent to the next. */
 export function rowId(row) {
@@ -84,144 +89,195 @@ function rowsOf(workspace, only) {
     return rows;
 }
 /**
- * What runs a profile of this type: `runDecision`, `runSession`, `runEmbedding`, else `runTurn`. A
- * host has none of its own: the tool runner runs its calls.
- */
-function runnerLabel(type) {
-    if (type === 'host')
-        return undefined;
-    if (type === 'decision')
-        return 'Decision runner';
-    if (type === 'live')
-        return 'Session runner';
-    if (type === 'embedding')
-        return 'Embedding runner';
-    return 'Turn runner';
-}
-/**
- * Each agent's runner (`runTurn`, or `runDecision` for a decision), beside its name; its providers,
- * beside its models; and the workspace's tool registry, beside its Tools row, with the tool runner
- * under it. A feed sits level with the middle of the rows it joins, or under the feed before it when
- * that is lower. With `detail`, every tool and each turn runner's steps.
+ * Beside the tree, shared by every agent drawn: the providers, each with the protocols the models
+ * it serves speak, and a line into each of those models; the first tool of each type the agents
+ * allow, with a line into each Tools row that allows it, an MCP tool's sessions under it and an
+ * agent tool's agent under it, joined to the runner; and the one runner, with a line into each
+ * agent but a host (whose calls the tool runner runs) and its steps under it. Past them, the tool
+ * runner the tool loop calls, its checks under it.
  */
-function feedsOf(workspace, rows, detail) {
+function feedsOf(workspace, rows) {
+    const drawn = workspace.agents.filter((agent) => rows.some((row) => row.agent === agent.key));
+    const rowOf = (agent, facet, key) => rows.find((row) => row.agent === agent &&
+        row.node.ref.facet === facet &&
+        (key === undefined || ('key' in row.node.ref && row.node.ref.key === key)));
     const feeds = [];
-    const add = (feed, into = [], depth = 0) => {
-        const below = (feeds.at(-1)?.y ?? Number.NEGATIVE_INFINITY) + ROW;
-        const middle = into.length ? into.reduce((sum, row) => sum + row.y, 0) / into.length : below;
-        feeds.push({ ...feed, y: Math.max(middle, below), into: into.map(rowId), depth });
-    };
-    for (const agent of workspace.agents) {
-        const mine = rows.filter((row) => row.agent === agent.key);
-        const name = mine.find((row) => row.node.ref.facet === 'identity');
-        if (!name)
-            continue;
-        const runner = runnerLabel(agent.identity.profileType);
-        if (runner) {
-            const id = `${agent.key}/runner`;
-            add({ id, label: runner, kind: 'runner', agent: agent.key }, [name]);
-            const steps = detail && runner === 'Turn runner' ? TURN_STEPS : [];
-            for (const step of steps) {
-                const of = step.id;
-                add({ id: `${id}/${of}`, label: step.label, kind: 'step', agent: agent.key, of, under: id }, [], 1);
-            }
-        }
-        const providers = new Map();
+    const providers = new Map();
+    for (const agent of drawn) {
         for (const binding of agent.modelBindings) {
-            const row = mine.find((each) => each.node.ref.facet === 'modelBinding' && each.node.ref.key === binding.key);
-            if (row)
-                providers.set(binding.provider, [...(providers.get(binding.provider) ?? []), row]);
+            const row = rowOf(agent.key, 'modelBinding', binding.key);
+            if (!row)
+                continue;
+            const provider = providers.get(binding.provider) ?? { into: [], protocols: new Set() };
+            provider.into.push(rowId(row));
+            provider.protocols.add(binding.protocol);
+            providers.set(binding.provider, provider);
         }
-        for (const [provider, into] of providers) {
-            const id = `${agent.key}/provider:${provider}`;
-            add({ id, label: provider, kind: 'provider', agent: agent.key }, into);
+    }
+    for (const [provider, { into, protocols }] of providers) {
+        const id = `provider:${provider}`;
+        feeds.push({ id, label: provider, kind: 'provider', into, column: 1, group: 'providers' });
+        for (const protocol of protocols) {
+            const nested = { id: `${id}/${protocol}`, label: protocol, kind: 'protocol' };
+            feeds.push({ ...nested, into: [], under: id, column: 1, group: 'providers' });
         }
-        // The workspace's tools are one registry that each agent's tool policy picks from: drawn once,
-        // beside the first Tools row, with a line into every other.
-        const tools = mine.find((row) => row.node.ref.facet === 'tools');
-        const drawn = feeds.find((feed) => feed.id === REGISTRY);
-        if (tools && drawn)
-            drawn.into.push(rowId(tools));
-        else if (tools && workspace.toolSpecs.length > 0) {
-            add({ id: REGISTRY, label: 'Tool registry', kind: 'registry', agent: agent.key }, [tools]);
-            for (const tool of listedTools(workspace.toolSpecs, detail)) {
-                const id = `${REGISTRY}/${tool.key}`;
-                const feed = { id, label: tool.toolName, kind: 'tool', agent: agent.key };
-                add({ ...feed, of: tool.toolType, under: REGISTRY }, [], 1);
-            }
-            const runs = { id: 'tool-runner', label: 'Tool runner', kind: 'tool-runner' };
-            add({ ...runs, agent: agent.key, under: REGISTRY });
+    }
+    const allowing = (key) => drawn.flatMap((agent) => {
+        const row = agent.tools.allow.includes(key) ? rowOf(agent.key, 'tools') : undefined;
+        return row ? [rowId(row)] : [];
+    });
+    for (const type of TOOL_TYPES) {
+        const tool = workspace.toolSpecs.find((each) => each.toolType === type && allowing(each.key).length > 0);
+        if (!tool)
+            continue;
+        const id = `tool:${tool.key}`;
+        const into = allowing(tool.key);
+        feeds.push({
+            id,
+            label: tool.toolName,
+            kind: 'tool',
+            of: type,
+            into,
+            column: 1,
+            group: 'tools',
+        });
+        const nested = { into: [], under: id, column: 1, group: 'tools' };
+        if (type === 'mcp') {
+            feeds.push({ ...nested, id: `${id}/sessions`, label: 'MCP sessions', kind: 'branch' });
+        }
+        const agent = workspace.agents.find((each) => each.key === tool.agentKey);
+        if (type === 'agent' && agent) {
+            const label = agent.identity.agentId || agent.identity.handle;
+            feeds.push({
+                ...nested,
+                id: `${id}/agent`,
+                label,
+                kind: 'subagent',
+                of: agent.identity.profileType,
+                joins: RUNNER,
+            });
         }
     }
-    return feeds;
-}
-/**
- * The registry's tools: the first of each type, then the rest in the registry's order. A few of
- * them, or with `detail` every one.
- */
-function listedTools(tools, detail) {
-    const firsts = TOOL_TYPES.flatMap((type) => {
-        const tool = tools.find((each) => each.toolType === type);
-        return tool ? [tool] : [];
+    const runs = drawn.filter((agent) => agent.identity.profileType !== 'host');
+    const into = runs.flatMap((agent) => {
+        const row = rowOf(agent.key, 'identity');
+        return row ? [rowId(row)] : [];
     });
-    const rest = tools.filter((tool) => !firsts.includes(tool));
-    const listed = [...firsts, ...rest];
-    return detail ? listed : listed.slice(0, SHOWN_TOOLS);
+    feeds.push({ id: RUNNER, label: 'Runner', kind: 'runner', into, column: 1, group: 'runner' });
+    for (const step of TURN_STEPS) {
+        feeds.push({
+            id: `${RUNNER}/${step.id}`,
+            label: step.label,
+            kind: 'step',
+            of: step.id,
+            into: [],
+            under: RUNNER,
+            column: 1,
+            group: 'runner',
+            ...(step.id === 'tools' ? { joins: TOOL_RUNNER } : {}),
+        });
+    }
+    const runner = { id: TOOL_RUNNER, label: 'Tool runner', kind: 'tool-runner' };
+    feeds.push({ ...runner, into: [], column: 2, group: 'tool-runner' });
+    for (const check of TOOL_CHECKS) {
+        const nested = { id: `${TOOL_RUNNER}/${check.id}`, label: check.label, of: check.id };
+        feeds.push({
+            ...nested,
+            kind: 'check',
+            into: [],
+            under: TOOL_RUNNER,
+            column: 2,
+            group: 'tool-runner',
+        });
+    }
+    return feeds;
 }
 const clamp = (value) => Math.min(Math.max(value, 0), 1);
 const between = (from, to, at) => from + (to - from) * at;
-/** Every other one from each list, while both last: the turn's steps and the tools draw by turns. */
-function byTurns(first, second) {
-    return Array.from({ length: Math.max(first.length, second.length) }, (_, index) => [first[index], second[index]].filter((each) => each !== undefined)).flat();
-}
-/** A step under its runner in rows so many across; a tool under the registry in columns. */
-function slotsOf(feeds) {
+/** A step under the runner two across, down one column and then the next; any other a level in. */
+function slotsOf(feeds, width) {
     const slots = new Map();
+    const steps = feeds.filter((feed) => feed.kind === 'step');
+    const stepColumn = Math.max(0, ...steps.map((step) => width(step.id))) + STEP_GAP;
     const counts = new Map();
     for (const feed of feeds) {
-        if (feed.under === undefined || feed.depth === 0)
+        if (feed.under === undefined)
             continue;
         const index = counts.get(feed.under) ?? 0;
         counts.set(feed.under, index + 1);
-        const slot = feed.kind === 'tool'
-            ? { across: Math.floor(index / TOOLS_DOWN) * TOOL_SLOT, down: (index % TOOLS_DOWN) + 1 }
-            : {
-                across: (index % STEPS_ACROSS) * STEP_SLOT,
-                down: Math.floor(index / STEPS_ACROSS) + 1,
-            };
+        const slot = feed.kind === 'step'
+            ? { across: Math.floor(index / STEPS_DOWN) * stepColumn, down: (index % STEPS_DOWN) + 1 }
+            : { across: 0, down: index + 1 };
         slots.set(feed.id, { holder: feed.under, across: INDENT + slot.across, down: slot.down });
     }
     return slots;
 }
-/**
- * The column grown: each agent a zone of its own, its rows restacked and its feeds in their order,
- * each level with its rows or under the room the one before it holds for its own.
- */
-function grownColumn(rows, feeds, slots, feedX) {
-    const places = new Map();
+/** Each column's groups of heads, and how many rows each group holds with what is under its heads. */
+function stacksOf(rows, feeds, slots) {
     const held = new Map();
     for (const slot of slots.values()) {
         held.set(slot.holder, Math.max(held.get(slot.holder) ?? 0, slot.down));
     }
-    let top = PAD + HALF;
-    for (const agent of new Set(rows.map((row) => row.agent))) {
-        const mine = rows.filter((row) => row.agent === agent);
-        mine.forEach((row, index) => {
-            places.set(rowId(row), { x: row.x, y: top + index * GROWN_ROW });
-        });
-        let cursor = top;
+    const stack = (groups) => {
+        const ids = [...groups.values()];
+        const count = ids.flat().reduce((sum, id) => sum + 1 + (held.get(id) ?? 0), 0);
+        return { ids, rows: count };
+    };
+    const tree = new Map();
+    for (const row of rows)
+        tree.set(row.agent, [...(tree.get(row.agent) ?? []), rowId(row)]);
+    const columns = [1, 2].map((column) => {
+        const groups = new Map();
         for (const feed of feeds) {
-            if (feed.agent !== agent || slots.has(feed.id))
+            if (feed.column !== column || feed.under !== undefined)
                 continue;
-            const level = feed.into.flatMap((id) => places.get(id)?.y ?? []);
-            const middle = level.length ? level.reduce((sum, y) => sum + y, 0) / level.length : cursor;
-            const y = Math.max(middle, cursor);
-            places.set(feed.id, { x: feedX, y });
-            cursor = y + GROWN_ROW * (1 + (held.get(feed.id) ?? 0));
+            groups.set(feed.group, [...(groups.get(feed.group) ?? []), feed.id]);
         }
-        top = Math.max(top + mine.length * GROWN_ROW, cursor) + AGENT_GAP;
-    }
-    return places;
+        return stack(groups);
+    });
+    return { held, columns: [stack(tree), ...columns] };
+}
+/**
+ * The map grown: the tree, each agent a zone of its own; beside it the providers, the tools and the
+ * runner; past them the tool runner. Rows stretch, up to a most, and the gaps between columns and
+ * between groups widen, so the map fills `box`; without one, rows and gaps are at their least.
+ */
+function grownPlaces(rows, feeds, slots, width, box) {
+    const { held, columns } = stacksOf(rows, feeds, slots);
+    // In rows, from the top node's middle to the bottom one's, each gap at its least of a row.
+    const span = Math.max(...columns.map((each) => each.rows + each.ids.length - 2));
+    const room = box ? box.height - 2 * (PAD + HALF) : 0;
+    const row = Math.min(Math.max(room / Math.max(span, 1), GROWN_ROW), TALLEST_ROW);
+    const height = Math.max(room, span * row);
+    const right = (id, x) => x + width(id);
+    const treeRight = Math.max(0, ...rows.map((each) => right(rowId(each), each.x)));
+    const columnWidth = (column) => Math.max(0, ...feeds
+        .filter((feed) => feed.column === column)
+        .map((feed) => {
+        const slot = slots.get(feed.id);
+        return right(feed.id, slot ? slot.across : 0);
+    }));
+    const [first, second] = [columnWidth(1), columnWidth(2)];
+    const spare = box ? (box.width - 2 * PAD - (treeRight - PAD) - first - second) / 2 : LEAST_GAP;
+    const gap = Math.min(Math.max(spare, LEAST_GAP), MOST_GAP);
+    const lefts = [0, treeRight + gap, treeRight + gap + first + gap];
+    const places = new Map();
+    const tree = new Map(rows.map((each) => [rowId(each), each]));
+    columns.forEach((stack, column) => {
+        const free = height - (stack.rows - 1) * row;
+        // Past a group, the next stands a row and its share of what is free further down.
+        const extra = stack.ids.length > 1 ? free / (stack.ids.length - 1) : 0;
+        // why: A column of one group has no gap to widen, so it stands in the middle of the map.
+        let y = PAD + HALF + (stack.ids.length > 1 ? 0 : free / 2);
+        for (const group of stack.ids) {
+            for (const id of group) {
+                places.set(id, { x: tree.get(id)?.x ?? lefts[column] ?? 0, y });
+                y += row * (1 + (held.get(id) ?? 0));
+            }
+            y += extra;
+        }
+    });
+    return { places, row };
 }
 /** Where a node stands this far grown: a node under a feed keeps its slot under it on the way. */
 export function placeAt(layout, id, grow) {
@@ -229,7 +285,8 @@ export function placeAt(layout, id, grow) {
     const slot = layout.slots.get(id);
     if (slot) {
         const holder = placeAt(layout, slot.holder, grow);
-        return { x: holder.x + slot.across, y: holder.y + slot.down * between(ROW, GROWN_ROW, moved) };
+        const row = between(ROW, layout.row, moved);
+        return { x: holder.x + slot.across, y: holder.y + slot.down * row };
     }
     const to = layout.grown.get(id) ?? { x: 0, y: 0 };
     const from = layout.closed.get(id) ?? to;
@@ -257,29 +314,40 @@ function clearFrom(layout, id, ids, width) {
     }
     return 0;
 }
-/** The tree and what feeds it, closed and grown, for tokens this wide. */
-export function treeMapLayout(workspace, agents, width) {
+/**
+ * The tree and what feeds it, closed and grown, for tokens this wide: grown, it fills `box` when
+ * one is given.
+ */
+export function treeMapLayout(workspace, agents, width, box) {
     const rows = rowsOf(workspace, agents);
-    const fewFeeds = feedsOf(workspace, rows, false);
+    const feeds = feedsOf(workspace, rows);
+    // Closed, the first column's heads stand beside the tree, each level with the first row it
+    // joins or under the one before.
+    const fewFeeds = feeds.filter((feed) => feed.column === 1 && feed.under === undefined);
     const few = new Set(fewFeeds.map((feed) => feed.id));
-    const feeds = feedsOf(workspace, rows, true);
     const feedX = Math.max(0, ...rows.map((row) => row.x + width(rowId(row)))) + GAP;
     const closed = new Map(rows.map((row) => [rowId(row), row]));
-    for (const feed of fewFeeds)
-        closed.set(feed.id, { x: feedX + feed.depth * INDENT, y: feed.y });
-    const slots = slotsOf(feeds);
+    const rowY = new Map(rows.map((row) => [rowId(row), row.y]));
+    let below = Number.NEGATIVE_INFINITY;
+    for (const feed of fewFeeds) {
+        const y = Math.max(rowY.get(feed.into[0] ?? '') ?? below, below);
+        closed.set(feed.id, { x: feedX, y });
+        below = y + ROW;
+    }
+    const slots = slotsOf(feeds, width);
+    const { places, row } = grownPlaces(rows, feeds, slots, width, box);
     const layout = {
         rows,
         feeds,
         few,
         closed,
-        grown: grownColumn(rows, feeds, slots, feedX),
+        grown: places,
+        row,
         slots,
         starts: new Map(),
     };
-    // What growing adds draws in order, the turn's steps and the tools by turns, each once it stands clear.
-    const added = feeds.filter((feed) => !few.has(feed.id));
-    const order = byTurns(added.filter((feed) => feed.under !== REGISTRY), added.filter((feed) => feed.under === REGISTRY));
+    // What growing adds draws in its columns' order, each once it stands clear.
+    const order = feeds.filter((feed) => !few.has(feed.id));
     const ids = [...rows.map(rowId), ...feeds.map((feed) => feed.id)];
     order.forEach((feed, index) => {
         const turn = DRAW_FROM + ((DRAW_TO - DRAW_SPAN - DRAW_FROM) * index) / Math.max(order.length - 1, 1);

package/ui/tree-map.d.ts

@@ -1,20 +1,21 @@
 import { type StudioWorkspace } from '../mod.ts';
+import { type Box } from './lib/tree-map-layout.ts';
 export interface StudioTreeMapProps {
     workspace: StudioWorkspace;
     /** The keys of the agents to draw, in the workspace's order; every agent when unset. */
     agents?: readonly string[] | undefined;
     /**
-     * How far the tree has grown, from 0 to 1. As it grows each agent drifts into a zone of its own,
-     * its runner and providers level with its rows, and room opens under each feed for its own. What
-     * growing adds draws in as its room opens, its line and then its token: the steps of a turn under
-     * each turn runner, and every tool in the registry. Shrinking takes it all back the same way.
+     * How far the tree has grown, from 0 to 1. As it grows each agent drifts into a zone of its own
+     * and what feeds the tree spreads into its columns. What growing adds draws in as its room opens,
+     * its line and then its token: the protocols under each provider, what branches off a tool, the
+     * runner's steps, and the tool runner with its checks. Shrinking takes it all back the same way.
      */
     grow?: number | undefined;
-    /** The box the map fits grown: growing, it eases smaller until all of it fits. */
-    fit?: {
-        width: number;
-        height: number;
-    } | undefined;
+    /**
+     * The box the map fills grown: its rows and gaps stretch to fill it, and it stands in the middle
+     * of it. When the map cannot fit, it eases smaller as it grows until all of it does.
+     */
+    fit?: Box | undefined;
     /** A token dragged moves to where it is dropped, its lines with it; the field dragged moves the whole map. */
     draggable?: boolean | undefined;
 }