@cat-factory/app 0.6.0

package/app/types/execution.ts

@@ -0,0 +1,383 @@
+// ---------------------------------------------------------------------------
+// Execution model: a pipeline of agents running against a single block.
+// Mirrors the `@cat-factory/contracts` execution schemas.
+// ---------------------------------------------------------------------------
+
+import type { AgentKind, TestReport } from './domain'
+import type { ConsensusStepConfig } from './consensus'
+
+/**
+ * A quality companion's verdict on one producer output — the standardized shape every
+ * pipeline companion step stores, one per rework cycle.
+ */
+export interface CompanionVerdict {
+  /** Overall quality rating of the graded output (0..1, higher = better). */
+  rating: number
+  /** The quality bar the rating had to reach to pass. */
+  threshold: number
+  /** Whether the rating met the threshold. */
+  passed: boolean
+  /** The companion's challenge, shown to the human and fed into the next rework. */
+  feedback: string
+}
+
+/** Live companion state on a companion step: the bar, the budget, and every verdict. */
+export interface StepCompanion {
+  /** the quality bar (0..1) the latest verdict's rating must reach */
+  threshold: number
+  /** the automatic rework budget: once `attempts` reaches this the gate parks for a human */
+  maxAttempts: number
+  /** how many AUTOMATIC reworks have run (human "request changes" cycles don't count) */
+  attempts?: number
+  /** one verdict per correction cycle, in order; the last is the latest */
+  verdicts: CompanionVerdict[]
+  /**
+   * Set once the automatic rework budget is spent with the rating still below the bar:
+   * the step parks on its approval gate for a human to resolve via the iteration-cap
+   * prompt (one more round / proceed / stop & reset). Cleared on an extra round.
+   */
+  exceeded?: boolean
+}
+
+/**
+ * How a human resolves an iterative agent gate that hit its budget — shared by the
+ * requirements reviewer and the quality companions. Mirror of the backend's
+ * `IterationCapChoice` (see `@cat-factory/contracts` iteration-cap.ts).
+ */
+export type IterationCapChoice = 'extra-round' | 'proceed' | 'stop-reset'
+
+/** Runtime state of a single agent within a running execution. */
+export type AgentState =
+  | 'pending' // not started
+  | 'working' // actively (visually) working
+  | 'waiting_decision' // paused, needs a human decision
+  | 'done' // finished
+
+/** A decision an agent surfaces mid-step that a human must resolve. */
+export interface Decision {
+  id: string
+  question: string
+  options: string[]
+  chosen: string | null
+}
+
+/** One entry of a running step's todo list — its label and current status. */
+export interface StepSubtaskItem {
+  label: string
+  status: 'pending' | 'in_progress' | 'completed'
+}
+
+/** Live subtask counts a running step reports from the agent's own todo list. */
+export interface StepSubtasks {
+  completed: number
+  inProgress: number
+  total: number
+  /** The individual todo entries, so a zoomed-in card can show the actual list. */
+  items?: StepSubtaskItem[]
+}
+
+// ---------------------------------------------------------------------------
+// Shared "agent run" failure model. Both flows that run an agent in a container
+// — a task pipeline `execution` and a repo `bootstrap` — surface failures with
+// this shape, so the board renders one failure banner + retry for either. Mirrors
+// `agentFailureSchema` in `@cat-factory/contracts`.
+// ---------------------------------------------------------------------------
+
+/** The agent flows that produce a container-backed "agent run". */
+export type AgentRunKind = 'bootstrap' | 'execution'
+
+/** How an agent run faulted, so the board can classify it (and hint at a retry).
+ * The union spans both flows; a given flow only ever produces a subset. */
+export type AgentFailureKind =
+  | 'preflight'
+  | 'dispatch'
+  | 'evicted'
+  | 'timeout'
+  | 'agent'
+  | 'job_failed'
+  | 'rejected'
+  | 'cancelled'
+  | 'unknown'
+
+/** Structured diagnostics captured when an agent run fails. */
+export interface AgentFailure {
+  kind: AgentFailureKind
+  /** Human-readable summary (mirrors the run's one-line `error`). */
+  message: string
+  /** Extended detail when available (the harness's reason, an HTTP body, …). */
+  detail: string | null
+  /** Where to look next (e.g. "check the container logs for this job id"). */
+  hint: string | null
+  /** Epoch ms the failure was recorded. */
+  occurredAt: number
+  /** Last subtask counts seen before the failure, for context (null if none). */
+  lastSubtasks: StepSubtasks | null
+}
+
+/**
+ * One GitHub-review-style comment on a block of an agent's proposal (mirrors
+ * `stepReviewCommentSchema` in contracts). `quotedSource` is the verbatim raw
+ * markdown of the commented block, so a "request changes" re-run quotes the
+ * agent's own text back to it.
+ */
+export interface ReviewComment {
+  quotedSource: string
+  /** 0-based source line range [start, end) of the commented block. */
+  srcStart: number
+  srcEnd: number
+  body: string
+}
+
+/**
+ * A human approval gate on a step (mirrors `stepApprovalSchema` in contracts).
+ * Raised once a gated step's proposal is ready; the human reviews it in the
+ * conclusions reader, then approves (advance), requests changes (re-run with
+ * freeform feedback + per-block comments) or rejects (stop the run).
+ */
+export interface StepApproval {
+  id: string
+  status: 'pending' | 'approved' | 'changes_requested' | 'rejected'
+  /** the agent's output the human reviews */
+  proposal: string
+  /** the human's freeform guidance when changes were requested */
+  feedback?: string
+  /** per-block review comments when changes were requested */
+  comments?: ReviewComment[]
+}
+
+/**
+ * LLM observability rollup for a step (mirrors `stepMetricsSchema` in contracts):
+ * a compact aggregate over every model call the step's container made — token
+ * usage, how close it ran to the output-token limit (truncation), the latency
+ * split between transport/proxy overhead and actual model execution, and any
+ * errors/warnings. Absent when the observability sink is not wired.
+ */
+export interface StepMetrics {
+  calls: number
+  promptTokens: number
+  completionTokens: number
+  /** the largest single completion produced (closest approach to the limit) */
+  peakCompletionTokens: number
+  /** the output ceiling in effect (max requested max_tokens), or null when unknown */
+  maxOutputTokens: number | null
+  /** calls cut short by the output limit (finish_reason === 'length') */
+  truncatedCalls: number
+  /** sum of model execution time (ms) — the actual prompt/tool execution */
+  upstreamMs: number
+  /** sum of transport/proxy overhead (ms) — the interim-layer cost */
+  overheadMs: number
+  /** calls that failed (non-2xx / refused / in-process error) */
+  errors: number
+  /** successful calls that warned (truncated or content-filtered) */
+  warnings: number
+}
+
+/** One proxied LLM call's full detail (mirrors `llmCallMetricSchema` in contracts). */
+export interface LlmCallMetric {
+  id: string
+  workspaceId: string
+  executionId: string | null
+  agentKind: string
+  provider: string
+  model: string
+  createdAt: number
+  streaming: boolean
+  messageCount: number
+  toolCount: number
+  requestMaxTokens: number | null
+  promptTokens: number
+  /** prompt tokens served from the provider's prompt cache (subset of promptTokens) */
+  cachedPromptTokens: number
+  completionTokens: number
+  totalTokens: number
+  finishReason: string | null
+  upstreamMs: number
+  overheadMs: number
+  totalMs: number
+  ok: boolean
+  httpStatus: number | null
+  errorMessage: string | null
+  /**
+   * the request messages serialised as JSON, stored as a delta — only the messages
+   * this call appended beyond `promptPrefixCount` (the full array when that is 0)
+   */
+  promptText: string
+  /** leading messages elided from `promptText` (0 ⇒ it is the full array) */
+  promptPrefixCount: number
+  /** hash of the call's full messages array (chain key for the next call's delta) */
+  promptHash: string
+  /** the full assistant response text */
+  responseText: string
+  /**
+   * the model's reasoning/"thinking" trace on a separate channel, when emitted (empty
+   * for non-reasoning models). a thinking model can spend its whole output budget here
+   * and return empty `responseText`.
+   */
+  reasoningText: string
+}
+
+/**
+ * The compact per-call summary pushed live over the workspace stream (the `llmCall`
+ * event). It is {@link LlmCallMetric} WITHOUT the heavy text bodies and delta
+ * bookkeeping, so an open "Model activity" panel updates in real time without
+ * shipping prompt bytes. The panel lazy-loads the full bodies for an expanded row
+ * from the persisted metrics endpoint, keyed by the shared `id`. Mirrors
+ * `LlmCallActivity` in `@cat-factory/contracts`.
+ */
+export type LlmCallActivity = Omit<
+  LlmCallMetric,
+  'promptText' | 'responseText' | 'reasoningText' | 'promptPrefixCount' | 'promptHash'
+>
+
+/** One per-agent-kind insight in the LLM-friendly export (rollup + derived ratios). */
+export interface LlmExportInsight extends StepMetrics {
+  agentKind: string
+  /** peakCompletionTokens / maxOutputTokens, 0..1; null when the ceiling is unknown. */
+  outputHeadroomRatio: number | null
+  /** overheadMs / (upstreamMs + overheadMs), 0..1; the share spent in transport. */
+  transportOverheadRatio: number | null
+}
+
+/** LLM-friendly export of a run's model activity (mirrors `llmMetricsExportSchema`). */
+export interface LlmMetricsExport {
+  kind: 'cat-factory.llm-metrics-export'
+  version: 1
+  executionId: string
+  generatedAt: number
+  totals: {
+    calls: number
+    promptTokens: number
+    completionTokens: number
+    upstreamMs: number
+    overheadMs: number
+    transportOverheadRatio: number | null
+    errors: number
+    warnings: number
+    truncatedCalls: number
+  }
+  insights: LlmExportInsight[]
+  calls: LlmCallMetric[]
+}
+
+/** One agent's slot in a running pipeline. */
+export interface PipelineStep {
+  /**
+   * Id of the run this step belongs to (always the enclosing ExecutionInstance's id);
+   * surfaced on every step so a lone step is self-describing for debugging.
+   */
+  runId?: string
+  agentKind: AgentKind
+  state: AgentState
+  /** 0..1 progress of this individual step */
+  progress: number
+  /** LLM observability rollup for this step (token use, headroom, latency split). */
+  metrics?: StepMetrics | null
+  /** live "N/M done" subtask counts while an async (container) step runs */
+  subtasks?: StepSubtasks
+  /**
+   * True while a container-backed step's per-run container is cold-booting (set at
+   * dispatch, cleared once the container is up). Drives the "Spinning up container…"
+   * phase indicator before any execution progress is available.
+   */
+  startingContainer?: boolean
+  /** present + unresolved => the step (and block) is blocked */
+  decision: Decision | null
+  /** whether a human approval gate fires after this step (from the pipeline) */
+  requiresApproval?: boolean
+  /** the live approval gate for this step; pending => the run is blocked on a human */
+  approval?: StepApproval | null
+  /**
+   * Live companion state when this step is a companion kind: its quality bar, rework
+   * budget, and the full sequence of verdicts (one per correction cycle). Absent on
+   * non-companion steps.
+   */
+  companion?: StepCompanion | null
+  /**
+   * Consensus config for this step, copied from the pipeline at run start; present (with
+   * `enabled`) when the step runs through the multi-model consensus mechanism. Absent ⇒
+   * standard single-actor agent.
+   */
+  consensus?: ConsensusStepConfig | null
+  /** text the agent produced for this step (when LLM execution is enabled). */
+  output?: string
+  /** identifier of the model that produced `output`, for transparency. */
+  model?: string
+  /** prompt-fragment library ids folded into this step (manual ∪ selector pick). */
+  selectedFragmentIds?: string[]
+  /** epoch ms the step first began executing (transitioned to `working`). */
+  startedAt?: number | null
+  /** epoch ms the step finished (transitioned to `done`); with `startedAt` gives duration. */
+  finishedAt?: number | null
+  /**
+   * epoch ms the step parked on a human (approval / decision / iteration-cap gate),
+   * freezing its duration while it waits for input; cleared (null) once it resumes or
+   * finishes. The counterpart of `finishedAt` for the "waiting on input" freeze.
+   */
+  pausedAt?: number | null
+  /**
+   * Live Tester→Fixer loop state when this step is a `tester` kind: which phase is in
+   * flight (testing vs fixing the issues it found), the fixer attempt budget, and the
+   * latest structured test report. Absent on non-tester steps.
+   */
+  test?: TesterStepState | null
+  /**
+   * Live gate state when this step is a polling gate (`ci` / `conflicts`): which phase
+   * is in flight (checking the precheck vs a helper working), the helper attempt
+   * budget, the gated commit, and the latest precheck verdict + failure detail. Absent
+   * on non-gate steps. Mirrors `gateStepStateSchema`.
+   */
+  gate?: GateStepState | null
+}
+
+/** One failing CI check the gate's precheck saw (mirrors `gateFailingCheckSchema`). */
+export interface GateFailingCheck {
+  name: string
+  conclusion: string | null
+}
+
+/** Live state of a polling gate step (`ci` / `conflicts`); mirrors `gateStepStateSchema`. */
+export interface GateStepState {
+  phase: 'checking' | 'working'
+  /** how many helper-agent attempts have been dispatched so far */
+  attempts: number
+  /** ceiling on helper attempts (from the task's merge preset) */
+  maxAttempts: number
+  /** the PR head commit being gated, once resolved */
+  headSha?: string | null
+  /** the most recent precheck verdict (why the gate is looping vs idle-passing) */
+  lastVerdict?: 'pass' | 'pending' | 'fail' | null
+  /** human-readable summary of the latest failing precheck (failing checks / conflict reason) */
+  lastFailureSummary?: string | null
+  /** structured failing checks behind the summary (CI gate only; absent for conflicts) */
+  failingChecks?: GateFailingCheck[] | null
+}
+
+/** Live state of a `tester` step's Tester→Fixer loop (mirrors `testerStepStateSchema`). */
+export interface TesterStepState {
+  phase: 'testing' | 'fixing'
+  /** how many fixer attempts have been dispatched so far */
+  attempts: number
+  /** ceiling on fixer attempts (from the task's merge preset) */
+  maxAttempts: number
+  /** the most recent Tester report (what was tested, outcomes, concerns, greenlight) */
+  lastReport?: TestReport | null
+}
+
+/** A pipeline instance running against one block. */
+export interface ExecutionInstance {
+  id: string
+  blockId: string
+  pipelineId: string
+  pipelineName: string
+  steps: PipelineStep[]
+  /** index into steps of the currently active step */
+  currentStep: number
+  /**
+   * 'paused' = halted by the spend safeguard until the budget frees up;
+   * 'failed' = the run faulted (see `failure`) — surfaces the shared failure
+   * banner + retry, instead of the old success-looking `pr_ready` lie.
+   */
+  status: 'running' | 'blocked' | 'done' | 'paused' | 'failed'
+  /** Structured failure diagnostics when `status` is `failed`; null otherwise. */
+  failure?: AgentFailure | null
+}

