@fungi.computer/oyster 0.5.0 → 0.7.0

package/dist/invocation.js

@@ -1,8 +1,6 @@
 import { approvedBindingGrants } from "./apps/gate.js";
 import { appToolPolicySchema } from "./apps/tools.js";
-import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import * as Semaphore from "effect/Semaphore";
 import { defineIdFamily } from "@fungi.computer/cairn/id";
 import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
 import { appBackendBindingKinds, appBackendBindingsSchema, appMethodCallContextSchema, } from "@fungi.computer/puffball/app";
@@ -152,28 +150,115 @@ function immutableFacts(facts) {
     Object.freeze(facts.ancestry);
     return Object.freeze(facts);
 }
-/** Serialize authority, preempt replay only for verified writes, and close each guest before admission. */
+const concurrentReadFrames = 8;
+/**
+ * First-come permits over one guest: a waiting exclusive frame holds back
+ * every frame queued after it, so a stream of reads never starves a write.
+ */
+function orderedPermits(total) {
+    let available = total;
+    const waiting = [];
+    const admit = () => {
+        for (let next = waiting[0]; next !== undefined; next = waiting[0]) {
+            const count = next.requested();
+            if (count > available)
+                break;
+            waiting.shift();
+            available -= count;
+            next.enter(count);
+        }
+    };
+    return async (requested, work) => {
+        const permits = await new Promise((enter) => {
+            waiting.push({ requested, enter });
+            admit();
+        });
+        try {
+            return await work();
+        }
+        catch (cause) {
+            throw cause instanceof Error
+                ? cause
+                : new Error("App invocation failed", { cause });
+        }
+        finally {
+            available += permits;
+            admit();
+        }
+    };
+}
+/** Only foreground reads declared by the verified API may share the guest. */
+function concurrentRead(facts) {
+    return (facts.subject.kind === "call" &&
+        facts.subject.replay === undefined &&
+        facts.subject.method?.effect === "read");
+}
+/**
+ * One Instance shares up to eight verified foreground reads; all other work
+ * runs alone in first-come order. Every finish fences its frame; the last live
+ * frame stops the native guest before closing authority and releasing admission.
+ * Binding checks alone cannot stop a timer mutating the facet's own SQLite.
+ * Revocation, expiry and a verified write preempting replay stop every live frame.
+ * Arrivals wait for a stopping guest. Once the opening deadline passes, new
+ * reads queue exclusively so the current cohort cannot be prolonged forever.
+ */
 export function createInvocationGate(ports) {
-    const permit = Semaphore.makeUnsafe(1);
+    const permits = orderedPermits(concurrentReadFrames);
     const now = ports.now ?? Date.now;
+    let stopping;
+    let cohortDeadlineAt;
+    const withPermits = (read, work) => permits(() => read && (cohortDeadlineAt === undefined || now() < cohortDeadlineAt)
+        ? 1
+        : concurrentReadFrames, async () => {
+        while (stopping !== undefined)
+            await stopping;
+        return work();
+    });
+    const stopGuest = () => {
+        if (stopping !== undefined)
+            return stopping;
+        let aborted;
+        try {
+            aborted = ports.abortGuest();
+        }
+        catch (cause) {
+            aborted = Promise.reject(cause instanceof Error
+                ? cause
+                : new Error("App guest stop failed", { cause }));
+        }
+        const stopped = aborted.finally(() => {
+            cohortDeadlineAt = undefined;
+            stopping = undefined;
+        });
+        stopping = stopped;
+        return stopped;
+    };
     let foregroundWaiting = 0;
-    let active;
-    const close = (state, reason) => {
+    const live = new Map();
+    const finish = (state, reason) => {
         if (state.closing)
             return state.closing;
-        if (active === state)
-            active = undefined;
         state.controller.abort(reason);
-        state.closing = (async () => {
-            try {
-                await ports.abortGuest();
-            }
-            finally {
-                await ports.close(state.frame);
-            }
-        })();
+        live.delete(state.frame.frameId);
+        state.closing =
+            live.size === 0
+                ? stopGuest().finally(() => ports.close(state.frame))
+                : ports.close(state.frame);
         return state.closing;
     };
+    // The guest is shared: aborting it ends every live frame's guest work, and
+    // each of those frames closes only after the guest abort has completed.
+    const abortAll = (reason) => {
+        const states = [...live.values()];
+        for (const state of states) {
+            live.delete(state.frame.frameId);
+            state.controller.abort(reason);
+        }
+        const guest = stopGuest();
+        for (const state of states)
+            state.closing ??= guest.finally(() => ports.close(state.frame));
+        return Promise.all([guest, ...states.map((state) => state.closing)]).then(() => undefined);
+    };
     const run = async (input, host, work) => {
         let facts;
         try {
@@ -196,64 +281,64 @@ export function createInvocationGate(ports) {
             if (queuedForeground &&
                 facts.subject.kind === "call" &&
                 facts.subject.method?.effect === "write" &&
-                active?.frame.facts.subject.kind === "call" &&
-                active.frame.facts.subject.replay !== undefined)
-                await close(active, new AppInstanceError("revoked"));
-            return await Effect.runPromise(permit.withPermits(1)(Effect.tryPromise({
-                try: async () => {
-                    if (facts.subject.kind === "call" &&
-                        facts.subject.replay !== undefined &&
-                        foregroundWaiting > 0)
-                        throw new AppInstanceError("revoked");
-                    if (queuedForeground) {
-                        foregroundWaiting -= 1;
-                        queuedForeground = false;
-                    }
-                    const { deadlineAt } = facts;
-                    if (deadlineAt <= now())
-                        throw new AppInstanceError("expired");
-                    const frameId = frameIds.frame.generate();
-                    const controller = new AbortController();
-                    const frame = Object.freeze({
-                        frameId,
-                        facts,
-                        host,
-                        signal: controller.signal,
-                    });
-                    const state = { frame, controller };
-                    active = state;
-                    let timer;
-                    let stop = () => undefined;
-                    const revoked = new Promise((_resolve, reject) => {
-                        const onAbort = () => {
-                            const reason = controller.signal.reason;
-                            reject(reason instanceof Error
-                                ? reason
-                                : new AppInstanceError("revoked"));
-                        };
-                        controller.signal.addEventListener("abort", onAbort, {
-                            once: true,
-                        });
-                        stop = () => {
-                            controller.signal.removeEventListener("abort", onAbort);
-                        };
-                        timer = setTimeout(() => {
-                            controller.abort(new AppInstanceError("expired"));
-                        }, Math.max(0, deadlineAt - now()));
+                [...live.values()].some(({ frame }) => frame.facts.subject.kind === "call" &&
+                    frame.facts.subject.replay !== undefined))
+                await abortAll(new AppInstanceError("revoked"));
+            return await withPermits(concurrentRead(facts), async () => {
+                if (facts.subject.kind === "call" &&
+                    facts.subject.replay !== undefined &&
+                    foregroundWaiting > 0)
+                    throw new AppInstanceError("revoked");
+                if (queuedForeground) {
+                    foregroundWaiting -= 1;
+                    queuedForeground = false;
+                }
+                const { deadlineAt } = facts;
+                if (deadlineAt <= now())
+                    throw new AppInstanceError("expired");
+                const frameId = frameIds.frame.generate();
+                const controller = new AbortController();
+                const frame = Object.freeze({
+                    frameId,
+                    facts,
+                    host,
+                    signal: controller.signal,
+                });
+                const state = { frame, controller };
+                cohortDeadlineAt ??= deadlineAt;
+                live.set(frameId, state);
+                let timer;
+                let stop = () => undefined;
+                const revoked = new Promise((_resolve, reject) => {
+                    const onAbort = () => {
+                        const reason = controller.signal.reason;
+                        reject(reason instanceof Error
+                            ? reason
+                            : new AppInstanceError("revoked"));
+                    };
+                    controller.signal.addEventListener("abort", onAbort, {
+                        once: true,
                     });
-                    try {
-                        return await Promise.race([work(frame), revoked]);
-                    }
-                    finally {
-                        clearTimeout(timer);
-                        stop();
-                        await close(state, new AppInstanceError("revoked"));
-                    }
-                },
-                catch: (cause) => cause instanceof Error
-                    ? cause
-                    : new Error("App invocation failed", { cause }),
-            })));
+                    stop = () => {
+                        controller.signal.removeEventListener("abort", onAbort);
+                    };
+                    timer = setTimeout(() => {
+                        // An expired frame's guest may still be running. Each frame's own
+                        // run awaits its close, so a failure reaches that caller.
+                        void Promise.allSettled([
+                            abortAll(new AppInstanceError("expired")),
+                        ]);
+                    }, Math.max(0, deadlineAt - now()));
+                });
+                try {
+                    return await Promise.race([work(frame), revoked]);
+                }
+                finally {
+                    clearTimeout(timer);
+                    stop();
+                    await finish(state, new AppInstanceError("revoked"));
+                }
+            });
         }
         finally {
             if (queuedForeground)
@@ -262,40 +347,30 @@ export function createInvocationGate(ports) {
     };
     return {
         run,
-        exclusive: (work) => Effect.runPromise(permit.withPermits(1)(Effect.tryPromise({
-            try: work,
-            catch: (cause) => cause instanceof Error
-                ? cause
-                : new Error("Instance supervisor operation failed", { cause }),
-        }))),
-        active: () => {
-            if (active === undefined ||
-                active.controller.signal.aborted ||
-                active.frame.facts.deadlineAt <= now())
+        exclusive: (work) => withPermits(false, work),
+        active: (frameId) => {
+            const state = live.get(frameId);
+            if (state === undefined ||
+                state.controller.signal.aborted ||
+                state.frame.facts.deadlineAt <= now())
                 throw new AppInstanceError("revoked");
-            return active.frame;
+            return state.frame;
         },
         revoke: (reason = new AppInstanceError("revoked"), target) => {
-            if (active === undefined)
-                return Promise.resolve();
-            if (target !== undefined &&
-                (active.frame.facts.subject.kind !== "call" ||
-                    active.frame.facts.subject.context.workflow?.runId !== target.runId))
-                return Promise.resolve();
-            return close(active, reason);
+            const matched = [...live.values()].some(({ frame }) => target === undefined ||
+                (frame.facts.subject.kind === "call" &&
+                    frame.facts.subject.context.workflow?.runId === target.runId));
+            return matched ? abortAll(reason) : Promise.resolve();
         },
     };
 }
 /**
  * Project an admitted principal into App attribution; only the host chooses
- * the fixed Computer context. The App caller grammar has no visitor actor, so
- * the anonymous public reader is attributed as the reserved `visitor` key
- * without a Computer. Host admission reads the principal, never this projection.
+ * the fixed Computer context. Host admission reads the principal, never this
+ * projection.
  */
 export function invocationCallerContext(principal, computerId) {
     const { actor } = principal;
-    if (actor.kind === "visitor")
-        return { computerId: null, actor: { kind: "team-key", keyId: "visitor" } };
     if (!("role" in principal))
         return { computerId, actor };
     return principal.soleMember === true

package/dist/keys.d.ts

@@ -1,6 +1,5 @@
 import type { Grant, GrantVocabulary, Scope } from "@fungi.computer/ear-tag/grants";
 import type { KeyPrincipal, KeyRecord, KeyStore } from "@fungi.computer/ear-tag/keys";
-import type { AppToolPolicy } from "./apps/tools.js";
 /** Every capability an Oyster key may carry. */
 export type OysterKeyCapability = "apps.read" | "apps.use" | "agents.use" | "computer.use" | "machine.enroll";
 /**
@@ -28,8 +27,8 @@ export type OysterKeyStore = KeyStore<OysterKeyCapability>;
 /**
  * The minimal live facts `OysterHost`'s `keys.live` port returns: enough to
  * gate one call, never the key's name or timestamps. `null` for an unknown,
- * revoked, expired or suspended key -- the same closed set `keyAppAccess`
- * and `keyAllowsComputerUse` already treat as no authority.
+ * revoked, expired or suspended key, which `authorization.ts` treats as no
+ * authority.
  */
 export type LiveOysterKey = Readonly<{
     keyId: string;
@@ -37,19 +36,3 @@ export type LiveOysterKey = Readonly<{
     grantVersion: number;
     grants: readonly Grant<OysterKeyCapability>[];
 }>;
-/**
- * One live key's access to one installation: `write` when its grants admit
- * `apps.use` there, `read` when they admit `apps.read`, otherwise `null` --
- * including for an installation added after the key was issued, unless the
- * key holds "All Apps" (`targets: {kind: "all"}`). The same shape as an
- * Agent's stored {@link AppToolPolicy}; its caller adds `bindingName` (which
- * varies by caller: the plain installation id for the gate, the uppercased
- * binding name for MCP) to reach the full `AppToolAccess`.
- */
-export declare function keyAppAccess(key: LiveOysterKey, installationId: string): AppToolPolicy | null;
-/** Agent access is scoped to the granted Agent ids, never inferred from App grants. */
-export declare function keyAgentAccess(key: LiveOysterKey, agentId: string): boolean;
-/** Whether a live key's own grants turn its Computer access on. Off by default. */
-export declare function keyAllowsComputerUse(key: LiveOysterKey): boolean;
-/** Whether a live key's grants permit a one-use device enrollment. */
-export declare function keyAllowsMachineEnroll(key: LiveOysterKey): boolean;

package/dist/keys.js

@@ -2,6 +2,7 @@
  * Oyster's own Ear Tag vocabulary: named keys an owner issues for selected
  * Apps and Agents, its Computer or machine enrollment. App grants never imply
  * Agent access. A key's id is its name, so name-derived identities stay stable.
+ * What a key reaches is decided only in `authorization.ts`.
  */
 import { defineGrants } from "@fungi.computer/ear-tag/grants";
 /**
@@ -32,40 +33,3 @@ export const computerUseGrant = {
     capability: "computer.use",
     targets: { kind: "all" },
 };
-/**
- * One live key's access to one installation: `write` when its grants admit
- * `apps.use` there, `read` when they admit `apps.read`, otherwise `null` --
- * including for an installation added after the key was issued, unless the
- * key holds "All Apps" (`targets: {kind: "all"}`). The same shape as an
- * Agent's stored {@link AppToolPolicy}; its caller adds `bindingName` (which
- * varies by caller: the plain installation id for the gate, the uppercased
- * binding name for MCP) to reach the full `AppToolAccess`.
- */
-export function keyAppAccess(key, installationId) {
-    const level = oysterKeyVocabulary.grantsAllow(key.grants, "apps.use", installationId)
-        ? "write"
-        : oysterKeyVocabulary.grantsAllow(key.grants, "apps.read", installationId)
-            ? "read"
-            : null;
-    if (level === null)
-        return null;
-    return {
-        level,
-        revision: `key:${key.keyId}:${String(key.grantVersion)}`,
-        grantedBy: key.owner,
-    };
-}
-/** Agent access is scoped to the granted Agent ids, never inferred from App grants. */
-export function keyAgentAccess(key, agentId) {
-    return oysterKeyVocabulary.grantsAllow(key.grants, "agents.use", agentId);
-}
-/** Whether a live key's own grants turn its Computer access on. Off by default. */
-export function keyAllowsComputerUse(key) {
-    return oysterKeyVocabulary.grantsAllow(key.grants, "computer.use");
-}
-/** Whether a live key's grants permit a one-use device enrollment. */
-export function keyAllowsMachineEnroll(key) {
-    return (key.grants.length === 1 &&
-        key.grants[0]?.capability === "machine.enroll" &&
-        oysterKeyVocabulary.grantsAllow(key.grants, "machine.enroll"));
-}

package/dist/mcp.d.ts

@@ -2,12 +2,11 @@ import { z } from "zod";
 import { type AppToolPolicy } from "./apps/tools.js";
 import type { DeclaredOperations, Installation } from "./apps/installation.js";
 import { type CapabilitySource, type Grants, type ModuleRegistration } from "@fungi.computer/mycelium";
-import { appToolSchemas } from "@fungi.computer/forage";
 import { computerPageSchema } from "@fungi.computer/computer/fleet/inventory-wire";
 import type { InvocationContext } from "@fungi.computer/mycelium";
 import type { ComputerControlPort } from "./computer-control-port.js";
 export type { ComputerControlPort } from "./computer-control-port.js";
-import type { OysterHost, OysterPrincipal } from "./host.js";
+import type { OysterHost } from "./host.js";
 import type { TenantPrincipal } from "./tenant.js";
 import { type VerifiedRelease } from "./release.js";
 /** Captured capabilities and grants offered to one admitted MCP caller. */
@@ -17,6 +16,8 @@ export type OysterMcpCatalogSnapshot = Readonly<{
     /** An omitted module has no grant. */
     grants: Grants;
 }>;
+/** Shared host result guidance for Agent and MCP instructions, not per method. */
+export declare const appApprovalInstructions: string;
 declare const fleetComputerId: z.ZodObject<{
     computerId: z.ZodString;
 }, z.core.$strict>;
@@ -33,10 +34,10 @@ declare const fleetCreation: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodEnum<{
+        invalid: "invalid";
         denied: "denied";
         uncertain: "uncertain";
         conflict: "conflict";
-        invalid: "invalid";
     }>;
     requestId: z.ZodString;
 }, z.core.$strict>], "kind">;
@@ -135,10 +136,10 @@ export declare function computerControlSpecs(port: ComputerControlPort): {
             }, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodEnum<{
+                invalid: "invalid";
                 denied: "denied";
                 uncertain: "uncertain";
                 conflict: "conflict";
-                invalid: "invalid";
             }>;
             requestId: z.ZodString;
         }, z.core.$strict>], "kind">;
@@ -159,7 +160,7 @@ export declare class AppMethodRefused extends Error {
  * The App-tool access one caller's catalog capture used, re-checked at call
  * time against a fresh read. An Agent's policy is one blanket level for
  * every installation (`host.appToolPolicy`); a key's is its own grants,
- * resolved per installation (`keyAppAccess`) -- an installation the key has
+ * resolved per installation (`appToolAccess`) -- an installation the key has
  * no grant for is captured as absent, never merely refused, so it is never
  * listed at all.
  */
@@ -171,35 +172,23 @@ export type OysterCallerAccess = Readonly<{
     keyId: string;
     byInstallation: ReadonlyMap<string, AppToolPolicy>;
 }> | null;
-/** What one Release contributes to every MCP catalog: its verified build,
- * its declared operations and its compiled tool schemas. */
+/** Immutable Release data shared by captures; no validator graphs live here. */
 export type ReleaseSurface = Readonly<{
     release: VerifiedRelease;
     api: NonNullable<VerifiedRelease["api"]>;
     declaredOperations: DeclaredOperations;
-    toolSchemas: ReturnType<typeof appToolSchemas>;
+    methods: NonNullable<VerifiedRelease["api"]>["methods"];
 }>;
 /**
- * Per-host memo of each installed Release's catalog surface. A Release's
- * artifacts are immutable and content-addressed, so verifying the build,
- * deriving its operations and compiling its tool schemas happens once per
- * Release ID and artifact digest, not on every catalog capture: an MCP call
- * captures the catalog several times (refresh, session acquire, the pre-call
- * authority check), and redoing this for every installed App on each one
- * exhausted a Durable Object's CPU and memory. Only Release-derived facts are
- * cached; installation authority, caller access and tool-family listings
- * are still read fresh on every capture. A failed build is not cached.
+ * Per-host verified data, keyed by immutable Release ID and artifact digest.
+ * Authority, caller access and tool-family listings stay fresh per capture.
+ * Failed verification is not cached.
  */
 export type AppSurfaceCache = (release: Installation["release"]) => Promise<ReleaseSurface | null>;
 /** Make one {@link AppSurfaceCache} for a host whose artifact store and capabilities stay fixed. */
 export declare function appSurfaceCache(host: Pick<OysterHost, "artifacts" | "capabilities">): AppSurfaceCache;
 /** Derive the current principal's admitted App modules and grants. */
-export declare function oysterAppSnapshot(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys">, surfaces: AppSurfaceCache, principal: OysterPrincipal, installations: readonly Installation[], access: OysterCallerAccess, sessionId?: string, 
-/** Shares one tool-family listing per Instance across the two
- * `appModules` passes one `oysterAppMethods` call can make (the eager
- * grants/version pass, and a session-scoped re-derivation); never shared
- * across separate calls, so it never serves another request's listing. */
-familyListingCache?: Map<string, unknown>): Promise<Readonly<{
+export declare function oysterAppSnapshot(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys" | "approvals">, surfaces: AppSurfaceCache, principal: TenantPrincipal, installations: readonly Installation[], access: OysterCallerAccess, sessionId: string | null, mode: "direct" | "approval"): Promise<Readonly<{
     modules: Readonly<Record<string, ModuleRegistration>>;
     levels: Readonly<Record<string, AppToolPolicy["level"]>>;
     fences: Readonly<Record<string, string>>;
@@ -208,14 +197,13 @@ familyListingCache?: Map<string, unknown>): Promise<Readonly<{
 /**
  * Capture installed App methods for MCP or agents as one principal-scoped source.
  * Enabled installations become `env.<APP>` modules using the Instance call path; a dotted method such as `repos.list` is `env.<APP>.repos.list()`.
- * Visitors see only public read methods; owners see every discoverable
- * method. A key sees only the installations its own grants admit, each at
+ * Owners see every discoverable method. A key sees only the installations its own grants admit, each at
  * the level (`read`/`write`) those grants give it; Mycelium itself refuses a
  * write call up front when the module's own grant is `read`
  * (`mycelium/src/access.ts`). Call again to capture changes to Releases,
  * installation authority or the caller's own grants.
  */
-export declare function oysterAppMethods(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys" | "approvals">, principal: OysterPrincipal, access: OysterCallerAccess, surfaces: AppSurfaceCache, preloadedInstallations?: readonly Installation[]): Promise<CapabilitySource & {
+export declare function oysterAppMethods(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys" | "approvals">, principal: TenantPrincipal, access: OysterCallerAccess, surfaces: AppSurfaceCache, preloadedInstallations?: readonly Installation[]): Promise<CapabilitySource & {
     readonly grants: Grants;
 }>;
 /**
@@ -224,7 +212,7 @@ export declare function oysterAppMethods(host: Pick<OysterHost, "installations"
  * still checks its host-issued grant on every call. Null when the host has no
  * Computer or the caller has no access. Grants name the captured module.
  */
-export declare function oysterComputerTools(host: Pick<OysterHost, "computerId" | "computer">, principal: OysterPrincipal): Promise<(CapabilitySource & {
+export declare function oysterComputerTools(host: Pick<OysterHost, "computerId" | "computer">, principal: TenantPrincipal): Promise<(CapabilitySource & {
     readonly grants: Grants;
 }) | null>;
 /**