@fungi.computer/oyster 0.4.1 → 0.5.0

package/dist/standalone/agent-mail.js

@@ -23,6 +23,7 @@ export function agentMail(options) {
         if (tick === undefined)
             throw new Error("Agent Post lane is not open");
         await tick();
+        await mail.stageUndeliverableReplies();
     };
     const mail = new AgentMail({ ...options, post: runtime, drain });
     const host = {
@@ -57,6 +58,8 @@ export function agentMail(options) {
     };
     return {
         host,
-        deliver: (value) => mail.send(value),
+        deliver: (value) => {
+            return mail.send(value);
+        },
     };
 }

package/dist/standalone/agents.d.ts

@@ -1,5 +1,7 @@
 import { type StandaloneTenancyEnv } from "./tenancy.js";
 import type { PostEnvelope } from "@fungi.computer/carrier/post";
+import { type ChannelConversations } from "../channels/conversations.js";
+import type { ConversationBinding } from "../channels/binding.js";
 import { type StandaloneMachineLinkBindings, type StandaloneMachineJoinResult } from "./machine-link.js";
 import { type MachineAgentSettlementPrincipal, type MachineAgentHome, type MachineEnrollment, type MachineLinkCaller, type MachineLinkIdentity } from "../machine-link/index.js";
 /** Workers AI binding surface used by the standalone provider adapter. */
@@ -78,6 +80,12 @@ export declare abstract class StandaloneAgentBase<Env extends StandaloneAgentEnv
     #private;
     /** The deployable root's host for this Agent's pinned tenant. */
     protected abstract hostFor(scope: TenantScope): Promise<OysterHost>;
+    /**
+     * Compose Oyster's channel owner on this Agent's real store and Shiitake.
+     * A host must supply its own binding lookup after authenticating its edge;
+     * this does not install an inbound route or mint provider credentials.
+     */
+    protected channelConversations(binding: (bindingId: string) => ConversationBinding | null): ChannelConversations;
     private uiOwner;
     private machineClient;
     private computerSnapshot;

package/dist/standalone/agents.js

@@ -7,6 +7,8 @@ import { AgentCreateRefused, } from "@fungi.computer/shiitake/agent-control";
 import { AgentDelegation, AgentDisclosureRefused, machineAgentCodecs, } from "@fungi.computer/shiitake/delegation";
 import { FungiMessageMetaSchema } from "@fungi.computer/agar/agents";
 import { agentMail } from "./agent-mail.js";
+import { createChannelConversations, } from "../channels/conversations.js";
+import { channelSessionDoor } from "./channel-session-door.js";
 import { createStandaloneMachineEnrollment, standaloneMachineAgentHome, standaloneMachineLinkAuthority, } from "./machine-link.js";
 import { createMachineLinkFences, MachineEnrollmentRefused, MachineLinkRefused, createMachineAgentClient, } from "../machine-link/index.js";
 import { memberInboxItemSchema } from "@fungi.computer/puffball/inbox";
@@ -228,6 +230,22 @@ const instructions = [
 ].join("\n");
 /** One agent: Shiitake's Cloudflare host over this Durable Object; its root supplies `hostFor`. */
 export class StandaloneAgentBase extends ShiitakeDO {
+    /**
+     * Compose Oyster's channel owner on this Agent's real store and Shiitake.
+     * A host must supply its own binding lookup after authenticating its edge;
+     * this does not install an inbound route or mint provider credentials.
+     */
+    channelConversations(binding) {
+        return createChannelConversations({
+            sql: this.ctx.storage.sql,
+            transactionSync: (body) => this.ctx.storage.transactionSync(body),
+            binding,
+            door: channelSessionDoor(() => this.shiitake(), () => {
+                // Standalone Agents have no Hub Team grants to deliver.
+            }),
+            now: () => Date.now(),
+        });
+    }
     /** Each installed Release's verified catalog surface, built once per Release for this Agent's lifetime. */
     #appSurfaces;
     uiOwner;
@@ -479,10 +497,11 @@ export class StandaloneAgentBase extends ShiitakeDO {
                     throw new Error("Delegated reply identity is unavailable");
                 if (mail.reply.outcome === "undeliverable")
                     return undefined;
-                if (mail.from.sessionId === undefined)
-                    throw new Error("Delegated reply Session is unavailable");
+                if (mail.from.kind !== "agent")
+                    throw new Error("Delegated reply Agent identity is unavailable");
                 return (await this.machineClient()).settlement(mail.from.agentId, mail.from.sessionId, mail.reply.commandId, mail.to.agentId);
             },
+            onUndeliverable: (original) => this.delegation().localUndeliverable(original),
             wake: () => this.wakeRuntime(),
         }));
     }

