@agentorg/cli 0.0.5 → 0.0.7

package/dist/src/model.js

@@ -1,299 +0,0 @@
-// 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 earlier runs made
- * (recorded in the person's store) is kept and brought to this build: an installer or model Actor
- * on another package is upgraded in place, with its id, its store and its bindings; so is an agent
- * on an assistant build an earlier run bundled (by the hashes recorded, never by a package's
- * name). A binding an upgrade drops, its interface having changed, is made again where its ends
- * match now. 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 kept = (read ?? {});
-    // Every assistant build a run has bundled, by hash: an agent on one of them is this app's to
-    // bring to this build. Never a package by its name, which an agent's own package could take.
-    const earlier = [
-        ...(Array.isArray(kept.assistants) ? kept.assistants : []),
-        kept.assistant,
-    ].filter((hash) => typeof hash === "string");
-    const isWiring = (wiring) => typeof wiring === "object" &&
-        wiring !== null &&
-        ["consumer", "slot", "provider", "export"].every((key) => typeof wiring[key] === "string");
-    const record = {
-        ...Object.fromEntries(Object.entries(kept).filter(([role, id]) => (role === "installer" || role === "chatgpt" || role === "assistant") &&
-            typeof id === "string")),
-        ...(earlier.length ? { assistants: [...new Set(earlier)] } : {}),
-        ...(Array.isArray(kept.rebind) && kept.rebind.some(isWiring)
-            ? { rebind: kept.rebind.filter(isWiring) }
-            : {}),
-    };
-    const save = () => call("store", "set", { key: RECORD, value: { ...record } });
-    const remember = (role, actorId) => {
-        record[role] = actorId;
-        return save();
-    };
-    // The assistant New agent installs is this build's, by hash.
-    if (packages.assistant) {
-        record.assistant = packages.assistant;
-        record.assistants = [...new Set([...earlier, packages.assistant])];
-        await attempt("recording the assistant", save);
-    }
-    /** Run this build's package as an Actor an earlier run made, keeping its id and its store. */
-    const upgrade = async (actor, hash, what) => {
-        const { dropped: lost } = await call("actors", "upgrade", {
-            actorId: actor.actorId,
-            package: hash,
-        });
-        if (lost.length) {
-            record.rebind = [...(record.rebind ?? []), ...lost];
-            await attempt("recording the bindings to make again", save);
-        }
-        log(`First run: upgraded ${what} (${actor.actorId}) to this build${lost.length ? `; ${lost.length} of its bindings to make again` : ""}.`);
-        return { ...actor, package: hash };
-    };
-    /** 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 {
-            const hash = packages[INSTALLER];
-            const before = actor;
-            if (hash && actor.package !== hash)
-                actor =
-                    (await attempt("upgrading the installer", () => upgrade(before, hash, "the installer"))) ?? actor;
-            await rebind(actor, INSTALLER_BINDINGS);
-        }
-        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 () => {
-        let actor = await madeBefore("chatgpt");
-        if (actor) {
-            const hash = packages[CHATGPT];
-            const before = actor;
-            if (hash && actor.package !== hash)
-                actor =
-                    (await attempt("upgrading ChatGPT", () => upgrade(before, hash, "ChatGPT"))) ?? actor;
-            await rebind(actor, chatgptBindings);
-            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" }));
-    // Agents on an assistant build an earlier run bundled: brought to this build's assistant.
-    const assistant = packages.assistant;
-    if (assistant) {
-        const agents = await attempt("finding agents on earlier builds", async () => (await call("actors", "list")).actors.filter((a) => a.state !== "closed" && a.package !== assistant && earlier.includes(a.package)));
-        for (const agent of agents ?? [])
-            await attempt(`upgrading ${agent.name}`, () => upgrade(agent, assistant, `the agent ${agent.name}`));
-    }
-    // What upgrades dropped, this run or one that stopped before this, made again where its slot is
-    // still unbound: the ends now match, both on this build. One that can't be yet (an upgrade
-    // failed, or its ends still differ) is logged and kept for the next start.
-    if (record.rebind) {
-        const left = [];
-        for (const wiring of record.rebind) {
-            const made = await attempt(`binding ${wiring.slot} again`, async () => {
-                if ((await bindingsOf(wiring.consumer)).some((b) => b.slot === wiring.slot))
-                    return true;
-                await call("grants", "bind", wiring);
-                log(`First run: bound ${wiring.consumer}'s ${wiring.slot} again.`);
-                return true;
-            });
-            if (!made)
-                left.push(wiring);
-        }
-        if (left.length)
-            record.rebind = left;
-        else
-            delete record.rebind;
-        await attempt("recording the bindings made again", save);
-    }
-    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/rules.d.ts

@@ -1,71 +0,0 @@
-import type { PersonSide } from "./api.js";
-/** Where the rules that are on are kept, in the person's store: `{<id>: {on}}`. */
-export declare const RULES_KEY = "app/rules";
-/** An exposure a request asks for: `provider`'s `export`, as a slot on `to`. */
-export interface Exposure {
-    provider: string;
-    export: string;
-    to: string;
-    as?: string;
-}
-/** An exposure as a request asks for it: by whom, and which side it lacks. */
-export interface Asked extends Exposure {
-    requestedBy?: string;
-    /** The side the requester lacks: `export` when it holds the slot side, as `to` does. */
-    needs?: string;
-}
-/** An open request, as `hub.grants` tells it. */
-export interface Request {
-    requestId: string;
-    [field: string]: unknown;
-}
-/**
- * The exposure an open request asks for, if it asks for one. The one place that reads the Hub's
- * request shape for exposures.
- */
-export declare function exposureOf(request: Request): Asked | undefined;
-interface Definition {
-    id: string;
-    name: string;
-    says: string;
-    /** Whether this rule approves the exposure, read from the Hub as the person. */
-    approves(asked: Asked, person: PersonSide): Promise<boolean>;
-}
-/** The rules the app knows, in the order Settings lists them. */
-export declare const DEFINITIONS: readonly Definition[];
-export interface RulesOptions {
-    person: PersonSide;
-    /** Where the rules say what they approved, and what they couldn't. */
-    log?: (message: string) => void;
-    /** Told after a rule is turned on or off. */
-    changed?: () => void;
-}
-/**
- * The rules, for `app.rules@1`, and their engine: it hears each request the person could approve,
- * and goes through the open ones at start and whenever a rule is turned on. It approves a request a
- * rule that is on matches, as an approver does, with the call the request asked for; the Hub checks
- * that the person could grant it. It never declines: anything no rule matches stays for the person.
- */
-export declare class Rules {
-    #private;
-    constructor(options: RulesOptions);
-    list(): Promise<{
-        rules: {
-            id: string;
-            name: string;
-            says: string;
-            on: boolean;
-        }[];
-    }>;
-    set({ id, on }: {
-        id: string;
-        on: boolean;
-    }): Promise<Record<string, never>>;
-    /** Hear each new request, and settle the open ones. */
-    start(): Promise<void>;
-    /** Stop: nothing more is heard, and a sweep under way approves nothing more. */
-    close(): void;
-    /** Go through every open request the person could approve. */
-    sweep(): Promise<void>;
-}
-export {};

package/dist/src/rules.js

@@ -1,157 +0,0 @@
-// The person's named rules: conveniences the person turns on, held by the gateway, which acts on a
-// rule that is on as the person (a manager) and only within what the person could grant. Each rule
-// is named and visible, and off until the person turns it on; nothing else acts on provenance.
-import { Refused } from "@agentorg/sdk";
-/** Where the rules that are on are kept, in the person's store: `{<id>: {on}}`. */
-export const RULES_KEY = "app/rules";
-/**
- * The exposure an open request asks for, if it asks for one. The one place that reads the Hub's
- * request shape for exposures.
- */
-export function exposureOf(request) {
-    const { exposed, provider, export: name, consumer, slot, requestedBy, needs, } = request;
-    if (exposed !== true)
-        return undefined;
-    if (typeof provider !== "string" || typeof name !== "string" || typeof consumer !== "string")
-        return undefined;
-    return {
-        provider,
-        export: name,
-        to: consumer,
-        ...(typeof slot === "string" ? { as: slot } : {}),
-        ...(typeof requestedBy === "string" ? { requestedBy } : {}),
-        ...(typeof needs === "string" ? { needs } : {}),
-    };
-}
-/** The rules the app knows, in the order Settings lists them. */
-export const DEFINITIONS = [
-    {
-        id: "agents-use-what-they-install",
-        name: "Let an agent use what it installs",
-        says: "When an agent asks to use an Actor it installed, approve it.",
-        async approves(asked, person) {
-            // The agent asked for itself: it holds its slot side and lacks the export side.
-            if (asked.requestedBy !== asked.to || asked.needs !== "export")
-                return false;
-            // Provenance only: who the installer installed it for. The Hub grants nothing from it.
-            const actor = (await person.call("actors", "get", { actorId: asked.provider }));
-            return actor.state !== "closed" && actor.installedFor === asked.to;
-        },
-    },
-];
-/**
- * The rules, for `app.rules@1`, and their engine: it hears each request the person could approve,
- * and goes through the open ones at start and whenever a rule is turned on. It approves a request a
- * rule that is on matches, as an approver does, with the call the request asked for; the Hub checks
- * that the person could grant it. It never declines: anything no rule matches stays for the person.
- */
-export class Rules {
-    #person;
-    #log;
-    #changed;
-    /** Requests being settled, so an event and a sweep don't settle one twice. */
-    #settling = new Set();
-    #stop;
-    #closed = false;
-    /** Turning rules on and off, one at a time, so none is lost. */
-    #setting = Promise.resolve();
-    constructor(options) {
-        this.#person = options.person;
-        this.#log = options.log ?? (() => { });
-        this.#changed = options.changed ?? (() => { });
-    }
-    /** The ids of the rules that are on. */
-    async #on() {
-        const { value } = (await this.#person.call("store", "get", { key: RULES_KEY }));
-        const held = typeof value === "object" && value !== null ? value : {};
-        return new Set(DEFINITIONS.filter((rule) => held[rule.id]?.on === true).map((rule) => rule.id));
-    }
-    async list() {
-        const on = await this.#on();
-        return {
-            rules: DEFINITIONS.map(({ id, name, says }) => ({ id, name, says, on: on.has(id) })),
-        };
-    }
-    set({ id, on }) {
-        if (!DEFINITIONS.some((rule) => rule.id === id))
-            return Promise.reject(new Refused("unknown", `There is no rule ${id}.`));
-        const done = this.#setting.then(async () => {
-            const now = await this.#on();
-            if (on)
-                now.add(id);
-            else
-                now.delete(id);
-            await this.#person.call("store", "set", {
-                key: RULES_KEY,
-                value: Object.fromEntries([...now].map((ruleId) => [ruleId, { on: true }])),
-            });
-            this.#changed();
-            // Turned on, it settles what already waits for it; a sweep that fails is logged, as the
-            // rule is on either way.
-            if (on)
-                await this.sweep().catch((error) => this.#log(`The rules couldn't go through what waits: ${messageOf(error)}`));
-            return {};
-        });
-        this.#setting = done.catch(() => { });
-        return done;
-    }
-    /** Hear each new request, and settle the open ones. */
-    async start() {
-        await this.sweep();
-    }
-    /** Hear each new request, once; heard again after a subscription that ended. */
-    #listen() {
-        if (this.#closed)
-            return;
-        this.#stop ??= this.#person.subscribe("grants", "requested", (request) => void this.#settle(request), () => {
-            this.#stop = undefined;
-        });
-    }
-    /** Stop: nothing more is heard, and a sweep under way approves nothing more. */
-    close() {
-        this.#closed = true;
-        this.#stop?.();
-        this.#stop = undefined;
-    }
-    /** Go through every open request the person could approve. */
-    async sweep() {
-        this.#listen();
-        for (const request of await this.#open())
-            await this.#settle(request);
-    }
-    async #open() {
-        if (this.#closed)
-            return [];
-        return (await this.#person.call("grants", "requests", {}))
-            .requests;
-    }
-    async #settle(request) {
-        const asked = exposureOf(request);
-        if (!asked || this.#closed || this.#settling.has(request.requestId))
-            return;
-        this.#settling.add(request.requestId);
-        try {
-            const on = await this.#on();
-            for (const rule of DEFINITIONS) {
-                if (!on.has(rule.id) || !(await rule.approves(asked, this.#person)))
-                    continue;
-                // Still open just before: one the person declined, or that was settled meanwhile, is left.
-                if (!(await this.#open()).some((open) => open.requestId === request.requestId))
-                    return;
-                const { provider, export: name, to, as } = asked;
-                const exposure = { provider, export: name, to, ...(as ? { as } : {}) };
-                // As an approver approves: the call the request asked for, checked by the Hub.
-                await this.#person.call("grants", "expose", exposure);
-                this.#log(`Rule "${rule.name}" approved ${exposure.provider}'s ${exposure.export} for ${exposure.to}.`);
-                return;
-            }
-        }
-        catch (error) {
-            this.#log(`A rule couldn't settle request ${request.requestId}: ${messageOf(error)}`);
-        }
-        finally {
-            this.#settling.delete(request.requestId);
-        }
-    }
-}
-const messageOf = (error) => (error instanceof Error ? error.message : String(error));

package/dist/src/transfer.d.ts

@@ -1,30 +0,0 @@
-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

@@ -1,110 +0,0 @@
-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 };
-}