@agentorg/cli 0.0.4 → 0.0.5

package/README.md

@@ -17,7 +17,7 @@ AgentOrg as a dynamic system: Actors and widgets are modules in content-addresse
 - `@agentorg/kit`: the shell's own components, for the shell and for any view, drawn in the theme's tokens by the kit's styles (`KIT_CSS`, every class `kit-`, put first in the document's head when the kit is imported, so a view's own styles win). Accessible primitives on Radix: `Dialog` (focus held inside; Escape and a click outside close it), `Menu` with `MenuItem`, `Switch` and `Tabs`; plain elements for the rest: `Button` (`primary`, `quiet`), `IconButton` (its label is its name), `Field`, `Select` (the browser's own), `Card`, `List`, `Table`, `Meter` and `Actions`; layout pieces that fill and adapt: `Stack`, `Row`, `Fill`, `Scroll`, and `ResizableGroup`, `ResizablePanel` and `ResizeHandle` from react-resizable-panels. `Markdown` renders an agent's GitHub-flavored markdown with react-markdown, safe as it streams: remend first closes what's still open, and raw HTML is shown as text. `Chat` is a conversation on assistant-ui's primitives over an external store: the caller keeps the messages (`ChatEntry`, as `chat@1` has them) and runs the turns (`onSend`, `onCancel`, `onRetry`, `onEarlier`). The person's messages, each run of replies and tool messages as one reply in markdown, a tool message as a card (its name, how it ended, what went in and came back) when it says which tool ran and as its line otherwise; Enter sends, never mid-composition or during a turn, when Send is Stop; a refused send puts the text back; it fills its parent and goes compact below 460 px wide. Its tests run on happy-dom.
 - `@agentorg/wire`: the channel: yamux streams, length-prefixed JSON frames, stream headers and transports.
 - `installer`: a bundled host package that turns packages into working Actors, exporting `installer@1`. Bound to the Hub's management (`hub.packages`, `hub.actors`, `hub.grants`, `hub.exports` and `hub.bindings`, which makes it the person's delegated manager) and to `storage.admin@1`, it proposes and installs. `plan({package})` lists each slot the package doesn't wire itself, with the exports that could serve it now: exactly its interface and schema hash, on Actors that aren't stopped or closed. `install({package, name, connections, start?})` makes the Actor with exactly those connections, all or none. It grants nothing its caller couldn't: each connection's export side must be the caller's (the provider, bound to that export, or a manager), else the whole install is refused (`forbidden`, listing every such connection) and nothing is made. It seeds each store bound to `storage.kv` from the package's `seed` (an object of key to value per `module.slot`), starts the Actor if asked (a seed or start that fails closes it), and lists the slots left unbound and the seeds that couldn't land (`unseeded`). It never picks a connection itself. `install` records the new Actor as made for its caller (`installedFor`, which grants nothing), and takes `expose: [{export, to}]`: the new Actor's exports to expose, each to one Actor, all or none like the connections. A manager's are made at once (`granted`, with the slot); one to the caller itself is left for the caller to file, its result giving the exact `hub.grants.expose` call, which makes it the caller's own request (`request`); any other is refused `forbidden`, saying a manager could, and nothing is created. Only `rpc` exports of the package's host modules can be listed, and the Hub's own Actors take no slots. `plan({package, expose})` lists each entry with how it would settle, and refuses one `install` would refuse. Nothing is exposed that isn't listed. Bound to the person's `layout@1` too, it carries a system between homes as data: `exportSystem()`, for a manager only (it lists every binding and the person's layout; any other caller is refused `forbidden`), gives an `agentorg.system/1` composition (every package Actor that isn't closed, by a name of its own, with its package as `name@version#hash` and whether it runs; the connections among them and to the built-in Actors, as `{consumer, slot, provider, export}` by names; and the layout's placements), never credentials, tokens, stores or logs, and lists what it leaves out (external Actors and what connects to them). `importSystem({composition})` makes it again with the caller's authority (connecting the new Actors to each other takes a manager): it creates the Actors whose packages are here (a taken name gets a suffix), binds the connections, seeds, starts what ran and places the layout, all or nothing, and lists what it couldn't: a package that isn't here or is another version (whoever holds the composition's folder adds its archives first) and what depends on it, an Actor that needs a sign-in, a seed that can't land, and the placements unless the caller holds the person's layout. The exporting home's installer stays out: every home has its own. An import never grants management: a connection to `hub` or to `storage.admin` is recorded by an export but never made by an import, even a manager's (a composition may come from anyone); it comes back in `ungranted`, for the person to grant one by one.
-- `@agentorg/hub`: the core. Its state, in `node:sqlite` in a private home: Actors, a verified package store (`hub.packages.add` takes an archive by path; `hub.packages.build` takes a package's source as data, `package.json` and files under `src/` up to 768 KiB, builds it as `agentorg build` does, but reading no tsconfig, in a scratch folder of the home that is always removed: its files import only `@agentorg/sdk`, `@agentorg/interfaces`, `zod`, and for views `react`, `react-dom` and `@agentorg/kit` (JSX compiles to `react/jsx-runtime`), by name, each only within its own package, nothing outside the package's folder, and nothing by a pattern; a library's own imports are its own, and only the files resolved for it are read; a library's wrapped modules are named in the bundle by their library and version (`agentorg-library:react@19.3.1/cjs/react.production.js`), never by where it is installed, in `agentorg build` and Hub builds alike, so a package names no machine's folders and builds the same on any install; a Hub build resolves each allowed package's entry file from the Hub's own install, so in that file esbuild omits Node's ESM-to-CommonJS interop flag, which `agentorg build` keeps: no package allowed now behaves differently for it, but a Hub build's bytes can differ from `agentorg build`'s for packages that use them; at most 16 modules, 16 MiB built and 60 s; one build per caller at a time; and it adds the result. Reading each module's definition runs the source's code, so the Hub runs it in the same OS sandbox as host processes, and where those can't start, `build` is refused `unsupported` with the same reason. A failed build is `Refused("build")` with the build's message, which names no path outside the package), what each Actor takes and offers, bindings, binding requests and an audit trail. A binding is the grant, and it needs both ends: the export side (the provider, an Actor already bound to that export, or a manager) and the slot side (the consumer itself, or a manager). Through `hub.grants@1`, a caller with both ends binds; one with a single end approves the other end's open request or asks that end's approvers; one with neither is refused. `hub.grants.expose({provider, export, to, as?})` exposes an `rpc` 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, named `as` (one word of at most 48 characters) or by default the provider's name camelCased, `_` and the export's last part (`Pocket Side Quests`' `logic.quests` is `pocketSideQuests_quests`), made unique on `to` with `_2`, `_3`…. Its authority is a binding's, `to` being the consumer: with both ends it is made; with one it is a request (`exposed: true` on the request, its `slot` the name it will have), which the other end approves by calling `expose` with the request's fields; with neither it is refused, naming who could. Exposing the same export to the same Actor again gives its slot back. A request reserves no name: the first exposure made under it has it, and the requests it settles close; one Actor has at most 32 exposure requests open toward another. An Actor that declares a slot of its own under an exposed slot's name takes the name, and the exposure goes. The slot goes with its binding: `unexpose({to, slot})`, `unbind`, the export withdrawn or either end closed; `hub.bindings` marks such a binding `exposed: true`. The Hub's own Actors take no slots. A manager creating an Actor for another (the installer, for its caller) passes `for`, shown as `installedFor` on the Actor: provenance only, from which the Hub grants nothing. A decision goes to the request's approvers and its requester, which can also read its requests' outcomes with `mine`. A manager is any Actor bound to `hub.bindings@1`. `hub.actors.create` can bind the new Actor's slots at once, with the creator's export side. The router serves it over WebSocket (`listen`), one yamux channel per Actor: a client's first stream is `hello` with its credential, then every `call`, `subscribe`, `open` and `http` stream is resolved through its binding, validated against the interface's JSON Schemas in both directions (ajv, 2020-12, in a pool of worker threads, each check under a time budget, since schemas come from Actors), forwarded to the provider with the caller named, and audited. A provider accepts or refuses an `open` or `http` stream with one body before any raw bytes. An Actor offers and withdraws exports at run time on its own channel (`offer`, `withdraw`). An Actor learns which of its slots are bound from hello's result, then from a `slot` notice on each change. A pipe the Hub makes for a package Actor's process says hello as that Actor without a credential (the pipe is the proof) and declares nothing (the manifest does). Every `serve` stream names the caller and the caller's slot, so a provider can keep state per consumer slot. `hub.actors.start` runs a package Actor's host modules in their own process: `node` under its permission model (reading only the runner and the package's folder, no child processes or workers), with an empty environment, a 256 MB heap and the channel on fd 3, inside the OS sandbox (`sandbox-exec` on macOS, a user, network and PID namespace with `unshare` on Linux), so it has no network, no DNS and no other process to signal. The Actor is running once its process says hello, within 30 s. `stop` sends SIGTERM, then SIGKILL after 5 s. A process that exits otherwise has crashed: it is restarted after a backoff from 1 s doubling to 60 s (starting over after 10 minutes up), and `hub.actors.get` counts `restarts` and keeps the `lastExit`. Every Actor's record in `hub.actors` says whether it is `connected`, holding a channel to the Hub now: an external Actor while its program is connected (the person while the app runs: its gateway holds the person's channel), a package Actor while its process is, so a running one isn't while its process starts or restarts; the built-in Actors are the Hub itself and have none. `hub.actors`' `changed` event names an Actor whose record may differ: made, started, stopped, closed, its process exited, or connected or gone; the audit trail records no connections. Actors running when the Hub stopped are started again when it opens. Where the sandbox can't run (stock Ubuntu restricts unprivileged user namespaces), `start` is refused with `unsupported` and every package Actor's `host` says why and what to change; the Hub probes again at each start. `hub.actors.logs` reads an Actor's log lines: its `ctx.log` entries and anything else its process writes (stdout as `info`, stderr as `error`). For the person's shell, `Hub.viewCall` and `Hub.viewSubscribe` run a package Actor's view module's calls and events in the Hub's process, as that Actor, through `<module>.<slot>`, and `Hub.viewSlots` tells the gateway a view module's slots: those bound now, then each change, and each bound again when it is usable again: its provider's channel comes back, or its Actor's own, since a view calls only while its Actor runs; `hub.actors.get` lists a package Actor's `views`. `Hub.viewLog` writes a view module's log line to its Actor's log, marked with the module; the Hub bounds each line itself (a known level, 4 KiB of text, 16 fields of 1 KiB) and rotates each Actor's log once at 1 MiB. The built-in `storage` Actor exports `kv@1`: one store per consumer slot (keyed by the consumer and slot the router names), in `<home>/storage.db`; values up to 256 KiB and 64 MiB per Actor, past which `Refused("quota")`; stores outlive unbinding and go when their Actor is closed. Its `admin` export (`storage.admin@1`, bound only to the installer) seeds a new Actor's store from its package's `seed`: all entries or none, into an empty store only, within the same limits, and audited as `storage.seed` with the consumer, the slot and how many entries. The built-in `net` Actor exports `egress` (`http.egress@1`): a consumer's request, made from the Hub's process to the public internet over HTTPS only. Its host is resolved and every address checked (loopback, private, shared, link-local including the cloud metadata address, multicast, reserved and documentation ranges, and their IPv4-mapped forms are refused), and the connection goes to the checked address with the name for SNI and the certificate, so a second resolution can't move it. Plain `http:`, a refused address and a name that resolves to one throw `Refused("forbidden")` at the consumer's `fetch`; a host that can't be reached before anything is sent throws `Refused("unreachable")`, and a failure after, or 5 minutes without a byte, throws `OutcomeUnknown`. Redirects come back as they are. Each request's method, host and status are audited as `net`'s; paths, queries and bodies never are. The `hub` Actor's six exports are served through the same path. A refusal that names an Actor names it as "Name (id)", and says what the caller can do instead: who could grant it, what to call, or what to do first.
+- `@agentorg/hub`: the core. Its state, in `node:sqlite` in a private home: Actors, a verified package store (`hub.packages.add` takes an archive by path; `hub.packages.build` takes a package's source as data, `package.json` and files under `src/` up to 768 KiB, builds it as `agentorg build` does, but reading no tsconfig, in a scratch folder of the home that is always removed: its files import only `@agentorg/sdk`, `@agentorg/interfaces`, `zod`, and for views `react`, `react-dom` and `@agentorg/kit` (JSX compiles to `react/jsx-runtime`), by name, each only within its own package, nothing outside the package's folder, and nothing by a pattern; a library's own imports are its own, and only the files resolved for it are read; a library's wrapped modules are named in the bundle by their library and version (`agentorg-library:react@19.3.1/cjs/react.production.js`), never by where it is installed, in `agentorg build` and Hub builds alike, so a package names no machine's folders and builds the same on any install; a Hub build resolves each allowed package's entry file from the Hub's own install, so in that file esbuild omits Node's ESM-to-CommonJS interop flag, which `agentorg build` keeps: no package allowed now behaves differently for it, but a Hub build's bytes can differ from `agentorg build`'s for packages that use them; at most 16 modules, 16 MiB built and 60 s; one build per caller at a time; and it adds the result. Reading each module's definition runs the source's code, so the Hub runs it in the same OS sandbox as host processes, and where those can't start, `build` is refused `unsupported` with the same reason. A failed build is `Refused("build")` with the build's message, which names no path outside the package), what each Actor takes and offers, bindings, binding requests and an audit trail. A binding is the grant, and it needs both ends: the export side (the provider, an Actor already bound to that export, or a manager) and the slot side (the consumer itself, or a manager). Through `hub.grants@1`, a caller with both ends binds; one with a single end approves the other end's open request or asks that end's approvers; one with neither is refused. `hub.grants.expose({provider, export, to, as?})` exposes an `rpc` 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, named `as` (one word of at most 48 characters) or by default the provider's name camelCased, `_` and the export's last part (`Pocket Side Quests`' `logic.quests` is `pocketSideQuests_quests`), made unique on `to` with `_2`, `_3`…. Its authority is a binding's, `to` being the consumer: with both ends it is made; with one it is a request (`exposed: true` on the request, its `slot` the name it will have), which the other end approves by calling `expose` with the request's fields; with neither it is refused, naming who could. Exposing the same export to the same Actor again gives its slot back. A request reserves no name: the first exposure made under it has it, and the requests it settles close; one Actor has at most 32 exposure requests open toward another. An Actor that declares a slot of its own under an exposed slot's name takes the name, and the exposure goes. The slot goes with its binding: `unexpose({to, slot})`, `unbind`, the export withdrawn or either end closed; `hub.bindings` marks such a binding `exposed: true`. The Hub's own Actors take no slots. A manager creating an Actor for another (the installer, for its caller) passes `for`, shown as `installedFor` on the Actor: provenance only, from which the Hub grants nothing. A decision goes to the request's approvers and its requester, which can also read its requests' outcomes with `mine`. A manager is any Actor bound to `hub.bindings@1`. `hub.actors.create` can bind the new Actor's slots at once, with the creator's export side. The router serves it over WebSocket (`listen`), one yamux channel per Actor: a client's first stream is `hello` with its credential, then every `call`, `subscribe`, `open` and `http` stream is resolved through its binding, validated against the interface's JSON Schemas in both directions (ajv, 2020-12, in a pool of worker threads, each check under a time budget, since schemas come from Actors), forwarded to the provider with the caller named, and audited. A provider accepts or refuses an `open` or `http` stream with one body before any raw bytes. An Actor offers and withdraws exports at run time on its own channel (`offer`, `withdraw`). An Actor learns which of its slots are bound from hello's result, then from a `slot` notice on each change. A pipe the Hub makes for a package Actor's process says hello as that Actor without a credential (the pipe is the proof) and declares nothing (the manifest does). Every `serve` stream names the caller and the caller's slot, so a provider can keep state per consumer slot. `hub.actors.start` runs a package Actor's host modules in their own process: `node` under its permission model (reading only the runner and the package's folder, no child processes or workers), with an empty environment, a 256 MB heap and the channel on fd 3, inside the OS sandbox (`sandbox-exec` on macOS, a user, network and PID namespace with `unshare` on Linux), so it has no network, no DNS and no other process to signal. The Actor is running once its process says hello, within 30 s. `stop` sends SIGTERM, then SIGKILL after 5 s. A process that exits otherwise has crashed: it is restarted after a backoff from 1 s doubling to 60 s (starting over after 10 minutes up), and `hub.actors.get` counts `restarts` and keeps the `lastExit`. Every Actor's record in `hub.actors` says whether it is `connected`, holding a channel to the Hub now: an external Actor while its program is connected (the person while the app runs: its gateway holds the person's channel), a package Actor while its process is, so a running one isn't while its process starts or restarts; the built-in Actors are the Hub itself and have none. `hub.actors`' `changed` event names an Actor whose record may differ: made, started, stopped, closed, its process exited, or connected or gone; the audit trail records no connections. Actors running when the Hub stopped are started again when it opens. `hub.actors.upgrade({actorId, package})` runs another package as the same package Actor, for a manager only, since the new package's code then holds everything the Actor was granted: its id, its stores and every binding whose interfaces still match stay, the new package's own wiring is made where its slot is unbound, and a running Actor restarts on it; a binding through a slot or export the new package drops or declares as another interface is dropped, audited and returned in `dropped`. When a redeclaration or an upgrade changes the interface of a bound name, the bindings whose other end doesn't declare the new one are dropped (audited as `binding.drop`) and the requests through it close: an external Actor's hello that redeclares a bound name as another is no longer refused for it. Dropping only takes access away. Where the sandbox can't run (stock Ubuntu restricts unprivileged user namespaces), `start` is refused with `unsupported` and every package Actor's `host` says why and what to change; the Hub probes again at each start. `hub.actors.logs` reads an Actor's log lines: its `ctx.log` entries and anything else its process writes (stdout as `info`, stderr as `error`). For the person's shell, `Hub.viewCall` and `Hub.viewSubscribe` run a package Actor's view module's calls and events in the Hub's process, as that Actor, through `<module>.<slot>`, and `Hub.viewSlots` tells the gateway a view module's slots: those bound now, then each change, and each bound again when it is usable again: its provider's channel comes back, or its Actor's own, since a view calls only while its Actor runs; `hub.actors.get` lists a package Actor's `views`. `Hub.viewLog` writes a view module's log line to its Actor's log, marked with the module; the Hub bounds each line itself (a known level, 4 KiB of text, 16 fields of 1 KiB) and rotates each Actor's log once at 1 MiB. The built-in `storage` Actor exports `kv@1`: one store per consumer slot (keyed by the consumer and slot the router names), in `<home>/storage.db`; values up to 256 KiB and 64 MiB per Actor, past which `Refused("quota")`; stores outlive unbinding and go when their Actor is closed. Its `admin` export (`storage.admin@1`, bound only to the installer) seeds a new Actor's store from its package's `seed`: all entries or none, into an empty store only, within the same limits, and audited as `storage.seed` with the consumer, the slot and how many entries. The built-in `net` Actor exports `egress` (`http.egress@1`): a consumer's request, made from the Hub's process to the public internet over HTTPS only. Its host is resolved and every address checked (loopback, private, shared, link-local including the cloud metadata address, multicast, reserved and documentation ranges, and their IPv4-mapped forms are refused), and the connection goes to the checked address with the name for SNI and the certificate, so a second resolution can't move it. Plain `http:`, a refused address and a name that resolves to one throw `Refused("forbidden")` at the consumer's `fetch`; a host that can't be reached before anything is sent throws `Refused("unreachable")`, and a failure after, or 5 minutes without a byte, throws `OutcomeUnknown`. Redirects come back as they are. Each request's method, host and status are audited as `net`'s; paths, queries and bodies never are. The `hub` Actor's six exports are served through the same path. A refusal that names an Actor names it as "Name (id)", and says what the caller can do instead: who could grant it, what to call, or what to do first.
 - `@agentorg/cli`: AgentOrg as one app. `agentorg` runs a Hub, the person's gateway and the shell on loopback; see "The app: the person's gateway".
 - `chatgpt`: the model Actor, a package with one host module. It signs in with ChatGPT for the person's plan (`account.login@1`: OpenAI's OAuth for open-source apps, with dynamic registration, PKCE and a verified id_token; refresh tokens rotate, one refresh at a time) and serves `llm.session@1` on that plan through the Responses API, streamed and stored nowhere. Its whole network is its `web: http.egress@1` slot and its sign-in lives in its `store: kv@1` slot; the tokens never leave it except to that store: never in a reply, an event, a log or a refusal. It never uses an API key or API billing: a usage limit is refused `usage_limit`, with where to manage it. Its tests run against an in-process fake of OpenAI, so none reaches OpenAI.
 - `assistant`: an agent, a package whose host module `logic` exports `chat@1` and runs the agent loop itself, with the model behind its `model: llm.session@1` slot. Its tools are its other bound slots (`layout`, `packages`, `actors`, `grants`, `exports` and `installer`), and every slot exposed to it at run time (`ctx.exposed()`): each method becomes a function tool named `<slot>__<method>` (a dot in the slot's name as `_`; a name past 64 characters is left out) with the method's input JSON Schema, so it can do exactly what it is connected to, and a call runs through the slot, checked and audited by the Hub. With `packages` and `installer: installer@1` bound, it can extend the system: its instructions then give the package format (views may use React and `@agentorg/kit`'s components), with a whole counter package and a view on the kit as the examples (`EXAMPLE` in `src/logic.ts`, built by its tests as the Hub builds), and the steps: `packages__build` with the files, fixing errors from the build's message; `installer__plan`; `installer__install` with explicit connections (a store to `storage.kv`); then `layout__place` with the new Actor's view. A turn makes at most 20 tool calls, and a function's output is cut at 16 KiB. Its chat is kept in its `store: kv@1` slot: each message once, its text and a call's arguments cut to fit a stored value, and the newest 2,000 messages (16 MiB) kept. The model is sent the newest whole exchanges that fit 400 KB of JSON (instructions and tool schemas aside), and always the latest one; if that alone is over, its oldest function outputs are left out, each call keeping an output. Its view module `chat` is the chat itself, the kit's `Chat` over its `chat: chat@1` slot: the record (the newest 100, earlier pages on request), the replies as they stream, in markdown, and a composer, with "Using ChatGPT plan" and "Manage usage" beside it, Retry under the last reply, and the action each refusal calls for (Manage usage, Continue with ChatGPT, Retry), which it asks of the shell through its `shell: ui.shell@1` slot.
@@ -137,7 +137,7 @@ From a clone, after `npm ci` and `npm run build`, with `agentorg` being `node pa
   - it makes the installer as the person, with its seven bindings (`hub.packages`, `hub.actors`, `hub.grants`, `hub.exports`, `hub.bindings`, `storage.admin` and `person.layout`), starts it, and binds the person's `installer` to it;
   - once the installer's process is connected, it installs ChatGPT through `installer.install`, with `model.web` to `net.egress` and `model.store` to `storage.kv`, started, and binds the person's `login` to its `model.login`.
 
-  It records the Actors it made, and the bundled assistant's hash, in the person's store (`app/first-run`), and trusts only those, never an Actor because of the name its package gives itself. Each step reads what is there first, so a restart, or a first run that stopped half way, converges and makes nothing twice: a recorded Actor that lost one of its slots' bindings gets it again (of the slots its package declares), and one of an older build is kept. A recorded Actor that was closed is made again. A step that fails is logged and tried again at the next start.
+  It records the Actors it made, and the bundled assistant's hash, in the person's store (`app/first-run`), and trusts only those, never an Actor because of the name its package gives itself. Each step reads what is there first, so a restart, or a first run that stopped half way, converges and makes nothing twice: a recorded Actor that lost one of its slots' bindings gets it again (of the slots its package declares). A recorded Actor of an older build is upgraded in place to the bundled one (`hub.actors.upgrade`: the same id, store and matching bindings), and so is an agent on an assistant build an earlier run bundled, known by the hashes the first run records, never by a package's name; the bindings an upgrade drops are made again where their ends now match, and each upgrade is logged. A recorded Actor that was closed is made again. A step that fails is logged and tried again at the next start.
 - **`/oauth/chatgpt`:** where ChatGPT sends the browser back after sign-in. It takes `GET` only and hands the whole address, which holds the sign-in's code, to `login.complete`. Then it sends the tab on (303) to `/oauth/chatgpt?result=<outcome>`, so the code leaves 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 referrer is sent.
 - **Named rules, `app.rules@1`:** conveniences the person turns on, served by the gateway on `/api` as `rules` (`list`, `set`, and `changed`). Each is named and off until the person turns it on, and the ones that are on are kept in the person's store under `app/rules`. The gateway acts on a rule that is on as the person, a manager, so only within what the person could grant: it hears each request through `grants.requested`, and goes through the open ones at start and whenever a rule is turned on. It approves a match the way an approver does, with the call the request asked for, and never declines; whatever no rule matches stays for the person.
   - **"Let an agent use what it installs"** (`agents-use-what-they-install`) approves a request to expose an Actor's export to the agent it was installed for (its `installedFor`), while the Actor isn't closed. `installedFor` is provenance only: nothing but a rule that is on acts on it.

package/dist/bundled/index.json

@@ -1,6 +1,6 @@
 {
-  "installer": "sha256-84165e3be5c904fc971d983dab31102e07cca725d8629a6fd7d118fa3a0a88b8.agentorg",
-  "chatgpt": "sha256-f4330f5987f37d8cf3aeb44d2f831b573641a87186daa2f811f0c35ba04804f0.agentorg",
-  "assistant": "sha256-ade9132b3f34b4c39db92adeadc7e540dc745e4a81b5b54f5d45bf9ec92bca75.agentorg",
-  "board": "sha256-01d69bc3888c2a53963f4413d47de909d129ad27c78e9af6d830bb50c3478419.agentorg"
+  "installer": "sha256-4055f8fddf6b90f3d356543f554b2a9e9a2c4a8827a8774f8f87952dc1692331.agentorg",
+  "chatgpt": "sha256-e356ea3c1899138a8494baf521556831006f38534fa9e92ae873e7e6956c3a46.agentorg",
+  "assistant": "sha256-1f64ca62a0209d767d6aa6c4feb50b0653d60f10bebbc301f79bd3a37e0153c1.agentorg",
+  "board": "sha256-0e91cc3d0e9762b81abc2427b5496b20f383abcd6fb97d928a8d50e956b54d1f.agentorg"
 }

package/dist/node_modules/@agentorg/hub/dist/src/hub-actor.js

@@ -116,6 +116,39 @@ export class HubActor {
                     await processes.stop(actorId);
                     state.closeActor(caller, actorId);
                 },
+                // A running Actor is stopped as `stop` does it, upgraded, and started again: on the new
+                // package, or on its own if the upgrade is refused. The machine's check comes first, so
+                // one that can't run it never has it stopped by an upgrade.
+                upgrade: async (caller, input) => {
+                    const actorId = String(input.actorId);
+                    const hash = String(input.package);
+                    const actor = state.checkUpgrade(caller, actorId, hash);
+                    if (actor.package === hash)
+                        return { dropped: [] };
+                    const running = actor.state === "running";
+                    if (running) {
+                        await processes.ready();
+                        state.stop(caller, actorId);
+                        await processes.stop(actorId);
+                    }
+                    const restart = () => {
+                        // Started meanwhile, by another call: it runs already.
+                        if (!running || state.actor(actorId).state === "running")
+                            return;
+                        state.start(caller, actorId);
+                        processes.start(actorId);
+                    };
+                    let dropped;
+                    try {
+                        dropped = state.upgrade(caller, actorId, hash);
+                    }
+                    catch (error) {
+                        restart();
+                        throw error;
+                    }
+                    restart();
+                    return { dropped };
+                },
                 logs: (_, input) => {
                     // The Actor must exist; its lines are its process's output and its views' lines.
                     const { actorId } = state.actor(String(input.actorId));

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

@@ -115,6 +115,17 @@ declare const HUB_EXPORTS: {
         close: import("@agentorg/sdk").MethodSpec<import("zod").ZodObject<{
             actorId: import("zod").ZodString;
         }, import("zod/v4/core").$strip>, import("zod").ZodObject<{}, import("zod/v4/core").$strip>>;
+        upgrade: import("@agentorg/sdk").MethodSpec<import("zod").ZodObject<{
+            actorId: import("zod").ZodString;
+            package: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+            dropped: import("zod").ZodArray<import("zod").ZodObject<{
+                consumer: import("zod").ZodString;
+                slot: import("zod").ZodString;
+                provider: import("zod").ZodString;
+                export: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>>;
         logs: import("@agentorg/sdk").MethodSpec<import("zod").ZodObject<{
             actorId: import("zod").ZodString;
             limit: import("zod").ZodOptional<import("zod").ZodNumber>;
@@ -472,6 +483,16 @@ export declare class HubState {
     stop(caller: string, actorId: string): void;
     /** Close an Actor for good: its bindings both ways, its declarations and its open requests go. */
     closeActor(caller: string, actorId: string): void;
+    /** Refused unless the caller may upgrade the Actor to the package now; changes nothing. */
+    checkUpgrade(caller: string, actorId: string, hash: string): ActorRecord;
+    /**
+     * Run another package as the same Actor: its id, its stores and every binding whose interfaces
+     * still match stay; a binding through a slot or export the new package drops or declares as
+     * another interface is dropped, audited and returned. The new package's own wiring is applied
+     * where its slot is unbound. The process isn't touched here: a running Actor is stopped first
+     * and started after, by whoever runs processes.
+     */
+    upgrade(caller: string, actorId: string, hash: string): Wiring[];
     /** Add a `.agentorg` archive from a path on this machine, verified; adding it again is a no-op. */
     addPackage(caller: string, path: string): {
         hash: string;
@@ -493,8 +514,9 @@ export declare class HubState {
     declaration(actor: string, side: "slot" | "export", name: string): Declaration | undefined;
     /**
      * An external Actor's slots and static exports, as it declares them when it connects; they
-     * replace what it declared before. A bound name keeps its interface: redeclaring it as another is
-     * refused. A name it no longer declares is dropped, with its bindings.
+     * replace what it declared before. A name redeclared as another interface loses its bindings
+     * (audited as `binding.drop`), since a binding holds only while both ends declare the same one.
+     * A name it no longer declares is dropped, with its bindings.
      */
     declareExternal(actorId: string, declares: {
         slots: Record<string, DescribedInterface>;

package/dist/node_modules/@agentorg/hub/dist/src/state.js

@@ -143,6 +143,18 @@ const requestOf = (row) => ({
     ...(row.exposed ? { exposed: true } : {}),
 });
 const other = (side) => (side === "export" ? "slot" : "export");
+/** What a package's Actor declares: each module's slots and exports, by `module.name`. */
+function packageDeclarations(manifest) {
+    return Object.entries(manifest.modules).flatMap(([module, m]) => [
+        ["slot", m.slots],
+        ["export", m.exports],
+    ].flatMap(([side, members]) => Object.entries(members).map(([member, id]) => {
+        const entry = manifest.interfaces[id];
+        if (!entry)
+            throw new Refused("invalid", `The package doesn't record ${id}.`);
+        return { side, name: `${module}.${member}`, iface: { id, ...entry } };
+    })));
+}
 /**
  * The core's state in its home folder: Actors, packages, declarations, bindings, binding requests
  * and the audit trail, in `node:sqlite`. Every method that changes something takes its caller, and
@@ -390,17 +402,8 @@ export class HubState {
             if (input.package) {
                 const { manifest } = this.package(input.package);
                 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],
-                        ["export", m.exports],
-                    ])
-                        for (const [member, id] of Object.entries(members)) {
-                            const entry = manifest.interfaces[id];
-                            if (!entry)
-                                throw new Refused("invalid", `The package doesn't record ${id}.`);
-                            this.#declare(actorId, side, `${module}.${member}`, { id, ...entry }, false);
-                        }
+                for (const { side, name, iface } of packageDeclarations(manifest))
+                    this.#declare(actorId, side, name, iface, false);
                 // A package's own wiring is applied as it is installed.
                 for (const [slot, exported] of manifest.connections)
                     this.#insertBinding({ consumer: actorId, slot, provider: actorId, export: exported }, HUB);
@@ -494,6 +497,112 @@ export class HubState {
             this.#emit(() => this.#events.closed?.(actorId));
         });
     }
+    /**
+     * Drop the bindings through one of an Actor's slots or exports, its interface having changed,
+     * but those `keeps` says still match: each is audited as `binding.drop`. Dropping only takes
+     * access away. Returns what was dropped.
+     */
+    #dropBindingsOf(actorId, side, name, by, keeps = () => false) {
+        const dropped = this.bindings(actorId).filter((b) => (side === "slot"
+            ? b.consumer === actorId && b.slot === name
+            : b.provider === actorId && b.export === name) && !keeps(b));
+        for (const b of dropped)
+            this.#removeBindings("consumer = ? AND slot = ?", b.consumer, b.slot);
+        const wirings = dropped.map(({ consumer, slot, provider, export: exported }) => ({
+            consumer,
+            slot,
+            provider,
+            export: exported,
+        }));
+        for (const wiring of wirings)
+            this.#audit(by, "binding.drop", { ...wiring, why: "its interface changed" });
+        return wirings;
+    }
+    /** Close the open requests to bind through one of an Actor's slots or exports. */
+    #closeRequestsThrough(actorId, side, name) {
+        const where = side === "slot" ? "consumer = ? AND slot = ?" : "provider = ? AND export = ?";
+        for (const open of this.#pending(where, actorId, name))
+            this.#decide(open, "closed");
+    }
+    /** Refused unless the caller may upgrade the Actor to the package now; changes nothing. */
+    checkUpgrade(caller, actorId, hash) {
+        this.#require(caller, "actors");
+        // An upgrade runs new code as an Actor that keeps its bindings and its store: whatever it was
+        // granted, the new code holds. Only a manager, who could grant all of it anyway, may.
+        if (!this.isManager(caller))
+            throw new Refused("forbidden", `Only a manager may upgrade an Actor, since the new package keeps its bindings and its store; ${this.named(caller)} isn't one.`);
+        const actor = this.actor(actorId);
+        if (actorId === HUB || actorId === PERSON || actorId === STORAGE || actorId === NET)
+            throw new Refused("forbidden", `${this.named(actorId)} is built in and can't be upgraded.`);
+        if (actor.package === "external")
+            throw new Refused("state", `${this.named(actorId)} isn't a package Actor; it declares what it takes when it connects.`);
+        if (actor.state === "closed")
+            throw new Refused("state", `${this.named(actorId)} is closed for good; make another.`);
+        packageDeclarations(this.package(hash).manifest);
+        return actor;
+    }
+    /**
+     * Run another package as the same Actor: its id, its stores and every binding whose interfaces
+     * still match stay; a binding through a slot or export the new package drops or declares as
+     * another interface is dropped, audited and returned. The new package's own wiring is applied
+     * where its slot is unbound. The process isn't touched here: a running Actor is stopped first
+     * and started after, by whoever runs processes.
+     */
+    upgrade(caller, actorId, hash) {
+        const actor = this.checkUpgrade(caller, actorId, hash);
+        if (actor.package === hash)
+            return [];
+        const { manifest } = this.package(hash);
+        const next = packageDeclarations(manifest);
+        const declared = (side, name) => next.find((n) => n.side === side && n.name === name)?.iface;
+        const dropped = [];
+        this.#transaction(() => {
+            // What it offered at run time was its process's, which this restarts: it goes, with the
+            // bindings to it, which are returned with the rest.
+            for (const row of this.#db
+                .prepare("SELECT name FROM declarations WHERE actor = ? AND side = 'export' AND dynamic = 1")
+                .all(actorId)) {
+                dropped.push(...this.#dropBindingsOf(actorId, "export", String(row.name), caller));
+                this.#drop(actorId, "export", String(row.name));
+            }
+            // A binding stays while its two ends declare the same interface: this Actor's end as the
+            // new package declares it, the other end as it is declared now.
+            const keeps = (b) => {
+                const slot = b.consumer === actorId
+                    ? declared("slot", b.slot)
+                    : this.declaration(b.consumer, "slot", b.slot)?.iface;
+                const exported = b.provider === actorId
+                    ? declared("export", b.export)
+                    : this.declaration(b.provider, "export", b.export)?.iface;
+                return !!slot && !!exported && compareInterfaces(slot, exported) === "same";
+            };
+            const old = this.#db
+                .prepare("SELECT side, name, iface FROM declarations WHERE actor = ? AND dynamic = 0")
+                .all(actorId).map((row) => ({
+                side: row.side,
+                name: String(row.name),
+                iface: JSON.parse(String(row.iface)),
+            }));
+            for (const was of old) {
+                dropped.push(...this.#dropBindingsOf(actorId, was.side, was.name, caller, keeps));
+                // A request through a name the package no longer declares as it was can't be made.
+                const fresh = declared(was.side, was.name);
+                if (!fresh || compareInterfaces(was.iface, fresh) !== "same")
+                    this.#closeRequestsThrough(actorId, was.side, was.name);
+            }
+            this.#db.prepare("DELETE FROM declarations WHERE actor = ? AND dynamic = 0").run(actorId);
+            for (const { side, name, iface } of next)
+                this.#declare(actorId, side, name, iface, false);
+            this.#db.prepare("UPDATE actors SET package = ? WHERE id = ?").run(hash, actorId);
+            for (const [slot, exported] of manifest.connections)
+                if (!this.binding(actorId, slot))
+                    this.#insertBinding({ consumer: actorId, slot, provider: actorId, export: exported }, HUB);
+            this.#audit(caller, "actor.upgrade", { actorId, from: actor.package, to: hash, dropped });
+            this.#emit(() => this.#events.exportsChanged?.(actorId));
+            this.#emit(() => this.#events.actorChanged?.(actorId));
+        });
+        return dropped;
+    }
     // ── Packages ────────────────────────────────────────────────────────────────
     /** Add a `.agentorg` archive from a path on this machine, verified; adding it again is a no-op. */
     addPackage(caller, path) {
@@ -604,8 +713,9 @@ export class HubState {
     }
     /**
      * An external Actor's slots and static exports, as it declares them when it connects; they
-     * replace what it declared before. A bound name keeps its interface: redeclaring it as another is
-     * refused. A name it no longer declares is dropped, with its bindings.
+     * replace what it declared before. A name redeclared as another interface loses its bindings
+     * (audited as `binding.drop`), since a binding holds only while both ends declare the same one.
+     * A name it no longer declares is dropped, with its bindings.
      */
     declareExternal(actorId, declares) {
         const actor = this.#open(actorId);
@@ -628,11 +738,19 @@ export class HubState {
                         for (const open of this.#pending("consumer = ? AND slot = ? AND exposed = 1", actorId, name))
                             this.#decide(open, "closed");
                     }
+                    // A binding holds while both ends declare the same interface: redeclared as another,
+                    // the name's bindings whose other end doesn't declare it are dropped, and its requests
+                    // close.
                     const known = this.declaration(actorId, side, name);
-                    if (known &&
-                        this.#isBound(actorId, side, name) &&
-                        compareInterfaces(known.iface, iface) !== "same")
-                        throw new Refused("conflict", `${name} is bound as ${known.iface.id}; it can't change while bound.`);
+                    if (known && compareInterfaces(known.iface, iface) !== "same") {
+                        this.#dropBindingsOf(actorId, side, name, actorId, (b) => {
+                            const other = side === "slot"
+                                ? this.declaration(b.provider, "export", b.export)?.iface
+                                : this.declaration(b.consumer, "slot", b.slot)?.iface;
+                            return !!other && compareInterfaces(iface, other) === "same";
+                        });
+                        this.#closeRequestsThrough(actorId, side, name);
+                    }
                     this.#declare(actorId, side, name, iface, false);
                 }
                 const kept = Object.keys(members);
