@agentorg/cli 0.0.5 → 0.0.7

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

@@ -0,0 +1,42 @@
+/** Running the functions a model calls, and what is kept of their output. */
+import { codeOf } from "./types.js";
+/** A function's output keeps this many characters, so one result can't fill a request. */
+export const MAX_OUTPUT = 30_000;
+/**
+ * `text`, or its first and last `MAX_OUTPUT / 2` characters with what was cut between them: a
+ * failing command's error is at the end, and what it was doing at the start.
+ */
+export function capped(text) {
+    if (text.length <= MAX_OUTPUT)
+        return text;
+    // Between characters: never half of a surrogate pair at either cut.
+    const head = text.slice(0, MAX_OUTPUT / 2).replace(/[\uD800-\uDBFF]$/, "");
+    const tail = text.slice(-MAX_OUTPUT / 2).replace(/^[\uDC00-\uDFFF]/, "");
+    return `${head}\n… [${text.length - head.length - tail.length} characters cut] …\n${tail}`;
+}
+const failure = ({ code, message }) => JSON.stringify({ error: { code, message } });
+/** Run a function call: 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.find((tool) => tool.name === 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);
+    }
+}

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

@@ -0,0 +1,147 @@
+/**
+ * What the looper is given and what it gives back, in its own words. Whoever hosts it maps its own
+ * world onto these: the looper names no interface, no chat and no agent.
+ */
+import { z } from "zod";
+/** A JSON value. */
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+/** One item of a conversation as a model reads it: something said, a function call, or its output. */
+export declare const Item: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    content: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"function_call">;
+    callId: z.ZodString;
+    name: z.ZodString;
+    arguments: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"function_call_output">;
+    callId: z.ZodString;
+    output: z.ZodString;
+}, z.core.$strip>], "type">;
+export type Item = z.output<typeof Item>;
+/** What a model gives back: something it says, or a function it calls. */
+export type OutputItem = Exclude<Item, {
+    type: "function_call_output";
+}>;
+/** A function the model may call, as a request describes it. */
+export interface ToolSpec {
+    name: string;
+    description?: string;
+    /** The JSON Schema of its arguments. */
+    parameters: Record<string, Json>;
+}
+/** How a function call ended, as the model and the record see it. */
+export interface Outcome {
+    output: string;
+    ok: boolean;
+    /** Why it didn't, when `ok` is false. */
+    code?: string;
+}
+/**
+ * A function the model may call, with the way to run it. `run` gets the call's arguments, parsed;
+ * what it throws is the call's output, as a refusal: with its code when it is a `Refusal`.
+ */
+export interface Tool extends ToolSpec {
+    run(input: unknown): Promise<Outcome>;
+}
+/**
+ * The model: one stateless answer to a whole conversation. A request that can't be answered rejects,
+ * with a `Refusal` when there is a code to show. Text it writes while it answers is given to the
+ * looper's `delta`, with the request's id.
+ */
+export interface Model {
+    respond(request: {
+        requestId: string;
+        model?: string;
+        instructions: string;
+        input: Item[];
+        tools: ToolSpec[];
+    }): Promise<{
+        output: OutputItem[];
+    }>;
+    /** Stop the answer to `requestId`, if it is still being made; its `respond` then rejects. */
+    cancel(request: {
+        requestId: string;
+    }): Promise<unknown>;
+}
+/** Where the looper keeps its records: values by key, listed in key order a page at a time. */
+export interface Store {
+    get(input: {
+        key: string;
+    }): Promise<{
+        value?: Json | undefined;
+    }>;
+    set(input: {
+        key: string;
+        value: Json;
+    }): Promise<unknown>;
+    delete(input: {
+        key: string;
+    }): Promise<unknown>;
+    list(input: {
+        prefix?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        keys: string[];
+        next: string | null;
+    }>;
+}
+/** Where the looper says what an operator may want to know; nothing a thread shows. */
+export interface Log {
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * A message as a thread shows it. A `tool` message tells what the loop did: with `tool`, the call
+ * it stands for, said as `running` when it starts and again under the same id when it ends;
+ * without, its `text` says it in one line, as for calls that never ran or a turn that goes on
+ * after it was cut off.
+ */
+export interface Shown {
+    id: string;
+    role: "user" | "assistant" | "tool";
+    text: string;
+    /** An ISO 8601 time. */
+    at: string;
+    tool?: {
+        name: string;
+        state: "running" | "done" | "refused";
+        input?: string;
+        output?: string;
+    };
+}
+/** What a loop is doing. On `error`, `detail.code` is the refusal's code. */
+export type Status = {
+    state: "idle" | "thinking" | "tool";
+} | {
+    state: "error";
+    detail: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * Something refused, with a stable code a host can show or map. A host that refuses for a reason of
+ * its own can keep that reason as the `cause`.
+ */
+export declare class Refusal extends Error {
+    readonly name = "Refusal";
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The code and message of anything a call or a turn can throw. */
+export declare function codeOf(error: unknown): {
+    code: string;
+    message: string;
+};

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

@@ -0,0 +1,32 @@
+/**
+ * What the looper is given and what it gives back, in its own words. Whoever hosts it maps its own
+ * world onto these: the looper names no interface, no chat and no agent.
+ */
+import { z } from "zod";
+/** What one text of a model request can hold, and one name in it. */
+const Text = z.string().max(200_000);
+const Name = z.string().min(1).max(256);
+/** One item of a conversation as a model reads it: something said, a function call, or its output. */
+export const Item = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("message"), role: z.enum(["user", "assistant"]), content: Text }),
+    z.object({ type: z.literal("function_call"), callId: Name, name: Name, arguments: Text }),
+    z.object({ type: z.literal("function_call_output"), callId: Name, output: Text }),
+]);
+/**
+ * Something refused, with a stable code a host can show or map. A host that refuses for a reason of
+ * its own can keep that reason as the `cause`.
+ */
+export class Refusal extends Error {
+    name = "Refusal";
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/** The code and message of anything a call or a turn can throw. */
+export function codeOf(error) {
+    if (error instanceof Refusal)
+        return { code: error.code, message: error.message };
+    return { code: "failed", message: "The call failed." };
+}

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

@@ -0,0 +1,24 @@
+{
+  "name": "@agentorg/looper",
+  "version": "0.0.0",
+  "private": true,
+  "description": "An agent's loops: a model and its tools run on a record, taking messages by thread. It knows nothing of what hosts it.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
+    "test": "node --test \"dist/test/**/*.test.js\""
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  }
+}

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

