@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/workflows.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { type ModuleRegistration } from "@fungi.computer/mycelium";
+import { cancelReplySchema, statusReply } from "@fungi.computer/workflows-wire";
+import type { ReleaseId } from "@fungi.computer/puffball";
+import { appComputerAdmissionRefusalSchema } from "@fungi.computer/agar/computer-contracts";
+export { createWorkflowWebhooks, workflowWebhookCommandSchema, workflowWebhookControlResponse, } from "./webhooks.js";
+export { workflowWebhookRefusal } from "./webhook-ingress.js";
+/** Existing authoring operations available to an admitted Agent App invocation. */
+export declare const agentWorkflowOperationSchema: z.ZodEnum<{
+    catalog: "catalog";
+    armSchedule: "armSchedule";
+    disarmSchedule: "disarmSchedule";
+    schedules: "schedules";
+    armEventTrigger: "armEventTrigger";
+    disarmEventTrigger: "disarmEventTrigger";
+    eventTriggers: "eventTriggers";
+}>;
+export declare const agentAppWorkflowRequestSchema: z.ZodObject<{
+    authorityVersion: z.ZodNumber;
+    method: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    releaseId: z.ZodPipe<z.ZodString, z.ZodCustom<ReleaseId, ReleaseId>>;
+    installationId: z.ZodString;
+    computerId: z.ZodNullable<z.ZodString>;
+    operation: z.ZodEnum<{
+        catalog: "catalog";
+        armSchedule: "armSchedule";
+        disarmSchedule: "disarmSchedule";
+        schedules: "schedules";
+        armEventTrigger: "armEventTrigger";
+        disarmEventTrigger: "disarmEventTrigger";
+        eventTriggers: "eventTriggers";
+    }>;
+    requestId: z.ZodUUID;
+}, z.core.$strict>;
+export type AgentAppWorkflowRequest = z.output<typeof agentAppWorkflowRequestSchema>;
+export type AgentAppWorkflowPreparation = z.output<typeof appComputerAdmissionRefusalSchema> | Readonly<{
+    kind: "admitted";
+    attachmentId: string;
+    attachmentVersion: number;
+    grantorMemberId: string;
+    computerId: string | null;
+    authorityVersion: number;
+    releaseId: string;
+    appId: string;
+}>;
+/** Neutral identity shared by both host catalogs. */
+export declare const WORKFLOW_CONTROL_MODULE_ID = "workflow-control";
+/**
+ * Host-bound calls re-admit their principal on every execution.
+ *
+ * @inline
+ */
+export type WorkflowControl = Readonly<{
+    /** Read an admitted run's current status, or null when it is unavailable. */
+    status(runId: string): Promise<z.output<typeof statusReply> | null>;
+    /** Cancel an admitted run through the host's current Workflow authority. */
+    cancel(runId: string): Promise<z.output<typeof cancelReplySchema>>;
+}>;
+/** The same module and parsed execution closures serve either host. */
+export type WorkflowControlModule = Readonly<{
+    module: ModuleRegistration;
+    operations: Readonly<Record<"status" | "cancel", (input: z.core.util.JSONType) => Promise<z.core.util.JSONType>>>;
+}>;
+/** Parsed MCP and Agent operations over the host's live Workflow authority. */
+export declare function createMcpWorkflowControl(control: WorkflowControl): WorkflowControlModule;

