workers

Import

Import

import * as api from "@fungi.computer/oyster/workers";

Exports

Kind	Export	Description
Cclass	OysterMcpOwner	One tenant’s live SDK transports; cold owners refuse old IDs without execution replay. The persisted origin is a lifetime pin. Changing the configured origin requires a fresh MCP namespace; an existing owner never retargets its retained pin.
Cclass	OysterRegistry	The installation registry: one SQLite-backed Durable Object per Oyster.
Cclass	OysterBinding	The plain Oyster Worker’s guest binding entrypoint.
Cclass	OysterInstance	One App Instance: Oyster’s lifecycle supervisor in this Durable Object’s SQLite and the App backend in its app facet.
Cclass	OysterMcp	The non-git standalone root’s MCP owner.
Cclass	OysterInstallationExecutor	Ordinary Worker execution; REGISTRY receives references and receipts only.
Ttype alias	OysterMcpOwnerEnv	Worker Loader used by the existing Mycelium sandbox.
Ttype alias	OysterMcpTenantPin	Serialized trusted tenant pin supplied by the selected host.
Ttype alias	OysterBindingResult	Native values returned by the standalone Git, event and JSON binding owners.
Ttype alias	OysterInvocationHost	Verified backend custody is captured in the frame, never in a current-context field.
Ttype alias	OysterStorageAgentDirectory	Existing fleet directory owner records, resolved by the host rather than App input.
Ttype alias	OysterWorkerEnv	Bindings a standalone Oyster Worker declares in its Wrangler config.
Ttype alias	OysterBindingContext	What a binding row may read from the Instance that owns the frame.
Ttype alias	OysterBindingRow	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.
Ttype alias	OysterBindingTable	The bindings an Instance serves, keyed by the closed App binding vocabulary; a missing row is binding_unavailable.
Ttype alias	OysterWorkspace	One host-selected workspace shared by App context and capability adapters.
constconstant	oysterBindings	The plain Oyster host’s bindings: App storage, the read-only catalog and replay admission.
fnfunction	installationWorkerEntrypoint()	A loopback export with ordinary Worker I/O, not another resource or HTTP API.
fnfunction	createOysterMcpOwner()	Bind the owner to the deployment’s existing host factory and options.
fnfunction	r2FileSource()	Files in an R2 bucket under prefix (one workspace per prefix).
fnfunction	oysterBindingEntrypoint()	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.
fnfunction	serveOysterBootCapability()	Resolve a scoped boot URL through the registry-backed HTTPS asset route.
fnfunction	oysterWorkerHost()	Create an Oyster host backed by this Worker environment’s registry, artifacts, Instances, and boot-check service.
fnfunction	createOysterWorker()	The standalone Worker’s fetch handler; frontend hosts are cached per env. MCP transports belong to the tenant Durable Object, independent of that cache.

OysterMcpOwnerCclass

One tenant’s live SDK transports; cold owners refuse old IDs without execution replay. The persisted origin is a lifetime pin. Changing the configured origin requires a fresh MCP namespace; an existing owner never retargets its retained pin.

Extends

• DurableObject<Env>

Extended by

• OysterMcp

Type Parameters

Type Parameter	Default type
Env extends OysterMcpOwnerEnv	OysterMcpOwnerEnv

Constructors

Constructor

Signature

new OysterMcpOwner<Env>(
   ctx,
   env,
   createHost
): OysterMcpOwner<Env>;

Parameters

Parameter	Type
ctx	DurableObjectState
env	Env
createHost	(env, scope) => | Readonly<{ approvals?: Readonly<{ submit: Promise< | { kind: "pending_approval"; recordId: string; description: { title: …; inputBytes: …; inputSha256: …; }; } | ApprovalApplyResult>; }>; workflows?: (principal) => Promise< | Readonly<{ status: Promise<…>; cancel: Promise<…>; }> | null>; computerControl?: (principal) => | Readonly<{ list: Promise<{ computers: …; nextOffset: …; }>; state: Promise<… | …>; start: Promise<… | …>; create: Promise<… | …>; }> | null; auth: OysterAuth; backgroundOriginKey?: () => Promise<CryptoKey>; artifacts: ArtifactStore; uiCache?: Readonly<{ match: (digest) => Promise<ReadableStream<…> | null>; put: (digest, bytes) => Promise<"stored" | "unstored">; }>; installations: InstallationStore; instances: InstanceDirectory; bootUi: (release) => Promise< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: … | … | … | … | …; errorName?: … | … | … | … | … | … | … | …; finalUrlPath: string; consoleErrors: …[]; pageErrors: …[]; failedRequests: …[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; }>; computerId?: string; computer?: (principal) => | Readonly<{ getCapabilities: (signal) => Promise<…>; call: (capabilityId, input, context) => Promise<…>; }> | Promise< | Readonly<{ getCapabilities: …; call: …; }> | null> | null; appToolPolicy?: (actor) => | { level: "read" | "write"; revision: string; grantedBy: string; } | Promise< | { level: … | …; revision: string; grantedBy: string; } | null> | null; keys?: Readonly<{ live: Promise< | Readonly<{ keyId: …; owner: …; grantVersion: …; grants: …; }> | null>; }>; guestLimits?: Partial<Readonly<{ cpuMs: number; subRequests: number; }>>; mcp?: Readonly<{ handleRequest: (request) => Promise<Response>; close?: () => Promise<void>; }>; git?: Readonly<{ writerOf: Extract<GitWriter, { kind: "actor"; }>; workflowPass?: Promise< | Readonly<{ kind: …; actor: …; role?: …; workflow?: …; }> | null>; buildPass?: Promise< | Readonly<{ kind: …; actor: …; role?: …; workflow?: …; }> | null>; git: Promise<Readonly<{ push: Promise<…>; read: Promise<…>; binding: GitBinding; }>>; }>; ownerRoutes?: Hono<OysterEnv, BlankSchema, "/">; capabilities?: readonly Readonly<object & object>[]; workbench?: Readonly<{ directory: Promise<Readonly<{ apps: readonly …[]; roles: OysterRootRoles; computer?: … | …; }>>; storage: Pick<AppStorageWire, "read" | "write" | "reset"> & Readonly<{ events: Promise<…>; }>; }>; homeInstallationId?: string; pageScript?: string; pageAssets?: () => Promise<{ pageScript: string; publicHomeScript: string; fontStyles: string; loginFontStyles: string; shellStyles: string; grantConsentScript: string; }>; title?: string; }> | Promise<Readonly<{ approvals?: Readonly<{ submit: Promise< | { kind: …; recordId: …; description: …; } | ApprovalApplyResult>; }>; workflows?: (principal) => Promise< | Readonly<{ status: …; cancel: …; }> | null>; computerControl?: (principal) => | Readonly<{ list: Promise<…>; state: Promise<…>; start: Promise<…>; create: Promise<…>; }> | null; auth: OysterAuth; backgroundOriginKey?: () => Promise<CryptoKey>; artifacts: ArtifactStore; uiCache?: Readonly<{ match: (digest) => Promise<… | …>; put: (digest, bytes) => Promise<… | …>; }>; installations: InstallationStore; instances: InstanceDirectory; bootUi: (release) => Promise< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: …; errorName?: …; finalUrlPath: …; consoleErrors: …; pageErrors: …; failedRequests: …; droppedCount: …; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; }>; computerId?: string; computer?: (principal) => | Readonly<{ getCapabilities: (signal) => …; call: (capabilityId, input, context) => …; }> | Promise<Readonly<…> | null> | null; appToolPolicy?: (actor) => | { level: "read" | "write"; revision: string; grantedBy: string; } | Promise< | { level: …; revision: …; grantedBy: …; } | null> | null; keys?: Readonly<{ live: Promise<Readonly<…> | null>; }>; guestLimits?: Partial<Readonly<{ cpuMs: number; subRequests: number; }>>; mcp?: Readonly<{ handleRequest: (request) => Promise<Response>; close?: () => Promise<…>; }>; git?: Readonly<{ writerOf: Extract<GitWriter, { kind: "actor"; }>; workflowPass?: Promise<Readonly<…> | null>; buildPass?: Promise<Readonly<…> | null>; git: Promise<Readonly<{ push: …; read: …; binding: …; }>>; }>; ownerRoutes?: Hono<OysterEnv, BlankSchema, "/">; capabilities?: readonly Readonly<object & object>[]; workbench?: Readonly<{ directory: Promise<Readonly<{ apps: …; roles: …; computer?: …; }>>; storage: Pick<AppStorageWire, … | … | …> & Readonly<{ events: …; }>; }>; homeInstallationId?: string; pageScript?: string; pageAssets?: () => Promise<{ pageScript: string; publicHomeScript: string; fontStyles: string; loginFontStyles: string; shellStyles: string; grantConsentScript: string; }>; title?: string; }>>

Returns

OysterMcpOwner<Env>

Overrides

Signature

DurableObject<Env>.constructor

Methods

serve()

Signature

serve(request, tenant): Promise<Response>;

Trusted host RPC: the namespace and pin are never selected by guest headers.

Parameters

Parameter	Type
request	Request
tenant	OysterMcpTenantPin

Returns

Promise<Response>

---

OysterRegistryCclass

The installation registry: one SQLite-backed Durable Object per Oyster.

Extends

• DurableObject<Env>

Type Parameters

Type Parameter	Default type
Env extends OysterWorkerEnv	OysterWorkerEnv

Constructors

Constructor

Signature

new OysterRegistry<Env>(ctx, env): OysterRegistry<Env>;

Parameters

Parameter	Type
ctx	DurableObjectState
env	Env

Returns

OysterRegistry<Env>

Overrides

Signature

DurableObject<Env>.constructor

Methods

approvalSubmit()

Signature

approvalSubmit(pin, call): Promise<
  | {
  kind: "pending_approval";
  recordId: string;
  description: {
     title: string;
     inputBytes: number;
     inputSha256: string;
  };
}
| ApprovalApplyResult>;

Trusted host RPC; an operation input cannot select actor, namespace or tenant.

Parameters

Parameter	Type
pin	Readonly<{ tenantId: string; origin: string; }>
call	{ actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; installationId: string; sessionId: string | null; operation: string; access: "write" | "external"; authorityFence: string; idempotencyKey: string; input: JSONType; }
call.actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }
call.installationId	string
call.sessionId	string | null
call.operation	string
call.access	"write" | "external"
call.authorityFence	string
call.idempotencyKey	string
call.input	JSONType

Returns

Promise< | { kind: "pending_approval"; recordId: string; description: { title: string; inputBytes: number; inputSha256: string; }; } | ApprovalApplyResult>

approvalList()

Signature

approvalList(
   pin,
   actor,
   input
): Promise<Readonly<{
  items: readonly object[];
  nextCursor: string | null;
}>>;

Read a bounded page for the current member of the pinned native home.

Parameters

Parameter	Type
pin	Readonly<{ tenantId: string; origin: string; }>
actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }
input	{ state?: | "pending" | "expired" | "denied" | "applied" | "requested" | "approved" | "claimed" | "outcome_unknown"; cursor?: string; limit?: number; }
input.state?	| "pending" | "expired" | "denied" | "applied" | "requested" | "approved" | "claimed" | "outcome_unknown"
input.cursor?	string
input.limit?	number

Returns

Promise<Readonly<{ items: readonly object[]; nextCursor: string | null; }>>

approvalGet()

Signature

