@agentorg/cli 0.0.1 → 0.0.3

package/README.md

@@ -1,48 +1,159 @@
-# agentorg
+# AgentOrg
 
-AgentOrg connects Actors into an organization. Each Actor is a position with a responsibility and
-a manager; the user is at the root. Hub keeps organizational state and exposes explicit Tools.
-Actors decide how to use those Tools independently of any native execution implementation.
+## Install
 
-Actors exchange Messages in pair conversations, and track shared Work with the asks on it, through
-Hub Tools backed by `@uniac/agentic-workspace`. Hub supplies canonical Actor identity and hierarchy,
-actual connection presence and shared resource claims. An enrolled Provider can provision an
-implementation when requested at Actor creation. Human applications, agent sessions and programs share the same authority.
+```sh
+npx @agentorg/cli
+```
 
-## Applications
+It needs Node.js 22.15 or later. It runs AgentOrg on this computer and opens it in your browser; see "The `agentorg` command".
 
-The package `@agentorg/cli` distributes three independent entry points:
+AgentOrg as a dynamic system: Actors and widgets are modules in content-addressed packages, connected through named, versioned interfaces. This repository holds the core, starting with the SDK a package author writes against (`@agentorg/sdk`) and the standard interfaces (`@agentorg/interfaces`). Only `@agentorg/cli` is published; the other packages ship inside it.
 
-| Executable | Responsibility |
-|---|---|
-| `agentorg-server` | Run the core and manage its user service. |
-| `agentorg` | Call organization operations from a terminal as an actor. |
-| `agentorg-mcp` | Present an actor's operations over stdio; configure project integrations and hooks. |
+## Packages
 
