@fungi.computer/oyster 0.0.1 → 0.2.0

package/docs/api/modules.md

@@ -8,35 +8,43 @@
 
 ## 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](shell/workbench.md)           | -           |
-| [tenant](tenant.md)                             | -           |
-| [workers-git](workers-git.md)                   | -           |
-| [workers](workers.md)                           | -           |
+| 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)                                     | -           |

package/docs/api/pack.md

@@ -123,9 +123,12 @@ its state; both go through its one install-or-select owner.
 function publishSource(input): Promise<Response>;
 ```
 
-Project one exact first-party commit's editable source and seed it into an
-Oyster's own template, so `APPS.fork` can later fork it. The operator owner key
-authenticates; no provider credential ever leaves this call.
+Project one exact first-party commit's editable source, `git push` it to an
+Oyster's own template for that App, and claim the pushed head, so `APPS.fork`
+and Computer builds can later read it. The operator owner key authenticates
+both; it reaches Git only through its config environment and no provider
+credential ever leaves the Oyster. Answers the claim response:
+`{ kind: "recorded" | "existing", receipt }` on success.
 
 #### Parameters
 

package/docs/api/shell/app-directory.md

@@ -55,6 +55,73 @@ An App directory row before host-specific permissions are attached.
 
 ---
 
+### AppComputerOperation
+
+```ts
+type AppComputerOperation = Extract<
+  z.output<typeof appComputerPermissionSchema>,
+  {
+    kind: "all-team-computers";
+  }
+>["operations"][number];
+```
+
+One operation an App may request for a Computer.
+
+---
+
+### AppComputerPermission
+
+```ts
+type AppComputerPermission = z.output<typeof appComputerPermissionSchema>;
+```
+
+Decoded Computer permission scope attached to an App directory entry.
+
+---
+
+### AppAgentPermission
+
+```ts
+type AppAgentPermission = z.output<typeof appAgentPermissionSchema>;
+```
+
+Decoded Agent permission scope attached to an App directory entry.
+
+---
+
+### AppGenerationPermissions
+
+```ts
+type AppGenerationPermissions = z.output<typeof appGenerationPermissionsSchema>;
+```
+
+Decoded generation permissions attached to an App directory entry.
+
+---
+
+### AppMarketplacePermissions
+
+```ts
+type AppMarketplacePermissions = z.output<
+  typeof appMarketplacePermissionsSchema
+>;
+```
+
+Decoded marketplace permissions attached to an App directory entry.
+
+---
+
+### AppDirectory
+
+```ts
+type AppDirectory = z.output<typeof appDirectoryResponseSchema>;
+```
+
+The host-resolved Team App directory and its permission projections.
+
+---
+
 ### AppCatalog
 
 ```ts
@@ -220,6 +287,206 @@ A host-resolved role selection; a surface address is not launch authority.
 
 ---
 
