Skip to content
Oyster0.6.0
API reference

agents

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/oyster/agents";

Exports

Section titled “Exports”
Kind Export Description
type alias OysterAgent One agent as Apps see it, in Agar’s appAgentSchema shape.
type alias OysterSessionRow An Agent owner’s Session facts before the member identity and visit are added.
type alias OysterInboxItem Both hosts expose the same Inbox item vocabulary.
type alias OysterInbox The whole inbox at one revision; the revision only grows.
type alias AgentPolicyActor Host-attested source of a policy request; request headers are not this fact.
type alias PendingAgentPolicy An App’s requested tools await the owner’s direct approval.
type alias AgentMcpServer One remote MCP server connected to an Agent; its bearer token is never returned.
type alias AgentMcpServerInput An owner’s request to connect one remote MCP server to an Agent.
type alias AgentMcpServerRefusal Why connecting an MCP server was refused.
type alias AgentToolPolicyStatus This Agent’s App-tool policy, in the shape Apps read it.
type alias OysterAgents Where an Oyster’s agents live and run.
type alias AgentModelChoice The Agent’s model preference and source reference, never credential material.
type alias AgentModelRefusal Stable reason for rejecting a model or credential source before a run.
constant maxAgentMcpServers At most this many MCP servers per Agent.
constant agentMcpServerInputSchema Owner input for one MCP server: a guest identifier, an https: endpoint and an optional bearer.
function agentCapabilities() Agent adapters admitted against each App’s declared capabilities.
function agentApprovalRoutes() Host-owned direct approval under the admitted owner; never an App capability.
function agentMcpServerRoutes() Host-owned Agent MCP server custody for the owner directly; never an App capability. Bearer tokens go in and never come back out.

OysterAgenttype alias

Section titled “OysterAgent”
Signature
type OysterAgent = Readonly<{
  agentId: string;
  name: string;
  avatar: Avatar;
  sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
}>;

One agent as Apps see it, in Agar’s appAgentSchema shape.

OysterSessionRowtype alias

Section titled “OysterSessionRow”
Signature
type OysterSessionRow =
  | Omit<
      Extract<
        MemberInboxSession,
        {
          title: string;
        }
      >,
      "agentId" | "visitedAt"
    >
  | Omit<
      Extract<
        MemberInboxSession,
        {
          state: "unavailable";
        }
      >,
      "agentId"
    >;

An Agent owner’s Session facts before the member identity and visit are added.

OysterInboxItemtype alias

Section titled “OysterInboxItem”
Signature
type OysterInboxItem = MemberInboxItem;

Both hosts expose the same Inbox item vocabulary.

OysterInboxtype alias

Section titled “OysterInbox”
Signature
type OysterInbox = Readonly<{
  items: readonly OysterInboxItem[];
  revision: number;
}>;

The whole inbox at one revision; the revision only grows.

AgentPolicyActortype alias

Section titled “AgentPolicyActor”
Signature
type AgentPolicyActor =
  | "owner-direct"
  | Readonly<{
      installationId: string;
    }>;

Host-attested source of a policy request; request headers are not this fact.

PendingAgentPolicytype alias

Section titled “PendingAgentPolicy”
Signature
type PendingAgentPolicy = Readonly<{
  status: "pending";
  revision: string;
}>;

An App’s requested tools await the owner’s direct approval.

AgentMcpServertype alias

Section titled “AgentMcpServer”
Signature
type AgentMcpServer = Readonly<{
  serverId: string;
  name: string;
  url: string;
  hasBearer: boolean;
}>;

One remote MCP server connected to an Agent; its bearer token is never returned.

AgentMcpServerInputtype alias

Section titled “AgentMcpServerInput”
Signature
type AgentMcpServerInput = typeof agentMcpServerInputSchema.Type;

An owner’s request to connect one remote MCP server to an Agent.

AgentMcpServerRefusaltype alias

Section titled “AgentMcpServerRefusal”
Signature
type AgentMcpServerRefusal = Readonly<{
  error: "not_found" | "duplicate_name" | "limit";
}>;

Why connecting an MCP server was refused.

AgentToolPolicyStatustype alias

Section titled “AgentToolPolicyStatus”
Signature
type AgentToolPolicyStatus = Readonly<{
  status: "pending" | "approved";
  revision: string;
}>;

This Agent’s App-tool policy, in the shape Apps read it.

OysterAgentstype alias

