API reference

agar

Import

import * as api from "@fungi.computer/agar";

Exports

Kind	Export	Description
type alias	FungiAuthor	Who a Session line came from, as the admitting host authenticated them.
type alias	FungiDelegationReply	A delegated Agent’s reply as the admitting host authenticated it.
type alias	FungiMessageMeta	The metadata the host attaches to every prompt and operator line it admits.
type alias	MessageMetaValue	Any JSON value, as Shiitake returns a message’s metadata.
type alias	AuthorMeta	The metadata the host attaches for one authenticated author, as JSON.
type alias	AppAgent	An Agent record as decoded from the host: its id, display name, and which session operations this App is permitted to perform on it.
type alias	AppAgentCreateInput	Input for creating a new Agent: its name, a caller-chosen request id for idempotency, whether to provision a new Computer for it, and the avatar it wears (omitted, it wears its seeded avatar).
type alias	AppAgentTransportHandle	Live object-capability shape received from Cap’n Web.
type alias	AppAgentListHandle	Capability handle for listing the Agents in a directory.
type alias	AppAgentCreateHandle	Capability handle for creating a new Agent in a directory.
type alias	AppAgentDirectoryHandle	Live capability handle for listing and creating Agents in a Team or local-project directory, and opening transports to them.
type alias	AppAgentRenameInput	Input for renaming an existing Agent: its id and the owner’s chosen replacement display name.
type alias	AppAgentRenameHandle	Capability handle for renaming an Agent the owner already created.
type alias	AppAgentAvatarInput	Input for changing an existing Agent’s avatar.
type alias	AppAgentAvatarHandle	Capability handle for changing an Agent’s avatar.
type alias	AppAgentToolPolicyStatus	Whether an Agent’s App tools are still pending the owner’s approval.
type alias	AppAgentToolPolicyResult	The outcome of an owner’s direct App-tool approval.
type alias	AppAgentToolPolicyHandle	Capability handle for reading and approving an Agent’s App-tool policy.
type alias	AppAgentTransport	A Fetch-based transport to one Agent’s session endpoint, scoped to this App and safe to hand to an HTTP client adapter.
type alias	CapabilityContract	A capability owner’s frozen, typed descriptor. Descriptor identity is not authority.
type alias	CapabilityDirectory	The App’s read-only view of its currently admitted capabilities.
type alias	CapabilityRegistry	Local capabilities admitted through their owner’s typed contract.
type alias	AppCommand	Semantic command metadata supplied by an App and owned by Whistle.
type alias	AppCommandHandler	One invocation’s semantic input; host correlation IDs are private.
type alias	AppCommandInvocation	One command invocation’s semantic input, passed to its handler.
type alias	AppCommands	Registers a command with the authenticated host for this page session. The promise resolves only after the host accepts the registration.
type alias	ConnectAppOptions	Options for connecting this iframe page to its authenticated host.
type alias	AppConnectMessage	The host’s handshake message that hands the App its RPC MessagePort.
type alias	AppReadyMessage	The App iframe’s handshake message announcing it is ready to connect.
type alias	AppContext	The host-published state surrounding a connected App: its Computer selection, focus, visibility, and any pending open request.
type alias	AppOpenRequest	One host-issued action an App must act on when it opens or reconfigures: start composing given text, or navigate to the given params. Each carries a `requestId` so the App can tell a repeated open from a fresh one.
type alias	AppIdentity	The App’s own identity, as admitted by its host.
type alias	AppLifecycle	The connection state of this App’s session with its host.
type alias	FocusState	Whether the App’s own surface is being edited and which surface, if any, the host considers focused.
type alias	MediaGenerationInput	The Media owner decides Team, Installation, Release, Grant and Computer authority before issuing this handle. The App contributes only generation settings and selected destination/references. The IDs in those selections are not authority: the host revalidates every one against its current admitted Computer scope when it accepts a generation.
type alias	MediaOutputFormat	The encodings a completed generation can be saved as.
type alias	MediaGenerationResult	Metadata for one completed generation: the saved destination, pixel dimensions, format, model used, and its cost.
type alias	MediaGenerationFailure	The host’s typed reason a generation failed: code, message, retry truth and, when known, the stage that failed.
type alias	MediaGenerationOutcome	Transport-safe result from the host-owned generation attempt.
type alias	MediaGenerationHandle	Live object-capability shape supplied by the host.
type alias	MediaGenerationAttemptHandle	Host-supplied object-capability for one attempt, before Agar wraps it into the typed MediaGenerationAttempt.
type alias	MediaGenerationAttempt	One generation attempt: a stable reference plus the ability to run (or retry) generation against it until disposed.
type alias	MediaGenerationSession	The validated, App-facing handle returned by openMediaGeneration: the Computer’s model catalog plus the ability to start or resume attempts.
type alias	MediaGenerationReference	An opaque replay identity for one attempt; it identifies a request, not an authorization to use it.
type alias	MediaModel	One generation model as the host describes it: identity, tier, input limits and supported output formats. The host owns the catalog.
type alias	MediaGenerationSelection	An App’s generation settings: model, prompt, size and optional steps, duration and Computer-relative reference paths.
type alias	Pending	The shared polling result, owned by the App contract.
type alias	AppRoot	The App’s live connection to its host: its admitted capabilities, commands, context, theme, UI door and window, all torn down together by `dispose`. Returned by `connectApp` and passed to `mountApp`.
type alias	Disposer	Releases a subscription or other held resource. Call once; further calls are a no-op.
type alias	ReadonlyStore	A retained SDK-owned snapshot.
type alias	HostUi	Deliberately narrow shell affordances; domain work belongs to capabilities.
type alias	AppStatusIcon	The marks a host can draw before a status button’s label.
type alias	AppStatusTone	A readout’s live state, shown as a small light before its text.
type alias	AppStatusOption	One choice in a status menu, such as a folder or a port.
type alias	AppStatusItem	One item an App declares for its window’s status bar, as data: a readout, a button, a toggle, or a menu of choices. Using one delivers an AppStatusAction back to the App.
type alias	AppStatusAction	The person used a status item; `optionId` names a chosen menu option. `anchor` is where the item sits along the App’s surface, in CSS pixels from its inline start, so App UI it opens can sit above it.
type alias	AppStatusActionHandler	Handles one status action; `true` when the App acted on it.
type alias	AgentSessionSelection	Exact Agent conversation selected by an App for the authenticated shell.
type alias	FileNavigationInput	A presentation-neutral request to open an already admitted Computer file.
type alias	ToastInput	A transient notification an App asks its host to show.
type alias	AgentAccessOperation	Agent rights an App may ask its host to grant through consent.
type alias	ComputerAccessOperation	Computer rights an App may ask its host to grant through consent.
type alias	AppPermissionRequest	The rights an App asks for; the host bounds them by its declared ceiling.
type alias	AppPermissionOutcome	`granted`: the host saved a grant covering the request. `declined`: the user said not now. `customize`: the host opened its full permission settings.
type alias	AppBrowserAction	Data only; browser authority and the gesture check belong to the host.
type alias	AppBrowserActionRefusal	A browser action can be refused without disconnecting the App.
type alias	AppBrowserActionOutcome	Saved means a browser download was initiated, not a confirmed disk write.
type alias	BeforeAppClose	Consulted before the person closes the App’s window; return (or resolve) `true` to allow the close.
type alias	AppCrumb	One place in the App’s path; `siblings` makes it a switcher.
type alias	AppHeaderCommand	A command the App offers in its window header; the App owns its effect.
type alias	AppHeaderStatus	A quiet fact about the view, shown as muted text with a status bead.
type alias	AppNavigationActivation	The person used a crumb (or a switcher’s sibling) or a header command.
type alias	AppNavigationActivationHandler	Handles one activation; `true` when the App acted on it.
type alias	AppNavigationState	What the App’s own router can do right now. The App owns its history; the host only offers a Back affordance and relays the person’s request.
type alias	AppBackHandler	Go back one step in the App’s own history; `true` when it moved.
type alias	HostNavigation	The App’s half of the host navigation contract.
type alias	AppWindow	App-owned presentation policy consulted before a user closes its window.
type alias	ResultRow	One shared result row; navigation and previews stay host-authorized.
constant	FungiAuthorSchema	Who a Session line came from, as the admitting host authenticated them.
constant	FungiDelegationReplySchema	A delegated Agent’s reply as the admitting host authenticated it against the mail it sent. `commandId` is the replying Session’s accepted command, the same id as the sender’s `agents.send` receipt.
constant	FungiMessageMetaSchema	The metadata the host attaches to every prompt and operator line it admits. Shiitake stores it opaquely; the host writes it and Apps read it.
constant	appAgentAvatarSchema	An Agent’s avatar: Sprite’s Avatar v1 envelope. Apps check its shape; the host owns the character-catalog refinement when it stores one.
constant	appAgentSchema	Validates the wire shape of an Agent record: its id, display name, avatar, and which session operations (read, send, manage) this App may perform on it. Every Agent has an avatar: the one its owner chose, else Sprite’s `seededAvatar(agentId)`. Conversations carry none of their own.
constant	appAgentCreateInputSchema	Validates Agent creation input: a name, a caller-chosen request id, an optional Computer provisioning choice and an optional chosen avatar.
constant	agentList	Capability to list the Agents visible to this App in read-only form.
constant	agentManage	Capability to create new Agents and open transports to them.
constant	appAgentRenameInputSchema	Validates Agent rename input: the target Agent and its new display name.
constant	agentRename	Owner-only capability to rename an existing Agent; not every host grants it.
constant	appAgentAvatarInputSchema	Validates avatar input: the target Agent and the avatar it now wears.
constant	agentAvatar	Owner-only capability to change an existing Agent’s avatar; not every host grants it.
constant	appAgentToolPolicyStatusSchema	One Agent’s App-tool policy, as the owner-only policy capability reports it.
constant	appAgentToolPolicyResultSchema	The outcome of an owner’s direct App-tool approval.
constant	agentToolPolicy	Owner-only capability to read and approve an Agent’s App-tool policy.
constant	agentSessionRead	Capability for read-only Agent sessions: open a transport to an existing Agent, or read the member’s inbox feed.
constant	agentSessionWrite	Capability for read-write Agent sessions: open a transport to an existing Agent and send to it, including the member’s inbox feed.
constant	approvals	Member-bound approval view. Authentication and current rights belong to the host.
constant	APP_PROTOCOL_VERSION	The iframe handshake version both App and host must speak.
constant	APP_READY_TYPE	Message type the App iframe posts to announce it is ready to connect.
constant	APP_CONNECT_TYPE	Message type the host posts to hand the App its RPC MessagePort.
constant	appDeliveryPendingSchema	Effect projection of the error owner’s declaration-safe pending refusal.
constant	parseAppStatusItems	Both edges: one window’s status items, bounded and copied.
constant	parseAppStatusAction	App edge: the status item the person used, as the host relays it.
constant	mediaGenerationReferenceSchema	A replay identity, never an authorization capability.
constant	mediaModelSchema	Validates one model row of the host’s Media catalog.
constant	mediaGenerationSelectionSchema	Validates the shape of an App’s generation settings. Model-specific limits (sizes, steps, durations, reference counts) and defaults are the host’s: it checks the selection against its catalog when it accepts a generation.
constant	mediaGenerationFailureSchema	Validates the typed failure a host reports for a generation attempt.
constant	mediaGeneration	Capability contract for generating Media (images or video). Apps declare it to request access; openMediaGeneration uses it to obtain the host’s handle.
constant	pendingSchema	An opted-in App method is still working; poll again after this bounded delay.
constant	APP_STATUS_ITEMS_MAX	The most readouts one App window’s status bar shows.
constant	APP_STATUS_TEXT_MAX	The longest readout a window’s status bar shows.
constant	APP_STATUS_OPTIONS_MAX	The most choices one status menu offers.
constant	APP_BROWSER_SAVE_MAX_BYTES	Maximum file size sent through the user-initiated host browser door.
constant	APP_BROWSER_COPY_MAX_BYTES	Maximum UTF-8 text size sent to the host clipboard.
constant	APP_NAVIGATION_CONTRACT_VERSION	Version of the navigation contract an App publishes. The host rejects any other version, so a future shape can never be misread as this one.
constant	APP_NAVIGATION_TITLE_MAX	The longest page title a host shows beside the App’s own name.
constant	APP_NAVIGATION_CRUMBS_MAX	The most crumbs one navigation report may carry.
constant	APP_NAVIGATION_SIBLINGS_MAX	The most siblings one switcher crumb may offer.
constant	APP_NAVIGATION_PRIMARY_MAX	The most primary header commands one report may carry.
constant	APP_NAVIGATION_STATUS_MAX	The most header status facts one report may carry.
constant	APP_NAVIGATION_MENU_MAX	The most ⋯ menu commands one report may carry.
constant	APP_NAVIGATION_LABEL_MAX	The longest crumb or command label a host shows.
constant	inertHostNavigation	Navigation for a root with no host chrome, such as a workbench fixture: it accepts every report and never asks the App to go back.
constant	resultRowSchemaV1	A finished App call as a person reads it: a shared row plus an optional thumbnail.
function	messageAuthor()	The author a message’s metadata names; none for anything else.
function	messageDelegationReply()	The authenticated delegation reply a message’s metadata carries; none for any other line, including text that merely looks like a reply.
function	authorMeta()	The metadata the host attaches for one authenticated author.
function	renameAppAgent()	Rename an Agent through the host-granted owner-only capability.
function	setAppAgentAvatar()	Change an Agent’s avatar through the host-granted owner-only capability.
function	listAppAgents()	List the Agents in the host-granted Team or local-project scope.
function	createAppAgent()	Create an Agent through the Team directory selected by the host.
function	openAppAgent()	Adapt one live object capability to Fetch without exposing the parent’s authenticated URL or credentials to the isolated App.
function	defineCapability()	Define a capability with the owner’s decoder for its live RPC interface.
function	createCapabilityRegistry()	Register typed local implementations without reopening their erased types.
function	registerCatalog()	Register one App’s Whistle catalog with its host. An App defines each command once, contributes the same catalog to its own composer runtime for slash commands, and registers it here so the shell projects it into the palette, menus, keys and the agent view. Availability is read once at registration; register again to publish a change.
function	connectApp()	Connects this iframe page to its authenticated host.
function	openMediaGeneration()	Discover the exact retained model catalog surfaced by the owner.
function	pending()	Return Pending with a polling delay between one and sixty seconds.
function	statusText()	Make person- or Computer-supplied text fit one status item: drop unsafe characters, collapse whitespace and shorten with an ellipsis.
function	statusActionAllowed()	Whether an action names something the App declares now: an enabled item, and for a menu exactly one enabled option. Every hop that delivers an action applies this rule against its own latest copy of the items.
function	navigationActivationAllowed()	Whether an activation names something the App published now: a crumb (and its sibling), or an enabled command. Every hop applies this rule against its own latest copy of the report, so a stale shell cannot reach the App.

