Skip to content
Oyster0.6.0
API reference

workers-git

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/oyster/workers-git";

Exports

Section titled “Exports”
Kind Export Description
class OysterKeys Named keys an owner issues directly: an Ear Tag key store scoped to this tenant. A key’s id is the name the owner chose for it, so forks and other name-derived identities (service.ts:95) stay stable across a reissue. Plaintext keys are never stored.
class OysterWebhooks The tenant’s App event delivery owner: webhook subscriptions with signed, retried deliveries, and host recipients with durable per-recipient records. An emit commits here and returns; every delivery happens on the alarm.
class OysterBinding A git Worker’s one guest binding entrypoint, over gitBindings.
class abstract OysterGitInstance An App Instance whose backend may also receive declared Git and Events bindings. Background wakes readmit members through the deployable root’s hostFor, the same composition HTTP and MCP use.
type alias HostEventSource The emitting installation as the host attested it on the emit’s frame.
type alias HostRecipientEvent One accepted event, as a host recipient receives it.
type alias RecipientDelivery One recipient’s delivery record for one event.
type alias ArtifactsGit The GIT binding plus the credential only the host’s git door may use.
type alias OysterKeysEnv Bindings the keys and webhook objects need: none of their own.
type alias WebhookSubscription One webhook subscription for an installation’s events.
type alias SubscriptionCreated A new subscription and its signing secret, shown once.
type alias WebhookDelivery One delivery attempt record.
type alias OysterGitEnv Bindings the git adapters read from a standalone Oyster Worker.
type alias OysterGitWorkerEnv A standalone Oyster Worker that also hosts git Apps.
type alias OysterGitWorkerOptions One deployable Git root’s options. Every door (HTTP, MCP, Agents, Workflows, background wakes) composes its tenant host from this one value through oysterGitRoot(options).hostFor.
type alias OysterGitWorkerHost A tenant’s whole Git host: the App server, host.git and the owner routes.
type alias OysterKeysLivePort host.keys.live’s own shape: the live facts behind a key id, re-checked against the tenant’s current owner on every read; null for an unknown, revoked, expired, suspended key, or one a since-reassigned tenant’s former owner held. The one path every caller – the HTTP/MCP host, a workspace’s own Computer admission – reaches a key’s liveness through.
type alias OysterGitRoot The one composition root of a Git Worker; build it once from its options.
type alias OysterWorkerGitOptions What oysterWorkerGit needs beyond the Worker’s bindings.
type alias OysterGitFrame One live guest frame’s Git custody; never a guest argument.
constant eventsBinding EVENTS for a host with webhook subscribers only.
constant gitBindings The plain host’s bindings plus native GIT over Artifacts and signed EVENTS.
function createArtifactsGit() The GIT binding over Artifacts for one installation (prefix scopes its names). Credentials remain host-held and are reused until thirty seconds before the provider expiry or eight minutes, whichever comes first. Every operation still checks its captured grant. Provider 401/403 discards the credential for remint.
function artifactsOf() The Artifacts namespace: the binding when present, else the REST API.
function eventsBindingFor() EVENTS: commit the emit to this tenant’s delivery owner and return. Webhook subscribers and the host recipients a root names are delivered afterwards, so a subscriber outage never fails the emitting App’s write.
function gitAdminRoutes() Owner routes for keys and webhooks; createOyster mounts them owner-only.
function oysterGitRoot() Compose a Git Worker’s root from its one options value.
function ownerOrKeyTenancy() The single-owner root’s tenancy: the owner key or a named key, at the configured origin only.
function createOysterGitWorker() The standalone Worker’s fetch handler with the git door and owner routes.
function oysterWorkerGit() host.git for an Oyster Worker: the git door’s writer projection and the admitted, installation-scoped Artifacts path with the App’s push policy and the Instance journal. Set it on your own createOyster host; the full standalone composition (oysterGitWorkerHost) uses this same builder.
function oysterGitWorkerHost() One selected tenant’s whole host from a root’s options. Roots reach it through oysterGitRoot(options).hostFor; a cold directory passes its own resolved tenant.
function createOysterGitMcpOwner() Deploy the MCP owner from the same root as createOysterGitWorker.

OysterKeysclass

Section titled “OysterKeys”