Section titled “OysterAgents”
Signature
type OysterAgents = Readonly<{
  list: Promise<
    readonly Readonly<{
      agentId: string;
      name: string;
      avatar: Avatar;
      sessionOperations: readonly (
        "agent.read" | "agent.send" | "agent.manage"
      )[];
    }>[]
  >;
  create: Promise<
    Readonly<{
      agentId: string;
      name: string;
      avatar: Avatar;
      sessionOperations: readonly (
        "agent.read" | "agent.send" | "agent.manage"
      )[];
    }>
  >;
  rename: Promise<
    | Readonly<{
        agentId: string;
        name: string;
        avatar: Avatar;
        sessionOperations: readonly (
          "agent.read" | "agent.send" | "agent.manage"
        )[];
      }>
    | Readonly<{
        error: "not_found" | "name_taken" | "not_granted";
      }>
  >;
  setAvatar: Promise<
    | Readonly<{
        agentId: string;
        name: string;
        avatar: Avatar;
        sessionOperations: readonly (
          "agent.read" | "agent.send" | "agent.manage"
        )[];
      }>
    | Readonly<{
        error: "not_found" | "not_granted";
      }>
  >;
  readModelChoice: Promise<{
    keySource: "workers-ai" | "ai-gateway" | "byok";
    model: {
      providerId: Schema.String;
      modelId: Schema.String;
      reasoning?: Schema.optional<
        Schema.Literals<
          readonly ["minimal", "low", "medium", "high", "xhigh", "max"]
        >
      >;
    };
  } | null>;
  decodeModelChoice: {
    keySource: "workers-ai" | "ai-gateway" | "byok";
    model: {
      providerId: Schema.String;
      modelId: Schema.String;
      reasoning?: Schema.optional<
        Schema.Literals<
          readonly ["minimal", "low", "medium", "high", "xhigh", "max"]
        >
      >;
    };
  } | null;
  setModelChoice: Promise<
    | {
        keySource: "workers-ai" | "ai-gateway" | "byok";
        model: {
          providerId: Schema.String;
          modelId: Schema.String;
          reasoning?: Schema.optional<
            Schema.Literals<
              readonly ["minimal", "low", "medium", "high", "xhigh", "max"]
            >
          >;
        };
      }
    | Readonly<{
        error: "not_found" | "not_granted" | AgentModelRefusal;
      }>
  >;
  policyStatus: Promise<Readonly<{
    status: "pending" | "approved";
    revision: string;
  }> | null>;
  appToolPolicy: Promise<{
    level: "read" | "write";
    revision: string;
    grantedBy: string;
  } | null>;
  policyRevision: Promise<string | null>;
  approveAppToolPolicy: Promise<
    | {
        level: "read" | "write";
        revision: string;
        grantedBy: string;
      }
    | Readonly<{
        status: "pending";
        revision: string;
      }>
    | Readonly<{
        error: "not_found" | "revision_conflict" | "not_granted";
      }>
  >;
  mcpServers: Promise<
    | readonly Readonly<{
        serverId: string;
        name: string;
        url: string;
        hasBearer: boolean;
      }>[]
    | null
  >;
  addMcpServer: Promise<
    | Readonly<{
        serverId: string;
        name: string;
        url: string;
        hasBearer: boolean;
      }>
    | Readonly<{
        error: "not_found" | "duplicate_name" | "limit";
      }>
  >;
  removeMcpServer: Promise<boolean>;
  fetch: Promise<Response | null>;
  inbox: Promise<
    Readonly<{
      items: readonly OysterInboxItem[];
      revision: number;
    }>
  >;
  revision: Promise<number>;
  visit: Promise<boolean>;
}>;

Where an Oyster’s agents live and run.

AgentModelChoicetype alias

Section titled “AgentModelChoice”
Signature
type AgentModelChoice = typeof agentModelChoiceSchema.Type;

The Agent’s model preference and source reference, never credential material.

AgentModelRefusaltype alias

Section titled “AgentModelRefusal”
Signature
type AgentModelRefusal =
  | "invalid_model_choice"
  | "unsupported_key_source"
  | "key_source_mismatch"
  | "model_unavailable"
  | "key_not_connected";

Stable reason for rejecting a model or credential source before a run.

maxAgentMcpServersconstant

Section titled “maxAgentMcpServers”
Signature
const maxAgentMcpServers: 16 = 16;

At most this many MCP servers per Agent.

agentMcpServerInputSchemaconstant

Section titled “agentMcpServerInputSchema”
Signature
const agentMcpServerInputSchema: Struct<{
  name: String;
  url: String;
  bearer: NullOr<String>;
}>;

Owner input for one MCP server: a guest identifier, an https: endpoint and an optional bearer.

agentCapabilities()function

Section titled “agentCapabilities()”
Signature
function agentCapabilities(
  agents,
  liveKey,
): readonly Readonly<object & object>[];

Agent adapters admitted against each App’s declared capabilities.

Parameters

Section titled “Parameters”
Parameter Type
agents OysterAgents
liveKey (keyId) => Promise< | Readonly<{ keyId: string; owner: string; grantVersion: number; grants: readonly Readonly<{ capability: OysterKeyCapability; targets: GrantTargets; }>[]; }> | null>

Returns

Section titled “Returns”

readonly Readonly<object & object>[]

agentApprovalRoutes()function

Section titled “agentApprovalRoutes()”
Signature
function agentApprovalRoutes(agents): Hono<OysterEnv>;

Host-owned direct approval under the admitted owner; never an App capability.

Parameters

Section titled “Parameters”
Parameter Type
agents OysterAgents

Returns

Section titled “Returns”

Hono<OysterEnv>

agentMcpServerRoutes()function

Section titled “agentMcpServerRoutes()”
Signature
function agentMcpServerRoutes(agents): 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.

Parameters

Section titled “Parameters”
Parameter Type
agents OysterAgents

Returns

Section titled “Returns”

Hono<OysterEnv>