@fungi.computer/oyster 0.6.0 → 0.7.0

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

@@ -38,6 +38,7 @@ import { AppInstanceError, } from "./index.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 { reportSlowInvocation } from "./internal/invocation-timing.js";
 import { releaseCache } from "./internal/host-gate.js";
 import { createOyster, } from "./host.js";
 import { createGitPushJournal } from "./git-journal.js";
@@ -66,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;
@@ -161,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({
@@ -376,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) {
@@ -762,9 +767,19 @@ export class OysterInstance extends DurableObject {
         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.
@@ -784,10 +799,14 @@ 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(props.frameId) !== frame)
             throw new AppInstanceError("revoked");
@@ -848,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",
@@ -860,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" &&
@@ -895,6 +917,7 @@ export class OysterInstance extends DurableObject {
             };
         }
         let host = {
+            bindingWaits: { count: 0, ms: 0 },
             artifact: { release, ...resolved },
             declaration: resolved.declaration,
             origin: "unchecked",
@@ -904,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

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.

package/docs/api/agents.md

@@ -167,6 +167,26 @@ type OysterAgents = Readonly<{
       )[];
     }>[]
   >;
+  setArchived: Promise<
+    | Readonly<{
+        archived: boolean;
+        revision: number;
+      }>
+    | Readonly<{
+        error:
+          | "not_found"
+          | "not_granted"
+          | "self"
+          | "not_creator"
+          | "running"
+          | "pending"
+          | "unreadable"
+          | "archived";
+        message?: string;
+        archived?: boolean;
+        revision?: number;
+      }>
+  >;
   create: Promise<
     Readonly<{
       agentId: string;
@@ -301,7 +321,12 @@ type OysterAgents = Readonly<{
 }>;
 ```
 
-Where an Oyster's agents live and run.
+Where an Oyster's agents live and run. Archive is non-destructive: `list()`
+hides archived agents, and `list({ archived: true })` shows only archives.
+Archived agents keep existing reads, replays and settlements, but refuse new
+Sessions, prompts and steers with `contract/archived`. Archive refuses non-idle
+Session work or unsettled delegations; it pauses Almanac and Loop schedules and
+restores only archive-paused schedules on unarchive.
 
 ---
 
@@ -358,20 +383,16 @@ optional bearer.
 ### agentCapabilities()
 
 ```ts
-function agentCapabilities(
-  agents,
-  liveKey,
-): readonly Readonly<object & object>[];
+function agentCapabilities(agents): readonly Readonly<object & object>[];
 ```
 
 Agent adapters admitted against each App's declared capabilities.
 
 #### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                 |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agents`  | [`OysterAgents`](#oysteragents)                                                                                                                                                                                                                                      |
-| `liveKey` | (`keyId`) => `Promise`\< \| `Readonly`\<\{ `keyId`: `string`; `owner`: `string`; `grantVersion`: `number`; `grants`: readonly `Readonly`\<\{ `capability`: [`OysterKeyCapability`](keys.md#oysterkeycapability); `targets`: `GrantTargets`; \}\>[]; \}\> \| `null`\> |
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `agents`  | [`OysterAgents`](#oysteragents) |
 
 #### Returns
 
@@ -382,7 +403,7 @@ readonly `Readonly`\<`object` & `object`\>[]
 ### agentApprovalRoutes()
 
 ```ts
-function agentApprovalRoutes(agents): Hono<OysterEnv>;
+function agentApprovalRoutes(agents): Routes<OysterEnv>;
 ```
 
 Host-owned direct approval under the admitted owner; never an App capability.
@@ -395,14 +416,14 @@ Host-owned direct approval under the admitted owner; never an App capability.
 
 #### Returns
 
-`Hono`\<[`OysterEnv`](host.md#oysterenv)\>
+[`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\>
 
 ---
 
 ### agentMcpServerRoutes()
 
 ```ts
-function agentMcpServerRoutes(agents): Hono<OysterEnv>;
+function agentMcpServerRoutes(agents): Routes<OysterEnv>;
 ```
 
 Host-owned Agent MCP server custody for the owner directly; never an App
@@ -416,4 +437,4 @@ capability. Bearer tokens go in and never come back out.
 
 #### Returns
 
-`Hono`\<[`OysterEnv`](host.md#oysterenv)\>
+[`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\>

package/docs/api/app-storage.md

@@ -131,7 +131,7 @@ Whether `writer` may mutate `scope`; anything else is `owner_required`.
 | Parameter | Type                                    |
 | --------- | --------------------------------------- |
 | `writer`  | [`AppStorageWriter`](#appstoragewriter) |
-| `scope`   | `"member"` \| `"team"`                  |
+| `scope`   | `"team"` \| `"member"`                  |
 
 #### Returns