@fungi.computer/agar 0.1.0 → 0.3.0

package/dist/internal/app-session.js

@@ -5,6 +5,7 @@ import * as Schema from "effect/Schema";
  */
 import { newMessagePortRpcSession, RpcStub, RpcTarget, } from "@fungi.computer/capnweb";
 import { statusActionAllowed } from "../status.js";
+import { navigationActivationAllowed } from "../window.js";
 import { AppError } from "../errors.js";
 import { reportCatchFailure } from "../failure.js";
 import { createLocalBindingState, createReservedChordState, installBrowserBridge, } from "./browser-bridge.js";
@@ -13,7 +14,7 @@ import { createCapabilityDirectory, disposeRpcValue, } from "./capabilities.js";
 import { createAppCommands } from "./commands.js";
 import { APP_PROTOCOL_VERSION, } from "./protocol.js";
 import { callRpc, rpcFailure, rpcSuccess, unwrapRpcResult } from "./result.js";
-import { parseBrowserAction, parseBrowserActionOutcomeResult, parseBootstrapResult, parseHostReconfiguration, parseContext, parseErrorData, parseFact, parseAgentSessionSelection, parseIdentity, parseLifecycle, parseNavigation, parseStatusAction, parseStatusItems, parseNavigationStateInput, parsePermissionOutcomeResult, parsePermissionRequest, parseReservedChords, parseTheme, parseToast, parseVoidResult, } from "./schemas.js";
+import { parseBrowserAction, parseBrowserActionOutcomeResult, parseBootstrapResult, parseHostReconfiguration, parseContext, parseErrorData, parseFact, parseAgentSessionSelection, parseIdentity, parseLifecycle, parseNavigation, parseNavigationActivation, parseNavigationState, parseStatusAction, parseStatusItems, parseNavigationStateInput, parsePermissionOutcomeResult, parsePermissionRequest, parseReservedChords, parseTheme, parseToast, parseVoidResult, } from "./schemas.js";
 const rpcStubSchema = Schema.declare((value) => value instanceof RpcStub);
 import { createReadonlyStore } from "./store.js";
 class AppClientTarget extends RpcTarget {
@@ -57,6 +58,21 @@ class AppClientTarget extends RpcTarget {
             return rpcFailure(cause);
         }
     }
