@civitai/app-sdk 0.56.1 → 0.58.0

package/dist/blocks/types.d.ts

@@ -1146,17 +1146,30 @@ export type WorkflowBodyStep = {
  *  3. **No resource policy / `urn:air:` scan.** AIR resources are ALLOWED here.
  *     Spend, not entitlement, is the binding control.
  *  4. **No `billingMode` and no load-time price invariant.** {@link maxBuzz}
- *     replaces them, exactly as on {@link WorkflowBodyCustomComfyInline}.
+ *     and a per-request orchestrator `whatif` quote replace them — see
+ *     `maxBuzz` below for how the two combine.
  *
  * WHAT STILL BOUNDS IT, all server-side:
  *  - A **denylist** of platform-internal `$type`s (scanners, moderation
  *    classifiers, hashing/model-ingestion, web egress) is refused by the host
  *    router before any spend reservation or orchestrator call. It is a DENYLIST,
  *    not an allowlist: a `$type` the host has never heard of is allowed through
- *    by construction, which is the point of this arm.
+ *    by construction, which is the point of this arm. `training` and
+ *    `imageResourceTraining` are deliberately NOT on it (a host operator
+ *    decision): both may be submitted here, on the same terms as every other
+ *    `$type`. If the orchestrator quotes the run, the host reserves the quote
+ *    (or `maxBuzz`, if larger), gated by the token's per-call budget, and
+ *    stamps no timeout; if it does
+ *    not, `maxBuzz` is both the reservation and the timeout — see `maxBuzz`
+ *    below. Whether a given training input is quoted, and at what price, is
+ *    the orchestrator's answer, not this package's: read it from `estimate`.
+ *    A host that supports it reports the trained epochs on
+ *    {@link BlockWorkflowSnapshot.trainedEpochs} without exposing the
+ *    checkpoint itself.
  *  - `$type` is bounded to **1…64 characters** and `input` to **262144 bytes**
  *    (256 KB) serialized. Both REJECT; neither truncates.
- *  - `maxBuzz` is the single spend knob — see its own note below.
+ *  - `maxBuzz` is the app's spend knob, and the host's quote can raise the
+ *    reservation above it — see its own note below.
  *
  * @example A pass-through body for an orchestrator step the registry does not
  * carry. Note there is no `step` key.
@@ -1205,26 +1218,197 @@ export type WorkflowBodyPassThroughStep = {
      */
     input: Record<string, unknown>;
     /**
-     * The per-job Buzz ceiling. Required, an integer in **1…250**.
-     *
-     * 🔴 **IT IS ALSO THE STEP TIMEOUT, IN SECONDS** — identical mechanism to
-     * {@link WorkflowBodyCustomComfyInline.maxBuzz}. The host stamps
-     * `stepTimeoutSeconds = maxBuzz`; there is only one number, which is what makes
-     * the ceiling physically enforceable rather than merely asserted. So
-     * `maxBuzz: 10` does not buy a cheap job; it buys one that is KILLED after 10
-     * seconds and comes back `expired`. Size it to the wall-clock time the step
-     * actually needs.
+     * The app's declared per-job Buzz amount: the least the host reserves, and —
+     * only when unquoted — the step timeout in seconds. NOT a spend ceiling (see
+     * below). Required, an integer in **1…250**.
      *
-     * You are billed the REAL cost: post-paid against measured GPU seconds,
-     * refunding the unused remainder of the ceiling, so a generous `maxBuzz` costs
-     * nothing extra when the job finishes early. `estimate` on a pass-through body
-     * echoes this number back as `cost.total` — an upper bound, not a price;
-     * surface it as "up to N Buzz".
+     * 🔴 **WHAT IT BOUNDS DEPENDS ON WHETHER THE HOST GOT A QUOTE** — this is NOT
+     * the mechanism of {@link WorkflowBodyCustomComfyInline.maxBuzz}, which is
+     * always the timeout. On both `estimate` and `submit` the host first asks the
+     * orchestrator for a `whatif` quote of this exact step, then:
+     *  - **Quoted** — the host reserves `max(maxBuzz, quote)` and stamps NO step
+     *    timeout. That reservation can exceed 250: it is gated against the token's
+     *    per-call budget (`token.buzzBudget` — the app's per-generation budget,
+     *    capped at 1000 when the host mints a production token), and a submit
+     *    whose reservation exceeds that budget comes back `failed` with an
+     *    `insufficient buzz budget` error before any Buzz is reserved.
+     *  - **Unquoted** (the orchestrator returned no price, or the quote could not
+     *    be had) — the host reserves `maxBuzz` and stamps it as the step timeout,
+     *    in seconds. `maxBuzz: 10` then buys a job that is KILLED after 10
+     *    seconds and comes back `expired`, so size it to the wall-clock time the
+     *    step actually needs. The same per-call budget gate applies. The timeout
+     *    bounds wall-clock time; it bounds spend only for a step billed by
+     *    compute time. A step priced per unit can bill ABOVE `maxBuzz`.
      *
-     * The host additionally requires `maxBuzz <= token.buzzBudget` before submit.
+     * `estimate` on a pass-through body returns, as `cost.total`, the number the
+     * submit would reserve: `max(maxBuzz, quote)`, or `maxBuzz` when unquoted.
+     * It is a reservation, NOT a guaranteed ceiling: the terminal settle refunds
+     * any unused remainder, but nothing on this arm stops a job billing above
+     * the reservation (see the unquoted case above). Do not present it to the
+     * viewer as a maximum.
      */
     maxBuzz: number;
 };
+/** Ceiling on what ONE confirmed `kind: 'training'` run may cost, in Buzz. Host constant `BLOCK_TRAINING_MAX_BUZZ_PER_RUN`. */
+export declare const BLOCK_TRAINING_MAX_BUZZ_PER_RUN = 5000;
+/** Max images in one prepared training dataset. Host constant `BLOCK_TRAINING_DATASET_MAX_ITEMS`. */
+export declare const BLOCK_TRAINING_DATASET_MAX_ITEMS = 50;
+/** Max characters of one dataset caption. Host constant `BLOCK_TRAINING_CAPTION_MAX_CHARS`. */
+export declare const BLOCK_TRAINING_CAPTION_MAX_CHARS = 1000;
+/** Max sample prompts on a training body. Host constant `BLOCK_TRAINING_SAMPLE_PROMPTS_MAX`. */
+export declare const BLOCK_TRAINING_SAMPLE_PROMPTS_MAX = 6;
+/** Max characters of one sample prompt. Host constant `BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS`. */
+export declare const BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS = 1000;
+/** Max characters of the trigger word. Host constant `BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS`. */
+export declare const BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS = 64;
+/** Max characters of the base-model key. Host constant `BLOCK_TRAINING_MODEL_KEY_MAX_CHARS`. */
+export declare const BLOCK_TRAINING_MODEL_KEY_MAX_CHARS = 64;
+/** `lrScheduler` values the host's ai-toolkit schema accepts. */
+export type AiToolkitLrScheduler = 'constant' | 'constant_with_warmup' | 'cosine' | 'linear' | 'step';
+/** `optimizerType` values the host's ai-toolkit schema accepts. */
+export type AiToolkitOptimizerType = 'adamw' | 'adamw8bit' | 'adam8bit' | 'lion' | 'lion8bit' | 'adafactor' | 'adagrad' | 'prodigy' | 'prodigy8bit' | 'automagic';
+/** The fields every ai-toolkit ecosystem shares (`aiToolkitBaseParams` on the host). */
+export interface AiToolkitTrainingParamsBase {
+    engine: 'ai-toolkit';
+    /** Saved checkpoint count, integer 1…50. With `steps` absent it is also the length knob. */
+    epochs?: number;
+    /** Total training steps, integer ≥ 1 — the primary length (and price) knob. */
+    steps?: number;
+    /** Integer ≥ 1. Exactly `1` on the `qwen21` / `ming` / `yue2` ecosystems. */
+    batchSize?: number;
+    sampleCfgScale?: number;
+    sampleStrength?: number;
+    continueFrom?: string;
+    resolution: number | null;
+    /**
+     * Learning rate. 🔴 Must be BELOW `0.1` unless `optimizerType` is `prodigy` or
+     * `prodigy8bit` — a host refinement this type cannot express; a body that
+     * breaks it is refused at estimate.
+     */
+    lr: number;
+    textEncoderLr: number | null;
+    trainTextEncoder: boolean;
+    lrScheduler: AiToolkitLrScheduler;
+    optimizerType: AiToolkitOptimizerType;
+    networkDim: number | null;
+    networkAlpha: number | null;
+    noiseOffset: number | null;
+    minSnrGamma: number | null;
+    flipAugmentation: boolean;
+    shuffleTokens: boolean;
+    keepTokens: number;
+    numRepeats?: number;
+}
+/**
+ * The ai-toolkit ecosystems that take NO `modelVariant` — send the key absent.
+ * (`qwen21` / `ming` / `yue2` also take none; they live on their own arm of
+ * {@link AiToolkitTrainingParams} because they pin `batchSize` to `1`.)
+ */
+export type AiToolkitPlainEcosystem = 'sd1' | 'sdxl' | 'chroma' | 'qwen' | 'zimageturbo' | 'zimagebase' | 'ltx2' | 'ltx23' | 'ltx25' | 'minimaxh3' | 'ernie' | 'anima' | 'boogu' | 'krea2' | 'mageflow' | 'ideogram4' | 'ace_step_15';
+/**
+ * `params` of a {@link WorkflowBodyTraining} — the host's
+ * `aiToolkitTrainingParamsSchema`, the same schema Civitai's own training form
+ * validates against, discriminated on `ecosystem`.
+ *
+ * ⚠️ THE ECOSYSTEM LIST IS CLOSED HERE AND OPEN ON THE HOST. The host adds
+ * ecosystems over time; until this package mirrors one, a body naming it does not
+ * type-check. That is the cost of a typed copy, paid deliberately: a free
+ * `string` would let a typo through to a refused estimate.
+ */
+export type AiToolkitTrainingParams = AiToolkitTrainingParamsBase & ({
+    ecosystem: AiToolkitPlainEcosystem;
+    modelVariant?: undefined;
+} | {
+    ecosystem: 'sd3';
+    modelVariant: 'large' | 'medium';
+} | {
+    ecosystem: 'flux1';
+    modelVariant: 'dev' | 'schnell';
+} | {
+    ecosystem: 'wan';
+    modelVariant: '2.1' | '2.2';
+} | {
+    ecosystem: 'flux2klein';
+    modelVariant: '4b' | '9b';
+} | {
+    ecosystem: 'qwen21' | 'ming' | 'yue2';
+    modelVariant?: undefined;
+    batchSize?: 1;
+} | {
+    ecosystem: 'ace_step_15_xl';
+    modelVariant: 'base' | 'sft';
+});
+/**
+ * Train a LoRA with the ai-toolkit engine on a dataset Civitai prepared from the
+ * VIEWER'S OWN images — the App Blocks `kind: 'training'` workflow body.
+ *
+ * ## Availability — read before building on it
+ *
+ *  - 🔴 Behind the host flag **`app-blocks-training-kind`**, which ships OFF and is
+ *    evaluated per viewer. Where it is off, every training call is refused
+ *    (`training from apps is not enabled`).
+ *  - **Page apps only** (`/apps/run/<slug>`). The model slot answers both training
+ *    messages with an error, and the server refuses a non-page token.
+ *  - The manifest must declare **`ai:write:budgeted`** and the viewer must have
+ *    granted it; the viewer must be signed in.
+ *  - **Not from a development or review session**: dev tokens (`dev:live`, dev
+ *    tunnel) and review-sandbox tokens are refused, run-for-real included. Use the
+ *    mock host (`createMockHost` / `Harness`) to build the flow.
+ *
+ * ## The flow
+ *
+ *  1. **Dataset** — `usePrepareTrainingDataset()` (`PREPARE_TRAINING_DATASET`)
+ *     with `[{ imageId, caption }]`. Only the viewer's OWN scanned, unflagged
+ *     images within the page's maturity ceiling are admitted; the rest come back
+ *     in `rejected`. You get an opaque {@link WorkflowBodyTraining.datasetId}.
+ *  2. **Quote** — `useBuzzWorkflow().estimate(body)` with this body, `quoteId`
+ *     ABSENT. The reply's {@link BlockWorkflowSnapshot.trainingQuote} is the
+ *     orchestrator's own price for exactly this run, stored server-side.
+ *  3. **Run** — `useRunTraining().runTraining({ ...body, quoteId })`
+ *     (`RUN_TRAINING`). Civitai shows the viewer a consent dialog in ITS chrome —
+ *     price, base model, length, dataset size, all read back from the server,
+ *     never from your body — and submits only on their click.
+ *  4. **Follow** — `useBuzzWorkflow().watch(snapshot.workflowId)`.
+ *
+ * 🔴 `useBuzzWorkflow().submit()` REFUSES THIS BODY before sending it. The server
+ * charges a training run only against a quote the viewer confirmed from a
+ * signed-in session, which only `RUN_TRAINING`'s dialog can record.
+ *
+ * ## Money
+ *
+ * There is no `maxBuzz` and no timeout knob, on purpose: the price is the quote.
+ * A run may cost more than the token's per-call `buzzBudget` (the viewer confirms
+ * the exact price), up to {@link BLOCK_TRAINING_MAX_BUZZ_PER_RUN} (5,000 Buzz);
+ * an estimate above that is refused.
+ */
+export interface WorkflowBodyTraining {
+    kind: 'training';
+    /** The handle `usePrepareTrainingDataset()` returned — `tds_` + 32 hex characters. */
+    datasetId: string;
+    /** The only engine accepted. */
+    engine: 'ai-toolkit';
+    /**
+     * A base-model key from Civitai's training catalog (1…64 characters), resolved
+     * and gated server-side. Custom AIRs are not accepted.
+     */
+    model: string;
+    params: AiToolkitTrainingParams;
+    /** At most {@link BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS} characters. Moderated like a prompt. */
+    triggerWord: string;
+    /**
+     * At most {@link BLOCK_TRAINING_SAMPLE_PROMPTS_MAX} prompts of at most
+     * {@link BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS} characters each. Moderated like
+     * prompts.
+     */
+    samplePrompts: string[];
+    /**
+     * The quote this run is charged against — {@link BlockTrainingQuote.quoteId}
+     * from the estimate (`tq_` + 32 hex characters). OMIT it on the estimate;
+     * REQUIRED on `RUN_TRAINING`. The server checks the rest of the body against
+     * the body that was quoted, so change nothing else between the two.
+     */
+    quoteId?: string;
+}
 /**
  * Body the block sends to `useBuzzWorkflow().{submit,estimate}`. A real
  * discriminated union keyed by `kind`:
@@ -1243,6 +1427,10 @@ export type WorkflowBodyPassThroughStep = {
  *    an orchestrator `$type` directly and has the host forward `input`
  *    unmodified. Bounded by a platform-internal denylist and by `maxBuzz`, not
  *    by a registry.
+ *  - {@link WorkflowBodyTraining} (`kind: 'training'`) — an ai-toolkit LoRA run
+ *    on a server-prepared dataset of the viewer's own images. ESTIMATE ONLY
+ *    through `useBuzzWorkflow`; it runs through `useRunTraining()`, whose
+ *    host-chrome consent dialog is the only way to confirm its quote.
  *
  * `kind: 'step'` is therefore itself a union, discriminated on the PRESENCE of
  * `step` — the same nesting {@link WorkflowBodyCustomComfy} has on `mode`.
@@ -1259,7 +1447,7 @@ export type WorkflowBodyPassThroughStep = {
  * over `kind`. Host code that must handle every member gets a compile error
  * pointing at the new one, which is the intended behaviour.
  */
-export type WorkflowBody = WorkflowBodyTextToImage | WorkflowBodyCustomComfy | WorkflowBodyStep | WorkflowBodyPassThroughStep;
+export type WorkflowBody = WorkflowBodyTextToImage | WorkflowBodyCustomComfy | WorkflowBodyStep | WorkflowBodyPassThroughStep | WorkflowBodyTraining;
 /**
  * The host-mediated view of an orchestrator workflow that an iframe block
  * receives over `postMessage`.
@@ -1310,6 +1498,253 @@ export interface BlockWorkflowSnapshot {
         amount: number;
         accountType: 'yellow' | 'blue' | 'red' | 'green';
     };
+    /**
+     * Checkpoint versions the host SILENTLY replaced before running the
+     * generation. `requested` is the version id the block asked for, `applied` is
+     * the one that actually ran (and was billed).
+     *
+     * On an ecosystem whose model is locked to a workflow, the host swaps a
+     * version id that is not offered for the current workflow for that workflow's
+     * default and still succeeds — graceful degradation that keeps an app pinned
+     * to a since-retired version working. This field only REPORTS the swap; the
+     * behaviour is unchanged.
+     *
+     * WHERE IT APPEARS: on the `kind: 'textToImage'` path only — the submit reply,
+     * the estimate reply, every submit reply that quotes a cost without
+     * submitting, and every later poll/cancel of that workflow (the record is
+     * persisted with it, so it sits next to the `imageUrls` it describes). An
+     * estimate creates no persisted workflow, so there it exists only on that
+     * reply. It does NOT appear for `customComfy` or `step` bodies: neither
+     * resolves a checkpoint, so there is nothing to substitute.
+     *
+     * OMITTED entirely when nothing was substituted. Absent on hosts that predate
+     * it.
+     */
+    modelSubstitutions?: BlockModelSubstitution[];
+    /**
+     * Generated FREE TEXT produced by a registered text-output step (e.g.
+     * `chat-completion`) — every string here has PASSED the host's output
+     * moderation scan.
+     *
+     * WHERE IT APPEARS: the poll and cancel replies (`poll()` / `cancel()` /
+     * `watch()` on `useBuzzWorkflow`). NOT on the submit reply — a submit returns
+     * a freshly-queued workflow with no output yet, so poll for the text. Also
+     * never on {@link AppWorkflow}, which has no text field.
+     *
+     * OMITTED entirely when there is no text. Independent of
+     * {@link BlockWorkflowSnapshot.textOutputWithheld}: a workflow with two text
+     * steps can release one and withhold the other, and both fields then appear.
+     */
+    textOutputs?: string[];
+    /**
+     * Set when a text-output step produced nothing the block can be given, with a
+     * user-facing sentence saying why. TWO distinct causes land here:
+     *
+     *   1. WITHHELD — text WAS produced and is being kept back: a content-policy
+     *      hit, or any other fail-CLOSED scan outcome (scanner error or timeout,
+     *      no verdict at all, an over-cap payload, or requested labels that came
+     *      back missing or errored). Every one of those paths returns the SAME
+     *      message, so this cause is one string with several origins.
+     *   2. UNPUBLISHABLE — the step SUCCEEDED and the scan RELEASED, but none of
+     *      what came back could be published (e.g. a provider tool-call `id`
+     *      outside the published charset). Nothing was moderated in this case,
+     *      and the message says so explicitly.
+     *
+     * `reason` is deliberately generic: it does not name the labels that
+     * triggered.
+     *
+     * 🔴 THE TWO CAUSES ARE NOT MACHINE-SEPARABLE without matching on the string,
+     * which is NOT a contract. Do not branch on the text of `reason`.
+     *
+     * 🔴 ONLY CAUSE 2 IS STATUS-GATED, and that gate reads the STEP's own
+     * `succeeded` status — never the workflow's. Cause 1 is not gated at all, so a
+     * CANCELLED generation CAN still set this field: the orchestrator returns
+     * whatever text it had already produced, that text is still scanned, and a
+     * hit still withholds it. A block that skips rendering `reason` on cancel
+     * would suppress a real content-policy explanation.
+     *
+     * A block polling a healthy in-flight generation sees the field absent — not
+     * because of its status, but because a step that has produced no text yet can
+     * reach neither cause.
+     *
+     * Independent of {@link BlockWorkflowSnapshot.textOutputs} rather than
+     * mutually exclusive, so `reason` is scoped to "a step in this response",
+     * never to the response as a whole. Same appearance rules as `textOutputs`.
+     */
+    textOutputWithheld?: {
+        reason: string;
+    };
+    /**
+     * Structured tool calls the model requested on a registered text-output step
+     * (e.g. `chat-completion` with tools), which have PASSED the same output
+     * moderation scan as {@link BlockWorkflowSnapshot.textOutputs}: every
+     * `arguments` string here was part of the text the scan released. The tool
+     * `name` is restricted to `[A-Za-z0-9_-]`, so it cannot carry prose.
+     *
+     * Each entry is fully populated — the host drops a call it cannot fill
+     * completely rather than publishing a partial one.
+     *
+     * Same appearance rules as `textOutputs` (poll and cancel replies only).
+     * OMITTED entirely when there are none.
+     */
+    toolCalls?: BlockStepToolCall[];
+    /**
+     * The raw orchestrator output of each PASS-THROUGH step
+     * ({@link WorkflowBodyPassThroughStep}: `kind: 'step'` with a `$type`), as
+     * `{ $type, output }`, forwarded as-is — minus its blobs.
+     *
+     * Blob-SHAPED values are removed from `output`; their available urls go to
+     * {@link BlockWorkflowSnapshot.imageUrls} (and to {@link AppWorkflow.images})
+     * instead, so a pass-through step does not open a second image channel.
+     * "Blob-shaped" is the exact scope of that: a url held in a plain string
+     * field of the output is not a blob and can still appear here.
+     *
+     * 🔴 UNSCANNED. Unlike `textOutputs`, no moderation scan runs over this
+     * field; moderation for the pass-through arm happens at the publish boundary.
+     * Treat any text in it accordingly.
+     *
+     * 🔴 A `$type` that is ALSO a registered step's orchestrator type (e.g.
+     * `chatCompletion`, which `chat-completion` uses) is handled by that
+     * registered step instead — its text arrives on `textOutputs`, scanned, and
+     * it does not appear here. Which channel a pass-through `$type` lands on can
+     * therefore change the day the host registers a step for it.
+     *
+     * `output` is `unknown`: its shape is whatever the orchestrator returns for
+     * that `$type`. OMITTED entirely when the workflow has no pass-through step
+     * with an unregistered `$type`.
+     */
+    stepOutputs?: Array<{
+        $type: string;
+        output: unknown;
+    }>;
+    /**
+     * The epochs of a pass-through `training` / `imageResourceTraining` step
+     * (see {@link WorkflowBodyPassThroughStep}) that PRODUCED A CHECKPOINT — one
+     * entry per epoch, each naming the step's `$type` and its `epochNumber`.
+     * Only runs whose training moderation status is approved are listed; an
+     * unmoderated or refused run reports no epochs.
+     *
+     * 🔴 THE CHECKPOINT ITSELF IS DELIBERATELY NOT EXPOSED — this field carries
+     * no download url. (An older host may still surface checkpoint urls in
+     * `imageUrls` or `stepOutputs` for a training step; that is a host defect,
+     * not a contract — never treat an `imageUrls` entry as a checkpoint.) To
+     * publish a trained epoch, navigate the viewer to Civitai's own model wizard:
+     *
+     * ```ts
+     * const { navigate } = useCivitaiNavigate();
+     * navigate(
+     *   `models/train/from-orchestrator?workflowId=${snapshot.workflowId}&epoch=${epoch.epochNumber}`,
+     *   { scope: 'site' },
+     * );
+     * ```
+     *
+     * The viewer completes (or abandons) the publish there, on Civitai's surface;
+     * {@link BlockWorkflowSnapshot.publishedModel} then reports the result.
+     *
+     * 🔴 REQUIRES A HOST VERSION THAT EMITS IT. Absent on older hosts — treat
+     * absence as "unknown", not as "no checkpoint". The run's spend and timeout
+     * follow the pass-through arm's rules — see
+     * {@link WorkflowBodyPassThroughStep.maxBuzz}.
+     */
+    trainedEpochs?: BlockTrainedEpoch[];
+    /**
+     * The Civitai model this run has been published as — present once the viewer
+     * has STARTED or FINISHED publishing it through the model wizard reached from
+     * {@link BlockWorkflowSnapshot.trainedEpochs}. `published` is `false` while the
+     * model is still a draft and `true` once it is published.
+     *
+     * 🔴 REQUIRES A HOST VERSION THAT EMITS IT. Absent on older hosts, and absent
+     * on any run nobody has started publishing.
+     */
+    publishedModel?: BlockPublishedModel;
+    /**
+     * The quote a {@link WorkflowBodyTraining} ESTIMATE produced — the orchestrator's
+     * own price for exactly that run, stored server-side. Pass
+     * `trainingQuote.quoteId` back as the body's `quoteId` on
+     * `useRunTraining().runTraining()`; the consent dialog then shows the viewer
+     * this price, read back from the server.
+     *
+     * `cost.total` on the same snapshot equals `trainingQuote.total`.
+     * `expiresAt` is an ISO-8601 timestamp: after it the run is refused and you
+     * estimate again. `imageCount` is the server-derived size of the prepared
+     * dataset, never a number the block sent.
+     *
+     * Present ONLY on the reply to a `kind: 'training'` estimate. Absent on hosts
+     * that predate civitai/civitai#5434.
+     */
+    trainingQuote?: BlockTrainingQuote;
+}
+/** {@link BlockWorkflowSnapshot.trainingQuote}. */
+export interface BlockTrainingQuote {
+    /** `tq_` + 32 hex characters. Opaque — pass it back verbatim. */
+    quoteId: string;
+    /** The quoted price, in Buzz. */
+    total: number;
+    /** How many images the prepared dataset holds. */
+    imageCount: number;
+    /** ISO-8601. The quote cannot be run after this. */
+    expiresAt: string;
+}
+/**
+ * Why the host substituted a checkpoint version — see
+ * {@link BlockWorkflowSnapshot.modelSubstitutions}.
+ *
+ *  - `'wrong-workflow'` — the id IS one of this ecosystem's workflow-scoped
+ *    versions, but for a DIFFERENT workflow (e.g. an edit-only version sent to
+ *    text-to-image).
+ *  - `'unrecognized'` — the id is in no scoped list for this ecosystem: a
+ *    community checkpoint, or a version retired since the app shipped.
+ *  - `'gated'` — the id IS offered for this workflow, but a gate rule hid it
+ *    from THIS viewer. The app is not wrong; the viewer may not use it.
+ *
+ * The host may add a reason in a later version, and the SDK's inbound
+ * validator does not reject an unrecognised one — handle an unknown value as a
+ * generic substitution rather than assuming the list is closed.
+ */
+export type ModelSubstitutionReason = 'wrong-workflow' | 'unrecognized' | 'gated';
+/** One entry of {@link BlockWorkflowSnapshot.modelSubstitutions}. */
+export interface BlockModelSubstitution {
+    /** The checkpoint version id the block asked for. */
+    requested: number;
+    /** The checkpoint version id that actually ran. */
+    applied: number;
+    reason: ModelSubstitutionReason;
+}
+/** One entry of {@link BlockWorkflowSnapshot.toolCalls}. */
+export interface BlockStepToolCall {
+    id: string;
+    /**
+     * The SDK's inbound validator checks only that it is a string, so a value
+     * the host adds later can arrive — do not assume `'function'` exhaustively.
+     */
+    type: 'function';
+    function: {
+        /** Restricted to `[A-Za-z0-9_-]`. */
+        name: string;
+        /** The model's arguments, as the JSON string it produced. Scanned. */
+        arguments: string;
+    };
+}
+/** One entry of {@link BlockWorkflowSnapshot.trainedEpochs} / {@link AppWorkflow.trainedEpochs}. */
+export interface BlockTrainedEpoch {
+    /**
+     * Which pass-through training `$type` produced this epoch. The SDK's inbound
+     * validator checks only that it is a string, so a value the host adds later
+     * can arrive — give an exhaustive `switch` a default branch.
+     */
+    $type: 'training' | 'imageResourceTraining';
+    /** Pass as `epoch` to the `/models/train/from-orchestrator` wizard route. */
+    epochNumber: number;
+}
+/**
+ * The model a training run was published as —
+ * {@link BlockWorkflowSnapshot.publishedModel} / {@link AppWorkflow.publishedModel}.
+ */
+export interface BlockPublishedModel {
+    modelId: number;
+    modelVersionId: number;
+    /** `false` while the model is still a draft in the wizard; `true` once published. */
+    published: boolean;
 }
 /**
  * Which side of the settings split a field lives on.
@@ -1827,6 +2262,28 @@ export interface AppWorkflow {
     cost: number | null;
     /** ISO-8601. */
     createdAt: string;