FungiAuthortype alias

type FungiAuthor = z.infer<typeof FungiAuthorSchema>;

Who a Session line came from, as the admitting host authenticated them.

FungiDelegationReplytype alias

type FungiDelegationReply = z.infer<typeof FungiDelegationReplySchema>;

A delegated Agent’s reply as the admitting host authenticated it.

FungiMessageMetatype alias

type FungiMessageMeta = z.infer<typeof FungiMessageMetaSchema>;

The metadata the host attaches to every prompt and operator line it admits.

MessageMetaValuetype alias

type MessageMetaValue =
  | string
  | number
  | boolean
  | null
  | readonly MessageMetaValue[]
  | Readonly<{
      [key: string]: MessageMetaValue;
    }>;

Any JSON value, as Shiitake returns a message’s metadata.

AuthorMetatype alias

type AuthorMeta = Readonly<{
  author: Readonly<{
    [K in keyof FungiAuthor]: Exclude<FungiAuthor[K], undefined>;
  }>;
}>;

The metadata the host attaches for one authenticated author, as JSON.

AppAgenttype alias

type AppAgent = Schema.Schema.Type<typeof appAgentSchema>;

An Agent record as decoded from the host: its id, display name, and which session operations this App is permitted to perform on it.

AppAgentCreateInputtype alias

type AppAgentCreateInput = Readonly<
  Schema.Schema.Type<typeof appAgentCreateInputSchema>
>;

Input for creating a new Agent: its name, a caller-chosen request id for idempotency, whether to provision a new Computer for it, and the avatar it wears (omitted, it wears its seeded avatar).

AppAgentTransportHandletype alias

type AppAgentTransportHandle = object;

Live object-capability shape received from Cap’n Web.

Methods

fetch()

fetch(request): Promise<Response>;

Send one request to the Agent’s session endpoint.

Parameters

Parameter	Type
`request`	`Request`

Returns

Promise<Response>

close()

close(): Promise<void>;

Release the underlying object capability.

Returns

Promise<void>

[dispose]()

dispose: void;

Synchronously release local resources, for using disposal.

Returns

void

AppAgentListHandletype alias

type AppAgentListHandle = object;

Capability handle for listing the Agents in a directory.

Methods

list()

list(): Promise<readonly object[]>;

List the Agents visible to this App in the directory.

Returns

Promise<readonly object[]>

AppAgentCreateHandletype alias

type AppAgentCreateHandle = object;

Capability handle for creating a new Agent in a directory.

Methods

create()

create(input): Promise<{
  agentId: string;
  name: string;
  avatar: {
     v: z.ZodLiteral<1>;
     character: z.ZodEnum<{
        mushroom: "mushroom";
        cat: "cat";
        burger: "burger";
     }>;
     appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
     expression: z.ZodString;
     renderStyle: z.ZodEnum<{
        plain: "plain";
        pencil: "pencil";
        manga: "manga";
        riso: "riso";
        halftone: "halftone";
        blueprint: "blueprint";
        crt: "crt";
        watercolor: "watercolor";
     }>;
  };
  sessionOperations: readonly ("agent.manage" | "agent.read" | "agent.send")[];
}>;

Create a new Agent with the given name and request id.

Parameters

Parameter	Type
`input`	`AppAgentCreateInput`

Returns

Promise<{ agentId: string; name: string; avatar: { v: z.ZodLiteral<1>; character: z.ZodEnum<{ mushroom: "mushroom"; cat: "cat"; burger: "burger"; }>; appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>; expression: z.ZodString; renderStyle: z.ZodEnum<{ plain: "plain"; pencil: "pencil"; manga: "manga"; riso: "riso"; halftone: "halftone"; blueprint: "blueprint"; crt: "crt"; watercolor: "watercolor"; }>; }; sessionOperations: readonly ("agent.manage" | "agent.read" | "agent.send")[]; }>

AppAgentDirectoryHandletype alias

type AppAgentDirectoryHandle = AppAgentListHandle &
  AppAgentCreateHandle &
  object;

Live capability handle for listing and creating Agents in a Team or local-project directory, and opening transports to them.

Type Declaration

Name	Type	Description
`open()`	`(input) => Promise<AppAgentTransportHandle>`	Open a transport to the Agent identified by `agentId`.
`openInbox()`	`() => Promise<AppAgentTransportHandle>`	The member’s inbox feed, limited to Agents this App may read.

AppAgentRenameInputtype alias

type AppAgentRenameInput = Readonly<
  Schema.Schema.Type<typeof appAgentRenameInputSchema>
>;

Input for renaming an existing Agent: its id and the owner’s chosen replacement display name.

AppAgentRenameHandletype alias

type AppAgentRenameHandle = object;

Capability handle for renaming an Agent the owner already created.

Methods

rename()

rename(input): Promise<{
  agentId: string;
  name: string;
  avatar: {
     v: z.ZodLiteral<1>;
     character: z.ZodEnum<{
        mushroom: "mushroom";
        cat: "cat";
        burger: "burger";
     }>;
     appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
     expression: z.ZodString;
     renderStyle: z.ZodEnum<{
        plain: "plain";
        pencil: "pencil";
        manga: "manga";
        riso: "riso";
        halftone: "halftone";
        blueprint: "blueprint";
        crt: "crt";
        watercolor: "watercolor";
     }>;
  };
  sessionOperations: readonly ("agent.manage" | "agent.read" | "agent.send")[];
}>;

Rename an existing Agent and return its updated record.

Parameters

Parameter	Type
`input`	`AppAgentRenameInput`

Returns

AppAgentAvatarInputtype alias

type AppAgentAvatarInput = Readonly<
  Schema.Schema.Type<typeof appAgentAvatarInputSchema>
>;

Input for changing an existing Agent’s avatar.