@@ -648,13 +766,6 @@ export class HubState {
             this.#emit(() => this.#events.exportsChanged?.(actorId));
         });
     }
-    #isBound(actor, side, name) {
-        return !!this.#db
-            .prepare(side === "slot"
-            ? "SELECT 1 FROM bindings WHERE consumer = ? AND slot = ?"
-            : "SELECT 1 FROM bindings WHERE provider = ? AND export = ?")
-            .get(actor, name);
-    }
     /** A declaration gone, and the bindings through it. */
     #drop(actor, side, name) {
         this.#db

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

@@ -172,6 +172,25 @@ export declare const hubActors: import("@agentorg/sdk").RpcInterface<"hub.actors
     close: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
         actorId: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{}, z.core.$strip>>;
+    /**
+     * Run another package as the same package Actor: its id, its stores and every binding whose
+     * interfaces still match stay. A binding through a slot or export the new package drops, or
+     * declares as another interface, is dropped and listed in `dropped`; the new package's own
+     * wiring is made where its slot is unbound. A running Actor restarts on the new package.
+     * Only a manager may upgrade: the new package runs as the Actor and keeps what it was granted
+     * (its bindings and its store), which only a manager could grant anyway.
+     */
+    upgrade: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
+        actorId: z.ZodString;
+        package: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        dropped: z.ZodArray<z.ZodObject<{
+            consumer: z.ZodString;
+            slot: z.ZodString;
+            provider: z.ZodString;
+            export: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     /** Its newest log lines, oldest first. */
     logs: import("@agentorg/sdk").MethodSpec<z.ZodObject<{
         actorId: z.ZodString;

package/dist/node_modules/@agentorg/interfaces/dist/src/hub.js

@@ -120,6 +120,20 @@ export const hubActors = defineInterface({
         stop: method({ input: z.object({ actorId: Id }), output: Empty }),
         /** Final: its bindings, both ways, are removed. */
         close: method({ input: z.object({ actorId: Id }), output: Empty }),
+        /**
+         * Run another package as the same package Actor: its id, its stores and every binding whose
+         * interfaces still match stay. A binding through a slot or export the new package drops, or
+         * declares as another interface, is dropped and listed in `dropped`; the new package's own
+         * wiring is made where its slot is unbound. A running Actor restarts on the new package.
+         * Only a manager may upgrade: the new package runs as the Actor and keeps what it was granted
+         * (its bindings and its store), which only a manager could grant anyway.
+         */
+        upgrade: method({
+            input: z.object({ actorId: Id, package: Hash }),
+            output: z.object({
+                dropped: z.array(z.object({ consumer: Id, slot: Name, provider: Id, export: Name })),
+            }),
+        }),
         /** Its newest log lines, oldest first. */
         logs: method({
             input: z.object({ actorId: Id, limit: z.number().int().min(1).max(1000).optional() }),

package/dist/src/model.d.ts

@@ -35,10 +35,13 @@ export interface FirstRun {
  * 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.
+ * 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 declare function firstRun(person: PersonCalls, options?: FirstRunOptions): Promise<FirstRun>;
 /**

package/dist/src/model.js

@@ -35,10 +35,13 @@ const INSTALLER_BINDINGS = [
  * 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.
+ * 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 ?? (() => { });
@@ -63,17 +66,48 @@ export async function firstRun(person, options = {}) {
     // 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 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 call("store", "set", { key: RECORD, value: { ...record } });
+        return save();
     };
-    // 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.
+    // The assistant New agent installs is this build's, by hash.
     if (packages.assistant) {
         record.assistant = packages.assistant;
-        await attempt("recording the assistant", () => call("store", "set", { key: RECORD, value: { ...record } }));
+        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];
@@ -129,9 +163,12 @@ export async function firstRun(person, options = {}) {
             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);
-            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);
@@ -143,11 +180,14 @@ export async function firstRun(person, options = {}) {
         { slot: "model.store", provider: "storage", export: "kv" },
     ];
     const chatgpt = await attempt("ChatGPT", async () => {
-        const actor = await madeBefore("chatgpt");
+        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);
-            if (actor.package !== packages[CHATGPT])
-                log("First run: kept ChatGPT; the bundled build is added, not used.");
             await running(actor);
             return actor.actorId;
         }
@@ -176,6 +216,35 @@ export async function firstRun(person, options = {}) {
     });
     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 } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentorg/cli",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "AgentOrg as one app: the Hub, the person's gateway and the shell, on loopback.",
   "license": "MIT",
   "repository": {