@agentorg/cli 0.0.7 → 0.0.9

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

@@ -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 } from "./types.js";
@@ -15,14 +17,32 @@ export const Entry = z.object({
     items: z.array(Item),
     /** For a tool message whose call ran: how it ended. */
     state: z.enum(["done", "refused"]).optional(),
-    /** For a user message said while a turn was running: it is part of that turn. */
+    /**
+     * For a user message said while a turn was running, or while a stopped turn was still writing:
+     * it is part of that turn. Also for what the main loop said in a thread, taken with such
+     * messages or said as it stopped the turn: it stays in its place among them.
+     */
     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.
+     * For what came of a model request that had read its work up to this place, when a user message
+     * was said after that, or the main loop said it stopped the turn: the model reads it ahead of
+     * those, which it doesn't answer.
      */
     ahead: z.number().optional(),
+    /** The piece of work it belongs to, when that isn't its thread's own. */
+    work: z.string().optional(),
+    /**
+     * For what the main loop said itself, which no piece of work said: the number in its thread it
+     * stands after, ahead of any said after that. For a reply that is the number it had read up to;
+     * for what it said as it stopped a piece of work, all the thread held then.
+     */
+    main: z.number().optional(),
+    /**
+     * Its place in its work's order, once that work follows more than one thread. Without it, its
+     * place is where it stands in its thread: its number, or for what the main loop said, right
+     * after the number that names.
+     */
+    place: z.number().optional(),
 });
 /** Where a record's messages are kept in its store. */
 export const MESSAGES = "msg/";
@@ -96,9 +116,24 @@ const kept = (entry) => ({
 });
 /** 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 }) {
+/** A user message as it is kept when said. */
+export const userEntry = (text) => ({
+    role: "user",
+    items: [{ type: "message", role: "user", content: text }],
+});
+/** What the main loop said, as it is kept: it stands after `after`, a number in its thread. */
+const mainEntry = (text, after) => ({
+    role: "assistant",
+    main: after,
+    items: [{ type: "message", role: "assistant", content: text }],
+});
+/**
+ * Where a message stands in its thread: its number, but what the main loop said stands right
+ * after the number it names, ahead of a message said while it answered.
+ */
+const orderOf = ({ seq, entry }) => (entry.main === undefined ? seq : entry.main + 0.5);
+/** A thread's messages in a store, by their numbers. */
+export function createThread(store, log, limits = { keep: KEEP, keepBytes: KEEP_BYTES }) {
     let loaded;
     const load = () => {
         if (loaded)
@@ -126,7 +161,7 @@ export function createRecord(store, log, limits = { keep: KEEP, keepBytes: KEEP_
                             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) };
+                        const record = { seq: seqOf(key), key, entry: parsed.data, bytes: size(parsed.data) };
                         records.push(record);
                         bytes += record.bytes;
                     });
@@ -142,58 +177,97 @@ export function createRecord(store, log, limits = { keep: KEEP, keepBytes: KEEP_
         });
         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;
