@agentorg/cli 0.0.1 → 0.0.3

package/dist/src/layout.js

@@ -0,0 +1,90 @@
+import { randomBytes } from "node:crypto";
+import { Refused } from "@agentorg/sdk";
+/** The key the layout is kept under, in the person's store. */
+export const LAYOUT_KEY = "layout";
+/** Placements one layout holds; past it, `place` is refused. */
+const MAX_PLACEMENTS = 200;
+/**
+ * `layout@1`'s logic: what the person has placed, in order, kept in its own store, so it is state
+ * like any other Actor's. Writes run one at a time; each one tells `changed`. `isView` says whether
+ * a module is a `view` module of an Actor's package, the only thing `place` accepts.
+ */
+export class Layout {
+    #store;
+    #isView;
+    #changed;
+    #queue = Promise.resolve();
+    constructor(options) {
+        this.#store = options.store;
+        this.#isView = options.isView;
+        this.#changed = options.changed;
+    }
+    async get() {
+        return { home: await this.#read() };
+    }
+    /** Place a view, recording `by`, the Actor that asked, as the call's caller says. */
+    place(input, by) {
+        return this.#write((home) => {
+            if (!this.#isView(input.actor, input.module))
+                throw new Refused("invalid", `${input.actor}.${input.module} isn't a view module of a running package Actor.`);
+            if (home.length >= MAX_PLACEMENTS)
+                throw new Refused("quota", `A layout holds ${MAX_PLACEMENTS} placements at most.`);
+            const placement = {
+                id: randomBytes(9).toString("base64url"),
+                actor: input.actor,
+                module: input.module,
+                ...(input.title === undefined ? {} : { title: input.title }),
+                by,
+            };
+            return { home: insert(home, placement, input.after), result: { id: placement.id } };
+        });
+    }
+    remove(input) {
+        return this.#write((home) => {
+            at(home, input.id);
+            return { home: home.filter((placement) => placement.id !== input.id), result: {} };
+        });
+    }
+    move(input) {
+        return this.#write((home) => {
+            const placement = at(home, input.id);
+            if (input.after === input.id)
+                throw new Refused("invalid", "A placement can't follow itself.");
+            const rest = home.filter((other) => other.id !== input.id);
+            // Moved with no `after`, it goes first; placed with none, last.
+            return { home: insert(rest, placement, input.after ?? null), result: {} };
+        });
+    }
+    async #read() {
+        const { value } = await this.#store().get(LAYOUT_KEY);
+        return Array.isArray(value) ? value : [];
+    }
+    /** One write at a time: read, change, write back, then tell. */
+    #write(change) {
+        const run = this.#queue.then(async () => {
+            const { home, result } = change(await this.#read());
+            await this.#store().set(LAYOUT_KEY, home);
+            this.#changed();
+            return result;
+        });
+        this.#queue = run.catch(() => { });
+        return run;
+    }
+}
+function at(home, id) {
+    const found = home.find((placement) => placement.id === id);
+    if (!found)
+        throw new Refused("unknown", `No placement ${id}.`);
+    return found;
+}
+/** `placement` after the one with id `after`: first for `null`, last for `undefined`. */
+function insert(home, placement, after) {
+    if (after === undefined)
+        return [...home, placement];
+    if (after === null)
+        return [placement, ...home];
+    const index = home.findIndex((other) => other.id === after);
+    if (index < 0)
+        throw new Refused("unknown", `No placement ${after}.`);
+    return [...home.slice(0, index + 1), placement, ...home.slice(index + 1)];
+}

