@cat-factory/app 0.195.1 → 0.196.0

package/app/composables/usePipelineErrorToast.spec.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { usePipelineErrorToast, parseConflict } from '~/composables/usePipelineErrorToast'
+import {
+  usePipelineErrorToast,
+  parseConflict,
+  describeGenericFailure,
+} from '~/composables/usePipelineErrorToast'
 import { ApiError } from '~/composables/api/errors'
 import en from '../../i18n/locales/en.json'
 
@@ -9,6 +13,9 @@ import en from '../../i18n/locales/en.json'
  * title AND the description (G1) — and only ever shows raw backend prose as a last-resort
  * description (an unmapped reason). These specs assert the KEYS and params a code path
  * resolves (never the English text), so they stay locale-agnostic.
+ *
+ * The same holds for the NON-conflict funnel (G2): the description is keyed off the envelope's
+ * status class and the raw prose is only reachable behind the "Show details" disclosure.
  */
 
 /** Dot-path lookup into the real `en.json`, so `te` mirrors which keys actually ship. */
@@ -21,11 +28,15 @@ function hasKey(path: string): boolean {
 }
 
 let add: ReturnType<typeof vi.fn>
+let update: ReturnType<typeof vi.fn>
 let t: ReturnType<typeof vi.fn>
 let ui: Record<string, ReturnType<typeof vi.fn>>
 
 beforeEach(() => {
-  add = vi.fn()
+  // `add` returns the created toast (Nuxt UI hands back the generated id synchronously), which
+  // the detail disclosure needs in order to `update` the SAME toast in place.
+  add = vi.fn(() => ({ id: 'toast-1' }))
+  update = vi.fn()
   // `t` echoes the key so the toast's title/description IS the resolved key — assert on it.
   t = vi.fn((key: string) => key)
   // The ui-store deep-links a jump action may navigate to (each echoed as a spy).
@@ -36,7 +47,7 @@ beforeEach(() => {
     openModelConfig: vi.fn(),
     openProviderConnection: vi.fn(),
   }
-  vi.stubGlobal('useToast', () => ({ add }))
+  vi.stubGlobal('useToast', () => ({ add, update }))
   vi.stubGlobal('useUiStore', () => ui)
   vi.stubGlobal('useI18n', () => ({ t, te: (key: string) => hasKey(key) }))
 })
@@ -128,10 +139,113 @@ describe('usePipelineErrorToast', () => {
     expect(ui.openAiProviderSetup).toHaveBeenCalledOnce()
   })
 
-  it('uses the fallback title key + raw message for a non-conflict error', () => {
+  it('uses the fallback title key + a TRANSLATED description for a non-conflict error', () => {
+    // G2: the raw JS/backend prose is no longer the description — a bare throw with no HTTP
+    // answer at all is presented as the network case.
     usePipelineErrorToast().present(new Error('boom'), 'errors.action.startFailed')
     const arg = add.mock.calls[0]![0]
     expect(arg.title).toBe('errors.action.startFailed')
-    expect(arg.description).toBe('boom')
+    expect(arg.description).toBe('errors.generic.description.network')
+    expect(arg.description).not.toBe('boom')
+  })
+
+  it('keys the description off the envelope status class, not the backend prose', () => {
+    usePipelineErrorToast().present(
+      new ApiError(503, { error: { code: 'unavailable', message: 'Task sources not configured' } }),
+    )
+    expect(add.mock.calls[0]![0].description).toBe('errors.generic.description.unavailable')
+  })
+
+  it('reveals the raw detail in place when "Show details" is clicked, and makes it sticky', () => {
+    usePipelineErrorToast().present(
+      new ApiError(503, { error: { code: 'unavailable', message: 'Task sources not configured' } }),
+    )
+    const arg = add.mock.calls[0]![0]
+    // Auto-dismissing until the user asks for detail: no `duration` override up front.
+    expect(arg.duration).toBeUndefined()
+    expect(arg.actions[0].label).toBe('errors.generic.showDetail')
+    arg.actions[0].onClick()
+    // Same toast, not a second one; sticky, and the button is dropped so it can't be re-clicked.
+    expect(add).toHaveBeenCalledTimes(1)
+    expect(update).toHaveBeenCalledWith('toast-1', {
+      description: 'Task sources not configured',
+      duration: 0,
+      actions: [],
+    })
+  })
+
+  it('folds validation issues and the requestId into the revealed detail', () => {
+    usePipelineErrorToast().present(
+      new ApiError(400, {
+        error: {
+          code: 'validation',
+          message: 'Request failed validation',
+          requestId: 'req-42',
+          issues: [{ path: 'body.title', message: 'Required' }, { message: 'Unexpected field' }],
+        },
+      }),
+    )
+    const arg = add.mock.calls[0]![0]
+    expect(arg.description).toBe('errors.generic.description.validation')
+    arg.actions[0].onClick()
+    expect(t).toHaveBeenCalledWith('errors.generic.requestId', { id: 'req-42' })
+    // The issues carry the real information on a 422/400 (the message is the fixed
+    // `Request failed validation`), so they must reach the disclosure.
+    expect(update.mock.calls[0]![1].description).toBe(
+      'Request failed validation · body.title: Required, Unexpected field · errors.generic.requestId',
+    )
+  })
+
+  it('offers no disclosure when there is no detail to reveal', () => {
+    usePipelineErrorToast().present(new ApiError(503, { error: { code: 'unavailable' } }))
+    const arg = add.mock.calls[0]![0]
+    // `ApiError` synthesises `Request failed (HTTP 503)` when the envelope carries no message,
+    // so a truly detail-less case is a non-Error throw.
+    expect(arg.description).toBe('errors.generic.description.unavailable')
+    expect(arg.actions[0].label).toBe('errors.generic.showDetail')
+    usePipelineErrorToast().present(null)
+    expect(add.mock.calls[1]![0].actions).toBeUndefined()
+  })
+})
+
+describe('describeGenericFailure', () => {
+  it('maps each known status class to its own description key', () => {
+    for (const code of [
+      'not_found',
+      'validation',
+      'credential_required',
+      'forbidden',
+      'unavailable',
+      'unauthorized',
+      'rate_limited',
+      'internal',
+    ]) {
+      const failure = describeGenericFailure(new ApiError(500, { error: { code } }))
+      expect(failure.descriptionKey).toBe(`errors.generic.description.${code}`)
+      expect(hasKey(failure.descriptionKey)).toBe(true)
+    }
+  })
+
+  it('separates "nothing answered" from "something answered unrecognisably"', () => {
+    // No envelope AND no status: offline / DNS / dropped connection — the remedy is the user's.
+    expect(describeGenericFailure(new Error('Failed to fetch')).descriptionKey).toBe(
+      'errors.generic.description.network',
+    )
+    // A status but not our envelope (an edge 502 page) — the remedy is the server's.
+    expect(
+      describeGenericFailure(new ApiError(502, '<html>bad gateway</html>')).descriptionKey,
+    ).toBe('errors.generic.description.unexpected')
+    // Our envelope, but a code this build does not know.
+    expect(
+      describeGenericFailure(new ApiError(418, { error: { code: 'teapot' } })).descriptionKey,
+    ).toBe('errors.generic.description.unexpected')
+  })
+
+  it('never presents a conflict (parseConflict owns those) but still classifies safely', () => {
+    // `conflict` is deliberately absent from the map, so it reads as an unrecognised code rather
+    // than throwing — the conflict path intercepts it long before this function is reached.
+    expect(
+      describeGenericFailure(new ApiError(409, { error: { code: 'conflict' } })).descriptionKey,
+    ).toBe('errors.generic.description.unexpected')
   })
 })

package/app/composables/usePipelineErrorToast.ts

@@ -11,10 +11,21 @@
  * locale missing the key) and stays untranslated — the contract is "if a server message must be
  * localizable, the backend emits a code and the frontend maps it", not "translate arbitrary server
  * prose on the client".
