@fungi.computer/oyster 0.2.0 → 0.3.1

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;

package/dist/page/app-access.js

@@ -0,0 +1,75 @@
+import { grantRequestFor, appPermissionPageSchema, } from "../apps/permissions.js";
+/**
+ * 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 function createShellAppAccess(directory) {
+    return async (target, input, dialog) => {
+        const { surfaceId, computerId } = target;
+        const current = await directory();
+        const app = current.apps.find((row) => row.surfaceId === surfaceId);
+        const installationId = app?.installationId ?? null;
+        const customize = () => dialog.customize(installationId);
+        if (installationId === null)
+            return customize();
+        const path = `/api/installations/${encodeURIComponent(installationId)}/grants`;
+        const response = await fetch(path, {
+            headers: { Accept: "application/json" },
+            credentials: "same-origin",
+            cache: "no-store",
+            redirect: "error",
+        });
+        if (!response.ok)
+            return "declined";
+        const view = appPermissionPageSchema.parse(await response.json());
+        const { permissions } = view;
+        const decision = grantRequestFor(permissions.authority, {
+            declaration: {
+                capabilities: permissions.declaredOperations.capabilities.map((row) => row.capability),
+            },
+            declaredOperations: permissions.declaredOperations,
+        }, input, { computerId });
+        if (decision.kind === "covered")
+            return "granted";
+        if (decision.kind === "refused") {
+            if (decision.code !== "window_scope_unavailable")
+                return "declined";
+            const outcome = await dialog.ask({
+                appName: view.appName,
+                agents: input.agents ?? [],
+                computers: input.computers ?? [],
+                refusal: {
+                    code: decision.code,
+                    message: "Allow for this window is unavailable on this Oyster. No access was changed. Use Customize to review Computer permissions explicitly.",
+                },
+                allow: () => Promise.resolve(false),
+            });
+            return outcome === "customize" ? customize() : outcome;
+        }
+        if (decision.kind === "customize")
+            return customize();
+        const outcome = await dialog.ask({
+            appName: view.appName,
+            agents: input.agents ?? [],
+            computers: input.computers ?? [],
+            allow: async () => {
+                const saved = await fetch(path, {
+                    method: "PUT",
+                    headers: { "Content-Type": "application/json" },
+                    credentials: "same-origin",
+                    cache: "no-store",
+                    redirect: "error",
+                    body: JSON.stringify({
+                        storeGeneration: view.storeGeneration,
+                        authorityVersion: permissions.authority.authorityVersion,
+                        artifactDigest: view.artifactDigest,
+                        command: decision.command,
+                    }),
+                });
+                return saved.ok;
+            },
+        });
+        // False saves settle declined; rejected saves leave the shell open for retry.
+        return outcome === "customize" ? customize() : outcome;
+    };
+}

package/dist/page/boot-host.js

@@ -0,0 +1,57 @@
+import { connectAppHost } from "@fungi.computer/agar/host";
+import { z } from "zod";
+import { bootUiSchema } from "../boot-gate.js";
+/**
+ * Trusted, zero-grant parent for a candidate entry. App readiness messages
+ * establish the ordinary Agar connection, never the boot-gate verdict.
+ */
+async function bootHost() {
+    const element = document.getElementById("boot-config");
+    if (element === null)
+        throw new Error("Host boot configuration unavailable");
+    const config = bootUiSchema
+        .pick({ identity: true })
+        .extend({ entry: z.url() })
+        .parse(JSON.parse(element.textContent));
+    const frame = document.getElementById("candidate");
+    if (!(frame instanceof HTMLIFrameElement) || frame.contentWindow === null)
+        throw new Error("Host candidate frame unavailable");
+    const denied = () => Promise.reject(new Error("No grants during host boot"));
+    const connection = connectAppHost({
+        appWindow: frame.contentWindow,
+        expectedAppOrigin: "null",
+        hostWindow: window,
+        launch: {
+            identity: config.identity,
+            capabilities: [],
+            context: {
+                version: 1,
+                value: {
+                    computerId: null,
+                    focus: { editing: false, surface: null },
+                    openRequest: null,
+                    visibility: "visible",
+                },
+            },
+            lifecycle: { version: 1, value: "connected" },
+            reservedChords: { version: 1, value: [] },
+            theme: { version: 1, value: "light" },
+        },
+        handlers: {
+            invokeReservedChord: denied,
+            onDisconnect: () => Promise.resolve(),
+            openNavigation: denied,
+            registerCommands: () => Promise.resolve({
+                update: () => undefined,
+                dispose: () => undefined,
+            }),
+            reportFocus: () => Promise.resolve(),
+            reportAgentSessionSelection: () => Promise.resolve(),
+            showToast: () => Promise.resolve(),
+        },
+    });
+    // Install the host connection listener before the candidate can announce ready.
+    frame.src = config.entry;
+    await connection;
+}
+await bootHost();

