@cat-factory/app 0.299.0 → 0.300.1

package/app/components/assistant/AssistantModal.logic.spec.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import { answerFor, revealTarget } from './AssistantModal.logic'
+
+describe('revealTarget', () => {
+  it('reveals the CONSUMER of a declared dependency, the frame the edge was written onto', () => {
+    expect(
+      revealTarget({
+        actionId: 'declare-service-dependency',
+        consumer: { blockId: 'f1', title: 'Checkout' },
+        provider: { blockId: 'f2', title: 'Payments' },
+        created: true,
+      }),
+    ).toBe('f1')
+  })
+
+  it('reveals the new service frame', () => {
+    expect(
+      revealTarget({
+        actionId: 'add-service-from-repo',
+        service: { blockId: 'f3', title: 'payments' },
+        repo: { owner: 'acme', name: 'payments', directory: null },
+        created: true,
+      }),
+    ).toBe('f3')
+  })
+
+  it('reveals the task, not the service it landed in', () => {
+    expect(
+      revealTarget({
+        actionId: 'create-task-from-issue',
+        task: { blockId: 't1', title: 'Card charges time out' },
+        service: { blockId: 'f2', title: 'Payments' },
+        issue: { source: 'github', externalId: 'acme/payments#12', url: 'https://example.test' },
+      }),
+    ).toBe('t1')
+  })
+})
+
+describe('answerFor', () => {
+  it('puts the chosen candidate in the field the platform named, keeping the rest', () => {
+    expect(
+      answerFor(
+        {
+          status: 'needs_input',
+          actionId: 'declare-service-dependency',
+          reason: 'ambiguous_service',
+          field: 'consumer',
+          candidates: ['Payments API', 'API Gateway'],
+          arguments: { consumer: 'api', provider: 'Ledger', description: 'reads balances' },
+        },
+        'Payments API',
+      ),
+    ).toEqual({
+      actionId: 'declare-service-dependency',
+      arguments: {
+        consumer: 'Payments API',
+        provider: 'Ledger',
+        description: 'reads balances',
+      },
+    })
+  })
+
+  it('answers a field the failed turn never resolved a value for', () => {
+    // The ambiguous-tracker case: `source` is absent from the arguments precisely because the
+    // request never named one, and the answer is what supplies it.
+    expect(
+      answerFor(
+        {
+          status: 'needs_input',
+          actionId: 'create-task-from-issue',
+          reason: 'ambiguous_issue_source',
+          field: 'source',
+          candidates: ['jira', 'linear'],
+          arguments: { issueUrl: 'PROJ-12' },
+        },
+        'jira',
+      ).arguments,
+    ).toEqual({ issueUrl: 'PROJ-12', source: 'jira' })
+  })
+})

package/app/components/assistant/AssistantModal.logic.ts

@@ -0,0 +1,45 @@
+import type { AssistantActionResult, AssistantAnswer, AssistantOutcome } from '~/types/domain'
+
+/**
+ * The block a performed turn should reveal on the board.
+ *
+ * Per action, the SUBJECT of what happened rather than the first id in the result: a filed task
+ * is the task, an added service is its frame, and a declared dependency is the CONSUMER, which is
+ * the frame the edge was written onto and the one whose panel shows it. Selecting the provider
+ * there would open the service that did not change.
+ *
+ * Exhaustive over the action union, so a fourth action fails to compile until it says what its
+ * turn produced. That is the point of extracting three lines: a `default` that fell back to some
+ * id would silently reveal the wrong block for whatever is added next.
+ */
+export function revealTarget(result: AssistantActionResult): string {
+  switch (result.actionId) {
+    case 'declare-service-dependency':
+      return result.consumer.blockId
+    case 'add-service-from-repo':
+      return result.service.blockId
+    case 'create-task-from-issue':
+      return result.task.blockId
+  }
+}
+
+/**
+ * The answer to a clarification, once a person has picked one of its candidates.
+ *
+ * The chosen value REPLACES the field the platform named and everything else is carried over
+ * untouched, so the next turn re-runs the same action with the one unresolved argument settled.
+ *
+ * Appending the candidate to the prompt and routing it again is what this replaces, and it could
+ * not terminate: the words that produced the question are still in the sentence (a repository
+ * under the wrong owner sits there beside the right one), and a candidate with no declared
+ * argument to land in is dropped on the way through.
+ */
+export function answerFor(
+  outcome: Extract<AssistantOutcome, { status: 'needs_input' }>,
+  candidate: string,
+): AssistantAnswer {
+  return {
+    actionId: outcome.actionId,
+    arguments: { ...outcome.arguments, [outcome.field]: candidate },
+  }
+}

