@agentorg/cli 0.0.5 → 0.0.7

package/dist/node_modules/assistant/dist/src/engine.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The engine: the looper bound to one agent. Its chats are the looper's threads, its model is the
+ * agent's `model` slot, and what a request says and offers is read from what the agent is bound to.
+ * Its host says where the records are kept and what the agent is told when no `settings` is bound.
+ */
+import type { agentSettings, chat, kv, llmSession } from "@agentorg/interfaces";
+import { type Context, type Slot } from "@agentorg/sdk";
+type Host = Pick<Context<{
+    model: typeof llmSession;
+    settings: typeof agentSettings;
+}, {
+    chat: typeof chat;
+}>, "slots" | "exports" | "exposed" | "onExposed" | "log">;
+export declare function startEngine(ctx: Host, options: {
+    store: Slot<typeof kv>["call"];
+    /** What the agent is told while no `settings` is bound. */
+    instructions(): string;
+    /** Whether it starts stopped, as it was left. */
+    stopped?: boolean;
+}): {
+    /** The models the agent can use, and the one chosen for it. */
+    models(): Promise<{
+        models: {
+            id: string;
+            name: string;
+        }[];
+        current?: string | undefined;
+    }>;
+    /** Choose the model for its next requests, kept with it; with none, the provider's default. */
+    setModel(model: string | undefined): Promise<void>;
+    /** Stop the agent: its turns are cut and none starts until `start`. Its chats stay readable. */
+    stop(): Promise<void>;
+    start: () => void;
+    /**
+     * Close for good: its turns are cut, and none starts after. They go on in the engine that
+     * opens this store next.
+     */
+    close(): Promise<void>;
+    /** Settles when every chat's latest turn has written all it will. */
+    settled(): Promise<void>;
+};
+export {};

package/dist/node_modules/assistant/dist/src/engine.js