approvalGet(
   pin,
   actor,
   input
): Promise<
  | {
  record: {
     recordId: string;
     requester: {
        principalId: string;
        agentId: string | null;
        sessionId: string | null;
        displayName: string;
     };
     module: string;
     operation: string;
     access: "write" | "external";
     description: {
        title: string;
        inputBytes: number;
        inputSha256: string;
     };
     evidence?: readonly object[];
     authorityFence: string;
     reversibility: "reversible" | "irreversible-external";
     state:   | "pending"
        | "expired"
        | "denied"
        | "applied"
        | "requested"
        | "approved"
        | "claimed"
        | "outcome_unknown";
     by:   | {
        kind: "human";
        memberId: string;
      }
        | {
        kind: "policy";
      }
        | null;
     reason:   | "pending"
        | "expired"
        | "not-found"
        | "not-eligible"
        | "already-answered"
        | "stale-revision"
        | "declined"
        | "fenced"
        | "not-granted"
        | "read-only"
        | "in-flight"
        | "outcome-unknown"
        | "identity-conflict"
        | null;
     denialNote?: string;
     requestedAt: number;
     expiresAt: number;
     updatedAt: number;
     revision: number;
  };
  canAnswer: boolean;
  canSetAutoApprove: boolean;
}
| null>;

Read one member-scoped view; the native home resolves membership again.

Parameters

Parameter	Type
pin	Readonly<{ tenantId: string; origin: string; }>
actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }
input	Readonly<{ recordId: string; }>

Returns

Promise< | { record: { recordId: string; requester: { principalId: string; agentId: string | null; sessionId: string | null; displayName: string; }; module: string; operation: string; access: "write" | "external"; description: { title: string; inputBytes: number; inputSha256: string; }; evidence?: readonly object[]; authorityFence: string; reversibility: "reversible" | "irreversible-external"; state: | "pending" | "expired" | "denied" | "applied" | "requested" | "approved" | "claimed" | "outcome_unknown"; by: | { kind: "human"; memberId: string; } | { kind: "policy"; } | null; reason: | "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict" | null; denialNote?: string; requestedAt: number; expiresAt: number; updatedAt: number; revision: number; }; canAnswer: boolean; canSetAutoApprove: boolean; } | null>

approvalAnswer()

Signature

approvalAnswer(
   pin,
   actor,
   input
): Promise<
  | Readonly<{
  kind: "answered";
  view: {
     record: {
        recordId: string;
        requester: {
           principalId: string;
           agentId: string | null;
           sessionId: string | null;
           displayName: string;
        };
        module: string;
        operation: string;
        access: "write" | "external";
        description: {
           title: string;
           inputBytes: number;
           inputSha256: string;
        };
        evidence?: readonly object[];
        authorityFence: string;
        reversibility: "reversible" | "irreversible-external";
        state:   | "pending"
           | "expired"
           | "denied"
           | "applied"
           | "requested"
           | "approved"
           | "claimed"
           | "outcome_unknown";
        by:   | {
           kind: "human";
           memberId: string;
         }
           | {
           kind: "policy";
         }
           | null;
        reason:   | "pending"
           | "expired"
           | "not-found"
           | "not-eligible"
           | "already-answered"
           | "stale-revision"
           | "declined"
           | "fenced"
           | "not-granted"
           | "read-only"
           | "in-flight"
           | "outcome-unknown"
           | "identity-conflict"
           | null;
        denialNote?: string;
        requestedAt: number;
        expiresAt: number;
        updatedAt: number;
        revision: number;
     };
     canAnswer: boolean;
     canSetAutoApprove: boolean;
  };
}>
  | 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";
  denialNote?: string;
}>>;

Persist an eligible answer and attempt its native decision work once.

Parameters

Parameter	Type
pin	Readonly<{ tenantId: string; origin: string; }>
actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }
input	{ recordId: string; decision: "approve" | "deny"; expectedRevision: number; denialNote?: string; }
input.recordId	string
input.decision	"approve" | "deny"
input.expectedRevision	number
input.denialNote?	string

Returns

Promise< | Readonly<{ kind: "answered"; view: { record: { recordId: string; requester: { principalId: string; agentId: string | null; sessionId: string | null; displayName: string; }; module: string; operation: string; access: "write" | "external"; description: { title: string; inputBytes: number; inputSha256: string; }; evidence?: readonly object[]; authorityFence: string; reversibility: "reversible" | "irreversible-external"; state: | "pending" | "expired" | "denied" | "applied" | "requested" | "approved" | "claimed" | "outcome_unknown"; by: | { kind: "human"; memberId: string; } | { kind: "policy"; } | null; reason: | "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict" | null; denialNote?: string; requestedAt: number; expiresAt: number; updatedAt: number; revision: number; }; canAnswer: boolean; canSetAutoApprove: boolean; }; }> | 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"; denialNote?: string; }>>

approvalSetAutoApprove()

Signature

approvalSetAutoApprove(
   pin,
   actor,
   input
): 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";
  denialNote?: string;
}>
  | Readonly<{
  kind: "updated";
  rule: {
     scope: {
        agentId: string | null;
     };
     family: {
        module: string | null;
        access: "write" | "external";
     };
     enabled: boolean;
  };
}>>;

Policy never grants operation authority; only the live Oyster owner may change it.

Parameters

Parameter	Type
pin	Readonly<{ tenantId: string; origin: string; }>
actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }
input	{ scope: { agentId: string | null; }; family: { module: string | null; access: "write" | "external"; }; enabled: boolean; }
input.scope	{ agentId: string | null; }
input.scope.agentId	string | null
input.family	{ module: string | null; access: "write" | "external"; }
input.family.module	string | null
input.family.access	"write" | "external"
input.enabled	boolean

Returns

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"; denialNote?: string; }> | Readonly<{ kind: "updated"; rule: { scope: { agentId: string | null; }; family: { module: string | null; access: "write" | "external"; }; enabled: boolean; }; }>>

installationOperation()

Signature

installationOperation(input): Promise<
  | {
  kind: "refused";
  code:   | "request_conflict"
     | "unavailable"
     | "stale_authority"
     | "needs_consent"
     | "stored_operation_invalid";
}
  | {
  kind: "operation";
  operation:   | {
     requestId: string;
     requestedInstallationId: string;
     installationId: string;
     release: {
        releaseId: ReleaseId;
        appId: AppId;
        artifact: {
           artifactRef: ArtifactRef;
           artifactDigest: Sha256Digest;
           provenance: {
              sourceRevision: SourceRevision;
              sourceTreeDigest: Sha256Digest;
              buildRecipeDigest: Sha256Digest;
           };
        };
     };
     state: "refused";
     status: number;
     code: string;
   }
     | {
     requestId: string;
     requestedInstallationId: string;
     installationId: string;
     release: {
        releaseId: ReleaseId;
        appId: AppId;
        artifact: {
           artifactRef: ArtifactRef;
           artifactDigest: Sha256Digest;
           provenance: {
              sourceRevision: SourceRevision;
              sourceTreeDigest: Sha256Digest;
              buildRecipeDigest: Sha256Digest;
           };
        };
     };
     state: "unconfirmed";
     outcome: "cancelled" | "outcome_unknown" | "interrupted";
   }
     | {
     requestId: string;
     requestedInstallationId: string;
     installationId: string;
     release: {
        releaseId: ReleaseId;
        appId: AppId;
        artifact: {
           artifactRef: ArtifactRef;
           artifactDigest: Sha256Digest;
           provenance: {
              sourceRevision: SourceRevision;
              sourceTreeDigest: Sha256Digest;
              buildRecipeDigest: Sha256Digest;
           };
        };
     };
     state: "succeeded";
     reference: {
        generation: string;
        instanceId: InstanceId;
        authorityVersion: number;
        status: "enabled" | "disabled" | "deleted";
     };
     creation: "fresh" | "replacement" | "reminted";
     uiCheck:   | {
        kind: "passed";
      }
        | {
        kind: "failed";
        code: "ui_mount_failed";
        diagnostics?: {
           failedPredicate:   | "unexpected_candidate_request"
              | "response_status"
              | "request_failed"
              | "page_error"
              | "candidate_not_mounted";
           errorName?:   | "TypeError"
              | "RangeError"
              | "SyntaxError"
              | "AbortError"
              | "TimeoutError"
              | "Other"
              | "Error";
           finalUrlPath: string;
           consoleErrors: string[];
           pageErrors: string[];
           failedRequests: object[];
           droppedCount: number;
        };
      }
        | {
        kind: "not_checked";
        code:   | "boot_runner_unavailable"
           | "boot_browser_binding_missing"
           | "boot_clone_unavailable"
           | "boot_timeout"
           | "boot_cleanup_failed"
           | "ui_check_not_run_on_host";
      }
        | null;
     installation:   | {
        installationId: string;
        instanceId: InstanceId | null;
        appId: AppId;
        release: {
           releaseId: ReleaseId;
           appId: AppId;
           artifact: {
              artifactRef: ArtifactRef;
              artifactDigest: Sha256Digest;
              provenance: {
                 sourceRevision: SourceRevision;
                 sourceTreeDigest: Sha256Digest;
                 buildRecipeDigest: Sha256Digest;
              };
           };
        };
        releasePin: "pinned" | "floating";
        authority: {
           authorityVersion: number;
           declaredOperationsDigest: Sha256Digest;
           approvedGrants: readonly Readonly<{
              capability: ...;
              capabilityApproved: ...;
              operations: ...;
              resources: ...;
           }>[];
           approval:   | Readonly<{
              by: ...;
              at: ...;
              authorityVersion: ...;
            }>
              | null;
        };
        status: "enabled" | "disabled" | "deleted";
        visibility: "private" | "public";
        approvedAnonymousMethods: readonly Readonly<{
           name: string;
           digest: Sha256Digest;
        }>[];
        anonymousApproval:   | Readonly<{
           by: ... | ... | ...;
           at: number;
           authorityVersion: number;
         }>
           | null;
      }
        | null;
   }
     | {
     requestId: string;
     requestedInstallationId: string;
     installationId: string;
     release: {
        releaseId: ReleaseId;
        appId: AppId;
        artifact: {
           artifactRef: ArtifactRef;
           artifactDigest: Sha256Digest;
           provenance: {
              sourceRevision: SourceRevision;
              sourceTreeDigest: Sha256Digest;
              buildRecipeDigest: Sha256Digest;
           };
        };
     };
     state: "pending";
   }
     | null;
}
  | {
  kind: "command";
  command:   | {
     admission: {
        requestId: string;
        installationId: string;
        release: {
           releaseId: ReleaseId;
           appId: AppId;
           artifact: {
              artifactRef: ArtifactRef;
              artifactDigest: Sha256Digest;
              provenance: {
                 sourceRevision: SourceRevision;
                 sourceTreeDigest: Sha256Digest;
                 buildRecipeDigest: Sha256Digest;
              };
           };
        };
        actor:   | {
           kind: "member";
           memberId: string;
         }
           | {
           kind: "agent";
           agentId: string;
         }
           | {
           kind: "team-key";
           keyId: string;
         };
        intent: "install-or-select" | "install-or-remint" | "create-only";
        origin: "workflow" | "owner-direct";
     };
     scope: {
        tenantId: string & Brand<"OysterTenantId">;
        origin: string;
     };
     installationId: string;
     instanceId: InstanceId;
     generation: string;
     baseline:   | {
        installationId: string;
        instanceId: InstanceId | null;
        appId: AppId;
        release: {
           releaseId: ReleaseId;
           appId: AppId;
           artifact: {
              artifactRef: ArtifactRef;
              artifactDigest: Sha256Digest;
              provenance: {
                 sourceRevision: SourceRevision;
                 sourceTreeDigest: Sha256Digest;
                 buildRecipeDigest: Sha256Digest;
              };
           };
        };
        releasePin: "pinned" | "floating";
        authority: {
           authorityVersion: number;
           declaredOperationsDigest: Sha256Digest;
           approvedGrants: readonly Readonly<{
              capability: ...;
              capabilityApproved: ...;
              operations: ...;
              resources: ...;
           }>[];
           approval:   | Readonly<{
              by: ...;
              at: ...;
              authorityVersion: ...;
            }>
              | null;
        };
        status: "enabled" | "disabled" | "deleted";
        visibility: "private" | "public";
        approvedAnonymousMethods: readonly Readonly<{
           name: string;
           digest: Sha256Digest;
        }>[];
        anonymousApproval:   | Readonly<{
           by: ... | ... | ...;
           at: number;
           authorityVersion: number;
         }>
           | null;
      }
        | null;
     acceptedAt: number;
     creation: "fresh" | "replacement" | "reminted";
     plan:   | {
        installation: {
           installationId: string;
           instanceId: InstanceId | null;
           appId: AppId;
           release: {
              releaseId: ReleaseId;
              appId: AppId;
              artifact: {
                 artifactRef: ArtifactRef;
                 artifactDigest: Sha256Digest;
                 provenance: {
                    sourceRevision: ...;
                    sourceTreeDigest: ...;
                    buildRecipeDigest: ...;
                 };
              };
           };
           releasePin: "pinned" | "floating";
           authority: {
              authorityVersion: number;
              declaredOperationsDigest: Sha256Digest;
              approvedGrants: readonly Readonly<...>[];
              approval: Readonly<...> | null;
           };
           status: "enabled" | "disabled" | "deleted";
           visibility: "private" | "public";
           approvedAnonymousMethods: readonly Readonly<{
              name: ...;
              digest: ...;
           }>[];
           anonymousApproval:   | Readonly<{
              by: ...;
              at: ...;
              authorityVersion: ...;
            }>
              | null;
        };
        hasBackend: boolean;
        prepared: boolean;
        uiCheck?:   | {
           kind: "passed";
         }
           | {
           kind: "failed";
           code: "ui_mount_failed";
           diagnostics?: {
              failedPredicate: ...;
              errorName?: ...;
              finalUrlPath: ...;
              consoleErrors: ...;
              pageErrors: ...;
              failedRequests: ...;
              droppedCount: ...;
           };
         }
           | {
           kind: "not_checked";
           code:   | "boot_runner_unavailable"
              | "boot_browser_binding_missing"
              | "boot_clone_unavailable"
              | "boot_timeout"
              | "boot_cleanup_failed"
              | "ui_check_not_run_on_host";
         }
           | null;
      }
        | null;
     operation: {
        requestId: string;
        requestedInstallationId: string;
        installationId: string;
        release: {
           releaseId: ReleaseId;
           appId: AppId;
           artifact: {
              artifactRef: ArtifactRef;
              artifactDigest: Sha256Digest;
              provenance: {
                 sourceRevision: SourceRevision;
                 sourceTreeDigest: Sha256Digest;
                 buildRecipeDigest: Sha256Digest;
              };
           };
        };
        state: "pending";
     };
   }
     | null;
}
  | {
  kind: "commit";
  commit:   | {
     ok: true;
   }
     | {
     ok: false;
     code: "stale_authority";
   };
}>;

