@fungi.computer/oyster 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,52 +6,673 @@
6
6
 
7
7
  # Oyster API overview
8
8
 
9
- | Import | Export | Purpose |
10
- | --------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
11
- | `@fungi.computer/oyster` | `createAppInstance` | Run one App Instance's lifecycle and admission over host-supplied ports. |
12
- | `@fungi.computer/oyster` | `InstancePorts` | The storage, artifact resolution, abort, purge and connection ports a host supplies. |
13
- | `@fungi.computer/oyster` | `selectionSchema` | Decode the owner-issued selection that authorizes a request. |
14
- | `@fungi.computer/oyster` | `ownerStateSchema` | Decode a complete owner state: `enabled`, `disabled` or `deleted`. |
15
- | `@fungi.computer/oyster` | `AppInstanceError` | Typed rejection with a stable `code` from `appInstanceErrorCodeSchema`. |
16
- | `@fungi.computer/oyster` | `instanceIds` | Mint and recognize App Instance IDs. |
17
- | `@fungi.computer/oyster/invocation` | `createInvocationGate`, `invocationFacts`, `InvocationFrame` | Run each request in one frame of host-admitted caller facts, with its deadline and abort signal. |
18
- | `@fungi.computer/oyster/cloudflare` | `createCloudflareAppInstance` | Run an Instance in a SQLite Durable Object with a Worker Loader facet (workerd or celld). |
19
- | `@fungi.computer/oyster/apps` | `Installation`, `applyInstallationCommand`, `admits`, `approvedBindingGrants` | Pure installation approvals and admission; host-owned commits and tenant freshness. |
20
- | `@fungi.computer/oyster/host` | `createOyster` | The Oyster App server: a Hono app over host adapters for sign-in, Releases, installations and Instances. |
21
- | `@fungi.computer/oyster/auth` | `ownerKeyAuth`, `ownerOrKeyAuth` | Owner-key sign-in (a Bearer key or the login cookie, compared in constant time) and named agent keys as Team-key principals. |
22
- | `@fungi.computer/oyster/tenant` | `TenantScope`, `tenantScope`, `singleTenant`, `OysterTenancy` | Host-resolved tenant identity and the scope that prefixes registry, key and repository names. |
23
- | `@fungi.computer/oyster/workers` | `createOysterWorker` | A standalone single-owner Oyster on Workers or celld: R2 Releases, a registry and one Durable Object per Instance. |
24
- | `@fungi.computer/oyster/pack` | `packRelease`, `installRelease`, `installFromSource`, `publishSource` | Build a committed App through the canonical recipe compiler and install its Release on an Oyster over HTTP. |
25
- | `@fungi.computer/oyster/build` | `createAppCandidatePreparer`, `createLocalBuildExecutor` | Node-only source capture, pinned compilation and local artifact writing. |
26
- | `@fungi.computer/oyster/build-contract` | Recipe schemas and candidate orchestration | The Worker-safe half of `./build`, without the executor. |
27
- | `@fungi.computer/oyster/app-storage` | `AppStorageBinding` | `env.APP_STORAGE` for methods and lifecycle handlers: lifecycle writes go to the team layer and reach `appStorage.watch`. |
28
- | `@fungi.computer/oyster/app-storage` | `createAppStorage`, `appStorageSchemaStatements` | SQLite owner for declared keys, live member/lifecycle admission, revision checks and watch invalidations. |
29
- | `@fungi.computer/oyster/mcp` | `oysterAppMethods`, `oysterComputerTools`, `oysterMcpCatalogLoad` | Installed App methods and the host's Computer as Mycelium modules for the shared MCP endpoint, scoped to the caller. |
30
- | `@fungi.computer/oyster/agents` | `OysterAgents`, `agentCapabilities`, `agentApprovalRoutes` | The host's Agent slot, its App capabilities and the owner-only approval routes. |
31
- | `@fungi.computer/oyster/computer` | `computerSlots`, `ComputerTerminalHost` | Computer ports, processes and terminal routes supplied by the host; execution stays in the Computer runtime. |
32
- | `@fungi.computer/oyster/media` | `mediaSlot` | The media capability slot a host fills; Oyster owns routing, never generation. |
33
- | `@fungi.computer/oyster/files` | `FileSource` | Files Apps reach through Agar's `computer.*` file contracts, with a compare-and-swap replace. |
34
- | `@fungi.computer/oyster/root-data` | `createOysterRootData` | Installation and verified Release owners as shared workbench metadata for a standalone root. |
35
- | `@fungi.computer/oyster/page` | `mountOysterPage`, `connectOysterApp`, `readOysterPageConfig` | Mount one installed App's sandboxed frame and connect its admitted slots. |
36
- | `@fungi.computer/oyster/git` | `EventSink`, `createGitDoor`, `signStandardWebhook` | The EVENTS binding contract, the git smart-HTTP door and Standard Webhooks signing. `GitBinding` comes from `@fungi.computer/agar/git`. |
37
- | `@fungi.computer/oyster/workers-git` | `oysterGitRoot`, `createOysterGitWorker`, `ownerOrKeyTenancy`, `oysterWorkerGit`, `gitAdminRoutes` | One Git root whose `hostFor` serves HTTP, MCP and Instances, or `host.git` and key/webhook routes for your own host. |
38
-
39
- Standalone Oyster owners can `POST /agents/:agentId/archive` and
40
- `POST /agents/:agentId/unarchive`. `GET /agents` lists active Agents;
41
- `GET /agents?archived=true` lists only archived Agents. Archive preserves
42
- existing Sessions and reads but refuses new Shiitake work with
43
- `contract/archived`. It pauses Almanac and Loop schedules; restore resumes only
44
- schedules paused by archive. The generated Agent API is in `docs/api/agents.md`.
45
-
46
- The host owns admission: it decides who may apply owner state and which
47
- selection a request carries. Oyster owns what happens to one Instance once the
48
- host has that authority: owner-state replay and conflict rules, Release
49
- resolution, state-schema compatibility, fencing on disable and purge on delete.
50
- The generated module pages below include every port and record type.
51
-
52
- ## App Agent send API — breaking change
53
-
54
- An App with the `AGENTS.send` binding sends into an existing authorized Session:
9
+ Oyster is built in layers. Most hosts need one import from the first table; the
10
+ rest of this page documents the building blocks those hosts are made of, how to
11
+ operate a deployed Oyster, and the low-level ports underneath. The generated
12
+ module pages that follow list every export.
13
+
14
+ ## Choose a host
15
+
16
+ | Import | Export | Use it when |
17
+ | ------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
18
+ | `@fungi.computer/oyster/standalone` | the whole Worker | You want the full Oyster: git, Computers, Agents, Workflows, media, tenancy and App builds. Re-export it from `worker.ts`. |
19
+ | `@fungi.computer/oyster/workers` | `createOysterWorker` | You want one owner's Apps from Releases, each in its own Durable Object with SQLite, plus MCP, and nothing else. |
20
+ | `@fungi.computer/oyster/workers-git` | `oysterGitRoot`, `createOysterGitWorker` | You want that Worker plus the git door, keys, webhooks and Agents, composed once for HTTP, MCP and Instances. |
21
+ | `@fungi.computer/oyster/host` | `createOyster` | You run on another server or need your own adapters for sign-in, Releases, installations and Instances. |
22
+ | `@fungi.computer/oyster/pack` | `packRelease`, `installRelease` | You build an App from an exact commit and install its Release on any Oyster over HTTP. |
23
+
24
+ `examples/standalone/wrangler.jsonc` declares every binding the standalone host
25
+ uses. A `createOysterWorker` host needs `LOADER`, `RELEASES`, `REGISTRY`,
26
+ `INSTANCES` and `MCP`, plus the `OYSTER_OWNER_KEY` secret and `OYSTER_ORIGIN`.
27
+
28
+ ## Building blocks
29
+
30
+ | Import | Export | Purpose |
31
+ | --------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
32
+ | `@fungi.computer/oyster/git` | `EventSink`, `createGitDoor`, `signStandardWebhook` | The EVENTS binding contract, the git smart-HTTP door and Standard Webhooks signing. |
33
+ | `@fungi.computer/oyster/mcp` | `oysterAppMethods`, `oysterComputerTools`, `oysterMcpCatalogLoad` | Installed App methods and the host's Computer as Mycelium modules for the shared MCP endpoint, scoped to the caller. |
34
+ | `@fungi.computer/oyster/apps` | `Installation`, `applyInstallationCommand`, `admits`, `approvedBindingGrants` | Pure installation approvals and admission; host-owned commits and tenant freshness. |
35
+ | `@fungi.computer/oyster/auth` | `ownerKeyAuth`, `ownerOrKeyAuth` | Owner-key sign-in (a Bearer key or the login cookie, compared in constant time) and named agent keys. |
36
+ | `@fungi.computer/oyster/authorization` | `routes`, route requirements | The one route table and its typed requirements. |
37
+ | `@fungi.computer/oyster/tenant` | `TenantScope`, `tenantScope`, `singleTenant`, `OysterTenancy` | Host-resolved tenant identity and the scope that prefixes registry, key and repository names. |
38
+ | `@fungi.computer/oyster/tenancy` | `createTenancy` and its adapters | Request resolution, a tenant registry and sign-in adapters (owner key, Auth0) for a multi-tenant host. |
39
+ | `@fungi.computer/oyster/app-storage` | `AppStorageBinding`, `createAppStorage`, `appStorageSchemaStatements` | `env.APP_STORAGE` and its SQLite owner: declared keys, live admission, revision checks and watch invalidations. |
40
+ | `@fungi.computer/oyster/agents` | `OysterAgents`, `agentCapabilities`, `agentApprovalRoutes` | The host's Agent slot, its App capabilities and the owner-only approval routes. |
41
+ | `@fungi.computer/oyster/computer` | `computerSlots`, `ComputerTerminalHost` | Computer ports, processes and terminal routes supplied by the host; execution stays in the Computer runtime. |
42
+ | `@fungi.computer/oyster/files` | `FileSource`, `fileCapabilities` | Files Apps reach through Agar's `computer.*` file contracts, with a compare-and-swap replace. |
43
+ | `@fungi.computer/oyster/media` | `mediaSlot` | The media capability slot a host fills; Oyster owns routing, never generation. |
44
+ | `@fungi.computer/oyster/browser` | `createBrowser`, `browserCapabilitySource` | The Agent browser over Cloudflare Browser Rendering: leases, URL policy, reaping and billing order. |
45
+ | `@fungi.computer/oyster/turnstile` | Turnstile configuration and verification | Cloudflare challenge configuration and token verification for a host's own challenged routes. |
46
+ | `@fungi.computer/oyster/build` | `createAppCandidatePreparer`, `createLocalBuildExecutor` | Node-only source capture, pinned compilation and local artifact writing. |
47
+ | `@fungi.computer/oyster/build-contract` | Recipe schemas and candidate orchestration | The Worker-safe half of `./build`, without the executor. |
48
+ | `@fungi.computer/oyster/root-data` | `createOysterRootData` | Installation and verified Release owners as shared workbench metadata for a standalone root. |
49
+ | `@fungi.computer/oyster/page` | `mountOysterPage`, `connectOysterApp`, `readOysterPageConfig` | Mount one installed App's sandboxed frame and connect its admitted slots. |
50
+
51
+ The lowest layer is one App Instance and the frame each request runs in:
52
+
53
+ | Import | Export | Purpose |
54
+ | ----------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
55
+ | `@fungi.computer/oyster` | `createAppInstance`, `InstancePorts` | Run one App Instance's lifecycle and admission over host-supplied ports. |
56
+ | `@fungi.computer/oyster` | `selectionSchema`, `ownerStateSchema` | Decode the owner-issued selection and a complete owner state: `enabled`, `disabled`, `deleted`. |
57
+ | `@fungi.computer/oyster` | `AppInstanceError`, `instanceIds` | Typed rejection with a stable `code`; mint and recognize App Instance IDs. |
58
+ | `@fungi.computer/oyster/invocation` | `createInvocationGate`, `invocationFacts`, `InvocationFrame` | Run each request in one frame of host-admitted caller facts, with its deadline and abort signal. |
59
+ | `@fungi.computer/oyster/cloudflare` | `createCloudflareAppInstance` | Run an Instance in a SQLite Durable Object with a Worker Loader facet (workerd or celld). |
60
+
61
+ The package's other entry points (`channels/*`, `boot-*`, `embed/*`,
62
+ `machine-link`, `agent-*`, `build-*`, `source`, `workflows`, `web` and
63
+ `testing`) are parts that the standalone host, the Fungi Hub and the first-party
64
+ Apps assemble. You do not need them to run or host Oyster.
65
+
66
+ ## Deploy and operate
67
+
68
+ ### Start a project without `try`
69
+
70
+ ```sh
71
+ mkdir my-oyster && cd my-oyster
72
+ cat > pnpm-workspace.yaml <<'YAML'
73
+ allowBuilds:
74
+ "@google/genai": false
75
+ "@mongodb-js/zstd": false
76
+ esbuild: true
77
+ exifreader: false
78
+ node-liblzma: false
79
+ protobufjs: false
80
+ workerd: true
81
+ YAML
82
+ pnpm add @fungi.computer/oyster @fungi.computer/computer react@^19.2.0 react-dom@^19.2.0
83
+ pnpm add -D wrangler
84
+ cp node_modules/@fungi.computer/oyster/examples/standalone/{worker.ts,wrangler.jsonc} .
85
+ export OYSTER_OWNER_KEY=$(openssl rand -hex 24)
86
+ printf '%s' "$OYSTER_OWNER_KEY" | npx wrangler secret put OYSTER_OWNER_KEY
87
+ ```
88
+
89
+ The policy file lets esbuild and workerd install their native binaries and
90
+ disables unneeded dependency scripts. If `pnpm add` reports
91
+ `ERR_PNPM_IGNORED_BUILDS`, check that the file exists. If it names a new
92
+ dependency not listed there, review that package before allowing its scripts.
93
+ Then create the bucket, deploy and install the Apps as in the README.
94
+
95
+ `wrangler.jsonc` names the Worker `oyster`, its Release bucket `oyster-releases`
96
+ and its Artifacts namespace `oyster`. If you rename the Worker, update
97
+ `OYSTER_ORIGIN` to its URL at the same time. Without the `BROWSER` binding, a
98
+ Release's UI is reported `not_checked` with
99
+ `code: "boot_browser_binding_missing"` and the install still proceeds.
100
+
101
+ `install-apps` accepts `--ref` for a branch or tag of the App repositories,
102
+ `--repositories` for another host of them, `--timings <file>` to write the
103
+ timing table as JSON, and `--concurrency <n>` (default 2, on the example's
104
+ `standard-4` Computer with 12 GiB).
105
+
106
+ ### Deploy with an API token
107
+
108
+ Load `CLOUDFLARE_API_TOKEN` into your shell without committing it, set
109
+ `CLOUDFLARE_ACCOUNT_ID` (or `account_id` in `wrangler.jsonc`) and skip
110
+ `wrangler login`. Use Wrangler 4.135.0 or newer. These account-scoped permission
111
+ groups cover deployment and teardown:
112
+
113
+ | Permission group | Used for |
114
+ | ------------------------ | ----------------------------------------------------------- |
115
+ | Workers Scripts Write | Deploy, secrets, Worker deletion and Workflow deletion |
116
+ | Workers R2 Storage Write | Release bucket creation, object cleanup and bucket deletion |
117
+ | Workers Containers Write | Computer container application management |
118
+ | Artifacts Edit | Artifacts namespace and repository management |
119
+
120
+ The Workers `BROWSER` binding
121
+ [needs no additional permission](https://developers.cloudflare.com/browser-run/quick-actions/).
122
+ With an explicit account ID, do not add Workers KV Storage Read, User Details
123
+ Read or Memberships Read for account discovery. AI Gateway permissions are not
124
+ needed unless media has created a gateway you want to remove.
125
+
126
+ ### Tear down
127
+
128
+ `npx wrangler delete` deletes the Worker, which deletes its Durable Object data,
129
+ not the whole Oyster. Also empty and delete the Release bucket, delete the
130
+ Computer's container application and the Workflow, and delete the Artifacts
131
+ repositories and namespace. Confirm each is gone in Cloudflare's dashboard or
132
+ API.
133
+
134
+ ### Upgrade
135
+
136
+ Oyster's version is not Fungi's. Find the Oyster and Computer versions for your
137
+ Fungi release on the
138
+ [package versions page](https://docs.fungi.computer/reference/packages/), and
139
+ follow [Upgrade Oyster](https://docs.fungi.computer/guides/run-your-own-oyster/)
140
+ with the package manager and store that installed the project. Redeploy with the
141
+ same `npx wrangler deploy` command, then run `npx oyster install-apps`. If pnpm
142
+ stops with `ERR_PNPM_UNEXPECTED_STORE`, rerun with `--store-dir` set to the
143
+ store the error names.
144
+
145
+ Two older upgrades reset data rather than convert it. From before 0.7.0, the
146
+ installed Apps are cleared once: Oyster Home asks you to reinstall them with
147
+ `npx oyster install-apps`, which restores the Apps and their App settings, while
148
+ each App's own backend database starts empty. Agents, Sessions, files and keys
149
+ are kept. From 0.2 or earlier, Oyster answers every request with `409` and
150
+ `store_from_older_oyster`; deploy under new resource names or tear the old one
151
+ down first. The changelog entry for each release says when it resets data.
152
+
153
+ ### Run on celld
154
+
155
+ The celld example is a limited trial, not the full Cloudflare setup, and needs
156
+ access to Fungi's private celld fork. Use
157
+ `examples/standalone/wrangler.celld.jsonc` beside `worker.ts`.
158
+
159
+ ### Put an Agent on a website
160
+
161
+ Owner-only means only the owner signs in to Oyster; you can still put an Agent
162
+ on a public site. In Settings, choose Channels, then Add website: pick the
163
+ Agent, give your site's address and a brief, and paste the script tag Oyster
164
+ shows into that site:
165
+
166
+ ```html
167
+ <script
168
+ src="https://your-oyster.example/embed/v1.js"
169
+ data-site="site_pk_…"
170
+ data-theme="auto"
171
+ async
172
+ ></script>
173
+ ```
174
+
175
+ Visitors are anonymous channel parties of that one Agent, never Oyster
176
+ principals, keys or App callers. They talk to the Agent with its own tools and
177
+ permissions plus the persona you wrote. Each site has its own key, allowed
178
+ origins, rate limits per visitor and per network address, and a pause switch; a
179
+ new site key stops the old code at once. The same page can require a Cloudflare
180
+ Turnstile check and shows the conversations.
181
+
182
+ The surface stays closed until you set two host secrets of at least 32 bytes
183
+ each: `OYSTER_WEBSITE_PROOF_KEY` signs a visitor's identity between the public
184
+ edge and the website Agent, and `OYSTER_WEBSITE_ADDRESS_KEY` salts the hashed
185
+ network address used for rate limits. For Turnstile, set `TURNSTILE_SITE_KEY`
186
+ and `TURNSTILE_SECRET_KEY`, or `TURNSTILE=off` for local use over `http`.
187
+ `@fungi.computer/oyster/turnstile` fails closed on HTTPS hosts without both
188
+ keys.
189
+
190
+ ### Read a build's log
191
+
192
+ The owner reads a build's status at `GET /api/builds/:jobId` and its combined
193
+ stdout and stderr at `GET /api/builds/:jobId?log`. The status diagnostic stays
194
+ within 200 characters and points to the log. The log returns base64url-encoded
195
+ raw bytes; past 2 MiB it keeps the head and tail and reports
196
+ `truncated.droppedBytes`.
197
+
198
+ ## Owner routes on the standalone host
199
+
200
+ These routes are owner-direct: they refuse App-origin requests, and Agents and
201
+ keys cannot use them.
202
+
203
+ **Agents.** `GET /agents` lists active Agents and `GET /agents?archived=true`
204
+ lists archived ones. `POST /agents/:agentId/archive` keeps existing Sessions and
205
+ reads but refuses new work with `contract/archived`, and pauses the Agent's
206
+ schedules; `POST /agents/:agentId/unarchive` resumes only the schedules archive
207
+ paused.
208
+
209
+ **Agent App tools.** An App with `agent.manage` can create Agents and request
210
+ tool-policy changes; those requests stay pending until the owner approves. Read
211
+ `GET /api/agent-policies/:agentId` for the current `expectedRevision`, then
212
+ `PUT` the same path with
213
+ `{"level":"write","expectedRevision":"<the returned revision>"}` (or `null` when
214
+ no policy exists). A stale revision returns 409, an unknown Agent 404 and
215
+ malformed input 400. The stored approval pins the owner's `membershipVersion`,
216
+ so demotion, removal or suspension requires new approval.
217
+
218
+ **Remote MCP servers.** Connect a Streamable HTTP MCP server once, then choose
219
+ which Agents use it; each sees its granted tools as `env.mcp.<name>.<tool>()`.
220
+ `GET /api/connections` returns the connections, their grants, the Agents and the
221
+ OAuth `callbackUrl`. `POST /api/connections` with
222
+ `{"name":"linear","url":"https://mcp.example.com/mcp","bearer":null}` creates
223
+ one; the name is up to 32 lowercase letters, digits or `_`, starting with a
224
+ letter, and the URL must be `https:` with no credentials or fragment. Set
225
+ `bearer` to a static token, or keep it `null` and add `oauth:{}` (optionally
226
+ with `clientId`, `clientSecret` and `scope`) and open the returned
227
+ `authorizeUrl` in your signed-in browser. A new connection grants nothing:
228
+ `PUT /api/connections/:connectionId/agents/:agentId` with `{"access":"read"}`,
229
+ `{"access":"all"}` or `{"access":["tool_name"]}` grants access,
230
+ `GET /api/connections/:connectionId/tools` lists tool names, and `DELETE` on
231
+ either path revokes. Credentials stay sealed on the owner side; Agents never
232
+ receive tokens. More than 16 connections per Agent, or a repeated name,
233
+ returns 409.
234
+
235
+ **App permissions.** After selecting a new Release, open **App access** beside
236
+ the App, or `/api/installations/<installationId>/grants`, review the requested
237
+ capabilities and choose **Save permissions**. The page sends a `PUT` carrying
238
+ the captured `storeGeneration`, `authorityVersion` and Release `artifactDigest`
239
+ with a `{kind:"change-grants",changes:[{capability,grant}]}` command; `null`
240
+ revokes a capability. A replaced store, stale Release or concurrent approval
241
+ returns `409`, and the page refreshes and rebases your edits. The required
242
+ `InstallationStore` exposes `generation()` and
243
+ `compareAndPut(record, expectedVersion, expectedGeneration)`, checking both pins
244
+ in one commit transaction.
245
+
246
+ **The Agents' browser.** With a `BROWSER` binding, every Agent gets a
247
+ `cloudBrowser` tool for public pages: `open`, `navigate`, `snapshot` (a bounded
248
+ accessibility-tree summary), `click`, `type`, `press`, `scroll` and `close`.
249
+ Every URL must be http(s), carry no credentials and resolve to a public address.
250
+ A standalone Oyster allows two open sessions, closes one after 5 idle minutes or
251
+ 30 minutes in all, and Cloudflare bills the owner's account. Hosts compose
252
+ `@fungi.computer/oyster/browser` behind one `BrowserHost` port: a provider
253
+ (`bindingSessions(env.BROWSER)`, or `browserRunSessions` with a Browser Run
254
+ account token, which also enables the `markdown`, `links`, `scrape` and
255
+ `extract` reads), a metering owner and an event sink. The Agent never reaches
256
+ raw CDP or runs script in the page.
257
+
258
+ ## Git
259
+
260
+ Git is one optional field of the typed host, `host.git`. When it is present,
261
+ `createOyster` mounts the git door at `/git/<installation>/<repo>.git`. There
262
+ are two ways to get it:
263
+
264
+ - **Use one git root.** `oysterGitRoot(options)` from
265
+ `@fungi.computer/oyster/workers-git` composes the git door with tenancy,
266
+ Agents and their owner-only approval routes, workspace and capability slots,
267
+ the page script and the home App. Its `hostFor(env, scope)` is the only way a
268
+ tenant host is built. Pass the root to `createOysterGitWorker` for HTTP and to
269
+ `createOysterGitMcpOwner` for MCP, and return `root.hostFor(this.env, scope)`
270
+ from your `OysterGitInstance` subclass, so HTTP, MCP and background wakes
271
+ share one composition. A single-owner root passes `ownerOrKeyTenancy`.
272
+ - **Set `host.git` on your own host.** Keep your own `createOyster(host)` and
273
+ set `git: oysterWorkerGit(env, { scope })` and
274
+ `ownerRoutes: gitAdminRoutes(env, scope)` for `/api/keys` and `/api/webhooks`,
275
+ with the tenant `scope` your host selected.
276
+
277
+ ```ts title="worker.ts"
278
+ import type { TenantScope } from "@fungi.computer/oyster/tenant";
279
+ import {
280
+ createOysterGitMcpOwner,
281
+ createOysterGitWorker,
282
+ OysterGitInstance,
283
+ oysterGitRoot,
284
+ ownerOrKeyTenancy,
285
+ type OysterGitWorkerEnv,
286
+ } from "@fungi.computer/oyster/workers-git";
287
+
288
+ const root = oysterGitRoot<OysterGitWorkerEnv>({ tenancy: ownerOrKeyTenancy });
289
+
290
+ export class OysterMcp extends createOysterGitMcpOwner(root) {}
291
+
292
+ export class OysterInstance extends OysterGitInstance {
293
+ protected hostFor(scope: TenantScope) {
294
+ return root.hostFor(this.env, scope);
295
+ }
296
+ }
297
+
298
+ export default createOysterGitWorker(root);
299
+ ```
300
+
301
+ A git host also exports the Durable Objects and the `OysterBinding` entrypoint,
302
+ whose table serves `env.GIT` and `env.EVENTS`, and its Wrangler config adds the
303
+ `ARTIFACTS` binding and the `KEYS` and `WEBHOOKS` Durable Objects. The package's
304
+ `test:git-door` check runs this root on workerd against real bare repositories.
305
+
306
+ Each layer of a push owns one decision:
307
+
308
+ ```mermaid
309
+ flowchart LR
310
+ client["git client<br/>clone · fetch · push"]
311
+ auth["Authentication<br/>owner key · named key<br/>Workflow Git pass header"]
312
+ admission["Git admission<br/>enabled installation · git.repository<br/>tenant scope · Workflow branch grant"]
313
+ policy["App push policy<br/>authorizeGitPush, every ref"]
314
+ burrow["Burrow<br/>Artifacts provider and repository<br/>host-held credentials"]
315
+ events["App events<br/>journal → onGitPush → env.EVENTS<br/>webhooks · Workflow triggers"]
316
+ client --> auth --> admission
317
+ admission -- "push: ask first" --> policy
318
+ admission -- "admitted bytes" --> burrow
319
+ burrow -- "accepted refs" --> events
320
+ ```
321
+
322
+ - **Authentication** is the host's own `auth`. The owner key is a Bearer token;
323
+ a named key may also be the Basic password from a git credential helper. A
324
+ clone needs App read and a push needs App use. Anonymous requests never clone
325
+ or push.
326
+ - **Git admission** reopens the live installation before every provider call: it
327
+ must be enabled and its Release must declare `git.repository`. The tenant
328
+ scope prefixes every repository name (`<installation>--<repo>` for the default
329
+ tenant), so an installation reaches only its own repositories.
330
+ - **The App's push policy** answers `authorizeGitPush` for every ref update
331
+ before any bytes reach the provider. One refusal rejects the whole push with
332
+ git's native `ng` report. Unsupported receive-pack commands, including signed
333
+ push certificates, fail closed.
334
+ - **Burrow** owns the provider and the repository. The host's Artifacts adapter
335
+ mints short-lived credentials through it and forwards the admitted smart-HTTP
336
+ exchange, up to 64 MiB per request. The App never sees a credential or remote.
337
+ - **App events** start from the accepted-ref journal. Delivery calls the
338
+ Instance's `onGitPush` when the Release declares `receives: ["git.push"]`. The
339
+ App emits typed events through `env.EVENTS`, which Oyster delivers as signed
340
+ Standard Webhooks and as Workflow triggers on hosts with Workflows.
341
+
342
+ An App's own `GIT` binding (`await env.GIT.cloneUrl(repo)`, create, fork, log,
343
+ read and merge) uses `admitted.binding(onBehalfOf)`. Its writes skip the App's
344
+ external-push policy but keep live host admission and enter the same journal.
345
+ The journal records only refs the provider accepted and commits before the
346
+ exchange is acknowledged; redelivery keeps the original fact and `eventId`, so
347
+ handlers record that ID with their effects. Hosts compose one
348
+ `createAdmittedGit` with an installation-scoped store, live grants, the App's
349
+ `authorizeGitPush` policy and a journal; `createGitPushJournal` is the
350
+ standalone one, committing the fact, ref tips and its Carrier send together.
351
+ `GitWriter`, `GitPushQuestion` and `GitPushVerdict` come from
352
+ `@fungi.computer/agar/git`.
353
+
354
+ `createGitDoor` from `@fungi.computer/oyster/git` takes the host's
355
+ `authenticate`, `isPublic` and `git` ports directly; `createOyster` builds them
356
+ from `host.auth`, `host.installations` and `host.git`, so most hosts never call
357
+ it.
358
+
359
+ A host whose Workflow run owner issues Workflow Git credentials supplies
360
+ `workflowGitPass` in `oysterGitRoot` or `oysterWorkerGit` options. Each
361
+ credential covers one native command of an admitted Git step, travels only as an
362
+ `Authorization: Bearer wgp.…` header (never in a URL), is admitted for one
363
+ repository and the Workflow's branch grant, and stops working when its command
364
+ closes or its run ends.
365
+
366
+ ## App capabilities
367
+
368
+ Each `OysterCapability` supplies its Agar `id` and `version`, a mount `base`,
369
+ relative declared `routes` (a `routes()` table from
370
+ `@fungi.computer/oyster/authorization`, where every route names its requirement:
371
+ `owner`, `agent`, `computer`, `member`...), and `methods`. Each method has a
372
+ `kind` (`json`, `transport`, `read` or `write`), an HTTP `method` and a relative
373
+ `path`. JSON calls return decoded data, transports return Fetch handles, and
374
+ reads and writes return Agar's stream handles. For example, a directory listing
375
+ is `{ kind: "json", method: "GET", path: "list" }`, and
376
+ `fileCapabilities(source)` from `@fungi.computer/oyster/files` supplies the
377
+ three file contracts.
378
+
379
+ Method paths may contain named parameters such as `:agentId/sessions`; Oyster
380
+ compiles input fields into them with `path-to-regexp`, and remaining scalar
381
+ fields become query parameters for GET and handle calls. Transport handles may
382
+ declare `method: "ANY"` to keep the request's HTTP method. Results, including
383
+ Agar's `{ kind: "pending", retryAfterMs }`, reach the App unchanged.
384
+
385
+ The page offers a capability only when the installed Release declares its ID and
386
+ `admits` allows the principal, and every route request rechecks both. Consent
387
+ approves capabilities, like OAuth scopes: an upgrade may add a method under an
388
+ approved capability without asking again, but a new capability always needs
389
+ approval, and each Worker call receives only the bindings its method's
390
+ `requires` allows. The `apps.call` permission also shows the target Apps and
391
+ methods it names; changing a target method needs approval, and the target
392
+ receives its own grants, never the caller's.
393
+
394
+ ## MCP and Agent tools
395
+
396
+ Connect an MCP client to `https://<your-oyster>/mcp` with
397
+ `Authorization: Bearer <key>`. Installed App methods are available through
398
+ `execute` as `env.<APP>`, a dotted method is a nested property
399
+ (`env.BONSAI.repos.list({})`), and `forage.search` and `forage.describe`
400
+ discover them. A key's App writes run under the owner's approval recorded when
401
+ the key was created, so a headless client such as `claude -p` can write. Every
402
+ other write, including the owner's own calls, needs a client that supports form
403
+ elicitation; anonymous callers are refused.
404
+
405
+ When the host has a Computer, the catalog also holds it as
406
+ `env.computers.workspace`, with the operations every Computer advertises
407
+ (`read`, `list`, `write`, `mkdir`, `bash`, `exec` and the process tools). Each
408
+ call asks for approval. `oysterComputerTools(host, principal)` returns that
409
+ Knapsack source and its grants.
410
+
411
+ Workers route every MCP request to the tenant's `MCP` Durable Object: export
412
+ `OysterMcp` from `oyster/workers`, or derive it from
413
+ `createOysterGitMcpOwner(root)`. SDK sessions belong to the authenticated owner;
414
+ after a restart that loses the live transport, the old session ID returns 404
415
+ and the client initializes a fresh one. Pending execution and elicitation are
416
+ never replayed.
417
+
418
+ Agent and key adapters call `await oysterAppMethods(host, principal, access)`
419
+ from `@fungi.computer/oyster/mcp` and pass the result in Mycelium's `sources`.
420
+ Its `grants` names each module at the level (`read` or `write`) the caller
421
+ holds, so Mycelium refuses a write to a read-only module up front. For an Agent,
422
+ `access` is `{kind: "agent", policy}`, the owner's one stored approval; for a
423
+ named key it is `{kind: "key", keyId, byInstallation}`, one approval per
424
+ installation the key's grants admit, and other installations are not listed at
425
+ all. A key's grants are fixed at `POST /api/keys`; to change them, revoke it
426
+ (`POST /api/keys/revoke`) and issue a new one. `external` methods are refused
427
+ with `approval_required`. Capture again when tool policy, installation
428
+ authority, a key's grants or a Release changes.
429
+
430
+ ## Pack and build App Releases
431
+
432
+ `packRelease` from `@fungi.computer/oyster/pack` builds an App from one commit.
433
+ Pass the repository root as `sourceDirectory`, an explicit `sourceRevision`
434
+ (`git:<full commit SHA>`) and a `recipe` whose paths are relative to that root;
435
+ dirty files and external build outputs are not inputs. This packs the Notes
436
+ example App kept at the root of its own repository, `./notes-app`:
437
+
438
+ ```ts
439
+ import { execFileSync } from "node:child_process";
440
+ import { packRelease } from "@fungi.computer/oyster/pack";
441
+
442
+ const commit = execFileSync("git", ["-C", "./notes-app", "rev-parse", "HEAD"], {
443
+ encoding: "utf8",
444
+ }).trim();
445
+
446
+ await packRelease({
447
+ appId: "app_notes",
448
+ sourceDirectory: "./notes-app",
449
+ sourceRevision: `git:${commit}`,
450
+ recipe: {
451
+ entry: "ui/index.html",
452
+ assets: {
453
+ maxManifestBytes: 1_048_576,
454
+ maxObjects: 1024,
455
+ maxObjectBytes: 16_777_216,
456
+ maxTotalBytes: 67_108_864,
457
+ },
458
+ assetBase: "./",
459
+ maxOutputBytes: 67_108_864,
460
+ backend: {
461
+ entry: "backend/index.ts",
462
+ exportName: "Notes",
463
+ compatibilityDate: "2026-09-04",
464
+ runtime: { kind: "durable-facet", stateSchema: 1 },
465
+ },
466
+ },
467
+ outDirectory: "./notes-release",
468
+ });
469
+ ```
470
+
471
+ The result holds `release.json` and `artifacts/`. Install it with
472
+ `oyster install ./notes-release --installation-id notes` (with `OYSTER_URL` and
473
+ `OYSTER_OWNER_KEY` set) or `installRelease`, which uploads the artifacts and
474
+ makes one `POST /api/installations`: 201 for a new installation, 200 when it
475
+ switches an existing one to the Release, keeping its data. `installFromSource`
476
+ captures a commit from an Artifacts remote, builds it the same way and installs
477
+ it, keeping source credentials and the owner key separate.
478
+
479
+ The compiler reads the nearest package's `fungi.app` declaration, plus
480
+ `fungi.backendDefinition` for Apps with a backend, and derives the API from that
481
+ definition; handwritten package API methods are refused. An App keeps its recipe
482
+ in `package.json#fungi.build`, with paths relative to the App's directory:
483
+ `readBuildManifest(packageJson)` decodes it and
484
+ `appBuildRecipe(manifest, directory)` roots it for a captured checkout. Unknown
485
+ build fields are refused, and the recipe policy is pinned as
486
+ `package-json-fungi-build-v4`.
487
+
488
+ Recipes come in two kinds. A closed source HTML recipe (no `kind`, an entry such
489
+ as `ui/index.html`) installs the captured lockfile with the pinned
490
+ `pnpm@11.24.0` and no lifecycle scripts, builds the workspace TypeScript
491
+ projects and stylesheets it imports, and builds the HTML with Vite; its package
492
+ must be a pnpm workspace member or a standalone repository root. A
493
+ `kind: "bundled-html"` recipe accepts committed, ready assets such as
494
+ `bundle/index.html`. Both require an explicit `assets` policy; set
495
+ `backend: null` for a UI-only App. A workspace dependency that cannot build from
496
+ its `tsconfig.build.json` may name one package script,
497
+ `"fungi": { "build": { "script": "build" } }`, which runs only in a Computer
498
+ build; every other composition, including `packRelease`, refuses it.
499
+
500
+ `@fungi.computer/oyster/build` is the Node half:
501
+ `createLocalCommitSourceCapture` captures a commit, `createAppCandidatePreparer`
502
+ builds it with `createLocalBuildExecutor`, `createLocalArtifactWriter` writes
503
+ the objects, and
504
+ `createArtifactsSourceCapture({ remote, token, sourceRevision })` captures an
505
+ exact commit from an Artifacts remote. `@fungi.computer/oyster/build-contract`
506
+ is the Worker-safe half: recipe schemas, normalization, digests and
507
+ orchestration, with no filesystem, subprocess or compiler imports. Builds run in
508
+ the host's trusted build environment, never inside a request handler.
509
+
510
+ **Builds on the standalone host.** Bonsai's repository Settings **Make this an
511
+ App** (or `APPS.register({ repo })`) registers a repository from the committed
512
+ root `package.json#fungi.build`; callers cannot override its identity or recipe.
513
+ `APPS.buildStatus({ repo })` or `APPS.buildStatus({ jobId })` reads a build. An
514
+ accepted push to main starts the Trellis build-on-merge Workflow, which builds,
515
+ verifies the source and installs within existing grants. New permissions, and
516
+ every fresh installation, return `needs_consent` until the owner selects the
517
+ built Release directly; Workflows can update an installation but never widen its
518
+ grants. `apps.install` and `APPS.select` need the successful build's `jobId`
519
+ alongside `installationId` and `release`.
520
+
521
+ ## The shell
522
+
523
+ The shell client lives in its own package,
524
+ [`@fungi.computer/nacre`](https://github.com/fungi-computer/nacre): workbench
525
+ host, command host, keys, commands, window manager and the shell-module
526
+ contract. `@fungi.computer/oyster/page` mounts one installed App's sandboxed
527
+ frame; menus, the command palette and every other piece of desktop chrome belong
528
+ to the shell.
529
+
530
+ A shell is not a framed App. When the owner opens the home installation, the
531
+ host's page script renders the shell in the top-level document with the host's
532
+ permissions: it reads the installation directory and opens, arranges and closes
533
+ every App. Choose a shell you trust, as you would the host. Child Apps stay
534
+ isolated: `WorkbenchHost.mount(container, launch, events)` mounts each in its
535
+ own sandboxed, cross-origin frame inside a slot the shell owns, and nothing
536
+ granted to the shell is lent to them. A minimized window keeps its frame
537
+ mounted, so restoring it never reloads the App. Read the home installation's
538
+ handles with `oysterShellHandles(readOysterPageConfig())`, and connect each
539
+ child frame with `connectOysterApp`.
540
+
541
+ Oyster core imports no home App: it serves the selected enabled installation, or
542
+ its installation list when there is none. `@fungi.computer/oyster/root-data`
543
+ adapts the installation and verified Release owners into workbench metadata. The
544
+ workbench host's `memberAvatar()` is a read-only projection of the signed-in
545
+ member's avatar preference.
546
+
547
+ ## Core concepts
548
+
549
+ ### Authorization
550
+
551
+ `@fungi.computer/oyster/authorization` is Oyster's one authorization owner.
552
+ Every route is registered through `routes()` with a typed requirement
553
+ (`publicRoute`, `door`, `owner`, `member`, `app`, `apps`, `agent`, `agents`,
554
+ `computer`), and an undeclared route is not served. The owner reaches
555
+ everything. A named key reaches exactly its Ear Tag grants: `apps.read` or
556
+ `apps.use` per installation (including that App's git repositories),
557
+ `agents.use` per Agent, and `computer.use` for the Computer, its files and
558
+ media. An Agent reaches its approved App tool policy, and nothing anonymous
559
+ reaches an App. `owner("direct")` refuses App-mediated requests, so consent,
560
+ keys and secrets never ride an App.
561
+
562
+ A browser signs in only with the owner key, through `/login` and its
563
+ `SameSite=Strict` session cookie; named keys sign in only by header. Anonymous
564
+ requests reach only `/login`, `robots.txt`, digest-pinned shell and App UI bytes
565
+ and the website chat.
566
+
567
+ ### Owner state and selection
568
+
569
+ Oyster is not admission: the host decides who may install, enable or call an
570
+ App, then calls `apply` with the complete owner-issued state and `fetch` or
571
+ `call` with the admitted selection. Both identify the Instance, owner, App,
572
+ Release and authority version. Oyster persists the version the owner supplied
573
+ and never trusts a guest's claim to it.
574
+
575
+ | Owner state | Runtime behavior |
576
+ | ----------- | --------------------------------------------------------------- |
577
+ | `enabled` | Resolve and activate the eligible backend. |
578
+ | `disabled` | Fence new requests and abort connections while retaining state. |
579
+ | `deleted` | Record deletion, abort, purge state and retain a tombstone. |
580
+
581
+ An exact retry returns its recorded result, changed input at the same version
582
+ conflicts, and older versions are stale. A same-schema Release replacement keeps
583
+ backend state; a changed schema fails with `state_schema_migration_unsupported`.
584
+ Deletion persists `deleting` before purge and `deleted` afterwards, and a later
585
+ access resumes an interrupted purge.
586
+
587
+ ### Instance ports
588
+
589
+ `createAppInstance` is the Effect core. Its host supplies `read`, `write`,
590
+ `resolve`, `abort`, `purge` and `connect` for one Instance ID. `resolve` returns
591
+ the selected Release's verified backend: runtime profile, state-schema version,
592
+ compatibility date, export name and bundled ESM under an immutable digest.
593
+ Admission takes the lifecycle lock while acquiring a connection but not while
594
+ waiting on App code, so disable and delete can abort in-flight work.
595
+
596
+ ### Scoped App storage
597
+
598
+ `createAppStorage` from `@fungi.computer/oyster/app-storage` is the SQLite owner
599
+ for declared App keys. Supply the database connection and an atomic `commit`;
600
+ `open(authorize)` binds a member view and `openInstallation(authorize)` binds
601
+ lifecycle work to the shared team layer. Each operation rechecks live admission,
602
+ and writes check the expected revision, declared scopes, size and quotas. After
603
+ commit, `events(key)` publishes bounded invalidations. Installation and
604
+ membership deletion use `purgeAppStorageInCommit` and
605
+ `purgeAppMemberStorageInCommit` inside the caller's transaction. A backend
606
+ receives `env.APP_STORAGE` only for operations its declaration and grants admit,
607
+ through the `OysterBinding` entrypoint the Worker exports.
608
+
609
+ ### Durable Object composition
610
+
611
+ `createCloudflareAppInstance` keeps supervisor state in a SQLite Durable Object
612
+ and runs the backend in a named `app` facet loaded through the Worker Loader; a
613
+ new Release keeps that facet's database. The loader key includes the Instance ID
614
+ and artifact digest, so Instances of one Release never share guest module scope.
615
+ Guest code receives only the `bindings()` its host builds, with no ambient
616
+ outbound access.
617
+
618
+ Activation is checked before it is selected: the candidate backend loads in a
619
+ unique isolate over a disposable `candidate` facet (a copy of `app` for an
620
+ initialized Instance) with denied bindings and no network, and the host opens
621
+ the immutable UI entry in a zero-grant browser session (`checkBootPage`). The UI
622
+ result is reported, never authority: `failed` when the page did not mount,
623
+ `not_checked` when no browser, a timeout or unconfirmed cleanup prevented the
624
+ check. The copy is a construction test, not a backup.
625
+
626
+ One Instance shares its guest between up to eight verified reads; writes, raw
627
+ requests and supervisor work run alone. Guest work runs only while a frame on
628
+ that Instance is admitted, and stopping the guest never erases its database.
629
+
630
+ ### Guest execution policy
631
+
632
+ `createOyster({ ...host, guestLimits: { cpuMs: 250, subRequests: 10 } })`
633
+ configures per-invocation budgets. Omitted fields default to 1,000 milliseconds
634
+ of CPU and 50 subrequests. CPU must be a positive integer; subrequests may be
635
+ zero to forbid them. Invalid configuration fails before accepting requests.
636
+ `createOysterWorker({ guestLimits })` wires this for the standalone Worker, and
637
+ direct `createCloudflareAppInstance` callers pass it in its final argument.
638
+ Changing an Instance's budgets restarts its facet and keeps its SQLite state.
639
+ Runtime enforcement uses the
640
+ [Worker Loader resource limits](https://developers.cloudflare.com/dynamic-workers/usage/limits/).
641
+
642
+ Guest HTTP responses keep only content metadata: content type, language,
643
+ encoding, length, disposition and range, accepted ranges, ETag and
644
+ last-modified. Oyster adds `Cache-Control: no-store`,
645
+ `X-Content-Type-Options: nosniff` and a sandboxed, deny-by-default Content
646
+ Security Policy. Cookies, redirects and other headers cannot come from guests.
647
+
648
+ ### Hosting many tenants
649
+
650
+ Pass your own `OysterTenancy` from `@fungi.computer/oyster/tenant` as
651
+ `oysterGitRoot({ tenancy })`. Its `resolve(request)` selects one tenant from the
652
+ request origin before sign-in and returns that tenant's `TenantScope` (built
653
+ with `tenantScope(tenantId, origin)`) and authentication, or `null` to refuse an
654
+ unknown origin. Oyster uses the scope for registry, workspace, keys, webhooks
655
+ and repository names, and pins each Instance to its tenant. `ownerOrKeyTenancy`
656
+ is the single-tenant case.
657
+
658
+ ## Contract changes
659
+
660
+ - **App `AGENTS.send`** requires a caller-owned `requestId`, non-empty and at
661
+ most 256 UTF-8 bytes. Mint it once per user intent and retry an UNKNOWN
662
+ outcome with the same input unchanged; the recipient may already have accepted
663
+ it. Grove's `sendMessage` requires and forwards the same field.
664
+ - **Build recipes** come from the selected source's `package.json`:
665
+ `standaloneAppSet` no longer carries `StarterApp.recipe`; read it with
666
+ `readBuildManifest` and `appBuildRecipe`. Builders refuse metadata under any
667
+ policy other than `package-json-fungi-build-v4`.
668
+ - **Repository registration** is repo-only `APPS.register({ repo })`; the
669
+ `PUT /api/apps/:appId/build-source` route is gone.
670
+ - **Installation from a build** (`apps.install`, `APPS.select`) needs the
671
+ build's `jobId`.
672
+ - **Five internal entry points are no longer exported:** `app-builds`,
673
+ `app-sources`, `catalog-frame`, `standalone/visitor-edge` and
674
+ `apps/permissions-port`. They were parts of the standalone host with no
675
+ outside callers; use the composed hosts above.
55
676
 
56
677
  ```ts
57
678
  const intent = {
@@ -66,50 +687,85 @@ const accepted = await env.AGENTS.send(intent);
66
687
  // If the outcome is UNKNOWN, retry env.AGENTS.send(intent), unchanged.
67
688
  ```
68
689
 
69
- `requestId` is required, non-empty, and bounded to 256 UTF-8 bytes. Mint it once
70
- per user intent, outside the send/retry function, and retain the same input
71
- until the outcome is known. An UNKNOWN response is not evidence that admission
72
- failed: the recipient may already have accepted the work. Retrying that same
73
- intent must not create another delivery. A new intent needs a new request ID.
690
+ ## Drive one Instance in memory
691
+
692
+ This self-contained example drives one Instance through in-memory ports. A
693
+ disabled Instance never resolves or connects a backend, so no Release is needed.
694
+ The request runs in a frame from `createInvocationGate`, the same gate the
695
+ standalone Instances and the Hub open for every call.
74
696
 
75
- The App bridge forwards the caller's ID. The standalone adapter no longer mints
76
- one, and neither path substitutes a transport `callId`. An omitted ID is
77
- refused; there is no compatibility form. Grove's `sendMessage` method requires
78
- and forwards the same field. Admission, the existing send budget, and follow-up
79
- delivery policy are unchanged.
697
+ ```ts
698
+ import * as Effect from "effect/Effect";
699
+ import * as Schema from "effect/Schema";
700
+ import {
701
+ AppInstanceError,
702
+ createAppInstance,
703
+ instanceIds,
704
+ ownerStateSchema,
705
+ type Instance,
706
+ } from "@fungi.computer/oyster";
707
+ import {
708
+ APP_INVOCATION_CEILING_MS,
709
+ createInvocationGate,
710
+ invocationFactsSchema,
711
+ } from "@fungi.computer/oyster/invocation";
80
712
 
81
- **BREAKING CHANGE:** App `AGENTS.send` and Grove `sendMessage` now require
82
- caller-owned `requestId`. Update existing Apps and their retry state before
83
- using this API. This release note does not authorize a version bump or
84
- publication.
713
+ const instanceId = instanceIds.instance.generate();
714
+ let stored: Instance | null = null;
715
+ const instance = createAppInstance({
716
+ instanceId,
717
+ read: () => Effect.succeed(stored),
718
+ write: (record) =>
719
+ Effect.sync(() => {
720
+ stored = record;
721
+ }),
722
+ resolve: () => Effect.fail(new Error("No Releases in this example")),
723
+ abort: () => Effect.void,
724
+ purge: () => Effect.void,
725
+ connect: () => Effect.fail(new Error("No backend in this example")),
726
+ });
85
727
 
86
- ## Guest execution policy
728
+ const selection = {
729
+ instanceId,
730
+ owner: { kind: "installation", id: "installation_example" },
731
+ appId: "app_example",
732
+ releaseId: "rel_example",
733
+ authorityVersion: 2,
734
+ } as const;
735
+ const disabled = Schema.decodeUnknownSync(ownerStateSchema)({
736
+ ...selection,
737
+ status: "disabled",
738
+ });
87
739
 
88
- `createOyster({ ...host, guestLimits: { cpuMs: 250, subRequests: 10 } })`
89
- configures per-invocation budgets. Omitted fields default to 1,000 milliseconds
90
- of CPU and 50 subrequests. CPU must be a positive integer; subrequests may be
91
- zero to forbid them. Both must fit a signed 32-bit integer. Invalid
92
- configuration fails before accepting requests.
93
-
94
- The host's `InstanceDirectory.get(id, limits)` adapter must carry those budgets
95
- to guest execution.
96
- `createOysterWorker({ guestLimits: { cpuMs: 250, subRequests: 10 } })` supplies
97
- this wiring for the standalone Worker. Direct `createCloudflareAppInstance`
98
- callers can supply the same policy in its final argument; otherwise the same
99
- defaults apply. The loader code carries limits for both HTTP and method calls,
100
- without granting ambient outbound access. Changing an Instance's budgets
101
- invalidates its running facet while preserving its SQLite state. Runtime
102
- enforcement uses the
103
- [Worker Loader resource limits](https://developers.cloudflare.com/dynamic-workers/usage/limits/).
740
+ const receipt = await Effect.runPromise(instance.apply(disabled));
741
+ console.log(receipt.status); // "disabled"
104
742
 
105
- Guest HTTP responses retain only content metadata: content type, language,
106
- encoding, length, disposition and range, accepted ranges, ETag and
107
- last-modified. Oyster supplies `Cache-Control: no-store`,
108
- `X-Content-Type-Options: nosniff`, and a sandboxed, deny-by-default Content
109
- Security Policy. Cookies, redirects, origin policy, service-worker scope and
110
- unrecognized headers cannot come from guests. Host-issued login responses retain
111
- their cookies.
112
-
113
- The Node-only `@fungi.computer/oyster/build` entry owns captured App
114
- compilation; `@fungi.computer/oyster/build-contract` provides its Worker-safe
115
- recipe and candidate orchestration without loading the executor.
743
+ // A request runs inside an invocation frame: the caller facts the host admitted,
744
+ // a deadline, and an abort signal the gate owns.
745
+ const gate = createInvocationGate<null>({
746
+ abortGuest: () => Promise.resolve(),
747
+ close: () => Promise.resolve(),
748
+ });
749
+ const facts = Schema.decodeUnknownSync(invocationFactsSchema)({
750
+ instanceId,
751
+ selection,
752
+ artifactDigest: `sha256:${"0".repeat(64)}`,
753
+ subject: {
754
+ kind: "call",
755
+ context: {
756
+ actor: { kind: "member", memberId: "member_example" },
757
+ computerId: null,
758
+ },
759
+ },
760
+ grants: [],
761
+ ancestry: [],
762
+ deadlineAt: Date.now() + APP_INVOCATION_CEILING_MS,
763
+ });
764
+ const refused = await gate.run(facts, null, (frame) =>
765
+ Effect.runPromise(
766
+ Effect.result(instance.fetch(frame, new Request("https://app.test/"))),
767
+ ),
768
+ );
769
+ if (refused._tag === "Failure" && refused.failure instanceof AppInstanceError)
770
+ console.log(refused.failure.code); // "instance_inactive"
771
+ ```