@fungi.computer/oyster 0.0.1 → 0.2.0

package/docs/api/workers-git.md

@@ -234,39 +234,75 @@ unknown, revoked, expired or suspended key.
 
 ### OysterWebhooks
 
-Webhook subscriptions, their secrets and signed, retried deliveries.
+The tenant's App event delivery owner: webhook subscriptions with signed,
+retried deliveries, and host recipients with durable per-recipient records. An
+emit commits here and returns; every delivery happens on the alarm.
 
 #### Extends
 
-- `DurableObject`\<[`OysterKeysEnv`](#oysterkeysenv)\>
+- `DurableObject`\<`Env`\>
+
+#### Type Parameters
+
+| Type Parameter                                    | Default type                      |
+| ------------------------------------------------- | --------------------------------- |
+| `Env` _extends_ [`OysterKeysEnv`](#oysterkeysenv) | [`OysterKeysEnv`](#oysterkeysenv) |
 
 #### Constructors
 
 ##### Constructor
 
 ```ts
-new OysterWebhooks(ctx, env): OysterWebhooks;
+new OysterWebhooks<Env>(ctx, env): OysterWebhooks<Env>;
 ```
 
 ###### Parameters
 
-| Parameter | Type                              |
-| --------- | --------------------------------- |
-| `ctx`     | `DurableObjectState`              |
-| `env`     | [`OysterKeysEnv`](#oysterkeysenv) |
+| Parameter | Type                 |
+| --------- | -------------------- |
+| `ctx`     | `DurableObjectState` |
+| `env`     | `Env`                |
 
 ###### Returns
 
-[`OysterWebhooks`](#oysterwebhooks)
+[`OysterWebhooks`](#oysterwebhooks)\<`Env`\>
 
 ###### Overrides
 
 ```ts
-DurableObject<OysterKeysEnv>.constructor
+DurableObject<Env>.constructor
 ```
 
 #### Methods
 
+##### recipientDeliveries()
+
+```ts
+recipientDeliveries(recipient): Readonly<{
+  recipient: string;
+  eventId: string;
+  type: string;
+  state: "pending" | "failed" | "delivered";
+  attempts: number;
+  lastError: string | null;
+  updatedAt: number;
+}>[];
+```
+
+Recent deliveries to one host recipient, newest first.
+
+###### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `recipient` | `string` |
+
+###### Returns
+
+`Readonly`\<\{ `recipient`: `string`; `eventId`: `string`; `type`: `string`;
+`state`: `"pending"` \| `"failed"` \| `"delivered"`; `attempts`: `number`;
+`lastError`: `string` \| `null`; `updatedAt`: `number`; \}\>[]
+
 ##### subscribe()
 
 ```ts
@@ -358,25 +394,29 @@ Recent deliveries for one subscription, newest first.
 
 ```ts
 enqueue(
-   installationId,
+   source,
    payload,
-   eventId
-): number;
+   eventId,
+   recipients
+): Promise<number>;
 ```
 
-Queue an event for every matching subscription (idempotent per event id).
+Accept an emitted event: queue it for every matching subscription and every
+named host recipient (idempotent per event id). Nothing is delivered before this
+returns, so no recipient can fail the emitter's write.
 
 ###### Parameters
 
-| Parameter        | Type                                                      |
-| ---------------- | --------------------------------------------------------- |
-| `installationId` | `string`                                                  |
-| `payload`        | [`StandardWebhookPayload`](git.md#standardwebhookpayload) |
-| `eventId`        | `string`                                                  |
+| Parameter    | Type                                                      |
+| ------------ | --------------------------------------------------------- |
+| `source`     | [`HostEventSource`](#hosteventsource)                     |
+| `payload`    | [`StandardWebhookPayload`](git.md#standardwebhookpayload) |
+| `eventId`    | `string`                                                  |
+| `recipients` | readonly `string`[]                                       |
 
 ###### Returns
 
-`number`
+`Promise`\<`number`\>
 
 ##### alarm()
 
@@ -384,7 +424,7 @@ Queue an event for every matching subscription (idempotent per event id).
 alarm(): Promise<void>;
 ```
 
-Deliver due webhooks, then schedule the next retry.
+Deliver due webhooks and recipient rows, then schedule the next retry.
 
 ###### Returns
 
@@ -1015,6 +1055,57 @@ host handle decodes.
 
 ## Type Aliases
 
+### HostEventSource
+
+```ts
+type HostEventSource = Readonly<{
+  installationId: string;
+  appId: string;
+  releaseId: string;
+}>;
+```
+
+The emitting installation as the host attested it on the emit's frame.
+
+---
+
+### HostRecipientEvent
+
+```ts
+type HostRecipientEvent = Readonly<{
+  source: HostEventSource;
+  type: string;
+  eventId: string;
+  payload: Readonly<{
+    type: string;
+    timestamp: string;
+    data: unknown;
+  }>;
+}>;
+```
+
+One accepted event, as a host recipient receives it.
+
+---
+
+### RecipientDelivery
+
+```ts
+type RecipientDelivery = Readonly<{
+  recipient: string;
+  eventId: string;
+  type: string;
+  state: "pending" | "delivered" | "failed";
+  attempts: number;
+  lastError: string | null;
+  updatedAt: number;
+}>;
+```
+
+One recipient's delivery record for one event.
+
+---
+
 ### ArtifactsGit
 
 ```ts
@@ -1288,7 +1379,7 @@ One live guest frame's Git custody; never a guest argument.
 const eventsBinding: OysterBindingRow<OysterGitWorkerEnv>;
 ```
 
-EVENTS: signed webhook delivery in this Instance's tenant namespace.
+EVENTS for a host with webhook subscribers only.
 
 ---
 
@@ -1347,6 +1438,34 @@ The Artifacts namespace: the binding when present, else the REST API.
 
 ---
 
+### eventsBindingFor()
+
+```ts
+function eventsBindingFor<Env>(recipients): OysterBindingRow<Env>;
+```
+
+EVENTS: commit the emit to this tenant's delivery owner and return. Webhook
+subscribers and the host recipients a root names are delivered afterwards, so a
+subscriber outage never fails the emitting App's write.
+
+#### Type Parameters
+
+| Type Parameter                                              |
+| ----------------------------------------------------------- |
+| `Env` _extends_ [`OysterGitWorkerEnv`](#oystergitworkerenv) |
+
+#### Parameters
+
+| Parameter    | Type                                                     |
+| ------------ | -------------------------------------------------------- |
+| `recipients` | (`context`, `frame`) => `Promise`\<readonly `string`[]\> |
+
+#### Returns
+
+[`OysterBindingRow`](workers.md#oysterbindingrow)\<`Env`\>
+
+---
+
 ### gitAdminRoutes()
 
 ```ts

package/docs/api/workers.md

@@ -1557,7 +1557,16 @@ Files in an R2 bucket under `prefix` (one workspace per prefix).
 ### r2ArtifactStore()
 
 ```ts
-function r2ArtifactStore(bucket): ArtifactStore;
+function r2ArtifactStore(bucket): Readonly<{
+  get: (artifactRef) => Promise<Uint8Array<ArrayBufferLike> | null>;
+  put: (artifactRef, bytes) => Promise<void>;
+}> &
+  Readonly<{
+    head: (artifactRef) => Promise<Readonly<{
+      byteLength: number;
+      digest: Sha256Digest | null;
+    }> | null>;
+  }>;
 ```
 
 Store Release artifacts in an R2 bucket.
@@ -1570,7 +1579,11 @@ Store Release artifacts in an R2 bucket.
 
 #### Returns
 
-[`ArtifactStore`](host.md#artifactstore)
+`Readonly`\<\{ `get`: (`artifactRef`) =>
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\> \| `null`\>; `put`: (`artifactRef`,
+`bytes`) => `Promise`\<`void`\>; \}\> & `Readonly`\<\{ `head`: (`artifactRef`)
+=> `Promise`\< \| `Readonly`\<\{ `byteLength`: `number`; `digest`:
+`Sha256Digest` \| `null`; \}\> \| `null`\>; \}\>
 
 ---
 

package/docs/site/agent-quickstart.mdx

@@ -23,7 +23,8 @@ read the "If it fails" notes under it before trying anything else.
 ## 1. Check prerequisites
 
 You need Node 24 or newer, pnpm, Git, curl and openssl. You do not need a
-Cloudflare account until step 7, and you never need Docker for these steps.
+Cloudflare account until step 7. Docker is needed only in step 7, where Wrangler
+builds the Computer's container image.
 
 ```sh
 node --version
@@ -43,13 +44,13 @@ If it fails:
 
 ## 2. Create a project
 
-Make a new directory, install Oyster and Wrangler, and copy the standalone
+Make a new directory, install Oyster, its Computer and Wrangler, and copy the
 example Worker out of the package:
 
 ```sh
 mkdir my-oyster
 cd my-oyster
-pnpm add @fungi.computer/oyster
+pnpm add @fungi.computer/oyster @fungi.computer/computer
 pnpm add -D wrangler
 cp node_modules/@fungi.computer/oyster/examples/standalone/worker.ts .
 cp node_modules/@fungi.computer/oyster/examples/standalone/wrangler.jsonc .
@@ -67,26 +68,30 @@ If it fails:
   `protobufjs`: pnpm installed them without running their install scripts, and
   nothing in this guide needs those scripts. Go on.
 - `cp: cannot stat …/examples/standalone/…`: the install did not finish. Run
-  `pnpm add @fungi.computer/oyster` again and read its first error.
+  `pnpm add @fungi.computer/oyster @fungi.computer/computer` again and read its
+  first error.
 
 ## 3. Run a local Oyster
 
-`worker.ts` and `wrangler.jsonc` are a complete single-owner Oyster. Run it
-under `wrangler dev` on your machine. Choose an owner key and keep this terminal
-open:
+`worker.ts` and `wrangler.jsonc` are the whole Oyster. Run it under
+`wrangler dev` on your machine, without its Computer container. Oyster serves an
+HTTPS origin; `--local-upstream` presents your loopback requests to it at
+`https://oyster.test`. Choose an owner key and keep this terminal open:
 
 ```sh
 export OYSTER_OWNER_KEY=$(openssl rand -hex 24)
 export OYSTER_URL=http://127.0.0.1:8787
 echo "$OYSTER_OWNER_KEY" > .oyster-owner-key
-npx wrangler dev --local --ip 127.0.0.1 --port 8787 \
-  --var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:$OYSTER_URL
+npx wrangler dev --local --enable-containers=false --ip 127.0.0.1 --port 8787 \
+  --local-upstream oyster.test --upstream-protocol https \
+  --var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:https://oyster.test
 ```
 
-Expected output: a bindings table listing `env.MCP (OysterMcp)`,
-`env.REGISTRY (OysterRegistry)`, `env.INSTANCES (OysterInstance)`,
-`env.RELEASES (oyster-releases)` and `env.LOADER`, then
-`Ready on http://127.0.0.1:8787`.
+Expected output: warnings that the AI and Artifacts bindings reach remote
+resources, a bindings table listing `env.REGISTRY (OysterRegistry)`,
+`env.INSTANCES (StandaloneInstance)`, `env.COMPUTER (ComputerDO)` and the rest,
+then `Ready on http://127.0.0.1:8787`. Locally there is no Computer, git storage
+or Workers AI; steps 3 to 5 need none of them.
 
 Keep it running. Open a second terminal in `my-oyster`, set the same two
 variables there, and check that Oyster answers:
@@ -114,8 +119,9 @@ If it fails:
   `/login` check prints `200`:
 
   ```sh
-  npx wrangler dev --local --ip 127.0.0.1 --port 8787 \
-    --var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:$OYSTER_URL \
+  npx wrangler dev --local --enable-containers=false --ip 127.0.0.1 --port 8787 \
+    --local-upstream oyster.test --upstream-protocol https \
+    --var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:https://oyster.test \
     > oyster-dev.log 2>&1 &
   ```
 
@@ -265,29 +271,10 @@ If it fails:
 
 ## 6. Add Git
 
-The package also ships `examples/git`: the same Oyster with the git door, so
-people and agents `clone`, `fetch` and `push` App repositories with ordinary
-`git` at `/git/<installation>/<repo>.git`. Repositories live in Cloudflare
-Artifacts, which `wrangler dev` cannot emulate, so the Git worker runs once it
-is deployed in step 7. To use it, copy it over the standalone files:
-
-```sh
-cp node_modules/@fungi.computer/oyster/examples/git/worker.ts .
-cp node_modules/@fungi.computer/oyster/examples/git/wrangler.jsonc .
-```
-
-Compared with `examples/standalone`, `examples/git/worker.ts` builds one
-`oysterGitRoot` with `ownerOrKeyTenancy` and adds:
-
-- the git door, mounted by `createOysterGitWorker(root)`;
-- owner and named keys that sign in to git, plus `/api/keys` and
-  `/api/webhooks`;
-- `OysterGitInstance` as `OysterInstance`, which hands Apps `env.GIT` and
-  `env.EVENTS`;
-- the `ARTIFACTS` binding and the `KEYS` and `WEBHOOKS` Durable Objects in its
-  `wrangler.jsonc`, which names the Worker `oyster-git`.
-
-With the Git worker deployed, give each agent its own key:
+Git is already part of the host: people and agents `clone`, `fetch` and `push`
+App repositories with ordinary `git` at `/git/<installation>/<repo>.git`, with
+repositories in Cloudflare Artifacts. Artifacts runs only once the Worker is
+deployed in step 7. There, give each agent its own key:
 
 ```sh
 curl -s -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" \
@@ -299,20 +286,15 @@ curl -s -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" \
 Expected output: JSON with a `plaintext` field starting `oyk_`. Oyster shows it
 once; that key signs in to `git` and to `/mcp`.
 
-If it fails:
-
-- `404`: the deployed Worker is the standalone one. Copy the `examples/git`
-  files and deploy again.
-
 ## 7. Deploy to Cloudflare Workers
 
-This step needs a Cloudflare account on Workers Paid; Git also needs Artifacts
-enabled on it. Ask the person before you deploy anything.
+This step needs a Cloudflare account on Workers Paid with Containers, Artifacts,
+Workers AI and Workflows enabled, and Docker running on this machine. Ask the
+person before you deploy anything.
 
-`wrangler.jsonc` names the Worker (`oyster`, or `oyster-git` for Git) and its R2
-bucket, `oyster-releases`. The Worker's address is
-`https://<worker name>.<your-subdomain>.workers.dev`, or a custom domain. For
-the standalone Worker:
+`wrangler.jsonc` names the Worker `oyster`, its R2 bucket `oyster-releases` and
+its Artifacts namespace `oyster`. The Worker's address is
+`https://oyster.<your-subdomain>.workers.dev`, or a custom domain:
 
 ```sh
 npx wrangler login
@@ -322,9 +304,21 @@ npx wrangler deploy --var OYSTER_ORIGIN:$OYSTER_URL
 printf '%s' "$OYSTER_OWNER_KEY" | npx wrangler secret put OYSTER_OWNER_KEY
 ```
 
-Expected output: `wrangler deploy` prints the deployed `https://` URL, and
-`wrangler secret put` reports the secret uploaded. Then install Hello exactly as
-in step 4, with `OYSTER_URL` set to the deployed address.
+Expected output: `wrangler deploy` builds the Computer image, uploads it and
+prints the deployed `https://` URL, and `wrangler secret put` reports the secret
+uploaded.
+
+Then install Fungi's seven starter Apps, each built on this Oyster's Computer
+from its own repository:
+
+```sh
+npx oyster install-apps
+```
+
+Expected output: a `source recorded` line per App, `Building … on the Computer`
+and `Installed …` lines (two builds at a time, Tourtois first), a timing table,
+and `Installed 7 Apps`. Open `$OYSTER_URL/login` with the owner key to see the
+Tourtois desktop.
 
 To keep `OYSTER_ORIGIN` across later deploys, set `vars.OYSTER_ORIGIN` in
 `wrangler.jsonc`; every deploy replaces the Worker's variables.
@@ -336,14 +330,17 @@ If it fails:
 - A secret prompt on stdin: pipe the key as shown; never type it into a log.
 - Bindings or migrations refused: deploy the copied `wrangler.jsonc` unchanged
   except for `vars` and the bucket name.
+- `docker` not found or not running: start Docker; Wrangler builds the Computer
+  image from `node_modules/@fungi.computer/computer/Dockerfile`.
+- A build `failed` in `install-apps`: run it again; finished Apps are kept and
+  replaced in place.
 
 ## Where to go next
 
 - The Oyster README (`node_modules/@fungi.computer/oyster/README.md`) explains
   the host, Apps, capabilities, MCP and the shell in depth.
-- [oyster.shiit.app](https://oyster.shiit.app/) is a complete deployment of the
-  Git worker with Fungi's App set: Bonsai, Workflows, Computers, Agents and
-  media.
+- [oyster.shiit.app](https://oyster.shiit.app/) runs this same host with the
+  seven starter Apps.
 - Oyster is built from the other Fungi packages, each its own repository under
   [github.com/fungi-computer](https://github.com/fungi-computer) and on npm as
   `@fungi.computer/<name>`. The README's "Part of Fungi" section lists them.

package/examples/standalone/worker.ts

@@ -1,14 +1,7 @@
-// A standalone Oyster: one owner, Apps installed from Releases, each App's
-// backend in its own Durable Object with SQLite. Runs on Cloudflare Workers
-// (`wrangler deploy`) and on celld (`celld dev`) from the same code.
-import { createOysterWorker } from "@fungi.computer/oyster/workers";
-
-// Every App binding in every invocation frame is the one `OysterBinding` entrypoint.
-export {
-  OysterBinding,
-  OysterInstance,
-  OysterRegistry,
-  OysterMcp,
-} from "@fungi.computer/oyster/workers";
-
-export default createOysterWorker();
+// The whole Oyster: Apps installed from Releases, each with its own Durable
+// Object and SQLite; git through Artifacts; a Computer in a Cloudflare
+// Container that builds App sources and runs terminals and files; Agents on
+// Workers AI; Workflows; and media. Runs on Cloudflare Workers
+// (`wrangler deploy`) and on celld from the same code.
+export * from "@fungi.computer/oyster/standalone";
+export { default } from "@fungi.computer/oyster/standalone";

package/examples/standalone/wrangler.jsonc

@@ -1,21 +1,82 @@
 {
-  "$schema": "../../../../node_modules/wrangler/config-schema.json",
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  // The whole Oyster. Copy it beside worker.ts, set OYSTER_ORIGIN, and deploy.
   "name": "oyster",
   "main": "worker.ts",
   "compatibility_date": "2026-09-04",
   "compatibility_flags": ["nodejs_compat"],
-  "vars": { "OYSTER_ORIGIN": "https://oyster.example" },
+  "workers_dev": true,
+  "preview_urls": false,
+  "observability": { "enabled": true },
+  "workflows": [
+    {
+      "binding": "GRAPH_WORKFLOWS",
+      "name": "oyster-graphs",
+      "class_name": "StandaloneGraphWorkflow",
+    },
+  ],
   "worker_loaders": [{ "binding": "LOADER" }],
-  "r2_buckets": [{ "binding": "RELEASES", "bucket_name": "oyster-releases" }],
+  "containers": [
+    {
+      "class_name": "ComputerDO",
+      "image": "./node_modules/@fungi.computer/computer/Dockerfile",
+      "instance_type": "standard-4",
+      "max_instances": 1,
+      "rollout_active_grace_period": 0,
+      "rollout_step_percentage": [100],
+    },
+  ],
+  "ai": { "binding": "AI" },
+  "images": { "binding": "IMAGES" },
+  "r2_buckets": [
+    { "binding": "RELEASES", "bucket_name": "oyster-releases" },
+    { "binding": "APP_ARTIFACTS", "bucket_name": "oyster-releases" },
+  ],
+  "artifacts": [{ "binding": "ARTIFACTS", "namespace": "oyster" }],
+  "vars": {
+    "OYSTER_COMPUTER_ID": "workspace",
+    "OYSTER_HOME_INSTALLATION": "tourtois",
+    "OYSTER_ORIGIN": "https://oyster.example",
+    "OYSTER_OWNER_NAME": "owner",
+    // Names the AI Gateway that Prints' third-party models (GPT Image 2,
+    // Seedance, Veo) and the background media retry owner route through.
+    // Not a secret: Cloudflare creates the gateway by this id on first use.
+    "AI_GATEWAY_ID": "oyster",
+  },
   "durable_objects": {
     "bindings": [
+      { "name": "TENANTS", "class_name": "StandaloneTenants" },
       { "name": "MCP", "class_name": "OysterMcp" },
+
       { "name": "REGISTRY", "class_name": "OysterRegistry" },
-      { "name": "INSTANCES", "class_name": "OysterInstance" },
+      { "name": "WORKFLOW_RUNS", "class_name": "StandaloneWorkflowRuns" },
+      { "name": "INSTANCES", "class_name": "StandaloneInstance" },
+      { "name": "COMPUTER", "class_name": "ComputerDO" },
+      { "name": "KEYS", "class_name": "OysterKeys" },
+      { "name": "WEBHOOKS", "class_name": "OysterWebhooks" },
+      { "name": "AGENTS", "class_name": "StandaloneAgent" },
+      { "name": "AGENT_DIRECTORY", "class_name": "AgentDirectory" },
+      { "name": "MEDIA_OPERATION", "class_name": "MediaOperationDO" },
     ],
   },
+  // One initial tag: pre-launch history was collapsed (Levi 10-14, data wipe
+  // authorized), so a fresh Worker creates every bound class at once.
   "migrations": [
-    { "tag": "v1", "new_sqlite_classes": ["OysterRegistry", "OysterInstance"] },
-    { "tag": "mcp-session-owner-v1", "new_sqlite_classes": ["OysterMcp"] },
+    {
+      "tag": "oyster-v1",
+      "new_sqlite_classes": [
+        "StandaloneTenants",
+        "OysterMcp",
+        "OysterRegistry",
+        "StandaloneWorkflowRuns",
+        "StandaloneInstance",
+        "ComputerDO",
+        "OysterKeys",
+        "OysterWebhooks",
+        "StandaloneAgent",
+        "AgentDirectory",
+        "MediaOperationDO",
+      ],
+    },
   ],
 }