@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/standalone/agents.d.ts

@@ -0,0 +1,220 @@
+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 { 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 and display name. */
+export type AgentEntry = Readonly<{
+    agentId: string;
+    name: string;
+}>;
+/** 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 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";
+    }>;
+    create(name: string, requestId: string, principal: OysterPrincipal, actor: AgentPolicyActor): 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 kind: "workflow-review";
+                    readonly installationId: string;
+                    readonly key: {
+                        readonly runId: string;
+                        readonly nodeId: string;
+                        readonly iteration: 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 {};