The installation owner’s RPC: admit, read, load, plan or commit one retained command for the caller’s tenant scope.

Parameters

Parameter

Type

input

| { action: "admit"; scope: { tenantId: string & Brand<"OysterTenantId">; origin: string; }; input: { requestId: string; installationId: string; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; intent: "install-or-select" | "install-or-remint" | "create-only"; origin: "workflow" | "owner-direct"; }; } | { action: "read"; scope: { tenantId: string & Brand<"OysterTenantId">; origin: string; }; requestId: string; installationId: string; } | { action: "load"; scope: { tenantId: string & Brand<"OysterTenantId">; origin: string; }; requestId: string; } | { action: "plan"; scope: { tenantId: string & Brand<"OysterTenantId">; origin: string; }; requestId: string; installation: { installationId: string; instanceId: InstanceId | null; appId: AppId; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; releasePin: "pinned" | "floating"; authority: { authorityVersion: number; declaredOperationsDigest: Sha256Digest; approvedGrants: readonly Readonly<{ capability: | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage"; capabilityApproved: true; operations: readonly string[]; resources: | "tenant-scope" | readonly Readonly<{ kind: …; id: …; }>[]; }>[]; approval: | Readonly<{ by: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; at: number; authorityVersion: number; }> | null; }; status: "enabled" | "disabled" | "deleted"; visibility: "private" | "public"; approvedAnonymousMethods: readonly Readonly<{ name: string; digest: Sha256Digest; }>[]; anonymousApproval: | Readonly<{ by: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; at: number; authorityVersion: number; }> | null; }; hasBackend: boolean; } | { action: "commit"; scope: { tenantId: string & Brand<"OysterTenantId">; origin: string; }; requestId: string; uiCheck: | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: | "unexpected_candidate_request" | "response_status" | "request_failed" | "page_error" | "candidate_not_mounted"; errorName?: | "TypeError" | "RangeError" | "SyntaxError" | "AbortError" | "TimeoutError" | "Other" | "Error"; finalUrlPath: string; consoleErrors: string[]; pageErrors: string[]; failedRequests: object[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; } | null; }

Returns

Promise< | { kind: "refused"; code: | "request_conflict" | "unavailable" | "stale_authority" | "needs_consent" | "stored_operation_invalid"; } | { kind: "operation"; operation: | { requestId: string; requestedInstallationId: string; installationId: string; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; state: "refused"; status: number; code: string; } | { requestId: string; requestedInstallationId: string; installationId: string; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; state: "unconfirmed"; outcome: "cancelled" | "outcome_unknown" | "interrupted"; } | { requestId: string; requestedInstallationId: string; installationId: string; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; state: "succeeded"; reference: { generation: string; instanceId: InstanceId; authorityVersion: number; status: "enabled" | "disabled" | "deleted"; }; creation: "fresh" | "replacement" | "reminted"; uiCheck: | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: | "unexpected_candidate_request" | "response_status" | "request_failed" | "page_error" | "candidate_not_mounted"; errorName?: | "TypeError" | "RangeError" | "SyntaxError" | "AbortError" | "TimeoutError" | "Other" | "Error"; finalUrlPath: string; consoleErrors: string[]; pageErrors: string[]; failedRequests: object[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; } | null; installation: | { installationId: string; instanceId: InstanceId | null; appId: AppId; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; releasePin: "pinned" | "floating"; authority: { authorityVersion: number; declaredOperationsDigest: Sha256Digest; approvedGrants: readonly Readonly<{ capability: …; capabilityApproved: …; operations: …; resources: …; }>[]; approval: | Readonly<{ by: …; at: …; authorityVersion: …; }> | null; }; status: "enabled" | "disabled" | "deleted"; visibility: "private" | "public"; approvedAnonymousMethods: readonly Readonly<{ name: string; digest: Sha256Digest; }>[]; anonymousApproval: | Readonly<{ by: … | … | …; at: number; authorityVersion: number; }> | null; } | null; } | { requestId: string; requestedInstallationId: string; installationId: string; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; state: "pending"; } | null; } | { kind: "command"; command: | { admission: { requestId: string; installationId: string; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; intent: "install-or-select" | "install-or-remint" | "create-only"; origin: "workflow" | "owner-direct"; }; scope: { tenantId: string & Brand<"OysterTenantId">; origin: string; }; installationId: string; instanceId: InstanceId; generation: string; baseline: | { installationId: string; instanceId: InstanceId | null; appId: AppId; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; releasePin: "pinned" | "floating"; authority: { authorityVersion: number; declaredOperationsDigest: Sha256Digest; approvedGrants: readonly Readonly<{ capability: …; capabilityApproved: …; operations: …; resources: …; }>[]; approval: | Readonly<{ by: …; at: …; authorityVersion: …; }> | null; }; status: "enabled" | "disabled" | "deleted"; visibility: "private" | "public"; approvedAnonymousMethods: readonly Readonly<{ name: string; digest: Sha256Digest; }>[]; anonymousApproval: | Readonly<{ by: … | … | …; at: number; authorityVersion: number; }> | null; } | null; acceptedAt: number; creation: "fresh" | "replacement" | "reminted"; plan: | { installation: { installationId: string; instanceId: InstanceId | null; appId: AppId; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: …; sourceTreeDigest: …; buildRecipeDigest: …; }; }; }; releasePin: "pinned" | "floating"; authority: { authorityVersion: number; declaredOperationsDigest: Sha256Digest; approvedGrants: readonly Readonly<…>[]; approval: Readonly<…> | null; }; status: "enabled" | "disabled" | "deleted"; visibility: "private" | "public"; approvedAnonymousMethods: readonly Readonly<{ name: …; digest: …; }>[]; anonymousApproval: | Readonly<{ by: …; at: …; authorityVersion: …; }> | null; }; hasBackend: boolean; prepared: boolean; uiCheck?: | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: …; errorName?: …; finalUrlPath: …; consoleErrors: …; pageErrors: …; failedRequests: …; droppedCount: …; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; } | null; } | null; operation: { requestId: string; requestedInstallationId: string; installationId: string; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; state: "pending"; }; } | null; } | { kind: "commit"; commit: | { ok: true; } | { ok: false; code: "stale_authority"; }; }>

alarm()

Signature

alarm(): Promise<void>;

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.

Returns

Promise<void>

Overrides

Signature

DurableObject.alarm;

directory()

Signature

directory(): Promise<Readonly<{
  apps: readonly object[];
  roles: OysterRootRoles;
  computer?: Readonly<{
     computerId: string;
     name: string;
  }>;
}>>;

Current desktop metadata; roles are the ADR’s derived default, never Hub’s stored choice.

Returns

Promise<Readonly<{ apps: readonly object[]; roles: OysterRootRoles; computer?: Readonly<{ computerId: string; name: string; }>; }>>

storageRead()

Signature

storageRead(
   installationId,
   ownerId,
   key
): Promise<AppStorageResult<{
  value: Json;
  source: "member" | "team" | "none";
  team:   | {
     value: Json;
     revision: number;
   }
     | null;
  member:   | {
     value: Json;
     revision: number;
   }
     | null;
  canWriteTeam: boolean;
}>>;

Read one key for the authenticated root owner, under fresh App admission.

Parameters

Parameter	Type
installationId	string
ownerId	string
key	string

Returns

Promise<AppStorageResult<{ value: Json; source: "member" | "team" | "none"; team: | { value: Json; revision: number; } | null; member: | { value: Json; revision: number; } | null; canWriteTeam: boolean; }>>

storageWrite()

Signature

storageWrite(
   installationId,
   ownerId,
   input
): Promise<AppStorageResult<{
  revision: number;
}>>;

Write one declared key for the authenticated root owner.

Parameters

Parameter	Type
installationId	string
ownerId	string
input	{ value: Json; key: string; scope: "member" | "team"; basedOn: number | null; }
input.value	Json
input.key	string
input.scope	"member" | "team"
input.basedOn	number | null

Returns

Promise<AppStorageResult<{ revision: number; }>>

storageReset()

Signature

storageReset(
   installationId,
   ownerId,
   input
): Promise<AppStorageResult<{
  revision: number;
}>>;

Reset one declared layer for the authenticated root owner.

Parameters

Parameter	Type
installationId	string
ownerId	string
input	{ key: string; scope: "member" | "team"; basedOn: number | null; }
input.key	string
input.scope	"member" | "team"
input.basedOn	number | null

Returns

Promise<AppStorageResult<{ revision: number; }>>

storageBackend()

Signature

storageBackend(
   raw,
   method,
   args,
   tenantId
): Promise<OysterBindingResult>;

Storage for a live owner method frame; no guest-selected installation or member.

Parameters

Parameter	Type
raw	{ instanceId: InstanceId; selection: { instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }; artifactDigest: Sha256Digest; subject: | { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }; grants: readonly object[]; deadlineAt: number; ancestry: readonly InstanceId[]; }
raw.instanceId	InstanceId
raw.selection	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }
raw.selection.instanceId	InstanceId
raw.selection.owner	{ kind: "installation" | "deployment"; id: string; }
raw.selection.owner.kind	"installation" | "deployment"
raw.selection.owner.id	string
raw.selection.appId	AppId
raw.selection.releaseId	ReleaseId
raw.selection.authorityVersion	number
raw.artifactDigest	Sha256Digest
raw.subject	| { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }
raw.grants	readonly object[]
raw.deadlineAt	number
raw.ancestry	readonly InstanceId[]
method	string
args	readonly unknown[]
tenantId	string & Brand<"OysterTenantId">

