@fungi.computer/oyster 0.0.1 → 0.2.0

package/dist/release.d.ts

@@ -9,6 +9,17 @@ export type ArtifactStore = Readonly<{
     /** Store bytes under `artifactRef`; the caller has verified the digest. */
     put: (artifactRef: ArtifactRef, bytes: Uint8Array) => Promise<void>;
 }>;
+/** What a store knows of one object without reading it. */
+export type ArtifactHead = Readonly<{
+    byteLength: number;
+    /** The digest the store verified when it took the bytes, if it did. */
+    digest: Sha256Digest | null;
+}>;
+/** A store that can describe an object without reading its bytes. */
+export type ArtifactHeads = Readonly<{
+    /** Describe the object at `artifactRef`, or `null` when absent. */
+    head: (artifactRef: ArtifactRef) => Promise<ArtifactHead | null>;
+}>;
 /** Why a Release could not be read; the host maps it to an HTTP refusal. */
 export declare class ReleaseError extends Error {
     readonly code: "artifact_missing" | "digest_mismatch" | "invalid_release" | "asset_missing";

package/dist/release.js

@@ -79,8 +79,11 @@ readAssets = true) {
             catch (cause) {
                 throw new ReleaseError("invalid_release", "Invalid assets", { cause });
             }
+            // One asset at a time: a Release's assets together can exceed an
+            // isolate's memory, each alone is bounded by its policy.
             if (readAssets)
-                await Promise.all(assets.assets.map((asset) => readVerified(store, asset.artifactRef, asset.digest)));
+                for (const asset of assets.assets)
+                    await readVerified(store, asset.artifactRef, asset.digest);
             ui = { kind: "assets", build: assets };
         }
         else

package/dist/shell/app-directory.d.ts

@@ -2,23 +2,23 @@ import * as Schema from "effect/Schema";
 import { appDeclaredGillSchema } from "@fungi.computer/gills";
 import * as z from "zod";
 /** An App address selects a host default or a specific installation. */
-export declare const appAddressSchema: z.ZodUnion<readonly [z.ZodObject<{
+export declare const appAddressSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"default">;
     appId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"installation">;
     installationId: z.ZodString;
-}, z.core.$strict>]>;
+}, z.core.$strict>]>>;
 /** Host-reported progress of applying a revised App authority version. */
-export declare const appAuthorityEnforcementSchema: z.ZodObject<{
+export declare const appAuthorityEnforcementSchema: z.ZodLazy<z.ZodObject<{
     requestId: z.ZodString;
-    address: z.ZodUnion<readonly [z.ZodObject<{
+    address: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
         kind: z.ZodLiteral<"default">;
         appId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"installation">;
         installationId: z.ZodString;
-    }, z.core.$strict>]>;
+    }, z.core.$strict>]>>;
     authorityVersion: z.ZodNumber;
     state: z.ZodEnum<{
         unaffected: "unaffected";
@@ -27,7 +27,7 @@ export declare const appAuthorityEnforcementSchema: z.ZodObject<{
         expired: "expired";
     }>;
     outstanding: z.ZodNumber;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Decoded address of a default App or an installation. */
 export type AppAddress = z.output<typeof appAddressSchema>;
 /** Stable identity of one App address across directory and settings views. */
@@ -43,13 +43,13 @@ export type AppDirectoryGill = {
 };
 /** Reusable App metadata supplied by an embedding host; it conveys no permissions. */
 export declare const appDirectoryEntrySchema: z.ZodObject<{
-    address: z.ZodUnion<readonly [z.ZodObject<{
+    address: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
         kind: z.ZodLiteral<"default">;
         appId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"installation">;
         installationId: z.ZodString;
-    }, z.core.$strict>]>;
+    }, z.core.$strict>]>>;
     installationId: z.ZodNullable<z.ZodString>;
     surfaceId: z.ZodString;
     appId: z.ZodString;
