@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/docs/api/README.md

@@ -0,0 +1,82 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/oyster**
+
+---
+
+# Oyster API overview
+
+| Import                                        | Export                                                                                             | Purpose                                                                                                                                 |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `@fungi.computer/oyster`                      | `createAppInstance`                                                                                | Run one App Instance's lifecycle and admission over host-supplied ports.                                                                |
+| `@fungi.computer/oyster`                      | `InstancePorts`                                                                                    | The storage, artifact resolution, abort, purge and connection ports a host supplies.                                                    |
+| `@fungi.computer/oyster`                      | `selectionSchema`                                                                                  | Decode the owner-issued selection that authorizes a request.                                                                            |
+| `@fungi.computer/oyster`                      | `ownerStateSchema`                                                                                 | Decode a complete owner state: `enabled`, `disabled` or `deleted`.                                                                      |
+| `@fungi.computer/oyster`                      | `AppInstanceError`                                                                                 | Typed rejection with a stable `code` from `appInstanceErrorCodeSchema`.                                                                 |
+| `@fungi.computer/oyster`                      | `instanceIds`                                                                                      | Mint and recognize App Instance IDs.                                                                                                    |
+| `@fungi.computer/oyster/invocation`           | `createInvocationGate`, `invocationFacts`, `InvocationFrame`                                       | Run each request in one frame of host-admitted caller facts, with its deadline and abort signal.                                        |
+| `@fungi.computer/oyster/cloudflare`           | `createCloudflareAppInstance`                                                                      | Run an Instance in a SQLite Durable Object with a Worker Loader facet (workerd or celld).                                               |
+| `@fungi.computer/oyster/apps`                 | `Installation`, `applyInstallationCommand`, `admits`, `approvedBindingGrants`                      | Pure installation approvals and admission; host-owned commits and tenant freshness.                                                     |
+| `@fungi.computer/oyster/host`                 | `createOyster`                                                                                     | The Oyster App server: a Hono app over host adapters for sign-in, Releases, installations and Instances.                                |
+| `@fungi.computer/oyster/auth`                 | `ownerKeyAuth`, `ownerOrKeyAuth`                                                                   | Owner-key sign-in (a Bearer key or the login cookie, compared in constant time) and named agent keys as Team-key principals.            |
+| `@fungi.computer/oyster/tenant`               | `TenantScope`, `tenantScope`, `singleTenant`, `OysterTenancy`                                      | Host-resolved tenant identity and the scope that prefixes registry, key and repository names.                                           |
+| `@fungi.computer/oyster/workers`              | `createOysterWorker`                                                                               | A standalone single-owner Oyster on Workers or celld: R2 Releases, a registry and one Durable Object per Instance.                      |
+| `@fungi.computer/oyster/pack`                 | `packRelease`, `installRelease`, `installFromSource`, `publishSource`                              | Build a committed App through the canonical recipe compiler and install its Release on an Oyster over HTTP.                             |
+| `@fungi.computer/oyster/build`                | `createAppCandidatePreparer`, `createLocalBuildExecutor`                                           | Node-only source capture, pinned compilation and local artifact writing.                                                                |
+| `@fungi.computer/oyster/build-contract`       | Recipe schemas and candidate orchestration                                                         | The Worker-safe half of `./build`, without the executor.                                                                                |
+| `@fungi.computer/oyster/app-storage`          | `AppStorageBinding`                                                                                | `env.APP_STORAGE` for methods and lifecycle handlers: lifecycle writes go to the team layer and reach `appStorage.watch`.               |
+| `@fungi.computer/oyster/app-storage`          | `createAppStorage`, `appStorageSchemaStatements`                                                   | SQLite owner for declared keys, live member/lifecycle admission, revision checks and watch invalidations.                               |
+| `@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.                    |
+| `@fungi.computer/oyster/agents`               | `OysterAgents`, `agentCapabilities`, `agentApprovalRoutes`                                         | The host's Agent slot, its App capabilities and the owner-only approval routes.                                                         |
+| `@fungi.computer/oyster/computer`             | `computerSlots`, `ComputerTerminalHost`                                                            | Computer ports, processes and terminal routes supplied by the host; execution stays in the Computer runtime.                            |
+| `@fungi.computer/oyster/media`                | `mediaSlot`                                                                                        | The media capability slot a host fills; Oyster owns routing, never generation.                                                          |
+| `@fungi.computer/oyster/files`                | `FileSource`                                                                                       | Files Apps reach through Agar's `computer.*` file contracts, with a compare-and-swap replace.                                           |
+| `@fungi.computer/oyster/root-data`            | `createOysterRootData`                                                                             | Installation and verified Release owners as shared workbench metadata for a standalone root.                                            |
+| `@fungi.computer/oyster/page`                 | `mountOysterPage`, `connectOysterApp`, `readOysterPageConfig`                                      | Mount one installed App's sandboxed frame and connect its admitted slots.                                                               |
+| `@fungi.computer/oyster/shell`                | Shell client exports                                                                               | Build a browser or terminal host from the focused entries below.                                                                        |
+| `@fungi.computer/oyster/shell/workbench`      | Workbench types and schemas                                                                        | Describe child mounts, geometry and Gill arrangers without platform policy.                                                             |
+| `@fungi.computer/oyster/shell/command-host`   | `createAppSurfaceCommandHost`                                                                      | Admit declared commands and own focus and contribution lifetimes.                                                                       |
+| `@fungi.computer/oyster/shell/keys`           | `installShellKeys`, `parseChord`                                                                   | Match chords and optionally install DOM key dispatch.                                                                                   |
+| `@fungi.computer/oyster/shell/commands`       | `shellCommands`                                                                                    | Declare shell commands over embedding-host callbacks.                                                                                   |
+| `@fungi.computer/oyster/shell/window-manager` | `createWindowManager`                                                                              | Own window generations, visibility and disposal over a mount adapter.                                                                   |
+| `@fungi.computer/oyster/shell/app-directory`  | Directory schemas                                                                                  | Decode host-neutral addresses and App metadata before permissions.                                                                      |
+| `@fungi.computer/oyster/shell/shell-module`   | `importShellModule`, `ShellMountInput`, `MountShell`                                               | Load the picked shell Release's `mountShell` module from the host's own origin and hand it the workbench, storage and methods.          |
+| `@fungi.computer/oyster/git`                  | `EventSink`, `createGitDoor`, `signStandardWebhook`                                                | The EVENTS binding contract, the git smart-HTTP door and Standard Webhooks signing. `GitBinding` comes from `@fungi.computer/agar/git`. |
+| `@fungi.computer/oyster/workers-git`          | `oysterGitRoot`, `createOysterGitWorker`, `ownerOrKeyTenancy`, `oysterWorkerGit`, `gitAdminRoutes` | One Git root whose `hostFor` serves HTTP, MCP and Instances, or `host.git` and key/webhook routes for your own host.                    |
+
+The host owns admission: it decides who may apply owner state and which
+selection a request carries. Oyster owns what happens to one Instance once the
+host has that authority: owner-state replay and conflict rules, Release
+resolution, state-schema compatibility, fencing on disable and purge on delete.
+The generated module pages below include every port and record type.
+
+## Guest execution policy
+
+`createOyster({ ...host, guestLimits: { cpuMs: 250, subRequests: 10 } })`
+configures per-invocation budgets. Omitted fields default to 1,000 milliseconds
+of CPU and 50 subrequests. CPU must be a positive integer; subrequests may be
+zero to forbid them. Both must fit a signed 32-bit integer. Invalid
+configuration fails before accepting requests.
+
+The host's `InstanceDirectory.get(id, limits)` adapter must carry those budgets
+to guest execution.
+`createOysterWorker({ guestLimits: { cpuMs: 250, subRequests: 10 } })` supplies
+this wiring for the standalone Worker. Direct `createCloudflareAppInstance`
+callers can supply the same policy in its final argument; otherwise the same
+defaults apply. The loader code carries limits for both HTTP and method calls,
+without granting ambient outbound access. Changing an Instance's budgets
+invalidates its running facet while preserving its SQLite state. Runtime
+enforcement uses the
+[Worker Loader resource limits](https://developers.cloudflare.com/dynamic-workers/usage/limits/).
+
+Guest HTTP responses retain only content metadata: content type, language,
+encoding, length, disposition and range, accepted ranges, ETag and
+last-modified. Oyster supplies `Cache-Control: no-store`,
+`X-Content-Type-Options: nosniff`, and a sandboxed, deny-by-default Content
+Security Policy. Cookies, redirects, origin policy, service-worker scope and
+unrecognized headers cannot come from guests. Host-issued login responses retain
+their cookies.
+
+The Node-only `@fungi.computer/oyster/build` entry owns captured App
+compilation; `@fungi.computer/oyster/build-contract` provides its Worker-safe
+recipe and candidate orchestration without loading the executor.

package/docs/api/agents.md

@@ -0,0 +1,332 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / agents
+
+# agents
+
+## Type Aliases
+
+### OysterAgent
+
+```ts
+type OysterAgent = Readonly<{
+  agentId: string;
+  name: string;
+  sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
+}>;
+```
+
+One agent as Apps see it, in Agar's `appAgentSchema` shape.
+
+---
+
+### OysterSessionRow
+
+```ts
+type OysterSessionRow =
+  | Omit<
+      Extract<
+        MemberInboxSession,
+        {
+          title: string;
+        }
+      >,
+      "agentId" | "visitedAt"
+    >
+  | Omit<
+      Extract<
+        MemberInboxSession,
+        {
+          state: "unavailable";
+        }
+      >,
+      "agentId"
+    >;
+```
+
+An Agent owner's Session facts before the member identity and visit are added.
+
+---
+
+### OysterInboxItem
+
+```ts
+type OysterInboxItem = MemberInboxItem;
+```
+
+Both hosts expose the same Inbox item vocabulary.
+
+---
+
+### OysterInbox
+
+```ts
+type OysterInbox = Readonly<{
+  items: readonly OysterInboxItem[];
+  revision: number;
+}>;
+```
+
+The whole inbox at one revision; the revision only grows.
+
+---
+
+### AgentPolicyActor
+
+```ts
+type AgentPolicyActor =
+  | "owner-direct"
+  | Readonly<{
+      installationId: string;
+    }>;
+```
+
+Host-attested source of a policy request; request headers are not this fact.
+
+---
+
+### PendingAgentPolicy
+
+```ts
+type PendingAgentPolicy = Readonly<{
+  status: "pending";
+  revision: string;
+}>;
+```
+
+An App's requested tools await the owner's direct approval.
+
+---
+
+### AgentMcpServer
+
+```ts
+type AgentMcpServer = Readonly<{
+  serverId: string;
+  name: string;
+  url: string;
+  hasBearer: boolean;
+}>;
+```
+
+One remote MCP server connected to an Agent; its bearer token is never returned.
+
+---
+
+### AgentMcpServerInput
+
+```ts
+type AgentMcpServerInput = typeof agentMcpServerInputSchema.Type;
+```
+
+An owner's request to connect one remote MCP server to an Agent.
+
+---
+
+### AgentMcpServerRefusal
+
+```ts
+type AgentMcpServerRefusal = Readonly<{
+  error: "not_found" | "duplicate_name" | "limit";
+}>;
+```
+
+Why connecting an MCP server was refused.
+
+---
+
+### AgentToolPolicyStatus
+
+```ts
+type AgentToolPolicyStatus = Readonly<{
+  status: "pending" | "approved";
+  revision: string;
+}>;
+```
+
+This Agent's App-tool policy, in the shape Apps read it.
+
+---
+
+### OysterAgents
+
+```ts
+type OysterAgents = Readonly<{
+  list: Promise<
+    readonly Readonly<{
+      agentId: string;
+      name: string;
+      sessionOperations: readonly (
+        "agent.read" | "agent.send" | "agent.manage"
+      )[];
+    }>[]
+  >;
+  create: Promise<
+    Readonly<{
+      agentId: string;
+      name: string;
+      sessionOperations: readonly (
+        "agent.read" | "agent.send" | "agent.manage"
+      )[];
+    }>
+  >;
+  rename: Promise<
+    | Readonly<{
+        agentId: string;
+        name: string;
+        sessionOperations: readonly (
+          "agent.read" | "agent.send" | "agent.manage"
+        )[];
+      }>
+    | Readonly<{
+        error: "not_found" | "name_taken" | "not_granted";
+      }>
+  >;
+  policyStatus: Promise<Readonly<{
+    status: "pending" | "approved";
+    revision: string;
+  }> | null>;
+  appToolPolicy: Promise<{
+    level: "read" | "write";
+    revision: string;
+    grantedBy: string;
+  } | null>;
+  policyRevision: Promise<string | null>;
+  approveAppToolPolicy: Promise<
+    | {
+        level: "read" | "write";
+        revision: string;
+        grantedBy: string;
+      }
+    | Readonly<{
+        status: "pending";
+        revision: string;
+      }>
+    | Readonly<{
+        error: "not_found" | "revision_conflict" | "not_granted";
+      }>
+  >;
+  mcpServers: Promise<
+    | readonly Readonly<{
+        serverId: string;
+        name: string;
+        url: string;
+        hasBearer: boolean;
+      }>[]
+    | null
+  >;
+  addMcpServer: Promise<
+    | Readonly<{
+        serverId: string;
+        name: string;
+        url: string;
+        hasBearer: boolean;
+      }>
+    | Readonly<{
+        error: "not_found" | "duplicate_name" | "limit";
+      }>
+  >;
+  removeMcpServer: Promise<boolean>;
+  fetch: Promise<Response | null>;
+  inbox: Promise<
+    Readonly<{
+      items: readonly OysterInboxItem[];
+      revision: number;
+    }>
+  >;
+  revision: Promise<number>;
+  visit: Promise<boolean>;
+}>;
+```
+
+Where an Oyster's agents live and run.
+
+## Variables
+
+### maxAgentMcpServers
+
+```ts
+const maxAgentMcpServers: 16 = 16;
+```
+
+At most this many MCP servers per Agent.
+
+---
+
+### agentMcpServerInputSchema
+
+```ts
+const agentMcpServerInputSchema: Struct<{
+  name: String;
+  url: String;
+  bearer: NullOr<String>;
+}>;
+```
+
+Owner input for one MCP server: a guest identifier, an `https:` endpoint and an
+optional bearer.
+
+## Functions
+
+### agentCapabilities()
+
+```ts
+function agentCapabilities(agents): readonly Readonly<object & object>[];
+```
+
+Agent adapters admitted against each App's declared capabilities.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `agents`  | [`OysterAgents`](#oysteragents) |
+
+#### Returns
+
+readonly `Readonly`\<`object` & `object`\>[]
+
+---
+
+### agentApprovalRoutes()
+
+```ts
+function agentApprovalRoutes(agents): Hono<OysterEnv>;
+```
+
+Host-owned direct approval under the admitted owner; never an App capability.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `agents`  | [`OysterAgents`](#oysteragents) |
+
+#### Returns
+
+`Hono`\<[`OysterEnv`](host.md#oysterenv)\>
+
+---
+
+### agentMcpServerRoutes()
+
+```ts
+function agentMcpServerRoutes(agents): Hono<OysterEnv>;
+```
+
+Host-owned Agent MCP server custody for the owner directly; never an App
+capability. Bearer tokens go in and never come back out.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `agents`  | [`OysterAgents`](#oysteragents) |
+
+#### Returns
+
+`Hono`\<[`OysterEnv`](host.md#oysterenv)\>

package/docs/api/app-storage.md

@@ -0,0 +1,209 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / app-storage
+
+# app-storage
+
+## Type Aliases
+
+### AppStorageBinding
+
+```ts
+type AppStorageBinding = Readonly<{
+  read: Promise<
+    AppStorageResult<{
+      value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+      source: Schema.Literals<readonly ["member", "team", "none"]>;
+      team: Schema.NullOr<
+        Schema.Struct<{
+          value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+          revision: Schema.Int;
+        }>
+      >;
+      member: Schema.NullOr<
+        Schema.Struct<{
+          value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+          revision: Schema.Int;
+        }>
+      >;
+      canWriteTeam: Schema.Boolean;
+    }>
+  >;
+  write: Promise<
+    AppStorageResult<{
+      revision: number;
+    }>
+  >;
+  reset: Promise<
+    AppStorageResult<{
+      revision: number;
+    }>
+  >;
+}>;
+```
+
+The App storage handle in `env.APP_STORAGE`.
+
+---
+
+### AppStorageWriter
+
+```ts
+type AppStorageWriter =
+  | Readonly<{
+      kind: "member";
+      memberId: string;
+      isOwner: boolean;
+    }>
+  | Readonly<{
+      kind: "lifecycle";
+      handler: string;
+    }>;
+```
+
+Trusted backend writer: owners may also edit the Team layer; lifecycle has no
+member.
+
+---
+
+### AppStorageAdmission
+
+```ts
+type AppStorageAdmission = Readonly<{
+  address: string;
+  appId: string;
+  memberId: string;
+  membershipVersion: number;
+  isOwner: boolean;
+  keys: readonly AppStorageKey[];
+  assertCurrent: () => void;
+}>;
+```
+
+Trusted live App admission, never supplied by the App or an HTTP body.
+
+---
+
+### AppStorageInstallationAdmission
+
+```ts
+type AppStorageInstallationAdmission = Pick<
+  AppStorageAdmission,
+  "address" | "appId" | "keys" | "assertCurrent"
+>;
+```
+
+Trusted installation lifecycle admission, with no member identity or private
+layer.
+
+## Variables
+
+### appStorageSchemaStatements
+
+```ts
+const appStorageSchemaStatements: readonly [
+  "CREATE TABLE IF NOT EXISTS hub_app_storage (\n    address TEXT NOT NULL, app_id TEXT NOT NULL, key TEXT NOT NULL,\n    scope TEXT NOT NULL CHECK(scope IN ('team','member')), member_id TEXT NOT NULL, membership_version INTEGER NOT NULL,\n    value TEXT NOT NULL, revision INTEGER NOT NULL, bytes INTEGER NOT NULL,\n    PRIMARY KEY(address,app_id,key,scope,member_id,membership_version),\n    CHECK((scope='team' AND member_id='' AND membership_version=0) OR (scope='member' AND member_id<>'' AND membership_version>0))) STRICT",
+  "CREATE INDEX IF NOT EXISTS hub_app_storage_member ON hub_app_storage(member_id) WHERE scope='member'",
+  "CREATE TABLE IF NOT EXISTS hub_app_storage_clock (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL) STRICT",
+  "INSERT OR IGNORE INTO hub_app_storage_clock VALUES(1,0)",
+  "CREATE TABLE IF NOT EXISTS hub_app_storage_writes (address TEXT NOT NULL, member_id TEXT NOT NULL, membership_version INTEGER NOT NULL, started_at INTEGER NOT NULL, count INTEGER NOT NULL, PRIMARY KEY(address,member_id,membership_version)) STRICT",
+];
+```
+
+SQLite tables, indexes and initial revision state used by the App storage owner.
+
+## Functions
+
+### appStorageWritable()
+
+```ts
+function appStorageWritable(writer, scope): boolean;
+```
+
+Whether `writer` may mutate `scope`; anything else is `owner_required`.
+
+#### Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| `writer`  | [`AppStorageWriter`](#appstoragewriter) |
+| `scope`   | `"team"` \| `"member"`                  |
+
+#### Returns
+
+`boolean`
+
+---
+
+### purgeAppStorageInCommit()
+
+```ts
+function purgeAppStorageInCommit(sql, address): void;
+```
+
+Called only inside the installation owner's delete transaction.
+
+#### Parameters
+
+| Parameter | Type                                                                                |
+| --------- | ----------------------------------------------------------------------------------- |
+| `sql`     | `Readonly`\<\{ `exec`: (`statement`, ...`bindings`) => `WatchdogSqliteCursor`; \}\> |
+| `address` | `string`                                                                            |
+
+#### Returns
+
+`void`
+
+---
+
+### purgeAppMemberStorageInCommit()
+
+```ts
+function purgeAppMemberStorageInCommit(sql, memberId, throughVersion): void;
+```
+
+Called only inside the membership owner's removal transaction.
+
+#### Parameters
+
+| Parameter        | Type                                                                                |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| `sql`            | `Readonly`\<\{ `exec`: (`statement`, ...`bindings`) => `WatchdogSqliteCursor`; \}\> |
+| `memberId`       | `string`                                                                            |
+| `throughVersion` | `number`                                                                            |
+
+#### Returns
+
+`void`
+
+---
+
+### createAppStorage()
+
+```ts
+function createAppStorage(options): object;
+```
+
+One SQLite owner for scoped App values; its views bind the admitted member.
+
+#### Parameters
+
+| Parameter        | Type                                                                                                                                                                             | Description                                                                 |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `options`        | \{ `sql`: `Readonly`\<\{ `exec`: (`statement`, ...`bindings`) => `WatchdogSqliteCursor`; \}\>; `now?`: () => `number`; `commit`: \<`A`\>(`body`) => `Effect`\<`A`, `Error`\>; \} | -                                                                           |
+| `options.sql`    | `Readonly`\<\{ `exec`: (`statement`, ...`bindings`) => `WatchdogSqliteCursor`; \}\>                                                                                              | The SQLite connection shared with installation and membership changes.      |
+| `options.now?`   | () => `number`                                                                                                                                                                   | Millisecond clock used for the existing per-principal write-rate limit.     |
+| `options.commit` | \<`A`\>(`body`) => `Effect`\<`A`, `Error`\>                                                                                                                                      | Commit the supplied mutation atomically before publishing its invalidation. |
+
+#### Returns
+
+| Name                  | Type                                     | Description                                                                                      |
+| --------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `purgeInstallation()` | (`address`) => `void`                    | Remove an installation's values and write counters inside its delete transaction.                |
+| `purgeMember()`       | (`memberId`, `throughVersion`) => `void` | Remove a member's private values and counters through the revoked membership version.            |
+| `openInstallation()`  | (`authorize`) => `object`                | Bind a lifecycle view to fresh installation admission; only declared team layers are accessible. |
+| `open()`              | (`authorize`) => `object`                | Bind a member view to live admission, declared keys and the current membership version.          |