@agentorg/cli 0.0.6 → 0.0.7

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

@@ -0,0 +1,282 @@
+/**
+ * The looper: the loops of whoever hosts it, one for each thread a message comes in on. A thread is
+ * a name its host gives; its record is kept under `thread/<name>/` in the store, and its loop and
+ * record are made when the thread is first used and then stay in memory.
+ *
+ * Turns run side by side, each in a place. There are `PLACES` of them, and one more that only a
+ * thread already begun (its record holds something) may take, so new threads never keep a message
+ * from one that is under way. A turn that finds no place waits for one, in the order it came. While
+ * begun threads keep five turns running, a new thread goes on waiting. `WAITING` turns may wait;
+ * past that a message that would start a turn is refused `busy`, and nothing of it is kept.
+ *
+ * A thread is marked in the store while a turn of it hasn't ended. A looper that closes under a
+ * turn, or goes without closing, leaves the mark, and `resume` on the same store goes on with that
+ * turn, once: the turn that goes on is not marked. A turn that ends, fails or is stopped leaves
+ * no mark.
+ */
+import { createLoop } from "./loop.js";
+import { createRecord } from "./record.js";
+import { Refusal, } from "./types.js";
+/** The turns that run at once, not counting the one more for a thread already begun. */
+export const PLACES = 4;
+/** The turns that may wait for a place at once. */
+export const WAITING = 16;
+/** Where a thread's record is kept in the looper's store. */
+const recordOf = (thread) => `thread/${encodeURIComponent(thread)}/`;
+/** Where a thread is marked while a turn of it hasn't ended. */
+const UNFINISHED = "unfinished/";
+/** The store's keys under `prefix`, as a store of its own. */
+function under(store, prefix) {
+    return {
+        get: ({ key }) => store.get({ key: prefix + key }),
+        set: ({ key, value }) => store.set({ key: prefix + key, value }),
+        delete: ({ key }) => store.delete({ key: prefix + key }),
+        async list({ prefix: inner = "", after, limit }) {
+            const page = await store.list({
+                prefix: prefix + inner,
+                ...(after === undefined ? {} : { after: prefix + after }),
+                ...(limit === undefined ? {} : { limit }),
+            });
+            return {
+                keys: page.keys.map((key) => key.slice(prefix.length)),
+                next: page.next === null ? null : page.next.slice(prefix.length),
+            };
+        },
+    };
+}
+/**
+ * Make a looper. Nothing is read or run until a thread is named: a message sent in it, or its
+ * messages asked for.
+ */
+export function createLooper(options) {
+    const { store, out, log } = options;
+    const threads = new Map();
+    /** Set while it is stopped: no turn starts until it is started. */
+    let stopped = options.stopped ?? false;
+    /** Set when it closes: no turn starts after. */
+    let closed = false;
+    /** Set once the turns that were cut off have been looked for. */
+    let looked = false;
+    /** Refuse a turn that can't start now, whatever thread it is for. */
+    const mayStart = () => {
+        if (closed)
+            throw new Refusal("unavailable", "This agent is closing.");
+        if (stopped)
+            throw new Refusal("busy", "It is stopped. Start it to go on.");
+    };
+    /** Messages being recorded now, each about to start a turn: stopping waits for them. */
+    const starting = new Set();
+    const started = (call) => {
+        const done = call.then(() => void starting.delete(done), () => void starting.delete(done));
+        starting.add(done);
+        return call;
+    };
+    /** The turns that have a place, and those waiting for one, first come first. */
+    const placed = new Set();
+    const waiting = [];
+    const fits = (begun) => placed.size < PLACES + (begun ? 1 : 0);
+    const enter = (begun) => {
+        let take = () => { };
+        const place = {
+            entered: new Promise((resolve) => {
+                take = resolve;
+            }),
+            leave() {
+                take();
+                const queued = waiting.findIndex((one) => one.place === place);
+                if (queued !== -1)
+                    waiting.splice(queued, 1);
+                if (!placed.delete(place))
+                    return;
+                // Its place goes to whoever has waited longest for one they may take.
+                const next = waiting.find((one) => fits(one.begun));
+                if (!next)
+                    return;
+                waiting.splice(waiting.indexOf(next), 1);
+                placed.add(next.place);
+                next.take();
+            },
+        };
+        if (fits(begun)) {
+            placed.add(place);
+            take();
+        }
+        else if (waiting.length < WAITING)
+            waiting.push({ place, begun, take });
+        else
+            throw new Refusal("busy", "Too many turns are waiting. Wait for one to start.");
+        return place;
+    };
+    const open = (thread) => {
+        const record = createRecord(under(store, recordOf(thread)), log);
+        const key = UNFINISHED + encodeURIComponent(thread);
+        const held = {
+            record,
+            /** What is being asked of its loop now: messages, going on. */
+            uses: 0,
+            /** Whether a turn of it is running, as its mark was last asked to say. */
+            marked: false,
+            /** Its mark's writes, one after another. */
+            writes: Promise.resolve(),
+            /** Keep its mark, or take it off, after any write before. */
+            mark(on) {
+                held.writes = held.writes
+                    .then(() => (on ? store.set({ key, value: true }) : store.delete({ key })))
+                    .then(() => { }, (error) => log.error("A thread's mark couldn't be written.", { thread, error: String(error) }));
+            },
+            loop: createLoop({
+                request: options.request,
+                model: options.model,
+                enter,
+                record,
+                out: {
+                    message: (message) => out.message(thread, message),
+                    delta: (id, text) => out.delta(thread, id, text),
+                    status(status) {
+                        const running = status.state === "thinking" || status.state === "tool";
+                        // A turn that starts is marked, but one that goes on from a cut-off has that mark
+                        // taken off: it goes on once. A turn that ends takes its mark off, but one cut by the
+                        // looper closing keeps it, for whoever opens the store next.
+                        if (running && !held.marked)
+                            held.mark(!held.loop.resumed());
+                        else if (!running && held.marked && !closed)
+                            held.mark(false);
+                        held.marked = running;
+                        out.status(thread, status);
+                    },
+                },
+                log,
+            }),
+        };
+        return held;
+    };
+    /**
+     * Ask something of a thread's loop. A thread first named by an ask that fails, with nothing else
+     * asked of it meanwhile, was never used: nothing is held for it.
+     */
+    const using = async (thread, ask) => {
+        const known = threads.has(thread);
+        const held = of(thread);
+        held.uses++;
+        try {
+            return await started(ask(held.loop));
+        }
+        catch (error) {
+            if (!known && held.uses === 1)
+                threads.delete(thread);
+            throw error;
+        }
+        finally {
+            held.uses--;
+        }
+    };
+    const of = (thread) => {
+        const found = threads.get(thread) ?? open(thread);
+        threads.set(thread, found);
+        return found;
+    };
+    /**
+     * Go on with each turn that was cut off when this store was last used: by a looper closing
+     * under it, or going without closing. Each goes on once, and waits for a place like any turn.
+     * One that can't go on now keeps its mark for the next time. A stopped looper goes on with
+     * none, and its marks go: so does one stopped before it was asked to. Whoever hosts the looper calls this when a request can be made;
+     * once the marks have been read, a later call does nothing.
+     */
+    async function resume() {
+        if (looked || closed)
+            return;
+        looked = true;
+        const keys = [];
+        try {
+            let after;
+            do {
+                const page = await store.list({ prefix: UNFINISHED, ...(after ? { after } : {}) });
+                keys.push(...page.keys);
+                after = page.next ?? undefined;
+            } while (after);
+        }
+        catch (error) {
+            looked = false;
+            throw error;
+        }
+        for (const key of keys) {
+            // Closed meanwhile: what is left stays marked, for whoever opens the store next.
+            if (closed)
+                return;
+            const thread = decodeURIComponent(key.slice(UNFINISHED.length));
+            const held = of(thread);
+            try {
+                if (!stopped)
+                    await using(thread, (loop) => loop.resume());
+                // A thread in a turn now keeps the mark as that turn's, and a looper that has closed
+                // leaves it. Otherwise nothing goes on, and it goes.
+                if (!held.marked && !closed)
+                    held.mark(false);
+            }
+            catch (error) {
+                log.warn("A turn that was cut off didn't go on.", { key, error: String(error) });
+            }
+        }
+    }
+    return {
+        /**
+         * Say a message in a thread. It is recorded and said at once. With no turn in the thread it
+         * starts one, which waits for a place if none is free; a turn running or waiting takes it at
+         * its next model request. Refused `busy` while `WAITING` turns already wait and it would start
+         * one more, or while the looper is stopped; and `unavailable` once it has closed.
+         */
+        async send(thread, text) {
+            mayStart();
+            const sent = await using(thread, (loop) => loop.send(text));
+            // Recorded as the looper closed, its turn was cut before it began: it is marked like one.
+            const held = threads.get(thread);
+            if (closed && held && !held.marked)
+                held.mark(true);
+            return sent;
+        },
+        /** Stop a thread's turn now. A call already running finishes, and its result is kept. */
+        cancel: async (thread) => threads.get(thread)?.loop.cancel(),
+        /** What a thread's loop is doing. */
+        state: (thread) => threads.get(thread)?.loop.state() ?? { state: "idle" },
+        /** A thread's messages before `before`, oldest first, as many as fit `limit`. */
+        page: (thread, before, limit) => of(thread).record.page(before, limit),
+        /**
+         * Stop: every turn is cut, running or waiting, and none starts until `start`. A call already
+         * running finishes first, so this answers when nothing more will be written. The records stay
+         * as they are, to be read. A turn that was cut off earlier no longer goes on.
+         */
+        async stop() {
+            stopped = true;
+            const loops = [...threads.values()].map(({ loop }) => loop);
+            await Promise.all(loops.map((loop) => loop.cancel()));
+            // A message being recorded as this was asked is recorded first, and a call still running ends.
+            await Promise.all(starting);
+            await Promise.all(loops.map((loop) => loop.drained()));
+            // What was cut off earlier and hasn't gone on doesn't after a stop either: its marks go.
+            await resume().catch((error) => log.warn("The turns that were cut off couldn't be looked for.", { error: String(error) }));
+        },
+        /** Take messages again. The turns `stop` cut stay cut. */
+        start() {
+            stopped = false;
+        },
+        resume,
+        /**
+         * Close for good: every turn is cut, and none starts after. Each stays marked, for `resume`
+         * in whoever opens the store next.
+         */
+        async close() {
+            closed = true;
+            await Promise.all([...threads.values()].map(({ loop }) => loop.cancel()));
+        },
+        /** Settles when every thread's latest turn has written all it will. */
+        async settled() {
+            await Promise.all([...threads.values()].map(({ loop }) => loop.settled()));
+            await Promise.all([...threads.values()].map(({ writes }) => writes));
+        },
+        /** Text the model writes while it answers `requestId`, for the reply it becomes. */
+        delta(requestId, text) {
+            for (const { loop } of threads.values())
+                loop.delta(requestId, text);
+        },
+    };
+}

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

