@cat-factory/app 0.167.1 → 0.169.0

package/app/components/panels/ObservabilityPanel.vue

@@ -8,7 +8,7 @@ import type {
   WebSearchProvider,
 } from '~/types/execution'
 import { agentKindMeta } from '~/utils/catalog'
-import { formatMs, formatTokens, freshPromptTokens, pct } from '~/utils/observability'
+import { formatMs, formatTokens, pct, totalInputTokens } from '~/utils/observability'
 
 // Drill-down overlay for a run's LLM activity. Opened via
 // `ui.openObservability(instanceId)` from a step surface; loads the full per-call
@@ -126,15 +126,18 @@ const totals = computed(() => {
   const upstreamMs = sum(c, (x) => x.upstreamMs)
   const overheadMs = sum(c, (x) => x.overheadMs)
   const total = upstreamMs + overheadMs
+  // The three input classes are orthogonal at the source, so they are simply summed —
+  // `promptTokens` IS the fresh figure and needs no heuristic to recover it; the headline is
+  // their TOTAL (see `totalInputTokens` — the like-for-like Claude Code context gauge).
   const promptTokens = sum(c, (x) => x.promptTokens)
-  const cachedPromptTokens = sum(c, (x) => x.cachedPromptTokens)
+  const cacheReadTokens = sum(c, (x) => x.cacheReadTokens)
+  const cacheWriteTokens = sum(c, (x) => x.cacheWriteTokens)
   return {
     calls: c.length,
     promptTokens,
-    cachedPromptTokens,
-    // Fresh (uncached) input — the raw prompt-token sum is dominated by per-turn cache reads
-    // on a long agentic run, so surface fresh vs cached rather than the misleading raw total.
-    freshPromptTokens: freshPromptTokens(promptTokens, cachedPromptTokens),
+    cacheReadTokens,
+    cacheWriteTokens,
+    inputTokens: totalInputTokens({ promptTokens, cacheReadTokens, cacheWriteTokens }),
     completionTokens: sum(c, (x) => x.completionTokens),
     upstreamMs,
     overheadMs,
@@ -290,18 +293,47 @@ function exportJson() {
                     {{ t('observability.summary.tokensInOut') }}
                   </dt>
                   <dd class="mt-0.5 tabular-nums text-slate-200">
-                    {{ formatTokens(totals.freshPromptTokens) }} /
-                    {{ formatTokens(totals.completionTokens) }}
+                    <span :title="t('observability.summary.inputTokensHint')">
+                      {{ formatTokens(totals.inputTokens) }} /
+                      {{ formatTokens(totals.completionTokens) }}
+                    </span>
                     <span
-                      v-if="totals.cachedPromptTokens > 0"
-                      class="ms-1 text-[11px] text-emerald-400/80"
+                      v-if="totals.cacheReadTokens > 0 || totals.cacheWriteTokens > 0"
+                      class="mt-0.5 block text-[11px]"
                     >
-                      ·
-                      {{
-                        t('observability.summary.cached', {
-                          tokens: formatTokens(totals.cachedPromptTokens),
-                        })
-                      }}
+                      <span class="text-slate-400" :title="t('observability.summary.freshHint')">
+                        {{
+                          t('observability.summary.fresh', {
+                            tokens: formatTokens(totals.promptTokens),
+                          })
+                        }}
+                      </span>
+                      <template v-if="totals.cacheReadTokens > 0">
+                        <span class="text-slate-600"> · </span>
+                        <span
+                          class="text-emerald-400/80"
+                          :title="t('observability.summary.cacheReadHint')"
+                        >
+                          {{
+                            t('observability.summary.cacheRead', {
+                              tokens: formatTokens(totals.cacheReadTokens),
+                            })
+                          }}
+                        </span>
+                      </template>
+                      <template v-if="totals.cacheWriteTokens > 0">
+                        <span class="text-slate-600"> · </span>
+                        <span
+                          class="text-amber-400/80"
+                          :title="t('observability.summary.cacheWriteHint')"
+                        >
+                          {{
+                            t('observability.summary.cacheWrite', {
+                              tokens: formatTokens(totals.cacheWriteTokens),
+                            })
+                          }}
+                        </span>
+                      </template>
                     </span>
                   </dd>
                 </div>
@@ -418,12 +450,14 @@ function exportJson() {
                     <span
                       :title="
                         t('observability.call.tokensTitle', {
-                          prompt: c.promptTokens,
+                          input: totalInputTokens(c),
+                          fresh: c.promptTokens,
                           completion: c.completionTokens,
                         })
                       "
                     >
-                      {{ formatTokens(c.promptTokens) }}↑ {{ formatTokens(c.completionTokens) }}↓
+                      {{ formatTokens(totalInputTokens(c)) }}↑
+                      {{ formatTokens(c.completionTokens) }}↓
                     </span>
                     <span
                       v-if="headroomOf(c) !== null"
@@ -467,11 +501,14 @@ function exportJson() {
                     <span v-if="c.requestMaxTokens != null">{{
                       t('observability.call.maxTokens', { value: c.requestMaxTokens })
                     }}</span>
-                    <span v-if="c.cachedPromptTokens > 0" class="text-emerald-400">{{
-                      t('observability.call.promptCached', {
-                        cached: c.cachedPromptTokens,
-                        prompt: c.promptTokens,
-                      })
+                    <span v-if="c.cacheReadTokens > 0 || c.cacheWriteTokens > 0">{{
+                      t('observability.call.fresh', { tokens: c.promptTokens })
+                    }}</span>
+                    <span v-if="c.cacheReadTokens > 0" class="text-emerald-400">{{
+                      t('observability.call.cacheRead', { tokens: c.cacheReadTokens })
+                    }}</span>
+                    <span v-if="c.cacheWriteTokens > 0" class="text-amber-400">{{
+                      t('observability.call.cacheWrite', { tokens: c.cacheWriteTokens })
                     }}</span>
                     <span>{{
                       t('observability.call.total', { duration: formatMs(c.totalMs) })

package/app/components/panels/inspector/TaskRunSettings.vue

@@ -4,6 +4,7 @@ import { connectionNeighborIds } from '@cat-factory/contracts'
 import type { Block } from '~/types/domain'
 import type { WritebackOverride } from '~/types/tracker'
 import { pipelineAllowedForManualStart } from '~/utils/pipeline'
+import { showOverrideField } from '~/utils/uiMode'
 import InspectorSection from '~/components/panels/inspector/InspectorSection.vue'
 import RiskPolicyPicker from '~/components/riskPolicy/RiskPolicyPicker.vue'
 import TaskAprioriBranches from '~/components/panels/inspector/TaskAprioriBranches.vue'
@@ -18,6 +19,23 @@ const pipelines = usePipelinesStore()
 const accounts = useAccountsStore()
 const tracker = useTrackerStore()
 const ui = useUiStore()
+// Interface tier. Basic mode hides only what OVERRIDES something already decided elsewhere:
+// a workspace-level default (merge policy, model preset, tracker writeback) or an
+// engine-inferred value (the technical/business label). That bound is what makes hiding safe
+// — what's left is exactly the value the hidden field would have displayed, so a basic-mode
+// task behaves identically. Everything that carries an input NOTHING else supplies stays in
+// both tiers, however advanced it feels: the pipeline, the involved services, the apriori
+// branches, the responsible person, auto-start. The same split applies at creation time in
+// `AddTaskModal`.
+//
+// Unlike creation — which always starts from the defaults — an EXISTING block can already
+// carry an override (a teammate on the advanced tier, the API, or this user before they
+// switched down). Hiding it then would break the very bound above: the task would run on
+// settings a basic-mode user can neither see nor clear, and no other inspector panel shows
+// them. So each group below asks `showOverrideField`, which keeps the field whenever it is
+// actually set. Basic mode stays clean for the common (unset) case without ever concealing a
+// deviation.
+const uiMode = useUiModeStore()
 const { ready, unavailableInPreset } = useAiReadiness()
 const { t, n } = useI18n()
 
@@ -290,8 +308,8 @@ const technicalLabel = computed(() => {
       </p>
     </div>
 
-    <!-- merge policy preset -->
-    <div>
+    <!-- merge policy preset (advanced, or basic with an override already set) -->
+    <div v-if="showOverrideField(uiMode.isAdvanced, block.riskPolicyId)">
       <div class="mb-1 flex items-center justify-between">
         <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
           {{ t('inspector.runSettings.mergePolicy') }}
@@ -348,8 +366,8 @@ const technicalLabel = computed(() => {
       </p>
     </div>
 
-    <!-- model preset -->
-    <div>
+    <!-- model preset (advanced, or basic with an override already set) -->
+    <div v-if="showOverrideField(uiMode.isAdvanced, block.modelPresetId)">
       <div class="mb-1 flex items-center justify-between">
         <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
           {{ t('inspector.runSettings.modelPreset') }}
@@ -422,8 +440,8 @@ const technicalLabel = computed(() => {
       </p>
     </div>
 
-    <!-- technical label (tri-state) -->
-    <div>
+    <!-- technical label (tri-state) — unset lets the engine infer it -->
+    <div v-if="showOverrideField(uiMode.isAdvanced, block.technical)">
       <div class="mb-1 flex items-center justify-between">
         <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
           {{ t('inspector.runSettings.taskKind') }}
@@ -498,8 +516,17 @@ const technicalLabel = computed(() => {
     <!-- reference repositories: read-only repos the doc-writer reads while drafting (doc tasks) -->
     <DocReferenceRepos v-if="block.taskType === 'document'" :block="block" />
 
-    <!-- issue-tracker writeback overrides -->
-    <div>
+    <!-- issue-tracker writeback overrides (any one set reveals the whole group) -->
+    <div
+      v-if="
+        showOverrideField(
+          uiMode.isAdvanced,
+          block.trackerCommentOnPrOpen,
+          block.trackerResolveOnMerge,
+          block.trackerQuestionsOnPark,
+        )
+      "
+    >
       <div class="mb-1 flex items-center justify-between">
         <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
           {{ t('inspector.runSettings.issueWriteback') }}

package/app/components/tasks/BugHuntModal.vue

@@ -10,6 +10,7 @@
 // unavailable or failed still shows its candidates (flagged as unassessed, since the scan is
 // useful on its own), and a scan that hit its cap says so — a silently shortened list reads
 // exactly like an exhaustive one.
+import type { TaskSourceReadReason } from '@cat-factory/contracts'
 import type {
   BugHuntAnalysisStatus,
   BugHuntCandidate,
@@ -69,8 +70,9 @@ const boardItems = computed(() =>
  * backend's reason code, not on "any error": an unreachable tracker or an expired token would
  * otherwise present as a free-text field that simply moves the same failure to the next click.
  */
+const BOARDS_UNSUPPORTED: TaskSourceReadReason = 'boards_unsupported'
 const boardIsFreeText = computed(
-  () => !hunt.boardsLoading && hunt.boardsErrorReason === 'boards_unsupported',
+  () => !hunt.boardsLoading && hunt.boardsErrorReason === BOARDS_UNSUPPORTED,
 )
 
 /** A board read that failed for a reason the user has to fix — shown, never silently swallowed. */

package/app/components/tasks/ContextIssuePicker.vue

@@ -7,12 +7,19 @@
 // them once the block exists (see useContextLinking). A search hit / pasted ref
 // carries `needsImport: true` so it's fetched + persisted before linking.
 //
+// Search results are always confined to ONE repository (`scopeBlockId`'s service).
+// An issue in another repo is reachable only by pasting its URL, which the explicit
+// "attach by reference" row below imports directly — it never comes back as a hit,
+// so what the search offers is exactly what the service owns.
+//
 // The tracker being searched is ALWAYS on screen (even when the workspace offers
 // exactly one), and its menu doubles as the "add a tracker" affordance: attaching a
 // context issue is where a missing integration is discovered, and the connect modal
 // opens over the caller's form rather than navigating away from it.
 import type { DropdownMenuItem } from '@nuxt/ui'
+import type { TaskSourceReadReason } from '@cat-factory/contracts'
 import type { SourceTask, TaskSearchResult, TaskSourceKind } from '~/types/domain'
+import { apiErrorReason } from '~/composables/api/errors'
 import EmptyState from '~/components/common/EmptyState.vue'
 import { buildSourceChoices, reconcileSource } from '~/components/tasks/ContextIssuePicker.logic'
 
@@ -21,10 +28,13 @@ const props = defineProps<{
   chosenKeys?: string[]
   /**
    * The block the picker is attaching context to (a service frame or a task/module
-   * under one). Scopes a GitHub search to that service's linked repo, so hits stay
-   * in-repo and a pasted URL / bare issue number resolves to the exact issue.
+   * under one). REQUIRED: it is what scopes a GitHub search to that service's linked
+   * repo, so hits stay in-repo and a bare issue number resolves to the exact issue.
+   * A search with no scope reaches every repository the deployment's credential can
+   * see (under a PAT, all of public GitHub), so there is no unscoped mode — a caller
+   * that has no block yet must not render the picker.
    */
-  scopeBlockId?: string
+  scopeBlockId: string
   /**
    * Controlled source: when provided the parent owns the selected tracker (via
    * `v-model:source`); omitted, the picker manages it internally (the add-task case).
@@ -147,7 +157,14 @@ async function runSearch() {
     results.value = await tasks.search(source.value, q, props.scopeBlockId)
   } catch (e) {
     results.value = []
-    searchError.value = e instanceof Error ? e.message : String(e)
+    // "This service has no repo" is the one failure with an action attached, so it gets its
+    // own localized copy off the backend's machine-readable reason rather than the raw
+    // message (CLAUDE.md "Backend strings"). Anything else keeps the generic wording.
+    const notLinked: TaskSourceReadReason = 'repo_not_linked'
+    searchError.value =
+      apiErrorReason(e) === notLinked
+        ? t('tasks.picker.searchNeedsRepo')
+        : t('tasks.picker.searchFailed', { error: e instanceof Error ? e.message : String(e) })
   } finally {
     searching.value = false
   }
@@ -295,7 +312,7 @@ onMounted(() => {
     />
 
     <p v-if="searchError" class="px-1 text-[11px] text-amber-400">
-      {{ t('tasks.picker.searchFailed', { error: searchError }) }}
+      {{ searchError }}
     </p>
 
     <div class="max-h-56 space-y-0.5 overflow-y-auto">

package/app/components/tasks/TaskImportModal.vue

@@ -163,7 +163,7 @@ async function doSpawnEpic() {
              or paste a URL/key — choosing one opens the prefilled add-task form. The
              search is scoped to the chosen container's repo (so a GitHub search stays
              in that service's repo and a pasted URL / bare number resolves there). -->
-        <UFormField :label="t('tasks.import.searchIssues')">
+        <UFormField v-if="containerId" :label="t('tasks.import.searchIssues')">
           <ContextIssuePicker
             v-model:source="source"
             :scope-block-id="containerId"

package/app/composables/api/errors.ts

@@ -54,6 +54,22 @@ export function apiErrorEnvelope(error: unknown): ApiErrorEnvelope | undefined {
   return envelopeOf(e?.body) ?? envelopeOf(e?.data)
 }
 
+/**
+ * The backend's machine-readable `error.details.reason` code, when it sent one.
+ *
+ * This is the client half of the "backend strings" contract (see CLAUDE.md): a localizable
+ * server condition emits a stable code and the SPA maps it to a message key, with the raw
+ * prose `message` as the untranslated last resort. Callers compare the result against a union
+ * imported from `@cat-factory/contracts`, so a renamed code fails the typecheck instead of
+ * silently falling through to the generic wording.
+ */
+export function apiErrorReason(error: unknown): string | null {
+  const details = apiErrorEnvelope(error)?.details
+  if (!details || typeof details !== 'object') return null
+  const reason = (details as Record<string, unknown>).reason
+  return typeof reason === 'string' ? reason : null
+}
+
 /** The HTTP status of a thrown API error, when present (contract client or `$fetch`). */
 export function apiErrorStatus(error: unknown): number | undefined {
   const e = error as { statusCode?: unknown; status?: unknown }

package/app/composables/api/tasks.ts

@@ -71,16 +71,19 @@ export function tasksApi({ send, ws }: ApiContext) {
     importTask: (workspaceId: string, source: TaskSourceKind, body: { ref: string }) =>
       send(importTaskContract, { pathPrefix: ws(workspaceId), pathParams: { source }, body }),
 
+    // `blockId` is required: it is what scopes a GitHub search to the block's service
+    // repo, and the backend refuses an unscoped one (it would reach every repository the
+    // deployment's credential can see).
     searchTaskSource: (
       workspaceId: string,
       source: TaskSourceKind,
       query: string,
-      blockId?: string,
+      blockId: string,
     ) =>
       send(searchTasksContract, {
         pathPrefix: ws(workspaceId),
         pathParams: { source },
-        body: { query, ...(blockId ? { blockId } : {}) },
+        body: { query, blockId },
       }),
 
     linkTask: (

package/app/composables/useNavContributions.ts

@@ -47,6 +47,9 @@ export function useNavContributions() {
     operatorDashboard: () => ui.openOperatorDashboard(),
     reports: () => ui.openReports(),
     shortcuts: () => ui.openShortcutsHelp(),
+    // No-op under an env pin (`setMode` refuses), so the palette entry matches the sidebar
+    // switcher's read-only state rather than pretending to flip a tier the resolver fixes.
+    toggleUiMode: () => useUiModeStore().toggleMode(),
   }
 
   /** Run a contribution's action (consumer `run` closure wins over the id map). */

package/app/docs/consumer-extensions.md

@@ -61,12 +61,17 @@ export default defineNuxtPlugin(() => {
 | 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`                                 |
 | Custom task types                   | `taskTypes`       | `{ taskType: '<ns>:<name>', presentation, fields?, defaultPipelineId?, formPanel? }`             | `AddTaskModal` picker/fields + `TaskCard` badge (via `taskTypeMeta`) |
-| Sidebar / command-palette / toolbar | `nav`             | `{ id, labelKey, icon, surfaces, gate?, run, sidebar?, command?, toolbar? }`                     | the three shells via `useNavContributions`                           |
+| Sidebar / command-palette / toolbar | `nav`             | `{ id, labelKey, icon, surfaces, gate?, advanced?, run, sidebar?, command?, toolbar? }`          | the three shells via `useNavContributions`                           |
 | Inspector body panels               | `inspectorPanels` | `{ id, component, when(block), order }` (`PanelEntry<Block>`)                                    | `<PanelsOutlet>` in `InspectorPanel`                                 |
 | Top-level overlays                  | `appOverlays`     | `{ id: '<ns>:<name>', component }`                                                               | `<AppOverlayHost>` via `useAppOverlays().open(id)`                   |
 | Multi-step wizards                  | (journeys)        | `registerJourney` + step modules                                                                 | `<JourneyHost>` / `<JourneyOutlet>`                                  |
 | Locale strings                      | (i18n)            | `i18n/locales/*.json` in the deployment                                                          | `@nuxtjs/i18n` layer deep-merge                                      |
 
+A `nav` entry may also declare `advanced: true`, which hides it in **basic** interface mode
+(the shipped default) exactly as it does for the first-party destinations — see
+[the layer README](../../README.md#interface-modes-basic--advanced). Use it for a power-user
+destination; the flag is independent of `gate`, so both must pass for the item to render.
+
 ### Run-detail windows (`resultViews` + `agentKinds`)
 
 Backend data selects a frontend component, joined by a namespaced id:

package/app/modular/nav-contributions.spec.ts

@@ -32,6 +32,9 @@ const NO_GATES: NavGates = {
   infrastructureAvailable: false,
   accountsEnabled: false,
   isAccountAdmin: false,
+  // The permission axis is what these cases vary; keep the interface tier at `advanced`
+  // so a dropped item is unambiguously an RBAC/availability drop, not a tier drop.
+  advancedMode: true,
 }
 
 const ALL_GATES: NavGates = {
@@ -43,6 +46,7 @@ const ALL_GATES: NavGates = {
   infrastructureAvailable: true,
   accountsEnabled: true,
   isAccountAdmin: true,
+  advancedMode: true,
 }
 
 const slots = (): AppSlots => ({
@@ -84,6 +88,58 @@ describe('navSlotFilter', () => {
     const kept = ids(navSlotFilter(slots(), {}))
     expect(kept.sort()).toEqual(NAV_CONTRIBUTIONS.map((i) => i.id).sort())
   })
+
+  it('drops every advanced destination in basic interface mode', () => {
+    const gates: NavGates = { ...ALL_GATES, advancedMode: false }
+    const kept = ids(navSlotFilter(slots(), { gates }))
+    const basicOnly = NAV_CONTRIBUTIONS.filter((i) => !i.advanced).map((i) => i.id)
+    expect(kept.sort()).toEqual(basicOnly.sort())
+    // The everyday surface survives...
+    expect(kept).toContain('add-from-repo')
+    expect(kept).toContain('integrations-hub')
+    expect(kept).toContain('workspace-settings')
+    expect(kept).toContain('model-config')
+    // ...and the authoring / operator surfaces don't.
+    expect(kept).not.toContain('build-pipeline')
+    expect(kept).not.toContain('fragments')
+    expect(kept).not.toContain('sandbox')
+    expect(kept).not.toContain('operator-dashboard')
+  })
+
+  it('keeps the tier switch itself reachable in basic mode', () => {
+    // Basic is the shipped default, so this palette entry is how a user who never finds the
+    // (icon-only, in the basic rail) sidebar switcher gets to the advanced half at all. Marking
+    // it `advanced` would hide the way back from exactly the tier that needs it.
+    const uiModeItem = NAV_CONTRIBUTIONS.find((i) => i.id === 'ui-mode')
+    expect(uiModeItem?.advanced).toBeUndefined()
+    expect(uiModeItem?.gate).toBeUndefined()
+
+    const gates: NavGates = { ...NO_GATES, advancedMode: false }
+    expect(ids(navSlotFilter(slots(), { gates }))).toContain('ui-mode')
+  })
+
+  it('keeps the tier and the permission axes independent — both must pass', () => {
+    // `build-pipeline` is advanced AND needs board.write: neither axis alone reveals it.
+    const advancedOnly: NavGates = { ...NO_GATES, advancedMode: true }
+    expect(ids(navSlotFilter(slots(), { gates: advancedOnly }))).not.toContain('build-pipeline')
+
+    const permissionOnly: NavGates = { ...NO_GATES, canWriteBoard: true, advancedMode: false }
+    expect(ids(navSlotFilter(slots(), { gates: permissionOnly }))).not.toContain('build-pipeline')
+
+    const both: NavGates = { ...NO_GATES, canWriteBoard: true, advancedMode: true }
+    expect(ids(navSlotFilter(slots(), { gates: both }))).toContain('build-pipeline')
+  })
+
+  it('leaves at least one sidebar destination in every basic-mode section it keeps', () => {
+    // A section whose every item is advanced is dropped wholesale upstream (groupSidebar drops
+    // empties), which is intended — but a basic-mode sidebar with NO destinations at all would
+    // be a broken shell, so pin that the everyday surface is non-empty.
+    const gates: NavGates = { ...ALL_GATES, advancedMode: false }
+    const kept = (navSlotFilter(slots(), { gates }) as AppSlots).nav
+    const groups = groupSidebar(kept)
+    expect(groups.length).toBeGreaterThan(0)
+    for (const group of groups) expect(group.items.length).toBeGreaterThan(0)
+  })
 })
 
 describe('NAV_CONTRIBUTIONS catalog integrity', () => {
@@ -172,7 +228,8 @@ describe('nav grouping helpers', () => {
 
   it('groupCommands preserves the pre-slice-1 workspace-group order', () => {
     const workspace = groupCommands(NAV_CONTRIBUTIONS).find((g) => g.group === 'workspace')
-    // Same order the old CommandBar pushed them in (parity, not a reorder).
+    // Same order the old CommandBar pushed them in (parity, not a reorder), with genuinely
+    // new entries appended after it rather than interleaved.
     expect(workspace?.items.map((ci) => ci.item.id)).toEqual([
       'fragments',
       'merge-thresholds',
@@ -182,6 +239,7 @@ describe('nav grouping helpers', () => {
       'local-models',
       'sandbox',
       'keyboard-shortcuts',
+      'ui-mode',
     ])
   })