Named keys an owner issues directly: an Ear Tag key store scoped to this tenant. A key’s id is the name the owner chose for it, so forks and other name-derived identities (service.ts:95) stay stable across a reissue. Plaintext keys are never stored.

Extends

Section titled “Extends”

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new OysterKeys(ctx, env): OysterKeys;
Parameters
Section titled “Parameters”
Parameter Type
ctx DurableObjectState
env OysterKeysEnv
Returns
Section titled “Returns”

OysterKeys

Overrides
Section titled “Overrides”
Signature
DurableObject<OysterKeysEnv>.constructor

Methods

Section titled “Methods”

issue()

Section titled “issue()”
Signature
issue(owner, input): Promise<KeyOutcome<Readonly<{
  key: string;
  record: KeyRecord<Capability>;
}>>>;

Issue a key named name, its id too. Refuses conflict once a name has been used, including by a now-revoked key: a name is never reused.

Parameters
Section titled “Parameters”
Parameter Type
owner string
input Readonly<{ name: string; grants: readonly Grant<OysterKeyCapability>[]; expiresAt?: number; }>
Returns
Section titled “Returns”

Promise<KeyOutcome<Readonly<{ key: string; record: KeyRecord<Capability>; }>>>

revoke()

Section titled “revoke()”
Signature
revoke(
   owner,
   requestId,
   keyId
): Promise<KeyOutcome<Readonly<{
  keyId: string;
  owner: string;
  name: string;
  scope:   | Readonly<{
     grants: readonly Readonly<{
        capability: OysterKeyCapability;
        targets: GrantTargets;
     }>[];
   }>
     | null;
  grantVersion: number;
  expiresAt: number | null;
  revokedAt: number | null;
  rateLimit:   | Readonly<{
     limit: number;
     windowSeconds: number;
   }>
     | null;
  lastUsedAt: number | null;
  createdAt: number;
  updatedAt: number;
}>>>;

Revoke a key by id; idempotent on repeat.

Parameters
Section titled “Parameters”
Parameter Type
owner string
requestId string
keyId string
Returns
Section titled “Returns”

Promise<KeyOutcome<Readonly<{ keyId: string; owner: string; name: string; scope: | Readonly<{ grants: readonly Readonly<{ capability: OysterKeyCapability; targets: GrantTargets; }>[]; }> | null; grantVersion: number; expiresAt: number | null; revokedAt: number | null; rateLimit: | Readonly<{ limit: number; windowSeconds: number; }> | null; lastUsedAt: number | null; createdAt: number; updatedAt: number; }>>>

list()

Section titled “list()”
Signature
list(owner): Promise<KeyOutcome<readonly Readonly<{
  keyId: string;
  owner: string;
  name: string;
  scope:   | Readonly<{
     grants: readonly Readonly<{
        capability: ...;
        targets: ...;
     }>[];
   }>
     | null;
  grantVersion: number;
  expiresAt: number | null;
  revokedAt: number | null;
  rateLimit:   | Readonly<{
     limit: number;
     windowSeconds: number;
   }>
     | null;
  lastUsedAt: number | null;
  createdAt: number;
  updatedAt: number;
}>[]>>;

Every key this tenant has issued, newest first.

Parameters
Section titled “Parameters”
Parameter Type
owner string
Returns
Section titled “Returns”

Promise<KeyOutcome<readonly Readonly<{ keyId: string; owner: string; name: string; scope: | Readonly<{ grants: readonly Readonly<{ capability: …; targets: …; }>[]; }> | null; grantVersion: number; expiresAt: number | null; revokedAt: number | null; rateLimit: | Readonly<{ limit: number; windowSeconds: number; }> | null; lastUsedAt: number | null; createdAt: number; updatedAt: number; }>[]>>

verify()

Section titled “verify()”
Signature
verify(secret): Promise<KeyOutcome<Readonly<{
  keyId: string;
  owner: string;
  name: string;
  scope: Scope<Capability>;
  grantVersion: number;
  expiresAt: number | null;
}>>>;

Verify a bearer secret and return its current principal.

Parameters
Section titled “Parameters”
Parameter Type
secret string
Returns
Section titled “Returns”

Promise<KeyOutcome<Readonly<{ keyId: string; owner: string; name: string; scope: Scope<Capability>; grantVersion: number; expiresAt: number | null; }>>>

live()

