@fungi.computer/agar 0.2.0 → 0.3.1

package/dist/internal/schemas.js

@@ -10,26 +10,9 @@ import { parseCommandDefinition, parseJsonValue, } from "@fungi.computer/whistle
 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_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 } from "../errors.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, {
@@ -189,6 +172,7 @@ const crumbSchema = Schema.Struct({
 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),
@@ -199,6 +183,7 @@ const commandsSchema = (maximum) => Schema.Array(headerCommandSchema).pipe(Schem
 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 = {
@@ -258,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,
 });
@@ -387,8 +377,12 @@ export const parseStatusAction = decoder(Schema.Struct({
     : { ...action, anchor: frozen({ ...action.anchor }) }), "INVALID_ARGUMENT");
 export const parseNavigation = decoder(navigationSchema, (value) => frozen({ ...value }), "INVALID_ARGUMENT");
 function statusOf(item) {
-    const copy = { id: item.id, label: item.label };
-    return frozen(item.tone === undefined ? copy : { ...copy, tone: item.tone });
+    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 };
@@ -401,6 +395,8 @@ function crumbOf(crumb) {
 }
 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)

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.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",

package/dist/query.d.ts

@@ -54,9 +54,9 @@ export declare function useMemberInbox(app: QueryApp | null): {
             readonly nodeId: string;
             readonly iteration: string;
         };
-        readonly state: "pending" | "closed" | "answered" | "delivered" | "timed_out";
-        readonly workflowId: string | null;
+        readonly state: "pending" | "answered" | "closed" | "delivered" | "timed_out";
         readonly expiresAt: number;
+        readonly workflowId: string | null;
         readonly installationId: string;
         readonly workflowTitle: string;
         readonly reviewTitle: string;

package/dist/react-mount.d.ts

@@ -1,16 +1,22 @@
 import { type QueryClient } from "@tanstack/react-query";
 import { type ReactNode } from "react";
+import { AppError } from "./errors.js";
 import type { AppRoot } from "./root.js";
 import type { Disposer } from "./store.js";
 /** The App connection state passed to `mountApp`'s `render` callback:
  * `live` once connected, or `connecting`/`standalone`/`ended` while there
- * is no usable App. */
+ * is no usable App. An embedded page whose handshake fails is `not-hosted`,
+ * never standalone; Agar also renders that failure visibly. */
 export type AppMountState = Readonly<{
     app: AppRoot;
     status: "live";
 } | {
     app: null;
     status: "connecting" | "standalone" | "ended";
+} | {
+    app: null;
+    status: "not-hosted";
+    error: AppError;
 }>;
 /** Options passed to `mountApp`. */
 export type AppMountOptions = Readonly<{

package/dist/react-mount.js

@@ -1,6 +1,6 @@
 import { applyTheme, getTheme } from "@fungi.computer/stipe/theme";
 import { QueryClientProvider } from "@tanstack/react-query";
-import { createElement, useLayoutEffect } from "react";
+import { createElement, Fragment, useLayoutEffect, } from "react";
 import { createRoot } from "react-dom/client";
 import { connectApp } from "./connect.js";
 import { AppError } from "./errors.js";
@@ -37,17 +37,25 @@ export function mountApp(element, options, render) {
             themed = false;
         }
     };
-    const { referrer, defaultView } = element.ownerDocument;
+    const { defaultView } = element.ownerDocument;
     performance.mark("fungi.app-open.react-root-render-start");
-    if (!defaultView ||
-        defaultView.parent === defaultView ||
-        !URL.canParse(referrer)) {
+    if (!defaultView) {
+        publish({
+            app: null,
+            status: "not-hosted",
+            error: new AppError("The App document has no window", {
+                code: "DISCONNECTED",
+                retryable: false,
+            }),
+        });
+    }
+    else if (defaultView.parent === defaultView) {
         publish({ app: null, status: "standalone" });
     }
     else {
         publish({ app: null, status: "connecting" });
         void connectApp({
-            expectedHostOrigin: new URL(referrer).origin,
+            host: "parent",
             signal: controller.signal,
         })
             .then((app) => {
@@ -85,7 +93,17 @@ export function mountApp(element, options, render) {
             console.error(`${options.name} host connection failed`, cause);
             releaseConnection();
             if (!controller.signal.aborted)
-                publish({ app: null, status: "ended" });
+                publish({
+                    app: null,
+                    status: "not-hosted",
+                    error: cause instanceof AppError
+                        ? cause
+                        : new AppError("The App host is unavailable", {
+                            cause,
+                            code: "HOST_FAILURE",
+                            retryable: true,
+                        }),
+                });
         });
     }
     return () => {
@@ -104,5 +122,7 @@ function AppView({ state, render, }) {
         if (state.app)
             performance.mark("fungi.app-open.react-connected-commit");
     }, [state.app]);
-    return render(state);
+    return createElement(Fragment, null, state.status === "not-hosted"
+        ? createElement("p", { role: "alert" }, "App host connection unavailable. Open this App through its host to try again.")
+        : null, render(state));
 }

package/dist/window.d.ts

@@ -34,6 +34,8 @@ export type AppCrumb = Readonly<{
 export type AppHeaderCommand = Readonly<{
     id: string;
     label: string;
+    /** Supported icon-only presentation; label remains the accessible name. */
+    icon?: "play";
     /** The Caps button a primary command wears; default `outline`. */
     variant?: "primary" | "outline" | "ghost";
     /** A menu command that removes or discards something. */
@@ -44,6 +46,8 @@ export type AppHeaderCommand = Readonly<{
 export type AppHeaderStatus = Readonly<{
     id: string;
     label: string;
+    /** Show the bead alone, with label retained as accessible text and a hint. */
+    presentation?: "bead";
     tone?: "neutral" | "info" | "warning" | "success" | "error";
 }>;
 /** The person used a crumb (or a switcher's sibling) or a header command. */

package/docs/api/README.md

@@ -6,21 +6,21 @@
 
 # Agar API overview
 
-| Import                                     | Export                                                 | Purpose                                                                                  |
-| ------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| `@fungi.computer/agar`                     | `connectApp`                                           | Connect a host-mounted App frontend and receive its context and grants.                  |
-| `@fungi.computer/agar`                     | `defineCapability`, `AppError`                         | Declare a typed host capability; the SDK's one typed failure.                            |
-| `@fungi.computer/agar/host`                | `connectAppHost`                                       | Mount an App in an author-owned iframe test or standalone page.                          |
-| `@fungi.computer/agar/react`               | `mountApp`, `useAppContext`                            | Mount a React App and read its host context.                                             |
-| `@fungi.computer/agar/query`               | `queryKeys`                                            | TanStack Query keys and live feeds for host data.                                        |
-| `@fungi.computer/agar/errors`              | `describeAppError`                                     | Turn a failure into approved, action-hinted UI copy.                                     |
-| `@fungi.computer/agar/backend-definition`  | `defineAppBackend`, `defineAppMethod`                  | Define typed backend methods once, with Zod input and output.                            |
-| `@fungi.computer/agar/backend-declaration` | `buildAppApi`, `buildAppDeclaration`                   | Project the backend definition to the JSON Schema App API at build time.                 |
-| `@fungi.computer/agar/backend`             | `appBackend`                                           | Call the App's own backend from its frontend.                                            |
-| `@fungi.computer/agar/rpc`                 | `rpcHandleSchema`, `rpcMethod`                         | Validate object-capability handles received over Cap'n Web.                              |
-| `@fungi.computer/agar/files`               | `readAppFile`, `writeAppFile`                          | Turn a host-owned file read or write handle into a `File` or an upload.                  |
-| `@fungi.computer/agar/storage`             | `appStorage`                                           | Read, write and watch the App's own member and Team data.                                |
-| `@fungi.computer/agar/computer-contracts`  | `workflowGitPassResultSchema`, `WorkflowGitPassResult` | Validate host-issued, credential-free Workflow pass metadata without granting authority. |
+| Import                                     | Export                                                              | Purpose                                                                                             |
+| ------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `@fungi.computer/agar`                     | `connectApp`                                                        | Connect a host-mounted App frontend and receive its context and grants.                             |
+| `@fungi.computer/agar`                     | `defineCapability`, `AppError`                                      | Declare a typed host capability; the SDK's one typed failure.                                       |
+| `@fungi.computer/agar/host`                | `connectAppHost`                                                    | Mount an App in an author-owned iframe test or standalone page.                                     |
+| `@fungi.computer/agar/react`               | `mountApp`, `useAppContext`                                         | Mount a React App and read its host context.                                                        |
+| `@fungi.computer/agar/query`               | `queryKeys`                                                         | TanStack Query keys and live feeds for host data.                                                   |
+| `@fungi.computer/agar/errors`              | `describeAppError`                                                  | Turn a failure into approved, action-hinted UI copy.                                                |
+| `@fungi.computer/agar/backend-definition`  | `defineAppBackend`, `defineAppMethod`                               | Define typed backend methods once, with Zod input and output.                                       |
+| `@fungi.computer/agar/backend-declaration` | `buildAppApi`, `buildAppDeclaration`                                | Project the backend definition to the JSON Schema App API at build time.                            |
+| `@fungi.computer/agar/backend`             | `appBackend`                                                        | Call the App's own backend from its frontend.                                                       |
+| `@fungi.computer/agar/rpc`                 | `rpcHandleSchema`, `rpcMethod`                                      | Validate object-capability handles received over Cap'n Web.                                         |
+| `@fungi.computer/agar/files`               | `readAppFile`, `writeAppFile`                                       | Turn a host-owned file read or write handle into a `File` or an upload.                             |
+| `@fungi.computer/agar/storage`             | `appStorage`                                                        | Read, write and watch the App's own member and Team data.                                           |
+| `@fungi.computer/agar/computer-contracts`  | `appComputerAdmissionRefusalSchema`, `appComputerExecTimeoutSchema` | Validate public Computer admission, dispatch and budget outcomes without exposing host credentials. |
 
 A host decides what an App may do: the frontend asks for a capability and the
 host grants, denies or revokes it. The backend definition is runtime-neutral;

package/docs/api/backend-definition.md

@@ -229,9 +229,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.toolPolicy"` \| `"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`; `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; \} & (\{ ...; \} \| \{ ...; \}) |
 
 #### Returns
 

package/docs/api/backend.md

@@ -99,6 +99,7 @@ const appBackendRefusalSchema: ZodObject<
   {
     error: ZodLiteral<"App execution unavailable">;
     reason: ZodEnum<{
+      disabled: "disabled";
       exec_isolation_required: "exec_isolation_required";
       execution_not_admitted: "execution_not_admitted";
       artifact_unavailable: "artifact_unavailable";

package/docs/api/errors.md

@@ -61,6 +61,30 @@ readonly retryable: boolean;
 
 ## Type Aliases
 
+### MediaProviderDiagnostic
+
+```ts
+type MediaProviderDiagnostic =
+  | Readonly<{
+      category:
+        | "InferenceUpstreamError"
+        | "AiInternalError"
+        | "TypeError"
+        | "AbortError"
+        | "TimeoutError"
+        | "Error";
+      code: number | null;
+    }>
+  | Readonly<{
+      category: "result_download";
+      status: number;
+    }>;
+```
+
+Declaration-safe projection of the canonical Media diagnostic grammar.
+
+---
+
 ### AppErrorCode
 
 ```ts
@@ -145,8 +169,88 @@ type ErrorDescription = ErrorCopy &
 Recovery hints are for the caller's UI, never an instruction to retry
 automatically.
 
+## Variables
+
+### 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
+  >
+>;
+```
+
+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.
+
 ## Functions
 
+### decodeMediaProviderDiagnostic()
+
+```ts
+function decodeMediaProviderDiagnostic(input): MediaProviderDiagnostic;
+```
+
+Decode only safe provider facts, rejecting unmodeled private fields.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `input`   | `unknown` |
+
+#### Returns
+
+[`MediaProviderDiagnostic`](#mediaproviderdiagnostic)
+
+---
+
+### decodeMediaProviderErrorCategory()
+
+```ts
+function decodeMediaProviderErrorCategory(
+  input,
+):
+  | "InferenceUpstreamError"
+  | "AiInternalError"
+  | "TypeError"
+  | "AbortError"
+  | "TimeoutError"
+  | "Error";
+```
+
+Decode an ordinary Error name without retaining arbitrary upstream text.
+
+#### Parameters
+
+| Parameter | Type                    |
+| --------- | ----------------------- |
+| `input`   | `string` \| `undefined` |
+
+#### Returns
+
+\| `"InferenceUpstreamError"` \| `"AiInternalError"` \| `"TypeError"` \|
+`"AbortError"` \| `"TimeoutError"` \| `"Error"`
+
+---
+
 ### describeAppError()
 
 ```ts