@@ -0,0 +1,160 @@
+import { Refused } from "@agentorg/sdk";
+import { createChats } from "./chats.js";
+import { instructionsWith, skillTool } from "./settings.js";
+import { listedBy, listsTools, offered, relayed } from "./tools.js";
+/** Where the agent keeps the model chosen for it, beside its chats in the store. */
+const MODEL_KEY = "settings/model";
+export function startEngine(ctx, options) {
+    const { store } = options;
+    /** The model chosen for this agent, if any; read for each request. */
+    const chosen = async () => {
+        const { value } = await store.get({ key: MODEL_KEY });
+        return typeof value === "string" ? value : undefined;
+    };
+    /** What was last reported as left out, so a change is logged once. */
+    let reported = "[]";
+    const report = (leftOut) => {
+        const now = JSON.stringify(leftOut);
+        if (now === reported)
+            return;
+        reported = now;
+        if (leftOut.length > 0)
+            ctx.log.warn("Not everything is offered to the model.", { leftOut });
+        else
+            ctx.log.info("Everything is offered to the model again.");
+    };
+    /**
+     * What a request says and offers, and to which model, read afresh: none of it outlives it.
+     * `leftOut` is what it couldn't offer, and why.
+     */
+    const request = async () => {
+        const settings = ctx.slots.settings.bound ? await ctx.slots.settings.call.get({}) : undefined;
+        const told = settings
+            ? instructionsWith(settings.instructions, settings.skills)
+            : { instructions: options.instructions(), leftOut: [] };
+        const own = settings?.skills.length ? [skillTool(ctx.slots.settings)] : [];
+        // In the order they came, each asked at once so one slow server delays only itself.
+        const exposed = await Promise.all(ctx
+            .exposed()
+            .filter((slot) => listsTools(slot.described))
+            .map((slot) => listedBy(slot.slot, slot)));
+        const fitted = offered([...own, ...exposed.flatMap((one) => one.candidates)]);
+        const leftOut = [...told.leftOut, ...exposed.flatMap((one) => one.leftOut), ...fitted.leftOut];
+        report(leftOut);
+        return { instructions: told.instructions, tools: fitted.tools, model: await chosen(), leftOut };
+    };
+    /** The model slot as the looper asks it: what it refuses is told with its code. */
+    const model = {
+        respond: (asked) => relayed(ctx.slots.model.call.respond(asked)),
+        // A model that is gone has nothing to stop.
+        cancel: async (asked) => (ctx.slots.model.bound ? ctx.slots.model.call.cancel(asked) : {}),
+    };
+    const chats = createChats({
+        store,
+        stopped: options.stopped ?? false,
+        model,
+        request: () => relayed(request()),
+        emit: {
+            message: (message) => ctx.exports.chat.emit("message", message),
+            delta: (delta) => ctx.exports.chat.emit("delta", delta),
+            status: (status) => ctx.exports.chat.emit("status", status),
+            chat: (entry) => ctx.exports.chat.emit("chat", entry),
+        },
+        log: ctx.log,
+    });
+    ctx.slots.model.on("delta", ({ requestId, text }) => chats.delta(requestId, text));
+    /**
+     * The turns that were cut off when the agent last ran go on once the model is bound, the
+     * settings answer, and no tools slot is away. As the agent starts, what it is bound to may not
+     * be running yet, so this is looked at again whenever that may have changed: a slot's provider
+     * is back, a tools slot is made or gone, or one says its tools changed. A tools slot that stays
+     * away holds them back; a message in a chat starts that chat's turn anyway.
+     */
+    let wentOn = false;
+    /** Each tools slot heard for its tools changing, with how to stop hearing it. */
+    const heard = new Map();
+    const goOn = async () => {
+        for (const slot of ctx.exposed())
+            if (listsTools(slot.described) && !heard.has(slot))
+                heard.set(slot, slot.on("changed", look));
+        if (!ctx.slots.model.bound)
+            return;
+        // Refused while the settings can't answer, as a turn's own request would be.
+        const { leftOut } = await request();
+        if (leftOut.some((one) => one.reason === "not_connected"))
+            return;
+        await chats.resume();
+        done();
+    };
+    /** Nothing more is looked for: the turns have gone on, or the agent is stopped or closing. */
+    const done = () => {
+        wentOn = true;
+        for (const stop of heard.values())
+            stop();
+        heard.clear();
+    };
+    /** The look running now, and whether to look once more after it. */
+    let looking;
+    let again = false;
+    const look = () => {
+        again = true;
+        looking ??= (async () => {
+            // A start binds its slots one after another in one go, and one not bound yet reads as one
+            // the agent doesn't have: so it looks once they all are.
+            await Promise.resolve();
+            while (again && !wentOn) {
+                again = false;
+                await goOn().catch((error) => ctx.log.info("Turns that were cut off aren't looked for yet.", { error: String(error) }));
+            }
+            looking = undefined;
+        })();
+    };
+    ctx.slots.model.onBind(look);
+    ctx.slots.settings.onBind(look);
+    ctx.onExposed(look);
+    ctx.exports.chat.implement({
+        send: (input) => chats.send(input),
+        history: (input) => chats.history(input),
+        state: () => chats.state(),
+        list: (input) => chats.list(input),
+        rename: (input) => chats.rename(input),
+        archive: (input) => chats.archive(input),
+    });
+    return {
+        /** The models the agent can use, and the one chosen for it. */
+        async models() {
+            const [{ models }, current] = await Promise.all([ctx.slots.model.call.models({}), chosen()]);
+            return { models, ...(current ? { current } : {}) };
+        },
+        /** Choose the model for its next requests, kept with it; with none, the provider's default. */
+        async setModel(model) {
+            if (!model) {
+                await store.delete({ key: MODEL_KEY });
+                return;
+            }
+            const { models } = await ctx.slots.model.call.models({});
+            if (!models.some((offered) => offered.id === model))
+                throw new Refused("unknown", `${model} isn't one of the models offered.`);
+            await store.set({ key: MODEL_KEY, value: model });
+        },
+        /** Stop the agent: its turns are cut and none starts until `start`. Its chats stay readable. */
+        stop() {
+            done();
+            return chats.stop();
+        },
+        start: () => chats.start(),
+        /**
+         * Close for good: its turns are cut, and none starts after. They go on in the engine that
+         * opens this store next.
+         */
+        close() {
+            done();
+            return chats.close();
+        },
+        /** Settles when every chat's latest turn has written all it will. */
+        async settled() {
+            await looking;
+            await chats.settled();
+        },
+    };
+}

package/dist/node_modules/assistant/dist/src/local-store.d.ts

@@ -0,0 +1,3 @@
+import type { kv } from "@agentorg/interfaces";
+import type { Slot } from "@agentorg/sdk";
+export declare function createLocalStore(dir: string): Slot<typeof kv>["call"];