Section titled “live()”
Signature
live(keyId): Promise<
  | Readonly<{
  keyId: string;
  owner: string;
  grantVersion: number;
  grants: readonly Readonly<{
     capability: OysterKeyCapability;
     targets: GrantTargets;
  }>[];
}>
| null>;

The live facts behind one key id, for the host’s keys.live port; null for an unknown, revoked, expired or suspended key.

Parameters
Section titled “Parameters”
Parameter Type
keyId string
Returns
Section titled “Returns”

Promise< | Readonly<{ keyId: string; owner: string; grantVersion: number; grants: readonly Readonly<{ capability: OysterKeyCapability; targets: GrantTargets; }>[]; }> | null>

OysterWebhooksclass

Section titled “OysterWebhooks”

The tenant’s App event delivery owner: webhook subscriptions with signed, retried deliveries, and host recipients with durable per-recipient records. An emit commits here and returns; every delivery happens on the alarm.

Extends

Section titled “Extends”
  • DurableObject<Env>

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
Env extends OysterKeysEnv OysterKeysEnv

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new OysterWebhooks<Env>(ctx, env): OysterWebhooks<Env>;
Parameters
Section titled “Parameters”
Parameter Type
ctx DurableObjectState
env Env
Returns
Section titled “Returns”

OysterWebhooks<Env>

Overrides
Section titled “Overrides”
Signature
DurableObject<Env>.constructor

Methods

Section titled “Methods”

recipientDeliveries()

Section titled “recipientDeliveries()”
Signature
recipientDeliveries(recipient): Readonly<{
  recipient: string;
  eventId: string;
  type: string;
  state: "pending" | "failed" | "delivered";
  attempts: number;
  lastError: string | null;
  updatedAt: number;
}>[];

Recent deliveries to one host recipient, newest first.

Parameters
Section titled “Parameters”
Parameter Type
recipient string
Returns
Section titled “Returns”

Readonly<{ recipient: string; eventId: string; type: string; state: "pending" | "failed" | "delivered"; attempts: number; lastError: string | null; updatedAt: number; }>[]

subscribe()

Section titled “subscribe()”
Signature
subscribe(input): SubscriptionCreated;

Subscribe url to an installation’s events; returns the secret once.

Parameters
Section titled “Parameters”
Parameter Type
input { installationId: string; url: string; types: readonly string[]; secret?: string; }
input.installationId string
input.url string
input.types readonly string[]
input.secret? string
Returns
Section titled “Returns”

SubscriptionCreated

subscriptions()

Section titled “subscriptions()”
Signature
subscriptions(): Readonly<{
  id: string;
  installationId: string;
  url: string;
  types: readonly string[];
  createdAt: number;
}>[];

Every subscription.

Returns
Section titled “Returns”

Readonly<{ id: string; installationId: string; url: string; types: readonly string[]; createdAt: number; }>[]

unsubscribe()

Section titled “unsubscribe()”
Signature
unsubscribe(id): boolean;

Remove a subscription and its deliveries.

Parameters
Section titled “Parameters”
Parameter Type
id string
Returns
Section titled “Returns”

boolean

deliveries()

Section titled “deliveries()”
Signature
deliveries(subscription): Readonly<{
  id: string;
  subscription: string;
  type: string;
  state: "pending" | "failed" | "delivered";
  attempts: number;
  lastStatus: number | null;
  updatedAt: number;
}>[];

Recent deliveries for one subscription, newest first.

Parameters
Section titled “Parameters”
Parameter Type
subscription string
Returns
Section titled “Returns”

Readonly<{ id: string; subscription: string; type: string; state: "pending" | "failed" | "delivered"; attempts: number; lastStatus: number | null; updatedAt: number; }>[]

enqueue()

Section titled “enqueue()”
Signature
enqueue(
   source,
   payload,
   eventId,
   recipients
): Promise<number>;

Accept an emitted event: queue it for every matching subscription and every named host recipient (idempotent per event id). Nothing is delivered before this returns, so no recipient can fail the emitter’s write.

Parameters
Section titled “Parameters”
Parameter Type
source HostEventSource
payload StandardWebhookPayload
eventId string
recipients readonly string[]
Returns
Section titled “Returns”

Promise<number>

alarm()

Section titled “alarm()”
Signature
alarm(): Promise<void>;

