@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/mcp.d.ts

@@ -0,0 +1,89 @@
+import { type AppToolPolicy } from "./apps/tools.js";
+import type { DeclaredOperations, Installation } from "./apps/installation.js";
+import { type CapabilitySource, type Grants } from "@fungi.computer/mycelium";
+import { appToolSchemas } from "@fungi.computer/forage";
+import type { OysterHost, OysterPrincipal } from "./host.js";
+import type { McpPrincipal, McpCatalogSnapshot } from "@fungi.computer/mycelium/mcp";
+import { type VerifiedRelease } from "./release.js";
+/** An installation ID as a guest binding name: `spawn-git` becomes `SPAWN_GIT`. */
+export declare function appBindingName(installationId: string): string;
+/** Why an App method call from the MCP catalog was refused. */
+export declare class AppMethodRefused extends Error {
+    readonly code: string;
+    readonly name = "AppMethodRefused";
+    /** `detail` is the App's own caller-facing refusal message, when it gave one. */
+    constructor(code: string, detail?: string);
+}
+/**
+ * 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
+ * no grant for is captured as absent, never merely refused, so it is never
+ * listed at all.
+ */
+export type OysterCallerAccess = Readonly<{
+    kind: "agent";
+    policy: AppToolPolicy;
+}> | Readonly<{
+    kind: "key";
+    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. */
+export type ReleaseSurface = Readonly<{
+    release: VerifiedRelease;
+    api: NonNullable<VerifiedRelease["api"]>;
+    declaredOperations: DeclaredOperations;
+    toolSchemas: ReturnType<typeof appToolSchemas>;
+}>;
+/**
+ * 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.
+ */
+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;
+/**
+ * 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
+ * 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">, principal: OysterPrincipal, access: OysterCallerAccess, surfaces: AppSurfaceCache, preloadedInstallations?: readonly Installation[]): Promise<CapabilitySource & {
+    readonly grants: Grants;
+}>;
+/**
+ * Capture the host's fixed Computer for one caller as a Knapsack source.
+ * The host decides whether the caller holds Computer access; the Computer
+ * owner accepts every call. Null when the host has no Computer or the caller
+ * has no access. Grants name exactly the one captured module.
+ */
+export declare function oysterComputerTools(host: Pick<OysterHost, "computerId" | "computer">, principal: OysterPrincipal): Promise<(CapabilitySource & {
+    readonly grants: Grants;
+}) | null>;
+/**
+ * Load the current catalog for an authenticated owner or key: installed App
+ * methods, plus the host's Computer when the caller holds Computer access.
+ * A key sees exactly the installations and levels its own grants admit, and
+ * the Computer only with its own `computer.use` grant; each App retains its
+ * own caller checks regardless. The owner's stored write approval of an
+ * Agent's App tools is that principal's confirmation for App writes, so a
+ * headless client can write; the shared MCP server asks the client to
+ * approve every other write (an owner's own calls, the Computer). Each call
+ * still re-admits the key, rechecks that same stored approval, and passes
+ * the App's gate.
+ */
+export declare function oysterMcpCatalogLoad(host: Pick<OysterHost, "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "computer" | "capabilities" | "appToolPolicy" | "keys">): (principal: McpPrincipal) => Promise<McpCatalogSnapshot>;

package/dist/mcp.js

@@ -0,0 +1,429 @@
+import { admits } from "./apps/gate.js";
+import { causeClass } from "./cause-class.js";
+import { deriveDeclaredOperations } from "./apps/operations.js";
+import { appToolPolicySchema } from "./apps/tools.js";
+import { emptyAppDeclaration } from "@fungi.computer/puffball/app";
+import { admittedMethodCallerFacts, invocationCallerContext, } from "./invocation.js";
+import { guestLimits } from "./guest-policy.js";
+import { Mycelium, } from "@fungi.computer/mycelium";
+import { appToolSchemas, appToolFamilySchemas } from "@fungi.computer/forage";
+import { Knapsack } from "@fungi.computer/knapsack";
+import * as Schema from "effect/Schema";
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+import { keyAppAccess } from "./keys.js";
+import { defaultAssetPolicy, sha256, verifyRelease, } from "./release.js";
+/** Mints the requestId a tool family tool sends on the caller's behalf to its
+ * declared `call` method: each MCP call is its own independent run, never a
+ * replay the caller controls. */
+const toolFamilyCallIds = defineIdFamily({
+    family: "oyster-tool-family-call",
+    version: 1,
+    kinds: { call: { prefix: "call" } },
+});
+/** An installation ID as a guest binding name: `spawn-git` becomes `SPAWN_GIT`. */
+export function appBindingName(installationId) {
+    return installationId.replace(/[^A-Za-z0-9]+/gu, "_").toUpperCase();
+}
+/** Why an App method call from the MCP catalog was refused. */
+export class AppMethodRefused extends Error {
+    code;
+    name = "AppMethodRefused";
+    /** `detail` is the App's own caller-facing refusal message, when it gave one. */
+    constructor(code, detail) {
+        super(detail === undefined
+            ? `App method refused: ${code}`
+            : `App method refused: ${code}: ${detail}`);
+        this.code = code;
+    }
+}
+function capturedAccessFor(access, installationId) {
+    if (access === null)
+        return null;
+    return access.kind === "agent"
+        ? access.policy
+        : (access.byInstallation.get(installationId) ?? null);
+}
+/** Re-read one actor's current App-tool access for one installation, fresh. */
+async function freshAccessFor(host, actor, installationId) {
+    if (actor.kind === "agent")
+        return (await host.appToolPolicy?.(actor)) ?? null;
+    const key = (await host.keys?.live(actor.keyId)) ?? null;
+    return key === null ? null : keyAppAccess(key, installationId);
+}
+/** Make one {@link AppSurfaceCache} for a host whose artifact store and capabilities stay fixed. */
+export function appSurfaceCache(host) {
+    const surfaces = new Map();
+    const build = async (installed) => {
+        const release = await verifyRelease(host.artifacts, installed, defaultAssetPolicy, false);
+        if (release.api === null)
+            return null;
+        return {
+            release,
+            api: release.api,
+            declaredOperations: await deriveDeclaredOperations(installed, release.declaration ?? emptyAppDeclaration, host.capabilities ?? []),
+            toolSchemas: appToolSchemas(release.api),
+        };
+    };
+    return (installed) => {
+        const key = `${installed.releaseId}:${installed.artifact.artifactDigest}`;
+        let entry = surfaces.get(key);
+        if (entry === undefined) {
+            entry = build(installed).catch((cause) => {
+                surfaces.delete(key);
+                throw cause;
+            });
+            surfaces.set(key, entry);
+        }
+        return entry;
+    };
+}
+async function appModules(host, surfaces, principal, installations, access, sessionId, 
+/** 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 = new Map()) {
+    const limits = guestLimits(host.guestLimits);
+    const caller = invocationCallerContext(principal, host.computerId ?? null);
+    const { actor } = principal;
+    const visitor = actor.kind === "visitor";
+    const modules = {};
+    const levels = {};
+    for (const installation of installations) {
+        if (installation.status !== "enabled" || installation.instanceId === null)
+            continue;
+        if (visitor && installation.visibility !== "public")
+            continue;
+        const captured = capturedAccessFor(access, installation.installationId);
+        // A key that holds no grant for this installation never sees it listed
+        // at all. An Agent's one blanket policy either covers every
+        // installation or none, so this never hides one from an Agent; an
+        // unapproved Agent still sees the list, refused at call time, as today.
+        if (access?.kind === "key" && captured === null)
+            continue;
+        const surface = await surfaces(installation.release);
+        if (surface === null)
+            continue;
+        const { release, api, declaredOperations, toolSchemas } = surface;
+        const instanceId = installation.instanceId;
+        const declaration = release.declaration ?? emptyAppDeclaration;
+        const id = `oyster-app:${installation.installationId}`;
+        // A member/owner/visitor, or an Agent/key with no captured access,
+        // defaults to "write" here exactly as every module always did before:
+        // the deeper gate (`admits`), not this coarse Mycelium-level grant, is
+        // what actually enforces visitor/role ceilings. Only a captured
+        // Agent/key access with its own level narrows this.
+        levels[id] = captured?.level ?? "write";
+        // Shared by every operation this installation exposes (ordinary methods
+        // and, below, a tool family's dynamic per-row tools): the same staleness
+        // check, the same owner-approved policy check, the same `admits` gate and
+        // the same Instance call. A tool family tool is sugar over this same
+        // admitted call to its declared `call` method; it gets no separate check.
+        const callAppMethod = async (name, effect, input, signal) => {
+            signal?.throwIfAborted();
+            const currentInstallation = await host.installations.get(installation.installationId);
+            signal?.throwIfAborted();
+            if (currentInstallation?.status !== "enabled" ||
+                currentInstallation.instanceId !== instanceId ||
+                currentInstallation.authorityVersion !==
+                    installation.authorityVersion ||
+                currentInstallation.release.releaseId !==
+                    installation.release.releaseId ||
+                currentInstallation.release.artifact.artifactDigest !==
+                    installation.release.artifact.artifactDigest)
+                throw new AppMethodRefused("stale_authority");
+            if (actor.kind === "agent" || actor.kind === "team-key") {
+                const fresh = Schema.decodeUnknownOption(appToolPolicySchema, {
+                    onExcessProperty: "error",
+                })(await freshAccessFor(host, actor, installation.installationId));
+                const capturedParsed = Schema.decodeUnknownOption(appToolPolicySchema, {
+                    onExcessProperty: "error",
+                })(captured);
+                // A call never pre-approved in the first place (no captured
+                // policy) is `not_approved`; one that WAS approved but whose
+                // authority has since changed or vanished entirely -- a key
+                // revoked or expired after capture, say -- is `stale_authority`,
+                // just like the other authority drift below. Only the absence
+                // of a captured policy gets the former code.
+                if (capturedParsed._tag === "None")
+                    throw new AppMethodRefused("not_approved");
+                if (fresh._tag === "None" ||
+                    fresh.value.revision !== capturedParsed.value.revision ||
+                    fresh.value.grantedBy !== capturedParsed.value.grantedBy ||
+                    fresh.value.level !== capturedParsed.value.level)
+                    throw new AppMethodRefused("stale_authority");
+            }
+            signal?.throwIfAborted();
+            const json = Schema.decodeUnknownSync(Schema.Json)(input);
+            const decision = admits({
+                installation,
+                declaration,
+                declaredOperations,
+                api,
+                principal: {
+                    actor,
+                    role: "role" in principal ? principal.role : null,
+                },
+                access: captured === null
+                    ? null
+                    : {
+                        level: captured.level,
+                        revision: captured.revision,
+                        grantedBy: captured.grantedBy,
+                        bindingName: appBindingName(installation.installationId),
+                    },
+            }, { kind: "method", name, input: json, via: "mcp" });
+            if (decision.kind === "refused")
+                throw new AppMethodRefused(decision.code);
+            const result = await host.instances.get(instanceId, limits).call(await admittedMethodCallerFacts(host, installation, release, caller, decision.grants, { name, effect }, [], sessionId, actor.kind === "agent" && captured !== null
+                ? {
+                    policyRevision: captured.revision,
+                    grantorMemberId: captured.grantedBy,
+                }
+                : undefined), api, name, json);
+            if (!result.ok)
+                throw new AppMethodRefused(result.code);
+            if (result.value.kind === "refused")
+                throw new AppMethodRefused(result.value.code, result.value.message);
+            return result.value.value;
+        };
+        const toolOperations = Object.entries(toolSchemas)
+            .filter(([, method]) => !visitor || method.effect === "read")
+            .map(([name, method]) => {
+            const appMethod = Mycelium.operation({
+                replay: "unsafe",
+                access: method.effect === "read" ? "read" : "write",
+                description: `${method.description}\nEffect: ${method.effect}.`,
+                input: method.input,
+                output: method.output,
+                execute: async (input, context) => {
+                    const value = await callAppMethod(name, method.effect, input, context.signal);
+                    return method.output.parse(value);
+                },
+            });
+            return [name, appMethod];
+        });
+        // A tool family publishes a dynamic, signed set of typed tools from one
+        // App (e.g. each published Workflow becomes its own tool). forage decodes
+        // that listing and compiles its schemas; it supplies no admission or
+        // invocation arguments by design, so the host supplies both here, reusing
+        // the exact same `callAppMethod` gate as every other method on this App.
+        // A visitor who cannot see non-read ordinary methods cannot see these
+        // either; a caller the App itself refuses to list for (stale authority,
+        // an unapproved App-tool policy, a missing capability grant) sees none.
+        const family = api.toolFamily;
+        const familyOperations = family === undefined ||
+            (visitor && api.methods[family.call]?.effect !== "read")
+            ? []
+            : await (async () => {
+                try {
+                    let listing = familyListingCache.get(instanceId);
+                    if (listing === undefined) {
+                        listing = await callAppMethod(family.list, "read", {});
+                        familyListingCache.set(instanceId, listing);
+                    }
+                    const compiled = appToolFamilySchemas(api, listing);
+                    if (compiled === null)
+                        return [];
+                    return compiled.tools.map((tool) => {
+                        const operation = Mycelium.operation({
+                            replay: "unsafe",
+                            access: compiled.effect === "read" ? "read" : "write",
+                            description: `${tool.description}\nEffect: ${compiled.effect}.`,
+                            input: tool.input,
+                            output: tool.output,
+                            execute: async (input, context) => {
+                                // The declaring App owns every field below except
+                                // `requestId` (this call's own identity) and `input`
+                                // (the caller's tool-shaped payload): `tool.row.call` is
+                                // opaque data this host never reads into or defaults.
+                                // `requestId` is last: a row whose own `call` data named
+                                // that key would otherwise replay the same run forever.
+                                const value = await callAppMethod(compiled.call, compiled.effect, {
+                                    ...tool.row.call,
+                                    input,
+                                    requestId: toolFamilyCallIds.call.generate(),
+                                }, context.signal);
+                                return tool.output.parse(value);
+                            },
+                        });
+                        return [
+                            `${compiled.name}.${tool.row.tool}`,
+                            operation,
+                        ];
+                    });
+                }
+                catch (error) {
+                    // One App's bad listing -- a refused or throwing Instance
+                    // call, or a reply forage's signed-listing codec rejects --
+                    // withholds only this App's family tools. Every other App's
+                    // ordinary and family operations are built independently and
+                    // stay unaffected; the whole catalog build never aborts for it.
+                    // An ordinary closed refusal (the same gate any App method
+                    // already produces) stays quiet; anything else is reported
+                    // exactly like any other AppInstance failure.
+                    if (!(error instanceof AppMethodRefused) ||
+                        error.code === "failed")
+                        console.error("AppInstance failure", {
+                            stage: "tool_family_listing",
+                            installationId: installation.installationId,
+                            causeClass: error instanceof AppMethodRefused
+                                ? "Refused"
+                                : causeClass(error),
+                        });
+                    return [];
+                }
+            })();
+        modules[id] = Mycelium.module({
+            id,
+            name: appBindingName(installation.installationId),
+            description: release.declaration?.displayName ?? installation.installationId,
+            operations: Object.fromEntries([...toolOperations, ...familyOperations]),
+        });
+    }
+    return { modules, levels };
+}
+function serializableAccess(access) {
+    return access === null || access.kind === "agent"
+        ? access
+        : {
+            kind: access.kind,
+            keyId: access.keyId,
+            byInstallation: [...access.byInstallation.entries()].sort(([left], [right]) => left.localeCompare(right)),
+        };
+}
+/**
+ * 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
+ * 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 async function oysterAppMethods(host, principal, access, surfaces, preloadedInstallations) {
+    const installations = preloadedInstallations ?? (await host.installations.list());
+    // Shared so a session-scoped re-derivation below reuses this call's tool-
+    // family listings instead of asking each Instance for them twice.
+    const familyListingCache = new Map();
+    const { modules: entries, levels } = await appModules(host, surfaces, principal, installations, access, undefined, familyListingCache);
+    const modules = Object.values(entries);
+    const version = await sha256(new TextEncoder().encode(JSON.stringify({
+        access: serializableAccess(access),
+        installations: [...installations]
+            .sort((a, b) => a.installationId.localeCompare(b.installationId))
+            .map((installation) => [
+            installation.installationId,
+            installation.instanceId,
+            installation.release.releaseId,
+            installation.release.artifact.artifactDigest,
+            installation.authorityVersion,
+            installation.status,
+            installation.visibility,
+        ]),
+    })));
+    return {
+        id: "oyster-apps",
+        grants: levels,
+        acquire: async ({ signal, session }) => {
+            signal.throwIfAborted();
+            const acquiredModules = session === undefined
+                ? modules
+                : Object.values((await appModules(host, surfaces, principal, installations, access, session.sessionId, familyListingCache)).modules);
+            signal.throwIfAborted();
+            return {
+                snapshot: { version, modules: acquiredModules },
+                release: () => Promise.resolve(),
+            };
+        },
+    };
+}
+/**
+ * Capture the host's fixed Computer for one caller as a Knapsack source.
+ * The host decides whether the caller holds Computer access; the Computer
+ * owner accepts every call. Null when the host has no Computer or the caller
+ * has no access. Grants name exactly the one captured module.
+ */
+export async function oysterComputerTools(host, principal) {
+    if (host.computerId === undefined || host.computer === undefined)
+        return null;
+    const computer = await host.computer(principal);
+    if (computer === null)
+        return null;
+    const id = `computer:${host.computerId}`;
+    return {
+        ...Knapsack.computer({
+            id,
+            name: "workspace",
+            namespace: ["computers"],
+            computer,
+        }),
+        grants: { [id]: "write" },
+    };
+}
+/**
+ * Load the current catalog for an authenticated owner or key: installed App
+ * methods, plus the host's Computer when the caller holds Computer access.
+ * A key sees exactly the installations and levels its own grants admit, and
+ * the Computer only with its own `computer.use` grant; each App retains its
+ * own caller checks regardless. The owner's stored write approval of an
+ * Agent's App tools is that principal's confirmation for App writes, so a
+ * headless client can write; the shared MCP server asks the client to
+ * approve every other write (an owner's own calls, the Computer). Each call
+ * still re-admits the key, rechecks that same stored approval, and passes
+ * the App's gate.
+ */
+export function oysterMcpCatalogLoad(host) {
+    const surfaces = appSurfaceCache(host);
+    return async (principal) => {
+        const { actor } = principal;
+        // One read of the installation list serves both a key's grant check
+        // below and oysterAppMethods' own capture, instead of two.
+        const installations = await host.installations.list();
+        let access = null;
+        if (actor.kind === "agent") {
+            const policy = (await host.appToolPolicy?.(actor)) ?? null;
+            access = policy === null ? null : { kind: "agent", policy };
+        }
+        else if (actor.kind === "team-key") {
+            // Always a "key" access, even an empty one for an unknown, revoked,
+            // expired or suspended key: that keeps every installation invisible
+            // (via appModules' own `access?.kind === "key"` check) rather than
+            // falling through to the member/owner default of "write" below.
+            const key = (await host.keys?.live(actor.keyId)) ?? null;
+            const byInstallation = new Map();
+            if (key !== null)
+                for (const installation of installations) {
+                    const level = keyAppAccess(key, installation.installationId);
+                    if (level !== null)
+                        byInstallation.set(installation.installationId, level);
+                }
+            access = { kind: "key", keyId: actor.keyId, byInstallation };
+        }
+        const apps = await oysterAppMethods(host, principal, access, surfaces, installations);
+        // Pre-approval ("never asked") is what a captured Agent/key policy
+        // itself grants; an owner's own calls, or an Agent/key with none, are
+        // never pre-approved even though their modules still default to the
+        // coarse "write" ceiling above.
+        const approvedWrites = access === null
+            ? []
+            : Object.entries(apps.grants)
+                .filter(([, level]) => level === "write")
+                .map(([id]) => id);
+        const computer = await oysterComputerTools(host, principal);
+        if (computer === null)
+            return {
+                instructions: "Installed Apps on this Oyster. Each App is env.<APP>; dotted method names are nested properties, e.g. env.BONSAI.repos.list({}). Use forage.search / forage.describe to find methods.",
+                grants: apps.grants,
+                approvedWrites,
+                sources: [apps],
+            };
+        return {
+            instructions: 'Installed Apps and this Oyster\'s Computer. Each App is env.<APP>; dotted method names are nested properties, e.g. env.BONSAI.repos.list({}). The Computer is env.computers.workspace, e.g. env.computers.workspace.exec({command: "ls"}). Use forage.search / forage.describe to find methods.',
+            grants: { ...apps.grants, ...computer.grants },
+            approvedWrites,
+            sources: [apps, computer],
+        };
+    };
+}

package/dist/media.d.ts

@@ -0,0 +1,23 @@
+/** Media slot supplied by the host; Oyster owns routing, never generation. */
+export declare const mediaSlot: {
+    readonly id: "media.generation";
+    readonly version: number;
+    readonly base: "/media/";
+    readonly methods: {
+        readonly describe: {
+            readonly kind: "json";
+            readonly method: "GET";
+            readonly path: "describe";
+        };
+        readonly generate: {
+            readonly kind: "json";
+            readonly method: "POST";
+            readonly path: "generate";
+        };
+        readonly cancelAttempt: {
+            readonly kind: "json";
+            readonly method: "POST";
+            readonly path: "cancel-attempt";
+        };
+    };
+};

package/dist/media.js

@@ -0,0 +1,12 @@
+import { mediaGeneration } from "@fungi.computer/agar/media";
+/** Media slot supplied by the host; Oyster owns routing, never generation. */
+export const mediaSlot = {
+    id: "media.generation",
+    version: mediaGeneration.version,
+    base: "/media/",
+    methods: {
+        describe: { kind: "json", method: "GET", path: "describe" },
+        generate: { kind: "json", method: "POST", path: "generate" },
+        cancelAttempt: { kind: "json", method: "POST", path: "cancel-attempt" },
+    },
+};

package/dist/pack.d.ts

@@ -0,0 +1,76 @@
+import { type ArtifactRef, type Release } from "@fungi.computer/puffball";
+import { type AppPublisherCoreConfigInput } from "./build.js";
+/** One committed repository and its canonical App build recipe. */
+export type PackOptions = Readonly<{
+    /** The App's ID, `app_<name>`. */
+    appId: string;
+    /** The Release ID; defaults to `rel_<commit prefix>`. */
+    releaseId?: string;
+    /** Repository root; all recipe paths are relative to this captured root. */
+    sourceDirectory: string;
+    /** Exact committed source, `git:<full commit SHA>`; dirty files are not inputs. */
+    sourceRevision: string;
+    /** The same pinned recipe input accepted by `oyster/build`. */
+    recipe: AppPublisherCoreConfigInput["recipe"];
+    /** Optional local pnpm content store used by the captured source compiler. */
+    packageStoreDirectory?: string;
+    /** Where to write `release.json` and the immutable `artifacts/` directory. */
+    outDirectory: string;
+}>;
+/** A packed Release on disk. */
+export type PackedRelease = Readonly<{
+    release: Release;
+    /** Every artifact file by reference. */
+    artifacts: readonly Readonly<{
+        artifactRef: ArtifactRef;
+        path: string;
+    }>[];
+}>;
+/** Build an exact local Git commit with the canonical compiler and artifact writer. */
+export declare function packRelease(options: PackOptions): Promise<PackedRelease>;
+/**
+ * Capture an Artifacts Git commit, build its Release, upload it to an Oyster,
+ * and install it, or switch an existing installation to it
+ * ({@link installRelease}).
+ */
+export declare function installFromSource(input: Readonly<{
+    appId: string;
+    releaseId?: string;
+    recipe: PackOptions["recipe"];
+    /** Credential-free trusted Artifacts Git URL and its exact committed source. */
+    source: Readonly<{
+        remote: string;
+        token: string;
+        sourceRevision: string;
+    }>;
+    packageStoreDirectory?: string;
+    /** Destination Oyster origin. */
+    url: string;
+    /** Destination Oyster owner key; distinct from the source Git credential. */
+    key: string;
+    installationId: string;
+}>): Promise<Response>;
+/**
+ * Upload a packed Release to an Oyster and install it. The host installs a
+ * new installation (201) or switches an existing one to this Release (200),
+ * keeping its state; both go through its one install-or-select owner.
+ */
+export declare function installRelease(input: Readonly<{
+    directory: string;
+    url: string;
+    /** The Oyster owner key. */
+    key: string;
+    installationId?: string;
+}>): Promise<Response>;
+/** Project one exact first-party commit's editable source and seed it into
+ * an Oyster's own template, so `APPS.fork` can later fork it. The operator
+ * owner key authenticates; no provider credential ever leaves this call. */
+export declare function publishSource(input: Readonly<{
+    appId: string;
+    entry: string;
+    repositoryPath: string;
+    sourceRevision: string;
+    recipe: PackOptions["recipe"];
+    url: string;
+    key: string;
+}>): Promise<Response>;