-The public Node Actor library (`@agentorg/cli/actor`, in `src/actor/`) lets programs connect as an
-Actor, list Hub Tools and call their interfaces. The Human client (OrgActor-Human)
-owns the browser application and its local HTTP service in a separate repository.
-The `agentorg` skill (`skills/agentorg/`) describes how a session reports its work as live records
-and works in a position; an organization can add its conventions beside it.
+- `@agentorg/sdk`: `defineInterface` (with `method` and `event`) for `rpc`, `stream` and `http` interfaces; `defineActor` for host modules and `defineWidget` for view modules, with typed slot and export handles; the errors `NotConnected`, `Refused` and `OutcomeUnknown`; and `createTestContext` (`@agentorg/sdk/testing`), which runs a module without a Hub. An `rpc` handler gets its input and `{ caller }`, the calling Actor as the Hub names it, and `emit(event, payload, { to })` sends an event only to the subscriptions of the Actor `to` names, so a provider serving several consumers keeps each one's events its own. In `createTestContext`, `call` takes the caller as a fourth argument (the module's own Actor by default) and `emitted` records each event's `to`. `@agentorg/sdk/client` connects a program outside the Hub as an Actor: `connect({hubUrl, actorId, credential, slots, exports})` gives the same handles as a module's context, on the same runtime, with slots bound as the Hub's notices say and `exports.add`/`withdraw()` over the channel; As in a module, implement in `start` (run before the channel opens) and use slots from `onBind`, which runs when a slot becomes usable: bound, or its provider back. `openChannel` is the wire layer beneath it, without local checks. `http` slots `fetch` and `http` exports `serve` over the Hub's stream (HTTP/1.1, one request per stream, `node:http` loaded only when used). The request line carries the consumer's absolute URL, so a handler's `request.url` is exactly the URL the consumer fetched, scheme included; a request line that isn't absolute, or whose host isn't the `Host` header's, is answered 400. A handler that throws `Refused`, `NotConnected` or `OutcomeUnknown` reaches the consumer's `fetch` as that same error (carried as a 502 with an `agentorg-error` header); any other throw is a plain 500 response. `@agentorg/sdk/host` runs a package Actor's host modules in one process, on the same runtime: `runHost({packageDir, actorId, channel, log})` imports each `host` module's bundle, runs every `start`, then says hello over the channel, with each module's slots and exports named `<module>.<name>`. The program the Hub runs is `@agentorg/sdk/host/runner.js`, one self-contained file: it takes `<packageDir> <actorId>`, uses fd 3 as the channel, writes `ctx.log` as JSON lines on stderr, and exits non-zero if a `start` throws or an exception goes uncaught. The SDK's errors keep their class and code between a package's bundle and the runner, though each carries its own copy of the SDK. It reads only itself and the package's folder, so it runs under Node's permission model with exactly those two paths allowed (as real paths: the allow list doesn't follow symlinks).
+- `@agentorg/interfaces`: the standard interfaces `kv@1`, `ui.view@1`, `chat@1` (a conversation with an agent; a `tool` message may carry the call it stands for, its name, `running`/`done`/`refused`, input and output, sent as `running` when it starts and again under the same id when it ends), `llm.session@1` (stateless model inference, with function tools), `account.login@1` (signing in to an outside account, driven by a person or a program), `http.egress@1` (HTTPS to the public internet), `storage.admin@1` (seeding a new Actor's empty stores), `layout@1` (the person's dashboard), `installer@1` (planning and installing a package) and `ui.shell@1` (what the shell offers a view in its frame: opening an https address and starting sign-in), and the Hub's management interfaces `hub.packages@1`, `hub.actors@1`, `hub.grants@1`, `hub.bindings@1`, `hub.exports@1` and `hub.audit@1`.
+- `@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. 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` and `zod` by name, nothing outside the package's folder, and nothing by a pattern; 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. 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.
+- `@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`): each method becomes a function tool named `<slot>__<method>` 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, with a whole counter package as the example (`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 messages as they stream and a composer, with "Using ChatGPT plan" and "Manage usage" beside it, 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.
 
-## Set up
+### Why `ui.view@1` is different
 
-Ask your coding agent in the project whose sessions should join:
+Every interface crosses the wire as schemas, and a module's handles are derived from them, with one exception. `ui.view@1` is a view module's render surface: the view draws into its own frame's DOM, which no message can carry. So its export handle is `implement({ mount(el, { theme, size }), resize?(size) })`, where `el` is the frame's root element, and the frame runtime maps the wire methods `mount`, `resize` and `unmount` onto it. Don't copy this shape for another interface; anything a module offers to others belongs in schemas.
 
+### A view's frame
+
+A shell runs each view module in its own sandboxed frame, with an opaque origin and no network. The frame holds only the SDK's frame runtime, `@agentorg/sdk/frame/runtime.js`, one self-contained script, and the view's bundle. The shell hands the frame one `MessagePort` (`openFrame`, then `new FrameHost(port, handlers)` from `@agentorg/sdk/frame/host`). Everything the view reaches crosses that port:
+
+- **Load:** the shell names the view's bundle and which of its slots are bound. The frame imports it, runs `start` on the same runtime a host module uses, then binds the slots, so `onBind` runs for each one bound. A frame loads one view, only a `view` module, and takes one port, from its parent window only.
+- **Slots:** a call or subscription on a slot goes to the shell, which runs it as the view's Actor; the shell says when a slot is bound, unbound or usable again. A view's `stream` and `http` slots aren't served yet.
+- **`ui.view@1`:** the shell drives `mount`, `resize` and `unmount`. At mount, the theme's CSS variables (names starting `--`) are set on the frame's document.
+- **`ui.shell@1`:** the shell's own interface, the mirror of `ui.view@1`. A view's slot of it is bound by the frame runtime itself, never by the Hub, so it is always bound. `openExternal({url})` takes only an `https:` URL, which the host checks; the shell's handler must open it in a new tab with no opener (`noopener`). `signIn()` starts the shell's own sign-in. Each method has one call in flight at a time. A frame can't open windows itself.
+- **Logs:** the view's `ctx.log` and any error it doesn't catch go to the shell, for its Actor's log.
+- **Height:** while the view is mounted, the frame runtime tells the shell its content's height (the frame's body, which sets no height of its own) each time it changes. It's the frame runtime's own message, not part of `ui.view@1`, and a shell may size the frame to it.
+
+The frame isn't trusted: `FrameHost` checks every message, drops what doesn't fit, and refuses what it can't serve. A frame holds one subscription per slot and event, 64 at most, and 64 calls in flight, past which a call is refused `busy`; its log lines are cut, their fields rebuilt as a small fresh object, and past 50 lines in 10 s the rest are dropped. A height reaches the shell's `size` handler only as a finite number, clamped to 120–2,000 px, and at most once per 100 ms, the latest one winning.
+
+## Building a package
+
+A package's `package.json` names its modules, its own wiring and any seed state:
+
+```json
+"agentorg": {
+  "modules": { "logic": "src/logic.ts", "panel": "src/panel.ts" },
+  "connections": [["panel.board", "logic.board"]],
+  "seed": { "logic.store": { "cards": [] } }
+}
 ```
-Set up AgentOrg for me in this project, following https://raw.githubusercontent.com/uniac-ai/AgentOrg/main/docs/setup.md
-```
 
-[Setup](docs/setup.md) covers services and project integrations.
-[Programs](docs/programs.md) covers credentials and client connections.
-[Design](docs/design.md) covers the component and layer boundaries.
-[Workspace storage](docs/workspace-storage.md) covers the dependency pin, retained history and coordinated backups.
+`seed` is optional initial state for state slots, keyed by `"module.slot"`; the build checks each slot exists. It is the only runtime state a package may carry.
+
+`agentorg build [dir]` (from `@agentorg/sdk`; `buildPackage` in `@agentorg/sdk/build`) then:
+
+- bundles each module, with every library it uses, into one ESM file, `dist/<module>.js`, with no imports at run time and no Node built-ins;
+- reads each module's definition from its code and writes `agentorg.json`: each module's placement, slots and exports, every interface's JSON Schemas and hash, the package's `connections` and `seed`;
+- hashes the tree, `agentorg.json` and `dist/`, as SHA-256 over the canonical list of each file's path and SHA-256, and archives it as `<hash>.agentorg`, a deterministic tar. The tree goes to `agentorg-build/package/` and the archive beside it.
+
+It finds `@agentorg/sdk`, `@agentorg/interfaces` and `zod` from the package's own folder, so it works in a checkout of this repository, where they are. With `agentorg` installed from npm, build through the running app instead: `agentorg call packages build '{"files": {"package.json": "…", "src/logic.ts": "…"}}'` is the Hub's build (`hub.packages.build`), which takes the source as data, builds it as above against the SDK, the interfaces and zod it ships with, and adds the package.
+
+A signature is detached: a file named `agentorg.sig` beside the package, signing the package hash, so it is never inside what it signs. The manifest has no signature field.
+
+The build bundles; it doesn't type-check. Run `tsc --noEmit` on the package first.
+
+`@agentorg/sdk/manifest` reads packages without esbuild, for a Hub or an installer: `verifyArchive(bytes, hash)` checks an archive holds exactly `agentorg.json` and each module's entry, hashes to the expected hash, and has a sound manifest (`checkManifest`: its shape, each interface's recorded hash against its schemas, and its connections). Problems are returned, not thrown.
+
+The examples folder holds the spec's board package; its tests build it.
+
+### Module top levels have no side effects
+
+To read a module's definition, the build runs the module's code in a separate Node process (Node 22.15 or later) under the permission model: it can read only its own scratch folder, write nothing, and start no processes; Node built-ins can't be imported, and the network globals are gone. A definition that takes over 30 seconds to read is stopped. Widget bundles run there too, in Node, not a browser. So a module's top level must only define: no I/O, no timers that do work, no DOM globals such as `document` or `window`. Do that work in `start()`. A top level that tries fails the build with a message naming the module and what it touched.
+
+### Errors
+
+- `NotConnected`: the slot is unbound, or the export was withdrawn.
+- `Refused` with code `invalid`: the caller's input broke the interface's schema. Nothing ran.
+- `Refused` with code `bad_output`: the provider ran, and its reply or event broke the contract. The call may have had its effect; read state before retrying.
+- `Refused` with code `unimplemented`: the export has no handler for that method yet.
+- `OutcomeUnknown`: the channel dropped mid-call. Read state before retrying.
+
+### The `agentorg` command
+
+`@agentorg/cli` provides `agentorg`.
+
+- **`agentorg`**, with no command, runs AgentOrg: a Hub in its home, the person's gateway and the shell, on `127.0.0.1` (`--port N`, else any free port). It opens the browser already signed in, and prints only its address, never a sign-in code. `--no-open` doesn't open a browser. The code is in the address it hands the system's opener; on Linux, other local users can see that program's arguments for the moment it runs, and the code works for 60 s.
+- **`agentorg open`** signs a browser in to the running app again.
+- **`agentorg build [dir]`** builds a package, as the SDK's build does, in a checkout of this repository. Installed from npm, build with `agentorg call packages build '{"files": {…}}'`, the Hub's build.
+- **`agentorg hub [--port N]`** runs a bare Hub in its home, without the gateway or the shell, serving WebSocket on loopback, and writes the address to `<home>/url`.
+- **The person's commands**, one per hub method:
+  - `agentorg add <file.agentorg>`;
+  - `agentorg actors|bindings|exports|audit`;
+  - `agentorg bind <consumer.slot> <provider.export>`;
+  - `agentorg call <slot> <method> [json]`.
+
+  While the app runs, they go through it, with the CLI's token in `<home>/cli-token`. Otherwise they connect as the person with `<home>/person-credential`, and never take over a channel something else holds (hello's `replace: false`).
+- **The home** is `--home`, else `$AGENTORG_HUB_HOME`, else `$XDG_DATA_HOME/agentorg` when `XDG_DATA_HOME` is an absolute path, else `~/.local/share/agentorg`, on Linux and macOS alike.
+- **Output:** results are JSON on stdout. A refusal exits 1 with its reason on stderr, and a usage mistake exits 2.
+
+`@agentorg/sdk`'s own bin is `agentorg-sdk`, with the same commands but no app.
+
+## Try it
+
+From a clone, after `npm ci` and `npm run build`, with `agentorg` being `node packages/app/dist/src/cli.js`:
+
+1. **Run the app:** `agentorg`. It prints its address and opens the shell in the browser, already signed in; `agentorg open` signs a browser in again.
+2. **Find the board:** the app's first run added it. `agentorg call packages list` shows its hash, under the name `board`.
+3. **Install it with its store, started,** through the installer the first run made:
+
+   ```sh
+   agentorg call installer install '{"package":"<hash>","name":"Board","connections":{"logic.store":{"actor":"storage","export":"kv"}},"start":true}'
+   ```
+4. **Place its panel on home:** `agentorg call layout place '{"actor":"<actorId>","module":"panel","title":"Launch"}'`. It shows in the shell at once.
+5. **Add a card** in the panel: type it and press Enter. It is kept in the board's store, so it's there after a reload, and after the board's process restarts (`actors stop`, then `actors start`).
+
+## The app: the person's gateway
+
+`agentorg` runs the person's Actor as the app's gateway: its single running instance, holding the person's one channel to the Hub, in this process. Browser tabs and the CLI are the person's UIs, not channels: they reach the gateway, not the Hub.
 
