@agentorg/cli 0.0.5 → 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/@agentorg/looper/dist/src/record.js

@@ -0,0 +1,278 @@
+/**
+ * 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 } 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. */
+    text: z.string().optional(),
+    at: z.string(),
+    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(),
+});
+/** 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. */
+export const KEEP = 2000;
+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 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;
+const LEFT_OUT = "(Left out: the conversation was too large to send it.)";
+const ARGUMENTS_LEFT_OUT = '{"left_out":"too large to keep"}';
+/** The first `length` UTF-16 units of `text`, never ending inside a surrogate pair. */
+export function head(text, length) {
+    const cut = text.slice(0, length);
+    return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut;
+}
+/** `text`, cut so its JSON fits `max` bytes, saying so when it is cut. */
+export function fitted(text, max) {
+    let kept = text;
+    for (let bytes = size(kept); bytes > max; bytes = size(kept))
+        kept = `${head(kept, Math.floor((kept.length * max) / bytes) - 16)}… (cut)`;
+    return kept;
+}
+/** 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 ??
+    entry.items.flatMap((item) => (item.type === "message" ? [item.content] : [])).join(""), MAX_SHOWN);
+/** 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 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 };
+    const call = entry.items.find((item) => item.type === "function_call");
+    if (entry.role !== "tool" || !entry.state || !call)
+        return message;
+    const output = entry.items.find((item) => item.type === "function_call_output");
+    return {
+        ...message,
+        tool: {
+            name: head(call.name, 128),
+            state: entry.state,
+            input: head(call.arguments, MAX_SHOWN),
+            ...(output ? { output: head(output.output, MAX_SHOWN) } : {}),
+        },
+    };
+}
+/** A message as it is stored: each text once, and nothing past its cap. */
+const kept = (entry) => ({
+    ...entry,
+    items: entry.items.map((item) => {
+        if (item.type === "message")
+            return { ...item, content: fitted(item.content, MAX_TEXT) };
+        if (item.type === "function_call_output")
+            return { ...item, output: fitted(item.output, MAX_TEXT) };
+        return { ...item, arguments: argumentsOf(item.arguments) };
+    }),
+});
+/** 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)
+            return loaded;
+        const attempt = (async () => {
+            const records = [];
+            let last = 0;
+            let bytes = 0;
+            let after;
+            do {
+                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 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, 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 });
+                            return;
+                        }
+                        const record = { key, entry: parsed.data, bytes: size(parsed.data) };
+                        records.push(record);
+                        bytes += record.bytes;
+                    });
+                }
+                after = page.next ?? undefined;
+            } while (after);
+            return { records, last, bytes };
+        })();
+        loaded = attempt;
+        attempt.catch(() => {
+            if (loaded === attempt)
+                loaded = undefined;
+        });
+        return attempt;
+    };
+    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. `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, read) {
+            const state = await load();
+            const key = keyOf(++state.last);
+            const record = {
+                key,
+                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") {
+                    state.records.splice(state.records.indexOf(record), 1);
+                    state.bytes -= record.bytes;
+                    throw error;
+                }
+                log.error("A tool message couldn't be stored; it is kept until a restart.", {
+                    error: String(error),
+                });
+            }
+            while (state.records.length > 1 &&
+                (state.records.length > limits.keep || state.bytes > limits.keepBytes)) {
+                const oldest = state.records.shift();
+                state.bytes -= oldest.bytes;
+                await store.delete({ key: oldest.key }).catch((error) => log.warn("An old message couldn't be deleted.", {
+                    key: oldest.key,
+                    error: String(error),
+                }));
+            }
+            return record.entry;
+        },
+        /** Whether nothing is kept. */
+        async empty() {
+            return (await load()).records.length === 0;
+        },
+        /** 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
+                ? records.length
+                : records.findIndex((record) => record.entry.id === before);
+            const messages = [];
+            let bytes = 0;
+            let start = Math.max(end, 0);
+            while (start > 0 && messages.length < limit) {
+                const { entry } = records[start - 1];
+                const message = messageOf(entry);
+                bytes += size(message);
+                if (bytes > PAGE_BUDGET && messages.length > 0)
+                    break;
+                messages.unshift(message);
+                start--;
+            }
+            return { messages, more: start > 0 };
+        },
+        /**
+         * 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, last } = await load();
+            const unwritten = records.find((record) => record.writing);
+            const read = unwritten ? seqOf(unwritten.key) - 1 : last;
+            const exchanges = [];
+            /** 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 > 2 && total > INPUT_BUDGET)
+                total -= size(exchanges.shift());
+            const items = exchanges.flat();
+            for (let i = 0; i < items.length && total > INPUT_BUDGET; i++) {
+                const item = items[i];
+                if (item.type === "function_call_output" && item.output !== LEFT_OUT) {
+                    total -= size(item.output) - size(LEFT_OUT);
+                    items[i] = { ...item, output: LEFT_OUT };
+                }
+                else if (item.type === "function_call" && item.arguments !== ARGUMENTS_LEFT_OUT) {
+                    total -= size(item.arguments) - size(ARGUMENTS_LEFT_OUT);
+                    items[i] = { ...item, arguments: ARGUMENTS_LEFT_OUT };
+                }
+            }
+            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>;