@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/media-json.js

@@ -0,0 +1,204 @@
+import { mediaRequestIds, mediaRequestIdSchema } from "./media-request-id.js";
+import { AppError } from "./errors.js";
+import { mediaModelSchema, mediaGenerationInputWireSchema, mediaGenerationSelectionSchema, mediaGenerationFailureSchema, mediaGenerationResultSchema, parseMediaGenerationInput, mediaGenerationReferenceSchema, } from "./media.js";
+import * as Schema from "effect/Schema";
+import { pendingSchema } from "./backend-definition.js";
+import { RpcTarget as TransportRpcTarget } from "@fungi.computer/capnweb";
+// Live RPC targets remain opaque in public declarations, as Agar host grants do.
+const RpcTarget = TransportRpcTarget;
+export { mediaGenerationReferenceSchema } from "./media.js";
+/** Plain JSON catalog reply, decoded with Agar's Media model grammar. */
+export const mediaGenerationDescriptionSchema = Schema.Struct({
+    /** Fixed Computer identity supplied by the host. */
+    computerId: mediaGenerationReferenceSchema.fields.computerId,
+    /** Whether the admitted host permits generation. */
+    canGenerate: Schema.Boolean,
+    /** Models supplied by the host catalog owner. */
+    models: Schema.Array(mediaModelSchema),
+});
+/** A generation call carries paths and a replay ID; the host supplies authority. */
+export const mediaGenerationJsonRequestSchema = Schema.Struct({
+    /** Canonical replay identity reused for polling and restoration. */
+    requestId: Schema.String.pipe(Schema.check(Schema.makeFilter((value) => mediaRequestIdSchema.safeParse(value).success))),
+    ...mediaGenerationInputWireSchema.fields,
+    /** Agar-owned image and video selection, including path references. */
+    settings: mediaGenerationSelectionSchema,
+});
+/** A typed completion or refusal; no live attempt handles cross this boundary. */
+export const mediaGenerationJsonOutcomeSchema = Schema.Union([
+    Schema.Struct({
+        /** Completed generation. */
+        kind: Schema.Literal("succeeded"),
+        /** Retained and saved host result. */
+        result: mediaGenerationResultSchema,
+    }),
+    Schema.Struct({
+        /** Refused or failed generation. */
+        kind: Schema.Literal("failed"),
+        /** Sanitized failure with truthful retry semantics. */
+        failure: mediaGenerationFailureSchema,
+    }),
+]);
+/** Generate may also report Agar's canonical, bounded Pending result. */
+export const mediaGenerationJsonReplySchema = Schema.Union([
+    mediaGenerationJsonOutcomeSchema,
+    Schema.declare((value) => pendingSchema.safeParse(value).success),
+]);
+/** Page-side Agar handle over an admitted generic JSON method caller. */
+export class MediaGeneration extends RpcTarget {
+    #signal;
+    #computerId;
+    #call;
+    #activeRequests = new Map();
+    constructor(call, computerId, signal) {
+        super();
+        this.#computerId = computerId;
+        this.#call = call;
+        this.#signal = signal;
+    }
+    /** Describe this handle's fixed Computer through the admitted JSON method. */
+    async describe() {
+        const description = decodeJson(mediaGenerationDescriptionSchema, await this.#call("describe", undefined, {
+            signal: accessSignal(this.#signal),
+        }));
+        if (description.computerId !== this.#computerId)
+            throw new AppError("Media generation unavailable", {
+                code: "IDENTITY",
+                retryable: false,
+            });
+        return description;
+    }
+    /** Issue a canonical replay identity for a new generation attempt. */
+    createAttempt() {
+        return Promise.resolve(this.#createAttempt(mediaRequestIds.request.generate()));
+    }
+    /** Resume the original Computer and canonical request without issuing a new ID. */
+    restoreAttempt(reference) {
+        const parsed = Schema.decodeUnknownSync(mediaGenerationReferenceSchema)(reference);
+        const requestId = mediaRequestIds.request.parse(parsed.requestId);
+        if (!requestId.ok || parsed.computerId !== this.#computerId)
+            throw new AppError("Media restore requires the original Computer and request", {
+                code: "IDENTITY",
+                retryable: false,
+            });
+        return Promise.resolve(this.#createAttempt(requestId.value));
+    }
+    /** Abort every active browser request belonging to this attempt. */
+    cancelAttempt(reference) {
+        const parsed = Schema.decodeUnknownSync(mediaGenerationReferenceSchema)(reference);
+        const requestId = mediaRequestIds.request.parse(parsed.requestId);
+        if (!requestId.ok || parsed.computerId !== this.#computerId)
+            throw new AppError("Media cancellation requires the original Computer and request", {
+                code: "IDENTITY",
+                retryable: false,
+            });
+        for (const controller of this.#activeRequests.get(requestId.value) ?? [])
+            controller.abort();
+        return this.#call("cancelAttempt", parsed, {
+            signal: accessSignal(this.#signal),
+        }).then((value) => {
+            decodeJson(Schema.Union([Schema.Null, Schema.Undefined]), value);
+        });
+    }
+    #createAttempt(requestId) {
+        return new MediaGenerationAttempt(this.#call, this.#computerId, this.#signal, requestId, this.#activeRequests);
+    }
+}
+/** One replayable host-issued Media attempt, sharing cancellation with its handle. */
+export class MediaGenerationAttempt extends RpcTarget {
+    #computerId;
+    #signal;
+    #requestId;
+    #call;
+    #activeRequests;
+    constructor(call, computerId, signal, requestId, activeRequests) {
+        super();
+        this.#computerId = computerId;
+        this.#call = call;
+        this.#signal = signal;
+        this.#requestId = requestId;
+        this.#activeRequests = activeRequests;
+    }
+    /** Return the stable Computer and request identity for replay. */
+    reference() {
+        return Promise.resolve({
+            requestId: this.#requestId,
+            computerId: this.#computerId,
+        });
+    }
+    /** Save through the admitted host; poll pending work with the same replay identity. */
+    async generate(input) {
+        const controller = new AbortController();
+        let active = this.#activeRequests.get(this.#requestId);
+        if (active === undefined) {
+            active = new Set();
+            this.#activeRequests.set(this.#requestId, active);
+        }
+        active.add(controller);
+        const signal = this.#signal === undefined
+            ? controller.signal
+            : AbortSignal.any([this.#signal, controller.signal]);
+        try {
+            signal.throwIfAborted();
+            const request = Schema.decodeUnknownSync(Schema.Json)(decodeJson(mediaGenerationJsonRequestSchema, {
+                requestId: this.#requestId,
+                ...parseMediaGenerationInput(input),
+            }));
+            const post = async () => {
+                signal.throwIfAborted();
+                const reply = await this.#call("generate", request, { signal });
+                signal.throwIfAborted();
+                return decodeJson(mediaGenerationJsonReplySchema, reply);
+            };
+            let response = await post();
+            const deadline = Date.now() + backgroundGenerationMs;
+            while (response.kind === "pending" && Date.now() < deadline) {
+                await abortableDelay(response.retryAfterMs, signal);
+                response = await post();
+            }
+            if (response.kind === "pending")
+                return {
+                    kind: "failed",
+                    failure: {
+                        message: "Media generation is still running; restore this request later to save it.",
+                        code: "HOST_FAILURE",
+                        retryable: true,
+                    },
+                };
+            return response;
+        }
+        finally {
+            active.delete(controller);
+            if (active.size === 0)
+                this.#activeRequests.delete(this.#requestId);
+        }
+    }
+}
+/** How long the browser keeps checking one background (video) generation. */
+const backgroundGenerationMs = 25 * 60_000;
+function abortableDelay(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        signal.throwIfAborted();
+        const timer = setTimeout(resolve, milliseconds);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(signal.reason instanceof Error
+                ? signal.reason
+                : new Error("Media generation was cancelled"));
+        }, { once: true });
+    });
+}
+function decodeJson(schema, value) {
+    try {
+        return Schema.decodeUnknownSync(schema, { onExcessProperty: "error" })(value);
+    }
+    catch (cause) {
+        throw new AppError("The Media JSON method returned malformed data", {
+            cause,
+            code: "PROTOCOL",
+            retryable: false,
+        });
+    }
+}
+const idleAccessSignal = new AbortController().signal;
+const accessSignal = (signal) => signal ?? idleAccessSignal;

package/dist/media-library.d.ts

@@ -0,0 +1,11 @@
+import * as Schema from "effect/Schema";
+/** A Media-role App exposes the selected library for one Computer to other granted Apps. */
+export declare const mediaLibraryRequestSchema: Schema.Struct<{
+    readonly operation: Schema.Literal<"read-library">;
+    readonly computerId: Schema.NonEmptyString;
+}>;
+/** A bounded Computer directory shared by folder selection and library reads. */
+export declare const mediaLibraryPathSchema: Schema.String;
+export declare const mediaLibraryResponseSchema: Schema.Struct<{
+    readonly path: Schema.NullOr<Schema.String>;
+}>;

package/dist/media-library.js

@@ -0,0 +1,15 @@
+import * as Schema from "effect/Schema";
+/** A Media-role App exposes the selected library for one Computer to other granted Apps. */
+export const mediaLibraryRequestSchema = Schema.Struct({
+    operation: Schema.Literal("read-library"),
+    computerId: Schema.NonEmptyString,
+});
+/** A bounded Computer directory shared by folder selection and library reads. */
+export const mediaLibraryPathSchema = Schema.String.pipe(Schema.check(Schema.isMaxLength(4096)), Schema.check(Schema.makeFilter((path) => path.startsWith("/") &&
+    path !== "/" &&
+    !path.includes("\0") &&
+    !path.endsWith("/") &&
+    !path.split("/").some((segment) => segment === "." || segment === ".."))));
+export const mediaLibraryResponseSchema = Schema.Struct({
+    path: Schema.NullOr(mediaLibraryPathSchema),
+});

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

@@ -0,0 +1,7 @@
+import * as z from "zod";
+/** One canonical identity for a retryable Media operation. */
+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;

package/dist/media-request-id.js

@@ -0,0 +1,16 @@
+import * as z from "zod";
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+/** One canonical identity for a retryable Media operation. */
+export const mediaRequestIds = defineIdFamily({
+    family: "hub-media-request",
+    version: 1,
+    kinds: {
+        /** Canonical request identity for exact replay. */
+        request: { prefix: "media_request" },
+    },
+});
+/** Public wire grammar for the canonical retry identity, visible in App JSON schemas. */
+export const mediaRequestIdSchema = z
+    .string()
+    .length(35)
+    .regex(/^media_request_[a-z0-9]{21}$/);

package/dist/media.d.ts

@@ -0,0 +1,354 @@
+import * as Schema from "effect/Schema";
+export { mediaLibraryRequestSchema, mediaLibraryPathSchema, mediaLibraryResponseSchema, } from "./media-library.js";
+import type { CapabilityContract, CapabilityDirectory } from "./capabilities.js";
+import { AppError } from "./errors.js";
+/**
+ * The Media owner decides Team, Installation, Release, Grant and Computer
+ * authority before issuing this handle. The App contributes only generation
+ * settings and selected destination/references. The IDs in those selections
+ * are not authority: the host revalidates every one against its current
+ * admitted Computer scope when it accepts a generation.
+ *
+ * The owner intentionally returns completed metadata. Operation state,
+ * provider identifiers and billing records remain owner facts. The exposed
+ * request reference identifies a replay; it grants no authority.
+ */
+export type MediaGenerationInput = Readonly<{
+    destination: Readonly<{
+        path: string;
+    }>;
+    settings: MediaGenerationSelection;
+}>;
+/** The encodings a completed generation can be saved as. */
+export type MediaOutputFormat = "png" | "jpeg" | "gif" | "webp" | "mp4";
+/** Metadata for one completed generation: the saved destination, pixel
+ * dimensions, format, model used, and its cost. */
+export type MediaGenerationResult = Readonly<{
+    bytes: number;
+    costMilliunits: number;
+    destination: Readonly<{
+        computerId: string;
+        path: string;
+    }>;
+    format: MediaOutputFormat;
+    height: number;
+    model: string;
+    width: number;
+}>;
+/** The host's typed reason a generation failed: code, message, retry truth
+ * and, when known, the stage that failed. */
+export type MediaGenerationFailure = Schema.Schema.Type<typeof mediaGenerationFailureSchema>;
+/** 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;
+    constructor(failure: MediaGenerationFailure);
+}
+/** Transport-safe result from the host-owned generation attempt. */
+export type MediaGenerationOutcome = Readonly<{
+    kind: "succeeded";
+    result: MediaGenerationResult;
+}> | Readonly<{
+    kind: "failed";
+    failure: MediaGenerationFailure;
+}>;
+/** Live object-capability shape supplied by the host. */
+export type MediaGenerationHandle = {
+    /** Fetch the Computer scope, available models, and whether generation
+     * is currently allowed. */
+    describe(): Promise<Partial<Disposable> & {
+        readonly computerId: string;
+        readonly canGenerate: boolean;
+        readonly models: readonly MediaModel[];
+    }>;
+    /** Begin a new generation attempt on the host and return its handle. */
+    createAttempt(): Promise<MediaGenerationAttemptHandle>;
+    /** Resume a previously started attempt identified by its reference. */
+    restoreAttempt(reference: MediaGenerationReference): Promise<MediaGenerationAttemptHandle>;
+    /** Tell the host to stop an in-flight or pending attempt. */
+    cancelAttempt(reference: MediaGenerationReference): Promise<void>;
+};
+/** Host-supplied object-capability for one attempt, before Agar wraps it
+ * into the typed MediaGenerationAttempt. */
+export type MediaGenerationAttemptHandle = Partial<Disposable> & {
+    /** Fetch this attempt's replay reference from the host. */
+    reference(): Promise<MediaGenerationReference & Partial<Disposable>>;
+    /** Ask the host to run generation for this attempt with the given
+     * input. */
+    generate(input: MediaGenerationInput): Promise<MediaGenerationOutcome & Partial<Disposable>>;
+};
+/** One generation attempt: a stable reference plus the ability to run
+ * (or retry) generation against it until disposed. */
+export type MediaGenerationAttempt = Disposable & {
+    readonly reference: MediaGenerationReference;
+    /** Run generation for this attempt and return the saved result, or
+     * throw MediaGenerationError on failure; an abort signal cancels it. */
+    generate(input: MediaGenerationInput, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<MediaGenerationResult>;
+};
+/** The validated, App-facing handle returned by openMediaGeneration: the
+ * Computer's model catalog plus the ability to start or resume
+ * attempts. */
+export type MediaGenerationSession = Readonly<{
+    computerId: string;
+    canGenerate: boolean;
+    models: readonly MediaModel[];
+    /** Start a fresh generation attempt scoped to this session's
+     * Computer. */
+    createAttempt(): Promise<MediaGenerationAttempt>;
+    /** Resume an attempt from a reference returned earlier in this
+     * session. */
+    restoreAttempt(reference: MediaGenerationReference): Promise<MediaGenerationAttempt>;
+}>;
+/** A replay identity, never an authorization capability. */
+export declare const mediaGenerationReferenceSchema: Schema.Struct<{
+    readonly requestId: Schema.String;
+    readonly computerId: Schema.String;
+}>;
+/** An opaque replay identity for one attempt; it identifies a request,
+ * not an authorization to use it. */
+export type MediaGenerationReference = Schema.Schema.Type<typeof mediaGenerationReferenceSchema>;
+/** Video frame/reference role, interpreted by the host's model catalog. */
+export declare const mediaVideoReferenceRoleSchema: Schema.Literals<readonly ["first-frame", "last-frame", "reference"]>;
+/** One provider-independent frame/reference role. */
+export type MediaVideoReferenceRole = Schema.Schema.Type<typeof mediaVideoReferenceRoleSchema>;
+/** A supported wire resolution. The host refines it against the chosen model. */
+export declare const mediaVideoResolutionSchema: Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>;
+/** Provider-independent resolution selector. */
+export type MediaVideoResolution = Schema.Schema.Type<typeof mediaVideoResolutionSchema>;
+/** A supported wire aspect. The host refines it against the chosen model. */
+export declare const mediaVideoAspectRatioSchema: Schema.Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>;
+/** Provider-independent requested aspect selector. */
+export type MediaVideoAspectRatio = Schema.Schema.Type<typeof mediaVideoAspectRatioSchema>;
+/** Path-only video reference. The host supplies Computer authority. */
+export declare const mediaVideoReferenceSchema: Schema.Struct<{
+    /** Computer-relative image path. */
+    readonly path: Schema.String;
+    /** First frame, last frame or reference-image mode. */
+    readonly role: Schema.Literals<readonly ["first-frame", "last-frame", "reference"]>;
+}>;
+/** One path-only video reference. */
+export type MediaVideoReference = Schema.Schema.Type<typeof mediaVideoReferenceSchema>;
+/** Host-described video capabilities and costs. This is wire grammar, not a catalog. */
+export declare const mediaVideoModelSchema: Schema.Struct<{
+    /** Smallest duration; the durations list owns exact membership. */
+    readonly minSeconds: Schema.Number;
+    /** Largest duration. */
+    readonly maxSeconds: Schema.Number;
+    /** Default whole seconds. */
+    readonly defaultSeconds: Schema.Number;
+    /** Exact admitted duration values. */
+    readonly durations: Schema.$Array<Schema.Number>;
+    /** Provider translation family. */
+    readonly provider: Schema.Literals<readonly ["seedance", "veo", "minimax"]>;
+    /** Resolution/aspect selectors and nominal dimensions. */
+    readonly formats: Schema.$Array<Schema.Struct<{
+        /** Provider resolution selector. */
+        readonly resolution: Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>;
+        /** Requested aspect selector. */
+        readonly aspectRatio: Schema.Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>;
+        /** Nominal width, not measured MP4 dimensions. */
+        readonly width: Schema.Number;
+        /** Nominal height, not measured MP4 dimensions. */
+        readonly height: Schema.Number;
+    }>>;
+    /** Default resolution. */
+    readonly defaultResolution: Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>;
+    /** Default requested aspect. */
+    readonly defaultAspectRatio: Schema.Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>;
+    /** Audio default, or null when the provider default is undocumented. */
+    readonly defaultGenerateAudio: Schema.NullOr<Schema.Boolean>;
+    /** Host/provider prompt bound. */
+    readonly maxPromptLength: Schema.Number;
+    /** Roles admitted by this model. */
+    readonly referenceRoles: Schema.$Array<Schema.Literals<readonly ["first-frame", "last-frame", "reference"]>>;
+    /** Maximum images in reference-image mode. */
+    readonly maxReferenceImages: Schema.Number;
+    /** Resolutions admitting reference-image mode. */
+    readonly referenceResolutions: Schema.$Array<Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>>;
+    /** Host-described costs, where 1 USD is 100,000 milliunits. */
+    readonly prices: Schema.$Array<Schema.Struct<{
+        /** Billed provider resolution. */
+        readonly resolution: Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>;
+        /** Provider milliunits per silent output second. */
+        readonly silentMilliunitsPerSecond: Schema.Number;
+        /** Provider milliunits per output second with audio. */
+        readonly audioMilliunitsPerSecond: Schema.Number;
+    }>>;
+}>;
+/** Immutable host-described video metadata. */
+export type MediaVideoModel = Schema.Schema.Type<typeof mediaVideoModelSchema>;
+/** Validates one model row of the host's Media catalog. */
+export declare const mediaModelSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly input: Schema.Struct<{
+        readonly defaultHeight: Schema.Number;
+        readonly defaultSteps: Schema.NullOr<Schema.Number>;
+        readonly defaultWidth: Schema.Number;
+        readonly dimensions: Schema.Literals<readonly ["none", "own"]>;
+        readonly maxDimension: Schema.NullOr<Schema.Number>;
+        readonly maxReferences: Schema.Number;
+        readonly maxSteps: Schema.NullOr<Schema.Number>;
+        readonly referenceField: Schema.NullOr<Schema.String>;
+        readonly steps: Schema.Literals<readonly ["steps", "num_steps", "fixed"]>;
+        readonly transport: Schema.Literals<readonly ["json", "multipart"]>;
+    }>;
+    readonly kind: Schema.Literals<readonly ["image", "video"]>;
+    readonly label: Schema.String;
+    readonly tier: Schema.Literals<readonly ["draft", "balanced", "premium", "max"]>;
+    readonly outputFormats: Schema.$Array<Schema.Literals<readonly ["png", "jpeg", "webp"]>>;
+    readonly sizes: Schema.NullOr<Schema.$Array<Schema.String>>;
+    readonly video: Schema.NullOr<Schema.Struct<{
+        /** Smallest duration; the durations list owns exact membership. */
+        readonly minSeconds: Schema.Number;
+        /** Largest duration. */
+        readonly maxSeconds: Schema.Number;
+        /** Default whole seconds. */
+        readonly defaultSeconds: Schema.Number;
+        /** Exact admitted duration values. */
+        readonly durations: Schema.$Array<Schema.Number>;
+        /** Provider translation family. */
+        readonly provider: Schema.Literals<readonly ["seedance", "veo", "minimax"]>;
+        /** Resolution/aspect selectors and nominal dimensions. */
+        readonly formats: Schema.$Array<Schema.Struct<{
+            /** Provider resolution selector. */
+            readonly resolution: Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>;
+            /** Requested aspect selector. */
+            readonly aspectRatio: Schema.Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>;
+            /** Nominal width, not measured MP4 dimensions. */
+            readonly width: Schema.Number;
+            /** Nominal height, not measured MP4 dimensions. */
+            readonly height: Schema.Number;
+        }>>;
+        /** Default resolution. */
+        readonly defaultResolution: Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>;
+        /** Default requested aspect. */
+        readonly defaultAspectRatio: Schema.Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>;
+        /** Audio default, or null when the provider default is undocumented. */
+        readonly defaultGenerateAudio: Schema.NullOr<Schema.Boolean>;
+        /** Host/provider prompt bound. */
+        readonly maxPromptLength: Schema.Number;
+        /** Roles admitted by this model. */
+        readonly referenceRoles: Schema.$Array<Schema.Literals<readonly ["first-frame", "last-frame", "reference"]>>;
+        /** Maximum images in reference-image mode. */
+        readonly maxReferenceImages: Schema.Number;
+        /** Resolutions admitting reference-image mode. */
+        readonly referenceResolutions: Schema.$Array<Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>>;
+        /** Host-described costs, where 1 USD is 100,000 milliunits. */
+        readonly prices: Schema.$Array<Schema.Struct<{
+            /** Billed provider resolution. */
+            readonly resolution: Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>;
+            /** Provider milliunits per silent output second. */
+            readonly silentMilliunitsPerSecond: Schema.Number;
+            /** Provider milliunits per output second with audio. */
+            readonly audioMilliunitsPerSecond: Schema.Number;
+        }>>;
+    }>>;
+}>;
+/** One generation model as the host describes it: identity, tier, input
+ * limits and supported output formats. The host owns the catalog. */
+export type MediaModel = Schema.Schema.Type<typeof mediaModelSchema>;
+/** The most reference images one generation request may name. */
+export declare const MAX_MEDIA_REFERENCES = 4;
+/**
+ * Validates the shape of an App's generation settings. Model-specific limits
+ * (sizes, steps, durations, reference counts) and defaults are the host's:
+ * it checks the selection against its catalog when it accepts a generation.
+ */
+export declare const mediaGenerationSelectionSchema: Schema.Struct<{
+    readonly model: Schema.String;
+    readonly prompt: Schema.String;
+    readonly width: Schema.Number;
+    readonly height: Schema.Number;
+    readonly steps: Schema.optional<Schema.Number>;
+    readonly durationSeconds: Schema.optional<Schema.Number>;
+    readonly resolution: Schema.optional<Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>>;
+    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 path: Schema.String;
+        readonly role: Schema.optional<Schema.Literals<readonly ["first-frame", "last-frame", "reference"]>>;
+    }>>>;
+}>;
+/** An App's generation settings: model, prompt, size and optional steps,
+ * duration and Computer-relative reference paths. */
+export type MediaGenerationSelection = Schema.Schema.Type<typeof mediaGenerationSelectionSchema>;
+/** Path-only video selection. Model defaults and combination refinements remain host-owned. */
+export declare const mediaVideoSelectionSchema: Schema.Struct<{
+    /** Host catalog model identifier. */
+    readonly model: Schema.String;
+    /** Host-bounded prompt. */
+    readonly prompt: Schema.String;
+    /** Optional provider resolution selector. */
+    readonly resolution: Schema.optional<Schema.Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>>;
+    /** Optional requested aspect selector. */
+    readonly aspectRatio: Schema.optional<Schema.Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>>;
+    /** Whole seconds, 4 through 15; the host checks exact model membership. */
+    readonly durationSeconds: Schema.optional<Schema.Number>;
+    /** Explicit audio choice. The host owns omitted defaults. */
+    readonly generateAudio: Schema.optional<Schema.Boolean>;
+    /** At most four paths with explicit frame/reference roles. */
+    readonly references: Schema.optional<Schema.$Array<Schema.Struct<{
+        /** Computer-relative image path. */
+        readonly path: Schema.String;
+        /** First frame, last frame or reference-image mode. */
+        readonly role: Schema.Literals<readonly ["first-frame", "last-frame", "reference"]>;
+    }>>>;
+}>;
+/** App-selected video parameters without host authority or output-path claims. */
+export type MediaVideoSelection = Schema.Schema.Type<typeof mediaVideoSelectionSchema>;
+/** Public diagnostic stages a host may name when a generation fails. */
+export declare const mediaFailureStages: readonly ["admission", "generation-authorization", "settings", "estimate", "billing", "operation", "provider", "normalization", "artifact", "destination-authorization", "destination-write"];
+/** Validates a generation input envelope; settings are parsed separately. */
+export declare const mediaGenerationInputWireSchema: Schema.Struct<{
+    readonly destination: Schema.Struct<{
+        readonly path: Schema.String;
+    }>;
+    readonly settings: Schema.Unknown;
+}>;
+/** Completed image or video metadata saved to a host-admitted destination. */
+export declare const mediaGenerationResultSchema: Schema.Struct<{
+    readonly [Symbol.dispose]: Schema.optional<Schema.Unknown>;
+    readonly bytes: Schema.Number;
+    readonly costMilliunits: Schema.Number;
+    readonly destination: Schema.Struct<{
+        readonly computerId: Schema.String;
+        readonly path: Schema.String;
+    }>;
+    readonly format: Schema.Literals<readonly ["png", "jpeg", "gif", "webp", "mp4"]>;
+    readonly height: Schema.Number;
+    readonly model: Schema.String;
+    readonly width: Schema.Number;
+}>;
+/** Completed native MEDIA video result, with a host-admitted destination. */
+export declare const mediaVideoResultSchema: Schema.Struct<{
+    /** Bounded fetched video encoding. */
+    readonly format: Schema.Literal<"mp4">;
+    readonly [Symbol.dispose]: Schema.optional<Schema.Unknown>;
+    readonly bytes: Schema.Number;
+    readonly costMilliunits: Schema.Number;
+    readonly destination: Schema.Struct<{
+        readonly computerId: Schema.String;
+        readonly path: Schema.String;
+    }>;
+    readonly height: Schema.Number;
+    readonly model: Schema.String;
+    readonly width: Schema.Number;
+}>;
+/** Completed video metadata. */
+export type MediaVideoResult = Schema.Schema.Type<typeof mediaVideoResultSchema>;
+/** Validates the typed failure a host reports for a generation attempt. */
+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"]>>;
+    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;
+}>;
+/** Capability contract for generating Media (images or video). Apps
+ * declare it to request access; openMediaGeneration uses it to obtain
+ * the host's handle. */
+export declare const mediaGeneration: CapabilityContract<MediaGenerationHandle>;
+/** Decode and normalize a typed input envelope; storage parses the envelope first. */
+export declare function parseMediaGenerationInput(input: Schema.Schema.Type<typeof mediaGenerationInputWireSchema>): MediaGenerationInput;
+/** Discover the exact retained model catalog surfaced by the owner. */
+export declare function openMediaGeneration(capabilities: CapabilityDirectory): Promise<MediaGenerationSession>;