package/dist/node_modules/assistant/dist/src/local-store.js

@@ -0,0 +1,58 @@
+/**
+ * The engine's record when it runs as an ordinary program: one small JSON file per key, in the
+ * agent's own folder. A new message writes one file, however long the record is, and each write
+ * lands whole. It answers as `kv@1` does, so the engine reads it as it reads any store.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const missing = (error) => error.code === "ENOENT";
+export function createLocalStore(dir) {
+    const keys = join(dir, "kv");
+    const scratch = join(dir, "tmp");
+    const pathOf = (key) => join(keys, encodeURIComponent(key));
+    return {
+        async get({ key }) {
+            try {
+                return { value: JSON.parse(await readFile(pathOf(key), "utf8")) };
+            }
+            catch (error) {
+                if (missing(error))
+                    return {};
+                throw error;
+            }
+        },
+        async set({ key, value }) {
+            await mkdir(keys, { recursive: true, mode: 0o700 });
+            await mkdir(scratch, { recursive: true, mode: 0o700 });
+            const temporary = join(scratch, randomUUID());
+            await writeFile(temporary, JSON.stringify(value), { mode: 0o600, flush: true });
+            await rename(temporary, pathOf(key));
+            return {};
+        },
+        async delete({ key }) {
+            try {
+                await rm(pathOf(key));
+                return { deleted: true };
+            }
+            catch (error) {
+                if (missing(error))
+                    return { deleted: false };
+                throw error;
+            }
+        },
+        async list({ prefix = "", after, limit = 1000 }) {
+            const names = await readdir(keys).catch((error) => {
+                if (missing(error))
+                    return [];
+                throw error;
+            });
+            const found = names
+                .map(decodeURIComponent)
+                .filter((key) => key.startsWith(prefix) && (after === undefined || key > after))
+                .sort();
+            const page = found.slice(0, limit);
+            return { keys: page, next: found.length > limit ? (page.at(-1) ?? null) : null };
+        },
+    };
+}

package/dist/node_modules/assistant/dist/src/provider.d.ts

@@ -0,0 +1,21 @@
+import { type Log } from "@agentorg/sdk";
+export interface AgentProviderOptions {
+    hubUrl: string;
+    /** The provider's own Actor, bound to `hub.actors@1` at `actors` and to the model at `model`. */
+    actorId: string;
+    credential: string;
+    /** The export its `model` slot is bound to, which each agent it makes is bound to in turn. */
+    model: {
+        actor: string;
+        export: string;
+    };
+    /** A private folder of the provider's, which holds each agent's credential and record. */
+    dir: string;
+    log?: Log;
+}
+export interface AgentProvider {
+    /** Leave the Hub, every agent with it. They stay, and rejoin at the next start as each was left. */
+    close(): Promise<void>;
+}
+/** Run the bundled agent provider as an Actor exporting `agent.provider@1` as `provider`. */
+export declare function startAgentProvider(options: AgentProviderOptions): Promise<AgentProvider>;

package/dist/node_modules/assistant/dist/src/provider.js