@@ -57,15 +57,15 @@ export declare const appDirectoryEntrySchema: z.ZodObject<{
     icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     releaseId: z.ZodNullable<z.ZodString>;
     authorityVersion: z.ZodNumber;
-    enforcement: z.ZodNullable<z.ZodObject<{
+    enforcement: z.ZodNullable<z.ZodLazy<z.ZodObject<{
         requestId: z.ZodString;
-        address: z.ZodUnion<readonly [z.ZodObject<{
+        address: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
             kind: z.ZodLiteral<"default">;
             appId: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"installation">;
             installationId: z.ZodString;
-        }, z.core.$strict>]>;
+        }, z.core.$strict>]>>;
         authorityVersion: z.ZodNumber;
         state: z.ZodEnum<{
             unaffected: "unaffected";
@@ -74,7 +74,7 @@ export declare const appDirectoryEntrySchema: z.ZodObject<{
             expired: "expired";
         }>;
         outstanding: z.ZodNumber;
-    }, z.core.$strict>>;
+    }, z.core.$strict>>>;
     handlers: z.ZodArray<z.ZodLiteral<"file.open">>;
     roles: z.ZodArray<z.ZodString>;
     declaredCapabilities: z.ZodArray<z.ZodString>;
@@ -132,14 +132,8 @@ export declare const appRoleSelectionSchema: z.ZodObject<{
     surfaceId: z.ZodNullable<z.ZodString>;
     chosen: z.ZodBoolean;
 }, z.core.$strict>;
-declare const appComputerOperationSchema: z.ZodEnum<{
-    "computer.list": "computer.list";
-    "computer.readFile": "computer.readFile";
-    "computer.writeFile": "computer.writeFile";
-    "computer.execute": "computer.execute";
-}>;
-export type AppComputerOperation = z.output<typeof appComputerOperationSchema>;
-export declare const appComputerPermissionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+/** App Computer permissions limited to selected Computers or the Team's Computers. */
+export declare const appComputerPermissionSchema: z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
     kind: z.ZodLiteral<"selected-computers">;
     computers: z.ZodArray<z.ZodObject<{
         computerId: z.ZodString;
@@ -150,7 +144,7 @@ export declare const appComputerPermissionSchema: z.ZodDiscriminatedUnion<[z.Zod
             "computer.execute": "computer.execute";
         }>>;
     }, z.core.$strict>>;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
     kind: z.ZodLiteral<"all-team-computers">;
     operations: z.ZodArray<z.ZodEnum<{
         "computer.list": "computer.list";
@@ -158,8 +152,14 @@ export declare const appComputerPermissionSchema: z.ZodDiscriminatedUnion<[z.Zod
         "computer.writeFile": "computer.writeFile";
         "computer.execute": "computer.execute";
     }>>;
-}, z.core.$strict>], "kind">;
+}, z.core.$strict>>], "kind">;
+/** One operation an App may request for a Computer. */
+export type AppComputerOperation = Extract<z.output<typeof appComputerPermissionSchema>, {
+    kind: "all-team-computers";
+}>["operations"][number];
+/** Decoded Computer permission scope attached to an App directory entry. */
 export type AppComputerPermission = z.output<typeof appComputerPermissionSchema>;