Returns

Promise<OysterBindingResult>

storageEvents()

Signature

storageEvents(
   installationId,
   ownerId,
   key
): Promise<Response>;

Open the existing App-storage invalidation stream under fresh owner admission.

Parameters

Parameter	Type
installationId	string
ownerId	string
key	string

Returns

Promise<Response>

storeFromOlderOyster()

Signature

storeFromOlderOyster(): boolean;

Whether this registry’s data was written by Oyster 0.2 or earlier; hosts refuse it.

Returns

boolean

list()

Signature

list(): Readonly<{
  installationId: string;
  instanceId: InstanceId | null;
  appId: AppId;
  release: {
     releaseId: ReleaseId;
     appId: AppId;
     artifact: {
        artifactRef: ArtifactRef;
        artifactDigest: Sha256Digest;
        provenance: {
           sourceRevision: SourceRevision;
           sourceTreeDigest: Sha256Digest;
           buildRecipeDigest: Sha256Digest;
        };
     };
  };
  releasePin: "pinned" | "floating";
  authority: {
     authorityVersion: number;
     declaredOperationsDigest: Sha256Digest;
     approvedGrants: readonly Readonly<{
        capability:   | "computer.list"
           | "computer.readFile"
           | "computer.writeFile"
           | "computer.execute"
           | "approvals"
           | "agent.list"
           | "agent.manage"
           | "agent.rename"
           | "agent.avatar"
           | "agent.toolPolicy"
           | "agent.read"
           | "agent.send"
           | "llm.generation"
           | "media.generation"
           | "games:servers"
           | "git.repository"
           | "apps.open"
           | "apps.call"
           | "app.storage"
           | "app.events.emit"
           | "team.workbenchHost"
           | "marketplace.browse"
           | "marketplace.purchase"
           | "workflow.run"
           | "workflow.publish"
           | "workflow.arm"
           | "world"
           | "channels.read"
           | "channels.personal.manage";
        capabilityApproved: true;
        operations: readonly string[];
        resources:   | "tenant-scope"
           | readonly Readonly<{
           kind: ...;
           id: ...;
         }>[];
     }>[];
     approval:   | Readonly<{
        by:   | {
           kind: "member";
           memberId: string;
         }
           | {
           kind: "agent";
           agentId: string;
         }
           | {
           kind: "team-key";
           keyId: string;
         };
        at: number;
        authorityVersion: number;
      }>
        | null;
  };
  status: "enabled" | "disabled" | "deleted";
  visibility: "private" | "public";
  approvedAnonymousMethods: readonly Readonly<{
     name: string;
     digest: Sha256Digest;
  }>[];
  anonymousApproval:   | Readonly<{
     by:   | {
        kind: "member";
        memberId: string;
      }
        | {
        kind: "agent";
        agentId: string;
      }
        | {
        kind: "team-key";
        keyId: string;
      };
     at: number;
     authorityVersion: number;
   }>
     | null;
}>[];

Every installation record.

Returns

Readonly<{ installationId: string; instanceId: InstanceId | null; appId: AppId; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; releasePin: "pinned" | "floating"; authority: { authorityVersion: number; declaredOperationsDigest: Sha256Digest; approvedGrants: readonly Readonly<{ capability: | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage"; capabilityApproved: true; operations: readonly string[]; resources: | "tenant-scope" | readonly Readonly<{ kind: …; id: …; }>[]; }>[]; approval: | Readonly<{ by: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; at: number; authorityVersion: number; }> | null; }; status: "enabled" | "disabled" | "deleted"; visibility: "private" | "public"; approvedAnonymousMethods: readonly Readonly<{ name: string; digest: Sha256Digest; }>[]; anonymousApproval: | Readonly<{ by: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; at: number; authorityVersion: number; }> | null; }>[]

get()

Signature

get(installationId):
  | Readonly<{
  installationId: string;
  instanceId: InstanceId | null;
  appId: AppId;
  release: {
     releaseId: ReleaseId;
     appId: AppId;
     artifact: {
        artifactRef: ArtifactRef;
        artifactDigest: Sha256Digest;
        provenance: {
           sourceRevision: SourceRevision;
           sourceTreeDigest: Sha256Digest;
           buildRecipeDigest: Sha256Digest;
        };
     };
  };
  releasePin: "pinned" | "floating";
  authority: {
     authorityVersion: number;
     declaredOperationsDigest: Sha256Digest;
     approvedGrants: readonly Readonly<{
        capability:   | "computer.list"
           | "computer.readFile"
           | "computer.writeFile"
           | "computer.execute"
           | "approvals"
           | "agent.list"
           | "agent.manage"
           | "agent.rename"
           | "agent.avatar"
           | "agent.toolPolicy"
           | "agent.read"
           | "agent.send"
           | "llm.generation"
           | "media.generation"
           | "games:servers"
           | "git.repository"
           | "apps.open"
           | "apps.call"
           | "app.storage"
           | "app.events.emit"
           | "team.workbenchHost"
           | "marketplace.browse"
           | "marketplace.purchase"
           | "workflow.run"
           | "workflow.publish"
           | "workflow.arm"
           | "world"
           | "channels.read"
           | "channels.personal.manage";
        capabilityApproved: true;
        operations: readonly string[];
        resources:   | "tenant-scope"
           | readonly Readonly<{
           kind: ...;
           id: ...;
         }>[];
     }>[];
     approval:   | Readonly<{
        by:   | {
           kind: "member";
           memberId: string;
         }
           | {
           kind: "agent";
           agentId: string;
         }
           | {
           kind: "team-key";
           keyId: string;
         };
        at: number;
        authorityVersion: number;
      }>
        | null;
  };
  status: "enabled" | "disabled" | "deleted";
  visibility: "private" | "public";
  approvedAnonymousMethods: readonly Readonly<{
     name: string;
     digest: Sha256Digest;
  }>[];
  anonymousApproval:   | Readonly<{
     by:   | {
        kind: "member";
        memberId: string;
      }
        | {
        kind: "agent";
        agentId: string;
      }
        | {
        kind: "team-key";
        keyId: string;
      };
     at: number;
     authorityVersion: number;
   }>
     | null;
}>
  | null;

One installation record, or null.

Parameters

Parameter	Type
installationId	string

Returns

| Readonly<{ installationId: string; instanceId: InstanceId | null; appId: AppId; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; releasePin: "pinned" | "floating"; authority: { authorityVersion: number; declaredOperationsDigest: Sha256Digest; approvedGrants: readonly Readonly<{ capability: | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage"; capabilityApproved: true; operations: readonly string[]; resources: | "tenant-scope" | readonly Readonly<{ kind: …; id: …; }>[]; }>[]; approval: | Readonly<{ by: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; at: number; authorityVersion: number; }> | null; }; status: "enabled" | "disabled" | "deleted"; visibility: "private" | "public"; approvedAnonymousMethods: readonly Readonly<{ name: string; digest: Sha256Digest; }>[]; anonymousApproval: | Readonly<{ by: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; at: number; authorityVersion: number; }> | null; }> | null

generation()

Signature

generation(): string;

Durable store identity, regenerated only when the store itself is replaced.

Returns

string

compareAndPut()

Signature

compareAndPut(
   installation,
   expectedAuthorityVersion,
   expectedGeneration,
   tenantId?
): Promise<InstallationCommit>;

Native RPC returns a closed result; callers never classify a transported Error.

Parameters

Parameter	Type	Default value
installation	Installation	undefined
expectedAuthorityVersion	number	undefined
expectedGeneration	string	undefined
tenantId	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<InstallationCommit>

bootCapability()

Signature

bootCapability(input):
  | {
  id: string;
  identity: {
     appId: string;
     releaseId: ReleaseId;
     surfaceId: "host-boot";
  };
  base: string;
  expiresAt: number;
  assets: object[];
}
  | null
  | undefined;

Issue, resolve, or revoke one bounded capability without storing its token.

Parameters

Parameter	Type
input	| Readonly<{ kind: "issue"; grant: { lease: { id: string; identity: { appId: string; releaseId: ReleaseId; surfaceId: "host-boot"; }; base: string; expiresAt: number; assets: object[]; }; tokenDigest: string; }; }> | Readonly<{ kind: "resolve"; tokenDigest: string; now: number; }> | Readonly<{ kind: "revoke"; id: string; }>

Returns

| { id: string; identity: { appId: string; releaseId: ReleaseId; surfaceId: "host-boot"; }; base: string; expiresAt: number; assets: object[]; } | null | undefined

---

OysterBindingCclass

The plain Oyster Worker’s guest binding entrypoint.

Extends

• WorkerEntrypoint<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }>; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string; AGENT_DIRECTORY?: Readonly<{ getByName: Readonly<{ readCreator: Promise<… | …>; }>; }>; OYSTER_ORIGIN: string; MCP: DurableObjectNamespace<OysterMcpOwner<Readonly<{ LOADER: WorkerLoader; }>>>; RELEASES: R2Bucket; REGISTRY: DurableObjectNamespace<OysterRegistry<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; INSTANCES: DurableObjectNamespace<OysterInstance<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; LOADER: WorkerLoader; }>, Readonly<{ instanceId: string; binding: | "BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS"; frameId: string; }>, this>

Constructors

Constructor

Signature

new OysterBinding(ctx, env): OysterBinding;

Parameters

Parameter	Type
ctx	ExecutionContext
env	Env

Returns

OysterBinding

Inherited from

Signature

oysterBindingEntrypoint(oysterBindings).constructor;

---

OysterInstanceCclass

One App Instance: Oyster’s lifecycle supervisor in this Durable Object’s SQLite and the App backend in its app facet.

Extends

• DurableObject<Env>

Extended by

• OysterGitInstance

Type Parameters

Type Parameter	Default type
Env extends OysterWorkerEnv	OysterWorkerEnv

Constructors

Constructor

Signature

new OysterInstance<Env>(ctx, env): OysterInstance<Env>;

Parameters

Parameter	Type
ctx	DurableObjectState
env	Env

Returns

OysterInstance<Env>

Overrides

Signature

DurableObject<Env>.constructor

Methods

bindingCall()

Signature

bindingCall(
   raw,
   method,
   input
): Promise<FrameBindingReply<OysterBindingResult>>;

Resolve each guest packet against its immutable frame before any host effect.

Parameters

Parameter	Type
raw	FrameBindingProps
method	string
input	readonly unknown[]

Returns

Promise<FrameBindingReply<OysterBindingResult>>

gitTip()

Signature

gitTip(
   installationId,
   repository,
   ref,
   tenantId?
): Promise<string | null>;

Last provider-accepted ref recorded by this installation’s journal.

Parameters

Parameter	Type	Default value
installationId	string	undefined
repository	string	undefined
ref	string	undefined
tenantId	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<string | null>

recordGitPush()

Signature

recordGitPush(
   installationId,
   fact,
   tenantId?
): Promise<"duplicate" | "recorded">;

Join accepted fact identity and Carrier delivery in one local transaction.

Parameters

Parameter	Type	Default value
installationId	string	undefined
fact	{ repository: string; writer: | { kind: "actor"; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; role?: "member" | "owner"; workflow?: { armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; branches: string[]; workflowId: string; runId: string; nodeId: string; }; } | { kind: "installation"; installationId: string; onBehalfOf: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; } | null; }; updates: object[]; unexplained?: object[]; eventId: string; }	undefined
fact.repository	string	undefined
fact.writer	| { kind: "actor"; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; role?: "member" | "owner"; workflow?: { armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; branches: string[]; workflowId: string; runId: string; nodeId: string; }; } | { kind: "installation"; installationId: string; onBehalfOf: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; } | null; }	undefined
fact.updates	object[]	undefined
fact.unexplained?	object[]	undefined
fact.eventId	string	undefined
tenantId	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<"duplicate" | "recorded">

alarm()

Signature

alarm(): Promise<void>;

Carrier owns retries, dead letters and retained delivery receipts.

Returns

Promise<void>

Overrides

Signature

DurableObject.alarm;

revoke()

Signature

revoke(
   installationId,
   runId?,
   tenantId?
): Promise<void>;

Installation changes end guest work; a Workflow cancel targets only its run.

Parameters

Parameter	Type	Default value
installationId	string	undefined
runId?	string	undefined
tenantId?	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<void>

prepare()

Signature

prepare(
   state,
   release,
   limits?,
   tenant?
): Promise<InstanceResult<
  | {
  kind: "passed";
}
  | {
  kind: "failed";
  code: "ui_mount_failed";
  diagnostics?: {
     failedPredicate:   | "unexpected_candidate_request"
        | "response_status"
        | "request_failed"
        | "page_error"
        | "candidate_not_mounted";
     errorName?:   | "TypeError"
        | "RangeError"
        | "SyntaxError"
        | "AbortError"
        | "TimeoutError"
        | "Other"
        | "Error";
     finalUrlPath: string;
     consoleErrors: string[];
     pageErrors: string[];
     failedRequests: object[];
     droppedCount: number;
  };
}
  | {
  kind: "not_checked";
  code:   | "boot_runner_unavailable"
     | "boot_browser_binding_missing"
     | "boot_clone_unavailable"
     | "boot_timeout"
     | "boot_cleanup_failed"
     | "ui_check_not_run_on_host";
}
| null>>;

Reuse lifecycle preflight without changing the active runtime or its budgets.

Parameters

Parameter	Type
state	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; status: "enabled" | "disabled" | "deleted"; }
state.instanceId	InstanceId
state.owner	{ kind: "installation" | "deployment"; id: string; }
state.owner.kind?	"installation" | "deployment"
state.owner.id?	string
state.appId?	AppId
state.releaseId?	ReleaseId
state.authorityVersion?	number
state.status?	"enabled" | "disabled" | "deleted"
release?	Release
limits?	Readonly<{ cpuMs: number; subRequests: number; }>
tenant?	Pick<Readonly<{ tenantId: string & Brand<"OysterTenantId">; origin: string; durableName: string; computerName: string; workspacePrefix: string; repositoryPrefix: string; }>, "origin" | "tenantId">

Returns

Promise<InstanceResult< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: | "unexpected_candidate_request" | "response_status" | "request_failed" | "page_error" | "candidate_not_mounted"; errorName?: | "TypeError" | "RangeError" | "SyntaxError" | "AbortError" | "TimeoutError" | "Other" | "Error"; finalUrlPath: string; consoleErrors: string[]; pageErrors: string[]; failedRequests: object[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; } | null>>

apply()

Signature

apply(
   state,
   release,
   limits,
   tenant
): Promise<InstanceResult<{
  instanceId: InstanceId;
  owner: {
     kind: "installation" | "deployment";
     id: string;
  };
  appId: AppId;
  releaseId: ReleaseId;
  authorityVersion: number;
  stateSchema: number | null;
  desiredStatus: "enabled" | "disabled" | "deleted";
  status: "active" | "disabled" | "deleted" | "deleting";
}>>;

Activate the exact committed selection under the host’s tenant pin.

Parameters

Parameter	Type
state	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; status: "enabled" | "disabled" | "deleted"; }
state.instanceId	InstanceId
state.owner	{ kind: "installation" | "deployment"; id: string; }
state.owner.kind	"installation" | "deployment"
state.owner.id	string
state.appId	AppId
state.releaseId	ReleaseId
state.authorityVersion	number
state.status	"enabled" | "disabled" | "deleted"
release	Release
limits	| Readonly<{ cpuMs: number; subRequests: number; }> | undefined
tenant	Pick<TenantScope, "tenantId" | "origin">