AppAgentAvatarHandletype alias

type AppAgentAvatarHandle = object;

Capability handle for changing an Agent’s avatar.

Methods

setAvatar()

setAvatar(input): Promise<{
  agentId: string;
  name: string;
  avatar: {
     v: z.ZodLiteral<1>;
     character: z.ZodEnum<{
        mushroom: "mushroom";
        cat: "cat";
        burger: "burger";
     }>;
     appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
     expression: z.ZodString;
     renderStyle: z.ZodEnum<{
        plain: "plain";
        pencil: "pencil";
        manga: "manga";
        riso: "riso";
        halftone: "halftone";
        blueprint: "blueprint";
        crt: "crt";
        watercolor: "watercolor";
     }>;
  };
  sessionOperations: readonly ("agent.manage" | "agent.read" | "agent.send")[];
}>;

Set an existing Agent’s avatar and return its updated record.

Parameters

Parameter	Type
`input`	`AppAgentAvatarInput`

Returns

AppAgentToolPolicyStatustype alias

type AppAgentToolPolicyStatus = z.infer<typeof appAgentToolPolicyStatusSchema>;

Whether an Agent’s App tools are still pending the owner’s approval.

AppAgentToolPolicyResulttype alias

type AppAgentToolPolicyResult = z.infer<typeof appAgentToolPolicyResultSchema>;

The outcome of an owner’s direct App-tool approval.

AppAgentToolPolicyHandletype alias

type AppAgentToolPolicyHandle = object;

Capability handle for reading and approving an Agent’s App-tool policy.

Methods

status()

status(input): Promise<
  | {
  status: "pending";
  revision: string;
}
  | {
  status: "approved";
  revision: string;
}
| null>;

This Agent’s current policy status, or null for no such Agent.

Parameters

Parameter	Type
`input`	`{ agentId: string; }`
`input.agentId`	`string`

Returns

Promise< | { status: "pending"; revision: string; } | { status: "approved"; revision: string; } | null>

approve()

approve(input): Promise<
  | {
  status: "pending";
  revision: string;
}
  | {
  status: "approved";
  revision: string;
}
  | {
  error: string;
}>;

Approve (or re-request) this Agent’s App tools under a CAS revision.

Parameters

Parameter	Type
`input`	`{ agentId: string; level: "read" \| "write"; expectedRevision: string \| null; }`
`input.agentId`	`string`
`input.level`	`"read" \| "write"`
`input.expectedRevision`	`string \| null`

Returns

Promise< | { status: "pending"; revision: string; } | { status: "approved"; revision: string; } | { error: string; }>

AppAgentTransporttype alias

type AppAgentTransport = Readonly<{
  baseUrl: string;
  fetch: typeof globalThis.fetch;
  close: () => Promise<void>;
}>;

A Fetch-based transport to one Agent’s session endpoint, scoped to this App and safe to hand to an HTTP client adapter.

CapabilityContracttype alias

type CapabilityContract<T> = object;

A capability owner’s frozen, typed descriptor. Descriptor identity is not authority.

Type Parameters

Type Parameter
`T`

Properties

id

readonly id: string;

version

readonly version: number;

schema

readonly schema: z.ZodType<T>;

CapabilityDirectorytype alias

type CapabilityDirectory = object;

The App’s read-only view of its currently admitted capabilities.

Properties

version

readonly version: number;

Changes after a successful grant replacement or disconnection.

Methods

subscribe(listener): Disposer;

Read the current directory after a change. Does not emit on subscribe.

Parameters

Parameter	Type
`listener`	`() => void`

Returns

Disposer

has()

has(contract): boolean;

Whether an implementation for this contract is currently admitted.

Parameters

Parameter	Type
`contract`	`CapabilityContract<unknown>`

Returns

boolean

require()

require<T>(contract): T;

The admitted implementation for this contract, or throw a CAPABILITY_DENIED AppError when none is granted.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`contract`	`CapabilityContract<T>`

Returns

T

CapabilityRegistrytype alias

type CapabilityRegistry = CapabilityDirectory & object;

Local capabilities admitted through their owner’s typed contract.

Type Declaration

Name	Type	Description
`provide()`	`<T>(contract, implementation) => void`	Admit an implementation for this contract, replacing any previous one and bumping `version` so subscribers can react.

AppCommandtype alias

type AppCommand = WhistleCommandDefinition;

Semantic command metadata supplied by an App and owned by Whistle.

AppCommandHandlertype alias

type AppCommandHandler = (
  invocation,
) => Promise<WhistleJsonValue | undefined> | WhistleJsonValue | undefined;

One invocation’s semantic input; host correlation IDs are private.

Parameters

Parameter	Type
`invocation`	`AppCommandInvocation`

Returns

| Promise<WhistleJsonValue | undefined> | WhistleJsonValue | undefined

AppCommandInvocationtype alias

type AppCommandInvocation = object;

One command invocation’s semantic input, passed to its handler.

Properties

arguments?

readonly optional arguments?: WhistleJsonValue;

origin

readonly origin: WhistleExecutionOrigin;

signal

readonly signal: AbortSignal;

AppCommandstype alias

type AppCommands = object;

Registers a command with the authenticated host for this page session. The promise resolves only after the host accepts the registration.

Methods

register()

register(command, handler): Promise<Disposer>;

Register one command and its handler with the host; resolves once the host accepts it. Call the returned Disposer to unregister.

Parameters

Parameter	Type
`command`	{ id: z.ZodLazy<z.ZodString>; title: z.ZodLazy<z.ZodString>; category: z.ZodLazy<z.ZodString>; description?: z.ZodOptional<z.ZodLazy<z.ZodString>>; projections?: z.ZodOptional<z.ZodLazy<z.ZodObject<{ bindings: z.ZodOptional<z.ZodObject<{ order: z.ZodOptional<z.ZodLazy<…>>; values: z.ZodArray<z.ZodLazy<…>>; }, z.core.$strict>>; agent: z.ZodOptional<z.ZodObject<{ keybind: z.ZodOptional<z.ZodLazy<…>>; order: z.ZodOptional<z.ZodLazy<…>>; }, z.core.$strict>>; help: z.ZodOptional<z.ZodLazy<z.ZodObject<{ order: z.ZodOptional<…>; }, z.core.$strict>>>; menu: z.ZodOptional<z.ZodLazy<z.ZodObject<{ order: z.ZodOptional<…>; }, z.core.$strict>>>; palette: z.ZodOptional<z.ZodLazy<z.ZodObject<{ order: z.ZodOptional<…>; }, z.core.$strict>>>; slash: z.ZodOptional<z.ZodObject<{ aliases: z.ZodArray<z.ZodLazy<…>>; consumesDraft: z.ZodOptional<z.ZodBoolean>; order: z.ZodOptional<z.ZodLazy<…>>; arguments: z.ZodOptional<z.ZodLazy<…>>; }, z.core.$strict>>; }, z.core.$strict>>>; action?: z.ZodOptional<z.ZodLazy<z.ZodObject<{ inputSchema: z.ZodOptional<z.ZodLazy<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>; outputSchema: z.ZodOptional<z.ZodLazy<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>; presentation: z.ZodOptional<z.ZodLazy<z.ZodUnion<readonly […, …, …, …, …]>>>; }, z.core.$strict>>>; availability?: z.ZodOptional<z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodObject<{ status: z.ZodLiteral<"available">; }, z.core.$strict>, z.ZodObject<{ status: z.ZodLiteral<"unavailable">; reason: z.ZodString; }, z.core.$strict>], "status">>>; }
`command.id`	`z.ZodLazy<z.ZodString>`
`command.title`	`z.ZodLazy<z.ZodString>`
`command.category`	`z.ZodLazy<z.ZodString>`
`command.description?`	`z.ZodOptional<z.ZodLazy<z.ZodString>>`
`command.projections?`	z.ZodOptional<z.ZodLazy<z.ZodObject<{ bindings: z.ZodOptional<z.ZodObject<{ order: z.ZodOptional<z.ZodLazy<…>>; values: z.ZodArray<z.ZodLazy<…>>; }, z.core.$strict>>; agent: z.ZodOptional<z.ZodObject<{ keybind: z.ZodOptional<z.ZodLazy<…>>; order: z.ZodOptional<z.ZodLazy<…>>; }, z.core.$strict>>; help: z.ZodOptional<z.ZodLazy<z.ZodObject<{ order: z.ZodOptional<…>; }, z.core.$strict>>>; menu: z.ZodOptional<z.ZodLazy<z.ZodObject<{ order: z.ZodOptional<…>; }, z.core.$strict>>>; palette: z.ZodOptional<z.ZodLazy<z.ZodObject<{ order: z.ZodOptional<…>; }, z.core.$strict>>>; slash: z.ZodOptional<z.ZodObject<{ aliases: z.ZodArray<z.ZodLazy<…>>; consumesDraft: z.ZodOptional<z.ZodBoolean>; order: z.ZodOptional<z.ZodLazy<…>>; arguments: z.ZodOptional<z.ZodLazy<…>>; }, z.core.$strict>>; }, z.core.$strict>>>
`command.action?`	`z.ZodOptional<z.ZodLazy<z.ZodObject<{ inputSchema: z.ZodOptional<z.ZodLazy<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>; outputSchema: z.ZodOptional<z.ZodLazy<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>; presentation: z.ZodOptional<z.ZodLazy<z.ZodUnion<readonly […, …, …, …, …]>>>; }, z.core.$strict>>>`
`command.availability?`	`z.ZodOptional<z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodObject<{ status: z.ZodLiteral<"available">; }, z.core.$strict>, z.ZodObject<{ status: z.ZodLiteral<"unavailable">; reason: z.ZodString; }, z.core.$strict>], "status">>>`
`handler`	`AppCommandHandler`

Returns

Promise<Disposer>

ConnectAppOptionstype alias

type ConnectAppOptions = object;

Options for connecting this iframe page to its authenticated host.

Properties

host

readonly host: "parent";

The parent is the host. Serve the App with CSP frame-ancestors pinned to its allowed host so an unrelated site cannot become its parent.

signal?

readonly optional signal?: AbortSignal;

Cancels a pending connection attempt.

AppConnectMessagetype alias

type AppConnectMessage = object;

The host’s handshake message that hands the App its RPC MessagePort.

Properties

epoch

readonly epoch: string;

protocolVersion