package/dist/workflows.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { Mycelium } from "@fungi.computer/mycelium";
+import { cancelReplySchema } from "@fungi.computer/workflows-wire";
+import * as Schema from "effect/Schema";
+import { releaseIdSchema } from "@fungi.computer/puffball/effect";
+import { causeClass } from "./cause-class.js";
+export { createWorkflowWebhooks, workflowWebhookCommandSchema, workflowWebhookControlResponse, } from "./webhooks.js";
+export { workflowWebhookRefusal } from "./webhook-ingress.js";
+/** Existing authoring operations available to an admitted Agent App invocation. */
+export const agentWorkflowOperationSchema = z.enum([
+    "catalog",
+    "schedules",
+    "armSchedule",
+    "disarmSchedule",
+    "eventTriggers",
+    "armEventTrigger",
+    "disarmEventTrigger",
+]);
+export const agentAppWorkflowRequestSchema = z.strictObject({
+    authorityVersion: z.number().int().nonnegative(),
+    method: z.string().min(1).max(128),
+    sessionId: z.string().min(1).max(256).optional(),
+    releaseId: z.string().pipe(z.custom(Schema.is(releaseIdSchema))),
+    installationId: z.string().min(1).max(256),
+    computerId: z.string().min(1).max(256).nullable(),
+    operation: agentWorkflowOperationSchema,
+    requestId: z.uuidv7(),
+});
+/** Neutral identity shared by both host catalogs. */
+export const WORKFLOW_CONTROL_MODULE_ID = "workflow-control";
+const jsonValue = z.json();
+function retain(spec) {
+    return async (input) => spec.output.parseAsync(await spec.execute(await spec.input.parseAsync(input)));
+}
+/** Parsed MCP and Agent operations over the host's live Workflow authority. */
+export function createMcpWorkflowControl(control) {
+    const input = z.strictObject({ runId: z.string().min(1).max(256) });
+    const specs = {
+        cancel: {
+            description: "Cancel a run you started or administer. Completed runs remain terminal.",
+            input,
+            output: z.union([
+                cancelReplySchema,
+                z.strictObject({ kind: z.literal("error"), error: z.string() }),
+            ]),
+            execute: async ({ runId }) => {
+                try {
+                    return cancelReplySchema.parse(await control.cancel(runId));
+                }
+                catch (cause) {
+                    console.error("Workflow cancellation unavailable", causeClass(cause));
+                    return {
+                        kind: "error",
+                        error: "Workflow cancellation unavailable",
+                    };
+                }
+            },
+        },
+        status: {
+            description: "Read the live status and step projection of a Workflow run.",
+            input,
+            output: z.discriminatedUnion("kind", [
+                z.object({ kind: z.literal("found"), snapshot: jsonValue }),
+                z.object({ kind: z.literal("error"), error: z.string() }),
+            ]),
+            execute: async ({ runId }) => {
+                try {
+                    const snapshot = await control.status(runId);
+                    return snapshot === null
+                        ? { kind: "error", error: "Workflow run not found" }
+                        : { kind: "found", snapshot };
+                }
+                catch (cause) {
+                    console.error("Workflow status unavailable", causeClass(cause));
+                    return {
+                        kind: "error",
+                        error: "Workflow status unavailable",
+                    };
+                }
+            },
+        },
+    };
+    return {
+        module: Mycelium.module({
+            id: WORKFLOW_CONTROL_MODULE_ID,
+            name: "workflows",
+            operations: {
+                cancel: Mycelium.operation({ ...specs.cancel, replay: "unsafe" }),
+                status: Mycelium.operation({ ...specs.status, replay: "safe" }),
+            },
+        }),
+        operations: {
+            cancel: retain(specs.cancel),
+            status: retain(specs.status),
+        },
+    };
+}

package/docs/api/README.md

@@ -6,43 +6,35 @@
 
 # Oyster API overview
 
