@fungi.computer/oyster 0.2.0 → 0.3.1

package/dist/workers.d.ts

@@ -1,4 +1,12 @@
+import type { ApprovalListInput, ApprovalAnswerInput, AutoApproveInput } from "@fungi.computer/approvals";
+import type { HostActor } from "@fungi.computer/puffball/app";
+import { type OysterApprovalCall } from "./approval-home.js";
+import { type BootCapabilityGrant, type BootCapabilityLease } from "./boot-capability.js";
 import { type Installation } from "./apps/installation.js";
+import { type BrowserBinding } from "./browser/sessions.js";
+import { type InstallationOperationRequest, type InstallationOperationReply } from "./installation-operations.js";
+import { installationWorkerEntrypoint } from "./installation-execution.js";
+export { installationWorkerEntrypoint };
 import { type BackgroundSyncRefusal } from "@fungi.computer/puffball/background-replay";
 import { type TenantScope, type TenantId } from "./tenant.js";
 import { type GillCall, type GillReply } from "@fungi.computer/gills";
@@ -13,16 +21,15 @@ import { DurableObject, type WorkerEntrypoint } from "cloudflare:workers";
 import * as Schema from "effect/Schema";
 import type { Release } from "@fungi.computer/puffball";
 import { type Backend, type Instance, type OwnerState } from "./index.js";
-import { type FrameBindingReply, type FrameBindingMethod, type FrameBindingProps } from "./cloudflare.js";
+import { r2ArtifactStore, type FrameBindingReply, type FrameBindingMethod, type FrameBindingProps } from "./cloudflare.js";
 import { type BackgroundFrameState, type InvocationFacts, type InvocationFrame } from "./invocation.js";
 import { type InstallationCommit, type InstanceResult, type OysterAuth, type OysterHost, type OysterJson } from "./host.js";
 import { type AppStorageResult, type AppStorageWrite, type AppStorageReset, type ResolvedAppStorage } from "@fungi.computer/agar/storage";
 import { type OysterRootDirectory } from "./root-data.js";
-import { type ArtifactHeads, type ArtifactStore } from "./release.js";
 import type { AppApi } from "@fungi.computer/puffball";
 import type { AppDeclaration } from "@fungi.computer/puffball/app";
 import { createOysterAppSourceReceipts, createOysterAppRegistrations, createOysterArtifactsRepositoryMetadataStore } from "./app-sources.js";
-export { r2FileSource, ownerKeyAuth };
+export { r2ArtifactStore, r2FileSource, ownerKeyAuth };
 /** Native values returned by the standalone Git, event and JSON binding owners. */
 export type OysterBindingResult = Awaited<ReturnType<GitBinding[keyof GitBinding]>> | Schema.Json | undefined;
 /** Verified backend custody is captured in the frame, never in a current-context field. */
