@theoremjs/studio 0.3.4-next.464.g5fc5eed → 0.3.4-next.468.ge2da06f

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

@@ -0,0 +1,289 @@
+/**
+ * Where each node of the tree map stands, closed and grown, and how far each node growing adds has
+ * drawn: the part of `tree-map.tsx` that is not drawing, so its motion can be checked without a page.
+ *
+ * invariant: Grown, every node keeps its place in its column's order and every gap stays a row or
+ * more, so no node passes through another on the way; a node growing adds shows only once nothing
+ * stands where it is.
+ */
+import { workspaceTree } from "../../mod.js";
+/** A row's height closed, and grown. */
+const ROW = 32;
+const GROWN_ROW = 28;
+/** 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. */
+const GAP = 72;
+/** How many of the registry's tools sit under it closed: one of each type first. */
+const SHOWN_TOOLS = 4;
+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;
+/** 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. */
+const DRAW_FROM = 0.2;
+const DRAW_TO = 0.95;
+const DRAW_SPAN = 0.1;
+/** How finely growing is walked to find where an added node first stands clear. */
+const SAMPLES = 100;
+/** Space kept clear round a token. */
+const CLEAR = 2;
+export const REGISTRY = 'tool-registry';
+/**
+ * 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.
+ */
+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' },
+];
+/** A row's token id: the tree's ids repeat from one agent to the next. */
+export function rowId(row) {
+    return `${row.agent}/${row.node.id}`;
+}
+function rowsOf(workspace, only) {
+    const rows = [];
+    const walk = (node, agent, depth, parent) => {
+        const row = {
+            node,
+            agent,
+            x: PAD + depth * INDENT,
+            y: PAD + HALF + rows.length * ROW,
+            ...(parent ? { parent: rowId(parent) } : {}),
+        };
+        rows.push(row);
+        for (const child of node.children)
+            walk(child, agent, depth + 1, row);
+    };
+    workspaceTree(workspace).agents.forEach((root, index) => {
+        const key = workspace.agents[index]?.key ?? '';
+        if (only === undefined || only.includes(key))
+            walk(root, key, 0);
+    });
+    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.
+ */
+function feedsOf(workspace, rows, detail) {
+    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();
+        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]);
+        }
+        for (const [provider, into] of providers) {
+            const id = `${agent.key}/provider:${provider}`;
+            add({ id, label: provider, kind: 'provider', agent: agent.key }, into);
+        }
+        // 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 });
+        }
+    }
+    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 rest = tools.filter((tool) => !firsts.includes(tool));
+    const listed = [...firsts, ...rest];
+    return detail ? listed : listed.slice(0, SHOWN_TOOLS);
+}
+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) {
+    const slots = new Map();
+    const counts = new Map();
+    for (const feed of feeds) {
+        if (feed.under === undefined || feed.depth === 0)
+            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,
+            };
+        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();
+    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;
+        for (const feed of feeds) {
+            if (feed.agent !== agent || slots.has(feed.id))
+                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));
+        }
+        top = Math.max(top + mine.length * GROWN_ROW, cursor) + AGENT_GAP;
+    }
+    return places;
+}
+/** 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) {
+    const moved = clamp(grow / MOVE_TO);
+    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 to = layout.grown.get(id) ?? { x: 0, y: 0 };
+    const from = layout.closed.get(id) ?? to;
+    return { x: between(from.x, to.x, moved), y: between(from.y, to.y, moved) };
+}
+/** How far a node growing adds has drawn, 0 to 1; undefined for one the map shows closed. */
+export function drawnAt(layout, id, grow) {
+    const start = layout.starts.get(id);
+    return start === undefined ? undefined : clamp((grow - start) / DRAW_SPAN);
+}
+/** Whether two tokens, at their left sides and middles, touch. */
+function touching(a, aWidth, b, bWidth) {
+    return (a.x < b.x + bWidth + CLEAR &&
+        b.x < a.x + aWidth + CLEAR &&
+        Math.abs(a.y - b.y) < 2 * HALF + CLEAR);
+}
+/** The least growing from which a node stands clear of every other, all the way grown. */
+function clearFrom(layout, id, ids, width) {
+    for (let step = SAMPLES; step >= 0; step -= 1) {
+        const grow = step / SAMPLES;
+        const place = placeAt(layout, id, grow);
+        const hit = ids.some((other) => other !== id && touching(place, width(id), placeAt(layout, other, grow), width(other)));
+        if (hit)
+            return (step + 1) / SAMPLES;
+    }
+    return 0;
+}
+/** The tree and what feeds it, closed and grown, for tokens this wide. */
+export function treeMapLayout(workspace, agents, width) {
+    const rows = rowsOf(workspace, agents);
+    const fewFeeds = feedsOf(workspace, rows, false);
+    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 layout = {
+        rows,
+        feeds,
+        few,
+        closed,
+        grown: grownColumn(rows, feeds, slots, feedX),
+        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));
+    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);
+        layout.starts.set(feed.id, Math.max(turn, clearFrom(layout, feed.id, ids, width)));
+    });
+    return layout;
+}

package/ui/tree-map.css

@@ -2,6 +2,8 @@
    background of its own: it sits on whatever holds it. */
 .studio-tree-map {
   position: relative;
+  /* why: Grown to fit, it eases smaller from its top left, where it stands closed. */
+  transform-origin: 0 0;
 }
 
 .studio-tree-map-lines {

package/ui/tree-map.d.ts

@@ -4,12 +4,16 @@ export interface StudioTreeMapProps {
     /** 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 section drifts to its own zone: the
-     * providers to a band along the top, each agent's tree apart from the next with its runner level
-     * with it, and the tool registry to a field of its own. What growing adds draws in on the way,
-     * each over its own stretch, 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,
+     * 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.
      */
     grow?: number | undefined;
+    /** The box the map fits grown: growing, it eases smaller until all of it fits. */
+    fit?: {
+        width: number;
+        height: number;
+    } | undefined;
 }
-export declare function StudioTreeMap({ workspace, agents, grow }: StudioTreeMapProps): import("react").JSX.Element;
+export declare function StudioTreeMap({ workspace, agents, grow, fit }: StudioTreeMapProps): import("react").JSX.Element;