package/dist/standalone/channel-session-door.d.ts

@@ -0,0 +1,4 @@
+import type { ShiitakeOwnerAgent } from "@fungi.computer/shiitake/cloudflare";
+import type { SessionDoor } from "../channels/conversations.js";
+/** Translate a standalone Agent's Shiitake owner into Oyster's channel Session port. */
+export declare function channelSessionDoor(open: () => Promise<ShiitakeOwnerAgent>, deliverGrants: (sessionId: string) => void): SessionDoor;

package/dist/standalone/channel-session-door.js

@@ -0,0 +1,42 @@
+import { authorMeta } from "@fungi.computer/agar/agents";
+import { ShiitakeError } from "@fungi.computer/shiitake";
+/** Translate a standalone Agent's Shiitake owner into Oyster's channel Session port. */
+export function channelSessionDoor(open, deliverGrants) {
+    return {
+        createSession: async (requestId) => (await open()).createSession(requestId),
+        deliverGrants,
+        withdraw: async (sessionId, requestId) => (await open()).session(sessionId).withdraw(requestId),
+        latestPending: async (sessionId, visitor) => (await open())
+            .withMeta(authorMeta(visitor))
+            .session(sessionId)
+            .latestPending(),
+        prompt: async (sessionId, { requestId, text, meta }) => {
+            // The conversation row exists now, so its channel admission is known;
+            // deliver Agent tools before the first run can call one.
+            deliverGrants(sessionId);
+            const agent = await open();
+            return await agent.withMeta(meta).session(sessionId).command({
+                type: "prompt",
+                requestId,
+                text,
+                delivery: "followUp",
+            });
+        },
+        line: async (sessionId, input) => {
+            const agent = await open();
+            const meta = input.author === "operator" ? authorMeta(input.identity) : input.meta;
+            await agent.withMeta(meta).session(sessionId).command({
+                type: "operator",
+                requestId: input.requestId,
+                author: input.author,
+                text: input.text,
+            });
+        },
+        errorKind: (error, requestId) => error instanceof ShiitakeError &&
+            error.boundary === "contract" &&
+            error.cause === "closed" &&
+            error.requestId === requestId
+            ? "closed_request"
+            : null,
+    };
+}

package/dist/standalone/machine-link.d.ts

@@ -268,6 +268,8 @@ export declare class MachineLinkDO extends DurableObject<StandaloneMachineLinkEn
     alarm(): Promise<void>;
     fetch(request: Request): Promise<Response>;
     deliver(id: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, envelope: PostEnvelope): Promise<PostDeliveryResult>;
