@agentorg/cli 0.0.8 → 0.0.9

package/dist/node_modules/@agentorg/looper/dist/src/main.d.ts

@@ -1,34 +1,90 @@
 import type { Log, Model, ToolSpec } from "./types.js";
-/** What the main loop is told. */
-export declare const MAIN_INSTRUCTIONS = "You are the front desk. You do none of the work and you answer nobody: you say whose a message is, by calling `route` once.\n\nYou are given the pieces of work under way, each by its id and title, and what has come in where no work is listening yet.\n\n- Give it to a piece of work under way only when it points at that work explicitly: it names it, quotes it, or refers to what it is doing, and exactly one piece of work fits. Call `route` with that work's id. Its worker will read it with everything it already knows, and answer where it came in. From then on everything said there goes to that work.\n- Anything else is new work, also when it is on a subject like that of work under way. Call `route` with no `work`, and a `title` of a few words that says what the new work is.\n\nA wrong match stays, so when in doubt it is new work. Your only answer is the call.";
+/** What the main loop is told, before who it speaks as. */
+export declare const MAIN_INSTRUCTIONS = "You are the front desk. You do none of the work: you say whose a message is, answer it yourself when it needs no work, or stop a piece of work it asks to stop.\n\nYou are given the latest pieces of work, each by its id and title, whether it is in a turn or at rest, and a line on what it last said; then the conversation where a message has come in that no work owns.\n\n- Give it to a piece of work only when it points at that work explicitly: it names it, quotes it, or refers to what it is doing or just did, and exactly one piece of work fits. Call `route` with that work's id. Its worker will read it with everything it already knows, and answer where it came in. From then on everything said there goes to that work.\n- Answer it yourself, in plain text and calling nothing, only when it needs no tools and nothing you can't see here: a greeting, thanks, a question about who you are or about the work listed, or a request to stop that no one piece of work in a turn fits. Never say you will do, find, check or look into something: you can't, and saying so starts no work.\n- Stop a piece of work when the message asks to stop it and exactly one piece of work in a turn fits. Call `route` with only `stop`, set to its id, and say in a few words that you stopped it. If none fits, or more than one, stop nothing and call nothing: say what is in a turn, so they can say which.\n- Anything else is new work, also when it is on a subject like that of work there is. Call `route` with no `work`, and a `title` of a few words that says what the new work is.\n\nWhatever you write is said to the person as the reply. So when you give a message to work, old or new, write nothing: the worker answers.\n\nA wrong match stays, and a promise starts nothing: when in doubt whose it is, it is new work.";
+/**
+ * What the main loop is told when a message was said to work that is in a turn: the worker has
+ * it, and the main loop may only stop that work.
+ */
+export declare const HEARD_INSTRUCTIONS = "You are the front desk. You are given one piece of work that is in a turn, by its id and title, and then a message that was just said in a conversation that work follows. Its worker has the message and will read it: you don't answer it, and you give it to nobody.\n\nAct only if the message asks to stop that work. Then call `route` with only `stop`, set to its id, and say in a few words that you stopped it. Otherwise call nothing and write nothing: what you write is said only when you stop it.";
+/** What is said where the main loop called to stop work and wrote nothing: whether a turn was cut. */
+export declare const stopWord: (cut: boolean) => "Nothing was stopped." | "Stopped.";
 /** The one function the main loop calls. */
 export declare const ROUTE: ToolSpec;
 /** A piece of work as the main loop is told of it. */