Returns

Promise<InstanceResult<{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; stateSchema: number | null; desiredStatus: "enabled" | "disabled" | "deleted"; status: "active" | "disabled" | "deleted" | "deleting"; }>>

backend()

Signature

backend(
   facts,
   request,
   limits?,
   tenantId?
): Promise<Response>;

Forward an admitted HTTP request to the App backend.

Parameters

Parameter	Type	Default value
facts	{ instanceId: InstanceId; selection: { instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }; artifactDigest: Sha256Digest; subject: | { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }; grants: readonly object[]; deadlineAt: number; ancestry: readonly InstanceId[]; }	undefined
facts.instanceId	InstanceId	instanceIdSchema
facts.selection	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }	selectionSchema
facts.selection.instanceId?	InstanceId	instanceIdSchema
facts.selection.owner?	{ kind: "installation" | "deployment"; id: string; }	ownerSchema
facts.selection.owner.kind?	"installation" | "deployment"	...
facts.selection.owner.id?	string	Schema.NonEmptyString
facts.selection.appId?	AppId	appIdSchema
facts.selection.releaseId?	ReleaseId	releaseIdSchema
facts.selection.authorityVersion?	number	...
facts.artifactDigest?	Sha256Digest	sha256DigestSchema
facts.subject?	| { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }	...
facts.grants?	readonly object[]	grantsSchema
facts.deadlineAt?	number	...
facts.ancestry?	readonly InstanceId[]	...
request?	Request	undefined
limits?	Readonly<{ cpuMs: number; subRequests: number; }>	undefined
tenantId?	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<Response>

onGitPush()

Signature

onGitPush(
   facts,
   fact,
   limits?,
   tenantId?
): Promise<void>;

Deliver a Git push through the same selected-Instance admission as methods.

Parameters

Parameter	Type	Default value
facts	{ instanceId: InstanceId; selection: { instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }; artifactDigest: Sha256Digest; subject: | { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }; grants: readonly object[]; deadlineAt: number; ancestry: readonly InstanceId[]; }	undefined
facts.instanceId	InstanceId	instanceIdSchema
facts.selection	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }	selectionSchema
facts.selection.instanceId?	InstanceId	instanceIdSchema
facts.selection.owner?	{ kind: "installation" | "deployment"; id: string; }	ownerSchema
facts.selection.owner.kind?	"installation" | "deployment"	...
facts.selection.owner.id?	string	Schema.NonEmptyString
facts.selection.appId?	AppId	appIdSchema
facts.selection.releaseId?	ReleaseId	releaseIdSchema
facts.selection.authorityVersion?	number	...
facts.artifactDigest?	Sha256Digest	sha256DigestSchema
facts.subject?	| { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }	...
facts.grants?	readonly object[]	grantsSchema
facts.deadlineAt?	number	...
facts.ancestry?	readonly InstanceId[]	...
fact?	{ repository: string; writer: | { kind: "actor"; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; role?: "member" | "owner"; workflow?: { armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; branches: string[]; workflowId: string; runId: string; nodeId: string; }; } | { kind: "installation"; installationId: string; onBehalfOf: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; } | null; }; updates: object[]; unexplained?: object[]; eventId: string; }	undefined
fact.repository?	string	undefined
fact.writer?	| { kind: "actor"; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; role?: "member" | "owner"; workflow?: { armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; branches: string[]; workflowId: string; runId: string; nodeId: string; }; } | { kind: "installation"; installationId: string; onBehalfOf: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; } | null; }	undefined
fact.updates?	object[]	undefined
fact.unexplained?	object[]	undefined
fact.eventId?	string	undefined
limits?	Readonly<{ cpuMs: number; subRequests: number; }>	undefined
tenantId?	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<void>

authorizeGitPush()

Signature

authorizeGitPush(
   facts,
   question,
   limits?,
   tenantId?
): Promise<
  | {
  allowed: true;
}
  | {
  allowed: false;
  refused: object[];
}>;

Ask the App’s declared authorizer through the same frame-bound connection.

Parameters

Parameter	Type	Default value
facts	{ instanceId: InstanceId; selection: { instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }; artifactDigest: Sha256Digest; subject: | { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }; grants: readonly object[]; deadlineAt: number; ancestry: readonly InstanceId[]; }	undefined
facts.instanceId	InstanceId	instanceIdSchema
facts.selection	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }	selectionSchema
facts.selection.instanceId?	InstanceId	instanceIdSchema
facts.selection.owner?	{ kind: "installation" | "deployment"; id: string; }	ownerSchema
facts.selection.owner.kind?	"installation" | "deployment"	...
facts.selection.owner.id?	string	Schema.NonEmptyString
facts.selection.appId?	AppId	appIdSchema
facts.selection.releaseId?	ReleaseId	releaseIdSchema
facts.selection.authorityVersion?	number	...
facts.artifactDigest?	Sha256Digest	sha256DigestSchema
facts.subject?	| { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }	...
facts.grants?	readonly object[]	grantsSchema
facts.deadlineAt?	number	...
facts.ancestry?	readonly InstanceId[]	...
question?	{ repository: string; writer: { kind: "actor"; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; role?: "member" | "owner"; workflow?: { armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; branches: string[]; workflowId: string; runId: string; nodeId: string; }; }; updates: object[]; }	undefined
question.repository?	string	undefined
question.writer?	{ kind: "actor"; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; role?: "member" | "owner"; workflow?: { armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; branches: string[]; workflowId: string; runId: string; nodeId: string; }; }	undefined
question.writer.kind?	"actor"	undefined
question.writer.actor?	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }	undefined
question.writer.role?	"member" | "owner"	undefined
question.writer.workflow?	{ armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; branches: string[]; workflowId: string; runId: string; nodeId: string; }	undefined
question.writer.workflow.armedBy?	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }	undefined
question.writer.workflow.branches?	string[]	undefined
question.writer.workflow.workflowId?	string	undefined
question.writer.workflow.runId?	string	undefined
question.writer.workflow.nodeId?	string	undefined
question.updates?	object[]	undefined
limits?	Readonly<{ cpuMs: number; subRequests: number; }>	undefined
tenantId?	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise< | { allowed: true; } | { allowed: false; refused: object[]; }>

syncRefused()

Signature

syncRefused(
   facts,
   refusal,
   limits?,
   tenantId?
): Promise<void>;

An available lane settles a refusal under an active frame with no binding grants.

Parameters

Parameter	Type	Default value
facts	{ instanceId: InstanceId; selection: { instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }; artifactDigest: Sha256Digest; subject: | { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }; grants: readonly object[]; deadlineAt: number; ancestry: readonly InstanceId[]; }	undefined
facts.instanceId	InstanceId	instanceIdSchema
facts.selection	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }	selectionSchema
facts.selection.instanceId?	InstanceId	instanceIdSchema
facts.selection.owner?	{ kind: "installation" | "deployment"; id: string; }	ownerSchema
facts.selection.owner.kind?	"installation" | "deployment"	...
facts.selection.owner.id?	string	Schema.NonEmptyString
facts.selection.appId?	AppId	appIdSchema
facts.selection.releaseId?	ReleaseId	releaseIdSchema
facts.selection.authorityVersion?	number	...
facts.artifactDigest?	Sha256Digest	sha256DigestSchema
facts.subject?	| { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }	...
facts.grants?	readonly object[]	grantsSchema
facts.deadlineAt?	number	...
facts.ancestry?	readonly InstanceId[]	...
refusal?	{ lane: string; code: "access_changed" | "installation_unavailable"; }	undefined
refusal.lane?	string	undefined
refusal.code?	"access_changed" | "installation_unavailable"	undefined
limits?	Readonly<{ cpuMs: number; subRequests: number; }>	undefined
tenantId?	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<void>

gill()

Signature

gill(
   facts,
   _api,
   source,
   input,
   limits?,
   tenantId?
): Promise<InstanceResult<
  | {
  viewId: string;
  title: string;
  state: "empty";
  rows: readonly [];
  next?: string;
}
  | {
  viewId: string;
  title: string;
  state: "error";
  rows: readonly [];
  reason?: "exec_isolation_required" | "params_required";
  error: string;
  recovery?:   | {
     kind: "configure";
     param: string;
   }
     | {
     kind: "open";
   };
}
  | {
  viewId: string;
  title: string;
  state: "full";
  rows: readonly object[];
  next?: string;
}
  | {
  options: readonly object[];
  next?: string;
}>>;