package/app/types/fragments.ts

@@ -0,0 +1,72 @@
+// ---------------------------------------------------------------------------
+// Prompt-fragment library (ADR 0006). Mirrors the `@cat-factory/contracts`
+// fragment-library schemas: the managed, tenant-scoped catalog a workspace
+// resolves (built-in ∪ account ∪ workspace), plus the repo sources that feed it.
+// ---------------------------------------------------------------------------
+
+import type { AgentKind, BlockType } from './domain'
+import type { PromptFragment } from './models'
+
+/** Which scope owns a managed fragment / source. */
+export type FragmentOwnerKind = 'account' | 'workspace'
+
+/** The tier a resolved fragment originates from after override-by-id. */
+export type FragmentTier = 'builtin' | 'account' | 'workspace'
+
+/** Inputs for creating a hand-authored fragment at a tier. */
+export interface CreatePromptFragmentInput {
+  id?: string
+  title: string
+  category?: string
+  summary: string
+  body: string
+  tags?: string[]
+  appliesTo?: { blockTypes?: BlockType[]; agentKinds?: AgentKind[] }
+  version?: string
+}
+
+/** Partial patch for editing a fragment at a tier. */
+export type UpdatePromptFragmentInput = Partial<CreatePromptFragmentInput>
+
+/** A fragment after the three tiers are merged for a workspace. */
+export interface ResolvedFragment extends PromptFragment {
+  tier: FragmentTier
+}
+
+/** A repo directory linked as a source of Markdown guideline files. */
+export interface FragmentSource {
+  id: string
+  ownerKind: FragmentOwnerKind
+  ownerId: string
+  repoOwner: string
+  repoName: string
+  gitRef: string
+  dirPath: string
+  lastSyncedSha: string | null
+  lastSyncedAt: number | null
+  createdAt: number
+}
+
+/** Inputs for linking a repo directory as a fragment source. */
+export interface LinkFragmentSourceInput {
+  repoOwner: string
+  repoName: string
+  gitRef?: string
+  dirPath?: string
+}
+
+/** Outcome of resyncing a source. */
+export interface FragmentSyncResult {
+  upserted: number
+  tombstoned: number
+  unchanged: number
+  lastSyncedSha: string | null
+}
+
+/** Cheap "check for changes" result (no writes); powers the resync badge. */
+export interface FragmentSourceStatus {
+  changed: boolean
+  changedCount: number
+  lastSyncedSha: string | null
+  remoteSha: string | null
+}