@@ -0,0 +1,99 @@
+/**
+ * The record a loop runs on, kept in a store: one key per message, holding the items a model reads
+ * for it, and for a tool message the line a person sees. It is read once, then kept in memory, and
+ * the oldest messages are deleted past a retention cap.
+ */
+import { z } from "zod";
+import { Item, type Log, type Shown, type Store } from "./types.js";
+/** A message as the record keeps it. */
+export declare const Entry: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        tool: "tool";
+        user: "user";
+    }>;
+    text: z.ZodOptional<z.ZodString>;
+    at: z.ZodString;
+    items: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"message">;
+        role: z.ZodEnum<{
+            assistant: "assistant";
+            user: "user";
+        }>;
+        content: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"function_call">;
+        callId: z.ZodString;
+        name: z.ZodString;
+        arguments: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"function_call_output">;
+        callId: z.ZodString;
+        output: z.ZodString;
+    }, z.core.$strip>], "type">>;
+    state: z.ZodOptional<z.ZodEnum<{
+        done: "done";
+        refused: "refused";
+    }>>;
+    joined: z.ZodOptional<z.ZodLiteral<true>>;
+    ahead: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type Entry = z.output<typeof Entry>;
+/** Where a record's messages are kept in its store. */
+export declare const MESSAGES = "msg/";
+/** What the model is sent of the past: the newest exchanges up to this many bytes of JSON. */
+export declare const INPUT_BUDGET = 400000;
+/** At most this many messages are kept, in at most this many bytes, oldest deleted first. */
+export declare const KEEP = 2000;
+export declare const KEEP_BYTES: number;
+/** The first `length` UTF-16 units of `text`, never ending inside a surrogate pair. */
+export declare function head(text: string, length: number): string;
+/** `text`, cut so its JSON fits `max` bytes, saying so when it is cut. */
+export declare function fitted(text: string, max: number): string;
+/** What the person sees of a message. */
+export declare const textOf: (entry: Entry) => string;
+/** A call's arguments as they are kept and shown: past their cap, a note in their place. */
+export declare const argumentsOf: (args: string) => string;
+/**
+ * A message as it is shown. A tool message whose call ran carries `tool`: the call's name, how it
+ * ended, its arguments and its output.
+ */
+export declare function messageOf(entry: Entry): Shown;
+/** Stored values read at once when what is kept is first loaded. */
+export declare const READS = 16;
+export declare function createRecord(store: Store, log: Log, limits?: {
+    keep: number;
+    keepBytes: number;
+}): {
+    /**
+     * Keep a message, under `id` or its own number, and delete the oldest past the cap. A tool
+     * message the store refuses is still kept in memory, since its call has run. `read` is given
+     * for what came of a model request that had read the record up to that number: when a user
+     * message was said since, it is kept as `ahead` of it.
+     */
+    append(entry: Omit<Entry, "id" | "at">, id?: string, read?: number): Promise<Entry>;
+    /** Whether nothing is kept. */
+    empty(): Promise<boolean>;
+    /** Messages before `before`, oldest first, as many as fit `limit` and `PAGE_BUDGET`. */
+    page(before: string | undefined, limit: number): Promise<{
+        messages: Shown[];
+        more: boolean;
+    }>;
+    /**
+     * The conversation to send: the newest exchanges (each from the user message that starts a turn
+     * 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
+     * whatever is `ahead` of it, so the model reads it as not yet answered. `read` is the number
+     * up to which every user message was read, for `append` and `saidAfter`: one still being
+     * written is not read yet.
+     */
+    input(): Promise<{
+        items: Item[];
+        read: number;
+    }>;
+    /** Whether a user message has been stored after the one numbered `read`, which `input` gave. */
+    saidAfter(read: number): Promise<boolean>;
+};
+export type LoopRecord = ReturnType<typeof createRecord>;

