@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/mcp-owner.js

@@ -2,7 +2,6 @@ import { DurableObject } from "cloudflare:workers";
 import { nanoid } from "@fungi.computer/cairn";
 import { createCodemodeSandbox } from "@fungi.computer/mycelium/workers";
 import * as Schema from "effect/Schema";
-import { oysterMcpCatalogLoad } from "./mcp.js";
 import { tenantIdSchema, tenantScope } from "./tenant.js";
 /**
  * The MCP protocol SDK builds hundreds of schemas when it loads. Only the first
@@ -10,11 +9,12 @@ import { tenantIdSchema, tenantScope } from "./tenant.js";
  * (which every request and every deploy pays) never does.
  */
 const loadMcpProtocol = async () => {
-    const [mycelium, sdk] = await Promise.all([
+    const [mycelium, sdk, catalog] = await Promise.all([
         import("@fungi.computer/mycelium/mcp"),
         import("@modelcontextprotocol/server"),
+        import("./mcp.js"),
     ]);
-    return { mycelium, sdk };
+    return { mycelium, sdk, catalog };
 };
 const pinSchema = Schema.Struct({
     tenant_id: tenantIdSchema,
@@ -97,39 +97,47 @@ export class OysterMcpOwner extends DurableObject {
         else {
             sql.exec("INSERT INTO oyster_mcp_tenant (id, tenant_id, origin) VALUES (1,?,?)", scope.tenantId, scope.origin);
         }
-        // Loaded before the check so the session map is still created exactly once.
-        const protocol = await loadMcpProtocol();
         if (this.#mcp === undefined) {
-            const host = this.#createHost(this.env, scope);
-            const persistence = {
-                eventStore: (id) => this.#eventStore(id, protocol),
-                initialized: (id, session) => {
-                    sql.exec("INSERT INTO oyster_mcp_sessions (protocol_id, catalog_id, principal) VALUES (?,?,?)", id, session.id, JSON.stringify(session.principal));
-                    return Promise.resolve();
-                },
-                closed: (id, session) => {
-                    this.ctx.storage.transactionSync(() => {
-                        sql.exec("DELETE FROM oyster_mcp_events WHERE catalog_id=?", session.id);
-                        sql.exec("DELETE FROM oyster_mcp_sessions WHERE protocol_id=?", id);
-                    });
-                    return Promise.resolve();
-                },
-            };
-            this.#mcp = protocol.mycelium.createMcp({
-                persistence,
-                catalog: protocol.mycelium.createMcpCatalog({
-                    load: oysterMcpCatalogLoad(host),
-                    sandbox: createCodemodeSandbox(this.env.LOADER),
-                }),
-                authenticate: async (incoming) => {
-                    const admission = await host.auth.authenticate(incoming);
-                    return admission.kind === "refused"
-                        ? admission
-                        : { kind: "admitted", principal: admission.principal };
-                },
+            // Publish the flight before any await: live SDK sessions belong to one owner.
+            this.#mcp = loadMcpProtocol()
+                .then(async (protocol) => {
+                const host = await this.#createHost(this.env, scope);
+                const persistence = {
+                    eventStore: (id) => this.#eventStore(id, protocol),
+                    initialized: (id, session) => {
+                        sql.exec("INSERT INTO oyster_mcp_sessions (protocol_id, catalog_id, principal) VALUES (?,?,?)", id, session.id, JSON.stringify(session.principal));
+                        return Promise.resolve();
+                    },
+                    closed: (id, session) => {
+                        this.ctx.storage.transactionSync(() => {
+                            sql.exec("DELETE FROM oyster_mcp_events WHERE catalog_id=?", session.id);
+                            sql.exec("DELETE FROM oyster_mcp_sessions WHERE protocol_id=?", id);
+                        });
+                        return Promise.resolve();
+                    },
+                };
+                return protocol.mycelium.createMcp({
+                    persistence,
+                    catalog: protocol.mycelium.createMcpCatalog({
+                        // Each acquisition captures the current durable selection. Existing
+                        // operation handles retain the Computer captured by their own catalog.
+                        load: async (principal) => protocol.catalog.oysterMcpCatalogLoad(await this.#createHost(this.env, scope))(principal),
+                        sandbox: createCodemodeSandbox(this.env.LOADER),
+                    }),
+                    authenticate: async (incoming) => {
+                        const admission = await host.auth.authenticate(incoming);
+                        return admission.kind === "refused"
+                            ? admission
+                            : { kind: "admitted", principal: admission.principal };
+                    },
+                });
+            })
+                .catch((error) => {
+                this.#mcp = undefined;
+                throw error;
             });
         }
-        return this.#mcp.handleRequest(request);
+        return (await this.#mcp).handleRequest(request);
     }
 }
 /** Bind the owner to the deployment's existing host factory and options. */

package/dist/mcp.d.ts

@@ -1,6 +1,6 @@
 import { type AppToolPolicy } from "./apps/tools.js";
 import type { DeclaredOperations, Installation } from "./apps/installation.js";
-import { type CapabilitySource, type Grants } from "@fungi.computer/mycelium";
+import { type CapabilitySource, type Grants, type ModuleRegistration } from "@fungi.computer/mycelium";
 import { appToolSchemas } from "@fungi.computer/forage";
 import type { OysterHost, OysterPrincipal } from "./host.js";
 import type { McpPrincipal, McpCatalogSnapshot } from "@fungi.computer/mycelium/mcp";
@@ -52,6 +52,18 @@ export type ReleaseSurface = Readonly<{
 export type AppSurfaceCache = (release: Installation["release"]) => Promise<ReleaseSurface | null>;
 /** Make one {@link AppSurfaceCache} for a host whose artifact store and capabilities stay fixed. */
 export declare function appSurfaceCache(host: Pick<OysterHost, "artifacts" | "capabilities">): AppSurfaceCache;
+/** Derive the current principal's admitted App modules and grants. */
+export declare function oysterAppSnapshot(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys">, surfaces: AppSurfaceCache, principal: OysterPrincipal, installations: readonly Installation[], access: OysterCallerAccess, sessionId?: string, 
+/** Shares one tool-family listing per Instance across the two
+ * `appModules` passes one `oysterAppMethods` call can make (the eager
+ * grants/version pass, and a session-scoped re-derivation); never shared
+ * across separate calls, so it never serves another request's listing. */
+familyListingCache?: Map<string, unknown>): Promise<Readonly<{
+    modules: Readonly<Record<string, ModuleRegistration>>;
+    levels: Readonly<Record<string, AppToolPolicy["level"]>>;
+    fences: Readonly<Record<string, string>>;
+    effects: Readonly<Record<string, Readonly<Record<string, "read" | "write" | "external">>>>;
+}>>;
 /**
  * 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()`.
@@ -62,7 +74,7 @@ export declare function appSurfaceCache(host: Pick<OysterHost, "artifacts" | "ca
  * (`mycelium/src/access.ts`). Call again to capture changes to Releases,
  * installation authority or the caller's own grants.
  */
-export declare function oysterAppMethods(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys">, principal: OysterPrincipal, access: OysterCallerAccess, surfaces: AppSurfaceCache, preloadedInstallations?: readonly Installation[]): Promise<CapabilitySource & {
+export declare function oysterAppMethods(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys" | "approvals">, principal: OysterPrincipal, access: OysterCallerAccess, surfaces: AppSurfaceCache, preloadedInstallations?: readonly Installation[]): Promise<CapabilitySource & {
     readonly grants: Grants;
 }>;
 /**
@@ -86,4 +98,4 @@ export declare function oysterComputerTools(host: Pick<OysterHost, "computerId"
  * still re-admits the key, rechecks that same stored approval, and passes
  * the App's gate.
  */
-export declare function oysterMcpCatalogLoad(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "computer" | "capabilities" | "appToolPolicy" | "keys">): (principal: McpPrincipal) => Promise<McpCatalogSnapshot>;
+export declare function oysterMcpCatalogLoad(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "computer" | "capabilities" | "appToolPolicy" | "keys" | "workflows">): (principal: McpPrincipal) => Promise<McpCatalogSnapshot>;

package/dist/mcp.js

@@ -1,4 +1,9 @@
+import { z } from "zod";
+import { describeModule, invokeModuleOperation, } from "@fungi.computer/mycelium/remote";
+import { PendingApprovalSchema, ApprovalRefusalSchema, } from "@fungi.computer/approvals";
+import { jsonSchemaToZod } from "@fungi.computer/forage";
 import { admits } from "./apps/gate.js";
+import { createMcpWorkflowControl, WORKFLOW_CONTROL_MODULE_ID, } from "./workflows.js";
 import { causeClass } from "./cause-class.js";
 import { deriveDeclaredOperations } from "./apps/operations.js";
 import { appToolPolicySchema } from "./apps/tools.js";
@@ -77,18 +82,22 @@ export function appSurfaceCache(host) {
         return entry;
     };
 }
-async function appModules(host, surfaces, principal, installations, access, sessionId, 
+/** Derive the current principal's admitted App modules and grants. */
+export async function oysterAppSnapshot(host, surfaces, principal, installations, access, sessionId, 
 /** Shares one tool-family listing per Instance across the two
  * `appModules` passes one `oysterAppMethods` call can make (the eager
  * grants/version pass, and a session-scoped re-derivation); never shared
  * across separate calls, so it never serves another request's listing. */
 familyListingCache = new Map()) {
     const limits = guestLimits(host.guestLimits);
+    const generation = await host.installations.generation();
     const caller = invocationCallerContext(principal, host.computerId ?? null);
     const { actor } = principal;
     const visitor = actor.kind === "visitor";
     const modules = {};
     const levels = {};
+    const fences = {};
+    const effects = {};
     for (const installation of installations) {
         if (installation.status !== "enabled" || installation.instanceId === null)
             continue;
@@ -125,8 +134,8 @@ familyListingCache = new Map()) {
             signal?.throwIfAborted();
             if (currentInstallation?.status !== "enabled" ||
                 currentInstallation.instanceId !== instanceId ||
-                currentInstallation.authorityVersion !==
-                    installation.authorityVersion ||
+                currentInstallation.authority.authorityVersion !==
+                    installation.authority.authorityVersion ||
                 currentInstallation.release.releaseId !==
                     installation.release.releaseId ||
                 currentInstallation.release.artifact.artifactDigest !==
@@ -156,7 +165,13 @@ familyListingCache = new Map()) {
             signal?.throwIfAborted();
             const json = Schema.decodeUnknownSync(Schema.Json)(input);
             const decision = admits({
-                installation,
+                installation: {
+                    status: installation.status,
+                    visibility: installation.visibility,
+                    instanceId: installation.instanceId,
+                    authority: installation.authority,
+                    artifactDigest: installation.release.artifact.artifactDigest,
+                },
                 declaration,
                 declaredOperations,
                 api,
@@ -187,9 +202,13 @@ familyListingCache = new Map()) {
                 throw new AppMethodRefused(result.value.code, result.value.message);
             return result.value.value;
         };
+        const operationEffects = {};
+        effects[id] = operationEffects;
+        let familyFacts = null;
         const toolOperations = Object.entries(toolSchemas)
             .filter(([, method]) => !visitor || method.effect === "read")
             .map(([name, method]) => {
+            operationEffects[name] = method.effect;
             const appMethod = Mycelium.operation({
                 replay: "unsafe",
                 access: method.effect === "read" ? "read" : "write",
@@ -225,7 +244,10 @@ familyListingCache = new Map()) {
                     const compiled = appToolFamilySchemas(api, listing);
                     if (compiled === null)
                         return [];
+                    familyFacts = Schema.decodeUnknownSync(Schema.Json)(listing);
                     return compiled.tools.map((tool) => {
+                        operationEffects[compiled.name + "." + tool.row.tool] =
+                            compiled.effect;
                         const operation = Mycelium.operation({
                             replay: "unsafe",
                             access: compiled.effect === "read" ? "read" : "write",
@@ -274,6 +296,15 @@ familyListingCache = new Map()) {
                     return [];
                 }
             })();
+        fences[id] = await sha256(new TextEncoder().encode(JSON.stringify({
+            installation,
+            generation,
+            principal,
+            access: captured,
+            api,
+            family: familyFacts,
+            computerId: host.computerId ?? null,
+        })));
         modules[id] = Mycelium.module({
             id,
             name: appBindingName(installation.installationId),
@@ -281,7 +312,7 @@ familyListingCache = new Map()) {
             operations: Object.fromEntries([...toolOperations, ...familyOperations]),
         });
     }
-    return { modules, levels };
+    return { modules, levels, fences, effects };
 }
 function serializableAccess(access) {
     return access === null || access.kind === "agent"
@@ -307,8 +338,8 @@ export async function oysterAppMethods(host, principal, access, surfaces, preloa
     // Shared so a session-scoped re-derivation below reuses this call's tool-
     // family listings instead of asking each Instance for them twice.
     const familyListingCache = new Map();
-    const { modules: entries, levels } = await appModules(host, surfaces, principal, installations, access, undefined, familyListingCache);
-    const modules = Object.values(entries);
+    const initial = await oysterAppSnapshot(host, surfaces, principal, installations, access, undefined, familyListingCache);
+    const modules = admittedAppModules(host, principal, initial, null);
     const version = await sha256(new TextEncoder().encode(JSON.stringify({
         access: serializableAccess(access),
         installations: [...installations]
@@ -318,19 +349,19 @@ export async function oysterAppMethods(host, principal, access, surfaces, preloa
             installation.instanceId,
             installation.release.releaseId,
             installation.release.artifact.artifactDigest,
-            installation.authorityVersion,
+            installation.authority.authorityVersion,
             installation.status,
             installation.visibility,
         ]),
     })));
     return {
         id: "oyster-apps",
-        grants: levels,
+        grants: initial.levels,
         acquire: async ({ signal, session }) => {
             signal.throwIfAborted();
             const acquiredModules = session === undefined
                 ? modules
-                : Object.values((await appModules(host, surfaces, principal, installations, access, session.sessionId, familyListingCache)).modules);
+                : admittedAppModules(host, principal, await oysterAppSnapshot(host, surfaces, principal, installations, access, session.sessionId, familyListingCache), session.sessionId);
             signal.throwIfAborted();
             return {
                 snapshot: { version, modules: acquiredModules },
@@ -402,28 +433,118 @@ export function oysterMcpCatalogLoad(host) {
             access = { kind: "key", keyId: actor.keyId, byInstallation };
         }
         const apps = await oysterAppMethods(host, principal, access, surfaces, installations);
-        // Pre-approval ("never asked") is what a captured Agent/key policy
-        // itself grants; an owner's own calls, or an Agent/key with none, are
-        // never pre-approved even though their modules still default to the
-        // coarse "write" ceiling above.
-        const approvedWrites = access === null
-            ? []
-            : Object.entries(apps.grants)
-                .filter(([, level]) => level === "write")
-                .map(([id]) => id);
         const computer = await oysterComputerTools(host, principal);
+        const control = await host.workflows?.(principal);
+        const workflowSources = control == null
+            ? []
+            : [
+                {
+                    id: "oyster-workflows",
+                    acquire: () => Promise.resolve({
+                        snapshot: {
+                            version: WORKFLOW_CONTROL_MODULE_ID,
+                            modules: [createMcpWorkflowControl(control).module],
+                        },
+                        release: () => Promise.resolve(),
+                    }),
+                },
+            ];
+        const workflowGrants = control == null ? {} : { [WORKFLOW_CONTROL_MODULE_ID]: "write" };
         if (computer === null)
             return {
                 instructions: "Installed Apps on this Oyster. Each App is env.<APP>; dotted method names are nested properties, e.g. env.BONSAI.repos.list({}). Use forage.search / forage.describe to find methods.",
-                grants: apps.grants,
-                approvedWrites,
-                sources: [apps],
+                grants: { ...apps.grants, ...workflowGrants },
+                sources: [apps, ...workflowSources],
             };
         return {
             instructions: 'Installed Apps and this Oyster\'s Computer. Each App is env.<APP>; dotted method names are nested properties, e.g. env.BONSAI.repos.list({}). The Computer is env.computers.workspace, e.g. env.computers.workspace.exec({command: "ls"}). Use forage.search / forage.describe to find methods.',
-            grants: { ...apps.grants, ...computer.grants },
-            approvedWrites,
-            sources: [apps, computer],
+            grants: { ...apps.grants, ...computer.grants, ...workflowGrants },
+            sources: [apps, computer, ...workflowSources],
         };
     };
 }
+function admittedAppModules(host, principal, snapshot, sessionId) {
+    return Object.entries(snapshot.modules).map(([id, raw]) => {
+        const { description: moduleDescription, ...descriptor } = describeModule(raw);
+        const installationId = id.slice("oyster-app:".length);
+        const moduleMetadata = {};
+        if (moduleDescription !== undefined)
+            moduleMetadata.description = moduleDescription;
+        return Mycelium.module({
+            ...descriptor,
+            ...moduleMetadata,
+            id,
+            name: appBindingName(installationId),
+            operations: Object.fromEntries(Object.entries(descriptor.operations).map(([path, rawOperation]) => {
+                const { description: operationDescription, ...operation } = rawOperation;
+                const effect = snapshot.effects[id]?.[path];
+                const fence = snapshot.fences[id];
+                if (effect === undefined || fence === undefined)
+                    throw new Error("App snapshot has no operation authority facts");
+                const declaredOutput = operation.output ?? true;
+                // Decode each document at its own root before composing: a nested
+                // JSON Schema document's root-relative $refs would otherwise escape.
+                const declared = jsonSchemaToZod(declaredOutput);
+                const output = effect === "read"
+                    ? declared
+                    : z.union([
+                        declared,
+                        jsonSchemaToZod(Schema.toStandardJSONSchemaV1(PendingApprovalSchema)["~standard"].jsonSchema.output({ target: "draft-2020-12" })),
+                        jsonSchemaToZod(Schema.toStandardJSONSchemaV1(ApprovalRefusalSchema)["~standard"].jsonSchema.output({ target: "draft-2020-12" })),
+                    ]);
+                const outputValidator = z.intersection(output, z.json());
+                const operationMetadata = {};
+                if (operationDescription !== undefined)
+                    operationMetadata.description = operationDescription;
+                // App methods are never replayed by the host: a write goes through
+                // its approval record, and even a read may have App-side effects.
+                const appOperation = Mycelium.operation({
+                    ...operation,
+                    ...operationMetadata,
+                    replay: "unsafe",
+                    access: effect === "read" ? "read" : "write",
+                    input: z.intersection(jsonSchemaToZod(operation.input), z.json()),
+                    output: {
+                        "~standard": {
+                            ...outputValidator["~standard"],
+                            // As appMethodSchemas does, describe the JSON contract
+                            // without nesting another redundant recursive JSON guard.
+                            jsonSchema: output["~standard"].jsonSchema,
+                        },
+                    },
+                    execute: async (input, context) => {
+                        if (effect === "read")
+                            return z
+                                .json()
+                                .parse(await invokeModuleOperation(raw, path, input, context));
+                        if (principal.actor.kind === "visitor")
+                            return { kind: "refused", reason: "not-granted" };
+                        if (host.approvals === undefined)
+                            return { kind: "refused", reason: "not-granted" };
+                        // Mycelium numbers each operation call within one execute and
+                        // replays the same sequence; a direct call is its own execution.
+                        const ordinal = context.operationOrdinal ?? 0;
+                        const result = await host.approvals.submit({
+                            actor: principal.actor,
+                            installationId,
+                            sessionId,
+                            operation: path,
+                            access: effect,
+                            authorityFence: fence,
+                            idempotencyKey: await sha256(new TextEncoder().encode(JSON.stringify([
+                                context.executionId,
+                                context.toolCallId,
+                                ordinal,
+                            ]))),
+                            input,
+                        });
+                        return z
+                            .json()
+                            .parse(result.kind === "applied" ? result.output : result);
+                    },
+                });
+                return [path, appOperation];
+            })),
+        });
+    });
+}

package/dist/pack.d.ts

@@ -1,5 +1,8 @@
+import { type InstallationObservationBudget } from "./installation-client.js";
 import { type ArtifactRef, type Release } from "@fungi.computer/puffball";
 import { type AppPublisherCoreConfigInput } from "./build.js";
+import type { InstallationOperation } from "./installation-operations.js";
+export { InstallationObservationError } from "./installation-client.js";
 /** One committed repository and its canonical App build recipe. */
 export type PackOptions = Readonly<{
     /** The App's ID, `app_<name>`. */
@@ -32,6 +35,8 @@ export declare function packRelease(options: PackOptions): Promise<PackedRelease
  * Capture an Artifacts Git commit, build its Release, upload it to an Oyster,
  * and install it, or switch an existing installation to it
  * ({@link installRelease}).
+ * `waitMs` starts with the upload/observation phase after packing; a supplied
+ * caller signal retains its original lifetime through that phase.
  */
 export declare function installFromSource(input: Readonly<{
     appId: string;
@@ -49,11 +54,15 @@ export declare function installFromSource(input: Readonly<{
     /** Destination Oyster owner key; distinct from the source Git credential. */
     key: string;
     installationId: string;
-}>): Promise<Response>;
+}> & InstallationObservationBudget): Promise<Response>;
 /**
  * Upload a packed Release to an Oyster and install it. The host installs a
  * new installation (201) or switches an existing one to this Release (200),
- * keeping its state; both go through its one install-or-select owner.
+ * keeping its state. Uploads precede admission; this helper then waits for the
+ * correlated terminal owner receipt, not merely the HTTP acknowledgement.
+ * Uploads and observation share the caller signal or explicit `waitMs`; absent
+ * either, the installer owns a twenty-minute default. Expiry does not cancel
+ * admitted work and is reported as an unconfirmed observation, not refusal.
  */
 export declare function installRelease(input: Readonly<{
     directory: string;
@@ -61,7 +70,9 @@ export declare function installRelease(input: Readonly<{
     /** The Oyster owner key. */
     key: string;
     installationId?: string;
-}>): Promise<Response>;
+    /** Report owner-correlated admission without shortening the completion wait. */
+    onAdmitted?: (operation: InstallationOperation) => void;
+}> & InstallationObservationBudget): Promise<Response>;
 /** 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

package/dist/pack.js

@@ -4,11 +4,13 @@ import { join, relative, resolve } from "node:path";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { releaseSchema } from "@fungi.computer/puffball/effect";
+import { installOnOyster, installationObservationSignal, completedInstallationResponse, } from "./installation-client.js";
 import { parseArtifactRef, parseReleaseId, parseSha256Digest, parseSourceRevision, } from "@fungi.computer/puffball";
 import { commitPreparedCandidate, createAppCandidatePreparer, createArtifactsSourceCapture, createFirstPartyAppSourceDistribution, createLocalArtifactWriter, createLocalBuildExecutor, createLocalCommitSourceCapture, normalizeAppPublisherRecipe, } from "./build.js";
 import { templateSeedClaimSchema, } from "./source/template-seed.js";
 import { pushTemplateSource } from "./source/template-push.js";
 import { sha256 } from "./release.js";
+export { InstallationObservationError } from "./installation-client.js";
 async function filesUnder(directory) {
     const entries = await readdir(directory, {
         recursive: true,
@@ -26,9 +28,9 @@ async function packCapturedSource(options, sourceCapture) {
     const preparer = createAppCandidatePreparer({
         config: { appId: options.appId, recipe: options.recipe },
         sourceCapture,
-        buildExecutor: createLocalBuildExecutor({
-            packageStoreDirectory: options.packageStoreDirectory,
-        }),
+        buildExecutor: createLocalBuildExecutor(options.packageStoreDirectory === undefined
+            ? {}
+            : { packageStoreDirectory: options.packageStoreDirectory }),
     });
     const prepared = await Effect.runPromise(Effect.scoped(preparer.prepareCandidate(parseReleaseId(options.releaseId ??
         `rel_${revision.slice("git:".length, "git:".length + 12)}`))));
@@ -52,27 +54,40 @@ export async function packRelease(options) {
  * Capture an Artifacts Git commit, build its Release, upload it to an Oyster,
  * and install it, or switch an existing installation to it
  * ({@link installRelease}).
+ * `waitMs` starts with the upload/observation phase after packing; a supplied
+ * caller signal retains its original lifetime through that phase.
  */
 export async function installFromSource(input) {
     const outDirectory = await mkdtemp(join(tmpdir(), "oyster-source-release-"));
     try {
-        await packCapturedSource({
+        let options = {
             appId: input.appId,
-            releaseId: input.releaseId,
             recipe: input.recipe,
             sourceRevision: input.source.sourceRevision,
-            packageStoreDirectory: input.packageStoreDirectory,
             outDirectory,
-        }, createArtifactsSourceCapture({
+        };
+        if (input.releaseId !== undefined)
+            options = { ...options, releaseId: input.releaseId };
+        if (input.packageStoreDirectory !== undefined)
+            options = {
+                ...options,
+                packageStoreDirectory: input.packageStoreDirectory,
+            };
+        await packCapturedSource(options, createArtifactsSourceCapture({
             ...input.source,
             sourceRevision: parseSourceRevision(input.source.sourceRevision),
         }));
-        return await installRelease({
+        let installation = {
             directory: outDirectory,
             url: input.url,
             key: input.key,
             installationId: input.installationId,
-        });
+        };
+        if (input.waitMs !== undefined)
+            installation = { ...installation, waitMs: input.waitMs };
+        if (input.signal !== undefined)
+            installation = { ...installation, signal: input.signal };
+        return await installRelease(installation);
     }
     finally {
         await rm(outDirectory, { recursive: true, force: true });
@@ -81,9 +96,16 @@ export async function installFromSource(input) {
 /**
  * Upload a packed Release to an Oyster and install it. The host installs a
  * new installation (201) or switches an existing one to this Release (200),
- * keeping its state; both go through its one install-or-select owner.
+ * keeping its state. Uploads precede admission; this helper then waits for the
+ * correlated terminal owner receipt, not merely the HTTP acknowledgement.
+ * Uploads and observation share the caller signal or explicit `waitMs`; absent
+ * either, the installer owns a twenty-minute default. Expiry does not cancel
+ * admitted work and is reported as an unconfirmed observation, not refusal.
  */
 export async function installRelease(input) {
+    // One installer budget for uploads + observation, not an App authority grant.
+    const signal = installationObservationSignal(input);
+    signal.throwIfAborted();
     const directory = resolve(input.directory);
     const release = Schema.decodeUnknownSync(Schema.fromJsonString(releaseSchema))(await readFile(join(directory, "release.json"), "utf8"));
     const authorization = { Authorization: `Bearer ${input.key}` };
@@ -91,18 +113,21 @@ export async function installRelease(input) {
         const bytes = new Uint8Array(await readFile(file));
         const artifactRef = `artifact:${relative(join(directory, "artifacts"), file)}`;
         const digest = parseSha256Digest(await sha256(bytes));
-        const response = await fetch(new URL(`/api/artifacts/${encodeURIComponent(artifactRef)}?digest=${digest}`, input.url), { method: "PUT", headers: authorization, body: bytes });
+        const response = await fetch(new URL(`/api/artifacts/${encodeURIComponent(artifactRef)}?digest=${digest}`, input.url), { method: "PUT", headers: authorization, body: bytes, signal });
         if (!response.ok)
             throw new Error(`Artifact upload failed (${String(response.status)}): ${artifactRef}`);
     }
-    return fetch(new URL("/api/installations", input.url), {
-        method: "POST",
-        headers: { ...authorization, "Content-Type": "application/json" },
-        body: JSON.stringify({
-            release: Schema.encodeUnknownSync(releaseSchema)(release),
-            installationId: input.installationId,
-        }),
-    });
+    let installation = {
+        url: input.url,
+        key: input.key,
+        release,
+        installationId: input.installationId ?? release.appId.replaceAll("_", "-"),
+        signal,
+    };
+    if (input.onAdmitted !== undefined)
+        installation = { ...installation, onAdmitted: input.onAdmitted };
+    const operation = await installOnOyster(installation);
+    return completedInstallationResponse(operation);
 }
 /** 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

package/dist/page/app-access.d.ts

@@ -0,0 +1,7 @@
+import type { RequestShellAppAccess } from "@fungi.computer/nacre/shell-module";
+import type { WorkbenchDirectory } from "@fungi.computer/nacre/workbench-directory";
+/**
+ * Keep standalone consent in the Oyster host: the picked shell draws the
+ * prompt, while Oyster bounds the request and commits through its owner CAS.
+ */
+export declare function createShellAppAccess(directory: () => Promise<WorkbenchDirectory>): RequestShellAppAccess;