+    /**
+     * The Civitai model a training run in this workflow was published as —
+     * present once the viewer has started or finished publishing it through the
+     * model wizard. Same shape and meaning as
+     * {@link BlockWorkflowSnapshot.publishedModel}.
+     *
+     * 🔴 REQUIRES A HOST VERSION THAT EMITS IT. Absent on older hosts, and on
+     * every workflow nobody has published.
+     */
+    publishedModel?: BlockPublishedModel;
+    /**
+     * The epochs of a pass-through `training` / `imageResourceTraining` step in
+     * this workflow that produced a checkpoint. Same shape and rule as
+     * {@link BlockWorkflowSnapshot.trainedEpochs}: only runs whose training
+     * moderation status is approved are listed, the checkpoint itself is not
+     * exposed, and the field is OMITTED when there are no epochs to list. Lets a
+     * block offer "publish epoch n" from its queue without polling each run.
+     *
+     * 🔴 REQUIRES A HOST VERSION THAT EMITS IT. Absent on older hosts — treat
+     * absence as "unknown", not as "no checkpoint".
+     */
+    trainedEpochs?: BlockTrainedEpoch[];
 }
 /**
  * Per-viewer gated projection of ONE image returned by `GET_IMAGES_BY_IDS`
@@ -2043,5 +2500,102 @@ export interface BlockCreatePostResult {
  *   write, so a dismissal mid-write can never claim this code.
  */
 export type BlockCreatePostHostError = 'review-mode' | 'block is not ready' | 'sign in to post' | 'no images to post' | 'no block token' | 'declined';
