@agentorg/cli 0.0.8 → 0.0.9

package/README.md

@@ -18,10 +18,10 @@ AgentOrg creates and manages agents. Each part is a program that joins a Hub as
 - `@agentorg/hub`: the core. Its state, in `node:sqlite` in a private home: Actors, what each takes and offers, bindings and an audit trail. An Actor is a program that connects itself, with a credential. A binding is the grant, and it needs both ends: the export side (the provider, an Actor already bound to that export, or a manager) and the slot side (the consumer itself, or a manager). Through `hub.grants@1`, a caller with both ends binds; any other is refused. `hub.grants.expose({provider, export, to, as?})` exposes an `rpc` export to one Actor: a slot made on `to` at run time, typed by the export's interface and bound to it in one step, named `as` (one word of at most 48 characters) or by default the provider's name camelCased, `_` and the export's last part, made unique on `to` with `_2`, `_3`…. Its authority is a binding's, `to` being the consumer. Exposing the same export to the same Actor again gives its slot back. The slot goes with its binding: `unexpose({to, slot})`, `unbind`, the export no longer declared or either end closed; `hub.bindings` marks such a binding `exposed: true`. A manager is any Actor bound to `hub.bindings@1`. `hub.actors.create` can bind the new Actor's slots at once, with the creator's export side. The router serves it over WebSocket (`listen`), one yamux channel per Actor: a client's first stream is `hello` with its credential, then every `call` and `subscribe` stream is resolved through its binding, validated against the interface's JSON Schemas in both directions (ajv, 2020-12, in a pool of worker threads, each check under a time budget, since schemas come from Actors), forwarded to the provider with the caller named, and audited. An Actor learns which of its slots are bound from hello's result, then from a `slot` notice on each change. Every Actor's record in `hub.actors` says whether it is `connected`, holding a channel to the Hub now, and `hub.actors`' `changed` event names an Actor whose record may differ. When a redeclaration changes the interface of a bound name, the bindings whose other end doesn't declare the new one are dropped (audited as `binding.drop`). A refusal that names an Actor names it as "Name (id)", and says what the caller can do instead.
 - `@agentorg/cli`: AgentOrg as one app. `agentorg` runs a Hub, the person's gateway and the shell on loopback; see "The app: the person's gateway".
 - `@agentorg/mcp`: the built-in MCP provider, an external Actor exporting `unit.provider@1` as `provider`, and the only code that imports the MCP client (`@modelcontextprotocol/client`). `startMcpProvider({hubUrl, actorId, credential, dir})` runs it; its slot `actors` is bound to `hub.actors@1`. It offers two kinds: `url` attaches to a server over Streamable HTTP, sending `secrets.token` as a bearer token on every request (only over https or to this machine), and `command` starts a local server over stdio, with the basic environment and each of its `secrets` as an environment variable. Each connection joins the Hub as its own Actor exporting `tools@1` as `tools`: `list` and `call` go to the server, a tool's result comes back as text, with `failed` when the tool reported an error, and `changed` fires when the server's tools change or it goes or comes back. While a server is away `list` and `call` are refused `not_connected`, and the provider tries again after a backoff from 1 s doubling to 60 s (starting over after 10 minutes up). `create`'s `secrets` are write-only: the values cross once and go only to the provider's private `dir`, never into `params`, `target`, `detail`, status or a log (what a server prints is scrubbed of them). Each connection's Hub credential, parameters and secrets are kept in that folder, and connections rejoin at its next start. A server started by `command` is an ordinary process with the person's rights, outside the Hub's sandbox.