Invoke a Release-declared Gill in a fresh immutable frame.

Parameters

Parameter	Type	Default value
facts	{ instanceId: InstanceId; selection: { instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }; artifactDigest: Sha256Digest; subject: | { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }; grants: readonly object[]; deadlineAt: number; ancestry: readonly InstanceId[]; }	undefined
facts.instanceId	InstanceId	instanceIdSchema
facts.selection	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }	selectionSchema
facts.selection.instanceId	InstanceId	instanceIdSchema
facts.selection.owner	{ kind: "installation" | "deployment"; id: string; }	ownerSchema
facts.selection.owner.kind?	"installation" | "deployment"	...
facts.selection.owner.id?	string	Schema.NonEmptyString
facts.selection.appId?	AppId	appIdSchema
facts.selection.releaseId?	ReleaseId	releaseIdSchema
facts.selection.authorityVersion?	number	...
facts.artifactDigest?	Sha256Digest	sha256DigestSchema
facts.subject?	| { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }	...
facts.grants?	readonly object[]	grantsSchema
facts.deadlineAt?	number	...
facts.ancestry?	readonly InstanceId[]	...
_api?	AppApi	undefined
source?	string	undefined
input?	{ id: string; params?: { [key: string]: string; }; after?: string; options?: string; }	undefined
input.id?	string	undefined
input.params?	{ [key: string]: string; }	undefined
input.after?	string	undefined
input.options?	string	undefined
limits?	Readonly<{ cpuMs: number; subRequests: number; }>	undefined
tenantId?	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<InstanceResult< | { viewId: string; title: string; state: "empty"; rows: readonly []; next?: string; } | { viewId: string; title: string; state: "error"; rows: readonly []; reason?: "exec_isolation_required" | "params_required"; error: string; recovery?: | { kind: "configure"; param: string; } | { kind: "open"; }; } | { viewId: string; title: string; state: "full"; rows: readonly object[]; next?: string; } | { options: readonly object[]; next?: string; }>>

call()

Signature

call(
   facts,
   _api,
   name,
   input,
   limits?,
   tenantId?
): Promise<InstanceResult<Json>>;

Invoke one declared App method; the value is its AppMethodReply wire, which the host handle decodes.

Parameters

Parameter	Type	Default value
facts	{ instanceId: InstanceId; selection: { instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }; artifactDigest: Sha256Digest; subject: | { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }; grants: readonly object[]; deadlineAt: number; ancestry: readonly InstanceId[]; }	undefined
facts.instanceId	InstanceId	instanceIdSchema
facts.selection	{ instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }	selectionSchema
facts.selection.instanceId	InstanceId	instanceIdSchema
facts.selection.owner	{ kind: "installation" | "deployment"; id: string; }	ownerSchema
facts.selection.owner.kind?	"installation" | "deployment"	...
facts.selection.owner.id?	string	Schema.NonEmptyString
facts.selection.appId?	AppId	appIdSchema
facts.selection.releaseId?	ReleaseId	releaseIdSchema
facts.selection.authorityVersion?	number	...
facts.artifactDigest?	Sha256Digest	sha256DigestSchema
facts.subject?	| { kind: "call"; context: { computerId: string | null; actor: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; backgroundLane?: string; backgroundOrigin?: { method: string; seal: string; }; role?: "member" | "owner"; soleMember?: true; workflow?: { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }; idempotencyKey?: string; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }	...
facts.grants?	readonly object[]	grantsSchema
facts.deadlineAt?	number	...
facts.ancestry?	readonly InstanceId[]	...
_api?	AppApi	undefined
name?	string	undefined
input?	Json	undefined
limits?	Readonly<{ cpuMs: number; subRequests: number; }>	undefined
tenantId?	string & Brand<"OysterTenantId">	defaultTenant

Returns

Promise<InstanceResult<Json>>

---

OysterMcpCclass

The non-git standalone root’s MCP owner.

Extends

• OysterMcpOwner<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }>; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string; AGENT_DIRECTORY?: Readonly<{ getByName: Readonly<{ readCreator: Promise<… | …>; }>; }>; OYSTER_ORIGIN: string; MCP: DurableObjectNamespace<OysterMcpOwner<Readonly<{ LOADER: WorkerLoader; }>>>; RELEASES: R2Bucket; REGISTRY: DurableObjectNamespace<OysterRegistry<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; INSTANCES: DurableObjectNamespace<OysterInstance<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; LOADER: WorkerLoader; }>, this>

Constructors

Constructor

Signature

new OysterMcp(ctx, env): OysterMcp;

Parameters

Parameter	Type
ctx	DurableObjectState
env	Env

Returns

OysterMcp

Inherited from

OysterMcpOwner.constructor

Methods

serve()

Signature

serve(request, tenant): Promise<Response>;

Trusted host RPC: the namespace and pin are never selected by guest headers.

Parameters

Parameter	Type
request	Request
tenant	OysterMcpTenantPin

Returns

Promise<Response>

Inherited from

OysterMcpOwner.serve

---

OysterInstallationExecutorCclass

Ordinary Worker execution; REGISTRY receives references and receipts only.

Extends

• WorkerEntrypoint<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }>; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string; AGENT_DIRECTORY?: Readonly<{ getByName: Readonly<{ readCreator: Promise<…>; }>; }>; OYSTER_ORIGIN: string; MCP: DurableObjectNamespace<OysterMcpOwner<Readonly<{ LOADER: WorkerLoader; }>>>; RELEASES: R2Bucket; REGISTRY: DurableObjectNamespace<OysterRegistry<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; INSTANCES: DurableObjectNamespace<OysterInstance<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; LOADER: WorkerLoader; }>, unknown, this> & object

Constructors

Constructor

Signature

new OysterInstallationExecutor(ctx, env): OysterInstallationExecutor;

Parameters

Parameter	Type
ctx	ExecutionContext
env	Env

Returns

OysterInstallationExecutor

Inherited from

Signature

installationWorkerEntrypoint<OysterWorkerEnv>((env, scope) =>
  ownerKeyRootHost(env, { scope }),
).constructor;

Methods

run()

Signature

run(): Promise<
  | {
  state: "succeeded";
  installation: {
     installationId: string;
     instanceId: InstanceId | null;
     appId: AppId;
     release: {
        releaseId: ReleaseId;
        appId: AppId;
        artifact: {
           artifactRef: ArtifactRef;
           artifactDigest: Sha256Digest;
           provenance: {
              sourceRevision: SourceRevision;
              sourceTreeDigest: Sha256Digest;
              buildRecipeDigest: Sha256Digest;
           };
        };
     };
     releasePin: "pinned" | "floating";
     authority: {
        authorityVersion: number;
        declaredOperationsDigest: Sha256Digest;
        approvedGrants: readonly Readonly<{
           capability:   | "computer.list"
              | "computer.readFile"
              | "computer.writeFile"
              | "computer.execute"
              | "approvals"
              | "agent.list"
              | "agent.manage"
              | "agent.rename"
              | "agent.avatar"
              | "agent.toolPolicy"
              | "agent.read"
              | "agent.send"
              | "llm.generation"
              | "media.generation"
              | "games:servers"
              | "git.repository"
              | "apps.open"
              | "apps.call"
              | "app.storage"
              | "app.events.emit"
              | "team.workbenchHost"
              | "marketplace.browse"
              | "marketplace.purchase"
              | "workflow.run"
              | "workflow.publish"
              | "workflow.arm"
              | "world"
              | "channels.read"
              | "channels.personal.manage";
           capabilityApproved: true;
           operations: readonly string[];
           resources: "tenant-scope" | readonly Readonly<...>[];
        }>[];
        approval:   | Readonly<{
           by:   | {
              kind: "member";
              memberId: string;
            }
              | {
              kind: "agent";
              agentId: string;
            }
              | {
              kind: "team-key";
              keyId: string;
            };
           at: number;
           authorityVersion: number;
         }>
           | null;
     };
     status: "enabled" | "disabled" | "deleted";
     visibility: "private" | "public";
     approvedAnonymousMethods: readonly Readonly<{
        name: string;
        digest: Sha256Digest;
     }>[];
     anonymousApproval:   | Readonly<{
        by:   | {
           kind: "member";
           memberId: string;
         }
           | {
           kind: "agent";
           agentId: string;
         }
           | {
           kind: "team-key";
           keyId: string;
         };
        at: number;
        authorityVersion: number;
      }>
        | null;
  };
  creation: "fresh" | "replacement" | "reminted";
  uiCheck:   | {
     kind: "passed";
   }
     | {
     kind: "failed";
     code: "ui_mount_failed";
     diagnostics?: {
        failedPredicate:   | "unexpected_candidate_request"
           | "response_status"
           | "request_failed"
           | "page_error"
           | "candidate_not_mounted";
        errorName?:   | "TypeError"
           | "RangeError"
           | "SyntaxError"
           | "AbortError"
           | "TimeoutError"
           | "Other"
           | "Error";
        finalUrlPath: string;
        consoleErrors: string[];
        pageErrors: string[];
        failedRequests: object[];
        droppedCount: number;
     };
   }
     | {
     kind: "not_checked";
     code:   | "boot_runner_unavailable"
        | "boot_browser_binding_missing"
        | "boot_clone_unavailable"
        | "boot_timeout"
        | "boot_cleanup_failed"
        | "ui_check_not_run_on_host";
   }
     | null;
}
  | {
  state: "refused";
  status: number;
  code: string;
}
  | {
  state: "unconfirmed";
  outcome: "cancelled" | "outcome_unknown" | "interrupted";
}>;

Execute the retained command these props name, in its tenant scope.

Returns