+ *
+ * G2 closes the same gap for everything that is NOT a 409: this composable is the funnel every
+ * other failure drains into, and it used to show the backend's prose verbatim as the description —
+ * so a non-English user read English, and an internal 500's fixed `Internal server error` was the
+ * whole of what they were told. Those now resolve translated copy from the envelope's STATUS CLASS
+ * (`error.code`, the `ApiErrorCode` union) and keep the untranslated detail — the prose, a
+ * validation 400's `issues`, and the `requestId` an operator can grep — one click away behind
+ * "Show details". Two rules follow from that split: the description says what a user can act on,
+ * the disclosure carries what a user quotes to someone else; and a raw string is never the FIRST
+ * thing shown, however good it is (many of them are — the elaborate remedies this initiative
+ * added — which is exactly why the detail stays reachable rather than being dropped).
  */
 
-import type { ConflictReason } from '@cat-factory/contracts'
-import { apiErrorEnvelope } from './api/errors'
+import type { ApiErrorCode, ConflictReason } from '@cat-factory/contracts'
+import { apiErrorEnvelope, apiErrorStatus } from './api/errors'
 
 /** The parsed shape of a backend conflict (`{ error: { code: 'conflict', details } }`). */
 interface ConflictDetails {
@@ -235,6 +246,87 @@ export function parseConflict(
 /** The non-null parsed shape of a backend conflict, as returned by {@link parseConflict}. */
 type ParsedConflict = NonNullable<ReturnType<typeof parseConflict>>
 
+/**
+ * Generic translated description per STATUS CLASS, for a failure no `reason` code narrows.
+ *
+ * Exhaustive over the wire union (minus `conflict`, which structurally cannot arrive here —
+ * {@link parseConflict} intercepts every envelope carrying that code, so a mapping for it would be
+ * dead copy in ten locales), which makes the `Record` the drift guard: a new `ApiErrorCode` fails
+ * this typecheck until it has wording. The copy is deliberately about the STATUS CLASS and nothing
+ * else — it is what we can say truthfully without having read the specific failure, so it names
+ * the shape of the remedy ("sign in again", "your deployment hasn't wired this", "wait and retry")
+ * and leaves the specifics to the detail disclosure.
+ */
+const GENERIC_DESCRIPTION_KEYS: Record<Exclude<ApiErrorCode, 'conflict'>, string> = {
+  not_found: 'errors.generic.description.not_found',
+  validation: 'errors.generic.description.validation',
+  credential_required: 'errors.generic.description.credential_required',
+  forbidden: 'errors.generic.description.forbidden',
+  unavailable: 'errors.generic.description.unavailable',
+  unauthorized: 'errors.generic.description.unauthorized',
+  rate_limited: 'errors.generic.description.rate_limited',
+  internal: 'errors.generic.description.internal',
+}
+
+/**
+ * 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
+ * is on the USER's side (check the connection), which is the opposite of "the server is broken".
+ */
+const NETWORK_DESCRIPTION_KEY = 'errors.generic.description.network'
+
+/**
+ * Something answered with an HTTP status but not one of our envelopes (an edge/proxy 502 page, a
+ * gateway timeout), or answered with a `code` this build doesn't know. Reported as an unexpected
+ * SERVER-side failure rather than folded into the network case.
+ */
+const UNEXPECTED_DESCRIPTION_KEY = 'errors.generic.description.unexpected'
+
+/**
+ * A non-conflict failure, split into the part that gets TRANSLATED and the parts that stay raw.
+ * Pure (no i18n, no store) so the classification is unit-testable on its own; the composable
+ * turns it into a toast.
+ */
+export interface GenericFailure {
+  /** i18n key for the translated description shown up front. */
+  descriptionKey: string
+  /** The backend's untranslated prose, when it sent any (absent for a bare network fault). */
+  message: string | null
+  /** `path: message` entries from a request-validation 400, in wire order. */
+  issues: string[]
+  /** The envelope's correlation id, so the user can quote it at whoever reads the logs. */
+  requestId: string | null
+}
+
+/**
+ * Classify a NON-conflict failure for presentation. Never throws and never returns an empty
+ * `descriptionKey`: an error this function cannot recognise at all still gets the network or
+ * unexpected-failure wording, because a toast with no description reads as a successful action.
+ */
+export function describeGenericFailure(error: unknown): GenericFailure {
+  const envelope = apiErrorEnvelope(error)
+  // Read through a widened alias rather than casting the wire string to the union: a `code` we
+  // 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
+  // No envelope at all AND no status ⇒ nothing answered; with a status, something did.
+  const unrecognised =
+    !envelope && apiErrorStatus(error) === undefined
+      ? NETWORK_DESCRIPTION_KEY
+      : UNEXPECTED_DESCRIPTION_KEY
+  return {
+    descriptionKey: mapped ?? unrecognised,
+    // `ApiError.message` is the envelope's prose, or a synthesised `Request failed (HTTP n)`; for
+    // a non-API throw it is the JS error text. Either way it is detail, never the headline.
+    message: error instanceof Error ? error.message : error == null ? null : String(error),
+    issues: (envelope?.issues ?? []).map((issue) =>
+      issue.path ? `${issue.path}: ${issue.message}` : issue.message,
+    ),
+    requestId: typeof envelope?.requestId === 'string' ? envelope.requestId : null,
+  }
+}
+
 export function usePipelineErrorToast() {
   const toast = useToast()
   const ui = useUiStore()
@@ -448,6 +540,51 @@ export function usePipelineErrorToast() {
     })
   }
 
+  /**
+   * Everything that is NOT a 409: a translated status-class description, with the raw detail
+   * behind a "Show details" button that swaps it into the same toast (G2).
+   *
+   * The reveal is an UPDATE rather than a second toast so the two readings can't sit on screen
+   * disagreeing, and it makes the toast sticky at the same time — the detail is what someone
+   * copies into a bug report, and a ~5s auto-dismiss takes it away mid-copy. `actions: []` has to
+   * be passed explicitly: `update` merges over the existing toast, so an omitted `actions` would
+   * leave a "Show details" button that is now a no-op.
+   *
+   * No detail worth showing (a network fault with an unhelpful `message` and no correlation id)
+   * ⇒ no button at all, rather than a disclosure that reveals nothing.
+   */
+  function presentGenericFailure(error: unknown, fallbackTitleKey: string): void {
+    const failure = describeGenericFailure(error)
+    const detail = [
+      failure.message,
+      failure.issues.join(', '),
+      failure.requestId ? t('errors.generic.requestId', { id: failure.requestId }) : '',
+    ]
+      .filter((part) => part && part.trim().length > 0)
+      .join(' · ')
+    // No `te` guard: the key comes from a Record exhaustive over the wire union and every entry
+    // ships in the base `en` catalog, so a locale missing it renders English via `fallbackLocale`
+    // (better than the raw prose this replaced) and a bare key can never leak.
+    const added = toast.add({
+      title: t(fallbackTitleKey),
+      description: t(failure.descriptionKey),
+      color: 'error',
+      icon: 'i-lucide-triangle-alert',
+      ...(detail
+        ? {
+            actions: [
+              {
+                label: t('errors.generic.showDetail'),
+                icon: 'i-lucide-info',
+                onClick: () =>
+                  toast.update(added.id, { description: detail, duration: 0, actions: [] }),
+              },
+            ],
+          }
+        : {}),
+    })
+  }
+
   /**
    * Present `error` as a toast. `fallbackTitleKey` is an i18n message key used for
    * non-conflict failures and any conflict reason without a dedicated title.
@@ -459,14 +596,7 @@ export function usePipelineErrorToast() {
       presentMappedConflict(conflict, fallbackTitleKey)
       return
     }
-
-    // Not a conflict (a 4xx/5xx or a network fault) — surface its message plainly.
-    toast.add({
-      title: t(fallbackTitleKey),
-      description: error instanceof Error ? error.message : String(error),
-      color: 'error',
-      icon: 'i-lucide-triangle-alert',
-    })
+    presentGenericFailure(error, fallbackTitleKey)
   }
 
   return { present }

package/app/composables/useStepPromptVariant.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import type { PipelineStep } from '~/types/execution'
+import { useStepPromptVariant } from '~/composables/useStepPromptVariant'
+import en from '../../i18n/locales/en.json'
+
+/**
+ * What the run panels report about a step's agent-kind VARIANT.
+ *
+ * The property under test is that they report what the DISPATCH did, not what the pipeline asked
+ * for. A step can name a variant whose text never reached its prompt — the workspace's own edit of
+ * that kind displaces a variant's replacement, and a variant can be withdrawn mid-run — and a
+ * panel that echoed the selection would confirm a variation that did not run. Each losing
+ * disposition therefore gets its own note.
+ *
+ * Assertions are on KEYS, never English text, so they stay locale-agnostic (the `t` spy echoes
+ * its key) — but every key is checked against the real `en.json` so a typo can't pass.
+ */
+
+function hasKey(path: string): boolean {
+  return (
+    path.split('.').reduce<unknown>((node, seg) => {
+      return node && typeof node === 'object' ? (node as Record<string, unknown>)[seg] : undefined
+    }, en) !== undefined
+  )
+}
+
+beforeEach(() => {
+  vi.stubGlobal('useI18n', () => ({ t: (key: string) => key, te: hasKey }))
+  vi.stubGlobal('useAgentsStore', () => ({
+    variantLabel: (id: string) => (id === 'org:tdd' ? 'TDD-first' : id),
+  }))
+})
+
+function step(promptVariant?: PipelineStep['promptVariant']): PipelineStep {
+  return {
+    agentKind: 'coder',
+    state: 'done',
+    ...(promptVariant ? { promptVariant } : {}),
+  } as PipelineStep
+}
+
+describe('useStepPromptVariant', () => {
+  it('reports nothing for a step that ran the shipped prompt', () => {
+    expect(useStepPromptVariant(() => step()).value).toBeNull()
+  })
+
+  it('reports the label with NO note when the variant fully applied', () => {
+    const variant = useStepPromptVariant(() => step({ id: 'org:tdd', applied: 'full' })).value
+    expect(variant).toEqual({ label: 'TDD-first', note: null })
+  })
+
+  it('reports a note when the workspace prompt displaced the variant entirely', () => {
+    // The case that used to read as a plain confirmation the variant ran.
+    const variant = useStepPromptVariant(() => step({ id: 'org:tdd', applied: 'superseded' })).value
+    expect(variant?.label).toBe('TDD-first')
+    expect(variant?.note).toBe('panels.stepMeta.promptVariantSuperseded')
+    expect(hasKey(variant!.note!)).toBe(true)
+  })
+
+  it('distinguishes a partly-applied variant from a fully displaced one', () => {
+    const note = useStepPromptVariant(() => step({ id: 'org:tdd', applied: 'addition-only' })).value
+      ?.note
+    expect(note).toBe('panels.stepMeta.promptVariantAdditionOnly')
+    expect(hasKey(note!)).toBe(true)
+  })
+
+  it('distinguishes a WITHDRAWN variant, and still names the id it asked for', () => {
+    // The label falls back to the raw id: the step really was configured to run it, so rendering
+    // nothing would show a varied step as if it were the stock kind.
+    const variant = useStepPromptVariant(() => step({ id: 'org:gone', applied: 'withdrawn' })).value
+    expect(variant?.label).toBe('org:gone')
+    expect(variant?.note).toBe('panels.stepMeta.promptVariantWithdrawn')
+    expect(hasKey(variant!.note!)).toBe(true)
+  })
+})

package/app/composables/useStepPromptVariant.ts

@@ -0,0 +1,50 @@
+import { computed, type ComputedRef } from 'vue'
+import type { PipelineStep } from '~/types/execution'
+
+// The deployment-registered agent-kind VARIANT a step ran under, as the run panels report it.
+//
+// Read off the dispatch-time PIN (`step.promptVariant`), never off `stepOptions.agentVariantId`:
+// the option is what the pipeline ASKED for, and the two diverge whenever the workspace has also
+// edited that kind's prompt — the workspace is the narrower tier, so it displaces a variant's own
+// replacement. A panel keyed on the selection would report `Prompt variant: TDD-first` on a step
+// whose prompt contains none of that variant's text, which is worse than saying nothing: it reads
+// as confirmation. So each losing disposition gets its own note rather than being flattened into
+// the label, because they need different fixes (drop the workspace's edit / use an addition
+// instead of a replacement / re-register the variant).
+//
+// Absent before the step dispatches, exactly like `step.model` beside it: what a step RAN under is
+// not a fact until it runs.
+
+/** The dispatch-time pin a panel reads (`PipelineStep.promptVariant`), narrowed to non-null. */
+type PromptVariantPin = NonNullable<PipelineStep['promptVariant']>
+
+/** What a panel shows for a step's variant: the label, plus a note when it did not fully apply. */
+export interface StepPromptVariant {
+  /** The variant's registered label, falling back to its raw id when it is no longer registered. */
+  label: string
+  /** Why the variant's text did not (fully) reach this step's prompt; null when it did. */
+  note: string | null
+}
+
+export function useStepPromptVariant(
+  step: () => PipelineStep,
+): ComputedRef<StepPromptVariant | null> {
+  const agents = useAgentsStore()
+  const { t } = useI18n()
+  // One STATIC literal `t()` per member of the closed disposition union, not a key assembled from
+  // `applied`: the typed-message-key check and the catalog drift guard both read literal keys, and
+  // a runtime-assembled one is invisible to them. The `Record` type is the exhaustiveness half —
+  // a new disposition fails to compile until it has copy.
+  const NOTE: Record<PromptVariantPin['applied'], () => string | null> = {
+    full: () => null,
+    'addition-only': () => t('panels.stepMeta.promptVariantAdditionOnly'),
+    superseded: () => t('panels.stepMeta.promptVariantSuperseded'),
+    withdrawn: () => t('panels.stepMeta.promptVariantWithdrawn'),
+  }
+
+  return computed(() => {
+    const pin = step().promptVariant
+    if (!pin) return null
+    return { label: agents.variantLabel(pin.id), note: NOTE[pin.applied]() }
+  })
+}

package/app/stores/agents.spec.ts

@@ -101,4 +101,34 @@ describe('agents store — custom-kind catalog (slice 2)', () => {
     expect(created.category).toBeUndefined() // lands in the palette "custom" bucket
     expect(agentKindMeta(created.kind).label).toBe('My Agent')
   })
+
+  it('holds agent-kind VARIANTS apart from the palette catalog', () => {
+    // A variant is a per-step OPTION on a kind that is already in the palette, not a kind of its
+    // own — so it must never reach `archetypes` / `agentKindMeta`, or it would become placeable.
+    const agents = useAgentsStore()
+    agents.hydrateVariants([
+      { id: 'org:tdd', baseKind: 'coder', label: 'TDD-first' },
+      { id: 'org:sec', baseKind: 'pr-reviewer', label: 'Security lens' },
+    ])
+    expect(agents.variantsForKind('coder').map((v) => v.id)).toEqual(['org:tdd'])
+    expect(agents.variantsForKind('architect')).toEqual([])
+    expect(agents.archetypes.some((a) => a.kind === 'org:tdd')).toBe(false)
+    expect(isKnownAgentKind('org:tdd')).toBe(false)
+  })
+
+  it('falls back to a variant id the deployment no longer registers', () => {
+    // A step really is configured to run that variant; rendering nothing would show a varied step
+    // as if it were the stock kind.
+    const agents = useAgentsStore()
+    agents.hydrateVariants([{ id: 'org:tdd', baseKind: 'coder', label: 'TDD-first' }])
+    expect(agents.variantLabel('org:tdd')).toBe('TDD-first')
+    expect(agents.variantLabel('org:withdrawn')).toBe('org:withdrawn')
+  })
+
+  it('swaps the variant list wholesale on re-hydrate (per-workspace snapshot)', () => {
+    const agents = useAgentsStore()
+    agents.hydrateVariants([{ id: 'org:tdd', baseKind: 'coder', label: 'TDD-first' }])
+    agents.hydrateVariants([])
+    expect(agents.variantsForKind('coder')).toEqual([])
+  })
 })

