@fungi.computer/oyster 0.5.0 → 0.7.0

package/dist/workers-git.js

@@ -13,7 +13,6 @@ import { APP_INVOCATION_CEILING_MS, invocationFacts, invocationCallerContext, }
 import { AppInstanceError, selectionOf } from "./index.js";
 import { ownerOrKeyAuth } from "./auth.js";
 import { causeClass } from "./cause-class.js";
-import { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import * as Schema from "effect/Schema";
 import { defineIdFamily } from "@fungi.computer/cairn";
@@ -26,7 +25,8 @@ import { agentCapabilities, agentApprovalRoutes, agentMcpServerRoutes, } from ".
 import { createArtifactsRestNamespace, } from "@fungi.computer/burrow";
 import { attemptWebhook } from "./webhook-delivery.js";
 import { createRecipientDeliveries, } from "./event-recipients.js";
-import { createOyster, oysterPrincipalIsOwner, } from "./host.js";
+import { createOyster, } from "./host.js";
+import { oysterPrincipalIsOwner, owner as ownerRoute, routes as routeTable, } from "./authorization.js";
 import { OysterInstance, oysterBindingEntrypoint, oysterBindings, oysterWorkerHost, r2FileSource, r2ArtifactStore, serveOysterBootCapability, } from "./workers.js";
 import { registryInstallations } from "./internal/registry-installations.js";
 import { refuseOlderOysterStore } from "./older-oyster-store-refusal.js";
@@ -763,36 +763,29 @@ const subscribeSchema = Schema.Struct({
     secret: Schema.optional(Schema.String.check(Schema.isMinLength(16))),
 });
 const keyNamePattern = /^[a-z0-9][a-z0-9-]{0,39}$/u;
-/** `invocation.ts:486` uses `team-key:visitor` for anonymous readers; a key can never claim that name. */
-const reservedKeyName = "visitor";
 const keysWire = keyWire(oysterKeyVocabulary);
 /** Owner routes for keys and webhooks; `createOyster` mounts them owner-only. */
 export function gitAdminRoutes(env, scope) {
-    const routes = new Hono();
+    const routes = routeTable();
     const keys = () => env.KEYS.getByName(scope.durableName("keys"));
-    routes.get("/api/keys", async (context) => {
-        const owner = context.get("principal");
-        if (!oysterPrincipalIsOwner(owner))
-            return Response.json({ error: "Owner only" }, { status: 403 });
-        const listed = await keys().list(owner.actor.memberId);
+    // Key and webhook custody is the owner's own, never through an App.
+    const owner = ownerRoute("direct");
+    routes.get("/api/keys", owner, async (_context, { principal }) => {
+        const listed = await keys().list(principal.actor.memberId);
         if (listed.kind === "error")
             return Response.json({ error: listed.error.code }, { status: 500 });
         return Response.json({ keys: listed.value.map(keysWire.toSummary) });
     });
-    routes.post("/api/keys", async (context) => {
+    routes.post("/api/keys", owner, async (context, { principal }) => {
         const body = keysWire.issue.safeParse(await context.req.json());
         if (!body.success)
             return Response.json({ error: "Invalid key" }, { status: 400 });
         // Named identities and rate policy belong to this host, not the wire grammar.
         if (!keyNamePattern.test(body.data.name) ||
-            body.data.name === reservedKeyName ||
             body.data.keyId !== undefined ||
             body.data.rateLimit !== undefined)
             return Response.json({ error: "Invalid key name" }, { status: 400 });
-        const owner = context.get("principal");
-        if (!oysterPrincipalIsOwner(owner))
-            return Response.json({ error: "Owner only" }, { status: 403 });
-        const issued = await keys().issue(owner.actor.memberId, {
+        const issued = await keys().issue(principal.actor.memberId, {
             name: body.data.name,
             grants: body.data.grants,
             expiresAt: body.data.expiresAt,
@@ -804,19 +797,16 @@ export function gitAdminRoutes(env, scope) {
             key: keysWire.toSummary(issued.value.record),
         }, { status: 201 });
     });
-    routes.post("/api/keys/revoke", async (context) => {
+    routes.post("/api/keys/revoke", owner, async (context, { principal }) => {
         const body = keysWire.revoke.safeParse(await context.req.json());
         if (!body.success)
             return Response.json({ error: "Invalid request" }, { status: 400 });
-        const owner = context.get("principal");
-        if (!oysterPrincipalIsOwner(owner))
-            return Response.json({ error: "Owner only" }, { status: 403 });
-        const revoked = await keys().revoke(owner.actor.memberId, body.data.requestId, body.data.keyId);
+        const revoked = await keys().revoke(principal.actor.memberId, body.data.requestId, body.data.keyId);
         if (revoked.kind === "error")
             return Response.json({ error: revoked.error.code }, { status: revoked.error.code === "denied" ? 404 : 400 });
         return Response.json({ key: keysWire.toSummary(revoked.value) });
     });
-    routes.post("/api/webhooks", async (context) => {
+    routes.post("/api/webhooks", owner, async (context) => {
         const body = Schema.decodeUnknownOption(subscribeSchema)(await context.req.json());
         if (body._tag === "None")
             return Response.json({ error: "Invalid subscription" }, { status: 400 });
@@ -825,9 +815,9 @@ export function gitAdminRoutes(env, scope) {
             types: body.value.types ?? [],
         }), { status: 201 });
     });
-    routes.get("/api/webhooks", async () => Response.json(await env.WEBHOOKS.getByName(scope.durableName("webhooks")).subscriptions()));
-    routes.get("/api/webhooks/:id/deliveries", async (context) => Response.json(await env.WEBHOOKS.getByName(scope.durableName("webhooks")).deliveries(context.req.param("id"))));
-    routes.delete("/api/webhooks/:id", async (context) => (await env.WEBHOOKS.getByName(scope.durableName("webhooks")).unsubscribe(context.req.param("id")))
+    routes.get("/api/webhooks", owner, async () => Response.json(await env.WEBHOOKS.getByName(scope.durableName("webhooks")).subscriptions()));
+    routes.get("/api/webhooks/:id/deliveries", owner, async (context) => Response.json(await env.WEBHOOKS.getByName(scope.durableName("webhooks")).deliveries(context.req.param("id"))));
+    routes.delete("/api/webhooks/:id", owner, async (context) => (await env.WEBHOOKS.getByName(scope.durableName("webhooks")).unsubscribe(context.req.param("id")))
         ? new Response(null, { status: 204 })
         : Response.json({ error: "Not found" }, { status: 404 }));
     return routes;
@@ -889,6 +879,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 +898,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 +908,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 +931,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 +942,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,8 +1126,8 @@ export async function oysterGitWorkerHost(env, options, selected, request) {
     const base = oysterWorkerHost(env, auth, policyOptions);
     const capabilities = [
         ...(base.capabilities ?? []),
-        ...(agents === undefined ? [] : agentCapabilities(agents, keysLive)),
-        ...(options.capabilities?.(env, workspace, keysLive) ?? []),
+        ...(agents === undefined ? [] : agentCapabilities(agents)),
+        ...(options.capabilities?.(env, workspace) ?? []),
     ];
     let gitOptions = { scope };
     if (options.workflowGitPass !== undefined)
@@ -1126,14 +1135,7 @@ export async function oysterGitWorkerHost(env, options, selected, request) {
     if (options.buildGitPass !== undefined)
         gitOptions = { ...gitOptions, buildGitPass: options.buildGitPass };
     const git = oysterWorkerGit(env, gitOptions);
-    const ownerRoutes = gitAdminRoutes(env, scope);
-    const hostOwnerRoutes = options.ownerRoutes?.(env, scope);
-    if (hostOwnerRoutes !== undefined)
-        ownerRoutes.route("/", hostOwnerRoutes);
-    if (agents !== undefined) {
-        ownerRoutes.route("/", agentApprovalRoutes(agents));
-        ownerRoutes.route("/", agentMcpServerRoutes(agents));
-    }
+    const ownerRoutes = oysterGitOwnerRoutes(env, scope, options.ownerRoutes?.(env, scope), agents);
     let host = {
         ...base,
         capabilities,
@@ -1149,8 +1151,28 @@ export async function oysterGitWorkerHost(env, options, selected, request) {
         host = { ...host, computerControl: options.computerControl(env, scope) };
     if (options.homeInstallationId !== undefined)
         host = { ...host, homeInstallationId: options.homeInstallationId(env) };
+    if (options.permissionResources !== undefined)
+        host = {
+            ...host,
+            permissionResources: options.permissionResources(env, scope),
+        };
     return host;
 }
+/**
+ * A Git host's whole owner table: keys and webhooks, the root's own owner
+ * routes, and Agent approval and MCP server custody. The host and the
+ * authorization law both compose it here.
+ */
+export function oysterGitOwnerRoutes(env, scope, hostOwnerRoutes, agents) {
+    const ownerRoutes = gitAdminRoutes(env, scope);
+    if (hostOwnerRoutes !== undefined)
+        ownerRoutes.include(hostOwnerRoutes);
+    if (agents !== undefined) {
+        ownerRoutes.include(agentApprovalRoutes(agents));
+        ownerRoutes.include(agentMcpServerRoutes(agents));
+    }
+    return ownerRoutes;
+}
 /**
  * Authenticate against the pinned tenant. A request admitted at the Worker's
  * top reuses that one admission; any other entry resolves its own.

package/dist/workers.d.ts

@@ -34,6 +34,11 @@ export { r2ArtifactStore, r2FileSource, ownerKeyAuth };
 export type OysterBindingResult = Awaited<ReturnType<GitBinding[keyof GitBinding]>> | Schema.Json | undefined;
 /** Verified backend custody is captured in the frame, never in a current-context field. */
 export type OysterInvocationHost = BackgroundFrameState & Readonly<{
+    /** This frame's guest binding packets and the wall time they waited. */
+    bindingWaits: {
+        count: number;
+        ms: number;
+    };
     artifact: Backend;
     declaration: AppDeclaration | null;
     /** The verified declared method; opaque backend and lifecycle frames have none. */
@@ -124,10 +129,10 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
                 readonly kind: "policy";
             } | null;
             readonly access: "write" | "external";
+            readonly state: "pending" | "expired" | "denied" | "applied" | "requested" | "approved" | "claimed" | "outcome_unknown";
             readonly reason: "pending" | "expired" | "not-found" | "not-eligible" | "already-answered" | "stale-revision" | "declined" | "fenced" | "not-granted" | "read-only" | "in-flight" | "outcome-unknown" | "identity-conflict" | null;
             readonly updatedAt: number;
             readonly module: string;
-            readonly state: "pending" | "expired" | "denied" | "applied" | "requested" | "approved" | "claimed" | "outcome_unknown";
             readonly recordId: string;
             readonly authorityFence: string;
             readonly requester: {
@@ -222,6 +227,8 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
     get(installationId: string): Installation | null;
     /** Durable store identity, regenerated only when the store itself is replaced. */
     generation(): string;
+    /** Permanent audit fact for the owner Home's empty installation notice. */
+    installationResetAt(): number | null;
     /** Native RPC returns a closed result; callers never classify a transported Error. */
     compareAndPut(installation: Installation, expectedAuthorityVersion: number, expectedGeneration: string, tenantId?: TenantId): Promise<InstallationCommit>;
     private writeInstallation;
@@ -387,6 +394,7 @@ export declare class OysterInstance<Env extends OysterWorkerEnv = OysterWorkerEn
     /** Resolve each guest packet against its immutable frame before any host effect. */
     bindingCall(raw: FrameBindingProps, method: string, input: readonly unknown[]): Promise<FrameBindingReply<OysterBindingResult>>;
     private executeBindingCall;
+    private dispatchBindingCall;
     /** Last provider-accepted ref recorded by this installation's journal. */
     gitTip(installationId: string, repository: string, ref: string, tenantId?: TenantId): Promise<string | null>;
     /** Join accepted fact identity and Carrier delivery in one local transaction. */

package/dist/workers.js

@@ -35,10 +35,12 @@ import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { releaseSchema } from "@fungi.computer/puffball/effect";
 import { AppInstanceError, } from "./index.js";
-import { createCloudflareAppInstance, r2ArtifactStore, createCloudflareInvocationGate, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
+import { createCloudflareAppInstance, r2ArtifactStore, createCloudflareInvocationGate, edgeVerifiedObjectCache, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
 import { invocationFactsSchema, assertBackgroundBinding, admitBackgroundFrame, } from "./invocation.js";
 import { deliverBackground, deliverGitPush } from "./internal/delivery.js";
-import { createOyster, verifyRelease, defaultAssetPolicy, } from "./host.js";
+import { reportSlowInvocation } from "./internal/invocation-timing.js";
+import { releaseCache } from "./internal/host-gate.js";
+import { createOyster, } from "./host.js";
 import { createGitPushJournal } from "./git-journal.js";
 import { AppStorageError, } from "@fungi.computer/agar/storage";
 import { storageFrameMethods } from "./storage-frame.js";
@@ -65,7 +67,7 @@ const approvalHomePinRow = Schema.Struct({
 });
 /** The installation registry: one SQLite-backed Durable Object per Oyster. */
 export class OysterRegistry extends DurableObject {
-    #generation;
+    #installationStore;
     /** Decided once, before this version writes anything, and never revised. */
     #installationsFromOlderOyster;
     #approval;
@@ -148,6 +150,7 @@ export class OysterRegistry extends DurableObject {
         return this.approvalHome(pin).capability(actor).setAutoApprove(input);
     }
     #rootData;
+    #releases = releaseCache(r2ArtifactStore(this.env.RELEASES));
     /** Append-only App source seed receipts; a Git-capable subclass forks over these. */
     appSourceReceipts;
     /** Team-owned fork registrations, one App publisher record per App. */
@@ -159,7 +162,7 @@ export class OysterRegistry extends DurableObject {
         this.#installationsFromOlderOyster = installationsFromOlderOyster(ctx.storage.sql);
         ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS oyster_approval_home (id INTEGER PRIMARY KEY CHECK (id = 1), tenant_id TEXT NOT NULL, origin TEXT NOT NULL) STRICT");
         ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS installations (installation_id TEXT PRIMARY KEY, record TEXT NOT NULL) STRICT");
-        this.#generation = createInstallationStoreGeneration(ctx.storage.sql);
+        this.#installationStore = createInstallationStoreGeneration(ctx.storage);
         ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS boot_capabilities (id TEXT PRIMARY KEY, token_digest TEXT NOT NULL, expires_at INTEGER NOT NULL, record TEXT NOT NULL) STRICT");
         ensureAppSourceTables(ctx.storage.sql);
         this.#installationOperations = createInstallationOperations({
@@ -196,7 +199,7 @@ export class OysterRegistry extends DurableObject {
             installations: {
                 list: () => Promise.resolve(this.list()),
             },
-            resolveRelease: (release) => verifyRelease(r2ArtifactStore(env.RELEASES), release, defaultAssetPolicy, false),
+            resolveRelease: this.#releases,
         });
     }
     /** The installation owner's RPC: admit, read, load, plan or commit one
@@ -319,7 +322,7 @@ export class OysterRegistry extends DurableObject {
                                 expected.selection.releaseId ||
                             installation.release.appId !== expected.selection.appId)))
                     throw new AppStorageError("unavailable");
-                const resolved = await verifyRelease(r2ArtifactStore(this.env.RELEASES), installation.release, defaultAssetPolicy, false);
+                const resolved = await this.#releases(installation.release);
                 if (expected !== undefined &&
                     resolved.backend?.digest !== expected.artifactDigest)
                     throw new AppStorageError("unavailable");
@@ -374,7 +377,11 @@ export class OysterRegistry extends DurableObject {
     }
     /** Durable store identity, regenerated only when the store itself is replaced. */
     generation() {
-        return this.#generation();
+        return this.#installationStore.generation();
+    }
+    /** Permanent audit fact for the owner Home's empty installation notice. */
+    installationResetAt() {
+        return this.#installationStore.resetAt();
     }
     /** Native RPC returns a closed result; callers never classify a transported Error. */
     async compareAndPut(installation, expectedAuthorityVersion, expectedGeneration, tenantId = defaultTenant) {
@@ -756,13 +763,23 @@ export class OysterInstance extends DurableObject {
     }
     async executeBindingCall(raw, method, input) {
         const props = decodeFrameBindingProps(raw);
-        const frame = this.frames.active();
-        if (props.instanceId !== frame.facts.instanceId ||
-            props.frameId !== frame.frameId)
+        // The packet's own frame: a closed or foreign frame id refuses.
+        const frame = this.frames.active(props.frameId);
+        if (props.instanceId !== frame.facts.instanceId)
             throw new AppInstanceError("revoked");
+        const started = Date.now();
+        try {
+            return await this.dispatchBindingCall(frame, props, method, input);
+        }
+        finally {
+            frame.host.bindingWaits.count += 1;
+            frame.host.bindingWaits.ms += Date.now() - started;
+        }
+    }
+    async dispatchBindingCall(frame, props, method, input) {
         assertBackgroundBinding(frame, props.binding);
         // A guest packet is its own entry: exactly one registry read re-admits it.
-        await this.assertCurrent(frame);
+        const current = await this.assertCurrent(frame);
         const row = this.bindings[props.binding];
         const descriptor = row?.methods[method];
         // Operations declared by the verified Release; absent bindings grant nothing.
@@ -782,12 +799,16 @@ export class OysterInstance extends DurableObject {
             throw new AppInstanceError("binding_unavailable");
         }
         const args = descriptor.decodeArgs(input);
-        if (!descriptor
-            .requiredOperations(args)
-            .every((operation) => granted.includes(operation)))
+        const required = descriptor.requiredOperations(args);
+        if (!required.every((operation) => granted.includes(operation)))
             throw new AppInstanceError("binding_not_granted");
+        if (descriptor.requestedResource !== undefined) {
+            const selected = approvedBindingGrants(current, frame.host.declaration ?? emptyAppDeclaration, descriptor.requestedResource(args)).find((grant) => grant.binding === props.binding)?.operations ?? [];
+            if (!required.every((operation) => selected.includes(operation)))
+                throw new AppInstanceError("binding_not_granted");
+        }
         const result = await row.dispatch(this.#bindingContext, frame, props, method, args);
-        if (this.frames.active() !== frame)
+        if (this.frames.active(props.frameId) !== frame)
             throw new AppInstanceError("revoked");
         assertBackgroundBinding(frame, props.binding);
         return descriptor.decodeResult(result);
@@ -846,8 +867,10 @@ export class OysterInstance extends DurableObject {
                 .find((currentGrant) => currentGrant.binding === grant.binding)
                 ?.operations.includes(operation) !== true)))
             throw new AppInstanceError("revoked");
+        return current;
     }
     async withFrame(raw, limits, work, tenantId = defaultTenant, methodName) {
+        const entered = Date.now();
         this.requireTenant(tenantId);
         const facts = Schema.decodeUnknownSync(invocationFactsSchema, {
             onExcessProperty: "error",
@@ -858,6 +881,7 @@ export class OysterInstance extends DurableObject {
             throw new AppInstanceError("instance_identity_mismatch");
         const release = this.release(facts.selection.releaseId);
         const resolved = await this.backends(release);
+        const verified = Date.now();
         if (resolved?.digest !== facts.artifactDigest)
             throw new AppInstanceError("invalid_invocation_facts");
         if (facts.subject.kind === "call" &&
@@ -893,6 +917,7 @@ export class OysterInstance extends DurableObject {
             };
         }
         let host = {
+            bindingWaits: { count: 0, ms: 0 },
             artifact: { release, ...resolved },
             declaration: resolved.declaration,
             origin: "unchecked",
@@ -902,7 +927,20 @@ export class OysterInstance extends DurableObject {
         // Facts carry the authority admitted at the request's top. The Instance
         // checks them against the owner state the host applied to it, never by
         // calling back up to the registry.
-        return this.frames.run(scoped, host, (frame) => work(this.runtimeFor(limits), frame));
+        let admitted = verified;
+        try {
+            return await this.frames.run(scoped, host, (frame) => {
+                admitted = Date.now();
+                return work(this.runtimeFor(limits), frame);
+            });
+        }
+        finally {
+            reportSlowInvocation(methodName ?? facts.subject.kind, host, {
+                entered,
+                verified,
+                admitted,
+            });
+        }
     }
     release(releaseId) {
         const row = this.ctx.storage.sql
@@ -1102,10 +1140,7 @@ export function oysterWorkerHost(env, auth, options = {}) {
         },
         auth,
         workbench: {
-            directory: async () => {
-                await installations.list();
-                return registry().directory();
-            },
+            directory: () => registry().directory(),
             storage: (installationId, ownerId) => ({
                 read: (key) => registry().storageRead(installationId, ownerId, key),
                 write: (input) => registry().storageWrite(installationId, ownerId, input),
@@ -1115,6 +1150,10 @@ export function oysterWorkerHost(env, auth, options = {}) {
         },
         guestLimits: guestLimits(options.guestLimits),
         artifacts,
+        // Workers and workerd keep a zone cache; a runtime without one reads R2.
+        ...("caches" in globalThis && {
+            uiCache: edgeVerifiedObjectCache(caches.default, scope.origin),
+        }),
         bootUi: oysterBootUi(env, scope),
         // File-only hosts may keep workspace files beside their Release artifacts.
         capabilities: [

package/dist/workflows.d.ts

@@ -10,6 +10,7 @@ export declare const agentWorkflowOperationSchema: z.ZodEnum<{
     catalog: "catalog";
     armSchedule: "armSchedule";
     disarmSchedule: "disarmSchedule";
+    pauseSchedule: "pauseSchedule";
     schedules: "schedules";
     armEventTrigger: "armEventTrigger";
     disarmEventTrigger: "disarmEventTrigger";
@@ -26,6 +27,7 @@ export declare const agentAppWorkflowRequestSchema: z.ZodObject<{
         catalog: "catalog";
         armSchedule: "armSchedule";
         disarmSchedule: "disarmSchedule";
+        pauseSchedule: "pauseSchedule";
         schedules: "schedules";
         armEventTrigger: "armEventTrigger";
         disarmEventTrigger: "disarmEventTrigger";

package/dist/workflows.js

@@ -11,6 +11,7 @@ export const agentWorkflowOperationSchema = z.enum([
     "catalog",
     "schedules",
     "armSchedule",
+    "pauseSchedule",
     "disarmSchedule",
     "eventTriggers",
     "armEventTrigger",

package/docs/api/README.md

@@ -36,6 +36,13 @@
 | `@fungi.computer/oyster/git`            | `EventSink`, `createGitDoor`, `signStandardWebhook`                                                | The EVENTS binding contract, the git smart-HTTP door and Standard Webhooks signing. `GitBinding` comes from `@fungi.computer/agar/git`. |
 | `@fungi.computer/oyster/workers-git`    | `oysterGitRoot`, `createOysterGitWorker`, `ownerOrKeyTenancy`, `oysterWorkerGit`, `gitAdminRoutes` | One Git root whose `hostFor` serves HTTP, MCP and Instances, or `host.git` and key/webhook routes for your own host.                    |
 
+Standalone Oyster owners can `POST /agents/:agentId/archive` and
+`POST /agents/:agentId/unarchive`. `GET /agents` lists active Agents;
+`GET /agents?archived=true` lists only archived Agents. Archive preserves
+existing Sessions and reads but refuses new Shiitake work with
+`contract/archived`. It pauses Almanac and Loop schedules; restore resumes only
+schedules paused by archive. The generated Agent API is in `docs/api/agents.md`.
+
 The host owns admission: it decides who may apply owner state and which
 selection a request carries. Oyster owns what happens to one Instance once the
 host has that authority: owner-state replay and conflict rules, Release

package/docs/api/agent-schedules.md

@@ -0,0 +1,175 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / agent-schedules
+
+# agent-schedules
+
+## Type Aliases
+
+### AppAgentScheduleListInput
+
+```ts
+type AppAgentScheduleListInput = z.input<
+  typeof appAgentScheduleListInputSchema
+>;
+```
+
+A single bounded native read, not an all-Agent inventory grant.
+
+---
+
+### AgentScheduleTarget
+
+```ts
+type AgentScheduleTarget = z.output<typeof agentScheduleTargetSchema>;
+```
+
+Identity to admit before acquiring the corresponding Agent owner.
+
+---
+
+### AgentSchedulePage
+
+```ts
+type AgentSchedulePage = typeof agentSchedulePageSchema.Type;
+```
+
+One Agent's page, with no directory fan-out or availability policy.
+
+---
+
+### AgentScheduleControlReceipt
+
+```ts
+type AgentScheduleControlReceipt =
+  typeof agentScheduleControlReceiptSchema.Type;
+```
+
+Content-free acknowledgement of the native owner's completed transition.
+
+## Variables
+
+### appAgentScheduleListInputSchema
+
+```ts
+const appAgentScheduleListInputSchema: ZodObject<
+  {
+    agentId: ZodString;
+    after: ZodOptional<
+      ZodObject<
+        {
+          agentId: ZodString;
+          kind: ZodUnion<readonly [ZodLiteral<"almanac">, ZodLiteral<"loop">]>;
+          after: ZodOptional<ZodString>;
+        },
+        $strict
+      >
+    >;
+    limit: ZodDefault<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+The App selects one Agent; its host must admit that target before opening it.
+
+---
+
+### agentScheduleBindingArgs
+
+```ts
+const agentScheduleBindingArgs: object;
+```
+
+Both hosts decode the ordinary AGENTS packet with the native owner's grammar.
+
+#### Type Declaration
+
+| Name                                                  | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Description                                                                 |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| <a id="property-schedules"></a> `schedules`           | `ZodTuple`\<\[`ZodObject`\<\{ `agentId`: `ZodString`; `after`: `ZodOptional`\<`ZodObject`\<\{ `agentId`: `ZodString`; `kind`: `ZodUnion`\<readonly \[`ZodLiteral`\<...\>, `ZodLiteral`\<...\>\]\>; `after`: `ZodOptional`\<`ZodString`\>; \}, `$strict`\>\>; `limit`: `ZodDefault`\<`ZodNumber`\>; \}, `$strict`\>\], `null`\>                                                                                                                                                                                                                                                | One bounded content-bearing read, admitted independently of manage.         |
+| <a id="property-pauseschedule"></a> `pauseSchedule`   | `ZodTuple`\<\[`ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `kind`: `ZodLiteral`\<`"almanac"`\>; `agentId`: `ZodString`; `scheduleId`: `ZodString` & `ZodType`\<`string`, `string`, `$ZodTypeInternals`\<`string`, `string`\>\>; \}, `$strict`\>, `ZodObject`\<\{ `kind`: `ZodLiteral`\<`"loop"`\>; `agentId`: `ZodString`; `sessionId`: `ZodString` & `ZodType`\<`string`, `string`, `$ZodTypeInternals`\<`string`, `string`\>\>; `loopId`: `ZodString` & `ZodType`\<`string`, `string`, `$ZodTypeInternals`\<`string`, `string`\>\>; \}, `$strict`\>\], `"kind"`\>\], `null`\> | Pause the exact listed schedule, retaining future resume and accepted work. |
+| <a id="property-deleteschedule"></a> `deleteSchedule` | `ZodTuple`\<\[`ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `kind`: `ZodLiteral`\<`"almanac"`\>; `agentId`: `ZodString`; `scheduleId`: `ZodString` & `ZodType`\<`string`, `string`, `$ZodTypeInternals`\<`string`, `string`\>\>; \}, `$strict`\>, `ZodObject`\<\{ `kind`: `ZodLiteral`\<`"loop"`\>; `agentId`: `ZodString`; `sessionId`: `ZodString` & `ZodType`\<`string`, `string`, `$ZodTypeInternals`\<`string`, `string`\>\>; `loopId`: `ZodString` & `ZodType`\<`string`, `string`, `$ZodTypeInternals`\<`string`, `string`\>\>; \}, `$strict`\>\], `"kind"`\>\], `null`\> | Cancel future occurrences of the exact identity without erasing history.    |
+
+---
+
+### agentSchedulePageSchema
+
+```ts
+const agentSchedulePageSchema: Schema.Struct<{
+  items: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+     agentId: Schema.String;
+     kind: Schema.Literal<"almanac">;
+     schedule: Schema.Struct<{
+        id: Schema.String;
+        sessionId: Schema.String;
+        prompt: Schema.String;
+        cron: Schema.NullOr<...>;
+        nextDueAt: Schema.Int;
+        state: Schema.Literals<...>;
+        lastCommandId: Schema.NullOr<...>;
+        lastError: Schema.NullOr<...>;
+        attempt: Schema.Int;
+     }>;
+   }>, Schema.Struct<{
+     agentId: Schema.String;
+     kind: Schema.Literal<"loop">;
+     schedule: Schema.Struct<{
+        sessionId: Schema.String;
+        loopId: Schema.String;
+        origin: Schema.Literals<...>;
+        expiresAt: Schema.NullOr<...>;
+        prompt: Schema.String;
+        mode: Schema.Literals<...>;
+        cron: Schema.NullOr<...>;
+        state: Schema.Literals<...>;
+        commandId: Schema.String;
+        reason: Schema.NullOr<...>;
+        nextDueAt: Schema.NullOr<...>;
+        lastError: Schema.NullOr<...>;
+        consecutiveFailures: Schema.Int;
+     }>;
+  }>]>>;
+  next: Schema.NullOr<Schema.Struct<{
+     agentId: Schema.String;
+     kind: Schema.Literals<readonly ["almanac", "loop"]>;
+     after: Schema.optionalKey<Schema.String>;
+  }>>;
+}>;
+```
+
+A bounded content-bearing page; owner failures reject rather than look empty.
+
+---
+
+### agentScheduleControlReceiptSchema
+
+```ts
+const agentScheduleControlReceiptSchema: Schema.Union<
+  readonly [
+    Schema.Struct<{
+      agentId: Schema.String;
+      kind: Schema.Literal<"almanac">;
+      scheduleId: Schema.String;
+      state: Schema.Literals<
+        readonly ["active", "paused", "cancelled", "finished"]
+      >;
+    }>,
+    Schema.Struct<{
+      agentId: Schema.String;
+      kind: Schema.Literal<"loop">;
+      sessionId: Schema.String;
+      loopId: Schema.String;
+      state: Schema.Literals<
+        readonly ["active", "paused", "finished", "failed", "cancelled"]
+      >;
+    }>,
+  ]
+>;
+```
+
+Manage-only result: exact target and native state, never prompt or history.