@adhdev/daemon-core 0.9.82-rc.15 → 0.9.82-rc.151

package/src/providers/read-chat-contract.ts

@@ -1,8 +1,16 @@
 import type { MessagePart, ModalInfo, ReadChatResult } from './contracts.js'
 import { normalizeMessageParts } from './contracts.js'
 import type { ChatBubbleState, ChatMessage } from '../types.js'
-
-const VALID_STATUSES = ['idle', 'generating', 'waiting_approval', 'error', 'panel_hidden', 'streaming', 'long_generating'] as const
+import {
+  CHAT_CONTRACT_VERSION_V1,
+  CHAT_CONTRACT_VERSION_V2,
+  assertReadChatResultV2Payload,
+  isSupportedChatContractVersion,
+  type ChatContractVersion,
+  type ReadChatResultV2,
+} from './transcript-v2.js'
+
+const VALID_STATUSES = ['idle', 'generating', 'waiting_approval', 'error', 'panel_hidden', 'starting', 'streaming', 'long_generating'] as const
 const VALID_ROLES = ['user', 'assistant', 'system', 'human'] as const
 const VALID_BUBBLE_STATES = ['draft', 'streaming', 'final', 'removed'] as const
 const VALID_TURN_STATUSES = ['open', 'waiting_approval', 'complete', 'error'] as const
@@ -63,7 +71,7 @@ function validateMessage(message: unknown, source: string, index: number): ChatM
     content: validateMessageContent(message.content, source, index),
   }
 
-  if (typeof message.kind === 'string') normalized.kind = message.kind as any
+  if (typeof message.kind === 'string') normalized.kind = message.kind as ChatMessage['kind']
   if (typeof message.id === 'string') normalized.id = message.id
   if (typeof message.bubbleId === 'string') normalized.bubbleId = message.bubbleId
   if (typeof message.providerUnitKey === 'string') normalized.providerUnitKey = message.providerUnitKey
@@ -71,20 +79,23 @@ function validateMessage(message: unknown, source: string, index: number): ChatM
   if (isFiniteNumber(message.index)) normalized.index = message.index
   if (isFiniteNumber(message.timestamp)) normalized.timestamp = message.timestamp
   if (isFiniteNumber(message.receivedAt)) normalized.receivedAt = message.receivedAt
-  if (typeof (message as any)._turnKey === 'string') normalized._turnKey = (message as any)._turnKey
-  if (Array.isArray(message.toolCalls)) normalized.toolCalls = message.toolCalls as any
-  if (isPlainObject(message.meta)) normalized.meta = message.meta as any
+  // (A2.3) sequence is the monotonic ordering key consumed by ChatSourceMachine.
+  // v1 producers omit it; the daemon derives it in normalizeNativeHistoryMessages.
+  if (isFiniteNumber(message.sequence)) normalized.sequence = message.sequence
+  if (typeof message._turnKey === 'string') normalized._turnKey = message._turnKey
+  if (Array.isArray(message.toolCalls)) normalized.toolCalls = message.toolCalls as ChatMessage['toolCalls']
+  if (isPlainObject(message.meta)) normalized.meta = message.meta as ChatMessage['meta']
   if (typeof message.senderName === 'string') normalized.senderName = message.senderName
-  if (typeof (message as any)._type === 'string') normalized._type = (message as any)._type
-  if (typeof (message as any)._sub === 'string') normalized._sub = (message as any)._sub
-  if (typeof (message as any).visibility === 'string') normalized.visibility = (message as any).visibility
-  if (typeof (message as any).transcriptVisibility === 'string') normalized.transcriptVisibility = (message as any).transcriptVisibility
-  if (typeof (message as any).audience === 'string') normalized.audience = (message as any).audience
-  if (typeof (message as any).source === 'string') normalized.source = (message as any).source
-  if (typeof (message as any).userFacing === 'boolean') normalized.userFacing = (message as any).userFacing
-  if (typeof (message as any).internal === 'boolean') normalized.internal = (message as any).internal
-  if (typeof (message as any).isInternal === 'boolean') normalized.isInternal = (message as any).isInternal
-  if (typeof (message as any).debug === 'boolean') normalized.debug = (message as any).debug
+  if (typeof message._type === 'string') normalized._type = message._type
+  if (typeof message._sub === 'string') normalized._sub = message._sub
+  if (typeof message.visibility === 'string') normalized.visibility = message.visibility
+  if (typeof message.transcriptVisibility === 'string') normalized.transcriptVisibility = message.transcriptVisibility
+  if (typeof message.audience === 'string') normalized.audience = message.audience
+  if (typeof message.source === 'string') normalized.source = message.source
+  if (typeof message.userFacing === 'boolean') normalized.userFacing = message.userFacing
+  if (typeof message.internal === 'boolean') normalized.internal = message.internal
+  if (typeof message.isInternal === 'boolean') normalized.isInternal = message.isInternal
+  if (typeof message.debug === 'boolean') normalized.debug = message.debug
 
   return normalized
 }
