@agentorg/cli 0.0.7 → 0.0.9

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

@@ -2,9 +2,11 @@
  * A loop: a turn sends its record and the tools to the model, runs each function the model calls,
  * and sends the results back, until the model answers without calling anything, or the turn has
  * made its `MAX_CALLS` calls. A message said while a turn runs is recorded at once, and the turn
- * takes it at its next model request.
+ * takes it at its next model request. A loop is one piece of work's: its messages come in the
+ * threads the work follows, and what comes of a request is kept in the thread of the newest
+ * message that request read.
  */
-import { argumentsOf, head, messageOf } from "./record.js";
+import { argumentsOf, head, messageOf, userEntry } from "./record.js";
 import { capped, runTool } from "./tools.js";
 import { codeOf, Refusal, } from "./types.js";
 /** A brake on a turn, not a budget: nothing approves a call, and the person can stop it. */
@@ -17,14 +19,23 @@ const CUT_OFF = {
 export function createLoop(options) {
     const { model, record, out, log } = options;
     let turn;
-    /** A cancelled turn whose running call hasn't settled: the next turn waits for its records. */
+    /**
+     * A stopped turn that had begun to run and hasn't ended: it may still write the result of its
+     * running call, or the reply it was keeping. What is kept meanwhile is kept as joined, so the
+     * model reads it after that; and the next turn reads the record once it has ended.
+     */
     let draining;
+    /**
+     * That turn's place, the loop's while it still writes. A turn started meanwhile asks for none:
+     * when the stopped turn has ended, its place goes to that turn, or is given back.
+     */
+    let lingering;
     /** Settles when the latest turn's loop has ended. */
     let lastEnded;
     /** The latest status, for a view that asks. */
     let latest = { state: "idle" };
-    /** Set once a turn has started here: nothing that was cut off earlier is left to go on with. */
-    let began = false;
+    /** The starts made here. After the first, nothing cut off earlier is left to go on with. */
+    let turns = 0;
     /** Counts the cancels, so that what was asked before one can tell when it is taken after it. */
     let cancels = 0;
     /** What is being taken now: the next thing asked is taken after it. */
@@ -55,7 +66,11 @@ export function createLoop(options) {
             if (current.cancelled)
                 return;
             log.error("A turn failed.", { error: String(error) });
-            status(current, { state: "error", detail: codeOf(error) });
+            // Every thread it took a message in, and the one it was answering in, is told.
+            const detail = codeOf(error);
+            for (const thread of new Set([...current.took, current.thread ?? record.id]))
+                out.failed(thread, detail);
+            status(current, { state: "error", detail });
         })
             .finally(() => {
             current.place?.leave();
@@ -65,9 +80,9 @@ export function createLoop(options) {
             .catch((error) => log.error("A turn's status failed.", { error: String(error) }));
         lastEnded = current.ended;
     };
-    const show = (entry) => out.message(messageOf(entry));
+    const show = ({ entry, thread }) => out.message(thread, messageOf(entry));
     /** A call starting: shown as running, under the id its record will have when it ends. */
-    const running = (call, id) => out.message({
+    const running = (call, id, thread) => out.message(thread, {
         id,
         role: "tool",
         text: `${call.name}: running`,
@@ -78,7 +93,7 @@ export function createLoop(options) {
      * Record a function call with its output, keeping every call paired, as the API needs. Its end
      * is shown even if the record can't be written, so no call is left shown as running.
      */
-    const answered = async (call, result, id, read) => {
+    const answered = async (call, result, id, read, thread) => {
         const entry = {
             role: "tool",
             text: `${call.name}: ${result.ok ? "done" : result.code}`,
@@ -93,10 +108,10 @@ export function createLoop(options) {
             ],
         };
         try {
-            show(await record.append(entry, id, read));
+            show(await record.append(entry, { thread, id, read }));
         }
         catch (error) {
-            out.message(messageOf({
+            out.message(thread, messageOf({
                 ...entry,
                 id,
                 at: new Date().toISOString(),
@@ -109,19 +124,20 @@ export function createLoop(options) {
      * Note calls that won't run, in one message however many there are. They never ran, so the
      * record leaves them out: what the model is sent next holds only calls with their outputs.
      */
-    const skipped = async (calls, code) => {
+    const skipped = async (calls, code, thread) => {
         if (calls.length === 0)
             return;
         const text = calls.length === 1 ? `${calls[0]?.name}: ${code}` : `${calls.length} calls: ${code}`;
-        show(await record.append({ role: "tool", text, items: [] }));
+        show(await record.append({ role: "tool", text, items: [] }, { thread }));
     };
     async function run(current) {
         let calls = 0;
         for (;;) {
             const { instructions, tools, model: chosen } = await options.request();
-            const { items: input, read } = await record.input();
+            const { items: input, read, thread } = await record.input();
             if (current.cancelled)
                 return;
+            current.thread = thread;
             const requestId = crypto.randomUUID();
             const replyId = crypto.randomUUID();
             current.requestId = requestId;
@@ -147,7 +163,7 @@ export function createLoop(options) {
                 show(await record.append({
                     role: "assistant",
                     items: texts.map((content) => ({ type: "message", role: "assistant", content })),
-                }, replyId, read));
+                }, { thread, id: replyId, read }));
             if (called.length === 0) {
                 if (current.cancelled)
                     return;
@@ -174,7 +190,7 @@ export function createLoop(options) {
             for (const [i, call] of called.entries()) {
                 if (current.cancelled || calls >= MAX_CALLS) {
                     const rest = called.slice(i);
-                    await skipped(rest, current.cancelled ? "cancelled" : "limit");
+                    await skipped(rest, current.cancelled ? "cancelled" : "limit", thread);
                     break;
                 }
                 calls++;
@@ -182,9 +198,9 @@ export function createLoop(options) {
                 // A call that has started runs to its end, and its real result is kept: it may have
                 // taken effect.
                 const id = crypto.randomUUID();
-                running(call, id);
+                running(call, id, thread);
                 const result = await runTool(tools, call.name, call.arguments);
-                await answered(call, result, id, read);
+                await answered(call, result, id, read, thread);
             }
             if (current.cancelled)
                 return;
@@ -193,53 +209,56 @@ export function createLoop(options) {
             status(current, { state: "thinking" });
         }
     }
-    /** A turn from its place to its end: it waits for the place already shown as thinking. */
+    /**
+     * A turn from its place to its end: it waits for the place, and for what a stopped turn before
+     * it still writes, already shown as thinking.
+     */
     async function placed(current) {
         status(current, { state: "thinking" });
+        await draining;
         await current.place?.entered;
         current.waiting = false;
         if (current.cancelled)
             return;
+        // Where it answers until a request says: so a failure before one names its thread.
+        current.thread = await record.where();
         await run(current);
     }
     /**
-     * Take a turn's place, or its turn in the line for one, before anything of it is kept. A turn
-     * cancelled already takes none: it runs nothing.
+     * Take a turn's place, or its turn in the line for one, before anything of it is kept. While a
+     * stopped turn of this work still writes, the turn takes none: it gets that turn's, so a piece
+     * of work holds one place. A turn cancelled already takes none: it runs nothing.
      */
     const enter = (current, begun) => {
         if (current.cancelled)
             return;
-        current.place = options.enter(begun);
+        if (!lingering)
+            current.place = options.enter(begun);
         current.waiting = true;
     };
-    const said = async (text, joined) => {
-        const entry = await record.append({
-            role: "user",
-            items: [{ type: "message", role: "user", content: text }],
-            ...(joined ? { joined: true } : {}),
-        });
-        show(entry);
-        return { messageId: entry.id };
+    const said = async (text, thread, joined) => {
+        const kept = await record.append({ ...userEntry(text), ...(joined ? { joined: true } : {}) }, { thread });
+        show(kept);
+        return { messageId: kept.entry.id };
     };
     /**
-     * Start a turn: `open` takes its place and keeps what opens it, then its loop runs. When `open`
-     * gives nothing, no turn starts. A turn `cancelled` before it started keeps what opens it and
-     * runs nothing.
+     * Start a turn: `open` takes its place and keeps what opens it, at once, then its loop runs.
+     * When `open` gives nothing, no turn starts. A turn `cancelled` before it started keeps what
+     * opens it and runs nothing.
      */
     const start = async (cancelled, open) => {
-        const current = { cancelled };
+        const current = { id: ++turns, cancelled, took: new Set() };
         if (!cancelled)
             turn = current;
-        began = true;
         try {
-            // A cancelled turn's last call lands in the record before anything new does.
-            await draining;
-            draining = undefined;
             const begun = await open(current);
             if (begun)
                 begin(current);
-            else if (turn === current)
-                turn = undefined;
+            else {
+                current.place?.leave();
+                if (turn === current)
+                    turn = undefined;
+            }
             return begun?.opened;
         }
         catch (error) {
@@ -251,37 +270,66 @@ export function createLoop(options) {
     };
     return {
         /**
-         * Say a message. With no turn it starts one, whose progress is said through `out`. In a turn,
-         * running or waiting for its place, it is recorded and said at once, and the turn takes it at
-         * its next model request.
+         * Say a message in a thread the work follows. It is recorded and said at once. In a turn,
+         * running or waiting for its place, the turn takes it at its next model request: `turn` is
+         * then that turn's number. With no turn it starts one, whose progress is said through `out`.
          */
-        send: (text) => inOrder(async (cancelled) => {
-            if (turn)
-                return said(text, true);
+        send: (text, thread) => inOrder(async (cancelled) => {
+            const into = turn;
+            if (into) {
+                into.took.add(thread);
+                return { ...(await said(text, thread, true)), turn: into.id };
+            }
             return (await start(cancelled, async (current) => {
-                enter(current, !(await record.empty()));
-                return { opened: await said(text, false) };
+                enter(current, await record.begun());
+                current.took.add(thread);
+                return { opened: await said(text, thread, draining !== undefined) };
             }));
         }),
         /**
-         * Go on with a turn that was cut off before it ended, as by a restart: the thread shows one
-         * line saying so, and the model is told once to check what is already done. Nothing goes on in
-         * a thread with nothing kept, in one that has had a turn since the loop was made, or when a
-         * cancel comes first.
+         * Take the messages waiting in `thread`, which the work has come to follow, as its own, and
+         * answer them: in the turn running, or in one this starts. With none waiting no turn starts.
+         * When a cancel came first nothing is taken, and it says so with `false`.
+         */
+        adopt: (thread) => inOrder(async (cancelled) => {
+            if (cancelled)
+                return false;
+            if (turn) {
+                turn.took.add(thread);
+                await record.adopt(thread, true);
+                return true;
+            }
+            await start(false, async (current) => {
+                enter(current, await record.begun());
+                current.took.add(thread);
+                if ((await record.adopt(thread, draining !== undefined)) > 0)
+                    return { opened: undefined };
+                return undefined;
+            });
+            return true;
+        }),
+        /**
+         * Go on with a turn that was cut off before it ended, as by a restart: the thread it was
+         * answering in shows one line saying so, and the model is told once to check what is already
+         * done. Nothing goes on in work with nothing kept, in work that has had a turn since the loop
+         * was made, or when a cancel comes first.
          */
         resume: () => inOrder(async (cancelled) => {
-            if (began || cancelled)
+            if (turns > 0 || cancelled)
                 return;
             await start(false, async (current) => {
                 if ((await record.empty()) || current.cancelled)
                     return undefined;
                 enter(current, true);
                 current.resumed = true;
+                // In the thread of the message it was answering.
+                const thread = await record.where();
+                current.took.add(thread);
                 show(await record.append({
                     role: "tool",
                     text: CUT_OFF.shown,
                     items: [{ type: "message", role: "user", content: CUT_OFF.told }],
-                }));
+                }, { thread }));
                 return { opened: undefined };
             });
         }),
@@ -289,44 +337,69 @@ export function createLoop(options) {
         resumed: () => turn?.resumed === true,
         /** The status now. */
         state: () => latest,
+        /** The number of the turn running or waiting for its place, if one is. */
+        turn: () => turn?.id,
         /**
-         * Stop the turn now: its model request is cancelled, no further call starts, and a new turn
-         * may begin at once. A call already running finishes, and its result is kept. A turn waiting
-         * for its place never starts.
+         * Stop the turn now, or with `only`, the turn of that number if it is still the one: its
+         * model request is cancelled and no further call starts. A call already running finishes,
+         * and its result is kept; a new turn may be started at once, and reads the record after
+         * that. A turn waiting for its place never starts. It says whether it cut a turn. `line` is
+         * what the main loop says as it stops it, kept in that thread in order with what was asked
+         * before.
          */
-        async cancel() {
+        async cancel(only, line) {
+            const current = turn;
+            if (only !== undefined && current?.id !== only)
+                return false;
             // Counted with no turn too: a message asked but not yet taken starts none after this.
             cancels++;
-            const current = turn;
             if (!current)
-                return;
+                return false;
             current.cancelled = true;
             turn = undefined;
             // A turn that will write nothing more gives its place back now: one still waiting for it,
-            // one the model is answering, or one waiting for its end. Any other keeps its place until it
-            // has written what it will, and what comes next waits for that: the reply it is storing,
-            // or the result of its running call.
+            // one the model is answering, or one waiting for its end. Any other's place is kept until
+            // it has written what it will: the reply it is storing, or the result of its running call.
             const quiet = current.requestId !== undefined || current.ending === true;
             if (current.waiting || quiet)
                 current.place?.leave();
-            if (!quiet)
-                draining = current.ended ?? draining;
+            else if (current.ended) {
+                const still = current.ended;
+                draining = still;
+                lingering = current.place;
+                current.place = undefined;
+                // Once that has ended nothing is being written by a stopped turn any more: its place
+                // goes to the turn that waited for this, or back.
+                still.finally(() => {
+                    if (draining !== still)
+                        return;
+                    draining = undefined;
+                    if (turn?.waiting && !turn.place)
+                        turn.place = lingering;
+                    else
+                        lingering?.leave();
+                    lingering = undefined;
+                });
+            }
             say({ state: "idle" });
-            if (current.requestId)
-                await model.cancel({ requestId: current.requestId }).catch(() => { });
+            await Promise.all([
+                current.requestId && model.cancel({ requestId: current.requestId }).catch(() => { }),
+                line && inOrder(async () => show(await record.stopLine(line.text, line.thread))),
+            ]);
+            return true;
         },
         /** Settles when the latest turn has written all it will. */
         settled: async () => {
             await lastEnded;
         },
-        /** Settles when a stopped turn's running call has ended: at once, if none is running. */
+        /** Settles when a stopped turn has written what it will: at once, if none is writing. */
         drained: async () => {
             await draining;
         },
         /** Streamed text of the model request running now, for the reply it becomes. */
         delta(requestId, text) {
             if (turn?.requestId === requestId && turn.replyId)
-                out.delta(turn.replyId, text);
+                out.delta(turn.thread ?? record.id, turn.replyId, text);
         },
     };
 }

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

@@ -1,14 +1,52 @@
+/**
+ * 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, or, when a message needs no work, the main loop.
+ *
+ * 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 decides on the thread: it answers itself, and
+ * the thread stays no work's; or it says whose the message is, new work, which has the thread's
+ * name as its id, or work there is, in a turn or at rest, 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.
+ *
+ * One piece of work is stopped by saying so. The main loop may answer a message in a thread
+ * nothing follows by stopping the turn of work it was told of; and it is told of each message that
+ * joins a turn of the work its thread follows, beside that work getting it, to stop that turn if
+ * the message asks. The turn is cut and the work is at rest. What the main loop says of it is
+ * said where the message was: in the work's own record when it joined the turn, for the work to
+ * read next, and otherwise in the asking thread alone, which stays no work's.
+ *
+ * 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 no
+ * work follows it and it holds messages. A looper that closes under a turn or a decision, 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; a thread the main loop answered, couldn't place,
+ * or was stopped over, waits for its next message, and the main loop is put what it holds.
+ */
 import { type Log, type Model, type Shown, type Status, type Store, type Tool } from "./types.js";
-/** The turns that run at once, not counting the one more for a thread already begun. */
+/** The turns that run at once, not counting the one more for work already begun. */
 export declare const PLACES = 4;
 /** The turns that may wait for a place at once. */
 export declare const WAITING = 16;
-/** Where a looper's loops say what they do, each with the thread it is said in. */
+/** Where a looper says what it does. */
 export interface LooperOut {
+    /** A message, with the thread it is shown in. */
     message(thread: string, message: Shown): void;
     /** Text of the reply `id` as the model writes it. */
     delta(thread: string, id: string, text: string): void;
-    status(thread: string, status: Status): void;
+    /** Whether anything is at work, the main loop included: said when it changes. */
+    working(on: boolean): void;
+    /** A message in `thread` got no answer, and why. */
+    failed(thread: string, problem: {
+        code: string;
+        message: string;
+    }): void;
 }
 /**
  * Make a looper. Nothing is read or run until a thread is named: a message sent in it, or its
@@ -19,12 +57,15 @@ export declare function createLooper(options: {
     model: Model;
     /**
      * Read for each model request, since any of it may change between two: what the model is told,
-     * what it can call, and which model to ask, none meaning the model's own default.
+     * what it can call, and which model to ask, none meaning the model's own default. `voice` is
+     * who the main loop speaks as when it answers a message itself: what the host's own model is
+     * told of itself, with nothing of what it can call.
      */
     request(): Promise<{
         instructions: string;
         tools: Tool[];
         model?: string | undefined;
+        voice?: string | undefined;
     }>;
     out: LooperOut;
     /** Whether it starts stopped: no turn starts until `start`. */
@@ -32,38 +73,41 @@ export declare function createLooper(options: {
     log: Log;
 }): {
     /**
-     * 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.
+     * 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 answers it or 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: string, text: string): Promise<{
         messageId: string;
     }>;
-    /** Stop a thread's turn now. A call already running finishes, and its result is kept. */
-    cancel: (thread: string) => Promise<void | undefined>;
-    /** What a thread's loop is doing. */
-    state: (thread: string) => Status;
+    /** Stop a piece of work's turn now. A call already running finishes, and its result is kept. */
+    cancel: (work: string) => Promise<undefined>;
+    /** What a piece of work's loop is doing. */
+    state: (work: string) => Status;
     /** A thread's messages before `before`, oldest first, as many as fit `limit`. */
     page: (thread: string, before: string | undefined, limit: number) => Promise<{
         messages: Shown[];
         more: boolean;
     }>;
     /**
-     * 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.
+     * 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.
      */
     stop(): Promise<void>;
     /** Take messages again. The turns `stop` cut stay cut. */
     start(): void;
     resume: () => Promise<void>;
     /**
-     * Close for good: every turn is cut, and none starts after. Each stays marked, for `resume`
-     * in whoever opens the store next.
+     * 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.
      */
     close(): Promise<void>;
-    /** Settles when every thread's latest turn has written all it will. */
+    /** Settles when every piece of work's latest turn has written all it will. */
     settled(): Promise<void>;
     /** Text the model writes while it answers `requestId`, for the reply it becomes. */
     delta(requestId: string, text: string): void;