package/app/stores/agents.ts

@@ -10,7 +10,7 @@ import {
   SYSTEM_AGENT_META,
   uid,
 } from '~/utils/catalog'
-import type { AgentArchetype, AgentKind, CustomAgentKind } from '~/types/domain'
+import type { AgentArchetype, AgentKind, AgentKindVariant, CustomAgentKind } from '~/types/domain'
 
 /**
  * The agent palette catalog (slice 2 of the modular-vue adoption —
@@ -39,6 +39,12 @@ export const useAgentsStore = defineStore('agents', () => {
   const capabilitiesManifest = ref<RemoteModuleManifest<AppSlots> | null>(null)
   // In-UI, client-only prototype agents created via the "add agent" modal.
   const runtimeAgents = ref<AgentArchetype[]>([])
+  // The deployment's registered agent-kind VARIANTS (alternate prompts for EXISTING kinds), from
+  // the snapshot. Deliberately NOT part of the capability manifest above: a variant is not a
+  // palette block and has no result view — it is a per-step OPTION on a kind that is already
+  // there — so folding it into the kind catalog would make it placeable, which is exactly what
+  // the backend model says it is not. A straight replace, like the skills catalog it mirrors.
+  const variants = ref<AgentKindVariant[]>([])
 
   /**
    * The merged CUSTOM catalog (consumer-slot → backend-manifest → runtime), each
@@ -134,6 +140,28 @@ export const useAgentsStore = defineStore('agents', () => {
     capabilitiesManifest.value = manifest
   }
 
+  /** Hydrate the deployment's registered agent-kind variants from the snapshot (straight replace). */
+  function hydrateVariants(list: readonly AgentKindVariant[]) {
+    variants.value = [...list]
+  }
+
+  /**
+   * The variants registered for one kind — what the pipeline builder offers as that step's
+   * alternate prompt. Empty for every kind on the stock product.
+   */
+  function variantsForKind(kind: AgentKind): AgentKindVariant[] {
+    return variants.value.filter((variant) => variant.baseKind === kind)
+  }
+
+  /**
+   * A variant's display label, or the raw id when the deployment no longer registers it. The id
+   * is the honest fallback: a step really is configured to run that variant, and rendering
+   * nothing would show a varied step as if it were the stock kind.
+   */
+  function variantLabel(id: string): string {
+    return variants.value.find((variant) => variant.id === id)?.label ?? id
+  }
+
   return {
     archetypes,
     customArchetypes,
@@ -141,5 +169,9 @@ export const useAgentsStore = defineStore('agents', () => {
     addAgent,
     registerConsumerKinds,
     hydrateCapabilities,
+    variants,
+    hydrateVariants,
+    variantsForKind,
+    variantLabel,
   }
 })

