@cat-factory/app 0.186.0 → 0.188.0

package/app/stores/agentTier.ts

@@ -0,0 +1,42 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type { AgentTier } from '~/types/domain'
+import { DEFAULT_AGENT_TIER_LEVEL, isAgentTier } from '~/utils/agentTier'
+
+/**
+ * How deep into the agent catalog the two catalog surfaces reach — the pipeline builder's
+ * palette and the model preset's per-agent override list.
+ *
+ * ONE persisted preference shared by both, not a per-surface one: the two are halves of the
+ * same job (pick the agents a pipeline runs, then pick what each of them runs on), so a user
+ * who widened the palette to reach a specialist kind expects to find that same kind when they
+ * go to pin its model. Persisted like the interface mode's own preference, so the choice
+ * survives a reload.
+ *
+ * Distinct from `uiMode` (the SPA-wide basic/advanced interface tier) on purpose — see
+ * `utils/agentTier.ts` for why the axes stay separate.
+ */
+export const useAgentTierStore = defineStore(
+  'agentTier',
+  () => {
+    /** The selected level, persisted. Seeded to the everyday-loop default. */
+    const storedTier = ref<AgentTier>(DEFAULT_AGENT_TIER_LEVEL)
+
+    // The restored value is untrusted input (a blob written by an older build, or hand-edited),
+    // and a catalog filtered on an unknown level would show nothing at all — so fall back
+    // rather than trust it, exactly as `uiMode` does with its persisted mode.
+    const tier = computed<AgentTier>(() =>
+      isAgentTier(storedTier.value) ? storedTier.value : DEFAULT_AGENT_TIER_LEVEL,
+    )
+
+    /** Whether the widest level is selected, i.e. the whole catalog is showing. */
+    const showsAll = computed(() => tier.value === 'advanced')
+
+    function setTier(next: AgentTier) {
+      storedTier.value = next
+    }
+
+    return { tier, showsAll, storedTier, setTier }
+  },
+  { persist: { pick: ['storedTier'] } },
+)

package/app/stores/consensusGroups.ts