@@ -0,0 +1,259 @@
+/**
+ * The bundled agent provider: it offers one creatable, Assistant, and runs each agent in this
+ * process as its own Actor on its own channel. A stopped agent stays on its channel, so its chats
+ * can be read, and runs no turn until it is started. Each agent's chats and model choice are kept
+ * in the provider's private folder.
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { agentProvider, agentSettings, chat, hubActors, llmSession } from "@agentorg/interfaces";
+import { NotConnected, Refused } from "@agentorg/sdk";
+import { connect } from "@agentorg/sdk/client";
+import { z } from "zod";
+import { startEngine } from "./engine.js";
+import { createLocalStore } from "./local-store.js";
+const ASSISTANT_INSTRUCTIONS = `You are an assistant in AgentOrg, working for the person who created you.
+You act only through your tools, and your tools are exactly the connections the person gave you. If something needs a connection you don't have, say which.
+Before you promise to do something, check that one of your tools does it. A connection you are given later shows up as new tools at your next turn; until then, don't say you can use it.
+Keep replies short and plain.`;
+const ASSISTANT = {
+    id: "assistant",
+    title: "Assistant",
+    description: "An agent that chats, and acts through the connections you give it.",
+    instructions: ASSISTANT_INSTRUCTIONS,
+    asks: [],
+};
+/** What is kept of an agent between runs, in the provider's private file. */
+const Stored = z.object({ credential: z.string(), stopped: z.boolean() });
+const FILE = "agents.json";
+const quiet = { info() { }, warn() { }, error() { } };
+/** Run the bundled agent provider as an Actor exporting `agent.provider@1` as `provider`. */
+export async function startAgentProvider(options) {
+    const log = options.log ?? quiet;
+    const { hubUrl, dir } = options;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const path = join(dir, FILE);
+    const folderOf = (agent) => join(dir, "agents", agent);
+    /** The file; one that can't be read is set aside, so the agents in it can be recovered by hand. */
+    const read = () => {
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+        try {
+            return z.record(z.string(), Stored).parse(JSON.parse(raw));
+        }
+        catch {
+            renameSync(path, `${path}.unreadable-${Date.now()}`);
+            log.error("The agents file can't be read: it is set aside and starts empty.");
+            return {};
+        }
+    };
+    const stored = read();
+    const save = () => {
+        writeFileSync(`${path}.tmp`, JSON.stringify(stored), { mode: 0o600, flush: true });
+        renameSync(`${path}.tmp`, path);
+    };
+    const agents = new Map();
+    let closing = false;
+    const held = (agent) => {
+        const found = agents.get(agent);
+        if (!found)
+            throw new Refused("unknown", `This provider made no agent ${agent}.`);
+        return found;
+    };
+    /** An agent's engine, while it is on its channel: running, or stopped. */
+    const engineOf = (agent) => {
+        const { channel, engine, detail } = held(agent);
+        if (!channel || !engine)
+            throw new Refused("unavailable", detail ?? "It isn't running.");
+        return engine;
+    };
+    /**
+     * What an agent's model answered. A model that is away is refused as that, where the bare
+     * error would reach the caller as its own slot being away.
+     */
+    const ofModel = (asked) => asked.catch((error) => {
+        if (error instanceof NotConnected)
+            throw new Refused("not_connected", "Its model isn't connected.");
+        throw error;
+    });
+    const inTurn = (agent, work) => {
+        const one = held(agent);
+        const done = one.queue.then(() => work(one));
+        one.queue = done.catch(() => { });
+        return done;
+    };
+    /** Join the Hub as the agent, with its engine running, or stopped if it was left so. */
+    const open = async (agent, one) => {
+        one.state = "starting";
+        delete one.detail;
+        const { stopped } = stored[agent];
+        let engine;
+        try {
+            const channel = await connect({
+                hubUrl,
+                actorId: agent,
+                credential: stored[agent].credential,
+                slots: { model: llmSession, settings: agentSettings },
+                exports: { chat },
+                log,
+                start(ctx) {
+                    engine = startEngine(ctx, {
+                        store: createLocalStore(folderOf(agent)),
+                        instructions: () => ASSISTANT_INSTRUCTIONS,
+                        stopped,
+                    });
+                },
+            });
+            one.channel = channel;
+            one.engine = engine;
+            one.state = stopped ? "stopped" : "running";
+            void channel.closed.then(() => {
+                if (one.channel !== channel)
+                    return;
+                delete one.channel;
+                one.state = "down";
+                one.detail = "Its connection to the Hub ended.";
+            });
+        }
+        catch (error) {
+            one.state = "down";
+            one.detail = error instanceof Error ? error.message : String(error);
+            throw error;
+        }
+    };
+    /** Cut its turns, close its channel, and wait until its engine has written all it will. */
+    const halt = async (one) => {
+        const { channel, engine } = one;
+        delete one.channel;
+        if (!channel || !engine)
+            return;
+        await engine.close();
+        channel.close();
+        await channel.closed;
+        await engine.settled();
+    };
+    await Promise.all(Object.keys(stored).map(async (agent) => {
+        const one = { state: "stopped", queue: Promise.resolve() };
+        agents.set(agent, one);
+        try {
+            await open(agent, one);
+        }
+        catch (error) {
+            log.error(`Agent ${agent} didn't rejoin the Hub: ${String(error)}`);
+            // The Hub no longer knows it: its Actor was closed while the provider was away.
+            if (error instanceof Refused && error.code === "forbidden") {
+                agents.delete(agent);
+                delete stored[agent];
+                save();
+            }
+        }
+    }));
+    const haltAll = () => Promise.all([...agents.keys()].map((agent) => inTurn(agent, halt).catch(() => { })));
+    const provider = await connect({
+        hubUrl,
+        actorId: options.actorId,
+        credential: options.credential,
+        slots: { actors: hubActors, model: llmSession },
+        exports: { provider: agentProvider },
+        log,
+        start(ctx) {
+            ctx.exports.provider.implement({
+                creatable: async () => ({ creatables: [ASSISTANT] }),
+                async create({ creatable, name }) {
+                    if (creatable !== ASSISTANT.id)
+                        throw new Refused("unknown", `This provider offers no ${creatable}.`);
+                    // The provider is bound to the model's export, so it can give the agent that binding.
+                    const { actorId: agent, credential } = await ctx.slots.actors.call.create({
+                        name,
+                        bindings: [
+                            { slot: "model", provider: options.model.actor, export: options.model.export },
+                        ],
+                    });
+                    const one = { state: "starting", queue: Promise.resolve() };
+                    try {
+                        stored[agent] = { credential: credential, stopped: false };
+                        await open(agent, one);
+                        if (closing)
+                            throw new Refused("unavailable", "This provider is stopping.");
+                        agents.set(agent, one);
+                        save();
+                    }
+                    catch (error) {
+                        delete stored[agent];
+                        await halt(one);
+                        await ctx.slots.actors.call.close({ actorId: agent }).catch(() => { });
+                        await rm(folderOf(agent), { recursive: true, force: true });
+                        throw error;
+                    }
+                    return { agent, settings: "settings", chat: "chat" };
+                },
+                status: async ({ agent }) => {
+                    const { state, detail } = held(agent);
+                    return { state, ...(detail ? { detail } : {}) };
+                },
+                start: ({ agent }) => inTurn(agent, async (one) => {
+                    if (one.state === "running")
+                        return {};
+                    stored[agent].stopped = false;
+                    save();
+                    // One whose connection ended joins again; one that is only stopped goes on.
+                    if (!one.channel || !one.engine)
+                        await open(agent, one);
+                    else {
+                        one.engine.start();
+                        one.state = "running";
+                    }
+                    return {};
+                }),
+                stop: ({ agent }) => inTurn(agent, async (one) => {
+                    stored[agent].stopped = true;
+                    save();
+                    // One whose connection ended joins again, stopped, so that it can be read.
+                    if (!one.channel || !one.engine)
+                        await open(agent, one);
+                    else {
+                        await one.engine.stop();
+                        one.state = "stopped";
+                    }
+                    return {};
+                }),
+                models: ({ agent }) => ofModel(engineOf(agent).models()),
+                // In the agent's turn, so a choice never lands after the agent is removed.
+                setModel: ({ agent, model }) => inTurn(agent, async () => {
+                    await ofModel(engineOf(agent).setModel(model));
+                    return {};
+                }),
+                remove: ({ agent }) => inTurn(agent, async (one) => {
+                    await halt(one);
+                    one.state = "down";
+                    one.detail = "It is being removed.";
+                    await ctx.slots.actors.call.close({ actorId: agent });
+                    agents.delete(agent);
+                    delete stored[agent];
+                    save();
+                    await rm(folderOf(agent), { recursive: true, force: true });
+                    return {};
+                }),
+            });
+        },
+    }).catch(async (error) => {
+        await haltAll();
+        throw error;
+    });
+    return {
+        async close() {
+            closing = true;
+            await haltAll();
+            provider.close();
+        },
+    };
+}