@@ -44,6 +51,8 @@ export type OysterStorageAgentDirectory = Readonly<{
 }>;
 /** Bindings a standalone Oyster Worker declares in its Wrangler config. */
 export type OysterWorkerEnv = Readonly<{
+    /** Cloudflare Browser Run binding for the UI boot check and the agent browser. */
+    BROWSER?: BrowserBinding;
     /** The owner's sign-in key, at least 24 characters (a secret). */
     OYSTER_OWNER_KEY: string;
     /** The single-tenant owner's identity, also recorded by the existing fleet creator. */
@@ -63,18 +72,120 @@ export type OysterWorkerEnv = Readonly<{
     /** Worker Loader that runs App backends. */
     LOADER: WorkerLoader;
 }>;
-/** Store Release artifacts in an R2 bucket. */
-export declare function r2ArtifactStore(bucket: R2Bucket): ArtifactStore & ArtifactHeads;
 /** The installation registry: one SQLite-backed Durable Object per Oyster. */
-export declare class OysterRegistry extends DurableObject<OysterWorkerEnv> {
+export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEnv> extends DurableObject<Env> {
     #private;
+    /** The plain root has the same single owner-key host as OysterInstance. */
+    protected hostFor(scope: TenantScope): Promise<OysterHost>;
+    /** Trusted host RPC; an operation input cannot select actor, namespace or tenant. */
+    approvalSubmit(pin: Readonly<{
+        tenantId: string;
+        origin: string;
+    }>, call: OysterApprovalCall): Promise<{
+        readonly kind: "pending_approval";
+        readonly recordId: string;
+        readonly description: {
+            readonly title: string;
+            readonly inputBytes: number;
+            readonly inputSha256: string;
+        };
+    } | import("@fungi.computer/approvals").ApprovalApplyResult>;
+    private approvalHome;
+    /** Recover approved work from the durable home, not a last-request memory pin. */
+    private approvalAlarm;
+    /** Read a bounded page for the current member of the pinned native home. */
+    approvalList(pin: Readonly<{
+        tenantId: string;
+        origin: string;
+    }>, actor: HostActor, input: ApprovalListInput): Promise<Readonly<{
+        items: readonly import("@fungi.computer/approvals").ApprovalView[];
+        nextCursor: string | null;
+    }>>;
+    /** Read one member-scoped view; the native home resolves membership again. */
+    approvalGet(pin: Readonly<{
+        tenantId: string;
+        origin: string;
+    }>, actor: HostActor, input: Readonly<{
+        recordId: string;
+    }>): Promise<{
+        readonly record: {
+            readonly revision: number;
+            readonly by: {
+                readonly kind: "human";
+                readonly memberId: string;
+            } | {
+                readonly kind: "policy";
+            } | null;
+            readonly description: {
+                readonly title: string;
+                readonly inputBytes: number;
+                readonly inputSha256: string;
+            };
+            readonly operation: string;
+            readonly access: "write" | "external";
+            readonly expiresAt: number;
+            readonly reason: "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict" | null;
+            readonly updatedAt: number;
+            readonly module: string;
+            readonly recordId: string;
+            readonly authorityFence: string;
+            readonly requester: {
+                readonly principalId: string;
+                readonly agentId: string | null;
+                readonly sessionId: string | null;
+                readonly displayName: string;
+            };
+            readonly reversibility: "reversible" | "irreversible-external";
+            readonly state: "pending" | "expired" | "denied" | "applied" | "requested" | "approved" | "claimed" | "outcome_unknown";
+            readonly requestedAt: number;
+            readonly evidence?: readonly {
+                readonly kind: "artifact";
+                readonly ref: string;
+                readonly mediaType: "image/png";
+                readonly bytes: number;
+            }[] | undefined;
+        };
+        readonly canAnswer: boolean;
+        readonly canSetAutoApprove: boolean;
+    } | null>;
+    /** Persist an eligible answer and attempt its native decision work once. */
+    approvalAnswer(pin: Readonly<{
+        tenantId: string;
+        origin: string;
+    }>, actor: HostActor, input: ApprovalAnswerInput): Promise<Readonly<{
+        kind: "refused";
+        reason: "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict";
+    }> | Readonly<{
+        kind: "answered";
+        view: import("@fungi.computer/approvals").ApprovalView;
+    }>>;
+    /** Policy never grants operation authority; only the live Oyster owner may change it. */
+    approvalSetAutoApprove(pin: Readonly<{
+        tenantId: string;
+        origin: string;
+    }>, actor: HostActor, input: AutoApproveInput): Promise<Readonly<{
+        kind: "refused";
+        reason: "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict";
+    }> | Readonly<{
+        kind: "updated";
+        rule: AutoApproveInput;
+    }>>;
     /** Append-only App source seed receipts; a Git-capable subclass forks over these. */
     protected readonly appSourceReceipts: ReturnType<typeof createOysterAppSourceReceipts>;
     /** Team-owned fork registrations, one App publisher record per App. */
     protected readonly appRegistrations: ReturnType<typeof createOysterAppRegistrations>;
     /** Durable Artifacts repository provenance for this Oyster's own fork compositions. */
     protected readonly artifactsRepositories: ReturnType<typeof createOysterArtifactsRepositoryMetadataStore>;
-    constructor(ctx: DurableObjectState, env: OysterWorkerEnv);
+    constructor(ctx: DurableObjectState, env: Env);
+    /** The installation owner's RPC: admit, read, load, plan or commit one
+     * retained command for the caller's tenant scope. */
+    installationOperation(input: InstallationOperationRequest): Promise<InstallationOperationReply>;
+    /**
+     * One Registry wake serves both owners: installation work, then the native
+     * approval home. Each re-arms only an earlier wake, so neither postpones the
+     * other, and one owner's failure never skips the other's quantum.
+     */
+    alarm(): Promise<void>;
     /** Current desktop metadata; roles are the ADR's derived default, never Hub's stored choice. */
     directory(): Promise<OysterRootDirectory>;
     /** Read one key for the authenticated root owner, under fresh App admission. */
@@ -100,16 +211,30 @@ export declare class OysterRegistry extends DurableObject<OysterWorkerEnv> {
      */
     protected currentOwner(memberId: string, tenantId: TenantId): Promise<string | null>;
     private storageView;
+    /** Whether this registry's data was written by Oyster 0.2 or earlier; hosts refuse it. */
+    storeFromOlderOyster(): boolean;
     /** Every installation record. */
     list(): Installation[];
     /** One installation record, or `null`. */
     get(installationId: string): Installation | null;
-    /** Create or replace one installation record. */
-    put(installation: Installation, tenantId?: TenantId): Promise<void>;
+    /** Durable store identity, regenerated only when the store itself is replaced. */
+    generation(): string;
     /** Native RPC returns a closed result; callers never classify a transported Error. */
-    compareAndPut(installation: Installation, expectedAuthorityVersion: number, tenantId?: TenantId): Promise<InstallationCommit>;
+    compareAndPut(installation: Installation, expectedAuthorityVersion: number, expectedGeneration: string, tenantId?: TenantId): Promise<InstallationCommit>;
     private writeInstallation;
     private decode;
+    /** Issue, resolve, or revoke one bounded capability without storing its token. */
+    bootCapability(input: Readonly<{
+        kind: "issue";
+        grant: BootCapabilityGrant;
+    }> | Readonly<{
+        kind: "resolve";
+        tokenDigest: string;
+        now: number;
+    }> | Readonly<{
+        kind: "revoke";
+        id: string;
+    }>): BootCapabilityLease | null | undefined;
 }
 /** What a binding row may read from the Instance that owns the frame. */
 export type OysterBindingContext<Env> = Readonly<{
@@ -153,6 +278,10 @@ export declare function oysterBindingEntrypoint<Env extends OysterWorkerEnv>(tab
 /** The plain Oyster host's bindings: App storage, the read-only catalog and replay admission. */
 export declare const oysterBindings: OysterBindingTable<OysterWorkerEnv>;
 declare const OysterBinding_base: abstract new (ctx: ExecutionContext, env: Readonly<{
+    /** Cloudflare Browser Run binding for the UI boot check and the agent browser. */
+    BROWSER?: Readonly<{
+        fetch: import("./browser/cdp-client.js").HttpFetch;
+    }>;
     /** The owner's sign-in key, at least 24 characters (a secret). */
     OYSTER_OWNER_KEY: string;
     /** The single-tenant owner's identity, also recorded by the existing fleet creator. */
@@ -178,6 +307,10 @@ declare const OysterBinding_base: abstract new (ctx: ExecutionContext, env: Read
     /** Worker Loader that runs App backends. */
     LOADER: WorkerLoader;
 }>) => WorkerEntrypoint<Readonly<{
+    /** Cloudflare Browser Run binding for the UI boot check and the agent browser. */
+    BROWSER?: Readonly<{
+        fetch: import("./browser/cdp-client.js").HttpFetch;
+    }>;
     /** The owner's sign-in key, at least 24 characters (a secret). */
     OYSTER_OWNER_KEY: string;
     /** The single-tenant owner's identity, also recorded by the existing fleet creator. */
@@ -234,7 +367,7 @@ export declare class OysterInstance<Env extends OysterWorkerEnv = OysterWorkerEn
     private readonly gitJournal;
     constructor(ctx: DurableObjectState, env: Env);
     /** The deployable root's host for one pinned tenant; this plain root is the single owner key. */
-    protected hostFor(scope: TenantScope): OysterHost;
+    protected hostFor(scope: TenantScope): Promise<OysterHost>;
     /** Reconstruct current host admission for each wake; non-default tenants get no wakes. */
     protected backgroundHost(): Promise<OysterHost | null>;
     private localInstance;
@@ -263,7 +396,10 @@ export declare class OysterInstance<Env extends OysterWorkerEnv = OysterWorkerEn
     private assertCurrent;
     private withFrame;
     private release;
-    /** Remember `release`, then apply the owner state under the host's tenant pin. */
+    private rememberRelease;
+    /** Reuse lifecycle preflight without changing the active runtime or its budgets. */
+    prepare(state: OwnerState, release: Release, limits?: GuestLimits, tenant?: Pick<TenantScope, "tenantId" | "origin">): Promise<InstanceResult<import("./boot-gate.js").UiBootCheckOutcome | null>>;
+    /** Activate the exact committed selection under the host's tenant pin. */
     apply(state: OwnerState, release: Release, limits: GuestLimits | undefined, tenant: Pick<TenantScope, "tenantId" | "origin">): Promise<InstanceResult<Instance>>;
     /** Forward an admitted HTTP request to the App backend. */
     backend(facts: InvocationFacts, request: Request, limits?: GuestLimits, tenantId?: TenantId): Promise<Response>;
@@ -286,12 +422,21 @@ export type OysterWorkspace = Readonly<{
     /** Caller-scoped Computer calls; file-only workspaces omit it. */
     computer?: OysterHost["computer"];
 }>;
-/** Host adapters for a standalone Oyster Worker over its own bindings. */
+/** Resolve a scoped boot URL through the registry-backed HTTPS asset route. */
+export declare function serveOysterBootCapability(request: Request, env: OysterWorkerEnv, scope: TenantScope): Promise<Response | null>;
+/**
+ * Create an Oyster host backed by this Worker environment's registry,
+ * artifacts, Instances, and boot-check service.
+ */
 export declare function oysterWorkerHost(env: OysterWorkerEnv, auth: OysterAuth, options?: Pick<OysterHost, "guestLimits" | "appToolPolicy"> & Readonly<{
     workspace?: OysterWorkspace;
     scope?: TenantScope;
 }>): OysterHost;
 declare const OysterMcp_base: new (ctx: DurableObjectState, env: Readonly<{
+    /** Cloudflare Browser Run binding for the UI boot check and the agent browser. */
+    BROWSER?: Readonly<{
+        fetch: import("./browser/cdp-client.js").HttpFetch;
+    }>;
     /** The owner's sign-in key, at least 24 characters (a secret). */
     OYSTER_OWNER_KEY: string;
     /** The single-tenant owner's identity, also recorded by the existing fleet creator. */
@@ -317,6 +462,10 @@ declare const OysterMcp_base: new (ctx: DurableObjectState, env: Readonly<{
     /** Worker Loader that runs App backends. */
     LOADER: WorkerLoader;
 }>) => OysterMcpOwner<Readonly<{
+    /** Cloudflare Browser Run binding for the UI boot check and the agent browser. */
+    BROWSER?: Readonly<{
+        fetch: import("./browser/cdp-client.js").HttpFetch;
+    }>;
     /** The owner's sign-in key, at least 24 characters (a secret). */
     OYSTER_OWNER_KEY: string;
     /** The single-tenant owner's identity, also recorded by the existing fleet creator. */
@@ -345,6 +494,70 @@ declare const OysterMcp_base: new (ctx: DurableObjectState, env: Readonly<{
 /** The non-git standalone root's MCP owner. */
 export declare class OysterMcp extends OysterMcp_base {
 }
+declare const OysterInstallationExecutor_base: new (ctx: ExecutionContext, env: Readonly<{
+    /** Cloudflare Browser Run binding for the UI boot check and the agent browser. */
+    BROWSER?: Readonly<{
+        fetch: import("./browser/cdp-client.js").HttpFetch;
+    }>;
+    /** The owner's sign-in key, at least 24 characters (a secret). */
+    OYSTER_OWNER_KEY: string;
+    /** The single-tenant owner's identity, also recorded by the existing fleet creator. */
+    OYSTER_OWNER_NAME?: string;
+    /** Optional existing fleet owner; absence grants no Agent storage authority. */
+    AGENT_DIRECTORY?: Readonly<{
+        /** Resolve the host-owned fleet directory by its existing durable name. */
+        getByName(name: string): Readonly<{
+            /** Return the recorded creator, or null when the Agent has no owner record. */
+            readCreator(agentId: string): Promise<string | null>;
+        }>;
+    }>;
+    /** Canonical configured origin; requests cannot choose the owner tenant. */
+    OYSTER_ORIGIN: string;
+    /** One tenant-scoped MCP session owner. Required when serving /mcp. */
+    MCP: DurableObjectNamespace<OysterMcpOwner>;
+    /** Release artifacts, keyed by artifact reference. */
+    RELEASES: R2Bucket;
+    /** The installation registry. */
+    REGISTRY: DurableObjectNamespace<OysterRegistry>;
+    /** One Durable Object per App Instance. */
+    INSTANCES: DurableObjectNamespace<OysterInstance>;
+    /** Worker Loader that runs App backends. */
+    LOADER: WorkerLoader;
+}>) => WorkerEntrypoint<Readonly<{
+    /** Cloudflare Browser Run binding for the UI boot check and the agent browser. */
+    BROWSER?: Readonly<{
+        fetch: import("./browser/cdp-client.js").HttpFetch;
+    }>;
+    /** The owner's sign-in key, at least 24 characters (a secret). */
+    OYSTER_OWNER_KEY: string;
+    /** The single-tenant owner's identity, also recorded by the existing fleet creator. */
+    OYSTER_OWNER_NAME?: string;
+    /** Optional existing fleet owner; absence grants no Agent storage authority. */
+    AGENT_DIRECTORY?: Readonly<{
+        /** Resolve the host-owned fleet directory by its existing durable name. */
+        getByName(name: string): Readonly<{
+            /** Return the recorded creator, or null when the Agent has no owner record. */
+            readCreator(agentId: string): Promise<string | null>;
+        }>;
+    }>;
+    /** Canonical configured origin; requests cannot choose the owner tenant. */
+    OYSTER_ORIGIN: string;
+    /** One tenant-scoped MCP session owner. Required when serving /mcp. */
+    MCP: DurableObjectNamespace<OysterMcpOwner>;
+    /** Release artifacts, keyed by artifact reference. */
+    RELEASES: R2Bucket;
+    /** The installation registry. */
+    REGISTRY: DurableObjectNamespace<OysterRegistry>;
+    /** One Durable Object per App Instance. */
+    INSTANCES: DurableObjectNamespace<OysterInstance>;
+    /** Worker Loader that runs App backends. */
+    LOADER: WorkerLoader;
+}>, unknown> & {
+    run(): Promise<import("./installation-operations.js").InstallationOutcome>;
+};
+/** Ordinary Worker execution; REGISTRY receives references and receipts only. */
+export declare class OysterInstallationExecutor extends OysterInstallationExecutor_base {
+}
 /**
  * The standalone Worker's `fetch` handler; frontend hosts are cached per env.
  * MCP transports belong to the tenant Durable Object, independent of that cache.