readonly protocolVersion: typeof APP_PROTOCOL_VERSION;

type

readonly type: typeof APP_CONNECT_TYPE;

AppReadyMessagetype alias

type AppReadyMessage = object;

The App iframe’s handshake message announcing it is ready to connect.

Properties

protocolVersion

readonly protocolVersion: typeof APP_PROTOCOL_VERSION;

type

readonly type: typeof APP_READY_TYPE;

AppContexttype alias

type AppContext = object;

The host-published state surrounding a connected App: its Computer selection, focus, visibility, and any pending open request.

Properties

computerId

readonly computerId: string | null;

Host-selected Computer backing this App’s admitted resource capabilities.

teamHasComputers?

readonly optional teamHasComputers?: boolean | null;

Whether the Team has Computers, when this host owns its Team directory.

computerAccessGranted?

readonly optional computerAccessGranted?: boolean;

Whether this App has execute access across the Team, when known.

focus

readonly focus: FocusState;

openRequest

readonly openRequest: AppOpenRequest | null;

One host-issued App open action, present only on the launch/reconfigure.

visibility

readonly visibility: "hidden" | "visible";

AppOpenRequesttype alias

type AppOpenRequest =
  | Readonly<{
      kind: "compose";
      requestId: string;
      text: string;
    }>
  | Readonly<{
      kind: "navigate";
      requestId: string;
      params: readonly Readonly<{
        key: string;
        value: string;
      }>[];
    }>;

One host-issued action an App must act on when it opens or reconfigures: start composing given text, or navigate to the given params. Each carries a requestId so the App can tell a repeated open from a fresh one.

AppIdentitytype alias

type AppIdentity = object;

The App’s own identity, as admitted by its host.

Properties

appId

readonly appId: string;

releaseId

readonly releaseId: string;

surfaceId

readonly surfaceId: string;

AppLifecycletype alias

type AppLifecycle =
  | "connected"
  | "connecting"
  | "disconnected"
  | "disposed"
  | "disposing"
  | "suspended";

The connection state of this App’s session with its host.

FocusStatetype alias

type FocusState = object;

Whether the App’s own surface is being edited and which surface, if any, the host considers focused.

Properties

editing

readonly editing: boolean;

surface

readonly surface: null | string;

MediaGenerationInputtype alias

type MediaGenerationInput = Readonly<{
  destination: Readonly<{
    path: string;
  }>;
  settings: MediaGenerationSelection;
}>;

The Media owner decides Team, Installation, Release, Grant and Computer authority before issuing this handle. The App contributes only generation settings and selected destination/references. The IDs in those selections are not authority: the host revalidates every one against its current admitted Computer scope when it accepts a generation.

The owner intentionally returns completed metadata. Operation state, provider identifiers and billing records remain owner facts. The exposed request reference identifies a replay; it grants no authority.

MediaOutputFormattype alias

type MediaOutputFormat = "png" | "jpeg" | "gif" | "webp" | "mp4";

The encodings a completed generation can be saved as.

MediaGenerationResulttype alias

type MediaGenerationResult = Readonly<{
  bytes: number;
  costMilliunits: number;
  destination: Readonly<{
    computerId: string;
    path: string;
  }>;
  format: MediaOutputFormat;
  height: number;
  model: string;
  width: number;
}>;

Metadata for one completed generation: the saved destination, pixel dimensions, format, model used, and its cost.

MediaGenerationFailuretype alias

type MediaGenerationFailure = Schema.Schema.Type<
  typeof mediaGenerationFailureSchema
>;

The host’s typed reason a generation failed: code, message, retry truth and, when known, the stage that failed.

MediaGenerationOutcometype alias

type MediaGenerationOutcome =
  | Readonly<{
      kind: "succeeded";
      result: MediaGenerationResult;
    }>
  | Readonly<{
      kind: "failed";
      failure: MediaGenerationFailure;
    }>;

Transport-safe result from the host-owned generation attempt.

MediaGenerationHandletype alias

type MediaGenerationHandle = object;

Live object-capability shape supplied by the host.

Methods

describe()

describe(): Promise<Partial<Disposable> & object>;

Fetch the Computer scope, available models, and whether generation is currently allowed.

Returns

Promise<Partial<Disposable> & object>

createAttempt()

createAttempt(): Promise<MediaGenerationAttemptHandle>;

Begin a new generation attempt on the host and return its handle.

Returns

Promise<MediaGenerationAttemptHandle>

restoreAttempt()

restoreAttempt(reference): Promise<MediaGenerationAttemptHandle>;

Resume a previously started attempt identified by its reference.

Parameters

Parameter	Type
`reference`	`{ requestId: string; computerId: string; }`
`reference.requestId`	`string`
`reference.computerId`	`string`

Returns

Promise<MediaGenerationAttemptHandle>

cancelAttempt()

cancelAttempt(reference): Promise<void>;

Tell the host to stop an in-flight or pending attempt.

Parameters

Parameter	Type
`reference`	`{ requestId: string; computerId: string; }`
`reference.requestId`	`string`
`reference.computerId`	`string`

Returns

Promise<void>

MediaGenerationAttemptHandletype alias

type MediaGenerationAttemptHandle = Partial<Disposable> & object;

Host-supplied object-capability for one attempt, before Agar wraps it into the typed MediaGenerationAttempt.

Type Declaration

Name	Type	Description
`reference()`	`() => Promise<object & Partial<Disposable>>`	Fetch this attempt’s replay reference from the host.
`generate()`	`(input) => Promise<MediaGenerationOutcome & Partial<Disposable>>`	Ask the host to run generation for this attempt with the given input.

MediaGenerationAttempttype alias

type MediaGenerationAttempt = Disposable & object;

One generation attempt: a stable reference plus the ability to run (or retry) generation against it until disposed.

Type Declaration

Name	Type	Description
`reference`	`MediaGenerationReference`	-
`generate()`	`(input, options?) => Promise<Readonly<{ bytes: number; costMilliunits: number; destination: Readonly<{ computerId: string; path: string; }>; format: MediaOutputFormat; height: number; model: string; width: number; }>>`	Run generation for this attempt and return the saved result, or throw MediaGenerationError on failure; an abort signal cancels it.

MediaGenerationSessiontype alias

type MediaGenerationSession = Readonly<{
  computerId: string;
  canGenerate: boolean;
  models: readonly MediaModel[];
  createAttempt: Promise<MediaGenerationAttempt>;
  restoreAttempt: Promise<MediaGenerationAttempt>;
}>;

The validated, App-facing handle returned by openMediaGeneration: the Computer’s model catalog plus the ability to start or resume attempts.

MediaGenerationReferencetype alias

type MediaGenerationReference = Schema.Schema.Type<
  typeof mediaGenerationReferenceSchema
>;

An opaque replay identity for one attempt; it identifies a request, not an authorization to use it.

MediaModeltype alias

type MediaModel = Schema.Schema.Type<typeof mediaModelSchema>;

One generation model as the host describes it: identity, tier, input limits and supported output formats. The host owns the catalog.

MediaGenerationSelectiontype alias

type MediaGenerationSelection = Schema.Schema.Type<
  typeof mediaGenerationSelectionSchema
>;

An App’s generation settings: model, prompt, size and optional steps, duration and Computer-relative reference paths.

Pendingtype alias

type Pending = Readonly<z.output<typeof pendingSchema>>;

The shared polling result, owned by the App contract.

AppRoottype alias

type AppRoot = object;

The App’s live connection to its host: its admitted capabilities, commands, context, theme, UI door and window, all torn down together by dispose. Returned by connectApp and passed to mountApp.

Properties

capabilities

readonly capabilities: CapabilityDirectory;

commands

readonly commands: AppCommands;

context

readonly context: ReadonlyStore<AppContext>;

identity

readonly identity: Readonly<AppIdentity>;

lifecycle

readonly lifecycle: ReadonlyStore<AppLifecycle>;

theme

readonly theme: ReadonlyStore<string>;

ui

readonly ui: HostUi;

window

readonly window: AppWindow;

Methods

dispose()

dispose(): void;

End this App’s connection to its host and release everything it owns.

Returns

void

Disposertype alias

type Disposer = () => void;

Releases a subscription or other held resource. Call once; further calls are a no-op.

Returns

void

ReadonlyStoretype alias

type ReadonlyStore<T> = object;

A retained SDK-owned snapshot.

Type Parameters

Type Parameter
`T`

Methods

get()

get(): T;

The current value; always available, even before any subscription.

Returns

T

subscribe(listener): Disposer;

Call listener on every change until the returned Disposer runs. Does not emit the current value immediately on subscribe.

Parameters

Parameter	Type
`listener`	`(value) => void`

Returns

Disposer

HostUitype alias

type HostUi = object;

Deliberately narrow shell affordances; domain work belongs to capabilities.

Methods

requestComputerChoice()

requestComputerChoice(): Promise<void>;

Open the host-owned Computer picker; selection arrives through App context.

Returns

Promise<void>

requestBrowserAction()

requestBrowserAction(input): Promise<AppBrowserActionOutcome>;

Request a host browser action from a fresh user click in this App.

Parameters

Parameter	Type
`input`	`AppBrowserAction`

Returns

Promise<AppBrowserActionOutcome>

requestAppPermissions()

requestAppPermissions(input): Promise<AppPermissionOutcome>;

Ask the trusted host for App rights. The host, never the App, renders the consent and writes any grant; an empty request opens App permissions.

Parameters

Parameter	Type
`input`	`AppPermissionRequest`

Returns

Promise<AppPermissionOutcome>

openNavigation()

openNavigation(input): Promise<void>;

Ask the host to open an already admitted Computer file.

Parameters

Parameter	Type
`input`	`FileNavigationInput`

Returns

Promise<void>

reportStatus()

reportStatus(items): Promise<void>;

Declare this window’s status bar items, such as “2 documents” or a Ports button. The host renders them beside the Computer it owns; the newest report wins and an empty list clears them.

Parameters

Parameter	Type
`items`	`readonly AppStatusItem[]`

Returns

Promise<void>

onStatusAction()

onStatusAction(handler): () => void;

Hear the person use one of this window’s declared status items. One owner at a time; the host never renders App UI in its chrome.

Parameters

Parameter	Type
`handler`	`AppStatusActionHandler`

Returns

() => void

openTeamBilling()

openTeamBilling(): Promise<void>;

Leave the App for the host’s Billing page for this Team.