-## Development
+- **Sign-in:** the browser opens `/signin#<code>`. The code is one-time, lasts 60 s, and sits in the fragment, which no request carries; the page drops it from the address at once. It trades the code, with a same-origin POST, for a session, which it keeps in the shell origin's `localStorage`. That's no cookie, because browsers send a `127.0.0.1` cookie to every port there; storage is the origin's alone, port included. Sessions live in the gateway's memory, so a restart signs every tab out.
+- **`/api`:** one WebSocket per tab, with the same calls a channel carries, as JSON:
+  - `{id, op: "call", slot, method, input}` is answered `{id, result}` or `{id, error}`;
+  - `{sub, op: "subscribe", slot, event}` gets `{sub, payload}` per event, and `{sub, end: true}` when it ends; `{sub, op: "unsubscribe"}` stops it.
+  - `{sub, op: "slots", view: {actor, module}}` watches a view's slots through the Hub's `viewSlots`: first `{sub, payload: {bound: [slot]}}`, every slot bound now, then `{sub, payload: {slot, bound}}` per change, `bound` again when the slot is usable again. A module that isn't a view is refused, as `{sub, end: true, error}`.
+  - `{op: "log", view: {actor, module}, level, message, fields?}` adds a line to the view's Actor's log, through the Hub's `viewLog`, which bounds it as a frame's line is; nothing answers.
 