+    /**
+     * Keep a message in a thread already read, at once, under `id` or its own number; `stored`
+     * settles when it is written and the oldest past the cap are deleted. A tool message the store
+     * refuses is still kept in memory, since its call has run; any other is taken out again.
+     */
+    const push = (held, entry, id) => {
+        const seq = ++held.last;
+        const key = keyOf(seq);
+        const record = {
+            seq,
+            key,
+            entry: kept({
+                id: id ?? key.slice(MESSAGES.length),
+                at: new Date().toISOString(),
+                ...entry,
+            }),
+            bytes: 0,
+            writing: entry.role === "user",
+        };
+        record.bytes = size(record.entry);
+        held.records.push(record);
+        held.bytes += record.bytes;
+        const stored = (async () => {
             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;
+                    held.records.splice(held.records.indexOf(record), 1);
+                    held.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;
+            while (held.records.length > 1 &&
+                (held.records.length > limits.keep || held.bytes > limits.keepBytes)) {
+                const oldest = held.records.shift();
+                held.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;
+        })();
+        return { record, stored };
+    };
+    return {
+        /** What it holds, read once. */
+        load,
+        push,
+        /**
+         * 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.
+         */
+        async said() {
+            const held = await load();
+            const said = held.records
+                .filter(({ entry }) => entry.role !== "tool")
+                .sort((a, b) => orderOf(a) - orderOf(b))
+                .map(({ entry }) => ({ role: entry.role, text: textOf(entry) }));
+            return { said, upTo: held.last };
         },
-        /** Whether nothing is kept. */
-        async empty() {
-            return (await load()).records.length === 0;
+        /**
+         * 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.
+         */
+        async answer(text, upTo, id) {
+            const held = await load();
+            const { record, stored } = push(held, mainEntry(text, upTo), id);
+            await stored;
+            const late = held.records.some(({ seq, entry }) => seq > upTo && entry.role === "user");
+            return { entry: record.entry, late };
+        },
+        /**
+         * 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, record, entry) {
+            const was = { entry: record.entry, bytes: record.bytes };
+            const swap = (to) => {
+                held.bytes += to.bytes - record.bytes;
+                Object.assign(record, to);
+            };
+            swap({ entry, bytes: size(entry) });
+            return {
+                store: () => store.set({ key: record.key, value: record.entry }),
+                undo: () => swap(was),
+            };
         },
         /** Messages before `before`, oldest first, as many as fit `limit` and `PAGE_BUDGET`. */
         async page(before, limit) {
@@ -215,19 +289,179 @@ export function createRecord(store, log, limits = { keep: KEEP, keepBytes: KEEP_
             }
             return { messages, more: start > 0 };
         },
+    };
+}
+/**
+ * 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 function createRecord(options) {
+    const { id } = options;
+    const placeOf = (record) => record.entry.place ?? orderOf(record);
+    const mine = (thread, record) => record.entry.work === undefined ? thread === id : record.entry.work === id;
+    /** Every thread it follows, read: what each holds, as it changes. */
+    const load = async () => {
+        const held = new Map();
+        for (const name of options.follows())
+            held.set(name, await options.thread(name).load());
+        return held;
+    };
+    /**
+     * Its own messages in the threads read, in order, as they stand now. Nothing waits between
+     * this and what is decided from it.
+     */
+    const own = (held) => {
+        const records = [...held].flatMap(([thread, { records }]) => records.flatMap((record) => (mine(thread, record) ? [{ thread, record }] : [])));
+        return records.sort((a, b) => placeOf(a.record) - placeOf(b.record));
+    };
+    /** The highest place among its messages. */
+    const topOf = (records) => {
+        const last = records.at(-1);
+        return last ? placeOf(last.record) : 0;
+    };
+    /**
+     * Take the messages waiting in `thread` as its own, after all it holds: at once in memory, and
+     * `written` settles when each is stored, or rejects with the first that isn't, which stays
+     * waiting with those after it. Like a message being written, the model is sent none of them
+     * until that has settled.
+     */
+    const take = (held, thread, joined) => {
+        const from = held.get(thread);
+        const waiting = thread === id
+            ? []
+            : from.records.filter(({ entry }) => !entry.work).sort((a, b) => orderOf(a) - orderOf(b));
+        let top = topOf(own(held));
+        // Each gets its place in the order it was said and answered: at once in memory.
+        const changes = waiting.map((record) => {
+            record.writing = true;
+            return options.thread(thread).change(from, record, {
+                ...record.entry,
+                work: id,
+                place: ++top,
+                ...(joined ? { joined: true } : {}),
+            });
+        });
+        // Stored one after another in that order, so what a crash or a refusal leaves taken is the
+        // start of them: the rest stay waiting, and are taken after it.
+        const written = (async () => {
+            try {
+                for (const [i, change] of changes.entries())
+                    await change.store().catch((error) => {
+                        for (const rest of changes.slice(i))
+                            rest.undo();
+                        throw error;
+                    });
+            }
+            finally {
+                for (const record of waiting)
+                    record.writing = false;
+            }
+        })();
+        return { taken: waiting.length, written };
+    };
+    /** Whether a user message of its, stored already, follows the place `read`. */
+    const saidAfter = (records, read) => records.some(({ record }) => record.entry.role === "user" && placeOf(record) > read && !record.writing);
+    /**
+     * Whether something the model reads after what a request made stands past the place `read`,
+     * which that request had read up to: a user message, or what the main loop said as it stopped
+     * the turn.
+     */
+    const heldBack = (records, read) => records.some(({ record }) => placeOf(record) > read && (record.entry.role === "user" || record.entry.joined === true));
+    /** The thread of its newest user message: where it answers. Its own, with none. */
+    const whereOf = (records) => records.findLast(({ record }) => record.entry.role === "user")?.thread ?? id;
+    /** Keep an entry of its in `thread`, made once nothing waits there, from what the thread holds. */
+    const keep = async (thread, make, at) => {
+        const held = await load();
+        const from = held.get(thread);
+        // What waits there is taken and stored first, so this is never kept ahead of it: it joins
+        // a turn if this does, or comes of one. If the store won't take it, nothing is kept.
+        const joins = make(from).joined === true || at.read !== undefined;
+        await take(held, thread, joins).written;
+        // From here to the push nothing waits, so its place and what is ahead of it are decided
+        // with the record as it stands.
+        const records = own(held);
+        const { record, stored } = options.thread(thread).push(from, {
+            ...make(from),
+            ...(thread === id ? {} : { work: id }),
+            ...(held.size > 1 ? { place: topOf(records) + 1 } : {}),
+            ...(at.read !== undefined && heldBack(records, at.read) ? { ahead: at.read } : {}),
+        }, at.id);
+        await stored;
+        return { entry: record.entry, thread };
+    };
+    return {
+        id,
+        /**
+         * 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, at) => keep(at.thread, () => entry, at),
+        /**
+         * 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, thread) => keep(thread, (from) => ({ ...mainEntry(text, from.last), joined: true }), {}),
+        /**
+         * 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.
+         */
+        async adopt(thread, joined) {
+            const held = await load();
+            const { taken, written } = take(held, thread, joined);
+            await written;
+            if (thread !== id)
+                return taken;
+            const records = own(held);
+            const done = records.findLastIndex(({ record: { entry } }) => entry.role !== "user" && entry.main === undefined);
+            return records.slice(done + 1).filter(({ record }) => record.entry.role === "user").length;
+        },
+        /**
+         * Whether it has had a turn that did something: it holds more than what was said to it and
+         * what the main loop said.
+         */
+        async begun() {
+            return own(await load()).some(({ record: { entry } }) => entry.role !== "user" && entry.main === undefined);
+        },
+        /** What it last said, if anything. */
+        async last() {
+            const said = own(await load()).findLast(({ record: { entry } }) => entry.role === "assistant" && entry.main === undefined);
+            return said ? textOf(said.record.entry) : undefined;
+        },
+        /** Whether it has no message. */
+        async empty() {
+            return own(await load()).length === 0;
+        },
+        /** The thread it answers in now. */
+        async where() {
+            return whereOf(own(await load()));
+        },
+        /** Its first user message, for a title. */
+        async opening() {
+            const first = own(await load()).find(({ record }) => record.entry.role === "user");
+            return first ? textOf(first.record.entry) : "";
+        },
         /**
-         * 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.
          */
         async input() {
-            const { records, last } = await load();
-            const unwritten = records.find((record) => record.writing);
-            const read = unwritten ? seqOf(unwritten.key) - 1 : last;
+            const records = own(await load());
+            const last = topOf(records);
+            const unwritten = records.find(({ record }) => record.writing);
+            const read = unwritten ? placeOf(unwritten.record) - 1 : last;
             const exchanges = [];
             /** Said during a turn, and not yet put: what is ahead of them goes first. */
             const late = [];
@@ -236,12 +470,12 @@ export function createRecord(store, log, limits = { keep: KEEP, keepBytes: KEEP_
                     exchanges.push([]);
                 exchanges.at(-1)?.push(...entry.items);
             };
-            /** Put the late messages numbered up to `read`. */
+            /** Put the late messages placed up to `read`. */
             const putLate = (read) => {
-                while (late[0] && seqOf(late[0].key) <= read)
+                while (late[0] && placeOf(late[0]) <= read)
                     put(late.shift().entry);
             };
-            for (const record of records) {
+            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;
@@ -268,11 +502,11 @@ export function createRecord(store, log, limits = { keep: KEEP, keepBytes: KEEP_
                     items[i] = { ...item, arguments: ARGUMENTS_LEFT_OUT };
                 }
             }
-            return { items, read };
+            return { items, read, thread: whereOf(records.filter(({ record }) => !record.writing)) };
         },
-        /** 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. */
         async saidAfter(read) {
-            return saidAfter((await load()).records, read, true);
+            return saidAfter(own(await load()), read);
         },
     };
 }

package/dist/node_modules/@agentorg/manager/dist/src/control.d.ts

@@ -16,7 +16,7 @@ export declare const LIMIT_MAX = 8;
 export declare const DEPTH_MAX = 3;
 /** Above this many agents in the home, none is made by an agent. They share one plan. */
 export declare const HOME_CAP = 24;
-export declare const skillFile: (path: string) => "---\nname: delegating\ndescription: How to hand work to agents of your own and see it through, and what else your control tools reach. Use it before creating an agent, and whenever you have work that can run apart from yours.\n---\nYour `control` connection's tools reach what the person allowed you: agents, and perhaps connections, skills and templates. A tool you don't have is one you weren't given.\n\n## Before you create an agent\n\nDo the work yourself when it is short. An agent costs model usage from the plan everyone here shares, and you have a limit on how many you can have. Use one when work can run apart from yours, or needs a shape you were not given.\n\nThere is one create tool per template you may use. Read its description and fields. Give the agent a plain name and a purpose: one sentence on what it is for, which it will be told. Fields you leave out keep the template's value.\n\n## Working with it\n\n- `agent_send` gives it a message and returns at once. It works on its own after that. Your name is on the message's first line.\n- A message with no chat named starts a new chat with it, and tells you which. Name that chat to go on in it. Start another only for work that is apart from the first.\n- `agent_chats` lists its chats and says whether it is working. A chat with a `problem` has a message that got no answer: send it another once the problem is dealt with. `agent_read` shows what was said in one. Check back when you need the result, rather than after every step.\n- Say what you want back and in what form. It knows only what you send it and its purpose.\n\n## When it is done\n\n`agent_remove` it when its work is finished, so your limit is free for the next one. `agent_stop` it to keep it for later. You can remove only agents you made, and theirs. The person sees every agent you create on their Agents page, and every change you make through these tools, and can undo any of it.\n" | undefined;
+export declare const skillFile: (path: string) => "---\nname: delegating\ndescription: How to hand work to agents of your own and see it through, and what else your control tools reach. Use it before creating an agent, and whenever you have work that can run apart from yours.\n---\nYour `control` connection's tools reach what the person allowed you: agents, and perhaps connections, skills and templates. A tool you don't have is one you weren't given.\n\n## Before you create an agent\n\nDo the work yourself when it is short. An agent costs model usage from the plan everyone here shares, and you have a limit on how many you can have. Use one when work can run apart from yours, or needs a shape you were not given.\n\nThere is one create tool per template you may use. Read its description and fields. Give the agent a plain name and a purpose: one sentence on what it is for, which it will be told. Fields you leave out keep the template's value.\n\n## Working with it\n\n- `agent_send` gives it a message and returns at once. It works on its own after that. Your name is on the message's first line.\n- A message with no chat named starts a new chat with it, and tells you which. Name that chat to go on in it. Start another only for work that is apart from the first.\n- `agent_chats` lists its chats and says whether it is working. A chat with a `problem` has a message that got no answer: send it another once the problem is dealt with. `agent_read` shows what was said in one. Check back when you need the result, rather than after every step.\n- Say what you want back and in what form. It knows only what you send it and its purpose.\n\n## When it is done\n\n`agent_remove` it when its work is finished, so your limit is free for the next one. `agent_stop` it to keep it for later. You can remove only agents you made, and theirs. The person sees every agent you create: it is listed with the person's own agents, and has a page of its own. The person also sees every change you make through these tools, and can undo any of it.\n" | undefined;
 type Values = z.infer<typeof FieldValues>;
 type TheUnit = z.infer<typeof Unit>;
 type TheAgent = z.infer<typeof AgentRecord>;

package/dist/node_modules/@agentorg/manager/dist/src/control.js

@@ -58,7 +58,7 @@ There is one create tool per template you may use. Read its description and fiel
 
 ## When it is done
 
-\`agent_remove\` it when its work is finished, so your limit is free for the next one. \`agent_stop\` it to keep it for later. You can remove only agents you made, and theirs. The person sees every agent you create on their Agents page, and every change you make through these tools, and can undo any of it.
+\`agent_remove\` it when its work is finished, so your limit is free for the next one. \`agent_stop\` it to keep it for later. You can remove only agents you made, and theirs. The person sees every agent you create: it is listed with the person's own agents, and has a page of its own. The person also sees every change you make through these tools, and can undo any of it.
 `;
 export const skillFile = (path) => (path === SKILL_FILE ? SKILL_TEXT : undefined);
 /** The agents unit's form, with what can be chosen today. */