Deliver due webhooks and recipient rows, then schedule the next retry.

Returns
Section titled “Returns”

Promise<void>

Overrides
Section titled “Overrides”
Signature
DurableObject.alarm;

OysterBindingclass

Section titled “OysterBinding”

A git Worker’s one guest binding entrypoint, over gitBindings.

Extends

Section titled “Extends”
  • WorkerEntrypoint<OysterGitWorkerEnv, Readonly<{ instanceId: string; binding: | "BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS"; frameId: string; }>, this>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new OysterBinding(ctx, env): OysterBinding;
Parameters
Section titled “Parameters”
Parameter Type
ctx ExecutionContext
env OysterGitWorkerEnv
Returns
Section titled “Returns”

OysterBinding

Inherited from
Section titled “Inherited from”
Signature
oysterBindingEntrypoint(gitBindings).constructor;

abstract OysterGitInstanceclass

Section titled “abstract OysterGitInstance”

An App Instance whose backend may also receive declared Git and Events bindings. Background wakes readmit members through the deployable root’s hostFor, the same composition HTTP and MCP use.

Extends

Section titled “Extends”

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
Env extends OysterGitWorkerEnv OysterGitWorkerEnv

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new OysterGitInstance<Env>(ctx, env): OysterGitInstance<Env>;
Parameters
Section titled “Parameters”
Parameter Type
ctx DurableObjectState
env Env
Returns
Section titled “Returns”

OysterGitInstance<Env>

Inherited from
Section titled “Inherited from”

OysterInstance.constructor

Methods

Section titled “Methods”

bindingCall()

Section titled “bindingCall()”
Signature
bindingCall(
   raw,
   method,
   input
): Promise<FrameBindingReply<OysterBindingResult>>;

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

Parameters
Section titled “Parameters”
Parameter Type
raw FrameBindingProps
method string
input readonly unknown[]
Returns
Section titled “Returns”

Promise<FrameBindingReply<OysterBindingResult>>

Inherited from
Section titled “Inherited from”

OysterInstance.bindingCall

gitTip()

Section titled “gitTip()”
Signature
gitTip(
   installationId,
   repository,
   ref,
   tenantId?
): Promise<string | null>;

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

Parameters
Section titled “Parameters”
Parameter Type Default value
installationId string undefined
repository string undefined
ref string undefined
tenantId string & Brand<"OysterTenantId"> defaultTenant
Returns
Section titled “Returns”

Promise<string | null>

Inherited from
Section titled “Inherited from”

OysterInstance.gitTip

recordGitPush()

Section titled “recordGitPush()”
Signature
recordGitPush(
   installationId,
   fact,
   tenantId?
): Promise<"duplicate" | "recorded">;

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

Parameters
Section titled “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
Section titled “Returns”

Promise<"duplicate" | "recorded">

Inherited from
Section titled “Inherited from”

OysterInstance.recordGitPush

alarm()

Section titled “alarm()”
Signature
alarm(): Promise<void>;

Carrier owns retries, dead letters and retained delivery receipts.

Returns
Section titled “Returns”

Promise<void>

Inherited from
Section titled “Inherited from”

OysterInstance.alarm

revoke()

Section titled “revoke()”
Signature
revoke(
   installationId,
   runId?,
   tenantId?
): Promise<void>;

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

Parameters
Section titled “Parameters”
Parameter Type Default value
installationId string undefined
runId? string undefined
tenantId? string & Brand<"OysterTenantId"> defaultTenant
Returns
Section titled “Returns”

Promise<void>

Inherited from
Section titled “Inherited from”

OysterInstance.revoke

prepare()

Section titled “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
Section titled “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
Section titled “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>>

Inherited from
Section titled “Inherited from”

OysterInstance.prepare

apply()

Section titled “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
Section titled “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
Section titled “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"; }>>

Inherited from
Section titled “Inherited from”

OysterInstance.apply

backend()

Section titled “backend()”
Signature
backend(
   facts,
   request,
   limits?,
   tenantId?
): Promise<Response>;

Forward an admitted HTTP request to the App backend.

Parameters
Section titled “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
Section titled “Returns”

Promise<Response>

Inherited from
Section titled “Inherited from”

OysterInstance.backend

onGitPush()

Section titled “onGitPush()”
Signature
onGitPush(
   facts,
   fact,
   limits?,
   tenantId?
): Promise<void>;

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