-Use Node 22.13 or later. Run `npm ci`, `npm run check` and `npm test`; tests build the
-server, clients and Actor library before running. CI also packs the SDK, installs it in an isolated
-consumer, checks strict declarations, and starts that flow in Node 22/24 containers. To check a
-local archive, run `node scripts/verify-packed-sdk.mjs <sdk.tgz>`. AgentOrg is pre-alpha; its protocol may change.
+  A socket holds 256 subscriptions and 64 calls in flight at most (past it, `busy`). A tab's socket must come from the gateway's own `Origin`, and its first message must be `{op: "hello", session}` with a live session, answered `{op: "hello"}`; otherwise it's closed with code 4401, and the tab signs in again. The CLI gets in with the token in `<home>/cli-token` (0600, new at each start) as a bearer. The gateway answers only to `127.0.0.1:<port>` in `Host`, so a page that rebinds DNS to loopback gets nothing.
+- **What the calls reach:**
+  - Calls run through the person's slots: `packages`, `actors`, `bindings`, `grants`, `exports`, `audit`, `store`, and the two the first run binds, either of which may be unbound: `installer` (`installer@1`) and `login` (`account.login@1`, the model's sign-in).
+  - `layout` is the person's own export, served by the gateway.
+  - With `view: {actor, module}`, a call runs as that view's Actor, through the Hub's view path (`viewCall` and `viewSubscribe`). The Hub refuses a module that isn't one of the Actor's views, or an Actor that isn't running.
+- **The first run,** at every start once the person's store is bound, beside serving: the shell follows the person's bindings as they're made (`firstRun` in `src/model.ts`; `app.firstRun` settles with what it made; `startApp({firstRun: false})` leaves a home as it is):
+  - it adds the bundled packages, `installer`, `chatgpt`, `assistant` and the `board` example, built into `dist/bundled` with the app (`scripts/bundle.js`);
+  - 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`.
 
-[MIT license](LICENSE).
+  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.
+- **`/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.
+- **`layout@1`:** the person exports it, so a program bound to it places a view as the person does. Each placement records `by`, the Actor that placed it, from the call's caller as the Hub names it (the person, through `/api`); no input sets it. The layout is kept in the person's `store` slot (`kv@1`) under the key `layout`, and the app binds that slot to the built-in `storage` where there is one.
+  - `place` takes only a `view` module of a package Actor, with no `after` meaning last.
+  - `move` with no `after` means first.
+  - Every change tells `changed`.
+- **Packages and systems, as files:** for the person's UIs only, a tab by its session and the CLI by its token, sent as `Authorization: Bearer`, which no other page can send.
+  - `GET /packages/<hash>.agentorg`: a stored package's archive, made again from its stored tree in the SDK's deterministic tar, so the same bytes `agentorg build` writes.
+  - `POST /packages`: an archive to add, through a private temporary file in the home, verified by `hub.packages.add`, then deleted. It's answered with the package's hash and manifest.
+  - `GET /system`: the system's file, `<name>.agentorg-system`, a tar of `composition.json` (the installer's `exportSystem`) and `packages/<hash>.agentorg` for every package it pins.
+  - `POST /system`: a system file. Its entries must be exactly `composition.json` and `packages/sha256-<64 hex>.agentorg`, regular files only. Each package is added under its hash's name, so one whose hash isn't its name is refused. Then the installer's `importSystem` runs with the person's authority.
+  - Files are 64 MiB at most (`too_large`, 413 past it), and failures answer `{error}` as `/api` does.
+  - The person's `installer` slot, bound by the app's first run, serves both.
+- **`/frames/`:** a view's frame, its runtime and its bundle, for `view` modules only, and only by package hash. Every response's policy is `sandbox allow-scripts`, so whatever loads there runs on an opaque origin, even opened as a top page, and never as the shell's origin, where the session is. It allows scripts only from the gateway's `/frames/`, inline styles, and no fetches, forms or windows. The frame's origin is opaque, so its module scripts are CORS requests from `Origin: null`: only those are answered `Access-Control-Allow-Origin: null`, and nothing there reads or needs the session.
+- **The app's own pages** carry a policy of their own: scripts and styles from the app only, framed by nothing.
+- **The shell,** `@agentorg/shell`, is what the gateway serves at `/`: one socket to `/api`, and nothing it decides on its own.
+  - **Agents** are the package Actors with a `chat` view. Selecting one mounts that view in the main container, with the placements beside it whose `actor` is that agent or whose `by` is. Between them, a handle (dragged, or the arrow keys) sets that column's width, from 280 to 640 px and at most half the stage, kept in this browser; an agent with nothing beside it has no column, and its chat takes the width. A placed view, beside an agent or on Home, takes the height its frame reports; one that reports none keeps the default.
+  - **Home** shows the open grant requests, with Allow and Decline, then every placement of `layout@1`, in order. Each event (`layout` `changed`, `grants` `requested` and `decided`, `actors` `changed`, and the audit's package and binding entries) reads its part again. A subscription the gateway ends is made again after a wait (1 s, growing to 30 s while it keeps ending), and what it says is read again then; a view's own subscriptions end in its frame instead.
+  - **Settings** reads the Actors, packages and connections through `hub.*`, and the ChatGPT account through `login` when it's bound; the person is "you". An external Actor, the person included, shows whether it's connected; a package Actor its process state; a built-in one runs inside the Hub. **Packages** downloads each archive (`GET /packages/<hash>.agentorg`) and installs one from a file: uploaded to `POST /packages`, then `installer.plan` shows each slot's candidates (a slot's only one preselected), `installer.install` makes it with the person's picks (a connection the person can't grant is named, to leave unconnected), and its views can be placed on home; slots left unconnected and seeds that didn't land are listed. **System** exports the system as one file (`GET /system`), listing what it leaves out, and imports one (`POST /system`): what it made, what isn't as it was, and each management connection, for the person to grant one by one.
+  - **New agent** is offered once the first run has recorded the app's assistant, by hash, in the person's store (`app/first-run`), never a package found by its name. It is `installer.install` of that package with step 5's connections plus `logic.installer` to the installer, less the grants switched off, started, all or nothing; then it opens. The ChatGPT and installer it connects to are the ones the person's `login` and `installer` are bound to. `installAgent` in `@agentorg/shell/agent-bindings` makes that call, for a test too, and returns the installer's answer. "install Actors" needs "create and run Actors": with that off, it is off too and can't be switched on. A refusal is said plainly in the dialog, in room kept for it: a grant that isn't the person's to give, by name, or that AgentOrg isn't set up yet. A grant left on that the installer didn't connect, or a seed that didn't land, is listed before the agent opens.
+  - **Views** each get their own frame and `FrameHost`. Their calls run with `view: {actor, module}`, `openExternal` opens a new tab with no opener, `signIn` is the shell's ChatGPT sign-in, and their log lines go to their Actor's log (`agentorg call actors logs`). Each frame watches its view's slots while it's open, loads with the bound ones, and passes the frame each change, so a view placed before its Actor runs comes alive when it does.
+  - **ChatGPT sign-in** calls `login.start`, opens the consent page in a new tab, and moves on when `login` says `signed_in`. Until the Actor the person's `login` is bound to is connected, its button is disabled and says ChatGPT is starting; nothing opens from a wait, and a sign-in asked for meanwhile (a view's `signIn`) is refused with "ChatGPT is still starting. Try again in a moment." The one-time plan notice is remembered in the person's store under `ui/plan-notice`.