package/app/types/github.ts

@@ -0,0 +1,173 @@
+// ---------------------------------------------------------------------------
+// GitHub integration. The backend's `GitHubModule` projects GitHub data
+// (repos/branches, pull requests/issues) into D1 and serves it fast and
+// rate-limit-free, alongside connect/resync/write endpoints. These mirror the
+// `@cat-factory/contracts` GitHub schemas so responses drop straight into the
+// Pinia store, just as the document-source types do for Confluence/Notion.
+// ---------------------------------------------------------------------------
+
+/** A workspace's GitHub App installation, as exposed to clients (no token). */
+export interface GitHubConnection {
+  installationId: number
+  accountLogin: string
+  targetType: 'Organization' | 'User'
+  connectedAt: number
+  /**
+   * Whether cat-factory can create repos under this account itself (privileged
+   * App tier). When true, the bootstrap UI drops the manual "create on GitHub"
+   * step. Defaults to false for older backends that don't send it.
+   */
+  canCreateRepos?: boolean
+  /**
+   * Whether the installation granted the App `workflows: write`. When false, agent
+   * pushes that add/update `.github/workflows/*` are rejected by GitHub, so the UI
+   * warns the user to grant the permission. Defaults to false for older backends.
+   */
+  canManageWorkflows?: boolean
+}
+
+/**
+ * A discoverable App installation for the connect picker. `connected` says
+ * whether it's already bound: to THIS workspace, to ANOTHER (so connecting would
+ * be rejected), or to NONE (free to connect).
+ */
+export interface GitHubInstallationOption {
+  installationId: number
+  accountLogin: string
+  targetType: 'Organization' | 'User'
+  accountAvatarUrl: string | null
+  connected: 'this' | 'other' | 'none'
+}
+
+/** A repository the integration tracks for a workspace. */
+export interface GitHubRepo {
+  githubId: number
+  installationId: number
+  owner: string
+  name: string
+  defaultBranch: string | null
+  private: boolean
+  /** Optional link to a board block this repo backs. */
+  blockId: string | null
+  /** Whether this repo is a monorepo hosting several services (each pinned to a subdirectory). */
+  isMonorepo?: boolean
+  syncedAt: number
+}
+
+/** One directory entry of a repo's tree, used by the monorepo service picker. */
+export interface RepoTreeEntry {
+  /** Path relative to the repo root, e.g. `packages/api`. */
+  path: string
+  /** Base name, e.g. `api`. */
+  name: string
+  /** `file` | `dir` | `symlink` | `submodule`. */
+  type: string
+}
+
+export interface GitHubBranch {
+  repoGithubId: number
+  name: string
+  headSha: string
+  protected: boolean
+  syncedAt: number
+}
+
+/**
+ * A repo the connected installation can access, annotated with whether the
+ * current workspace links it. Drives the per-workspace repo picker — repos are
+ * linked explicitly per board, since the installation is shared across an
+ * account's workspaces.
+ */
+export interface GitHubAvailableRepo {
+  githubId: number
+  owner: string
+  name: string
+  defaultBranch: string | null
+  private: boolean
+  linked: boolean
+  /** Whether the (linked) repo is flagged as a monorepo. */
+  isMonorepo?: boolean
+}
+
+export type GitHubPullRequestState = 'open' | 'closed'
+
+export interface GitHubPullRequest {
+  repoGithubId: number
+  number: number
+  githubId: number
+  title: string
+  state: GitHubPullRequestState
+  headRef: string | null
+  baseRef: string | null
+  headSha: string | null
+  merged: boolean
+  author: string | null
+  updatedAt: number | null
+  syncedAt: number
+}
+
+export type GitHubIssueState = 'open' | 'closed'
+
+export interface GitHubIssue {
+  repoGithubId: number
+  number: number
+  githubId: number
+  title: string
+  state: GitHubIssueState
+  author: string | null
+  labels: string[]
+  updatedAt: number | null
+  syncedAt: number
+}
+
+// ---- request inputs -------------------------------------------------------
+
+/** Trigger a resync. Defaults to an incremental resync of all tracked repos. */
+export interface ResyncRequest {
+  /** Limit the resync to a single repo (by its GitHub numeric id). */
+  repoGithubId?: number
+  /** Run a full backfill (durable Workflow) instead of an incremental pass. */
+  full?: boolean
+}
+
+export interface CreateBranchInput {
+  name: string
+  fromSha: string
+}
+
+/** Body for programmatic repo creation (privileged App tier). */
+export interface CreateRepoRequest {
+  /** A single GitHub name segment — no "owner/" prefix. */
+  name: string
+  private?: boolean
+  description?: string
+}
+
+/** The freshly-created repository returned by the create-repo endpoint. */
+export interface CreatedRepo {
+  githubId: number
+  owner: string
+  name: string
+  defaultBranch: string | null
+  private: boolean
+}
+
+export interface CommitFilesInput {
+  branch: string
+  message: string
+  files: { path: string; content: string }[]
+  /** Parent commit to build on; defaults to the branch tip. */
+  baseSha?: string
+}
+
+export interface OpenPullRequestInput {
+  title: string
+  head: string
+  base: string
+  body?: string
+  draft?: boolean
+}
+
+export interface MergePullRequestInput {
+  method?: 'merge' | 'squash' | 'rebase'
+}

