@cat-factory/app 0.205.0 → 0.207.0

package/app/components/binaryOutput/BinaryOutputReport.vue

@@ -88,6 +88,16 @@ const state = computed(() => {
         <dt class="text-slate-500">{{ t('binaryOutput.contextServices') }}</dt>
         <dd class="min-w-0 font-mono text-slate-400">{{ view.contextServices.join(', ') }}</dd>
       </template>
+      <!-- The formats the step REQUIRED, beside where they were meant to go. Rendered whenever
+           the step stated any, including on a run that delivered them: the requirement is what
+           makes the content types below it readable, and a reader checking whether a mesh will
+           load needs to see what was asked for even when nothing went wrong. -->
+      <template v-if="view.mediaTypes.length">
+        <dt class="text-slate-500">{{ t('binaryOutput.mediaTypes') }}</dt>
+        <dd class="min-w-0 font-mono text-slate-400" data-testid="binary-output-media-types">
+          {{ view.mediaTypes.join(', ') }}
+        </dd>
+      </template>
     </dl>
 
     <!-- The artifacts. `location` is the service's OWN addressing — an object key, a path, a
@@ -194,6 +204,29 @@ const state = computed(() => {
           )
         }}
       </li>
+      <!-- The third state of the same question, and the reason it is not the line above with an
+           empty list: an empty `unknownDeclaredGenerators` otherwise means every claimed id
+           checked out. Someone reading this panel to decide whether these artifacts are real
+           must not be handed a clean bill of health nobody issued. -->
+      <li v-if="view.generatorsUnverified" data-testid="binary-output-generators-unverified">
+        {{ t('binaryOutput.warning.generatorsUnverified') }}
+      </li>
+      <!-- The one judgement this panel can make that admission could not: admission checked what
+           the selected integrations CAN emit, this checks what came back. Derived in code from
+           the step's own two records — the requirement and the reported content types — never
+           read off the agent's prose. -->
+      <li v-if="view.undeliveredMediaTypes.length" data-testid="binary-output-undelivered-formats">
+        {{
+          t(
+            'binaryOutput.warning.undeliveredMediaTypes',
+            {
+              formats: view.undeliveredMediaTypes.join(', '),
+              count: view.undeliveredMediaTypes.length,
+            },
+            view.undeliveredMediaTypes.length,
+          )
+        }}
+      </li>
       <li v-if="view.misdirected" data-testid="binary-output-misdirected-note">
         {{
           t(

package/app/components/pipeline/BinaryOutputStepPicker.logic.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { parseMediaTypeRequirement, sameFormats } from './BinaryOutputStepPicker.logic'
+
+describe('parseMediaTypeRequirement', () => {
+  it('stores the reduction the backend compares against, not what was typed', () => {
+    // The field is forgiving on the way in and exact on the way out. A locally-lowercased copy
+    // would store a format that matches nothing and then reads everywhere as one that was simply
+    // never emitted — indistinguishable from a real delivery failure.
+    expect(parseMediaTypeRequirement(' Model/GLTF-Binary , image/PNG ').usable).toEqual([
+      'model/gltf-binary',
+      'image/png',
+    ])
+  })
+
+  it('drops a parameter, because a requirement is a format and not one request encoding', () => {
+    expect(parseMediaTypeRequirement('model/gltf-binary; charset=binary').usable).toEqual([
+      'model/gltf-binary',
+    ])
+  })
+
+  it('NAMES what it refused rather than quietly shortening the requirement', () => {
+    // A requirement someone typed and the step does not carry is the "absent reads as fine"
+    // failure the rest of this surface is built to avoid, so the entry survives verbatim for the
+    // warning to quote.
+    const parsed = parseMediaTypeRequirement('gltf, model/obj, ')
+    expect(parsed.usable).toEqual(['model/obj'])
+    expect(parsed.unusable).toEqual(['gltf'])
+  })
+
+  it('deduplicates what two spellings reduce to, keeping first-stated order', () => {
+    const parsed = parseMediaTypeRequirement('model/obj, MODEL/OBJ, model/gltf-binary')
+    expect(parsed.usable).toEqual(['model/obj', 'model/gltf-binary'])
+  })
+
+  it('maps no synonyms, so a near neighbour stays a separate requirement', () => {
+    // `model/obj` and `application/x-tgif` are the same file. Collapsing them would make the
+    // admission check accept a GLB where an OBJ was required — the failure it exists to prevent.
+    const parsed = parseMediaTypeRequirement('model/obj, application/x-tgif')
+    expect(parsed.usable).toEqual(['model/obj', 'application/x-tgif'])
+  })
+
+  it('reads an empty requirement as no requirement', () => {
+    expect(parseMediaTypeRequirement('  ,  ')).toEqual({ usable: [], unusable: [] })
+  })
+})
+
+describe('sameFormats', () => {
+  it('treats an absent list and an empty one as the same write', () => {
+    // Clearing the field stores `undefined`, so the two spellings of "no requirement" must not
+    // read as a change that came from elsewhere.
+    expect(sameFormats(undefined, [])).toBe(true)
+  })
+
+  it('is order-sensitive, because the field writes back exactly what it read', () => {
+    expect(sameFormats(['a/b', 'c/d'], ['c/d', 'a/b'])).toBe(false)
+    expect(sameFormats(['a/b', 'c/d'], ['a/b', 'c/d'])).toBe(true)
+  })
+})

package/app/components/pipeline/BinaryOutputStepPicker.logic.ts

@@ -0,0 +1,55 @@
+import { mediaTypeSchema, normalizeMediaType } from '@cat-factory/contracts'
+import * as v from 'valibot'
+
+// The pure half of BinaryOutputStepPicker: reading a free-text FORMAT requirement, and telling
+// this field's own write apart from one that landed underneath it. Extracted for the reason every
+// `*.logic.ts` here is — a decision worth a test should not need a mounted component to reach.
+
+/** A parsed format requirement: what the step will carry, and what was refused on the way in. */
+export interface ParsedMediaTypeRequirement {
+  /** Normalised, deduplicated, order-preserving — exactly what gets stored. */
+  usable: string[]
+  /** Entries that are not a `type/subtype` at all, kept VERBATIM so the warning can quote them. */
+  unusable: string[]
+}
+
+/**
+ * Read a comma-separated format requirement the way the field accepts it and the way the backend
+ * will hold it.
+ *
+ * Forgiving on the way IN, exact on the way out, and both halves are the backend's own rules
+ * imported rather than re-implemented: `normalizeMediaType` is the same reduction the comparison
+ * uses at both ends (a divergent local lowercasing would store a format that matches nothing and
+ * reads everywhere as one that was simply never emitted), and `mediaTypeSchema` is what the save
+ * boundary holds this to — so what is refused here is exactly what would come back as a 422 one
+ * round trip later.
+ *
+ * A refused entry is REPORTED, never quietly dropped: a requirement someone typed and the step
+ * does not carry is the "absent reads as fine" failure the rest of this surface exists to avoid.
+ */
+export function parseMediaTypeRequirement(text: string): ParsedMediaTypeRequirement {
+  const usable: string[] = []
+  const unusable: string[] = []
+  for (const entry of text
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)) {
+    const normalized = normalizeMediaType(entry)
+    if (normalized && v.safeParse(mediaTypeSchema, normalized).success) usable.push(normalized)
+    else unusable.push(entry)
+  }
+  return { usable: [...new Set(usable)], unusable }
+}
+
+/**
+ * Whether two stored format lists are the same write.
+ *
+ * Order-sensitive on purpose: the field writes back what it read, so a differing order means the
+ * value came from somewhere else, which is precisely what the caller is asking about.
+ */
+export function sameFormats(
+  a: readonly string[] | undefined,
+  b: readonly string[] | undefined,
+): boolean {
+  return (a ?? []).join(',') === (b ?? []).join(',')
+}

package/app/components/pipeline/BinaryOutputStepPicker.vue

@@ -19,14 +19,16 @@
 // ride the workspace snapshot (`binaryGenerators`) rather than a catalog read. Both halves are
 // offered here because a step needs both to work, and only this surface can tell a human that the
 // content types it promises to deliver are not covered by anything it selected.
-import { computed } from 'vue'
+import { computed, ref, watch } from 'vue'
 import {
   ASSET_STORAGE_CAPABILITY,
   GENERATION_CONTEXT_CAPABILITY,
+  isBinaryModality,
   type BinaryModality,
   type BinaryOutputConfig,
 } from '@cat-factory/contracts'
 import { binaryOutputPickIssues, type BinaryOutputPickIssue } from '~/utils/binaryOutput'
+import { parseMediaTypeRequirement, sameFormats } from './BinaryOutputStepPicker.logic'
 
 const props = defineProps<{ index: number }>()
 
@@ -44,12 +46,42 @@ const MODALITY_LABELS: Record<BinaryModality, () => string> = {
   image: () => t('pipeline.builder.binaryOutputModality.image'),
   audio: () => t('pipeline.builder.binaryOutputModality.audio'),
   video: () => t('pipeline.builder.binaryOutputModality.video'),
-  '3d': () => t('pipeline.builder.binaryOutputModality.3d'),
+  '3d-model': () => t('pipeline.builder.binaryOutputModality.3d-model'),
+  '3d-scene': () => t('pipeline.builder.binaryOutputModality.3d-scene'),
   document: () => t('pipeline.builder.binaryOutputModality.document'),
 }
-const MODALITY_ORDER: BinaryModality[] = ['image', 'audio', 'video', '3d', 'document']
+const MODALITY_ORDER: BinaryModality[] = [
+  'image',
+  'audio',
+  'video',
+  '3d-model',
+  '3d-scene',
+  'document',
+]
+/**
+ * A content type in the reader's language, INCLUDING one this build no longer defines.
+ *
+ * The `Record` above is exhaustive over the union, so the lookup looks total — and is not, because
+ * `modalities` is PERSISTED: a step saved under an earlier vocabulary carries a member that has
+ * since been retired (`3d` did exactly that when it split into `3d-model` and `3d-scene`). Such a
+ * value is by construction uncovered by every registered integration, so it lands in the
+ * `modality_uncovered` warning below — the one line whose job is to tell someone what to re-pick —
+ * and a bare `MODALITY_LABELS[modality]()` there is a `TypeError` that takes the whole builder
+ * down, on exactly the surface the fix has to be made on.
+ *
+ * The guard is `isBinaryModality` (contracts, derived from the picklist itself) rather than an
+ * optional call on the `Record`, so the narrowing says WHY it is needed and a member added to the
+ * vocabulary is known here without anyone remembering to widen anything.
+ *
+ * The retired value is NAMED rather than silently dropped or guessed at a current member: nothing
+ * here knows which one was meant, and a modality quietly missing from the list reads as a step
+ * that never required it. This is the standing "absent is not zero" rule at the one place the
+ * typed-key check cannot reach — the key is static, but the LOOKUP is a runtime value.
+ */
 function modalityLabel(modality: BinaryModality): string {
-  return MODALITY_LABELS[modality]()
+  return isBinaryModality(modality)
+    ? MODALITY_LABELS[modality]()
+    : t('pipeline.builder.binaryOutputModalityRetired', { modality: String(modality) })
 }
 
 const config = computed(() => pipelines.draftBinaryOutput(props.index))
@@ -99,6 +131,7 @@ const pick = computed(() =>
     catalog.resolved,
     catalog.available,
     agents.binaryGenerators,
+    agents.binaryGeneratorsUnavailable,
   ),
 )
 function has(issue: BinaryOutputPickIssue): boolean {
@@ -142,6 +175,64 @@ function setGenerators(ids: string[]) {
 function setModalities(modalities: BinaryModality[]) {
   patch({ modalities })
 }
+
+/**
+ * The FORMAT requirement is free text, not a pick from the selection, and that is deliberate: the
+ * whole reason a step states a format is that the selected integrations might not cover it, and a
+ * picker offering only what they declare could never express the requirement whose violation this
+ * feature exists to catch. What the selection declares is offered as a HINT below instead.
+ *
+ * Held in a local ref rather than bound straight to the config so a half-typed `model/` is not
+ * parsed on every keystroke, and so the normalisation the field applies is VISIBLE — the text
+ * snaps back to what was stored.
+ */
+const mediaTypeText = ref((config.value?.mediaTypes ?? []).join(', '))
+
+/**
+ * Entries that are not a `type/subtype` at all, named rather than silently dropped — a
+ * requirement someone typed and the step does not carry is exactly the "absent reads as fine"
+ * failure the rest of this surface is built to avoid.
+ */
+const unusableMediaTypes = ref<string[]>([])
+
+/**
+ * What this field last wrote, so the watch below can tell its OWN patch from a config that
+ * changed underneath it.
+ */
+let lastWritten: string[] | undefined = config.value?.mediaTypes
+
+watch(
+  () => config.value?.mediaTypes,
+  (mediaTypes) => {
+    mediaTypeText.value = (mediaTypes ?? []).join(', ')
+    // The rejected entries belong to the TEXT that was typed, so they outlive this field's own
+    // patch — clearing them on every config change would erase the warning in the same tick it
+    // was raised, since accepting `image/png` out of `foo, image/png` is itself a patch. Any
+    // OTHER route to a new value (the picker rebound to another step, the draft reloaded,
+    // storage cleared and the bag dropped) is describing text that no longer exists, and a
+    // warning about entries nobody can see is the same "absent reads as fine" failure pointed
+    // the other way.
+    if (!sameFormats(mediaTypes, lastWritten)) unusableMediaTypes.value = []
+    lastWritten = mediaTypes
+  },
+)
+
+function setMediaTypes(text: string) {
+  const { usable, unusable } = parseMediaTypeRequirement(text)
+  unusableMediaTypes.value = unusable
+  mediaTypeText.value = usable.join(', ')
+  // Claimed BEFORE the patch, so the watch above reads this write as its own however it is
+  // flushed, and the entries just rejected survive to be rendered.
+  lastWritten = usable.length ? usable : undefined
+  patch({ mediaTypes: lastWritten })
+}
+
+/** What the SELECTED integrations say they emit — the discoverable half of the free-text field. */
+const declaredFormats = computed(() => {
+  const byId = new Map(agents.binaryGenerators.map((generator) => [generator.id, generator]))
+  const selected = (config.value?.generatorIds ?? []).flatMap((id) => byId.get(id) ?? [])
+  return [...new Set(selected.flatMap((generator) => generator.mediaTypes ?? []))]
+})
 </script>
 
 <template>
@@ -215,6 +306,33 @@ function setModalities(modalities: BinaryModality[]) {
       />
     </div>
 
+    <!-- The FORMAT requirement, one notch finer than the content types above it and shown right
+         under them. Both tiers: like the rest of this picker it is not an override of a default —
+         a format nobody stated is a format the run does not check. -->
+    <div v-if="config?.storageServiceId" class="flex items-center gap-2">
+      <span class="text-[10px] text-slate-500">{{
+        t('pipeline.builder.binaryOutputMediaTypes')
+      }}</span>
+      <UInput
+        class="w-56"
+        :model-value="mediaTypeText"
+        size="xs"
+        :placeholder="t('pipeline.builder.binaryOutputMediaTypesPlaceholder')"
+        data-testid="binary-output-media-type-input"
+        @update:model-value="mediaTypeText = String($event)"
+        @change="setMediaTypes(mediaTypeText)"
+      />
+    </div>
+    <p
+      v-if="config?.storageServiceId && declaredFormats.length"
+      class="ms-1 text-[10px] text-slate-500"
+      data-testid="binary-output-declared-formats"
+    >
+      {{
+        t('pipeline.builder.binaryOutputDeclaredFormats', { formats: declaredFormats.join(', ') })
+      }}
+    </p>
+
     <!-- Every refusal this step would hit, named where it is fixable. Each is its own line
          with its own remedy: an unreachable catalog is not an empty one, a lost service is not
          an untagged one, and a lost CONTEXT service is not a lost storage target. -->
@@ -247,7 +365,16 @@ function setModalities(modalities: BinaryModality[]) {
     </p>
     <!-- The generative refusals stay their own lines, and their remedies point somewhere else
          entirely: an unregistered integration is fixed in the DEPLOYMENT'S BUILD, not in this
-         workspace, which is the whole reason the backend keeps the two reason codes apart. -->
+         workspace, which is the whole reason the backend keeps the two reason codes apart.
+         Unless the set could not be READ, in which case none of them is a claim anyone can make:
+         it says so and stops, exactly as run admission does. -->
+    <p
+      v-if="has('generators_unavailable')"
+      class="text-[10px] text-amber-400"
+      data-testid="binary-output-generators-unavailable"
+    >
+      {{ t('pipeline.builder.binaryOutputGeneratorsUnavailable') }}
+    </p>
     <p
       v-if="has('unknown_generator')"
       class="text-[10px] text-amber-400"
@@ -270,5 +397,42 @@ function setModalities(modalities: BinaryModality[]) {
         })
       }}
     </p>
+    <p
+      v-if="has('media_type_uncovered')"
+      class="text-[10px] text-amber-400"
+      data-testid="binary-output-media-type-uncovered"
+    >
+      {{
+        t('pipeline.builder.binaryOutputMediaTypeUncovered', {
+          formats: pick.uncoveredMediaTypes.join(', '),
+        })
+      }}
+    </p>
+    <!-- ADVISORY, and styled apart from every line above it: the step starts. The backend admits
+         a format requirement it could not judge, because a generator that declares no formats has
+         said only that its formats are unknown — and a surface that dressed that up as a refusal
+         would send someone editing a selection that is fine. -->
+    <p
+      v-if="has('media_type_unverifiable')"
+      class="text-[10px] text-slate-500"
+      data-testid="binary-output-media-type-unverifiable"
+    >
+      {{
+        t('pipeline.builder.binaryOutputMediaTypeUnverifiable', {
+          formats: pick.unverifiableMediaTypes.join(', '),
+        })
+      }}
+    </p>
+    <p
+      v-if="unusableMediaTypes.length"
+      class="text-[10px] text-amber-400"
+      data-testid="binary-output-media-type-unusable"
+    >
+      {{
+        t('pipeline.builder.binaryOutputMediaTypeUnusable', {
+          entries: unusableMediaTypes.join(', '),
+        })
+      }}
+    </p>
   </div>
 </template>

package/app/composables/usePipelineErrorToast.ts

@@ -25,8 +25,8 @@
  */
 
 import { createBespokeConflictToasts } from '~/composables/pipelineErrorToast/bespokeConflicts'
-import type { ApiErrorCode, ConflictReason } from '@cat-factory/contracts'
-import { apiErrorEnvelope, apiErrorStatus } from './api/errors'
+import type { ApiErrorCode, ConflictReason, UnavailableReason } from '@cat-factory/contracts'
+import { apiErrorEnvelope, apiErrorReason, apiErrorStatus } from './api/errors'
 
 /** The parsed shape of a backend conflict (`{ error: { code: 'conflict', details } }`). */
 interface ConflictDetails {
@@ -285,6 +285,28 @@ const GENERIC_DESCRIPTION_KEYS: Record<Exclude<ApiErrorCode, 'conflict'>, string
   internal: 'errors.generic.description.internal',
 }
 
+/**
+ * Translated description per REASON, for the non-conflict failures whose status class alone would
+ * describe them wrongly. Checked before {@link GENERIC_DESCRIPTION_KEYS} and falling through to
+ * it for every reason not listed, so this stays a short list of exceptions rather than a second
+ * vocabulary to keep in sync.
+ *
+ * It exists because the generic 503 copy has to commit to something, and what it commits to is
+ * "this deployment has not configured the capability this action needs". That is right for the
+ * common 503 (a module nobody wired) and exactly wrong for an outage: it tells an operator their
+ * build is missing a registration when the truth is that a set could not be read right now. On a
+ * mothership-mode node that is the misattribution this whole seam exists to remove, reappearing
+ * one layer up — with the honest wording demoted to untranslated detail behind a disclosure. So
+ * the reasons in {@link UNAVAILABLE_REASONS} carry their own copy, and the exhaustive `Record`
+ * over that union is the drift guard: a new user-reachable 503 reason fails this typecheck until
+ * it has wording.
+ */
+const UNAVAILABLE_DESCRIPTION_KEYS: Record<UnavailableReason, string> = {
+  binary_generators_unreachable: 'errors.unavailable.description.binary_generators_unreachable',
+  foundational_builtins_unreachable:
+    'errors.unavailable.description.foundational_builtins_unreachable',
+}
+
 /**
  * The request never reached a server that answered in our envelope shape — offline, DNS, a dropped
  * connection, CORS. Distinct from {@link UNEXPECTED_DESCRIPTION_KEY} on purpose: this one's remedy
@@ -326,7 +348,13 @@ export function describeGenericFailure(error: unknown): GenericFailure {
   // don't know must resolve to `undefined`, which is exactly what the alias's index signature
   // says and what a cast would have hidden. The narrow Record above stays the drift guard.
   const byCode: Readonly<Record<string, string | undefined>> = GENERIC_DESCRIPTION_KEYS
-  const mapped = envelope?.code ? byCode[envelope.code] : undefined
+  // A REASON that has its own copy wins over the status class's, through the same widened-alias
+  // read and for the same reason: a `reason` this build doesn't know must resolve to `undefined`
+  // and fall through, never narrow the wire string to the union by casting.
+  const byReason: Readonly<Record<string, string | undefined>> = UNAVAILABLE_DESCRIPTION_KEYS
+  const reason = apiErrorReason(error)
+  const mapped =
+    (reason ? byReason[reason] : undefined) ?? (envelope?.code ? byCode[envelope.code] : undefined)
   // No envelope at all AND no status ⇒ nothing answered; with a status, something did.
   const unrecognised =
     !envelope && apiErrorStatus(error) === undefined

package/app/stores/agents.ts

@@ -54,6 +54,15 @@ export const useAgentsStore = defineStore('agents', () => {
    */
   const binaryGenerators = ref<RegisteredBinaryGenerator[]>([])
 
+  /**
+   * Whether that set could not be READ, straight off the snapshot's own flag. Its own piece of
+   * state rather than something inferred from an empty list, because the two are opposite facts:
+   * an empty list means this deployment registers none (fix it in the build), and an unreadable
+   * one means nobody knows (fix the connection). A picker that renders them alike sends someone
+   * to the wrong repository. False on every deployment that reads its integrations in-process.
+   */
+  const binaryGeneratorsUnavailable = ref(false)
+
   /**
    * The merged CUSTOM catalog (consumer-slot → backend-manifest → runtime), each
    * mapped to display metadata, de-duplicated, and never shadowing a built-in or
@@ -154,8 +163,12 @@ export const useAgentsStore = defineStore('agents', () => {
    * exactly these ids, so they are the same set run admission resolves a step's `generatorIds`
    * against — an id offered from anywhere else would save clean and be refused at run START.
    */
-  function hydrateBinaryGenerators(list: readonly RegisteredBinaryGenerator[]) {
+  function hydrateBinaryGenerators(
+    list: readonly RegisteredBinaryGenerator[],
+    unavailable = false,
+  ) {
     binaryGenerators.value = [...list]
+    binaryGeneratorsUnavailable.value = unavailable
   }
 
   /** Hydrate the deployment's registered agent-kind variants from the snapshot (straight replace). */
@@ -191,6 +204,7 @@ export const useAgentsStore = defineStore('agents', () => {
     hydrateVariants,
     variantsForKind,
     binaryGenerators,
+    binaryGeneratorsUnavailable,
     hydrateBinaryGenerators,
     variantLabel,
   }

package/app/stores/workspace/hydrate.ts

@@ -102,7 +102,12 @@ export function applySnapshotToStores(snapshot: WorkspaceSnapshot, boardSince?:
   useAgentsStore().hydrateVariants(snapshot.agentKindVariants ?? [])
   // The deployment's registered generative binary integrations, so the builder's binary-output
   // picker can offer a step's `generatorIds` from the same set run admission validates against.
-  useAgentsStore().hydrateBinaryGenerators(snapshot.binaryGenerators ?? [])
+  // …and whether that set could not be read at all, which the picker must say rather than
+  // render as an empty deployment (see `binaryGeneratorsUnavailable` on the snapshot).
+  useAgentsStore().hydrateBinaryGenerators(
+    snapshot.binaryGenerators ?? [],
+    snapshot.binaryGeneratorsUnavailable === true,
+  )
   useTaskTypesStore().hydrateCapabilities(capabilities)
   // The account's repo-sourced Claude Skills catalog (shared across its workspaces), so the
   // pipeline builder's per-step skill picker has its options. A straight replace.