@agentorg/cli 0.0.5 → 0.0.7

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

@@ -0,0 +1,27 @@
+import { SkillEntry } from "@agentorg/interfaces";
+import type { z } from "zod";
+type Entry = z.infer<typeof SkillEntry>;
+export type SkillFiles = Record<string, string>;
+/** A skill's folder on this machine, as files; each must be text within a skill's limits. */
+export declare function readSkillFolder(folder: string): SkillFiles;
+/** The skills, each a `SKILL.md` folder under `dir`. What each says of itself is read from it. */
+export declare function createSkills(dir: string): {
+    has: (name: string) => boolean;
+    /** The name a skill's files give themselves; refused as `add` would refuse them. */
+    nameOf(files: SkillFiles): string;
+    entry: (name: string) => Entry | undefined;
+    read: (name: string, path?: string) => string | undefined;
+    list(): {
+        name: string;
+        description: string;
+    }[];
+    paths(name: string): string[];
+    /**
+     * Add a skill, or replace the one of its name, whole: it is never seen half written. With
+     * `expected`, a skill that calls itself anything else is refused before anything is touched.
+     */
+    add(files: SkillFiles, expected?: string): Entry;
+    remove(name: string): void;
+};
+export type Skills = ReturnType<typeof createSkills>;
+export {};

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

