@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/docs/api/keys.md

@@ -0,0 +1,175 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / keys
+
+# keys
+
+## Type Aliases
+
+### OysterKeyCapability
+
+```ts
+type OysterKeyCapability = "apps.read" | "apps.use" | "computer.use";
+```
+
+Every capability an Oyster key may carry.
+
+---
+
+### OysterKeyRecord
+
+```ts
+type OysterKeyRecord = KeyRecord<OysterKeyCapability>;
+```
+
+One key's durable record, in the shape a host's own App reads.
+
+---
+
+### OysterKeyPrincipal
+
+```ts
+type OysterKeyPrincipal = KeyPrincipal<OysterKeyCapability>;
+```
+
+One key's live, authenticated principal.
+
+---
+
+### OysterKeyScope
+
+```ts
+type OysterKeyScope = Scope<OysterKeyCapability>;
+```
+
+One key's authority, as `defineGrants` canonicalizes it.
+
+---
+
+### OysterKeyStore
+
+```ts
+type OysterKeyStore = KeyStore<OysterKeyCapability>;
+```
+
+The Ear Tag store's own interface, closed over Oyster's capability vocabulary.
+
+---
+
+### LiveOysterKey
+
+```ts
+type LiveOysterKey = Readonly<{
+  keyId: string;
+  owner: string;
+  grantVersion: number;
+  grants: readonly Grant<OysterKeyCapability>[];
+}>;
+```
+
+The minimal live facts `OysterHost`'s `keys.live` port returns: enough to gate
+one call, never the key's name or timestamps. `null` for an unknown, revoked,
+expired or suspended key -- the same closed set `keyAppAccess` and
+`keyAllowsComputerUse` already treat as no authority.
+
+## Variables
+
+### oysterKeyVocabulary
+
+```ts
+const oysterKeyVocabulary: GrantVocabulary<OysterKeyCapability>;
+```
+
+`apps.use` also reaches `apps.read` (one level, per `defineGrants`'s own
+`implies`): a key that may change an App's data may also read it. `computer.use`
+has no narrower capability under it; the Computer is on or off, host-wide.
+
+---
+
+### computerUseGrant
+
+```ts
+const computerUseGrant: Grant<OysterKeyCapability>;
+```
+
+The grant that turns on the Computer for a key, host-wide; there is no narrower
+target.
+
+## Functions
+
+### allInstallations()
+
+```ts
+function allInstallations(capability): Grant<OysterKeyCapability>;
+```
+
+A grant reaching every current and future installation for `capability`.
+
+#### Parameters
+
+| Parameter    | Type                          |
+| ------------ | ----------------------------- |
+| `capability` | `"apps.read"` \| `"apps.use"` |
+
+#### Returns
+
+`Grant`\<[`OysterKeyCapability`](#oysterkeycapability)\>
+
+---
+
+### keyAppAccess()
+
+```ts
+function keyAppAccess(
+  key,
+  installationId,
+): {
+  level: "read" | "write";
+  revision: string;
+  grantedBy: string;
+} | null;
+```
+
+One live key's access to one installation: `write` when its grants admit
+`apps.use` there, `read` when they admit `apps.read`, otherwise `null` --
+including for an installation added after the key was issued, unless the key
+holds "All Apps" (`targets: {kind: "all"}`). The same shape as an Agent's stored
+[AppToolPolicy](apps.md#apptoolpolicy); its caller adds `bindingName` (which
+varies by caller: the plain installation id for the gate, the uppercased binding
+name for MCP) to reach the full `AppToolAccess`.
+
+#### Parameters
+
+| Parameter        | Type                              |
+| ---------------- | --------------------------------- |
+| `key`            | [`LiveOysterKey`](#liveoysterkey) |
+| `installationId` | `string`                          |
+
+#### Returns
+
+\| \{ `level`: `"read"` \| `"write"`; `revision`: `string`; `grantedBy`:
+`string`; \} \| `null`
+
+---
+
+### keyAllowsComputerUse()
+
+```ts
+function keyAllowsComputerUse(key): boolean;
+```
+
+Whether a live key's own grants turn its Computer access on. Off by default.
+
+#### Parameters
+
+| Parameter | Type                              |
+| --------- | --------------------------------- |
+| `key`     | [`LiveOysterKey`](#liveoysterkey) |
+
+#### Returns
+
+`boolean`

package/docs/api/mcp.md

@@ -0,0 +1,301 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / mcp
+
+# mcp
+
+## Classes
+
+### AppMethodRefused
+
+Why an App method call from the MCP catalog was refused.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AppMethodRefused(code, detail?): AppMethodRefused;
+```
+
+`detail` is the App's own caller-facing refusal message, when it gave one.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `code`    | `string` |
+| `detail?` | `string` |
+
+###### Returns
+
+[`AppMethodRefused`](#appmethodrefused)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "AppMethodRefused" = "AppMethodRefused";
+```
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+##### code
+
+```ts
+readonly code: string;
+```
+
+## Type Aliases
+
+### OysterCallerAccess
+
+```ts
+type OysterCallerAccess =
+  | Readonly<{
+      kind: "agent";
+      policy: AppToolPolicy;
+    }>
+  | Readonly<{
+      kind: "key";
+      keyId: string;
+      byInstallation: ReadonlyMap<string, AppToolPolicy>;
+    }>
+  | null;
+```
+
+The App-tool access one caller's catalog capture used, re-checked at call time
+against a fresh read. An Agent's policy is one blanket level for every
+installation (`host.appToolPolicy`); a key's is its own grants, resolved per
+installation (`keyAppAccess`) -- an installation the key has no grant for is
+captured as absent, never merely refused, so it is never listed at all.
+
+---
+
+### ReleaseSurface
+
+```ts
+type ReleaseSurface = Readonly<{
+  release: VerifiedRelease;
+  api: NonNullable<VerifiedRelease["api"]>;
+  declaredOperations: DeclaredOperations;
+  toolSchemas: ReturnType<typeof appToolSchemas>;
+}>;
+```
+
+What one Release contributes to every MCP catalog: its verified build, its
+declared operations and its compiled tool schemas.
+
+---
+
+### AppSurfaceCache
+
+```ts
+type AppSurfaceCache = (release) => Promise<ReleaseSurface | null>;
+```
+
+Per-host memo of each installed Release's catalog surface. A Release's artifacts
+are immutable and content-addressed, so verifying the build, deriving its
+operations and compiling its tool schemas happens once per Release ID and
+artifact digest, not on every catalog capture: an MCP call captures the catalog
+several times (refresh, session acquire, the pre-call authority check), and
+redoing this for every installed App on each one exhausted a Durable Object's
+CPU and memory. Only Release-derived facts are cached; installation authority,
+caller access and tool-family listings are still read fresh on every capture. A
+failed build is not cached.
+
+#### Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `release` | [`Installation`](apps.md#installation)\[`"release"`\] |
+
+#### Returns
+
+`Promise`\<[`ReleaseSurface`](#releasesurface) \| `null`\>
+
+## Functions
+
+### appBindingName()
+
+```ts
+function appBindingName(installationId): string;
+```
+
+An installation ID as a guest binding name: `spawn-git` becomes `SPAWN_GIT`.
+
+#### Parameters
+
+| Parameter        | Type     |
+| ---------------- | -------- |
+| `installationId` | `string` |
+
+#### Returns
+
+`string`
+
+---
+
+### appSurfaceCache()
+
+```ts
+function appSurfaceCache(host): AppSurfaceCache;
+```
+
+Make one [AppSurfaceCache](#appsurfacecache) for a host whose artifact store and
+capabilities stay fixed.
+
+#### Parameters
+
+| Parameter | Type                                                                            |
+| --------- | ------------------------------------------------------------------------------- |
+| `host`    | `Pick`\<[`OysterHost`](host.md#oysterhost), `"artifacts"` \| `"capabilities"`\> |
+
+#### Returns
+
+[`AppSurfaceCache`](#appsurfacecache)
+
+---
+
+### oysterAppMethods()
+
+```ts
+function oysterAppMethods(
+  host,
+  principal,
+  access,
+  surfaces,
+  preloadedInstallations?,
+): Promise<
+  Readonly<{
+    id: string;
+    acquire: (context) => Promise<
+      Readonly<{
+        snapshot: CapabilitySourceSnapshot;
+        release: () => Promise<void>;
+      }>
+    >;
+  }> &
+    object
+>;
+```
+
+Capture installed App methods for MCP or agents as one principal-scoped source.
+Enabled installations become `env.<APP>` modules using the Instance call path; a
+dotted method such as `repos.list` is `env.<APP>.repos.list()`. Visitors see
+only public read methods; owners see every discoverable method. A key sees only
+the installations its own grants admit, each at the level (`read`/`write`) those
+grants give it; Mycelium itself refuses a write call up front when the module's
+own grant is `read` (`mycelium/src/access.ts`). Call again to capture changes to
+Releases, installation authority or the caller's own grants.
+
+#### Parameters
+
+| Parameter                 | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `host`                    | `Pick`\<[`OysterHost`](host.md#oysterhost), \| `"installations"` \| `"instances"` \| `"artifacts"` \| `"guestLimits"` \| `"backgroundOriginKey"` \| `"computerId"` \| `"capabilities"` \| `"appToolPolicy"` \| `"keys"`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `principal`               | [`OysterPrincipal`](host.md#oysterprincipal)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `access`                  | [`OysterCallerAccess`](#oystercalleraccess)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `surfaces`                | [`AppSurfaceCache`](#appsurfacecache)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `preloadedInstallations?` | readonly `Readonly`\<\{ `installationId`: `string`; `instanceId`: [`InstanceId`](index.md#instanceid) \| `null`; `appId`: `AppId`; `release`: \{ `releaseId`: `ReleaseId`; `appId`: `AppId`; `artifact`: \{ `artifactRef`: `ArtifactRef`; `artifactDigest`: `Sha256Digest`; `provenance`: \{ `sourceRevision`: `SourceRevision`; `sourceTreeDigest`: `Sha256Digest`; `buildRecipeDigest`: `Sha256Digest`; \}; \}; \}; `releasePin`: `"pinned"` \| `"floating"`; `authorityVersion`: `number`; `status`: `"enabled"` \| `"disabled"` \| `"deleted"`; `visibility`: `"private"` \| `"public"`; `declaredOperationsDigest`: `Sha256Digest`; `approvedGrants`: readonly `Readonly`\<\{ `capability`: \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `capabilityApproved`: `true`; `operations`: readonly `string`[]; `resources`: \| `"tenant-scope"` \| readonly `Readonly`\<\{ `kind`: ...; `id`: ...; \}\>[]; \}\>[]; `approval`: \| `Readonly`\<\{ `by`: \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \}; `at`: `number`; `authorityVersion`: `number`; \}\> \| `null`; `approvedAnonymousMethods`: readonly `Readonly`\<\{ `name`: `string`; `digest`: `Sha256Digest`; \}\>[]; `anonymousApproval`: \| `Readonly`\<\{ `by`: \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \}; `at`: `number`; `authorityVersion`: `number`; \}\> \| `null`; \}\>[] |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `id`: `string`; `acquire`: (`context`) =>
+`Promise`\<`Readonly`\<\{ `snapshot`: `CapabilitySourceSnapshot`; `release`: ()
+=> `Promise`\<`void`\>; \}\>\>; \}\> & `object`\>
+
+---
+
+### oysterComputerTools()
+
+```ts
+function oysterComputerTools(host, principal): Promise<
+  | Readonly<{
+  id: string;
+  acquire: (context) => Promise<Readonly<{
+     snapshot: CapabilitySourceSnapshot;
+     release: () => Promise<...>;
+  }>>;
+}> & object
+| null>;
+```
+
+Capture the host's fixed Computer for one caller as a Knapsack source. The host
+decides whether the caller holds Computer access; the Computer owner accepts
+every call. Null when the host has no Computer or the caller has no access.
+Grants name exactly the one captured module.
+
+#### Parameters
+
+| Parameter   | Type                                                                         |
+| ----------- | ---------------------------------------------------------------------------- |
+| `host`      | `Pick`\<[`OysterHost`](host.md#oysterhost), `"computerId"` \| `"computer"`\> |
+| `principal` | [`OysterPrincipal`](host.md#oysterprincipal)                                 |
+
+#### Returns
+
+`Promise`\< \| `Readonly`\<\{ `id`: `string`; `acquire`: (`context`) =>
+`Promise`\<`Readonly`\<\{ `snapshot`: `CapabilitySourceSnapshot`; `release`: ()
+=> `Promise`\<...\>; \}\>\>; \}\> & `object` \| `null`\>
+
+---
+
+### oysterMcpCatalogLoad()
+
+```ts
+function oysterMcpCatalogLoad(host): (principal) => Promise<Readonly<{
+  instructions: string;
+  sources: readonly Readonly<{
+     id: string;
+     acquire: (context) => Promise<Readonly<{
+        snapshot: ...;
+        release: ...;
+     }>>;
+  }>[];
+  grants: Grants;
+  approvedWrites?: readonly string[];
+}>>;
+```
+
+Load the current catalog for an authenticated owner or key: installed App
+methods, plus the host's Computer when the caller holds Computer access. A key
+sees exactly the installations and levels its own grants admit, and the Computer
+only with its own `computer.use` grant; each App retains its own caller checks
+regardless. The owner's stored write approval of an Agent's App tools is that
+principal's confirmation for App writes, so a headless client can write; the
+shared MCP server asks the client to approve every other write (an owner's own
+calls, the Computer). Each call still re-admits the key, rechecks that same
+stored approval, and passes the App's gate.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                      |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `host`    | `Pick`\<[`OysterHost`](host.md#oysterhost), \| `"installations"` \| `"instances"` \| `"artifacts"` \| `"guestLimits"` \| `"backgroundOriginKey"` \| `"computerId"` \| `"computer"` \| `"capabilities"` \| `"appToolPolicy"` \| `"keys"`\> |
+
+#### Returns
+
+(`principal`) => `Promise`\<`Readonly`\<\{ `instructions`: `string`; `sources`:
+readonly `Readonly`\<\{ `id`: `string`; `acquire`: (`context`) =>
+`Promise`\<`Readonly`\<\{ `snapshot`: ...; `release`: ...; \}\>\>; \}\>[];
+`grants`: `Grants`; `approvedWrites?`: readonly `string`[]; \}\>\>

package/docs/api/media.md

@@ -0,0 +1,40 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / media
+
+# media
+
+## Variables
+
+### mediaSlot
+
+```ts
+const mediaSlot: object;
+```
+
+Media slot supplied by the host; Oyster owns routing, never generation.
+
+#### Type Declaration
+
+| Name                                    | Type                 | Default value             |
+| --------------------------------------- | -------------------- | ------------------------- |
+| <a id="property-id"></a> `id`           | `"media.generation"` | `"media.generation"`      |
+| <a id="property-version"></a> `version` | `number`             | `mediaGeneration.version` |
+| <a id="property-base"></a> `base`       | `"/media/"`          | `"/media/"`               |
+| <a id="property-methods"></a> `methods` | `object`             | -                         |
+| `methods.describe`                      | `object`             | -                         |
+| `methods.describe.kind`                 | `"json"`             | `"json"`                  |
+| `methods.describe.method`               | `"GET"`              | `"GET"`                   |
+| `methods.describe.path`                 | `"describe"`         | `"describe"`              |
+| `methods.generate`                      | `object`             | -                         |
+| `methods.generate.kind`                 | `"json"`             | `"json"`                  |
+| `methods.generate.method`               | `"POST"`             | `"POST"`                  |
+| `methods.generate.path`                 | `"generate"`         | `"generate"`              |
+| `methods.cancelAttempt`                 | `object`             | -                         |
+| `methods.cancelAttempt.kind`            | `"json"`             | `"json"`                  |
+| `methods.cancelAttempt.method`          | `"POST"`             | `"POST"`                  |
+| `methods.cancelAttempt.path`            | `"cancel-attempt"`   | `"cancel-attempt"`        |

package/docs/api/modules.md

@@ -0,0 +1,50 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+# @fungi.computer/oyster
+
+## Modules
+
+| Module                                                    | Description |
+| --------------------------------------------------------- | ----------- |
+| [agents](agents.md)                                       | -           |
+| [app-storage](app-storage.md)                             | -           |
+| [apps](apps.md)                                           | -           |
+| [auth](auth.md)                                           | -           |
+| [build-contract](build-contract.md)                       | -           |
+| [build](build.md)                                         | -           |
+| [cloudflare](cloudflare.md)                               | -           |
+| [computer](computer.md)                                   | -           |
+| [files](files.md)                                         | -           |
+| [git](git.md)                                             | -           |
+| [host](host.md)                                           | -           |
+| [index](index.md)                                         | -           |
+| [invocation](invocation.md)                               | -           |
+| [keys](keys.md)                                           | -           |
+| [mcp](mcp.md)                                             | -           |
+| [media](media.md)                                         | -           |
+| [pack](pack.md)                                           | -           |
+| [page/mount](page/mount.md)                               | -           |
+| [root-data](root-data.md)                                 | -           |
+| [shell/app-directory](shell/app-directory.md)             | -           |
+| [shell/command-host](shell/command-host.md)               | -           |
+| [shell/commands](shell/commands.md)                       | -           |
+| [shell](shell.md)                                         | -           |
+| [shell/keys](shell/keys.md)                               | -           |
+| [shell/shell-module](shell/shell-module.md)               | -           |
+| [shell/window-manager](shell/window-manager.md)           | -           |
+| [shell/workbench-directory](shell/workbench-directory.md) | -           |
+| [shell/workbench](shell/workbench.md)                     | -           |
+| [tenancy/auth0](tenancy/auth0.md)                         | -           |
+| [tenancy/cloudflare](tenancy/cloudflare.md)               | -           |
+| [tenancy/cold-directory](tenancy/cold-directory.md)       | -           |
+| [tenancy](tenancy.md)                                     | -           |
+| [tenancy/owner-key](tenancy/owner-key.md)                 | -           |
+| [tenancy/registry](tenancy/registry.md)                   | -           |
+| [tenancy/resolve](tenancy/resolve.md)                     | -           |
+| [tenant](tenant.md)                                       | -           |
+| [workers-git](workers-git.md)                             | -           |
+| [workers](workers.md)                                     | -           |