Returns

Promise<void>

openDesktopSettings()

openDesktopSettings(): Promise<void>;

Suggest this App’s desktop Gills while focused with browser activation. The host shows a notice; the member must choose Review to open Settings. The App receives no layout or placement authority.

Returns

Promise<void>

reportAgentSessionSelection()

reportAgentSessionSelection(selection): Promise<void>;

Tell the host which Agent conversation this App currently has selected, or null when none is selected.

Parameters

Parameter	Type
`selection`	`\| Readonly<{ agentId: string; sessionId: string; }> \| null`

Returns

Promise<void>

showToast()

showToast(input): Promise<void>;

Ask the host to show a transient toast notification.

Parameters

Parameter	Type
`input`	`ToastInput`

Returns

Promise<void>

AppStatusIcontype alias

type AppStatusIcon = "folder" | "ports" | "processes" | "access";

The marks a host can draw before a status button’s label.

AppStatusTonetype alias

type AppStatusTone = "neutral" | "success" | "warning" | "error";

A readout’s live state, shown as a small light before its text.

AppStatusOptiontype alias

type AppStatusOption = Readonly<{
  id: string;
  text: string;
  checked?: boolean;
  disabled?: boolean;
}>;

One choice in a status menu, such as a folder or a port.

AppStatusItemtype alias

type AppStatusItem =
  | Readonly<{
      id: string;
      text: string;
      end?: boolean;
      kind: "text";
      tone?: AppStatusTone;
    }>
  | Readonly<{
      id: string;
      text: string;
      end?: boolean;
      kind: "button";
      icon?: AppStatusIcon;
      count?: number;
      tone?: AppStatusTone;
      busy?: boolean;
      title?: string;
      disabled?: boolean;
      opens?: "dialog";
      expanded?: boolean;
    }>
  | Readonly<{
      id: string;
      text: string;
      end?: boolean;
      kind: "toggle";
      pressed: boolean;
    }>
  | Readonly<{
      id: string;
      text: string;
      end?: boolean;
      kind: "menu";
      count?: number;
      title?: string;
      options: readonly AppStatusOption[];
    }>;

One item an App declares for its window’s status bar, as data: a readout, a button, a toggle, or a menu of choices. Using one delivers an AppStatusAction back to the App.

AppStatusActiontype alias

type AppStatusAction = Readonly<{
  itemId: string;
  optionId?: string;
  anchor?: Readonly<{
    start: number;
    width: number;
  }>;
}>;

The person used a status item; optionId names a chosen menu option. anchor is where the item sits along the App’s surface, in CSS pixels from its inline start, so App UI it opens can sit above it.

AppStatusActionHandlertype alias

type AppStatusActionHandler = (action) => boolean | Promise<boolean>;

Handles one status action; true when the App acted on it.

Parameters

Parameter	Type
`action`	`AppStatusAction`

Returns

boolean | Promise<boolean>

AgentSessionSelectiontype alias

type AgentSessionSelection = Readonly<{
  agentId: string;
  sessionId: string;
}>;

Exact Agent conversation selected by an App for the authenticated shell.

FileNavigationInputtype alias

type FileNavigationInput = object;

A presentation-neutral request to open an already admitted Computer file.

Properties

computerId

readonly computerId: string;

path

readonly path: string;

ToastInputtype alias

type ToastInput = object;

A transient notification an App asks its host to show.

Properties

message

readonly message: string;

tone?

readonly optional tone?: "error" | "info" | "success" | "warning";

AgentAccessOperationtype alias

type AgentAccessOperation =
  "agent.list" | "agent.manage" | "agent.read" | "agent.send";

Agent rights an App may ask its host to grant through consent.

ComputerAccessOperationtype alias

type ComputerAccessOperation =
  | "computer.list"
  | "computer.readFile"
  | "computer.writeFile"
  | "computer.execute";

Computer rights an App may ask its host to grant through consent.

AppPermissionRequesttype alias

type AppPermissionRequest = Readonly<{
  agents?: readonly AgentAccessOperation[];
  computers?: readonly ComputerAccessOperation[];
}>;

The rights an App asks for; the host bounds them by its declared ceiling.

AppPermissionOutcometype alias

type AppPermissionOutcome = "granted" | "declined" | "customize";

granted: the host saved a grant covering the request. declined: the user said not now. customize: the host opened its full permission settings.

AppBrowserActiontype alias

type AppBrowserAction =
  | Readonly<{
      kind: "saveFile";
      name: string;
      mime: string;
      bytes: Uint8Array;
    }>
  | Readonly<{
      kind: "copyText";
      text: string;
    }>;

Data only; browser authority and the gesture check belong to the host.

AppBrowserActionRefusaltype alias

type AppBrowserActionRefusal = Readonly<{
  kind: "refused";
  reason:
    | "no-user-gesture"
    | "too-large"
    | "invalid-request"
    | "unavailable"
    | "denied"
    | "busy";
}>;

A browser action can be refused without disconnecting the App.

AppBrowserActionOutcometype alias

type AppBrowserActionOutcome =
  | Readonly<{
      kind: "saved";
    }>
  | Readonly<{
      kind: "copied";
    }>
  | AppBrowserActionRefusal;

Saved means a browser download was initiated, not a confirmed disk write.

BeforeAppClosetype alias

type BeforeAppClose = () => boolean | Promise<boolean>;

Consulted before the person closes the App’s window; return (or resolve) true to allow the close.

Returns

boolean | Promise<boolean>

AppCrumbtype alias

type AppCrumb = Readonly<{
  id: string;
  label: string;
  siblings?: readonly Readonly<{
    id: string;
    label: string;
  }>[];
}>;

One place in the App’s path; siblings makes it a switcher.

AppHeaderCommandtype alias

type AppHeaderCommand = Readonly<{
  id: string;
  label: string;
  icon?: "play";
  variant?: "primary" | "outline" | "ghost";
  tone?: "destructive";
  disabled?: boolean;
}>;

A command the App offers in its window header; the App owns its effect.

AppHeaderStatustype alias

type AppHeaderStatus = Readonly<{
  id: string;
  label: string;
  presentation?: "bead";
  tone?: "neutral" | "info" | "warning" | "success" | "error";
}>;

A quiet fact about the view, shown as muted text with a status bead.

AppNavigationActivationtype alias

type AppNavigationActivation =
  | Readonly<{
      kind: "crumb";
      crumbId: string;
      siblingId?: string;
    }>
  | Readonly<{
      kind: "action";
      actionId: string;
    }>;

The person used a crumb (or a switcher’s sibling) or a header command.

AppNavigationActivationHandlertype alias

type AppNavigationActivationHandler = (
  activation,
) => boolean | Promise<boolean>;

Handles one activation; true when the App acted on it.

Parameters

Parameter	Type
`activation`	`AppNavigationActivation`

Returns

boolean | Promise<boolean>

AppNavigationStatetype alias

type AppNavigationState = Readonly<{
  canGoBack: boolean;
  title?: string;
  crumbs?: readonly AppCrumb[];
  primary?: readonly AppHeaderCommand[];
  menu?: readonly AppHeaderCommand[];
  status?: readonly AppHeaderStatus[];
}>;

What the App’s own router can do right now. The App owns its history; the host only offers a Back affordance and relays the person’s request.

AppBackHandlertype alias

type AppBackHandler = () => boolean | Promise<boolean>;

Go back one step in the App’s own history; true when it moved.

Returns

boolean | Promise<boolean>

HostNavigationtype alias

type HostNavigation = Readonly<{
  publish: Promise<void>;
  onBack: Disposer;
  onActivate: Disposer;
}>;

The App’s half of the host navigation contract.

AppWindowtype alias

type AppWindow = Readonly<{
  onBeforeClose: Disposer;
  navigation: HostNavigation;
}>;

App-owned presentation policy consulted before a user closes its window.

ResultRowtype alias

type ResultRow = Schema.Schema.Type<typeof resultRowSchemaV1>;

One shared result row; navigation and previews stay host-authorized.

FungiAuthorSchemaconstant

const FungiAuthorSchema: ZodLazy<
  ZodObject<
    {
      id: ZodString;
      name: ZodString;
      kind: ZodOptional<ZodLiteral<"agent">>;
    },
    $strict
  >
>;

Who a Session line came from, as the admitting host authenticated them.

FungiDelegationReplySchemaconstant

const FungiDelegationReplySchema: ZodLazy<
  ZodObject<
    {
      agentId: ZodLazy<ZodString>;
      sessionId: ZodLazy<ZodString>;
      commandId: ZodLazy<ZodString>;
      outcome: ZodEnum<{
        completed: "completed";
        failed: "failed";
        interrupted: "interrupted";
        cancelled: "cancelled";
        outcome_unknown: "outcome_unknown";
      }>;
      diagnostic: ZodOptional<ZodString>;
      waitingOnYou: ZodOptional<
        ZodArray<
          ZodObject<
            {
              itemId: ZodLazy<ZodString>;
              kind: ZodString;
              summary: ZodString;
            },
            $strict
          >
        >
      >;
    },
    $strict
  >
>;

A delegated Agent’s reply as the admitting host authenticated it against the mail it sent. commandId is the replying Session’s accepted command, the same id as the sender’s agents.send receipt.

FungiMessageMetaSchemaconstant

const FungiMessageMetaSchema: ZodObject<{
  author: ZodOptional<ZodLazy<ZodObject<{
     id: ZodString;
     name: ZodString;
     kind: ZodOptional<ZodLiteral<"agent">>;
  }, $strict>>>;
  sourceRequestId: ZodOptional<ZodLazy<ZodString>>;
  delegation: ZodOptional<ZodObject<{
     ancestors: ZodArray<ZodLazy<ZodString>>;
     maxDepth: ZodNumber;
     steer: ZodOptional<ZodLiteral<true>>;
     reply: ZodOptional<ZodLazy<ZodObject<{
        agentId: ZodLazy<ZodString>;
        sessionId: ZodLazy<ZodString>;
        commandId: ZodLazy<ZodString>;
        outcome: ZodEnum<{
           completed: ...;
           failed: ...;
           interrupted: ...;
           cancelled: ...;
           outcome_unknown: ...;
        }>;
        diagnostic: ZodOptional<ZodString>;
        waitingOnYou: ZodOptional<ZodArray<...>>;
     }, $strict>>>;
  }, $strict>>;
}, $strict>;