package/dist/src/model.d.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * How the first run reaches the Hub: the person's own calls, as `/api` makes them. A call that
+ * doesn't reach its provider rejects with an error named `NotConnected`, as `/api` names it.
+ */
+export interface PersonCalls {
+    call(slot: string, method: string, input: unknown): Promise<unknown>;
+}
+/** An export of a running Actor. */
+export interface Target {
+    actor: string;
+    export: string;
+}
+export interface FirstRunOptions {
+    /** Where the bundled archives and their `index.json` are; the app's own by default. */
+    bundled?: string;
+    /** What the model Actor's `web` connects to: the built-in `net`'s `egress` by default. */
+    egress?: Target;
+    /** Where the first run says what it did, and what it couldn't. */
+    log?: (message: string) => void;
+    /**
+     * Whether an Actor's process is connected (the Hub's `connected`): the first run waits for the
+     * installer's before it installs through it. Without it, it installs at once.
+     */
+    connected?: (actorId: string) => boolean;
+}
+export interface FirstRun {
+    /** The bundled packages by name, each added. */
+    packages: Record<string, string>;
+    /** The installer Actor and the model Actor, when they exist. */
+    installer?: string;
+    chatgpt?: string;
+}
+/**
+ * The first run, at every start after the person's store is bound: add the bundled packages,
+ * ensure the installer (made by the person, with its bindings, started), bind the person's
+ * `installer` to it, ensure the model Actor installed through it (`web` to `egress`, `store` to
+ * storage's `kv`, started), and bind the person's `login` to the model's. What is there already is
+ * kept: an installer or model Actor an earlier run made (recorded in the person's store) stays,
+ * of whatever build. A step that fails is logged and the rest still runs where it can; the next
+ * start tries again.
+ */
+export declare function firstRun(person: PersonCalls, options?: FirstRunOptions): Promise<FirstRun>;
+/**
+ * `/oauth/chatgpt`: where ChatGPT sends the browser back. It hands the whole callback address to
+ * the person's `login.complete`, then sends the tab on to `?result=<outcome>`, an address without
+ * the sign-in's code, so the code stays out of the tab's address and history; that page says how
+ * it went and links back to the shell. The code is never logged or shown, and no page sends a
+ * referrer.
+ */
+export declare function oauthRoute(person: PersonCalls): (request: IncomingMessage, response: ServerResponse, url: URL) => void;

package/dist/src/model.js