-| Import                                        | Export                                                                                             | Purpose                                                                                                                                 |
-| --------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `@fungi.computer/oyster`                      | `createAppInstance`                                                                                | Run one App Instance's lifecycle and admission over host-supplied ports.                                                                |
-| `@fungi.computer/oyster`                      | `InstancePorts`                                                                                    | The storage, artifact resolution, abort, purge and connection ports a host supplies.                                                    |
-| `@fungi.computer/oyster`                      | `selectionSchema`                                                                                  | Decode the owner-issued selection that authorizes a request.                                                                            |
-| `@fungi.computer/oyster`                      | `ownerStateSchema`                                                                                 | Decode a complete owner state: `enabled`, `disabled` or `deleted`.                                                                      |
-| `@fungi.computer/oyster`                      | `AppInstanceError`                                                                                 | Typed rejection with a stable `code` from `appInstanceErrorCodeSchema`.                                                                 |
-| `@fungi.computer/oyster`                      | `instanceIds`                                                                                      | Mint and recognize App Instance IDs.                                                                                                    |
-| `@fungi.computer/oyster/invocation`           | `createInvocationGate`, `invocationFacts`, `InvocationFrame`                                       | Run each request in one frame of host-admitted caller facts, with its deadline and abort signal.                                        |
-| `@fungi.computer/oyster/cloudflare`           | `createCloudflareAppInstance`                                                                      | Run an Instance in a SQLite Durable Object with a Worker Loader facet (workerd or celld).                                               |
-| `@fungi.computer/oyster/apps`                 | `Installation`, `applyInstallationCommand`, `admits`, `approvedBindingGrants`                      | Pure installation approvals and admission; host-owned commits and tenant freshness.                                                     |
-| `@fungi.computer/oyster/host`                 | `createOyster`                                                                                     | The Oyster App server: a Hono app over host adapters for sign-in, Releases, installations and Instances.                                |
-| `@fungi.computer/oyster/auth`                 | `ownerKeyAuth`, `ownerOrKeyAuth`                                                                   | Owner-key sign-in (a Bearer key or the login cookie, compared in constant time) and named agent keys as Team-key principals.            |
-| `@fungi.computer/oyster/tenant`               | `TenantScope`, `tenantScope`, `singleTenant`, `OysterTenancy`                                      | Host-resolved tenant identity and the scope that prefixes registry, key and repository names.                                           |
-| `@fungi.computer/oyster/workers`              | `createOysterWorker`                                                                               | A standalone single-owner Oyster on Workers or celld: R2 Releases, a registry and one Durable Object per Instance.                      |
-| `@fungi.computer/oyster/pack`                 | `packRelease`, `installRelease`, `installFromSource`, `publishSource`                              | Build a committed App through the canonical recipe compiler and install its Release on an Oyster over HTTP.                             |
-| `@fungi.computer/oyster/build`                | `createAppCandidatePreparer`, `createLocalBuildExecutor`                                           | Node-only source capture, pinned compilation and local artifact writing.                                                                |
-| `@fungi.computer/oyster/build-contract`       | Recipe schemas and candidate orchestration                                                         | The Worker-safe half of `./build`, without the executor.                                                                                |
-| `@fungi.computer/oyster/app-storage`          | `AppStorageBinding`                                                                                | `env.APP_STORAGE` for methods and lifecycle handlers: lifecycle writes go to the team layer and reach `appStorage.watch`.               |
-| `@fungi.computer/oyster/app-storage`          | `createAppStorage`, `appStorageSchemaStatements`                                                   | SQLite owner for declared keys, live member/lifecycle admission, revision checks and watch invalidations.                               |
-| `@fungi.computer/oyster/mcp`                  | `oysterAppMethods`, `oysterComputerTools`, `oysterMcpCatalogLoad`                                  | Installed App methods and the host's Computer as Mycelium modules for the shared MCP endpoint, scoped to the caller.                    |
-| `@fungi.computer/oyster/agents`               | `OysterAgents`, `agentCapabilities`, `agentApprovalRoutes`                                         | The host's Agent slot, its App capabilities and the owner-only approval routes.                                                         |
-| `@fungi.computer/oyster/computer`             | `computerSlots`, `ComputerTerminalHost`                                                            | Computer ports, processes and terminal routes supplied by the host; execution stays in the Computer runtime.                            |
-| `@fungi.computer/oyster/media`                | `mediaSlot`                                                                                        | The media capability slot a host fills; Oyster owns routing, never generation.                                                          |
-| `@fungi.computer/oyster/files`                | `FileSource`                                                                                       | Files Apps reach through Agar's `computer.*` file contracts, with a compare-and-swap replace.                                           |
-| `@fungi.computer/oyster/root-data`            | `createOysterRootData`                                                                             | Installation and verified Release owners as shared workbench metadata for a standalone root.                                            |
-| `@fungi.computer/oyster/page`                 | `mountOysterPage`, `connectOysterApp`, `readOysterPageConfig`                                      | Mount one installed App's sandboxed frame and connect its admitted slots.                                                               |
-| `@fungi.computer/oyster/shell`                | Shell client exports                                                                               | Build a browser or terminal host from the focused entries below.                                                                        |
-| `@fungi.computer/oyster/shell/workbench`      | Workbench types and schemas                                                                        | Describe child mounts, geometry and Gill arrangers without platform policy.                                                             |
-| `@fungi.computer/oyster/shell/command-host`   | `createAppSurfaceCommandHost`                                                                      | Admit declared commands and own focus and contribution lifetimes.                                                                       |
-| `@fungi.computer/oyster/shell/keys`           | `installShellKeys`, `parseChord`                                                                   | Match chords and optionally install DOM key dispatch.                                                                                   |
-| `@fungi.computer/oyster/shell/commands`       | `shellCommands`                                                                                    | Declare shell commands over embedding-host callbacks.                                                                                   |
-| `@fungi.computer/oyster/shell/window-manager` | `createWindowManager`                                                                              | Own window generations, visibility and disposal over a mount adapter.                                                                   |
-| `@fungi.computer/oyster/shell/app-directory`  | Directory schemas                                                                                  | Decode host-neutral addresses and App metadata before permissions.                                                                      |
-| `@fungi.computer/oyster/shell/shell-module`   | `importShellModule`, `ShellMountInput`, `MountShell`                                               | Load the picked shell Release's `mountShell` module from the host's own origin and hand it the workbench, storage and methods.          |
-| `@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.                    |
+| Import                                  | Export                                                                                             | Purpose                                                                                                                                 |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `@fungi.computer/oyster`                | `createAppInstance`                                                                                | Run one App Instance's lifecycle and admission over host-supplied ports.                                                                |
+| `@fungi.computer/oyster`                | `InstancePorts`                                                                                    | The storage, artifact resolution, abort, purge and connection ports a host supplies.                                                    |
+| `@fungi.computer/oyster`                | `selectionSchema`                                                                                  | Decode the owner-issued selection that authorizes a request.                                                                            |
+| `@fungi.computer/oyster`                | `ownerStateSchema`                                                                                 | Decode a complete owner state: `enabled`, `disabled` or `deleted`.                                                                      |
+| `@fungi.computer/oyster`                | `AppInstanceError`                                                                                 | Typed rejection with a stable `code` from `appInstanceErrorCodeSchema`.                                                                 |
+| `@fungi.computer/oyster`                | `instanceIds`                                                                                      | Mint and recognize App Instance IDs.                                                                                                    |
+| `@fungi.computer/oyster/invocation`     | `createInvocationGate`, `invocationFacts`, `InvocationFrame`                                       | Run each request in one frame of host-admitted caller facts, with its deadline and abort signal.                                        |
+| `@fungi.computer/oyster/cloudflare`     | `createCloudflareAppInstance`                                                                      | Run an Instance in a SQLite Durable Object with a Worker Loader facet (workerd or celld).                                               |
+| `@fungi.computer/oyster/apps`           | `Installation`, `applyInstallationCommand`, `admits`, `approvedBindingGrants`                      | Pure installation approvals and admission; host-owned commits and tenant freshness.                                                     |
+| `@fungi.computer/oyster/host`           | `createOyster`                                                                                     | The Oyster App server: a Hono app over host adapters for sign-in, Releases, installations and Instances.                                |
+| `@fungi.computer/oyster/auth`           | `ownerKeyAuth`, `ownerOrKeyAuth`                                                                   | Owner-key sign-in (a Bearer key or the login cookie, compared in constant time) and named agent keys as Team-key principals.            |
+| `@fungi.computer/oyster/tenant`         | `TenantScope`, `tenantScope`, `singleTenant`, `OysterTenancy`                                      | Host-resolved tenant identity and the scope that prefixes registry, key and repository names.                                           |
+| `@fungi.computer/oyster/workers`        | `createOysterWorker`                                                                               | A standalone single-owner Oyster on Workers or celld: R2 Releases, a registry and one Durable Object per Instance.                      |
+| `@fungi.computer/oyster/pack`           | `packRelease`, `installRelease`, `installFromSource`, `publishSource`                              | Build a committed App through the canonical recipe compiler and install its Release on an Oyster over HTTP.                             |
+| `@fungi.computer/oyster/build`          | `createAppCandidatePreparer`, `createLocalBuildExecutor`                                           | Node-only source capture, pinned compilation and local artifact writing.                                                                |
+| `@fungi.computer/oyster/build-contract` | Recipe schemas and candidate orchestration                                                         | The Worker-safe half of `./build`, without the executor.                                                                                |
+| `@fungi.computer/oyster/app-storage`    | `AppStorageBinding`                                                                                | `env.APP_STORAGE` for methods and lifecycle handlers: lifecycle writes go to the team layer and reach `appStorage.watch`.               |
+| `@fungi.computer/oyster/app-storage`    | `createAppStorage`, `appStorageSchemaStatements`                                                   | SQLite owner for declared keys, live member/lifecycle admission, revision checks and watch invalidations.                               |
+| `@fungi.computer/oyster/mcp`            | `oysterAppMethods`, `oysterComputerTools`, `oysterMcpCatalogLoad`                                  | Installed App methods and the host's Computer as Mycelium modules for the shared MCP endpoint, scoped to the caller.                    |
+| `@fungi.computer/oyster/agents`         | `OysterAgents`, `agentCapabilities`, `agentApprovalRoutes`                                         | The host's Agent slot, its App capabilities and the owner-only approval routes.                                                         |
+| `@fungi.computer/oyster/computer`       | `computerSlots`, `ComputerTerminalHost`                                                            | Computer ports, processes and terminal routes supplied by the host; execution stays in the Computer runtime.                            |
+| `@fungi.computer/oyster/media`          | `mediaSlot`                                                                                        | The media capability slot a host fills; Oyster owns routing, never generation.                                                          |
+| `@fungi.computer/oyster/files`          | `FileSource`                                                                                       | Files Apps reach through Agar's `computer.*` file contracts, with a compare-and-swap replace.                                           |
+| `@fungi.computer/oyster/root-data`      | `createOysterRootData`                                                                             | Installation and verified Release owners as shared workbench metadata for a standalone root.                                            |
+| `@fungi.computer/oyster/page`           | `mountOysterPage`, `connectOysterApp`, `readOysterPageConfig`                                      | Mount one installed App's sandboxed frame and connect its admitted slots.                                                               |
+| `@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.                    |
 
 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