package/app/stores/pipelines/draftStepConfig.ts

@@ -6,7 +6,7 @@ import { defaultConsensusConfig, type PipelinesContext } from './context'
  * The pipeline-builder draft's PER-STEP CONFIG toggles: consensus (inline panel and the workspace
  * consensus-GROUP tier set), the human approval gate, the estimate gate on a companion step, the
  * follow-up and test-QC companions, the per-step enable flag, and the `StepOptions` bag
- * (requirements auto-recommendation, the picked skill).
+ * (requirements auto-recommendation, the picked skill, the picked agent-kind variant).
  *
  * Split out of `./draftActions`, which owns the draft's STRUCTURE (insert / remove / reorder /
  * units). Every function here reads and writes one of the parallel per-step arrays at an index and
@@ -139,6 +139,27 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
     draftStepOptions.value[index] = Object.keys(next).length ? next : null
   }
 
+  /**
+   * The agent-kind VARIANT picked for the draft step at `index` (its
+   * `stepOptions.agentVariantId`), or undefined when it runs the kind's shipped prompt.
+   */
+  function draftAgentVariantId(index: number): string | undefined {
+    return draftStepOptions.value[index]?.agentVariantId
+  }
+
+  /**
+   * Set (or clear) the picked variant on the draft step at `index`. Merges into the step's
+   * `StepOptions` bag rather than clobbering it; clearing drops the field and, if the bag
+   * empties, the whole entry — exactly like the other options here, so a step back on the
+   * shipped prompt persists nothing.
+   */
+  function setDraftAgentVariantId(index: number, agentVariantId: string | undefined) {
+    const next: StepOptions = { ...draftStepOptions.value[index] }
+    if (agentVariantId) next.agentVariantId = agentVariantId
+    else delete next.agentVariantId
+    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+  }
+
   /**
    * The output-token ceiling pinned on the draft step at `index`, or undefined when the step
    * inherits (the workspace's per-kind setting, else the deployment default).
@@ -174,6 +195,8 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
     toggleDraftAutoRecommend,
     draftSkillId,
     setDraftSkillId,
+    draftAgentVariantId,
+    setDraftAgentVariantId,
     draftMaxOutputTokens,
     setDraftMaxOutputTokens,
   }

package/app/stores/workspace/hydrate.ts

@@ -97,6 +97,9 @@ export function applySnapshotToStores(snapshot: WorkspaceSnapshot, boardSince?:
     snapshot.customTaskTypes ?? [],
   )
   useAgentsStore().hydrateCapabilities(capabilities)
+  // The deployment's registered agent-kind variants (alternate prompts for existing kinds), so
+  // the builder can offer them per step and the run views can name the one a step ran under.
+  useAgentsStore().hydrateVariants(snapshot.agentKindVariants ?? [])
   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.

package/app/types/domain.ts

@@ -62,6 +62,7 @@ export type {
   AgentCategory,
   AgentTier,
   CustomAgentKind,
+  AgentKindVariant,
   CustomTaskType,
   TaskTypePresentation,
   TaskTypeFieldDescriptor,