@fungi.computer/agar 0.5.0 → 0.6.0

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

@@ -47,6 +47,7 @@ export declare const FungiMessageMetaSchema: z.ZodObject<{
         ancestors: z.ZodArray<z.ZodLazy<z.ZodString>>;
         maxDepth: z.ZodNumber;
         steer: z.ZodOptional<z.ZodLiteral<true>>;
+        goal: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
         reply: z.ZodOptional<z.ZodLazy<z.ZodObject<{
             agentId: z.ZodLazy<z.ZodString>;
             sessionId: z.ZodLazy<z.ZodString>;

package/dist/agent-message-meta.js

@@ -56,6 +56,10 @@ export const FungiMessageMetaSchema = z.strictObject({
         maxDepth: z.number().int().min(1).max(8),
         /** The sender asked to steer the recipient's running turn, not queue behind it. */
         steer: z.literal(true).optional(),
+        /** A new recipient Session's objective; false opts out of an automatic goal. */
+        goal: z
+            .union([z.string().min(1).max(4_000), z.literal(false)])
+            .optional(),
         /**
          * Present only on a line the host admitted as an authenticated reply;
          * a line's text never sets it.

package/dist/agents.js

@@ -150,13 +150,22 @@ async function openOperationHandles(openRead, openWrite) {
     return {
         fetch: async (request) => {
             ensureOpen();
+            request.signal.throwIfAborted();
             const handle = request.method === "GET" ||
                 request.method === "HEAD" ||
                 openRead === openWrite
                 ? read
                 : await (write ??= openWrite());
             ensureOpen();
-            return decodeResponse(await handle.fetch(request));
+            request.signal.throwIfAborted();
+            const response = decodeResponse(await handle.fetch(request));
+            if (response.body === null)
+                return response;
+            // Request signals do not cross Cap'n Web. Cancelling the local response
+            // pipeline cancels its remote body, including EventSource's locked reader.
+            return new Response(response.body.pipeThrough(new TransformStream(), {
+                signal: request.signal,
+            }), response);
         },
         close: () => {
             if (!closing) {

package/dist/backend-declaration.js

@@ -3,7 +3,7 @@ import * as Schema from "effect/Schema";
 import { appApiSchema, appDeclarationSchema, } from "@fungi.computer/puffball/app";
 /** Build-only API projection from the schemas used by runtime calls. */
 export function buildAppApi(backend) {
-    let api = {
+    const api = {
         methods: Object.fromEntries(Object.entries(backend.methods).map(([name, method]) => [
             name,
             {
@@ -14,8 +14,7 @@ export function buildAppApi(backend) {
         ])),
     };
     if (backend.events !== undefined)
-        api = {
-            ...api,
+        Object.assign(api, {
             events: Object.fromEntries(Object.entries(backend.events).map(([name, event]) => [
                 name,
                 {
@@ -23,9 +22,9 @@ export function buildAppApi(backend) {
                     payload: z.toJSONSchema(event.payload, { io: "output" }),
                 },
             ])),
-        };
+        });
     if (backend.toolFamily !== undefined)
-        api = { ...api, toolFamily: backend.toolFamily };
+        Object.assign(api, { toolFamily: backend.toolFamily });
     return Schema.decodeUnknownSync(appApiSchema)(api);
 }
 /** Strict build-only declaration generation; Workers never import this module. */

package/dist/backend-definition.d.ts

@@ -23,8 +23,6 @@ export type MethodPolicy = Readonly<{
     requires: readonly AppCapabilityId[];
     /** Omit this method from Workflow and tool discovery; direct calls keep their validators. */
     hidden?: true;
-    /** Request anonymous read admission; hosts still require explicit installer approval. */
-    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}. */

package/dist/backend-definition.js

@@ -26,8 +26,6 @@ export function defineAppMethod(method) {
         policy = { ...policy, pending: true };
     if (method.hidden === true)
         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);

package/dist/backend.d.ts

@@ -10,8 +10,7 @@ export declare const appBackend: CapabilityContract<{
 /**
  * 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).
+ * method's declared effect.
  */
 export declare const appMethods: CapabilityContract<{
     /** Call the named method with JSON-encoded `input`; resolves with its JSON result. */

package/dist/backend.js

@@ -9,8 +9,7 @@ export const appBackend = defineCapability("app.backend", 1, z.lazy(() => rpcHan
 /**
  * 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).
+ * method's declared effect.
  */
 export const appMethods = defineCapability("app.methods", 1, z.lazy(() => rpcHandleSchema({
     call: rpcMethod(rpcDataSchema(z.unknown().transform((value) => parseJsonValue(value)))),

package/dist/errors.d.ts

@@ -5,6 +5,8 @@ export type MediaProviderDiagnostic = Readonly<{
     category: "InferenceUpstreamError" | "AiInternalError" | "TypeError" | "AbortError" | "TimeoutError" | "Error";
     /** Four- or five-digit provider prefix, or null when absent. */
     code: number | null;
+    /** Host-classified provider refusal, independent of public error prose. */
+    reason?: "credits_exhausted";
 }> | Readonly<{
     /** A completed video result could not be downloaded. */
     category: "result_download";
@@ -15,25 +17,15 @@ export type MediaProviderDiagnostic = Readonly<{
 export declare function decodeMediaProviderDiagnostic(input: unknown): MediaProviderDiagnostic;
 /**
  * Documentable wire projection of the canonical diagnostic grammar.
- * Maintained converters preserve its closed objects and numeric bounds;
- * decoding still returns the declaration-safe public diagnostic type.
+ * Its owner supplies the native Zod dialect so output declarations remain
+ * documentable without transforms, coercions or an unchecked type assertion.
  */
-export declare const mediaProviderDiagnosticWireSchema: z.ZodPipe<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodTransform<Readonly<{
-    /** Allowlisted Workers AI category; never a provider message. */
-    category: "InferenceUpstreamError" | "AiInternalError" | "TypeError" | "AbortError" | "TimeoutError" | "Error";
-    /** Four- or five-digit provider prefix, or null when absent. */
-    code: number | null;
-}> | Readonly<{
-    /** A completed video result could not be downloaded. */
-    category: "result_download";
-    /** Native Response status, including zero. */
-    status: number;
-}>, unknown>>;
+export declare const mediaProviderDiagnosticWireSchema: z.ZodType<MediaProviderDiagnostic>;
 /** Decode an ordinary Error name without retaining arbitrary upstream text. */
 export declare function decodeMediaProviderErrorCategory(input: string | undefined): Exclude<MediaProviderDiagnostic["category"], "result_download">;
 /** The closed set of reasons an AppError can state; every SDK and
  * host-reported failure is tagged with exactly one of these codes. */
-export declare const appErrorCodes: readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "COMMAND_NOT_DECLARED", "CONFLICT", "DELIVERY_PENDING", "DISCONNECTED", "FILE_TOO_LARGE", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "PROTOCOL", "SAFETY_FILTER_REFUSED", "SELECTION_CHANGED", "TIMEOUT"];
+export declare const appErrorCodes: readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "COMMAND_NOT_DECLARED", "CONFLICT", "DELIVERY_PENDING", "DISCONNECTED", "FILE_TOO_LARGE", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "MEDIA_PROVIDER_FAILURE", "MEDIA_PROVIDER_FAILURE_UNCHARGED", "PROTOCOL", "SAFETY_FILTER_REFUSED", "SELECTION_CHANGED", "TIMEOUT"];
 /** One closed App error code from `appErrorCodes`. */
 export type AppErrorCode = (typeof appErrorCodes)[number];
 /** One pending-delivery refusal shared by admission and the shell. */

package/dist/errors.js

@@ -1,7 +1,7 @@
 import * as Schema from "effect/Schema";
 import * as Option from "effect/Option";
 import * as z from "zod";
-import { mediaProviderDiagnosticSchema, mediaProviderErrorCategorySchema, } from "./internal/media-diagnostic.js";
+import { mediaProviderDiagnosticSchema, mediaProviderDiagnosticZodSchema, mediaProviderErrorCategorySchema, } from "./internal/media-diagnostic.js";
 /** Decode only safe provider facts, rejecting unmodeled private fields. */
 export function decodeMediaProviderDiagnostic(input) {
     // Bidirectional projection check, erased from the Promise declaration graph.
@@ -11,14 +11,10 @@ export function decodeMediaProviderDiagnostic(input) {
 }
 /**
  * Documentable wire projection of the canonical diagnostic grammar.
- * Maintained converters preserve its closed objects and numeric bounds;
- * decoding still returns the declaration-safe public diagnostic type.
+ * Its owner supplies the native Zod dialect so output declarations remain
+ * documentable without transforms, coercions or an unchecked type assertion.
  */
-export const mediaProviderDiagnosticWireSchema = z
-    .fromJSONSchema(Schema.toJsonSchemaDocument(mediaProviderDiagnosticSchema, {
-    onExcessProperty: "error",
-}).schema)
-    .transform(decodeMediaProviderDiagnostic);
+export const mediaProviderDiagnosticWireSchema = mediaProviderDiagnosticZodSchema;
 /** Decode an ordinary Error name without retaining arbitrary upstream text. */
 export function decodeMediaProviderErrorCategory(input) {
     return (Option.getOrUndefined(Schema.decodeUnknownOption(mediaProviderErrorCategorySchema)(input)) ?? "Error");
@@ -38,6 +34,8 @@ export const appErrorCodes = [
     "IDENTITY",
     "INSUFFICIENT_CREDIT",
     "INVALID_ARGUMENT",
+    "MEDIA_PROVIDER_FAILURE",
+    "MEDIA_PROVIDER_FAILURE_UNCHARGED",
     "PROTOCOL",
     "SAFETY_FILTER_REFUSED",
     "SELECTION_CHANGED",
@@ -116,13 +114,21 @@ const errorCopy = {
         title: "Request not accepted",
         message: "The App couldn't use the details in this request.",
     },
+    MEDIA_PROVIDER_FAILURE: {
+        title: "Generation failed",
+        message: "The model couldn't complete this generation. Change the prompt or model and send again.",
+    },
+    MEDIA_PROVIDER_FAILURE_UNCHARGED: {
+        title: "Generation failed",
+        message: "The model couldn't complete this generation. You weren't charged. Change the prompt or model and send again.",
+    },
     PROTOCOL: {
         title: "Couldn't read the response",
         message: "The App received a response it couldn't use.",
     },
     SAFETY_FILTER_REFUSED: {
-        title: "Safety filter refused this prompt",
-        message: "The model's safety filter refused this prompt — try rewording.",
+        title: "Generation refused",
+        message: "The model refused this generation. Change the prompt or reference image and send again.",
     },
     SELECTION_CHANGED: {
         title: "Selection changed",

package/dist/internal/media-diagnostic.d.ts

@@ -1,11 +1,29 @@
 import * as Schema from "effect/Schema";
+import * as z from "zod";
 /** Names emitted by the maintained Workers AI boundary, never arbitrary names. */
 export declare const mediaProviderErrorCategorySchema: Schema.Literals<readonly ["InferenceUpstreamError", "AiInternalError", "TypeError", "AbortError", "TimeoutError", "Error"]>;
 /** One canonical grammar for safe provider facts across Media transports. */
 export declare const mediaProviderDiagnosticSchema: Schema.Union<readonly [Schema.Struct<{
     readonly category: Schema.Literals<readonly ["InferenceUpstreamError", "AiInternalError", "TypeError", "AbortError", "TimeoutError", "Error"]>;
     readonly code: Schema.NullOr<Schema.Int>;
+    readonly reason: Schema.optionalKey<Schema.Literal<"credits_exhausted">>;
 }>, Schema.Struct<{
     readonly category: Schema.Literal<"result_download">;
     readonly status: Schema.Int;
 }>]>;
+/** Documentable Promise transport grammar; this module owns both schema dialects. */
+export declare const mediaProviderDiagnosticZodSchema: z.ZodUnion<readonly [z.ZodObject<{
+    category: z.ZodEnum<{
+        InferenceUpstreamError: "InferenceUpstreamError";
+        AiInternalError: "AiInternalError";
+        TypeError: "TypeError";
+        AbortError: "AbortError";
+        TimeoutError: "TimeoutError";
+        Error: "Error";
+    }>;
+    code: z.ZodNullable<z.ZodNumber>;
+    reason: z.ZodOptional<z.ZodLiteral<"credits_exhausted">>;
+}, z.core.$strict>, z.ZodObject<{
+    category: z.ZodLiteral<"result_download">;
+    status: z.ZodNumber;
+}, z.core.$strict>]>;

package/dist/internal/media-diagnostic.js

@@ -1,21 +1,47 @@
 import * as Schema from "effect/Schema";
-/** Names emitted by the maintained Workers AI boundary, never arbitrary names. */
-export const mediaProviderErrorCategorySchema = Schema.Literals([
+import * as z from "zod";
+const categories = [
     "InferenceUpstreamError",
     "AiInternalError",
     "TypeError",
     "AbortError",
     "TimeoutError",
     "Error",
-]);
+];
+const providerCodeBounds = { minimum: 0, maximum: 99_999 };
+const responseStatusBounds = { minimum: 0, maximum: 599 };
+/** Names emitted by the maintained Workers AI boundary, never arbitrary names. */
+export const mediaProviderErrorCategorySchema = Schema.Literals(categories);
 /** One canonical grammar for safe provider facts across Media transports. */
 export const mediaProviderDiagnosticSchema = Schema.Union([
     Schema.Struct({
         category: mediaProviderErrorCategorySchema,
-        code: Schema.NullOr(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 99_999 }))),
+        code: Schema.NullOr(Schema.Int.check(Schema.isBetween(providerCodeBounds))),
+        reason: Schema.optionalKey(Schema.Literal("credits_exhausted")),
     }),
     Schema.Struct({
         category: Schema.Literal("result_download"),
-        status: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 599 })),
+        status: Schema.Int.check(Schema.isBetween(responseStatusBounds)),
+    }),
+]);
+/** Documentable Promise transport grammar; this module owns both schema dialects. */
+export const mediaProviderDiagnosticZodSchema = z.union([
+    z.strictObject({
+        category: z.enum(categories),
+        code: z
+            .number()
+            .int()
+            .min(providerCodeBounds.minimum)
+            .max(providerCodeBounds.maximum)
+            .nullable(),
+        reason: z.literal("credits_exhausted").optional(),
+    }),
+    z.strictObject({
+        category: z.literal("result_download"),
+        status: z
+            .number()
+            .int()
+            .min(responseStatusBounds.minimum)
+            .max(responseStatusBounds.maximum),
     }),
 ]);

package/dist/media-json.d.ts

@@ -75,6 +75,7 @@ export declare const mediaGenerationJsonRequestSchema: Schema.Struct<{
         readonly aspectRatio: Schema.optional<Schema.Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>>;
         readonly generateAudio: Schema.optional<Schema.Boolean>;
         readonly references: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly computerId: Schema.optional<Schema.String>;
             readonly path: Schema.String;
             readonly role: Schema.optional<Schema.Literals<readonly ["first-frame", "last-frame", "reference"]>>;
         }>>>;
@@ -115,11 +116,12 @@ export declare const mediaGenerationJsonOutcomeSchema: Schema.Union<readonly [Sc
         readonly provider: Schema.optional<Schema.Union<readonly [Schema.Struct<{
             readonly category: Schema.Literals<readonly ["InferenceUpstreamError", "AiInternalError", "TypeError", "AbortError", "TimeoutError", "Error"]>;
             readonly code: Schema.NullOr<Schema.Int>;
+            readonly reason: Schema.optionalKey<Schema.Literal<"credits_exhausted">>;
         }>, Schema.Struct<{
             readonly category: Schema.Literal<"result_download">;
             readonly status: Schema.Int;
         }>]>>;
-        readonly code: Schema.Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
+        readonly code: Schema.Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "MEDIA_PROVIDER_FAILURE", "MEDIA_PROVIDER_FAILURE_UNCHARGED", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
         readonly retryable: Schema.Boolean;
     }>;
 }>]>;
@@ -151,11 +153,12 @@ export declare const mediaGenerationJsonReplySchema: Schema.Union<readonly [Sche
         readonly provider: Schema.optional<Schema.Union<readonly [Schema.Struct<{
             readonly category: Schema.Literals<readonly ["InferenceUpstreamError", "AiInternalError", "TypeError", "AbortError", "TimeoutError", "Error"]>;
             readonly code: Schema.NullOr<Schema.Int>;
+            readonly reason: Schema.optionalKey<Schema.Literal<"credits_exhausted">>;
         }>, Schema.Struct<{
             readonly category: Schema.Literal<"result_download">;
             readonly status: Schema.Int;
         }>]>>;
-        readonly code: Schema.Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
+        readonly code: Schema.Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "MEDIA_PROVIDER_FAILURE", "MEDIA_PROVIDER_FAILURE_UNCHARGED", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
         readonly retryable: Schema.Boolean;
     }>;
 }>]>, Schema.declare<Readonly<{

package/dist/media.d.ts

@@ -278,6 +278,8 @@ export declare const mediaGenerationSelectionSchema: Schema.Struct<{
     readonly aspectRatio: Schema.optional<Schema.Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>>;
     readonly generateAudio: Schema.optional<Schema.Boolean>;
     readonly references: Schema.optional<Schema.$Array<Schema.Struct<{
+        /** Omit for the selected Computer; a named Computer requires its own authorization. */
+        readonly computerId: Schema.optional<Schema.String>;
         readonly path: Schema.String;
         readonly role: Schema.optional<Schema.Literals<readonly ["first-frame", "last-frame", "reference"]>>;
     }>>>;
@@ -357,11 +359,12 @@ export declare const mediaGenerationFailureSchema: Schema.Struct<{
     readonly provider: Schema.optional<Schema.Union<readonly [Schema.Struct<{
         readonly category: Schema.Literals<readonly ["InferenceUpstreamError", "AiInternalError", "TypeError", "AbortError", "TimeoutError", "Error"]>;
         readonly code: Schema.NullOr<Schema.Int>;
+        readonly reason: Schema.optionalKey<Schema.Literal<"credits_exhausted">>;
     }>, Schema.Struct<{
         readonly category: Schema.Literal<"result_download">;
         readonly status: Schema.Int;
     }>]>>;
-    readonly code: Schema.Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
+    readonly code: Schema.Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "MEDIA_PROVIDER_FAILURE", "MEDIA_PROVIDER_FAILURE_UNCHARGED", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
     readonly retryable: Schema.Boolean;
 }>;
 /** Capability contract for generating Media (images or video). Apps

package/dist/media.js

@@ -109,6 +109,8 @@ export const mediaVideoAspectRatioSchema = Schema.Literals([
     "9:21",
 ]);
 const referenceSchema = Schema.Struct({
+    /** Omit for the selected Computer; a named Computer requires its own authorization. */
+    computerId: Schema.optional(text(256)),
     path: text(4_096),
     role: Schema.optional(mediaVideoReferenceRoleSchema),
 });
@@ -297,6 +299,8 @@ export const mediaGenerationFailureSchema = Schema.Struct({
         "IDENTITY",
         "INSUFFICIENT_CREDIT",
         "INVALID_ARGUMENT",
+        "MEDIA_PROVIDER_FAILURE",
+        "MEDIA_PROVIDER_FAILURE_UNCHARGED",
         "PROTOCOL",
         "SAFETY_FILTER_REFUSED",
         "TIMEOUT",

package/docs/api/backend-definition.md

@@ -28,7 +28,6 @@ type MethodPolicy = Readonly<{
   effect: "read" | "write" | "external";
   requires: readonly AppCapabilityId[];
   hidden?: true;
-  anonymous?: true;
   pending?: true;
   present?: Readonly<{
     verb: string;
@@ -229,9 +228,9 @@ Define a typed method once; neither discovery nor builds execute its handler.
 
 #### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `method`  | `Omit`\<`Readonly`\<\{ `description`: `string`; `effect`: `"external"` \| `"read"` \| `"write"`; `requires`: readonly ( \| `"agent.list"` \| `"agent.manage"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"approvals"` \| `"apps.open"` \| `"apps.call"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`)[]; `hidden?`: `true`; `anonymous?`: `true`; `pending?`: `true`; `present?`: `Readonly`\<\{ `verb`: `string`; \}\>; \}\>, `"present"`\> & \{ input: I; output: O; present?: Readonly\<\{ verb: string; row: (call: Readonly\<\{ input: output\<I\>; output: output\<O\>; \}\>) =\> \{ readonly id: string; readonly title: string; ... 4 more ...; readonly media?: \{ ...; \} \| undefined; \}; rows: Readonly\<...\>; \}\> \| undefined; \} & (\{ ...; \} \| \{ ...; \}) |
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `method`  | `Omit`\<`Readonly`\<\{ `description`: `string`; `effect`: `"external"` \| `"read"` \| `"write"`; `requires`: readonly ( \| `"agent.list"` \| `"agent.manage"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"approvals"` \| `"apps.open"` \| `"apps.call"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`)[]; `hidden?`: `true`; `pending?`: `true`; `present?`: `Readonly`\<\{ `verb`: `string`; \}\>; \}\>, `"present"`\> & \{ input: I; output: O; present?: Readonly\<\{ verb: string; row: (call: Readonly\<\{ input: output\<I\>; output: output\<O\>; \}\>) =\> \{ readonly id: string; readonly title: string; ... 4 more ...; readonly media?: \{ ...; \} \| undefined; \}; rows: Readonly\<...\>; \}\> \| undefined; \} & (\{ ...; \} \| \{ ...; \}) |
 
 #### Returns
 

package/docs/api/backend.md

@@ -135,8 +135,7 @@ const appMethods: CapabilityContract<{
 
 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).
+method's declared effect.
 
 ---
 

package/docs/api/errors.md

@@ -63,6 +63,8 @@ readonly code:
   | "IDENTITY"
   | "INSUFFICIENT_CREDIT"
   | "INVALID_ARGUMENT"
+  | "MEDIA_PROVIDER_FAILURE"
+  | "MEDIA_PROVIDER_FAILURE_UNCHARGED"
   | "PROTOCOL"
   | "SAFETY_FILTER_REFUSED"
   | "SELECTION_CHANGED"
@@ -90,6 +92,7 @@ type MediaProviderDiagnostic =
         | "TimeoutError"
         | "Error";
       code: number | null;
+      reason?: "credits_exhausted";
     }>
   | Readonly<{
       category: "result_download";
@@ -186,31 +189,13 @@ automatically.
 ### mediaProviderDiagnosticWireSchema
 
 ```ts
-const mediaProviderDiagnosticWireSchema: ZodPipe<
-  ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>,
-  ZodTransform<
-    | Readonly<{
-        category:
-          | "InferenceUpstreamError"
-          | "AiInternalError"
-          | "TypeError"
-          | "AbortError"
-          | "TimeoutError"
-          | "Error";
-        code: number | null;
-      }>
-    | Readonly<{
-        category: "result_download";
-        status: number;
-      }>,
-    unknown
-  >
->;
+const mediaProviderDiagnosticWireSchema: z.ZodType<MediaProviderDiagnostic> =
+  mediaProviderDiagnosticZodSchema;
 ```
 
-Documentable wire projection of the canonical diagnostic grammar. Maintained
-converters preserve its closed objects and numeric bounds; decoding still
-returns the declaration-safe public diagnostic type.
+Documentable wire projection of the canonical diagnostic grammar. Its owner
+supplies the native Zod dialect so output declarations remain documentable
+without transforms, coercions or an unchecked type assertion.
 
 ---
 
@@ -230,6 +215,8 @@ const appErrorCodes: readonly [
   "IDENTITY",
   "INSUFFICIENT_CREDIT",
   "INVALID_ARGUMENT",
+  "MEDIA_PROVIDER_FAILURE",
+  "MEDIA_PROVIDER_FAILURE_UNCHARGED",
   "PROTOCOL",
   "SAFETY_FILTER_REFUSED",
   "SELECTION_CHANGED",
@@ -303,10 +290,10 @@ prerequisites, so they can accompany a non-retryable operation.
 
 #### Parameters
 
-| Parameter    | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cause`      | `unknown`                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `overrides?` | `Partial`\<`Record`\< \| `"CANCELLED"` \| `"CAPABILITY_DENIED"` \| `"CAPABILITY_REVOKED"` \| `"COMMAND_NOT_DECLARED"` \| `"CONFLICT"` \| `"DELIVERY_PENDING"` \| `"DISCONNECTED"` \| `"FILE_TOO_LARGE"` \| `"HOST_FAILURE"` \| `"IDENTITY"` \| `"INSUFFICIENT_CREDIT"` \| `"INVALID_ARGUMENT"` \| `"PROTOCOL"` \| `"SAFETY_FILTER_REFUSED"` \| `"SELECTION_CHANGED"` \| `"TIMEOUT"`, `Readonly`\<\{ `title`: `string`; `message`: `string`; \}\>\>\> |
+| Parameter    | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cause`      | `unknown`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `overrides?` | `Partial`\<`Record`\< \| `"CANCELLED"` \| `"CAPABILITY_DENIED"` \| `"CAPABILITY_REVOKED"` \| `"COMMAND_NOT_DECLARED"` \| `"CONFLICT"` \| `"DELIVERY_PENDING"` \| `"DISCONNECTED"` \| `"FILE_TOO_LARGE"` \| `"HOST_FAILURE"` \| `"IDENTITY"` \| `"INSUFFICIENT_CREDIT"` \| `"INVALID_ARGUMENT"` \| `"MEDIA_PROVIDER_FAILURE"` \| `"MEDIA_PROVIDER_FAILURE_UNCHARGED"` \| `"PROTOCOL"` \| `"SAFETY_FILTER_REFUSED"` \| `"SELECTION_CHANGED"` \| `"TIMEOUT"`, `Readonly`\<\{ `title`: `string`; `message`: `string`; \}\>\>\> |
 
 #### Returns
 

package/docs/api/index.md

@@ -2111,6 +2111,7 @@ const FungiMessageMetaSchema: ZodObject<{
      ancestors: ZodArray<ZodLazy<ZodString>>;
      maxDepth: ZodNumber;
      steer: ZodOptional<ZodLiteral<true>>;
+     goal: ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<false>]>>;
      reply: ZodOptional<ZodLazy<ZodObject<{
         agentId: ZodLazy<ZodString>;
         sessionId: ZodLazy<ZodString>;
@@ -2708,6 +2709,7 @@ const mediaGenerationSelectionSchema: Struct<{
   references: optional<
     $Array<
       Struct<{
+        computerId: optional<String>;
         path: String;
         role: optional<
           Literals<readonly ["first-frame", "last-frame", "reference"]>
@@ -2761,6 +2763,7 @@ const mediaGenerationFailureSchema: Struct<{
             ]
           >;
           code: NullOr<Int>;
+          reason: optionalKey<Literal<"credits_exhausted">>;
         }>,
         Struct<{
           category: Literal<"result_download">;
@@ -2779,6 +2782,8 @@ const mediaGenerationFailureSchema: Struct<{
       "IDENTITY",
       "INSUFFICIENT_CREDIT",
       "INVALID_ARGUMENT",
+      "MEDIA_PROVIDER_FAILURE",
+      "MEDIA_PROVIDER_FAILURE_UNCHARGED",
       "PROTOCOL",
       "SAFETY_FILTER_REFUSED",
       "TIMEOUT",

package/docs/api/media-json.md

@@ -385,6 +385,7 @@ const mediaGenerationJsonRequestSchema: Struct<{
      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<{
+        computerId: optional<String>;
         path: String;
         role: optional<Literals<readonly [..., ..., ...]>>;
      }>>>;
@@ -425,11 +426,12 @@ const mediaGenerationJsonOutcomeSchema: Union<readonly [Struct<{
      provider: optional<Union<readonly [Struct<{
         category: ...;
         code: ...;
+        reason: ...;
       }>, Struct<{
         category: ...;
         status: ...;
      }>]>>;
-     code: Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
+     code: Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "MEDIA_PROVIDER_FAILURE", "MEDIA_PROVIDER_FAILURE_UNCHARGED", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
      retryable: Boolean;
   }>;
 }>]>;
@@ -463,7 +465,7 @@ const mediaGenerationJsonReplySchema: Union<readonly [Union<readonly [Struct<{
      message: String;
      stage: optional<Literals<readonly [..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ...]>>;
      provider: optional<Union<readonly [..., ...]>>;
-     code: Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
+     code: Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "MEDIA_PROVIDER_FAILURE", "MEDIA_PROVIDER_FAILURE_UNCHARGED", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
      retryable: Boolean;
   }>;
 }>]>, declare<Readonly<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/agar",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "App contract for fungi.computer: typed backend methods, host capabilities and the App frontend connection",
   "type": "module",
@@ -168,7 +168,7 @@
     }
   },
   "dependencies": {
-    "@fungi.computer/puffball": "0.2.0",
+    "@fungi.computer/puffball": "0.3.0",
     "@fungi.computer/whistle": "0.3.0",
     "@opentui/keymap": "0.5.10",
     "@fungi.computer/capnweb": "0.12.0",