@theoremjs/studio 0.0.0-stage → 0.3.2

package/shared-carry.js

@@ -0,0 +1,523 @@
+/**
+ * A change to a value the project's files write once, made on every agent or
+ * tool that shares it. The files hold one value, so the workspace does too.
+ * The same stop names the other code that reads the value, when some does.
+ *
+ * @module
+ */
+import { agentToolInputSchema, compileStudio } from "./compile.js";
+import { draftKey } from "./draft.js";
+import { ON_OWN_KEYS } from "./lent-keys.js";
+import { agentDraft } from "./workspace.js";
+const text = (value) => JSON.stringify(value);
+const same = (a, b) => text(a) === text(b);
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/**
+ * One agent's profile, when the agent compiles on its own. With the builder's own keys: which
+ * models the studio's keys may call is a rule for a run, and does not change a profile's shape.
+ */
+function profileOf(workspace, key) {
+    const result = compiledOf(workspace, key);
+    return result?.ok ? result.profile : undefined;
+}
+/** A workspace does not change, so each of its agents compiles once. */
+const COMPILED = new WeakMap();
+function compiledOf(workspace, key) {
+    const known = COMPILED.get(workspace) ?? new Map();
+    COMPILED.set(workspace, known);
+    if (known.has(key))
+        return known.get(key);
+    const draft = agentDraft(workspace, key);
+    const idOf = (other) => workspace.agents.find((agent) => agent.key === other)?.identity.agentId.trim();
+    const inputOf = (other) => {
+        const called = agentDraft(workspace, other);
+        return called && agentToolInputSchema(called);
+    };
+    const result = draft && compileStudio(draft, ON_OWN_KEYS, idOf, inputOf);
+    known.set(key, result);
+    return result;
+}
+/**
+ * Each agent of `workspace` as it compiles now. One that does not compile keeps what `before`
+ * holds for it, so a change made while it did not is still read once it does.
+ */
+export function sharedSnapshot(workspace, before) {
+    const snapshot = new Map();
+    for (const draft of workspace.agents) {
+        const profile = profileOf(workspace, draft.key);
+        const held = profile === undefined ? before?.get(draft.key) : { draft, profile };
+        if (held)
+            snapshot.set(draft.key, held);
+    }
+    return snapshot;
+}
+/** Each setting that differs, as the keys that lead to it: a record key by key, a list of one length item by item. */
+function changedPaths(before, after, path = []) {
+    if (same(before, after))
+        return [];
+    if (isRecord(before) && isRecord(after)) {
+        return [...new Set([...Object.keys(before), ...Object.keys(after)])].flatMap((key) => changedPaths(before[key], after[key], [...path, key]));
+    }
+    if (Array.isArray(before) && Array.isArray(after) && before.length === after.length) {
+        return before.flatMap((each, index) => changedPaths(each, after[index], [...path, String(index)]));
+    }
+    return [path];
+}
+function valueAt(value, path) {
+    let held = value;
+    for (const key of path) {
+        held =
+            isRecord(held) || Array.isArray(held) ? held[key] : undefined;
+    }
+    return held;
+}
+const leads = (prefix, path) => prefix.length <= path.length && prefix.every((key, index) => path[index] === key);
+/** The place that writes `path`: the deepest one that leads to it, and the last of those the files reach. */
+function writerOf(sites, path) {
+    let found;
+    for (const site of sites) {
+        if (leads(site.path, path) && (!found || site.path.length >= found.path.length))
+            found = site;
+    }
+    return found;
+}
+/** `onto` with what changed from `before` to `after`: a record field by field, anything else whole. */
+function carried(before, after, onto) {
+    if (same(before, after))
+        return onto;
+    if (!isRecord(before) || !isRecord(after) || !isRecord(onto))
+        return after;
+    const next = { ...onto };
+    for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+        const value = carried(before[key], after[key], onto[key]);
+        if (value === undefined)
+            delete next[key];
+        else
+            next[key] = value;
+    }
+    return next;
+}
+const modelOf = (path) => (path[0] === 'models' && path.length > 1 ? path[1] : undefined);
+const bindingOf = (agent, model) => agent?.modelBindings.find((binding) => binding.modelId.trim() === model);
+/** `agent` with what `owed` names changed as the edited agent changed it. A model is matched by its name. */
+function withOwed(agent, owed, was, now) {
+    const [model, fromModel] = [modelOf(owed.path), modelOf(owed.fromPath)];
+    if (model === undefined || fromModel === undefined) {
+        const next = { ...agent };
+        for (const field of Object.keys(now)) {
+            if (field !== 'key' && field !== 'modelBindings')
+                next[field] = carried(was[field], now[field], agent[field]);
+        }
+        return next;
+    }
+    const [old, held, mine] = [
+        bindingOf(was, fromModel),
+        bindingOf(now, fromModel),
+        bindingOf(agent, model),
+    ];
+    let modelBindings = agent.modelBindings;
+    if (old && held && mine) {
+        const next = {
+            ...carried(old, held, mine),
+            key: mine.key,
+            modelId: mine.modelId,
+        };
+        modelBindings = modelBindings.map((binding) => (binding === mine ? next : binding));
+    }
+    else if (!old && held && !mine) {
+        modelBindings = [...modelBindings, { ...held, key: draftKey('model'), modelId: model }];
+    }
+    else if (old && !held && mine)
+        modelBindings = modelBindings.filter((binding) => binding !== mine);
+    return modelBindings === agent.modelBindings ? agent : { ...agent, modelBindings };
+}
+/** Each place `other` holds the value `edit` changed and does not hold the change yet. */
+function owedOn(among, other, edit) {
+    const sites = among.sitesOf(other.key);
+    const held = among.now.get(other.key);
+    return (sites
+        .filter((place) => place.site === edit.site.site)
+        .map((place) => [...place.path, ...edit.rest])
+        // What the other sets apart inside the shared value is its own.
+        .filter((target) => writerOf(sites, target)?.site === edit.site.site)
+        .filter((target) => held === undefined || !same(valueAt(held, target), edit.value))
+        .map((path) => ({
+        key: other.key,
+        path,
+        from: edit.from,
+        fromPath: edit.fromPath,
+        value: edit.value,
+        site: edit.site,
+    })));
+}
+/** Each change one of them made since it last compiled, with the place in the files that writes it. */
+function editsOf(among, draft) {
+    const [before, after] = [among.goodOf(draft.key)?.value, among.now.get(draft.key)];
+    if (before === undefined || after === undefined)
+        return [];
+    const sites = among.sitesOf(draft.key);
+    return changedPaths(before, after).map((path) => {
+        const site = writerOf(sites, path);
+        return { path, ...(site ? { site } : {}), value: valueAt(after, path) };
+    });
+}
+/**
+ * What each change to a shared value is owed on, and each place a change is written that other
+ * code reads too, with who made it.
+ */
+function owedAmong(among) {
+    const owed = new Map();
+    const read = [];
+    for (const draft of among.made) {
+        for (const { path, site, value } of editsOf(among, draft)) {
+            if (site?.readBy)
+                read.push({ site, from: draft.key });
+            if (!site?.shared)
+                continue;
+            const edit = {
+                site,
+                rest: path.slice(site.path.length),
+                value,
+                from: draft.key,
+                fromPath: path,
+            };
+            for (const mine of among.made.flatMap((other) => owedOn(among, other, edit))) {
+                const id = text([mine.key, mine.path]);
+                const known = owed.get(id);
+                // Two changed one value two ways: neither is carried.
+                if (known === undefined)
+                    owed.set(id, mine);
+                else if (known && !same(known.value, value))
+                    owed.set(id, null);
+            }
+        }
+    }
+    return { all: [...owed.values()].filter((each) => each !== null), read };
+}
+/** Whether what one compiles to now holds each change it is owed, and nothing else new. */
+function holdsOwed(before, held, mine) {
+    return (same(changedPaths(before, held).map(text).sort(), mine.map((each) => text(each.path)).sort()) &&
+        mine.every((each) => same(valueAt(held, each.path), each.value)));
+}
+/**
+ * Each change to a shared value made on every one that shares it. A change is carried only when
+ * the one it is owed on then compiles to that value there and to nothing else new: otherwise it
+ * is left as it is, and Save names it.
+ */
+function carriedAmong(among) {
+    const { all, read } = owedAmong(among);
+    const kept = new Map();
+    const left = new Set();
+    const from = all[0]?.from ?? read[0]?.from;
+    if (from === undefined)
+        return { drafts: [...among.made], kept, left };
+    const place = { ...placeOf([...all, ...read].map((each) => each.site)), from };
+    const edited = new Map(among.made.map((draft) => [draft.key, draft]));
+    const drafts = new Map(edited);
+    for (const each of all) {
+        const [old, held, draft] = [
+            among.goodOf(each.from)?.draft,
+            edited.get(each.from),
+            drafts.get(each.key),
+        ];
+        // One that does not compile cannot show that it holds the value: it is left.
+        const able = old && held && draft && among.now.get(each.key) !== undefined;
+        const next = able ? among.withOwed(draft, each, old, held) : undefined;
+        if (next)
+            drafts.set(each.key, next);
+        else
+            left.add(each.key);
+    }
+    const compiled = among.compiledWith(among.made.map((draft) => drafts.get(draft.key) ?? draft));
+    for (const key of new Set(all.map((each) => each.key))) {
+        const before = among.now.get(key);
+        const held = left.has(key) || drafts.get(key) === edited.get(key) ? undefined : compiled(key);
+        const mine = all.filter((each) => each.key === key);
+        if (before !== undefined && held !== undefined && holdsOwed(before, held, mine))
+            kept.set(key, held);
+        else
+            left.add(key);
+    }
+    return {
+        drafts: among.made.map((draft) => kept.has(draft.key) ? (drafts.get(draft.key) ?? draft) : draft),
+        kept,
+        left,
+        place,
+    };
+}
+/**
+ * `made`, with each change since `good` to a shared value made on every agent that shares it.
+ * A change is carried only when the agent then compiles to that value there and to nothing else
+ * new: otherwise the agent is left as it is, and Save names it.
+ */
+export function withSharedCarry(good, made, sites) {
+    const { drafts, kept, left, place } = carriedAmong({
+        made: made.agents,
+        goodOf: (key) => {
+            const held = good.get(key);
+            return held && { draft: held.draft, value: held.profile };
+        },
+        now: new Map(made.agents.map((agent) => [agent.key, profileOf(made, agent.key)])),
+        sitesOf: (key) => sites[made.starts.agents[key]?.identity.agentId.trim() ?? ''] ?? [],
+        withOwed,
+        compiledWith: (agents) => {
+            const next = { ...made, agents: [...agents] };
+            return (key) => profileOf(next, key);
+        },
+    });
+    const snapshot = sharedSnapshot(made, good);
+    for (const agent of drafts) {
+        if (kept.has(agent.key))
+            snapshot.set(agent.key, { draft: agent, profile: kept.get(agent.key) });
+    }
+    const others = (keys) => [...keys].filter((key) => key !== place?.from);
+    return {
+        workspace: kept.size ? { ...made, agents: drafts } : made,
+        snapshot,
+        ...(place ? { reach: { ...place, agents: others(kept.keys()), left: others(left) } } : {}),
+    };
+}
+/** What a reach says of the places a change is written: each one, where the first is, and the code that reads them. */
+function placeOf(sites) {
+    const [first] = sites;
+    const lines = new Map(sites
+        .flatMap((site) => site.readBy ?? [])
+        .map((each) => [`${each.file}:${String(each.line)}`, each]));
+    return {
+        sites: [...new Set(sites.map((site) => site.site))],
+        ...(first?.name ? { name: first.name } : {}),
+        file: first?.file ?? '',
+        line: first?.line ?? 0,
+        ...(sites.some((site) => site.readBy) ? { readBy: [...lines.values()] } : {}),
+    };
+}
+/** Each tool an agent that compiles allows, by key, as that agent registers it. */
+function toolsOf(workspace) {
+    const byName = new Map();
+    for (const agent of workspace.agents) {
+        const result = compiledOf(workspace, agent.key);
+        if (result?.ok)
+            for (const tool of result.customTools)
+                byName.set(tool.name, tool);
+    }
+    const held = new Map();
+    for (const tool of workspace.toolSpecs) {
+        const registered = byName.get(tool.toolName.trim());
+        if (registered !== undefined)
+            held.set(tool.key, registered);
+    }
+    return held;
+}
+/**
+ * Each tool of `workspace` as it registers now. One that does not compile keeps what `before`
+ * holds for it, so a change made while it did not is still read once it does.
+ */
+export function toolSnapshot(workspace, before) {
+    const now = toolsOf(workspace);
+    const snapshot = new Map();
+    for (const draft of workspace.toolSpecs) {
+        const tool = now.get(draft.key);
+        const held = tool === undefined ? before?.get(draft.key) : { draft, tool };
+        if (held)
+            snapshot.set(draft.key, held);
+    }
+    return snapshot;
+}
+/** A tool's schema as the draft holds it, by the key the tool is registered with. */
+const SCHEMA_FIELDS = {
+    inputSchema: 'inputJson',
+    outputSchema: 'outputJson',
+};
+/** `value` with `to` at `path`. Nothing at the path takes the key away. */
+function putAt(value, path, to) {
+    const [key, ...rest] = path;
+    if (key === undefined)
+        return to;
+    if (Array.isArray(value))
+        return value.map((each, index) => (String(index) === key ? putAt(each, rest, to) : each));
+    const next = { ...(isRecord(value) ? value : {}) };
+    const inner = putAt(next[key], rest, to);
+    if (inner === undefined)
+        delete next[key];
+    else
+        next[key] = inner;
+    return next;
+}
+/** `tool` with what `owed` names changed as the edited tool changed it. Undefined when its schema does not read. */
+function toolWithOwed(tool, owed, was, now) {
+    const [head, ...rest] = owed.path;
+    const schema = SCHEMA_FIELDS[head ?? ''];
+    if (schema) {
+        try {
+            return {
+                ...tool,
+                [schema]: JSON.stringify(putAt(JSON.parse(tool[schema]), rest, owed.value), null, 2),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const next = { ...tool };
+    for (const field of Object.keys(now)) {
+        if (field === 'key' || field === 'toolName' || field === 'inputJson' || field === 'outputJson')
+            continue;
+        next[field] = carried(was[field], now[field], tool[field]);
+    }
+    return next;
+}
+/**
+ * `made`, with each change since `good` to a value tools share made on every tool that shares it:
+ * a schema several tools take, a list they all name. A change is carried only when the tool then
+ * registers with that value there and nothing else new: otherwise the tool is left as it is, and
+ * Save names it. A tool no agent allows is not registered here, so it is not read.
+ */
+export function withToolCarry(good, made, sites) {
+    const { drafts, kept, left, place } = carriedAmong({
+        made: made.toolSpecs,
+        goodOf: (key) => {
+            const held = good.get(key);
+            return held && { draft: held.draft, value: held.tool };
+        },
+        now: toolsOf(made),
+        sitesOf: (key) => sites[made.starts.tools[key]?.toolName ?? ''] ?? [],
+        withOwed: toolWithOwed,
+        compiledWith: (toolSpecs) => {
+            const after = toolsOf({ ...made, toolSpecs: [...toolSpecs] });
+            return (key) => after.get(key);
+        },
+    });
+    const snapshot = toolSnapshot(made, good);
+    for (const tool of drafts) {
+        if (kept.has(tool.key))
+            snapshot.set(tool.key, { draft: tool, tool: kept.get(tool.key) });
+    }
+    const others = (keys) => [...keys].filter((key) => key !== place?.from);
+    const amongTools = { made: others(kept.keys()), left: others(left) };
+    return {
+        workspace: kept.size ? { ...made, toolSpecs: drafts } : made,
+        snapshot,
+        ...(place ? { reach: { ...place, agents: [], left: [], amongTools } } : {}),
+    };
+}
+/** The most names the question lists before it counts the rest. */
+const NAMED = 4;
+/** `ids` as a sentence names them: the first few, then a count of the rest. */
+function listed(ids) {
+    const rest = ids.length - NAMED;
+    const shown = rest > 0 ? [...ids.slice(0, NAMED), `${String(rest)} more`] : ids;
+    return shown.length > 1
+        ? `${shown.slice(0, -1).join(', ')}${shown.length > 2 ? ',' : ''} and ${shown.at(-1) ?? ''}`
+        : (shown[0] ?? '');
+}
+/** What a change from `before` to `made`, made in the agent `from`, does to tools other agents allow. */
+export function toolReach(before, made, from) {
+    const now = new Map(made.toolSpecs.map((tool) => [tool.key, tool]));
+    const changed = before.toolSpecs.filter((tool) => !same(now.get(tool.key), tool));
+    const keys = new Set(changed.map((tool) => tool.key));
+    const agents = before.agents
+        .filter((agent) => agent.key !== from && agent.tools.allow.some((key) => keys.has(key)))
+        .map((agent) => agent.key);
+    if (!agents.length)
+        return undefined;
+    const used = changed.filter((tool) => before.agents.some((agent) => agent.key !== from && agent.tools.allow.includes(tool.key)));
+    return {
+        tools: used.map((tool) => tool.key),
+        names: used.map((tool) => tool.toolName),
+        from,
+        agents,
+    };
+}
+const placeText = ({ file, line }) => `${file}:${String(line)}`;
+/** A place as the question shows it: the file's name and the line. The folders it is in are for whoever asks. */
+export function shortPlace({ file, line }) {
+    const name = file.slice(Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\')) + 1);
+    return `${name === file ? '' : '…/'}${name}:${String(line)}`;
+}
+/** The question's line as its text and the places it names, in the order it says them. */
+export function askParts(ask) {
+    const parts = [];
+    let rest = ask.line;
+    for (const place of ask.places) {
+        const text = placeText(place);
+        const at = rest.indexOf(text);
+        // A long list names only its first places.
+        if (at < 0)
+            continue;
+        if (at > 0)
+            parts.push(rest.slice(0, at));
+        parts.push(place);
+        rest = rest.slice(at + text.length);
+    }
+    if (rest)
+        parts.push(rest);
+    return parts;
+}
+/** The ids of agents, by key, as the builder knows them. */
+const idsOf = (workspace, keys) => keys
+    .map((key) => workspace.agents.find((agent) => agent.key === key)?.identity.agentId.trim())
+    .filter((id) => Boolean(id));
+/** The names of tools, by key. */
+const toolNames = (workspace, keys) => keys
+    .map((key) => workspace.toolSpecs.find((tool) => tool.key === key)?.toolName.trim())
+    .filter((name) => Boolean(name));
+/** The question for a tool of the library that other agents allow too. */
+function libraryAsk(reach, workspace) {
+    const [ids, one] = [idsOf(workspace, reach.agents), reach.names.length === 1];
+    return {
+        title: `Change it for ${String(ids.length)} other ${ids.length === 1 ? 'profile' : 'profiles'}?`,
+        line: `${listed(reach.names)} ${one ? 'is one tool' : 'are tools'} in the library. ` +
+            `${listed(ids)} ${ids.length === 1 ? 'uses' : 'use'} ${one ? 'it' : 'them'} too, ` +
+            `and will change with ${one ? 'it' : 'them'}.`,
+        places: [],
+    };
+}
+/** What the builder is asked before a change to a shared value is made: the question, then its cause and effect. */
+export function sharedAsk(reach, workspace) {
+    if ('tools' in reach)
+        return libraryAsk(reach, workspace);
+    const among = reach.amongTools;
+    const [ids, left] = among
+        ? [toolNames(workspace, among.made), toolNames(workspace, among.left)]
+        : [idsOf(workspace, reach.agents), idsOf(workspace, reach.left)];
+    const [one, many] = among ? ['tool', 'tools'] : ['profile', 'profiles'];
+    const places = [{ file: reach.file, line: reach.line }, ...(reach.readBy ?? [])];
+    const place = `${reach.name ? `${reach.name} · ` : ''}${reach.file}:${String(reach.line)}`;
+    // The other code that reads it, by line when the studio can name one.
+    const lines = reach.readBy?.map((each) => `${each.file}:${String(each.line)}`) ?? [];
+    const code = reach.readBy
+        ? ` Other code in your project reads it too${lines.length ? ` (${listed(lines)})` : ''}.`
+        : '';
+    if (!ids.length && !left.length) {
+        if (reach.readBy) {
+            return {
+                title: 'Change it for your other code too?',
+                line: `${place} sets this once.${code} That code runs on the new value once you save.`,
+                places,
+            };
+        }
+        return {
+            title: `Change it everywhere this ${one} uses it?`,
+            line: `${place} sets this once, and this ${one} uses it in more than one place. Each of them changes.`,
+            places,
+        };
+    }
+    const changes = ids.length
+        ? ` ${listed(ids)} ${ids.length === 1 ? 'uses' : 'use'} it too, and will change with it.`
+        : '';
+    // The cause, the effect, and the way out.
+    const waits = left.length
+        ? ` ${listed(left)} ${left.length === 1 ? 'uses' : 'use'} it too, but ${left.length === 1 ? 'has' : 'have'} ` +
+            `issues and ${left.length === 1 ? 'stays as it is' : 'stay as they are'}. ` +
+            `Fix them, then set this there too: Save writes it once every ${one} agrees.`
+        : '';
+    // The title says what agreeing does: one that is left as it is does not count.
+    const title = ids.length
+        ? `Change it for ${String(ids.length)} other ${ids.length === 1 ? one : many}?`
+        : `Change it for this ${one} only?`;
+    return { title, line: `${place} sets this once.${changes}${waits}${code}`, places };
+}
+/** Whether agreeing to a change makes it on others too: other agents, other tools. */
+export function reachesOthers(reach) {
+    return (reach.agents.length > 0 || ('amongTools' in reach && (reach.amongTools?.made.length ?? 0) > 0));
+}

package/shared-settings.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The project's shared settings as the studio's workspace holds them: which
+ * agents share each one, and the section of an agent it fills.
+ *
+ * @module
+ */
+import { type ProfileGraphFacetId } from '@theoremjs/agents/schema';
+import type { ProjectOrigins, SharedSetting, Unregistered } from './server/save-wire.ts';
+import { type StudioWorkspace } from './workspace.ts';
+/** One shared setting, beside the agents of the workspace that share it. */
+export interface SharedEntry {
+    setting: SharedSetting;
+    /** The agents that share it, by key, in the workspace's order. */
+    agents: string[];
+    /**
+     * The section the studio edits it in. Unset when the constant is not the whole of one section in
+     * every profile, or a profile that reads it is not open: then it is changed in the builder's editor.
+     */
+    facet?: ProfileGraphFacetId;
+    /** Where each agent shows the value: the node that holds the field the files set from it, by agent key. */
+    places: Record<string, string>;
+    /** The tool that shows the value, when no agent does. */
+    tool?: string;
+    /** The profiles and tools that read it and that the project did not register, so nothing opens them. */
+    idle: Unregistered[];
+}
+/** Each shared setting with the agents that share it, as the project opened. */
+export declare function sharedEntries(workspace: StudioWorkspace, settings: readonly SharedSetting[], sites?: ProjectOrigins['sites'], unregistered?: readonly Unregistered[]): SharedEntry[];
+/** The node that opens a shared setting on one of its agents: the field the files set from it. */
+export declare function sharedNodeId(entry: SharedEntry, agentKey: string): string;
+/** The node that opens a shared setting: the first agent that shows it, else the tool that does. */
+export declare function sharedOpens(entry: SharedEntry): string | undefined;
+/** The shared setting the open node edits, when it is one. A shared `models` is edited in each binding. */
+export declare function sharedAt(entries: readonly SharedEntry[], nodeId: string): SharedEntry | undefined;

package/shared-settings.js

@@ -0,0 +1,70 @@
+/**
+ * The project's shared settings as the studio's workspace holds them: which
+ * agents share each one, and the section of an agent it fills.
+ *
+ * @module
+ */
+import { PROFILE_GRAPH } from '@theoremjs/agents/schema';
+import { modelBindingNodeId, toolSpecNodeId } from "./tree.js";
+import { agentNodeId, workspaceTree } from "./workspace.js";
+/** The node of `agent` that holds the setting at `path`: its model, its section, else the agent. */
+function nodeAt(agent, path, sections) {
+    const [head, name] = path;
+    const binding = head === 'models' ? agent.modelBindings.find((each) => each.modelId === name) : undefined;
+    if (binding)
+        return agentNodeId(agent.key, modelBindingNodeId(binding.key));
+    const facet = PROFILE_GRAPH.find((each) => each.role === 'spine' && each.profilePath === head)?.id;
+    const section = facet ? agentNodeId(agent.key, facet) : '';
+    return sections.has(section) ? section : agentNodeId(agent.key);
+}
+/** The section whose whole value is the profile key `key`. */
+function facetOf(key) {
+    return PROFILE_GRAPH.find((facet) => facet.role === 'spine' && facet.profilePath === key)?.id;
+}
+/** Each shared setting with the agents that share it, as the project opened. */
+export function sharedEntries(workspace, settings, sites, unregistered = []) {
+    const sections = new Set(workspaceTree(workspace)
+        .agents.flatMap((agent) => agent.children ?? [])
+        .map((row) => row.id));
+    return settings.map((setting) => {
+        const users = workspace.agents.filter((agent) => setting.profiles.includes(agent.identity.agentId.trim()));
+        const agents = users.map((agent) => agent.key);
+        const facet = agents.length === setting.profiles.length ? facetOf(setting.key) : undefined;
+        const written = (held, id) => held?.[id]?.find((site) => site.name === setting.name && site.file === setting.file);
+        const places = Object.fromEntries(users.flatMap((agent) => {
+            const site = written(sites?.profiles, agent.identity.agentId.trim());
+            return site ? [[agent.key, nodeAt(agent, site.path, sections)]] : [];
+        }));
+        const tool = workspace.toolSpecs.find((spec) => written(sites?.tools, spec.toolName));
+        const idle = unregistered.filter(({ kind, name }) => (kind === 'profile' ? setting.profiles : setting.tools).includes(name));
+        return {
+            setting,
+            agents,
+            places,
+            idle,
+            ...(facet ? { facet } : {}),
+            ...(tool ? { tool: toolSpecNodeId(tool.key) } : {}),
+        };
+    });
+}
+/** The node that opens a shared setting on one of its agents: the field the files set from it. */
+export function sharedNodeId(entry, agentKey) {
+    return entry.places[agentKey] ?? agentNodeId(agentKey, entry.facet ?? 'identity');
+}
+/** The node that opens a shared setting: the first agent that shows it, else the tool that does. */
+export function sharedOpens(entry) {
+    const shown = entry.agents.find((key) => entry.places[key] !== undefined) ??
+        (entry.facet ? entry.agents[0] : undefined);
+    return shown ? sharedNodeId(entry, shown) : entry.tool;
+}
+/** The shared setting the open node edits, when it is one. A shared `models` is edited in each binding. */
+export function sharedAt(entries, nodeId) {
+    return entries.find(({ facet, agents }) => facet !== undefined &&
+        agents.some((key) => {
+            const root = `${agentNodeId(key)}/`;
+            if (!nodeId.startsWith(root))
+                return false;
+            const inner = nodeId.slice(root.length);
+            return inner === facet || (facet === 'models' && inner.startsWith(modelBindingNodeId('')));
+        }));
+}