package/app/components/assistant/AssistantModal.vue

@@ -0,0 +1,260 @@
+<script setup lang="ts">
+// The in-app assistant: type what you want done, and the platform does it.
+//
+// The whole surface is one prompt box and one OUTCOME, and the outcome is rendered from the
+// turn's DATA rather than from anything a model wrote. That is not a stylistic choice: the
+// backend deliberately puts no model prose on the wire (a turn answers with the action it
+// performed, or a machine-readable reason it could not), so every sentence here comes out of the
+// i18n catalog and reads the same in every locale.
+//
+// Two of the three outcomes are not failures and must not look like one:
+//   - `needs_input` is a QUESTION. Where the platform had candidates (two services matching the
+//     name, a repository under a different owner, two trackers that both read the reference) each
+//     is a chip that ANSWERS it: one click re-runs the same action with that value in the field
+//     the platform named, with no model call and nothing retyped.
+//   - `declined` means nothing in the catalog matches. It renders the catalog, because "I can't
+//     do that" without saying what it CAN do is the least useful answer this surface can give.
+// Everything that IS a failure (no model wired, the budget spent, an unconfigured tracker, an
+// issue already filed) arrives as an error and goes through the shared toast funnel with its
+// reason, its detail and its request id, the same path a failed button press takes.
+import type { AssistantActionId, AssistantOutcome } from '~/types/domain'
+import { answerFor, revealTarget } from './AssistantModal.logic'
+
+const { t } = useI18n()
+const ui = useUiStore()
+const assistant = useAssistantStore()
+const { present } = usePipelineErrorToast()
+
+const open = computed({
+  get: () => ui.assistantOpen,
+  set: (value: boolean) => (value ? ui.openAssistant() : ui.closeAssistant()),
+})
+
+const prompt = ref('')
+
+/** The outcome of the last turn, or null before the first one / after the prompt is edited. */
+const outcome = computed<AssistantOutcome | null>(() => assistant.turn?.outcome ?? null)
+
+/** The example prompts offered as a starting point, one per action this deployment can perform. */
+const examples = computed(() =>
+  assistant.actions.map((actionId: AssistantActionId) => ({
+    actionId,
+    label: t(`assistant.actions.${actionId}.label`),
+    example: t(`assistant.actions.${actionId}.example`),
+  })),
+)
+
+// Read the capability on open rather than on mount: the modal is lazily loaded, and a deployment
+// that wires a provider while the tab is open should not have to be reloaded to offer the box.
+watch(open, (isOpen) => {
+  if (!isOpen) return
+  assistant.reset()
+  void assistant.loadCapability().catch((error: unknown) => present(error, 'assistant.title'))
+})
+
+/** Editing the prompt clears the previous answer, so an outcome never sits under a new question. */
+watch(prompt, () => {
+  if (outcome.value) assistant.reset()
+})
+
+const canSubmit = computed(
+  () => assistant.available && !assistant.running && prompt.value.trim().length > 0,
+)
+
+async function submit(): Promise<void> {
+  if (!canSubmit.value) return
+  try {
+    await assistant.run(prompt.value.trim())
+  } catch (error) {
+    present(error, 'assistant.title')
+  }
+}
+
+/** Put an example in the box, ready to edit, never submitted for the person. */
+function useExample(example: string): void {
+  prompt.value = example
+  assistant.reset()
+}
+
+/**
+ * Answer a clarification with one of the candidates the platform offered.
+ *
+ * Submitted as DATA, not as more prose: the turn re-runs the action it was already heading for
+ * with the chosen value in the field it named. Appending the candidate to the sentence and asking
+ * the model again is what this replaces, and it could not settle the question (see `answerFor`).
+ * The prompt box is left exactly as the person typed it, because the request has not changed.
+ */
+async function useCandidate(
+  question: Extract<AssistantOutcome, { status: 'needs_input' }>,
+  candidate: string,
+): Promise<void> {
+  if (assistant.running) return
+  try {
+    await assistant.answer(answerFor(question, candidate))
+  } catch (error) {
+    present(error, 'assistant.title')
+  }
+}
+
+/** Select what a performed turn produced, and close, so the board shows it straight away. */
+function reveal(blockId: string): void {
+  ui.select(blockId)
+  ui.focus(blockId)
+  ui.closeAssistant()
+}
+</script>
+
+<template>
+  <UModal v-model:open="open" :title="t('assistant.title')" :ui="{ content: 'max-w-2xl' }">
+    <template #body>
+      <div class="space-y-4">
+        <p class="text-sm text-slate-400">{{ t('assistant.intro') }}</p>
+
+        <!-- No model wired: say so, rather than offering a box whose every submit would 503. -->
+        <div
+          v-if="assistant.capability && !assistant.available"
+          class="flex items-start gap-2 rounded-md bg-slate-800/60 p-3 text-sm text-slate-300"
+        >
+          <UIcon name="i-lucide-plug" class="mt-0.5 h-4 w-4 shrink-0 text-slate-500" />
+          <span>{{ t('assistant.unavailable') }}</span>
+        </div>
+
+        <template v-else>
+          <UTextarea
+            v-model="prompt"
+            :rows="3"
+            autofocus
+            :disabled="assistant.running"
+            :placeholder="t('assistant.placeholder')"
+            data-testid="assistant-prompt"
+            @keydown.enter.meta.prevent="submit"
+            @keydown.enter.ctrl.prevent="submit"
+          />
+
+          <div class="flex flex-wrap items-center gap-2">
+            <UButton
+              color="primary"
+              icon="i-lucide-sparkles"
+              :loading="assistant.running"
+              :disabled="!canSubmit"
+              data-testid="assistant-submit"
+              @click="submit"
+            >
+              {{ t('assistant.submit') }}
+            </UButton>
+            <span class="text-xs text-slate-500">{{ t('assistant.submitHint') }}</span>
+          </div>
+
+          <!-- What it can do, always visible: the catalog is the affordance. -->
+          <div v-if="examples.length" class="space-y-2">
+            <p class="text-xs font-medium uppercase tracking-wide text-slate-500">
+              {{ t('assistant.examplesTitle') }}
+            </p>
+            <div class="flex flex-col gap-1">
+              <button
+                v-for="entry in examples"
+                :key="entry.actionId"
+                type="button"
+                class="rounded-md px-2 py-1 text-left text-sm text-slate-300 hover:bg-slate-800"
+                @click="useExample(entry.example)"
+              >
+                <span class="text-slate-400">{{ entry.label }}</span>
+                <span class="block text-xs text-slate-500">“{{ entry.example }}”</span>
+              </button>
+            </div>
+          </div>
+
+          <!-- The outcome. Rendered from the turn's data; no model prose reaches this. -->
+          <div
+            v-if="outcome"
+            class="rounded-md border border-slate-700 p-3 text-sm"
+            data-testid="assistant-outcome"
+          >
+            <template v-if="outcome.status === 'performed'">
+              <div class="flex items-start gap-2 text-slate-200">
+                <UIcon name="i-lucide-check" class="mt-0.5 h-4 w-4 shrink-0 text-emerald-400" />
+                <div class="space-y-2">
+                  <p v-if="outcome.result.actionId === 'declare-service-dependency'">
+                    {{
+                      t(
+                        outcome.result.created
+                          ? 'assistant.done.dependencyDeclared'
+                          : 'assistant.done.dependencyAlready',
+                        {
+                          consumer: outcome.result.consumer.title,
+                          provider: outcome.result.provider.title,
+                        },
+                      )
+                    }}
+                  </p>
+                  <p v-else-if="outcome.result.actionId === 'add-service-from-repo'">
+                    {{
+                      t(
+                        outcome.result.created
+                          ? 'assistant.done.serviceAdded'
+                          : 'assistant.done.serviceMounted',
+                        {
+                          service: outcome.result.service.title,
+                          repo: `${outcome.result.repo.owner}/${outcome.result.repo.name}`,
+                        },
+                      )
+                    }}
+                  </p>
+                  <p v-else>
+                    {{
+                      t('assistant.done.taskCreated', {
+                        task: outcome.result.task.title,
+                        service: outcome.result.service.title,
+                        issue: outcome.result.issue.externalId,
+                      })
+                    }}
+                  </p>
+                  <UButton
+                    size="xs"
+                    variant="soft"
+                    icon="i-lucide-crosshair"
+                    @click="reveal(revealTarget(outcome.result))"
+                  >
+                    {{ t('assistant.showOnBoard') }}
+                  </UButton>
+                </div>
+              </div>
+            </template>
+
+            <template v-else-if="outcome.status === 'needs_input'">
+              <div class="flex items-start gap-2 text-slate-200">
+                <UIcon name="i-lucide-help-circle" class="mt-0.5 h-4 w-4 shrink-0 text-amber-400" />
+                <div class="space-y-2">
+                  <p>{{ t(`assistant.needsInput.${outcome.reason}`) }}</p>
+                  <div v-if="outcome.candidates.length" class="flex flex-wrap gap-1">
+                    <UButton
+                      v-for="candidate in outcome.candidates"
+                      :key="candidate"
+                      size="xs"
+                      variant="soft"
+                      :disabled="assistant.running"
+                      data-testid="assistant-candidate"
+                      @click="useCandidate(outcome, candidate)"
+                    >
+                      {{ candidate }}
+                    </UButton>
+                  </div>
+                </div>
+              </div>
+            </template>
+
+            <template v-else>
+              <div class="flex items-start gap-2 text-slate-200">
+                <UIcon
+                  name="i-lucide-circle-slash"
+                  class="mt-0.5 h-4 w-4 shrink-0 text-slate-500"
+                />
+                <p>{{ t('assistant.declined') }}</p>
+              </div>
+            </template>
+          </div>
+        </template>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/outcome/OutcomeSummaryWindow.vue