-- `@agentorg/manager`: management, an external Actor exporting `agents@1`, `connections@1`, `skills@1` and, as `settings`, `agent.settings@1`. `startManager({hubUrl, actorId, credential, dir})` runs it; bound to `hub.actors@1`, `hub.grants@1` and `hub.bindings@1`, it is a manager. A provider of either sort is connected by exposing its export to it: the Hub's slots are the only list. It keeps what the Hub can't know, in its private `dir`: each connection's origin, each agent's provider, creatable, instructions and skills, and the skills as `SKILL.md` folders. Status is read when asked, what a connection is exposed to is the Hub's bindings, and `secrets` go straight to the provider. `agents.create` is all or none: the provider makes the agent, its `settings` are bound, its skills added (one whose name is here keeps the one here), each connection it needs made or picked and exposed under its slot, and its chats exposed to the person; if a step fails, what this creation made is removed. The Hub drops that exposure when an agent comes back offering its chats in another shape, as after an upgrade, so management makes it again each time an agent connects. An agent reads only its own instructions and skills, and only it hears that they changed. `agents.models` and `agents.setModel` pass to the agent's provider, as `start` and `stop` do; stopping an agent is the one way to stop its work.
+- `@agentorg/manager`: management, an external Actor exporting `agents@1`, `connections@1`, `skills@1` and, as `settings`, `agent.settings@1`. `startManager({hubUrl, actorId, credential, dir})` runs it; bound to `hub.actors@1`, `hub.grants@1` and `hub.bindings@1`, it is a manager. A provider of either sort is connected by exposing its export to it: the Hub's slots are the only list. It keeps what the Hub can't know, in its private `dir`: each connection's origin, each agent's provider, creatable, instructions and skills, and the skills as `SKILL.md` folders. Status is read when asked, what a connection is exposed to is the Hub's bindings, and `secrets` go straight to the provider. `agents.create` is all or none: the provider makes the agent, its `settings` are bound, its skills added (one whose name is here keeps the one here), each connection it needs made or picked and exposed under its slot, and its chats exposed to the person; if a step fails, what this creation made is removed. The Hub drops that exposure when an agent comes back offering its chats in another shape, as after an upgrade, so management makes it again each time an agent connects. An agent reads only its own instructions and skills, and only it hears that they changed. `agents.models` and `agents.setModel` pass to the agent's provider, as `start` and `stop` do; stopping an agent stops all of its work.
 - `chatgpt`: the model, a program. It signs in with ChatGPT for the person's plan (`account.login@1`: OpenAI's OAuth for open-source apps, with dynamic registration, PKCE and a verified id_token; refresh tokens rotate, one refresh at a time) and serves `llm.session@1` on that plan through the Responses API, streamed and stored nowhere. The tokens never leave it: never in a reply, an event, a log or a refusal. It never uses an API key or API billing: a usage limit is refused `usage_limit`, with where to manage it. `startChatGPT({hubUrl, actorId, credential, dir})` runs it as an Actor exporting `login` and `session` with no slots at all: the sign-in is in `sign-in.json` in its private `dir` (mode 0600, written through before a change is acknowledged, since a rotated refresh token can't be had again), and it reaches OpenAI over the network directly, https only, with redirects returned as they are. Its tests run against an in-process fake of OpenAI, so none reaches OpenAI.
-- `@agentorg/looper`: an agent's loops, knowing nothing of what hosts them. `createLooper` is given a model client, the tools a request may call, a store for its records and where to say what it does, each as a plain type of its own, and takes a message with the name of the thread it came in on. What answers is a piece of work, with a loop of its own: a turn sends the work's messages and the tools to the model, runs what the model calls, and goes on until the model answers or the turn has made 200 calls. A message in a thread that a piece of work follows is given to that work, in code. One in a thread nothing follows is recorded and said at once, and put to the main loop, which makes one model request with one function, `route`, and no other tool: it is told the work that is in a turn now, by id and title, and what has come in (the newest eight messages waiting in the thread, the first 4,000 characters of each), and says that is new work, with a title, or points at one of those, which then follows that thread too. It is told to give a message to work in a turn only when the message points at that work explicitly. It decides for one thread at a time, on all that waits in the thread, keeps nothing between decisions and answers nobody; an answer that calls nothing, or names no work in a turn, starts new work. A message is kept once, in the thread it is shown in; a piece of work reads its own across the threads it follows, in the order it took them, and what comes of a model request is written in the thread of the newest message that request read. Turns of different pieces of work run side by side, four at once, and one more that only work that has already done something may take; a turn past that waits for a place, and while such work keeps five turns running new work goes on waiting. Sixteen turns may wait; past that a message that would start a turn is refused `busy`, or, if it is new work's first, kept and told to have failed `busy`. The main loop takes no place. A message said to work whose turn is running or waiting is recorded and said at once, and that turn takes it at its next model request. A turn that fails tells every thread it had taken a message in. A piece of work is marked in the store while a turn of it hasn't ended, and a thread while messages wait in it: `resume` goes on, once, with each that was cut off by a looper closing or going without closing, and the model of a turn that goes on is told to check what is already done. Messages the main loop couldn't place, or was stopped over, wait for their thread's next message, and all of them are put to it together. Stopped, it cuts every turn and the main loop, and takes no message until it is started. It imports no other package of this repository, and a test of its own fails if a file under its `src` does.
-- `assistant`: the agent engine and the bundled agent provider. The engine binds the looper to one agent: a chat is a thread, the model and the tools are the agent's slots, and the records go where the agent's are kept. A new chat's first message is read by the agent's main loop, which starts new work for it or, when it points at work in a turn, gives it to that work, which reads it with all it holds; a piece of work answers in the chat of the newest message it has read, and the chat is that work's from then on. The main loop's request is the looper's own words and one function: none of the agent's instructions, skills or tools. So an agent works on several things at once, as the looper's places allow. `startAgentProvider` runs an external Actor exporting `agent.provider@1` as `provider`, which offers one creatable, Assistant. Each agent is its own Actor on its own channel in that process, exporting `chat@1`, with the model behind `model: llm.session@1`, instructions and skills from an optional `settings: agent.settings@1`, and tools from each `tools@1` slot exposed to it. Its chats and model choice stay in the provider's private folder; the model is chosen through the provider's `models` and `setModel`, which name the agent. The agent is `working` while its main loop decides or any work's turn runs or waits. A stopped agent stays on its channel and runs no turn: its chats can still be read, and a message is refused `busy`. A message sent in a chat whose work is in a turn is recorded and shown at once, and that turn takes it at its next model request. A message that gets no answer leaves its chat with a `problem`, until that chat's next reply, and a message sent after it is read with what went unanswered. A turn that a restart cut off goes on once when the agent is back, the chat of the message it was answering showing one line that says so and its model told to check what is already done; one that ended, failed or was stopped doesn't.
+- `@agentorg/looper`: an agent's loops, knowing nothing of what hosts them. `createLooper` is given a model client, the tools a request may call, a store for its records and where to say what it does, each as a plain type of its own, and takes a message with the name of the thread it came in on. What answers is a piece of work, with a loop of its own, or, when a message needs no work, the main loop. A turn of a piece of work sends the work's messages and the tools to the model, runs what the model calls, and goes on until the model answers or the turn has made 200 calls. A message in a thread that a piece of work follows is given to that work, in code. One in a thread nothing follows is recorded and said at once, and the main loop decides on the thread: one model request with one function, `route`, and no other tool. It is told the work there is, each piece by id and title, whether it is in a turn or at rest, and whether its last turn failed, and the head of what it last said (twelve at most: those in a turn, then the latest at rest), and then the thread as a conversation (its newest eight messages, the first 4,000 characters of each). It says what came in is new work, with a title, or points at work there is, which then follows that thread too and, if at rest, starts a turn; or it answers itself, in text, when the message needs no work: that text is kept and said as the thread's reply, streamed as it is written, and the thread stays no work's, so its next message is decided the same way. Text beside a call is said too, and what came in is placed all the same, unless the call names work to stop. It is told to give a message to work only when the message points at that work explicitly, and to answer only what needs no tools and never to promise work. It speaks as whoever hosts it says (`voice`), told after its own words. It decides for one thread at a time, on all that waits in the thread, and keeps nothing between decisions but what the thread holds; an answer that says and calls nothing, or places with no work it was told of, starts new work. When a turn ends, the work's record is given the time, the head of what it last said, and whether the turn failed. One piece of work is stopped by saying so. The main loop may answer a message in a thread nothing follows by stopping work in a turn that the message asks to stop, when exactly one fits: it calls `route` with `stop`, which places nothing, and what it wrote is that thread's answer, or, when it wrote nothing, `Stopped.` if a turn was cut and `Nothing was stopped.` if not. Only that thread is told, and it stays no work's. And a message said in a thread a piece of work follows, which joins a turn of that work, is, beside that turn taking it, put to the main loop with that work alone, unless that turn has ended by then: one more request, in the looper's own words without `voice`, in which it may only stop that turn. These requests take their place among the decisions, one at a time; a message that starts a turn makes none, nor does one said before the work followed its thread, which the work takes with the thread. Stopping cuts the turn the main loop was told of, as the looper's own stop does for all, and no turn that began after it: a call already running finishes and its result is kept, and the work is at rest, not failed. Where the message joined the turn, what the main loop says of stopping it is kept at once in that thread as the work's own, and the work reads it after whatever the stopped turn still writes; if the store refuses it, the turn is cut all the same and the thread is told it failed. A message said to work whose stopped turn is still writing (a running call's result, or a reply being kept) is kept and said at once, as part of that turn's tail: the turn it starts takes over the stopped turn's place and shows as running, and makes its first request once the stopped turn has written what it will, so the model reads that call's result before the message. What the main loop was to hear of is not kept: a stop, a close or a restart before it has answered drops it, and the worker has the message all the same. A message is kept once, in the thread it is shown in; a piece of work reads its own across the threads it follows, in the order it took them, and what comes of a model request is written in the thread of the newest message that request read. Turns of different pieces of work run side by side, four at once, and one more that only work that has already done something may take; a turn past that waits for a place, and while such work keeps five turns running new work goes on waiting. Sixteen turns may wait; past that a message that would start a turn is refused `busy`, or, when the main loop had it, kept and told to have failed `busy`. The main loop takes no place. A message said to work whose turn is running or waiting is recorded and said at once, and that turn takes it at its next model request. A turn that fails tells every thread it had taken a message in. A piece of work is marked in the store while a turn of it hasn't ended, and a thread while it holds messages and no work has taken them: `resume` goes on, once, with each turn and each decision that was cut off by a looper closing or going without closing, and the model of a turn that goes on is told to check what is already done. 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 the thread holds. Stopped, it cuts every turn and the main loop, and takes no message until it is started. It imports no other package of this repository, and a test of its own fails if a file under its `src` does.
+- `assistant`: the agent engine and the bundled agent provider. The engine binds the looper to one agent: a chat is a thread, the model and the tools are the agent's slots, and the records go where the agent's are kept. Saying stop in a chat whose work is in a turn stops that turn, and no other work's; the agent's own Stop stops all. A message in a chat no work follows is read by the agent's main loop. It answers a plain message itself, as the agent, and that chat stays no work's; or it starts new work for it, or, when the message points at work there is, gives it to that work, which reads it with all it holds. A piece of work answers in the chat of the newest message it has read, and the chat is that work's from then on. The main loop's request is the looper's own words, then the agent's own instructions, which it speaks as, and one function: none of the agent's skills or tools. The request that only hears of a message said to work in a turn has the looper's words alone. So an agent works on several things at once, as the looper's places allow. `startAgentProvider` runs an external Actor exporting `agent.provider@1` as `provider`, which offers one creatable, Assistant. Each agent is its own Actor on its own channel in that process, exporting `chat@1`, with the model behind `model: llm.session@1`, instructions and skills from an optional `settings: agent.settings@1`, and tools from each `tools@1` slot exposed to it. Its chats and model choice stay in the provider's private folder; the model is chosen through the provider's `models` and `setModel`, which name the agent. The agent is `working` while its main loop decides or any work's turn runs or waits. A stopped agent stays on its channel and runs no turn: its chats can still be read, and a message is refused `busy`. A message sent in a chat whose work is in a turn is recorded and shown at once, and that turn takes it at its next model request. A message that gets no answer leaves its chat with a `problem`, until that chat's next reply, and a message sent after it is read with what went unanswered. A turn that a restart cut off goes on once when the agent is back, the chat of the message it was answering showing one line that says so and its model told to check what is already done; one that ended, failed or was stopped doesn't.
 
 ## Errors
 

package/dist/node_modules/@agentorg/computer/dist/types/generated/schema.d.ts

@@ -487,6 +487,9 @@ export interface components {
             /** @constant */
             type: "entries";
             id: string;
+            /** @description What the workspace is called: its folder's own name, and nothing of where it is. It comes with every entries answer, whichever folder was asked for, so that with path it names the folder. A computer in a container made before `workspace` was added sends none, and there path alone names the folder. It is `workspace` for a workspace the service made, and empty for one at the top of a disk. */
+            workspace?: string;
+            /** @description The folder as it was asked for: `.` for the workspace itself. */
             path: string;
             entries: {
                 name: string;

package/dist/node_modules/@agentorg/computer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentorg/computer",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {

package/dist/node_modules/@agentorg/computer-connector/dist/src/provider.js

@@ -90,7 +90,7 @@ function problems(unit, values, found, secrets) {
             wrong.push({ field: "address", message: `That address won't do. ${why}` });
     }
     else if (values.service !== LOCAL)
-        wrong.push({ field: "service", message: "Choose a service." });
+        wrong.push({ field: "service", message: "Choose where it resides." });
     if (values.access === "none") {
         if (values.browser !== true)
             wrong.push({
@@ -99,7 +99,7 @@ function problems(unit, values, found, secrets) {
             });
     }
     else if (!LEVELS.includes(values.access))
-        wrong.push({ field: "access", message: "Choose what it can do." });
+        wrong.push({ field: "access", message: "Choose what it reaches." });
     const workspace = fromHome(values.workspace);
     if (values.service === LOCAL && workspace !== undefined) {
         let folder = false;
@@ -313,7 +313,7 @@ export async function startComputerProvider(options) {
         // The folder, so the person can find it: the service says where one it made is.
         const folder = workspace ??
             (await computer.getInfo().then((info) => info.workspace, () => null));
-        const where = local ? "this machine" : new URL(reached.apiUrl).host;
+        const where = local ? "this computer" : new URL(reached.apiUrl).host;
         const on = isolation === "container" ? `${where}, in a container` : `${where}, no isolation`;
         const servers = [];
         if (access !== "none")

package/dist/node_modules/@agentorg/computer-connector/dist/src/unit.d.ts

@@ -7,7 +7,7 @@ export type Access = "read" | "files" | "terminal";
 export declare const LOCAL = "local";
 export declare const ANOTHER = "another";
 /** What to do when there is no service here: the app never starts or ships one. */
-export declare const INSTALL_STEPS = "No AgentComputer is running on this machine. Install it with npm install -g @agentorg/computer, start it with agentcomputer serve, and try again.";
+export declare const INSTALL_STEPS = "No AgentComputer is running on this computer. Install it with npm install -g @agentorg/computer, start it with agentcomputer serve, and try again.";
 /** How the service on this machine isolates its computers, if one is running. */
 export type Found = {
     isolation: "none" | "container";

package/dist/node_modules/@agentorg/computer-connector/dist/src/unit.js

@@ -7,12 +7,12 @@ const WITH_FILES = { slots: [{ name: COMPUTER }], skills: [skill("files"), skill
 export const LOCAL = "local";
 export const ANOTHER = "another";
 /** What to do when there is no service here: the app never starts or ships one. */
-export const INSTALL_STEPS = "No AgentComputer is running on this machine. Install it with npm install -g @agentorg/computer, start it with agentcomputer serve, and try again.";
+export const INSTALL_STEPS = "No AgentComputer is running on this computer. Install it with npm install -g @agentorg/computer, start it with agentcomputer serve, and try again.";
 const localLine = (found) => !found
     ? INSTALL_STEPS
     : found.isolation === "container"
-        ? "On this machine, started by you. Each computer is a container of its own."
-        : "On this machine, started by you. No isolation: it acts as you, and with a terminal it reaches everything you can.";
+        ? "On this computer, by a service you started. Each agent's computer is a container of its own."
+        : "On this computer, by a service you started. No isolation: it acts as you, and with a terminal it reaches everything you can.";
 /** The form as it stands now, with what was found on this machine. */
 export const computerUnit = (found) => ({
     id: COMPUTER,
@@ -23,12 +23,12 @@ export const computerUnit = (found) => ({
             id: "service",
             type: "choice",
             value: "string",
-            title: "Service",
+            title: "Where it resides",
             description: "Where its computer runs, and how that's kept apart from everything else.",
             // Not required: with none found, `check` says what to do, which is more than "fill this in".
             ...(found ? { default: LOCAL } : {}),
             options: [
-                { value: LOCAL, title: "This machine", description: localLine(found) },
+                { value: LOCAL, title: "This computer", description: localLine(found) },
                 {
                     value: ANOTHER,
                     title: "Another address",
@@ -41,7 +41,7 @@ export const computerUnit = (found) => ({
             type: "text",
             value: "string",
             title: "Address",
-            description: "The service's address, over https unless it's on this machine.",
+            description: "The service's address, over https unless it's on this computer.",
             required: true,
             visible: { field: "service", in: [ANOTHER] },
         },
@@ -54,25 +54,46 @@ export const computerUnit = (found) => ({
             required: true,
             visible: { field: "service", in: [ANOTHER] },
         },
+        {
+            id: "workspace",
+            type: "directory",
+            value: "string",
+            title: "Workspace directory",
+            description: "The folder it works in. Left empty, it's a folder with the agent's name in ~/Agents, made if it's missing. Its file tools stay inside it by a check, not a sandbox. Removing the agent leaves it.",
+            placeholder: "~/Agents/{name}",
+            visible: { field: "service", in: [LOCAL] },
+        },
+        {
+            id: "path",
+            type: "text",
+            value: "string",
+            title: "Workspace directory",
+            description: "A path on the service's machine. Removing the agent leaves it.",
+            visible: { field: "service", in: [ANOTHER] },
+        },
         {
             id: "access",
             authority: "setting",
             type: "choice",
             value: "string",
-            title: "What it can do",
+            title: "What it reaches",
             required: true,
             options: [
-                { value: "none", title: "Nothing", description: "It has no files and can't run anything." },
+                {
+                    value: "none",
+                    title: "No files or terminal",
+                    description: "It has no files and can't run anything.",
+                },
                 {
                     value: "read",
-                    title: "Read files",
-                    description: "It can read files in its working directory, but can't change them or run anything.",
+                    title: "Read-only files",
+                    description: "It can read files in its workspace directory, but can't change them or run anything.",
                     adds: WITH_FILES,
                 },
                 {
                     value: "files",
-                    title: "Read and change files",
-                    description: "It can read and change files in its working directory, but can't run anything.",
+                    title: "Files",
+                    description: "It can read and change files in its workspace directory, but can't run anything.",
                     adds: WITH_FILES,
                 },
                 {
@@ -91,28 +112,11 @@ export const computerUnit = (found) => ({
             authority: "setting",
             type: "toggle",
             value: "boolean",
-            title: "Browser",
+            title: "With a browser",
             description: "It can open web pages and act on them, in a browser of its own.",
             default: false,
             adds: { slots: [{ name: BROWSER_SLOT }], skills: [skill("browser")] },
         },
-        {
-            id: "workspace",
-            type: "directory",
-            value: "string",
-            title: "Working directory",
-            description: "The folder it works in. Left empty, it's a folder with the agent's name in ~/Agents, made if it's missing. Its file tools stay inside it by a check, not a sandbox. Removing the agent leaves it.",
-            placeholder: "~/Agents/{name}",
-            visible: { field: "service", in: [LOCAL] },
-        },
-        {
-            id: "path",
-            type: "text",
-            value: "string",
-            title: "Working directory",
-            description: "A path on the service's machine. Removing the agent leaves it.",
-            visible: { field: "service", in: [ANOTHER] },
-        },
     ],
     needs: [],
     gives: { slots: [], skills: [], results: [] },

package/dist/node_modules/@agentorg/computer-connector/package.json

@@ -20,7 +20,7 @@
     "test": "node --test \"dist/test/**/*.test.js\""
   },
   "dependencies": {
-    "@agentorg/computer": "0.0.10",
+    "@agentorg/computer": "0.0.11",
     "@agentorg/interfaces": "0.0.0",
     "@agentorg/mcp": "0.0.0",
     "@agentorg/sdk": "0.0.0",

package/dist/node_modules/@agentorg/interfaces/dist/src/index.d.ts

@@ -3,7 +3,6 @@ export { AgentStatus, Answers, agentProvider, Creatable, CreatableId, } from "./
 export { agentSettings, SKILL_FILE_MAX, SkillEntry, SkillName, SkillPath, } from "./agent-settings.js";
 export { CHAT_TITLE_MAX, ChatEntry, ChatMessage, ChatStatus, ChatTool, chat, } from "./chat.js";
 export { ConnectionKind, ConnectionParams, ConnectionSecrets, ConnectionState, ConnectionStatus, ConnectionTarget, ConnectionTool, } from "./connection.js";
-export { FOLDERS_MAX, folders } from "./folders.js";
 export { Actor, ActorState, AuditEntry, Binding, ExportEntry, hubActors, hubAudit, hubBindings, hubExports, hubGrants, SlotName, } from "./hub.js";
 export { kv } from "./kv.js";
 export { Item, llmSession, OutputItem, Tool } from "./llm-session.js";

package/dist/node_modules/@agentorg/interfaces/dist/src/index.js

@@ -3,7 +3,6 @@ export { AgentStatus, Answers, agentProvider, Creatable, CreatableId, } from "./
 export { agentSettings, SKILL_FILE_MAX, SkillEntry, SkillName, SkillPath, } from "./agent-settings.js";
 export { CHAT_TITLE_MAX, ChatEntry, ChatMessage, ChatStatus, ChatTool, chat, } from "./chat.js";
 export { ConnectionKind, ConnectionParams, ConnectionSecrets, ConnectionState, ConnectionStatus, ConnectionTarget, ConnectionTool, } from "./connection.js";
-export { FOLDERS_MAX, folders } from "./folders.js";
 export { Actor, ActorState, AuditEntry, Binding, ExportEntry, hubActors, hubAudit, hubBindings, hubExports, hubGrants, SlotName, } from "./hub.js";
 export { kv } from "./kv.js";
 export { Item, llmSession, OutputItem, Tool } from "./llm-session.js";

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

@@ -410,7 +410,7 @@ export declare const agents: import("@agentorg/sdk").RpcInterface<"agents", {
     }, z.core.$strip>, z.ZodObject<{}, z.core.$strip>>;
     /**
      * Stops the agent: whatever it was doing ends, and it does nothing until started; all else
-     * stays. This is the one way to stop an agent's work.
+     * stays.
      */
     stop: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
         agent: z.ZodString;

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

@@ -207,7 +207,7 @@ export const agents = defineInterface({
         start: method({ input: OnAgent, output: z.object({}) }),
         /**
          * Stops the agent: whatever it was doing ends, and it does nothing until started; all else
-         * stays. This is the one way to stop an agent's work.
+         * stays.
          */
         stop: method({ input: OnAgent, output: z.object({}) }),
         /** The models the agent can use, and the one chosen, as its provider says. */

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

@@ -50,12 +50,13 @@ export declare function createLoop(options: {
     log: Log;
 }): {
     /**
-     * Say a message in a thread the work follows. 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: string, thread: string) => Promise<{
         messageId: string;
+        turn?: number;
     }>;
     /**
      * Take the messages waiting in `thread`, which the work has come to follow, as its own, and
@@ -74,15 +75,23 @@ export declare function createLoop(options: {
     resumed: () => boolean;
     /** The status now. */
     state: () => Status;
+    /** The number of the turn running or waiting for its place, if one is. */
+    turn: () => number | undefined;
     /**
-     * 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.
      */
-    cancel(): Promise<void>;
+    cancel(only?: number, line?: {
+        text: string;
+        thread: string;
+    }): Promise<boolean>;
     /** Settles when the latest turn has written all it will. */
     settled: () => Promise<void>;
-    /** 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: () => Promise<void>;
     /** Streamed text of the model request running now, for the reply it becomes. */
     delta(requestId: string, text: string): void;

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

@@ -19,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. */
@@ -200,9 +209,13 @@ 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)
@@ -212,13 +225,15 @@ export function createLoop(options) {
         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, thread, joined) => {
@@ -227,24 +242,23 @@ export function createLoop(options) {
         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, took: new Set() };
+        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) {
@@ -256,19 +270,20 @@ export function createLoop(options) {
     };
     return {
         /**
-         * Say a message in a thread the work follows. 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, thread) => inOrder(async (cancelled) => {
-            if (turn) {
-                turn.took.add(thread);
-                return said(text, thread, true);
+            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.begun());
                 current.took.add(thread);
-                return { opened: await said(text, thread, false) };
+                return { opened: await said(text, thread, draining !== undefined) };
             }));
         }),
         /**
@@ -287,9 +302,8 @@ export function createLoop(options) {
             await start(false, async (current) => {
                 enter(current, await record.begun());
                 current.took.add(thread);
-                if ((await record.adopt(thread, false)) > 0)
+                if ((await record.adopt(thread, draining !== undefined)) > 0)
                     return { opened: undefined };
-                current.place?.leave();
                 return undefined;
             });
             return true;
@@ -301,7 +315,7 @@ export function createLoop(options) {
          * 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)
@@ -323,37 +337,62 @@ 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;
         },

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

@@ -1,3 +1,34 @@
+/**
+ * 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 work already begun. */
 export declare const PLACES = 4;
@@ -26,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`. */
@@ -42,15 +76,15 @@ export declare function createLooper(options: {
      * Say a message in a thread. It is recorded and said at once. In a thread a piece of work
      * follows it is that work's: with no turn of it running it starts one, which waits for a place
      * if none is free, and a turn running or waiting takes it at its next model request. In a
-     * thread nothing follows, the main loop says whose it is first. Refused `busy` while `WAITING`
-     * turns already wait and it would start one more, or while the looper is stopped; and
-     * `unavailable` once it has closed.
+     * 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 piece of work's turn now. A call already running finishes, and its result is kept. */
-    cancel: (work: string) => Promise<void | undefined>;
+    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`. */