@agentorg/cli 0.0.6 → 0.0.8

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

@@ -0,0 +1,574 @@
+/**
+ * The looper: the loops of whoever hosts it. Messages come in on threads, which are names its host
+ * gives; a thread's messages are kept under `thread/<name>/` in the store. What answers them is a
+ * piece of work, with a loop of its own.
+ *
+ * Intake is code. A message in a thread that a piece of work follows is given to that work. One in
+ * a thread nothing follows is kept, and the main loop says whose it is: new work, which has the
+ * thread's name as its id, or work in a turn now, which then follows that thread too. The main
+ * loop makes one decision at a time, and one for a thread on all that waits in it. A piece of
+ * work answers in the thread of the newest message it has read.
+ *
+ * Turns run side by side, each in a place; the main loop takes none. There are `PLACES` of them,
+ * and one more that only work already begun (it has done something) may take, so new work never
+ * keeps a message from work that is under way. A turn that finds no place waits for one, in the
+ * order it came. While begun work keeps five turns running, new work goes on waiting. `WAITING`
+ * turns may wait; past that a message that would start a turn is refused `busy`.
+ *
+ * A piece of work is marked in the store while a turn of it hasn't ended, and a thread while
+ * messages wait in it. A looper that closes under either, or goes without closing, leaves the
+ * mark, and `resume` on the same store goes on with it, once. A turn that ends, fails or is
+ * stopped leaves no mark; messages the main loop couldn't place, or was stopped over, wait for
+ * their thread's next message, and all of them are put to the main loop together.
+ */
+import { createLoop } from "./loop.js";
+import { createMain, titled } from "./main.js";
+import { createRecord, createThread, messageOf, READS, textOf, userEntry, } from "./record.js";
+import { codeOf, Refusal, } from "./types.js";
+/** The turns that run at once, not counting the one more for work 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 piece of work is marked while a turn of it hasn't ended. */
+const UNFINISHED = "unfinished/";
+/**
+ * Where a thread is marked while messages wait in it for a piece of work to take them: `true`
+ * while that is still to happen, so the next start goes on with it, and `false` once it couldn't
+ * or was stopped, when the thread's next message does.
+ */
+const UNROUTED = "unrouted/";
+/** Where a piece of work's title and the threads it follows are kept. */
+const WORKS = "work/";
+const running = (status) => status.state === "thinking" || status.state === "tool";
+/** 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;
+    /** The pieces of work that have a loop here, by id. */
+    const works = new Map();
+    const threads = new Map();
+    /** A thread's messages, read when first asked for. */
+    const threadOf = (name) => {
+        const found = threads.get(name) ?? createThread(under(store, recordOf(name)), log);
+        threads.set(name, found);
+        return found;
+    };
+    /** What is kept of each piece of work the main loop placed, and the work each thread has. */
+    const kept = new Map();
+    const followed = new Map();
+    /** The threads that are marked: messages wait in them. */
+    const unrouted = new Set();
+    const markOf = (thread) => UNROUTED + encodeURIComponent(thread);
+    /** Keep a thread's mark: `again` is whether the next start goes on with what waits there. */
+    const wait = (thread, again) => store.set({ key: markOf(thread), value: again });
+    /** Take a thread's mark off: nothing waits there. */
+    const settle = async (thread) => {
+        unrouted.delete(thread);
+        await store
+            .delete({ key: markOf(thread) })
+            .catch((error) => log.warn("A thread's mark couldn't be taken off.", { thread, error: String(error) }));
+    };
+    /** The threads being decided or given now; each settles when that has ended. */
+    const routes = 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;
+    /** Counts the stops and the close: what was asked before one starts nothing after it. */
+    let cuts = 0;
+    /** Refuse a turn that can't start now, or was asked for before a stop, whatever its thread. */
+    const mayStart = (at = cuts) => {
+        if (closed)
+            throw new Refusal("unavailable", "This agent is closing.");
+        if (stopped || at !== cuts)
+            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;
+    };
+    /** Whether anything is at work, as it was last said. */
+    let working = false;
+    const tally = () => {
+        const now = routes.size > 0 || [...works.values()].some(({ loop }) => running(loop.state()));
+        if (now === working)
+            return;
+        working = now;
+        out.working(now);
+    };
+    /** 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;
+    };
+    /** What the store holds of the work the main loop placed, and of what waits: read once. */
+    let learned;
+    const keysUnder = async (prefix) => {
+        const keys = [];
+        let after;
+        do {
+            const page = await store.list({ prefix, ...(after ? { after } : {}) });
+            keys.push(...page.keys);
+            after = page.next ?? undefined;
+        } while (after);
+        return keys;
+    };
+    const learn = () => {
+        if (learned)
+            return learned;
+        const attempt = (async () => {
+            const keys = await keysUnder(WORKS);
+            for (let at = 0; at < keys.length; at += READS) {
+                const some = keys.slice(at, at + READS);
+                const values = await Promise.all(some.map((key) => store.get({ key })));
+                some.forEach((key, i) => {
+                    const value = values[i]?.value;
+                    const follows = Array.isArray(value?.follows)
+                        ? value.follows.filter((name) => typeof name === "string")
+                        : [];
+                    if (follows.length === 0) {
+                        log.warn("A piece of work's record didn't read back; it is left out.", { key });
+                        return;
+                    }
+                    const id = decodeURIComponent(key.slice(WORKS.length));
+                    kept.set(id, { title: typeof value?.title === "string" ? value.title : "", follows });
+                    for (const name of follows)
+                        followed.set(name, id);
+                });
+            }
+            for (const key of await keysUnder(UNROUTED))
+                unrouted.add(decodeURIComponent(key.slice(UNROUTED.length)));
+        })();
+        learned = attempt;
+        attempt.catch(() => {
+            if (learned === attempt)
+                learned = undefined;
+        });
+        return attempt;
+    };
+    /**
+     * The work a thread is followed by, if any: the one the main loop gave it, or its own when it
+     * holds messages and none of them waits.
+     */
+    const workOf = async (thread) => {
+        await learn();
+        const work = followed.get(thread);
+        if (work !== undefined)
+            return work;
+        if (unrouted.has(thread))
+            return undefined;
+        return (await threadOf(thread).load()).records.length > 0 ? thread : undefined;
+    };
+    const open = (id) => {
+        const record = createRecord({
+            id,
+            follows: () => kept.get(id)?.follows ?? [id],
+            thread: threadOf,
+        });
+        const key = UNFINISHED + encodeURIComponent(id);
+        const held = {
+            record,
+            /** 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 work's mark couldn't be written.", { work: id, error: String(error) }));
+            },
+            loop: createLoop({
+                request: options.request,
+                model: options.model,
+                enter,
+                record,
+                out: {
+                    message: out.message,
+                    delta: out.delta,
+                    failed: out.failed,
+                    status(status) {
+                        const on = running(status);
+                        // 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 (on && !held.marked)
+                            held.mark(!held.loop.resumed());
+                        else if (!on && held.marked && !closed)
+                            held.mark(false);
+                        held.marked = on;
+                        tally();
+                    },
+                },
+                log,
+            }),
+        };
+        return held;
+    };
+    const of = (id) => {
+        const found = works.get(id) ?? open(id);
+        works.set(id, found);
+        return found;
+    };
+    /** A work's title: the main loop's, or its opening line for work begun before it had one. */
+    const titleOf = async (id) => kept.get(id)?.title || titled(await of(id).record.opening());
+    /** Ask something of a piece of work's loop. */
+    const using = (id, ask) => started(ask(of(id).loop));
+    /** Work given something as the looper closed, its turn cut before it began: marked like one. */
+    const leftAtClose = (id) => {
+        const work = works.get(id);
+        if (closed && work && !work.marked)
+            work.mark(true);
+    };
+    /**
+     * What is asked of a thread whose work has to be found, or is being given it, taken one at a
+     * time in the order it was asked; and how much is still to be taken.
+     */
+    const lines = new Map();
+    const inLine = (thread, take) => {
+        const line = lines.get(thread) ?? { last: Promise.resolve(), waiting: 0 };
+        lines.set(thread, line);
+        line.waiting++;
+        const taken = line.last.then(take).finally(() => void line.waiting--);
+        line.last = taken.catch(() => { });
+        return taken;
+    };
+    const main = createMain({
+        model: options.model,
+        chosen: async () => (await options.request()).model,
+        log,
+    });
+    /**
+     * Have the main loop say whose the messages waiting in a thread are, and keep what it says:
+     * new work of the thread's own, or work in a turn now, which then follows the thread too.
+     * Nothing is decided, and it says so with none, once `cut` says the looper stopped or closed.
+     */
+    const decide = async (thread, cut) => {
+        // Read in the thread's line: a message being kept there now is kept first.
+        const texts = await inLine(thread, async () => {
+            const { records } = await threadOf(thread).load();
+            const said = records.flatMap(({ entry }) => (entry.role === "user" ? [textOf(entry)] : []));
+            // Marked before a message that was never kept: nothing waits.
+            if (said.length === 0)
+                await settle(thread);
+            return said;
+        });
+        if (texts.length === 0)
+            return undefined;
+        const underway = await Promise.all([...works]
+            .filter(([, { loop }]) => running(loop.state()))
+            .map(async ([id]) => ({ id, title: await titleOf(id) })));
+        if (cut())
+            return undefined;
+        const routed = await main.route(texts, underway);
+        if (!routed || cut())
+            return undefined;
+        const work = "work" in routed ? routed.work : thread;
+        const record = {
+            title: "work" in routed ? await titleOf(work) : routed.title,
+            follows: [...new Set([...(kept.get(work)?.follows ?? [work]), thread])],
+        };
+        // Kept before the messages are taken, so a start in between finds whose they are.
+        await store.set({ key: WORKS + encodeURIComponent(work), value: record });
+        kept.set(work, record);
+        followed.set(thread, work);
+        return work;
+    };
+    /** Decisions are made one at a time, each to its end, so each knows what the last began. */
+    let decided = Promise.resolve();
+    /** The threads a message was kept in while they were being decided or given. */
+    const again = new Set();
+    /**
+     * Give the messages waiting in a thread to a piece of work: the one it has, or the one the main
+     * loop says. One at a time for a thread, on all that waits in it; what is said there meanwhile
+     * goes with them, or is asked about when that has ended without taking it. Once the looper has
+     * stopped or closed since this was asked, nothing starts, and what waits goes on waiting.
+     */
+    const route = (thread) => {
+        if (stopped || closed)
+            return;
+        if (routes.has(thread))
+            return void again.add(thread);
+        const at = cuts;
+        const cut = () => at !== cuts;
+        const routing = decided
+            .then(async () => {
+            if (cut())
+                return;
+            const work = followed.get(thread) ?? (await decide(thread, cut));
+            if (work === undefined)
+                return;
+            // In the thread's line: a message being kept there now is kept first, and goes with them.
+            await inLine(thread, async () => {
+                if (cut())
+                    return;
+                if (!(await using(work, (loop) => loop.adopt(thread)))) {
+                    // Its work was told to stop first: they wait for the thread's next message.
+                    if (!cut())
+                        await wait(thread, false);
+                    return;
+                }
+                leftAtClose(work);
+                await settle(thread);
+            });
+        })
+            .catch(async (error) => {
+            if (closed)
+                return;
+            log.error("A message got no answer.", { thread, error: String(error) });
+            out.failed(thread, codeOf(error));
+            // Still waiting: for the thread's next message, not for the next start.
+            if (unrouted.has(thread))
+                await wait(thread, false).catch(() => { });
+        })
+            .finally(() => {
+            routes.delete(thread);
+            // Not once it has stopped or closed since: then what waits goes on waiting.
+            if (again.delete(thread) && !cut() && unrouted.has(thread))
+                route(thread);
+            tally();
+        });
+        decided = routing;
+        routes.set(thread, routing);
+        tally();
+    };
+    /** Keep a message in a thread nothing follows, and have it routed, unless a stop came since `at`. */
+    const intake = async (thread, text, at) => {
+        const waited = unrouted.has(thread);
+        unrouted.add(thread);
+        const entry = await (async () => {
+            await wait(thread, true);
+            const into = threadOf(thread);
+            const { record, stored } = into.push(await into.load(), userEntry(text));
+            await stored;
+            return record.entry;
+        })().catch(async (error) => {
+            // Not kept: nothing of it waits, unless an earlier message of the thread does.
+            if (!waited)
+                await settle(thread);
+            throw error;
+        });
+        out.message(thread, messageOf(entry));
+        // Stopped or closed while it was kept, it waits: for the next message, or the next start.
+        if (at === cuts)
+            route(thread);
+        return { messageId: entry.id };
+    };
+    /** Give a message to the work its thread is followed by. */
+    const give = async (work, thread, text) => {
+        const sent = await using(work, (loop) => loop.send(text, thread));
+        leftAtClose(work);
+        // What waited there, its work decided but not begun, went with it.
+        if (unrouted.has(thread) && !routes.has(thread))
+            await settle(thread);
+        return sent;
+    };
+    /**
+     * Go on with what was cut off when this store was last used, by a looper closing under it or
+     * going without closing: each turn that hadn't ended, once, waiting for a place like any turn;
+     * and each thread whose messages were still to be given to a piece of work, once too. A turn
+     * that can't go on now keeps its mark for the next time. A stopped looper goes on with none:
+     * its turns' marks go, and its waiting messages wait for their thread's next. Whoever hosts the
+     * looper calls this when a request can be made; once the marks have been read, a later call
+     * does nothing. `drop` goes on with nothing, as a stopped looper does.
+     */
+    const goOn = async (drop) => {
+        const at = cuts;
+        /** Whether anything may still go on: not once it has stopped or closed since this began. */
+        const going = () => !drop && !stopped && at === cuts;
+        await learn();
+        const keys = await keysUnder(UNFINISHED);
+        for (const key of keys) {
+            // Closed meanwhile: what is left stays marked, for whoever opens the store next.
+            if (closed)
+                return;
+            const id = decodeURIComponent(key.slice(UNFINISHED.length));
+            const held = of(id);
+            try {
+                if (going())
+                    await using(id, (loop) => loop.resume());
+                // Work 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) });
+            }
+        }
+        for (const thread of [...unrouted]) {
+            // Closed meanwhile: what waits keeps its mark, for whoever opens the store next.
+            if (closed)
+                return;
+            try {
+                // In the thread's line, so its mark is read and written apart from a message kept there.
+                await inLine(thread, async () => {
+                    if (routes.has(thread) || !unrouted.has(thread))
+                        return;
+                    // Only what was still to go on, and once: whatever comes of it, the next start doesn't.
+                    if ((await store.get({ key: markOf(thread) })).value !== true || closed)
+                        return;
+                    if (going())
+                        route(thread);
+                    await wait(thread, false);
+                });
+            }
+            catch (error) {
+                log.warn("A message that was waiting wasn't placed.", { thread, error: String(error) });
+            }
+        }
+    };
+    /** What was cut off is looked for once; a look that couldn't read the store is made again. */
+    let looked;
+    const resume = (drop = false) => {
+        if (closed)
+            return Promise.resolve();
+        if (!looked) {
+            const look = goOn(drop);
+            looked = look;
+            look.catch(() => {
+                if (looked === look)
+                    looked = undefined;
+            });
+        }
+        return looked;
+    };
+    return {
+        /**
+         * Say a message in a thread. It is recorded and said at once. In a thread a piece of work
+         * follows it is that work's: with no turn of it running it starts one, which waits for a place
+         * if none is free, and a turn running or waiting takes it at its next model request. In a
+         * thread nothing follows, the main loop says whose it is first. 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.
+         */
+        send(thread, text) {
+            try {
+                mayStart();
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            const at = cuts;
+            // Work known here is asked at once, so a stop that comes after this cuts it too.
+            const known = followed.get(thread) ?? (!unrouted.has(thread) && works.has(thread) ? thread : undefined);
+            if (known !== undefined && !lines.get(thread)?.waiting)
+                return give(known, thread, text);
+            return started(inLine(thread, async () => {
+                const work = await workOf(thread);
+                // Stopped or closed while its work was found: nothing of it is kept.
+                mayStart(at);
+                return work === undefined ? intake(thread, text, at) : give(work, thread, text);
+            }));
+        },
+        /** Stop a piece of work's turn now. A call already running finishes, and its result is kept. */
+        cancel: async (work) => works.get(work)?.loop.cancel(),
+        /** What a piece of work's loop is doing. */
+        state: (work) => works.get(work)?.loop.state() ?? { state: "idle" },
+        /** A thread's messages before `before`, oldest first, as many as fit `limit`. */
+        page: (thread, before, limit) => threadOf(thread).page(before, limit),
+        /**
+         * Stop: every turn is cut, running or waiting, the main loop is cut too, and nothing 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. What was cut off earlier no longer
+         * goes on, and messages waiting for a piece of work wait for their thread's next.
+         */
+        async stop() {
+            stopped = true;
+            cuts++;
+            const loops = [...works.values()].map(({ loop }) => loop);
+            await Promise.all([...loops.map((loop) => loop.cancel()), main.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(routes.values());
+            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.
+            // Nor does the next start go on with what waits: a thread's next message does.
+            await resume(true)
+                .then(() => Promise.all([...unrouted].map((thread) => wait(thread, false))))
+                .catch((error) => log.warn("What was cut off couldn't be looked for.", { error: String(error) }));
+        },
+        /** Take messages again. The turns `stop` cut stay cut. */
+        start() {
+            stopped = false;
+        },
+        resume: () => resume(),
+        /**
+         * Close for good: every turn is cut, and none starts after. Each stays marked, as does each
+         * thread where messages wait, for `resume` in whoever opens the store next.
+         */
+        async close() {
+            closed = true;
+            cuts++;
+            await Promise.all([...[...works.values()].map(({ loop }) => loop.cancel()), main.cancel()]);
+        },
+        /** Settles when every piece of work's latest turn has written all it will. */
+        async settled() {
+            await Promise.all(routes.values());
+            await Promise.all([...works.values()].map(({ loop }) => loop.settled()));
+            await Promise.all([...works.values()].map(({ writes }) => writes));
+        },
+        /** Text the model writes while it answers `requestId`, for the reply it becomes. */
+        delta(requestId, text) {
+            for (const { loop } of works.values())
+                loop.delta(requestId, text);
+        },
+    };
+}

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

@@ -0,0 +1,34 @@
+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.";
+/** 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 {
+    id: string;
+    title: string;
+}
+/** 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;
+export declare function createMain(options: {
+    model: Model;
+    /** Which model to ask, none meaning the model's own default. */
+    chosen(): Promise<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.
+     */
+    route(texts: string[], underway: Underway[]): Promise<Routed | undefined>;
+    /** Drop the decision being made: its request is cancelled, and it says nothing. */
+    cancel(): Promise<void>;
+};