@@ -0,0 +1,18 @@
+import type { Activity } from "./control.js";
+interface Entry extends Activity {
+    seq: number;
+    at: string;
+}
+export declare function createActivity(path: string, maxBytes?: number): {
+    add(entry: Activity): void;
+    /** Newest first; with `agent`, those it made or that were about it. */
+    read({ agent, before, limit }: {
+        agent?: string;
+        before?: number;
+        limit?: number;
+    }): {
+        entries: Entry[];
+        more: boolean;
+    };
+};
+export {};

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

@@ -0,0 +1,65 @@
+/**
+ * The control log: one line for each control call that changed something, and for each refusal.
+ * Append-only, and kept to a size: past it, the older half goes. It holds no message an agent
+ * sent, and no secret.
+ */
+import { appendFileSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+/** Past this, the older half of the log goes. */
+const MAX_BYTES = 4 * 1024 * 1024;
+export function createActivity(path, maxBytes = MAX_BYTES) {
+    const read = () => {
+        let text;
+        try {
+            text = readFileSync(path, "utf8");
+        }
+        catch {
+            return [];
+        }
+        return text.split("\n").flatMap((line) => {
+            try {
+                const entry = line ? JSON.parse(line) : undefined;
+                return entry && Number.isInteger(entry.seq) ? [entry] : [];
+            }
+            catch {
+                return [];
+            }
+        });
+    };
+    const sizeOf = () => {
+        try {
+            return statSync(path).size;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const kept = read();
+    let next = Math.max(-1, ...kept.map((one) => one.seq)) + 1;
+    let bytes = sizeOf();
+    // A line cut off by a crash ends here, so the next doesn't join it.
+    let torn = bytes > 0 && !readFileSync(path, "utf8").endsWith("\n");
+    return {
+        add(entry) {
+            const line = `${JSON.stringify({ seq: next++, at: new Date().toISOString(), ...entry })}\n`;
+            appendFileSync(path, torn ? `\n${line}` : line, { mode: 0o600 });
+            torn = false;
+            bytes += Buffer.byteLength(line);
+            if (bytes <= maxBytes)
+                return;
+            const all = read();
+            const newer = all.slice(Math.floor(all.length / 2));
+            const text = newer.map((one) => `${JSON.stringify(one)}\n`).join("");
+            writeFileSync(`${path}.tmp`, text, { mode: 0o600 });
+            renameSync(`${path}.tmp`, path);
+            bytes = Buffer.byteLength(text);
+        },
+        /** Newest first; with `agent`, those it made or that were about it. */
+        read({ agent, before, limit = 50 }) {
+            const matching = read()
+                .filter((one) => before === undefined || one.seq < before)
+                .filter((one) => agent === undefined || one.caller === agent || one.target === agent)
+                .reverse();
+            return { entries: matching.slice(0, limit), more: matching.length > limit };
+        },
+    };
+}

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

@@ -0,0 +1,134 @@
+/**
+ * AgentOrg control: what lets an agent reach what the person's own surface reaches, within the
+ * scopes the person set on its unit. The agent holds no authority of the Hub's. It calls
+ * management's tools, and management, which holds that authority, works out who is calling, what
+ * that caller's unit allows, and whether the target is within its reach.
+ */
+import { type chat, type FieldValues, type Problem, type Template, type Unit } from "@agentorg/interfaces";
+import { type Slot } from "@agentorg/sdk";
+import { z } from "zod";
+import type { AgentRecord, Offer, StackInput } from "./stack.js";
+export declare const AGENTS_UNIT = "control";
+export declare const AGENTS_SLOT = "control";
+/** How many agents one agent may have alive at once, at most and unless the person says. */
+export declare const LIMIT_MAX = 8;
+/** How many levels below an agent may exist, at most. */
+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;
+type Values = z.infer<typeof FieldValues>;
+type TheUnit = z.infer<typeof Unit>;
+type TheAgent = z.infer<typeof AgentRecord>;
+type TheTemplate = z.infer<typeof Template>;
+type TheProblem = z.infer<typeof Problem>;
+/** The agents unit's form, with what can be chosen today. */
+export declare function agentsUnit(templates: {
+    value: string;
+    title: string;
+    description?: string;
+}[], places: {
+    value: string;
+    title: string;
+}[]): TheUnit;
+/** A computer's reach: how far it can act, and what an agent sharing it is given. */
+export interface Reach {
+    access: string;
+    browser: boolean;
+    connections: {
+        slot: string;
+        connection: string;
+    }[];
+    skills: string[];
+    /** Which service it is on, when it says. */
+    service?: string;
+}
+/** How far an agent's own computer reaches now. */
+export declare function reachOf(record: TheAgent): Reach;
+/** What an agents unit may not ask for, given the computer of the agent that holds it. */
+export declare function reachProblems(values: Values, reach: {
+    access: string;
+    browser: boolean;
+}): TheProblem[];
+/** What the control tools use of an agent's chats. */
+type ChatCalls = Pick<Slot<typeof chat>["call"], "send" | "history" | "list" | "state" | "rename">;
+/** What management's own interfaces answer, called as the person would. */
+type Person = (iface: "agents" | "connections" | "skills", method: string, input: object, 
+/** Who it's made as: the agent, so what it makes is recorded as its own. */
+caller?: string) => Promise<any>;
+/** One control call that changed something, or was refused: never a message or a secret. */
+export interface Activity {
+    caller: string;
+    tool: string;
+    target?: string;
+    outcome: "done" | "refused";
+    reason?: string;
+}
+export interface ControlParts {
+    self: string;
+    records: {
+        agents: Record<string, TheAgent>;
+    };
+    creatingCount(): number;
+    catalog(): Promise<Offer[]>;
+    /** What is bound to an agent now, each as its slot and provider. */
+    boundTo(agent: string): Promise<Set<string>>;
+    templates(): TheTemplate[];
+    baseProviderNamed(name: string): Promise<string>;
+    serial<T>(key: string, work: () => T | Promise<T>): Promise<T>;
+    create(input: {
+        stack: StackInput;
+        name: string;
+        purpose: string;
+    }, caller: string, child: {
+        parent: {
+            agent: string;
+            name: string;
+        };
+        reach: Reach;
+        shares: {
+            slot: string;
+            connection: string;
+        }[];
+        skills: string[];
+        computer?: Reach;
+    }): Promise<{
+        agent: string;
+    }>;
+    nameOf(actor: string): Promise<string>;
+    /** A child's chat, once the Hub has told management of it. */
+    chatOf(agent: string): Promise<ChatCalls>;
+    statusOf(agent: string, provider: string): Promise<{
+        state: string;
+        detail?: string;
+    }>;
+    start(agent: string): Promise<unknown>;
+    stop(agent: string): Promise<unknown>;
+    remove(agent: string): Promise<unknown>;
+    /** Management's interfaces, as the person reaches them. */
+    person: Person;
+    /** Where each connection came from, to know which an agent made. */
+    madeBy(connection: string): string | undefined;
+    /** Whether the library has a skill of this name that this agent may see. */
+    hasSkill(name: string, caller: string): boolean;
+    /** The agent that saved a template, if one did. */
+    templateAuthor(id: string): string | undefined;
+    /** Keep a line of the control log. */
+    log(entry: Activity): void;
+}
+export declare function createControl(parts: ControlParts): {
+    list(caller: string): Promise<{
+        name: string;
+        description?: string | undefined;
+        inputSchema: Record<string, z.JSONType>;
+    }[]>;
+    /** A tool that ran and failed answers `failed`, for the caller's model to read. */
+    call(caller: string, name: string, input: unknown): Promise<{
+        output: string;
+        failed?: undefined;
+    } | {
+        output: string;
+        failed: true;
+    }>;
+};
+export {};