@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/agents.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Agents for Apps on a standalone Oyster: one adapter shape and the routes
+ * the App page calls. Apps reach agents through Agar's `agent.list`,
+ * `agent.manage`, `agent.read` and `agent.send` contracts, so an App written
+ * for the Hub (Grove) runs unchanged. Each agent's own transport is
+ * Shiitake's HTTP routes (`/sessions…`, `/acp`), served by the adapter.
+ */
+import { Hono } from "hono";
+import type { AppToolPolicy } from "./apps/tools.js";
+import * as Schema from "effect/Schema";
+import { type OysterCapability, type OysterEnv, type OysterPrincipal } from "./host.js";
+import type { HostActor } from "@fungi.computer/puffball/app";
+import type { MemberInboxItem, MemberInboxSession } from "@fungi.computer/puffball/inbox";
+/** One agent as Apps see it, in Agar's `appAgentSchema` shape. */
+export type OysterAgent = Readonly<{
+    agentId: string;
+    name: string;
+    sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
+}>;
+/** An Agent owner's Session facts before the member identity and visit are added. */
+export type OysterSessionRow = Omit<Extract<MemberInboxSession, {
+    title: string;
+}>, "agentId" | "visitedAt"> | Omit<Extract<MemberInboxSession, {
+    state: "unavailable";
+}>, "agentId">;
+/** Both hosts expose the same Inbox item vocabulary. */
+export type OysterInboxItem = MemberInboxItem;
+/** The whole inbox at one revision; the revision only grows. */
+export type OysterInbox = Readonly<{
+    items: readonly OysterInboxItem[];
+    revision: number;
+}>;
+/** Host-attested source of a policy request; request headers are not this fact. */
+export type AgentPolicyActor = "owner-direct" | Readonly<{
+    installationId: string;
+}>;
+/** An App's requested tools await the owner's direct approval. */
+export type PendingAgentPolicy = Readonly<{
+    status: "pending";
+    revision: string;
+}>;
+/** One remote MCP server connected to an Agent; its bearer token is never returned. */
+export type AgentMcpServer = Readonly<{
+    serverId: string;
+    /** The guest calls this server's tools as `env.mcp.<name>.<tool>()`. */
+    name: string;
+    url: string;
+    hasBearer: boolean;
+}>;
+/** An owner's request to connect one remote MCP server to an Agent. */
+export type AgentMcpServerInput = typeof agentMcpServerInputSchema.Type;
+/** Why connecting an MCP server was refused. */
+export type AgentMcpServerRefusal = Readonly<{
+    error: "not_found" | "duplicate_name" | "limit";
+}>;
+/** At most this many MCP servers per Agent. */
+export declare const maxAgentMcpServers = 16;
+/** Owner input for one MCP server: a guest identifier, an `https:` endpoint and an optional bearer. */
+export declare const agentMcpServerInputSchema: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly url: Schema.String;
+    readonly bearer: Schema.NullOr<Schema.String>;
+}>;
+/** This Agent's App-tool policy, in the shape Apps read it. */
+export type AgentToolPolicyStatus = Readonly<{
+    status: "pending" | "approved";
+    revision: string;
+}>;
+/** Where an Oyster's agents live and run. */
+export type OysterAgents = Readonly<{
+    /** Every agent, oldest first. */
+    list(): Promise<readonly OysterAgent[]>;
+    /** Create an agent; retrying with the same `requestId` returns the same one. */
+    create(name: string, requestId: string, principal: OysterPrincipal, actor: AgentPolicyActor): Promise<OysterAgent>;
+    /** Owner-only rename; refuses a name already held by another Agent. */
+    rename(agentId: string, name: string, principal: OysterPrincipal): Promise<OysterAgent | Readonly<{
+        error: "not_found" | "name_taken" | "not_granted";
+    }>>;
+    /** This Agent's App-tool policy status, or `null` for no such Agent. */
+    policyStatus(agentId: string): Promise<AgentToolPolicyStatus | null>;
+    /** Read this Agent's stored App-tool approval; absence requires re-approval. A key's App access is its own grants (Ear Tag), not this policy. */
+    appToolPolicy(actor: Extract<HostActor, {
+        kind: "agent";
+    }>): Promise<AppToolPolicy | null>;
+    /** Read the current revision for direct owner approval. */
+    policyRevision(agentId: string): Promise<string | null>;
+    /** Replace an Agent's tool approval under its authenticated attaching human. */
+    approveAppToolPolicy(agentId: string, principal: OysterPrincipal, level: AppToolPolicy["level"], expectedRevision: string | null, actor: AgentPolicyActor): Promise<AppToolPolicy | PendingAgentPolicy | Readonly<{
+        error: "not_found" | "revision_conflict" | "not_granted";
+    }>>;
+    /** An Agent's connected MCP servers, or `null` when there is no such Agent. */
+    mcpServers(agentId: string): Promise<readonly AgentMcpServer[] | null>;
+    /** Connect one remote MCP server; the Agent's next run sees its tools. */
+    addMcpServer(agentId: string, input: AgentMcpServerInput): Promise<AgentMcpServer | AgentMcpServerRefusal>;
+    /** Disconnect one MCP server; `false` when the Agent or server is unknown. */
+    removeMcpServer(agentId: string, serverId: string): Promise<boolean>;
+    /** Serve one Shiitake transport request (`/sessions…`, `/acp`) for an agent. */
+    fetch(agentId: string, request: Request): Promise<Response | null>;
+    /** This member's Session and Workflow review rows, admitted by the host. */
+    inbox(): Promise<OysterInbox>;
+    /** Current inbox revision without enumerating Session rows. */
+    revision(): Promise<number>;
+    /** Record that the member opened a Session. */
+    visit(agentId: string, sessionId: string): Promise<boolean>;
+}>;
+/** Agent adapters admitted against each App's declared capabilities. */
+export declare function agentCapabilities(agents: OysterAgents): readonly OysterCapability[];
+/** Host-owned direct approval under the admitted owner; never an App capability. */
+export declare function agentApprovalRoutes(agents: OysterAgents): Hono<OysterEnv>;
+/**
+ * Host-owned Agent MCP server custody for the owner directly; never an App
+ * capability. Bearer tokens go in and never come back out.
+ */
+export declare function agentMcpServerRoutes(agents: OysterAgents): Hono<OysterEnv>;