Parameters
Section titled “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
Section titled “Returns”

Promise<void>

Inherited from
Section titled “Inherited from”

OysterInstance.onGitPush

authorizeGitPush()

Section titled “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
Section titled “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
Section titled “Returns”

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

Inherited from
Section titled “Inherited from”

OysterInstance.authorizeGitPush

syncRefused()

Section titled “syncRefused()”
Signature
syncRefused(
   facts,
   refusal,
   limits?,
   tenantId?
): Promise<void>;

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

Parameters
Section titled “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
Section titled “Returns”

Promise<void>

Inherited from
Section titled “Inherited from”

OysterInstance.syncRefused

gill()

Section titled “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
Section titled “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
Section titled “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; }>>

Inherited from
Section titled “Inherited from”

OysterInstance.gill

call()

Section titled “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
Section titled “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
Section titled “Returns”

Promise<InstanceResult<Json>>

Inherited from
Section titled “Inherited from”

OysterInstance.call

HostEventSourcetype alias

Section titled “HostEventSource”
Signature
type HostEventSource = Readonly<{
  installationId: string;
  appId: string;
  releaseId: string;
}>;

The emitting installation as the host attested it on the emit’s frame.

HostRecipientEventtype alias

Section titled “HostRecipientEvent”
Signature
type HostRecipientEvent = Readonly<{
  source: HostEventSource;
  type: string;
  eventId: string;
  payload: Readonly<{
    type: string;
    timestamp: string;
    data: unknown;
  }>;
}>;

One accepted event, as a host recipient receives it.

RecipientDeliverytype alias

Section titled “RecipientDelivery”
Signature
type RecipientDelivery = Readonly<{
  recipient: string;
  eventId: string;
  type: string;
  state: "pending" | "delivered" | "failed";
  attempts: number;
  lastError: string | null;
  updatedAt: number;
}>;

One recipient’s delivery record for one event.

ArtifactsGittype alias

Section titled “ArtifactsGit”
Signature
type ArtifactsGit = Omit<GitBinding, "cloneUrl"> &
  Readonly<{
    credential: Promise<
      Readonly<{
        remote: string;
        token: string;
      }>
    >;
  }>;

The GIT binding plus the credential only the host’s git door may use.

OysterKeysEnvtype alias

Section titled “OysterKeysEnv”
Signature
type OysterKeysEnv = Readonly<Record<never, never>>;

Bindings the keys and webhook objects need: none of their own.

WebhookSubscriptiontype alias

Section titled “WebhookSubscription”
Signature
type WebhookSubscription = Readonly<{
  id: string;
  installationId: string;
  url: string;
  types: readonly string[];
  createdAt: number;
}>;

One webhook subscription for an installation’s events.

SubscriptionCreatedtype alias

Section titled “SubscriptionCreated”
Signature
type SubscriptionCreated = Readonly<{
  subscription: WebhookSubscription;
  secret: string;
}>;

A new subscription and its signing secret, shown once.

WebhookDeliverytype alias

Section titled “WebhookDelivery”
Signature
type WebhookDelivery = Readonly<{
  id: string;
  subscription: string;
  type: string;
  state: "pending" | "delivered" | "failed";
  attempts: number;
  lastStatus: number | null;
  updatedAt: number;
}>;

One delivery attempt record.

OysterGitEnvtype alias

Section titled “OysterGitEnv”
Signature
type OysterGitEnv = Readonly<{
  ARTIFACTS?: ArtifactsNamespace;
  ARTIFACTS_ACCOUNT_ID?: string;
  ARTIFACTS_NAMESPACE?: string;
  ARTIFACTS_API_TOKEN?: string;
  KEYS: DurableObjectNamespace<OysterKeys>;
  WEBHOOKS: DurableObjectNamespace<OysterWebhooks>;
}>;

Bindings the git adapters read from a standalone Oyster Worker.

OysterGitWorkerEnvtype alias

Section titled “OysterGitWorkerEnv”
Signature
type OysterGitWorkerEnv = OysterWorkerEnv &
  OysterGitEnv &
  Readonly<{
    OYSTER_ORIGIN: string;
    OYSTER_OWNER_NAME?: string;
  }>;

A standalone Oyster Worker that also hosts git Apps.

