@agentorg/cli 0.0.6 → 0.0.7

package/dist/node_modules/@agentorg/manager/dist/src/stack.js

@@ -0,0 +1,917 @@
+/**
+ * An agent built as a stack of units on a base: checking one, applying it all or none, keeping its
+ * instances, removing them last first, and the templates that prefill one.
+ */
+import { ConnectionOrigin, FieldValues, ResultKind, SkillName, SlotName, Template, UnitResult, } from "@agentorg/interfaces";
+import { Refused } from "@agentorg/sdk";
+import { z } from "zod";
+import { AGENTS_SLOT, AGENTS_UNIT, agentsUnit, reachOf, reachProblems, skillFile, } from "./control.js";
+import { formProblems, settle, workedOut } from "./form.js";
+/** A unit an agent has: what its provider made, and what was filled in. Never a secret. */
+const UnitRecord = z.object({
+    /** Management's own id for it. */
+    instance: z.string(),
+    provider: z.string(),
+    /** The provider's id for it. */
+    providerInstance: z.string(),
+    unit: z.string(),
+    title: z.string(),
+    values: FieldValues,
+    /** By kind, the instance it took each result from. */
+    needs: z.record(ResultKind, z.string()),
+    results: z.array(UnitResult),
+    connections: z.array(z.object({ slot: z.string(), connection: z.string() })),
+    skills: z.array(z.string()),
+    /** It was added as the MCP unit, and reads back as one. */
+    viaMcp: z.literal(true).optional(),
+});
+/** What only management knows of an agent: where it came from, what it is told, and its skills. */
+export const AgentRecord = z.object({
+    provider: z.string(),
+    creatable: z.string(),
+    instructions: z.string(),
+    skills: z.array(z.string()),
+    purpose: z.string().optional(),
+    template: z.string().optional(),
+    units: z.array(UnitRecord).default([]),
+    /** Its export that is its chats, as its provider named it; `chat` for one kept before this was. */
+    chat: z.string().default("chat"),
+    /** The agent that made it, which may be gone by now. */
+    parent: z.object({ agent: z.string(), name: z.string() }).optional(),
+    /** The parent's computer, when it shares one: its own reach, for agents it makes. */
+    computer: z
+        .object({
+        access: z.string(),
+        service: z.string().optional(),
+        browser: z.boolean(),
+        connections: z.array(z.object({ slot: z.string(), connection: z.string() })),
+        skills: z.array(z.string()),
+    })
+        .optional(),
+});
+export const Records = z.object({
+    agents: z.record(z.string(), AgentRecord),
+    connections: z.record(z.string(), ConnectionOrigin),
+    templates: z.record(z.string(), Template).default({}),
+    /** A connection the person made, to its provider's id for it; none means they are the same. */
+    instances: z.record(z.string(), z.string()).default({}),
+    /** The agent that added a skill or saved a template, which only it may replace or remove. */
+    authors: z
+        .object({
+        skills: z.record(z.string(), z.string()).default({}),
+        templates: z.record(z.string(), z.string()).default({}),
+    })
+        .default({ skills: {}, templates: {} }),
+});
+/** Management's own units. They ask no provider: each is an exposure and is read back as one. */
+const SKILL_UNIT = "skill";
+const CONNECTION_UNIT = "connection";
+/** One exposure, however it's reached: it stands for the Connection unit or a kind of connection. */
+const MCP_UNIT = "mcp";
+const MCP_SLOT = "slot";
+const MCP_HOW = "how";
+const skillInstance = (name) => `skill:${name}`;
+const slotInstance = (slot) => `slot:${slot}`;
+const MAX_MESSAGE = 2000;
+/** How many templates one agent may save. */
+const AGENT_TEMPLATES = 32;
+const MAX_OPTIONS = 256;
+const MAX_PROBLEMS = 256;
+const MAX_NAME = 128;
+const TOOLS = "tools@1";
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+const alreadyGone = (error) => error instanceof Refused && error.code === "unknown";
+const refusal = (problems) => new Refused("invalid", problems
+    .map((p) => p.message)
+    .join(" ")
+    .slice(0, MAX_MESSAGE));
+/** A unit that makes one connection and nothing else, by the field that names it, is a kind. */
+export const slotFieldOf = ({ needs, gives, form }) => {
+    const [slot] = gives.slots;
+    return slot &&
+        "field" in slot &&
+        gives.slots.length === 1 &&
+        !needs.length &&
+        !gives.skills.length &&
+        !gives.results.length &&
+        !form.some((field) => field.adds || field.options?.some((option) => option.adds))
+        ? slot.field
+        : undefined;
+};
+export function createStacks(parts) {
+    const { self, hub, records, save, library, creating, log, changed, recordOf } = parts;
+    const queues = new Map();
+    /** One change to an agent at a time, in the order they came: each spans many calls. */
+    const serial = (agent, work) => {
+        const running = (queues.get(agent) ?? Promise.resolve()).then(work);
+        const done = () => {
+            if (queues.get(agent) === settled)
+                queues.delete(agent);
+        };
+        const settled = running.then(done, done);
+        queues.set(agent, settled);
+        return running;
+    };
+    const isAgentsUnit = (offer) => offer.provider === self && offer.unit.id === AGENTS_UNIT;
+    /** The connections the person made, which an agents unit can list as places. */
+    const places = async () => {
+        const actors = await parts.openActors();
+        return Object.entries(records.connections).flatMap(([connection, origin]) => {
+            const actor = actors.get(connection);
+            return actor && !origin.madeFor ? [{ value: connection, title: actor.name }] : [];
+        });
+    };
+    /** The MCP unit: a connection there is, or any kind on offer, each with its own fields. */
+    const mcpUnit = (kinds) => {
+        const fields = new Map();
+        for (const kind of kinds)
+            for (const field of kind.form) {
+                if (field.id === slotFieldOf(kind) ||
+                    [MCP_HOW, MCP_SLOT, CONNECTION_UNIT].includes(field.id))
+                    continue;
+                const shared = fields.get(field.id);
+                if (shared?.visible) {
+                    shared.visible.in.push(kind.id);
+                    // Shared, it's open to an agent only if every kind says so.
+                    if (shared.authority !== field.authority)
+                        delete shared.authority;
+                }
+                else
+                    fields.set(field.id, { ...field, visible: { field: MCP_HOW, in: [kind.id] } });
+            }
+        return {
+            id: MCP_UNIT,
+            title: "MCP",
+            description: "A server's tools, for this agent to use.",
+            form: [
+                {
+                    id: MCP_HOW,
+                    type: "choice",
+                    value: "string",
+                    title: "How",
+                    required: true,
+                    options: [
+                        { value: CONNECTION_UNIT, title: "A connection you have" },
+                        ...kinds.map(({ id, title, description }) => ({ value: id, title, description })),
+                    ],
+                },
+                {
+                    id: CONNECTION_UNIT,
+                    type: "connection",
+                    value: "string",
+                    title: "Connection",
+                    authority: "holds",
+                    required: true,
+                    visible: { field: MCP_HOW, in: [CONNECTION_UNIT] },
+                },
+                ...fields.values(),
+                { id: MCP_SLOT, type: "text", value: "string", title: "Name", required: true },
+            ],
+            needs: [],
+            gives: { slots: [{ field: MCP_SLOT }], skills: [], results: [] },
+        };
+    };
+    const ownUnits = async (kinds) => [
+        mcpUnit(kinds),
+        agentsUnit(templates()
+            .slice(0, MAX_OPTIONS)
+            .map(({ id, title, description }) => ({ value: id, title, description })), (await places()).slice(0, MAX_OPTIONS - 1)),
+        {
+            id: SKILL_UNIT,
+            title: "Skill",
+            description: "A skill from the library.",
+            form: [
+                {
+                    id: "skill",
+                    authority: "holds",
+                    type: "choice",
+                    value: "string",
+                    title: "Skill",
+                    required: true,
+                    options: library
+                        .list()
+                        .slice(0, MAX_OPTIONS)
+                        .map(({ name, description }) => ({ value: name, title: name, description })),
+                },
+            ],
+            needs: [],
+            gives: { slots: [], skills: [{ field: "skill" }], results: [] },
+        },
+        {
+            id: CONNECTION_UNIT,
+            title: "Connection",
+            description: "A connection that already exists, under a name the agent sees.",
+            form: [
+                {
+                    id: "connection",
+                    authority: "holds",
+                    type: "connection",
+                    value: "string",
+                    title: "Connection",
+                    required: true,
+                },
+                { id: "slot", type: "text", value: "string", title: "Name", required: true },
+            ],
+            needs: [],
+            gives: { slots: [{ field: "slot" }], skills: [], results: [] },
+        },
+    ];
+    /** Every unit on offer now; a provider that doesn't answer offers none. */
+    const catalog = async () => {
+        const [providerName, others] = await Promise.all([
+            parts.nameOf(self),
+            parts.fromEach(parts.unitProviders(), async ({ actor, call }) => {
+                const name = await parts.nameOf(actor);
+                return (await call.units({})).units.map((unit) => ({ unit, provider: actor, providerName: name, call }));
+            }),
+        ]);
+        const offers = others.flat();
+        const kinds = offers.map((offer) => offer.unit).filter((unit) => slotFieldOf(unit));
+        return [
+            ...(await ownUnits(kinds)).map((unit) => ({ unit, provider: self, providerName })),
+            ...offers,
+        ];
+    };
+    const baseOf = async (base) => {
+        const provider = parts.agentProviders().find((one) => one.actor === base.provider);
+        if (!provider)
+            throw new Refused("unknown", `${base.provider} isn't a connected agent provider.`);
+        const { creatables } = await provider.call.creatable({});
+        const creatable = creatables.find((one) => one.id === base.creatable);
+        if (!creatable)
+            throw new Refused("unknown", `${base.provider} offers no ${base.creatable}.`);
+        return { provider, creatable };
+    };
+    /** The unit's own logic on what was filled in; one that can't say is a problem. */
+    const unitProblems = async (offer, values, secrets) => {
+        if (!offer.call) {
+            if (offer.unit.id !== CONNECTION_UNIT)
+                return [];
+            return (await parts.openActors()).has(String(values.connection))
+                ? []
+                : [{ field: "connection", message: "That connection doesn't exist." }];
+        }
+        try {
+            return (await offer.call.check({ unit: offer.unit.id, values, secrets })).problems;
+        }
+        catch (error) {
+            return [
+                { message: `This unit couldn't check it: ${messageOf(error)}`.slice(0, MAX_MESSAGE) },
+            ];
+        }
+    };
+    /** What the MCP unit stands for, as it was filled in: the unit that does the work. */
+    const throughMcp = (asked, offers) => {
+        const own = offers.find((one) => one.provider === self && one.unit.id === MCP_UNIT);
+        if (asked.provider !== self || asked.unit !== MCP_UNIT || !own)
+            return { filled: asked };
+        const settled = settle(own.unit.form, asked.values ?? {}, Object.keys(asked.secrets ?? {}));
+        if (settled.problems.length)
+            return { problems: settled.problems };
+        const { [MCP_HOW]: how, [MCP_SLOT]: slot, ...values } = settled.values;
+        if (how === CONNECTION_UNIT)
+            return {
+                filled: {
+                    provider: self,
+                    unit: CONNECTION_UNIT,
+                    values: { connection: values.connection, slot: slot },
+                },
+            };
+        const kind = offers.find((one) => one.provider !== self && one.unit.id === how && slotFieldOf(one.unit));
+        if (!kind)
+            return { problems: [{ field: MCP_HOW, message: "That way isn't on offer now." }] };
+        return {
+            viaMcp: true,
+            filled: {
+                provider: kind.provider,
+                unit: kind.unit.id,
+                values: { ...values, [slotFieldOf(kind.unit)]: slot },
+                secrets: Object.fromEntries(Object.entries(asked.secrets ?? {}).filter(([name]) => settled.secrets.includes(name))),
+            },
+        };
+    };
+    /** Everything that can be known about one unit before anything runs. `taken` grows by it. */
+    const place = async (asked, picks, taken, offers, ref) => {
+        const through = throughMcp(asked, offers);
+        if (!through.filled)
+            return { problems: through.problems };
+        const { filled } = through;
+        const offer = offers.find((one) => one.provider === filled.provider && one.unit.id === filled.unit);
+        if (!offer)
+            return { problems: [{ message: `${filled.provider} offers no unit ${filled.unit}.` }] };
+        const { unit } = offer;
+        const malformed = formProblems(unit.form);
+        if (malformed.length)
+            return { problems: malformed.map((message) => ({ message })) };
+        const given = filled.secrets ?? {};
+        const settled = settle(unit.form, filled.values ?? {}, Object.keys(given));
+        const problems = [...settled.problems];
+        const needs = {};
+        for (const kind of Object.keys(picks))
+            if (!unit.needs.includes(kind))
+                problems.push({ message: `${unit.title} doesn't need ${kind}.` });
+        for (const kind of unit.needs) {
+            const able = taken.givers.filter((giver) => giver.provider === offer.provider && giver.results.includes(kind));
+            const pick = picks[kind];
+            const giver = pick === undefined
+                ? able.length === 1
+                    ? able[0]
+                    : undefined
+                : able.find((one) => one.ref === pick);
+            if (giver)
+                needs[kind] = giver.ref;
+            else
+                problems.push({
+                    message: pick !== undefined
+                        ? `${unit.title} can't take ${kind} from the unit picked.`
+                        : able.length
+                            ? `${unit.title} needs one ${kind}: pick which.`
+                            : `${unit.title} needs a ${kind} from a unit above it.`,
+                });
+        }
+        const worked = workedOut(unit, settled.values);
+        for (const slot of worked.slots) {
+            if (!SlotName.safeParse(slot).success)
+                problems.push({ message: `${slot} can't name a connection.` });
+            if (taken.slots.has(slot))
+                problems.push({ message: `The name ${slot} is already taken.` });
+            taken.slots.add(slot);
+        }
+        for (const skill of worked.skills) {
+            if (!SkillName.safeParse(skill.name).success)
+                problems.push({ message: `${skill.name} can't name a skill.` });
+            else if (!skill.files && !library.has(skill.name))
+                problems.push({ message: `There is no skill ${skill.name}.` });
+            if (taken.skills.has(skill.name))
+                problems.push({ message: `Two units give the skill ${skill.name}.` });
+            taken.skills.add(skill.name);
+        }
+        if (ref !== undefined)
+            taken.givers.push({ ref, provider: offer.provider, results: unit.gives.results });
+        if (settled.problems.length === 0)
+            problems.push(...(await unitProblems(offer, settled.values, settled.secrets)));
+        const secrets = Object.fromEntries(Object.entries(given).filter(([name]) => settled.secrets.includes(name)));
+        return {
+            problems: problems.map((one) => ({ ...one, message: one.message.slice(0, MAX_MESSAGE) })),
+            placed: {
+                offer,
+                values: settled.values,
+                secrets,
+                worked,
+                needs,
+                ...(through.viaMcp ? { viaMcp: true } : {}),
+            },
+        };
+    };
+    const plan = async (units, reach) => {
+        const offers = await catalog();
+        const taken = { slots: new Set(), skills: new Set(), givers: [] };
+        const placed = [];
+        const problems = [];
+        for (const [position, unit] of units.entries()) {
+            const one = await place(unit, unit.needs ?? {}, taken, offers, position);
+            problems.push(...one.problems.map((problem) => ({ ...problem, unit: position })));
+            if (one.placed)
+                placed.push(one.placed);
+        }
+        const computer = placed.find((one) => one.offer.unit.id === "computer");
+        const own = reach ?? {
+            access: String(computer?.values.access ?? "none"),
+            browser: computer?.values.browser === true,
+        };
+        for (const [position, one] of placed.entries())
+            if (isAgentsUnit(one.offer))
+                problems.push(...reachProblems(one.values, own).map((p) => ({ ...p, unit: position })));
+        return { placed, problems };
+    };
+    /** The connections a living agent has now; what is exposed to it is the Hub's to say. */
+    const toolsOf = async (agent) => (await hub.bindings.list({ actor: agent })).bindings.filter((binding) => binding.consumer === agent && binding.interface === TOOLS);
+    const placeOnAgent = async (input) => {
+        const record = recordOf(input.agent);
+        const taken = {
+            slots: new Set((await hub.bindings.list({ actor: input.agent })).bindings
+                .filter((binding) => binding.consumer === input.agent)
+                .map((binding) => binding.slot)),
+            skills: new Set(record.skills),
+            givers: record.units.map((unit) => ({
+                ref: unit.instance,
+                provider: unit.provider,
+                results: unit.results.map((result) => result.kind),
+            })),
+        };
+        const placing = await place(input.unit, input.needs ?? {}, taken, await catalog(), undefined);
+        if (placing.placed && isAgentsUnit(placing.placed.offer))
+            placing.problems.push(...reachProblems(placing.placed.values, reachOf(record)));
+        return placing;
+    };
+    const unwind = async (undo) => {
+        for (const step of undo.reverse())
+            await Promise.resolve()
+                .then(step)
+                .catch((failed) => log.error(`Undoing a creation: ${messageOf(failed)}`));
+    };
+    const closeAll = async (connections) => {
+        for (const { connection } of connections)
+            await hub.actors.close({ actorId: connection });
+    };
+    /** Run one placed unit for the agent, and give it what it gives. */
+    const run = async (work, placed, earlier) => {
+        const { offer, values, worked } = placed;
+        const { agent, record, undo } = work;
+        let made;
+        if (offer.call) {
+            const { call } = offer;
+            const needs = {};
+            const handles = {};
+            for (const [kind, ref] of Object.entries(placed.needs)) {
+                const giver = earlier(ref);
+                const handle = giver?.results.find((result) => result.kind === kind)?.handle;
+                if (!giver || !handle)
+                    throw new Refused("failed", `The unit above didn't give ${kind} as it said it would.`);
+                needs[kind] = giver.instance;
+                handles[kind] = handle;
+            }
+            const applied = await call.apply({
+                unit: offer.unit.id,
+                values,
+                secrets: placed.secrets,
+                needs: handles,
+                agent,
+                name: `${work.name}: ${offer.unit.title}`.slice(0, MAX_NAME),
+                // Not for a child: a folder by a name it chose could be another agent's.
+                ...(record.parent ? {} : { agentName: work.name }),
+            });
+            undo.push(async () => {
+                try {
+                    await call.remove({ instance: applied.instance });
+                }
+                catch (error) {
+                    log.warn(`Removing a unit: ${messageOf(error)}`);
+                    await closeAll(applied.connections);
+                }
+            });
+            const slots = applied.connections.map((one) => one.slot).sort();
+            if (slots.join() !== [...worked.slots].sort().join())
+                throw new Refused("failed", `${offer.unit.title} didn't give the connections it said it would.`);
+            const results = applied.results.map((result) => result.kind);
+            if (offer.unit.gives.results.some((kind) => !results.includes(kind)))
+                throw new Refused("failed", `${offer.unit.title} didn't give the results it said it would.`);
+            for (const { slot, connection, target } of applied.connections) {
+                await parts.exposeConnection(agent, connection, slot);
+                work.origins[connection] = {
+                    provider: offer.provider,
+                    kind: offer.unit.id,
+                    target,
+                    madeBy: work.caller,
+                    madeFor: agent,
+                    at: new Date().toISOString(),
+                };
+            }
+            made = {
+                instance: `uni_${crypto.randomUUID().replaceAll("-", "")}`,
+                provider: offer.provider,
+                providerInstance: applied.instance,
+                unit: offer.unit.id,
+                title: offer.unit.title,
+                values,
+                needs,
+                results: applied.results,
+                connections: applied.connections.map(({ slot, connection }) => ({ slot, connection })),
+                skills: worked.skills.map((skill) => skill.name),
+                ...(placed.viaMcp ? { viaMcp: true } : {}),
+            };
+        }
+        else if (offer.unit.id === CONNECTION_UNIT) {
+            const slot = values.slot;
+            await parts.exposeConnection(agent, values.connection, slot);
+            undo.push(() => hub.grants.unexpose({ to: agent, slot }));
+        }
+        else if (isAgentsUnit(offer)) {
+            await parts.exposeConnection(agent, self, AGENTS_SLOT);
+            undo.push(() => hub.grants.unexpose({ to: agent, slot: AGENTS_SLOT }));
+            const instance = `uni_${crypto.randomUUID().replaceAll("-", "")}`;
+            made = {
+                instance,
+                provider: self,
+                providerInstance: instance,
+                unit: offer.unit.id,
+                title: offer.unit.title,
+                values,
+                needs: {},
+                results: [],
+                connections: [{ slot: AGENTS_SLOT, connection: self }],
+                skills: worked.skills.map((skill) => skill.name),
+            };
+        }
+        for (const { name, files } of worked.skills) {
+            if (!library.has(name)) {
+                if (!files)
+                    throw new Refused("unknown", `There is no skill ${name}.`);
+                const copied = {};
+                for (const path of files)
+                    copied[path] = offer.call
+                        ? (await offer.call.skill({ unit: offer.unit.id, name, path })).text
+                        : skillFile(path);
+                library.add(copied, name);
+                // Another agent may have been given it meanwhile, and then it stays.
+                undo.push(() => {
+                    if (![...Object.values(records.agents), ...creating.values()].some((one) => one.skills.includes(name)))
+                        library.remove(name);
+                });
+            }
+            record.skills.push(name);
+            undo.push(() => {
+                record.skills = record.skills.filter((skill) => skill !== name);
+            });
+        }
+        if (made) {
+            const instance = made.instance;
+            record.units.push(made);
+            undo.push(() => {
+                record.units = record.units.filter((unit) => unit.instance !== instance);
+            });
+        }
+        return made;
+    };
+    const keepOrigins = (work) => {
+        Object.assign(records.connections, work.origins);
+        work.undo.push(() => {
+            for (const connection of Object.keys(work.origins))
+                delete records.connections[connection];
+        });
+    };
+    /** What a stack is, whichever way the caller said it. */
+    const stackOf = async (input) => {
+        if ("stack" in input)
+            return input.stack;
+        const template = templates().find((one) => one.id === input.template);
+        if (!template)
+            throw new Refused("unknown", `There is no template ${input.template}.`);
+        const fill = input.fill ?? [];
+        if (fill.length > template.units.length)
+            throw new Refused("invalid", `The template has ${template.units.length} units.`);
+        const offers = await catalog();
+        const base = await baseProviderNamed(template.base.provider);
+        return {
+            base: {
+                provider: base,
+                creatable: template.base.creatable,
+                answers: { ...template.base.answers, ...input.answers },
+            },
+            units: template.units.map((unit, position) => {
+                const offer = offerNamed(offers, unit.provider, unit.unit);
+                const filled = fill[position];
+                return {
+                    provider: offer.provider,
+                    unit: unit.unit,
+                    values: { ...unit.values, ...filled?.values },
+                    ...(unit.needs ? { needs: unit.needs } : {}),
+                    ...(filled?.secrets ? { secrets: filled.secrets } : {}),
+                };
+            }),
+            template: template.id,
+        };
+    };
+    const baseProviderNamed = async (name) => {
+        for (const { actor } of parts.agentProviders())
+            if ((await parts.nameOf(actor)) === name)
+                return actor;
+        throw new Refused("unknown", `No connected agent provider is called ${name}.`);
+    };
+    const offerNamed = (offers, providerName, unit) => {
+        const offer = offers.find((one) => one.providerName === providerName && one.unit.id === unit);
+        if (!offer)
+            throw new Refused("unknown", `${providerName} offers no unit ${unit}.`);
+        return offer;
+    };
+    const templates = () => Object.values({
+        ...Object.fromEntries(parts.shipped.map((one) => [one.id, one])),
+        ...records.templates,
+    });
+    /** Remove a unit and what it made; a provider that has lost it leaves only the connections. */
+    const dropUnit = async (agent, record, unit) => {
+        if (unit.provider === self) {
+            await hub.grants.unexpose({ to: agent, slot: AGENTS_SLOT }).catch((error) => {
+                if (!alreadyGone(error))
+                    throw error;
+            });
+            record.skills = record.skills.filter((skill) => !unit.skills.includes(skill));
+            record.units = record.units.filter((one) => one.instance !== unit.instance);
+            save();
+            return;
+        }
+        const provider = parts.unitProviders().find((one) => one.actor === unit.provider);
+        let removed = false;
+        try {
+            if (provider) {
+                await provider.call.remove({ instance: unit.providerInstance });
+                removed = true;
+            }
+        }
+        catch (error) {
+            if (!alreadyGone(error))
+                throw error;
+        }
+        if (!removed)
+            await closeAll(unit.connections);
+        for (const { connection } of unit.connections)
+            delete records.connections[connection];
+        record.skills = record.skills.filter((skill) => !unit.skills.includes(skill));
+        record.units = record.units.filter((one) => one.instance !== unit.instance);
+        save();
+    };
+    /** Which unit made a connection, if one did. */
+    const unitMaking = (connection) => {
+        for (const record of Object.values(records.agents))
+            for (const unit of record.units)
+                if (unit.connections.some((one) => one.connection === connection))
+                    return unit;
+        return undefined;
+    };
+    const statusOf = async (unit) => unit.provider === self
+        ? { state: "connected", detail: undefined, connections: [] }
+        : parts
+            .unitProviders()
+            .find((one) => one.actor === unit.provider)
+            ?.call.status({ instance: unit.providerInstance });
+    const DOWN = { state: "down", detail: "Its provider can't be reached." };
+    const fromUnit = (record, given) => record.units.some((unit) => "slot" in given
+        ? unit.connections.some((one) => one.slot === given.slot)
+        : unit.skills.includes(given.skill));
+    return {
+        serial,
+        fromUnit,
+        unitMaking,
+        catalog,
+        allTemplates: templates,
+        baseProviderNamed,
+        /** How one connection a unit made stands, as its unit says. */
+        async connectionStatus(unit, connection) {
+            if (unit.provider === self)
+                return { state: "connected", tools: [] };
+            try {
+                const found = (await statusOf(unit))?.connections.find((one) => one.connection === connection);
+                if (found) {
+                    const { connection: _, ...status } = found;
+                    return status;
+                }
+            }
+            catch (error) {
+                log.warn(`A unit's status: ${messageOf(error)}`);
+            }
+            return { ...DOWN, tools: [] };
+        },
+        /** The agent's stack, top to bottom: its exposures as units, then what providers made. */
+        async read(agent, record, connectionStatus) {
+            const tools = await toolsOf(agent);
+            const instanceOfSkill = (name) => record.units.find((unit) => unit.skills.includes(name))?.instance ?? skillInstance(name);
+            const instanceOfSlot = (slot) => record.units.find((unit) => unit.connections.some((one) => one.slot === slot))?.instance ??
+                slotInstance(slot);
+            const own = (unit, title, instance, values, status) => ({ instance, provider: self, unit, title, values, needs: {}, status });
+            const units = [
+                ...record.skills
+                    .filter((name) => instanceOfSkill(name) === skillInstance(name))
+                    .map((name) => own(SKILL_UNIT, "Skill", skillInstance(name), { skill: name }, { state: "connected" })),
+                ...(await Promise.all(tools
+                    .filter(({ slot }) => instanceOfSlot(slot) === slotInstance(slot))
+                    .map(async ({ slot, provider }) => {
+                    const { state, detail } = await connectionStatus(provider);
+                    return own(MCP_UNIT, "MCP", slotInstance(slot), { [MCP_HOW]: CONNECTION_UNIT, connection: provider, slot }, { state, ...(detail ? { detail } : {}) });
+                }))),
+                ...(await Promise.all(record.units.map(async (unit) => {
+                    let status = DOWN;
+                    try {
+                        const answer = await statusOf(unit);
+                        if (answer)
+                            status = {
+                                state: answer.state,
+                                ...(answer.detail ? { detail: answer.detail } : {}),
+                                ...("surfaces" in answer && answer.surfaces ? { surfaces: answer.surfaces } : {}),
+                            };
+                    }
+                    catch (error) {
+                        log.warn(`A unit's status: ${messageOf(error)}`);
+                    }
+                    return {
+                        instance: unit.instance,
+                        ...(unit.viaMcp
+                            ? {
+                                provider: self,
+                                unit: MCP_UNIT,
+                                title: "MCP",
+                                values: { [MCP_HOW]: unit.unit, ...unit.values },
+                            }
+                            : {
+                                provider: unit.provider,
+                                unit: unit.unit,
+                                title: unit.title,
+                                values: unit.values,
+                            }),
+                        needs: unit.needs,
+                        status,
+                    };
+                }))),
+            ];
+            return { units, tools, instanceOfSkill, instanceOfSlot };
+        },
+        async units() {
+            const [bases, offers] = await Promise.all([
+                parts.fromEach(parts.agentProviders(), async ({ actor, call }) => {
+                    const providerName = await parts.nameOf(actor);
+                    return (await call.creatable({})).creatables.map((one) => ({
+                        ...one,
+                        provider: actor,
+                        providerName,
+                    }));
+                }),
+                catalog(),
+            ]);
+            return {
+                bases: bases.flat(),
+                // What the MCP unit stands for isn't listed apart from it.
+                units: offers
+                    .filter(({ unit, provider }) => !(provider === self ? unit.id === CONNECTION_UNIT : slotFieldOf(unit)))
+                    .map(({ unit, provider, providerName }) => ({ ...unit, provider, providerName })),
+            };
+        },
+        templates: () => ({ templates: templates() }),
+        /** With `agent`, it's that agent's own: it replaces nothing, and starts no program. */
+        async saveTemplate(template, agent) {
+            if (agent && templates().some((one) => one.id === template.id))
+                throw new Refused("state", `There is a template ${template.id} already.`);
+            if (agent &&
+                Object.values(records.authors.templates).filter((one) => one === agent).length >=
+                    AGENT_TEMPLATES)
+                throw new Refused("limit", `An agent can save at most ${AGENT_TEMPLATES} templates.`);
+            await baseProviderNamed(template.base.provider);
+            const offers = await catalog();
+            for (const unit of template.units) {
+                const { form } = offerNamed(offers, unit.provider, unit.unit).unit;
+                // A way not on offer now has fields no one can tell are secret, so it can't be kept.
+                const how = form.find((field) => field.id === MCP_HOW);
+                if (unit.unit === MCP_UNIT && !how?.options?.some((one) => one.value === unit.values?.how))
+                    throw new Refused("unknown", `${String(unit.values?.how)} isn't on offer now.`);
+                for (const field of form) {
+                    if (field.value === "secret" && unit.values?.[field.id] !== undefined)
+                        throw new Refused("invalid", `${field.title} is a secret: a template holds none.`);
+                    if (agent && field.authority === "runs" && unit.values?.[field.id] !== undefined)
+                        throw new Refused("invalid", `An agent's template can't say what ${field.title} runs.`);
+                }
+            }
+            records.templates[template.id] = template;
+            // Saved by the person, it's the person's, whoever saved it first.
+            if (agent)
+                records.authors.templates[template.id] = agent;
+            else
+                delete records.authors.templates[template.id];
+            save();
+            return {};
+        },
+        removeTemplate({ id }, agent) {
+            if (!records.templates[id] || (agent && records.authors.templates[id] !== agent))
+                throw new Refused("unknown", `No saved template ${id}.`);
+            delete records.templates[id];
+            delete records.authors.templates[id];
+            save();
+            return {};
+        },
+        async check(input) {
+            const problems = [];
+            if ("stack" in input) {
+                await baseOf(input.stack.base).catch((error) => problems.push({ message: messageOf(error).slice(0, MAX_MESSAGE) }));
+                problems.push(...(await plan(input.stack.units)).problems);
+            }
+            else
+                problems.push(...(await placeOnAgent(input)).problems);
+            return { problems: problems.slice(0, MAX_PROBLEMS) };
+        },
+        /** All or none: what this made is undone, last first, if a step fails. */
+        async create(input, caller, child) {
+            const stack = await stackOf(input);
+            const { provider, creatable } = await baseOf(stack.base);
+            const { placed, problems } = await plan(stack.units, child?.reach);
+            if (problems.length)
+                throw refusal(problems);
+            const undo = [];
+            try {
+                const made = await provider.call.create({
+                    creatable: creatable.id,
+                    name: input.name,
+                    answers: stack.base.answers ?? {},
+                });
+                const { agent } = made;
+                undo.push(() => parts.closing(agent, () => parts.removeAgent(agent, provider.actor)));
+                const record = {
+                    provider: provider.actor,
+                    creatable: creatable.id,
+                    instructions: creatable.instructions,
+                    skills: [],
+                    units: [],
+                    chat: made.chat,
+                    ...(input.purpose ? { purpose: input.purpose } : {}),
+                    ...(stack.template ? { template: stack.template } : {}),
+                    ...(child ? { parent: child.parent } : {}),
+                    ...(child?.computer ? { computer: child.computer } : {}),
+                };
+                creating.set(agent, record);
+                undo.push(() => creating.delete(agent));
+                await hub.grants.bind({
+                    consumer: agent,
+                    slot: made.settings,
+                    provider: self,
+                    export: "settings",
+                });
+                const work = { agent, name: input.name, caller, record, undo, origins: {} };
+                const applied = new Map();
+                for (const [position, one] of placed.entries()) {
+                    const unit = await run(work, one, (ref) => applied.get(ref));
+                    if (unit)
+                        applied.set(position, unit);
+                }
+                if (child) {
+                    for (const { slot, connection } of child.shares)
+                        await parts.exposeConnection(agent, connection, slot);
+                    for (const name of child.skills)
+                        if (library.has(name) && !record.skills.includes(name))
+                            record.skills.push(name);
+                    // Its parent reaches its chat through management, which needs it for that.
+                    await hub.grants.expose({ provider: agent, export: made.chat, to: self });
+                }
+                await hub.grants.expose({ provider: agent, export: made.chat, to: "person" });
+                records.agents[agent] = record;
+                undo.push(() => delete records.agents[agent]);
+                keepOrigins(work);
+                save();
+                creating.delete(agent);
+                return { agent };
+            }
+            catch (error) {
+                await unwind(undo);
+                throw error;
+            }
+        },
+        async addUnit(input, caller) {
+            const { agent } = input;
+            const record = recordOf(agent);
+            const { placed, problems } = await placeOnAgent(input);
+            if (problems.length || !placed)
+                throw refusal(problems);
+            const undo = [];
+            const work = {
+                agent,
+                name: await parts.nameOf(agent),
+                caller,
+                record,
+                undo,
+                origins: {},
+            };
+            try {
+                const unit = await run(work, placed, (ref) => record.units.find((one) => one.instance === ref));
+                keepOrigins(work);
+                save();
+                changed(agent);
+                if (unit)
+                    return { instance: unit.instance };
+                return {
+                    instance: placed.offer.unit.id === SKILL_UNIT
+                        ? skillInstance(placed.values.skill)
+                        : slotInstance(placed.values.slot),
+                };
+            }
+            catch (error) {
+                await unwind(undo);
+                throw error;
+            }
+        },
+        async removeUnit({ agent, instance }) {
+            const record = recordOf(agent);
+            const unit = record.units.find((one) => one.instance === instance);
+            if (unit) {
+                const needing = record.units.find((one) => Object.values(one.needs).includes(instance));
+                if (needing)
+                    throw new Refused("state", `${needing.title} needs this unit.`);
+                await dropUnit(agent, record, unit);
+                changed(agent);
+                return {};
+            }
+            // What a provider's unit gave isn't a unit of its own, so it can't be taken off alone.
+            const skill = record.skills.find((name) => skillInstance(name) === instance && !fromUnit(record, { skill: name }));
+            if (skill) {
+                record.skills = record.skills.filter((name) => name !== skill);
+                save();
+                changed(agent);
+                return {};
+            }
+            const tool = (await toolsOf(agent)).find(({ slot }) => slotInstance(slot) === instance && !fromUnit(record, { slot }));
+            if (!tool)
+                throw new Refused("unknown", `${agent} has no unit ${instance}.`);
+            await hub.grants.unexpose({ to: agent, slot: tool.slot });
+            return {};
+        },
+        /** Every unit, last first: if one can't go, what is left can be tried again. */
+        async removeAll(agent, record) {
+            for (const unit of [...record.units].reverse())
+                await dropUnit(agent, record, unit);
+        },
+    };
+}