+### appComputerPermissionSchema
+
+```ts
+const appComputerPermissionSchema: ZodDiscriminatedUnion<[ZodObject<{
+  kind: ZodLiteral<"selected-computers">;
+  computers: ZodArray<ZodObject<{
+     computerId: ZodString;
+     operations: ZodArray<ZodEnum<{
+        computer.list: "computer.list";
+        computer.readFile: "computer.readFile";
+        computer.writeFile: "computer.writeFile";
+        computer.execute: "computer.execute";
+     }>>;
+  }, $strict>>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"all-team-computers">;
+  operations: ZodArray<ZodEnum<{
+     computer.list: "computer.list";
+     computer.readFile: "computer.readFile";
+     computer.writeFile: "computer.writeFile";
+     computer.execute: "computer.execute";
+  }>>;
+}, $strict>], "kind">;
+```
+
+App Computer permissions limited to selected Computers or the Team's Computers.
+
+---
+
+### appAgentPermissionSchema
+
+```ts
+const appAgentPermissionSchema: ZodDiscriminatedUnion<[ZodObject<{
+  kind: ZodLiteral<"all-team-agents">;
+  directoryOperations: ZodArray<ZodEnum<{
+     agent.list: "agent.list";
+  }>>;
+  sessionOperations: ZodArray<ZodEnum<{
+     agent.manage: "agent.manage";
+     agent.read: "agent.read";
+     agent.send: "agent.send";
+  }>>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"selected-agents">;
+  directoryOperations: ZodArray<ZodEnum<{
+     agent.list: "agent.list";
+  }>>;
+  agents: ZodArray<ZodObject<{
+     agentId: ZodString;
+     sessionOperations: ZodArray<ZodEnum<{
+        agent.manage: "agent.manage";
+        agent.read: "agent.read";
+        agent.send: "agent.send";
+     }>>;
+  }, $strict>>;
+}, $strict>], "kind">;
+```
+
+Agent directory and session operations an App may request from its host.
+
+---
+
+### appGenerationPermissionsSchema
+
+```ts
+const appGenerationPermissionsSchema: ZodObject<
+  {
+    llm: ZodBoolean;
+    media: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Whether an App may use language-model and media generation services.
+
+---
+
+### appMarketplacePermissionsSchema
+
+```ts
+const appMarketplacePermissionsSchema: ZodObject<
+  {
+    browse: ZodBoolean;
+    purchase: ZodBoolean;
+    installFree: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Whether an App may browse, buy, or install free marketplace entries.
+
+---
+
+### appDirectoryResponseSchema
+
+```ts
+const appDirectoryResponseSchema: ZodObject<{
+  actorIsTeamOwner: ZodBoolean;
+  needsUpdate: ZodOptional<ZodArray<ZodObject<{
+     installationId: ZodNullable<ZodString>;
+     appId: ZodNullable<ZodString>;
+     displayName: ZodString;
+  }, $strict>>>;
+  apps: ZodArray<ZodObject<{
+     address: ZodUnion<readonly [ZodObject<{
+        kind: ZodLiteral<"default">;
+        appId: ZodString;
+      }, $strict>, ZodObject<{
+        kind: ZodLiteral<"installation">;
+        installationId: ZodString;
+     }, $strict>]>;
+     installationId: ZodNullable<ZodString>;
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     icon: ZodOptional<ZodNullable<ZodString>>;
+     releaseId: ZodNullable<ZodString>;
+     authorityVersion: ZodNumber;
+     enforcement: ZodNullable<ZodObject<{
+        requestId: ZodString;
+        address: ZodUnion<readonly [ZodObject<..., ...>, ZodObject<..., ...>]>;
+        authorityVersion: ZodNumber;
+        state: ZodEnum<{
+           pending: "pending";
+           expired: "expired";
+           unaffected: "unaffected";
+           applied: "applied";
+        }>;
+        outstanding: ZodNumber;
+     }, $strict>>;
+     handlers: ZodArray<ZodLiteral<"file.open">>;
+     roles: ZodArray<ZodString>;
+     declaredCapabilities: ZodArray<ZodString>;
+     calls: ZodOptional<ZodPipe<ZodUnknown, ZodTransform<readonly object[], unknown>>>;
+     commands: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<Readonly<{
+        id: string;
+        title: string;
+        category: string;
+        description?: ... | ...;
+        sigil?: ... | ...;
+        projections?: ... | ...;
+     }>[], unknown[]>>;
+     gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
+     availability: ZodEnum<{
+        unavailable: "unavailable";
+        available: "available";
+     }>;
+     surface: ZodNullable<ZodObject<{
+        stableRoute: ZodString;
+     }, $strict>>;
+     surfacePath: ZodString;
+     override: ZodNullable<ZodObject<{
+        appId: ZodOptional<ZodString>;
+        releaseId: ZodString;
+        surfaceRoute: ZodNullable<ZodString>;
+     }, $strict>>;
+     grants: ZodArray<ZodObject<{
+        operation: ZodString;
+        resourceId: ZodString;
+     }, $strict>>;
+     computerPermission: ZodOptional<ZodNullable<ZodDiscriminatedUnion<[ZodObject<{
+        kind: ...;
+        computers: ...;
+      }, $strict>, ZodObject<{
+        kind: ...;
+        operations: ...;
+     }, $strict>], "kind">>>;
+     generationPermissions: ZodObject<{
+        llm: ZodBoolean;
+        media: ZodBoolean;
+     }, $strict>;
+     marketplacePermissions: ZodObject<{
+        browse: ZodBoolean;
+        purchase: ZodBoolean;
+        installFree: ZodBoolean;
+     }, $strict>;
+     agentPermission: ZodDiscriminatedUnion<[ZodObject<{
+        kind: ZodLiteral<"all-team-agents">;
+        directoryOperations: ZodArray<ZodEnum<...>>;
+        sessionOperations: ZodArray<ZodEnum<...>>;
+      }, $strict>, ZodObject<{
+        kind: ZodLiteral<"selected-agents">;
+        directoryOperations: ZodArray<ZodEnum<...>>;
+        agents: ZodArray<ZodObject<..., ...>>;
+     }, $strict>], "kind">;
+  }, $strict>>;
+  roles: ZodRecord<ZodString, ZodObject<{
+     surfaceId: ZodNullable<ZodString>;
+     chosen: ZodBoolean;
+  }, $strict>>;
+}, $strict>;
+```
+
+A host's Team App directory with its permission projection, parsed strictly by
+every consumer: an unknown field is a contract change both sides make.
+
+---
+
 ### appCatalogEntrySchema
 
 ```ts

package/docs/api/shell/shell-module.md

@@ -120,16 +120,75 @@ that removes it again. The shell loads its own code and styles.
 
 `Promise`\<() => `void`\>
 
+---
+
+### ShellPlatformControls
+
+```ts
+type ShellPlatformControls = Readonly<{
+  controls: WorkbenchHostControls;
+  suggestDesktopSettings: void;
+  dispose: void;
+}>;
+```
+
+Settings a shell renders for a host that has none of its own, such as a
+standalone Oyster: the shell draws them into `root`, and the host hands
+`controls` to its workbench so Apps and the dashboard can open them.
+
+---
+
+### MountPlatformControls
+
+```ts
+type MountPlatformControls = (root, input) => Promise<ShellPlatformControls>;
+```
+
+Render the shell's own Settings into `root` for the host at `teamId`.
+
+#### Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| `root`    | `HTMLElement`                           |
+| `input`   | `Readonly`\<\{ `teamId`: `string`; \}\> |
+
+#### Returns
+
+`Promise`\<[`ShellPlatformControls`](#shellplatformcontrols)\>
+
+---
+
+### ShellModule
+
+```ts
+type ShellModule = Readonly<{
+  mountShell: MountShell;
+  mountPlatformControls: MountPlatformControls | null;
+}>;
+```
+
+What a host gets from a picked shell Release's module.
+
 ## Functions
 
 ### importShellModule()
 
 ```ts
-function importShellModule(moduleUrl, hostOrigin): Promise<MountShell>;
+function importShellModule(
+  moduleUrl,
+  hostOrigin,
+): Promise<
+  Readonly<{
+    mountShell: MountShell;
+    mountPlatformControls: MountPlatformControls | null;
+  }>
+>;
 ```
 
 Import the picked shell Release's module from the host's own origin and check
-that it exports `mountShell`. The host never bundles a shell.
+that it exports `mountShell`, and `mountPlatformControls` when it offers its own
+Settings. The host never bundles a shell.
 
 #### Parameters
 
@@ -140,4 +199,6 @@ that it exports `mountShell`. The host never bundles a shell.
 
 #### Returns
 
-`Promise`\<[`MountShell`](#mountshell)\>
+`Promise`\<`Readonly`\<\{ `mountShell`: [`MountShell`](#mountshell);
+`mountPlatformControls`: [`MountPlatformControls`](#mountplatformcontrols) \|
+`null`; \}\>\>

package/docs/api/shell/workbench-directory.md

@@ -0,0 +1,119 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / shell/workbench-directory
+
+# shell/workbench-directory
+
+## Type Aliases
+
+### WorkbenchDirectory
+
+```ts
+type WorkbenchDirectory = z.output<typeof workbenchDirectorySchema>;
+```
+
+One host's current desktop rows and actual role selections.
+
+## Variables
+
+### workbenchDirectorySchema
+
+```ts
+const workbenchDirectorySchema: ZodPipe<ZodObject<{
+  apps: ZodArray<ZodObject<{
+     address: ZodUnion<readonly [ZodObject<{
+        kind: ZodLiteral<...>;
+        appId: ZodString;
+      }, $strict>, ZodObject<{
+        kind: ZodLiteral<...>;
+        installationId: ZodString;
+     }, $strict>]>;
+     installationId: ZodNullable<ZodString>;
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     icon: ZodOptional<ZodNullable<ZodString>>;
+     releaseId: ZodNullable<ZodString>;
+     authorityVersion: ZodNumber;
+     enforcement: ZodNullable<ZodObject<{
+        requestId: ZodString;
+        address: ZodUnion<readonly [..., ...]>;
+        authorityVersion: ZodNumber;
+        state: ZodEnum<{
+           unaffected: ...;
+           pending: ...;
+           applied: ...;
+           expired: ...;
+        }>;
+        outstanding: ZodNumber;
+     }, $strict>>;
+     handlers: ZodArray<ZodLiteral<"file.open">>;
+     roles: ZodArray<ZodString>;
+     declaredCapabilities: ZodArray<ZodString>;
+     calls: ZodOptional<ZodPipe<ZodUnknown, ZodTransform<readonly object[], unknown>>>;
+     commands: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<Readonly<{
+        id: ...;
+        title: ...;
+        category: ...;
+        description?: ...;
+        sigil?: ...;
+        projections?: ...;
+     }>[], unknown[]>>;
+     gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
+     availability: ZodEnum<{
+        available: "available";
+        unavailable: "unavailable";
+     }>;
+     surface: ZodNullable<ZodObject<{
+        stableRoute: ZodString;
+     }, $strict>>;
+     surfacePath: ZodString;
+     computer: ZodOptional<ZodObject<{
+        computerId: ZodString;
+        name: ZodString;
+     }, $strip>>;
+     computerPermission: ZodOptional<ZodNullable<ZodDiscriminatedUnion<[ZodObject<..., ...>, ZodObject<..., ...>], "kind">>>;
+  }, $strip>>;
+  computer: ZodOptional<ZodObject<{
+     computerId: ZodString;
+     name: ZodString;
+  }, $strip>>;
+  roles: ZodRecord<ZodString, ZodObject<{
+     surfaceId: ZodNullable<ZodString>;
+     chosen: ZodBoolean;
+  }, $strict>>;
+  needsUpdate: ZodOptional<ZodArray<ZodObject<{
+     installationId: ZodNullable<ZodString>;
+     appId: ZodNullable<ZodString>;
+     displayName: ZodString;
+  }, $strict>>>;
+}, $strip>, ZodTransform<{
+  apps: object[];
+  computer?: {
+     computerId: string;
+     name: string;
+  };
+  roles: Record<string, {
+     surfaceId: string | null;
+     chosen: boolean;
+  }>;
+  needsUpdate?: object[];
+}, {
+  apps: object[];
+  computer?: {
+     computerId: string;
+     name: string;
+  };
+  roles: Record<string, {
+     surfaceId: string | null;
+     chosen: boolean;
+  }>;
+  needsUpdate?: object[];
+}>>;
+```
+
+Desktop metadata shared by hosts; hosted administration stays in Settings.

package/docs/api/shell/workbench.md

@@ -169,6 +169,25 @@ Re-exports [appOpenRequestSchema](../shell.md#appopenrequestschema)
 
 ---
 
+### teamComputerSchema
+
+Re-exports [teamComputerSchema](../shell.md#teamcomputerschema)
+
+---
+
+### TeamComputer
+
+Re-exports [TeamComputer](../shell.md#teamcomputer)
+
+---
+
+### teamComputerDirectorySchema
+
+Re-exports
+[teamComputerDirectorySchema](../shell.md#teamcomputerdirectoryschema)
+
+---
+
 ### TeamWorkbenchHostHandle
 
 Re-exports [TeamWorkbenchHostHandle](../shell.md#teamworkbenchhosthandle)