+    async activateNavigation(value) {
+        try {
+            if (this.#disposed)
+                throw disconnected();
+            const activation = parseNavigationActivation(value);
+            // A shell's stale copy can still send a crumb or command the App has
+            // since dropped; only what it published now reaches the App.
+            if (!navigationActivationAllowed(this.#state.navigation, activation))
+                return rpcSuccess(false);
+            return rpcSuccess(await (this.#state.activate?.(activation) ?? false));
+        }
+        catch (cause) {
+            return rpcFailure(cause);
+        }
+    }
     async activateStatus(value) {
         try {
             if (this.#disposed)
@@ -231,6 +247,7 @@ function createBrokenPromise(remote) {
 function createClientState() {
     return {
         statusItems: [],
+        navigation: { canGoBack: false },
         bindings: createLocalBindingState(),
         chords: createReservedChordState([]),
         context: createReadonlyStore({
@@ -293,6 +310,7 @@ function createRootRuntime(options, identity, capabilities) {
             () => {
                 options.state.beforeClose = undefined;
                 options.state.back = undefined;
+                options.state.activate = undefined;
                 options.state.statusAction = undefined;
             },
             () => {
@@ -370,8 +388,26 @@ function createAppWindow(state, remote, assertConnected) {
             assertConnected();
             const wire = parseNavigationStateInput(input);
             state.canGoBack = wire.canGoBack;
+            state.navigation = parseNavigationState(wire);
             await callRpc(remote.reportNavigation(wire), parseVoidResult);
         },
+        onActivate(handler) {
+            assertConnected();
+            if (state.activate !== undefined)
+                throw new AppError("The App already owns navigation activations", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            state.activate = handler;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                if (state.activate === handler)
+                    state.activate = undefined;
+            };
+        },
         onBack(handler) {
             assertConnected();
             if (state.back !== undefined)

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

@@ -0,0 +1,11 @@
+import * as Schema from "effect/Schema";
+/** 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>;
+}>, Schema.Struct<{
+    readonly category: Schema.Literal<"result_download">;
+    readonly status: Schema.Int;
+}>]>;

package/dist/internal/media-diagnostic.js

@@ -0,0 +1,21 @@
+import * as Schema from "effect/Schema";
+/** Names emitted by the maintained Workers AI boundary, never arbitrary names. */
+export const mediaProviderErrorCategorySchema = Schema.Literals([
+    "InferenceUpstreamError",
+    "AiInternalError",
+    "TypeError",
+    "AbortError",
+    "TimeoutError",
+    "Error",
+]);
+/** 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 }))),
+    }),
+    Schema.Struct({
+        category: Schema.Literal("result_download"),
+        status: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 599 })),
+    }),
+]);

package/dist/internal/protocol.d.ts

@@ -2,7 +2,7 @@ import type { AppCommand } from "../commands.js";
 import type { WhistleExecutionOrigin, WhistleJsonValue } from "@fungi.computer/whistle";
 import type { AppContext, AppIdentity, AppLifecycle, FocusState } from "../lifecycle.js";
 import type { AppBrowserAction, AppBrowserActionOutcome, AgentSessionSelection, AppPermissionOutcome, AppPermissionRequest, AppStatusAction, AppStatusItem, FileNavigationInput, ToastInput } from "../ui.js";
-import type { APP_NAVIGATION_CONTRACT_VERSION } from "../window.js";
+import type { APP_NAVIGATION_CONTRACT_VERSION, AppNavigationActivation, AppNavigationState } from "../window.js";
 import type { AppErrorData } from "./app-error.js";
 import type { RpcResult } from "./result.js";
 import type { WhistleFailure } from "@fungi.computer/whistle";
@@ -17,6 +17,8 @@ export type AppClientRpc = {
     requestClose(): Promise<RpcResult<boolean>>;
     /** Ask the App to go back one step in its own history; `true` when it did. */
     requestBack(): Promise<RpcResult<boolean>>;
+    /** The person used a crumb or header command; `true` when the App acted. */
+    activateNavigation(activation: AppNavigationActivation): Promise<RpcResult<boolean>>;
     /** The person used one of the App's status items; `true` when it acted. */
     activateStatus(action: AppStatusAction): Promise<RpcResult<boolean>>;
     updateContext(context: VersionedFact<AppContext>): Promise<RpcResult<void>>;
@@ -51,9 +53,7 @@ export type AppHostRpc = {
 /** The versioned navigation contract an App reports to its host. */
 export type NavigationStateWire = Readonly<{
     contractVersion: typeof APP_NAVIGATION_CONTRACT_VERSION;
-    canGoBack: boolean;
-    title?: string;
-}>;
+}> & AppNavigationState;
 /** The App iframe's handshake message announcing it is ready to connect. */
 export type AppReadyMessage = {
     readonly protocolVersion: typeof APP_PROTOCOL_VERSION;

package/dist/internal/schemas.d.ts

@@ -8,10 +8,14 @@ import type { WhistleJsonValue } from "@fungi.computer/whistle";
 import type { AppContext, AppIdentity, AppLifecycle, FocusState } from "../lifecycle.js";
 import type { AppBrowserAction, AppBrowserActionRefusal, AppBrowserActionOutcome, AppPermissionOutcome, AppStatusItem, FileNavigationInput, ToastInput } from "../ui.js";
 import type { AppErrorData } from "./app-error.js";
-import type { CapabilityGrantWire, AppHostReconfigurationWire, CommandInvocationResultWire, HostBootstrapWire, RegisteredCommandWire } from "./protocol.js";
+import type { CapabilityGrantWire, AppHostReconfigurationWire, CommandInvocationResultWire, HostBootstrapWire, NavigationStateWire, RegisteredCommandWire } from "./protocol.js";
 import type { RpcResult } from "./result.js";
-import { APP_NAVIGATION_CONTRACT_VERSION } from "../window.js";
+import { type AppNavigationActivation } from "../window.js";
 import { type AppConnectMessage, type AppReadyMessage, type CommandInvocationWire, type ConnectRequestWire, type ReservedChord, type VersionedFact } from "./protocol.js";
+/** Effect projection of the error owner's declaration-safe pending refusal. */
+export declare const appDeliveryPendingSchema: Schema.Struct<{
+    readonly code: Schema.Literals<readonly ["DELIVERY_PENDING"]>;
+}>;
 export declare function appInvocation(value: CommandInvocationWire, signal: AbortSignal): Readonly<AppCommandInvocation>;
 export declare const parseCommand: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Readonly<{
     readonly id: string;
@@ -38,6 +42,7 @@ export declare const parseCommand: (input: unknown, options?: import("effect/Sch
         } | undefined;
         readonly slash?: {
             readonly aliases: readonly string[];
+            readonly consumesDraft?: boolean | undefined;
             readonly order?: number | undefined;
             readonly arguments?: {
                 readonly hint: string;
@@ -263,13 +268,41 @@ export declare const parseNavigation: (input: unknown, options?: import("effect/
 export declare const parseNavigationState: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Readonly<{
     canGoBack: boolean;
     title?: string;
+    crumbs?: readonly Readonly<{
+        id: string;
+        label: string;
+        siblings?: readonly Readonly<{
+            id: string;
+            label: string;
+        }>[];
+    }>[];
+    primary?: readonly Readonly<{
+        id: string;
+        label: string;
+        icon?: "play";
+        variant?: "primary" | "outline" | "ghost";
+        tone?: "destructive";
+        disabled?: boolean;
+    }>[];
+    menu?: readonly Readonly<{
+        id: string;
+        label: string;
+        icon?: "play";
+        variant?: "primary" | "outline" | "ghost";
+        tone?: "destructive";
+        disabled?: boolean;
+    }>[];
+    status?: readonly Readonly<{
+        id: string;
+        label: string;
+        presentation?: "bead";
+        tone?: "neutral" | "info" | "warning" | "success" | "error";
+    }>[];
 }>;
 /** App edge: trim the title, drop an empty one, then check the wire bounds. */
-export declare const parseNavigationStateInput: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Readonly<{
-    contractVersion: typeof APP_NAVIGATION_CONTRACT_VERSION;
-    canGoBack: boolean;
-    title?: string;
-}>;
+export declare const parseNavigationStateInput: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => NavigationStateWire;
+/** Host to App: one crumb or command the person used. */
+export declare const parseNavigationActivation: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => AppNavigationActivation;
 export declare const parseAgentSessionSelection: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Readonly<{
     agentId: string;
     sessionId: string;

package/dist/internal/schemas.js

@@ -9,27 +9,10 @@ import { flow } from "effect/Function";
 import { parseCommandDefinition, parseJsonValue, } from "@fungi.computer/whistle/wire";
 import { isUnsafeStatusCodeUnit } from "../status.js";
 import { APP_BROWSER_SAVE_MAX_BYTES, APP_BROWSER_COPY_MAX_BYTES, APP_STATUS_ITEMS_MAX, APP_STATUS_OPTIONS_MAX, APP_STATUS_TEXT_MAX, } from "../ui.js";
-import { APP_NAVIGATION_CONTRACT_VERSION, APP_NAVIGATION_TITLE_MAX, } from "../window.js";
-import { AppError } from "../errors.js";
+import { APP_NAVIGATION_CONTRACT_VERSION, APP_NAVIGATION_CRUMBS_MAX, APP_NAVIGATION_LABEL_MAX, APP_NAVIGATION_MENU_MAX, APP_NAVIGATION_PRIMARY_MAX, APP_NAVIGATION_SIBLINGS_MAX, APP_NAVIGATION_STATUS_MAX, APP_NAVIGATION_TITLE_MAX, } from "../window.js";
+import { AppError, appErrorCodes } from "../errors.js";
 import { parseFailure } from "@fungi.computer/whistle/wire";
 import { APP_CONNECT_TYPE, APP_PROTOCOL_VERSION, APP_READY_TYPE, } from "./protocol.js";
-const errorCodes = [
-    "PROTOCOL",
-    "IDENTITY",
-    "INSUFFICIENT_CREDIT",
-    "FILE_TOO_LARGE",
-    "CAPABILITY_DENIED",
-    "CAPABILITY_REVOKED",
-    "COMMAND_NOT_DECLARED",
-    "CONFLICT",
-    "INVALID_ARGUMENT",
-    "TIMEOUT",
-    "CANCELLED",
-    "DISCONNECTED",
-    "HOST_FAILURE",
-    "SELECTION_CHANGED",
-    "SAFETY_FILTER_REFUSED",
-];
 const boundedText = (maximum) => Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(maximum)));
 const boundedOptionalText = (maximum) => Schema.optional(boundedText(maximum));
 const safeInteger = Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.makeFilter(Number.isSafeInteger, {
@@ -175,15 +158,64 @@ const navigationSchema = Schema.Struct({
 const navigationTitleSchema = boundedText(APP_NAVIGATION_TITLE_MAX).pipe(Schema.check(Schema.makeFilter((title) => title.trim() === title, {
     message: "Expected a trimmed title",
 })));
+const navigationIdSchema = boundedText(64);
+const navigationLabelSchema = boundedText(APP_NAVIGATION_LABEL_MAX);
+/** Ids name what a person used; repeats would make an activation ambiguous. */
+const uniqueIds = (items) => new Set(items.map((item) => item.id)).size === items.length;
+const crumbSchema = Schema.Struct({
+    id: navigationIdSchema,
+    label: navigationLabelSchema,
+    siblings: Schema.optional(Schema.Array(Schema.Struct({ id: navigationIdSchema, label: navigationLabelSchema })).pipe(Schema.check(Schema.isMaxLength(APP_NAVIGATION_SIBLINGS_MAX)), Schema.check(Schema.makeFilter(uniqueIds, {
+        message: "Expected unique crumb sibling ids",
+    })))),
+});
+const headerCommandSchema = Schema.Struct({
+    id: navigationIdSchema,
+    label: navigationLabelSchema,
+    icon: Schema.optional(Schema.Literal("play")),
+    variant: Schema.optional(Schema.Literals(["primary", "outline", "ghost"])),
+    tone: Schema.optional(Schema.Literal("destructive")),
+    disabled: Schema.optional(Schema.Boolean),
+});
+const commandsSchema = (maximum) => Schema.Array(headerCommandSchema).pipe(Schema.check(Schema.isMaxLength(maximum)), Schema.check(Schema.makeFilter(uniqueIds, {
+    message: "Expected unique header command ids",
+})));
+const headerStatusSchema = Schema.Struct({
+    id: navigationIdSchema,
+    label: navigationLabelSchema,
+    presentation: Schema.optional(Schema.Literal("bead")),
+    tone: Schema.optional(Schema.Literals(["neutral", "info", "warning", "success", "error"])),
+});
+const navigationFields = {
+    status: Schema.optional(Schema.Array(headerStatusSchema).pipe(Schema.check(Schema.isMaxLength(APP_NAVIGATION_STATUS_MAX)), Schema.check(Schema.makeFilter(uniqueIds, {
+        message: "Expected unique header status ids",
+    })))),
+    crumbs: Schema.optional(Schema.Array(crumbSchema).pipe(Schema.check(Schema.isMaxLength(APP_NAVIGATION_CRUMBS_MAX)), Schema.check(Schema.makeFilter(uniqueIds, { message: "Expected unique crumb ids" })))),
+    primary: Schema.optional(commandsSchema(APP_NAVIGATION_PRIMARY_MAX)),
+    menu: Schema.optional(commandsSchema(APP_NAVIGATION_MENU_MAX)),
+};
 const navigationStateWireSchema = Schema.Struct({
     contractVersion: Schema.Literal(APP_NAVIGATION_CONTRACT_VERSION),
     canGoBack: Schema.Boolean,
     title: Schema.optional(navigationTitleSchema),
+    ...navigationFields,
 });
 const navigationStateInputSchema = Schema.Struct({
     canGoBack: Schema.Boolean,
     title: Schema.optional(Schema.String),
+    ...navigationFields,
 });
+const navigationActivationSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("crumb"),
+        crumbId: navigationIdSchema,
+        siblingId: Schema.optional(navigationIdSchema),
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("action"),
+        actionId: navigationIdSchema,
+    }),
+]);
 const agentSessionSelectionSchema = Schema.NullOr(Schema.Struct({
     agentId: boundedText(256),
     sessionId: boundedText(256),
@@ -211,8 +243,13 @@ const toastSchema = Schema.Struct({
     message: boundedText(512),
     tone: Schema.optional(Schema.Literals(["info", "success", "warning", "error"])),
 });
+const appErrorCodeSchema = Schema.Literals(appErrorCodes);
+/** Effect projection of the error owner's declaration-safe pending refusal. */
+export const appDeliveryPendingSchema = Schema.Struct({
+    code: appErrorCodeSchema.pick(["DELIVERY_PENDING"]),
+});
 const errorSchema = Schema.Struct({
-    code: Schema.Literals(errorCodes),
+    code: appErrorCodeSchema,
     message: boundedText(512),
     retryable: Schema.Boolean,
 });
@@ -339,25 +376,75 @@ export const parseStatusAction = decoder(Schema.Struct({
     ? { ...action }
     : { ...action, anchor: frozen({ ...action.anchor }) }), "INVALID_ARGUMENT");
 export const parseNavigation = decoder(navigationSchema, (value) => frozen({ ...value }), "INVALID_ARGUMENT");
+function statusOf(item) {
+    let copy = { id: item.id, label: item.label };
+    if (item.presentation !== undefined)
+        copy = { ...copy, presentation: item.presentation };
+    if (item.tone !== undefined)
+        copy = { ...copy, tone: item.tone };
+    return frozen(copy);
+}
+function crumbOf(crumb) {
+    const copy = { id: crumb.id, label: crumb.label };
+    if (crumb.siblings === undefined)
+        return frozen(copy);
+    return frozen({
+        ...copy,
+        siblings: frozen(crumb.siblings.map((item) => frozen({ ...item }))),
+    });
+}
+function commandOf(command) {
+    let copy = { id: command.id, label: command.label };
+    if (command.icon !== undefined)
+        copy = { ...copy, icon: command.icon };
+    if (command.variant !== undefined)
+        copy = { ...copy, variant: command.variant };
+    if (command.tone !== undefined)
+        copy = { ...copy, tone: command.tone };
+    if (command.disabled !== undefined)
+        copy = { ...copy, disabled: command.disabled };
+    return frozen(copy);
+}
+/** One report's fields, each present only when the App sent it. */
+function navigationOf(value) {
+    let state = { canGoBack: value.canGoBack };
+    if (value.title !== undefined)
+        state = { ...state, title: value.title };
+    if (value.crumbs !== undefined)
+        state = { ...state, crumbs: frozen(value.crumbs.map(crumbOf)) };
+    if (value.primary !== undefined)
+        state = { ...state, primary: frozen(value.primary.map(commandOf)) };
+    if (value.menu !== undefined)
+        state = { ...state, menu: frozen(value.menu.map(commandOf)) };
+    if (value.status !== undefined)
+        state = { ...state, status: frozen(value.status.map(statusOf)) };
+    return frozen(state);
+}
 /** Host edge: one App report, projected without its contract version. */
-export const parseNavigationState = decoder(navigationStateWireSchema, (value) => frozen(value.title === undefined
-    ? { canGoBack: value.canGoBack }
-    : { canGoBack: value.canGoBack, title: value.title }), "INVALID_ARGUMENT");
+export const parseNavigationState = decoder(navigationStateWireSchema, navigationOf, "INVALID_ARGUMENT");
 /** App edge: trim the title, drop an empty one, then check the wire bounds. */
 export const parseNavigationStateInput = decoder(navigationStateInputSchema, (value) => {
-    const title = value.title?.trim();
-    return parseNavigationStateWire(title === undefined || title.length === 0
-        ? {
-            contractVersion: APP_NAVIGATION_CONTRACT_VERSION,
-            canGoBack: value.canGoBack,
-        }
-        : {
-            contractVersion: APP_NAVIGATION_CONTRACT_VERSION,
-            canGoBack: value.canGoBack,
-            title,
-        });
+    const trimmed = value.title?.trim();
+    return parseNavigationStateWire({
+        ...navigationOf({
+            ...value,
+            title: trimmed === undefined || trimmed.length === 0 ? undefined : trimmed,
+        }),
+        contractVersion: APP_NAVIGATION_CONTRACT_VERSION,
+    });
+}, "INVALID_ARGUMENT");
+const parseNavigationStateWire = decoder(navigationStateWireSchema, (value) => frozen({
+    ...navigationOf(value),
+    contractVersion: APP_NAVIGATION_CONTRACT_VERSION,
+}), "INVALID_ARGUMENT");
+/** Host to App: one crumb or command the person used. */
+export const parseNavigationActivation = decoder(navigationActivationSchema, (value) => {
+    if (value.kind === "action")
+        return frozen({ ...value });
+    return frozen(value.siblingId === undefined
+        ? { kind: value.kind, crumbId: value.crumbId }
+        : value);
 }, "INVALID_ARGUMENT");
-const parseNavigationStateWire = decoder(navigationStateWireSchema, (value) => frozen({ ...value }), "INVALID_ARGUMENT");
 export const parseAgentSessionSelection = decoder(agentSessionSelectionSchema, (value) => value === null ? null : frozen({ ...value }), "INVALID_ARGUMENT");
 export const parsePermissionRequest = decoder(permissionRequestSchema, (value) => frozen({
     agents: frozen([...new Set(value.agents ?? [])]),

package/dist/marketplace.js

@@ -72,19 +72,21 @@ export const marketplaceAcquisitionSchema = Schema.Union([
     }),
 ]);
 /** Read the Marketplace gallery as the Team that mounted this App. */
-export const marketplaceBrowse = defineCapability("marketplace.browse", 1, rpcHandleSchema({
-    list: rpcMethod(rpcDataSchema(z.unknown().transform((value) => decodeMarketplaceBrowseResult(value)))),
-}));
+export const marketplaceBrowse = defineCapability("marketplace.browse", 1, z.lazy(() => rpcHandleSchema({
+    list: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => decodeMarketplaceBrowseResult(value)))),
+})));
 /**
  * Acquire a listing for the mounting Team. Free listings install at once;
  * paid listings return a hosted Checkout URL and install after payment.
  * The host re-checks Team authority and entitlement on every call.
  */
-export const marketplacePurchase = defineCapability("marketplace.purchase", 1, rpcHandleSchema({
+export const marketplacePurchase = defineCapability("marketplace.purchase", 1, z.lazy(() => rpcHandleSchema({
     acquire: rpcMethod(rpcDataSchema(z
         .unknown()
         .transform((value) => Schema.decodeUnknownSync(marketplaceAcquisitionSchema)(value)))),
-}));
+})));
 /** Anonymous discovery only; acquisition and launch still require Team admission. */
 export async function browsePublicMarketplace(hubOrigin, category, request = fetch) {
     const url = new URL("/api/public/marketplace/listings", hubOrigin);

package/dist/media-json.d.ts

@@ -110,6 +110,13 @@ export declare const mediaGenerationJsonOutcomeSchema: Schema.Union<readonly [Sc
     readonly failure: Schema.Struct<{
         readonly message: Schema.String;
         readonly stage: Schema.optional<Schema.Literals<readonly ["admission", "generation-authorization", "settings", "estimate", "billing", "operation", "provider", "normalization", "artifact", "destination-authorization", "destination-write"]>>;
+        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>;
+        }>, 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 retryable: Schema.Boolean;
     }>;
@@ -139,6 +146,13 @@ export declare const mediaGenerationJsonReplySchema: Schema.Union<readonly [Sche
     readonly failure: Schema.Struct<{
         readonly message: Schema.String;
         readonly stage: Schema.optional<Schema.Literals<readonly ["admission", "generation-authorization", "settings", "estimate", "billing", "operation", "provider", "normalization", "artifact", "destination-authorization", "destination-write"]>>;
+        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>;
+        }>, 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 retryable: Schema.Boolean;
     }>;

package/dist/media-json.js

@@ -165,6 +165,7 @@ export class MediaGenerationAttempt extends RpcTarget {
                         retryable: true,
                     },
                 };
+            // Preserve the decoded failure intact, including safe provider facts.
             return response;
         }
         finally {

package/dist/media-request-id.d.ts

@@ -4,4 +4,4 @@ export declare const mediaRequestIds: Readonly<{
     readonly request: import("@fungi.computer/cairn/id").IdCodec<"hub-media-request", "request", 1>;
 }>;
 /** Public wire grammar for the canonical retry identity, visible in App JSON schemas. */
-export declare const mediaRequestIdSchema: z.ZodString;
+export declare const mediaRequestIdSchema: z.ZodLazy<z.ZodString>;

package/dist/media-request-id.js

@@ -10,7 +10,7 @@ export const mediaRequestIds = defineIdFamily({
     },
 });
 /** Public wire grammar for the canonical retry identity, visible in App JSON schemas. */
-export const mediaRequestIdSchema = z
+export const mediaRequestIdSchema = z.lazy(() => z
     .string()
     .length(35)
-    .regex(/^media_request_[a-z0-9]{21}$/);
+    .regex(/^media_request_[a-z0-9]{21}$/));

package/dist/media.d.ts

@@ -1,4 +1,5 @@
 import * as Schema from "effect/Schema";
+import type { MediaProviderDiagnostic } from "./errors.js";
 export { mediaLibraryRequestSchema, mediaLibraryPathSchema, mediaLibraryResponseSchema, } from "./media-library.js";
 import type { CapabilityContract, CapabilityDirectory } from "./capabilities.js";
 import { AppError } from "./errors.js";
@@ -41,6 +42,8 @@ export type MediaGenerationFailure = Schema.Schema.Type<typeof mediaGenerationFa
 /** A decoded Media failure; null stage means the host could not identify it. */
 export declare class MediaGenerationError extends AppError {
     readonly stage: NonNullable<MediaGenerationFailure["stage"]> | null;
+    /** Bounded provider facts only; never the original provider cause. */
+    readonly provider: MediaProviderDiagnostic | undefined;
     constructor(failure: MediaGenerationFailure);
 }
 /** Transport-safe result from the host-owned generation attempt. */
@@ -341,6 +344,14 @@ export type MediaVideoResult = Schema.Schema.Type<typeof mediaVideoResultSchema>
 export declare const mediaGenerationFailureSchema: Schema.Struct<{
     readonly message: Schema.String;
     readonly stage: Schema.optional<Schema.Literals<readonly ["admission", "generation-authorization", "settings", "estimate", "billing", "operation", "provider", "normalization", "artifact", "destination-authorization", "destination-write"]>>;
+    /** Safe provider facts decoded by the one canonical Media grammar. */
+    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>;
+    }>, 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 retryable: Schema.Boolean;
 }>;

package/dist/media.js

@@ -54,18 +54,22 @@ import * as z from "zod";
 import { defineCapability } from "./capabilities.js";
 import { rpcDataSchema, rpcHandleSchema, rpcMethod, rpcVoid, } from "./internal/rpc-contract.js";
 import * as Schema from "effect/Schema";
+import { mediaProviderDiagnosticSchema } from "./internal/media-diagnostic.js";
 export { mediaLibraryRequestSchema, mediaLibraryPathSchema, mediaLibraryResponseSchema, } from "./media-library.js";
 import { AppError } from "./errors.js";
 import { ownedRpcValue } from "./internal/capabilities.js";
 /** A decoded Media failure; null stage means the host could not identify it. */
 export class MediaGenerationError extends AppError {
     stage;
+    /** Bounded provider facts only; never the original provider cause. */
+    provider;
     constructor(failure) {
         super(failure.message, {
             code: failure.code,
             retryable: failure.retryable,
         });
         this.stage = failure.stage ?? null;
+        this.provider = failure.provider;
     }
 }
 /** One narrow Media capability: discover the retained catalog and generate. */
@@ -273,6 +277,8 @@ export const mediaVideoResultSchema = Schema.Struct({
 export const mediaGenerationFailureSchema = Schema.Struct({
     message: text(512),
     stage: Schema.optional(Schema.Literals(mediaFailureStages)),
+    /** Safe provider facts decoded by the one canonical Media grammar. */
+    provider: Schema.optional(mediaProviderDiagnosticSchema),
     code: Schema.Literals([
         "CANCELLED",
         "CAPABILITY_DENIED",
@@ -327,7 +333,7 @@ const mediaAttemptHandleSchema = rpcHandleSchema({
 /** Capability contract for generating Media (images or video). Apps
  * declare it to request access; openMediaGeneration uses it to obtain
  * the host's handle. */
-export const mediaGeneration = defineCapability("media.generation", 5, rpcHandleSchema({
+export const mediaGeneration = defineCapability("media.generation", 5, z.lazy(() => rpcHandleSchema({
     describe: rpcMethod(rpcDataSchema(z.unknown().transform((value) => {
         const { computerId, canGenerate, models } = Schema.decodeUnknownSync(descriptionSchema, {
             onExcessProperty: "error",
@@ -337,7 +343,7 @@ export const mediaGeneration = defineCapability("media.generation", 5, rpcHandle
     createAttempt: rpcMethod(mediaAttemptHandleSchema),
     restoreAttempt: rpcMethod(mediaAttemptHandleSchema),
     cancelAttempt: rpcVoid,
-}));
+})));
 /** Parse a value received from the host and turn schema failures into the
  * transport-safe Agar error used by the other capability helpers. */
 function decode(schema, value) {

package/dist/method-presentation.d.ts

@@ -0,0 +1,7 @@
+import type { ResultRowCodec } from "./backend-definition.js";
+/**
+ * The shared result row's decoder and JSON boundary, for
+ * `defineAppMethod({ present: { verb, row, rows: resultRows } })`. Only
+ * backends that present import this module, so the rest carry no decoder.
+ */
+export declare const resultRows: ResultRowCodec;

package/dist/method-presentation.js

@@ -0,0 +1,14 @@
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { resultRowSchemaV1 } from "@fungi.computer/gills";
+/**
+ * The shared result row's decoder and JSON boundary, for
+ * `defineAppMethod({ present: { verb, row, rows: resultRows } })`. Only
+ * backends that present import this module, so the rest carry no decoder.
+ */
+export const resultRows = Object.freeze({
+    decode: Schema.decodeUnknownSync(resultRowSchemaV1, {
+        onExcessProperty: "error",
+    }),
+    schema: z.fromJSONSchema(Schema.toJsonSchemaDocument(resultRowSchemaV1).schema),
+});

package/dist/method-refusal.d.ts

@@ -29,7 +29,7 @@ export declare class AppMethodRefusal extends Error {
     constructor(code: AppMethodRefusalCode, message: string);
 }
 /** A refused call as it crosses the generated method boundary. */
-export declare const appMethodRefusedReplySchema: z.ZodObject<{
+export declare const appMethodRefusedReplySchema: z.ZodLazy<z.ZodObject<{
     kind: z.ZodLiteral<"refused">;
     code: z.ZodEnum<{
         unavailable: "unavailable";
@@ -39,14 +39,14 @@ export declare const appMethodRefusedReplySchema: z.ZodObject<{
         not_found: "not_found";
     }>;
     message: z.ZodString;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** A decoded {@link appMethodRefusedReplySchema} value. */
 export type AppMethodRefusedReply = z.output<typeof appMethodRefusedReplySchema>;
 /** Every generated App method RPC answers with exactly one of these. */
-export declare const appMethodReplySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const appMethodReplySchema: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"ok">;
     value: z.ZodJSONSchema;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>, z.ZodLazy<z.ZodObject<{
     kind: z.ZodLiteral<"refused">;
     code: z.ZodEnum<{
         unavailable: "unavailable";
@@ -56,7 +56,7 @@ export declare const appMethodReplySchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         not_found: "not_found";
     }>;
     message: z.ZodString;
-}, z.core.$strict>], "kind">;
+}, z.core.$strict>>], "kind">>;
 /** A decoded {@link appMethodReplySchema} value; the result is read-only JSON. */
 export type AppMethodReply = Readonly<{
     kind: "ok";