+/** Agent directory and session operations an App may request from its host. */
 export declare const appAgentPermissionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"all-team-agents">;
     directoryOperations: z.ZodArray<z.ZodEnum<{
@@ -184,23 +184,28 @@ export declare const appAgentPermissionSchema: z.ZodDiscriminatedUnion<[z.ZodObj
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>], "kind">;
+/** Decoded Agent permission scope attached to an App directory entry. */
 export type AppAgentPermission = z.output<typeof appAgentPermissionSchema>;
+/** Whether an App may use language-model and media generation services. */
 export declare const appGenerationPermissionsSchema: z.ZodObject<{
     llm: z.ZodBoolean;
     media: z.ZodBoolean;
 }, z.core.$strict>;
+/** Decoded generation permissions attached to an App directory entry. */
 export type AppGenerationPermissions = z.output<typeof appGenerationPermissionsSchema>;
+/** Whether an App may browse, buy, or install free marketplace entries. */
 export declare const appMarketplacePermissionsSchema: z.ZodObject<{
     browse: z.ZodBoolean;
     purchase: z.ZodBoolean;
     installFree: z.ZodBoolean;
 }, z.core.$strict>;
+/** Decoded marketplace permissions attached to an App directory entry. */
 export type AppMarketplacePermissions = z.output<typeof appMarketplacePermissionsSchema>;
 /**
  * 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.
  */
-export declare const appDirectoryResponseSchema: z.ZodObject<{
+export declare const appDirectoryResponseSchema: z.ZodLazy<z.ZodObject<{
     actorIsTeamOwner: z.ZodBoolean;
     needsUpdate: z.ZodOptional<z.ZodArray<z.ZodObject<{
         installationId: z.ZodNullable<z.ZodString>;
@@ -208,13 +213,13 @@ export declare const appDirectoryResponseSchema: z.ZodObject<{
         displayName: z.ZodString;
     }, z.core.$strict>>>;
     apps: z.ZodArray<z.ZodObject<{
-        address: z.ZodUnion<readonly [z.ZodObject<{
+        address: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
             kind: z.ZodLiteral<"default">;
             appId: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"installation">;
             installationId: z.ZodString;
-        }, z.core.$strict>]>;
+        }, z.core.$strict>]>>;
         installationId: z.ZodNullable<z.ZodString>;
         surfaceId: z.ZodString;
         appId: z.ZodString;
@@ -222,15 +227,15 @@ export declare const appDirectoryResponseSchema: z.ZodObject<{
         icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         releaseId: z.ZodNullable<z.ZodString>;
         authorityVersion: z.ZodNumber;
-        enforcement: z.ZodNullable<z.ZodObject<{
+        enforcement: z.ZodNullable<z.ZodLazy<z.ZodObject<{
             requestId: z.ZodString;
-            address: z.ZodUnion<readonly [z.ZodObject<{
+            address: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
                 kind: z.ZodLiteral<"default">;
                 appId: z.ZodString;
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"installation">;
                 installationId: z.ZodString;
-            }, z.core.$strict>]>;
+            }, z.core.$strict>]>>;
             authorityVersion: z.ZodNumber;
             state: z.ZodEnum<{
                 unaffected: "unaffected";
@@ -239,7 +244,7 @@ export declare const appDirectoryResponseSchema: z.ZodObject<{
                 expired: "expired";
             }>;
             outstanding: z.ZodNumber;
-        }, z.core.$strict>>;
+        }, z.core.$strict>>>;
         handlers: z.ZodArray<z.ZodLiteral<"file.open">>;
         roles: z.ZodArray<z.ZodString>;
         declaredCapabilities: z.ZodArray<z.ZodString>;
@@ -298,7 +303,7 @@ export declare const appDirectoryResponseSchema: z.ZodObject<{
             operation: z.ZodString;
             resourceId: z.ZodString;
         }, z.core.$strict>>;
-        computerPermission: z.ZodOptional<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        computerPermission: z.ZodOptional<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
             kind: z.ZodLiteral<"selected-computers">;
             computers: z.ZodArray<z.ZodObject<{
                 computerId: z.ZodString;
@@ -309,7 +314,7 @@ export declare const appDirectoryResponseSchema: z.ZodObject<{
                     "computer.execute": "computer.execute";
                 }>>;
             }, z.core.$strict>>;
-        }, z.core.$strict>, z.ZodObject<{
+        }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
             kind: z.ZodLiteral<"all-team-computers">;
             operations: z.ZodArray<z.ZodEnum<{
                 "computer.list": "computer.list";
@@ -317,7 +322,7 @@ export declare const appDirectoryResponseSchema: z.ZodObject<{
                 "computer.writeFile": "computer.writeFile";
                 "computer.execute": "computer.execute";
             }>>;
-        }, z.core.$strict>], "kind">>>;
+        }, z.core.$strict>>], "kind">>>;
         generationPermissions: z.ZodObject<{
             llm: z.ZodBoolean;
             media: z.ZodBoolean;
@@ -356,7 +361,8 @@ export declare const appDirectoryResponseSchema: z.ZodObject<{
         surfaceId: z.ZodNullable<z.ZodString>;
         chosen: z.ZodBoolean;
     }, z.core.$strict>>;
-}, z.core.$strict>;
+}, z.core.$strict>>;
+/** The host-resolved Team App directory and its permission projections. */
 export type AppDirectory = z.output<typeof appDirectoryResponseSchema>;
 /** Read-only catalog metadata for one App, without host-specific role policy. */
 export declare const appCatalogEntrySchema: z.ZodObject<{
@@ -366,7 +372,7 @@ export declare const appCatalogEntrySchema: z.ZodObject<{
     gills: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
-        params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        params: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
             label: z.ZodString;
             kind: z.ZodEnum<{
@@ -400,7 +406,7 @@ export declare const appCatalogEntrySchema: z.ZodObject<{
             kind: "computer" | "repository" | "branch";
             required: boolean;
             options?: string | undefined;
-        }[]>>>;
+        }[]>>>>;
         desktop: z.ZodOptional<z.ZodObject<{
             sizes: z.ZodArray<z.ZodEnum<{
                 S: "S";
@@ -411,7 +417,7 @@ export declare const appCatalogEntrySchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** Read-only desktop metadata; identities are surface addresses, never launch authority. */
-export declare const appCatalogResponseSchema: z.ZodObject<{
+export declare const appCatalogResponseSchema: z.ZodLazy<z.ZodObject<{
     apps: z.ZodArray<z.ZodObject<{
         appId: z.ZodString;
         surfaceId: z.ZodString;
@@ -419,7 +425,7 @@ export declare const appCatalogResponseSchema: z.ZodObject<{
         gills: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             title: z.ZodString;
-            params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            params: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 label: z.ZodString;
                 kind: z.ZodEnum<{
@@ -453,7 +459,7 @@ export declare const appCatalogResponseSchema: z.ZodObject<{
                 kind: "computer" | "repository" | "branch";
                 required: boolean;
                 options?: string | undefined;
-            }[]>>>;
+            }[]>>>>;
             desktop: z.ZodOptional<z.ZodObject<{
                 sizes: z.ZodArray<z.ZodEnum<{
                     S: "S";
@@ -469,11 +475,11 @@ export declare const appCatalogResponseSchema: z.ZodObject<{
             chosen: z.ZodBoolean;
         }, z.core.$strict>>;
     }, z.core.$strict>;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Parsed metadata returned by the read-only APPS.catalog binding. */
 export type AppCatalog = z.output<typeof appCatalogResponseSchema>;
 /** Complete APPS.catalog reply, including broker admission failures. */
-export declare const appCatalogBrokerResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+export declare const appCatalogBrokerResultSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodLazy<z.ZodObject<{
     apps: z.ZodArray<z.ZodObject<{
         appId: z.ZodString;
         surfaceId: z.ZodString;
@@ -481,7 +487,7 @@ export declare const appCatalogBrokerResultSchema: z.ZodUnion<readonly [z.ZodObj
         gills: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             title: z.ZodString;
-            params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            params: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 label: z.ZodString;
                 kind: z.ZodEnum<{
@@ -515,7 +521,7 @@ export declare const appCatalogBrokerResultSchema: z.ZodUnion<readonly [z.ZodObj
                 kind: "computer" | "repository" | "branch";
                 required: boolean;
                 options?: string | undefined;
-            }[]>>>;
+            }[]>>>>;
             desktop: z.ZodOptional<z.ZodObject<{
                 sizes: z.ZodArray<z.ZodEnum<{
                     S: "S";
@@ -531,7 +537,6 @@ export declare const appCatalogBrokerResultSchema: z.ZodUnion<readonly [z.ZodObj
             chosen: z.ZodBoolean;
         }, z.core.$strict>>;
     }, z.core.$strict>;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export {};
+}, z.core.$strict>]>>;

package/dist/shell/app-directory.js

@@ -3,7 +3,7 @@ import { appDeclaredCommandSchema, appCallsSchema, } from "@fungi.computer/puffb
 import { appDeclaredGillSchema, appGillParamsSchema, } from "@fungi.computer/gills";
 import * as z from "zod";
 /** An App address selects a host default or a specific installation. */
-export const appAddressSchema = z.union([
+export const appAddressSchema = z.lazy(() => z.union([
     z.strictObject({
         kind: z.literal("default"),
         appId: z.string().min(1),
@@ -12,15 +12,15 @@ export const appAddressSchema = z.union([
         kind: z.literal("installation"),
         installationId: z.string().min(1),
     }),
-]);
+]));
 /** Host-reported progress of applying a revised App authority version. */
-export const appAuthorityEnforcementSchema = z.strictObject({
+export const appAuthorityEnforcementSchema = z.lazy(() => z.strictObject({
     requestId: z.string().min(1),
     address: appAddressSchema,
     authorityVersion: z.number().int().positive(),
     state: z.enum(["unaffected", "pending", "applied", "expired"]),
     outstanding: z.number().int().nonnegative(),
-});
+}));
 /** Stable identity of one App address across directory and settings views. */
 export const addressKey = (address) => address.kind === "default"
     ? `default:${address.appId}`
@@ -69,17 +69,18 @@ const appComputerOperationSchema = z.enum([
     "computer.writeFile",
     "computer.execute",
 ]);
-const selectedComputerPermissionSchema = z.strictObject({
+const selectedComputerPermissionSchema = z.lazy(() => z.strictObject({
     kind: z.literal("selected-computers"),
     computers: z.array(z.strictObject({
         computerId: z.string().min(1),
         operations: z.array(appComputerOperationSchema),
     })),
-});
-const allTeamComputersPermissionSchema = z.strictObject({
+}));
+const allTeamComputersPermissionSchema = z.lazy(() => z.strictObject({
     kind: z.literal("all-team-computers"),
     operations: z.array(appComputerOperationSchema),
-});
+}));
+/** App Computer permissions limited to selected Computers or the Team's Computers. */
 export const appComputerPermissionSchema = z.discriminatedUnion("kind", [
     selectedComputerPermissionSchema,
     allTeamComputersPermissionSchema,
@@ -90,6 +91,7 @@ const agentSessionOperationSchema = z.enum([
     "agent.send",
     "agent.manage",
 ]);
+/** Agent directory and session operations an App may request from its host. */
 export const appAgentPermissionSchema = z.discriminatedUnion("kind", [
     z.strictObject({
         kind: z.literal("all-team-agents"),
@@ -105,10 +107,12 @@ export const appAgentPermissionSchema = z.discriminatedUnion("kind", [
         })),
     }),
 ]);
+/** Whether an App may use language-model and media generation services. */
 export const appGenerationPermissionsSchema = z.strictObject({
     llm: z.boolean(),
     media: z.boolean(),
 });
+/** Whether an App may browse, buy, or install free marketplace entries. */
 export const appMarketplacePermissionsSchema = z.strictObject({
     browse: z.boolean(),
     purchase: z.boolean(),
@@ -118,7 +122,7 @@ export const appMarketplacePermissionsSchema = z.strictObject({
  * 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.
  */
-export const appDirectoryResponseSchema = z.strictObject({
+export const appDirectoryResponseSchema = z.lazy(() => z.strictObject({
     actorIsTeamOwner: z.boolean(),
     needsUpdate: z
         .array(z.strictObject({
@@ -146,9 +150,9 @@ export const appDirectoryResponseSchema = z.strictObject({
     })),
     /** The Team's effective App per role, owned and resolved by the host. */
     roles: z.record(z.string().min(1), appRoleSelectionSchema),
-});
+}));
 /** Desktop metadata is a method result, distinct from the full Release Gill declaration. */
-const catalogGillParamsSchema = z
+const catalogGillParamsSchema = z.lazy(() => z
     .array(z.strictObject({
     key: z.string().max(64),
     label: z.string().max(256),
@@ -158,7 +162,7 @@ const catalogGillParamsSchema = z
 }))
     .max(4)
     // The wire shape is representable; Gill owns its domain refinements.
-    .refine(Schema.is(appGillParamsSchema), "Invalid Gill placement parameters");
+    .refine(Schema.is(appGillParamsSchema), "Invalid Gill placement parameters"));
 const catalogGillSchema = z.strictObject({
     id: z.string().trim().min(1).max(256),
     title: z.string().trim().min(1).max(256),
@@ -182,14 +186,11 @@ export const appCatalogEntrySchema = appDirectoryEntrySchema
 })
     .extend({ gills: z.array(catalogGillSchema).max(16) });
 /** Read-only desktop metadata; identities are surface addresses, never launch authority. */
-export const appCatalogResponseSchema = z.strictObject({
+export const appCatalogResponseSchema = z.lazy(() => z.strictObject({
     apps: z.array(appCatalogEntrySchema).max(50),
     roles: z.strictObject({
         inbox: appRoleSelectionSchema.optional(),
     }),
-});
+}));
 /** Complete APPS.catalog reply, including broker admission failures. */
-export const appCatalogBrokerResultSchema = z.union([
-    appCatalogResponseSchema,
-    z.strictObject({ error: z.string() }),
-]);
+export const appCatalogBrokerResultSchema = z.lazy(() => z.union([appCatalogResponseSchema, z.strictObject({ error: z.string() })]));

package/dist/shell/shell-module.d.ts

@@ -1,6 +1,7 @@
 import type { AppStorage } from "@fungi.computer/agar/storage";
 import type { WhistleJsonValue } from "@fungi.computer/whistle";
 import type { TeamWorkbenchHostHandle } from "./workbench-contract.js";
+import type { WorkbenchHostControls } from "./workbench-host-types.js";
 /**
  * What a host hands the shell a Team picked. The host composes that shell into
  * its own top-level document, so it runs with the host's escalated
@@ -20,12 +21,35 @@ export type ShellMountInput = Readonly<{
  * function that removes it again. The shell loads its own code and styles.
  */
 export type MountShell = (root: HTMLElement, input: ShellMountInput) => Promise<() => 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.
+ */
+export type ShellPlatformControls = Readonly<{
+    controls: WorkbenchHostControls;
+    /** A child App suggested desktop Settings for one of its surfaces. */
+    suggestDesktopSettings(surfaceId: string): void;
+    /** Remove the rendered Settings. */
+    dispose(): void;
+}>;
+/** Render the shell's own Settings into `root` for the host at `teamId`. */
+export type MountPlatformControls = (root: HTMLElement, input: Readonly<{
+    teamId: string;
+}>) => Promise<ShellPlatformControls>;
+/** What a host gets from a picked shell Release's module. */
+export type ShellModule = Readonly<{
+    mountShell: MountShell;
+    /** Absent when the shell renders no Settings of its own. */
+    mountPlatformControls: MountPlatformControls | null;
+}>;
 /** The picked shell's module could not be loaded or does not fit the contract. */
 export declare class ShellModuleError extends Error {
     readonly name = "ShellModuleError";
 }
 /**
  * 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.
+ * check that it exports `mountShell`, and `mountPlatformControls` when it
+ * offers its own Settings. The host never bundles a shell.
  */
-export declare function importShellModule(moduleUrl: URL, hostOrigin: string): Promise<MountShell>;
+export declare function importShellModule(moduleUrl: URL, hostOrigin: string): Promise<ShellModule>;

package/dist/shell/shell-module.js

@@ -1,4 +1,5 @@
 import * as z from "zod";
+const unsubscribe = () => z.function({ input: [], output: z.void() });
 /** The module namespace a shell Release must export; built on first use,
  * since only a browser has `HTMLElement`. */
 const shellModuleSchema = () => z.object({
@@ -7,6 +8,50 @@ const shellModuleSchema = () => z.object({
         input: [z.instanceof(HTMLElement), z.unknown()],
         output: z.promise(z.function({ input: [], output: z.void() })),
     }),
+    mountPlatformControls: z
+        .function({
+        input: [
+            z.instanceof(HTMLElement),
+            z.object({ teamId: z.string() }).readonly(),
+        ],
+        output: z.promise(z.object({
+            controls: z.object({
+                sections: z.array(z.string()).readonly().optional(),
+                // The host passes the workbench's own values; the shell
+                // parses what it reads.
+                parseSettings: z.function({
+                    input: [z.unknown()],
+                    output: z.json(),
+                }),
+                openSettings: z.function({
+                    input: [z.unknown(), z.object({ restoreFocus: z.boolean() })],
+                    output: z.void(),
+                }),
+                subscribeSettingsClosed: z.function({
+                    input: [unsubscribe()],
+                    output: unsubscribe(),
+                }),
+                subscribeChanges: z.function({
+                    input: [unsubscribe()],
+                    output: unsubscribe(),
+                }),
+                attachDesktopSettings: z.function({
+                    input: [z.unknown()],
+                    output: unsubscribe(),
+                }),
+                requestAppAccess: z.function({
+                    input: [z.unknown(), z.unknown()],
+                    output: z.promise(z.enum(["granted", "declined", "customize"])),
+                }),
+            }),
+            suggestDesktopSettings: z.function({
+                input: [z.string()],
+                output: z.void(),
+            }),
+            dispose: unsubscribe(),
+        })),
+    })
+        .optional(),
 });
 /** The picked shell's module could not be loaded or does not fit the contract. */
 export class ShellModuleError extends Error {
@@ -14,7 +59,8 @@ export class ShellModuleError extends Error {
 }
 /**
  * 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.
+ * check that it exports `mountShell`, and `mountPlatformControls` when it
+ * offers its own Settings. The host never bundles a shell.
  */
 export async function importShellModule(moduleUrl, hostOrigin) {
     if (moduleUrl.origin !== hostOrigin || moduleUrl.hash !== "")
@@ -33,5 +79,8 @@ export async function importShellModule(moduleUrl, hostOrigin) {
         throw new ShellModuleError("The picked shell does not export mountShell", {
             cause: decoded.error,
         });
-    return decoded.data.mountShell;
+    return {
+        mountShell: decoded.data.mountShell,
+        mountPlatformControls: decoded.data.mountPlatformControls ?? null,
+    };
 }

package/dist/shell/window-manager.d.ts

@@ -1,4 +1,4 @@
-import { type AppNavigationState, type AppStatusAction, type AppStatusItem } from "@fungi.computer/agar";
+import { type AppNavigationActivation, type AppNavigationState, type AppStatusAction, type AppStatusItem } from "@fungi.computer/agar";
 /** Minimum identity required to own a window across mount generations. */
 export type WindowLaunch = Readonly<{
     windowId: string;
@@ -15,6 +15,8 @@ export type WindowHost<Launch extends WindowLaunch> = Readonly<{
     requestClose?: () => boolean | Promise<boolean>;
     /** Ask the mounted App to go back in its own history; `true` when it did. */
     requestBack?: () => boolean | Promise<boolean>;
+    /** Deliver the person's use of a crumb or header command; `true` when the App acted. */
+    activateNavigation?: (activation: AppNavigationActivation) => boolean | Promise<boolean>;
     /** Deliver the person's use of a status item; `true` when the App acted. */
     activateStatus?: (action: AppStatusAction) => boolean | Promise<boolean>;
     /** Release the current mount and its host resources. */
@@ -79,6 +81,8 @@ export type WindowManager<Launch extends WindowLaunch, Container> = Readonly<{
     replace: (windowId: string, launch: Launch) => Promise<void>;
     /** Ask a ready window's App to go back; `false` when it cannot. */
     back: (windowId: string) => Promise<boolean>;
+    /** Deliver a crumb or header command to a ready window's App; `false` when it cannot. */
+    activateNavigation: (windowId: string, activation: AppNavigationActivation) => Promise<boolean>;
     /** Deliver a status item action to a ready window's App; `false` when it cannot. */
     activateStatus: (windowId: string, action: AppStatusAction) => Promise<boolean>;
     /** Register the current window generation's host-owned picker. */

package/dist/shell/window-manager.js

@@ -1,5 +1,5 @@
 import * as Redacted from "effect/Redacted";
-import { AppError, statusActionAllowed, } from "@fungi.computer/agar";
+import { AppError, navigationActivationAllowed, statusActionAllowed, } from "@fungi.computer/agar";
 /**
  * Shared window lifetime owner for browser and terminal shells.
  *
@@ -18,7 +18,14 @@ function sameStatusItems(current, next) {
 function sameNavigation(current, next) {
     if (current === null || next === null)
         return current === next;
-    return current.canGoBack === next.canGoBack && current.title === next.title;
+    return (current.canGoBack === next.canGoBack &&
+        current.title === next.title &&
+        JSON.stringify([
+            current.crumbs,
+            current.primary,
+            current.menu,
+            current.status,
+        ]) === JSON.stringify([next.crumbs, next.primary, next.menu, next.status]));
 }
 /** Whether any projected App window is still visible in the workspace. */
 export function hasVisibleWindows(projection) {
@@ -626,6 +633,17 @@ export function createWindowManager(options) {
         const requestBack = record.host?.requestBack;
         return requestBack ? await requestBack() : false;
     };
+    const activateNavigation = async (windowId, activation) => {
+        const record = records.get(windowId);
+        if (!record || !isActive(record) || record.status !== "ready")
+            return false;
+        // Only a crumb or enabled command the App currently publishes.
+        if (record.navigation === null ||
+            !navigationActivationAllowed(record.navigation, activation))
+            return false;
+        const deliver = record.host?.activateNavigation;
+        return deliver ? await deliver(activation) : false;
+    };
     const activateStatus = async (windowId, action) => {
         const record = records.get(windowId);
         if (!record || !isActive(record) || record.status !== "ready")
@@ -697,6 +715,7 @@ export function createWindowManager(options) {
         close,
         reconfigure,
         update,
+        activateNavigation,
         activateStatus,
         registerComputerChoice,
         replace,