@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.
- package/README.md +178 -1552
- package/dist/app-builds.d.ts +5 -6
- package/dist/app-builds.js +3 -10
- package/dist/boot-host-script.js +1 -1
- package/dist/catalog-frame.d.ts +0 -1
- package/dist/embed-metafiles.js +2 -2
- package/dist/embed-scripts.js +3 -3
- package/dist/hello-app-script.js +1 -1
- package/dist/page/app-permissions.js +165 -50
- package/dist/page-script.js +3 -3
- package/dist/standalone/app-set.d.ts +9 -0
- package/dist/standalone/app-set.js +43 -0
- package/dist/standalone/app-source.js +16 -1
- package/dist/standalone/builds.d.ts +2 -2
- package/dist/standalone/builds.js +4 -0
- package/dist/standalone/computer.d.ts +6 -1
- package/dist/standalone/computer.js +10 -2
- package/dist/standalone/install-apps-cli.js +1 -1
- package/dist/standalone/local-desktop.d.ts +19 -2
- package/dist/standalone/local-desktop.js +38 -15
- package/dist/standalone/registry.d.ts +4 -1
- package/dist/standalone/registry.js +6 -0
- package/dist/standalone/try-cli.d.ts +7 -0
- package/dist/standalone/try-cli.js +88 -8
- package/docs/api/README.md +744 -88
- package/docs/site/agent-quickstart.mdx +1 -1
- package/package.json +29 -49
package/docs/api/README.md
CHANGED
|
@@ -6,52 +6,673 @@
|
|
|
6
6
|
|
|
7
7
|
# Oyster API overview
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
| `@fungi.computer/oyster/
|
|
19
|
-
| `@fungi.computer/oyster/
|
|
20
|
-
| `@fungi.computer/oyster/
|
|
21
|
-
| `@fungi.computer/oyster/
|
|
22
|
-
| `@fungi.computer/oyster/
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
| `@fungi.computer/oyster/
|
|
33
|
-
| `@fungi.computer/oyster/
|
|
34
|
-
| `@fungi.computer/oyster/
|
|
35
|
-
| `@fungi.computer/oyster/
|
|
36
|
-
| `@fungi.computer/oyster/
|
|
37
|
-
| `@fungi.computer/oyster/
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
`
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
-
|
|
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
|
-
|
|
89
|
-
|
|
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
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|
+
```
|