+    deliverRelayDisposition(id: MachineLinkIdentity, relay: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<PostDeliveryResult>;
+    hasStagedDisposition(id: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<boolean>;
     operation(id: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, operation: MachineAgentOperation): Promise<import("effect/Schema").Json>;
     applyFence(fact: MachineLinkFenceFact): Promise<MachineLinkFenceResult>;
     preflightErasure(teamId: string, deviceId: string): Promise<void>;

package/dist/standalone/machine-link.js

@@ -1,4 +1,4 @@
-import { machineAgentReservations } from "@fungi.computer/shiitake/delegation";
+import { machineAgentCodecs, machineAgentReservations, } from "@fungi.computer/shiitake/delegation";
 import { createMachineEnrollment, MachineEnrollmentRefused, MachineLinkRefused, } from "../machine-link/index.js";
 import { keyAllowsMachineEnroll, } from "../keys.js";
 import { agentIds, createAgentDirectory, } from "@fungi.computer/shiitake/fleet";
@@ -8,6 +8,7 @@ import { bodyLimit } from "hono/body-limit";
 import { validator } from "hono/validator";
 import { machineEnrollmentSchema, machineLinkName, } from "../machine-link/index.js";
 import { createMachineLink } from "../machine-link/workers.js";
+import { deliverUndeliverableMail } from "../machine-link/delivery.js";
 import { defaultTenant, tenantScope } from "../tenant.js";
 import { presentedGitKey } from "../git-auth.js";
 import { standaloneTenancy } from "./tenancy.js";
@@ -49,6 +50,7 @@ export function standaloneMachineLinkAuthority(env) {
             return directory().machineDevice(id);
         },
         currentFence: async (id) => id.teamId !== teamId ? null : directory().machineFence(id),
+        agentHome: async (id, agentId) => id.teamId !== teamId ? null : directory().agentHome(agentId),
         directory: async (id) => {
             if (!(await authority.admitDevice(id)).live)
                 throw new MachineLinkRefused("actor_not_allowed");
@@ -69,6 +71,31 @@ export function standaloneMachineLinkAuthority(env) {
                 throw new MachineLinkRefused("actor_not_allowed");
             return env.MACHINE_LINK.getByName(machineLinkName(next)).deliver(next, caller, facts.targetAgentId, envelope);
         },
+        deliverUndeliverable: async (id, original, reply) => {
+            if ((await authority.currentFence(id)) === null)
+                return "refused";
+            const mail = original.event;
+            if (mail.from.kind !== "agent")
+                return "refused";
+            const home = await authority.agentHome(id, mail.from.agentId);
+            if (home === null)
+                throw new MachineLinkRefused("unavailable");
+            return await deliverUndeliverableMail({
+                identity: id,
+                original,
+                reply,
+                senderHome: home,
+                hosted: env.AGENTS,
+                accepted: machineAgentCodecs.accepted,
+                machine: async (deviceId, envelope) => {
+                    const destination = { teamId, deviceId };
+                    return await env.MACHINE_LINK.getByName(machineLinkName(destination)).deliverRelayDisposition(destination, id, original, envelope);
+                },
+            });
+        },
+        verifyRelayDisposition: async (relay, original, reply) => {
+            return await env.MACHINE_LINK.getByName(machineLinkName(relay)).hasStagedDisposition(relay, original, reply);
+        },
         canErase: async (id) => {
             if (id.teamId !== teamId)
                 return false;
@@ -185,6 +212,12 @@ export class MachineLinkDO extends DurableObject {
     deliver(id, caller, agentId, envelope) {
         return this.link.deliver(id, caller, agentId, envelope);
     }
+    deliverRelayDisposition(id, relay, original, reply) {
+        return this.link.deliverRelayDisposition(id, relay, original, reply);
+    }
+    hasStagedDisposition(id, original, reply) {
+        return this.link.hasStagedDisposition(id, original, reply);
+    }
     operation(id, caller, agentId, operation) {
         return this.link.operation(id, caller, agentId, operation);
     }

package/dist/testing/capabilities.d.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { type AppCapabilityId } from "@fungi.computer/puffball/app";
 import { type OysterAgents } from "../agents.js";
+import type { LiveOysterKey } from "../keys.js";
 import { type FileSource } from "../files.js";
 import { type OysterAuthResult, type OysterCapability } from "../host.js";
 /** How one capability fixture host admits its single installation. */
@@ -19,6 +20,7 @@ export type CapabilityFixtureOptions = Readonly<{
     visitor?: boolean;
     authenticate?: (request: Request) => Promise<OysterAuthResult>;
     agents?: OysterAgents;
+    liveKey?: (keyId: string) => Promise<LiveOysterKey | null>;
 }>;
 /** One Oyster host with a single installation whose capability grants the options shape. */
 export declare function capabilityFixture(options?: CapabilityFixtureOptions): Promise<{

package/dist/testing/capabilities.js

@@ -84,7 +84,7 @@ export async function capabilityFixture(options = {}) {
     if (options.visitor)
         installation = { ...installation, visibility: "public" };
     const readOnly = () => Promise.reject(new Error("Fixture installations are read-only"));
-    const base = {
+    let base = {
         bootUi: () => Promise.resolve({ kind: "passed" }),
         auth: {
             resolve: () => Promise.reject(new Error("Capability fixture resolves no actor")),
@@ -116,6 +116,8 @@ export async function capabilityFixture(options = {}) {
         },
         capabilities,
     };
+    if (options.liveKey !== undefined)
+        base = { ...base, keys: { live: options.liveKey } };
     const host = options.agents === undefined
         ? base
         : { ...base, ownerRoutes: agentApprovalRoutes(options.agents) };

package/dist/workers-git.js

@@ -1117,7 +1117,7 @@ export async function oysterGitWorkerHost(env, options, selected, request) {
     const base = oysterWorkerHost(env, auth, policyOptions);
     const capabilities = [
         ...(base.capabilities ?? []),
-        ...(agents === undefined ? [] : agentCapabilities(agents)),
+        ...(agents === undefined ? [] : agentCapabilities(agents, keysLive)),
         ...(options.capabilities?.(env, workspace, keysLive) ?? []),
     ];
     let gitOptions = { scope };

package/dist/workers.d.ts

@@ -138,6 +138,7 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
             };
             readonly reversibility: "reversible" | "irreversible-external";
             readonly requestedAt: number;
+            readonly denialNote?: string | undefined;
             readonly evidence?: readonly {
                 readonly kind: "artifact";
                 readonly ref: string;
@@ -155,6 +156,7 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
     }>, actor: HostActor, input: ApprovalAnswerInput): Promise<Readonly<{
         kind: "refused";
         reason: "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict";
+        denialNote?: string;
     }> | Readonly<{
         kind: "answered";
         view: import("@fungi.computer/approvals").ApprovalView;
@@ -166,6 +168,7 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
     }>, actor: HostActor, input: AutoApproveInput): Promise<Readonly<{
         kind: "refused";
         reason: "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict";
+        denialNote?: string;
     }> | Readonly<{
         kind: "updated";
         rule: AutoApproveInput;

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/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/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

package/docs/api/workers.md

@@ -253,6 +253,7 @@ approvalGet(
         | "outcome-unknown"
         | "identity-conflict"
         | null;
+     denialNote?: string;
      requestedAt: number;
      expiresAt: number;
      updatedAt: number;
@@ -289,9 +290,9 @@ Read one member-scoped view; the native home resolves membership again.
 `"not-found"` \| `"not-eligible"` \| `"already-answered"` \| `"stale-revision"`
 \| `"declined"` \| `"fenced"` \| `"not-granted"` \| `"read-only"` \|
 `"in-flight"` \| `"outcome-unknown"` \| `"identity-conflict"` \| `null`;
-`requestedAt`: `number`; `expiresAt`: `number`; `updatedAt`: `number`;
-`revision`: `number`; \}; `canAnswer`: `boolean`; `canSetAutoApprove`:
-`boolean`; \} \| `null`\>
+`denialNote?`: `string`; `requestedAt`: `number`; `expiresAt`: `number`;
+`updatedAt`: `number`; `revision`: `number`; \}; `canAnswer`: `boolean`;
+`canSetAutoApprove`: `boolean`; \} \| `null`\>
 
 ##### approvalAnswer()
 
@@ -353,6 +354,7 @@ approvalAnswer(
            | "outcome-unknown"
            | "identity-conflict"
            | null;
+        denialNote?: string;
         requestedAt: number;
         expiresAt: number;
         updatedAt: number;
@@ -377,6 +379,7 @@ approvalAnswer(
      | "in-flight"
      | "outcome-unknown"
      | "identity-conflict";
+  denialNote?: string;
 }>>;
 ```
 
@@ -388,10 +391,11 @@ Persist an eligible answer and attempt its native decision work once.
 | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `pin`                    | `Readonly`\<\{ `tenantId`: `string`; `origin`: `string`; \}\>                                                                                         |
 | `actor`                  | \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \} |
-| `input`                  | \{ `recordId`: `string`; `decision`: `"approve"` \| `"deny"`; `expectedRevision`: `number`; \}                                                        |
+| `input`                  | \{ `recordId`: `string`; `decision`: `"approve"` \| `"deny"`; `expectedRevision`: `number`; `denialNote?`: `string`; \}                               |
 | `input.recordId`         | `string`                                                                                                                                              |
 | `input.decision`         | `"approve"` \| `"deny"`                                                                                                                               |
 | `input.expectedRevision` | `number`                                                                                                                                              |
+| `input.denialNote?`      | `string`                                                                                                                                              |
 
 ###### Returns
 
@@ -408,13 +412,14 @@ Persist an eligible answer and attempt its native decision work once.
 `reason`: \| `"pending"` \| `"expired"` \| `"not-found"` \| `"not-eligible"` \|
 `"already-answered"` \| `"stale-revision"` \| `"declined"` \| `"fenced"` \|
 `"not-granted"` \| `"read-only"` \| `"in-flight"` \| `"outcome-unknown"` \|
-`"identity-conflict"` \| `null`; `requestedAt`: `number`; `expiresAt`: `number`;
-`updatedAt`: `number`; `revision`: `number`; \}; `canAnswer`: `boolean`;
-`canSetAutoApprove`: `boolean`; \}; \}\> \| `Readonly`\<\{ `kind`: `"refused"`;
-`reason`: \| `"pending"` \| `"expired"` \| `"not-found"` \| `"not-eligible"` \|
-`"already-answered"` \| `"stale-revision"` \| `"declined"` \| `"fenced"` \|
-`"not-granted"` \| `"read-only"` \| `"in-flight"` \| `"outcome-unknown"` \|
-`"identity-conflict"`; \}\>\>
+`"identity-conflict"` \| `null`; `denialNote?`: `string`; `requestedAt`:
+`number`; `expiresAt`: `number`; `updatedAt`: `number`; `revision`: `number`;
+\}; `canAnswer`: `boolean`; `canSetAutoApprove`: `boolean`; \}; \}\> \|
+`Readonly`\<\{ `kind`: `"refused"`; `reason`: \| `"pending"` \| `"expired"` \|
+`"not-found"` \| `"not-eligible"` \| `"already-answered"` \| `"stale-revision"`
+\| `"declined"` \| `"fenced"` \| `"not-granted"` \| `"read-only"` \|
+`"in-flight"` \| `"outcome-unknown"` \| `"identity-conflict"`; `denialNote?`:
+`string`; \}\>\>
 
 ##### approvalSetAutoApprove()
 
@@ -439,6 +444,7 @@ approvalSetAutoApprove(
      | "in-flight"
      | "outcome-unknown"
      | "identity-conflict";
+  denialNote?: string;
 }>
   | Readonly<{
   kind: "updated";
@@ -478,9 +484,10 @@ it.
 `"expired"` \| `"not-found"` \| `"not-eligible"` \| `"already-answered"` \|
 `"stale-revision"` \| `"declined"` \| `"fenced"` \| `"not-granted"` \|
 `"read-only"` \| `"in-flight"` \| `"outcome-unknown"` \| `"identity-conflict"`;
-\}\> \| `Readonly`\<\{ `kind`: `"updated"`; `rule`: \{ `scope`: \{ `agentId`:
-`string` \| `null`; \}; `family`: \{ `module`: `string` \| `null`; `access`:
-`"write"` \| `"external"`; \}; `enabled`: `boolean`; \}; \}\>\>
+`denialNote?`: `string`; \}\> \| `Readonly`\<\{ `kind`: `"updated"`; `rule`: \{
+`scope`: \{ `agentId`: `string` \| `null`; \}; `family`: \{ `module`: `string`
+\| `null`; `access`: `"write"` \| `"external"`; \}; `enabled`: `boolean`; \};
+\}\>\>
 
 ##### installationOperation()
 

package/docs/site/agent-quickstart.mdx

@@ -10,6 +10,29 @@ Run every command exactly as written, from the directory each step names.
 Compare its output with the expected output before you go on. When a step fails,
 read the "If it fails" notes under it before trying anything else.
 
+## Before you start
+
+- **Cloudflare plan:** SQLite-backed Durable Objects are available on Workers
+  Free; they do not by themselves require Paid. Cloudflare's SQLite-backed
+  Durable Objects limits list 30 seconds of CPU per request by default,
+  configurable to 5 minutes. See Cloudflare's
+  [Durable Objects limits](https://developers.cloudflare.com/durable-objects/platform/limits/)
+  and
+  [Durable Objects pricing](https://developers.cloudflare.com/durable-objects/platform/pricing/).
+- **Agent chat and AI Gateway:** By default, Agent chat uses the Workers AI
+  binding; it needs no separate provider key or Gateway setup. Prints uses your
+  account's default AI Gateway (created automatically); set `AI_GATEWAY_ID` to
+  use another. The routed models include `openai/gpt-image-2` and video IDs
+  `bytedance/seedance-2.0`, `bytedance/seedance-2.0-fast`,
+  `bytedance/seedance-2.0-mini`, `google/veo-3.1`, `google/veo-3.1-fast` and
+  `minimax/h3-max`.
+
+- **Deployment plan:** Step 7 needs Workers Paid because this deployment uses
+  Containers for the Computer image; Cloudflare lists Containers as available on
+  the
+  [Workers Paid plan](https://developers.cloudflare.com/containers/platform/).
+  SQLite-backed Durable Objects alone do not require Paid.
+
 ## What Oyster is
 
 - Oyster hosts Apps on one Cloudflare Worker, or on celld, a Workers-compatible