OysterGitWorkerOptionstype alias

Section titled “OysterGitWorkerOptions”
Signature
type OysterGitWorkerOptions<Env> = Readonly<{
  computerControl?: (env, scope) => NonNullable<OysterHost["computerControl"]>;
  workflows?: (env, host) => NonNullable<OysterHost["workflows"]>;
  tenancy: (env) => OysterTenancy;
  homeInstallationId?: (env) => string;
  pageScript?: string;
  agents?: (env, scope) => OysterAgents;
  workspace?: (
    env,
    keysLive,
    scope,
    request?,
  ) => OysterWorkspace | Promise<OysterWorkspace>;
  capabilities?: (env, workspace, keysLive) => readonly OysterCapability[];
  workflowGitPass?: (
    env,
    scope,
    pass,
    target,
  ) => Promise<Extract<
    GitWriter,
    {
      kind: "actor";
    }
  > | null>;
  buildGitPass?: (
    env,
    scope,
    pass,
    target,
  ) => Promise<Extract<
    GitWriter,
    {
      kind: "actor";
    }
  > | null>;
  ownerRoutes?: (env, scope) => Hono<OysterEnv>;
}>;

One deployable Git root’s options. Every door (HTTP, MCP, Agents, Workflows, background wakes) composes its tenant host from this one value through oysterGitRoot(options).hostFor.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

OysterGitWorkerHosttype alias

Section titled “OysterGitWorkerHost”
Signature
type OysterGitWorkerHost = OysterHost &
  Readonly<{
    git: OysterGitHost;
  }>;

A tenant’s whole Git host: the App server, host.git and the owner routes.

OysterKeysLivePorttype alias

Section titled “OysterKeysLivePort”
Signature
type OysterKeysLivePort = (keyId) => Promise<LiveOysterKey | null>;

host.keys.live’s own shape: the live facts behind a key id, re-checked against the tenant’s current owner on every read; null for an unknown, revoked, expired, suspended key, or one a since-reassigned tenant’s former owner held. The one path every caller – the HTTP/MCP host, a workspace’s own Computer admission – reaches a key’s liveness through.

Parameters

Section titled “Parameters”
Parameter Type
keyId string

Returns

Section titled “Returns”

Promise<LiveOysterKey | null>

OysterGitRoottype alias

Section titled “OysterGitRoot”
Signature
type OysterGitRoot<Env> = Readonly<{
  admit: Promise<Readonly<{
    scope: TenantScope;
    auth: OysterAuth;
  }> | null>;
  hostFor: Promise<OysterGitWorkerHost>;
}>;

The one composition root of a Git Worker; build it once from its options.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

OysterWorkerGitOptionstype alias

Section titled “OysterWorkerGitOptions”
Signature
type OysterWorkerGitOptions<Env> = Pick<
  OysterGitWorkerOptions<Env>,
  "workflowGitPass" | "buildGitPass"
> &
  Readonly<{
    scope: TenantScope;
  }>;

What oysterWorkerGit needs beyond the Worker’s bindings.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

OysterGitFrametype alias

Section titled “OysterGitFrame”
Signature
type OysterGitFrame = Readonly<{
  invocation: InvocationFrame<OysterInvocationHost>;
  store?: ArtifactsGit;
}>;

One live guest frame’s Git custody; never a guest argument.

eventsBindingconstant

Section titled “eventsBinding”
Signature
const eventsBinding: OysterBindingRow<OysterGitWorkerEnv>;

EVENTS for a host with webhook subscribers only.

gitBindingsconstant

Section titled “gitBindings”
Signature
const gitBindings: OysterBindingTable<OysterGitWorkerEnv>;

The plain host’s bindings plus native GIT over Artifacts and signed EVENTS.

createArtifactsGit()function

Section titled “createArtifactsGit()”
Signature
function createArtifactsGit(binding, prefix, grant): ArtifactsGit;

The GIT binding over Artifacts for one installation (prefix scopes its names). Credentials remain host-held and are reused until thirty seconds before the provider expiry or eight minutes, whichever comes first. Every operation still checks its captured grant. Provider 401/403 discards the credential for remint.

Parameters

Section titled “Parameters”
Parameter Type
binding ArtifactsNamespace
prefix string
grant Readonly<{ operations: readonly string[]; beforeProvider?: () => void; }>

