@fungi.computer/agar 0.1.0 → 0.2.0

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

@@ -1,9 +1,9 @@
 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>;
+}, z.core.$strict>>;
 /** Who a Session line came from, as the admitting host authenticated them. */
 export type FungiAuthor = z.infer<typeof FungiAuthorSchema>;
 /**
@@ -11,10 +11,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 +23,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 +31,17 @@ 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>>;
+    }, z.core.$strict>>>;
     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 +50,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. */

package/dist/agent-message-meta.js

@@ -1,16 +1,16 @@
 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);
+}));
+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,7 +24,7 @@ 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.

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/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)))),
-}));
+})));

package/dist/backend-definition.d.ts

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import type { GillCall, GillReply } from "@fungi.computer/gills";
+import type { GillCall, GillReply, ResultRow } from "@fungi.computer/gills";
 import type { AppBackendGill } from "./gills.js";
 export type { AppBackendGill } from "./gills.js";
 import { type AppMethodCallContext } from "@fungi.computer/puffball/app-method-runtime";
@@ -10,10 +10,10 @@ export { pending, pendingSchema, type Pending } from "./pending.js";
 /** EVENTS.emit acknowledges delivery with native void, not a JSON value. */
 export declare const appEventEmitResultSchema: z.ZodUndefined;
 /** App-originated Session send refusal; retry advice is a duration, not a timestamp. */
