@fungi.computer/oyster 0.4.1 → 0.6.0

package/dist/workers.js

@@ -35,10 +35,11 @@ import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { releaseSchema } from "@fungi.computer/puffball/effect";
 import { AppInstanceError, } from "./index.js";
-import { createCloudflareAppInstance, r2ArtifactStore, createCloudflareInvocationGate, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
+import { createCloudflareAppInstance, r2ArtifactStore, createCloudflareInvocationGate, edgeVerifiedObjectCache, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
 import { invocationFactsSchema, assertBackgroundBinding, admitBackgroundFrame, } from "./invocation.js";
 import { deliverBackground, deliverGitPush } from "./internal/delivery.js";
-import { createOyster, verifyRelease, defaultAssetPolicy, } from "./host.js";
+import { releaseCache } from "./internal/host-gate.js";
+import { createOyster, } from "./host.js";
 import { createGitPushJournal } from "./git-journal.js";
 import { AppStorageError, } from "@fungi.computer/agar/storage";
 import { storageFrameMethods } from "./storage-frame.js";
@@ -148,6 +149,7 @@ export class OysterRegistry extends DurableObject {
         return this.approvalHome(pin).capability(actor).setAutoApprove(input);
     }
     #rootData;
+    #releases = releaseCache(r2ArtifactStore(this.env.RELEASES));
     /** Append-only App source seed receipts; a Git-capable subclass forks over these. */
     appSourceReceipts;
     /** Team-owned fork registrations, one App publisher record per App. */
@@ -196,7 +198,7 @@ export class OysterRegistry extends DurableObject {
             installations: {
                 list: () => Promise.resolve(this.list()),
             },
-            resolveRelease: (release) => verifyRelease(r2ArtifactStore(env.RELEASES), release, defaultAssetPolicy, false),
+            resolveRelease: this.#releases,
         });
     }
     /** The installation owner's RPC: admit, read, load, plan or commit one
@@ -319,7 +321,7 @@ export class OysterRegistry extends DurableObject {
                                 expected.selection.releaseId ||
                             installation.release.appId !== expected.selection.appId)))
                     throw new AppStorageError("unavailable");
-                const resolved = await verifyRelease(r2ArtifactStore(this.env.RELEASES), installation.release, defaultAssetPolicy, false);
+                const resolved = await this.#releases(installation.release);
                 if (expected !== undefined &&
                     resolved.backend?.digest !== expected.artifactDigest)
                     throw new AppStorageError("unavailable");
@@ -756,9 +758,9 @@ export class OysterInstance extends DurableObject {
     }
     async executeBindingCall(raw, method, input) {
         const props = decodeFrameBindingProps(raw);
-        const frame = this.frames.active();
-        if (props.instanceId !== frame.facts.instanceId ||
-            props.frameId !== frame.frameId)
+        // The packet's own frame: a closed or foreign frame id refuses.
+        const frame = this.frames.active(props.frameId);
+        if (props.instanceId !== frame.facts.instanceId)
             throw new AppInstanceError("revoked");
         assertBackgroundBinding(frame, props.binding);
         // A guest packet is its own entry: exactly one registry read re-admits it.
@@ -787,7 +789,7 @@ export class OysterInstance extends DurableObject {
             .every((operation) => granted.includes(operation)))
             throw new AppInstanceError("binding_not_granted");
         const result = await row.dispatch(this.#bindingContext, frame, props, method, args);
-        if (this.frames.active() !== frame)
+        if (this.frames.active(props.frameId) !== frame)
             throw new AppInstanceError("revoked");
         assertBackgroundBinding(frame, props.binding);
         return descriptor.decodeResult(result);
@@ -1102,10 +1104,7 @@ export function oysterWorkerHost(env, auth, options = {}) {
         },
         auth,
         workbench: {
-            directory: async () => {
-                await installations.list();
-                return registry().directory();
-            },
+            directory: () => registry().directory(),
             storage: (installationId, ownerId) => ({
                 read: (key) => registry().storageRead(installationId, ownerId, key),
                 write: (input) => registry().storageWrite(installationId, ownerId, input),
@@ -1115,6 +1114,10 @@ export function oysterWorkerHost(env, auth, options = {}) {
         },
         guestLimits: guestLimits(options.guestLimits),
         artifacts,
+        // Workers and workerd keep a zone cache; a runtime without one reads R2.
+        ...("caches" in globalThis && {
+            uiCache: edgeVerifiedObjectCache(caches.default, scope.origin),
+        }),
         bootUi: oysterBootUi(env, scope),
         // File-only hosts may keep workspace files beside their Release artifacts.
         capabilities: [

package/docs/api/agents.md

@@ -358,16 +358,20 @@ optional bearer.
 ### agentCapabilities()
 
 ```ts
-function agentCapabilities(agents): readonly Readonly<object & object>[];
+function agentCapabilities(
+  agents,
+  liveKey,
+): readonly Readonly<object & object>[];
 ```
 
 Agent adapters admitted against each App's declared capabilities.
 
 #### Parameters
 
-| Parameter | Type                            |
-| --------- | ------------------------------- |
-| `agents`  | [`OysterAgents`](#oysteragents) |
+| Parameter | Type                                                                                                                                                                                                                                                                 |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents`  | [`OysterAgents`](#oysteragents)                                                                                                                                                                                                                                      |
+| `liveKey` | (`keyId`) => `Promise`\< \| `Readonly`\<\{ `keyId`: `string`; `owner`: `string`; `grantVersion`: `number`; `grants`: readonly `Readonly`\<\{ `capability`: [`OysterKeyCapability`](keys.md#oysterkeycapability); `targets`: `GrantTargets`; \}\>[]; \}\> \| `null`\> |
 
 #### Returns
 

package/docs/api/apps.md

@@ -852,6 +852,10 @@ const gateRequestSchema: ZodLazy<ZodDiscriminatedUnion<[ZodObject<{
      | "channels.read"
     | "channels.personal.manage", unknown>>;
   operation: ZodString;
+  effect: ZodEnum<{
+     read: "read";
+     write: "write";
+  }>;
 }, $strict>], "kind">>;
 ```
 
@@ -1676,10 +1680,10 @@ stay outside this pure gate.
 
 #### Parameters
 
-| Parameter    | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `facts`      | [`GateFacts`](#gatefacts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `rawRequest` | \| \{ `kind`: `"method"`; `name`: `string`; `input`: `unknown`; `via`: `"ui"` \| `"agent"` \| `"mcp"` \| `"workflow"`; `resource?`: `Readonly`\<\{ `kind`: `string`; `id`: `string`; \}\>; \} \| \{ `kind`: `"capability"`; `capability`: \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"approvals"` \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `operation?`: `string`; `resource`: \| `"any"` \| `Readonly`\<\{ `kind`: `string`; `id`: `string`; \}\>; \} \| \{ `kind`: `"capability-route"`; `capability`: \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"approvals"` \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `operation`: `string`; \} \| \{ `kind`: `"binding"`; `binding`: \| `"BACKGROUND"` \| `"GIT"` \| `"EVENTS"` \| `"APPS"` \| `"WORKFLOWS"` \| `"APP_STORAGE"` \| `"MEDIA"` \| `"COMPUTER"` \| `"INBOX"` \| `"AGENTS"`; `operation`: `string`; \} \| \{ `kind`: `"list-tools"`; \} \| \{ `kind`: `"backend"`; \} |
+| Parameter    | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `facts`      | [`GateFacts`](#gatefacts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `rawRequest` | \| \{ `kind`: `"method"`; `name`: `string`; `input`: `unknown`; `via`: `"ui"` \| `"agent"` \| `"mcp"` \| `"workflow"`; `resource?`: `Readonly`\<\{ `kind`: `string`; `id`: `string`; \}\>; \} \| \{ `kind`: `"capability"`; `capability`: \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"approvals"` \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `operation?`: `string`; `resource`: \| `"any"` \| `Readonly`\<\{ `kind`: `string`; `id`: `string`; \}\>; \} \| \{ `kind`: `"capability-route"`; `capability`: \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"approvals"` \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `operation`: `string`; `effect`: `"read"` \| `"write"`; \} \| \{ `kind`: `"binding"`; `binding`: \| `"BACKGROUND"` \| `"GIT"` \| `"EVENTS"` \| `"APPS"` \| `"WORKFLOWS"` \| `"APP_STORAGE"` \| `"MEDIA"` \| `"COMPUTER"` \| `"INBOX"` \| `"AGENTS"`; `operation`: `string`; \} \| \{ `kind`: `"list-tools"`; \} \| \{ `kind`: `"backend"`; \} |
 
 #### Returns
 

package/docs/api/auth.md

@@ -8,6 +8,26 @@
 
 # auth
 
+## Type Aliases
+
+### OysterKeySessionResolver
+
+```ts
+type OysterKeySessionResolver = Readonly<{
+  resolve: (value) => Promise<Readonly<{
+    keyId: string;
+  }> | null>;
+}>;
+```
+
+The host owns session minting, hashing/storage and expiry. A session resolves
+only to a key id, never to owner or grant authority. Hosts should use Path=/,
+HttpOnly, Secure and SameSite=Lax (or stricter) as defense in depth; Oyster
+independently checks request provenance. Cookie-only admission allows GET/HEAD
+navigation. Every other method requires Origin to be present and equal the
+request URL's origin, and Sec-Fetch-Site not to be cross-site. Missing Origin is
+refused.
+
 ## Variables
 
 ### ownerKeyCookieName
@@ -18,6 +38,16 @@ const ownerKeyCookieName: "oyster_session" = "oyster_session";
 
 Cookie emitted by ownerKeyAuth, for composing credential-specific adapters.
 
+---
+
+### keySessionCookieName
+
+```ts
+const keySessionCookieName: "oyster_key_session" = "oyster_key_session";
+```
+
+Host-minted opaque sessions for named keys, separate from the owner cookie.
+
 ## Functions
 
 ### ownerKeyAuth()
@@ -61,3 +91,28 @@ The owner key, or a named key admitted as its canonical Team-key actor.
 #### Returns
 
 [`OysterAuth`](host.md#oysterauth)
+
+---
+
+### keySessionAuth()
+
+```ts
+function keySessionAuth(auth, ownerId, keys, sessions): OysterAuth;
+```
+
+Add host-owned browser sessions to ownerOrKeyAuth. Explicit credentials and
+non-401 refusals keep their ordinary result; ambient cookies cannot undo them.
+Every cookie admission rechecks the key's liveness and canonical owner.
+
+#### Parameters
+
+| Parameter  | Type                                                                  |
+| ---------- | --------------------------------------------------------------------- |
+| `auth`     | [`OysterAuth`](host.md#oysterauth)                                    |
+| `ownerId`  | `string`                                                              |
+| `keys`     | () => `NonNullable`\<[`OysterHost`](host.md#oysterhost)\[`"keys"`\]\> |
+| `sessions` | [`OysterKeySessionResolver`](#oysterkeysessionresolver)               |
+
+#### Returns
+
+[`OysterAuth`](host.md#oysterauth)

package/docs/api/browser.md

@@ -91,7 +91,7 @@ Data.TaggedError("CloudBrowserUrlDenied").message;
 
 ### CloudBrowserUpstreamError
 
-The provider (Cloudflare Browser Run) answered with a failure.
+The configured provider answered with a failure or is unreachable.
 
 #### Extends
 
@@ -593,10 +593,11 @@ type BrowserLimits = Readonly<{
 
 `@fungi.computer/oyster/browser`: the one agent browser for the Hub and a
 standalone Oyster. A host builds the port from a provider (`browserRunSessions`
-or `bindingSessions`, plus Browser Run Quick Reads when it has them), its
-required metering owner and an event sink; `createBrowser` owns lease ownership,
-egress policy and billing order; `browserCapabilitySource` is the agent's
-`cloudBrowser` tool. Raw CDP stays internal to this directory.
+or `bindingSessions` or `onboxBrowserSessions` on staging, plus Browser Run
+Quick Reads when it has them), its required metering owner and an event sink;
+`createBrowser` owns lease ownership, egress policy and billing order;
+`browserCapabilitySource` is the agent's `cloudBrowser` tool. Raw CDP stays
+internal to this directory.
 
 ---
 
@@ -643,10 +644,11 @@ type Browser = Readonly<{
 
 `@fungi.computer/oyster/browser`: the one agent browser for the Hub and a
 standalone Oyster. A host builds the port from a provider (`browserRunSessions`
-or `bindingSessions`, plus Browser Run Quick Reads when it has them), its
-required metering owner and an event sink; `createBrowser` owns lease ownership,
-egress policy and billing order; `browserCapabilitySource` is the agent's
-`cloudBrowser` tool. Raw CDP stays internal to this directory.
+or `bindingSessions` or `onboxBrowserSessions` on staging, plus Browser Run
+Quick Reads when it has them), its required metering owner and an event sink;
+`createBrowser` owns lease ownership, egress policy and billing order;
+`browserCapabilitySource` is the agent's `cloudBrowser` tool. Raw CDP stays
+internal to this directory.
 
 ---
 
@@ -1058,9 +1060,9 @@ caller (`browser.ts`) owns the deadline through `signal`.
 type BrowserSessions = Readonly<{}>;
 ```
 
-The provider half of the host port. Built only by the two functions below. Each
-step is separate so `createBrowser` owns a provider session id from the moment
-it exists, including when its CDP connect then fails.
+The provider half of the host port. Each step is separate so `createBrowser`
+owns a provider session id from the moment it exists, including when its CDP
+connect then fails.
 
 ---
 
@@ -1338,10 +1340,11 @@ function createBrowser(host, limits): Browser;
 
 `@fungi.computer/oyster/browser`: the one agent browser for the Hub and a
 standalone Oyster. A host builds the port from a provider (`browserRunSessions`
-or `bindingSessions`, plus Browser Run Quick Reads when it has them), its
-required metering owner and an event sink; `createBrowser` owns lease ownership,
-egress policy and billing order; `browserCapabilitySource` is the agent's
-`cloudBrowser` tool. Raw CDP stays internal to this directory.
+or `bindingSessions` or `onboxBrowserSessions` on staging, plus Browser Run
+Quick Reads when it has them), its required metering owner and an event sink;
+`createBrowser` owns lease ownership, egress policy and billing order;
+`browserCapabilitySource` is the agent's `cloudBrowser` tool. Raw CDP stays
+internal to this directory.
 
 #### Parameters
 
@@ -1438,3 +1441,24 @@ A standalone Oyster's own Workers BROWSER binding.
 #### Returns
 
 [`BrowserSessions`](#browsersessions)
+
+---
+
+### onboxBrowserSessions()
+
+```ts
+function onboxBrowserSessions(origin, fetcher?): BrowserSessions;
+```
+
+Staging uses Chromium's native CDP browser contexts; no session store.
+
+#### Parameters
+
+| Parameter | Type                      |
+| --------- | ------------------------- |
+| `origin`  | `string`                  |
+| `fetcher` | [`HttpFetch`](#httpfetch) |
+
+#### Returns
+
+[`BrowserSessions`](#browsersessions)

package/docs/api/build-contract.md

@@ -966,7 +966,7 @@ function putContentObject(
   object,
   body,
   mediaType,
-): Promise<"refused" | "stored">;
+): Promise<"stored" | "refused">;
 ```
 
 Stream one object into the store under its digest. The store refuses a body
@@ -987,7 +987,7 @@ the body is discarded, never stored.
 
 #### Returns
 
-`Promise`\<`"refused"` \| `"stored"`\>
+`Promise`\<`"stored"` \| `"refused"`\>
 
 ---
 

package/docs/api/cloudflare.md

@@ -305,6 +305,30 @@ frame or guestEnv factory is accepted.
 
 ---
 
+### edgeVerifiedObjectCache()
+
+```ts
+function edgeVerifiedObjectCache(cache, origin): VerifiedObjectCache;
+```
+
+The zone's edge cache as a [VerifiedObjectCache](host.md#verifiedobjectcache):
+each verified object under a digest-named key on `origin` that no route serves.
+A failed write is logged and answers `unstored`; the next reader verifies from
+the store again.
+
+#### Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| `cache`   | `Pick`\<`Cache`, `"match"` \| `"put"`\> |
+| `origin`  | `string`                                |
+
+#### Returns
+
+[`VerifiedObjectCache`](host.md#verifiedobjectcache)
+
+---
+
 ### r2ArtifactStore()
 
 ```ts
@@ -435,7 +459,8 @@ function createCloudflareInvocationGate<Host, FacetClass>(
 ): InvocationGate<Host>;
 ```
 
-End the native App facet before shared frame admission releases its permit.
+End the native App facet when live authority closes early, before the gate
+admits again.
 
 #### Type Parameters
 

package/docs/api/host.md

@@ -375,24 +375,17 @@ A capability adapter whose routes require live installation admission.
 ### OysterVariables
 
 ```ts
-type OysterVariables = object;
+type OysterVariables = TimingVariables & object;
 ```
 
 What the host stamps once per request; inner routes read it with `c.get`.
 
-#### Properties
-
-##### principal
-
-```ts
-principal: OysterPrincipal;
-```
-
-##### installation?
+#### Type Declaration
 
-```ts
-optional installation?: Installation;
-```
+| Name            | Type                                   |
+| --------------- | -------------------------------------- |
+| `principal`     | [`OysterPrincipal`](#oysterprincipal)  |
+| `installation?` | [`Installation`](apps.md#installation) |
 
 ---
 
@@ -473,6 +466,7 @@ type OysterHost = Readonly<{
   auth: OysterAuth;
   backgroundOriginKey?: () => Promise<CryptoKey>;
   artifacts: ArtifactStore;
+  uiCache?: VerifiedObjectCache;
   installations: InstallationStore;
   instances: InstanceDirectory;
   bootUi: (release) => Promise<UiBootCheckOutcome>;
@@ -1309,6 +1303,21 @@ type VerifiedRelease = Readonly<{
 
 A Release whose root, UI and backend artifacts were read and verified.
 
+---
+
+### VerifiedObjectCache
+
+```ts
+type VerifiedObjectCache = Readonly<{
+  match: (digest) => Promise<ReadableStream<Uint8Array> | null>;
+  put: (digest, bytes) => Promise<"stored" | "unstored">;
+}>;
+```
+
+Copies of verified artifacts near the reader, keyed by content digest. An entry
+holds only bytes that already matched its digest, so a hit is served without
+another store read or hash.
+
 ## Variables
 
 ### capabilityMethodKindSchema

package/docs/api/invocation.md

@@ -122,7 +122,7 @@ The host's native guest-abort and authority-close hooks.
 ```ts
 type InvocationGate<Host> = Readonly<{
   run: <A>(facts, host, work) => Promise<A>;
-  active: () => InvocationFrame<Host>;
+  active: (frameId) => InvocationFrame<Host>;
   revoke: (reason?, target?) => Promise<void>;
   exclusive: <A>(work) => Promise<A>;
 }>;
@@ -412,8 +412,12 @@ only its decision.
 function createInvocationGate<Host>(ports): InvocationGate<Host>;
 ```
 
-Serialize authority, preempt replay only for verified writes, and close each
-guest before admission.
+Admit frames against one guest. Verified foreground reads share it, up to eight
+at once; writes, raw backend requests, Gills and replay run alone. Every guest
+binding packet names its frame, so a finished frame's leftover timers cannot
+borrow a later frame's authority and a normal finish keeps the guest warm.
+Closing authority early (revocation, expiry, a write preempting replay) aborts
+the guest and so every frame sharing it; replay only yields to a verified write.
 
 #### Type Parameters
 

package/docs/api/keys.md

@@ -14,7 +14,7 @@
 
 ```ts
 type OysterKeyCapability =
-  "apps.read" | "apps.use" | "computer.use" | "machine.enroll";
+  "apps.read" | "apps.use" | "agents.use" | "computer.use" | "machine.enroll";
 ```
 
 Every capability an Oyster key may carry.
@@ -88,8 +88,9 @@ const oysterKeyVocabulary: GrantVocabulary<OysterKeyCapability>;
 `apps.use` also reaches `apps.read` (one level, per `defineGrants`'s own
 `implies`): a key that may change an App's data may also read it. `computer.use`
 has no narrower capability under it; the Computer is on or off, host-wide.
-`machine.enroll` admits enrollment only; it implies no App or Computer access.
-The enrollment owner, not this vocabulary, owns one-use consumption.
+`agents.use` selects Agent ids independently of App grants. `machine.enroll`
+admits enrollment only; it implies no App or Computer access. The enrollment
+owner, not this vocabulary, owns one-use consumption.
 
 ---
 
@@ -159,6 +160,27 @@ name for MCP) to reach the full `AppToolAccess`.
 
 ---
 
+### keyAgentAccess()
+
+```ts
+function keyAgentAccess(key, agentId): boolean;
+```
+
+Agent access is scoped to the granted Agent ids, never inferred from App grants.
+
+#### Parameters
+
+| Parameter | Type                              |
+| --------- | --------------------------------- |
+| `key`     | [`LiveOysterKey`](#liveoysterkey) |
+| `agentId` | `string`                          |
+
+#### Returns
+
+`boolean`
+
+---
+
 ### keyAllowsComputerUse()
 
 ```ts