@cat-factory/app 0.133.0 → 0.135.0

package/app/stores/agents.ts

@@ -1,21 +1,96 @@
 import { defineStore } from 'pinia'
-import { ref } from 'vue'
-import { AGENT_ARCHETYPES, AGENT_BY_KIND, uid } from '~/utils/catalog'
+import { computed, ref, watch } from 'vue'
+import type { RemoteModuleManifest } from '@modular-vue/core'
+import { buildAgentCapabilitiesManifest, customKindToArchetype } from '~/modular/agent-kinds'
+import type { AppSlots } from '~/modular/slots'
+import {
+  AGENT_ARCHETYPES,
+  AGENT_BY_KIND,
+  setCustomAgentKindMeta,
+  SYSTEM_AGENT_META,
+  uid,
+} from '~/utils/catalog'
 import type { AgentArchetype, AgentKind, CustomAgentKind } from '~/types/domain'
 
 /**
- * The agent palette. Seeded from the static catalog, but custom agents can be
- * added at runtime (they show up in the pipeline builder). Newly created agents
- * are also registered into AGENT_BY_KIND so the many components that look an
- * agent up by kind keep rendering it correctly.
+ * The agent palette catalog (slice 2 of the modular-vue adoption —
+ * docs/initiatives/modular-vue-adoption.md).
+ *
+ * Reactive union of three sources, none of which mutates the frozen built-in
+ * {@link AGENT_BY_KIND} const any more:
+ *  - the built-in archetypes (static);
+ *  - CONSUMER-shipped kinds contributed as CODE via the modular `agentKinds`
+ *    slot (`registerConsumerKinds`, fed once at boot from the resolved manifest);
+ *  - the deployment's BACKEND-registered kinds, modeled as a single
+ *    {@link RemoteModuleManifest} swapped per workspace snapshot
+ *    (`hydrateCustomKinds`) and read directly (single-active-manifest shape).
+ *
+ * The merged custom catalog is projected back into `catalog.ts`'s
+ * {@link setCustomAgentKindMeta} read-model so the pure `agentKindMeta` /
+ * `isKnownAgentKind` lookups (used across ~17 renderers) resolve a custom kind
+ * reactively without importing this store.
  */
 export const useAgentsStore = defineStore('agents', () => {
-  const archetypes = ref<AgentArchetype[]>([...AGENT_ARCHETYPES])
+  // CODE-shipped consumer kinds from the static `agentKinds` slot (fed once at
+  // boot by the modular install plugin — module slots are resolved once).
+  const consumerKinds = ref<CustomAgentKind[]>([])
+  // The active per-workspace capability manifest built from the snapshot's
+  // `customAgentKinds`, or null before the first hydrate.
+  const capabilitiesManifest = ref<RemoteModuleManifest<AppSlots> | null>(null)
+  // In-UI, client-only prototype agents created via the "add agent" modal.
+  const runtimeAgents = ref<AgentArchetype[]>([])
 
-  function get(kind: AgentKind) {
-    return AGENT_BY_KIND[kind]
+  /**
+   * The merged CUSTOM catalog (consumer-slot → backend-manifest → runtime), each
+   * mapped to display metadata, de-duplicated, and never shadowing a built-in or
+   * system kind. The old `registerCustomKinds` only guarded `AGENT_BY_KIND`; this
+   * intentionally ALSO drops any custom kind colliding with a `SYSTEM_AGENT_META`
+   * kind (`ci` / `merger` / `blueprints` / gates …), so a snapshot can't override an
+   * engine kind's palette entry either — matching `agentKindMeta`'s precedence
+   * (built-in → system → custom), where a colliding custom kind would never win anyway.
+   */
+  const customArchetypes = computed<AgentArchetype[]>(() => {
+    const seen = new Set<string>()
+    const out: AgentArchetype[] = []
+    const add = (a: AgentArchetype) => {
+      if (a.kind in AGENT_BY_KIND || a.kind in SYSTEM_AGENT_META || seen.has(a.kind)) return
+      seen.add(a.kind)
+      out.push(a)
+    }
+    for (const k of consumerKinds.value) add(customKindToArchetype(k))
+    for (const k of capabilitiesManifest.value?.slots?.agentKinds ?? [])
+      add(customKindToArchetype(k))
+    for (const a of runtimeAgents.value) add(a)
+    return out
+  })
+
+  /** The full palette: built-in archetypes + the merged custom ones. */
+  const archetypes = computed<AgentArchetype[]>(() => [
+    ...AGENT_ARCHETYPES,
+    ...customArchetypes.value,
+  ])
+
+  // Known-kind lookup (built-in ∪ system ∪ custom) for `get`.
+  const customByKind = computed<Record<string, AgentArchetype>>(() =>
+    Object.fromEntries(customArchetypes.value.map((a) => [a.kind, a])),
+  )
+
+  // Keep `catalog.ts`'s pure-util projection in sync with the merged custom
+  // catalog so `agentKindMeta` / `isKnownAgentKind` resolve custom kinds. Sync
+  // flush so an imperative read right after `hydrateCustomKinds` (e.g. the run
+  // dispatch resolving a custom kind's `resultView`) sees the fresh catalog with
+  // no tick gap. The watch lives in the store's effect scope (disposed with it).
+  watch(customByKind, (map) => setCustomAgentKindMeta(map), { immediate: true, flush: 'sync' })
+
+  /** Display metadata for a KNOWN kind (built-in / system / custom), else undefined. */
+  function get(kind: AgentKind): AgentArchetype | undefined {
+    return AGENT_BY_KIND[kind] ?? SYSTEM_AGENT_META[kind] ?? customByKind.value[kind]
   }
 
+  /**
+   * Add an in-UI prototype agent (the pipeline builder's "add agent" modal).
+   * Client-only, so it lives in store state — no backend, no global mutation.
+   */
   function addAgent(input: {
     label: string
     description?: string
@@ -30,36 +105,42 @@ export const useAgentsStore = defineStore('agents', () => {
       icon: input.icon || 'i-lucide-sparkles',
       color: input.color || '#22d3ee',
     }
-    // register for kind-based lookups across the app, then surface in the palette
-    AGENT_BY_KIND[archetype.kind] = archetype
-    archetypes.value.push(archetype)
+    runtimeAgents.value = [...runtimeAgents.value, archetype]
     return archetype
   }
 
   /**
-   * Merge the deployment's registered CUSTOM agent kinds (from the workspace snapshot)
-   * into the palette catalog: each becomes a first-class palette block + a kind-based
-   * lookup (so timelines / inspectors render it instead of the generic fallback), and its
-   * declared `resultView` opens through the same registry the built-ins use. Idempotent
-   * and built-in-safe — a kind already known (a built-in, or a prior load) is left
-   * untouched, so a snapshot can't shadow a built-in or duplicate on reload.
+   * Register the deployment's CODE-shipped consumer agent kinds — the resolved
+   * modular `agentKinds` slot, fed once by the install plugin. Idempotent
+   * replace (module slots resolve once, so this is called a single time).
    */
-  function registerCustomKinds(kinds: CustomAgentKind[]) {
-    for (const { kind, presentation } of kinds) {
-      if (AGENT_BY_KIND[kind]) continue
-      const archetype: AgentArchetype = {
-        kind,
-        label: presentation.label,
-        icon: presentation.icon,
-        color: presentation.color,
-        description: presentation.description,
-        ...(presentation.category ? { category: presentation.category } : {}),
-        ...(presentation.resultView ? { resultView: presentation.resultView } : {}),
-      }
-      AGENT_BY_KIND[kind] = archetype
-      archetypes.value.push(archetype)
-    }
+  function registerConsumerKinds(kinds: readonly CustomAgentKind[]) {
+    consumerKinds.value = [...kinds]
   }
 
-  return { archetypes, get, addAgent, registerCustomKinds }
+  /**
+   * Hydrate the deployment's BACKEND-registered custom kinds from a workspace
+   * snapshot, modeled as a single remote capability manifest (swapped wholesale
+   * per workspace). Replaces the old `registerCustomKinds` that mutated
+   * {@link AGENT_BY_KIND} directly.
+   *
+   * The snapshot re-delivers the same deployment kinds on every board refresh, so
+   * skip the swap — and the downstream projection invalidation of every
+   * `agentKindMeta` consumer — when the content-derived manifest version is
+   * unchanged. A genuinely different workspace's kinds change the version and swap.
+   */
+  function hydrateCustomKinds(kinds: CustomAgentKind[]) {
+    const next = buildAgentCapabilitiesManifest(kinds)
+    if (capabilitiesManifest.value?.version === next.version) return
+    capabilitiesManifest.value = next
+  }
+
+  return {
+    archetypes,
+    customArchetypes,
+    get,
+    addAgent,
+    registerConsumerKinds,
+    hydrateCustomKinds,
+  }
 })

package/app/stores/environmentWizard.ts

@@ -23,7 +23,7 @@ import { usePreflightsStore } from '~/stores/preflights'
 import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
 
-// The environment setup wizard's cross-step state + actions (shared-stacks slice 7). It walks the
+// The environment setup wizard's cross-step DATA + actions (shared-stacks slice 7). It backs the
 // guided flow — pick a service frame → review the recommended `docker-compose` recipe (detector
 // facts + the opt-in analyst draft, merged with provenance) → run the machine preflights → save
 // (persist the recipe on the frame AND register the workspace's docker-compose handler so the
@@ -31,17 +31,19 @@ import { useWorkspaceStore } from '~/stores/workspace'
 //
 // The detector + analyst only RECOMMEND; the human confirms/edits the working `recipe` here and the
 // compose provider keys purely on the saved recipe (the build-flag rule). Mirrors the other infra
-// stores' idiom; the flow state is a singleton so the wizard modal + its step children share it.
+// stores' idiom; the flow state is a singleton so the wizard's step children share it.
+//
+// Since slice 3 of the modular-vue adoption (docs/initiatives/modular-vue-adoption.md) the wizard's
+// step NAVIGATION lives in a modular-vue journey (`app/modular/journeys/environmentSetup.ts`), NOT
+// here — this store no longer holds a `step` / `STEP_ORDER` / `goToStep`. It is purely the per-frame
+// data+action layer the journey's step components drive; `beginForFrame` seeds it when a step first
+// targets a frame.
 
 /** The seeded analyst-only pipeline the "run deep analysis" trigger starts against the frame. */
 const ANALYSIS_PIPELINE_ID = 'pl_environment_analysis'
 /** The analyst agent kind whose `result.custom` carries the drafted recipe. */
 const ANALYST_AGENT_KIND = 'environment-analyst'
 
-/** The wizard's ordered steps. `trial` is an optional post-save action, not a gate. */
-export type EnvWizardStep = 'pick' | 'review' | 'preflight' | 'save'
-export const ENV_WIZARD_STEPS: EnvWizardStep[] = ['pick', 'review', 'preflight', 'save']
-
 /** The analyst run's lifecycle as the wizard surfaces it. */
 export type AnalysisStatus = 'idle' | 'running' | 'ready' | 'failed'
 
@@ -70,9 +72,11 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
   const pipelines = usePipelinesStore()
   const preflights = usePreflightsStore()
 
-  // ---- Flow position ------------------------------------------------------
+  // ---- Target frame -------------------------------------------------------
+  // The frame the flow currently targets. Set by `beginForFrame` when a journey
+  // step first mounts against a frame; the journey (not this store) owns which
+  // step is showing.
   const frameId = ref<string | null>(null)
-  const step = ref<EnvWizardStep>('pick')
 
   // ---- Detection ----------------------------------------------------------
   const detecting = ref(false)
@@ -212,19 +216,18 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
     trialStarted.value = false
   }
 
-  /** Reset the flow for a (possibly preselected) frame. */
-  function open(preselectFrameId: string | null) {
-    frameId.value = preselectFrameId
-    step.value = preselectFrameId ? 'review' : 'pick'
-    resetFlowState()
-    if (preselectFrameId) void detect()
-  }
-
-  function selectFrame(id: string) {
+  /**
+   * Seed the data layer for a frame the journey's review step is entering. The
+   * journey owns navigation, so this is idempotent by frame: it (re)seeds +
+   * detects only when the target frame actually changes, so back-navigating to
+   * the review step (or a resume) does NOT clobber the operator's in-progress
+   * recipe edits. Selecting a different frame resets the flow for it.
+   */
+  function beginForFrame(id: string | null) {
+    if (frameId.value === id) return
     frameId.value = id
     resetFlowState()
-    step.value = 'review'
-    void detect()
+    if (id) void detect()
   }
 
   /** Re-seed the working recipe from the current merge (detector-only, or +analyst after apply). */
@@ -435,14 +438,9 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
     }
   }
 
-  function goToStep(next: EnvWizardStep) {
-    step.value = next
-  }
-
   return {
     // state
     frameId,
-    step,
     detecting,
     detectError,
     recommendation,
@@ -472,8 +470,7 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
     analysisStatus,
     merged,
     // actions
-    open,
-    selectFrame,
+    beginForFrame,
     detect,
     startAnalysis,
     applyAnalystDraft,
@@ -484,6 +481,5 @@ export const useEnvironmentWizardStore = defineStore('environmentWizard', () =>
     runPreflight,
     save,
     trialProvision,
-    goToStep,
   }
 })

package/app/stores/workspace.ts

@@ -168,9 +168,10 @@ export const useWorkspaceStore = defineStore(
       useInitiativesStore().hydratePresets(snapshot.initiativePresets)
       useTrackerStore().hydrate(snapshot.trackerSettings)
       useServicesStore().hydrate(snapshot.mounts ?? [], snapshot.serviceCatalog ?? [])
-      // Merge the deployment's registered custom agent kinds into the palette catalog so a
-      // proprietary kind renders as a first-class block + result view (idempotent on reload).
-      useAgentsStore().registerCustomKinds(snapshot.customAgentKinds ?? [])
+      // Hydrate the deployment's backend-registered custom agent kinds as the workspace's
+      // remote capability manifest, so a proprietary kind renders as a first-class palette
+      // block + result view. Swapped wholesale per workspace (no global-catalog mutation).
+      useAgentsStore().hydrateCustomKinds(snapshot.customAgentKinds ?? [])
       // 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.
       useSkillsStore().hydrate(snapshot.skills ?? [])

package/app/types/domain.ts

@@ -108,9 +108,10 @@ export interface AgentArchetype {
   category?: AgentCategory
   /**
    * Optional id of a DEDICATED result window this agent's step opens instead of the
-   * generic prose step-detail panel. Resolved through the result-view registry
-   * (`STEP_RESULT_VIEWS`) so any agent can declare a bespoke visualization without the
-   * renderer hardcoding a kind. Absent → the generic `AgentStepDetail` panel.
+   * generic prose step-detail panel. Resolved through the modular `resultViews` slot
+   * registry (`~/modular/result-views`, read by `StepResultViewHost`) so any agent —
+   * built-in or a consumer's — can declare a bespoke visualization without the renderer
+   * hardcoding a kind. Absent → the generic `AgentStepDetail` panel.
    */
   resultView?: string
 }

package/app/utils/catalog.ts

@@ -1,3 +1,4 @@
+import { shallowRef } from 'vue'
 import type {
   AgentArchetype,
   AgentCategory,
@@ -304,10 +305,44 @@ export function isProducerCompanion(kind: string): boolean {
   return COMPANION_KINDS.has(kind)
 }
 
-export const AGENT_BY_KIND: Record<AgentKind, AgentArchetype> = Object.fromEntries(
-  [...AGENT_ARCHETYPES, ...COMPANION_ARCHETYPES].map((a) => [a.kind, a]),
+/**
+ * The BUILT-IN palette + companion catalog, keyed by kind. Frozen and never
+ * mutated: custom (deployment/consumer) kinds no longer reach into this const —
+ * they flow through the modular `agentKinds` slot / the workspace-capability
+ * remote manifest and land in {@link customAgentKindMeta} instead (slice 2 of
+ * the modular-vue adoption). Freezing turns any stray write into a loud runtime
+ * error rather than silently conflating built-ins with custom kinds.
+ */
+export const AGENT_BY_KIND: Record<AgentKind, AgentArchetype> = Object.freeze(
+  Object.fromEntries([...AGENT_ARCHETYPES, ...COMPANION_ARCHETYPES].map((a) => [a.kind, a])),
 ) as Record<AgentKind, AgentArchetype>
 
+/**
+ * Reactive read-model of the deployment's CUSTOM agent kinds (consumer-slot +
+ * backend remote-manifest), kept in sync by the agents store from the resolved
+ * modular `agentKinds` slot. The slot/manifest is the source of truth; this
+ * `shallowRef` is its synchronous projection so the pure kind-meta lookups below
+ * ({@link agentKindMeta} / {@link isKnownAgentKind}) resolve a custom kind — and
+ * re-render when the catalog changes — WITHOUT importing the store (which would
+ * be circular) or mutating {@link AGENT_BY_KIND}. Empty until the store first
+ * populates it, so an unknown custom kind degrades to the generic fallback,
+ * exactly as before registration.
+ */
+const customAgentKindMeta = shallowRef<Record<string, AgentArchetype>>({})
+
+/**
+ * Replace the custom-kind projection (called only by the agents store, whenever
+ * its merged custom catalog changes). Whole-map replace, not per-key mutation.
+ */
+export function setCustomAgentKindMeta(map: Record<string, AgentArchetype>): void {
+  customAgentKindMeta.value = map
+}
+
+/** Test-only: clear the custom-kind projection so a spec starts from built-ins only. */
+export function __resetCustomAgentKindMetaForTest(): void {
+  customAgentKindMeta.value = {}
+}
+
 /**
  * Agent kinds eligible for the optional consensus mechanism (the pipeline builder shows an
  * "Enable Consensus" toggle for these). Mirrors the backend default-eligible set assigned by
@@ -596,30 +631,36 @@ const FALLBACK_AGENT_META: Omit<AgentArchetype, 'kind'> = {
 }
 
 /**
- * Resolve display metadata for ANY agent kind — a palette archetype (incl. custom
- * agents registered into {@link AGENT_BY_KIND}), an engine system kind, or an
- * unknown one — ALWAYS returning a usable icon/label/color. This is the single
- * lookup every pipeline / run renderer should use so a kind missing from the
- * archetype map (e.g. `ci`/`merger`/`blueprints` in a seeded pipeline) can never
- * blow up a component with an undefined access.
+ * Resolve display metadata for ANY agent kind — a built-in palette archetype
+ * ({@link AGENT_BY_KIND}), an engine system kind ({@link SYSTEM_AGENT_META}), a
+ * deployment CUSTOM kind (projected from the modular `agentKinds` slot into
+ * {@link customAgentKindMeta} by the agents store), or an unknown one — ALWAYS
+ * returning a usable icon/label/color. This is the single lookup every pipeline
+ * / run renderer should use so a kind missing from the archetype map (e.g.
+ * `ci`/`merger`/`blueprints` in a seeded pipeline) can never blow up a component
+ * with an undefined access. Reading `customAgentKindMeta` reactively means a
+ * component computed re-runs when the custom catalog changes.
  */
 export function agentKindMeta(kind: string): AgentArchetype {
   return (
     AGENT_BY_KIND[kind as AgentKind] ??
-    SYSTEM_AGENT_META[kind] ?? { kind: kind as AgentKind, ...FALLBACK_AGENT_META }
+    SYSTEM_AGENT_META[kind] ??
+    customAgentKindMeta.value[kind] ?? { kind: kind as AgentKind, ...FALLBACK_AGENT_META }
   )
 }
 
 /**
- * Whether an agent kind is actually known to this build — a palette archetype or companion
- * ({@link AGENT_BY_KIND}, which deployment custom kinds are merged into via
- * `useAgentsStore().registerCustomKinds`), or an engine system/gate kind
- * ({@link SYSTEM_AGENT_META}). Unlike {@link agentKindMeta} (which always returns a usable
- * fallback so renderers never crash), this returns `false` for an unknown kind — used to flag
- * a pipeline that references a nonexistent agent. Call AFTER custom kinds are registered.
+ * Whether an agent kind is actually known to this build — a built-in palette
+ * archetype or companion ({@link AGENT_BY_KIND}), an engine system/gate kind
+ * ({@link SYSTEM_AGENT_META}), or a deployment CUSTOM kind projected from the
+ * modular `agentKinds` slot ({@link customAgentKindMeta}). Unlike
+ * {@link agentKindMeta} (which always returns a usable fallback so renderers
+ * never crash), this returns `false` for an unknown kind — used to flag a
+ * pipeline that references a nonexistent agent. Call AFTER the workspace
+ * snapshot has hydrated the custom kinds.
  */
 export function isKnownAgentKind(kind: string): boolean {
-  return kind in AGENT_BY_KIND || kind in SYSTEM_AGENT_META
+  return kind in AGENT_BY_KIND || kind in SYSTEM_AGENT_META || kind in customAgentKindMeta.value
 }
 
 type BlockTypeMeta = { label: string; icon: string; accent: string }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.133.0",
+  "version": "0.135.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -18,14 +18,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@modular-frontend/core": "^0.1.0",
-    "@modular-vue/core": "^1.0.1",
-    "@modular-vue/nuxt": "^0.1.1",
-    "@modular-vue/runtime": "^1.1.0",
-    "@modular-vue/vue": "^1.1.0",
-    "@nuxt/ui": "^4.9.0",
+    "@modular-frontend/core": "^0.2.0",
+    "@modular-vue/core": "^1.2.0",
+    "@modular-vue/journeys": "^1.1.0",
+    "@modular-vue/nuxt": "^0.3.0",
+    "@modular-vue/runtime": "^1.3.0",
+    "@modular-vue/vue": "^1.2.0",
+    "@nuxt/ui": "^4.10.0",
     "@nuxtjs/i18n": "^10.4.1",
-    "@pinia/nuxt": "^0.11.3",
+    "@pinia/nuxt": "^1.0.1",
     "@toad-contracts/core": "0.4.0",
     "@toad-contracts/frontend-http-client": "0.3.2",
     "@toad-contracts/valibot": "0.5.0",
@@ -34,26 +35,26 @@
     "@vue-flow/node-resizer": "^1.5.1",
     "@vueuse/core": "^14.3.0",
     "markdown-it": "^14.3.0",
-    "pinia": "^3.0.4",
+    "pinia": "^4.0.2",
     "pinia-plugin-persistedstate": "^4.7.1",
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.147.1"
+    "@cat-factory/contracts": "0.148.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",
     "@types/markdown-it": "^14.1.2",
     "happy-dom": "^20.10.6",
     "msw": "^2.15.0",
-    "nuxt": "^4.4.8",
+    "nuxt": "^4.5.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "vue-i18n-extract": "^2.0.7",
     "vue-tsc": "^3.3.7"
   },
   "peerDependencies": {
-    "nuxt": "^4.4.8"
+    "nuxt": "^4.5.0"
   },
   "scripts": {
     "postinstall": "nuxt prepare",