@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/standalone/agents.js

@@ -0,0 +1,795 @@
+import { standaloneTenancy, } from "./tenancy.js";
+import { AcceptedSchema } from "@fungi.computer/shiitake/client";
+import { memberInboxItemSchema } from "@fungi.computer/puffball/inbox";
+/**
+ * Agents on a standalone Oyster Worker. Each agent is Shiitake's public
+ * Cloudflare host (`ShiitakeDO`), one Durable Object per agent; a directory
+ * Durable Object names them and keeps the member's visits. The model comes
+ * from a pluggable `ModelSource`; the default runs Workers AI through the
+ * Worker's AI binding, with no API token.
+ */
+import { agentDirectoryForScope } from "./agent-directory.js";
+import { DurableObject } from "cloudflare:workers";
+import { ShiitakeDO } from "@fungi.computer/shiitake/cloudflare";
+import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
+import { configuredProviderEgress, providerFetch, } from "@fungi.computer/veil/gatekeeper";
+import { CLOUDFLARE_GATEWAY_BINDING_AUTH_SENTINEL, createAiBindingFetch, } from "@earendil-works/pi-ai/api/cloudflare-ai-binding";
+import { cloudflareWorkersAIProvider } from "@earendil-works/pi-ai/providers/cloudflare-workers-ai";
+import * as Schema from "effect/Schema";
+import { z } from "zod";
+import {} from "../cloudflare.js";
+import { AppInstanceError } from "../index.js";
+import { defineIdFamily } from "@fungi.computer/cairn";
+import { agentIds, createAgentDirectory, createFleetSessions, DirectoryError, } from "@fungi.computer/shiitake/fleet";
+import { appSurfaceCache, oysterAppMethods, } from "../mcp.js";
+import { appToolPolicySchema } from "../apps/index.js";
+import { oysterPrincipalIsOwner, oysterPrincipalId, } from "../host.js";
+import { defaultTenant, tenantIdSchema, tenantScope, } from "../tenant.js";
+import { createCodemodeSandbox } from "@fungi.computer/mycelium/workers";
+import { Knapsack } from "@fungi.computer/knapsack";
+import { maxAgentMcpServers, } from "../agents.js";
+/** Default Workers AI chat model: one that reliably calls tools. */
+const defaultAgentModel = "@cf/moonshotai/kimi-k2.6";
+/**
+ * Workers AI over the AI binding. Requests go through AI Gateway's
+ * `workers-ai` passthrough on the binding, so no API token is needed.
+ */
+function workersAiModels(ai, options = {}) {
+    const id = options.model ?? defaultAgentModel;
+    const listed = cloudflareWorkersAIProvider()
+        .getModels()
+        .find((model) => model.id === id);
+    if (listed === undefined)
+        throw new Error(`Workers AI has no chat model ${id}`);
+    const model = {
+        ...listed,
+        baseUrl: `https://workers-binding.ai/ai-gateway/gateways/${options.gateway ?? "default"}/workers-ai/v1`,
+    };
+    const fetch = createAiBindingFetch(ai);
+    return {
+        acquire: async () => {
+            const streamSimple = await loadStreamSimple();
+            return {
+                model,
+                stream: (selected, context, streamOptions) => streamSimple(selected, context, {
+                    ...streamOptions,
+                    fetch,
+                    apiKey: CLOUDFLARE_GATEWAY_BINDING_AUTH_SENTINEL,
+                    headers: {
+                        "cf-aig-authorization": `Bearer ${CLOUDFLARE_GATEWAY_BINDING_AUTH_SENTINEL}`,
+                        // The binding carries identity; a request auth header would be
+                        // taken as a provider key that overrides the gateway's own.
+                        Authorization: null,
+                    },
+                }),
+                release: () => Promise.resolve(),
+            };
+        },
+    };
+}
+/**
+ * Pi's dispatching `streamSimple` evaluates every provider's model catalog when
+ * it loads; only a run needs it, so acquisition loads it instead of startup.
+ */
+const loadStreamSimple = async () => (await import("@earendil-works/pi-ai/compat")).streamSimple;
+const policyDirectorySchema = Schema.Struct({
+    directoryName: Schema.NonEmptyString,
+    tenantId: tenantIdSchema,
+});
+/** This Agent's remote MCP servers; the bearer stays in this Durable Object. */
+const storedMcpServersSchema = Schema.Array(Schema.Struct({
+    serverId: Schema.NonEmptyString,
+    name: Schema.NonEmptyString,
+    url: Schema.NonEmptyString,
+    bearer: Schema.NullOr(Schema.NonEmptyString),
+}));
+const mcpServersKey = "agent-mcp-servers";
+const mcpServerIds = defineIdFamily({
+    family: "oyster-mcp",
+    version: 1,
+    kinds: { server: { prefix: "mcp" } },
+});
+/** The Knapsack connection for one stored server; its bearer goes only to that endpoint. */
+function mcpConnection(server) {
+    const connection = {
+        id: `mcp.${server.serverId}`,
+        name: server.name,
+        url: new URL(server.url),
+    };
+    if (server.bearer === null)
+        return connection;
+    return {
+        ...connection,
+        headers: { authorization: `Bearer ${server.bearer}` },
+    };
+}
+const toMcpServer = (stored) => ({
+    serverId: stored.serverId,
+    name: stored.name,
+    url: stored.url,
+    hasBearer: stored.bearer !== null,
+});
+const instructions = [
+    "You are an agent on a personal Oyster: a small, self-hosted home for Apps.",
+    "Your tool is execute: it runs JavaScript in an isolated sandbox. Each installed App is an env.<APP> module; dotted method names are nested properties, e.g. `return await env.BONSAI.repos.list({})`.",
+    "Remote MCP servers the owner connected are env.mcp.<server> modules; call a tool as `return await env.mcp.<server>.<tool>({...})`.",
+    "Discover what exists with `return await forage.list({limit:50})` and `return await forage.describe({path})` before calling a method you have not seen.",
+    "Only the value your program returns is visible to you; console.log output is not. Always `return` the result.",
+    "Be direct and brief. Say plainly when you cannot do something.",
+].join("\n");
+/** One agent: Shiitake's Cloudflare host over this Durable Object; its root supplies `hostFor`. */
+export class StandaloneAgentBase extends ShiitakeDO {
+    /** Each installed Release's verified catalog surface, built once per Release for this Agent's lifetime. */
+    #appSurfaces;
+    /** The root host for this Agent's pinned policy directory; unpinned Agents have no App tools. */
+    async appHost() {
+        const stored = await this.ctx.storage.get("app-policy-directory");
+        if (stored === undefined)
+            return null;
+        const pinned = Schema.decodeUnknownSync(policyDirectorySchema)(stored);
+        const scope = tenantScope(pinned.tenantId, this.env.OYSTER_ORIGIN);
+        return pinned.directoryName === scope.durableName("agents")
+            ? this.hostFor(scope)
+            : null;
+    }
+    /** Choose this agent's model door; override to plug in another. */
+    modelSource() {
+        if (this.env.OYSTER_AGENT_MODEL === "@fungi/luna") {
+            const egress = configuredProviderEgress(this.env);
+            const baseUrl = egress.baseUrl("ai-gateway");
+            if (baseUrl === null)
+                throw new Error("Configure the Luna AI Gateway Worker secret and gateway");
+            const provider = openaiProvider();
+            const listed = provider
+                .getModels()
+                .find((item) => item.id === "gpt-6-luna");
+            if (listed === undefined)
+                throw new Error("The OpenAI catalog has no Luna model");
+            const model = { ...listed, id: "openai/gpt-6-luna", baseUrl };
+            return {
+                acquire: async () => {
+                    const streamSimple = await loadStreamSimple();
+                    return {
+                        model,
+                        stream: (selected, context, options) => streamSimple(selected, context, {
+                            ...options,
+                            apiKey: "oyster-provider-egress",
+                            fetch: providerFetch(egress, "ai-gateway"),
+                        }),
+                        release: () => Promise.resolve(),
+                    };
+                },
+            };
+        }
+        if (this.env.AI === undefined)
+            throw new Error("Configure the AI binding to run agents");
+        const options = {};
+        if (this.env.OYSTER_AGENT_MODEL !== undefined)
+            options.model = this.env.OYSTER_AGENT_MODEL;
+        if (this.env.OYSTER_AI_GATEWAY !== undefined)
+            options.gateway = this.env.OYSTER_AI_GATEWAY;
+        return workersAiModels(this.env.AI, options);
+    }
+    /** Host-only initialization; Agent/App transports never receive this directory binding. */
+    async usePolicyDirectory(input) {
+        const directory = Schema.decodeUnknownSync(policyDirectorySchema)(input);
+        const previous = await this.ctx.storage.get("app-policy-directory");
+        if (previous !== undefined) {
+            const pinned = Schema.decodeUnknownSync(policyDirectorySchema)(previous);
+            if (pinned.directoryName !== directory.directoryName ||
+                pinned.tenantId !== directory.tenantId)
+                throw new Error("Agent policy directory mismatch");
+            return;
+        }
+        await this.ctx.storage.put("app-policy-directory", directory);
+    }
+    /** Host-only policy pin read, used before an owner can approve tools. */
+    async policyDirectory() {
+        const stored = await this.ctx.storage.get("app-policy-directory");
+        return stored === undefined
+            ? null
+            : Schema.decodeUnknownSync(policyDirectorySchema)(stored);
+    }
+    /** Listeners from live codemode acquisitions, told when the server list changes. */
+    mcpInvalidations = new Set();
+    async storedMcpServers() {
+        const stored = await this.ctx.storage.get(mcpServersKey);
+        return stored === undefined
+            ? []
+            : Schema.decodeUnknownSync(storedMcpServersSchema)(stored);
+    }
+    async writeMcpServers(servers) {
+        await this.ctx.storage.put(mcpServersKey, servers);
+        for (const invalidate of this.mcpInvalidations)
+            invalidate();
+    }
+    /** Host-only: this Agent's MCP servers, without their bearer tokens. */
+    async mcpServers() {
+        return (await this.storedMcpServers()).map(toMcpServer);
+    }
+    /** Host-only: connect one remote MCP server, admitted by the owner route. */
+    async addMcpServer(input) {
+        const servers = await this.storedMcpServers();
+        if (servers.some((server) => server.name === input.name))
+            return { error: "duplicate_name" };
+        if (servers.length >= maxAgentMcpServers)
+            return { error: "limit" };
+        const added = {
+            serverId: mcpServerIds.server.generate(),
+            name: input.name,
+            url: new URL(input.url).href,
+            bearer: input.bearer,
+        };
+        await this.writeMcpServers([...servers, added]);
+        return toMcpServer(added);
+    }
+    /** Host-only: disconnect one MCP server. */
+    async removeMcpServer(serverId) {
+        const servers = await this.storedMcpServers();
+        const kept = servers.filter((server) => server.serverId !== serverId);
+        if (kept.length === servers.length)
+            return false;
+        await this.writeMcpServers(kept);
+        return true;
+    }
+    shiitakeOptions() {
+        const principal = {
+            actor: { kind: "agent", agentId: this.ctx.id.name ?? "agent" },
+        };
+        return {
+            model: this.modelSource(),
+            instructions: {
+                load: () => Promise.resolve({ revision: "oyster-4", text: instructions }),
+            },
+            tools: {
+                sources: [
+                    {
+                        id: "oyster-apps",
+                        // Capture once per catalog acquisition, so the next run sees
+                        // changed Releases, installation authority and removals.
+                        acquire: async (context) => {
+                            const host = await this.appHost();
+                            if (host === null)
+                                return {
+                                    snapshot: { version: "unpinned", modules: [] },
+                                    release: () => Promise.resolve(),
+                                };
+                            const policy = (await host.appToolPolicy?.(principal.actor)) ?? null;
+                            this.#appSurfaces ??= appSurfaceCache(host);
+                            const source = await oysterAppMethods(host, principal, policy === null ? null : { kind: "agent", policy }, this.#appSurfaces);
+                            return source.acquire(context);
+                        },
+                    },
+                    Knapsack.mcpServers({
+                        id: "agent-mcp",
+                        read: async () => {
+                            const servers = await this.storedMcpServers();
+                            return {
+                                // Secret-free: ids and endpoints, never the bearer.
+                                version: JSON.stringify(servers.map((server) => [server.serverId, server.url])),
+                                servers: servers.map(mcpConnection),
+                            };
+                        },
+                        subscribe: (invalidate) => {
+                            this.mcpInvalidations.add(invalidate);
+                            return () => this.mcpInvalidations.delete(invalidate);
+                        },
+                        onUnavailable: (error) => {
+                            console.warn("agent MCP server unavailable", {
+                                serverId: error.serverId,
+                                reason: error.reason,
+                            });
+                        },
+                        // The Worker's own egress: public internet only.
+                        fetch: (url, init) => fetch(url, init),
+                    }),
+                ],
+                sandbox: createCodemodeSandbox(this.env.LOADER, "oyster-workerd"),
+            },
+            extensions: { roster: [], grants: [] },
+        };
+    }
+    /** Send an installation-admitted message through fleet Session operations. */
+    async sendFromApp(installationId, sessionId, message) {
+        const id = this.ctx.id.name;
+        if (id === undefined)
+            throw new Error("Agent address is unnamed");
+        const sessions = createFleetSessions(async () => ({
+            agent: await this.shiitake(),
+            release: () => Promise.resolve(),
+        }));
+        const grant = {
+            agents: [id],
+            actions: ["send"],
+            expiresAt: Date.now() + 60_000,
+            provenance: { actor: installationId },
+        };
+        return sessions.send(grant, id, sessionId, message);
+    }
+    /** Latest inbox clock from the same Shiitake owner, without reading Session rows. */
+    async revision() {
+        await this.shiitake();
+        return this.readInboxRevision();
+    }
+    /** Every live Session of this agent, as inbox rows. */
+    async inboxRows() {
+        const changes = await this.readInboxChanges(0, 1_000);
+        const rows = [];
+        for (const row of changes.rows) {
+            if ("deleted" in row)
+                continue;
+            rows.push(row);
+        }
+        return { rows, revision: changes.latest };
+    }
+}
+const actingInstallationSchema = Schema.Union([
+    Schema.Literal("owner-direct"),
+    Schema.Struct({ installationId: Schema.NonEmptyString }),
+]);
+const approverVersionSchema = Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }));
+const storedPolicySchema = Schema.Union([
+    Schema.Struct({
+        status: Schema.Literal("pending"),
+        level: Schema.Literals(["read", "write"]),
+        revision: Schema.NonEmptyString,
+        actingInstallation: actingInstallationSchema,
+    }),
+    Schema.Struct({
+        status: Schema.Literal("approved"),
+        policy: appToolPolicySchema,
+        membershipVersion: approverVersionSchema,
+        actingInstallation: actingInstallationSchema,
+    }),
+]);
+const requestIds = defineIdFamily({
+    family: "oyster-agent",
+    version: 1,
+    kinds: { request: { prefix: "request" } },
+});
+const visitRow = Schema.Struct({
+    agent_id: Schema.String,
+    session_id: Schema.String,
+    visited_at: Schema.Number,
+});
+const counterRow = Schema.Struct({ value: Schema.Number });
+/** Names this Oyster's agents and remembers which Sessions the member opened. */
+export class AgentDirectory extends DurableObject {
+    directory;
+    composedTenancy;
+    grant() {
+        return {
+            agents: "all",
+            actions: ["create", "read", "manage"],
+            expiresAt: Date.now() + 60_000,
+            provenance: { actor: this.env.OYSTER_OWNER_NAME ?? "owner" },
+        };
+    }
+    constructor(ctx, env) {
+        super(ctx, env);
+        this.directory = createAgentDirectory(ctx.storage.sql);
+        ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS visits (agent_id TEXT NOT NULL, session_id TEXT NOT NULL, visited_at INTEGER NOT NULL, PRIMARY KEY (agent_id, session_id)) STRICT");
+        ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS counters (name TEXT PRIMARY KEY, value INTEGER NOT NULL) STRICT");
+        ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS app_tool_policies (agent_id TEXT PRIMARY KEY, policy TEXT NOT NULL) STRICT");
+    }
+    list() {
+        return this.directory
+            .list(this.grant())
+            .toReversed()
+            .map(({ agentId, name }) => ({ agentId, name }));
+    }
+    has(agentId) {
+        const id = agentIds.agent.parse(agentId);
+        return id.ok && this.directory.read(this.grant(), id.value) !== null;
+    }
+    /** Resolve the existing recorded creator for host-side owner admission. */
+    readCreator(agentId) {
+        return this.directory.readCreator(this.grant(), agentId);
+    }
+    /** Owner-only rename; refuses a name already held by another Agent. */
+    rename(agentId, name, principal) {
+        if (!oysterPrincipalIsOwner(principal))
+            return { error: "not_granted" };
+        const id = agentIds.agent.parse(agentId);
+        if (!id.ok)
+            return { error: "not_found" };
+        return this.ctx.storage.transactionSync(() => {
+            try {
+                const renamed = this.directory.rename(this.grant(), id.value, {
+                    name,
+                });
+                this.bump();
+                return { agentId: renamed.agentId, name: renamed.name };
+            }
+            catch (cause) {
+                if (cause instanceof DirectoryError && cause.code === "not_found")
+                    return { error: "not_found" };
+                if (cause instanceof DirectoryError && cause.code === "name_taken")
+                    return { error: "name_taken" };
+                throw cause;
+            }
+        });
+    }
+    create(name, requestId, principal, actor) {
+        if (!oysterPrincipalIsOwner(principal))
+            throw new Error("Only the authenticated owner creates Agents");
+        return this.ctx.storage.transactionSync(() => {
+            const { agent, fact } = this.directory.create({
+                ...this.grant(),
+                provenance: { actor: oysterPrincipalId(principal) },
+            }, { name, requestId, configuration: "none" });
+            if (fact !== null) {
+                this.bump();
+                this.writePolicy(agent.agentId, {
+                    status: "pending",
+                    level: "write",
+                    revision: `${agent.agentId}:${String(this.revision())}`,
+                    actingInstallation: actor,
+                });
+            }
+            const stored = this.storedPolicy(agent.agentId);
+            return {
+                agentId: agent.agentId,
+                name: agent.name,
+                policyRevision: stored === null
+                    ? null
+                    : stored.status === "pending"
+                        ? stored.revision
+                        : null,
+            };
+        });
+    }
+    writePolicy(agentId, policy) {
+        const encoded = Schema.encodeSync(Schema.fromJsonString(storedPolicySchema))(policy);
+        this.ctx.storage.sql.exec("INSERT INTO app_tool_policies(agent_id,policy) VALUES(?,?) ON CONFLICT(agent_id) DO UPDATE SET policy=excluded.policy", agentId, encoded);
+    }
+    storedPolicy(agentId) {
+        if (!this.has(agentId))
+            return null;
+        return this.readPolicy("SELECT policy FROM app_tool_policies WHERE agent_id=?", agentId);
+    }
+    readPolicy(query, id) {
+        const row = this.ctx.storage.sql.exec(query, id).toArray()[0];
+        if (row === undefined)
+            return null;
+        const stored = Schema.decodeUnknownSync(Schema.Struct({ policy: Schema.String }))(row);
+        const parsed = Schema.decodeUnknownOption(Schema.fromJsonString(storedPolicySchema), { onExcessProperty: "error" })(stored.policy);
+        return parsed._tag === "Some" ? parsed.value : null;
+    }
+    /** Current revision for the direct owner's compare-and-swap request. */
+    policyRevision(agentId) {
+        const stored = this.storedPolicy(agentId);
+        return stored === null
+            ? null
+            : stored.status === "pending"
+                ? stored.revision
+                : stored.policy.revision;
+    }
+    /** Whether this Agent's App-tool policy still awaits the owner's approval. */
+    policyStatus(agentId) {
+        const stored = this.storedPolicy(agentId);
+        if (stored === null)
+            return null;
+        return stored.status === "pending"
+            ? { status: "pending", revision: stored.revision }
+            : { status: "approved", revision: stored.policy.revision };
+    }
+    async currentMember(tenantId, memberId) {
+        if (this.env.TENANCY !== undefined)
+            return this.env.TENANCY.memberById(tenantId, memberId);
+        // KEYS is always present on StandaloneAgentEnv (via StandaloneComputerEnv).
+        if (this.env.TENANTS === undefined)
+            return null;
+        let configured = {
+            TENANTS: this.env.TENANTS,
+            KEYS: this.env.KEYS,
+            OYSTER_ORIGIN: this.env.OYSTER_ORIGIN,
+            OYSTER_OWNER_KEY: this.env.OYSTER_OWNER_KEY,
+        };
+        if (this.env.OYSTER_OWNER_NAME !== undefined)
+            configured = {
+                ...configured,
+                OYSTER_OWNER_NAME: this.env.OYSTER_OWNER_NAME,
+            };
+        const pending = (this.composedTenancy ??= standaloneTenancy(configured));
+        const composed = await pending.catch((cause) => {
+            if (this.composedTenancy === pending)
+                this.composedTenancy = undefined;
+            throw cause;
+        });
+        const owner = await composed.owner();
+        if (owner === null ||
+            tenantId !== composed.tenantId ||
+            owner.actor.memberId !== memberId)
+            return null;
+        return composed.tenancy.memberById(tenantId, memberId);
+    }
+    /** Approval stays revoked after any membership authority revision. */
+    async appToolPolicy(actor, tenantId = defaultTenant) {
+        const stored = this.storedPolicy(actor.agentId);
+        if (stored?.status !== "approved")
+            return null;
+        const current = await this.currentMember(tenantId, stored.policy.grantedBy);
+        return current !== null &&
+            oysterPrincipalIsOwner(current) &&
+            oysterPrincipalId(current) === stored.policy.grantedBy &&
+            current.membershipVersion === stored.membershipVersion
+            ? stored.policy
+            : null;
+    }
+    /** Only direct human approval records an authenticated canonical grantor. */
+    async approveAppToolPolicy(agentId, principal, level, expectedRevision, actor, tenantId) {
+        if (!oysterPrincipalIsOwner(principal))
+            return { error: "not_granted" };
+        if (!this.has(agentId))
+            return { error: "not_found" };
+        const member = actor === "owner-direct"
+            ? await this.currentMember(tenantId, oysterPrincipalId(principal))
+            : null;
+        if (actor === "owner-direct" &&
+            (member === null ||
+                !oysterPrincipalIsOwner(member) ||
+                !Schema.is(approverVersionSchema)(member.membershipVersion) ||
+                oysterPrincipalId(member) !== oysterPrincipalId(principal)))
+            return { error: "not_granted" };
+        return this.ctx.storage.transactionSync(() => {
+            const current = this.storedPolicy(agentId);
+            const revision = current === null
+                ? null
+                : current.status === "pending"
+                    ? current.revision
+                    : current.policy.revision;
+            if (revision !== expectedRevision)
+                return { error: "revision_conflict" };
+            this.bump();
+            const nextRevision = `${agentId}:${String(this.revision())}`;
+            if (actor !== "owner-direct" || member === null) {
+                this.writePolicy(agentId, {
+                    status: "pending",
+                    level,
+                    revision: nextRevision,
+                    actingInstallation: actor,
+                });
+                return { status: "pending", revision: nextRevision };
+            }
+            const policy = {
+                level,
+                revision: nextRevision,
+                grantedBy: oysterPrincipalId(member),
+            };
+            this.writePolicy(agentId, {
+                status: "approved",
+                policy,
+                membershipVersion: member.membershipVersion,
+                actingInstallation: actor,
+            });
+            return policy;
+        });
+    }
+    visit(agentId, sessionId) {
+        this.ctx.storage.sql.exec("INSERT INTO visits(agent_id, session_id, visited_at) VALUES(?,?,?) ON CONFLICT(agent_id, session_id) DO UPDATE SET visited_at=excluded.visited_at", agentId, sessionId, Date.now());
+        this.bump();
+    }
+    visits() {
+        return this.ctx.storage.sql
+            .exec("SELECT agent_id, session_id, visited_at FROM visits")
+            .toArray()
+            .map((row) => {
+            const decoded = Schema.decodeUnknownSync(visitRow)(row);
+            return {
+                agentId: decoded.agent_id,
+                sessionId: decoded.session_id,
+                visitedAt: decoded.visited_at,
+            };
+        });
+    }
+    /** Grows on every directory change (a new agent, a visit). */
+    revision() {
+        const row = this.ctx.storage.sql
+            .exec("SELECT value FROM counters WHERE name='revision'")
+            .toArray()[0];
+        return row === undefined
+            ? 0
+            : Schema.decodeUnknownSync(counterRow)(row).value;
+    }
+    bump() {
+        this.ctx.storage.sql.exec("INSERT INTO counters(name, value) VALUES('revision', 1) ON CONFLICT(name) DO UPDATE SET value=value+1");
+    }
+}
+const everyOperation = [
+    "agent.read",
+    "agent.send",
+    "agent.manage",
+];
+/** The `agents` adapter over a Worker's agent bindings. */
+export function standaloneAgents(env, scope) {
+    const directoryName = scope === undefined ? "agents" : scope.durableName("agents");
+    const directory = () => scope === undefined
+        ? env.AGENT_DIRECTORY.getByName(directoryName)
+        : agentDirectoryForScope(env, scope);
+    const toAgent = (entry) => ({
+        agentId: entry.agentId,
+        name: entry.name,
+        sessionOperations: everyOperation,
+    });
+    return {
+        list: async () => (await directory().list()).map(toAgent),
+        create: async (name, requestId, principal, actor) => {
+            const entry = await directory().create(name, requestId, principal, actor);
+            await env.AGENTS.getByName(entry.agentId).usePolicyDirectory({
+                directoryName,
+                tenantId: scope?.tenantId ?? defaultTenant,
+            });
+            if (actor === "owner-direct" && entry.policyRevision !== null) {
+                // Best-effort: a stale membership lookup leaves the Agent pending
+                // rather than failing its creation. Grove's "Allow App tools"
+                // control recovers it through the same approval path.
+                await directory().approveAppToolPolicy(entry.agentId, principal, "write", entry.policyRevision, actor, scope?.tenantId ?? defaultTenant);
+            }
+            return toAgent(entry);
+        },
+        rename: async (agentId, name, principal) => {
+            const result = await directory().rename(agentId, name, principal);
+            return "error" in result ? result : toAgent(result);
+        },
+        policyStatus: async (agentId) => directory().policyStatus(agentId),
+        appToolPolicy: (actor) => directory().appToolPolicy(actor, scope?.tenantId ?? defaultTenant),
+        policyRevision: (agentId) => directory().policyRevision(agentId),
+        approveAppToolPolicy: async (agentId, principal, level, expectedRevision, actor) => {
+            if (!(await directory().has(agentId)))
+                return { error: "not_found" };
+            const pinned = await env.AGENTS.getByName(agentId).policyDirectory();
+            if (pinned?.directoryName !== directoryName ||
+                pinned.tenantId !== (scope?.tenantId ?? defaultTenant))
+                return { error: "not_found" };
+            return directory().approveAppToolPolicy(agentId, principal, level, expectedRevision, actor, scope?.tenantId ?? defaultTenant);
+        },
+        mcpServers: async (agentId) => (await directory().has(agentId))
+            ? await env.AGENTS.getByName(agentId).mcpServers()
+            : null,
+        addMcpServer: async (agentId, input) => (await directory().has(agentId))
+            ? await env.AGENTS.getByName(agentId).addMcpServer(input)
+            : { error: "not_found" },
+        removeMcpServer: async (agentId, serverId) => (await directory().has(agentId)) &&
+            (await env.AGENTS.getByName(agentId).removeMcpServer(serverId)),
+        fetch: async (agentId, request) => (await directory().has(agentId))
+            ? await env.AGENTS.getByName(agentId).fetch(request)
+            : null,
+        inbox: async () => {
+            const [agents, visits, directoryRevision] = await Promise.all([
+                directory().list(),
+                directory().visits(),
+                directory().revision(),
+            ]);
+            const visited = new Map(visits.map((visit) => [
+                `${visit.agentId}\u0000${visit.sessionId}`,
+                visit.visitedAt,
+            ]));
+            const items = [];
+            // Each agent's revision only grows, so their sum with the directory's does too.
+            let revision = directoryRevision;
+            const inboxes = await Promise.all(agents.map(async (agent) => {
+                const agentHost = env.AGENTS.getByName(agent.agentId);
+                return { agent, own: await agentHost.inboxRows() };
+            }));
+            for (const { agent, own } of inboxes) {
+                revision += own.revision;
+                for (const row of own.rows) {
+                    const visitedAt = visited.get(`${agent.agentId}\u0000${row.sessionId}`);
+                    if (row.state === "unavailable" || visitedAt === undefined)
+                        items.push({ ...row, agentId: agent.agentId });
+                    else
+                        items.push({ ...row, agentId: agent.agentId, visitedAt });
+                }
+            }
+            return { items, revision };
+        },
+        revision: async () => {
+            const [agents, directoryRevision] = await Promise.all([
+                directory().list(),
+                directory().revision(),
+            ]);
+            const revisions = await Promise.all(agents.map((agent) => env.AGENTS.getByName(agent.agentId).revision()));
+            return revisions.reduce((total, revision) => total + revision, directoryRevision);
+        },
+        visit: async (agentId, sessionId) => {
+            if (!(await directory().has(agentId)))
+                return false;
+            await directory().visit(agentId, sessionId);
+            return true;
+        },
+    };
+}
+const agentTarget = z.strictObject({
+    agentId: z.string(),
+    sessionId: z.string(),
+});
+const agentBindingArgs = {
+    INBOX: {
+        page: z.tuple([
+            z.strictObject({ after: z.string().nullable().optional() }).optional(),
+        ]),
+        visit: z.tuple([agentTarget]),
+    },
+    AGENTS: {
+        send: z.tuple([
+            agentTarget.extend({ text: z.string(), delivery: z.literal("followUp") }),
+        ]),
+    },
+};
+const inboxPageSchema = Schema.Struct({
+    items: Schema.Array(memberInboxItemSchema),
+    next: Schema.Null,
+    cursor: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0)),
+});
+const inboxVisitSchema = Schema.Struct({ visited: Schema.Literal(true) });
+const decodeInboxPage = Schema.decodeUnknownSync(inboxPageSchema, {
+    onExcessProperty: "error",
+});
+const decodeInboxVisit = Schema.decodeUnknownSync(inboxVisitSchema, {
+    onExcessProperty: "error",
+});
+const decodeAgentAccepted = Schema.decodeUnknownSync(AcceptedSchema, {
+    onExcessProperty: "error",
+});
+/** Shared packet codecs; the Instance alone admits the current frame's operations. */
+export const agentFrameMethods = {
+    INBOX: {
+        page: {
+            decodeArgs: (raw) => agentBindingArgs.INBOX.page.parse(raw),
+            decodeResult: decodeInboxPage,
+            requiredOperations: () => ["page"],
+        },
+        visit: {
+            decodeArgs: (raw) => agentBindingArgs.INBOX.visit.parse(raw),
+            decodeResult: decodeInboxVisit,
+            requiredOperations: () => ["visit"],
+        },
+    },
+    AGENTS: {
+        send: {
+            decodeArgs: (raw) => agentBindingArgs.AGENTS.send.parse(raw),
+            decodeResult: decodeAgentAccepted,
+            requiredOperations: () => ["send"],
+        },
+    },
+};
+/** Provider effects are admitted by the originating Instance's live frame. */
+export async function dispatchAgentBinding(env, scope, frame, props, method, args) {
+    frame.signal.throwIfAborted();
+    if (frame.facts.selection.owner.kind !== "installation")
+        throw new AppInstanceError("revoked");
+    const installationId = frame.facts.selection.owner.id;
+    const directory = agentDirectoryForScope(env, scope);
+    let result;
+    if (props.binding === "INBOX" && method === "page") {
+        agentBindingArgs.INBOX.page.parse(args);
+        const inbox = await standaloneAgents(env, scope).inbox();
+        result = { items: inbox.items, next: null, cursor: inbox.revision };
+    }
+    else if (props.binding === "INBOX" && method === "visit") {
+        const [input] = agentBindingArgs.INBOX.visit.parse(args);
+        if (!(await directory.has(input.agentId)))
+            throw new Error("No such agent");
+        frame.signal.throwIfAborted();
+        await directory.visit(input.agentId, input.sessionId);
+        result = { visited: true };
+    }
+    else if (props.binding === "AGENTS" && method === "send") {
+        const [input] = agentBindingArgs.AGENTS.send.parse(args);
+        if (!(await directory.has(input.agentId)))
+            throw new Error("No such agent");
+        frame.signal.throwIfAborted();
+        const accepted = await env.AGENTS.getByName(input.agentId).sendFromApp(installationId, input.sessionId, {
+            requestId: requestIds.request.generate(),
+            text: input.text,
+            delivery: input.delivery,
+        });
+        result = { status: accepted.status, commandId: accepted.commandId };
+    }
+    else {
+        throw new AppInstanceError("revoked");
+    }
+    frame.signal.throwIfAborted();
+    return Schema.decodeUnknownSync(Schema.Union([inboxPageSchema, inboxVisitSchema, AcceptedSchema]), { onExcessProperty: "error" })(result);
+}