@agentorg/cli 0.0.7 → 0.0.9

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

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

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

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

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

@@ -1,7 +1,9 @@
 /**
- * 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.
+ * What a loop runs on, kept in a store. A thread keeps its messages, one key each: the items a
+ * model reads for it, and for a tool message the line a person sees. A thread is read once, then
+ * kept in memory, and its oldest messages are deleted past a retention cap. A piece of work reads
+ * its context from the threads it follows: each message is kept once, in the thread where it is
+ * shown, and says which work it belongs to when that isn't its thread's own.
  */
 import { z } from "zod";
 import { Item, type Log, type Shown, type Store } from "./types.js";
@@ -38,6 +40,9 @@ export declare const Entry: z.ZodObject<{
     }>>;
     joined: z.ZodOptional<z.ZodLiteral<true>>;
     ahead: z.ZodOptional<z.ZodNumber>;
+    work: z.ZodOptional<z.ZodString>;
+    main: z.ZodOptional<z.ZodNumber>;
+    place: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type Entry = z.output<typeof Entry>;
 /** Where a record's messages are kept in its store. */
@@ -62,38 +67,173 @@ export declare const argumentsOf: (args: string) => string;
 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?: {
+/** A user message as it is kept when said. */
+export declare const userEntry: (text: string) => {
+    role: "user";
+    items: {
+        type: "message";
+        role: "user";
+        content: string;
+    }[];
+};
+/** A message as a thread holds it. */
+interface Kept {
+    /** Its number in its thread. */
+    seq: number;
+    key: string;
+    entry: Entry;
+    bytes: number;
+    /** Set while a user message is being written, or taken: the model is sent it once stored. */
+    writing?: boolean;
+}
+interface Held {
+    records: Kept[];
+    last: number;
+    bytes: number;
+}
+/** A thread's messages in a store, by their numbers. */
+export declare function createThread(store: Store, log: Log, limits?: {
     keep: number;
     keepBytes: number;
 }): {
+    /** What it holds, read once. */
+    load: () => Promise<Held>;
+    push: (held: Held, entry: Omit<Entry, "id" | "at">, id?: string) => {
+        record: Kept;
+        stored: Promise<void>;
+    };
     /**
-     * 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.
+     * What was said in it, as a conversation: each message and each reply the main loop gave, in
+     * the order they were answered; and the number it holds up to.
      */
-    append(entry: Omit<Entry, "id" | "at">, id?: string, read?: number): Promise<Entry>;
-    /** Whether nothing is kept. */
-    empty(): Promise<boolean>;
+    said(): Promise<{
+        said: {
+            role: "user" | "assistant";
+            text: string;
+        }[];
+        upTo: number;
+    }>;
+    /**
+     * Keep, under `id`, a reply the main loop gave after it had read up to `upTo`. `late` says
+     * whether a message was said after that, which this reply doesn't answer.
+     */
+    answer(text: string, upTo: number, id: string): Promise<{
+        entry: {
+            id: string;
+            role: "assistant" | "tool" | "user";
+            text?: string | undefined;
+            at: string;
+            items: ({
+                type: "message";
+                role: "assistant" | "user";
+                content: string;
+            } | {
+                type: "function_call";
+                callId: string;
+                name: string;
+                arguments: string;
+            } | {
+                type: "function_call_output";
+                callId: string;
+                output: string;
+            })[];
+            state?: "done" | "refused" | undefined;
+            joined?: true | undefined;
+            ahead?: number | undefined;
+            work?: string | undefined;
+            main?: number | undefined;
+            place?: number | undefined;
+        };
+        late: boolean;
+    }>;
+    /**
+     * Hold a message as `entry` from now on, in memory: `store` writes it as it then is, and
+     * `undo` puts it back as it was.
+     */
+    change(held: Held, record: Kept, entry: Entry): {
+        store: () => Promise<unknown>;
+        undo: () => void;
+    };
     /** Messages before `before`, oldest first, as many as fit `limit` and `PAGE_BUDGET`. */
     page(before: string | undefined, limit: number): Promise<{
         messages: Shown[];
         more: boolean;
     }>;
+};
+export type Thread = ReturnType<typeof createThread>;
+/**
+ * A piece of work's record: its messages across the threads it follows, in the order it took them.
+ * Its id is the name of its own thread, whose messages are its unless they name another work; in
+ * any other thread, the messages that name it are. A message's place is where it stands in its
+ * own thread until the work follows a second thread, and a count kept with each message after. A
+ * message waiting in a thread it follows, said before the work had the thread, names no work yet:
+ * the work takes it, in the order it was said, before it keeps anything else there.
+ */
+export declare function createRecord(options: {
+    id: string;
+    /** The threads it follows now, its own first. */
+    follows(): string[];
+    thread(name: string): Thread;
+}): {
+    id: string;
+    /**
+     * Keep a message of its in `thread`, one of those it follows, after any waiting there. `read`
+     * is given for what came of a model request that had read it up to that place: when a user
+     * message was said since, or the turn was stopped by saying so, it is kept as `ahead` of
+     * that.
+     */
+    append: (entry: Omit<Entry, "id" | "at" | "work" | "place" | "ahead">, at: {
+        thread: string;
+        id?: string;
+        read?: number;
+    }) => Promise<{
+        entry: Entry;
+        thread: string;
+    }>;
+    /**
+     * Keep in `thread` what the main loop said as it stopped a turn of this work. It stands after
+     * all the thread holds, and like a message said in that turn, the work reads it after
+     * whatever the turn still writes.
+     */
+    stopLine: (text: string, thread: string) => Promise<{
+        entry: Entry;
+        thread: string;
+    }>;
+    /**
+     * Take the messages waiting in `thread`, which it has come to follow, as its own: `joined`,
+     * when a turn of its is running or a stopped one is still writing. It says how many there were to answer: in its own thread,
+     * where nothing needs taking, those said since it last did anything itself.
+     */
+    adopt(thread: string, joined: boolean): Promise<number>;
+    /**
+     * Whether it has had a turn that did something: it holds more than what was said to it and
+     * what the main loop said.
+     */
+    begun(): Promise<boolean>;
+    /** What it last said, if anything. */
+    last(): Promise<string | undefined>;
+    /** Whether it has no message. */
+    empty(): Promise<boolean>;
+    /** The thread it answers in now. */
+    where(): Promise<string>;
+    /** Its first user message, for a title. */
+    opening(): Promise<string>;
     /**
-     * The conversation to send: the newest exchanges (each from the user message that starts a turn
+     * The conversation to send: the newest exchanges (each from a user message that is not `joined`
      * on) that fit the budget, and always the latest two, so "go on" after a long turn still has
      * that turn. When those two are over the budget, their oldest function arguments and outputs
      * are left out, each call still paired with an output. A message said during a turn comes after
-     * 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.
+     * whatever is `ahead` of it, so the model reads it as not yet answered. `read` is the place up
+     * to which every user message was read, for `append` and `saidAfter`: one still being written
+     * is not read yet. `thread` is where what comes of it is kept.
      */
     input(): Promise<{
         items: Item[];
         read: number;
+        thread: string;
     }>;
-    /** Whether a user message has been stored after the one numbered `read`, which `input` gave. */
+    /** Whether a user message of its has been stored after the place `read`, which `input` gave. */
     saidAfter(read: number): Promise<boolean>;
 };
 export type LoopRecord = ReturnType<typeof createRecord>;
+export {};