@@ -50,6 +42,40 @@ host has that authority: owner-state replay and conflict rules, Release
 resolution, state-schema compatibility, fencing on disable and purge on delete.
 The generated module pages below include every port and record type.
 
+## App Agent send API — breaking change
+
+An App with the `AGENTS.send` binding sends into an existing authorized Session:
+
+```ts
+const intent = {
+  agentId,
+  sessionId,
+  requestId: crypto.randomUUID(),
+  text: "Continue this work",
+  delivery: "followUp" as const,
+};
+
+const accepted = await env.AGENTS.send(intent);
+// If the outcome is UNKNOWN, retry env.AGENTS.send(intent), unchanged.
+```
+
+`requestId` is required, non-empty, and bounded to 256 UTF-8 bytes. Mint it once
+per user intent, outside the send/retry function, and retain the same input
+until the outcome is known. An UNKNOWN response is not evidence that admission
+failed: the recipient may already have accepted the work. Retrying that same
+intent must not create another delivery. A new intent needs a new request ID.
+
+The App bridge forwards the caller's ID. The standalone adapter no longer mints
+one, and neither path substitutes a transport `callId`. An omitted ID is
+refused; there is no compatibility form. Grove's `sendMessage` method requires
+and forwards the same field. Admission, the existing send budget, and follow-up
+delivery policy are unchanged.
+
+**BREAKING CHANGE:** App `AGENTS.send` and Grove `sendMessage` now require
+caller-owned `requestId`. Update existing Apps and their retry state before
+using this API. This release note does not authorize a version bump or
+publication.
+
 ## Guest execution policy
 
 `createOyster({ ...host, guestLimits: { cpuMs: 250, subRequests: 10 } })`

