@fungi.computer/oyster 0.4.1 → 0.6.0

package/dist/release.d.ts

@@ -60,6 +60,19 @@ export type VerifiedRelease = Readonly<{
 export declare function sha256(bytes: Uint8Array): Promise<string>;
 /** Read one artifact and refuse it unless its bytes match `digest`. */
 export declare function readVerified(store: ArtifactStore, artifactRef: ArtifactRef, digest: Sha256Digest): Promise<Uint8Array>;
+/**
+ * Copies of verified artifacts near the reader, keyed by content digest. An
+ * entry holds only bytes that already matched its digest, so a hit is served
+ * without another store read or hash.
+ */
+export type VerifiedObjectCache = Readonly<{
+    /** The cached bytes for `digest`, or null on a miss. */
+    match: (digest: Sha256Digest) => Promise<ReadableStream<Uint8Array> | null>;
+    /** Keep verified bytes; an unstored write only costs the next reader a store read. */
+    put: (digest: Sha256Digest, bytes: Uint8Array) => Promise<"stored" | "unstored">;
+}>;
+/** {@link readVerified} through an optional digest-keyed cache it fills on a miss. */
+export declare function readCachedVerified(store: ArtifactStore, cache: VerifiedObjectCache | undefined, artifactRef: ArtifactRef, digest: Sha256Digest): Promise<ReadableStream<Uint8Array> | Uint8Array<ArrayBuffer>>;
 /** Decode an untrusted Release record, as an install request carries it. */
 export declare function parseRelease(value: unknown): Release;
 /**

package/dist/release.js

@@ -36,6 +36,16 @@ export async function readVerified(store, artifactRef, digest) {
         throw new ReleaseError("digest_mismatch", `Digest mismatch ${artifactRef}`);
     return bytes;
 }
+/** {@link readVerified} through an optional digest-keyed cache it fills on a miss. */
+export async function readCachedVerified(store, cache, artifactRef, digest) {
+    const hit = await cache?.match(digest);
+    if (hit !== undefined && hit !== null)
+        return hit;
+    const bytes = await readVerified(store, artifactRef, digest);
+    await cache?.put(digest, bytes);
+    // A response body owns a plain ArrayBuffer, whatever view the store returned.
+    return new Uint8Array(bytes);
+}
 const decodeText = (bytes) => new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes);
 /** Decode an untrusted Release record, as an install request carries it. */
 export function parseRelease(value) {

package/dist/request-origin.d.ts

@@ -0,0 +1,4 @@
+/** Require the request's own Origin and refuse cross-site provenance. */
+export declare function sameOriginRequest(request: Request): boolean;
+/** Channel reads allow absent Origin but never conflicting or cross-site provenance. */
+export declare function sameOriginReadRequest(request: Request): boolean;

package/dist/request-origin.js

@@ -0,0 +1,10 @@
+/** Require the request's own Origin and refuse cross-site provenance. */
+export function sameOriginRequest(request) {
+    return request.headers.has("origin") && sameOriginReadRequest(request);
+}
+/** Channel reads allow absent Origin but never conflicting or cross-site provenance. */
+export function sameOriginReadRequest(request) {
+    const origin = request.headers.get("origin");
+    return (request.headers.get("sec-fetch-site") !== "cross-site" &&
+        (origin === null || origin === new URL(request.url).origin));
+}

package/dist/standalone/agent-mail.js

@@ -23,6 +23,7 @@ export function agentMail(options) {
         if (tick === undefined)
             throw new Error("Agent Post lane is not open");
         await tick();
+        await mail.stageUndeliverableReplies();
     };
     const mail = new AgentMail({ ...options, post: runtime, drain });
     const host = {
@@ -57,6 +58,8 @@ export function agentMail(options) {
     };
     return {
         host,
-        deliver: (value) => mail.send(value),
+        deliver: (value) => {
+            return mail.send(value);
+        },
     };
 }

package/dist/standalone/agents.d.ts

@@ -1,5 +1,7 @@
 import { type StandaloneTenancyEnv } from "./tenancy.js";
 import type { PostEnvelope } from "@fungi.computer/carrier/post";
+import { type ChannelConversations } from "../channels/conversations.js";
+import type { ConversationBinding } from "../channels/binding.js";
 import { type StandaloneMachineLinkBindings, type StandaloneMachineJoinResult } from "./machine-link.js";
 import { type MachineAgentSettlementPrincipal, type MachineAgentHome, type MachineEnrollment, type MachineLinkCaller, type MachineLinkIdentity } from "../machine-link/index.js";
 /** Workers AI binding surface used by the standalone provider adapter. */
@@ -78,6 +80,12 @@ export declare abstract class StandaloneAgentBase<Env extends StandaloneAgentEnv
     #private;
     /** The deployable root's host for this Agent's pinned tenant. */
     protected abstract hostFor(scope: TenantScope): Promise<OysterHost>;
+    /**
+     * Compose Oyster's channel owner on this Agent's real store and Shiitake.
+     * A host must supply its own binding lookup after authenticating its edge;
+     * this does not install an inbound route or mint provider credentials.
+     */
+    protected channelConversations(binding: (bindingId: string) => ConversationBinding | null): ChannelConversations;
     private uiOwner;
     private machineClient;
     private computerSnapshot;

package/dist/standalone/agents.js

@@ -1,5 +1,4 @@
-import { normalizeModel, streamModel } from "@fungi.computer/mule/effect";
-import { observeProviderStatus } from "@fungi.computer/mule/effect";
+import { isRetryableProviderRejection, normalizeModel, observeProviderStatus, streamModel, } from "@fungi.computer/mule/effect";
 import { standaloneTenancy, } from "./tenancy.js";
 import { AcceptedSchema } from "@fungi.computer/shiitake/client";
 import { createShiitakeClient } from "@fungi.computer/shiitake/client";
@@ -7,6 +6,8 @@ import { AgentCreateRefused, } from "@fungi.computer/shiitake/agent-control";
 import { AgentDelegation, AgentDisclosureRefused, machineAgentCodecs, } from "@fungi.computer/shiitake/delegation";
 import { FungiMessageMetaSchema } from "@fungi.computer/agar/agents";
 import { agentMail } from "./agent-mail.js";
+import { createChannelConversations, } from "../channels/conversations.js";
+import { channelSessionDoor } from "./channel-session-door.js";
 import { createStandaloneMachineEnrollment, standaloneMachineAgentHome, standaloneMachineLinkAuthority, } from "./machine-link.js";
 import { createMachineLinkFences, MachineEnrollmentRefused, MachineLinkRefused, createMachineAgentClient, } from "../machine-link/index.js";
 import { memberInboxItemSchema } from "@fungi.computer/puffball/inbox";
@@ -51,10 +52,10 @@ function observedModels(model, defaults) {
         acquire: ({ signal }) => {
             const retryableMessages = new WeakSet();
             const safeFailures = new WeakMap();
-            const failure = (message, code) => {
+            const failure = (message, rejection) => {
                 // Pi can include raw response bodies in errorMessage. No provider
                 // prose enters a Session, retry journal, model context or diagnostics.
-                const safe = `Model request failed (${code}). Retry the request.`;
+                const safe = `Model request failed (${rejection?.code ?? "provider_rejected"}). Retry the request.`;
                 const terminal = {
                     role: "assistant",
                     content: [],
@@ -67,7 +68,7 @@ function observedModels(model, defaults) {
                     timestamp: message.timestamp,
                 };
                 safeFailures.set(terminal, safe);
-                if (code === "provider_unavailable")
+                if (isRetryableProviderRejection(rejection))
                     retryableMessages.add(terminal);
                 return terminal;
             };
@@ -90,7 +91,7 @@ function observedModels(model, defaults) {
                             });
                             for await (const event of response) {
                                 if (event.type === "error") {
-                                    const terminal = failure(event.error, observed.rejection()?.code ?? "provider_rejected");
+                                    const terminal = failure(event.error, observed.rejection(event.error));
                                     events.push({ ...event, error: terminal });
                                     events.end(terminal);
                                     return;
@@ -98,7 +99,7 @@ function observedModels(model, defaults) {
                                 if (event.type === "done" &&
                                     (event.message.stopReason === "error" ||
                                         event.message.stopReason === "aborted")) {
-                                    const terminal = failure(event.message, observed.rejection()?.code ?? "provider_rejected");
+                                    const terminal = failure(event.message, observed.rejection(event.message));
                                     events.push({ ...event, message: terminal });
                                     events.end(terminal);
                                     return;
@@ -107,7 +108,7 @@ function observedModels(model, defaults) {
                             }
                             const result = await response.result();
                             events.end(result.stopReason === "error" || result.stopReason === "aborted"
-                                ? failure(result, observed.rejection()?.code ?? "provider_rejected")
+                                ? failure(result, observed.rejection(result))
                                 : result);
                         }
                         catch {
@@ -134,7 +135,7 @@ function observedModels(model, defaults) {
                                 },
                                 stopReason: signal.aborted ? "aborted" : "error",
                                 timestamp: Date.now(),
-                            }, "provider_unavailable");
+                            }, { code: "provider_unavailable" });
                             events.push({
                                 type: "error",
                                 reason: signal.aborted ? "aborted" : "error",
@@ -228,6 +229,23 @@ const instructions = [
 ].join("\n");
 /** One agent: Shiitake's Cloudflare host over this Durable Object; its root supplies `hostFor`. */
 export class StandaloneAgentBase extends ShiitakeDO {
+    /**
+     * Compose Oyster's channel owner on this Agent's real store and Shiitake.
+     * A host must supply its own binding lookup after authenticating its edge;
+     * this does not install an inbound route or mint provider credentials.
+     */
+    channelConversations(binding) {
+        const owner = createChannelConversations({
+            sql: this.ctx.storage.sql,
+            transactionSync: (body) => this.ctx.storage.transactionSync(body),
+            binding,
+            door: channelSessionDoor(() => this.shiitake(), () => {
+                // Standalone Agents have no Hub Team grants to deliver.
+            }, () => owner),
+            now: () => Date.now(),
+        });
+        return owner;
+    }
     /** Each installed Release's verified catalog surface, built once per Release for this Agent's lifetime. */
     #appSurfaces;
     uiOwner;
@@ -479,10 +497,11 @@ export class StandaloneAgentBase extends ShiitakeDO {
                     throw new Error("Delegated reply identity is unavailable");
                 if (mail.reply.outcome === "undeliverable")
                     return undefined;
-                if (mail.from.sessionId === undefined)
-                    throw new Error("Delegated reply Session is unavailable");
+                if (mail.from.kind !== "agent")
+                    throw new Error("Delegated reply Agent identity is unavailable");
                 return (await this.machineClient()).settlement(mail.from.agentId, mail.from.sessionId, mail.reply.commandId, mail.to.agentId);
             },
+            onUndeliverable: (original) => this.delegation().localUndeliverable(original),
             wake: () => this.wakeRuntime(),
         }));
     }

package/dist/standalone/channel-session-door.d.ts

@@ -0,0 +1,4 @@
+import type { ShiitakeOwnerAgent } from "@fungi.computer/shiitake/cloudflare";
+import type { ChannelConversations, SessionDoor } from "../channels/conversations.js";
+/** Translate a standalone Agent's Shiitake owner into Oyster's channel Session port. */
+export declare function channelSessionDoor(open: () => Promise<ShiitakeOwnerAgent>, deliverGrants: (sessionId: string) => void, conversations: () => ChannelConversations): SessionDoor;

package/dist/standalone/channel-session-door.js

@@ -0,0 +1,72 @@
+import { authorMeta } from "@fungi.computer/agar/agents";
+import { ShiitakeError } from "@fungi.computer/shiitake";
+import { participantSnapshot, visitorPendingPrompt, visitorSnapshot, } from "@fungi.computer/shiitake/client";
+import { visitorStream } from "@fungi.computer/shiitake/server-visitor-stream";
+/** Translate a standalone Agent's Shiitake owner into Oyster's channel Session port. */
+export function channelSessionDoor(open, deliverGrants, conversations) {
+    const policy = () => conversations();
+    return {
+        createSession: async (requestId) => (await open()).createSession(requestId),
+        deliverGrants,
+        withdraw: async (sessionId, requestId) => (await open()).session(sessionId).withdraw(requestId),
+        latestPending: async (sessionId, visitor) => {
+            const prompt = await (await open())
+                .withMeta(authorMeta(visitor))
+                .session(sessionId)
+                .latestPending();
+            return prompt === null ? null : visitorPendingPrompt(prompt, visitor.id);
+        },
+        participantDocument: async (sessionId, visitorId, options) => {
+            const snapshot = await (await open()).session(sessionId).read(options);
+            return JSON.stringify(visitorSnapshot(participantSnapshot(snapshot, policy()), visitorId));
+        },
+        participantStream: async (sessionId, visitorId, options) => {
+            let watch;
+            try {
+                watch = await (await open()).session(sessionId).watch();
+            }
+            catch (cause) {
+                options.release();
+                throw cause;
+            }
+            return visitorStream({
+                ...options,
+                watch,
+                visitorId,
+                filter: (snapshot) => participantSnapshot(snapshot, policy()),
+                read: async () => (await open()).session(sessionId).read(),
+                onError: (event, cause) => {
+                    console.warn(event, cause);
+                },
+            });
+        },
+        prompt: async (sessionId, { requestId, text, meta }) => {
+            // The conversation row exists now, so its channel admission is known;
+            // deliver Agent tools before the first run can call one.
+            deliverGrants(sessionId);
+            const agent = await open();
+            return await agent.withMeta(meta).session(sessionId).command({
+                type: "prompt",
+                requestId,
+                text,
+                delivery: "followUp",
+            });
+        },
+        line: async (sessionId, input) => {
+            const agent = await open();
+            const meta = input.author === "operator" ? authorMeta(input.identity) : input.meta;
+            await agent.withMeta(meta).session(sessionId).command({
+                type: "operator",
+                requestId: input.requestId,
+                author: input.author,
+                text: input.text,
+            });
+        },
+        errorKind: (error, requestId) => error instanceof ShiitakeError &&
+            error.boundary === "contract" &&
+            error.cause === "closed" &&
+            error.requestId === requestId
+            ? "closed_request"
+            : null,
+    };
+}

package/dist/standalone/computer-fleet.js

@@ -1,8 +1,10 @@
 import { Hono } from "hono";
+import { endTime, startTime } from "hono/timing";
 import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
 import { computerCreateRequestSchema, computerPageSchema, } from "@fungi.computer/computer/fleet";
 import { oysterPrincipalIsOwner, } from "../host.js";
+import { computerTargetParam } from "../computer-target.js";
 /** Fleet controls never accept an actor from the request body. */
 const fleetComputerId = z.string().min(1).max(256);
 export const standaloneFleetRequestSchema = z.discriminatedUnion("operation", [
@@ -48,7 +50,7 @@ function fleetResponse(result) {
 export async function standaloneComputerSelection(registry, incoming) {
     if (incoming === undefined)
         return registry.selectedComputer();
-    const requested = new URL(incoming.request.url).searchParams.getAll("computerId");
+    const requested = new URL(incoming.request.url).searchParams.getAll(computerTargetParam);
     if (requested.length === 0)
         return registry.selectedComputer();
     const admission = await incoming.auth.authenticate(incoming.request);
@@ -91,16 +93,20 @@ export function standaloneComputerFleetRoutes(registryFor) {
         if (!oysterPrincipalIsOwner(principal))
             return context.json({ error: "Owner only" }, 403);
         const registry = registryFor();
+        startTime(context, "fleet");
         const admitted = await registry.computerFleet(principal.actor.memberId, {
             operation: "list",
             page: { limit: 1, offset: 0 },
         });
+        endTime(context, "fleet");
         if (admitted === null || "error" in admitted)
             return fleetResponse(admitted);
+        startTime(context, "registry");
         const [directory, computerId] = await Promise.all([
             registry.directory(),
             registry.selectedComputer(),
         ]);
+        endTime(context, "registry");
         return context.json({
             ...directory,
             computer: { computerId, name: computerId },

package/dist/standalone/machine-link.d.ts

@@ -268,6 +268,8 @@ export declare class MachineLinkDO extends DurableObject<StandaloneMachineLinkEn
     alarm(): Promise<void>;
     fetch(request: Request): Promise<Response>;
     deliver(id: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, envelope: PostEnvelope): Promise<PostDeliveryResult>;
+    deliverRelayDisposition(id: MachineLinkIdentity, relay: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<PostDeliveryResult>;
+    hasStagedDisposition(id: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<boolean>;
     operation(id: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, operation: MachineAgentOperation): Promise<import("effect/Schema").Json>;
     applyFence(fact: MachineLinkFenceFact): Promise<MachineLinkFenceResult>;
     preflightErasure(teamId: string, deviceId: string): Promise<void>;

package/dist/standalone/machine-link.js

@@ -1,4 +1,4 @@
-import { machineAgentReservations } from "@fungi.computer/shiitake/delegation";
+import { machineAgentCodecs, machineAgentReservations, } from "@fungi.computer/shiitake/delegation";
 import { createMachineEnrollment, MachineEnrollmentRefused, MachineLinkRefused, } from "../machine-link/index.js";
 import { keyAllowsMachineEnroll, } from "../keys.js";
 import { agentIds, createAgentDirectory, } from "@fungi.computer/shiitake/fleet";
@@ -8,6 +8,7 @@ import { bodyLimit } from "hono/body-limit";
 import { validator } from "hono/validator";
 import { machineEnrollmentSchema, machineLinkName, } from "../machine-link/index.js";
 import { createMachineLink } from "../machine-link/workers.js";
+import { deliverUndeliverableMail } from "../machine-link/delivery.js";
 import { defaultTenant, tenantScope } from "../tenant.js";
 import { presentedGitKey } from "../git-auth.js";
 import { standaloneTenancy } from "./tenancy.js";
@@ -49,6 +50,7 @@ export function standaloneMachineLinkAuthority(env) {
             return directory().machineDevice(id);
         },
         currentFence: async (id) => id.teamId !== teamId ? null : directory().machineFence(id),
+        agentHome: async (id, agentId) => id.teamId !== teamId ? null : directory().agentHome(agentId),
         directory: async (id) => {
             if (!(await authority.admitDevice(id)).live)
                 throw new MachineLinkRefused("actor_not_allowed");
@@ -69,6 +71,31 @@ export function standaloneMachineLinkAuthority(env) {
                 throw new MachineLinkRefused("actor_not_allowed");
             return env.MACHINE_LINK.getByName(machineLinkName(next)).deliver(next, caller, facts.targetAgentId, envelope);
         },
+        deliverUndeliverable: async (id, original, reply) => {
+            if ((await authority.currentFence(id)) === null)
+                return "refused";
+            const mail = original.event;
+            if (mail.from.kind !== "agent")
+                return "refused";
+            const home = await authority.agentHome(id, mail.from.agentId);
+            if (home === null)
+                throw new MachineLinkRefused("unavailable");
+            return await deliverUndeliverableMail({
+                identity: id,
+                original,
+                reply,
+                senderHome: home,
+                hosted: env.AGENTS,
+                accepted: machineAgentCodecs.accepted,
+                machine: async (deviceId, envelope) => {
+                    const destination = { teamId, deviceId };
+                    return await env.MACHINE_LINK.getByName(machineLinkName(destination)).deliverRelayDisposition(destination, id, original, envelope);
+                },
+            });
+        },
+        verifyRelayDisposition: async (relay, original, reply) => {
+            return await env.MACHINE_LINK.getByName(machineLinkName(relay)).hasStagedDisposition(relay, original, reply);
+        },
         canErase: async (id) => {
             if (id.teamId !== teamId)
                 return false;
@@ -185,6 +212,12 @@ export class MachineLinkDO extends DurableObject {
     deliver(id, caller, agentId, envelope) {
         return this.link.deliver(id, caller, agentId, envelope);
     }
+    deliverRelayDisposition(id, relay, original, reply) {
+        return this.link.deliverRelayDisposition(id, relay, original, reply);
+    }
+    hasStagedDisposition(id, original, reply) {
+        return this.link.hasStagedDisposition(id, original, reply);
+    }
     operation(id, caller, agentId, operation) {
         return this.link.operation(id, caller, agentId, operation);
     }

package/dist/standalone/tenancy.d.ts

@@ -1,5 +1,6 @@
 import { TenancyRegistryDO } from "../tenancy/cloudflare.js";
 import { type Identity, type Tenant, type ReadonlyTenancy } from "../tenancy/index.js";
+import { type OysterKeySessionResolver } from "../auth.js";
 import type { OysterGitWorkerEnv } from "../workers-git.js";
 import { type OysterTenancy, type TenantId } from "../tenant.js";
 /** Trusted standalone provisioning inputs; credentials never enter the seed. */
@@ -28,6 +29,8 @@ export declare class StandaloneTenants extends TenancyRegistryDO {
 /** The same trusted bindings are used by HTTP, MCP and cold root readers. */
 export type StandaloneTenancyEnv = Pick<OysterGitWorkerEnv, "OYSTER_ORIGIN" | "OYSTER_OWNER_NAME" | "OYSTER_OWNER_KEY" | "KEYS"> & Readonly<{
     TENANTS: DurableObjectNamespace<StandaloneTenants>;
+    /** Optional host-owned named-key browser sessions; Oyster mints none. */
+    OYSTER_KEY_SESSIONS?: OysterKeySessionResolver;
 }>;
 /** A live registry-owned owner; the configured label is never its member ID. */
 export type StandaloneOwner = Readonly<{

package/dist/standalone/tenancy.js

@@ -2,7 +2,7 @@ import { TenancyRegistryDO, admittedRegistry, durableObjectRegistry, } from "../
 import { createTenancy, } from "../tenancy/index.js";
 import { ownerKey } from "../tenancy/owner-key.js";
 import { hosts } from "../tenancy/resolve.js";
-import { ownerOrKeyAuth } from "../auth.js";
+import { keySessionAuth, ownerOrKeyAuth, } from "../auth.js";
 import { HTTPException } from "hono/http-exception";
 import { defaultTenant, tenantScope, } from "../tenant.js";
 import * as Schema from "effect/Schema";
@@ -173,7 +173,12 @@ async function composeTenancy(env) {
                     async authenticate(request) {
                         if (owner === null)
                             return { kind: "refused", status: 403 };
-                        const admission = await ownerOrKeyAuth(env.OYSTER_OWNER_KEY, owner.actor.memberId, () => env.KEYS.getByName(scope.durableName("keys"))).authenticate(request);
+                        const keys = () => env.KEYS.getByName(scope.durableName("keys"));
+                        const namedKeyAuth = ownerOrKeyAuth(env.OYSTER_OWNER_KEY, owner.actor.memberId, keys);
+                        const auth = env.OYSTER_KEY_SESSIONS === undefined
+                            ? namedKeyAuth
+                            : keySessionAuth(namedKeyAuth, owner.actor.memberId, keys, env.OYSTER_KEY_SESSIONS);
+                        const admission = await auth.authenticate(request);
                         // This entry admits only named keys; the owner key has its own entry.
                         return admission.kind === "admitted" &&
                             admission.principal.actor.kind === "team-key"

package/dist/testing/capabilities.d.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { type AppCapabilityId } from "@fungi.computer/puffball/app";
 import { type OysterAgents } from "../agents.js";
+import type { LiveOysterKey } from "../keys.js";
 import { type FileSource } from "../files.js";
 import { type OysterAuthResult, type OysterCapability } from "../host.js";
 /** How one capability fixture host admits its single installation. */
@@ -19,6 +20,7 @@ export type CapabilityFixtureOptions = Readonly<{
     visitor?: boolean;
     authenticate?: (request: Request) => Promise<OysterAuthResult>;
     agents?: OysterAgents;
+    liveKey?: (keyId: string) => Promise<LiveOysterKey | null>;
 }>;
 /** One Oyster host with a single installation whose capability grants the options shape. */
 export declare function capabilityFixture(options?: CapabilityFixtureOptions): Promise<{

package/dist/testing/capabilities.js

@@ -84,7 +84,7 @@ export async function capabilityFixture(options = {}) {
     if (options.visitor)
         installation = { ...installation, visibility: "public" };
     const readOnly = () => Promise.reject(new Error("Fixture installations are read-only"));
-    const base = {
+    let base = {
         bootUi: () => Promise.resolve({ kind: "passed" }),
         auth: {
             resolve: () => Promise.reject(new Error("Capability fixture resolves no actor")),
@@ -116,6 +116,8 @@ export async function capabilityFixture(options = {}) {
         },
         capabilities,
     };
+    if (options.liveKey !== undefined)
+        base = { ...base, keys: { live: options.liveKey } };
     const host = options.agents === undefined
         ? base
         : { ...base, ownerRoutes: agentApprovalRoutes(options.agents) };

package/dist/turnstile.d.ts

@@ -0,0 +1,27 @@
+/** Host-owned configuration inputs, decoded before any challenge is opened. */
+export type TurnstileEnvironment = Readonly<{
+    TURNSTILE?: string;
+    TURNSTILE_SITE_KEY?: string;
+    TURNSTILE_SECRET_KEY?: string;
+}>;
+/** Explicit opt-out, complete verification credentials, or a closed door. */
+export type TurnstileConfiguration = Readonly<{
+    kind: "disabled";
+}> | Readonly<{
+    kind: "enabled";
+    siteKey: string;
+    secretKey: string;
+}> | Readonly<{
+    kind: "misconfigured";
+}>;
+/** Retain the development default; HTTPS hosts without keys fail closed. */
+export declare function readTurnstileConfiguration(environment: TurnstileEnvironment, origin: string | undefined): TurnstileConfiguration;
+/** Verify with Cloudflare; timeout policy and safe failure reporting belong to the host. */
+export declare function verifyTurnstileToken(input: {
+    secretKey: string;
+    token: string;
+    remoteIp?: string;
+}, options: {
+    timeoutMs: number;
+    onError(cause: unknown): void;
+}): Promise<"passed" | "failed" | "unavailable">;

package/dist/turnstile.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+const siteverifyUrl = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+const environmentSchema = z.object({
+    TURNSTILE: z.literal("off").optional(),
+    TURNSTILE_SITE_KEY: z.string().trim().min(1).optional(),
+    TURNSTILE_SECRET_KEY: z.string().trim().min(1).optional(),
+});
+const responseSchema = z.object({ success: z.boolean() });
+/** Retain the development default; HTTPS hosts without keys fail closed. */
+export function readTurnstileConfiguration(environment, origin) {
+    const parsed = environmentSchema.safeParse(environment);
+    if (!parsed.success)
+        return { kind: "misconfigured" };
+    if (parsed.data.TURNSTILE === "off")
+        return { kind: "disabled" };
+    const { TURNSTILE_SITE_KEY: siteKey, TURNSTILE_SECRET_KEY: secretKey } = parsed.data;
+    if (siteKey === undefined && secretKey === undefined)
+        return URL.parse(origin ?? "")?.protocol === "https:"
+            ? { kind: "misconfigured" }
+            : { kind: "disabled" };
+    if (siteKey === undefined || secretKey === undefined)
+        return { kind: "misconfigured" };
+    return { kind: "enabled", siteKey, secretKey };
+}
+/** Verify with Cloudflare; timeout policy and safe failure reporting belong to the host. */
+export async function verifyTurnstileToken(input, options) {
+    try {
+        const body = {
+            secret: input.secretKey,
+            response: input.token,
+        };
+        if (input.remoteIp !== undefined)
+            body.remoteip = input.remoteIp;
+        const response = await fetch(siteverifyUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(options.timeoutMs),
+        });
+        if (!response.ok)
+            return "unavailable";
+        const verdict = responseSchema.safeParse(await response.json());
+        if (!verdict.success)
+            return "unavailable";
+        return verdict.data.success ? "passed" : "failed";
+    }
+    catch (cause) {
+        options.onError(cause);
+        return "unavailable";
+    }
+}

package/dist/workers-git.js

@@ -889,6 +889,7 @@ export function createOysterGitWorker(root) {
                 hosts = new Map();
                 environments.set(env, hosts);
             }
+            const started = Date.now();
             let resolved;
             try {
                 resolved = await root.admit(env, request);
@@ -907,6 +908,7 @@ export function createOysterGitWorker(root) {
             const boot = await serveOysterBootCapability(request, env, scope);
             if (boot !== null)
                 return boot;
+            const admitted = Date.now();
             let host;
             try {
                 host = await root.hostFor(env, scope, request);
@@ -916,6 +918,7 @@ export function createOysterGitWorker(root) {
                     return error.getResponse();
                 throw error;
             }
+            const hosted = Date.now();
             const key = `${scope.tenantId}:${scope.origin}:${host.computerId ?? ""}`;
             let entry = hosts.get(key);
             let cache = true;
@@ -938,7 +941,10 @@ export function createOysterGitWorker(root) {
             }
             entry.active += 1;
             try {
-                return await entry.app.fetch(request, env, ctx);
+                return withStageTimings(await entry.app.fetch(request, env, ctx), {
+                    admit: admitted - started,
+                    host: hosted - admitted,
+                });
             }
             finally {
                 entry.active -= 1;
@@ -946,6 +952,19 @@ export function createOysterGitWorker(root) {
         },
     };
 }
+/**
+ * Add the root's own stages (tenant admission, host selection) to the App
+ * server's Server-Timing, so a slow request names the hop it waited on. An
+ * upgraded socket keeps its response untouched.
+ */
+function withStageTimings(response, stages) {
+    if (response.status === 101)
+        return response;
+    const timed = new Response(response.body, response);
+    for (const [name, duration] of Object.entries(stages))
+        timed.headers.append("Server-Timing", `${name};dur=${String(duration)}`);
+    return timed;
+}
 /**
  * `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
@@ -1117,7 +1136,7 @@ export async function oysterGitWorkerHost(env, options, selected, request) {
     const base = oysterWorkerHost(env, auth, policyOptions);
     const capabilities = [
         ...(base.capabilities ?? []),
-        ...(agents === undefined ? [] : agentCapabilities(agents)),
+        ...(agents === undefined ? [] : agentCapabilities(agents, keysLive)),
         ...(options.capabilities?.(env, workspace, keysLive) ?? []),
     ];
     let gitOptions = { scope };

package/dist/workers.d.ts

@@ -138,6 +138,7 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
             };
             readonly reversibility: "reversible" | "irreversible-external";
             readonly requestedAt: number;
+            readonly denialNote?: string | undefined;
             readonly evidence?: readonly {
                 readonly kind: "artifact";
                 readonly ref: string;
@@ -155,6 +156,7 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
     }>, actor: HostActor, input: ApprovalAnswerInput): Promise<Readonly<{
         kind: "refused";
         reason: "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict";
+        denialNote?: string;
     }> | Readonly<{
         kind: "answered";
         view: import("@fungi.computer/approvals").ApprovalView;
@@ -166,6 +168,7 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
     }>, actor: HostActor, input: AutoApproveInput): Promise<Readonly<{
         kind: "refused";
         reason: "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict";
+        denialNote?: string;
     }> | Readonly<{
         kind: "updated";
         rule: AutoApproveInput;