The metadata the host attaches to every prompt and operator line it admits. Shiitake stores it opaquely; the host writes it and Apps read it.

appAgentAvatarSchemaconstant

const appAgentAvatarSchema: declare<
  {
    v: 1;
    character: "mushroom" | "cat" | "burger";
    appearance: z.ZodRecord<
      z.ZodString,
      z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
    >;
    expression: string;
    renderStyle:
      | "plain"
      | "pencil"
      | "manga"
      | "riso"
      | "halftone"
      | "blueprint"
      | "crt"
      | "watercolor";
  },
  {
    v: 1;
    character: "mushroom" | "cat" | "burger";
    appearance: z.ZodRecord<
      z.ZodString,
      z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
    >;
    expression: string;
    renderStyle:
      | "plain"
      | "pencil"
      | "manga"
      | "riso"
      | "halftone"
      | "blueprint"
      | "crt"
      | "watercolor";
  }
>;

An Agent’s avatar: Sprite’s Avatar v1 envelope. Apps check its shape; the host owns the character-catalog refinement when it stores one.

appAgentSchemaconstant

const appAgentSchema: Struct<{
  agentId: String;
  name: String;
  avatar: declare<
    {
      v: 1;
      character: "mushroom" | "cat" | "burger";
      appearance: z.ZodRecord<
        z.ZodString,
        z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
      >;
      expression: string;
      renderStyle:
        | "plain"
        | "pencil"
        | "manga"
        | "riso"
        | "halftone"
        | "blueprint"
        | "crt"
        | "watercolor";
    },
    {
      v: 1;
      character: "mushroom" | "cat" | "burger";
      appearance: z.ZodRecord<
        z.ZodString,
        z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
      >;
      expression: string;
      renderStyle:
        | "plain"
        | "pencil"
        | "manga"
        | "riso"
        | "halftone"
        | "blueprint"
        | "crt"
        | "watercolor";
    }
  >;
  sessionOperations: $Array<
    Literals<readonly ["agent.read", "agent.send", "agent.manage"]>
  >;
}>;

Validates the wire shape of an Agent record: its id, display name, avatar, and which session operations (read, send, manage) this App may perform on it. Every Agent has an avatar: the one its owner chose, else Sprite’s seededAvatar(agentId). Conversations carry none of their own.

appAgentCreateInputSchemaconstant

const appAgentCreateInputSchema: Struct<{
  name: String;
  requestId: String;
  computer: optionalKey<Literals<readonly ["new", "none"]>>;
  avatar: optionalKey<
    declare<
      {
        v: 1;
        character: "mushroom" | "cat" | "burger";
        appearance: z.ZodRecord<
          z.ZodString,
          z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
        >;
        expression: string;
        renderStyle:
          | "plain"
          | "pencil"
          | "manga"
          | "riso"
          | "halftone"
          | "blueprint"
          | "crt"
          | "watercolor";
      },
      {
        v: 1;
        character: "mushroom" | "cat" | "burger";
        appearance: z.ZodRecord<
          z.ZodString,
          z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
        >;
        expression: string;
        renderStyle:
          | "plain"
          | "pencil"
          | "manga"
          | "riso"
          | "halftone"
          | "blueprint"
          | "crt"
          | "watercolor";
      }
    >
  >;
}>;

Validates Agent creation input: a name, a caller-chosen request id, an optional Computer provisioning choice and an optional chosen avatar.

agentListconstant

const agentList: CapabilityContract<AppAgentListHandle>;

Capability to list the Agents visible to this App in read-only form.

agentManageconstant

const agentManage: CapabilityContract<
  Pick<AppAgentDirectoryHandle, "create" | "open">
>;

Capability to create new Agents and open transports to them.

appAgentRenameInputSchemaconstant

const appAgentRenameInputSchema: Struct<{
  agentId: String;
  name: String;
}>;

Validates Agent rename input: the target Agent and its new display name.

agentRenameconstant

const agentRename: CapabilityContract<AppAgentRenameHandle>;

Owner-only capability to rename an existing Agent; not every host grants it.

appAgentAvatarInputSchemaconstant

const appAgentAvatarInputSchema: Struct<{
  agentId: String;
  avatar: declare<
    {
      v: 1;
      character: "mushroom" | "cat" | "burger";
      appearance: z.ZodRecord<
        z.ZodString,
        z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
      >;
      expression: string;
      renderStyle:
        | "plain"
        | "pencil"
        | "manga"
        | "riso"
        | "halftone"
        | "blueprint"
        | "crt"
        | "watercolor";
    },
    {
      v: 1;
      character: "mushroom" | "cat" | "burger";
      appearance: z.ZodRecord<
        z.ZodString,
        z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
      >;
      expression: string;
      renderStyle:
        | "plain"
        | "pencil"
        | "manga"
        | "riso"
        | "halftone"
        | "blueprint"
        | "crt"
        | "watercolor";
    }
  >;
}>;

Validates avatar input: the target Agent and the avatar it now wears.

agentAvatarconstant

const agentAvatar: CapabilityContract<AppAgentAvatarHandle>;

Owner-only capability to change an existing Agent’s avatar; not every host grants it.

appAgentToolPolicyStatusSchemaconstant

const appAgentToolPolicyStatusSchema: ZodLazy<
  ZodUnion<
    readonly [
      ZodObject<
        {
          status: ZodLiteral<"pending">;
          revision: ZodString;
        },
        $strip
      >,
      ZodObject<
        {
          status: ZodLiteral<"approved">;
          revision: ZodString;
        },
        $strip
      >,
    ]
  >
>;

One Agent’s App-tool policy, as the owner-only policy capability reports it.

appAgentToolPolicyResultSchemaconstant

const appAgentToolPolicyResultSchema: ZodLazy<
  ZodUnion<
    readonly [
      ZodLazy<
        ZodUnion<
          readonly [
            ZodObject<
              {
                status: ZodLiteral<"pending">;
                revision: ZodString;
              },
              $strip
            >,
            ZodObject<
              {
                status: ZodLiteral<"approved">;
                revision: ZodString;
              },
              $strip
            >,
          ]
        >
      >,
      ZodObject<
        {
          error: ZodString;
        },
        $strip
      >,
    ]
  >
>;

The outcome of an owner’s direct App-tool approval.

agentToolPolicyconstant

const agentToolPolicy: CapabilityContract<AppAgentToolPolicyHandle>;

Owner-only capability to read and approve an Agent’s App-tool policy.

agentSessionReadconstant

const agentSessionRead: CapabilityContract<
  Pick<AppAgentDirectoryHandle, "open" | "openInbox">
>;

Capability for read-only Agent sessions: open a transport to an existing Agent, or read the member’s inbox feed.

agentSessionWriteconstant

const agentSessionWrite: CapabilityContract<
  Pick<AppAgentDirectoryHandle, "open" | "openInbox">
>;

Capability for read-write Agent sessions: open a transport to an existing Agent and send to it, including the member’s inbox feed.

approvalsconstant

const approvals: CapabilityContract<Approvals>;

Member-bound approval view. Authentication and current rights belong to the host.

APP_PROTOCOL_VERSIONconstant

const APP_PROTOCOL_VERSION: 2;

The iframe handshake version both App and host must speak.

APP_READY_TYPEconstant

const APP_READY_TYPE: "fungi.app.ready";

Message type the App iframe posts to announce it is ready to connect.

APP_CONNECT_TYPEconstant

const APP_CONNECT_TYPE: "fungi.app.connect";

Message type the host posts to hand the App its RPC MessagePort.

appDeliveryPendingSchemaconstant

const appDeliveryPendingSchema: Struct<{
  code: Literals<readonly ["DELIVERY_PENDING"]>;
}>;

Effect projection of the error owner’s declaration-safe pending refusal.

parseAppStatusItemsconstant

const parseAppStatusItems: (...a) => readonly AppStatusItem[];

Both edges: one window’s status items, bounded and copied.

Parameters

Parameter	Type
…`a`	`[unknown, ParseOptions]`

Returns

readonly AppStatusItem[]

parseAppStatusActionconstant

const parseAppStatusAction: (...a) => C;

App edge: the status item the person used, as the host relays it.

Parameters

Parameter	Type
…`a`	`[unknown, ParseOptions]`

Returns

C

mediaGenerationReferenceSchemaconstant

const mediaGenerationReferenceSchema: Struct<{
  requestId: String;
  computerId: String;
}>;

A replay identity, never an authorization capability.

mediaModelSchemaconstant

const mediaModelSchema: Struct<{
  id: String;
  input: Struct<{
    defaultHeight: Number;
    defaultSteps: NullOr<Number>;
    defaultWidth: Number;
    dimensions: Literals<readonly ["none", "own"]>;
    maxDimension: NullOr<Number>;
    maxDimensionDocumented: Boolean;
    maxReferences: Number;
    maxSteps: NullOr<Number>;
    referenceField: NullOr<String>;
    steps: Literals<readonly ["steps", "num_steps", "fixed"]>;
    transport: Literals<readonly ["json", "multipart"]>;
  }>;
  kind: Literals<readonly ["image", "video"]>;
  label: String;
  maxPromptLength: Number;
  tier: Literals<readonly ["draft", "balanced", "premium", "max"]>;
  outputFormats: $Array<Literals<readonly ["png", "jpeg", "webp"]>>;
  sizes: NullOr<$Array<String>>;
  video: NullOr<
    Struct<{
      minSeconds: Number;
      maxSeconds: Number;
      defaultSeconds: Number;
      durations: $Array<Number>;
      provider: Literals<readonly ["seedance", "veo", "minimax"]>;
      formats: $Array<
        Struct<{
          resolution: Literals<
            readonly ["480p", "720p", "768p", "1080p", "4k"]
          >;
          aspectRatio: Literals<
            readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]
          >;
          width: Number;
          height: Number;
        }>
      >;
      defaultResolution: Literals<
        readonly ["480p", "720p", "768p", "1080p", "4k"]
      >;
      defaultAspectRatio: Literals<
        readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]
      >;
      supportsAudio: Boolean;
      defaultGenerateAudio: NullOr<Boolean>;
      referenceRoles: $Array<
        Literals<readonly ["first-frame", "last-frame", "reference"]>
      >;
      maxReferenceImages: Number;
      referenceResolutions: $Array<
        Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>
      >;
      prices: $Array<
        Struct<{
          resolution: Literals<
            readonly ["480p", "720p", "768p", "1080p", "4k"]
          >;
          silentMilliunitsPerSecond: Number;
          audioMilliunitsPerSecond: Number;
        }>
      >;
    }>
  >;
}>;

