@cat-factory/app 0.147.4 → 0.147.5

package/README.md

@@ -52,6 +52,17 @@ over the WebSocket. How that sync works is written up in
 | `types/`          | TypeScript domain unions (`domain.ts`) and wire types mirroring the contracts.                                                                        |
 | `utils/`          | Small pure helpers.                                                                                                                                   |
 
+## Extending the layer (consumer modules)
+
+A deployment can contribute its own components — result windows, nav entries, inspector
+panels, agent-kind palette data — **without forking**, through the auto-imported
+`registerAppModule` seam (the frontend analogue of the backend's `registerAgentKind` /
+`registerGate` registries). The authoring walkthrough, the reusable shared building blocks
+(`ResultWindowShell`, the `StepRunMeta` run-metadata block, `useResultView`, …), and the
+namespacing / degradation rules are in
+[`app/docs/consumer-extensions.md`](./app/docs/consumer-extensions.md); a full worked
+example ships in [`deploy/frontend`](../../deploy/frontend) (the `acme:security` module).
+
 ## Key UI surfaces
 
 - **Board canvas** (`components/board`) — `BoardCanvas` + `nodes/` (`BlockNode`,

package/app/components/panels/StepRunMeta.vue

@@ -27,7 +27,7 @@ const props = defineProps<{
 const models = useModelsStore()
 const { t, d } = useI18n()
 
-const { isRunning, durationLabel } = useStepTimer({
+const { isRunning, durationLabel, activityAgoLabel } = useStepTimer({
   step: () => props.step,
   runFailed: () => props.runFailed ?? false,
   failureAt: () => props.failureAt,
@@ -74,6 +74,19 @@ async function copyRunId() {
       </p>
     </div>
 
+    <!-- Liveness: time since the agent's last sign of life (the harness heartbeat), distinct from
+         the elapsed clock above — a long, quiet phase keeps this small while elapsed climbs, so a
+         genuinely-active-but-quiet run reads apart from a wedged one. Only while actively running. -->
+    <div v-if="isRunning && activityAgoLabel" data-testid="step-activity">
+      <h4 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+        {{ t('panels.stepMeta.activity') }}
+      </h4>
+      <p class="flex items-center gap-1.5 text-[12px] tabular-nums text-slate-300">
+        <span class="h-1.5 w-1.5 rounded-full bg-emerald-400" />
+        {{ t('panels.stepMeta.activityAgo', { duration: activityAgoLabel }) }}
+      </p>
+    </div>
+
     <div v-if="formatClock(step.startedAt)">
       <h4 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
         {{ t('panels.stepMeta.started') }}

package/app/composables/useStepTimer.spec.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from 'vitest'
 import type { PipelineStep } from '~/types/execution'
-import { stepDurationLabel, stepDurationMs, stepIsRunning } from '~/composables/useStepTimer'
+import {
+  stepActivityAgoMs,
+  stepDurationLabel,
+  stepDurationMs,
+  stepIsRunning,
+} from '~/composables/useStepTimer'
 
 // The pure helpers encode one freeze rule shared by the list surfaces (pipeline timeline,
 // inspector run list) and the single-step overlay, so pin the precedence here:
@@ -66,6 +71,22 @@ describe('stepDurationMs', () => {
   })
 })
 
+describe('stepActivityAgoMs (liveness clock, distinct from elapsed)', () => {
+  it('is null when the step has no heartbeat (non-container / not yet polled / old image)', () => {
+    expect(stepActivityAgoMs(step({ startedAt: 4000 }), NOW)).toBeNull()
+    expect(stepActivityAgoMs(null, NOW)).toBeNull()
+  })
+
+  it('measures time since the last heartbeat, not since the step started', () => {
+    // Started long ago (elapsed 6s) but active 1s ago — the whole point: a quiet run reads active.
+    expect(stepActivityAgoMs(step({ startedAt: 4000, lastActivityAt: 9000 }), NOW)).toBe(1000)
+  })
+
+  it('clamps to 0 so container/server clock skew never renders a negative value', () => {
+    expect(stepActivityAgoMs(step({ startedAt: 4000, lastActivityAt: NOW + 5000 }), NOW)).toBe(0)
+  })
+})
+
 describe('stepDurationLabel', () => {
   it('is null until the step has started', () => {
     expect(stepDurationLabel(step({ startedAt: undefined }), NOW, false, null)).toBeNull()

package/app/composables/useStepTimer.ts

@@ -39,6 +39,21 @@ export function stepDurationLabel(
   return ms == null ? null : formatDuration(ms)
 }
 
+/**
+ * Milliseconds since the container agent's last observed sign of life (`lastActivityAt`, the
+ * harness liveness heartbeat), at wall-clock `nowMs` — or null when the step has none (a
+ * non-container step, one not yet polled, or an older harness image). Clamped at 0 so minor
+ * container/server clock skew never renders a negative "active in the future" value. This is the
+ * LIVENESS clock (time since the agent last did anything), distinct from {@link stepDurationMs}'s
+ * ELAPSED clock (total time the step has been running) — a long, quiet phase keeps the elapsed
+ * clock climbing while this stays small, which is exactly how a genuinely-active-but-quiet run is
+ * told apart from a wedged one.
+ */
+export function stepActivityAgoMs(step: PipelineStep | null, nowMs: number): number | null {
+  if (step?.lastActivityAt == null) return null
+  return Math.max(0, nowMs - step.lastActivityAt)
+}
+
 /**
  * A shared 1s wall-clock tick for surfaces that render many steps' live durations
  * at once (the pipeline timeline, the inspector run list). One interval drives every
@@ -84,7 +99,16 @@ export function useStepTimer(opts: {
     durationMs.value == null ? null : formatDuration(durationMs.value),
   )
 
-  return { isRunning, durationMs, durationLabel }
+  // Time since the agent's last sign of life (the liveness heartbeat), ticking only while the
+  // step is actively running — a finished/parked/failed step isn't "active", so it reads null.
+  const activityAgoMs = computed(() =>
+    isRunning.value ? stepActivityAgoMs(opts.step(), nowTick.value) : null,
+  )
+  const activityAgoLabel = computed(() =>
+    activityAgoMs.value == null ? null : formatDuration(activityAgoMs.value),
+  )
+
+  return { isRunning, durationMs, durationLabel, activityAgoMs, activityAgoLabel }
 }
 
 export function formatDuration(ms: number): string {

package/app/docs/consumer-extensions.md

@@ -0,0 +1,171 @@
+# Extending the SPA from a consumer deployment
+
+A deployment that consumes this layer (`extends: ['@cat-factory/app']`) can contribute
+its own **components** — result windows, navigation entries, inspector panels, agent-kind
+palette data — **without forking the layer**. This is the frontend counterpart of the
+backend's public registries (`registerAgentKind`, `registerGate`; see
+[`backend/docs/custom-agents.md`](../../../backend/docs/custom-agents.md)). The governing
+principle is the same: **zero host edits for a consumer extension**.
+
+A worked, end-to-end example ships in the template deployment —
+[`deploy/frontend/app/`](../../../deploy/frontend) (the `acme:security` module) — the
+frontend analogue of the backend
+[`@cat-factory/example-custom-agent`](../../../backend/internal/example-custom-agent)
+package. Read this guide alongside it.
+
+> This is the **landed** surface (modular-vue adoption slices 1–5). The larger consumer
+> extension programme (custom task types, generic interactive phases, overlays, consumer
+> notification kinds, stream events, and the hardened public export surface) is tracked in
+> [`docs/initiatives/frontend-extension-mechanism.md`](../../../docs/initiatives/frontend-extension-mechanism.md).
+
+## The one seam: `registerAppModule`
+
+Everything is one call from your own Nuxt plugin. A module is a plain descriptor; each
+capability is a slot contribution.
+
+```ts
+// deploy/frontend/app/plugins/acme.client.ts
+import { defineModule } from '@modular-vue/core'
+import AcmeSecurityReport from '../components/acme/AcmeSecurityReport.vue'
+
+export default defineNuxtPlugin(() => {
+  registerAppModule(
+    defineModule({
+      id: 'acme:security', // namespaced — see "Rules" below
+      version: '1.0.0',
+      slots: {
+        resultViews: [{ id: 'acme:security-report', component: AcmeSecurityReport }],
+        agentKinds: [
+          /* palette entries — see "Agent kinds" */
+        ],
+        nav: [
+          /* sidebar / command-palette destinations — see "Navigation" */
+        ],
+        inspectorPanels: [
+          /* per-block detail panels — see "Inspector panels" */
+        ],
+      },
+    }),
+  )
+})
+```
+
+- **`registerAppModule` is auto-imported** from the layer (`app/utils/modular.ts`), so you
+  need no deep import into the layer's internals.
+- **`enforce: 'post'` is load-bearing.** The layer's own install plugin is `enforce:
+'post'`, and Nuxt runs layer plugins before the consuming app's plugins within one
+  enforce bucket. So your registration plugin must run in the **default** (or `pre`) bucket
+  — i.e. **do not** put `enforce: 'post'` on it, or it registers too late and is silently
+  missed.
+- **`defineModule` / the slot-entry types come from `@modular-vue/core`** — add it to your
+  deployment's `dependencies`.
+
+## The landed seams
+
+| Seam                                | Slot key          | Entry shape                                                                                      | Host                                        |
+| ----------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------- |
+| Run-detail windows                  | `resultViews`     | `{ id: '<ns>:<name>', component }`                                                               | `StepResultViewHost` via `dispatchStepView` |
+| Agent kinds (palette data)          | `agentKinds`      | `{ kind, container, presentation: { label, icon, color, description, category?, resultView? } }` | agents store merge → `agentKindMeta`        |
+| Sidebar / command-palette / toolbar | `nav`             | `{ id, labelKey, icon, surfaces, gate?, run, sidebar?, command?, toolbar? }`                     | the three shells via `useNavContributions`  |
+| Inspector body panels               | `inspectorPanels` | `{ id, component, when(block), order }` (`PanelEntry<Block>`)                                    | `<PanelsOutlet>` in `InspectorPanel`        |
+| Multi-step wizards                  | (journeys)        | `registerJourney` + step modules                                                                 | `<JourneyHost>` / `<JourneyOutlet>`         |
+| Locale strings                      | (i18n)            | `i18n/locales/*.json` in the deployment                                                          | `@nuxtjs/i18n` layer deep-merge             |
+
+### Run-detail windows (`resultViews` + `agentKinds`)
+
+Backend data selects a frontend component, joined by a namespaced id:
+
+1. A backend agent kind (registered on `AgentKindRegistry`, e.g.
+   `@cat-factory/example-custom-agent`'s `security-auditor`) arrives in the workspace
+   snapshot with `presentation.resultView: '<ns>:<name>'` — **or** you code-ship the kind's
+   palette entry via the `agentKinds` slot (as the example does, to give an existing kind a
+   bespoke window).
+2. You contribute the component to `resultViews` under the SAME id.
+3. When a step of that kind is opened, `dispatchStepView` resolves the kind's `resultView`
+   id, and `StepResultViewHost` mounts your paired component.
+
+An unpaired id degrades to the generic prose panel (a dev-console warning names the dangling
+id); a structured kind with no bespoke window gets the built-in `generic-structured` viewer
+for free.
+
+### Navigation
+
+A consumer nav item carries its own `run` closure (first-party items use a typed `action`
+id instead). Optional `gate: (g) => g.canManageIntegrations` hides it reactively without the
+permission. `surfaces` picks which shells render it (`'sidebar' | 'command' | 'toolbar'`),
+and `sidebar` / `command` / `toolbar` place it within each.
+
+### Inspector panels
+
+Contribute `PanelEntry<Block>` entries; each `when(block)` predicate decides which blocks
+show the panel, and `order` places it among the built-ins. Your panel component reads the
+selected block via `usePanelSubject<Block>()` (`@modular-vue/core`). `when` must tolerate a
+nullish subject (the boot-time validation resolve passes `null`).
+
+## Reuse the shared building blocks — don't reinvent them
+
+The layer ships window/inspector primitives you compose instead of hand-rolling chrome or
+re-deriving the "which run is this / how did the model do" facts. **Composables** (and the
+`registerAppModule` helper) are auto-imported into your consumer code with zero imports;
+**components** must be named through the `#components` virtual module (see the boxed note
+below). Compose these:
+
+| Building block         | Reference it as                           | What it gives you                                                                                                                                                                                                                                                                                             |
+| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ResultWindowShell`    | `#components` → `PanelsResultWindowShell` | The shared modal chrome for a result window — backdrop, header (icon/title/subtitle), a `#header-extras` slot, close button, and the modal _behaviour_ (focus-trap + return, body-scroll lock, shared-stack Escape via `useModalBehavior`). Pass `stepRef` to surface the shared "restart from here" control. |
+| `StepRunMeta`          | `#components` → `PanelsStepRunMeta`       | **The shared run-details metadata block** every agent window reuses: step position, live duration, model, run id, and the LLM model-activity rollup. Drop it into your window's sidebar — never reinvent run metadata.                                                                                        |
+| `MarkdownProse`        | `#components` → `CommonMarkdownProse`     | Render an agent's prose output as markdown.                                                                                                                                                                                                                                                                   |
+| `CopyButton`           | `#components` → `CommonCopyButton`        | The shared copy-to-clipboard affordance.                                                                                                                                                                                                                                                                      |
+| `InspectorSection`     | `#components` → `PanelsInspectorSection`  | The collapsible inspector-section shell (chevron header, count, hint) so a consumer panel reads like a built-in one.                                                                                                                                                                                          |
+| `useResultView(id)`    | auto-imported                             | The window seam contract: `{ open, blockId, instanceId, stepIndex, close }` (+ an `onOpen` loader for windows that fetch, and an `onClose` flush). Escape is owned by the shell, not here.                                                                                                                    |
+| `usePanelSubject<T>()` | `@modular-vue/core`                       | Read the block injected into an inspector panel by `<PanelsOutlet>`.                                                                                                                                                                                                                                          |
+
+> **Reference layer components through `#components`, not bare tags.** Nuxt auto-registers a
+> layer's components under a **path-derived** name (`components/panels/ResultWindowShell.vue`
+> → `PanelsResultWindowShell`), and only rewrites bare `<ResultWindowShell>` tags inside the
+> layer's own SFCs. A bare tag in a **consumer** SFC resolves to nothing and silently renders
+> as an unknown element — its `<slot>` children still appear, so a shallow test can pass while
+> the shared chrome (and its `data-testid`) never mounts. Import the ones you use from
+> `#components` (Nuxt's stable virtual registry — **not** a deep path into the layer's
+> `app/components/*`), aliasing them back to the short names for readable templates:
+>
+> ```ts
+> import {
+>   PanelsResultWindowShell as ResultWindowShell,
+>   PanelsStepRunMeta as StepRunMeta,
+>   CommonMarkdownProse as MarkdownProse,
+> } from '#components'
+> ```
+>
+> Composables (`useResultView`, `useI18n`, the Pinia stores) and `registerAppModule` are
+> auto-imported across layers by Nuxt's separate imports mechanism, so those need no import.
+> Hardening these building blocks into an explicitly exported, location-independent public
+> surface is slice G of the initiative.
+
+The example `AcmeSecurityReport.vue` window is a full demonstration: it imports
+`ResultWindowShell` + `StepRunMeta` + `MarkdownProse` from `#components`, composes them with
+the auto-imported `useResultView`, adds only its own bespoke body (the security findings), and
+reads the auditor's structured assessment straight off `step.custom`.
+
+## i18n
+
+Ship your strings under your own namespace in the deployment's `i18n/locales/*.json` (e.g.
+`acme.*`). `@nuxtjs/i18n` is layer-aware and **deep-merges** them into the layer catalog, so
+`t('acme.securityReport.title')` resolves in your components with no config change. The
+layer's typed-key and locale-parity guards govern only the layer's own keys — your namespace
+is yours.
+
+## Rules that hold across every seam
+
+- **Namespacing.** Every consumer-authored id is `<ns>:<name>`. Built-ins are never
+  shadowable — the merge logic drops a consumer entry whose id collides with a built-in
+  (see the agents store).
+- **Fail fast at boot, degrade at runtime.** Duplicate ids across first-party + consumer
+  modules throw when the layer resolves the merged slots at startup; missing pairings and
+  unknown wire ids degrade with a dev-console warning, never a crash.
+- **Never crash on stale data.** An id that arrives on the wire (a `resultView`, an agent
+  kind) after its extension was removed must degrade to a defined rendering — extensions get
+  uninstalled while persisted rows outlive them.
+- **The remote manifest is DATA only.** Components never travel the wire; per-workspace
+  variability comes from which capabilities the snapshot lists, not from which modules are
+  registered (registration is boot-static).

package/i18n/locales/de.json

@@ -1386,6 +1386,8 @@
       "stateLabel": "Status",
       "duration": "Dauer",
       "elapsed": "vergangen",
+      "activity": "Letzte Aktivität",
+      "activityAgo": "vor {duration} aktiv",
       "step": "Schritt",
       "stepOf": "{number} von {total}",
       "started": "Gestartet",

package/i18n/locales/en.json

@@ -1161,6 +1161,8 @@
       "stateLabel": "State",
       "duration": "Duration",
       "elapsed": "elapsed",
+      "activity": "Last activity",
+      "activityAgo": "active {duration} ago",
       "step": "Step",
       "stepOf": "{number} of {total}",
       "started": "Started",

package/i18n/locales/es.json

@@ -1104,6 +1104,8 @@
       "stateLabel": "Estado",
       "duration": "Duración",
       "elapsed": "transcurrido",
+      "activity": "Última actividad",
+      "activityAgo": "activo hace {duration}",
       "step": "Paso",
       "stepOf": "{number} de {total}",
       "started": "Iniciado",

package/i18n/locales/fr.json

@@ -1104,6 +1104,8 @@
       "stateLabel": "État",
       "duration": "Durée",
       "elapsed": "écoulé",
+      "activity": "Dernière activité",
+      "activityAgo": "actif il y a {duration}",
       "step": "Étape",
       "stepOf": "{number} sur {total}",
       "started": "Démarré",

package/i18n/locales/he.json

@@ -1104,6 +1104,8 @@
       "stateLabel": "מצב",
       "duration": "משך",
       "elapsed": "חלף",
+      "activity": "פעילות אחרונה",
+      "activityAgo": "פעיל לפני {duration}",
       "step": "שלב",
       "stepOf": "{number} מתוך {total}",
       "started": "התחיל",

package/i18n/locales/it.json

@@ -1386,6 +1386,8 @@
       "stateLabel": "Stato",
       "duration": "Durata",
       "elapsed": "trascorso",
+      "activity": "Ultima attività",
+      "activityAgo": "attivo {duration} fa",
       "step": "Passaggio",
       "stepOf": "{number} di {total}",
       "started": "Iniziato",

package/i18n/locales/ja.json

@@ -1104,6 +1104,8 @@
       "stateLabel": "状態",
       "duration": "所要時間",
       "elapsed": "経過",
+      "activity": "最終アクティビティ",
+      "activityAgo": "{duration}前にアクティブ",
       "step": "ステップ",
       "stepOf": "{total} 中 {number}",
       "started": "開始",

package/i18n/locales/pl.json

@@ -1104,6 +1104,8 @@
       "stateLabel": "Stan",
       "duration": "Czas trwania",
       "elapsed": "upłynęło",
+      "activity": "Ostatnia aktywność",
+      "activityAgo": "aktywny {duration} temu",
       "step": "Krok",
       "stepOf": "{number} z {total}",
       "started": "Rozpoczęto",

package/i18n/locales/tr.json

@@ -1104,6 +1104,8 @@
       "stateLabel": "Durum",
       "duration": "Süre",
       "elapsed": "geçen süre",
+      "activity": "Son etkinlik",
+      "activityAgo": "{duration} önce etkindi",
       "step": "Adım",
       "stepOf": "{total} adımdan {number}.",
       "started": "Başladı",

package/i18n/locales/uk.json

@@ -1104,6 +1104,8 @@
       "stateLabel": "Стан",
       "duration": "Тривалість",
       "elapsed": "минуло",
+      "activity": "Остання активність",
+      "activityAgo": "активний {duration} тому",
       "step": "Крок",
       "stepOf": "{number} з {total}",
       "started": "Розпочато",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.147.4",
+  "version": "0.147.5",
   "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",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.154.1"
+    "@cat-factory/contracts": "0.154.2"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",