@agentshouse/app-bridge 0.1.0-ca4ec913df08d → 0.1.0-ca559eade7c19

package/dist/test-host.js

@@ -1,5 +1,5 @@
 const HOST_ORIGIN = 'https://house.invalid';
-const ADDRESS_MAX_CHARS = 1000;
+const ADDRESS_MAX_CHARS = 64 * 1024;
 function sameOriginPath(value) {
     if (typeof value !== 'string')
         return null;
@@ -16,15 +16,34 @@ function appAddress(address) {
 function ceremonyRefused(path) {
     return Object.assign(new Error('house_ceremony_refused'), {
         name: 'HouseCeremonyRefused',
+        code: 'house_ceremony_refused',
+        retryable: false,
         path,
     });
 }
 function navigationRefused(address) {
     return Object.assign(new Error('house_navigation_refused'), {
         name: 'HouseNavigationRefused',
+        code: 'house_navigation_refused',
+        retryable: false,
         address,
     });
 }
+function followHeld(listeners, listener, held) {
+    let following = true;
+    queueMicrotask(() => {
+        if (!following)
+            return;
+        listeners.add(listener);
+        const value = held();
+        if (value !== null)
+            listener(value);
+    });
+    return () => {
+        following = false;
+        listeners.delete(listener);
+    };
+}
 export function createHouseBridgeTestHost(options = {}) {
     const navigations = [];
     const ceremonies = [];
@@ -38,6 +57,7 @@ export function createHouseBridgeTestHost(options = {}) {
     let published = options.status ?? null;
     let shown = null;
     let seen = null;
+    let cooperation = null;
     let attached = () => { };
     const runtime = new Promise((resolve) => {
         attached = resolve;
@@ -59,7 +79,17 @@ export function createHouseBridgeTestHost(options = {}) {
         });
     }
     function navigate(mode, asked) {
-        const target = sameOriginPath(asked);
+        let path = asked;
+        if (/^https?:\/\//i.test(asked)) {
+            try {
+                const target = new URL(asked);
+                path = target.origin === HOST_ORIGIN ? target.pathname + target.search + target.hash : '';
+            }
+            catch {
+                path = '';
+            }
+        }
+        const target = sameOriginPath(path);
         if (target === null)
             return Promise.reject(navigationRefused(asked));
         navigations.push({ mode, address: target });
@@ -72,10 +102,7 @@ export function createHouseBridgeTestHost(options = {}) {
         runtime,
         address: () => shown,
         onAddress(listener) {
-            addressListeners.add(listener);
-            return () => {
-                addressListeners.delete(listener);
-            };
+            return followHeld(addressListeners, listener, () => shown);
         },
         push: (asked) => navigate('push', asked),
         replace: (asked) => navigate('replace', asked),
@@ -92,17 +119,6 @@ export function createHouseBridgeTestHost(options = {}) {
         setTab(tab) {
             tabs.push(tab);
         },
-        readAttachment(room, attachment) {
-            const image = options.images?.find((entry) => entry.room === room && entry.attachment === attachment);
-            return Promise.resolve(image === undefined
-                ? null
-                : {
-                    attachment: image.attachment,
-                    copy: image.copy,
-                    name: image.name,
-                    media_type: image.media_type,
-                });
-        },
         sourceTop: (app) => Promise.resolve(options.sources?.find((entry) => entry.top.app_ref === app)?.top ?? null),
         sourceDownload: (app) => Promise.resolve(options.sources?.find((entry) => entry.top.app_ref === app)?.download ?? null),
         callExternal(request) {
@@ -113,10 +129,7 @@ export function createHouseBridgeTestHost(options = {}) {
         readSiteScreenshot: (site) => Promise.resolve(options.siteScreenshots?.[site] ?? null),
         status: () => seen,
         onStatus(listener) {
-            statusListeners.add(listener);
-            return () => {
-                statusListeners.delete(listener);
-            };
+            return followHeld(statusListeners, listener, () => seen);
         },
         messages(listener) {
             messageListeners.add(listener);
@@ -132,7 +145,19 @@ export function createHouseBridgeTestHost(options = {}) {
             consents.push(choice);
             publish({ ...published, analytics: { measures: true, choice } });
         },
+        cooperate(given) {
+            cooperation = given;
+            return () => {
+                if (cooperation === given)
+                    cooperation = null;
+            };
+        },
     };
+    function cooperating() {
+        if (cooperation === null)
+            throw new Error('the App registered no cooperation');
+        return cooperation;
+    }
     Object.defineProperty(globalThis, 'houseBridge', { value: bridge, configurable: true });
     if (published !== null)
         publish(published);
@@ -157,5 +182,19 @@ export function createHouseBridgeTestHost(options = {}) {
         attachRuntime(client) {
             attached(client);
         },
+        async checkpoint() {
+            const held = cooperating();
+            await held.checkpoint();
+            await held.persist();
+            return JSON.parse(JSON.stringify((await held.capture()) ?? null));
+        },
+        async restore(task) {
+            const held = cooperating();
+            await held.restore(task);
+            return (await held.ready()) === true;
+        },
+        settle(activation) {
+            cooperating().settle(activation);
+        },
     };
 }

package/docs/families.md

@@ -12,23 +12,25 @@
   purpose-bound authenticated pages. The shell navigates only to a same-origin
   absolute path, carries its current address as the return target, and the page
   returns there when it completes. An App names an address House gave it in a
-  reading and composes none.
+  reading and composes one only for `/bind/<app_ref>`, where the User binds
+  its Rooms and connects its account slots, with `?slot=<name>` to open at one
+  slot.
 - **Installation** - `install()` offers the page as a Home-screen app. Where the
   browser has an install prompt ready the shell shows it and the call resolves
   `'accepted'` or `'dismissed'` with the User's choice, spending that prompt;
   otherwise, as on every iPhone and iPad, it resolves `'manual'` and the App
   shows its own instructions. A prompt the browser refuses to show, as for a
-  call made without a click, rejects with the browser's own `DOMException`
-  and stays ready. Call it from a click. The standard
+  call made without a click, rejects with an error named and coded by the
+  browser's own error name, with `retryable` false, and stays ready. Call it from a click. The standard
   `display-mode: standalone` media query tells the App it runs installed.
 - **Notifications** - House's own panel alone; an App's or a Site's call
-  rejects with an error named `HouseCeremonyRefused`. `notifications()` answers this browser
+  rejects with an error named `HouseCeremonyRefused`, carrying `code` and `retryable`. `notifications()` answers this browser
   storage's push state: `'on'`, `'off'`, `'blocked'` where the browser refuses
   notifications, or `'unavailable'` where it has no push, as on an iPhone or
   iPad outside a Home-screen app. `notifications(true)` asks the browser's
   permission and subscribes, `notifications(false)` unsubscribes, and each
-  answers the state it leaves; a failure of the browser's push service rejects
-  with the browser's own `DOMException`. Call `notifications(true)` from a
+  answers the state it leaves; a failure of the browser's push service, and
+  of `setBadge`, rejects the same way. Call `notifications(true)` from a
   click. `setBadge(unread)` takes the identifiers of the Human Notifications
   unread in this storage and sets the icon's badge to their number, or clears
   it at none, where the browser shows one.
@@ -39,10 +41,21 @@
   whether the page measures and the visitor's stored analytics choice, and
   `serviceMode`: `open`, `write-halted` while House refuses writes, so the
   App can stop retrying them, or `null` while the runtime holds no House
-  connection. Every status field is camelCase.
+  connection. Every status field is camelCase. `onStatus(listener)` and
+  `onAddress(listener)` hand a listener the status and the address the bridge
+  already holds, then each change.
   The App reports the visitor's choice with `analyticsConsent('accept')` or
   `analyticsConsent('decline')`; the shell hands it to House's analytics loader, and
   the choice never reaches House.
+- **Handoff** - when House hands its runtime over to a newer build, the App keeps
+  running, its `runtime` client and observations included: a call it makes
+  meanwhile waits for the newer runtime, however long that takes, and is
+  answered once, by it; each observation goes on with the newer runtime's
+  values; and the status and the address arrive again. A runtime that ended
+  before answering has its reads answered by the next one; since it may have
+  applied any other call, an act on House is answered the outcome
+  `transport-uncertainty`, and every other call, a Save or a draft write among
+  them, fails with the retryable code `transport-uncertainty`.
 - **Site image read** - given a Published Room and an original attachment
   reference, it answers the web copy's path and metadata, or `null` when no
   copy exists. The original bytes never cross this bridge at a Site.
@@ -53,23 +66,24 @@
   path, its size and its `text`, or its bytes as `base64`. The browser keeps
   each answer per App and release: a read naming a release it holds answers
   without asking House, and keeping a newer release drops the earlier one. A
-  refusal is House's `{ error: { code } }`, `app_release_not_found` for an
+  refusal is House's `{ error: { code, retryable } }`, `app_release_not_found` for an
   App with no release; a read House does not answer, or one that outlived
   the browser's signed-in User, is `null`.
-- **External calls** - `callExternal({ url, method, headers, body, slot })`
+- **External calls** - `callExternal({ url, method, headers, body, slot, room_ref })`
   has House's server send an HTTPS request to one of the release's declared
   external origins and resolves with the service's `status`, `headers` and its
   body as `body` text or `body_base64`, or a refusal as House's
-  `{ error: { code } }`, or `null` when House does not answer. House fills in the
-  App and its running release; naming an account slot places the key of the
-  account the User connected to it, which the App never sees, and naming none
-  sends no key. A Site's call names no slot, and the House panel names an
+  `{ error: { code, retryable } }`, or `null` when House does not answer. House fills in the
+  App and its running release; naming an account slot and one of the App's
+  bound Rooms places the key of the account that Room connects to the slot,
+  when the User holds one of the account's roles there, which the App never
+  sees, and naming neither sends no key. A Site's call names no slot, and the House panel names an
   `account` instead. `body_base64` replaces `body` for bytes.
 - **App messages** - `messages(listener)` hands the listener each message
   another holder of this App sends to this User's running copies, as `from`,
   the sender's User id, and `body`, the JSON value they sent, until the
   function it returns is called. App code sends one through the Runtime's
-  `call('apps/messages/send', { to, body })` with the recipient's User id and
+  `call('message.send', { to, body })` with the recipient's User id and
   a body of at most 32 KiB of JSON; House fills in the App and relays it only
   to copies running now, storing nothing. The panel sends none.
 - **App screenshot read** - given an App reference, `readScreenshot(app)`
@@ -82,6 +96,31 @@
   after its latest release, as a JPEG `Blob`, or `null` when House holds none
   or does not answer. A Site's own renderer reads none.
 
+- **Cooperation** - `cooperate({ checkpoint, persist, capture, restore,
+ready, settle })` lets House activate a newer release of the App while it
+  runs, keeping the User's task; the function it returns withdraws it.
+  Register it in the entry script, before the first draw, or House treats the
+  page as not cooperating and the newer release waits for the App's next
+  open. When a newer release is stored, House calls `checkpoint()`, which
+  resolves at the App's next safe checkpoint and may never resolve, then
+  `persist()`, which makes authored work durable, then `capture()`, which
+  answers the meaningful task the App owns, such as the selected record,
+  filters, cursor, selection and scroll position, as JSON of at most 65,536
+  characters; House keeps the address itself. In the newer release House
+  calls `restore(task)` once its document has drawn, so the scroll position
+  and focus it sets hold, or `restore(null)` when it opens the release without
+  a task, then `ready()`, the App's own check that its local data and
+  capabilities work, and finally `settle('committed')` once the release is
+  active or `settle('abandoned')` when House returns to the release before
+  it, restoring the same task there. A release House opens already active is
+  settled `'committed'` at once, after `restore(task)` when House hands it a
+  task, and a cooperation registered after House settled is settled at its
+  registration. Until `settle('committed')` House fails the release's outside
+  calls at once, as offline, those of the workers it starts included, and
+  refuses its Saves, write acts and external calls with the retryable code
+  `house_trial_withheld`, so a start-up effect is not repeated; run start-up
+  effects after `settle('committed')`.
+
 ## The test host
 
 `createHouseBridgeTestHost(options)` plays House in one page: it installs a
@@ -104,4 +143,7 @@ given by Site identifier, answers every `install()` `'manual'`, as a browser
 with no install prompt does, answers every `notifications()` `'unavailable'`,
 as a browser without push does, settles every `setBadge`, delivers each App
 message `message({ from, body })` plays, and hands `bridge.runtime` the MD
-Runtime client `attachRuntime(client)` gives it.
+Runtime client `attachRuntime(client)` gives it. `checkpoint()` runs the
+registered cooperation's checkpoint, persist and capture and answers the task,
+`restore(task)` runs its restore and answers its readiness check, and
+`settle(activation)` hands it the outcome.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-ca4ec913df08d",
+  "version": "0.1.0-ca559eade7c19",
   "description": "Types of the agents.house App bridge House hands every App: navigation, the tab title and icon, ceremonies, installation, notifications and the icon badge, status, Site image reads, App release code, App and Site screenshot reads, and App messages, with an accessor and an in-page test host.",
   "license": "MIT",
   "type": "module",
@@ -18,9 +18,6 @@
       "default": "./dist/test-host.js"
     }
   },
-  "dependencies": {
-    "@agentshouse/mdruntime": "0.1.0-cf6d5f0a5c9c8"
-  },
   "files": [
     "dist",
     "docs",