+/**
+ * One image of a training dataset request — an `Image` id the VIEWER owns, and
+ * the caption to train it with.
+ *
+ * Host bounds (`blockTrainingDatasetItemsSchema`): `imageId` a positive integer,
+ * `caption` at most {@link BLOCK_TRAINING_CAPTION_MAX_CHARS} characters, no other
+ * keys; 1…{@link BLOCK_TRAINING_DATASET_MAX_ITEMS} items per request. A payload
+ * outside them is refused by the host with `invalid training dataset` before any
+ * server call. Captions are moderated like prompts.
+ */
+export interface BlockTrainingDatasetItem {
+    imageId: number;
+    caption: string;
+}
+/**
+ * Why the server left an image out of a prepared dataset. Mirrors
+ * civitai/civitai's `BlockTrainingRejectionReason`.
+ *
+ * - `unavailable` — not found, OR not the viewer's own image. One reason for
+ *   both, on purpose: the server will not tell an app whether someone else's
+ *   image id exists.
+ * - `unsupported-media` — a video or audio row.
+ * - `not-eligible` — refused by moderation state or the page's maturity ceiling.
+ * - `pending-scan` — not scanned yet; retry once the scan finishes.
+ * - `import-failed` — the orchestrator did not accept the image.
+ * - `import-unavailable` — the import timed out or the orchestrator was
+ *   unavailable; retryable.
+ *
+ * The SDK's inbound validator checks `reason` only as a STRING, so a reason the
+ * host adds later still arrives — give an exhaustive `switch` a default branch.
+ */
+export type BlockTrainingRejectionReason = 'unavailable' | 'unsupported-media' | 'not-eligible' | 'pending-scan' | 'import-failed' | 'import-unavailable';
+/**
+ * The success payload of `TRAINING_DATASET_RESULT` — what
+ * `usePrepareTrainingDataset().prepareDataset()` resolves with.
+ */
+export interface BlockTrainingDatasetResult {
+    /**
+     * Opaque handle for {@link WorkflowBodyTraining.datasetId} (`tds_` + 32 hex
+     * characters), bound to this viewer, app and install.
+     */
+    datasetId: string;
+    /**
+     * How many images were ADMITTED — always at least 1: when nothing is admitted
+     * the server refuses the request instead of returning an empty dataset. The
+     * server derives it; a run trains on exactly these.
+     */
+    count: number;
+    /** The images left out, each with its reason. Empty when every image was admitted. */
+    rejected: Array<{
+        imageId: number;
+        reason: BlockTrainingRejectionReason;
+    }>;
+}
+/**
+ * The HOST'S OWN refusal codes on a `TRAINING_DATASET_RESULT`'s `error`. Mirrors
+ * civitai/civitai's `PREPARE_TRAINING_DATASET_HOST_ERRORS`
+ * (`src/components/AppBlocks/prepareTrainingDatasetGate.ts`, civitai/civitai#5438).
+ *
+ * 🔴 THE SET A BLOCK MAY RELY ON, NOT THE SET IT MAY RECEIVE: `error` also carries
+ * any server message verbatim (`training from apps is not enabled`, a rate limit,
+ * a moderation refusal of a caption). Compare by EQUALITY against these members
+ * and treat anything else as an opaque server message.
+ *
+ * - `review-mode` — a mod-review sandbox with "run for real" off.
+ * - `block is not ready` — the host handshake has not completed.
+ * - `sign in to train` — anonymous viewer; there are no images of theirs to read.
+ * - `invalid training dataset` — `items` failed the host's item schema (shape,
+ *   count or caption length). Nothing was sent to the server.
+ * - `no block token` — the host holds no block token yet.
+ */
+export type BlockPrepareTrainingDatasetHostError = 'review-mode' | 'block is not ready' | 'sign in to train' | 'invalid training dataset' | 'no block token';
+/**
+ * The HOST'S OWN refusal codes on a `TRAINING_RESULT`'s `error`. Mirrors
+ * civitai/civitai's `RUN_TRAINING_HOST_ERRORS`
+ * (`src/components/AppBlocks/runTrainingGate.ts`).
+ *
+ * 🔴 THE SET A BLOCK MAY RELY ON, NOT THE SET IT MAY RECEIVE: server messages
+ * (an expired or already-used quote, a body that differs from the quoted one, an
+ * ineligible dataset image) arrive verbatim in the same field.
+ *
+ * - `review-mode` — a mod-review sandbox with "run for real" off.
+ * - `block is not ready` — the host handshake has not completed.
+ * - `sign in to train` — anonymous viewer; there is no account to charge.
+ * - `invalid training request` — the body is not a `kind: 'training'` body
+ *   naming a `quoteId`.
+ * - `no block token` — the host holds no block token yet.
+ * - `declined` — the viewer dismissed the consent dialog. 🔴 GUARANTEED to mean
+ *   NO RUN WAS SUBMITTED.
+ * - `submission-unconfirmed` — the submit was SENT but its outcome is unknown
+ *   (the connection dropped, or the server attempted the run and could not
+ *   confirm it). 🔴 The run MAY BE RUNNING AND CHARGED. Check the viewer's
+ *   trainings (`useAppWorkflows()`, or send them to their Training page) before
+ *   offering a retry — a retry of the same body after the server did start the
+ *   run is a SECOND, separately charged run.
+ */
+export type BlockRunTrainingHostError = 'review-mode' | 'block is not ready' | 'sign in to train' | 'invalid training request' | 'no block token' | 'declined' | 'submission-unconfirmed';
 export {};
 //# sourceMappingURL=types.d.ts.map