@fungi.computer/oyster 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,599 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / shell/app-directory
+
+# shell/app-directory
+
+## Type Aliases
+
+### AppAddress
+
+```ts
+type AppAddress = z.output<typeof appAddressSchema>;
+```
+
+Decoded address of a default App or an installation.
+
+---
+
+### AppAuthorityEnforcement
+
+```ts
+type AppAuthorityEnforcement = z.output<typeof appAuthorityEnforcementSchema>;
+```
+
+A host-reported authority change and its remaining work.
+
+---
+
+### AppDirectoryGill
+
+```ts
+type AppDirectoryGill = {
+  [
+    Field in keyof Schema.Schema.Type<typeof appDeclaredGillSchema>
+  ]: Schema.Schema.Type<typeof appDeclaredGillSchema>[Field];
+};
+```
+
+A Release-declared Gill carried by the host's App directory. The named mapped
+type keeps consumer declarations attached to this public contract.
+
+---
+
+### AppDirectoryEntry
+
+```ts
+type AppDirectoryEntry = z.output<typeof appDirectoryEntrySchema>;
+```
+
+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
+type AppCatalog = z.output<typeof appCatalogResponseSchema>;
+```
+
+Parsed metadata returned by the read-only APPS.catalog binding.
+
+## Variables
+
+### appAddressSchema
+
+```ts
+const appAddressSchema: ZodUnion<
+  readonly [
+    ZodObject<
+      {
+        kind: ZodLiteral<"default">;
+        appId: ZodString;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        kind: ZodLiteral<"installation">;
+        installationId: ZodString;
+      },
+      $strict
+    >,
+  ]
+>;
+```
+
+An App address selects a host default or a specific installation.
+
+---
+
+### appAuthorityEnforcementSchema
+
+```ts
+const appAuthorityEnforcementSchema: ZodObject<
+  {
+    requestId: ZodString;
+    address: ZodUnion<
+      readonly [
+        ZodObject<
+          {
+            kind: ZodLiteral<"default">;
+            appId: ZodString;
+          },
+          $strict
+        >,
+        ZodObject<
+          {
+            kind: ZodLiteral<"installation">;
+            installationId: ZodString;
+          },
+          $strict
+        >,
+      ]
+    >;
+    authorityVersion: ZodNumber;
+    state: ZodEnum<{
+      pending: "pending";
+      expired: "expired";
+      unaffected: "unaffected";
+      applied: "applied";
+    }>;
+    outstanding: ZodNumber;
+  },
+  $strict
+>;
+```
+
+Host-reported progress of applying a revised App authority version.
+
+---
+
+### appDirectoryEntrySchema
+
+```ts
+const appDirectoryEntrySchema: 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<{
+        kind: ZodLiteral<"default">;
+        appId: ZodString;
+      }, $strict>, ZodObject<{
+        kind: ZodLiteral<"installation">;
+        installationId: ZodString;
+     }, $strict>]>;
+     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?: string;
+     sigil?: string;
+     projections?: Readonly<{
+        bindings?: ... | ...;
+        agent?: ... | ...;
+        help?: ... | ...;
+        menu?: ... | ...;
+        palette?: ... | ...;
+        slash?: ... | ...;
+     }>;
+  }>[], unknown[]>>;
+  gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
+  availability: ZodEnum<{
+     unavailable: "unavailable";
+     available: "available";
+  }>;
+  surface: ZodNullable<ZodObject<{
+     stableRoute: ZodString;
+  }, $strict>>;
+  surfacePath: ZodString;
+}, $strict>;
+```
+
+Reusable App metadata supplied by an embedding host; it conveys no permissions.
+
+---
+
+### appRoleSelectionSchema
+
+```ts
+const appRoleSelectionSchema: ZodObject<
+  {
+    surfaceId: ZodNullable<ZodString>;
+    chosen: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+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
+const appCatalogEntrySchema: ZodObject<{
+  surfaceId: ZodString;
+  appId: ZodString;
+  displayName: ZodOptional<ZodString>;
+  gills: ZodArray<ZodObject<{
+     id: ZodString;
+     title: ZodString;
+     params: ZodOptional<ZodArray<ZodObject<{
+        key: ZodString;
+        label: ZodString;
+        kind: ZodEnum<...>;
+        required: ZodBoolean;
+        options: ZodOptional<...>;
+     }, $strict>> & ZodType<readonly object[], object[], $ZodTypeInternals<readonly object[], object[]>>>;
+     desktop: ZodOptional<ZodObject<{
+        sizes: ZodArray<ZodEnum<{
+           S: ...;
+           M: ...;
+           L: ...;
+        }>>;
+     }, $strict>>;
+  }, $strict>>;
+}, $strict>;
+```
+
+Read-only catalog metadata for one App, without host-specific role policy.
+
+---
+
+### appCatalogResponseSchema
+
+```ts
+const appCatalogResponseSchema: ZodObject<{
+  apps: ZodArray<ZodObject<{
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     gills: ZodArray<ZodObject<{
+        id: ZodString;
+        title: ZodString;
+        params: ZodOptional<ZodArray<...> & ZodType<..., ..., ...>>;
+        desktop: ZodOptional<ZodObject<{
+           sizes: ...;
+        }, $strict>>;
+     }, $strict>>;
+  }, $strict>>;
+  roles: ZodObject<{
+     inbox: ZodOptional<ZodObject<{
+        surfaceId: ZodNullable<ZodString>;
+        chosen: ZodBoolean;
+     }, $strict>>;
+  }, $strict>;
+}, $strict>;
+```
+
+Read-only desktop metadata; identities are surface addresses, never launch
+authority.
+
+---
+
+### appCatalogBrokerResultSchema
+
+```ts
+const appCatalogBrokerResultSchema: ZodUnion<readonly [ZodObject<{
+  apps: ZodArray<ZodObject<{
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     gills: ZodArray<ZodObject<{
+        id: ZodString;
+        title: ZodString;
+        params: ZodOptional<...>;
+        desktop: ZodOptional<...>;
+     }, $strict>>;
+  }, $strict>>;
+  roles: ZodObject<{
+     inbox: ZodOptional<ZodObject<{
+        surfaceId: ZodNullable<ZodString>;
+        chosen: ZodBoolean;
+     }, $strict>>;
+  }, $strict>;
+}, $strict>, ZodObject<{
+  error: ZodString;
+}, $strict>]>;
+```
+
+Complete APPS.catalog reply, including broker admission failures.
+
+## Functions
+
+### addressKey()
+
+```ts
+function addressKey(address): string;
+```
+
+Stable identity of one App address across directory and settings views.
+
+#### Parameters
+
+| Parameter | Type                                                                                                            |
+| --------- | --------------------------------------------------------------------------------------------------------------- |
+| `address` | \| \{ `kind`: `"default"`; `appId`: `string`; \} \| \{ `kind`: `"installation"`; `installationId`: `string`; \} |
+
+#### Returns
+
+`string`