Validates one model row of the host’s Media catalog.

mediaGenerationSelectionSchemaconstant

const mediaGenerationSelectionSchema: Struct<{
  model: String;
  prompt: String;
  width: Number;
  height: Number;
  steps: optional<Number>;
  durationSeconds: optional<Number>;
  resolution: optional<
    Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>
  >;
  aspectRatio: optional<
    Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>
  >;
  generateAudio: optional<Boolean>;
  references: optional<
    $Array<
      Struct<{
        path: String;
        role: optional<
          Literals<readonly ["first-frame", "last-frame", "reference"]>
        >;
      }>
    >
  >;
}>;

Validates the shape of an App’s generation settings. Model-specific limits (sizes, steps, durations, reference counts) and defaults are the host’s: it checks the selection against its catalog when it accepts a generation.

mediaGenerationFailureSchemaconstant

const mediaGenerationFailureSchema: Struct<{
  message: String;
  stage: optional<
    Literals<
      readonly [
        "admission",
        "generation-authorization",
        "settings",
        "estimate",
        "billing",
        "operation",
        "provider",
        "normalization",
        "artifact",
        "destination-authorization",
        "destination-write",
      ]
    >
  >;
  provider: optional<
    Union<
      readonly [
        Struct<{
          category: Literals<
            readonly [
              "InferenceUpstreamError",
              "AiInternalError",
              "TypeError",
              "AbortError",
              "TimeoutError",
              "Error",
            ]
          >;
          code: NullOr<Int>;
        }>,
        Struct<{
          category: Literal<"result_download">;
          status: Int;
        }>,
      ]
    >
  >;
  code: Literals<
    readonly [
      "CANCELLED",
      "CAPABILITY_DENIED",
      "CAPABILITY_REVOKED",
      "DISCONNECTED",
      "HOST_FAILURE",
      "IDENTITY",
      "INSUFFICIENT_CREDIT",
      "INVALID_ARGUMENT",
      "PROTOCOL",
      "SAFETY_FILTER_REFUSED",
      "TIMEOUT",
    ]
  >;
  retryable: Boolean;
}>;

Validates the typed failure a host reports for a generation attempt.

mediaGenerationconstant

const mediaGeneration: CapabilityContract<MediaGenerationHandle>;

Capability contract for generating Media (images or video). Apps declare it to request access; openMediaGeneration uses it to obtain the host’s handle.

pendingSchemaconstant

const pendingSchema: ZodObject<
  {
    kind: ZodLiteral<"pending">;
    retryAfterMs: ZodNumber;
  },
  $strict
>;

An opted-in App method is still working; poll again after this bounded delay.

APP_STATUS_ITEMS_MAXconstant

const APP_STATUS_ITEMS_MAX: 6 = 6;

The most readouts one App window’s status bar shows.

APP_STATUS_TEXT_MAXconstant

const APP_STATUS_TEXT_MAX: 80 = 80;

The longest readout a window’s status bar shows.

APP_STATUS_OPTIONS_MAXconstant

const APP_STATUS_OPTIONS_MAX: 16 = 16;

The most choices one status menu offers.

APP_BROWSER_SAVE_MAX_BYTESconstant

const APP_BROWSER_SAVE_MAX_BYTES: number;

Maximum file size sent through the user-initiated host browser door.

APP_BROWSER_COPY_MAX_BYTESconstant

const APP_BROWSER_COPY_MAX_BYTES: number;

Maximum UTF-8 text size sent to the host clipboard.

APP_NAVIGATION_CONTRACT_VERSIONconstant

const APP_NAVIGATION_CONTRACT_VERSION: 1;

Version of the navigation contract an App publishes. The host rejects any other version, so a future shape can never be misread as this one.

APP_NAVIGATION_TITLE_MAXconstant

const APP_NAVIGATION_TITLE_MAX: 80 = 80;

The longest page title a host shows beside the App’s own name.

APP_NAVIGATION_CRUMBS_MAXconstant

const APP_NAVIGATION_CRUMBS_MAX: 8 = 8;

The most crumbs one navigation report may carry.

APP_NAVIGATION_SIBLINGS_MAXconstant

const APP_NAVIGATION_SIBLINGS_MAX: 16 = 16;

The most siblings one switcher crumb may offer.

APP_NAVIGATION_PRIMARY_MAXconstant

const APP_NAVIGATION_PRIMARY_MAX: 3 = 3;

The most primary header commands one report may carry.

APP_NAVIGATION_STATUS_MAXconstant

const APP_NAVIGATION_STATUS_MAX: 4 = 4;

The most header status facts one report may carry.

APP_NAVIGATION_MENU_MAXconstant

const APP_NAVIGATION_MENU_MAX: 12 = 12;

The most ⋯ menu commands one report may carry.

APP_NAVIGATION_LABEL_MAXconstant

const APP_NAVIGATION_LABEL_MAX: 80 = 80;

The longest crumb or command label a host shows.

inertHostNavigationconstant

const inertHostNavigation: HostNavigation;

Navigation for a root with no host chrome, such as a workbench fixture: it accepts every report and never asks the App to go back.

resultRowSchemaV1constant

const resultRowSchemaV1: Schema.Struct<{
  media: Schema.optional<
    Schema.Struct<{
      path: Schema.String;
      format: Schema.Literals<readonly ["fungi:image", "fungi:video"]>;
    }>
  >;
  id: Schema.String;
  title: Schema.String;
  detail: Schema.optional<Schema.String>;
  tone: Schema.optional<
    Schema.Literals<
      readonly ["attention", "running", "error", "settled", "muted"]
    >
  >;
  status: Schema.optional<
    Schema.Struct<{
      label: Schema.String;
      tone: Schema.Literals<
        readonly [
          "neutral",
          "primary",
          "secondary",
          "accent",
          "success",
          "info",
          "warning",
          "error",
        ]
      >;
    }>
  >;
  open: Schema.optional<
    Schema.Struct<{
      params: Schema.$Array<
        Schema.Struct<{
          key: Schema.String;
          value: Schema.String;
        }>
      >;
    }>
  >;
}>;

A finished App call as a person reads it: a shared row plus an optional thumbnail.

messageAuthor()function

function messageAuthor(meta):
  | {
      id: string;
      name: string;
      kind?: "agent";
    }
  | undefined;

The author a message’s metadata names; none for anything else.

Parameters

Parameter	Type
`meta`	`MessageMetaValue \| undefined`

Returns

Type Literal

{
  id: string;
  name: string;
  kind?: "agent";
}

Name	Type	Description
`id`	`string`	-
`name`	`string`	-
`kind?`	`"agent"`	Present only when the author is another Agent the host admitted a delegated send or reply from; a line’s text never sets it. Human and host/system authors carry no kind.

undefined

messageDelegationReply()function

function messageDelegationReply(meta):
  | {
      agentId: string;
      sessionId: string;
      commandId: string;
      outcome:
        | "completed"
        | "failed"
        | "interrupted"
        | "cancelled"
        | "outcome_unknown";
      diagnostic?: string;
      waitingOnYou?: object[];
    }
  | undefined;

The authenticated delegation reply a message’s metadata carries; none for any other line, including text that merely looks like a reply.

Parameters

Parameter	Type
`meta`	`MessageMetaValue \| undefined`

Returns

Type Literal

{
  agentId: string;
  sessionId: string;
  commandId: string;
  outcome: "completed" | "failed" | "interrupted" | "cancelled" | "outcome_unknown";
  diagnostic?: string;
  waitingOnYou?: object[];
}

Name	Type	Default value	Description
`agentId`	`string`	`identifier`	-
`sessionId`	`string`	`identifier`	-
`commandId`	`string`	`identifier`	-
`outcome`	`"completed" \| "failed" \| "interrupted" \| "cancelled" \| "outcome_unknown"`	-	The exact settlement outcome; failures are never collapsed.
`diagnostic?`	`string`	-	Bounded, single-line terminal diagnostic for work that did not complete.
`waitingOnYou?`	`object[]`	-	Open items of the replying Session that now wait on the recipient.

undefined

authorMeta()function

function authorMeta(author): AuthorMeta;

The metadata the host attaches for one authenticated author.

Parameters

Parameter	Type	Description
`author`	`{ id: string; name: string; kind?: "agent"; }`	-
`author.id`	`string`	-
`author.name`	`string`	-
`author.kind?`	`"agent"`	Present only when the author is another Agent the host admitted a delegated send or reply from; a line’s text never sets it. Human and host/system authors carry no kind.

Returns

AuthorMeta

renameAppAgent()function

function renameAppAgent(
  capabilities,
  input,
): Promise<{
  agentId: string;
  name: string;
  avatar: {
    v: 1;
    character: "mushroom" | "cat" | "burger";
    appearance: z.ZodRecord<
      z.ZodString,
      z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
    >;
    expression: string;
    renderStyle:
      | "plain"
      | "pencil"
      | "manga"
      | "riso"
      | "halftone"
      | "blueprint"
      | "crt"
      | "watercolor";
  };
  sessionOperations: readonly ("agent.manage" | "agent.read" | "agent.send")[];
}>;

Rename an Agent through the host-granted owner-only capability.

Parameters

Parameter	Type
`capabilities`	`CapabilityDirectory`
`input`	`AppAgentRenameInput`

Returns

Promise<{ agentId: string; name: string; avatar: { v: 1; character: "mushroom" | "cat" | "burger"; appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>; expression: string; renderStyle: | "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor"; }; sessionOperations: readonly ("agent.manage" | "agent.read" | "agent.send")[]; }>

setAppAgentAvatar()function

function setAppAgentAvatar(
  capabilities,
  input,
): Promise<{
  agentId: string;
  name: string;
  avatar: {
    v: 1;
    character: "mushroom" | "cat" | "burger";
    appearance: z.ZodRecord<
      z.ZodString,
      z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
    >;
    expression: string;
    renderStyle:
      | "plain"
      | "pencil"
      | "manga"
      | "riso"
      | "halftone"
      | "blueprint"
      | "crt"
      | "watercolor";
  };
  sessionOperations: readonly ("agent.manage" | "agent.read" | "agent.send")[];
}>;

Change an Agent’s avatar through the host-granted owner-only capability.

