@fungi.computer/oyster 0.0.1 → 0.2.0

package/dist/source/template-push.js

@@ -0,0 +1,223 @@
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseAppId, parseSourceRevision, } from "@fungi.computer/puffball";
+import { authenticatedGitEnvironment, repositoryEnvironment, } from "../build/git-environment.js";
+/** The fixed identity of every seed commit, so a retry of the same tree on
+ * the same parent is the same commit. */
+const seedIdentity = {
+    GIT_AUTHOR_NAME: "Botanical App Source",
+    GIT_AUTHOR_EMAIL: "app-source@botanical.invalid",
+    GIT_AUTHOR_DATE: "@0 +0000",
+    GIT_COMMITTER_NAME: "Botanical App Source",
+    GIT_COMMITTER_EMAIL: "app-source@botanical.invalid",
+    GIT_COMMITTER_DATE: "@0 +0000",
+};
+/** Artifacts' native fork drops delta-encoded objects, so seed packs carry
+ * whole objects only. Every local object is loose (written here, or fetched
+ * with an unpack limit no fetch reaches), so no delta exists to reuse; a zero
+ * window computes none, `--no-thin` sends none against remote objects and no
+ * pack is reused verbatim. */
+const wholeObjectPush = [
+    "-c",
+    "pack.window=0",
+    "-c",
+    "pack.depth=0",
+    "-c",
+    "pack.allowPackReuse=false",
+];
+const looseFetch = ["-c", "fetch.unpackLimit=1000000000"];
+const objectId = /^[0-9a-f]{40}$/u;
+/** One whole publication (project, fetch, push, confirm) is bounded. */
+const TEMPLATE_PUSH_TIMEOUT_MS = 10 * 60_000;
+/** The Git subcommand of `args`, past any leading `-c name=value` pairs. */
+function command(args) {
+    let at = 0;
+    while (args[at] === "-c")
+        at += 2;
+    return args[at] ?? "";
+}
+function runGit(args, environment, signal, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", [...args], {
+            env: environment,
+            shell: false,
+            signal,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let spawnError;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.once("error", (error) => {
+            spawnError = error;
+        });
+        child.once("close", (code) => {
+            if (code === 0 && spawnError === undefined) {
+                resolve(stdout);
+                return;
+            }
+            const detail = stderr.trim();
+            reject(spawnError ??
+                new Error(`git ${command(args)} failed${detail ? `: ${detail}` : ` (${String(code)})`}`));
+        });
+        child.stdin.end(input);
+    });
+}
+/** A template path names one regular file below the root: relative, no empty,
+ * `.`, `..` or `.git` part, and never both a file and a directory. */
+function checkTemplatePaths(files) {
+    const paths = new Set();
+    for (const { path } of files) {
+        const parts = path.split("/");
+        if (path.length > 4096 ||
+            path.includes("\\") ||
+            path.includes("\0") ||
+            parts.some((part) => part === "" ||
+                part === "." ||
+                part === ".." ||
+                part.toLowerCase() === ".git"))
+            throw new Error("Template source path is invalid");
+        if (paths.has(path))
+            throw new Error("Duplicate template source path");
+        paths.add(path);
+    }
+    for (const path of paths) {
+        const parts = path.split("/");
+        for (let end = 1; end < parts.length; end += 1)
+            if (paths.has(parts.slice(0, end).join("/")))
+                throw new Error("Template source path is both a file and a directory");
+    }
+}
+function oid(output) {
+    const value = output.trim();
+    if (!objectId.test(value))
+        throw new Error("git returned no object id");
+    return value;
+}
+function remoteMain(output) {
+    for (const line of output.split("\n")) {
+        const [hash, ref] = line.split("\t");
+        if (ref === "refs/heads/main" && hash !== undefined && objectId.test(hash))
+            return hash;
+    }
+    return null;
+}
+/**
+ * Commit one projected App source tree onto its template repository's `main`
+ * with ordinary Git, and push it there over smart HTTP.
+ *
+ * The tree holds exactly the given bytes (no attributes or filters), each a
+ * regular non-executable file. The first seed is a parentless commit; a later
+ * different tree is an ordinary fast-forward on the current head; an exact
+ * retry pushes nothing and answers the current head. Nothing is forced. The
+ * `headers` authenticate every request and reach Git only through its config
+ * environment.
+ */
+export async function pushTemplateSource(input) {
+    const appId = parseAppId(input.appId);
+    const sourceRevision = parseSourceRevision(input.sourceRevision);
+    const remote = new URL(input.remote);
+    if (remote.username || remote.password || remote.search || remote.hash)
+        throw new Error("Template remote must not carry credentials or a query");
+    if (input.files.length === 0)
+        throw new Error("Template source is empty");
+    checkTemplatePaths(input.files);
+    const deadline = AbortSignal.timeout(TEMPLATE_PUSH_TIMEOUT_MS);
+    const signal = input.signal === undefined
+        ? deadline
+        : AbortSignal.any([input.signal, deadline]);
+    const work = await mkdtemp(join(tmpdir(), "oyster-template-push-"));
+    try {
+        const gitDir = join(work, "repository.git");
+        const staging = join(work, "files");
+        const local = {
+            ...repositoryEnvironment(),
+            HOME: work,
+            GIT_CONFIG_NOSYSTEM: "1",
+            GIT_CONFIG_GLOBAL: "/dev/null",
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_DIR: gitDir,
+            GIT_INDEX_FILE: join(work, "index"),
+        };
+        const network = {
+            ...authenticatedGitEnvironment(input.headers),
+            HOME: work,
+            GIT_CONFIG_NOSYSTEM: "1",
+            GIT_CONFIG_GLOBAL: "/dev/null",
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_DIR: gitDir,
+        };
+        const git = (args, stdin) => runGit(args, local, signal, stdin);
+        const remoteGit = (args) => runGit(args, network, signal);
+        await runGit(["init", "--quiet", "--bare", "--initial-branch=main", gitDir], local, signal);
+        // Blobs: raw bytes, loose objects, no clean/smudge or eol filters.
+        await mkdir(staging);
+        const paths = [];
+        for (const [at, file] of input.files.entries()) {
+            const path = join(staging, String(at));
+            await writeFile(path, file.contents);
+            paths.push(path);
+        }
+        const blobs = (await git(["hash-object", "-w", "--no-filters", "--stdin-paths"], `${paths.join("\n")}\n`))
+            .trim()
+            .split("\n");
+        if (blobs.length !== input.files.length ||
+            !blobs.every((b) => objectId.test(b)))
+            throw new Error("git did not write every template blob");
+        const index = input.files
+            .map((file, at) => `100644 ${blobs[at] ?? ""}\t${file.path}\0`)
+            .join("");
+        await git(["update-index", "-z", "--add", "--index-info"], index);
+        const tree = oid(await git(["write-tree"]));
+        const head = remoteMain(await remoteGit(["ls-remote", input.remote, "refs/heads/main"]));
+        let parents = [];
+        if (head !== null) {
+            await remoteGit([
+                ...looseFetch,
+                "fetch",
+                "--quiet",
+                "--depth=1",
+                "--no-tags",
+                input.remote,
+                "refs/heads/main",
+            ]);
+            if (oid(await git(["rev-parse", `${head}^{tree}`])) === tree)
+                return {
+                    seedRevision: parseSourceRevision(`git:${head}`),
+                    pushed: false,
+                };
+            parents = ["-p", head];
+        }
+        const commit = oid(await runGit([
+            "commit-tree",
+            tree,
+            ...parents,
+            "-m",
+            `Seed ${appId} from ${sourceRevision}`,
+        ], { ...local, ...seedIdentity }, signal));
+        await remoteGit([
+            ...wholeObjectPush,
+            "push",
+            "--quiet",
+            "--no-thin",
+            input.remote,
+            `${commit}:refs/heads/main`,
+        ]);
+        // A successful push is not sufficient: main must now name this commit.
+        if (remoteMain(await remoteGit(["ls-remote", input.remote, "refs/heads/main"])) !== commit)
+            throw new Error("Template main moved during the push");
+        return { seedRevision: parseSourceRevision(`git:${commit}`), pushed: true };
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}

package/dist/source/template-repository.d.ts

@@ -1,2 +1,4 @@
 /** Derive the private editable source repository from its validated App identity. */
 export declare function templateRepositoryForApp(appId: string): string;
+/** The App whose template `repository` is, or null when it names none. */
+export declare function appForTemplateRepository(repository: string): string | null;

package/dist/source/template-repository.js

@@ -1,4 +1,7 @@
 import { parseAppId } from "@fungi.computer/puffball";
+import { appIdSchema } from "@fungi.computer/puffball/effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 const TEMPLATE_REPOSITORY_PREFIX = "template-";
 /** Derive the private editable source repository from its validated App identity. */
 export function templateRepositoryForApp(appId) {
@@ -6,3 +9,13 @@ export function templateRepositoryForApp(appId) {
     // AppId's maximum 63-character suffix makes this repository at most 72 chars.
     return `${TEMPLATE_REPOSITORY_PREFIX}${parsed.slice("app_".length)}`;
 }
+/** The App whose template `repository` is, or null when it names none. */
+export function appForTemplateRepository(repository) {
+    if (!repository.startsWith(TEMPLATE_REPOSITORY_PREFIX))
+        return null;
+    const appId = Schema.decodeUnknownOption(appIdSchema)(`app_${repository.slice(TEMPLATE_REPOSITORY_PREFIX.length)}`);
+    return Option.isSome(appId) &&
+        templateRepositoryForApp(appId.value) === repository
+        ? appId.value
+        : null;
+}

package/dist/source/{template-write.d.ts → template-seed.d.ts}

@@ -1,12 +1,17 @@
 import * as Schema from "effect/Schema";
 import type { Artifacts } from "@fungi.computer/burrow";
 import type { PublisherTemplateSeedReceipts } from "./seed-receipt.js";
-/** A bounded operator source upload; decoding happens only at the Publisher boundary. */
-export declare const TEMPLATE_WRITE_MAX_REQUEST_BYTES: number;
-export declare const templateWriteInputSchema: Schema.Struct<{
+/** A seed claim is a few fields and one pinned recipe; the source itself
+ * arrived by `git push`. */
+export declare const TEMPLATE_SEED_CLAIM_MAX_BYTES: number;
+/** The operator's claim after pushing a projected source commit to the App's
+ * template: that `seedRevision` is that commit, projected from
+ * `sourceRevision`, and builds with `recipe`. */
+export declare const templateSeedClaimSchema: Schema.Struct<{
     readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
     readonly sourceRevision: Schema.refine<import("@fungi.computer/puffball").SourceRevision, Schema.String>;
     readonly sourceTreeDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
+    readonly seedRevision: Schema.refine<import("@fungi.computer/puffball").SourceRevision, Schema.String>;
     readonly recipe: Schema.Struct<{
         readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
         readonly bundle: Schema.Literal<true>;
@@ -33,24 +38,18 @@ export declare const templateWriteInputSchema: Schema.Struct<{
         }>]>;
         readonly target: Schema.Tuple<readonly [Schema.Literal<"es2022">]>;
     }>;
-    readonly files: Schema.$Array<Schema.Struct<{
-        readonly path: Schema.String;
-        readonly contents: Schema.Uint8ArrayFromBase64;
-    }>>;
 }>;
-export type TemplateWriteInput = Schema.Schema.Type<typeof templateWriteInputSchema>;
-/** The Publisher's own `exchangeGit` admission root (`source-git.ts`) stays the
- * sole caller of that physical transport; this port only ever sees a Request
- * in, a Response out, already bound to the one template repository. */
-export type TemplateSourceTransport = Readonly<{
-    ensureRepository: Artifacts["ensureRepository"];
-    exchangeTemplateGit(repository: string, request: Request): Promise<Response>;
-}>;
-/** The only operator template-write result contains provenance, never custody. */
-export declare function seedPublisherTemplate(receipts: PublisherTemplateSeedReceipts, transport: TemplateSourceTransport, rawAppId: string, request: Request): Promise<{
-    readonly kind: "invalid" | "too-large";
-    readonly receipt?: undefined;
-} | {
+export type TemplateSeedClaim = Schema.Schema.Type<typeof templateSeedClaimSchema>;
+/** Decode one claim body at its I/O boundary, strictly; null when it is not
+ * exactly a seed claim. */
+export declare function parseTemplateSeedClaim(body: string): TemplateSeedClaim | null;
+/**
+ * Record the seed receipt for a template the operator already pushed. The
+ * template's current `main` must be exactly the claimed seed commit, whose
+ * hash pins its tree and history; the recipe digest is computed here; an
+ * existing receipt for that commit must carry the same provenance.
+ */
+export declare function recordTemplateSeed(receipts: PublisherTemplateSeedReceipts, artifacts: Pick<Artifacts, "readDefaultBranchHead">, rawAppId: string, claim: TemplateSeedClaim): Promise<{
     readonly kind: "conflict";
     readonly receipt?: undefined;
 } | {

package/dist/source/template-seed.js

@@ -0,0 +1,80 @@
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { parseAppId } from "@fungi.computer/puffball";
+import { appIdSchema, sha256DigestSchema, sourceRevisionSchema, } from "@fungi.computer/puffball/effect";
+import { capturedPinnedRecipeSchema, digestPinnedRecipe, } from "../build-contract.js";
+import { templateRepositoryForApp } from "./template-repository.js";
+/** A seed claim is a few fields and one pinned recipe; the source itself
+ * arrived by `git push`. */
+export const TEMPLATE_SEED_CLAIM_MAX_BYTES = 64 * 1024;
+/** The operator's claim after pushing a projected source commit to the App's
+ * template: that `seedRevision` is that commit, projected from
+ * `sourceRevision`, and builds with `recipe`. */
+export const templateSeedClaimSchema = Schema.Struct({
+    appId: appIdSchema,
+    sourceRevision: sourceRevisionSchema,
+    sourceTreeDigest: sha256DigestSchema,
+    seedRevision: sourceRevisionSchema,
+    recipe: capturedPinnedRecipeSchema,
+});
+/** Decode one claim body at its I/O boundary, strictly; null when it is not
+ * exactly a seed claim. */
+export function parseTemplateSeedClaim(body) {
+    const decoded = Schema.decodeUnknownOption(Schema.fromJsonString(templateSeedClaimSchema), { onExcessProperty: "error" })(body);
+    return Option.isSome(decoded) ? decoded.value : null;
+}
+function logEvent(operation, cause) {
+    console.error(JSON.stringify({
+        source: "app-source",
+        operation,
+        failureKind: cause instanceof Error ? "Error" : "NonErrorThrown",
+    }));
+}
+/**
+ * Record the seed receipt for a template the operator already pushed. The
+ * template's current `main` must be exactly the claimed seed commit, whose
+ * hash pins its tree and history; the recipe digest is computed here; an
+ * existing receipt for that commit must carry the same provenance.
+ */
+export async function recordTemplateSeed(receipts, artifacts, rawAppId, claim) {
+    try {
+        const appId = parseAppId(rawAppId);
+        if (claim.appId !== appId)
+            return { kind: "conflict" };
+        const repository = templateRepositoryForApp(appId);
+        const head = await artifacts.readDefaultBranchHead(repository);
+        if (head === null || `git:${head}` !== claim.seedRevision)
+            return { kind: "conflict" };
+        const receipt = {
+            appId,
+            sourceRevision: claim.sourceRevision,
+            sourceTreeDigest: claim.sourceTreeDigest,
+            seedRevision: claim.seedRevision,
+            recipe: claim.recipe,
+            buildRecipeDigest: digestPinnedRecipe(claim.recipe),
+        };
+        const existing = await receipts.read(appId, claim.seedRevision);
+        if (existing !== null &&
+            (existing.sourceRevision !== receipt.sourceRevision ||
+                existing.sourceTreeDigest !== receipt.sourceTreeDigest ||
+                existing.buildRecipeDigest !== receipt.buildRecipeDigest))
+            return { kind: "conflict" };
+        // The write-once, digest-checked receipt owner records it.
+        await receipts.record(receipt);
+        return {
+            kind: existing === null ? "recorded" : "existing",
+            receipt: {
+                appId,
+                repository,
+                sourceRevision: receipt.sourceRevision,
+                sourceTreeDigest: receipt.sourceTreeDigest,
+                seedRevision: receipt.seedRevision,
+                buildRecipeDigest: receipt.buildRecipeDigest,
+            },
+        };
+    }
+    catch (cause) {
+        logEvent("operator.template.record", cause);
+        return { kind: "unavailable" };
+    }
+}

package/dist/standalone/agent-directory.d.ts

@@ -0,0 +1,4 @@
+import type { TenantScope } from "../tenant.js";
+import type { StandaloneAgentsEnv } from "./agents.js";
+/** Host-only lookup from the already selected frame tenant; never derive it from an App or caller. */
+export declare function agentDirectoryForScope(env: Pick<StandaloneAgentsEnv, "AGENT_DIRECTORY">, scope: Pick<TenantScope, "durableName">): DurableObjectStub<import("./agents.js").AgentDirectory>;

package/dist/standalone/agent-directory.js

@@ -0,0 +1,4 @@
+/** Host-only lookup from the already selected frame tenant; never derive it from an App or caller. */
+export function agentDirectoryForScope(env, scope) {
+    return env.AGENT_DIRECTORY.getByName(scope.durableName("agents"));
+}

package/dist/standalone/agents.d.ts

@@ -0,0 +1,227 @@
+import { type StandaloneTenancyEnv } from "./tenancy.js";
+import { DurableObject } from "cloudflare:workers";
+import type { StandaloneComputerEnv } from "./computer.js";
+import { ShiitakeDO } from "@fungi.computer/shiitake/cloudflare";
+import type { CloudflareShiitakeOptions } from "@fungi.computer/shiitake/cloudflare";
+import { type AiBinding } from "@earendil-works/pi-ai/api/cloudflare-ai-binding";
+import * as Schema from "effect/Schema";
+import { type FrameBindingProps } from "../cloudflare.js";
+import type { Avatar } from "@fungi.computer/sprite/avatar";
+import type { InvocationFrame } from "../invocation.js";
+import type { OysterJson } from "../host.js";
+import { type FleetMessage } from "@fungi.computer/shiitake/fleet";
+import { type AppToolPolicy } from "../apps/index.js";
+import { type OysterPrincipal, type OysterHost } from "../host.js";
+import { type TenantScope, type TenantId } from "../tenant.js";
+import type { ReadonlyTenancy } from "../tenancy/index.js";
+import type { HostActor } from "@fungi.computer/puffball/app";
+import type { OysterWorkerEnv } from "../workers.js";
+import { type AgentMcpServer, type AgentMcpServerInput, type AgentMcpServerRefusal } from "../agents.js";
+import type { AgentPolicyActor, OysterAgents, OysterSessionRow } from "../agents.js";
+/** The model door an agent runs on; Shiitake's own contract. */
+export type StandaloneModelSource = CloudflareShiitakeOptions["model"];
+/** One directory entry: an agent's id, display name and own avatar. */
+export type AgentEntry = Readonly<{
+    agentId: string;
+    name: string;
+    avatar: Avatar;
+}>;
+/** Bindings the agent host reads. */
+export type StandaloneAgentsEnv = Readonly<{
+    /** Configured standalone-owner identity subject; never a stored member ID. */
+    OYSTER_OWNER_NAME?: string;
+    /** Gateway custody remains in Veil; only the host receives these bindings. */
+    AI_GATEWAY_AUTH_TOKEN?: string;
+    AI_GATEWAY_ACCOUNT_ID?: string;
+    AI_GATEWAY_ID?: string;
+    /** Workers AI, the default model door. */
+    AI?: AiBinding;
+    /** The model: `@fungi/luna` via AI Gateway, or a Workers AI id (default {@link defaultAgentModel}). */
+    OYSTER_AGENT_MODEL?: string;
+    /** The AI Gateway the binding routes through (default `default`). */
+    OYSTER_AI_GATEWAY?: string;
+    /** Maintained current-member authority; absent means no nondefault-tenant policy admission. */
+    TENANCY?: Pick<ReadonlyTenancy, "memberById">;
+    TENANTS?: StandaloneTenancyEnv["TENANTS"];
+    KEYS?: StandaloneTenancyEnv["KEYS"];
+    OYSTER_ORIGIN: string;
+    OYSTER_OWNER_KEY?: string;
+    AGENTS: DurableObjectNamespace<StandaloneAgentBase>;
+    /** Host-only directory custody. Guest entrypoints expose operations, not this binding; Codemode receives only Mycelium modules. */
+    AGENT_DIRECTORY: DurableObjectNamespace<AgentDirectory>;
+}>;
+/** An agent host's whole env: its own bindings and the Oyster's. */
+export type StandaloneAgentEnv = StandaloneAgentsEnv & OysterWorkerEnv & StandaloneComputerEnv;
+declare const policyDirectorySchema: Schema.Struct<{
+    readonly directoryName: Schema.NonEmptyString;
+    readonly tenantId: Schema.brand<Schema.String, "OysterTenantId">;
+}>;
+/** A row of this agent's own inbox, before the directory names the agent. */
+export type AgentInboxRows = Readonly<{
+    rows: readonly OysterSessionRow[];
+    revision: number;
+}>;
+/** One agent: Shiitake's Cloudflare host over this Durable Object; its root supplies `hostFor`. */
+export declare abstract class StandaloneAgentBase<Env extends StandaloneAgentEnv = StandaloneAgentEnv> extends ShiitakeDO<Env> {
+    #private;
+    /** The deployable root's host for this Agent's pinned tenant. */
+    protected abstract hostFor(scope: TenantScope): OysterHost;
+    /** The root host for this Agent's pinned policy directory; unpinned Agents have no App tools. */
+    private appHost;
+    /** Choose this agent's model door; override to plug in another. */
+    protected modelSource(): StandaloneModelSource;
+    /** Host-only initialization; Agent/App transports never receive this directory binding. */
+    usePolicyDirectory(input: {
+        directoryName: string;
+        tenantId: TenantId;
+    }): Promise<void>;
+    /** Host-only policy pin read, used before an owner can approve tools. */
+    policyDirectory(): Promise<typeof policyDirectorySchema.Type | null>;
+    /** Listeners from live codemode acquisitions, told when the server list changes. */
+    private readonly mcpInvalidations;
+    private storedMcpServers;
+    private writeMcpServers;
+    /** Host-only: this Agent's MCP servers, without their bearer tokens. */
+    mcpServers(): Promise<readonly AgentMcpServer[]>;
+    /** Host-only: connect one remote MCP server, admitted by the owner route. */
+    addMcpServer(input: AgentMcpServerInput): Promise<AgentMcpServer | AgentMcpServerRefusal>;
+    /** Host-only: disconnect one MCP server. */
+    removeMcpServer(serverId: string): Promise<boolean>;
+    protected shiitakeOptions(): CloudflareShiitakeOptions;
+    /** Send an installation-admitted message through fleet Session operations. */
+    sendFromApp(installationId: string, sessionId: string, message: FleetMessage): Promise<{
+        sessionId: string;
+        status: "accepted";
+        commandId: string;
+    }>;
+    /** Latest inbox clock from the same Shiitake owner, without reading Session rows. */
+    revision(): Promise<number>;
+    /** Every live Session of this agent, as inbox rows. */
+    inboxRows(): Promise<AgentInboxRows>;
+}
+/** Names this Oyster's agents and remembers which Sessions the member opened. */
+export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
+    private readonly directory;
+    private readonly avatars;
+    private composedTenancy;
+    private grant;
+    constructor(ctx: DurableObjectState, env: StandaloneAgentEnv);
+    list(): readonly AgentEntry[];
+    has(agentId: string): boolean;
+    /** Resolve the existing recorded creator for host-side owner admission. */
+    readCreator(agentId: string): string | null;
+    /** Owner-only rename; refuses a name already held by another Agent. */
+    rename(agentId: string, name: string, principal: OysterPrincipal): AgentEntry | Readonly<{
+        error: "not_found" | "name_taken" | "not_granted";
+    }>;
+    /** Owner-only avatar change; the Agent wears it in every App and list. */
+    setAvatar(agentId: string, avatar: Avatar, principal: OysterPrincipal): AgentEntry | Readonly<{
+        error: "not_found" | "not_granted";
+    }>;
+    create(name: string, requestId: string, principal: OysterPrincipal, actor: AgentPolicyActor, avatar?: Avatar): AgentEntry & {
+        policyRevision: string | null;
+    };
+    private writePolicy;
+    private storedPolicy;
+    private readPolicy;
+    /** Current revision for the direct owner's compare-and-swap request. */
+    policyRevision(agentId: string): string | null;
+    /** Whether this Agent's App-tool policy still awaits the owner's approval. */
+    policyStatus(agentId: string): Readonly<{
+        status: "pending" | "approved";
+        revision: string;
+    }> | null;
+    private currentMember;
+    /** Approval stays revoked after any membership authority revision. */
+    appToolPolicy(actor: Extract<HostActor, {
+        kind: "agent";
+    }>, tenantId?: TenantId): Promise<AppToolPolicy | null>;
+    /** Only direct human approval records an authenticated canonical grantor. */
+    approveAppToolPolicy(agentId: string, principal: OysterPrincipal, level: AppToolPolicy["level"], expectedRevision: string | null, actor: AgentPolicyActor, tenantId: TenantId): Promise<Awaited<ReturnType<OysterAgents["approveAppToolPolicy"]>>>;
+    visit(agentId: string, sessionId: string): void;
+    visits(): readonly Readonly<{
+        agentId: string;
+        sessionId: string;
+        visitedAt: number;
+    }>[];
+    /** Grows on every directory change (a new agent, a visit). */
+    revision(): number;
+    private bump;
+}
+/** The `agents` adapter over a Worker's agent bindings. */
+export declare function standaloneAgents(env: StandaloneAgentsEnv, scope?: TenantScope): OysterAgents;
+/** Shared packet codecs; the Instance alone admits the current frame's operations. */
+export declare const agentFrameMethods: {
+    INBOX: {
+        page: {
+            decodeArgs: (raw: readonly unknown[]) => [({
+                after?: string | null | undefined;
+            } | undefined)?];
+            decodeResult: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+                readonly items: readonly ({
+                    readonly agentId: string;
+                    readonly title: string;
+                    readonly state: "done" | "running" | "needs_you" | "errored";
+                    readonly createdAt: number;
+                    readonly sessionId: string;
+                    readonly lastActivityAt: number;
+                    readonly triggerId?: string | undefined;
+                    readonly settledAt?: number | undefined;
+                    readonly visitedAt?: number | undefined;
+                } | {
+                    readonly agentId: string;
+                    readonly sessionId: string;
+                    readonly state: "unavailable";
+                } | {
+                    readonly key: {
+                        readonly runId: string;
+                        readonly nodeId: string;
+                        readonly iteration: string;
+                    };
+                    readonly kind: "workflow-review";
+                    readonly installationId: string;
+                    readonly state: "pending" | "delivered" | "answered" | "timed_out" | "closed";
+                    readonly workflowId: string | null;
+                    readonly workflowTitle: string;
+                    readonly reviewTitle: string;
+                    readonly reviewers: "runner" | "owners";
+                    readonly show: readonly Schema.Json[];
+                    readonly openedAt: number;
+                    readonly expiresAt: number;
+                    readonly choices?: readonly string[] | undefined;
+                })[];
+                readonly next: null;
+                readonly cursor: number;
+            };
+            requiredOperations: () => string[];
+        };
+        visit: {
+            decodeArgs: (raw: readonly unknown[]) => [{
+                agentId: string;
+                sessionId: string;
+            }];
+            decodeResult: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+                readonly visited: true;
+            };
+            requiredOperations: () => string[];
+        };
+    };
+    AGENTS: {
+        send: {
+            decodeArgs: (raw: readonly unknown[]) => [{
+                agentId: string;
+                sessionId: string;
+                text: string;
+                delivery: "followUp";
+            }];
+            decodeResult: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Readonly<{
+                status: "accepted";
+                commandId: string;
+            }>;
+            requiredOperations: () => string[];
+        };
+    };
+};
+/** Provider effects are admitted by the originating Instance's live frame. */
+export declare function dispatchAgentBinding(env: StandaloneAgentsEnv, scope: TenantScope, frame: InvocationFrame, props: FrameBindingProps, method: string, args: readonly unknown[]): Promise<OysterJson>;
+export {};