@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/workers.d.ts

@@ -0,0 +1,352 @@
+import { type Installation } from "./apps/installation.js";
+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";
+import { ownerKeyAuth } from "./auth.js";
+import type { AppGitPushFact, GitBinding, GitPushQuestion, GitPushVerdict } from "@fungi.computer/agar/git";
+import { type OysterMcpOwner } from "./mcp-owner.js";
+export { createOysterMcpOwner, OysterMcpOwner, type OysterMcpOwnerEnv, type OysterMcpTenantPin, } from "./mcp-owner.js";
+import { type GuestLimits } from "./guest-policy.js";
+import { r2FileSource } from "./r2-files.js";
+import { type FileSource } from "./files.js";
+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 { 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 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 };
+/** 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. */
+export type OysterInvocationHost = BackgroundFrameState & Readonly<{
+    artifact: Backend;
+    declaration: AppDeclaration | null;
+    /** The verified declared method; opaque backend and lifecycle frames have none. */
+    method?: Readonly<{
+        name: string;
+    }>;
+}>;
+/** Existing fleet directory owner records, resolved by the host rather than App input. */
+export type OysterStorageAgentDirectory = 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>;
+    }>;
+}>;
+/** Bindings a standalone Oyster Worker declares in its Wrangler config. */
+export type OysterWorkerEnv = Readonly<{
+    /** 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?: OysterStorageAgentDirectory;
+    /** 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;
+}>;
+/** Store Release artifacts in an R2 bucket. */
+export declare function r2ArtifactStore(bucket: R2Bucket): ArtifactStore;
+/** The installation registry: one SQLite-backed Durable Object per Oyster. */
+export declare class OysterRegistry extends DurableObject<OysterWorkerEnv> {
+    #private;
+    /** 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);
+    /** 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. */
+    storageRead(installationId: string, ownerId: string, key: string): Promise<AppStorageResult<ResolvedAppStorage>>;
+    /** Write one declared key for the authenticated root owner. */
+    storageWrite(installationId: string, ownerId: string, input: AppStorageWrite): Promise<AppStorageResult<{
+        revision: number;
+    }>>;
+    /** Reset one declared layer for the authenticated root owner. */
+    storageReset(installationId: string, ownerId: string, input: AppStorageReset): Promise<AppStorageResult<{
+        revision: number;
+    }>>;
+    /** Storage for a live owner method frame; no guest-selected installation or member. */
+    storageBackend(raw: InvocationFacts, method: string, args: readonly unknown[], tenantId: TenantId): Promise<OysterBindingResult>;
+    /** Open the existing App-storage invalidation stream under fresh owner admission. */
+    storageEvents(installationId: string, ownerId: string, key: string): Promise<Response>;
+    private storageResult;
+    private storageOwner;
+    /**
+     * Resolve a stored creator against the live owner. The single-owner root's
+     * owner is the identity its owner key admits; tenant roots override this
+     * with their canonical membership.
+     */
+    protected currentOwner(memberId: string, tenantId: TenantId): Promise<string | null>;
+    private storageView;
+    /** 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>;
+    /** Native RPC returns a closed result; callers never classify a transported Error. */
+    compareAndPut(installation: Installation, expectedAuthorityVersion: number, tenantId?: TenantId): Promise<InstallationCommit>;
+    private writeInstallation;
+    private decode;
+}
+/** What a binding row may read from the Instance that owns the frame. */
+export type OysterBindingContext<Env> = Readonly<{
+    env: Env;
+    /** The tenant this Instance's host pinned at its first apply. */
+    scope(): TenantScope;
+    /** The root host that readmits background work, or `null` where it is refused. */
+    backgroundHost(): Promise<OysterHost | null>;
+}>;
+/**
+ * One guest binding: the frame codecs both sides of the RPC share, and the
+ * host owner that serves a decoded, granted packet under its captured frame.
+ */
+export type OysterBindingRow<Env> = Readonly<{
+    methods: Readonly<Record<string, FrameBindingMethod<OysterBindingResult>>>;
+    /** Serve one decoded packet; the Instance has already admitted its frame and grant. */
+    dispatch(context: OysterBindingContext<Env>, frame: InvocationFrame<OysterInvocationHost>, props: FrameBindingProps, method: string, args: readonly unknown[]): Promise<OysterBindingResult>;
+}>;
+/**
+ * The bindings an Instance serves, keyed by the closed App binding vocabulary;
+ * a missing row is `binding_unavailable`.
+ */
+export type OysterBindingTable<Env> = Readonly<{
+    APP_STORAGE?: OysterBindingRow<Env>;
+    APPS?: OysterBindingRow<Env>;
+    BACKGROUND?: OysterBindingRow<Env>;
+    GIT?: OysterBindingRow<Env>;
+    EVENTS?: OysterBindingRow<Env>;
+    INBOX?: OysterBindingRow<Env>;
+    AGENTS?: OysterBindingRow<Env>;
+    COMPUTER?: OysterBindingRow<Env>;
+    MEDIA?: OysterBindingRow<Env>;
+    WORKFLOWS?: OysterBindingRow<Env>;
+}>;
+/**
+ * The one guest binding entrypoint over `table`. Every binding in a frame is
+ * this export with its own props; each packet returns to its originating
+ * Instance, which serves it from the same table.
+ */
+export declare function oysterBindingEntrypoint<Env extends OysterWorkerEnv>(table: OysterBindingTable<Env>): typeof WorkerEntrypoint<Env, FrameBindingProps>;
+/** 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<{
+    /** 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<{
+    /** 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;
+}>, Readonly<{
+    instanceId: string;
+    binding: import("@fungi.computer/puffball/app").AppBackendBindingName;
+    frameId: string;
+}>>;
+/** The plain Oyster Worker's guest binding entrypoint. */
+export declare class OysterBinding extends OysterBinding_base {
+}
+/**
+ * One App Instance: Oyster's lifecycle supervisor in this Durable Object's
+ * SQLite and the App backend in its `app` facet.
+ */
+export declare class OysterInstance<Env extends OysterWorkerEnv = OysterWorkerEnv> extends DurableObject<Env> {
+    #private;
+    protected ctx: DurableObjectState<Record<never, never>> & Readonly<{
+        exports: Readonly<{
+            /** The root's one guest binding entrypoint; every binding name maps to it. */
+            OysterBinding(input: {
+                props: FrameBindingProps;
+            }): object;
+        }>;
+    }>;
+    /** The bindings this Instance serves; a root's Instance names its own table. */
+    protected readonly bindings: OysterBindingTable<Env>;
+    private runtime;
+    private limits;
+    private readonly frames;
+    /** Content-addressed backends are verified once per Instance, not per call. */
+    private readonly backends;
+    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;
+    /** Reconstruct current host admission for each wake; non-default tenants get no wakes. */
+    protected backgroundHost(): Promise<OysterHost | null>;
+    private localInstance;
+    private closeBackground;
+    private createRuntime;
+    private runtimeFor;
+    /** The tenant this Instance's host pinned at its first apply; never its guest frame. */
+    protected scope(): TenantScope;
+    private requireTenant;
+    /** The installation this Instance serves, once an owner state named it. */
+    protected installationId(): string | null;
+    /** Every binding name is the one entrypoint, routed by props; authority is checked per packet. */
+    private guestEnv;
+    /** Resolve each guest packet against its immutable frame before any host effect. */
+    bindingCall(raw: FrameBindingProps, method: string, input: readonly unknown[]): Promise<FrameBindingReply<OysterBindingResult>>;
+    private executeBindingCall;
+    /** Last provider-accepted ref recorded by this installation's journal. */
+    gitTip(installationId: string, repository: string, ref: string, tenantId?: TenantId): Promise<string | null>;
+    /** Join accepted fact identity and Carrier delivery in one local transaction. */
+    recordGitPush(installationId: string, fact: AppGitPushFact, tenantId?: TenantId): Promise<"recorded" | "duplicate">;
+    /** Carrier owns retries, dead letters and retained delivery receipts. */
+    alarm(): Promise<void>;
+    /** Installation changes end guest work; a Workflow cancel targets only its run. */
+    revoke(installationId: string, runId?: string, tenantId?: TenantId): Promise<void>;
+    /** One registry read re-admits a guest binding packet against its frame. */
+    private assertCurrent;
+    private withFrame;
+    private release;
+    /** Remember `release`, then apply the owner state 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>;
+    /** Deliver a Git push through the same selected-Instance admission as methods. */
+    onGitPush(facts: InvocationFacts, fact: AppGitPushFact, limits?: GuestLimits, tenantId?: TenantId): Promise<void>;
+    /** Ask the App's declared authorizer through the same frame-bound connection. */
+    authorizeGitPush(facts: InvocationFacts, question: GitPushQuestion, limits?: GuestLimits, tenantId?: TenantId): Promise<GitPushVerdict>;
+    /** An available lane settles a refusal under an active frame with no binding grants. */
+    syncRefused(facts: InvocationFacts, refusal: BackgroundSyncRefusal, limits?: GuestLimits, tenantId?: TenantId): Promise<void>;
+    /** Invoke a Release-declared Gill in a fresh immutable frame. */
+    gill(facts: InvocationFacts, _api: AppApi, source: string, input: GillCall, limits?: GuestLimits, tenantId?: TenantId): Promise<InstanceResult<GillReply>>;
+    /** Invoke one declared App method; the value is its AppMethodReply wire,
+     * which the host handle decodes. */
+    call(facts: InvocationFacts, _api: AppApi, name: string, input: OysterJson, limits?: GuestLimits, tenantId?: TenantId): Promise<InstanceResult<OysterJson>>;
+}
+/** One host-selected workspace shared by App context and capability adapters. */
+export type OysterWorkspace = Readonly<{
+    computerId: string;
+    files: FileSource;
+    /** Caller-scoped Computer calls; file-only workspaces omit it. */
+    computer?: OysterHost["computer"];
+}>;
+/** Host adapters for a standalone Oyster Worker over its own bindings. */
+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<{
+    /** 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;
+}>) => OysterMcpOwner<Readonly<{
+    /** 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;
+}>>;
+/** The non-git standalone root's MCP owner. */
+export declare class OysterMcp extends OysterMcp_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.
+ */
+export declare function createOysterWorker(options?: Pick<OysterHost, "guestLimits">): ExportedHandler<OysterWorkerEnv>;