@agentorg/cli 0.0.3 → 0.0.4

package/{node_modules → dist/node_modules}/@agentorg/hub/dist/src/state.js

@@ -23,6 +23,27 @@ const HUB_EXPORTS = {
     audit: hubAudit,
 };
 const NAME = /^[a-z][A-Za-z0-9_]*$/;
+/** The longest name of a slot made at run time, so a tool named `<slot>__<method>` fits. */
+const EXPOSED_MAX = 48;
+/** Exposure requests one Actor may have open toward one other at a time. */
+const MAX_OPEN_EXPOSURES = 32;
+/** The Actors that are the Hub itself: they take no slots. */
+const BUILTIN = new Set(["hub", "storage", "net"]);
+/**
+ * The default name of a slot exposing `exportName` of the Actor named `providerName`: the name's
+ * ASCII words camelCased, `_`, and the export's last part; the export's part alone when the name
+ * has no ASCII letters.
+ */
+export function exposedName(providerName, exportName) {
+    const words = (providerName.match(/[A-Za-z0-9]+/g) ?? []).map((word) => word.toLowerCase());
+    const joined = words
+        .map((word, i) => (i ? word[0]?.toUpperCase() + word.slice(1) : word))
+        .join("");
+    const letters = joined.replace(/^[^A-Za-z]+/, "");
+    const camel = letters && (letters[0] ?? "").toLowerCase() + letters.slice(1);
+    const part = exportName.slice(exportName.lastIndexOf(".") + 1);
+    return (camel ? `${camel}_${part}` : part).slice(0, EXPOSED_MAX);
+}
 const MEMBER = /^[a-z][A-Za-z0-9_]*(\.[a-z][A-Za-z0-9_]*)?$/;
 const now = () => new Date().toISOString();
 const digest = (secret) => createHash("sha256").update(secret).digest();
