@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/docs/media/architecture.mmd

@@ -0,0 +1,32 @@
+flowchart LR
+  people["Browsers<br/>git clients<br/>MCP agents"]
+
+  subgraph oyster["Oyster Worker · Cloudflare Workers or celld"]
+    direction TB
+    router["Router<br/>/apps · /api · /git · /mcp"]
+    home["Tourtois home<br/>launcher · windows · settings"]
+    registry[("OysterRegistry DO<br/>installations")]
+    instance["App Instance DO<br/>one per installation"]
+    facet["App backend<br/>Worker Loader facet<br/>with its own SQLite"]
+    door["git door<br/>per-agent keys"]
+    router --> home
+    router --> registry
+    router --> instance --> facet
+    router --> door
+  end
+
+  apps["Apps as immutable Releases<br/>Bonsai · Workflows · Shed<br/>Inkcap · Grove · Prints"]
+
+  subgraph services["Bindings the host provides"]
+    direction TB
+    r2[("R2<br/>Release artifacts")]
+    artifacts[("Artifacts<br/>git repositories")]
+    platform["Braid Workflows · Computers<br/>Agents · Workers AI"]
+  end
+
+  people --> router
+  home -. "UI in sandboxed frames" .-> apps
+  registry -- "Release refs" --> r2
+  door --> artifacts
+  facet -- "declared only" --> platform
+  facet -- "GIT binding" --> artifacts

package/docs/site/agent-quickstart.mdx