package/dist/agents.js

@@ -0,0 +1,322 @@
+/**
+ * Agents for Apps on a standalone Oyster: one adapter shape and the routes
+ * the App page calls. Apps reach agents through Agar's `agent.list`,
+ * `agent.manage`, `agent.read` and `agent.send` contracts, so an App written
+ * for the Hub (Grove) runs unchanged. Each agent's own transport is
+ * Shiitake's HTTP routes (`/sessions…`, `/acp`), served by the adapter.
+ */
+import { Hono } from "hono";
+import * as Schema from "effect/Schema";
+import { oysterPrincipalIsOwner, } from "./host.js";
+import { agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, } from "@fungi.computer/agar/agents";
+/** At most this many MCP servers per Agent. */
+export const maxAgentMcpServers = 16;
+/** Owner input for one MCP server: a guest identifier, an `https:` endpoint and an optional bearer. */
+export const agentMcpServerInputSchema = Schema.Struct({
+    name: Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9_]{0,31}$/u)),
+    url: Schema.String.check(Schema.isMaxLength(2_048), Schema.makeFilter((value) => {
+        if (!URL.canParse(value))
+            return "Use an https:// MCP endpoint";
+        const url = new URL(value);
+        return url.protocol === "https:" &&
+            url.username === "" &&
+            url.password === "" &&
+            url.hash === ""
+            ? undefined
+            : "Use an https:// MCP endpoint without credentials or a fragment";
+    })),
+    bearer: Schema.NullOr(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(4_096), Schema.isPattern(/^[\x21-\x7e]+$/u))),
+});
+const createSchema = Schema.Struct({
+    name: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256)),
+    requestId: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_.:-]{1,256}$/u)),
+});
+const renameSchema = Schema.Struct({
+    name: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256)),
+});
+const visitSchema = Schema.Struct({
+    agentId: Schema.String,
+    sessionId: Schema.String,
+});
+const agentIdPattern = /^[a-z0-9_-]{1,64}$/u;
+/** How often an open inbox stream re-reads the revision. */
+const inboxPollMs = 2_000;
+const maxAgentRequestBytes = 512 * 1024;
+function refusal(status, error) {
+    return Response.json({ error }, { status });
+}
+/** Agent adapters admitted against each App's declared capabilities. */
+export function agentCapabilities(agents) {
+    const routes = createAgentRoutes(agents);
+    const shared = { base: "/", routes };
+    return [
+        {
+            ...shared,
+            id: "agent.list",
+            permission: "agent.list",
+            version: agentList.version,
+            methods: { list: { kind: "json", method: "GET", path: "agents" } },
+        },
+        {
+            ...shared,
+            id: "agent.manage",
+            permission: "agent.manage",
+            version: agentManage.version,
+            methods: {
+                create: { kind: "json", method: "POST", path: "agents" },
+                open: { kind: "transport", method: "ANY", path: "agents/:agentId" },
+            },
+        },
+        {
+            ...shared,
+            id: "agent.rename",
+            permission: "agent.rename",
+            version: agentRename.version,
+            methods: {
+                rename: { kind: "json", method: "PUT", path: "agent-names/:agentId" },
+            },
+        },
+        {
+            ...shared,
+            id: "agent.toolPolicy",
+            permission: "agent.toolPolicy",
+            version: agentToolPolicy.version,
+            methods: {
+                status: {
+                    kind: "json",
+                    method: "GET",
+                    path: "agent-policies/:agentId",
+                },
+                approve: {
+                    kind: "json",
+                    method: "PUT",
+                    path: "agent-policies/:agentId",
+                },
+            },
+        },
+        {
+            ...shared,
+            id: "agent.read",
+            permission: "agent.read",
+            version: agentSessionRead.version,
+            methods: {
+                open: { kind: "transport", method: "GET", path: "agents/:agentId" },
+                openInbox: { kind: "transport", method: "GET", path: "member" },
+            },
+        },
+        {
+            ...shared,
+            id: "agent.send",
+            permission: "agent.send",
+            version: agentSessionWrite.version,
+            methods: {
+                open: { kind: "transport", method: "ANY", path: "agents/:agentId" },
+                openInbox: { kind: "transport", method: "ANY", path: "member" },
+            },
+        },
+    ];
+}
+function createAgentRoutes(agents) {
+    const routes = new Hono();
+    routes.get("/agents", async () => Response.json(await agents.list()));
+    routes.post("/agents", async (context) => {
+        const { principal } = context.env;
+        if (!oysterPrincipalIsOwner(principal))
+            return refusal(403, "Only the owner creates agents");
+        const body = Schema.decodeUnknownOption(createSchema)(await context.req.json());
+        if (body._tag === "None")
+            return refusal(400, "Name the agent");
+        // The owner's own authenticated request creates this Agent; its App tools
+        // are approved the same way direct owner approval is, with no second path.
+        return Response.json(await agents.create(body.value.name, body.value.requestId, principal, "owner-direct"));
+    });
+    routes.put("/agent-names/:agentId", async (context) => {
+        const { principal } = context.env;
+        if (!oysterPrincipalIsOwner(principal))
+            return refusal(403, "Only the owner renames agents");
+        const agentId = context.req.param("agentId");
+        if (!agentIdPattern.test(agentId))
+            return refusal(404, "No such agent");
+        const body = Schema.decodeUnknownOption(renameSchema)(await context.req.json());
+        if (body._tag === "None")
+            return refusal(400, "Name the agent");
+        const result = await agents.rename(agentId, body.value.name, principal);
+        if ("error" in result)
+            return refusal(result.error === "not_found"
+                ? 404
+                : result.error === "name_taken"
+                    ? 409
+                    : 403, result.error);
+        return Response.json(result);
+    });
+    routes.get("/agent-policies/:agentId", async (context) => {
+        const agentId = context.req.param("agentId");
+        if (!agentIdPattern.test(agentId))
+            return refusal(404, "No such agent");
+        const status = await agents.policyStatus(agentId);
+        return status === null
+            ? refusal(404, "No such agent")
+            : Response.json(status);
+    });
+    routes.put("/agent-policies/:agentId", async (context) => approvePolicy(agents, context.env.principal, "owner-direct", context.req.param("agentId"), await context.req.text()));
+    routes.all("/agents/:agentId/*", async (context) => {
+        const agentId = context.req.param("agentId");
+        if (!agentIdPattern.test(agentId))
+            return refusal(404, "No such agent");
+        const incoming = context.req.raw;
+        const url = new URL(incoming.url);
+        const path = url.pathname.slice(`/agents/${agentId}`.length);
+        if (!(path === "/acp" ||
+            path === "/sessions" ||
+            path.startsWith("/sessions/")))
+            return refusal(404, "Not found");
+        const length = Number(incoming.headers.get("content-length") ?? "0");
+        if (length > maxAgentRequestBytes)
+            return refusal(413, "Request too large");
+        const target = new URL(`https://agent.internal${path}${url.search}`);
+        const response = await agents.fetch(agentId, new Request(target, incoming));
+        return response ?? refusal(404, "No such agent");
+    });
+    routes.get("/member/inbox", async () => {
+        const inbox = await agents.inbox();
+        return Response.json({
+            items: inbox.items,
+            next: null,
+            cursor: inbox.revision,
+        });
+    });
+    routes.get("/member/inbox/notices", () => Response.json({ items: [], next: null }));
+    routes.post("/member/inbox/visits", async (context) => {
+        const body = Schema.decodeUnknownOption(visitSchema)(await context.req.json());
+        if (body._tag === "None")
+            return refusal(400, "Invalid visit");
+        return (await agents.visit(body.value.agentId, body.value.sessionId))
+            ? new Response(null, { status: 204 })
+            : refusal(404, "No such Session");
+    });
+    // The feed is small (one person's agents), so a change is announced as a
+    // `reset` and the client re-reads the whole inbox.
+    routes.get("/member/inbox/events", (context) => {
+        const after = Number(context.req.query("after") ?? "0");
+        const signal = context.req.raw.signal;
+        const encoder = new TextEncoder();
+        let revision = after;
+        const stream = new ReadableStream({
+            async start(controller) {
+                controller.enqueue(encoder.encode(": open\n\n"));
+                while (!signal.aborted) {
+                    const current = await agents.revision();
+                    if (current !== revision) {
+                        revision = current;
+                        controller.enqueue(encoder.encode("event: reset\ndata: {}\n\n"));
+                    }
+                    else
+                        controller.enqueue(encoder.encode(": keep-alive\n\n"));
+                    await new Promise((resolve) => setTimeout(resolve, inboxPollMs));
+                }
+                controller.close();
+            },
+        });
+        return new Response(stream, {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-store",
+            },
+        });
+    });
+    return routes;
+}
+async function approvePolicy(agents, principal, actor, agentId, body) {
+    if (!oysterPrincipalIsOwner(principal))
+        return refusal(403, "Only the owner approves Agent tools");
+    const input = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Struct({
+        level: Schema.Literals(["read", "write"]),
+        expectedRevision: Schema.NullOr(Schema.NonEmptyString),
+    })), { onExcessProperty: "error" })(body);
+    if (input._tag === "None")
+        return refusal(400, "Choose read or write tools");
+    if (!agentIdPattern.test(agentId) ||
+        !(await agents.list()).some((agent) => agent.agentId === agentId))
+        return refusal(404, "No such agent");
+    const result = await agents.approveAppToolPolicy(agentId, principal, input.value.level, input.value.expectedRevision, actor);
+    const failureStatuses = {
+        not_found: 404,
+        not_granted: 403,
+        revision_conflict: 409,
+    };
+    return "error" in result
+        ? refusal(failureStatuses[result.error], result.error)
+        : Response.json(result);
+}
+/** Host-owned direct approval under the admitted owner; never an App capability. */
+export function agentApprovalRoutes(agents) {
+    return new Hono()
+        .get("/api/agent-policies/:agentId", async (context) => {
+        if (context.req.raw.headers.has("X-Oyster-Installation"))
+            return refusal(403, "Owner direct only");
+        if (!oysterPrincipalIsOwner(context.get("principal")))
+            return refusal(403, "Owner only");
+        const agentId = context.req.param("agentId");
+        if (!(await agents.list()).some((agent) => agent.agentId === agentId))
+            return refusal(404, "No such agent");
+        return Response.json({
+            expectedRevision: await agents.policyRevision(agentId),
+        });
+    })
+        .put("/api/agent-policies/:agentId", async (context) => context.req.raw.headers.has("X-Oyster-Installation")
+        ? refusal(403, "Missing admitted Agent installation")
+        : approvePolicy(agents, context.get("principal"), "owner-direct", context.req.param("agentId"), await context.req.text()));
+}
+const serverIdPattern = /^[a-z0-9_-]{1,64}$/u;
+const mcpRefusalStatus = { not_found: 404, duplicate_name: 409, limit: 409 };
+/**
+ * Host-owned Agent MCP server custody for the owner directly; never an App
+ * capability. Bearer tokens go in and never come back out.
+ */
+export function agentMcpServerRoutes(agents) {
+    const routes = new Hono();
+    const ownerOnly = async (context, next) => {
+        if (context.req.raw.headers.has("X-Oyster-Installation"))
+            return refusal(403, "Owner direct only");
+        if (!oysterPrincipalIsOwner(context.get("principal")))
+            return refusal(403, "Only the owner connects MCP servers");
+        await next();
+        return undefined;
+    };
+    routes.use("/api/agent-mcp-servers", ownerOnly);
+    routes.use("/api/agent-mcp-servers/*", ownerOnly);
+    // One owner read for the settings panel: every Agent with its servers.
+    routes.get("/api/agent-mcp-servers", async () => {
+        const listed = await agents.list();
+        const rows = await Promise.all(listed.map(async (agent) => ({
+            agentId: agent.agentId,
+            name: agent.name,
+            servers: (await agents.mcpServers(agent.agentId)) ?? [],
+        })));
+        return Response.json({ agents: rows });
+    });
+    routes.post("/api/agent-mcp-servers/:agentId", async (context) => {
+        if (!agentIdPattern.test(context.req.param("agentId")))
+            return refusal(404, "No such agent");
+        const length = Number(context.req.header("content-length") ?? "0");
+        if (length > 16 * 1024)
+            return refusal(413, "Request too large");
+        const input = Schema.decodeUnknownOption(Schema.fromJsonString(agentMcpServerInputSchema), { onExcessProperty: "error" })(await context.req.text());
+        if (input._tag === "None")
+            return refusal(400, "Name the server (lowercase letters, digits, _) and give its https:// endpoint");
+        const added = await agents.addMcpServer(context.req.param("agentId"), input.value);
+        return "error" in added
+            ? refusal(mcpRefusalStatus[added.error], added.error)
+            : Response.json(added, { status: 201 });
+    });
+    routes.delete("/api/agent-mcp-servers/:agentId/:serverId", async (context) => {
+        const serverId = context.req.param("serverId");
+        if (!agentIdPattern.test(context.req.param("agentId")) ||
+            !serverIdPattern.test(serverId))
+            return refusal(404, "No such server");
+        return (await agents.removeMcpServer(context.req.param("agentId"), serverId))
+            ? new Response(null, { status: 204 })
+            : refusal(404, "No such server");
+    });
+    return routes;
+}