package/dist/page/capabilities.d.ts

@@ -5,7 +5,7 @@ import type { CapabilityDescriptor } from "../capability-descriptor.js";
 /** Agar's opaque host handle, shared by the page's exported factory contracts. */
 export type HostCapabilityHandle = AppHostLaunch["capabilities"][number]["handle"];
 /** Bind a page-local JSON caller; cancellation never enters serialized input. */
-export declare function capabilityJsonCaller(descriptor: CapabilityDescriptor, installationId: string): (method: string, raw?: unknown, options?: {
+export declare function capabilityJsonCaller(descriptor: CapabilityDescriptor, installationId: string, computerTarget?: string): (method: string, raw?: unknown, options?: {
     readonly signal?: AbortSignal;
 }) => Promise<import("zod").JSONType | undefined>;
 /** Local JSON calls carry cancellation separately from their serialized input. */
@@ -13,11 +13,11 @@ export type CapabilityJsonCaller = ReturnType<typeof capabilityJsonCaller>;
 /** Local factories may open only transports present in their descriptor. */
 export type CapabilityTransportOpener = (method: string, input?: Schema.Json) => WebSocket;
 /** Build the App's RPC handle from its admitted descriptor and installation. */
-export declare function capabilityHandle(descriptor: CapabilityDescriptor, installationId: string): HostCapabilityHandle;
+export declare function capabilityHandle(descriptor: CapabilityDescriptor, installationId: string, computerTarget?: string): HostCapabilityHandle;
 /** A supported contract may adapt local JSON calls into its App-facing handle. */
 export type CapabilityRegistration = Readonly<{
     contract: CapabilityContract<unknown>;
     createHandle?: (call: CapabilityJsonCaller, transport: CapabilityTransportOpener) => HostCapabilityHandle | Promise<HostCapabilityHandle>;
 }>;
 /** Create a registered handle, using the descriptor's ordinary RPC handle by default. */
-export declare function registeredCapabilityHandle(registration: CapabilityRegistration, descriptor: CapabilityDescriptor, installationId: string): Promise<HostCapabilityHandle>;
+export declare function registeredCapabilityHandle(registration: CapabilityRegistration, descriptor: CapabilityDescriptor, installationId: string, computerTarget?: string): Promise<HostCapabilityHandle>;

package/dist/page/capabilities.js

@@ -3,6 +3,7 @@ import { compile, parse, pathToRegexp } from "path-to-regexp";
 import * as Schema from "effect/Schema";
 import { AppError } from "@fungi.computer/agar";
 import { parseJsonValue } from "@fungi.computer/whistle/wire";
+import { computerTargetUrl } from "./computer-target.js";
 const queryInput = Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Number, Schema.Boolean]));
 const capabilityInputSchema = Schema.Union([Schema.Json, Schema.Undefined]);
 function resolveRoute(path, input) {
@@ -163,7 +164,7 @@ class TransportHandle extends RpcTarget {
         return Promise.resolve();
     }
 }