@@ -0,0 +1,152 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { SKILL_FILE_MAX, SkillEntry, SkillName, SkillPath } from "@agentorg/interfaces";
+import { Refused } from "@agentorg/sdk";
+import { parse } from "yaml";
+const MANIFEST = "SKILL.md";
+const MAX_FILES = 256;
+const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+/** What a `SKILL.md` says of itself, from its front matter, or refused. */
+function entryOf(text) {
+    const matter = FRONT_MATTER.exec(text)?.[1];
+    let fields;
+    try {
+        fields = matter === undefined ? undefined : parse(matter);
+    }
+    catch {
+        fields = undefined;
+    }
+    const entry = SkillEntry.safeParse(fields && typeof fields === "object"
+        ? {
+            name: fields.name,
+            description: fields.description,
+        }
+        : undefined);
+    if (!entry.success || entry.data.description.trim() === "")
+        throw new Refused("invalid", `${MANIFEST} needs front matter with a name (lowercase words joined by hyphens) and a description.`);
+    return entry.data;
+}
+/** Every file under `root`, by its path inside it; a link is refused, since it could leave it. */
+function walk(root, each) {
+    for (const found of readdirSync(root, { withFileTypes: true, recursive: true })) {
+        if (found.isDirectory())
+            continue;
+        const file = join(found.parentPath, found.name);
+        if (!found.isFile())
+            throw new Refused("invalid", `${relative(root, file)} isn't a plain file.`);
+        each(file, relative(root, file).split(sep).join("/"));
+    }
+}
+/** A skill's folder on this machine, as files; each must be text within a skill's limits. */
+export function readSkillFolder(folder) {
+    const files = {};
+    try {
+        if (!statSync(folder).isDirectory())
+            throw new Error("not a folder");
+    }
+    catch {
+        throw new Refused("invalid", `${folder} isn't a folder here.`);
+    }
+    walk(folder, (file, path) => {
+        if (basename(path) === ".DS_Store")
+            return;
+        if (Object.keys(files).length >= MAX_FILES)
+            throw new Refused("invalid", `A skill holds at most ${MAX_FILES} files.`);
+        if (!SkillPath.safeParse(path).success)
+            throw new Refused("invalid", `${path} isn't a name a skill's file can have.`);
+        const bytes = readFileSync(file);
+        if (bytes.length > SKILL_FILE_MAX)
+            throw new Refused("invalid", `${path} is over ${SKILL_FILE_MAX} bytes.`);
+        try {
+            files[path] = utf8.decode(bytes);
+        }
+        catch {
+            throw new Refused("invalid", `${path} isn't text.`);
+        }
+    });
+    return files;
+}
+/** The skills, each a `SKILL.md` folder under `dir`. What each says of itself is read from it. */
+export function createSkills(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const folderOf = (name) => join(dir, name);
+    const read = (name, path = MANIFEST) => {
+        try {
+            return readFileSync(join(folderOf(name), path), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const entry = (name) => {
+        const text = read(name);
+        return text === undefined ? undefined : entryOf(text);
+    };
+    return {
+        has: (name) => read(name) !== undefined,
+        /** The name a skill's files give themselves; refused as `add` would refuse them. */
+        nameOf(files) {
+            const manifest = files[MANIFEST];
+            if (manifest === undefined)
+                throw new Refused("invalid", `A skill needs a ${MANIFEST}.`);
+            return entryOf(manifest).name;
+        },
+        entry,
+        read,
+        list() {
+            return readdirSync(dir, { withFileTypes: true })
+                .filter((found) => found.isDirectory() && SkillName.safeParse(found.name).success)
+                .map((found) => entry(found.name))
+                .filter((found) => found !== undefined)
+                .sort((a, b) => a.name.localeCompare(b.name));
+        },
+        paths(name) {
+            const paths = [];
+            walk(folderOf(name), (_, path) => paths.push(path));
+            return paths.sort();
+        },
+        /**
+         * Add a skill, or replace the one of its name, whole: it is never seen half written. With
+         * `expected`, a skill that calls itself anything else is refused before anything is touched.
+         */
+        add(files, expected) {
+            const manifest = files[MANIFEST];
+            if (manifest === undefined)
+                throw new Refused("invalid", `A skill needs a ${MANIFEST}.`);
+            const found = entryOf(manifest);
+            if (expected !== undefined && found.name !== expected)
+                throw new Refused("invalid", `The skill ${expected} names itself ${found.name}.`);
+            // Named so `list` passes it by: a skill's name can't start with a dot.
+            const adding = join(dir, `.adding-${crypto.randomUUID()}`);
+            try {
+                for (const [path, text] of Object.entries(files)) {
+                    const file = join(adding, path);
+                    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+                    writeFileSync(file, text, { mode: 0o600 });
+                }
+                const final = folderOf(found.name);
+                const aside = join(dir, `.replaced-${crypto.randomUUID()}`);
+                const replacing = existsSync(final);
+                if (replacing)
+                    renameSync(final, aside);
+                try {
+                    renameSync(adding, final);
+                }
+                catch (error) {
+                    if (replacing)
+                        renameSync(aside, final);
+                    throw error;
+                }
+                rmSync(aside, { recursive: true, force: true });
+            }
+            finally {
+                rmSync(adding, { recursive: true, force: true });
+            }
+            return found;
+        },
+        remove(name) {
+            rmSync(folderOf(name), { recursive: true, force: true });
+        },
+    };
+}

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

@@ -0,0 +1,454 @@
+/**
+ * An agent built as a stack of units on a base: checking one, applying it all or none, keeping its
+ * instances, removing them last first, and the templates that prefill one.
+ */
+import { type agentProvider, type agents, type ConnectionStatus, Template, type Unit, type unitProvider } from "@agentorg/interfaces";
+import { type Log, type Slot } from "@agentorg/sdk";
+import { z } from "zod";
+import { type Reach } from "./control.js";
+import type { Skills } from "./skills.js";
+/** A unit an agent has: what its provider made, and what was filled in. Never a secret. */
+declare const UnitRecord: z.ZodObject<{
+    instance: z.ZodString;
+    provider: z.ZodString;
+    providerInstance: z.ZodString;
+    unit: z.ZodString;
+    title: z.ZodString;
+    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    needs: z.ZodRecord<z.ZodString, z.ZodString>;
+    results: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        handle: z.ZodString;
+    }, z.core.$strip>>;
+    connections: z.ZodArray<z.ZodObject<{
+        slot: z.ZodString;
+        connection: z.ZodString;
+    }, z.core.$strip>>;
+    skills: z.ZodArray<z.ZodString>;
+    viaMcp: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+/** What only management knows of an agent: where it came from, what it is told, and its skills. */
+export declare const AgentRecord: z.ZodObject<{
+    provider: z.ZodString;
+    creatable: z.ZodString;
+    instructions: z.ZodString;
+    skills: z.ZodArray<z.ZodString>;
+    purpose: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+    units: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        instance: z.ZodString;
+        provider: z.ZodString;
+        providerInstance: z.ZodString;
+        unit: z.ZodString;
+        title: z.ZodString;
+        values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+        needs: z.ZodRecord<z.ZodString, z.ZodString>;
+        results: z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            handle: z.ZodString;
+        }, z.core.$strip>>;
+        connections: z.ZodArray<z.ZodObject<{
+            slot: z.ZodString;
+            connection: z.ZodString;
+        }, z.core.$strip>>;
+        skills: z.ZodArray<z.ZodString>;
+        viaMcp: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strip>>>;
+    chat: z.ZodDefault<z.ZodString>;
+    parent: z.ZodOptional<z.ZodObject<{
+        agent: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    computer: z.ZodOptional<z.ZodObject<{
+        access: z.ZodString;
+        service: z.ZodOptional<z.ZodString>;
+        browser: z.ZodBoolean;
+        connections: z.ZodArray<z.ZodObject<{
+            slot: z.ZodString;
+            connection: z.ZodString;
+        }, z.core.$strip>>;
+        skills: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const Records: z.ZodObject<{
+    agents: z.ZodRecord<z.ZodString, z.ZodObject<{
+        provider: z.ZodString;
+        creatable: z.ZodString;
+        instructions: z.ZodString;
+        skills: z.ZodArray<z.ZodString>;
+        purpose: z.ZodOptional<z.ZodString>;
+        template: z.ZodOptional<z.ZodString>;
+        units: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            instance: z.ZodString;
+            provider: z.ZodString;
+            providerInstance: z.ZodString;
+            unit: z.ZodString;
+            title: z.ZodString;
+            values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+            needs: z.ZodRecord<z.ZodString, z.ZodString>;
+            results: z.ZodArray<z.ZodObject<{
+                kind: z.ZodString;
+                handle: z.ZodString;
+            }, z.core.$strip>>;
+            connections: z.ZodArray<z.ZodObject<{
+                slot: z.ZodString;
+                connection: z.ZodString;
+            }, z.core.$strip>>;
+            skills: z.ZodArray<z.ZodString>;
+            viaMcp: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strip>>>;
+        chat: z.ZodDefault<z.ZodString>;
+        parent: z.ZodOptional<z.ZodObject<{
+            agent: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>;
+        computer: z.ZodOptional<z.ZodObject<{
+            access: z.ZodString;
+            service: z.ZodOptional<z.ZodString>;
+            browser: z.ZodBoolean;
+            connections: z.ZodArray<z.ZodObject<{
+                slot: z.ZodString;
+                connection: z.ZodString;
+            }, z.core.$strip>>;
+            skills: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    connections: z.ZodRecord<z.ZodString, z.ZodObject<{
+        provider: z.ZodString;
+        kind: z.ZodString;
+        target: z.ZodString;
+        madeBy: z.ZodString;
+        madeFor: z.ZodOptional<z.ZodString>;
+        at: z.ZodString;
+    }, z.core.$strip>>;
+    templates: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        from: z.ZodOptional<z.ZodString>;
+        base: z.ZodObject<{
+            creatable: z.ZodString;
+            answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            provider: z.ZodString;
+        }, z.core.$strict>;
+        units: z.ZodArray<z.ZodObject<{
+            unit: z.ZodString;
+            values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+            needs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+            provider: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    instances: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    authors: z.ZodDefault<z.ZodObject<{
+        skills: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        templates: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type TheAgent = z.infer<typeof AgentRecord>;
+type TheRecords = z.infer<typeof Records>;
+type TheUnitRecord = z.infer<typeof UnitRecord>;
+type TheTemplate = z.infer<typeof Template>;
+type TheUnit = z.infer<typeof Unit>;
+type Agents = Slot<typeof agentProvider>["call"];
+type Units = Slot<typeof unitProvider>["call"];
+type AgentCalls = Slot<typeof agents>["call"];
+type CreateInput = Parameters<AgentCalls["create"]>[0];
+type CheckInput = Parameters<AgentCalls["check"]>[0];
+type AddInput = Parameters<AgentCalls["addUnit"]>[0];
+export type StackInput = Extract<CreateInput, {
+    stack: unknown;
+}>["stack"];
+type Provided<T> = {
+    actor: string;
+    call: T;
+};
+export interface Offer {
+    unit: TheUnit;
+    provider: string;
+    providerName: string;
+    /** None for management's own. */
+    call?: Units;
+}
+/** What makes an agent an agent's: who made it, and what of its parent's it shares. */
+interface Child {
+    parent: {
+        agent: string;
+        name: string;
+    };
+    reach: Reach;
+    shares: {
+        slot: string;
+        connection: string;
+    }[];
+    skills: string[];
+    computer?: Reach;
+}
+export interface StackParts {
+    self: string;
+    hub: {
+        actors: {
+            close(input: {
+                actorId: string;
+            }): Promise<unknown>;
+        };
+        grants: {
+            bind(input: {
+                consumer: string;
+                slot: string;
+                provider: string;
+                export: string;
+            }): Promise<unknown>;
+            expose(input: {
+                provider: string;
+                export: string;
+                to: string;
+            }): Promise<unknown>;
+            unexpose(input: {
+                to: string;
+                slot: string;
+            }): Promise<unknown>;
+        };
+        bindings: {
+            list(input: {
+                actor: string;
+            }): Promise<{
+                bindings: {
+                    consumer: string;
+                    interface: string;
+                    slot: string;
+                    provider: string;
+                }[];
+            }>;
+        };
+    };
+    records: TheRecords;
+    save(): void;
+    library: Skills;
+    creating: Map<string, TheAgent>;
+    log: Log;
+    /** Shipped with the app; one the person saves under the same id is the one used. */
+    shipped: TheTemplate[];
+    agentProviders(): Provided<Agents>[];
+    unitProviders(): Provided<Units>[];
+    recordOf(agent: string): TheAgent;
+    openActors(): Promise<Map<string, {
+        name: string;
+    }>>;
+    nameOf(actor: string): Promise<string>;
+    changed(agent: string): void;
+    fromEach<T, R>(list: T[], read: (one: T) => Promise<R>): Promise<R[]>;
+    exposeConnection(agent: string, connection: string, as?: string): Promise<string>;
+    closing(what: string, remove: () => Promise<void>): Promise<void>;
+    removeAgent(agent: string, provider: string): Promise<void>;
+}
+/** A unit that makes one connection and nothing else, by the field that names it, is a kind. */
+export declare const slotFieldOf: ({ needs, gives, form }: TheUnit) => string | undefined;
+export declare function createStacks(parts: StackParts): {
+    serial: <T>(agent: string, work: () => T | Promise<T>) => Promise<T>;
+    fromUnit: (record: TheAgent, given: {
+        slot: string;
+    } | {
+        skill: string;
+    }) => boolean;
+    unitMaking: (connection: string) => {
+        instance: string;
+        provider: string;
+        providerInstance: string;
+        unit: string;
+        title: string;
+        values: Record<string, string | number | boolean | string[]>;
+        needs: Record<string, string>;
+        results: {
+            kind: string;
+            handle: string;
+        }[];
+        connections: {
+            slot: string;
+            connection: string;
+        }[];
+        skills: string[];
+        viaMcp?: true | undefined;
+    } | undefined;
+    catalog: () => Promise<Offer[]>;
+    allTemplates: () => {
+        id: string;
+        title: string;
+        description: string;
+        from?: string | undefined;
+        base: {
+            creatable: string;
+            answers?: Record<string, string> | undefined;
+            provider: string;
+        };
+        units: {
+            unit: string;
+            values?: Record<string, string | number | boolean | string[]> | undefined;
+            needs?: Record<string, number> | undefined;
+            provider: string;
+        }[];
+    }[];
+    baseProviderNamed: (name: string) => Promise<string>;
+    /** How one connection a unit made stands, as its unit says. */
+    connectionStatus(unit: Pick<TheUnitRecord, "provider" | "providerInstance">, connection: string): Promise<z.infer<typeof ConnectionStatus>>;
+    /** The agent's stack, top to bottom: its exposures as units, then what providers made. */
+    read(agent: string, record: TheAgent, connectionStatus: (connection: string) => Promise<z.infer<typeof ConnectionStatus>>): Promise<{
+        units: {
+            instance: string;
+            provider: string;
+            unit: string;
+            title: string;
+            values: Record<string, string | number | boolean | string[]>;
+            needs: {};
+            status: Pick<{
+                state: "connected" | "connecting" | "down";
+                detail?: string | undefined;
+                tools: {
+                    name: string;
+                    description?: string | undefined;
+                }[];
+            }, "detail" | "state">;
+        }[];
+        tools: {
+            consumer: string;
+            interface: string;
+            slot: string;
+            provider: string;
+        }[];
+        instanceOfSkill: (name: string) => string;
+        instanceOfSlot: (slot: string) => string;
+    }>;
+    units(): Promise<{
+        bases: {
+            id: string;
+            title: string;
+            description: string;
+            instructions: string;
+            asks: {
+                id: string;
+                title: string;
+                description?: string | undefined;
+                optional?: true | undefined;
+            }[];
+            provider: string;
+            providerName: string;
+        }[];
+        units: {
+            id: string;
+            title: string;
+            description: string;
+            form: {
+                id: string;
+                type: string;
+                value: "boolean" | "number" | "secret" | "string" | "strings";
+                title: string;
+                description?: string | undefined;
+                required?: true | undefined;
+                default?: string | number | boolean | string[] | undefined;
+                authority?: "contacts" | "holds" | "instructs" | "runs" | "setting" | undefined;
+                placeholder?: string | undefined;
+                visible?: {
+                    field: string;
+                    in: (string | number | boolean | string[])[];
+                } | undefined;
+                options?: {
+                    value: string;
+                    title: string;
+                    description?: string | undefined;
+                    adds?: {
+                        slots: ({
+                            name: string;
+                        } | {
+                            field: string;
+                        })[];
+                        skills: ({
+                            name: string;
+                            files: string[];
+                        } | {
+                            field: string;
+                        })[];
+                    } | undefined;
+                }[] | undefined;
+                adds?: {
+                    slots: ({
+                        name: string;
+                    } | {
+                        field: string;
+                    })[];
+                    skills: ({
+                        name: string;
+                        files: string[];
+                    } | {
+                        field: string;
+                    })[];
+                } | undefined;
+                min?: number | undefined;
+                max?: number | undefined;
+                step?: number | undefined;
+                unit?: string | undefined;
+            }[];
+            needs: string[];
+            gives: {
+                slots: ({
+                    name: string;
+                } | {
+                    field: string;
+                })[];
+                skills: ({
+                    name: string;
+                    files: string[];
+                } | {
+                    field: string;
+                })[];
+                results: string[];
+            };
+            provider: string;
+            providerName: string;
+        }[];
+    }>;
+    templates: () => {
+        templates: {
+            id: string;
+            title: string;
+            description: string;
+            from?: string | undefined;
+            base: {
+                creatable: string;
+                answers?: Record<string, string> | undefined;
+                provider: string;
+            };
+            units: {
+                unit: string;
+                values?: Record<string, string | number | boolean | string[]> | undefined;
+                needs?: Record<string, number> | undefined;
+                provider: string;
+            }[];
+        }[];
+    };
+    /** With `agent`, it's that agent's own: it replaces nothing, and starts no program. */
+    saveTemplate(template: TheTemplate, agent?: string): Promise<{}>;
+    removeTemplate({ id }: {
+        id: string;
+    }, agent?: string): {};
+    check(input: CheckInput): Promise<{
+        problems: ({
+            field?: string | undefined;
+            message: string;
+        } & {
+            unit?: number;
+        })[];
+    }>;
+    /** All or none: what this made is undone, last first, if a step fails. */
+    create(input: CreateInput, caller: string, child?: Child): Promise<{
+        agent: string;
+    }>;
+    addUnit(input: AddInput, caller: string): Promise<{
+        instance: string;
+    }>;
+    removeUnit({ agent, instance }: {
+        agent: string;
+        instance: string;
+    }): Promise<{}>;
+    /** Every unit, last first: if one can't go, what is left can be tried again. */
+    removeAll(agent: string, record: TheAgent): Promise<void>;
+};
+export {};