package/dist/node_modules/{assistant/dist/src/history.js → @agentorg/looper/dist/src/record.js}

@@ -1,11 +1,12 @@
 /**
- * The assistant's record of its chat, kept in its `store` slot: one key per message, holding the
- * Responses items it stands for, and for a tool message the line the person sees. It is read once,
- * then kept in memory, and the oldest messages are deleted past a retention cap.
+ * The record a loop runs on, kept in a store: one key per message, holding the items a model reads
+ * for it, and for a tool message the line a person sees. It is read once, then kept in memory, and
+ * the oldest messages are deleted past a retention cap.
  */
-import { Item } from "@agentorg/interfaces";
 import { z } from "zod";
-const Entry = z.object({
+import { Item } from "./types.js";
+/** A message as the record keeps it. */
+export const Entry = z.object({
     id: z.string(),
     role: z.enum(["user", "assistant", "tool"]),
     /** What the person sees, for a tool message; the others show their message items. */
@@ -14,9 +15,21 @@ const Entry = z.object({
     items: z.array(Item),
     /** For a tool message whose call ran: how it ended. */
     state: z.enum(["done", "refused"]).optional(),
+    /** For a user message said while a turn was running: it is part of that turn. */
+    joined: z.literal(true).optional(),
+    /**
+     * For what came of a model request that had read the record up to the message of this number,
+     * when a user message was said after that: the model reads it ahead of that message, which it
+     * doesn't answer.
+     */
+    ahead: z.number().optional(),
 });
-const PREFIX = "msg/";
-const keyOf = (seq) => `${PREFIX}${String(seq).padStart(12, "0")}`;
+/** Where a record's messages are kept in its store. */
+export const MESSAGES = "msg/";
+const keyOf = (seq) => `${MESSAGES}${String(seq).padStart(12, "0")}`;
+const seqOf = (key) => Number(key.slice(MESSAGES.length)) || 0;
+// The record's limits are fixed here for now, sized for a host that carries a model request, or a
+// page of messages, in one piece of about a megabyte.
 /** What the model is sent of the past: the newest exchanges up to this many bytes of JSON. */
 export const INPUT_BUDGET = 400_000;
 /** At most this many messages are kept, in at most this many bytes, oldest deleted first. */
@@ -25,7 +38,7 @@ export const KEEP_BYTES = 16 * 1024 * 1024;
 /** A stored message's text, and a call's arguments, are cut to fit these, in bytes of JSON. */
 const MAX_TEXT = 192 * 1024;
 const MAX_ARGUMENTS = 16 * 1024;
-/** A history page stays well inside one frame. */
+/** A page of messages stays under this, so whatever carries it can do so in one piece. */
 const PAGE_BUDGET = 512 * 1024;
 const encoder = new TextEncoder();
 const size = (value) => encoder.encode(JSON.stringify(value)).byteLength;
@@ -43,7 +56,7 @@ export function fitted(text, max) {
         kept = `${head(kept, Math.floor((kept.length * max) / bytes) - 16)}… (cut)`;
     return kept;
 }
-/** A chat message shows at most this much; the record keeps all of it. */
+/** A message shows at most this much; the record keeps all of it. */
 const MAX_SHOWN = 100_000;
 /** What the person sees of a message. */
 export const textOf = (entry) => head(entry.text ??
@@ -51,8 +64,8 @@ export const textOf = (entry) => head(entry.text ??
 /** A call's arguments as they are kept and shown: past their cap, a note in their place. */
 export const argumentsOf = (args) => size(args) > MAX_ARGUMENTS ? ARGUMENTS_LEFT_OUT : args;
 /**
- * A message as the chat shows it. A tool message whose call ran carries `tool`: the call's name,
- * how it ended, its arguments and its output.
+ * A message as it is shown. A tool message whose call ran carries `tool`: the call's name, how it
+ * ended, its arguments and its output.
  */
 export function messageOf(entry) {
     const message = { id: entry.id, role: entry.role, text: textOf(entry), at: entry.at };
@@ -81,9 +94,11 @@ const kept = (entry) => ({
         return { ...item, arguments: argumentsOf(item.arguments) };
     }),
 });
-/** Stored messages read at once when the record is first loaded. */
-const READS = 16;
-export function createHistory(store, log, limits = { keep: KEEP, keepBytes: KEEP_BYTES }) {
+/** Stored values read at once when what is kept is first loaded. */
+export const READS = 16;
+/** Whether a user message follows the one numbered `read`: one `stored` already, when asked so. */
+const saidAfter = (records, read, stored = false) => records.some((record) => record.entry.role === "user" && seqOf(record.key) > read && !(stored && record.writing));
+export function createRecord(store, log, limits = { keep: KEEP, keepBytes: KEEP_BYTES }) {
     let loaded;
     const load = () => {
         if (loaded)
@@ -94,14 +109,18 @@ export function createHistory(store, log, limits = { keep: KEEP, keepBytes: KEEP
             let bytes = 0;
             let after;
             do {
-                const page = await store.list({ prefix: PREFIX, limit: 1000, ...(after ? { after } : {}) });
+                const page = await store.list({
+                    prefix: MESSAGES,
+                    limit: 1000,
+                    ...(after ? { after } : {}),
+                });
                 // A few at a time, in order: a long record shouldn't hold up the first send one read at
-                // a time, nor flood the Hub.
+                // a time, nor flood its store.
                 for (let at = 0; at < page.keys.length; at += READS) {
                     const keys = page.keys.slice(at, at + READS);
                     const values = await Promise.all(keys.map((key) => store.get({ key })));
                     keys.forEach((key, i) => {
-                        last = Math.max(last, Number(key.slice(PREFIX.length)) || 0);
+                        last = Math.max(last, seqOf(key));
                         const parsed = Entry.safeParse(values[i]?.value);
                         if (!parsed.success) {
                             log.warn("A stored message didn't read back; it is left out.", { key });
@@ -126,21 +145,30 @@ export function createHistory(store, log, limits = { keep: KEEP, keepBytes: KEEP
     return {
         /**
          * Keep a message, under `id` or its own number, and delete the oldest past the cap. A tool
-         * message the store refuses is still kept in memory, since its call has run.
+         * message the store refuses is still kept in memory, since its call has run. `read` is given
+         * for what came of a model request that had read the record up to that number: when a user
+         * message was said since, it is kept as `ahead` of it.
          */
-        async append(entry, id) {
+        async append(entry, id, read) {
             const state = await load();
             const key = keyOf(++state.last);
             const record = {
                 key,
-                entry: kept({ id: id ?? key.slice(PREFIX.length), at: new Date().toISOString(), ...entry }),
+                entry: kept({
+                    id: id ?? key.slice(MESSAGES.length),
+                    at: new Date().toISOString(),
+                    ...entry,
+                    ...(read !== undefined && saidAfter(state.records, read) ? { ahead: read } : {}),
+                }),
                 bytes: 0,
+                writing: entry.role === "user",
             };
             record.bytes = size(record.entry);
             state.records.push(record);
             state.bytes += record.bytes;
             try {
                 await store.set({ key, value: record.entry });
+                record.writing = false;
             }
             catch (error) {
                 if (entry.role !== "tool") {
@@ -163,25 +191,11 @@ export function createHistory(store, log, limits = { keep: KEEP, keepBytes: KEEP
             }
             return record.entry;
         },
-        /** Forget everything after the message `id`: a retry takes the place of what followed it. */
-        async dropAfter(id) {
-            const state = await load();
-            const at = state.records.findLastIndex((record) => record.entry.id === id);
-            if (at === -1)
-                return;
-            for (const gone of state.records.splice(at + 1)) {
-                state.bytes -= gone.bytes;
-                await store.delete({ key: gone.key }).catch((error) => log.warn("A replaced message couldn't be deleted.", {
-                    key: gone.key,
-                    error: String(error),
-                }));
-            }
-        },
-        /** The person's last message, if any. */
-        async lastUser() {
-            return (await load()).records.findLast((record) => record.entry.role === "user")?.entry;
+        /** Whether nothing is kept. */
+        async empty() {
+            return (await load()).records.length === 0;
         },
-        /** Messages before `before`, oldest first, as many as fit `limit` and one frame. */
+        /** Messages before `before`, oldest first, as many as fit `limit` and `PAGE_BUDGET`. */
         async page(before, limit) {
             const { records } = await load();
             const end = before === undefined
@@ -202,20 +216,45 @@ export function createHistory(store, log, limits = { keep: KEEP, keepBytes: KEEP
             return { messages, more: start > 0 };
         },
         /**
-         * The conversation to send: the newest whole exchanges (each from a user message on) that fit
-         * the budget, and always the latest one. A latest one that alone is over the budget has its
-         * oldest function arguments and outputs left out, each call still paired with an output.
+         * The conversation to send: the newest exchanges (each from the user message that starts a turn
+         * 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
+         * whatever is `ahead` of it, so the model reads it as not yet answered. `read` is the number
+         * up to which every user message was read, for `append` and `saidAfter`: one still being
+         * written is not read yet.
          */
         async input() {
-            const { records } = await load();
+            const { records, last } = await load();
+            const unwritten = records.find((record) => record.writing);
+            const read = unwritten ? seqOf(unwritten.key) - 1 : last;
             const exchanges = [];
-            for (const { entry } of records) {
-                if (entry.role === "user" || exchanges.length === 0)
+            /** Said during a turn, and not yet put: what is ahead of them goes first. */
+            const late = [];
+            const put = (entry) => {
+                if ((entry.role === "user" && !entry.joined) || exchanges.length === 0)
                     exchanges.push([]);
                 exchanges.at(-1)?.push(...entry.items);
+            };
+            /** Put the late messages numbered up to `read`. */
+            const putLate = (read) => {
+                while (late[0] && seqOf(late[0].key) <= read)
+                    put(late.shift().entry);
+            };
+            for (const record of records) {
+                // Nothing to send: a user message still being written, or a line with no items.
+                if (record.writing || record.entry.items.length === 0)
+                    continue;
+                if (record.entry.joined) {
+                    late.push(record);
+                    continue;
+                }
+                putLate(record.entry.ahead ?? last);
+                put(record.entry);
             }
+            putLate(last);
             let total = exchanges.reduce((sum, items) => sum + size(items), 0);
-            while (exchanges.length > 1 && total > INPUT_BUDGET)
+            while (exchanges.length > 2 && total > INPUT_BUDGET)
                 total -= size(exchanges.shift());
             const items = exchanges.flat();
             for (let i = 0; i < items.length && total > INPUT_BUDGET; i++) {
@@ -229,7 +268,11 @@ export function createHistory(store, log, limits = { keep: KEEP, keepBytes: KEEP
                     items[i] = { ...item, arguments: ARGUMENTS_LEFT_OUT };
                 }
             }
-            return items;
+            return { items, read };
+        },
+        /** Whether a user message has been stored after the one numbered `read`, which `input` gave. */
+        async saidAfter(read) {
+            return saidAfter((await load()).records, read, true);
         },
     };
 }

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

@@ -0,0 +1,11 @@
+/** Running the functions a model calls, and what is kept of their output. */
+import { type Outcome, type Tool } from "./types.js";
+/** A function's output keeps this many characters, so one result can't fill a request. */
+export declare const MAX_OUTPUT = 30000;
+/**
+ * `text`, or its first and last `MAX_OUTPUT / 2` characters with what was cut between them: a
+ * failing command's error is at the end, and what it was doing at the start.
+ */
+export declare function capped(text: string): string;
+/** Run a function call: the result, or the refusal, as the function's output. */
+export declare function runTool(tools: Tool[], name: string, args: string): Promise<Outcome>;