@@ -129,6 +140,55 @@ function validateControlValues(controlValues: unknown, source: string): Record<s
   return normalized
 }
 
+/**
+ * Read the producer-declared contract version from a raw read_chat payload.
+ * Returns v1 when absent or unrecognised, so legacy producers keep working
+ * through A1. A2 will tighten this to throw when an unsupported version is
+ * declared.
+ */
+export function readPayloadContractVersion(raw: unknown): ChatContractVersion {
+  if (!isPlainObject(raw)) return CHAT_CONTRACT_VERSION_V1
+  const declared = (raw as Record<string, unknown>).contractVersion
+  if (isSupportedChatContractVersion(declared)) return declared
+  return CHAT_CONTRACT_VERSION_V1
+}
+
+/**
+ * Validate a v2 payload. Thin wrapper around assertReadChatResultV2Payload
+ * that prefixes the contract violation with the caller's source label.
+ */
+export function validateReadChatResultV2Payload(raw: unknown, source = 'read_chat'): ReadChatResultV2 {
+  try {
+    return assertReadChatResultV2Payload(raw)
+  } catch (err) {
+    if (err instanceof Error) {
+      err.message = `${source}: ${err.message}`
+    }
+    throw err
+  }
+}
+
+/**
+ * Versioned entry point. Routes on the producer-declared contractVersion:
+ *   - v2 → strict v2 validation (transcript-v2.ts invariants)
+ *   - v1 (or absent) → legacy permissive validation
+ *
+ * Callers that have not yet been audited to handle v2 outputs should use
+ * validateReadChatResultPayload directly; that path stays bound to v1 shape
+ * during the A1 transition.
+ */
+export function validateReadChatResultPayloadVersioned(
+  raw: unknown,
+  source = 'read_chat',
+): { version: typeof CHAT_CONTRACT_VERSION_V1; payload: ReadChatResult & Record<string, unknown> }
+  | { version: typeof CHAT_CONTRACT_VERSION_V2; payload: ReadChatResultV2 } {
+  const version = readPayloadContractVersion(raw)
+  if (version === CHAT_CONTRACT_VERSION_V2) {
+    return { version, payload: validateReadChatResultV2Payload(raw, source) }
+  }
+  return { version: CHAT_CONTRACT_VERSION_V1, payload: validateReadChatResultPayload(raw, source) }
+}
+
 export function validateReadChatResultPayload(raw: unknown, source = 'read_chat'): ReadChatResult & Record<string, unknown> {
   if (!isPlainObject(raw)) {
     throw new Error(`${source}: payload must be an object`)

package/src/providers/sdk/README.md

@@ -0,0 +1,49 @@
+# Provider SDK
+
+> Status: Phase 1 in progress · License of this directory: AGPL-3.0 (part of `oss/`) · See [marketplace plan](../../../../../../docs/design/v1.0.0-marketplace-plan.md).
+
+This directory is the **Provider SDK** — the framework that lets external developers author CLI providers (and later IDE, Extension, ACP) against a versioned, typed contract.
+
+It lives **inside daemon-core**, not as a separate package, by design:
+
+- the contract definitions live next to the runtime that consumes them, eliminating version drift
+- `adhdev provider *` CLI commands call straight into these modules
+- two npm packages are extracted from this source at build time:
+  - `@adhdev/provider-types` (Apache 2.0) — TypeScript types for external authors
+  - `@adhdev/provider-schemas` (Apache 2.0) — JSON Schemas for editor support
+
+## Layout
+
+```
+sdk/
+  v1/                                  ← contract version 1 (current)
+    types/                             ← TypeScript types — extracted to @adhdev/provider-types
+      cli/                             ← CLI category types
+      common/                          ← shared types (settings, capabilities, auth, spawn)
+    schemas/                           ← JSON Schemas — extracted to @adhdev/provider-schemas
+      cli/
+        provider.schema.json           ← top-level provider.json (mirrors adhdev-providers/schemas/v1/cli/)
+      primitives/                      ← per-primitive schemas, namespaced by category
+      common/
+    primitives/                        ← daemon-side primitive implementations
+      cli/                             ← TUI primitives, native-history adapters, capability handlers
+    builders/                          ← functions that turn manifest blocks into runtime handlers
+    validators/                        ← schema check, AST taint analysis, fixture replay
+    scaffolders/                       ← `adhdev provider init` templates
+    fixture-tooling/                   ← PTY capture + replay utilities
+  v2/                                  ← reserved for next contract major
+```
+
+## Primitive identifiers
+
+Primitives are referenced by `$schema: adhdev:<category>/<id>@<version>` in provider manifests. See the audit-derived v1 catalog of 50 primitives at [`audit-cli-v1.md §5`](../../../../../../../adhdev-providers/docs/provider-contract/cli/audit-cli-v1.md#5-proposed-v1-primitive-set).
+
+## Stability
+
+`v1/` is unstable until SDK `1.0.0` is published. Breaking changes between SDK `0.x` releases are permitted during Phase 1-2 migration. After SDK `1.0.0`, breaking changes require an `engines.adhdev` major bump.
+
+## Out of scope
+
+- This SDK does not provide IDE, Extension, or ACP primitives in v1.0.0. They follow in v1.1+.
+- This SDK does not include the registry server code — that lives in [`oss/packages/registry/`](../../../../../registry/) (not yet created).
+- This SDK does not include the marketplace web UI — that lives separately.

package/src/providers/sdk/v1/builders/acp/detect-status.ts

@@ -0,0 +1,144 @@
+/**
+ * buildDetectStatusFromAcp
+ *
+ * Turns a declarative `acp/session-protocol@1` block into a runtime
+ * `(input: AcpStatusInput) => 'idle' | 'generating' | 'waiting_approval' | null`
+ * function.
+ *
+ * Dispatch order:
+ *   1. Not connected → null (no information available).
+ *   2. Error patterns — checked first; first match returns the declared verdict.
+ *   3. Generating pattern — `generating`.
+ *   4. Idle pattern — `idle`.
+ *   5. Default: `null` (no change — caller preserves last known status).
+ *
+ * All regex patterns are compiled once at builder time so the returned
+ * detector function is allocation-free on the hot path.
+ */
+
+// ─── Spec shapes (mirror the JSON schema) ──────────────────────────────
+
+interface AcpRegexPatternSpec {
+  regex: string;
+  flags?: string;
+  description?: string;
+}
+
+interface AcpErrorPatternSpec extends AcpRegexPatternSpec {
+  verdict: 'idle' | 'generating' | 'waiting_approval';
+}
+
+export interface AcpSessionSpec {
+  $schema?: 'adhdev:acp/session-protocol@1';
+  /** Pattern that matches a line emitted when the agent is idle/ready. */
+  idlePattern?: AcpRegexPatternSpec;
+  /** Pattern that matches a line emitted while the agent is actively working. */
+  generatingPattern?: AcpRegexPatternSpec;
+  /**
+   * Error/edge-case patterns. Checked in order; first match returns the
+   * declared verdict. Useful for approval prompts, fatal errors, etc.
+   */
+  errorPatterns?: AcpErrorPatternSpec[];
+  /** Wire format; informational only at the builder level — regex matching
+   *  is identical regardless of promptStyle. */
+  promptStyle?: 'json-rpc' | 'plain-text' | 'mcp';
+  /** Message delimiter used to split incoming bytes (default: newline). */
+  messageDelimiter?: string;
+}
+
+// ─── Input shape ────────────────────────────────────────────────────────
+
+export interface AcpStatusInput {
+  /** The most recently received line from the stdio stream. */
+  lastLine: string;
+  /**
+   * A sliding window of recent output lines (newest last).
+   * Builders may check these when a single line is not enough for context.
+   */
+  recentLines: string[];
+  /** Whether the ACP process is currently connected and running. */
+  isConnected: boolean;
+}
+
+// ─── Output type ────────────────────────────────────────────────────────
+
+export type AcpDetectedStatus = 'idle' | 'generating' | 'waiting_approval' | null;
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+function compile(re: string, flags?: string): RegExp {
+  try {
+    return new RegExp(re, flags ?? 'i');
+  } catch (e) {
+    throw new Error(`Invalid regex /${re}/${flags ?? 'i'}: ${(e as Error).message}`);
+  }
+}
+
+/**
+ * Safe `.test()` wrapper: resets `lastIndex` before each call so that
+ * regexes compiled with the `g` or `y` flag remain stateless across
+ * multiple detect invocations.
+ */
+function testRe(re: RegExp, text: string): boolean {
+  re.lastIndex = 0;
+  return re.test(text);
+}
+
+// ─── Compiled internal representation ───────────────────────────────────
+
+interface CompiledAcpSpec {
+  idle: RegExp | null;
+  generating: RegExp | null;
+  errors: Array<{ re: RegExp; verdict: AcpDetectedStatus }>;
+}
+
+function compileSpec(spec: AcpSessionSpec): CompiledAcpSpec {
+  const idle = spec.idlePattern
+    ? compile(spec.idlePattern.regex, spec.idlePattern.flags)
+    : null;
+
+  const generating = spec.generatingPattern
+    ? compile(spec.generatingPattern.regex, spec.generatingPattern.flags)
+    : null;
+
+  const errors = (spec.errorPatterns ?? []).map((ep) => ({
+    re: compile(ep.regex, ep.flags),
+    verdict: ep.verdict as AcpDetectedStatus,
+  }));
+
+  return { idle, generating, errors };
+}
+
+// ─── Public builder ─────────────────────────────────────────────────────
+
+export function buildDetectStatusFromAcp(
+  spec: AcpSessionSpec,
+): (input: AcpStatusInput) => AcpDetectedStatus {
+  const compiled = compileSpec(spec);
+
+  return function detectAcpStatus(input: AcpStatusInput): AcpDetectedStatus {
+    // 1. No connection → no information.
+    if (!input.isConnected) return null;
+
+    const line = input.lastLine;
+
+    // 2. Error/edge-case patterns take priority.
+    for (const { re, verdict } of compiled.errors) {
+      if (testRe(re, line)) return verdict;
+    }
+
+    // 3. Generating pattern.
+    if (compiled.generating && testRe(compiled.generating, line)) return 'generating';
+
+    // 4. Idle pattern.
+    if (compiled.idle && testRe(compiled.idle, line)) return 'idle';
+
+    // 5. Nothing matched.
+    return null;
+  };
+}
+
+// Internal exports for builder reuse + tests.
+export const __internal = {
+  compileSpec,
+};

package/src/providers/sdk/v1/builders/cli/detect-status.ts

@@ -0,0 +1,262 @@
+/**
+ * buildDetectStatusFromTui
+ *
+ * Turns a manifest's declarative TUI block into a runtime
+ * `(input: CliStatusInput) => CliStatus | null` function.
+ *
+ * Inputs handled (all optional except spinner):
+ *   - tui/spinner@1          → contributes `generating`
+ *   - tui/settled-prompt@1   → contributes `idle`
+ *   - tui/modal@1            → contributes `waiting_approval`
+ *
+ * Dispatch order (sprint-2026-06 contract):
+ *   1. Active generation cues win over idle prompt — checked first.
+ *      Reason: codex/claude keep model footer visible during `Working` and
+ *      `hasReadyPrompt` falsely fired idle. Audit §4.2 introduces
+ *      `tui/cue-ordering` as the named primitive for this rule.
+ *   2. Modal cue (if present) is checked next — `waiting_approval`.
+ *   3. Settled-prompt cue — `idle`.
+ *   4. Default: `null` (no change).
+ */
+
+import type {
+  CliStatusInput,
+  CliStatus,
+  CliDetectStatusFn,
+} from '../../types/cli/index.js';
+import {
+  applyVisibleRegion,
+  type VisibleRegionSpec,
+} from './visible-region.js';
+
+// ─── Primitive spec shapes (mirror the JSON schemas) ───────────────────
+
+interface RegexLikeSpec {
+  regex: string;
+  flags?: string;
+}
+
+interface SpinnerPatternSpec extends RegexLikeSpec {
+  description?: string;
+}
+
+interface SpinnerSpec {
+  $schema: 'adhdev:tui/spinner@1';
+  patterns: SpinnerPatternSpec[];
+  scope?: 'live-frame-tail' | 'whole-screen' | 'recent-buffer';
+  scopeWindowLines?: number;
+}
+
+interface SettledPromptFooterSpec {
+  pattern: string;
+  kind?: 'substring' | 'regex';
+  flags?: string;
+}
+
+interface SettledPromptSpec {
+  $schema: 'adhdev:tui/settled-prompt@1';
+  regex: string;
+  flags?: string;
+  withFooter?: SettledPromptFooterSpec[];
+  scope?: 'last-n-lines' | 'whole-screen';
+  scopeWindowLines?: number;
+}
+
+interface ModalSpec {
+  $schema: 'adhdev:tui/modal@1';
+  questionPattern: string;
+  questionFlags?: string;
+  questionVariants?: Array<{ regex: string; flags?: string; label?: string }>;
+  buttonPattern: string;
+  buttonFlags?: string;
+}
+
+export type DispatchGroup =
+  | 'spinner'
+  | 'modal'
+  | 'settled-prompt'
+  | 'cue-ordering'
+  | 'error-detection'
+  | 'approval-stitching';
+
+export interface DispatchOrderSpec {
+  $schema: 'adhdev:tui/dispatch-order@1';
+  order: DispatchGroup[];
+  onNoMatch?: 'idle' | 'unknown' | 'preserve-last';
+}
+
+export interface DetectStatusTuiSpec {
+  spinner?: SpinnerSpec;
+  settledPrompt?: SettledPromptSpec;
+  modal?: ModalSpec;
+  dispatchOrder?: DispatchOrderSpec;
+  visibleRegion?: VisibleRegionSpec;
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+function compile(re: string, flags?: string): RegExp {
+  try {
+    return new RegExp(re, flags ?? '');
+  } catch (e) {
+    throw new Error(`Invalid regex /${re}/${flags ?? ''}: ${(e as Error).message}`);
+  }
+}
+
+function takeTail(text: string, lines: number): string {
+  if (!text) return '';
+  const split = text.split('\n');
+  if (split.length <= lines) return text;
+  return split.slice(-lines).join('\n');
+}
+
+function scopeText(
+  input: CliStatusInput,
+  scope: SpinnerSpec['scope'] | SettledPromptSpec['scope'],
+  windowLines: number | undefined,
+): string {
+  const lines = windowLines && windowLines > 0 ? windowLines : 8;
+  switch (scope) {
+    case 'whole-screen':
+      return input.screenText ?? '';
+    case 'recent-buffer':
+      return input.tail ?? '';
+    case 'last-n-lines':
+    case 'live-frame-tail':
+    case undefined:
+    default:
+      return takeTail(input.screenText ?? '', lines);
+  }
+}
+
+function compileSpinnerMatchers(spec: SpinnerSpec): RegExp[] {
+  return spec.patterns.map((p) => compile(p.regex, p.flags ?? 'i'));
+}
+
+function spinnerMatches(spec: SpinnerSpec, input: CliStatusInput): boolean {
+  const matchers = compileSpinnerMatchers(spec);
+  const text = scopeText(input, spec.scope, spec.scopeWindowLines);
+  return matchers.some((re) => re.test(text));
+}
+
+function compileSettledPromptMatchers(spec: SettledPromptSpec): {
+  prompt: RegExp;
+  footers: Array<{ test: (s: string) => boolean }>;
+} {
+  const prompt = compile(spec.regex, spec.flags ?? 'm');
+  const footers = (spec.withFooter ?? []).map((f) => {
+    if (f.kind === 'regex') {
+      const re = compile(f.pattern, f.flags ?? 'i');
+      return { test: (s: string) => re.test(s) };
+    }
+    const needle = f.pattern.toLowerCase();
+    return { test: (s: string) => s.toLowerCase().includes(needle) };
+  });
+  return { prompt, footers };
+}
+
+function settledPromptMatches(spec: SettledPromptSpec, input: CliStatusInput): boolean {
+  const { prompt, footers } = compileSettledPromptMatchers(spec);
+  const text = scopeText(input, spec.scope, spec.scopeWindowLines);
+  if (!prompt.test(text)) return false;
+  if (footers.length === 0) return true;
+  return footers.every((f) => f.test(text));
+}
+
+function modalMatches(spec: ModalSpec, input: CliStatusInput): boolean {
+  // Status-level modal detection is cue-only — does the question appear at all?
+  // Button extraction lives in buildParseApprovalFromTui.
+  const text = input.screenText ?? '';
+  const question = compile(spec.questionPattern, spec.questionFlags ?? 'i');
+  if (question.test(text)) return true;
+  for (const variant of spec.questionVariants ?? []) {
+    const re = compile(variant.regex, variant.flags ?? 'i');
+    if (re.test(text)) return true;
+  }
+  return false;
+}
+
+// ─── Public builder ────────────────────────────────────────────────────
+
+const DEFAULT_ORDER: DispatchGroup[] = ['spinner', 'modal', 'settled-prompt'];
+
+function evaluateGroup(
+  group: DispatchGroup,
+  spec: DetectStatusTuiSpec,
+  input: CliStatusInput,
+  compiled: {
+    spinner: RegExp[] | null;
+    settled: ReturnType<typeof compileSettledPromptMatchers> | null;
+  },
+): CliStatus | null {
+  switch (group) {
+    case 'spinner': {
+      if (!spec.spinner || !compiled.spinner) return null;
+      const text = scopeText(input, spec.spinner.scope, spec.spinner.scopeWindowLines);
+      return compiled.spinner.some((re) => re.test(text)) ? 'generating' : null;
+    }
+    case 'modal': {
+      if (!spec.modal) return null;
+      return modalMatches(spec.modal, input) ? 'waiting_approval' : null;
+    }
+    case 'settled-prompt': {
+      if (!spec.settledPrompt || !compiled.settled) return null;
+      const text = scopeText(input, spec.settledPrompt.scope, spec.settledPrompt.scopeWindowLines);
+      if (!compiled.settled.prompt.test(text)) return null;
+      if (compiled.settled.footers.length === 0) return 'idle';
+      return compiled.settled.footers.every((f) => f.test(text)) ? 'idle' : null;
+    }
+    // Groups declared in the catalog but not yet implemented as builder steps
+    // return null so they are no-ops in dispatch — declaring them in `order`
+    // is forward-compatible. Phase 2 Week 8+ will wire them.
+    case 'cue-ordering':
+    case 'error-detection':
+    case 'approval-stitching':
+      return null;
+    default:
+      return null;
+  }
+}
+
+export function buildDetectStatusFromTui(spec: DetectStatusTuiSpec): CliDetectStatusFn {
+  const compiledSpinner = spec.spinner ? compileSpinnerMatchers(spec.spinner) : null;
+  const compiledSettled = spec.settledPrompt
+    ? compileSettledPromptMatchers(spec.settledPrompt)
+    : null;
+  const compiled = { spinner: compiledSpinner, settled: compiledSettled };
+  const order = spec.dispatchOrder?.order && spec.dispatchOrder.order.length > 0
+    ? spec.dispatchOrder.order
+    : DEFAULT_ORDER;
+
+  return function detectStatus(input: CliStatusInput): CliStatus | null {
+    // Apply visible-region scoping before running any matchers.
+    const effectiveInput: CliStatusInput = spec.visibleRegion
+      ? {
+          ...input,
+          screenText: applyVisibleRegion(spec.visibleRegion, input.screenText ?? ''),
+          tail: applyVisibleRegion(spec.visibleRegion, input.tail),
+        }
+      : input;
+
+    for (const group of order) {
+      const verdict = evaluateGroup(group, spec, effectiveInput, compiled);
+      if (verdict !== null) return verdict;
+    }
+    // onNoMatch policy: the builder always returns null when nothing matched.
+    // The daemon's outer state machine maps null per the policy below:
+    //   'idle'          → caller treats null as idle (default)
+    //   'unknown'       → caller keeps status unknown / shows last
+    //   'preserve-last' → caller preserves the last reported verdict
+    // Encoding this here would require call-site state; instead the daemon
+    // reads `dispatchOrder.onNoMatch` from the manifest directly.
+    return null;
+  };
+}
+
+// Internal exports for builder reuse + tests.
+export const __internal = {
+  scopeText,
+  spinnerMatches,
+  settledPromptMatches,
+  modalMatches,
+};