Promise< | { state: "succeeded"; installation: { installationId: string; instanceId: InstanceId | null; appId: AppId; release: { releaseId: ReleaseId; appId: AppId; artifact: { artifactRef: ArtifactRef; artifactDigest: Sha256Digest; provenance: { sourceRevision: SourceRevision; sourceTreeDigest: Sha256Digest; buildRecipeDigest: Sha256Digest; }; }; }; releasePin: "pinned" | "floating"; authority: { authorityVersion: number; declaredOperationsDigest: Sha256Digest; approvedGrants: readonly Readonly<{ capability: | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage"; capabilityApproved: true; operations: readonly string[]; resources: "tenant-scope" | readonly Readonly<…>[]; }>[]; approval: | Readonly<{ by: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; at: number; authorityVersion: number; }> | null; }; status: "enabled" | "disabled" | "deleted"; visibility: "private" | "public"; approvedAnonymousMethods: readonly Readonly<{ name: string; digest: Sha256Digest; }>[]; anonymousApproval: | Readonly<{ by: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; at: number; authorityVersion: number; }> | null; }; creation: "fresh" | "replacement" | "reminted"; uiCheck: | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: | "unexpected_candidate_request" | "response_status" | "request_failed" | "page_error" | "candidate_not_mounted"; errorName?: | "TypeError" | "RangeError" | "SyntaxError" | "AbortError" | "TimeoutError" | "Other" | "Error"; finalUrlPath: string; consoleErrors: string[]; pageErrors: string[]; failedRequests: object[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; } | null; } | { state: "refused"; status: number; code: string; } | { state: "unconfirmed"; outcome: "cancelled" | "outcome_unknown" | "interrupted"; }>

Inherited from

Signature

installationWorkerEntrypoint<OysterWorkerEnv>((env, scope) =>
  ownerKeyRootHost(env, { scope }),
).run;

OysterMcpOwnerEnvTtype alias

Signature

type OysterMcpOwnerEnv = Readonly<{
  LOADER: WorkerLoader;
}>;

Worker Loader used by the existing Mycelium sandbox.

---

OysterMcpTenantPinTtype alias

Signature

type OysterMcpTenantPin = Readonly<{
  tenantId: string;
  origin: string;
}>;

Serialized trusted tenant pin supplied by the selected host.

---

OysterBindingResultTtype alias

Signature

type OysterBindingResult =
  Awaited<ReturnType<GitBinding[keyof GitBinding]>> | Schema.Json | undefined;

Native values returned by the standalone Git, event and JSON binding owners.

---

OysterInvocationHostTtype alias

Signature

type OysterInvocationHost = BackgroundFrameState &
  Readonly<{
    artifact: Backend;
    declaration: AppDeclaration | null;
    method?: Readonly<{
      name: string;
    }>;
  }>;

Verified backend custody is captured in the frame, never in a current-context field.

---

OysterStorageAgentDirectoryTtype alias

Signature

type OysterStorageAgentDirectory = Readonly<{
  getByName: Readonly<{
    readCreator: Promise<string | null>;
  }>;
}>;

Existing fleet directory owner records, resolved by the host rather than App input.

---

OysterWorkerEnvTtype alias

Signature

type OysterWorkerEnv = Readonly<{
  BROWSER?: BrowserBinding;
  OYSTER_OWNER_KEY: string;
  OYSTER_OWNER_NAME?: string;
  AGENT_DIRECTORY?: OysterStorageAgentDirectory;
  OYSTER_ORIGIN: string;
  MCP: DurableObjectNamespace<OysterMcpOwner>;
  RELEASES: R2Bucket;
  REGISTRY: DurableObjectNamespace<OysterRegistry>;
  INSTANCES: DurableObjectNamespace<OysterInstance>;
  LOADER: WorkerLoader;
}>;

Bindings a standalone Oyster Worker declares in its Wrangler config.

---

OysterBindingContextTtype alias

Signature

type OysterBindingContext<Env> = Readonly<{
  env: Env;
  scope: TenantScope;
  backgroundHost: Promise<
     | Readonly<{
     approvals?: Readonly<{
        submit: Promise<
           | {
           kind: ...;
           recordId: ...;
           description: ...;
         }
          | ApprovalApplyResult>;
     }>;
     workflows?: (principal) => Promise<
        | {
        status: Promise<...>;
        cancel: Promise<...>;
      }
       | null>;
     computerControl?: (principal) => ComputerControlPort | null;
     auth: OysterAuth;
     backgroundOriginKey?: () => Promise<CryptoKey>;
     artifacts: ArtifactStore;
     uiCache?: VerifiedObjectCache;
     installations: InstallationStore;
     instances: InstanceDirectory;
     bootUi: (release) => Promise<UiBootCheckOutcome>;
     computerId?: string;
     computer?: (principal) => KnapsackComputer | null | Promise<KnapsackComputer | null>;
     appToolPolicy?: (actor) =>
        | AppToolPolicy
        | null
       | Promise<AppToolPolicy | null>;
     keys?: Readonly<{
        live: Promise<Readonly<...> | null>;
     }>;
     guestLimits?: Partial<GuestLimits>;
     mcp?: OysterMcp;
     git?: OysterGitHost;
     ownerRoutes?: Hono<OysterEnv>;
     capabilities?: readonly OysterCapability[];
     workbench?: Readonly<{
        directory: Promise<Readonly<{
           apps: ...;
           roles: ...;
           computer?: ...;
        }>>;
        storage: Pick<AppStorageWire, ... | ... | ...> & Readonly<{
           events: ...;
        }>;
     }>;
     homeInstallationId?: string;
     pageScript?: string;
     pageAssets?: () => Promise<{
        pageScript: string;
        publicHomeScript: string;
        fontStyles: string;
        loginFontStyles: string;
        shellStyles: string;
        grantConsentScript: string;
     }>;
     title?: string;
   }>
    | null>;
}>;

What a binding row may read from the Instance that owns the frame.

Type Parameters

Type Parameter
Env

---

OysterBindingRowTtype alias

Signature

type OysterBindingRow<Env> = Readonly<{
  methods: Readonly<Record<string, FrameBindingMethod<OysterBindingResult>>>;
  dispatch: Promise<OysterBindingResult>;
}>;

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.

Type Parameters

Type Parameter
Env

---

OysterBindingTableTtype alias

Signature

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 bindings an Instance serves, keyed by the closed App binding vocabulary; a missing row is binding_unavailable.

Type Parameters

Type Parameter
Env

---

OysterWorkspaceTtype alias

Signature

type OysterWorkspace = Readonly<{
  computerId: string;
  files: FileSource;
  computer?: OysterHost["computer"];
}>;

One host-selected workspace shared by App context and capability adapters.

oysterBindingsconstconstant

Signature

const oysterBindings: OysterBindingTable<OysterWorkerEnv>;

The plain Oyster host’s bindings: App storage, the read-only catalog and replay admission.

installationWorkerEntrypoint()fnfunction

Signature

function installationWorkerEntrypoint<Env>(
  hostFor,
): (ctx, env) => WorkerEntrypoint<Env, unknown> & object;

A loopback export with ordinary Worker I/O, not another resource or HTTP API.

Type Parameters

Type Parameter
Env

Parameters

Parameter

Type

hostFor

(env, scope) => | Readonly<{ approvals?: Readonly<{ submit: Promise< | { kind: "pending_approval"; recordId: string; description: { title: …; inputBytes: …; inputSha256: …; }; } | ApprovalApplyResult>; }>; workflows?: (principal) => Promise< | Readonly<{ status: Promise<…>; cancel: Promise<…>; }> | null>; computerControl?: (principal) => | Readonly<{ list: Promise<{ computers: …; nextOffset: …; }>; state: Promise<… | …>; start: Promise<… | …>; create: Promise<… | …>; }> | null; auth: OysterAuth; backgroundOriginKey?: () => Promise<CryptoKey>; artifacts: ArtifactStore; uiCache?: Readonly<{ match: (digest) => Promise<ReadableStream<…> | null>; put: (digest, bytes) => Promise<"stored" | "unstored">; }>; installations: InstallationStore; instances: InstanceDirectory; bootUi: (release) => Promise< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: … | … | … | … | …; errorName?: … | … | … | … | … | … | … | …; finalUrlPath: string; consoleErrors: …[]; pageErrors: …[]; failedRequests: …[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; }>; computerId?: string; computer?: (principal) => | Readonly<{ getCapabilities: (signal) => Promise<…>; call: (capabilityId, input, context) => Promise<…>; }> | Promise< | Readonly<{ getCapabilities: …; call: …; }> | null> | null; appToolPolicy?: (actor) => | { level: "read" | "write"; revision: string; grantedBy: string; } | Promise< | { level: … | …; revision: string; grantedBy: string; } | null> | null; keys?: Readonly<{ live: Promise< | Readonly<{ keyId: …; owner: …; grantVersion: …; grants: …; }> | null>; }>; guestLimits?: Partial<Readonly<{ cpuMs: number; subRequests: number; }>>; mcp?: Readonly<{ handleRequest: (request) => Promise<Response>; close?: () => Promise<void>; }>; git?: Readonly<{ writerOf: Extract<GitWriter, { kind: "actor"; }>; workflowPass?: Promise< | Readonly<{ kind: …; actor: …; role?: …; workflow?: …; }> | null>; buildPass?: Promise< | Readonly<{ kind: …; actor: …; role?: …; workflow?: …; }> | null>; git: Promise<Readonly<{ push: Promise<…>; read: Promise<…>; binding: GitBinding; }>>; }>; ownerRoutes?: Hono<OysterEnv, BlankSchema, "/">; capabilities?: readonly Readonly<object & object>[]; workbench?: Readonly<{ directory: Promise<Readonly<{ apps: readonly …[]; roles: OysterRootRoles; computer?: … | …; }>>; storage: Pick<AppStorageWire, "read" | "write" | "reset"> & Readonly<{ events: Promise<…>; }>; }>; homeInstallationId?: string; pageScript?: string; pageAssets?: () => Promise<{ pageScript: string; publicHomeScript: string; fontStyles: string; loginFontStyles: string; shellStyles: string; grantConsentScript: string; }>; title?: string; }> | Promise<Readonly<{ approvals?: Readonly<{ submit: Promise< | { kind: …; recordId: …; description: …; } | ApprovalApplyResult>; }>; workflows?: (principal) => Promise< | Readonly<{ status: …; cancel: …; }> | null>; computerControl?: (principal) => | Readonly<{ list: Promise<…>; state: Promise<…>; start: Promise<…>; create: Promise<…>; }> | null; auth: OysterAuth; backgroundOriginKey?: () => Promise<CryptoKey>; artifacts: ArtifactStore; uiCache?: Readonly<{ match: (digest) => Promise<… | …>; put: (digest, bytes) => Promise<… | …>; }>; installations: InstallationStore; instances: InstanceDirectory; bootUi: (release) => Promise< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: …; errorName?: …; finalUrlPath: …; consoleErrors: …; pageErrors: …; failedRequests: …; droppedCount: …; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; }>; computerId?: string; computer?: (principal) => | Readonly<{ getCapabilities: (signal) => …; call: (capabilityId, input, context) => …; }> | Promise<Readonly<…> | null> | null; appToolPolicy?: (actor) => | { level: "read" | "write"; revision: string; grantedBy: string; } | Promise< | { level: …; revision: …; grantedBy: …; } | null> | null; keys?: Readonly<{ live: Promise<Readonly<…> | null>; }>; guestLimits?: Partial<Readonly<{ cpuMs: number; subRequests: number; }>>; mcp?: Readonly<{ handleRequest: (request) => Promise<Response>; close?: () => Promise<…>; }>; git?: Readonly<{ writerOf: Extract<GitWriter, { kind: "actor"; }>; workflowPass?: Promise<Readonly<…> | null>; buildPass?: Promise<Readonly<…> | null>; git: Promise<Readonly<{ push: …; read: …; binding: …; }>>; }>; ownerRoutes?: Hono<OysterEnv, BlankSchema, "/">; capabilities?: readonly Readonly<object & object>[]; workbench?: Readonly<{ directory: Promise<Readonly<{ apps: …; roles: …; computer?: …; }>>; storage: Pick<AppStorageWire, … | … | …> & Readonly<{ events: …; }>; }>; homeInstallationId?: string; pageScript?: string; pageAssets?: () => Promise<{ pageScript: string; publicHomeScript: string; fontStyles: string; loginFontStyles: string; shellStyles: string; grantConsentScript: string; }>; title?: string; }>>

Returns

(ctx, env) => WorkerEntrypoint<Env, unknown> & object

---

createOysterMcpOwner()fnfunction

Signature

function createOysterMcpOwner<Env>(host): (ctx, env) => OysterMcpOwner<Env>;

Bind the owner to the deployment’s existing host factory and options.

Type Parameters

Type Parameter
Env extends Readonly<{ LOADER: WorkerLoader; }>

Parameters

Parameter

Type

host

(env, scope) => | Readonly<{ approvals?: Readonly<{ submit: Promise< | { kind: "pending_approval"; recordId: string; description: { title: …; inputBytes: …; inputSha256: …; }; } | ApprovalApplyResult>; }>; workflows?: (principal) => Promise< | Readonly<{ status: Promise<…>; cancel: Promise<…>; }> | null>; computerControl?: (principal) => | Readonly<{ list: Promise<{ computers: …; nextOffset: …; }>; state: Promise<… | …>; start: Promise<… | …>; create: Promise<… | …>; }> | null; auth: OysterAuth; backgroundOriginKey?: () => Promise<CryptoKey>; artifacts: ArtifactStore; uiCache?: Readonly<{ match: (digest) => Promise<ReadableStream<…> | null>; put: (digest, bytes) => Promise<"stored" | "unstored">; }>; installations: InstallationStore; instances: InstanceDirectory; bootUi: (release) => Promise< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: … | … | … | … | …; errorName?: … | … | … | … | … | … | … | …; finalUrlPath: string; consoleErrors: …[]; pageErrors: …[]; failedRequests: …[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; }>; computerId?: string; computer?: (principal) => | Readonly<{ getCapabilities: (signal) => Promise<…>; call: (capabilityId, input, context) => Promise<…>; }> | Promise< | Readonly<{ getCapabilities: …; call: …; }> | null> | null; appToolPolicy?: (actor) => | { level: "read" | "write"; revision: string; grantedBy: string; } | Promise< | { level: … | …; revision: string; grantedBy: string; } | null> | null; keys?: Readonly<{ live: Promise< | Readonly<{ keyId: …; owner: …; grantVersion: …; grants: …; }> | null>; }>; guestLimits?: Partial<Readonly<{ cpuMs: number; subRequests: number; }>>; mcp?: Readonly<{ handleRequest: (request) => Promise<Response>; close?: () => Promise<void>; }>; git?: Readonly<{ writerOf: Extract<GitWriter, { kind: "actor"; }>; workflowPass?: Promise< | Readonly<{ kind: …; actor: …; role?: …; workflow?: …; }> | null>; buildPass?: Promise< | Readonly<{ kind: …; actor: …; role?: …; workflow?: …; }> | null>; git: Promise<Readonly<{ push: Promise<…>; read: Promise<…>; binding: GitBinding; }>>; }>; ownerRoutes?: Hono<OysterEnv, BlankSchema, "/">; capabilities?: readonly Readonly<object & object>[]; workbench?: Readonly<{ directory: Promise<Readonly<{ apps: readonly …[]; roles: OysterRootRoles; computer?: … | …; }>>; storage: Pick<AppStorageWire, "read" | "write" | "reset"> & Readonly<{ events: Promise<…>; }>; }>; homeInstallationId?: string; pageScript?: string; pageAssets?: () => Promise<{ pageScript: string; publicHomeScript: string; fontStyles: string; loginFontStyles: string; shellStyles: string; grantConsentScript: string; }>; title?: string; }> | Promise<Readonly<{ approvals?: Readonly<{ submit: Promise< | { kind: …; recordId: …; description: …; } | ApprovalApplyResult>; }>; workflows?: (principal) => Promise< | Readonly<{ status: …; cancel: …; }> | null>; computerControl?: (principal) => | Readonly<{ list: Promise<…>; state: Promise<…>; start: Promise<…>; create: Promise<…>; }> | null; auth: OysterAuth; backgroundOriginKey?: () => Promise<CryptoKey>; artifacts: ArtifactStore; uiCache?: Readonly<{ match: (digest) => Promise<… | …>; put: (digest, bytes) => Promise<… | …>; }>; installations: InstallationStore; instances: InstanceDirectory; bootUi: (release) => Promise< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: …; errorName?: …; finalUrlPath: …; consoleErrors: …; pageErrors: …; failedRequests: …; droppedCount: …; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; }>; computerId?: string; computer?: (principal) => | Readonly<{ getCapabilities: (signal) => …; call: (capabilityId, input, context) => …; }> | Promise<Readonly<…> | null> | null; appToolPolicy?: (actor) => | { level: "read" | "write"; revision: string; grantedBy: string; } | Promise< | { level: …; revision: …; grantedBy: …; } | null> | null; keys?: Readonly<{ live: Promise<Readonly<…> | null>; }>; guestLimits?: Partial<Readonly<{ cpuMs: number; subRequests: number; }>>; mcp?: Readonly<{ handleRequest: (request) => Promise<Response>; close?: () => Promise<…>; }>; git?: Readonly<{ writerOf: Extract<GitWriter, { kind: "actor"; }>; workflowPass?: Promise<Readonly<…> | null>; buildPass?: Promise<Readonly<…> | null>; git: Promise<Readonly<{ push: …; read: …; binding: …; }>>; }>; ownerRoutes?: Hono<OysterEnv, BlankSchema, "/">; capabilities?: readonly Readonly<object & object>[]; workbench?: Readonly<{ directory: Promise<Readonly<{ apps: …; roles: …; computer?: …; }>>; storage: Pick<AppStorageWire, … | … | …> & Readonly<{ events: …; }>; }>; homeInstallationId?: string; pageScript?: string; pageAssets?: () => Promise<{ pageScript: string; publicHomeScript: string; fontStyles: string; loginFontStyles: string; shellStyles: string; grantConsentScript: string; }>; title?: string; }>>

Returns

(ctx, env) => OysterMcpOwner<Env>

---

r2FileSource()fnfunction

Signature

function r2FileSource(bucket, prefix): FileSource;

Files in an R2 bucket under prefix (one workspace per prefix).

Parameters

Parameter	Type
bucket	R2Bucket
prefix	string

Returns

FileSource

---

oysterBindingEntrypoint()fnfunction

Signature

function oysterBindingEntrypoint<Env>(table): typeof WorkerEntrypoint;

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.

Type Parameters

Type Parameter

Env extends Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }>; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string; AGENT_DIRECTORY?: Readonly<{ getByName: Readonly<{ readCreator: Promise<string | null>; }>; }>; OYSTER_ORIGIN: string; MCP: DurableObjectNamespace<OysterMcpOwner<Readonly<{ LOADER: WorkerLoader; }>>>; RELEASES: R2Bucket; REGISTRY: DurableObjectNamespace<OysterRegistry<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; INSTANCES: DurableObjectNamespace<OysterInstance<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; LOADER: WorkerLoader; }>