-function capabilityRequest(descriptor, installationId, route, raw) {
+function capabilityRequest(descriptor, installationId, route, raw, computerTarget) {
     const resolved = resolveRoute(route.path, raw);
     const input = resolved.input;
     const headers = new Headers({ "X-Oyster-Installation": installationId });
@@ -184,9 +185,12 @@ function capabilityRequest(descriptor, installationId, route, raw) {
     if (route.kind === "json" && route.method !== "GET") {
         headers.set("Content-Type", "application/json");
         init.body = JSON.stringify(input);
-        return { url, init };
+        return { url: computerTargetUrl(url, computerTarget), init };
     }
-    return { url: `${url}${query(input)}`, init };
+    return {
+        url: computerTargetUrl(`${url}${query(input)}`, computerTarget),
+        init,
+    };
 }
 async function jsonReply(url, init) {
     const response = await fetch(url, init);
@@ -196,7 +200,7 @@ async function jsonReply(url, init) {
     return parseJsonValue(await response.json());
 }
 /** Bind a page-local JSON caller; cancellation never enters serialized input. */
-export function capabilityJsonCaller(descriptor, installationId) {
+export function capabilityJsonCaller(descriptor, installationId, computerTarget) {
     return async (method, raw, options) => {
         const input = Schema.decodeUnknownSync(capabilityInputSchema)(raw);
         const route = descriptor.methods[method];
@@ -205,12 +209,12 @@ export function capabilityJsonCaller(descriptor, installationId) {
                 code: "INVALID_ARGUMENT",
                 retryable: false,
             });
-        const { url, init } = capabilityRequest(descriptor, installationId, route, input);
+        const { url, init } = capabilityRequest(descriptor, installationId, route, input, computerTarget);
         return jsonReply(url, { ...init, signal: options?.signal });
     };
 }
 /** Open a browser transport using the page's admitted installation. */
-function capabilityTransportOpener(descriptor, installationId) {
+function capabilityTransportOpener(descriptor, installationId, computerTarget) {
     return (method, raw) => {
         const route = descriptor.methods[method];
         if (route?.kind !== "transport" ||
@@ -219,7 +223,7 @@ function capabilityTransportOpener(descriptor, installationId) {
                 code: "INVALID_ARGUMENT",
                 retryable: false,
             });
-        const { url } = capabilityRequest(descriptor, installationId, route, Schema.decodeUnknownSync(capabilityInputSchema)(raw));
+        const { url } = capabilityRequest(descriptor, installationId, route, Schema.decodeUnknownSync(capabilityInputSchema)(raw), computerTarget);
         const target = new URL(url, "https://oyster.invalid");
         // Browser WebSockets cannot send the installation header used by Fetch.
         target.searchParams.set("oysterInstallation", installationId);
@@ -227,7 +231,7 @@ function capabilityTransportOpener(descriptor, installationId) {
     };
 }
 /** Build the App's RPC handle from its admitted descriptor and installation. */
-export function capabilityHandle(descriptor, installationId) {
+export function capabilityHandle(descriptor, installationId, computerTarget) {
     // Cap'n Web exposes prototype methods, never an instance's own properties.
     // Only input crosses RPC; AbortSignal options belong to the local caller.
     class CapabilityHandle extends RpcTarget {
@@ -236,7 +240,7 @@ export function capabilityHandle(descriptor, installationId) {
         name,
         async (raw) => {
             const input = Schema.decodeUnknownSync(capabilityInputSchema)(raw);
-            const { url, init } = capabilityRequest(descriptor, installationId, route, input);
+            const { url, init } = capabilityRequest(descriptor, installationId, route, input, computerTarget);
             if (route.kind === "read")
                 return new ReadHandle(url, init);
             if (route.kind === "write")
@@ -249,8 +253,8 @@ export function capabilityHandle(descriptor, installationId) {
     return new CapabilityHandle();
 }
 /** Create a registered handle, using the descriptor's ordinary RPC handle by default. */
-export async function registeredCapabilityHandle(registration, descriptor, installationId) {
+export async function registeredCapabilityHandle(registration, descriptor, installationId, computerTarget) {
     if (registration.createHandle === undefined)
-        return capabilityHandle(descriptor, installationId);
-    return await registration.createHandle(capabilityJsonCaller(descriptor, installationId), capabilityTransportOpener(descriptor, installationId));
+        return capabilityHandle(descriptor, installationId, computerTarget);
+    return await registration.createHandle(capabilityJsonCaller(descriptor, installationId, computerTarget), capabilityTransportOpener(descriptor, installationId, computerTarget));
 }

package/dist/page/computer-handles.d.ts

@@ -46,7 +46,7 @@ export declare class ComputerProcessesHandle extends RpcTarget implements Handle
         readonly startedAt: number;
         readonly state: "running" | "exited" | "uncertain";
         readonly exitCode: number | null;
-        readonly sync: "synced" | "pending" | "unknown";
+        readonly sync: "unknown" | "pending" | "synced";
         readonly endedAt: number | null;
     }>;
     list(): Promise<{
@@ -58,7 +58,7 @@ export declare class ComputerProcessesHandle extends RpcTarget implements Handle
             readonly startedAt: number;
             readonly state: "running" | "exited" | "uncertain";
             readonly exitCode: number | null;
-            readonly sync: "synced" | "pending" | "unknown";
+            readonly sync: "unknown" | "pending" | "synced";
             readonly endedAt: number | null;
         }[];
     }>;
@@ -71,7 +71,7 @@ export declare class ComputerProcessesHandle extends RpcTarget implements Handle
             readonly startedAt: number;
             readonly state: "running" | "exited" | "uncertain";
             readonly exitCode: number | null;
-            readonly sync: "synced" | "pending" | "unknown";
+            readonly sync: "unknown" | "pending" | "synced";
             readonly endedAt: number | null;
         };
         readonly signalled: boolean;

package/dist/page/computer-target.d.ts

@@ -0,0 +1,3 @@
+/** Serialize a window's routing hint. The server must admit it through the live
+ * owner and fleet before constructing that request's workspace. */
+export declare function computerTargetUrl(path: string, computerId?: string): string;

package/dist/page/computer-target.js

@@ -0,0 +1,9 @@
+/** Serialize a window's routing hint. The server must admit it through the live
+ * owner and fleet before constructing that request's workspace. */
+export function computerTargetUrl(path, computerId) {
+    if (computerId === undefined)
+        return path;
+    const url = new URL(path, "https://oyster.invalid");
+    url.searchParams.set("computerId", computerId);
+    return url.pathname + url.search;
+}

package/dist/page/mount.d.ts

@@ -1,7 +1,21 @@
 import { type AppOpenInput, type AppRoleChoice } from "@fungi.computer/agar/apps";
+import type { WhistleRuntime } from "@fungi.computer/whistle";
 import * as Schema from "effect/Schema";
+import { type CapabilityDirectory, type AgentSessionSelection } from "@fungi.computer/agar";
 import { type AppHost, type AppHostLaunch, type AppHostHandlers } from "@fungi.computer/agar/host";
 import type { WhistleJsonValue } from "@fungi.computer/whistle";
+/** One page-wide selected Session, using only its reporting App's admitted view. */
+export declare class OysterAgentBrowserHost {
+    #private;
+    /** End the selected connection with the page's own lifetime. */
+    constructor(signal: AbortSignal);
+    /** A departing or deselecting mount cannot close a different active mount. */
+    release(frame: HTMLIFrameElement): void;
+    /** Release the page's current selection; later reports cannot reconnect it. */
+    dispose(): void;
+    /** Bind the reporting mount's current command view to its explicitly selected Session. */
+    report(frame: HTMLIFrameElement, selection: AgentSessionSelection | null, capabilities: CapabilityDirectory, whistle: Pick<WhistleRuntime, "snapshot" | "execute">): Promise<void>;
+}
 /** Current server-admitted configuration for one installed App page. */
 export declare const oysterAppConfigSchema: Schema.Struct<{
     readonly workbench: Schema.Boolean;
@@ -32,7 +46,7 @@ export declare const oysterAppConfigSchema: Schema.Struct<{
             help?: Readonly<{
                 order?: number | undefined;
             }> | undefined;
-            menu? /** Which App that role's open would reach, or null when none fills it. */: Readonly<{
+            menu?: Readonly<{
                 order?: number | undefined;
             }> | undefined;
             palette?: Readonly<{
@@ -64,7 +78,7 @@ export declare const oysterAppConfigSchema: Schema.Struct<{
             help?: Readonly<{
                 order?: number | undefined;
             }> | undefined;
-            menu? /** Which App that role's open would reach, or null when none fills it. */: Readonly<{
+            menu?: Readonly<{
                 order?: number | undefined;
             }> | undefined;
             palette?: Readonly<{
@@ -141,6 +155,12 @@ export type OysterAppConfig = typeof oysterAppConfigSchema.Type;
 /** One isolated App connection, with the slots this host admitted for it. */
 export type OysterAppConnectionOptions = Readonly<{
     config: OysterAppConfig;
+    /** The page-wide selected Session owner shared by all child mounts. */
+    agentBrowser: OysterAgentBrowserHost;
+    /** The existing command owner's live, mount-scoped Agent view. */
+    agentCommands: Pick<WhistleRuntime, "snapshot" | "execute">;
+    /** An independently admitted per-window target; absent on fixed/default hosts. */
+    computerTarget?: string | undefined;
     frame: HTMLIFrameElement;
     signal: AbortSignal;
     handlers: AppHostHandlers;
@@ -156,4 +176,4 @@ export declare function connectOysterApp(options: OysterAppConnectionOptions): P
 export { oysterStorageHandle } from "./storage.js";
 export { appSandbox } from "../app-sandbox.js";
 /** Resolve only the slots admitted for this installation by its current host. */
-export declare function oysterAppCapabilities(options: Pick<OysterAppConnectionOptions, "config" | "signal" | "appOpen">): Promise<AppHostLaunch["capabilities"]>;
+export declare function oysterAppCapabilities(options: Pick<OysterAppConnectionOptions, "config" | "signal" | "appOpen" | "computerTarget">): Promise<AppHostLaunch["capabilities"]>;