package/dist/app-builds.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Oyster's App build owner: an App's registered source, its build jobs on the
+ * host's own Computer, and the Releases those builds produce.
+ *
+ * A build runs the shared job lifecycle (`build/build-jobs.ts`) and the fixed
+ * captured builder command on one Computer. The Computer holds no key: its
+ * clone is admitted at egress for exactly the job's one repository (read
+ * only), and its candidate upload for exactly the job. A source is either a
+ * repository in an installation's Git (a fork, through the Git door) or the
+ * App's own published template, built only at a recorded seed revision of
+ * its pinned recipe (no installed App is needed). The build streams each
+ * built object into the host's artifact store itself, through the egress, and
+ * then submits a small manifest naming them. This owner only records facts:
+ * it checks each named object's stored size and digest, writes the asset
+ * manifest and App root in Oyster's one immutable artifact representation
+ * (the same objects a packed upload writes), verifies the Release like any
+ * installed one, and records it; installing it is a separate owner act.
+ */
+import * as Schema from "effect/Schema";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import { type Release } from "@fungi.computer/puffball";
+import { type TeamAppCandidateManifest } from "./build/submission-contract.js";
+import { type ArtifactHeads, type ArtifactStore } from "./release.js";
+import type { PublisherTemplateSeedReceipts } from "./source/seed-receipt.js";
+/** A Computer's whole-build budget: a cold build on a 6 GiB Computer measured 185-270 s. */
+export declare const oysterAppBuildTimeoutMs = 900000;
+/** Host names the Computer's egress serves for a build; never public hosts. */
+export declare const oysterBuildGitHost = "git.team.internal";
+export declare const oysterBuildReportHost = "build.team.internal";
+/** Where an App's source is cloned from. */
+export declare const oysterBuildLocationSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"installation">;
+    /** The installation whose Git holds the repository (Bonsai for a fork). */
+    readonly installationId: Schema.String;
+    readonly repository: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"template">;
+}>]>;
+export type OysterBuildLocation = Schema.Schema.Type<typeof oysterBuildLocationSchema>;
+/** An App's registered build source: where it is cloned and its pinned recipe. */
+export declare const oysterBuildSourceSchema: Schema.Struct<{
+    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly location: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"installation">;
+        /** The installation whose Git holds the repository (Bonsai for a fork). */
+        readonly installationId: Schema.String;
+        readonly repository: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"template">;
+    }>]>;
+    readonly recipe: Schema.Struct<{
+        readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
+        readonly bundle: Schema.Literal<true>;
+        readonly entry: Schema.String;
+        readonly format: Schema.Literals<readonly ["html", "esm", "assets"]>;
+        readonly assets: Schema.optional<Schema.Struct<{
+            readonly maxManifestBytes: Schema.Number;
+            readonly maxObjects: Schema.Number;
+            readonly maxObjectBytes: Schema.Number;
+            readonly maxTotalBytes: Schema.Number;
+        }>>;
+        readonly assetBase: Schema.optionalKey<Schema.String>;
+        readonly toolchain: Schema.$Record<Schema.String, Schema.String>;
+        readonly maxOutputBytes: Schema.Number;
+        readonly platform: Schema.Literals<readonly ["browser", "neutral"]>;
+        readonly backend: Schema.Union<readonly [Schema.Null, Schema.Struct<{
+            readonly entry: Schema.optional<Schema.String>;
+            readonly runtime: Schema.Struct<{
+                readonly kind: Schema.Literal<"durable-facet">;
+                readonly stateSchema: Schema.Number;
+            }>;
+            readonly compatibilityDate: Schema.String;
+            readonly exportName: Schema.String;
+        }>]>;
+        readonly target: Schema.Tuple<readonly [Schema.Literal<"es2022">]>;
+    }>;
+    readonly buildRecipeDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
+}>;
+export type OysterBuildSource = Schema.Schema.Type<typeof oysterBuildSourceSchema>;
+/** What an owner sees of one build. */
+export type OysterBuildView = Readonly<{
+    jobId: string;
+    appId: string;
+    releaseId: string;
+    sourceRevision: string;
+    status: "running" | "succeeded" | "failed" | "revoked";
+    detail: string | null;
+    release: Release | null;
+}>;
+export type OysterBuildComputer = Readonly<{
+    /** Run the fixed build command; the Computer re-admits the job first.
+     * A missing `output` means no terminal result was established: the
+     * command may still be running, so it is never read as an exit. */
+    runBuild(input: {
+        jobId: string;
+        command: string;
+        timeoutMs: number;
+    }): Promise<Readonly<{
+        output?: Readonly<{
+            exitCode: number | null;
+            stderr?: string;
+        }> | null;
+    }>>;
+}>;
+export type OysterAppBuildOptions = Readonly<{
+    owner: WatchdogSqliteOwner;
+    /** The tenant the jobs belong to (the job lifecycle's team). */
+    tenantId: string;
+    /** The fixed Computer this host builds on, and its Durable Object id. */
+    computer: Readonly<{
+        name: string;
+        objectId: string;
+        port: OysterBuildComputer;
+    }>;
+    /** The host's artifact store; a build's objects are already in it. */
+    artifacts: ArtifactStore & ArtifactHeads;
+    /** The seed receipts a template build must match. */
+    templates: Pick<PublisherTemplateSeedReceipts, "read">;
+    now?: () => number;
+}>;
+/**
+ * The SQLite tables one Oyster build owner keeps. Creation and any carrying
+ * forward of retained facts run as one transaction of the owner's storage, so
+ * an interrupted conversion leaves the facts as they were for a retry.
+ */
+export declare function migrateOysterAppBuilds(owner: WatchdogSqliteOwner): void;
+/** The build owner over one tenant's SQLite, Computer and artifact store. */
+export declare function createOysterAppBuilds(options: OysterAppBuildOptions): Readonly<{
+    /** Record (or replace) an App's build source; the caller is the owner. */
+    registerSource(source: OysterBuildSource): OysterBuildSource;
+    readSource: (appId: string) => OysterBuildSource | null;
+    /**
+     * Mint one build job for an App's registered source at one exact commit.
+     * A template source builds only a seed revision recorded for its pinned
+     * recipe.
+     * Answers the job and its one run, which the caller keeps alive (the
+     * upload grant exists only inside that run's fixed command).
+     */
+    start(input: {
+        appId: string;
+        sourceRevision: string;
+        requestedBy: string;
+    }): Promise<Readonly<{
+        build: OysterBuildView;
+        run: () => Promise<OysterBuildView>;
+    }>>;
+    read(jobId: string): OysterBuildView | null;
+    /** A built Release by id, for an owner to install or select. */
+    release(releaseId: string): Release | null;
+    /** May this Computer execute this job now? Re-checked by the Computer. */
+    admitExecution(jobId: string, computerObjectId: string): boolean;
+    /** The live job a build report from this Computer may speak for. */
+    admitBuild(jobId: string, computerObjectId: string): Readonly<{
+        credentialId: string;
+    }> | null;
+    /**
+     * The clone credential the egress presents for this Computer's live job
+     * on exactly this repository, read only; null when no job admits it.
+     */
+    gitPassFor(computerObjectId: string, target: Readonly<{
+        installationId: string;
+        repository: string;
+        scope: "read" | "write";
+    }>): string | null;
+    /** Admit a presented clone credential at the Git door: one repository, read. */
+    admitGitPass(pass: string, target: Readonly<{
+        installationId: string;
+        repository: string;
+        scope: "read" | "write";
+    }>): Readonly<{
+        requestedBy: string;
+    }> | null;
+    /**
+     * May this Computer's clone read this template repository now? Only while
+     * a live template job on this Computer names it.
+     */
+    admitTemplateClone(computerObjectId: string, repository: string): boolean;
+    /** A reported artifact or status for a live job. */
+    record(event: Readonly<{
+        kind: "build-artifact";
+        jobId: string;
+        credentialId: string;
+        digest: string;
+        bytes: number;
+    }> | Readonly<{
+        kind: "build-status";
+        jobId: string;
+        credentialId: string;
+        status: "succeeded" | "failed";
+        detail: string | null;
+    }>): void;
+    /**
+     * May this live job's build upload one object now, and how large? The
+     * grant is the one inside the job's fixed command; the bound is its
+     * recipe's (`pinnedRecipeObjectBound`).
+     */
+    admitObjectUpload(jobId: string, computerObjectId: string, grant: string): Promise<Readonly<{
+        maxObjectBytes: number;
+    }> | null>;
+    /**
+     * The Computer's candidate manifest for a live job: checked against the
+     * job and its pinned recipe, each named object found stored with its
+     * size and verified digest (one at a time; only the backend descriptor
+     * is read), its asset manifest and App root written, verified as an
+     * installable Release and recorded. An over-policy candidate stores
+     * nothing.
+     */
+    submitCandidate(jobId: string, manifest: TeamAppCandidateManifest, grant: string, credentialId: string): Promise<Response>;
+}>;
+export type OysterAppBuilds = ReturnType<typeof createOysterAppBuilds>;