@@ -52,6 +73,9 @@ const MIGRATIONS = [
    CREATE TABLE audit (
      seq INTEGER PRIMARY KEY AUTOINCREMENT, at TEXT NOT NULL, actor TEXT NOT NULL,
      kind TEXT NOT NULL, details TEXT NOT NULL);`,
+    // Exposure: an Actor made for another (provenance only), and requests to expose.
+    `ALTER TABLE actors ADD COLUMN installed_for TEXT;
+   ALTER TABLE requests ADD COLUMN exposed INTEGER NOT NULL DEFAULT 0;`,
 ];
 /** Whether a process with this pid runs now. */
 function alive(pid) {
@@ -101,7 +125,11 @@ const bindingOf = (row) => ({
     interface: String(row.interface),
     madeBy: String(row.made_by),
     at: String(row.at),
+    ...(row.exposed ? { exposed: true } : {}),
 });
+/** A binding's columns, with whether its slot was made at run time. */
+const BINDING = `b.*, (SELECT d.dynamic FROM declarations d
+  WHERE d.actor = b.consumer AND d.side = 'slot' AND d.name = b.slot) AS exposed`;
 const requestOf = (row) => ({
     requestId: String(row.id),
     consumer: String(row.consumer),
@@ -112,6 +140,7 @@ const requestOf = (row) => ({
     requestedBy: String(row.requested_by),
     at: String(row.at),
     needs: row.needs === "slot" ? "slot" : "export",
+    ...(row.exposed ? { exposed: true } : {}),
 });
 const other = (side) => (side === "export" ? "slot" : "export");
 /**
@@ -302,7 +331,7 @@ export class HubState {
     // ── Actors ──────────────────────────────────────────────────────────────────
     #actor(actorId) {
         const row = this.#db
-            .prepare("SELECT id, name, package, state, restarts, last_exit FROM actors WHERE id = ?")
+            .prepare("SELECT id, name, package, state, restarts, last_exit, installed_for FROM actors WHERE id = ?")
             .get(actorId);
         return (row && {
             actorId: String(row.id),
@@ -311,12 +340,18 @@ export class HubState {
             state: row.state,
             restarts: Number(row.restarts),
             ...(row.last_exit ? { lastExit: JSON.parse(String(row.last_exit)) } : {}),
+            ...(row.installed_for ? { installedFor: String(row.installed_for) } : {}),
         });
     }
+    /** An Actor as a refusal names it: "Name (id)", or the id alone when there's no such Actor. */
+    named(actorId) {
+        const actor = this.#actor(actorId);
+        return actor ? `${actor.name} (${actor.actorId})` : actorId;
+    }
     actor(actorId) {
         const actor = this.#actor(actorId);
         if (!actor)
-            throw new Refused("unknown", `No Actor ${actorId}.`);
+            throw new Refused("unknown", `No Actor ${actorId}; hub.actors.list lists them.`);
         return actor;
     }
     /** The host sandbox's status changed: every package Actor's record (its `host`) differs. */
@@ -337,18 +372,24 @@ export class HubState {
     }
     #require(caller, hubExport) {
         if (!this.holds(caller, hubExport))
-            throw new Refused("forbidden", `${caller} isn't bound to hub.${hubExport}@1.`);
+            throw new Refused("forbidden", `${this.named(caller)} isn't bound to hub.${hubExport}@1; a manager (the person) can bind it, or do this for it.`);
     }
     /** Create an Actor: one that runs a package, or an external one, whose credential comes back once. */
     createActor(caller, input) {
         this.#require(caller, "actors");
+        if (input.for !== undefined) {
+            if (!this.isManager(caller))
+                throw new Refused("forbidden", `Only a manager says whom an Actor is made for; ${this.named(caller)} isn't one. Create it without for.`);
+            this.#open(input.for);
+        }
         const actorId = `act_${randomBytes(8).toString("hex")}`;
         const credential = input.package ? undefined : randomBytes(32).toString("base64url");
-        const insert = this.#db.prepare("INSERT INTO actors (id, name, package, state, credential, created_at) VALUES (?, ?, ?, 'created', ?, ?)");
+        const insert = this.#db.prepare("INSERT INTO actors (id, name, package, state, credential, created_at, installed_for) VALUES (?, ?, ?, 'created', ?, ?, ?)");
+        const madeFor = input.for ?? null;
         this.#transaction(() => {
             if (input.package) {
                 const { manifest } = this.package(input.package);
-                insert.run(actorId, input.name, input.package, null, now());
+                insert.run(actorId, input.name, input.package, null, now(), madeFor);
                 for (const [module, m] of Object.entries(manifest.modules))
                     for (const [side, members] of [
                         ["slot", m.slots],
@@ -365,23 +406,24 @@ export class HubState {
                     this.#insertBinding({ consumer: actorId, slot, provider: actorId, export: exported }, HUB);
             }
             else
-                insert.run(actorId, input.name, "external", digest(credential), now());
+                insert.run(actorId, input.name, "external", digest(credential), now(), madeFor);
             this.#audit(caller, "actor.create", {
                 actorId,
                 name: input.name,
                 package: input.package ?? "external",
+                ...(input.for === undefined ? {} : { for: input.for }),
             });
             this.#emit(() => this.#events.actorChanged?.(actorId));
             for (const initial of input.bindings ?? []) {
                 const wiring = { consumer: actorId, ...initial };
                 if (!this.sides(caller, wiring).export)
-                    throw new Refused("forbidden", `${caller} can't grant ${initial.provider}'s ${initial.export}.`);
+                    throw new Refused("forbidden", `${this.named(caller)} can't grant ${this.named(initial.provider)}'s ${initial.export}. Create it without that binding, then it can ask for it with hub.grants.request, or the provider or a manager can bind it.`);
                 if (!input.package && !this.declaration(actorId, "slot", initial.slot)) {
                     if (!NAME.test(initial.slot))
                         throw new Refused("invalid", `${JSON.stringify(initial.slot)} isn't a valid slot name.`);
                     const offered = this.declaration(initial.provider, "export", initial.export);
                     if (!offered)
-                        throw new Refused("unknown", `${initial.provider} offers no ${initial.export}.`);
+                        throw new Refused("unknown", `${this.named(initial.provider)} offers no ${initial.export}; hub.exports.list lists what it offers.`);
                     this.#declare(actorId, "slot", initial.slot, offered.iface, false);
                 }
                 this.#insertBinding(wiring, caller);
@@ -403,14 +445,14 @@ export class HubState {
         this.#require(caller, "actors");
         const actor = this.actor(actorId);
         if (actor.package === "external" || actor.package === "builtin")
-            throw new Refused("state", `${actorId} isn't a package Actor; it connects itself.`);
+            throw new Refused("state", `${this.named(actorId)} isn't a package Actor, so the Hub doesn't run its process.`);
         return actor;
     }
     /** Refused unless the caller may start the Actor and it can be started now; changes nothing. */
     checkStart(caller, actorId) {
         const actor = this.#packageActor(caller, actorId);
         if (actor.state !== "created" && actor.state !== "stopped")
-            throw new Refused("state", `${actorId} is ${actor.state}.`);
+            throw new Refused("state", `${this.named(actorId)} is ${actor.state === "running" ? "already running" : "closed and can't start again; make another"}.`);
     }
     /** Start a package Actor: recorded as running; the Hub spawns its process. */
     start(caller, actorId) {
@@ -424,7 +466,7 @@ export class HubState {
     stop(caller, actorId) {
         const actor = this.#packageActor(caller, actorId);
         if (actor.state !== "running")
-            throw new Refused("state", `${actorId} is ${actor.state}.`);
+            throw new Refused("state", `${this.named(actorId)} is ${actor.state}, not running.`);
         this.#transaction(() => {
             this.#db.prepare("UPDATE actors SET state = 'stopped' WHERE id = ?").run(actorId);
             this.#audit(caller, "actor.stop", { actorId });
@@ -436,7 +478,7 @@ export class HubState {
         this.#require(caller, "actors");
         const actor = this.actor(actorId);
         if (actorId === HUB || actorId === PERSON || actorId === STORAGE || actorId === NET)
-            throw new Refused("forbidden", `${actorId} can't be closed.`);
+            throw new Refused("forbidden", `${this.named(actorId)} is built in and can't be closed.`);
         if (actor.state === "closed")
             return;
         this.#transaction(() => {
@@ -557,7 +599,7 @@ export class HubState {
     #open(actorId) {
         const actor = this.actor(actorId);
         if (actor.state === "closed")
-            throw new Refused("state", `${actorId} is closed.`);
+            throw new Refused("state", `${this.named(actorId)} is closed for good; make another.`);
         return actor;
     }
     /**
@@ -568,7 +610,7 @@ export class HubState {
     declareExternal(actorId, declares) {
         const actor = this.#open(actorId);
         if (actor.package !== "external")
-            throw new Refused("forbidden", `${actorId} declares through its package.`);
+            throw new Refused("forbidden", `${this.named(actorId)} declares through its package; an Actor of another package declares otherwise.`);
         this.#transaction(() => {
             for (const [side, members] of [
                 ["slot", declares.slots],
@@ -578,6 +620,14 @@ export class HubState {
                     if (!NAME.test(name))
                         throw new Refused("invalid", `${JSON.stringify(name)} isn't a valid name.`);
                     this.#checked(iface);
+                    if (side === "slot") {
+                        // The Actor's own slots are its to name: an exposure under the same name yields,
+                        // with its binding, and requests to make one under it close.
+                        if (this.declaration(actorId, side, name)?.dynamic)
+                            this.#drop(actorId, side, name);
+                        for (const open of this.#pending("consumer = ? AND slot = ? AND exposed = 1", actorId, name))
+                            this.#decide(open, "closed");
+                    }
                     const known = this.declaration(actorId, side, name);
                     if (known &&
                         this.#isBound(actorId, side, name) &&
@@ -622,7 +672,7 @@ export class HubState {
         if (!MEMBER.test(name))
             throw new Refused("invalid", `${JSON.stringify(name)} isn't a valid export name.`);
         if (this.declaration(actorId, "export", name))
-            throw new Refused("conflict", `${actorId} already offers ${name}.`);
+            throw new Refused("conflict", `${this.named(actorId)} already offers ${name}; offer it under another name${this.declaration(actorId, "export", name)?.dynamic ? ", or withdraw it first" : ""}.`);
         this.#checked(iface);
         this.#transaction(() => {
             this.#declare(actorId, "export", name, iface, true);
@@ -634,7 +684,7 @@ export class HubState {
     withdraw(actorId, name) {
         const declared = this.declaration(actorId, "export", name);
         if (!declared?.dynamic)
-            throw new Refused("unknown", `${actorId} offers no ${name} at run time to withdraw.`);
+            throw new Refused("unknown", `${this.named(actorId)} offers no ${name} at run time to withdraw; only exports offered at run time can be.`);
         this.#transaction(() => {
             this.#drop(actorId, "export", name);
             this.#audit(actorId, "export.withdraw", { export: name });
@@ -673,7 +723,7 @@ export class HubState {
     // ── Bindings: a binding is the grant ────────────────────────────────────────
     binding(consumer, slot) {
         const row = this.#db
-            .prepare("SELECT * FROM bindings WHERE consumer = ? AND slot = ?")
+            .prepare(`SELECT ${BINDING} FROM bindings b WHERE consumer = ? AND slot = ?`)
             .get(consumer, slot);
         return row && bindingOf(row);
     }
@@ -691,9 +741,9 @@ export class HubState {
     bindings(actor) {
         const rows = actor
             ? this.#db
-                .prepare("SELECT * FROM bindings WHERE consumer = ? OR provider = ? ORDER BY rowid")
+                .prepare(`SELECT ${BINDING} FROM bindings b WHERE consumer = ? OR provider = ? ORDER BY b.rowid`)
                 .all(actor, actor)
-            : this.#db.prepare("SELECT * FROM bindings ORDER BY rowid").all();
+            : this.#db.prepare(`SELECT ${BINDING} FROM bindings b ORDER BY b.rowid`).all();
         return rows.map(bindingOf);
     }
     /** A manager is bound to the hub's `hub.bindings@1`; there is no other role. */
@@ -737,10 +787,10 @@ export class HubState {
         this.#open(wiring.provider);
         const slot = this.declaration(wiring.consumer, "slot", wiring.slot);
         if (!slot)
-            throw new Refused("unknown", `${wiring.consumer} has no slot ${wiring.slot}.`);
+            throw new Refused("unknown", `${this.named(wiring.consumer)} has no slot ${wiring.slot}; hub.grants.expose makes one at run time.`);
         const exported = this.declaration(wiring.provider, "export", wiring.export);
         if (!exported)
-            throw new Refused("unknown", `${wiring.provider} offers no ${wiring.export}.`);
+            throw new Refused("unknown", `${this.named(wiring.provider)} offers no ${wiring.export}; hub.exports.list lists what it offers.`);
         const fit = compareInterfaces(slot.iface, exported.iface);
         if (fit === "unrelated")
             throw new Refused("conflict", `${wiring.slot} takes ${slot.iface.id}; ${wiring.export} offers ${exported.iface.id}.`);
@@ -751,7 +801,7 @@ export class HubState {
     #insertBinding(wiring, madeBy) {
         const iface = this.#ends(wiring);
         if (this.binding(wiring.consumer, wiring.slot))
-            throw new Refused("bound", `${wiring.consumer}'s ${wiring.slot} is already bound; unbind it first.`);
+            throw new Refused("bound", `${this.named(wiring.consumer)}'s ${wiring.slot} is already bound; unbind it first.`);
         const at = now();
         this.#db
             .prepare("INSERT INTO bindings (consumer, slot, provider, export, interface, made_by, at) VALUES (?, ?, ?, ?, ?, ?, ?)")
@@ -761,14 +811,19 @@ export class HubState {
         this.#emit(() => this.#events.bound?.(record));
     }
     #removeBindings(where, ...params) {
-        const removed = this.#db.prepare(`SELECT * FROM bindings WHERE ${where}`).all(...params).map(bindingOf);
+        const removed = this.#db.prepare(`SELECT ${BINDING} FROM bindings b WHERE ${where}`).all(...params).map(bindingOf);
         if (!removed.length)
             return;
-        if (removed.some((b) => b.consumer === PERSON && b.provider === HUB))
+        if (removed.some((b) => b.consumer === PERSON && b.provider === HUB && !b.exposed))
             throw new Refused("forbidden", "The person's hub bindings stay, so someone can always manage the Hub.");
         // Requests whose requester held its end through these bindings can't be approved any more.
         const open = this.#pending("1 = 1");
         this.#db.prepare(`DELETE FROM bindings WHERE ${where}`).run(...params);
+        // A slot made at run time goes with its binding.
+        const dropExposed = this.#db.prepare("DELETE FROM declarations WHERE actor = ? AND side = 'slot' AND name = ? AND dynamic = 1");
+        for (const binding of removed)
+            if (binding.exposed)
+                dropExposed.run(binding.consumer, binding.slot);
         this.#emit(() => this.#events.unbound?.(removed));
         for (const pending of open)
             if (!this.#standing(pending.request))
@@ -783,7 +838,7 @@ export class HubState {
     bind(caller, wiring) {
         const sides = this.sides(caller, wiring);
         if (!sides.export && !sides.slot)
-            throw new Refused("forbidden", `${caller} holds neither end of this binding.`);
+            throw new Refused("forbidden", `${this.named(caller)} holds neither end of this binding: the export side is ${this.named(wiring.provider)}, an Actor bound to that export, or a manager; the slot side is ${this.named(wiring.consumer)} or a manager. Ask one of them.`);
         if (!(sides.export && sides.slot)) {
             const has = sides.export ? "export" : "slot";
             if (!this.#asked(wiring, has))
@@ -805,9 +860,9 @@ export class HubState {
     unbind(caller, consumer, slot) {
         const binding = this.binding(consumer, slot);
         if (!binding)
-            throw new Refused("unknown", `${consumer}'s ${slot} isn't bound.`);
+            throw new Refused("unknown", `${this.named(consumer)}'s ${slot} isn't bound.`);
         if (caller !== consumer && caller !== binding.provider && !this.isManager(caller))
-            throw new Refused("forbidden", `${caller} can't unbind ${consumer}'s ${slot}.`);
+            throw new Refused("forbidden", `${this.named(caller)} can't unbind ${this.named(consumer)}'s ${slot}: its consumer, its provider or a manager can.`);
         this.#transaction(() => {
             this.#removeBindings("consumer = ? AND slot = ?", consumer, slot);
             this.#audit(caller, "unbind", {
@@ -818,6 +873,84 @@ export class HubState {
             });
         });
     }
+    /**
+     * Expose an export to one Actor: a slot made on `to` at run time, typed by the export's
+     * interface and bound to it, in one step. The authority is a binding's, with `to` as the
+     * consumer: with both ends it is made (approving any open request for it); with one, it is a
+     * request to the other end's approvers, who approve by exposing the same; with neither, it is
+     * refused. The same export already exposed to `to` gives that slot back.
+     */
+    expose(caller, input) {
+        const to = this.#open(input.to);
+        const provider = this.#open(input.provider);
+        // Authority first, as bind's: a caller with neither end learns nothing more.
+        const ends = { consumer: to.actorId, provider: provider.actorId, export: input.export };
+        const sides = this.sides(caller, { ...ends, slot: "" });
+        if (!sides.export && !sides.slot)
+            throw new Refused("forbidden", `${this.named(caller)} can't expose ${input.export} of ${this.named(provider.actorId)} to ${this.named(to.actorId)}: that takes the provider's side (it, an Actor bound to that export, or a manager) or ${this.named(to.actorId)}'s (it, or a manager). Ask one of them to expose it.`);
+        if (BUILTIN.has(to.actorId))
+            throw new Refused("forbidden", `${this.named(to.actorId)} is the Hub itself and takes no slots.`);
+        const offered = this.declaration(provider.actorId, "export", input.export);
+        if (!offered)
+            throw new Refused("unknown", `${this.named(provider.actorId)} offers no ${input.export}.`);
+        if (offered.iface.kind !== "rpc")
+            throw new Refused("unsupported", `Only an rpc export can be exposed; ${input.export} is ${offered.iface.kind}.`);
+        const same = (row) => row.provider === provider.actorId && row.export === input.export;
+        const already = this.bindings(to.actorId).find((b) => b.consumer === to.actorId && b.exposed && same(b));
+        if (already && (input.as === undefined || input.as === already.slot))
+            return { exposed: true, slot: already.slot };
+        const requested = this.#db
+            .prepare("SELECT * FROM requests WHERE status = 'open' AND exposed = 1 AND consumer = ?")
+            .all(to.actorId).map(requestOf);
+        // An open request's name for this export is taken again, so approving needs no `as`.
+        const slot = input.as ??
+            requested.find(same)?.slot ??
+            this.#freeName(to.actorId, exposedName(provider.name, input.export), requested);
+        if (!NAME.test(slot) || slot.length > EXPOSED_MAX)
+            throw new Refused("invalid", `${JSON.stringify(slot)} isn't a slot name: one word of letters, digits and _, at most ${EXPOSED_MAX}.`);
+        // A request reserves no name: the first exposure made under it has it, and the rest close.
+        if (this.declaration(to.actorId, "slot", slot))
+            throw new Refused("conflict", `${this.named(to.actorId)} already has a slot ${slot}; name another with as.`);
+        const wiring = { ...ends, slot };
+        if (!(sides.export && sides.slot)) {
+            const has = sides.export ? "export" : "slot";
+            if (!this.#asked(wiring, has)) {
+                const mine = requested.filter((r) => r.requestedBy === caller && !(same(r) && r.slot === slot));
+                if (mine.length >= MAX_OPEN_EXPOSURES)
+                    throw new Refused("limit", `${this.named(caller)} has ${MAX_OPEN_EXPOSURES} exposures to ${this.named(to.actorId)} waiting; wait for them to be decided, or withdraw one by exposing it.`);
+                const request = this.#ask(caller, wiring, "", other(has), true);
+                return { exposed: false, slot, requestId: request.requestId };
+            }
+        }
+        this.#transaction(() => {
+            // Settled: this slot's requests (approved if for this export), and this export's requests
+            // to `to` under other names, which can't be made any more.
+            const pending = this.#pending("consumer = ? AND (slot = ? OR (exposed = 1 AND provider = ? AND export = ?))", wiring.consumer, wiring.slot, wiring.provider, wiring.export);
+            this.#declare(to.actorId, "slot", slot, offered.iface, true);
+            this.#insertBinding(wiring, caller);
+            for (const open of pending)
+                this.#decide(open, same(open.request) && open.request.slot === slot ? "approved" : "closed");
+            this.#audit(caller, "expose", { ...wiring });
+        });
+        return { exposed: true, slot };
+    }
+    /** A name free on `to`: `base`, else `base_2`, `base_3`…, each within the longest name. */
+    #freeName(to, base, requested) {
+        const taken = (name) => !!this.declaration(to, "slot", name) || requested.some((r) => r.slot === name);
+        for (let n = 1;; n++) {
+            const suffix = n === 1 ? "" : `_${n}`;
+            const name = base.slice(0, EXPOSED_MAX - suffix.length) + suffix;
+            if (!taken(name))
+                return name;
+        }
+    }
+    /** Remove a slot made by `expose`, with its binding: its consumer, its provider or a manager may. */
+    unexpose(caller, to, slot) {
+        const binding = this.binding(to, slot);
+        if (!binding?.exposed)
+            throw new Refused("unknown", `${this.named(to)} has no slot ${slot} made by expose; unbind a declared slot instead.`);
+        this.unbind(caller, to, slot);
+    }
     /**
      * Ask for a binding the caller holds one end of; it goes to the other end's approvers. Asking
      * again for the same wiring while a request is open returns that request.
@@ -825,9 +958,9 @@ export class HubState {
     request(caller, wiring, reason) {
         const sides = this.sides(caller, wiring);
         if (!sides.export && !sides.slot)
-            throw new Refused("forbidden", `${caller} holds neither end of this binding.`);
+            throw new Refused("forbidden", `${this.named(caller)} holds neither end of this binding: the export side is ${this.named(wiring.provider)}, an Actor bound to that export, or a manager; the slot side is ${this.named(wiring.consumer)} or a manager. Ask one of them.`);
         if (sides.export && sides.slot)
-            throw new Refused("state", `${caller} holds both ends: bind it instead.`);
+            throw new Refused("state", `${this.named(caller)} holds both ends: bind it instead.`);
         const has = sides.export ? "export" : "slot";
         if (this.#asked(wiring, has))
             throw new Refused("state", "The other end has asked already: bind to approve.");
@@ -841,10 +974,12 @@ export class HubState {
             .map(requestOf)
             .some((request) => this.#standing(request));
     }
-    #ask(caller, wiring, reason, needs) {
-        this.#ends(wiring);
+    #ask(caller, wiring, reason, needs, exposed = false) {
+        // An exposure's slot doesn't exist until it is approved; `expose` checked its ends.
+        if (!exposed)
+            this.#ends(wiring);
         if (this.binding(wiring.consumer, wiring.slot))
-            throw new Refused("bound", `${wiring.consumer}'s ${wiring.slot} is already bound.`);
+            throw new Refused("bound", `${this.named(wiring.consumer)}'s ${wiring.slot} is already bound; unbind it first.`);
         const open = this.#db
             .prepare("SELECT * FROM requests WHERE status = 'open' AND requested_by = ? AND consumer = ? AND slot = ? AND provider = ? AND export = ?")
             .get(caller, wiring.consumer, wiring.slot, wiring.provider, wiring.export);
@@ -857,12 +992,18 @@ export class HubState {
             reason,
             requestedBy: caller,
             at: now(),
+            ...(exposed ? { exposed: true } : {}),
         };
         this.#transaction(() => {
             this.#db
-                .prepare("INSERT INTO requests (id, consumer, slot, provider, export, reason, requested_by, at, status, needs) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'open', ?)")
-                .run(request.requestId, wiring.consumer, wiring.slot, wiring.provider, wiring.export, reason, caller, request.at, needs);
-            this.#audit(caller, "request", { ...wiring, needs, requestId: request.requestId });
+                .prepare("INSERT INTO requests (id, consumer, slot, provider, export, reason, requested_by, at, status, needs, exposed) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'open', ?, ?)")
+                .run(request.requestId, wiring.consumer, wiring.slot, wiring.provider, wiring.export, reason, caller, request.at, needs, exposed ? 1 : 0);
+            this.#audit(caller, "request", {
+                ...wiring,
+                needs,
+                requestId: request.requestId,
+                ...(exposed ? { exposed: true } : {}),
+            });
             const approvers = this.approvers(request).filter((a) => a !== caller);
             this.#emit(() => this.#events.requested?.(request, approvers));
         });
@@ -919,7 +1060,7 @@ export class HubState {
     decline(caller, requestId) {
         const request = this.requests(caller).find((r) => r.requestId === requestId);
         if (!request)
-            throw new Refused("unknown", `No open request ${requestId} for ${caller} to decide.`);
+            throw new Refused("unknown", `No open request ${requestId} for ${this.named(caller)} to decide; hub.grants.requests lists those it can.`);
         this.#transaction(() => {
             const [pending] = this.#pending("id = ?", requestId);
             if (pending)

package/{node_modules → dist/node_modules}/@agentorg/hub/dist/src/storage.d.ts

@@ -21,10 +21,11 @@ export declare class Storage {
      * Seed the store of (consumer, slot), all or none, if it holds nothing: `storage.admin@1`'s
      * `seed`. Each entry has kv@1's limits, and together they count toward the consumer's quota.
      */
+    /** `named` is the consumer as a refusal names it: "Name (id)". */
     seed(consumer: string, slot: string, entries: {
         key: string;
         value: unknown;
-    }[]): void;
+    }[], named?: string): void;
     /** Every store of an Actor, gone: it was closed for good. */
     deleteConsumer(consumer: string): void;
     /**

package/{node_modules → dist/node_modules}/@agentorg/hub/dist/src/storage.js

@@ -139,7 +139,8 @@ export class Storage {
      * Seed the store of (consumer, slot), all or none, if it holds nothing: `storage.admin@1`'s
      * `seed`. Each entry has kv@1's limits, and together they count toward the consumer's quota.
      */
-    seed(consumer, slot, entries) {
+    /** `named` is the consumer as a refusal names it: "Name (id)". */
+    seed(consumer, slot, entries, named = consumer) {
         const keys = new Set();
         const rows = entries.map(({ key, value }) => {
             checkKey(key);
@@ -159,7 +160,7 @@ export class Storage {
             if (this.#db
                 .prepare("SELECT 1 FROM store WHERE consumer = ? AND slot = ? LIMIT 1")
                 .get(consumer, slot))
-                throw new Refused("not_empty", `The store of ${consumer}.${slot} isn't empty.`);
+                throw new Refused("not_empty", `The store of ${named}'s ${slot} isn't empty.`);
             const used = this.#db.prepare("SELECT used FROM usage WHERE consumer = ?").get(consumer);
             if (Number(used?.used ?? 0) + total > this.#limits.maxPerConsumer)
                 throw new Refused("quota", `An Actor's stores hold at most ${this.#limits.maxPerConsumer} bytes.`);

package/{node_modules → dist/node_modules}/@agentorg/hub/package.json

@@ -23,9 +23,12 @@
   },
   "dependencies": {
     "@agentorg/interfaces": "0.0.0",
+    "@agentorg/kit": "0.0.0",
     "@agentorg/sdk": "0.0.0",
     "@agentorg/wire": "0.0.0",
     "ajv": "^8.20.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
     "ws": "^8.22.1",
     "zod": "^4.6.7"
   },

package/{node_modules → dist/node_modules}/@agentorg/interfaces/dist/src/hub.d.ts

@@ -36,8 +36,8 @@ export declare const hubPackages: import("@agentorg/sdk").RpcInterface<"hub.pack
     /**
      * Build a package from its source, given as data (`package.json` and files under `src/`, up to
      * 768 KiB), and add it as `add` does. It's `agentorg build`'s build, reading no tsconfig; its
-     * files import only `@agentorg/sdk`, `@agentorg/interfaces` and `zod` by name, and nothing outside
-     * the package's folder, never by a pattern. A build that fails is
+     * files import only `@agentorg/sdk`, `@agentorg/interfaces`, `zod`, `react`, `react-dom` and
+     * `@agentorg/kit` by name, and nothing outside the package's folder, never by a pattern. A build that fails is
      * `Refused("build")` with the build's message, so the source can be fixed and built again.
      */
     build: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
@@ -75,6 +75,7 @@ export declare const Actor: z.ZodObject<{
         reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     views: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    installedFor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** One line of an Actor's log, from its `ctx.log` or its process's own output. */
 export declare const LogLine: z.ZodObject<{
@@ -93,11 +94,13 @@ export declare const hubActors: import("@agentorg/sdk").RpcInterface<"hub.actors
     /**
      * With a package, an Actor that runs it; without, an external one, whose credential is returned
      * once. `bindings` wire the new Actor's slots at once, with the caller's export-side authority
-     * (the creation is the slot side's yes), for example to its own `hub.grants@1`.
+     * (the creation is the slot side's yes), for example to its own `hub.grants@1`. `for` names
+     * the Actor it is made for, recorded as `installedFor`; only a manager may give it.
      */
     create: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
         name: z.ZodString;
         package: z.ZodOptional<z.ZodString>;
+        for: z.ZodOptional<z.ZodString>;
         bindings: z.ZodOptional<z.ZodArray<z.ZodObject<{
             slot: z.ZodString;
             provider: z.ZodString;
@@ -130,6 +133,7 @@ export declare const hubActors: import("@agentorg/sdk").RpcInterface<"hub.actors
                 reason: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
             views: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            installedFor: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     get: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
@@ -156,6 +160,7 @@ export declare const hubActors: import("@agentorg/sdk").RpcInterface<"hub.actors
             reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         views: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        installedFor: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     start: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
         actorId: z.ZodString;
@@ -193,6 +198,8 @@ export declare const hubActors: import("@agentorg/sdk").RpcInterface<"hub.actors
         actor: z.ZodString;
     }, z.core.$strip>>;
 }, 1>;
+/** A slot made at run time: one segment, at most 48 characters, so tools named from it fit. */
+export declare const SlotName: z.ZodString;
 export declare const Binding: z.ZodObject<{
     consumer: z.ZodString;
     slot: z.ZodString;
@@ -201,6 +208,7 @@ export declare const Binding: z.ZodObject<{
     interface: z.ZodString;
     madeBy: z.ZodString;
     at: z.ZodString;
+    exposed: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
 export declare const BindingRequest: z.ZodObject<{
     consumer: z.ZodString;
@@ -215,6 +223,7 @@ export declare const BindingRequest: z.ZodObject<{
     reason: z.ZodString;
     requestedBy: z.ZodString;
     at: z.ZodString;
+    exposed: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
 /**
  * `hub.grants@1`: binding with the caller's own authority, so it is safe to give any Actor. A
@@ -241,6 +250,32 @@ export declare const hubGrants: import("@agentorg/sdk").RpcInterface<"hub.grants
         consumer: z.ZodString;
         slot: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{}, z.core.$strip>>;
+    /**
+     * Expose an `rpc` export to one Actor: a slot made on `to`, typed by the export's interface,
+     * named `as` (by default the provider's name camelCased, `_`, and the export's last part, made
+     * unique on `to`), and bound to the export, in one step. Its authority is a binding's: with
+     * both ends it is made; with one, it is a request to the other end's approvers, who approve it
+     * by calling `expose` with the request's fields. The same export already exposed to `to`
+     * gives that slot back.
+     */
+    expose: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
+        provider: z.ZodString;
+        export: z.ZodString;
+        to: z.ZodString;
+        as: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodUnion<readonly [z.ZodObject<{
+        exposed: z.ZodLiteral<true>;
+        slot: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        exposed: z.ZodLiteral<false>;
+        slot: z.ZodString;
+        requestId: z.ZodString;
+    }, z.core.$strip>]>>;
+    /** Remove a slot made by `expose`, with its binding: as `unbind`, the consumer, the provider or a manager may. */
+    unexpose: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
+        to: z.ZodString;
+        slot: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{}, z.core.$strip>>;
     request: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
         consumer: z.ZodString;
         slot: z.ZodString;
@@ -265,6 +300,7 @@ export declare const hubGrants: import("@agentorg/sdk").RpcInterface<"hub.grants
             reason: z.ZodString;
             requestedBy: z.ZodString;
             at: z.ZodString;
+            exposed: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     decline: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
@@ -290,6 +326,7 @@ export declare const hubGrants: import("@agentorg/sdk").RpcInterface<"hub.grants
             reason: z.ZodString;
             requestedBy: z.ZodString;
             at: z.ZodString;
+            exposed: z.ZodOptional<z.ZodLiteral<true>>;
             status: z.ZodEnum<{
                 approved: "approved";
                 closed: "closed";
@@ -313,6 +350,7 @@ export declare const hubGrants: import("@agentorg/sdk").RpcInterface<"hub.grants
         reason: z.ZodString;
         requestedBy: z.ZodString;
         at: z.ZodString;
+        exposed: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>>;
     /**
      * A request the subscriber could approve, or made, was approved (its binding made), declined,
@@ -332,6 +370,7 @@ export declare const hubGrants: import("@agentorg/sdk").RpcInterface<"hub.grants
             reason: z.ZodString;
             requestedBy: z.ZodString;
             at: z.ZodString;
+            exposed: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strip>;
         status: z.ZodEnum<{
             approved: "approved";
@@ -357,6 +396,7 @@ export declare const hubBindings: import("@agentorg/sdk").RpcInterface<"hub.bind
             interface: z.ZodString;
             madeBy: z.ZodString;
             at: z.ZodString;
+            exposed: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, {}, 1>;