@@ -0,0 +1,349 @@
+---
+title: Agent quick start
+description:
+  Hand this guide to a coding agent to install Oyster from npm, run it locally,
+  install an App, connect over MCP and deploy.
+---
+
+You are an agent setting up Oyster for a person. Follow these steps in order.
+Run every command exactly as written, from the directory each step names.
+Compare its output with the expected output before you go on. When a step fails,
+read the "If it fails" notes under it before trying anything else.
+
+## What Oyster is
+
+- Oyster hosts Apps on one Cloudflare Worker, or on celld, a Workers-compatible
+  runtime you host yourself.
+- Each App is an immutable Release built from an exact git commit. Its backend
+  runs in its own Durable Object with its own SQLite, and it gets only the
+  bindings it declares.
+- People use Apps in a browser. Agents call the same App methods over HTTP or
+  through one MCP endpoint, `/mcp`.
+
+## 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.
+
+```sh
+node --version
+pnpm --version
+git --version
+```
+
+Expected output: a `v24.` or later Node version, any pnpm version, then any
+`git version 2.x` line.
+
+If it fails:
+
+- Wrong Node: install Node 24 with your version manager, for example
+  `mise use node@24` or `nvm install 24`.
+- No pnpm: run `corepack enable`, or use `npm install` wherever this guide says
+  `pnpm add`.
+
+## 2. Create a project
+
+Make a new directory, install Oyster and Wrangler, and copy the standalone
+example Worker out of the package:
+
+```sh
+mkdir my-oyster
+cd my-oyster
+pnpm add @fungi.computer/oyster
+pnpm add -D wrangler
+cp node_modules/@fungi.computer/oyster/examples/standalone/worker.ts .
+cp node_modules/@fungi.computer/oyster/examples/standalone/wrangler.jsonc .
+```
+
+Expected output: pnpm lists the added package after each `add`, and `ls` now
+shows `node_modules`, `package.json`, `worker.ts` and `wrangler.jsonc`.
+
+Every later command runs from this `my-oyster` directory unless the step says
+otherwise.
+
+If it fails:
+
+- `ERR_PNPM_IGNORED_BUILDS` naming packages such as `esbuild`, `workerd` or
+  `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.
+
+## 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:
+
+```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
+```
+
+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`.
+
+Keep it running. Open a second terminal in `my-oyster`, set the same two
+variables there, and check that Oyster answers:
+
+```sh
+export OYSTER_OWNER_KEY=$(cat .oyster-owner-key)
+export OYSTER_URL=http://127.0.0.1:8787
+curl -s -o /dev/null -w '%{http_code}\n' $OYSTER_URL/login
+curl -s -o /dev/null -w '%{http_code}\n' $OYSTER_URL/api/installations
+curl -s -H "Authorization: Bearer $OYSTER_OWNER_KEY" $OYSTER_URL/api/installations
+```
+
+Expected output: `200`, then `401` (no key), then `[]` (no Apps installed yet).
+
+If it fails:
+
+- `Address already in use`: another process holds port 8787. Pick another port
+  and use it in both `--port` and `OYSTER_URL`.
+- `curl` prints `000`: the server is not ready yet. Wait for the `Ready on`
+  line.
+- `401` with the key: the two terminals hold different keys. Set
+  `OYSTER_OWNER_KEY` from `.oyster-owner-key` in both.
+- An agent runtime that cannot keep a process in the foreground starts the same
+  command in the background with its output in a log, then waits until the
+  `/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 \
+    > oyster-dev.log 2>&1 &
+  ```
+
+To stop the server, press Ctrl-C in its terminal. A background server runs as
+several processes (`npm exec`, `wrangler.js` and `workerd`); stop them all by
+ending `wrangler.js`, then check that `/login` prints `000`:
+
+```sh
+pkill -f 'wrangler[.]js dev .*--port 8787'
+```
+
+## 4. Add an App
+
+An App is a git repository with a `package.json` that declares it under
+`fungi.app`. Make the smallest one, a single committed HTML page:
+
+```sh
+mkdir -p hello-app/bundle
+cat > hello-app/package.json <<'EOF'
+{
+  "name": "hello-app",
+  "private": true,
+  "fungi": { "app": { "displayName": "Hello", "capabilities": [] } }
+}
+EOF
+cat > hello-app/bundle/index.html <<'EOF'
+<!doctype html>
+<title>Hello</title>
+<h1>Hello from my first Oyster App</h1>
+EOF
+git -C hello-app init -q
+git -C hello-app add .
+git -C hello-app -c user.name=Oyster -c user.email=oyster@example.invalid \
+  commit -qm "Hello App"
+```
+
+Then pack that commit into a Release and install it as installation `hello` with
+`@fungi.computer/oyster/pack`:
+
+```sh
+cat > install-hello.mjs <<'EOF'
+import { execFileSync } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import { installRelease, packRelease } from "@fungi.computer/oyster/pack";
+
+const source = resolve("hello-app");
+const commit = execFileSync("git", ["-C", source, "rev-parse", "HEAD"], {
+  encoding: "utf8",
+}).trim();
+const out = await mkdtemp(join(tmpdir(), "oyster-hello-"));
+try {
+  await packRelease({
+    appId: "app_hello",
+    sourceDirectory: source,
+    sourceRevision: `git:${commit}`,
+    recipe: {
+      kind: "bundled-html",
+      entry: "bundle/index.html",
+      assets: {
+        maxManifestBytes: 65_536,
+        maxObjects: 16,
+        maxObjectBytes: 1_048_576,
+        maxTotalBytes: 4_194_304,
+      },
+      assetBase: "./",
+      backend: null,
+      maxOutputBytes: 4_194_304,
+    },
+    outDirectory: join(out, "release"),
+  });
+  const response = await installRelease({
+    directory: join(out, "release"),
+    url: process.env.OYSTER_URL,
+    key: process.env.OYSTER_OWNER_KEY,
+    installationId: "hello",
+  });
+  console.log(`installed hello: ${response.status} ${await response.text()}`);
+} finally {
+  await rm(out, { recursive: true, force: true });
+}
+EOF
+node install-hello.mjs
+curl -s -o /dev/null -w '%{http_code}\n' \
+  -H "Authorization: Bearer $OYSTER_OWNER_KEY" $OYSTER_URL/apps/hello/
+```
+
+Expected output: one line starting
+`installed hello: 201 {"installationId":"hello",` and containing
+`"status":"enabled"`, then `200`. Running `node install-hello.mjs` again prints
+`installed hello: 200`: the installation already exists, and Oyster switches it
+to the Release just packed.
+
+A person can open `$OYSTER_URL/login`, sign in with the owner key, and open
+Hello from the installation list at `$OYSTER_URL/`.
+
+If it fails:
+
+- `installed hello: 401`: `OYSTER_OWNER_KEY` in this terminal differs from the
+  server's. Set it from `.oyster-owner-key`.
+- `fetch failed` or `ECONNREFUSED`: the server from step 3 is not running.
+- The build reads committed files only. To install an edit, commit it in
+  `hello-app` and run `node install-hello.mjs` again; Oyster switches the
+  installation to the new Release and keeps its data.
+
+An App with a backend, typed methods and its own SQLite adds
+`fungi.backendDefinition` and a `backend` entry to its recipe. The
+[Notes example App](https://github.com/fungi-computer/oyster/tree/main/examples/notes-app)
+is one, and the Oyster README's "Pack an App" and "Build App Releases" sections
+describe the recipe.
+
+## 5. Connect over MCP
+
+`/mcp` serves every installed App to MCP clients through one `execute` tool, in
+which each App's methods are `env.<APP>`. The owner key signs in. For Claude
+Code:
+
+```sh
+claude mcp add --transport http oyster "$OYSTER_URL/mcp" \
+  --header "Authorization: Bearer $OYSTER_OWNER_KEY"
+```
+
+To check `/mcp` without an MCP client, open a session and list its tools:
+
+```sh
+MCP=(-H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream')
+SESSION=$(curl -s "${MCP[@]}" -D - -o /dev/null \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
+  $OYSTER_URL/mcp | grep -i '^mcp-session-id' | cut -d' ' -f2 | tr -d '\r')
+curl -s "${MCP[@]}" -H "mcp-session-id: $SESSION" -H 'mcp-protocol-version: 2025-11-25' \
+  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' $OYSTER_URL/mcp
+curl -s "${MCP[@]}" -H "mcp-session-id: $SESSION" -H 'mcp-protocol-version: 2025-11-25' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' $OYSTER_URL/mcp
+```
+
+Expected output: the last command prints an `event: message` block whose `data:`
+line contains `"name":"execute"`.
+
+If it fails:
+
+- `SESSION` is empty: the `initialize` call was refused. Check the key as in
+  step 3.
+- Named keys for each agent (`POST /api/keys`) come with the Git worker in
+  step 6. The plain standalone Worker answers `404` there.
+
+## 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:
+
+```sh
+curl -s -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" \
+  -H 'content-type: application/json' \
+  -d '{"name":"morel","grants":[{"capability":"apps.use","targets":{"kind":"all"}}]}' \
+  $OYSTER_URL/api/keys
+```
+
+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.
+
+`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:
+
+```sh
+npx wrangler login
+npx wrangler r2 bucket create oyster-releases
+export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
+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.
+
+To keep `OYSTER_ORIGIN` across later deploys, set `vars.OYSTER_ORIGIN` in
+`wrangler.jsonc`; every deploy replaces the Worker's variables.
+
+If it fails:
+
+- `R2 bucket … already exists`: use that bucket, or pick a new name and put it
+  in `wrangler.jsonc`.
+- 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.
+
+## 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 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/git/worker.ts

@@ -0,0 +1,39 @@
+// Add Git to an Oyster Worker. `host.git` is the whole seam: `createOyster`
+// mounts the git door at `/git/<installation>/<repo>.git`, and every clone,
+// fetch and push passes host authentication, live installation admission and
+// the App's own push policy before Artifacts sees a byte.
+//
+// One root composes every tenant host. HTTP, MCP and background wakes all reach
+// it through `root.hostFor`, so they share one auth, one workspace and one
+// capability set.
+import type { TenantScope } from "@fungi.computer/oyster/tenant";
+import {
+  createOysterGitMcpOwner,
+  createOysterGitWorker,
+  OysterGitInstance,
+  oysterGitRoot,
+  ownerOrKeyTenancy,
+  type OysterGitWorkerEnv,
+} from "@fungi.computer/oyster/workers-git";
+
+export { OysterRegistry } from "@fungi.computer/oyster/workers";
+// The one binding entrypoint, whose table also hands Apps `env.GIT` and `env.EVENTS`.
+export {
+  OysterBinding,
+  OysterKeys,
+  OysterWebhooks,
+} from "@fungi.computer/oyster/workers-git";
+
+// The owner key, or a named key minted at POST /api/keys, signs `git` in.
+const root = oysterGitRoot<OysterGitWorkerEnv>({ tenancy: ownerOrKeyTenancy });
+
+export class OysterMcp extends createOysterGitMcpOwner(root) {}
+
+/** Instances that hand Apps `env.GIT` and `env.EVENTS`; wakes use the root's host. */
+export class OysterInstance extends OysterGitInstance {
+  protected hostFor(scope: TenantScope) {
+    return root.hostFor(this.env, scope);
+  }
+}
+
+export default createOysterGitWorker(root);

package/examples/git/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+  "$schema": "../../../../node_modules/wrangler/config-schema.json",
+  "name": "oyster-git",
+  "main": "worker.ts",
+  "compatibility_date": "2026-09-04",
+  "compatibility_flags": ["nodejs_compat"],
+  "vars": { "OYSTER_ORIGIN": "https://oyster.example" },
+  "worker_loaders": [{ "binding": "LOADER" }],
+  "r2_buckets": [{ "binding": "RELEASES", "bucket_name": "oyster-releases" }],
+  "artifacts": [{ "binding": "ARTIFACTS", "namespace": "oyster" }],
+  "durable_objects": {
+    "bindings": [
+      { "name": "MCP", "class_name": "OysterMcp" },
+      { "name": "REGISTRY", "class_name": "OysterRegistry" },
+      { "name": "INSTANCES", "class_name": "OysterInstance" },
+      { "name": "KEYS", "class_name": "OysterKeys" },
+      { "name": "WEBHOOKS", "class_name": "OysterWebhooks" },
+    ],
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": [
+        "OysterMcp",
+        "OysterRegistry",
+        "OysterInstance",
+        "OysterKeys",
+        "OysterWebhooks",
+      ],
+    },
+  ],
+}

package/examples/standalone/worker.ts

@@ -0,0 +1,14 @@
+// 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();

package/examples/standalone/wrangler.jsonc

@@ -0,0 +1,21 @@
+{
+  "$schema": "../../../../node_modules/wrangler/config-schema.json",
+  "name": "oyster",
+  "main": "worker.ts",
+  "compatibility_date": "2026-09-04",
+  "compatibility_flags": ["nodejs_compat"],
+  "vars": { "OYSTER_ORIGIN": "https://oyster.example" },
+  "worker_loaders": [{ "binding": "LOADER" }],
+  "r2_buckets": [{ "binding": "RELEASES", "bucket_name": "oyster-releases" }],
+  "durable_objects": {
+    "bindings": [
+      { "name": "MCP", "class_name": "OysterMcp" },
+      { "name": "REGISTRY", "class_name": "OysterRegistry" },
+      { "name": "INSTANCES", "class_name": "OysterInstance" },
+    ],
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["OysterRegistry", "OysterInstance"] },
+    { "tag": "mcp-session-owner-v1", "new_sqlite_classes": ["OysterMcp"] },
+  ],
+}