package/app/types/localModels.ts

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// Per-user "local model runners" — a developer running cat-factory in local (or
+// self-hosted Node) mode can point agents at an LLM running on their OWN machine
+// (Ollama, LM Studio, llama.cpp, vLLM, or any OpenAI-compatible server). A runner
+// is just a provider id + a base URL, configured PER USER (a runner lives on a
+// person's machine) and surfaced automatically in the per-workspace model picker.
+//
+// Mirrors the `@cat-factory/contracts` `localModels` schemas exactly, so a payload
+// returned by the backend drops straight into the Pinia store without translation.
+// ---------------------------------------------------------------------------
+
+/** The supported local runner types. The runner type IS the `ModelRef.provider`. */
+export type LocalRunner = 'ollama' | 'lmstudio' | 'llamacpp' | 'vllm' | 'custom'
+
+/** Default base URL per runner, for UI prefill. `custom` has none (user supplies it). */
+export const LOCAL_RUNNER_DEFAULTS: Record<LocalRunner, string | null> = {
+  ollama: 'http://localhost:11434/v1',
+  lmstudio: 'http://localhost:1234/v1',
+  llamacpp: 'http://localhost:8080/v1',
+  vllm: 'http://localhost:8000/v1',
+  custom: null,
+}
+
+/** Short display label per runner, shown in the picker as the provider label. */
+export const LOCAL_RUNNER_LABELS: Record<LocalRunner, string> = {
+  ollama: 'Ollama',
+  lmstudio: 'LM Studio',
+  llamacpp: 'llama.cpp',
+  vllm: 'vLLM',
+  custom: 'Custom',
+}
+
+/**
+ * A user's configured local runner endpoint, as returned to the SPA. The API key is
+ * write-only (never returned); `hasApiKey` reports whether one is stored.
+ */
+export interface LocalModelEndpoint {
+  provider: LocalRunner
+  label: string
+  baseUrl: string
+  /** Whether a (write-only) API key is stored for this endpoint. */
+  hasApiKey: boolean
+  /** The model ids the user has enabled from this runner (surfaced in the picker). */
+  models: string[]
+  createdAt: number
+  updatedAt: number
+}
+
+/** Create or replace the signed-in user's endpoint for a runner (one per runner). */
+export interface UpsertLocalModelEndpointInput {
+  provider: LocalRunner
+  label?: string
+  baseUrl: string
+  /** Optional bearer key (most local runners ignore it); stored encrypted at rest. */
+  apiKey?: string
+  models: string[]
+}
+
+/** Probe a runner endpoint for reachability + the models it currently serves. */
+export interface TestLocalModelEndpointInput {
+  provider: LocalRunner
+  baseUrl: string
+  apiKey?: string
+}
+
+/** The result of probing a runner endpoint's `/models`. */
+export interface LocalModelEndpointTestResult {
+  reachable: boolean
+  /** Model ids the runner reports (empty when unreachable). */
+  models: string[]
+  /** Human-readable failure reason when `reachable` is false. */
+  error?: string
+}