@@ -0,0 +1,77 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type {
+  ConsensusGroup,
+  CreateConsensusGroupInput,
+  UpdateConsensusGroupInput,
+} from '~/types/consensus'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * The workspace's consensus-GROUP library: the reusable, estimate-gated review panels a pipeline
+ * step escalates to. Hydrated from the workspace snapshot (like the model presets) and managed
+ * from the Model Configuration settings screen; the pipeline builder reads it to offer a step's
+ * tier set.
+ *
+ * A workspace that has authored no group simply has nothing to escalate to, and every consensus
+ * step runs the inline participants written on it — so an empty library is a valid, quiet state,
+ * not an error.
+ */
+export const useConsensusGroupsStore = defineStore('consensusGroups', () => {
+  const api = useApi()
+
+  const groups = ref<ConsensusGroup[]>([])
+
+  function hydrate(list: ConsensusGroup[]) {
+    groups.value = [...list].sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  /** Whether the workspace has any tier to escalate to (drives the builder's empty state). */
+  const hasGroups = computed(() => groups.value.length > 0)
+
+  /** Resolve ids to groups, dropping any the library no longer holds. */
+  function resolve(ids: readonly string[] | undefined): ConsensusGroup[] {
+    if (!ids?.length) return []
+    return ids
+      .map((id) => groups.value.find((g) => g.id === id))
+      .filter((g): g is ConsensusGroup => !!g)
+  }
+
+  /**
+   * The estimate bar a group sets, as a display number: the highest threshold it names, or null
+   * when it is ungated (the unconditional floor tier). Mirrors kernel's `consensusGroupBar`,
+   * which returns -1 for the same case — the sentinel exists so an ungated group SORTS below
+   * every gated one, which is a ranking concern the UI doesn't share.
+   */
+  function barFor(group: ConsensusGroup): number | null {
+    if (!group.gating.enabled) return null
+    const thresholds = [
+      group.gating.minComplexity,
+      group.gating.minRisk,
+      group.gating.minImpact,
+    ].filter((t): t is number => t !== undefined)
+    return thresholds.length ? Math.max(...thresholds) : null
+  }
+
+  async function create(input: CreateConsensusGroupInput) {
+    const ws = useWorkspaceStore()
+    const created = await api.createConsensusGroup(ws.requireId(), input)
+    await ws.refresh()
+    return created
+  }
+
+  async function update(groupId: string, patch: UpdateConsensusGroupInput) {
+    const ws = useWorkspaceStore()
+    const updated = await api.updateConsensusGroup(ws.requireId(), groupId, patch)
+    await ws.refresh()
+    return updated
+  }
+
+  async function remove(groupId: string) {
+    const ws = useWorkspaceStore()
+    await api.deleteConsensusGroup(ws.requireId(), groupId)
+    await ws.refresh()
+  }
+
+  return { groups, hasGroups, hydrate, resolve, barFor, create, update, remove }
+})

package/app/stores/pipelines/draftActions.ts

@@ -1,15 +1,18 @@
 import { computed } from 'vue'
 import type { AgentKind, Pipeline } from '~/types/domain'
-import type { ConsensusStepConfig } from '~/types/consensus'
-import type { StepOptions } from '@cat-factory/contracts'
 import { companionForProducer } from '~/utils/catalog'
-import { defaultConsensusConfig, type PipelinesContext } from './context'
+import type { PipelinesContext } from './context'
+import { createPipelineStepConfigActions } from './draftStepConfig'
 
 /**
- * The pipeline-builder draft manipulation: inserting/removing/reordering steps and toggling each
- * step's per-step config, plus `clearDraft` / `loadForEdit`. Extracted from the store setup into a
- * factory closing over the shared {@link PipelinesContext} so behaviour is byte-identical to the
- * former in-closure functions — the split is purely to keep the setup within the size budget.
+ * The pipeline-builder draft's STRUCTURE: inserting/removing/reordering steps, the companion
+ * folding that turns the flat arrays into renderable units, and `clearDraft` / `loadForEdit`.
+ * Extracted from the store setup into a factory closing over the shared {@link PipelinesContext}.
+ *
+ * The per-step CONFIG toggles (consensus + its group tiers, gates, companions, step options) are
+ * the sibling factory in `./draftStepConfig` — a different concern on the same context, and the
+ * seam this file was split along when it outgrew the per-function budget. Both are spread into
+ * the store, so callers see one flat API exactly as before.
  */
 export function createPipelineDraftActions(ctx: PipelinesContext) {
   const {
@@ -97,13 +100,6 @@ export function createPipelineDraftActions(ctx: PipelinesContext) {
     else insertAt(index + 1, companion)
   }
 
-  /** Toggle estimate gating on/off for the (companion) step at `index`. */
-  function toggleDraftGating(index: number) {
-    draftGating.value[index] = draftGating.value[index]?.enabled
-      ? null
-      : { enabled: true, minRisk: 0.5, minImpact: 0.5, onMissingEstimate: 'run' }
-  }
-
   /**
    * The draft as a list of "units" for rendering: each step is one unit, EXCEPT a companion
    * that sits immediately after its producer — that companion is folded into the producer's
@@ -157,93 +153,6 @@ export function createPipelineDraftActions(ctx: PipelinesContext) {
     draftStepOptions.value = reorder(draftStepOptions.value)
   }
 
-  /** Toggle the consensus mechanism on the draft step at `index` (default config / off). */
-  function toggleDraftConsensus(index: number) {
-    draftConsensus.value[index] = draftConsensus.value[index] ? null : defaultConsensusConfig()
-  }
-
-  /** Replace the consensus config of the draft step at `index` (builder editor edits). */
-  function setDraftConsensus(index: number, config: ConsensusStepConfig | null) {
-    draftConsensus.value[index] = config
-  }
-
-  /** Toggle the approval gate on the draft step at `index`. */
-  function toggleDraftGate(index: number) {
-    draftGates.value[index] = !draftGates.value[index]
-  }
-
-  /** Toggle the Follow-up companion on the draft (coder) step at `index` (default on → off). */
-  function toggleDraftFollowUps(index: number) {
-    // Default (null/true) is enabled, so the first toggle disables it (false); toggle back to null.
-    draftFollowUps.value[index] = draftFollowUps.value[index] === false ? null : false
-  }
-
-  /**
-   * Toggle the test quality-control companion on the draft (Tester) step at `index`. The
-   * companion is enabled by default (a `null` entry), so the first toggle disables it
-   * (`{ enabled: false }`, dropping any gating) and the next restores the default.
-   */
-  function toggleDraftTesterQuality(index: number) {
-    draftTesterQuality.value[index] =
-      draftTesterQuality.value[index]?.enabled === false ? null : { enabled: false }
-  }
-
-  /**
-   * Toggle estimate gating on/off for the QC companion on the draft (Tester) step at `index`.
-   * A no-op while the companion is disabled (nothing to gate). Enabling gating pins the config
-   * to `{ enabled: true, gating }` so the thresholds are editable; disabling drops back to the
-   * default `null` (enabled, ungated).
-   */
-  function toggleDraftTesterQualityGating(index: number) {
-    const cur = draftTesterQuality.value[index]
-    if (cur?.enabled === false) return
-    draftTesterQuality.value[index] = cur?.gating?.enabled
-      ? null
-      : {
-          enabled: true,
-          gating: { enabled: true, minRisk: 0.5, minImpact: 0.5, onMissingEstimate: 'run' },
-        }
-  }
-
-  /** Enable/disable the draft step at `index` without removing it. */
-  function toggleDraftEnabled(index: number) {
-    draftEnabled.value[index] = draftEnabled.value[index] === false
-  }
-
-  /** Whether auto-recommendation is on for the draft (requirements-review) step at `index`. */
-  function draftAutoRecommendEnabled(index: number): boolean {
-    return draftStepOptions.value[index]?.autoRecommend !== false
-  }
-
-  /**
-   * Toggle the requirements-review auto-recommendation on the draft step at `index`. It is on by
-   * default, so we store ONLY the opt-out (`{ autoRecommend: false }`); toggling back drops the
-   * flag. Merges with any other future StepOptions fields rather than clobbering the whole bag.
-   */
-  function toggleDraftAutoRecommend(index: number) {
-    const next: StepOptions = { ...draftStepOptions.value[index] }
-    if (draftAutoRecommendEnabled(index)) next.autoRecommend = false
-    else delete next.autoRecommend
-    draftStepOptions.value[index] = Object.keys(next).length ? next : null
-  }
-
-  /** The skill picked for the draft `skill` step at `index` (its `stepOptions.skillId`). */
-  function draftSkillId(index: number): string | undefined {
-    return draftStepOptions.value[index]?.skillId
-  }
-
-  /**
-   * Set (or clear) the picked skill on the draft `skill` 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 (so it normalizes away like the other options).
-   */
-  function setDraftSkillId(index: number, skillId: string | undefined) {
-    const next: StepOptions = { ...draftStepOptions.value[index] }
-    if (skillId) next.skillId = skillId
-    else delete next.skillId
-    draftStepOptions.value[index] = Object.keys(next).length ? next : null
-  }
-
   function clearDraft() {
     draft.value = []
     draftGates.value = []
@@ -282,25 +191,14 @@ export function createPipelineDraftActions(ctx: PipelinesContext) {
   }
 
   return {
+    ...createPipelineStepConfigActions(ctx),
     addToDraft,
     removeFromDraft,
     moveInDraft,
     hasCompanion,
     toggleCompanion,
-    toggleDraftGating,
     units,
     moveUnit,
-    toggleDraftConsensus,
-    setDraftConsensus,
-    toggleDraftGate,
-    toggleDraftFollowUps,
-    toggleDraftTesterQuality,
-    toggleDraftTesterQualityGating,
-    toggleDraftEnabled,
-    draftAutoRecommendEnabled,
-    toggleDraftAutoRecommend,
-    draftSkillId,
-    setDraftSkillId,
     clearDraft,
     loadForEdit,
   }

package/app/stores/pipelines/draftStepConfig.ts

@@ -0,0 +1,157 @@
+import type { StepOptions } from '@cat-factory/contracts'
+import type { ConsensusStepConfig } from '~/types/consensus'
+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).
+ *
+ * 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
+ * touches nothing else, which is what makes the two independent; both are spread into the store,
+ * so the store's API is unchanged.
+ */
+export function createPipelineStepConfigActions(ctx: PipelinesContext) {
+  const {
+    draftGates,
+    draftEnabled,
+    draftConsensus,
+    draftGating,
+    draftFollowUps,
+    draftTesterQuality,
+    draftStepOptions,
+  } = ctx
+
+  /** Toggle estimate gating on/off for the (companion) step at `index`. */
+  function toggleDraftGating(index: number) {
+    draftGating.value[index] = draftGating.value[index]?.enabled
+      ? null
+      : { enabled: true, minRisk: 0.5, minImpact: 0.5, onMissingEstimate: 'run' }
+  }
+
+  /** Toggle the consensus mechanism on the draft step at `index` (default config / off). */
+  function toggleDraftConsensus(index: number) {
+    draftConsensus.value[index] = draftConsensus.value[index] ? null : defaultConsensusConfig()
+  }
+
+  /** Replace the consensus config of the draft step at `index` (builder editor edits). */
+  function setDraftConsensus(index: number, config: ConsensusStepConfig | null) {
+    draftConsensus.value[index] = config
+  }
+
+  /**
+   * Add/remove a workspace consensus GROUP from the draft step's tier set. The array is a SET,
+   * not a precedence list — the engine ranks candidates by the bar each group sets — so this
+   * appends without ceremony.
+   *
+   * An empty tier set falls back to the step's inline participants; a non-empty one takes over,
+   * which is why the builder shows only one of the two editors at a time.
+   */
+  function toggleDraftConsensusGroup(index: number, groupId: string) {
+    const config = draftConsensus.value[index]
+    if (!config) return
+    const current = config.groupIds ?? []
+    const next = current.includes(groupId)
+      ? current.filter((id) => id !== groupId)
+      : [...current, groupId]
+    // Drop the key entirely when the set empties, so a step that never used tiers persists the
+    // same shape it always did rather than an empty array that reads as "tiered, but none".
+    if (next.length) config.groupIds = next
+    else delete config.groupIds
+  }
+
+  /** Toggle the approval gate on the draft step at `index`. */
+  function toggleDraftGate(index: number) {
+    draftGates.value[index] = !draftGates.value[index]
+  }
+
+  /** Toggle the Follow-up companion on the draft (coder) step at `index` (default on → off). */
+  function toggleDraftFollowUps(index: number) {
+    // Default (null/true) is enabled, so the first toggle disables it (false); toggle back to null.
+    draftFollowUps.value[index] = draftFollowUps.value[index] === false ? null : false
+  }
+
+  /**
+   * Toggle the test quality-control companion on the draft (Tester) step at `index`. The
+   * companion is enabled by default (a `null` entry), so the first toggle disables it
+   * (`{ enabled: false }`, dropping any gating) and the next restores the default.
+   */
+  function toggleDraftTesterQuality(index: number) {
+    draftTesterQuality.value[index] =
+      draftTesterQuality.value[index]?.enabled === false ? null : { enabled: false }
+  }
+
+  /**
+   * Toggle estimate gating on/off for the QC companion on the draft (Tester) step at `index`.
+   * A no-op while the companion is disabled (nothing to gate). Enabling gating pins the config
+   * to `{ enabled: true, gating }` so the thresholds are editable; disabling drops back to the
+   * default `null` (enabled, ungated).
+   */
+  function toggleDraftTesterQualityGating(index: number) {
+    const cur = draftTesterQuality.value[index]
+    if (cur?.enabled === false) return
+    draftTesterQuality.value[index] = cur?.gating?.enabled
+      ? null
+      : {
+          enabled: true,
+          gating: { enabled: true, minRisk: 0.5, minImpact: 0.5, onMissingEstimate: 'run' },
+        }
+  }
+
+  /** Enable/disable the draft step at `index` without removing it. */
+  function toggleDraftEnabled(index: number) {
+    draftEnabled.value[index] = draftEnabled.value[index] === false
+  }
+
+  /** Whether auto-recommendation is on for the draft (requirements-review) step at `index`. */
+  function draftAutoRecommendEnabled(index: number): boolean {
+    return draftStepOptions.value[index]?.autoRecommend !== false
+  }
+
+  /**
+   * Toggle the requirements-review auto-recommendation on the draft step at `index`. It is on by
+   * default, so we store ONLY the opt-out (`{ autoRecommend: false }`); toggling back drops the
+   * flag. Merges with any other future StepOptions fields rather than clobbering the whole bag.
+   */
+  function toggleDraftAutoRecommend(index: number) {
+    const next: StepOptions = { ...draftStepOptions.value[index] }
+    if (draftAutoRecommendEnabled(index)) next.autoRecommend = false
+    else delete next.autoRecommend
+    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+  }
+
+  /** The skill picked for the draft `skill` step at `index` (its `stepOptions.skillId`). */
+  function draftSkillId(index: number): string | undefined {
+    return draftStepOptions.value[index]?.skillId
+  }
+
+  /**
+   * Set (or clear) the picked skill on the draft `skill` 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 (so it normalizes away like the other options).
+   */
+  function setDraftSkillId(index: number, skillId: string | undefined) {
+    const next: StepOptions = { ...draftStepOptions.value[index] }
+    if (skillId) next.skillId = skillId
+    else delete next.skillId
+    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+  }
+
+  return {
+    toggleDraftGating,
+    toggleDraftConsensus,
+    setDraftConsensus,
+    toggleDraftConsensusGroup,
+    toggleDraftGate,
+    toggleDraftFollowUps,
+    toggleDraftTesterQuality,
+    toggleDraftTesterQualityGating,
+    toggleDraftEnabled,
+    draftAutoRecommendEnabled,
+    toggleDraftAutoRecommend,
+    draftSkillId,
+    setDraftSkillId,
+  }
+}

package/app/stores/workspace/hydrate.ts

@@ -12,6 +12,7 @@ import { useFragmentsStore } from '~/stores/fragments'
 import { useGitHubStore } from '~/stores/github'
 import { useInitiativesStore } from '~/stores/initiative'
 import { useModelPresetsStore } from '~/stores/modelPresets'
+import { useConsensusGroupsStore } from '~/stores/consensusGroups'
 import { useNotificationsStore } from '~/stores/notifications'
 import { usePipelinesStore } from '~/stores/pipelines'
 import { useProviderConnectionsStore } from '~/stores/providerConnections'
@@ -72,6 +73,7 @@ export function applySnapshotToStores(snapshot: WorkspaceSnapshot, boardSince?:
   useWorkspaceSettingsStore().hydrate(snapshot.settings)
   useAgentConfigStore().hydrate(snapshot.agentConfigCatalog ?? [])
   useModelPresetsStore().hydrate(snapshot.modelPresets ?? [], snapshot.modelPresetCatalogVersions)
+  useConsensusGroupsStore().hydrate(snapshot.consensusGroups ?? [])
   useServiceFragmentDefaultsStore().hydrate(snapshot.serviceFragmentDefaults?.fragmentIds)
   useRecurringPipelinesStore().hydrate(snapshot.recurringPipelines ?? [])
   useInitiativesStore().hydrate(snapshot.initiatives)

package/app/types/consensus.ts

@@ -15,4 +15,7 @@ export type {
   ConsensusRound,
   ConsensusSessionStatus,
   ConsensusSession,
+  ConsensusGroup,
+  CreateConsensusGroupInput,
+  UpdateConsensusGroupInput,
 } from '@cat-factory/contracts'

package/app/types/domain.ts

@@ -60,6 +60,7 @@ export type {
   TestScreenshot,
   AgentKind,
   AgentCategory,
+  AgentTier,
   CustomAgentKind,
   CustomTaskType,
   TaskTypePresentation,
@@ -96,7 +97,7 @@ export type {
   PreviewStatus,
 } from '@cat-factory/contracts'
 
-import type { AgentCategory, AgentKind } from '@cat-factory/contracts'
+import type { AgentCategory, AgentKind, AgentTier } from '@cat-factory/contracts'
 
 // The document-kind list + the per-kind field descriptors are runtime values (used to render
 // the picker and the conditional per-kind inputs), so they are re-exported as values — the
@@ -114,6 +115,12 @@ export interface AgentArchetype {
   description: string
   /** Palette category this archetype is grouped under. Absent ⇒ ungrouped/system kind. */
   category?: AgentCategory
+  /**
+   * How specialist this kind is — the tier the palette / model-preset override list filter on
+   * (`basic` shows only basic kinds, `intermediate` adds those, `advanced` shows everything).
+   * Absent ⇒ `DEFAULT_AGENT_TIER`, which is how an unclassified deployment kind behaves.
+   */
+  tier?: AgentTier
   /**
    * Optional id of a DEDICATED result window this agent's step opens instead of the
    * generic prose step-detail panel. Resolved through the modular `resultViews` slot

package/app/utils/agentTier.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import type { AgentArchetype } from '~/types/domain'
+import { filterByAgentTier, filterByAgentTierKeeping, isAgentTier } from '~/utils/agentTier'
+
+const archetype = (kind: string, tier?: AgentArchetype['tier']): AgentArchetype => ({
+  kind: kind as AgentArchetype['kind'],
+  label: kind,
+  icon: 'i-lucide-bot',
+  color: '#fff',
+  description: kind,
+  ...(tier ? { tier } : {}),
+})
+
+const CATALOG: AgentArchetype[] = [
+  archetype('coder', 'basic'),
+  archetype('researcher', 'intermediate'),
+  archetype('mocker', 'advanced'),
+  // A deployment-registered kind that declared no tier.
+  archetype('acme-auditor'),
+]
+
+describe('filterByAgentTier', () => {
+  it('shows only the basic kinds at the default level', () => {
+    expect(filterByAgentTier(CATALOG, 'basic').map((a) => a.kind)).toEqual(['coder'])
+  })
+
+  it('accumulates the levels, with advanced showing the whole catalog', () => {
+    expect(filterByAgentTier(CATALOG, 'intermediate').map((a) => a.kind)).toEqual([
+      'coder',
+      'researcher',
+      // An undeclared tier defaults to intermediate, so it appears here.
+      'acme-auditor',
+    ])
+    expect(filterByAgentTier(CATALOG, 'advanced')).toHaveLength(CATALOG.length)
+  })
+})
+
+describe('filterByAgentTierKeeping', () => {
+  it('keeps a pinned kind the tier would otherwise hide, in catalog order', () => {
+    const kept = filterByAgentTierKeeping(CATALOG, 'basic', (a) => a.kind === 'mocker')
+    expect(kept.map((a) => a.kind)).toEqual(['coder', 'mocker'])
+  })
+
+  it('does not duplicate a pinned kind the tier already shows', () => {
+    const kept = filterByAgentTierKeeping(CATALOG, 'advanced', () => true)
+    expect(kept.map((a) => a.kind)).toEqual(CATALOG.map((a) => a.kind))
+  })
+})
+
+describe('isAgentTier', () => {
+  it('accepts the known tiers and rejects anything else', () => {
+    expect(isAgentTier('basic')).toBe(true)
+    expect(isAgentTier('advanced')).toBe(true)
+    // A persisted blob from an older build, or a hand-edited one.
+    expect(isAgentTier('expert')).toBe(false)
+    expect(isAgentTier(undefined)).toBe(false)
+    expect(isAgentTier(2)).toBe(false)
+  })
+})

package/app/utils/agentTier.ts

@@ -0,0 +1,49 @@
+import { AGENT_TIERS, agentTierVisibleAt, type AgentTier } from '@cat-factory/contracts'
+import type { AgentArchetype } from '~/types/domain'
+
+/**
+ * Agent-tier filtering for the two catalog surfaces — the pipeline builder's palette and the
+ * model preset's per-agent override list.
+ *
+ * The tier vocabulary, the default and the cumulative predicate live in `@cat-factory/contracts`
+ * (beside `purposeAllowsAgentCategory`) so a deployment-registered kind's declared tier and the
+ * SPA's own built-ins are read by ONE rule. This module holds only the frontend-shaped helpers
+ * built on it.
+ *
+ * Deliberately NOT the interface mode (`utils/uiMode.ts`). That tier says which SURFACES the
+ * whole SPA offers; this one says how deep into the agent catalog a given surface reaches. They
+ * are independent axes — an advanced-mode user still starts on the basic agent tier — and the
+ * control for this one is visible in both interface modes, since it is the only way to reach
+ * the kinds it hides.
+ */
+
+/** The default agent tier a surface opens on: the everyday delivery loop, nothing else. */
+export const DEFAULT_AGENT_TIER_LEVEL: AgentTier = 'basic'
+
+/** Whether an untrusted (persisted / hand-edited) value is one of the known tiers. */
+export function isAgentTier(value: unknown): value is AgentTier {
+  return typeof value === 'string' && (AGENT_TIERS as readonly string[]).includes(value)
+}
+
+/** Keep only the archetypes visible at `level` (cumulative — see `agentTierVisibleAt`). */
+export function filterByAgentTier<T extends Pick<AgentArchetype, 'tier'>>(
+  archetypes: readonly T[],
+  level: AgentTier,
+): T[] {
+  return archetypes.filter((a) => agentTierVisibleAt(a.tier, level))
+}
+
+/**
+ * Keep the archetypes visible at `level`, PLUS any the caller marks as pinned — the model
+ * preset editor's kinds that already carry an override. An entity can hold a setting written
+ * by a teammate, by the API, or by this user at a wider tier; hiding the row would leave them
+ * unable to see or clear it, which is the same failure the interface mode's `showOverrideField`
+ * exists to prevent. Order follows the input, so a pinned kind stays where the catalog puts it.
+ */
+export function filterByAgentTierKeeping<T extends Pick<AgentArchetype, 'tier' | 'kind'>>(
+  archetypes: readonly T[],
+  level: AgentTier,
+  isPinned: (archetype: T) => boolean,
+): T[] {
+  return archetypes.filter((a) => agentTierVisibleAt(a.tier, level) || isPinned(a))
+}

package/app/utils/catalog.spec.ts

@@ -67,6 +67,18 @@ describe('catalog', () => {
     }
   })
 
+  it('classifies every built-in kind into a tier', () => {
+    // The palette / model-preset surfaces open on `basic`, so a built-in that forgot its tier
+    // would silently fall to the DEFAULT (intermediate) and vanish from the default view for
+    // no stated reason. Only a deployment-registered kind may leave it to the default.
+    for (const a of [...AGENT_ARCHETYPES, ...Object.values(SYSTEM_AGENT_META)]) {
+      expect(a.tier, `${a.kind} declares no tier`).toBeDefined()
+    }
+    // And the everyday delivery loop has to be assemblable without touching the control.
+    const basic = AGENT_ARCHETYPES.filter((a) => a.tier === 'basic').map((a) => a.kind)
+    expect(basic).toEqual(expect.arrayContaining(['architect', 'coder', 'tester-api']))
+  })
+
   it('resolves usable metadata for every kind via agentKindMeta', () => {
     // Palette archetypes resolve to their own entry.
     for (const a of AGENT_ARCHETYPES) {