package/dist/bundled/index.json

@@ -0,0 +1,6 @@
+{
+  "installer": "sha256-51ecf151e590f5e57f28229d4cb36e4932a2f1670e50ddf1a3ccf335a1ee146d.agentorg",
+  "chatgpt": "sha256-b76ec31282e5b863ee9569dfd9d50b283a21101cbe1b3fac23d1cbcf16b9a408.agentorg",
+  "assistant": "sha256-e4c0e857cea3a721998effe2ca859c4011978b9bc36e63c058bfc17c27a1772e.agentorg",
+  "board": "sha256-87e121cbe58279f3a633e61c9773b61fc17fd53eac3d7c6f037925cbfd5d5384.agentorg"
+}

package/dist/src/api.d.ts

@@ -0,0 +1,55 @@
+/** A view the person has open: an Actor's `view` module. */
+export interface View {
+    actor: string;
+    module: string;
+}
+/** The person's own side: its slots, and `layout`, its own export, which the gateway serves. */
+export interface PersonSide {
+    call(slot: string, method: string, input: unknown): Promise<unknown>;
+    /** Events until the returned stop; `end` when the subscription can't go on. */
+    subscribe(slot: string, event: string, send: (payload: unknown) => void, end: () => void): () => void;
+}
+/**
+ * Calls run as a view's Actor through its `module.slot` bindings: the Hub's in-process view path
+ * (`hub.viewCall` and `hub.viewSubscribe`), validated and audited like any call. The Hub refuses a
+ * module that isn't one of the Actor's views, so any view of the Actor's package is open to the
+ * person, and nothing else is.
+ */
+export interface ViewCalls {
+    call(view: View, slot: string, method: string, input: unknown): Promise<unknown>;
+    subscribe(view: View, slot: string, event: string, send: (payload: unknown) => void, end: () => void): () => void;
+    /**
+     * The view's slots: `onSlot` hears each bound one at once, then every change (bound again when
+     * it's usable again). Returns how to stop. Refused for a module that isn't a view.
+     */
+    slots(view: View, onSlot: (slot: string, bound: boolean) => void): () => void;
+    /** A line for the view's Actor's log, which the Hub bounds as it does a frame's. */
+    log(view: View, level: "info" | "warn" | "error", message: string, fields?: Record<string, unknown>): void;
+}
+/** The socket a tab or the CLI holds: text messages in, text messages out. */
+export interface Socket {
+    send(text: string): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * One `/api` socket: the same calls a channel carries, as JSON.
+ *
+ * - `{id, op: "call", slot, method, input}`, or with `view: {actor, module}` for a view's slot;
+ *   answered `{id, result}` or `{id, error}`.
+ * - `{sub, op: "subscribe", slot, event}` (or with `view`): then `{sub, payload}` per event, and
+ *   `{sub, end: true}` once it can't go on. `{sub, op: "unsubscribe"}` stops it.
+ * - `{sub, op: "slots", view}`: the view's slots. First `{sub, payload: {bound: [slot]}}`, every
+ *   one bound now, then `{sub, payload: {slot, bound}}` per change, `bound` again for a slot that's
+ *   usable again. `{sub, op: "unsubscribe"}` stops it, as a subscription.
+ * - `{op: "log", view, level, message, fields?}`: a line for the view's Actor's log, unanswered.
+ *
+ * A view's calls run as its Actor, for one of its views only, which the Hub checks. Everything else
+ * runs as the person: through its own slots, and `layout`, its own export.
+ */
+export declare function serveSocket(socket: Socket, deps: {
+    person: PersonSide;
+    views: ViewCalls;
+}): {
+    receive(text: string): void;
+    closed(): void;
+};

package/dist/src/api.js

@@ -0,0 +1,182 @@
+import { NotConnected, OutcomeUnknown, Refused } from "@agentorg/sdk";
+/** Subscriptions one socket may hold. */
+const MAX_SUBSCRIPTIONS = 256;
+/** Calls one socket may have in flight; past it, `busy`. */
+const MAX_CALLS = 64;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isName = (value) => typeof value === "string" && value.length > 0 && value.length <= 256;
+const isId = (value) => Number.isSafeInteger(value) && value > 0;
+function errorBody(error) {
+    if (error instanceof Refused)
+        return { name: "Refused", message: error.message, code: error.code };
+    if (error instanceof NotConnected)
+        return { name: "NotConnected", message: error.message };
+    if (error instanceof OutcomeUnknown)
+        return { name: "OutcomeUnknown", message: error.message };
+    return { name: "Refused", message: "The gateway couldn't handle this.", code: "internal" };
+}
+/**
+ * One `/api` socket: the same calls a channel carries, as JSON.
+ *
+ * - `{id, op: "call", slot, method, input}`, or with `view: {actor, module}` for a view's slot;
+ *   answered `{id, result}` or `{id, error}`.
+ * - `{sub, op: "subscribe", slot, event}` (or with `view`): then `{sub, payload}` per event, and
+ *   `{sub, end: true}` once it can't go on. `{sub, op: "unsubscribe"}` stops it.
+ * - `{sub, op: "slots", view}`: the view's slots. First `{sub, payload: {bound: [slot]}}`, every
+ *   one bound now, then `{sub, payload: {slot, bound}}` per change, `bound` again for a slot that's
+ *   usable again. `{sub, op: "unsubscribe"}` stops it, as a subscription.
+ * - `{op: "log", view, level, message, fields?}`: a line for the view's Actor's log, unanswered.
+ *
+ * A view's calls run as its Actor, for one of its views only, which the Hub checks. Everything else
+ * runs as the person: through its own slots, and `layout`, its own export.
+ */
+export function serveSocket(socket, deps) {
+    const subscriptions = new Map();
+    let calls = 0;
+    const send = (message) => {
+        try {
+            socket.send(JSON.stringify(message));
+        }
+        catch {
+            // The socket is gone; its close stops the rest.
+        }
+    };
+    const viewOf = (value) => {
+        if (value === undefined)
+            return undefined;
+        if (!isRecord(value) || !isName(value.actor) || !isName(value.module))
+            throw new Refused("invalid", "A view is {actor, module}.");
+        return { actor: value.actor, module: value.module };
+    };
+    const receive = (text) => {
+        let message;
+        try {
+            const parsed = JSON.parse(text);
+            if (!isRecord(parsed))
+                return;
+            message = parsed;
+        }
+        catch {
+            return;
+        }
+        switch (message.op) {
+            case "call": {
+                const { id, slot, method, input } = message;
+                if (!isId(id))
+                    return;
+                if (calls >= MAX_CALLS) {
+                    const busy = new Refused("busy", `A socket has ${MAX_CALLS} calls in flight at most.`);
+                    return send({ id, error: errorBody(busy) });
+                }
+                calls++;
+                void (async () => {
+                    if (!isName(slot) || !isName(method))
+                        throw new Refused("invalid", "A call names its slot and method.");
+                    const view = viewOf(message.view);
+                    return view
+                        ? deps.views.call(view, slot, method, input)
+                        : deps.person.call(slot, method, input);
+                })()
+                    .then((result) => send({ id, result }), (error) => send({ id, error: errorBody(error) }))
+                    .finally(() => calls--);
+                return;
+            }
+            case "subscribe": {
+                const { sub, slot, event } = message;
+                if (!isId(sub) || subscriptions.has(sub))
+                    return;
+                let ended = false;
+                const end = () => {
+                    if (ended)
+                        return;
+                    ended = true;
+                    subscriptions.get(sub)?.();
+                    subscriptions.delete(sub);
+                    send({ sub, end: true });
+                };
+                try {
+                    if (!isName(slot) || !isName(event))
+                        throw new Refused("invalid", "A subscription names its slot and event.");
+                    if (subscriptions.size >= MAX_SUBSCRIPTIONS)
+                        throw new Refused("quota", `A socket holds ${MAX_SUBSCRIPTIONS} subscriptions at most.`);
+                    const view = viewOf(message.view);
+                    const forward = (payload) => {
+                        if (!ended)
+                            send({ sub, payload });
+                    };
+                    const stop = view
+                        ? deps.views.subscribe(view, slot, event, forward, end)
+                        : deps.person.subscribe(slot, event, forward, end);
+                    if (ended)
+                        stop();
+                    else
+                        subscriptions.set(sub, stop);
+                }
+                catch (error) {
+                    ended = true;
+                    send({ sub, end: true, error: errorBody(error) });
+                }
+                return;
+            }
+            case "slots": {
+                const { sub } = message;
+                if (!isId(sub) || subscriptions.has(sub))
+                    return;
+                try {
+                    if (subscriptions.size >= MAX_SUBSCRIPTIONS)
+                        throw new Refused("quota", `A socket holds ${MAX_SUBSCRIPTIONS} subscriptions at most.`);
+                    const view = viewOf(message.view);
+                    if (!view)
+                        throw new Refused("invalid", "A slots watch names its view.");
+                    // The Hub tells the bound slots at once, within the call: gathered, they're one snapshot.
+                    let snapshot = [];
+                    const stop = deps.views.slots(view, (slot, bound) => {
+                        if (snapshot && bound)
+                            snapshot.push(slot);
+                        else if (!snapshot)
+                            send({ sub, payload: { slot, bound } });
+                    });
+                    send({ sub, payload: { bound: snapshot } });
+                    snapshot = undefined;
+                    subscriptions.set(sub, stop);
+                }
+                catch (error) {
+                    send({ sub, end: true, error: errorBody(error) });
+                }
+                return;
+            }
+            case "log": {
+                const { level, message: text, fields } = message;
+                if (level !== "info" && level !== "warn" && level !== "error")
+                    return;
+                if (typeof text !== "string")
+                    return;
+                try {
+                    const view = viewOf(message.view);
+                    if (view)
+                        deps.views.log(view, level, text, isRecord(fields) ? fields : undefined);
+                }
+                catch {
+                    // Not one of an Actor's views: nothing is logged, and nothing answers.
+                }
+                return;
+            }
+            case "unsubscribe": {
+                const stop = isId(message.sub) ? subscriptions.get(message.sub) : undefined;
+                if (!stop)
+                    return;
+                subscriptions.delete(message.sub);
+                stop();
+                return;
+            }
+        }
+    };
+    return {
+        receive,
+        closed() {
+            for (const stop of subscriptions.values())
+                stop();
+            subscriptions.clear();
+        },
+    };
+}