-export declare const appSendBudgetRefusalSchema: z.ZodObject<{
+export declare const appSendBudgetRefusalSchema: z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"send_budget_exceeded">;
     retryAfterMs: z.ZodNumber;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** A declined Session send, with how long to wait before retrying. */
 export type AppSendBudgetRefusal = z.output<typeof appSendBudgetRefusalSchema>;
 /** A method's schemas own both its TypeScript contract and JSON boundary. */
@@ -27,19 +27,56 @@ export type MethodPolicy = Readonly<{
     anonymous?: true;
     /** Allow the shared Pending result while this method is still working. */
     pending?: true;
+    /** Past tense for timelines ("made", "wrote"); the row itself comes from {@link MethodPresentation}. */
+    present?: Readonly<{
+        verb: string;
+    }>;
+}>;
+/** Decodes and bounds result rows; see `resultRows` in `@fungi.computer/agar/method-presentation`. */
+export type ResultRowCodec = Readonly<{
+    /** Check one projected row against the shared row's bounds; throws when it breaks them. */
+    decode: (row: ResultRow) => ResultRow;
+    /** The row's JSON boundary, as the generated `present` method's output. */
+    schema: z.ZodType;
+}>;
+/**
+ * How a finished call reads to a person: a pure projection run in the App
+ * backend. `rows` is `resultRows` from
+ * `@fungi.computer/agar/method-presentation`; only a backend that presents
+ * imports it, so one without presentations carries no row decoder.
+ */
+export type MethodPresentation<I, O> = Readonly<{
+    /** Past tense for timelines: "made", "wrote", "pushed". */
+    verb: string;
+    /** Pure: one finished call to the row a person reads. */
+    row: (call: Readonly<{
+        input: I;
+        output: O;
+    }>) => ResultRow;
+    /** The shared row codec, `resultRows`. */
+    rows: ResultRowCodec;
 }>;
+/** Name of the generated, hidden read method that projects a finished call into its row. */
+export declare const presentMethodName = "present";
 /** Prepared method export consumed by the backend and its build. */
 export type AppBackendMethod<Context = void> = Readonly<{
     policy: MethodPolicy;
     input: z.ZodType;
     output: z.ZodType;
+    /** Parse a recorded call against this method's schemas and project its row. */
+    present?: (input: WhistleJsonValue, output: WhistleJsonValue) => ResultRow;
+    /** The row's JSON boundary, present exactly when `present` is. */
+    presentRow?: z.ZodType;
     /** Parse the raw input, run the handler, and return its JSON result. */
     call: (input: WhistleJsonValue, context: Context, caller: AppMethodCallContext) => Promise<WhistleJsonValue>;
 }>;
+/** The prepared methods of one backend, keyed by their public names. */
+export type AppBackendMethods<Context = void> = Readonly<Record<string, AppBackendMethod<Context>>>;
 /** Define a typed method once; neither discovery nor builds execute its handler. */
-export declare function defineAppMethod<I extends z.ZodType, O extends z.ZodType, Context = void>(method: MethodPolicy & {
+export declare function defineAppMethod<I extends z.ZodType, O extends z.ZodType, Context = void>(method: Omit<MethodPolicy, "present"> & {
     input: I;
     output: O;
+    present?: MethodPresentation<z.output<I>, z.output<O>>;
 } & ({
     pending: true;
     handler: (input: z.output<I>, context: Context, caller: AppMethodCallContext) => z.input<O> | Pending | Promise<z.input<O> | Pending>;

package/dist/backend-definition.js

@@ -6,10 +6,12 @@ export { pending, pendingSchema } from "./pending.js";
 /** EVENTS.emit acknowledges delivery with native void, not a JSON value. */
 export const appEventEmitResultSchema = z.undefined();
 /** App-originated Session send refusal; retry advice is a duration, not a timestamp. */
-export const appSendBudgetRefusalSchema = z.strictObject({
+export const appSendBudgetRefusalSchema = z.lazy(() => z.strictObject({
     error: z.literal("send_budget_exceeded"),
     retryAfterMs: z.number().int().min(1).max(60_000),
-});
+}));
+/** Name of the generated, hidden read method that projects a finished call into its row. */
+export const presentMethodName = "present";
 /** Define a typed method once; neither discovery nor builds execute its handler. */
 export function defineAppMethod(method) {
     const output = method.pending === true
@@ -26,16 +28,31 @@ export function defineAppMethod(method) {
         policy = { ...policy, hidden: true };
     if (method.anonymous === true)
         policy = { ...policy, anonymous: true };
+    const call = async (rawInput, context, rawCaller) => {
+        const caller = parseAppMethodCallContext(rawCaller);
+        const parsed = method.input.parse(rawInput);
+        const result = await method.handler(parsed, context, caller);
+        return z.json().parse(output.parse(result));
+    };
+    const presentation = method.present;
+    if (presentation === undefined)
+        return Object.freeze({
+            policy: Object.freeze(policy),
+            input: method.input,
+            output,
+            call,
+        });
+    policy = { ...policy, present: Object.freeze({ verb: presentation.verb }) };
     return Object.freeze({
         policy: Object.freeze(policy),
         input: method.input,
         output,
-        call: async (rawInput, context, rawCaller) => {
-            const caller = parseAppMethodCallContext(rawCaller);
-            const parsed = method.input.parse(rawInput);
-            const result = await method.handler(parsed, context, caller);
-            return z.json().parse(output.parse(result));
-        },
+        present: (rawInput, rawOutput) => presentation.rows.decode(presentation.row({
+            input: method.input.parse(rawInput),
+            output: method.output.parse(rawOutput),
+        })),
+        presentRow: presentation.rows.schema,
+        call,
     });
 }
 /** The generated method RPC answers with a typed reply: a handler's
@@ -54,9 +71,52 @@ async function methodReply(run) {
         });
     }
 }
+const presentInput = z.strictObject({
+    method: z.string().min(1).max(80),
+    input: z.json(),
+    output: z.json(),
+});
+const generatedPresentMethods = new WeakSet();
+/**
+ * Methods that declare a presentation share one generated, hidden read method
+ * that projects a recorded call into its row, so hosts reach it through the
+ * ordinary method admission instead of a second invocation path.
+ */
+function withPresentation(all) {
+    // A backend rebuilt from another definition's methods regenerates its own.
+    const methods = Object.fromEntries(Object.entries(all).filter(([name, method]) => name !== presentMethodName || !generatedPresentMethods.has(method)));
+    const presenting = new Map(Object.entries(methods).filter(([, method]) => method.present !== undefined));
+    const presentRow = [...presenting.values()][0]?.presentRow;
+    if (presentRow === undefined)
+        return methods;
+    if (Object.hasOwn(methods, presentMethodName))
+        throw new Error(`App backend method is reserved: ${presentMethodName}`);
+    const present = Object.freeze({
+        policy: Object.freeze({
+            description: "Project one finished call of a presenting method into its result row.",
+            effect: "read",
+            requires: Object.freeze([]),
+            hidden: true,
+        }),
+        input: presentInput,
+        output: presentRow,
+        call: (rawInput) => Promise.resolve().then(() => {
+            const request = presentInput.parse(rawInput);
+            const row = presenting
+                .get(request.method)
+                ?.present?.(request.input, request.output);
+            if (row === undefined)
+                throw new Error(`Undeclared App presentation: ${request.method}`);
+            return z.json().parse(presentRow.parse(row));
+        }),
+    });
+    generatedPresentMethods.add(present);
+    return { ...methods, [presentMethodName]: present };
+}
 /** Generate the API from the method exports; callers cannot supply a second catalog. */
 export function defineAppBackend(options) {
-    const methods = new Map(Object.entries(options.methods));
+    const declared = withPresentation(options.methods);
+    const methods = new Map(Object.entries(declared));
     for (const name of methods.keys())
         if (!isAppApiMethodName(name))
             throw new Error(`Invalid App backend method name: ${name}`);
@@ -97,7 +157,7 @@ export function defineAppBackend(options) {
         });
     };
     let definition = {
-        methods: Object.freeze({ ...options.methods }),
+        methods: Object.freeze({ ...declared }),
         implement: (implementation) => {
             const members = new Map();
             let prototype = implementation.prototype;

package/dist/backend.js

@@ -3,18 +3,18 @@ import { defineCapability } from "./capabilities.js";
 import { parseJsonValue } from "@fungi.computer/whistle/wire";
 import { rpcDataSchema, rpcHandleSchema, rpcMethod, } from "./internal/rpc-contract.js";
 /** Invoke this App's admitted backend. The App defines its JSON request/result. */
-export const appBackend = defineCapability("app.backend", 1, rpcHandleSchema({
+export const appBackend = defineCapability("app.backend", 1, z.lazy(() => rpcHandleSchema({
     request: rpcMethod(rpcDataSchema(z.unknown().transform((value) => parseJsonValue(value)))),
-}));
+})));
 /**
  * Call one of this App's declared, typed methods through its host. Unlike
  * `appBackend`, the host knows which method is called, so it can apply the
  * method's declared effect (for example, allow only `read` methods to a
  * visitor of a public App).
  */
-export const appMethods = defineCapability("app.methods", 1, rpcHandleSchema({
+export const appMethods = defineCapability("app.methods", 1, z.lazy(() => rpcHandleSchema({
     call: rpcMethod(rpcDataSchema(z.unknown().transform((value) => parseJsonValue(value)))),
-}));
+})));
 /** The admitting host overwrites this header from its authenticated principal.
  * App request bodies and incoming browser headers never supply this identity. */
 export const appBackendActorHeader = "X-Agar-Actor-Id";

package/dist/channels.js

@@ -84,14 +84,14 @@ export const appWebsiteReplyResponseSchema = z.strictObject({
     status: z.literal("sent"),
 });
 /** Reading website conversations is never an automatic default-App grant. */
-export const channelsRead = defineCapability("channels.read", 1, rpcHandleSchema({
+export const channelsRead = defineCapability("channels.read", 1, z.lazy(() => rpcHandleSchema({
     list: rpcMethod(rpcDataSchema(appWebsitePageSchema)),
     conversations: rpcMethod(rpcDataSchema(appWebsiteConversationPageSchema)),
-}));
+})));
 /** Member-only takeover; separate consent from read-only channel access. */
-export const channelsPersonalManage = defineCapability("channels.personal.manage", 1, rpcHandleSchema({
+export const channelsPersonalManage = defineCapability("channels.personal.manage", 1, z.lazy(() => rpcHandleSchema({
     hold: rpcMethod(rpcDataSchema(appWebsiteConversationSchema)),
     release: rpcMethod(rpcDataSchema(appWebsiteConversationSchema)),
     dismiss: rpcMethod(rpcDataSchema(appWebsiteConversationSchema)),
     reply: rpcMethod(rpcDataSchema(appWebsiteReplyResponseSchema)),
-}));
+})));