@fungi.computer/agar 0.1.0 → 0.3.0

package/README.md

@@ -1,9 +1,8 @@
 # Agar (`@fungi.computer/agar`)
 
 Agar defines typed App backends and host capabilities. Most people want
-[Oyster](https://docs.fungi.computer/reference/packages/#oyster) to run Apps or
-[Shiitake](https://docs.fungi.computer/reference/packages/#shiitake) to run
-Agents.
+[Oyster](https://docs.fungi.computer/oyster/) to run Apps or
+[Shiitake](https://docs.fungi.computer/shiitake/) to run Agents.
 
 Agar is the App contract for fungi.computer. It defines an App's typed backend
 methods, connects its frontend to a host through typed capabilities, and gives
@@ -336,10 +335,15 @@ the declared methods separately.
 
 ## Connect and release
 
-connectApp takes an exact `expectedHostOrigin` and optional abort signal. It
-checks the parent window, origin, protocol and transferred port before returning
-an AppRoot. It permits one live connection per frontend page. Do not use a
-wildcard origin or a stranger-controlled query parameter as the expected host.
+`connectApp({ host: "parent", signal })` discovers the host through the existing
+parent handshake, without reading a referrer or accepting an origin parameter.
+Serve the App document with CSP `frame-ancestors` pinned to its allowed host.
+The browser checks the entire ancestor chain; without that policy an unrelated
+site embedding the App could become its host. Hub and Oyster supply this policy
+on their App document routes. Only the public, secret-free ready announcement
+uses `"*"`; connection acceptance checks the actual parent Window, its
+non-opaque origin, protocol and single transferred port before returning an
+AppRoot. It permits one live connection per frontend page.
 
 The root supplies:
 
@@ -557,14 +561,18 @@ const dispose = mountApp(root, { name: "Bazaar" }, ({ app }) => (
 import.meta.hot?.dispose(dispose);
 ```
 
-`mountApp` authenticates the iframe host using the parsed referrer origin,
-applies and subscribes to its theme, and restores the original theme on
+`mountApp` discovers its actual parent through Agar's existing handshake,
+independently of referrer policy. The parent must have a non-opaque origin and
+transfer exactly one port for the validated epoch. Top-level launches remain
+standalone; embedded pages without a valid handshake report `not-hosted` with an
+`AppError` and a visible alert rather than silently becoming standalone. It
+applies and subscribes to the host's theme, and restores the original theme on
 disconnect or unmount. Its render callback receives `connecting`, `live`,
-`standalone` (no host or usable referrer), or `ended` (failed/closed
-connection). Only `live` carries an AppRoot. The returned disposer aborts a
-pending handshake, releases subscriptions, disposes the connection and unmounts
-React. A late connection is disposed too. Existing App-open React performance
-marks are emitted at root render and commits.
+`standalone` (a top-level launch), `not-hosted` (an initial connection failure),
+or `ended` (a closed live connection). Only `live` carries an AppRoot. The
+returned disposer aborts a pending handshake, releases subscriptions, disposes
+the connection and unmounts React. A late connection is disposed too. Existing
+App-open React performance marks are emitted at root render and commits.
 
 Supply `queryClient` to wrap the App in `QueryClientProvider`. The caller owns
 that client, its cache policy and grant invalidation; mounting does not clear
@@ -751,6 +759,13 @@ The exported `mediaGenerationDescriptionSchema`,
 `mediaGenerationJsonReplySchema` and `mediaGenerationReferenceSchema` decode
 these boundaries with the existing Agar Media grammar.
 
+Failures may include safe `provider` facts: an allowlisted category and bounded
+code, or `result_download` and an HTTP status. JSON, RPC and
+`MediaGenerationError.provider` preserve the same facts and retry truth.
+`./errors` exposes declaration-safe diagnostic types and decoder helpers; one
+internal Effect schema owns validation. Private provider messages, bodies, URLs
+and causes are not diagnostic fields and are rejected at this boundary.
+
 Attempts retain their canonical request ID when restored or when polling
 Pending. The shared Agar Pending validator requires an integer `retryAfterMs`
 from 1000 to 60000. Cancellation aborts the attempt's active local requests;
@@ -761,7 +776,8 @@ the platform DOM types and `ESNext.Disposable`.
 See the [generated API](docs/api/README.md) for signatures and host ports.
 
 `@fungi.computer/agar/computer-contracts` is the runtime-neutral public home for
-`workflowGitPassResultSchema` and `WorkflowGitPassResult`. App backend
-definitions can validate host-issued Workflow pass metadata without importing
-the Computer RPC client. The parser preserves the complete credential-free HTTPS
-remote; admission, expiry and revocation remain host authority.
+Computer admission, input, dispatch, timeout and attachment-budget outcomes. App
+backend definitions can validate these outcomes without importing the Computer
+RPC client. Apps request ordinary Computer execution; Workflow Git credential
+issuance, carriage, renewal and revocation stay inside the trusted host and
+native execution boundary, not the App contract.

package/dist/agent-message-meta.d.ts

@@ -1,9 +1,10 @@
 import * as z from "zod";
 /** Who a Session line came from, as the admitting host authenticated them. */
-export declare const FungiAuthorSchema: z.ZodObject<{
+export declare const FungiAuthorSchema: z.ZodLazy<z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
-}, z.core.$strict>;
+    kind: z.ZodOptional<z.ZodLiteral<"agent">>;
+}, z.core.$strict>>;
 /** Who a Session line came from, as the admitting host authenticated them. */
 export type FungiAuthor = z.infer<typeof FungiAuthorSchema>;
 /**
@@ -11,10 +12,10 @@ export type FungiAuthor = z.infer<typeof FungiAuthorSchema>;
  * mail it sent. `commandId` is the replying Session's accepted command, the
  * same id as the sender's `agents.send` receipt.
  */
-export declare const FungiDelegationReplySchema: z.ZodObject<{
-    agentId: z.ZodString;
-    sessionId: z.ZodString;
-    commandId: z.ZodString;
+export declare const FungiDelegationReplySchema: z.ZodLazy<z.ZodObject<{
+    agentId: z.ZodLazy<z.ZodString>;
+    sessionId: z.ZodLazy<z.ZodString>;
+    commandId: z.ZodLazy<z.ZodString>;
     outcome: z.ZodEnum<{
         completed: "completed";
         failed: "failed";
@@ -23,7 +24,7 @@ export declare const FungiDelegationReplySchema: z.ZodObject<{
         outcome_unknown: "outcome_unknown";
     }>;
     diagnostic: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** A delegated Agent's reply as the admitting host authenticated it. */
 export type FungiDelegationReply = z.infer<typeof FungiDelegationReplySchema>;
 /**
@@ -31,17 +32,19 @@ export type FungiDelegationReply = z.infer<typeof FungiDelegationReplySchema>;
  * Shiitake stores it opaquely; the host writes it and Apps read it.
  */
 export declare const FungiMessageMetaSchema: z.ZodObject<{
-    author: z.ZodOptional<z.ZodObject<{
+    author: z.ZodOptional<z.ZodLazy<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
-    }, z.core.$strict>>;
+        kind: z.ZodOptional<z.ZodLiteral<"agent">>;
+    }, z.core.$strict>>>;
+    sourceRequestId: z.ZodOptional<z.ZodLazy<z.ZodString>>;
     delegation: z.ZodOptional<z.ZodObject<{
-        ancestors: z.ZodArray<z.ZodString>;
+        ancestors: z.ZodArray<z.ZodLazy<z.ZodString>>;
         maxDepth: z.ZodNumber;
-        reply: z.ZodOptional<z.ZodObject<{
-            agentId: z.ZodString;
-            sessionId: z.ZodString;
-            commandId: z.ZodString;
+        reply: z.ZodOptional<z.ZodLazy<z.ZodObject<{
+            agentId: z.ZodLazy<z.ZodString>;
+            sessionId: z.ZodLazy<z.ZodString>;
+            commandId: z.ZodLazy<z.ZodString>;
             outcome: z.ZodEnum<{
                 completed: "completed";
                 failed: "failed";
@@ -50,7 +53,7 @@ export declare const FungiMessageMetaSchema: z.ZodObject<{
                 outcome_unknown: "outcome_unknown";
             }>;
             diagnostic: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** The metadata the host attaches to every prompt and operator line it admits. */
@@ -68,7 +71,9 @@ export declare function messageAuthor(meta: MessageMetaValue | undefined): Fungi
 export declare function messageDelegationReply(meta: MessageMetaValue | undefined): FungiDelegationReply | undefined;
 /** The metadata the host attaches for one authenticated author, as JSON. */
 export type AuthorMeta = Readonly<{
-    author: Readonly<FungiAuthor>;
+    author: Readonly<{
+        [K in keyof FungiAuthor]: Exclude<FungiAuthor[K], undefined>;
+    }>;
 }>;
 /** The metadata the host attaches for one authenticated author. */
 export declare function authorMeta(author: FungiAuthor): AuthorMeta;

package/dist/agent-message-meta.js

@@ -1,16 +1,22 @@
 import * as z from "zod";
 /** Who a Session line came from, as the admitting host authenticated them. */
-export const FungiAuthorSchema = z.strictObject({
+export const FungiAuthorSchema = z.lazy(() => z.strictObject({
     id: z.string().min(1).max(256),
     name: z.string().min(1).max(128),
-});
-const identifier = z.string().min(1).max(256);
+    /**
+     * 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
+     * authors carry no kind.
+     */
+    kind: z.literal("agent").optional(),
+}));
+const identifier = z.lazy(() => z.string().min(1).max(256));
 /**
  * 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.
  */
-export const FungiDelegationReplySchema = z.strictObject({
+export const FungiDelegationReplySchema = z.lazy(() => z.strictObject({
     agentId: identifier,
     sessionId: identifier,
     commandId: identifier,
@@ -24,13 +30,15 @@ export const FungiDelegationReplySchema = z.strictObject({
     ]),
     /** Bounded, single-line terminal diagnostic for work that did not complete. */
     diagnostic: z.string().min(1).max(200).optional(),
-});
+}));
 /**
  * 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.
  */
 export const FungiMessageMetaSchema = z.strictObject({
     author: FungiAuthorSchema.optional(),
+    /** Original caller identity when the host translates its request into an owner key. */
+    sourceRequestId: identifier.optional(),
     /** Host-admitted delegation path and its inherited abuse bound. */
     delegation: z
         .strictObject({
@@ -59,5 +67,8 @@ export function messageDelegationReply(meta) {
 }
 /** The metadata the host attaches for one authenticated author. */
 export function authorMeta(author) {
-    return { author: { id: author.id, name: author.name } };
+    const { id, name, kind } = author;
+    return kind === undefined
+        ? { author: { id, name } }
+        : { author: { id, name, kind } };
 }

package/dist/agents.d.ts

@@ -4,13 +4,44 @@ import * as z from "zod";
 import * as Schema from "effect/Schema";
 import type { CapabilityContract, CapabilityDirectory } from "./capabilities.js";
 /**
- * Validates the wire shape of an Agent record: its id, display name,
- * and which session operations (read, send, manage) this App may
- * perform on it.
+ * An Agent's avatar: Sprite's Avatar v1 envelope. Apps check its shape; the
+ * host owns the character-catalog refinement when it stores one.
+ */
+export declare const appAgentAvatarSchema: Schema.declare<{
+    v: 1;
+    character: "mushroom" | "cat" | "burger";
+    appearance: Record<string, string | number | boolean>;
+    expression: string;
+    renderStyle: "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor";
+}, {
+    v: 1;
+    character: "mushroom" | "cat" | "burger";
+    appearance: Record<string, string | number | boolean>;
+    expression: string;
+    renderStyle: "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor";
+}>;
+/**
+ * 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.
  */
 export declare const appAgentSchema: Schema.Struct<{
     readonly agentId: Schema.String;
     readonly name: Schema.String;
+    readonly avatar: Schema.declare<{
+        v: 1;
+        character: "mushroom" | "cat" | "burger";
+        appearance: Record<string, string | number | boolean>;
+        expression: string;
+        renderStyle: "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor";
+    }, {
+        v: 1;
+        character: "mushroom" | "cat" | "burger";
+        appearance: Record<string, string | number | boolean>;
+        expression: string;
+        renderStyle: "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor";
+    }>;
     readonly sessionOperations: Schema.$Array<Schema.Literals<readonly ["agent.read", "agent.send", "agent.manage"]>>;
 }>;
 /**
@@ -19,24 +50,38 @@ export declare const appAgentSchema: Schema.Struct<{
  */
 export type AppAgent = Schema.Schema.Type<typeof appAgentSchema>;
 /** The admitted AGENTS.list projection, containing only ids and display names. */
-export declare const appAgentListResultSchema: z.ZodObject<{
+export declare const appAgentListResultSchema: z.ZodLazy<z.ZodObject<{
     agents: z.ZodArray<z.ZodObject<{
         agentId: z.ZodString;
         name: z.ZodString;
     }, z.core.$strict>>;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Computer provisioning is a Team creation choice, separate from Home policy. */
 export declare const appAgentComputerSchema: Schema.Literals<readonly ["new", "none"]>;
-/** Validates Agent creation input: a name, a caller-chosen request id and an
- * optional Computer provisioning choice. */
+/** Validates Agent creation input: a name, a caller-chosen request id, an
+ * optional Computer provisioning choice and an optional chosen avatar. */
 export declare const appAgentCreateInputSchema: Schema.Struct<{
     readonly name: Schema.String;
     readonly requestId: Schema.String;
     readonly computer: Schema.optionalKey<Schema.Literals<readonly ["new", "none"]>>;
+    readonly avatar: Schema.optionalKey<Schema.declare<{
+        v: 1;
+        character: "mushroom" | "cat" | "burger";
+        appearance: Record<string, string | number | boolean>;
+        expression: string;
+        renderStyle: "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor";
+    }, {
+        v: 1;
+        character: "mushroom" | "cat" | "burger";
+        appearance: Record<string, string | number | boolean>;
+        expression: string;
+        renderStyle: "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor";
+    }>>;
 }>;
 /**
  * Input for creating a new Agent: its name, a caller-chosen request id
- * for idempotency, and whether to provision a new Computer for it.
+ * for idempotency, whether to provision a new Computer for it, and the
+ * avatar it wears (omitted, it wears its seeded avatar).
  */
 export type AppAgentCreateInput = Readonly<Schema.Schema.Type<typeof appAgentCreateInputSchema>>;
 /** Live object-capability shape received from Cap'n Web. */
@@ -93,26 +138,54 @@ export type AppAgentRenameHandle = {
 export declare const agentRename: CapabilityContract<AppAgentRenameHandle>;
 /** Rename an Agent through the host-granted owner-only capability. */
 export declare function renameAppAgent(capabilities: CapabilityDirectory, input: AppAgentRenameInput): Promise<AppAgent>;
+/** Validates avatar input: the target Agent and the avatar it now wears. */
+export declare const appAgentAvatarInputSchema: Schema.Struct<{
+    readonly agentId: Schema.String;
+    readonly avatar: Schema.declare<{
+        v: 1;
+        character: "mushroom" | "cat" | "burger";
+        appearance: Record<string, string | number | boolean>;
+        expression: string;
+        renderStyle: "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor";
+    }, {
+        v: 1;
+        character: "mushroom" | "cat" | "burger";
+        appearance: Record<string, string | number | boolean>;
+        expression: string;
+        renderStyle: "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor";
+    }>;
+}>;
+/** Input for changing an existing Agent's avatar. */
+export type AppAgentAvatarInput = Readonly<Schema.Schema.Type<typeof appAgentAvatarInputSchema>>;
+/** Capability handle for changing an Agent's avatar. */
+export type AppAgentAvatarHandle = {
+    /** Set an existing Agent's avatar and return its updated record. */
+    setAvatar(input: AppAgentAvatarInput): Promise<AppAgent>;
+};
+/** Owner-only capability to change an existing Agent's avatar; not every host grants it. */
+export declare const agentAvatar: CapabilityContract<AppAgentAvatarHandle>;
+/** Change an Agent's avatar through the host-granted owner-only capability. */
+export declare function setAppAgentAvatar(capabilities: CapabilityDirectory, input: AppAgentAvatarInput): Promise<AppAgent>;
 /** One Agent's App-tool policy, as the owner-only policy capability reports it. */
-export declare const appAgentToolPolicyStatusSchema: z.ZodUnion<readonly [z.ZodObject<{
+export declare const appAgentToolPolicyStatusSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     status: z.ZodLiteral<"pending">;
     revision: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     status: z.ZodLiteral<"approved">;
     revision: z.ZodString;
-}, z.core.$strip>]>;
+}, z.core.$strip>]>>;
 /** Whether an Agent's App tools are still pending the owner's approval. */
 export type AppAgentToolPolicyStatus = z.infer<typeof appAgentToolPolicyStatusSchema>;
 /** The outcome of an owner's direct App-tool approval. */
-export declare const appAgentToolPolicyResultSchema: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+export declare const appAgentToolPolicyResultSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     status: z.ZodLiteral<"pending">;
     revision: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     status: z.ZodLiteral<"approved">;
     revision: z.ZodString;
-}, z.core.$strip>]>, z.ZodObject<{
+}, z.core.$strip>]>>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strip>]>;
+}, z.core.$strip>]>>;
 /** The outcome of an owner's direct App-tool approval. */
 export type AppAgentToolPolicyResult = z.infer<typeof appAgentToolPolicyResultSchema>;
 /** Capability handle for reading and approving an Agent's App-tool policy. */

package/dist/agents.js

@@ -3,31 +3,40 @@ import * as z from "zod";
 import { defineCapability } from "./capabilities.js";
 import { rpcDataSchema, rpcHandleSchema, rpcMethod, rpcFetchHandleSchema, } from "./internal/rpc-contract.js";
 import * as Schema from "effect/Schema";
+import { avatarEnvelopeSchema, } from "@fungi.computer/sprite/avatar";
 import { AppError } from "./errors.js";
 import { reportCatchFailure } from "./failure.js";
 const boundedIdentity = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
 /**
- * Validates the wire shape of an Agent record: its id, display name,
- * and which session operations (read, send, manage) this App may
- * perform on it.
+ * An Agent's avatar: Sprite's Avatar v1 envelope. Apps check its shape; the
+ * host owns the character-catalog refinement when it stores one.
+ */
+export const appAgentAvatarSchema = Schema.declare((value) => avatarEnvelopeSchema.safeParse(value).success, { expected: "an Avatar v1 descriptor" });
+/**
+ * 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.
  */
 export const appAgentSchema = Schema.Struct({
     agentId: boundedIdentity,
     name: boundedIdentity,
+    avatar: appAgentAvatarSchema,
     sessionOperations: Schema.Array(Schema.Literals(["agent.read", "agent.send", "agent.manage"])),
 });
 /** The admitted AGENTS.list projection, containing only ids and display names. */
-export const appAgentListResultSchema = z.strictObject({
+export const appAgentListResultSchema = z.lazy(() => z.strictObject({
     agents: z.array(z.strictObject({ agentId: z.string(), name: z.string() })),
-});
+}));
 /** Computer provisioning is a Team creation choice, separate from Home policy. */
 export const appAgentComputerSchema = Schema.Literals(["new", "none"]);
-/** Validates Agent creation input: a name, a caller-chosen request id and an
- * optional Computer provisioning choice. */
+/** Validates Agent creation input: a name, a caller-chosen request id, an
+ * optional Computer provisioning choice and an optional chosen avatar. */
 export const appAgentCreateInputSchema = Schema.Struct({
     name: boundedIdentity,
     requestId: boundedIdentity,
     computer: Schema.optionalKey(appAgentComputerSchema),
+    avatar: Schema.optionalKey(appAgentAvatarSchema),
 });
 const appAgentDirectorySchema = Schema.Array(appAgentSchema);
 const decodeAgents = Schema.decodeUnknownSync(appAgentDirectorySchema, {
@@ -36,64 +45,78 @@ const decodeAgents = Schema.decodeUnknownSync(appAgentDirectorySchema, {
 const decodeAgentId = Schema.decodeUnknownSync(boundedIdentity);
 const decodeResponse = Schema.decodeUnknownSync(Schema.instanceOf(Response));
 /** Capability to list the Agents visible to this App in read-only form. */
-export const agentList = defineCapability("agent.list", 1, rpcHandleSchema({
+export const agentList = defineCapability("agent.list", 1, z.lazy(() => rpcHandleSchema({
     list: rpcMethod(rpcDataSchema(z.unknown().transform((value) => decodeAgents(value)))),
-}));
+})));
 /** Capability to create new Agents and open transports to them. */
-export const agentManage = defineCapability("agent.manage", 1, rpcHandleSchema({
+export const agentManage = defineCapability("agent.manage", 1, z.lazy(() => rpcHandleSchema({
     open: rpcMethod(rpcFetchHandleSchema),
     create: rpcMethod(rpcDataSchema(z
         .unknown()
         .transform((value) => Schema.decodeUnknownSync(appAgentSchema)(value)))),
-}));
+})));
 /** Validates Agent rename input: the target Agent and its new display name. */
 export const appAgentRenameInputSchema = Schema.Struct({
     agentId: boundedIdentity,
     name: boundedIdentity,
 });
 /** Owner-only capability to rename an existing Agent; not every host grants it. */
-export const agentRename = defineCapability("agent.rename", 1, rpcHandleSchema({
+export const agentRename = defineCapability("agent.rename", 1, z.lazy(() => rpcHandleSchema({
     rename: rpcMethod(rpcDataSchema(z
         .unknown()
         .transform((value) => Schema.decodeUnknownSync(appAgentSchema)(value)))),
-}));
+})));
 /** Rename an Agent through the host-granted owner-only capability. */
 export async function renameAppAgent(capabilities, input) {
     const request = Schema.decodeUnknownSync(appAgentRenameInputSchema)(input);
     const agent = await capabilities.require(agentRename).rename(request);
     return Schema.decodeUnknownSync(appAgentSchema)(agent);
 }
+/** Validates avatar input: the target Agent and the avatar it now wears. */
+export const appAgentAvatarInputSchema = Schema.Struct({
+    agentId: boundedIdentity,
+    avatar: appAgentAvatarSchema,
+});
+/** Owner-only capability to change an existing Agent's avatar; not every host grants it. */
+export const agentAvatar = defineCapability("agent.avatar", 1, z.lazy(() => rpcHandleSchema({
+    setAvatar: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(appAgentSchema)(value)))),
+})));
+/** Change an Agent's avatar through the host-granted owner-only capability. */
+export async function setAppAgentAvatar(capabilities, input) {
+    const request = Schema.decodeUnknownSync(appAgentAvatarInputSchema)(input);
+    const agent = await capabilities.require(agentAvatar).setAvatar(request);
+    return Schema.decodeUnknownSync(appAgentSchema)(agent);
+}
 /** One Agent's App-tool policy, as the owner-only policy capability reports it. */
-export const appAgentToolPolicyStatusSchema = z.union([
+export const appAgentToolPolicyStatusSchema = z.lazy(() => z.union([
     z.object({ status: z.literal("pending"), revision: z.string() }),
     z.object({ status: z.literal("approved"), revision: z.string() }),
-]);
+]));
 /** The outcome of an owner's direct App-tool approval. */
-export const appAgentToolPolicyResultSchema = z.union([
-    appAgentToolPolicyStatusSchema,
-    z.object({ error: z.string() }),
-]);
+export const appAgentToolPolicyResultSchema = z.lazy(() => z.union([appAgentToolPolicyStatusSchema, z.object({ error: z.string() })]));
 /** Owner-only capability to read and approve an Agent's App-tool policy. */
-export const agentToolPolicy = defineCapability("agent.toolPolicy", 1, rpcHandleSchema({
+export const agentToolPolicy = defineCapability("agent.toolPolicy", 1, z.lazy(() => rpcHandleSchema({
     status: rpcMethod(rpcDataSchema(z.union([appAgentToolPolicyStatusSchema, z.null()]))),
     approve: rpcMethod(rpcDataSchema(appAgentToolPolicyResultSchema)),
-}));
+})));
 /**
  * Capability for read-only Agent sessions: open a transport to an
  * existing Agent, or read the member's inbox feed.
  */
-export const agentSessionRead = defineCapability("agent.read", 1, rpcHandleSchema({
+export const agentSessionRead = defineCapability("agent.read", 1, z.lazy(() => rpcHandleSchema({
     open: rpcMethod(rpcFetchHandleSchema),
     openInbox: rpcMethod(rpcFetchHandleSchema),
-}));
+})));
 /**
  * Capability for read-write Agent sessions: open a transport to an
  * existing Agent and send to it, including the member's inbox feed.
  */
-export const agentSessionWrite = defineCapability("agent.send", 1, rpcHandleSchema({
+export const agentSessionWrite = defineCapability("agent.send", 1, z.lazy(() => rpcHandleSchema({
     open: rpcMethod(rpcFetchHandleSchema),
     openInbox: rpcMethod(rpcFetchHandleSchema),
-}));
+})));
 /** List the Agents in the host-granted Team or local-project scope. */
 export async function listAppAgents(capabilities) {
     return decodeAgents(await capabilities.require(agentList).list());

package/dist/approvals.d.ts

@@ -0,0 +1,5 @@
+import { type Approvals } from "@fungi.computer/approvals";
+import { type CapabilityContract } from "./capabilities.js";
+export type { Approvals } from "@fungi.computer/approvals";
+/** Member-bound approval view. Authentication and current rights belong to the host. */
+export declare const approvals: CapabilityContract<Approvals>;

package/dist/approvals.js

@@ -0,0 +1,36 @@
+import * as Schema from "effect/Schema";
+import * as z from "zod";
+import { ApprovalViewSchema, ApprovalRefusalReasonSchema, AutoApproveInputSchema, } from "@fungi.computer/approvals";
+import { defineCapability } from "./capabilities.js";
+import { rpcDataSchema, rpcHandleSchema, rpcMethod, } from "./internal/rpc-contract.js";
+const refusal = Schema.Struct({
+    kind: Schema.Literal("refused"),
+    reason: ApprovalRefusalReasonSchema,
+});
+const page = Schema.Struct({
+    items: Schema.Array(ApprovalViewSchema),
+    nextCursor: Schema.NullOr(Schema.String),
+});
+const answer = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("answered"), view: ApprovalViewSchema }),
+    refusal,
+]);
+const policy = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("updated"),
+        rule: AutoApproveInputSchema,
+    }),
+    refusal,
+]);
+// Match the existing storage/Agent capability adapters: the maintained RPC
+// helpers bind native stub receivers, decode data and release result envelopes.
+const data = (schema) => rpcDataSchema(z
+    .unknown()
+    .transform((value) => Schema.decodeUnknownSync(schema, { onExcessProperty: "error" })(value)));
+/** Member-bound approval view. Authentication and current rights belong to the host. */
+export const approvals = defineCapability("approvals", 1, z.lazy(() => rpcHandleSchema({
+    list: rpcMethod(data(page)),
+    get: rpcMethod(data(Schema.NullOr(ApprovalViewSchema))),
+    answer: rpcMethod(data(answer)),
+    setAutoApprove: rpcMethod(data(policy)),
+})));

package/dist/apps.js

@@ -36,12 +36,12 @@ export const appRoleChoiceSchema = z
  * `role` answers which App that open would reach (null when none fills it),
  * so a caller can name or hide its entry without hard-coding another App.
  */
-export const appsOpen = defineCapability("apps.open", 1, rpcHandleSchema({
+export const appsOpen = defineCapability("apps.open", 1, z.lazy(() => rpcHandleSchema({
     open: rpcVoid,
     role: rpcMethod(rpcDataSchema(appRoleChoiceSchema)),
-}));
+})));
 export const openApp = (directory, input) => directory.require(appsOpen).open(input);
 /** Call a declared method of another App as the signed-in member. Caller grants never travel. */
-export const appsCall = defineCapability("apps.call", 1, rpcHandleSchema({
+export const appsCall = defineCapability("apps.call", 1, z.lazy(() => rpcHandleSchema({
     call: rpcMethod(rpcDataSchema(z.unknown().transform((value) => parseJsonValue(value)))),
-}));
+})));