@@ -0,0 +1,230 @@
+// The app's first run: the bundled packages, the installer the person bootstraps, the model Actor
+// installed through it, and the person's `login` bound to that model. Every step reads what is
+// there before it acts, so each start converges on the same system and makes nothing twice.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The app's bundled packages, built into `dist/bundled` with the app. */
+const BUNDLED = join(dirname(fileURLToPath(import.meta.url)), "..", "bundled");
+const PERSON = "person";
+/** How long the first run waits for the installer's process to connect, and how often it looks. */
+const CONNECT_MS = 30_000;
+const CONNECT_EVERY_MS = 100;
+/**
+ * Where the first run keeps the Actors it made, in the person's store: it trusts those, never an
+ * Actor because of the name its package gives itself, which any package can take.
+ */
+const RECORD = "app/first-run";
+/** The installer's own module, and the model's. */
+const INSTALLER = "installer";
+const CHATGPT = "chatgpt";
+/**
+ * The installer's slots, each bound explicitly by the person at first run: the Hub's management
+ * (it is the person's delegated manager), seeding new Actors' stores, and the person's layout.
+ */
+const INSTALLER_BINDINGS = [
+    ...["packages", "actors", "grants", "exports", "bindings"].map((name) => ({
+        slot: `installer.${name}`,
+        provider: "hub",
+        export: name,
+    })),
+    { slot: "installer.storage", provider: "storage", export: "admin" },
+    { slot: "installer.layout", provider: PERSON, export: "layout" },
+];
+/**
+ * The first run, at every start after the person's store is bound: add the bundled packages,
+ * ensure the installer (made by the person, with its bindings, started), bind the person's
+ * `installer` to it, ensure the model Actor installed through it (`web` to `egress`, `store` to
+ * storage's `kv`, started), and bind the person's `login` to the model's. What is there already is
+ * kept: an installer or model Actor an earlier run made (recorded in the person's store) stays,
+ * of whatever build. A step that fails is logged and the rest still runs where it can; the next
+ * start tries again.
+ */
+export async function firstRun(person, options = {}) {
+    const log = options.log ?? (() => { });
+    const call = (slot, method, input = {}) => person.call(slot, method, input);
+    const attempt = async (what, run) => {
+        try {
+            return await run();
+        }
+        catch (error) {
+            log(`First run: ${what} didn't work: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    };
+    const bundled = options.bundled ?? BUNDLED;
+    const index = JSON.parse(readFileSync(join(bundled, "index.json"), "utf8"));
+    const packages = {};
+    for (const [name, file] of Object.entries(index)) {
+        const added = await attempt(`adding ${name}`, () => call("packages", "add", { path: join(bundled, file) }));
+        if (added)
+            packages[name] = added.hash;
+    }
+    // What earlier runs made, by role, kept while it isn't closed. Unread, nothing is made: a run that
+    // couldn't see its record would make a second installer.
+    const read = (await call("store", "get", { key: RECORD })).value;
+    const record = Object.fromEntries(Object.entries((read ?? {})).filter(([role, id]) => (role === "installer" || role === "chatgpt") && typeof id === "string"));
+    const remember = (role, actorId) => {
+        record[role] = actorId;
+        return call("store", "set", { key: RECORD, value: { ...record } });
+    };
+    // The assistant New agent installs is this build's, by hash: never a package by its name, which
+    // an agent's own package could take.
+    if (packages.assistant) {
+        record.assistant = packages.assistant;
+        await attempt("recording the assistant", () => call("store", "set", { key: RECORD, value: { ...record } }));
+    }
+    /** The Actor an earlier run made for `role`, unless it is gone or closed. */
+    const madeBefore = async (role) => {
+        const id = record[role];
+        if (!id)
+            return undefined;
+        const { actors } = await call("actors", "list");
+        return actors.find((a) => a.actorId === id && a.state !== "closed");
+    };
+    const running = async (actor) => {
+        if (actor.state !== "running")
+            await call("actors", "start", { actorId: actor.actorId });
+    };
+    const bindingsOf = async (actor) => (await call("bindings", "list", { actor })).bindings.filter((b) => b.consumer === actor);
+    /**
+     * Made before: each of these slots it lost is bound again, if its package declares the slot (an
+     * older build may not); one bound to another is kept.
+     */
+    const rebind = async (actor, bindings) => {
+        const { manifest } = await call("packages", "get", { hash: actor.package });
+        const declared = (slot) => {
+            const [module = "", name = ""] = slot.split(".");
+            return Object.hasOwn(manifest.modules[module]?.slots ?? {}, name);
+        };
+        const held = new Set((await bindingsOf(actor.actorId)).map((b) => b.slot));
+        for (const binding of bindings)
+            if (!held.has(binding.slot) && declared(binding.slot))
+                await call("grants", "bind", { consumer: actor.actorId, ...binding });
+    };
+    /** Bind the person's `slot` to `target`, unless it is bound already (to it, or to another). */
+    const personSlot = async (slot, target) => {
+        if ((await bindingsOf(PERSON)).some((b) => b.slot === slot))
+            return;
+        await call("grants", "bind", {
+            consumer: PERSON,
+            slot,
+            provider: target.actor,
+            export: target.export,
+        });
+    };
+    const installer = await attempt("the installer", async () => {
+        let actor = await madeBefore("installer");
+        if (!actor) {
+            const hash = packages[INSTALLER];
+            if (!hash)
+                return undefined;
+            const { actorId } = await call("actors", "create", {
+                name: "Installer",
+                package: hash,
+                bindings: INSTALLER_BINDINGS,
+            });
+            await remember("installer", actorId);
+            log("First run: made the installer.");
+            actor = { actorId, name: "Installer", package: hash, state: "created" };
+        }
+        else {
+            await rebind(actor, INSTALLER_BINDINGS);
+            if (actor.package !== packages[INSTALLER])
+                log("First run: kept the installer; the bundled build is added, not used.");
+        }
+        await personSlot("installer", { actor: actor.actorId, export: "installer.installer" });
+        await running(actor);
+        return actor.actorId;
+    });
+    const egress = options.egress ?? { actor: "net", export: "egress" };
+    const chatgptBindings = [
+        { slot: "model.web", provider: egress.actor, export: egress.export },
+        { slot: "model.store", provider: "storage", export: "kv" },
+    ];
+    const chatgpt = await attempt("ChatGPT", async () => {
+        const actor = await madeBefore("chatgpt");
+        if (actor) {
+            await rebind(actor, chatgptBindings);
+            if (actor.package !== packages[CHATGPT])
+                log("First run: kept ChatGPT; the bundled build is added, not used.");
+            await running(actor);
+            return actor.actorId;
+        }
+        const hash = packages[CHATGPT];
+        if (!hash || !installer)
+            return undefined;
+        // The installer's process may still be connecting: wait for it, then install once.
+        const { connected } = options;
+        if (connected) {
+            const until = Date.now() + CONNECT_MS;
+            while (!connected(installer)) {
+                if (Date.now() > until)
+                    throw new Error("the installer's process didn't connect; the next start tries again.");
+                await new Promise((done) => setTimeout(done, CONNECT_EVERY_MS));
+            }
+        }
+        const { actorId } = await call("installer", "install", {
+            package: hash,
+            name: "ChatGPT",
+            connections: Object.fromEntries(chatgptBindings.map((b) => [b.slot, { actor: b.provider, export: b.export }])),
+            start: true,
+        });
+        await remember("chatgpt", actorId);
+        log("First run: installed ChatGPT.");
+        return actorId;
+    });
+    if (chatgpt)
+        await attempt("binding the login", () => personSlot("login", { actor: chatgpt, export: "model.login" }));
+    return {
+        packages,
+        ...(installer ? { installer } : {}),
+        ...(chatgpt ? { chatgpt } : {}),
+    };
+}
+/** What the sign-in tab says, by outcome: `complete`'s refusal code, or `signed_in`. */
+const SAYS = {
+    signed_in: "Signed in to ChatGPT. You can close this tab.",
+    denied: "You declined on ChatGPT's page. Start again from AgentOrg when you're ready.",
+    expired: "This sign-in expired. Start again from AgentOrg.",
+};
+const FAILED = "The sign-in didn't work. Start again from AgentOrg.";
+/**
+ * `/oauth/chatgpt`: where ChatGPT sends the browser back. It hands the whole callback address to
+ * the person's `login.complete`, then sends the tab on to `?result=<outcome>`, an address without
+ * the sign-in's code, so the code stays out of the tab's address and history; that page says how
+ * it went and links back to the shell. The code is never logged or shown, and no page sends a
+ * referrer.
+ */
+export function oauthRoute(person) {
+    return (request, response, url) => {
+        if (request.method !== "GET")
+            return void response.writeHead(405).end();
+        const result = url.searchParams.get("result");
+        if (result !== null && [...url.searchParams.keys()].length === 1)
+            return page(response, result === "signed_in" ? 200 : 400, Object.hasOwn(SAYS, result) ? SAYS[result] : FAILED);
+        const after = (outcome) => {
+            response.writeHead(303, {
+                Location: `${url.pathname}?result=${encodeURIComponent(outcome)}`,
+                "Cache-Control": "no-store",
+                "Referrer-Policy": "no-referrer",
+            });
+            response.end();
+        };
+        void person.call("login", "complete", { callbackUrl: url.href }).then(() => after("signed_in"), (error) => {
+            const code = error?.code;
+            after(typeof code === "string" && Object.hasOwn(SAYS, code) ? code : "failed");
+        });
+    };
+}
+function page(response, status, text) {
+    response.writeHead(status, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+        "Referrer-Policy": "no-referrer",
+        "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'",
+    });
+    response.end(`<!doctype html><meta charset="utf-8"><title>AgentOrg</title>` +
+        `<style>body{font:15px system-ui,sans-serif;margin:20vh auto;max-width:28rem;padding:0 16px}</style>` +
+        `<p>${text}</p><p><a href="/">Back to AgentOrg</a></p>`);
+}

package/dist/src/signin.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Who may use the gateway: browser tabs with a session, made from a one-time code, and the CLI
+ * with the token in the home. A code works once, within 60 s, and travels only in a URL's
+ * fragment, which no request carries. A session is a random id the gateway holds in memory, so a
+ * restart signs every tab out. It is no cookie, which every port on 127.0.0.1 would receive: the
+ * shell keeps it in its origin's own storage and says it in its socket's first message.
+ */
+export declare class SignIn {
+    #private;
+    readonly cliToken: string;
+    constructor(options?: {
+        now?: () => number;
+    });
+    /** A new one-time code, for `/signin#<code>`. */
+    code(): string;
+    /** Trade a code for a session: once, within its time; anything else is `undefined`. */
+    redeem(code: unknown): string | undefined;
+    /** Whether a session is live. */
+    isSession(session: unknown): boolean;
+    /** Whether an `Authorization` header carries the CLI's token. */
+    isCli(authorization: string | undefined): boolean;
+}

package/dist/src/signin.js

@@ -0,0 +1,70 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+/** How long a sign-in code works. */
+const CODE_TTL_MS = 60_000;
+/** Codes not yet used; past it, the oldest go, so nothing grows without bound. */
+const MAX_CODES = 16;
+const SESSIONS_MAX = 256;
+const token = () => randomBytes(32).toString("base64url");
+const same = (a, b) => {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+};
+/**
+ * Who may use the gateway: browser tabs with a session, made from a one-time code, and the CLI
+ * with the token in the home. A code works once, within 60 s, and travels only in a URL's
+ * fragment, which no request carries. A session is a random id the gateway holds in memory, so a
+ * restart signs every tab out. It is no cookie, which every port on 127.0.0.1 would receive: the
+ * shell keeps it in its origin's own storage and says it in its socket's first message.
+ */
+export class SignIn {
+    cliToken = token();
+    #codes = new Map();
+    #sessions = new Set();
+    #now;
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+    }
+    /** A new one-time code, for `/signin#<code>`. */
+    code() {
+        const code = token();
+        this.#codes.set(code, this.#now() + CODE_TTL_MS);
+        while (this.#codes.size > MAX_CODES)
+            this.#codes.delete(this.#codes.keys().next().value);
+        return code;
+    }
+    /** Trade a code for a session: once, within its time; anything else is `undefined`. */
+    redeem(code) {
+        if (typeof code !== "string")
+            return undefined;
+        let found;
+        for (const known of this.#codes.keys())
+            if (same(known, code))
+                found = known;
+        if (!found)
+            return undefined;
+        const expires = this.#codes.get(found);
+        this.#codes.delete(found);
+        if (this.#now() > expires)
+            return undefined;
+        const session = token();
+        this.#sessions.add(session);
+        while (this.#sessions.size > SESSIONS_MAX)
+            this.#sessions.delete(this.#sessions.values().next().value);
+        return session;
+    }
+    /** Whether a session is live. */
+    isSession(session) {
+        if (typeof session !== "string")
+            return false;
+        for (const known of this.#sessions)
+            if (same(known, session))
+                return true;
+        return false;
+    }
+    /** Whether an `Authorization` header carries the CLI's token. */
+    isCli(authorization) {
+        const match = /^Bearer (\S+)$/.exec(authorization ?? "");
+        return !!match && same(match[1], this.cliToken);
+    }
+}

package/dist/src/transfer.d.ts

@@ -0,0 +1,30 @@
+import { Composition } from "@agentorg/interfaces";
+import type { z } from "zod";
+/** A package's or a system's file, sent or received: 64 MiB at most. */
+export declare const MAX_TRANSFER: number;
+/**
+ * A stored package as its archive. The Hub keeps a package as its verified tree, so the archive is
+ * made again from it, in the SDK's deterministic tar: the same bytes `agentorg build` writes, and
+ * so the same hash. `undefined` for a package the store doesn't hold.
+ */
+export declare function packageArchive(home: string, hash: string): Uint8Array | undefined;
+/**
+ * Run `use` with `bytes` in a private temporary file in the home, named `name`, then delete it,
+ * whatever happens: the Hub adds packages from a path.
+ */
+export declare function withTemporaryFile<T>(home: string, name: string, bytes: Uint8Array, use: (path: string) => Promise<T>): Promise<T>;
+export type SystemComposition = z.output<typeof Composition>;
+/** The hash each of a composition's Actors pins: its package is `name@version#hash`. */
+export declare function pinnedHashes(composition: SystemComposition): string[];
+/** A system file: `composition.json`, and each pinned package's archive under `packages/`. */
+export declare function writeSystem(composition: SystemComposition, archives: Map<string, Uint8Array>): Uint8Array;
+/**
+ * A system file, read strictly: a tar of regular files whose entries are exactly
+ * `composition.json` and `packages/sha256-<64 hex>.agentorg`, nothing else. A composition may
+ * come from anyone, so anything else is refused (`invalid`). Each archive's hash is checked
+ * against its name when it is added.
+ */
+export declare function readSystem(bytes: Uint8Array): {
+    composition: SystemComposition;
+    packages: Map<string, Uint8Array>;
+};

package/dist/src/transfer.js

@@ -0,0 +1,110 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { Composition } from "@agentorg/interfaces";
+import { Refused } from "@agentorg/sdk";
+import { readTar, writeTar } from "@agentorg/sdk/manifest";
+/** A package's or a system's file, sent or received: 64 MiB at most. */
+export const MAX_TRANSFER = 64 * 1024 * 1024;
+const HASH = /^sha256-[0-9a-f]{64}$/;
+/** A system file's package entries: exactly `packages/<hash>.agentorg`. */
+const PACKAGE_ENTRY = /^packages\/(sha256-[0-9a-f]{64})\.agentorg$/;
+/**
+ * A stored package as its archive. The Hub keeps a package as its verified tree, so the archive is
+ * made again from it, in the SDK's deterministic tar: the same bytes `agentorg build` writes, and
+ * so the same hash. `undefined` for a package the store doesn't hold.
+ */
+export function packageArchive(home, hash) {
+    if (!HASH.test(hash))
+        return undefined;
+    const root = join(home, "packages", hash);
+    const files = new Map();
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.isFile())
+                files.set(relative(root, path).split(sep).join("/"), readFileSync(path));
+        }
+    };
+    try {
+        walk(root);
+    }
+    catch {
+        return undefined;
+    }
+    return files.size ? writeTar(files) : undefined;
+}
+/**
+ * Run `use` with `bytes` in a private temporary file in the home, named `name`, then delete it,
+ * whatever happens: the Hub adds packages from a path.
+ */
+export async function withTemporaryFile(home, name, bytes, use) {
+    const dir = join(home, "tmp", randomBytes(9).toString("base64url"));
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        const path = join(dir, name);
+        writeFileSync(path, bytes, { mode: 0o600 });
+        return await use(path);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** The hash each of a composition's Actors pins: its package is `name@version#hash`. */
+export function pinnedHashes(composition) {
+    const hashes = new Set();
+    for (const { package: pinned } of Object.values(composition.actors)) {
+        const hash = pinned.slice(pinned.lastIndexOf("#") + 1);
+        if (HASH.test(hash))
+            hashes.add(hash);
+    }
+    return [...hashes];
+}
+/** A system file: `composition.json`, and each pinned package's archive under `packages/`. */
+export function writeSystem(composition, archives) {
+    const files = new Map([
+        ["composition.json", new TextEncoder().encode(`${JSON.stringify(composition, null, 2)}\n`)],
+    ]);
+    for (const [hash, archive] of archives)
+        files.set(`packages/${hash}.agentorg`, archive);
+    return writeTar(files);
+}
+/**
+ * A system file, read strictly: a tar of regular files whose entries are exactly
+ * `composition.json` and `packages/sha256-<64 hex>.agentorg`, nothing else. A composition may
+ * come from anyone, so anything else is refused (`invalid`). Each archive's hash is checked
+ * against its name when it is added.
+ */
+export function readSystem(bytes) {
+    let files;
+    try {
+        files = readTar(bytes);
+    }
+    catch (error) {
+        throw new Refused("invalid", `This isn't a system file: ${error.message}`);
+    }
+    const packages = new Map();
+    let composition;
+    for (const [path, data] of files) {
+        const entry = PACKAGE_ENTRY.exec(path);
+        if (entry)
+            packages.set(entry[1], data);
+        else if (path === "composition.json")
+            try {
+                composition = JSON.parse(new TextDecoder().decode(data));
+            }
+            catch {
+                throw new Refused("invalid", "composition.json isn't JSON.");
+            }
+        else
+            throw new Refused("invalid", `A system file holds no ${JSON.stringify(path)}.`);
+    }
+    if (composition === undefined)
+        throw new Refused("invalid", "A system file has a composition.json.");
+    const parsed = Composition.safeParse(composition);
+    if (!parsed.success)
+        throw new Refused("invalid", `composition.json doesn't fit: ${parsed.error.issues[0]?.message}`);
+    return { composition: parsed.data, packages };
+}

package/node_modules/@agentorg/hub/dist/src/build.d.ts

@@ -0,0 +1,17 @@
+/** What a package's source may total, paths and text: it fits in one frame. */
+export declare const MAX_SOURCE: number;
+/**
+ * The source as given, checked before anything is written or queued: its paths (no two the same
+ * but for case, none both a file and a folder), its size.
+ */
+export declare function checkSource(files: unknown): [string, string][];
+/**
+ * Build a package from its source, given as data, and add it with `add`: the files are written to
+ * a fresh folder in the home, built as `agentorg build` builds (importing only the SDK, the
+ * interfaces and zod by name, and nothing outside the folder; reading no tsconfig; at most 16
+ * modules and 16 MiB built), and the folder is gone after, whatever happened. A build that fails
+ * is `Refused("build")` with the build's message, which names no path outside the package.
+ */
+export declare function buildSource<T>(home: string, entries: [string, string][], sandbox: (paths: string[]) => string[], add: (file: string) => T): Promise<T>;
+/** Folders of builds a crash interrupted: removed when the Hub opens. */
+export declare function sweepBuilds(home: string): void;