Parameters

Parameter	Type
`capabilities`	`CapabilityDirectory`
`input`	`AppAgentAvatarInput`

Returns

listAppAgents()function

function listAppAgents(capabilities): Promise<readonly object[]>;

List the Agents in the host-granted Team or local-project scope.

Parameters

Parameter	Type
`capabilities`	`CapabilityDirectory`

Returns

Promise<readonly object[]>

createAppAgent()function

function createAppAgent(
  capabilities,
  input,
): Promise<{
  agentId: string;
  name: string;
  avatar: {
    v: 1;
    character: "mushroom" | "cat" | "burger";
    appearance: z.ZodRecord<
      z.ZodString,
      z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
    >;
    expression: string;
    renderStyle:
      | "plain"
      | "pencil"
      | "manga"
      | "riso"
      | "halftone"
      | "blueprint"
      | "crt"
      | "watercolor";
  };
  sessionOperations: readonly ("agent.manage" | "agent.read" | "agent.send")[];
}>;

Create an Agent through the Team directory selected by the host.

Parameters

Parameter	Type
`capabilities`	`CapabilityDirectory`
`input`	`AppAgentCreateInput`

Returns

openAppAgent()function

function openAppAgent(
  capabilities,
  input,
): Promise<
  Readonly<{
    baseUrl: string;
    fetch: {
      (input, init?): Promise<Response>;
      (input, init?): Promise<Response>;
    };
    close: () => Promise<void>;
  }>
>;

Adapt one live object capability to Fetch without exposing the parent’s authenticated URL or credentials to the isolated App.

Parameters

Parameter	Type
`capabilities`	`CapabilityDirectory`
`input`	`{ agentId: string; }`
`input.agentId`	`string`

Returns

Promise<Readonly<{ baseUrl: string; fetch: { (input, init?): Promise<Response>; (input, init?): Promise<Response>; }; close: () => Promise<void>; }>>

defineCapability()function

function defineCapability<T>(id, version, schema): CapabilityContract<T>;

Define a capability with the owner’s decoder for its live RPC interface.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`id`	`string`
`version`	`number`
`schema`	`ZodType<T>`

Returns

CapabilityContract<T>

createCapabilityRegistry()function

function createCapabilityRegistry(): CapabilityRegistry;

Returns

CapabilityRegistry

registerCatalog()function

function registerCatalog(commands, catalog): Disposer;

Register one App’s Whistle catalog with its host. An App defines each command once, contributes the same catalog to its own composer runtime for slash commands, and registers it here so the shell projects it into the palette, menus, keys and the agent view. Availability is read once at registration; register again to publish a change.

Parameters

Parameter	Type	Description
`commands`	`AppCommands`	The App’s host command door, `app.commands`.
`catalog`	readonly Readonly<{ id: string; title: string; category: string; description?: string; projections?: { bindings?: { order?: number; values: readonly string[]; }; agent?: { keybind?: string; order?: number; }; help?: { order?: number; }; menu?: { order?: number; }; palette?: { order?: number; }; slash?: { aliases: readonly string[]; consumesDraft?: boolean; order?: number; arguments?: { hint: string; words?: readonly …[]; text?: { field: …; arguments: …; requestIdField?: …; }; }; }; }; action?: { inputSchema?: { [key: string]: \| string \| number \| boolean \| readonly string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| … 4 more … \| null)[] \| { …; } \| null)[] \| { …; } \| null)[] \| { …; } \| …[] \| { [key: string]: string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| … 4 more … \| null)[] \| { …; } \| null)[] \| { …; } \| null)[] \| { …; } \| …; } \| null; }; outputSchema?: { [key: string]: \| string \| number \| boolean \| readonly string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| … 4 more … \| null)[] \| { …; } \| null)[] \| { …; } \| null)[] \| { …; } \| …[] \| { [key: string]: string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| … 4 more … \| null)[] \| { …; } \| null)[] \| { …; } \| null)[] \| { …; } \| …; } \| null; }; presentation?: \| { type: "action"; } \| { type: "custom"; data: { [key: string]: \| string \| number \| boolean \| readonly string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| … 4 more … \| null)[] \| { …; } \| null)[] \| { …; } \| null)[] \| { …; } \| …[] \| { [key: string]: string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| … 4 more … \| null)[] \| { …; } \| null)[] \| { …; } \| null)[] \| { …; } \| …; } \| null; }; } \| { type: "choice"; options: readonly object[]; } \| { type: "form"; submitLabel?: string; } \| { type: "confirmation"; message: string; confirmLabel?: string; cancelLabel?: string; }; }; availability?: () => WhistleAvailability; handler: (input) => unknown; }>[]	The App’s Whistle commands, handlers included.

Returns

Disposer

Release every registration made by this call.

connectApp()function

function connectApp(options): Promise<AppRoot>;

Connects this iframe page to its authenticated host.

Parameters

Parameter	Type
`options`	`ConnectAppOptions`

Returns

Promise<AppRoot>

openMediaGeneration()function

function openMediaGeneration(capabilities): Promise<
  Readonly<{
    computerId: string;
    canGenerate: boolean;
    models: readonly object[];
    createAttempt: Promise<MediaGenerationAttempt>;
    restoreAttempt: Promise<MediaGenerationAttempt>;
  }>
>;

Discover the exact retained model catalog surfaced by the owner.

Parameters

Parameter	Type
`capabilities`	`CapabilityDirectory`

Returns

Promise<Readonly<{ computerId: string; canGenerate: boolean; models: readonly object[]; createAttempt: Promise<MediaGenerationAttempt>; restoreAttempt: Promise<MediaGenerationAttempt>; }>>

pending()function

function pending(retryAfterMs): Pending;

Return Pending with a polling delay between one and sixty seconds.

Parameters

Parameter	Type
`retryAfterMs`	`number`

Returns

Pending

statusText()function

function statusText(value, max?): string;

Make person- or Computer-supplied text fit one status item: drop unsafe characters, collapse whitespace and shorten with an ellipsis.

Parameters

Parameter	Type	Default value
`value`	`string`	`undefined`
`max`	`number`	`APP_STATUS_TEXT_MAX`

Returns

string

statusActionAllowed()function

function statusActionAllowed(items, action): boolean;

Whether an action names something the App declares now: an enabled item, and for a menu exactly one enabled option. Every hop that delivers an action applies this rule against its own latest copy of the items.

Parameters

Parameter	Type
`items`	`readonly AppStatusItem[]`
`action`	`AppStatusAction`

Returns

boolean

navigationActivationAllowed()function

function navigationActivationAllowed(state, activation): boolean;

Whether an activation names something the App published now: a crumb (and its sibling), or an enabled command. Every hop applies this rule against its own latest copy of the report, so a stale shell cannot reach the App.

Parameters

Parameter	Type
`state`	`AppNavigationState`
`activation`	`AppNavigationActivation`

Returns

boolean

References

AppError

Re-exports AppError

appStorage

Re-exports appStorage

AppStorageError

Re-exports AppStorageError

AppStorage

Re-exports AppStorage

AppStorageWatch

Re-exports AppStorageWatch

AppStorageWrite

Re-exports AppStorageWrite

AppStorageReset

Re-exports AppStorageReset

ResolvedAppStorage

Re-exports ResolvedAppStorage

agar

Import

Exports

FungiAuthorTtype alias

FungiDelegationReplyTtype alias

FungiMessageMetaTtype alias

MessageMetaValueTtype alias

AuthorMetaTtype alias

AppAgentTtype alias

AppAgentCreateInputTtype alias

AppAgentTransportHandleTtype alias

Methods

fetch()

Parameters

Returns

close()

Returns

[dispose]()

Returns

AppAgentListHandleTtype alias

Methods

list()

Returns

AppAgentCreateHandleTtype alias

Methods

create()

Parameters

Returns

AppAgentDirectoryHandleTtype alias

Type Declaration

AppAgentRenameInputTtype alias

AppAgentRenameHandleTtype alias

Methods

rename()

Parameters

Returns

AppAgentAvatarInputTtype alias

AppAgentAvatarHandleTtype alias

Methods

setAvatar()

Parameters

Returns

AppAgentToolPolicyStatusTtype alias

AppAgentToolPolicyResultTtype alias

AppAgentToolPolicyHandleTtype alias

Methods

status()

Parameters

Returns

approve()

Parameters

Returns

AppAgentTransportTtype alias

CapabilityContractTtype alias

Type Parameters

Properties

id

version

schema

CapabilityDirectoryTtype alias

Properties

version

Methods

subscribe()

Parameters

Returns

has()

Parameters

Returns

require()

Type Parameters

Parameters

Returns

CapabilityRegistryTtype alias

Type Declaration

AppCommandTtype alias

AppCommandHandlerTtype alias

Parameters

Returns

AppCommandInvocationTtype alias

FungiAuthortype alias

FungiDelegationReplytype alias

FungiMessageMetatype alias

MessageMetaValuetype alias

AuthorMetatype alias

AppAgenttype alias

AppAgentCreateInputtype alias

AppAgentTransportHandletype alias

AppAgentListHandletype alias

AppAgentCreateHandletype alias

AppAgentDirectoryHandletype alias

AppAgentRenameInputtype alias

AppAgentRenameHandletype alias

AppAgentAvatarInputtype alias

AppAgentAvatarHandletype alias

AppAgentToolPolicyStatustype alias

AppAgentToolPolicyResulttype alias

AppAgentToolPolicyHandletype alias

AppAgentTransporttype alias

CapabilityContracttype alias

CapabilityDirectorytype alias

CapabilityRegistrytype alias

AppCommandtype alias

AppCommandHandlertype alias

AppCommandInvocationtype alias

AppCommandstype alias

ConnectAppOptionstype alias

AppConnectMessagetype alias

AppReadyMessagetype alias

AppContexttype alias

AppOpenRequesttype alias

AppIdentitytype alias

AppLifecycletype alias

FocusStatetype alias

MediaGenerationInputtype alias

MediaOutputFormattype alias

MediaGenerationResulttype alias

MediaGenerationFailuretype alias

MediaGenerationOutcometype alias

MediaGenerationHandletype alias

MediaGenerationAttemptHandletype alias

MediaGenerationAttempttype alias

MediaGenerationSessiontype alias

MediaGenerationReferencetype alias

MediaModeltype alias

MediaGenerationSelectiontype alias

Pendingtype alias

AppRoottype alias