package/docs/api/agents.md

@@ -16,6 +16,7 @@
 type OysterAgent = Readonly<{
   agentId: string;
   name: string;
+  avatar: Avatar;
   sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
 }>;
 ```
@@ -160,6 +161,7 @@ type OysterAgents = Readonly<{
     readonly Readonly<{
       agentId: string;
       name: string;
+      avatar: Avatar;
       sessionOperations: readonly (
         "agent.read" | "agent.send" | "agent.manage"
       )[];
@@ -169,6 +171,7 @@ type OysterAgents = Readonly<{
     Readonly<{
       agentId: string;
       name: string;
+      avatar: Avatar;
       sessionOperations: readonly (
         "agent.read" | "agent.send" | "agent.manage"
       )[];
@@ -178,6 +181,7 @@ type OysterAgents = Readonly<{
     | Readonly<{
         agentId: string;
         name: string;
+        avatar: Avatar;
         sessionOperations: readonly (
           "agent.read" | "agent.send" | "agent.manage"
         )[];
@@ -186,6 +190,19 @@ type OysterAgents = Readonly<{
         error: "not_found" | "name_taken" | "not_granted";
       }>
   >;
+  setAvatar: Promise<
+    | Readonly<{
+        agentId: string;
+        name: string;
+        avatar: Avatar;
+        sessionOperations: readonly (
+          "agent.read" | "agent.send" | "agent.manage"
+        )[];
+      }>
+    | Readonly<{
+        error: "not_found" | "not_granted";
+      }>
+  >;
   policyStatus: Promise<Readonly<{
     status: "pending" | "approved";
     revision: string;

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`   | `"team"` \| `"member"`                  |
+| `scope`   | `"member"` \| `"team"`                  |
 
 #### Returns