package/dist/node_modules/assistant/dist/src/settings.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What the `settings` slot adds to a request: the skills exposed to this agent, named in its
+ * instructions, and one tool to read them. A skill's text is read only when the model asks for it.
+ */
+import type { agentSettings, SkillEntry } from "@agentorg/interfaces";
+import type { Slot } from "@agentorg/sdk";
+import type { z } from "zod";
+import type { Candidate, LeftOut } from "./tools.js";
+/** The longest instructions a request can carry. */
+export declare const MAX_INSTRUCTIONS = 200000;
+/** The agent's instructions and the skills that fit in them; any that don't are reported. */
+export declare function instructionsWith(instructions: string, skills: z.output<typeof SkillEntry>[]): {
+    instructions: string;
+    leftOut: LeftOut[];
+};
+/** The one way the model reads a skill: its `SKILL.md`, or a file of its folder by `path`. */
+export declare function skillTool(slot: Slot<typeof agentSettings>): Candidate;

package/dist/node_modules/assistant/dist/src/settings.js

@@ -0,0 +1,43 @@
+/** The longest instructions a request can carry. */
+export const MAX_INSTRUCTIONS = 200_000;
+const SLOT = "settings";
+const HEADING = `## Skills
+A skill is written instructions for a kind of task. When one fits what you're asked, read it with settings__skill and follow it before you start. Pass path to read a file its SKILL.md refers to.`;
+/** The agent's instructions and the skills that fit in them; any that don't are reported. */
+export function instructionsWith(instructions, skills) {
+    const leftOut = [];
+    if (skills.length === 0)
+        return { instructions, leftOut };
+    let text = `${instructions}\n\n${HEADING}`;
+    for (const { name, description } of skills) {
+        const line = `\n- ${name}: ${description}`;
+        if (text.length + line.length > MAX_INSTRUCTIONS)
+            leftOut.push({ slot: SLOT, tool: name, reason: "limit" });
+        else
+            text += line;
+    }
+    return leftOut.length === skills.length
+        ? { instructions, leftOut }
+        : { instructions: text, leftOut };
+}
+/** The one way the model reads a skill: its `SKILL.md`, or a file of its folder by `path`. */
+export function skillTool(slot) {
+    return {
+        slot: SLOT,
+        name: "skill",
+        description: "Read a skill: its SKILL.md, or with path a file in its folder.",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "The skill's name, as your instructions list it." },
+                path: { type: "string", description: "A file in the skill's folder, relative to it." },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        run: async (args) => {
+            const { text } = await slot.call.skill(args);
+            return { output: text, ok: true };
+        },
+    };
+}