Parameters

Parameter	Type
table	OysterBindingTable<Env>

Returns

typeof WorkerEntrypoint

---

serveOysterBootCapability()fnfunction

Signature

function serveOysterBootCapability(
  request,
  env,
  scope,
): Promise<Response | null>;

Resolve a scoped boot URL through the registry-backed HTTPS asset route.

Parameters

Parameter	Type
request	Request
env	OysterWorkerEnv
scope	TenantScope

Returns

Promise<Response | null>

---

oysterWorkerHost()fnfunction

Signature

function oysterWorkerHost(env, auth, options?): OysterHost;

Create an Oyster host backed by this Worker environment’s registry, artifacts, Instances, and boot-check service.

Parameters

Parameter	Type
env	OysterWorkerEnv
auth	OysterAuth
options	Pick<Readonly<{ approvals?: Readonly<{ submit: Promise< | { kind: "pending_approval"; recordId: string; description: { title: …; inputBytes: …; inputSha256: …; }; } | ApprovalApplyResult>; }>; workflows?: (principal) => Promise< | Readonly<{ status: Promise<…>; cancel: Promise<…>; }> | null>; computerControl?: (principal) => | Readonly<{ list: Promise<{ computers: …; nextOffset: …; }>; state: Promise<… | …>; start: Promise<… | …>; create: Promise<… | …>; }> | null; auth: OysterAuth; backgroundOriginKey?: () => Promise<CryptoKey>; artifacts: ArtifactStore; uiCache?: Readonly<{ match: (digest) => Promise<ReadableStream<…> | null>; put: (digest, bytes) => Promise<"stored" | "unstored">; }>; installations: InstallationStore; instances: InstanceDirectory; bootUi: (release) => Promise< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: … | … | … | … | …; errorName?: … | … | … | … | … | … | … | …; finalUrlPath: string; consoleErrors: …[]; pageErrors: …[]; failedRequests: …[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; }>; computerId?: string; computer?: (principal) => | Readonly<{ getCapabilities: (signal) => Promise<…>; call: (capabilityId, input, context) => Promise<…>; }> | Promise< | Readonly<{ getCapabilities: …; call: …; }> | null> | null; appToolPolicy?: (actor) => | { level: "read" | "write"; revision: string; grantedBy: string; } | Promise< | { level: … | …; revision: string; grantedBy: string; } | null> | null; keys?: Readonly<{ live: Promise< | Readonly<{ keyId: …; owner: …; grantVersion: …; grants: …; }> | null>; }>; guestLimits?: Partial<Readonly<{ cpuMs: number; subRequests: number; }>>; mcp?: Readonly<{ handleRequest: (request) => Promise<Response>; close?: () => Promise<void>; }>; git?: Readonly<{ writerOf: Extract<GitWriter, { kind: "actor"; }>; workflowPass?: Promise< | Readonly<{ kind: …; actor: …; role?: …; workflow?: …; }> | null>; buildPass?: Promise< | Readonly<{ kind: …; actor: …; role?: …; workflow?: …; }> | null>; git: Promise<Readonly<{ push: Promise<…>; read: Promise<…>; binding: GitBinding; }>>; }>; ownerRoutes?: Hono<OysterEnv, BlankSchema, "/">; capabilities?: readonly Readonly<object & object>[]; workbench?: Readonly<{ directory: Promise<Readonly<{ apps: readonly …[]; roles: OysterRootRoles; computer?: … | …; }>>; storage: Pick<AppStorageWire, "read" | "write" | "reset"> & Readonly<{ events: Promise<…>; }>; }>; homeInstallationId?: string; pageScript?: string; pageAssets?: () => Promise<{ pageScript: string; publicHomeScript: string; fontStyles: string; loginFontStyles: string; shellStyles: string; grantConsentScript: string; }>; title?: string; }>, "appToolPolicy" | "guestLimits"> & Readonly<{ workspace?: Readonly<{ computerId: string; files: FileSource; computer?: (principal) => | Readonly<{ getCapabilities: …; call: …; }> | Promise<… | …> | null; }>; scope?: Readonly<{ tenantId: string & Brand<"OysterTenantId">; origin: string; durableName: string; computerName: string; workspacePrefix: string; repositoryPrefix: string; }>; }>

Returns

OysterHost

---

createOysterWorker()fnfunction

Signature

function createOysterWorker(options?): ExportedHandler<Readonly<{
  BROWSER?: Readonly<{
     fetch: HttpFetch;
  }>;
  OYSTER_OWNER_KEY: string;
  OYSTER_OWNER_NAME?: string;
  AGENT_DIRECTORY?: Readonly<{
     getByName: Readonly<{
        readCreator: Promise<string | null>;
     }>;
  }>;
  OYSTER_ORIGIN: string;
  MCP: DurableObjectNamespace<OysterMcpOwner<Readonly<{
     LOADER: WorkerLoader;
  }>>>;
  RELEASES: R2Bucket;
  REGISTRY: DurableObjectNamespace<OysterRegistry<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<...>; }> | undefined; ... 5 more ...; LOADER: WorkerLoader; }>>>;
  INSTANCES: DurableObjectNamespace<OysterInstance<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<...>; }> | undefined; ... 5 more ...; LOADER: WorkerLoader; }>>>;
  LOADER: WorkerLoader;
}>>;

The standalone Worker’s fetch handler; frontend hosts are cached per env. MCP transports belong to the tenant Durable Object, independent of that cache.

Parameters

Parameter	Type
options	Pick<OysterHost, "guestLimits">

Returns

ExportedHandler<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }>; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string; AGENT_DIRECTORY?: Readonly<{ getByName: Readonly<{ readCreator: Promise<string | null>; }>; }>; OYSTER_ORIGIN: string; MCP: DurableObjectNamespace<OysterMcpOwner<Readonly<{ LOADER: WorkerLoader; }>>>; RELEASES: R2Bucket; REGISTRY: DurableObjectNamespace<OysterRegistry<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; INSTANCES: DurableObjectNamespace<OysterInstance<Readonly<{ BROWSER?: Readonly<{ fetch: HttpFetch; }> | undefined; OYSTER_OWNER_KEY: string; OYSTER_OWNER_NAME?: string | undefined; AGENT_DIRECTORY?: Readonly<{ getByName(name: string): Readonly<…>; }> | undefined; … 5 more …; LOADER: WorkerLoader; }>>>; LOADER: WorkerLoader; }>>

References

r2ArtifactStore

Re-exports r2ArtifactStore

---

ownerKeyAuth

Re-exports ownerKeyAuth