@fungi.computer/oyster 0.6.0 → 0.7.0

package/dist/invocation.js

@@ -114,8 +114,6 @@ export async function admitBackgroundFrame(key, frame, raw) {
     frame.host.origin = decision.kind;
     return decision;
 }
-/** Foreground reads one Instance runs at once; every other frame runs alone. */
-const concurrentReadFrames = 8;
 const frameIds = defineIdFamily({
     family: "app-invocation-frame",
     version: 1,
@@ -152,6 +150,7 @@ function immutableFacts(facts) {
     Object.freeze(facts.ancestry);
     return Object.freeze(facts);
 }
+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.
@@ -160,15 +159,18 @@ function orderedPermits(total) {
     let available = total;
     const waiting = [];
     const admit = () => {
-        for (let next = waiting[0]; next !== undefined && next.permits <= available; next = waiting[0]) {
+        for (let next = waiting[0]; next !== undefined; next = waiting[0]) {
+            const count = next.requested();
+            if (count > available)
+                break;
             waiting.shift();
-            available -= next.permits;
-            next.enter();
+            available -= count;
+            next.enter(count);
         }
     };
-    return async (permits, work) => {
-        await new Promise((enter) => {
-            waiting.push({ permits, enter });
+    return async (requested, work) => {
+        const permits = await new Promise((enter) => {
+            waiting.push({ requested, enter });
             admit();
         });
         try {
@@ -185,31 +187,63 @@ function orderedPermits(total) {
         }
     };
 }
-/** A foreground call to a verified read method; only these share the guest. */
+/** 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");
 }
 /**
- * Admit frames against one guest. Verified foreground reads share it, up to
- * eight at once; writes, raw backend requests, Gills and replay run alone. Every guest binding packet names its frame, so a finished
- * frame's leftover timers cannot borrow a later frame's authority and a
- * normal finish keeps the guest warm. Closing authority early (revocation,
- * expiry, a write preempting replay) aborts the guest and so every frame
- * sharing it; replay only yields to a verified write.
+ * 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 withPermits = orderedPermits(concurrentReadFrames);
+    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;
     const live = new Map();
     const finish = (state, reason) => {
         if (state.closing)
             return state.closing;
-        live.delete(state.frame.frameId);
         state.controller.abort(reason);
-        state.closing = 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
@@ -220,7 +254,7 @@ export function createInvocationGate(ports) {
             live.delete(state.frame.frameId);
             state.controller.abort(reason);
         }
-        const guest = ports.abortGuest();
+        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);
@@ -250,7 +284,7 @@ export function createInvocationGate(ports) {
                 [...live.values()].some(({ frame }) => frame.facts.subject.kind === "call" &&
                     frame.facts.subject.replay !== undefined))
                 await abortAll(new AppInstanceError("revoked"));
-            return await withPermits(concurrentRead(facts) ? 1 : concurrentReadFrames, async () => {
+            return await withPermits(concurrentRead(facts), async () => {
                 if (facts.subject.kind === "call" &&
                     facts.subject.replay !== undefined &&
                     foregroundWaiting > 0)
@@ -271,6 +305,7 @@ export function createInvocationGate(ports) {
                     signal: controller.signal,
                 });
                 const state = { frame, controller };
+                cohortDeadlineAt ??= deadlineAt;
                 live.set(frameId, state);
                 let timer;
                 let stop = () => undefined;
@@ -312,7 +347,7 @@ export function createInvocationGate(ports) {
     };
     return {
         run,
-        exclusive: (work) => withPermits(concurrentReadFrames, work),
+        exclusive: (work) => withPermits(false, work),
         active: (frameId) => {
             const state = live.get(frameId);
             if (state === undefined ||
@@ -331,14 +366,11 @@ export function createInvocationGate(ports) {
 }
 /**
  * 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>;
 /**