Returns

Section titled “Returns”

ArtifactsGit

artifactsOf()function

Section titled “artifactsOf()”
Signature
function artifactsOf(env): ArtifactsNamespace;

The Artifacts namespace: the binding when present, else the REST API.

Parameters

Section titled “Parameters”
Parameter Type
env OysterGitEnv

Returns

Section titled “Returns”

ArtifactsNamespace

eventsBindingFor()function

Section titled “eventsBindingFor()”
Signature
function eventsBindingFor<Env>(recipients): OysterBindingRow<Env>;

EVENTS: commit the emit to this tenant’s delivery owner and return. Webhook subscribers and the host recipients a root names are delivered afterwards, so a subscriber outage never fails the emitting App’s write.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

Parameters

Section titled “Parameters”
Parameter Type
recipients (context, frame) => Promise<readonly string[]>

Returns

Section titled “Returns”

OysterBindingRow<Env>

gitAdminRoutes()function

Section titled “gitAdminRoutes()”
Signature
function gitAdminRoutes(env, scope): Hono<OysterEnv>;

Owner routes for keys and webhooks; createOyster mounts them owner-only.

Parameters

Section titled “Parameters”
Parameter Type
env OysterGitEnv
scope TenantScope

Returns

Section titled “Returns”

Hono<OysterEnv>

oysterGitRoot()function

Section titled “oysterGitRoot()”
Signature
function oysterGitRoot<Env>(options): OysterGitRoot<Env>;

Compose a Git Worker’s root from its one options value.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

Parameters

Section titled “Parameters”
Parameter Type
options OysterGitWorkerOptions<Env>

Returns

Section titled “Returns”

OysterGitRoot<Env>

ownerOrKeyTenancy()function

Section titled “ownerOrKeyTenancy()”
Signature
function ownerOrKeyTenancy(env): OysterTenancy;

The single-owner root’s tenancy: the owner key or a named key, at the configured origin only.

Parameters

Section titled “Parameters”
Parameter Type
env OysterGitWorkerEnv

Returns

Section titled “Returns”

OysterTenancy

createOysterGitWorker()function

Section titled “createOysterGitWorker()”
Signature
function createOysterGitWorker<Env>(root): ExportedHandler<Env>;

The standalone Worker’s fetch handler with the git door and owner routes.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

Parameters

Section titled “Parameters”
Parameter Type
root OysterGitRoot<Env>

Returns

Section titled “Returns”

ExportedHandler<Env>

oysterWorkerGit()function

Section titled “oysterWorkerGit()”
Signature
function oysterWorkerGit<Env>(env, options, frame?): OysterGitHost;

host.git for an Oyster Worker: the git door’s writer projection and the admitted, installation-scoped Artifacts path with the App’s push policy and the Instance journal. Set it on your own createOyster host; the full standalone composition (oysterGitWorkerHost) uses this same builder.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

Parameters

Section titled “Parameters”
Parameter Type
env Env
options OysterWorkerGitOptions<Env>
frame? Readonly<{ invocation: InvocationFrame<OysterInvocationHost>; store?: ArtifactsGit; }>

Returns

Section titled “Returns”

OysterGitHost

oysterGitWorkerHost()function

Section titled “oysterGitWorkerHost()”
Signature
function oysterGitWorkerHost<Env>(
  env,
  options,
  selected,
  request?,
): Promise<OysterGitWorkerHost>;

One selected tenant’s whole host from a root’s options. Roots reach it through oysterGitRoot(options).hostFor; a cold directory passes its own resolved tenant.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

Parameters

Section titled “Parameters”
Parameter Type
env Env
options OysterGitWorkerOptions<Env>
selected ResolvedTenant
request? Request<unknown, CfProperties<unknown>>

Returns

Section titled “Returns”

Promise<OysterGitWorkerHost>

createOysterGitMcpOwner()function

Section titled “createOysterGitMcpOwner()”
Signature
function createOysterGitMcpOwner<Env>(root): (ctx, env) => OysterMcpOwner<Env>;

Deploy the MCP owner from the same root as createOysterGitWorker.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Env extends OysterGitWorkerEnv

Parameters

Section titled “Parameters”
Parameter Type
root OysterGitRoot<Env>

Returns

Section titled “Returns”

(ctx, env) => OysterMcpOwner<Env>