-export interface Underway {
+export interface Listed {
     id: string;
     title: string;
+    /** Which turn of it is running or waiting for its place, when one is. */
+    turn?: number | undefined;
+    /** The head of what it last said, if it has said anything. */
+    last?: string | undefined;
+    /** Whether its last turn failed. */
+    failed?: boolean | undefined;
+}
+/** A message of the thread, as the main loop reads it. */
+export interface Said {
+    role: "user" | "assistant";
+    text: string;
+}
+/**
+ * What the main loop decided. `answer` is what it wrote. `placed` is whose what came in is: work
+ * it was told of, or new work by its title. `stop` is there when it called to stop work, and
+ * then nothing is placed: the turn to cut is the one it was told of, and none when that work was
+ * not told of as in a turn.
+ */
+export interface Decided {
+    answer?: string;
+    placed?: {
+        work: string;
+    } | {
+        title: string;
+    };
+    stop?: {
+        work: string;
+        turn?: number;
+    };
 }
-/** What the main loop decided: work under way that takes the messages, or new work's title. */
-export type Routed = {
-    work: string;
-} | {
-    title: string;
-};
 /** A work's title: the first line of `text` that says anything, in a few words. */
 export declare const titled: (text: string) => string;
-/** What has come in, as it is put to the main loop with the work under way. */
-export declare const put: (texts: string[], underway: Underway[]) => string;
+/**
+ * How much the main loop is told, enough to place a message: the thread's newest messages and the
+ * start of each, the latest pieces of work with the start of what each last said, and the start
+ * of who it speaks as.
+ */
+export declare const TOLD: {
+    messages: number;
+    each: number;
+    works: number;
+    last: number;
+    voice: number;
+};
 export declare function createMain(options: {
     model: Model;
-    /** Which model to ask, none meaning the model's own default. */
-    chosen(): Promise<string | undefined>;
+    /**
+     * Read for each request: which model to ask, none meaning the model's own default, and who the
+     * main loop speaks as when it answers itself.
+     */
+    request(): Promise<{
+        model?: string | undefined;
+        voice?: string | undefined;
+    }>;
     log: Log;
 }): {
     /**
-     * Say whose `texts` are, given the work under way: one decision at a time. Nothing is said
-     * for a decision that is cancelled. A request the model refuses rejects, as it refused.
+     * Decide on a thread, given what was said in it and the work there is. `written` is given its
+     * text as the model writes it. Nothing is said for a decision that is dropped. A request the
+     * model refuses rejects, as it refused.
+     */
+    decide(said: Said[], works: Listed[], written: (text: string) => void): Promise<Decided | undefined>;
+    /**
+     * Hear a message that joined a turn of `work`, which has it: the main loop may only stop
+     * that turn, and is not told who it speaks as. It gives what to say where the message was
+     * said if it says to stop it, and none if it doesn't or the request is dropped. Nothing it
+     * writes is said otherwise. A request the model refuses rejects, as it refused.
      */
-    route(texts: string[], underway: Underway[]): Promise<Routed | undefined>;
-    /** Drop the decision being made: its request is cancelled, and it says nothing. */
+    hear(text: string, work: Listed): Promise<string | undefined>;
+    /** Text the model writes while it answers `requestId`, if that is the request out now. */
+    delta(requestId: string, text: string): void;
+    /** Drop the request out now: it is cancelled, and it says nothing. */
     cancel(): Promise<void>;
 };

package/dist/node_modules/@agentorg/looper/dist/src/main.js

@@ -1,111 +1,200 @@
 /**
- * The main loop: one per looper. It is given the messages that have come in where no piece of
- * work is listening, and says whose they are: new work, or work under way. It does none of the
- * work and answers nobody. It has one function to call, and each decision is one model request
- * that holds nothing of the decisions before it.
+ * The main loop: one per looper. It is given a thread no piece of work follows, in which a message
+ * has come in, and the work there is. It says whose the message is, new work or work there is, or
+ * answers it itself when it needs no work, or stops a piece of work the message asks to stop. It
+ * is also told of a message said to work that is in a turn, which that work has: then it is given
+ * that work and that message, and may only stop that work. It does none of the work, and it has
+ * one function to call. Each time is one model request, which holds nothing of those before it
+ * but what it is given.
  */
 import { head } from "./record.js";
-/** What the main loop is told. */
-export const MAIN_INSTRUCTIONS = `You are the front desk. You do none of the work and you answer nobody: you say whose a message is, by calling \`route\` once.
+/** What the main loop is told, before who it speaks as. */
+export const MAIN_INSTRUCTIONS = `You are the front desk. You do none of the work: you say whose a message is, answer it yourself when it needs no work, or stop a piece of work it asks to stop.
 
-You are given the pieces of work under way, each by its id and title, and what has come in where no work is listening yet.
+You are given the latest pieces of work, each by its id and title, whether it is in a turn or at rest, and a line on what it last said; then the conversation where a message has come in that no work owns.
 
-- Give it to a piece of work under way only when it points at that work explicitly: it names it, quotes it, or refers to what it is doing, and exactly one piece of work fits. Call \`route\` with that work's id. Its worker will read it with everything it already knows, and answer where it came in. From then on everything said there goes to that work.
-- Anything else is new work, also when it is on a subject like that of work under way. Call \`route\` with no \`work\`, and a \`title\` of a few words that says what the new work is.
+- Give it to a piece of work only when it points at that work explicitly: it names it, quotes it, or refers to what it is doing or just did, and exactly one piece of work fits. Call \`route\` with that work's id. Its worker will read it with everything it already knows, and answer where it came in. From then on everything said there goes to that work.
+- Answer it yourself, in plain text and calling nothing, only when it needs no tools and nothing you can't see here: a greeting, thanks, a question about who you are or about the work listed, or a request to stop that no one piece of work in a turn fits. Never say you will do, find, check or look into something: you can't, and saying so starts no work.
+- Stop a piece of work when the message asks to stop it and exactly one piece of work in a turn fits. Call \`route\` with only \`stop\`, set to its id, and say in a few words that you stopped it. If none fits, or more than one, stop nothing and call nothing: say what is in a turn, so they can say which.
+- Anything else is new work, also when it is on a subject like that of work there is. Call \`route\` with no \`work\`, and a \`title\` of a few words that says what the new work is.
 
-A wrong match stays, so when in doubt it is new work. Your only answer is the call.`;
+Whatever you write is said to the person as the reply. So when you give a message to work, old or new, write nothing: the worker answers.
+
+A wrong match stays, and a promise starts nothing: when in doubt whose it is, it is new work.`;
+/**
+ * What the main loop is told when a message was said to work that is in a turn: the worker has
+ * it, and the main loop may only stop that work.
+ */
+export const HEARD_INSTRUCTIONS = `You are the front desk. You are given one piece of work that is in a turn, by its id and title, and then a message that was just said in a conversation that work follows. Its worker has the message and will read it: you don't answer it, and you give it to nobody.
+
+Act only if the message asks to stop that work. Then call \`route\` with only \`stop\`, set to its id, and say in a few words that you stopped it. Otherwise call nothing and write nothing: what you write is said only when you stop it.`;
+/** What is said where the main loop called to stop work and wrote nothing: whether a turn was cut. */
+export const stopWord = (cut) => (cut ? "Stopped." : "Nothing was stopped.");
+/** How who it speaks as is told after that. */
+const VOICE = "When you answer yourself, you speak as the one described below. What that one is told to do is a worker's to do, not yours:";
 /** The one function the main loop calls. */
 export const ROUTE = {
     name: "route",
-    description: "Says whose what came in is: a piece of work under way, or new work.",
+    description: "Says whose what came in is: a piece of work there is, or new work. Or stops a piece of work.",
     parameters: {
         type: "object",
         properties: {
             work: {
                 type: "string",
-                description: "The id of the work under way that it points at. Leave it out for new work.",
+                description: "The id of the work that it points at. Leave it out for new work.",
             },
             title: {
                 type: "string",
                 description: "For new work: a few words that say what it is.",
             },
+            stop: {
+                type: "string",
+                description: "The id of the work in a turn to stop. With it, leave the others out.",
+            },
         },
     },
 };
 /** A work's title: the first line of `text` that says anything, in a few words. */
 export const titled = (text) => head((text.split("\n").find((line) => /\S/.test(line)) ?? "").replace(/\s+/g, " ").trim(), 80);
-/** The main loop is put the newest messages waiting, and the start of each: enough to place them. */
-const PUT = { messages: 8, each: 4000 };
-/** What has come in, as it is put to the main loop with the work under way. */
-export const put = (texts, underway) => [
-    underway.length === 0 ? "No work is under way." : "Work under way:",
-    ...underway.map(({ id, title }) => `- ${id}: ${title}`),
-    "",
-    "What came in:",
-    texts
-        .slice(-PUT.messages)
-        .map((text) => (text.length > PUT.each ? `${head(text, PUT.each)}…` : text))
-        .join("\n\n"),
-].join("\n");
+/**
+ * How much the main loop is told, enough to place a message: the thread's newest messages and the
+ * start of each, the latest pieces of work with the start of what each last said, and the start
+ * of who it speaks as.
+ */
+export const TOLD = { messages: 8, each: 4000, works: 12, last: 200, voice: 100_000 };
+/** The work there is, as the main loop is told of it. */
+const listing = (works) => works.length === 0
+    ? "There is no work."
+    : [
+        "The work there is:",
+        ...works.map(({ id, title, turn, last, failed }) => {
+            const state = turn !== undefined ? "in a turn" : failed ? "at rest; its last turn failed" : "at rest";
+            return `- ${id}: ${title} (${state})${last ? `; it last said: ${last}` : ""}`;
+        }),
+    ].join("\n");
+/** What the main loop's request holds: the work there is, then the thread as a conversation. */
+const put = (said, works) => [
+    { type: "message", role: "user", content: listing(works) },
+    ...said.slice(-TOLD.messages).map(({ role, text }) => ({
+        type: "message",
+        role,
+        content: text.length > TOLD.each ? `${head(text, TOLD.each)}…` : text,
+    })),
+];
 export function createMain(options) {
-    /** The decision being made now, and how to drop it. */
-    let deciding;
+    /** The request out now, whether it was dropped, and where its text goes as it is written. */
+    let asking;
+    /**
+     * Make one request of the model: what it wrote, and what it called `route` with. `voiced` is
+     * whether it is told who it speaks as. None for a request that is dropped, which the model is
+     * then not asked, or told to cancel; one the model refuses rejects, as it refused.
+     */
+    const ask = async (instructions, voiced, input, written) => {
+        let drop = () => { };
+        const gone = new Promise((resolve) => {
+            drop = () => {
+                mine.dropped = true;
+                resolve(undefined);
+            };
+        });
+        const mine = { drop: () => drop(), written };
+        asking = mine;
+        try {
+            const given = await Promise.race([options.request().then((to) => ({ to })), gone]);
+            if (!given || mine.dropped)
+                return undefined;
+            const { model, voice } = given.to;
+            mine.requestId = crypto.randomUUID();
+            const asked = options.model.respond({
+                requestId: mine.requestId,
+                ...(model ? { model } : {}),
+                instructions: voiced && voice
+                    ? `${instructions}\n\n${VOICE}\n\n${head(voice, TOLD.voice)}`
+                    : instructions,
+                input,
+                tools: [ROUTE],
+            });
+            // A model that never answers a request it was told to cancel holds nothing up.
+            asked.catch(() => { });
+            const reply = await Promise.race([asked, gone]);
+            if (!reply || mine.dropped)
+                return undefined;
+            const text = reply.output
+                .flatMap((item) => (item.type === "message" ? [item.content] : []))
+                .join("");
+            const call = reply.output.find((item) => item.type === "function_call" && item.name === ROUTE.name);
+            let routed;
+            if (call?.type === "function_call")
+                try {
+                    routed = (JSON.parse(call.arguments) ?? {});
+                }
+                catch {
+                    // Arguments that don't read: as a call that says nothing.
+                    routed = {};
+                }
+            return { ...(text.trim() ? { text } : {}), routed };
+        }
+        finally {
+            if (asking === mine)
+                asking = undefined;
+        }
+    };
+    /** The turn of the work that `stop` names, if it was told of as in a turn. */
+    const turnOf = (stop, works) => works.find(({ id }) => id === stop)?.turn;
     return {
         /**
-         * Say whose `texts` are, given the work under way: one decision at a time. Nothing is said
-         * for a decision that is cancelled. A request the model refuses rejects, as it refused.
+         * Decide on a thread, given what was said in it and the work there is. `written` is given its
+         * text as the model writes it. Nothing is said for a decision that is dropped. A request the
+         * model refuses rejects, as it refused.
          */
-        async route(texts, underway) {
-            let drop = () => { };
-            const dropped = new Promise((resolve) => {
-                drop = () => resolve(undefined);
-            });
-            const mine = { drop };
-            deciding = mine;
-            try {
-                const chosen = await Promise.race([options.chosen().then((model) => ({ model })), dropped]);
-                if (!chosen)
-                    return undefined;
-                mine.requestId = crypto.randomUUID();
-                const asked = options.model.respond({
-                    requestId: mine.requestId,
-                    ...(chosen.model ? { model: chosen.model } : {}),
-                    instructions: MAIN_INSTRUCTIONS,
-                    input: [{ type: "message", role: "user", content: put(texts, underway) }],
-                    tools: [ROUTE],
-                });
-                // A model that never answers a request it was told to cancel holds nothing up.
-                asked.catch(() => { });
-                const answer = await Promise.race([asked, dropped]);
-                if (!answer)
-                    return undefined;
-                const call = answer.output.find((item) => item.type === "function_call" && item.name === ROUTE.name);
-                let said = {};
-                if (call?.type === "function_call")
-                    try {
-                        said = (JSON.parse(call.arguments) ?? {});
-                    }
-                    catch {
-                        // Arguments that don't read: new work, as with no call.
-                    }
-                if (underway.some(({ id }) => id === said.work))
-                    return { work: said.work };
-                // Anything else starts new work, titled by what came in if the model gave no title.
-                if (typeof said.work === "string" && said.work !== "")
-                    options.log.warn("The main loop named work that isn't under way; it is new work.", {
-                        work: head(said.work, 128),
-                    });
-                const title = titled(typeof said.title === "string" ? said.title : "");
-                return { title: title || titled(texts.join("\n")) };
-            }
-            finally {
-                if (deciding === mine)
-                    deciding = undefined;
+        async decide(said, works, written) {
+            const asked = await ask(MAIN_INSTRUCTIONS, true, put(said, works), written);
+            if (!asked)
+                return undefined;
+            const { text, routed } = asked;
+            const answered = text === undefined ? {} : { answer: text };
+            // Text and no call: it answered, and nothing is placed.
+            if (!routed && text !== undefined)
+                return answered;
+            // A call that names work to stop only stops: nothing is placed.
+            if (typeof routed?.stop === "string" && routed.stop !== "") {
+                const turn = turnOf(routed.stop, works);
+                return {
+                    ...answered,
+                    stop: { work: routed.stop, ...(turn === undefined ? {} : { turn }) },
+                };
             }
+            if (works.some(({ id }) => id === routed?.work))
+                return { ...answered, placed: { work: routed?.work } };
+            // Anything else starts new work, titled by what came in if the model gave no title.
+            if (typeof routed?.work === "string" && routed.work !== "")
+                options.log.warn("The main loop named work there isn't; it is new work.", {
+                    work: head(routed.work, 128),
+                });
+            const title = titled(typeof routed?.title === "string" ? routed.title : "");
+            const newest = said.findLast(({ role }) => role === "user")?.text ?? "";
+            return { ...answered, placed: { title: title || titled(newest) } };
+        },
+        /**
+         * Hear a message that joined a turn of `work`, which has it: the main loop may only stop
+         * that turn, and is not told who it speaks as. It gives what to say where the message was
+         * said if it says to stop it, and none if it doesn't or the request is dropped. Nothing it
+         * writes is said otherwise. A request the model refuses rejects, as it refused.
+         */
+        async hear(text, work) {
+            const asked = await ask(HEARD_INSTRUCTIONS, false, put([{ role: "user", text }], [work]), () => { });
+            return asked && turnOf(asked.routed?.stop, [work]) !== undefined
+                ? (asked.text ?? stopWord(true))
+                : undefined;
+        },
+        /** Text the model writes while it answers `requestId`, if that is the request out now. */
+        delta(requestId, text) {
+            if (asking?.requestId === requestId)
+                asking.written(text);
         },
-        /** Drop the decision being made: its request is cancelled, and it says nothing. */
+        /** Drop the request out now: it is cancelled, and it says nothing. */
         async cancel() {
-            const cut = deciding;
+            const cut = asking;
             if (!cut)
                 return;
             cut.drop();

package/dist/node_modules/@agentorg/looper/dist/src/record.d.ts

@@ -41,6 +41,7 @@ export declare const Entry: z.ZodObject<{
     joined: z.ZodOptional<z.ZodLiteral<true>>;
     ahead: z.ZodOptional<z.ZodNumber>;
     work: z.ZodOptional<z.ZodString>;
+    main: z.ZodOptional<z.ZodNumber>;
     place: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type Entry = z.output<typeof Entry>;
@@ -97,20 +98,62 @@ export declare function createThread(store: Store, log: Log, limits?: {
 }): {
     /** What it holds, read once. */
     load: () => Promise<Held>;
-    /**
-     * Keep a message in a thread already read, at once, under `id` or its own number; `stored`
-     * settles when it is written and the oldest past the cap are deleted. A tool message the store
-     * refuses is still kept in memory, since its call has run; any other is taken out again.
-     */
-    push(held: Held, entry: Omit<Entry, "id" | "at">, id?: string): {
+    push: (held: Held, entry: Omit<Entry, "id" | "at">, id?: string) => {
         record: Kept;
         stored: Promise<void>;
     };
     /**
-     * Keep a message as `entry` from now on: at once in memory, then in the store. A write the
-     * store refuses leaves it as it was.
+     * What was said in it, as a conversation: each message and each reply the main loop gave, in
+     * the order they were answered; and the number it holds up to.
+     */
+    said(): Promise<{
+        said: {
+            role: "user" | "assistant";
+            text: string;
+        }[];
+        upTo: number;
+    }>;
+    /**
+     * Keep, under `id`, a reply the main loop gave after it had read up to `upTo`. `late` says
+     * whether a message was said after that, which this reply doesn't answer.
+     */
+    answer(text: string, upTo: number, id: string): Promise<{
+        entry: {
+            id: string;
+            role: "assistant" | "tool" | "user";
+            text?: string | undefined;
+            at: string;
+            items: ({
+                type: "message";
+                role: "assistant" | "user";
+                content: string;
+            } | {
+                type: "function_call";
+                callId: string;
+                name: string;
+                arguments: string;
+            } | {
+                type: "function_call_output";
+                callId: string;
+                output: string;
+            })[];
+            state?: "done" | "refused" | undefined;
+            joined?: true | undefined;
+            ahead?: number | undefined;
+            work?: string | undefined;
+            main?: number | undefined;
+            place?: number | undefined;
+        };
+        late: boolean;
+    }>;
+    /**
+     * Hold a message as `entry` from now on, in memory: `store` writes it as it then is, and
+     * `undo` puts it back as it was.
      */
-    rewrite(held: Held, record: Kept, entry: Entry): Promise<void>;
+    change(held: Held, record: Kept, entry: Entry): {
+        store: () => Promise<unknown>;
+        undo: () => void;
+    };
     /** Messages before `before`, oldest first, as many as fit `limit` and `PAGE_BUDGET`. */
     page(before: string | undefined, limit: number): Promise<{
         messages: Shown[];
@@ -121,8 +164,8 @@ export type Thread = ReturnType<typeof createThread>;
 /**
  * A piece of work's record: its messages across the threads it follows, in the order it took them.
  * Its id is the name of its own thread, whose messages are its unless they name another work; in
- * any other thread, the messages that name it are. A message's place is its number in its own
- * thread until the work follows a second thread, and a count kept with each message after. A
+ * any other thread, the messages that name it are. A message's place is where it stands in its
+ * own thread until the work follows a second thread, and a count kept with each message after. A
  * message waiting in a thread it follows, said before the work had the thread, names no work yet:
  * the work takes it, in the order it was said, before it keeps anything else there.
  */
@@ -136,24 +179,39 @@ export declare function createRecord(options: {
     /**
      * Keep a message of its in `thread`, one of those it follows, after any waiting there. `read`
      * is given for what came of a model request that had read it up to that place: when a user
-     * message was said since, it is kept as `ahead` of it.
+     * message was said since, or the turn was stopped by saying so, it is kept as `ahead` of
+     * that.
      */
-    append(entry: Omit<Entry, "id" | "at" | "work" | "place" | "ahead">, at: {
+    append: (entry: Omit<Entry, "id" | "at" | "work" | "place" | "ahead">, at: {
         thread: string;
         id?: string;
         read?: number;
-    }): Promise<{
+    }) => Promise<{
+        entry: Entry;
+        thread: string;
+    }>;
+    /**
+     * Keep in `thread` what the main loop said as it stopped a turn of this work. It stands after
+     * all the thread holds, and like a message said in that turn, the work reads it after
+     * whatever the turn still writes.
+     */
+    stopLine: (text: string, thread: string) => Promise<{
         entry: Entry;
         thread: string;
     }>;
     /**
      * Take the messages waiting in `thread`, which it has come to follow, as its own: `joined`,
-     * when a turn of its is running. It says how many there were to answer: in its own thread,
-     * where nothing needs taking, those said since it last did anything.
+     * when a turn of its is running or a stopped one is still writing. It says how many there were to answer: in its own thread,
+     * where nothing needs taking, those said since it last did anything itself.
      */
     adopt(thread: string, joined: boolean): Promise<number>;
-    /** Whether it holds anything but what was said to it: it has had a turn that did something. */
+    /**
+     * Whether it has had a turn that did something: it holds more than what was said to it and
+     * what the main loop said.
+     */
     begun(): Promise<boolean>;
+    /** What it last said, if anything. */
+    last(): Promise<string | undefined>;
     /** Whether it has no message. */
     empty(): Promise<boolean>;
     /** The thread it answers in now. */
@@ -161,7 +219,7 @@ export declare function createRecord(options: {
     /** Its first user message, for a title. */
     opening(): Promise<string>;
     /**
-     * The conversation to send: the newest exchanges (each from the user message that starts a turn
+     * The conversation to send: the newest exchanges (each from a user message that is not `joined`
      * on) that fit the budget, and always the latest two, so "go on" after a long turn still has
      * that turn. When those two are over the budget, their oldest function arguments and outputs
      * are left out, each call still paired with an output. A message said during a turn comes after