@agentorg/cli 0.0.6 → 0.0.8

package/dist/node_modules/assistant/dist/src/engine.js

@@ -1,13 +1,11 @@
 import { Refused } from "@agentorg/sdk";
-import { createAgent } from "./agent.js";
-import { createHistory } from "./history.js";
+import { createChats } from "./chats.js";
 import { instructionsWith, skillTool } from "./settings.js";
-import { listedBy, listsTools, offered } from "./tools.js";
-/** Where the agent keeps the model chosen for it, beside its record in the store. */
+import { listedBy, listsTools, offered, relayed } from "./tools.js";
+/** Where the agent keeps the model chosen for it, beside its chats in the store. */
 const MODEL_KEY = "settings/model";
 export function startEngine(ctx, options) {
     const { store } = options;
-    const history = createHistory(store, ctx.log);
     /** The model chosen for this agent, if any; read for each request. */
     const chosen = async () => {
         const { value } = await store.get({ key: MODEL_KEY });
@@ -25,7 +23,10 @@ export function startEngine(ctx, options) {
         else
             ctx.log.info("Everything is offered to the model again.");
     };
-    /** What a request says and offers, read afresh: nothing here outlives the request. */
+    /**
+     * What a request says and offers, and to which model, read afresh: none of it outlives it.
+     * `leftOut` is what it couldn't offer, and why.
+     */
     const request = async () => {
         const settings = ctx.slots.settings.bound ? await ctx.slots.settings.call.get({}) : undefined;
         const told = settings
@@ -37,52 +38,123 @@ export function startEngine(ctx, options) {
             .exposed()
             .filter((slot) => listsTools(slot.described))
             .map((slot) => listedBy(slot.slot, slot)));
-        const { tools, leftOut } = offered([...own, ...exposed.flatMap((one) => one.candidates)]);
-        report([...told.leftOut, ...exposed.flatMap((one) => one.leftOut), ...leftOut]);
-        return { instructions: told.instructions, tools };
+        const fitted = offered([...own, ...exposed.flatMap((one) => one.candidates)]);
+        const leftOut = [...told.leftOut, ...exposed.flatMap((one) => one.leftOut), ...fitted.leftOut];
+        report(leftOut);
+        return { instructions: told.instructions, tools: fitted.tools, model: await chosen(), leftOut };
     };
-    const agent = createAgent({
-        request,
-        model: ctx.slots.model,
-        chosenModel: chosen,
-        history,
-        chat: {
+    /** The model slot as the looper asks it: what it refuses is told with its code. */
+    const model = {
+        respond: (asked) => relayed(ctx.slots.model.call.respond(asked)),
+        // A model that is gone has nothing to stop.
+        cancel: async (asked) => (ctx.slots.model.bound ? ctx.slots.model.call.cancel(asked) : {}),
+    };
+    const chats = createChats({
+        store,
+        stopped: options.stopped ?? false,
+        model,
+        request: () => relayed(request()),
+        emit: {
             message: (message) => ctx.exports.chat.emit("message", message),
-            delta: (id, text) => ctx.exports.chat.emit("delta", { id, text }),
+            delta: (delta) => ctx.exports.chat.emit("delta", delta),
             status: (status) => ctx.exports.chat.emit("status", status),
+            chat: (entry) => ctx.exports.chat.emit("chat", entry),
         },
         log: ctx.log,
     });
-    ctx.slots.model.on("delta", ({ requestId, text }) => agent.delta(requestId, text));
+    ctx.slots.model.on("delta", ({ requestId, text }) => chats.delta(requestId, text));
+    /**
+     * The turns that were cut off when the agent last ran go on once the model is bound, the
+     * settings answer, and no tools slot is away. As the agent starts, what it is bound to may not
+     * be running yet, so this is looked at again whenever that may have changed: a slot's provider
+     * is back, a tools slot is made or gone, or one says its tools changed. A tools slot that stays
+     * away holds them back; a message in a chat starts a turn anyway.
+     */
+    let wentOn = false;
+    /** Each tools slot heard for its tools changing, with how to stop hearing it. */
+    const heard = new Map();
+    const goOn = async () => {
+        for (const slot of ctx.exposed())
+            if (listsTools(slot.described) && !heard.has(slot))
+                heard.set(slot, slot.on("changed", look));
+        if (!ctx.slots.model.bound)
+            return;
+        // Refused while the settings can't answer, as a turn's own request would be.
+        const { leftOut } = await request();
+        if (leftOut.some((one) => one.reason === "not_connected"))
+            return;
+        await chats.resume();
+        done();
+    };
+    /** Nothing more is looked for: the turns have gone on, or the agent is stopped or closing. */
+    const done = () => {
+        wentOn = true;
+        for (const stop of heard.values())
+            stop();
+        heard.clear();
+    };
+    /** The look running now, and whether to look once more after it. */
+    let looking;
+    let again = false;
+    const look = () => {
+        again = true;
+        looking ??= (async () => {
+            // A start binds its slots one after another in one go, and one not bound yet reads as one
+            // the agent doesn't have: so it looks once they all are.
+            await Promise.resolve();
+            while (again && !wentOn) {
+                again = false;
+                await goOn().catch((error) => ctx.log.info("Turns that were cut off aren't looked for yet.", { error: String(error) }));
+            }
+            looking = undefined;
+        })();
+    };
+    ctx.slots.model.onBind(look);
+    ctx.slots.settings.onBind(look);
+    ctx.onExposed(look);
     ctx.exports.chat.implement({
-        send: ({ text }) => agent.send(text),
-        history: ({ before, limit }) => history.page(before, limit ?? 50),
-        cancel: async () => {
-            await agent.cancel();
-            return {};
-        },
-        state: () => agent.state(),
-        retry: () => agent.retry(),
-        models: async () => {
+        send: (input) => chats.send(input),
+        history: (input) => chats.history(input),
+        state: () => chats.state(),
+        list: (input) => chats.list(input),
+        rename: (input) => chats.rename(input),
+        archive: (input) => chats.archive(input),
+    });
+    return {
+        /** The models the agent can use, and the one chosen for it. */
+        async models() {
             const [{ models }, current] = await Promise.all([ctx.slots.model.call.models({}), chosen()]);
             return { models, ...(current ? { current } : {}) };
         },
-        setModel: async ({ model }) => {
+        /** Choose the model for its next requests, kept with it; with none, the provider's default. */
+        async setModel(model) {
             if (!model) {
                 await store.delete({ key: MODEL_KEY });
-                return {};
+                return;
             }
             const { models } = await ctx.slots.model.call.models({});
             if (!models.some((offered) => offered.id === model))
                 throw new Refused("unknown", `${model} isn't one of the models offered.`);
             await store.set({ key: MODEL_KEY, value: model });
-            return {};
         },
-    });
-    return {
-        /** Stop the turn in progress. */
-        cancel: () => agent.cancel(),
-        /** Settles when the latest turn has written all it will. */
-        settled: () => agent.settled(),
+        /** Stop the agent: its turns are cut and none starts until `start`. Its chats stay readable. */
+        stop() {
+            done();
+            return chats.stop();
+        },
+        start: () => chats.start(),
+        /**
+         * Close for good: its turns are cut, and none starts after. They go on in the engine that
+         * opens this store next.
+         */
+        close() {
+            done();
+            return chats.close();
+        },
+        /** Settles when every chat's latest turn has written all it will. */
+        async settled() {
+            await looking;
+            await chats.settled();
+        },
     };
 }

package/dist/node_modules/assistant/dist/src/local-store.js

@@ -1,7 +1,7 @@
 /**
  * The engine's record when it runs as an ordinary program: one small JSON file per key, in the
  * agent's own folder. A new message writes one file, however long the record is, and each write
- * lands whole. It answers as `kv@1` does, so the history reads it as it reads any store.
+ * lands whole. It answers as `kv@1` does, so the engine reads it as it reads any store.
  */
 import { randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";

package/dist/node_modules/assistant/dist/src/provider.d.ts

@@ -14,7 +14,7 @@ export interface AgentProviderOptions {
     log?: Log;
 }
 export interface AgentProvider {
-    /** Leave the Hub and stop every agent. They stay, and those not stopped resume at the next start. */
+    /** Leave the Hub, every agent with it. They stay, and rejoin at the next start as each was left. */
     close(): Promise<void>;
 }
 /** Run the bundled agent provider as an Actor exporting `agent.provider@1` as `provider`. */

package/dist/node_modules/assistant/dist/src/provider.js

@@ -1,13 +1,14 @@
 /**
  * The bundled agent provider: it offers one creatable, Assistant, and runs each agent in this
- * process as its own Actor on its own channel. Stopping an agent closes its channel; starting it
- * opens one. Each agent's record and model choice are kept in the provider's private folder.
+ * process as its own Actor on its own channel. A stopped agent stays on its channel, so its chats
+ * can be read, and runs no turn until it is started. Each agent's chats and model choice are kept
+ * in the provider's private folder.
  */
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { agentProvider, agentSettings, chat, hubActors, llmSession } from "@agentorg/interfaces";
-import { Refused } from "@agentorg/sdk";
+import { NotConnected, Refused } from "@agentorg/sdk";
 import { connect } from "@agentorg/sdk/client";
 import { z } from "zod";
 import { startEngine } from "./engine.js";
@@ -22,8 +23,6 @@ const ASSISTANT = {
     description: "An agent that chats, and acts through the connections you give it.",
     instructions: ASSISTANT_INSTRUCTIONS,
     asks: [],
-    skills: [],
-    mcp: [],
 };
 /** What is kept of an agent between runs, in the provider's private file. */
 const Stored = z.object({ credential: z.string(), stopped: z.boolean() });
@@ -70,16 +69,33 @@ export async function startAgentProvider(options) {
             throw new Refused("unknown", `This provider made no agent ${agent}.`);
         return found;
     };
+    /** An agent's engine, while it is on its channel: running, or stopped. */
+    const engineOf = (agent) => {
+        const { channel, engine, detail } = held(agent);
+        if (!channel || !engine)
+            throw new Refused("unavailable", detail ?? "It isn't running.");
+        return engine;
+    };
+    /**
+     * What an agent's model answered. A model that is away is refused as that, where the bare
+     * error would reach the caller as its own slot being away.
+     */
+    const ofModel = (asked) => asked.catch((error) => {
+        if (error instanceof NotConnected)
+            throw new Refused("not_connected", "Its model isn't connected.");
+        throw error;
+    });
     const inTurn = (agent, work) => {
         const one = held(agent);
         const done = one.queue.then(() => work(one));
         one.queue = done.catch(() => { });
         return done;
     };
-    /** Join the Hub as the agent, with its engine running. */
+    /** Join the Hub as the agent, with its engine running, or stopped if it was left so. */
     const open = async (agent, one) => {
         one.state = "starting";
         delete one.detail;
+        const { stopped } = stored[agent];
         let engine;
         try {
             const channel = await connect({
@@ -93,12 +109,13 @@ export async function startAgentProvider(options) {
                     engine = startEngine(ctx, {
                         store: createLocalStore(folderOf(agent)),
                         instructions: () => ASSISTANT_INSTRUCTIONS,
+                        stopped,
                     });
                 },
             });
             one.channel = channel;
             one.engine = engine;
-            one.state = "running";
+            one.state = stopped ? "stopped" : "running";
             void channel.closed.then(() => {
                 if (one.channel !== channel)
                     return;
@@ -113,22 +130,20 @@ export async function startAgentProvider(options) {
             throw error;
         }
     };
-    /** Cut its turn, close its channel, and wait until its engine has written all it will. */
+    /** Cut its turns, close its channel, and wait until its engine has written all it will. */
     const halt = async (one) => {
         const { channel, engine } = one;
         delete one.channel;
         if (!channel || !engine)
             return;
-        await engine.cancel();
+        await engine.close();
         channel.close();
         await channel.closed;
         await engine.settled();
     };
-    await Promise.all(Object.entries(stored).map(async ([agent, { stopped }]) => {
+    await Promise.all(Object.keys(stored).map(async (agent) => {
         const one = { state: "stopped", queue: Promise.resolve() };
         agents.set(agent, one);
-        if (stopped)
-            return;
         try {
             await open(agent, one);
         }
@@ -153,9 +168,6 @@ export async function startAgentProvider(options) {
         start(ctx) {
             ctx.exports.provider.implement({
                 creatable: async () => ({ creatables: [ASSISTANT] }),
-                skill: async ({ creatable, name, path: file }) => {
-                    throw new Refused("unknown", `${creatable} has no file ${file} of a skill ${name}.`);
-                },
                 async create({ creatable, name }) {
                     if (creatable !== ASSISTANT.id)
                         throw new Refused("unknown", `This provider offers no ${creatable}.`);
@@ -193,15 +205,31 @@ export async function startAgentProvider(options) {
                         return {};
                     stored[agent].stopped = false;
                     save();
-                    await open(agent, one);
+                    // One whose connection ended joins again; one that is only stopped goes on.
+                    if (!one.channel || !one.engine)
+                        await open(agent, one);
+                    else {
+                        one.engine.start();
+                        one.state = "running";
+                    }
                     return {};
                 }),
                 stop: ({ agent }) => inTurn(agent, async (one) => {
                     stored[agent].stopped = true;
                     save();
-                    await halt(one);
-                    one.state = "stopped";
-                    delete one.detail;
+                    // One whose connection ended joins again, stopped, so that it can be read.
+                    if (!one.channel || !one.engine)
+                        await open(agent, one);
+                    else {
+                        await one.engine.stop();
+                        one.state = "stopped";
+                    }
+                    return {};
+                }),
+                models: ({ agent }) => ofModel(engineOf(agent).models()),
+                // In the agent's turn, so a choice never lands after the agent is removed.
+                setModel: ({ agent, model }) => inTurn(agent, async () => {
+                    await ofModel(engineOf(agent).setModel(model));
                     return {};
                 }),
                 remove: ({ agent }) => inTurn(agent, async (one) => {

package/dist/node_modules/assistant/dist/src/tools.d.ts

@@ -1,30 +1,13 @@
-/**
- * The assistant's tools, gathered afresh for each model request. A `tools@1` slot gives whatever
- * it lists now, with its server's own input schemas. Each is offered as
- * `<slot>__<name>`, and a call runs through the slot, so the Hub checks and audits it like any
- * other.
- */
-import { type Tool } from "@agentorg/interfaces";
+import { type Outcome, type Tool } from "@agentorg/looper";
 import { type DescribedInterface } from "@agentorg/sdk";
 import type { z } from "zod";
-/** How a function call ended, as the model and the record see it. */
-export interface Outcome {
-    output: string;
-    ok: boolean;
-    code?: string;
-}
-interface Found {
-    tool: z.input<typeof Tool>;
-    run(input: unknown): Promise<Outcome>;
-}
-export type Tools = Map<string, Found>;
 /** A tool as its slot gives it, before it has the name a request offers it under. */
 export interface Candidate {
     slot: string;
     name: string;
     description?: string;
     parameters: Record<string, z.core.util.JSONType>;
-    run: Found["run"];
+    run(input: unknown): Promise<Outcome>;
 }
 /**
  * Something the model isn't offered, and why: `name` (past 64 characters as a function name),
@@ -36,18 +19,21 @@ export interface LeftOut {
     tool?: string;
     reason: string;
 }
-/** A function's output is cut to this many bytes of UTF-8, so one result can't fill a request. */
-export declare const MAX_OUTPUT: number;
 /** What a request can carry: its tools count, and, with the record and instructions, one frame. */
 export declare const MAX_TOOLS = 128;
 export declare const TOOLS_BUDGET: number;
-/** The code and message of anything a call or a turn can throw. */
+/** The first `length` UTF-16 units of `text`, never ending inside a surrogate pair. */
+export declare function head(text: string, length: number): string;
+/** The code and message of what a call through a slot threw. */
 export declare function codeOf(error: unknown): {
     code: string;
     message: string;
 };
-/** At most `MAX_OUTPUT` bytes of `text`, cut at a character, saying so when it is cut. */
-export declare function capped(text: string): string;
+/**
+ * A call through a slot, as the looper is told how it went: what the slot refuses is the looper's
+ * `Refusal`, with the code to show and the slot's own error as its cause.
+ */
+export declare const relayed: <T>(call: Promise<T>) => Promise<T>;
 /** Whether a slot is a `tools@1`, whose tools are whatever it lists. */
 export declare const listsTools: (described: DescribedInterface) => boolean;
 /**
@@ -66,9 +52,6 @@ export declare function listedBy(name: string, slot: {
  * when a request is full; what doesn't fit is reported, never sent.
  */
 export declare function offered(candidates: Candidate[]): {
-    tools: Tools;
+    tools: Tool[];
     leftOut: LeftOut[];
 };
-/** Run a function call through its slot: the result, or the refusal, as the function's output. */
-export declare function runTool(tools: Tools, name: string, args: string): Promise<Outcome>;
-export {};

package/dist/node_modules/assistant/dist/src/tools.js

@@ -5,10 +5,8 @@
  * other.
  */
 import { tools as toolsInterface } from "@agentorg/interfaces";
+import { Refusal } from "@agentorg/looper";
 import { describeInterface, NotConnected, OutcomeUnknown, Refused, } from "@agentorg/sdk";
-import { head } from "./history.js";
-/** A function's output is cut to this many bytes of UTF-8, so one result can't fill a request. */
-export const MAX_OUTPUT = 16 * 1024;
 /** What a request can carry: its tools count, and, with the record and instructions, one frame. */
 export const MAX_TOOLS = 128;
 export const TOOLS_BUDGET = 256 * 1024;
@@ -16,7 +14,12 @@ const MAX_NAME = 64;
 const MAX_DESCRIPTION = 1024;
 const encoder = new TextEncoder();
 const TOOLS_ID = describeInterface(toolsInterface).id;
-/** The code and message of anything a call or a turn can throw. */
+/** The first `length` UTF-16 units of `text`, never ending inside a surrogate pair. */
+export function head(text, length) {
+    const cut = text.slice(0, length);
+    return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut;
+}
+/** The code and message of what a call through a slot threw. */
 export function codeOf(error) {
     if (error instanceof Refused)
         return { code: error.code, message: error.message };
@@ -26,14 +29,16 @@ export function codeOf(error) {
         return { code: "outcome_unknown", message: error.message };
     return { code: "failed", message: "The call failed." };
 }
-/** At most `MAX_OUTPUT` bytes of `text`, cut at a character, saying so when it is cut. */
-export function capped(text) {
-    const bytes = encoder.encode(text);
-    if (bytes.byteLength <= MAX_OUTPUT)
-        return text;
-    const head = new TextDecoder().decode(bytes.subarray(0, MAX_OUTPUT - 16)).replace(/�$/, "");
-    return `${head}… (cut)`;
-}
+/**
+ * A call through a slot, as the looper is told how it went: what the slot refuses is the looper's
+ * `Refusal`, with the code to show and the slot's own error as its cause.
+ */
+export const relayed = (call) => call.catch((error) => {
+    const { code, message } = codeOf(error);
+    throw code === "failed" && !(error instanceof Refused)
+        ? error
+        : new Refusal(code, message, { cause: error });
+});
 /** Whether a slot is a `tools@1`, whose tools are whatever it lists. */
 export const listsTools = (described) => described.id === TOOLS_ID;
 /**
@@ -91,33 +96,7 @@ export function offered(candidates) {
             continue;
         }
         bytes += size;
-        tools.set(toolName, { tool, run });
-    }
-    return { tools, leftOut };
-}
-const failure = ({ code, message }) => JSON.stringify({ error: { code, message } });
-/** Run a function call through its slot: the result, or the refusal, as the function's output. */
-export async function runTool(tools, name, args) {
-    const refused = (code, message) => ({
-        output: failure({ code, message }),
-        ok: false,
-        code,
-    });
-    const found = tools.get(name);
-    if (!found)
-        return refused("unknown_tool", `No tool is named ${name.slice(0, 64)}.`);
-    let input;
-    try {
-        input = args.trim() === "" ? {} : JSON.parse(args);
-    }
-    catch {
-        return refused("invalid", "The arguments aren't JSON.");
-    }
-    try {
-        return await found.run(input);
-    }
-    catch (error) {
-        const { code, message } = codeOf(error);
-        return refused(code, message);
+        tools.set(toolName, { ...tool, run: (input) => relayed(run(input)) });
     }
+    return { tools: [...tools.values()], leftOut };
 }

package/dist/node_modules/assistant/package.json

@@ -20,6 +20,7 @@
   },
   "dependencies": {
     "@agentorg/interfaces": "0.0.0",
+    "@agentorg/looper": "0.0.0",
     "@agentorg/sdk": "0.0.0",
     "zod": "^4.6.7"
   },

package/dist/src/api.js

@@ -59,6 +59,10 @@ export function serveSocket(socket, deps) {
                 void (async () => {
                     if (!isName(slot) || !isName(method))
                         throw new Refused("invalid", "A call names its slot and method.");
+                    // A live ticket is for the gateway's own pipe at `/live`, never for a page to hold, under
+                    // whatever slot a page might expose it at.
+                    if (method === "live")
+                        throw new Refused("forbidden", "Open a live surface at /live.");
                     return deps.person.call(slot, method, input);
                 })()
                     .then((result) => send({ id, result }), (error) => send({ id, error: errorBody(error) }))

package/dist/src/folders.d.ts

@@ -0,0 +1,2 @@
+/** One `folders@1` call, checked as a call through the Hub would be. */
+export declare function callFolders(method: string, input: unknown): Promise<unknown>;

package/dist/src/folders.js

@@ -0,0 +1,45 @@
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import { FOLDERS_MAX, folders } from "@agentorg/interfaces";
+import { Refused } from "@agentorg/sdk";
+async function isFolder(at, entry) {
+    if (entry.isDirectory())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    return stat(join(at, entry.name)).then((found) => found.isDirectory(), () => false);
+}
+async function list(path) {
+    if (path !== undefined && !isAbsolute(path))
+        throw new Refused("invalid", "A folder's path starts at the top of the disk.");
+    const at = path === undefined ? homedir() : normalize(path);
+    const entries = await readdir(at, { withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT" || error.code === "ENOTDIR")
+            throw new Refused("unknown", "There's no such folder.");
+        throw new Refused("invalid", "That folder can't be read.");
+    });
+    // Dot folders stay out of the list, as in a file picker; a path can still be typed.
+    const shown = entries.filter((entry) => !entry.name.startsWith("."));
+    const kept = await Promise.all(shown.map((entry) => isFolder(at, entry)));
+    const names = shown
+        .filter((_, i) => kept[i])
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b))
+        .slice(0, FOLDERS_MAX);
+    const parent = dirname(at);
+    return {
+        path: at,
+        ...(parent === at ? {} : { parent }),
+        folders: names.map((name) => ({ name })),
+    };
+}
+/** One `folders@1` call, checked as a call through the Hub would be. */
+export function callFolders(method, input) {
+    if (method !== "list")
+        throw new Refused("invalid", `folders has no method ${method}.`);
+    const parsed = folders.methods.list.input.safeParse(input);
+    if (!parsed.success)
+        throw new Refused("invalid", `folders.list: ${parsed.error.message}`);
+    return list(parsed.data.path);
+}

package/dist/src/gateway.d.ts

@@ -1,12 +1,18 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import { Hub } from "@agentorg/hub";
 import { type Programs, type ProgramsOptions } from "./programs.js";
+/** A model's reply can take minutes; every other interface keeps the Hub's own limit. */
+export declare const HUB_OPTIONS: {
+    answerTimeoutsMs: {
+        [x: string]: number;
+    };
+};
 /** A route another part of the app adds, such as the model Actor's sign-in callback (step 5). */
 export type Route = (request: IncomingMessage, response: ServerResponse, url: URL) => void;
 export interface AppOptions {
     /** The Hub home. */
     home: string;
-    /** The gateway's port on 127.0.0.1; any free one by default. */
+    /** The gateway's port on 127.0.0.1; by default the kept sessions' if it can, else any free one. */
     port?: number;
     /** Where the shell's static files are; `@agentorg/shell`'s build by default. */
     shell?: string;