@@ -141,6 +141,7 @@ const TESTS_GAP_KEYS: Record<TestsGap, string> = {
   run_unavailable: RUN_UNAVAILABLE_KEY,
   no_tester_step: 'outcome.tests.gap.no_tester_step',
   tester_not_reported: 'outcome.tests.gap.tester_not_reported',
+  verified_by_committed_tests: 'outcome.tests.gap.verified_by_committed_tests',
 }
 const SOURCES_GAP_KEYS: Record<SourcesGap, string> = {
   run_unavailable: RUN_UNAVAILABLE_KEY,

package/app/composables/api/assistant.ts

@@ -0,0 +1,29 @@
+import { getAssistantCapabilityContract, runAssistantTurnContract } from '@cat-factory/contracts'
+import type { AssistantAnswer } from '~/types/domain'
+import type { ApiContext } from './context'
+
+/** In-app assistant: what it can do here, and one prompt-to-action turn. */
+export function assistantApi({ send, ws }: ApiContext) {
+  return {
+    // Whether a model is wired and which actions this deployment offers. Read before the prompt
+    // box is shown, so an unconfigured deployment says so instead of failing on submit.
+    getAssistantCapability: (workspaceId: string) =>
+      send(getAssistantCapabilityContract, { pathPrefix: ws(workspaceId) }),
+
+    // Run one turn. A live model call plus a board write, so it can take a couple of seconds:
+    // the modal shows progress and the outcome is rendered from the returned data.
+    runAssistantTurn: (workspaceId: string, prompt: string) =>
+      send(runAssistantTurnContract, {
+        pathPrefix: ws(workspaceId),
+        body: { kind: 'prompt', prompt },
+      }),
+
+    // Answer a question the last turn asked. The same endpoint, and deliberately: it performs one
+    // catalog action exactly as a prompt does. It reaches no model, so it is the fast half.
+    answerAssistantTurn: (workspaceId: string, answer: AssistantAnswer) =>
+      send(runAssistantTurnContract, {
+        pathPrefix: ws(workspaceId),
+        body: { kind: 'answer', answer },
+      }),
+  }
+}

package/app/composables/useApi.ts

@@ -54,6 +54,7 @@ import { reviewsApi } from './api/reviews'
 import { slackApi } from './api/slack'
 import { specApi } from './api/spec'
 import { tasksApi } from './api/tasks'
+import { assistantApi } from './api/assistant'
 import { bugHuntApi } from './api/bugHunt'
 import { testSecretsApi } from './api/testSecrets'
 import { userSecretsApi } from './api/userSecrets'
@@ -131,6 +132,7 @@ export function useApi() {
     ...executionApi(ctx),
     ...documentsApi(ctx),
     ...tasksApi(ctx),
+    ...assistantApi(ctx),
     ...bugHuntApi(ctx),
     ...reviewsApi(ctx),
     ...followUpsApi(ctx),

package/app/composables/useNavContributions.ts

@@ -40,6 +40,7 @@ export function useNavContributions() {
   // with no catalog entry) is a compile error, not a silently dead button.
   // Consumer items bypass this map entirely via their own `run` closure.
   const actions: Record<NavActionId, () => void> = {
+    assistant: () => ui.openAssistant(),
     buildPipeline: () => ui.openBuilder(),
     addFromRepo: () => ui.openAddService(),
     bootstrapRepo: () => ui.openBootstrap(),

package/app/composables/usePipelineErrorToast.ts

@@ -440,6 +440,8 @@ const REASON_DESCRIPTION_KEYS: Record<UnavailableReason | BootstrapReferenceReas
   service_catalog_filter_missing: 'errors.unavailable.description.service_catalog_filter_missing',
   service_catalog_response_too_large:
     'errors.unavailable.description.service_catalog_response_too_large',
+  assistant_generation_failed: 'errors.unavailable.description.assistant_generation_failed',
+  assistant_reply_unreadable: 'errors.unavailable.description.assistant_reply_unreadable',
 }
 
 /**

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

@@ -219,6 +219,8 @@ describe('navSlotFilter', () => {
     // surface has quietly stopped being simple. The table is the claim; adding `intake: true`
     // fails here until the reason is written down.
     const REASON: Record<string, string> = {
+      assistant:
+        'the shortest route to the two things this role is here to do (put a repository on the board, file a task from a ticket) and it configures nothing',
       tutorial: 'the walkthroughs - the surface with the fewest destinations needs them most',
       'keyboard-shortcuts': 'the cheatsheet covers the board and the palette, which every role has',
       'ui-role': 'the way BACK out of the narrowed role',

package/app/modular/nav-contributions.ts

@@ -196,6 +196,7 @@ export interface NavCommandSpec {
  * dead button. Consumer modules don't use these — they carry their own `run`.
  */
 export const NAV_ACTIONS = [
+  'assistant',
   'buildPipeline',
   'addFromRepo',
   'bootstrapRepo',
@@ -341,6 +342,27 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  * the whole sidebar costs it nothing it is there to do.
  */
 export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
+  {
+    // The in-app assistant. `intake: true` and not `advanced`, because it is the shortest route
+    // to the two things a narrowed role is on the board to do (put a repository on it, file a
+    // task from a ticket) and it configures nothing: every action behind it is a board write the
+    // member tier already allows, refused server-side for anyone it should not be.
+    id: 'assistant',
+    labelKey: 'nav.assistant',
+    icon: 'i-lucide-sparkles',
+    surfaces: S('sidebar', 'command'),
+    gate: (g) => g.canWriteBoard,
+    action: 'assistant',
+    intake: true,
+    testId: 'nav-assistant',
+    sidebar: { group: 'create', order: 5 },
+    command: {
+      group: 'create',
+      order: 5,
+      labelKey: 'layout.commandBar.cmd.assistant',
+      keywordsKey: 'layout.commandBar.keywords.assistant',
+    },
+  },
   {
     id: 'build-pipeline',
     labelKey: 'nav.buildPipeline',

package/app/pages/index.vue

@@ -48,6 +48,7 @@ const TaskSourceConnectModal = defineAsyncView(
 )
 const TaskImportModal = defineAsyncView(() => import('~/components/tasks/TaskImportModal.vue'))
 const BugHuntModal = defineAsyncView(() => import('~/components/tasks/BugHuntModal.vue'))
+const AssistantModal = defineAsyncView(() => import('~/components/assistant/AssistantModal.vue'))
 const RecurringPipelineModal = defineAsyncView(
   () => import('~/components/board/RecurringPipelineModal.vue'),
 )
@@ -501,6 +502,7 @@ watch(
         <TaskSourceConnectModal v-if="ui.taskConnect" />
         <TaskImportModal v-if="ui.taskImport" />
         <BugHuntModal v-if="ui.bugHunt" />
+        <AssistantModal v-if="ui.assistantOpen" />
         <RecurringPipelineModal v-if="ui.addRecurringFrameId" />
         <ObservabilityPanel v-if="ui.observabilityInstanceId" />
         <OperatorDashboardPanel v-if="ui.operatorDashboardOpen" />

package/app/stores/assistant.ts

@@ -0,0 +1,69 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type { AssistantAnswer, AssistantCapability, AssistantTurn } from '~/types/domain'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * In-app assistant state: what this deployment's assistant can do, and the last turn's outcome.
+ *
+ * Nothing is persisted server-side and nothing accumulates here: a turn is one prompt and one
+ * outcome, and the board itself is where the result lives afterwards (the write arrives over the
+ * live stream like any other, so the frame or task shows up without this store touching the board).
+ * Keeping a transcript would be a second, staler record of changes the board already carries.
+ *
+ * Failures are NOT held here: every refusal a turn can raise is a `DomainError` the shared error
+ * funnel (`usePipelineErrorToast`) already renders translated, copyable and with its request id.
+ * The three OUTCOMES are the ones this store keeps, because they are answers rather than errors.
+ */
+export const useAssistantStore = defineStore('assistant', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+
+  const capability = ref<AssistantCapability | null>(null)
+  const turn = ref<AssistantTurn | null>(null)
+  const running = ref(false)
+
+  /** Whether a model is wired at all; unknown (not yet read) reads as unavailable. */
+  const available = computed(() => capability.value?.available === true)
+  const actions = computed(() => capability.value?.actions ?? [])
+
+  /** Read what the assistant can do here. Idempotent: re-reading replaces the answer. */
+  async function loadCapability(): Promise<void> {
+    capability.value = await api.getAssistantCapability(workspace.requireId())
+  }
+
+  /**
+   * Run one turn. Throws on a refusal so the caller can hand it to the error funnel; the three
+   * outcomes (performed / needs_input / declined) come back as the resolved value.
+   */
+  async function run(prompt: string): Promise<AssistantTurn> {
+    return record(() => api.runAssistantTurn(workspace.requireId(), prompt))
+  }
+
+  /**
+   * Answer the question the last turn asked, by re-running its action with the chosen value in the
+   * field it named. Same outcomes, same funnel, and no model call.
+   */
+  async function answer(chosen: AssistantAnswer): Promise<AssistantTurn> {
+    return record(() => api.answerAssistantTurn(workspace.requireId(), chosen))
+  }
+
+  /** The half both turns share: hold `running`, keep the outcome, let a refusal through. */
+  async function record(send: () => Promise<AssistantTurn>): Promise<AssistantTurn> {
+    running.value = true
+    try {
+      const result = await send()
+      turn.value = result
+      return result
+    } finally {
+      running.value = false
+    }
+  }
+
+  /** Forget the last outcome (the modal closing, or a fresh prompt being typed). */
+  function reset(): void {
+    turn.value = null
+  }
+
+  return { capability, turn, running, available, actions, loadCapability, run, answer, reset }
+})

package/app/stores/ui/modals.ts

@@ -216,6 +216,11 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
   // the create-in target AND scopes the issue search to the frame's linked repo.
   // Null → the unscoped "import an issue" surface (workspace-wide search).
   const taskImport = ref<{ source: TaskSourceKind | null; containerId: string | null } | null>(null)
+  // In-app assistant: the prompt box that routes one sentence to one board action. It carries no
+  // subject (a turn resolves every name it needs from the board itself), so a plain flag says
+  // everything the host needs to know.
+  const assistantOpen = ref(false)
+
   // Bug hunt: pick a tracker + one of its boards, rank its open unassigned bugs, adopt one.
   // `containerId` (a service frame or module) preselects where an adopted bug lands; null →
   // opened standalone, and the modal offers every container on the board.
@@ -293,6 +298,13 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
   function closeTaskImport() {
     taskImport.value = null
   }
+  function openAssistant() {
+    resetHubReturn()
+    assistantOpen.value = true
+  }
+  function closeAssistant() {
+    assistantOpen.value = false
+  }
   function openBugHunt(source: TaskSourceKind | null = null, containerId: string | null = null) {
     resetHubReturn()
     bugHunt.value = { source, containerId }
@@ -341,6 +353,7 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
     spawnPreview,
     taskConnect,
     taskImport,
+    assistantOpen,
     bugHunt,
     startFromDesign,
     addTaskContainerId,
@@ -360,6 +373,8 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
     closeTaskConnect,
     openTaskImport,
     closeTaskImport,
+    openAssistant,
+    closeAssistant,
     openBugHunt,
     closeBugHunt,
     openStartFromDesign,

package/app/types/assistant.ts

@@ -0,0 +1,24 @@
+// ---------------------------------------------------------------------------
+// The in-app assistant: one natural-language prompt, one action the platform performs on the
+// person's behalf (declare a service dependency, add a service from a repository URL, file a task
+// from a tracker issue).
+//
+// A turn answers with DATA, never with model prose: the outcome variant carries the ids and names
+// of what was touched, or the machine-readable reason it could not act, and the SPA renders every
+// sentence from those members through the i18n catalog. All wire shapes are sourced from
+// @cat-factory/contracts (single source of truth).
+// ---------------------------------------------------------------------------
+
+export type {
+  AssistantActionId,
+  AssistantActionResult,
+  AssistantAnswer,
+  AssistantArguments,
+  AssistantCapability,
+  AssistantClarificationReason,
+  AssistantDeclineReason,
+  AssistantOutcome,
+  AssistantServiceRef,
+  AssistantTurn,
+  AssistantTurnInput,
+} from '@cat-factory/contracts'

package/app/types/domain.ts

@@ -220,6 +220,7 @@ export type * from './skills'
 export type * from './foundationalServices'
 export type * from './documents'
 export type * from './tasks'
+export type * from './assistant'
 export type * from './bugHunt'
 export type * from './bootstrap'
 export type * from './envConfigRepair'