package/dist/node_modules/assistant/dist/src/tools.d.ts

@@ -0,0 +1,57 @@
+import { type Outcome, type Tool } from "@agentorg/looper";
+import { type DescribedInterface } from "@agentorg/sdk";
+import type { z } from "zod";
+/** A tool as its slot gives it, before it has the name a request offers it under. */
+export interface Candidate {
+    slot: string;
+    name: string;
+    description?: string;
+    parameters: Record<string, z.core.util.JSONType>;
+    run(input: unknown): Promise<Outcome>;
+}
+/**
+ * Something the model isn't offered, and why: `name` (past 64 characters as a function name),
+ * `duplicate` (its function name is already taken), `limit` (past what a request can carry), or,
+ * with no `tool`, the code its slot's list failed with.
+ */
+export interface LeftOut {
+    slot: string;
+    tool?: string;
+    reason: string;
+}
+/** What a request can carry: its tools count, and, with the record and instructions, one frame. */
+export declare const MAX_TOOLS = 128;
+export declare const TOOLS_BUDGET: number;
+/** The first `length` UTF-16 units of `text`, never ending inside a surrogate pair. */
+export declare function head(text: string, length: number): string;
+/** The code and message of what a call through a slot threw. */
+export declare function codeOf(error: unknown): {
+    code: string;
+    message: string;
+};
+/**
+ * A call through a slot, as the looper is told how it went: what the slot refuses is the looper's
+ * `Refusal`, with the code to show and the slot's own error as its cause.
+ */
+export declare const relayed: <T>(call: Promise<T>) => Promise<T>;
+/** Whether a slot is a `tools@1`, whose tools are whatever it lists. */
+export declare const listsTools: (described: DescribedInterface) => boolean;
+/**
+ * What a `tools@1` slot lists now. A slot that can't answer gives no tools and says why, and is
+ * asked again at the next request.
+ */
+export declare function listedBy(name: string, slot: {
+    readonly call: Readonly<Record<string, (input: unknown) => Promise<unknown>>>;
+}): Promise<{
+    candidates: Candidate[];
+    leftOut: LeftOut[];
+}>;
+/**
+ * The tools one request offers, by function name, and what it can't. A character a function name
+ * can't have becomes `_`. Candidates are taken in order, so the first ones given are the ones kept
+ * when a request is full; what doesn't fit is reported, never sent.
+ */
+export declare function offered(candidates: Candidate[]): {
+    tools: Tool[];
+    leftOut: LeftOut[];
+};