@adhdev/daemon-core 0.9.82-rc.142 → 0.9.82-rc.144

package/src/providers/provider-loader.ts

@@ -33,6 +33,26 @@ import { validateProviderDefinition } from './provider-schema.js';
 import type { ProviderSourceMode } from '../config/config.js';
 import type { ProviderSourceConfigSnapshot, ProviderUserDirSource } from '../config/provider-source-config.js';
 
+/**
+ * Adds a provider-script root to the require whitelist. Wrapped in a
+ * try/catch + null check so a loader hot-path can't crash on a path
+ * that doesn't exist yet or one the whitelist hook rejects.
+ *
+ * The require-whitelist module is loaded lazily on first call. Eagerly
+ * top-level importing it pulls `node:fs.realpathSync.native` into
+ * module evaluation, which breaks unit tests that partially mock `fs`
+ * (e.g. test/commands/get-logs-incremental.test.ts mocks only
+ * existsSync + readFileSync). Lazy load keeps that mock surface valid.
+ */
+function registerProviderScriptRootSafely(root: string | null | undefined): void {
+  if (!root || typeof root !== 'string') return;
+  try {
+    const { registerProviderScriptRoot } =
+      require('./sdk/v1/sandbox/require-whitelist.js') as typeof import('./sdk/v1/sandbox/require-whitelist.js');
+    registerProviderScriptRoot(root);
+  } catch { /* boot-time only — swallow */ }
+}
+
 interface ProviderAvailabilityState {
   installed: boolean;
   detectedPath: string | null;
@@ -92,7 +112,9 @@ export class ProviderLoader {
   }
 
   private static readonly GITHUB_TARBALL_URL = 'https://github.com/vilmire/adhdev-providers/archive/refs/heads/main.tar.gz';
+  private static readonly REGISTRY_BASE_URL = 'https://api.adhf.dev/api/v1/registry';
   private static readonly META_FILE = '.meta.json';
+  private static readonly REGISTRY_META_FILE = '.registry-meta.json';
   private static readonly REPO_PROVIDER_DIRNAME = 'adhdev-providers';
   private static readonly SIBLING_MARKER_FILE = '.adhdev-provider-root';
   private static readonly SIBLING_ENV_VAR = 'ADHDEV_USE_SIBLING_PROVIDERS';
@@ -224,7 +246,12 @@ export class ProviderLoader {
    * Highest-priority editable overrides come first.
    */
   getProviderRoots(): string[] {
-    return [this.userDir, this.upstreamDir];
+    // Order matters: user customs > marketplace installs > upstream auto-sync.
+    // findProviderDirInternal walks this list in order to locate the provider
+    // dir containing the scripts/, so marketplace must be included here even
+    // though loadAll() also reads it directly.
+    const marketplaceDir = path.join(os.homedir(), '.adhdev', 'marketplace');
+    return [this.userDir, marketplaceDir, this.upstreamDir];
   }
 
   getSourceConfig(): ProviderSourceConfigSnapshot {
@@ -336,7 +363,19 @@ export class ProviderLoader {
       this.log('Upstream loading disabled (sourceMode=no-upstream)');
     }
 
- // 2. Load user custom (excluding .upstream — highest priority, never auto-updated)
+ // 2. Load marketplace installs from ~/.adhdev/marketplace/ (overrides upstream,
+ //    but is itself overridden by user customs in step 3). These are providers the
+ //    user explicitly installed via the Marketplace UI. They are NOT touched by
+ //    upstream sync.
+    const marketplaceDir = path.join(os.homedir(), '.adhdev', 'marketplace');
+    if (fs.existsSync(marketplaceDir)) {
+      const marketplaceCount = this.loadDir(marketplaceDir);
+      if (marketplaceCount > 0) {
+        this.log(`Loaded ${marketplaceCount} marketplace-installed providers`);
+      }
+    }
+
+ // 3. Load user custom (excluding .upstream — highest priority, never auto-updated)
     if (fs.existsSync(this.userDir)) {
       const userCount = this.loadDir(this.userDir, ['.upstream']);
       if (userCount > 0) {
@@ -988,7 +1027,12 @@ export class ProviderLoader {
     }
 
  // 3. Composite override (OS + version)
-    if (base.overrides) {
+ //    Legacy shape: base.overrides is an Array<{ when: {os,version}, scripts }>.
+ //    v1 manifests (Phase 3-4) repurposed `overrides` as an object map of
+ //    capability overrides (e.g. { detectStatus: { path, schema } }), which is
+ //    consumed by the SDK builders, not by this resolver. Only iterate when
+ //    the field is in the legacy array shape.
+    if (Array.isArray(base.overrides)) {
       for (const override of base.overrides) {
         const osMatch = !override.when.os || override.when.os === currentOs;
         const verMatch = !override.when.version || (currentVersion && this.matchesVersion(currentVersion, override.when.version));
@@ -996,6 +1040,40 @@ export class ProviderLoader {
           resolved.scripts = { ...resolved.scripts, ...override.scripts };
         }
       }
+    } else if (base.overrides && typeof base.overrides === 'object') {
+      // v1 manifest shape: { detectStatus: { path }, parseSession: { path }, ... }
+      // Each script name maps to a path inside the provider directory. We load
+      // the file and merge its export(s) into resolved.scripts. Lets a
+      // provider override a single primitive (e.g. just detectStatus) while
+      // letting the SDK synthesize the rest from the tui block.
+      const providerDir = this.findProviderDirInternal(base.type);
+      if (providerDir) {
+        for (const [scriptName, override] of Object.entries(base.overrides as Record<string, any>)) {
+          if (!override || typeof override.path !== 'string') continue;
+          const fullPath = path.join(providerDir, override.path);
+          if (!fs.existsSync(fullPath)) {
+            this.log(`  [overrides] ${base.type}: ${scriptName} path not found: ${fullPath}`);
+            continue;
+          }
+          try {
+            // Override scripts go through the same whitelist gate as the
+            // main scripts dir. Use the provider parent root so a v1
+            // override can still require ../_shared helpers.
+            registerProviderScriptRootSafely(path.dirname(path.dirname(providerDir)));
+            delete require.cache[require.resolve(fullPath)];
+            const fn = require(fullPath);
+            const target = typeof fn === 'function' ? fn : (fn && fn[scriptName]);
+            if (typeof target === 'function') {
+              resolved.scripts = { ...resolved.scripts, [scriptName]: target } as any;
+              this.log(`  [overrides] ${base.type}: ${scriptName} loaded from ${override.path}`);
+            } else {
+              this.log(`  [overrides] ${base.type}: ${scriptName} export missing in ${override.path}`);
+            }
+          } catch (e: any) {
+            this.log(`  [overrides] ${base.type}: ${scriptName} require failed: ${e?.message || e}`);
+          }
+        }
+      }
     }
 
     if ((resolved.category === 'cli' || resolved.category === 'acp') && resolved.spawn?.command) {
@@ -1026,6 +1104,13 @@ export class ProviderLoader {
       return null;
     }
 
+    // Register the provider's *parent root* (e.g. .../adhdev-providers/) so
+    // the require whitelist gates every script + every _shared helper this
+    // provider may reach. Picking the grandparent (one above the category
+    // dir `cli/`) lets sibling helpers in `_shared` resolve while still
+    // blocking `../../etc/...` escapes. Idempotent.
+    registerProviderScriptRootSafely(path.dirname(path.dirname(providerDir)));
+
     // Return cached scripts if available (cleared on reload/watch)
     const cached = this.scriptsCache.get(dir);
     if (cached) return cached;
@@ -1128,6 +1213,109 @@ export class ProviderLoader {
  * 
  * @returns Whether an update occurred
  */
+  /**
+   * Sync providers from the ADHDev registry (registry.adhf.dev).
+   *
+   * Downloads only providers whose server checksum differs from the locally
+   * cached checksum. Falls back gracefully to the GitHub tarball path if the
+   * registry is unreachable or returns an unexpected response.
+   *
+   * Returns `{ updated: true }` when at least one provider file changed on disk,
+   * `{ updated: false }` when everything is already current, or
+   * `{ updated: false, error }` when the registry couldn't be reached and we
+   * should proceed to the GitHub tarball fallback.
+   */
+  async fetchFromRegistry(): Promise<{ updated: boolean; error?: string }> {
+    if (this.disableUpstream) {
+      this.log('Registry sync skipped (sourceMode=no-upstream)');
+      return { updated: false };
+    }
+    this.log(`Registry sync starting (${ProviderLoader.REGISTRY_BASE_URL})...`);
+
+    const https = require('https') as typeof import('https');
+    const regMetaPath = path.join(this.upstreamDir, ProviderLoader.REGISTRY_META_FILE);
+
+    // Load cached checksums
+    let cachedChecksums: Record<string, string> = {};
+    try {
+      if (fs.existsSync(regMetaPath)) {
+        cachedChecksums = JSON.parse(fs.readFileSync(regMetaPath, 'utf-8')).checksums ?? {};
+      }
+    } catch { }
+
+    try {
+      // 1. Fetch provider list
+      const listUrl = `${ProviderLoader.REGISTRY_BASE_URL}/providers`;
+      const listBody = await new Promise<string>((resolve, reject) => {
+        const req = https.get(listUrl, { headers: { 'User-Agent': 'adhdev-daemon', 'Accept': 'application/json' }, timeout: 10000 }, (res) => {
+          if (res.statusCode !== 200) { reject(new Error(`registry list HTTP ${res.statusCode}`)); return; }
+          const chunks: Buffer[] = [];
+          res.on('data', (c: Buffer) => chunks.push(c));
+          res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('registry list timeout')); });
+      });
+
+      const list = JSON.parse(listBody) as { providers: Array<{ type: string; category: string; checksum: string; version: string }> };
+      if (!Array.isArray(list.providers)) throw new Error('unexpected registry response shape');
+
+      let updatedCount = 0;
+
+      for (const entry of list.providers) {
+        const { type, category, checksum, version } = entry;
+        const cacheKey = `${category}/${type}`;
+        if (cachedChecksums[cacheKey] === checksum) continue; // already current
+
+        // Download this provider's manifest
+        const dlUrl = `${ProviderLoader.REGISTRY_BASE_URL}/providers/${type}/${version}/download`;
+        const manifestBody = await new Promise<string>((resolve, reject) => {
+          const req = https.get(dlUrl, { headers: { 'User-Agent': 'adhdev-daemon', 'Accept': 'application/json' }, timeout: 30000 }, (res) => {
+            if (res.statusCode !== 200) { reject(new Error(`registry download HTTP ${res.statusCode} for ${type}@${version}`)); return; }
+            const chunks: Buffer[] = [];
+            res.on('data', (c: Buffer) => chunks.push(c));
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+          });
+          req.on('error', reject);
+          req.on('timeout', () => { req.destroy(); reject(new Error(`download timeout for ${type}`)); });
+        });
+
+        // Verify checksum
+        const actualChecksum = await new Promise<string>((resolve) => {
+          const crypto = require('crypto') as typeof import('crypto');
+          resolve(crypto.createHash('sha256').update(manifestBody, 'utf-8').digest('hex'));
+        });
+        if (actualChecksum !== checksum) {
+          this.log(`⚠ Registry checksum mismatch for ${type}@${version} — skipping`);
+          continue;
+        }
+
+        // Write to upstream dir
+        const providerDir = path.join(this.upstreamDir, category, type);
+        fs.mkdirSync(providerDir, { recursive: true });
+        fs.writeFileSync(path.join(providerDir, 'provider.json'), manifestBody, 'utf-8');
+
+        cachedChecksums[cacheKey] = checksum;
+        updatedCount++;
+        this.log(`✓ Registry updated: ${category}/${type}@${version}`);
+      }
+
+      // Persist updated checksums
+      fs.mkdirSync(this.upstreamDir, { recursive: true });
+      fs.writeFileSync(regMetaPath, JSON.stringify({
+        checksums: cachedChecksums,
+        syncedAt: new Date().toISOString(),
+        providerCount: list.providers.length,
+      }, null, 2));
+
+      this.log(`Registry sync complete: ${list.providers.length} providers, ${updatedCount} updated`);
+      return { updated: updatedCount > 0 };
+    } catch (e: any) {
+      this.log(`⚠ Registry sync failed (falling back to GitHub tarball): ${e?.message}`);
+      return { updated: false, error: e?.message };
+    }
+  }
+
   async fetchLatest(): Promise<{ updated: boolean; error?: string }> {
     if (this.disableUpstream) {
       this.log('Upstream fetch skipped (sourceMode=no-upstream)');
@@ -1321,15 +1509,17 @@ export class ProviderLoader {
     } catch { }
   }
 
-  /** Count provider files (provider.js or provider.json) */
+  /** Count provider files (provider.v1.json or provider.json — at most one per dir). */
   private countProviders(dir: string): number {
     if (!fs.existsSync(dir)) return 0;
     let count = 0;
     const scan = (d: string) => {
       try {
-        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const entries = fs.readdirSync(d, { withFileTypes: true });
+        const hasManifest = entries.some(e => e.name === 'provider.v1.json' || e.name === 'provider.json');
+        if (hasManifest) count++;
+        for (const entry of entries) {
           if (entry.isDirectory()) scan(path.join(d, entry.name));
-          else if (entry.name === 'provider.json') count++;
         }
       } catch { }
     };
@@ -1601,23 +1791,32 @@ export class ProviderLoader {
     const cat = provider.category;
 
     const searchRoots = this.getProviderRoots();
+    const hasManifest = (dir: string) =>
+      fs.existsSync(path.join(dir, 'provider.v1.json')) || fs.existsSync(path.join(dir, 'provider.json'));
+    const readManifestType = (dir: string): string | null => {
+      for (const file of ['provider.v1.json', 'provider.json']) {
+        const p = path.join(dir, file);
+        if (!fs.existsSync(p)) continue;
+        try {
+          const data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+          if (typeof data?.type === 'string') return data.type;
+        } catch { /* skip */ }
+      }
+      return null;
+    };
     for (const root of searchRoots) {
       if (!fs.existsSync(root)) continue;
       const candidate = this.getProviderDir(root, cat, type);
-      if (fs.existsSync(path.join(candidate, 'provider.json'))) return candidate;
+      if (hasManifest(candidate)) return candidate;
       // Scan category dir for type match
       const catDir = path.join(root, cat);
       if (fs.existsSync(catDir)) {
         try {
           for (const entry of fs.readdirSync(catDir, { withFileTypes: true })) {
             if (!entry.isDirectory()) continue;
-            const jsonPath = path.join(catDir, entry.name, 'provider.json');
-            if (fs.existsSync(jsonPath)) {
-              try {
-                const data = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
-                if (data.type === type) return path.join(catDir, entry.name);
-              } catch { /* skip */ }
-            }
+            const entryDir = path.join(catDir, entry.name);
+            const manifestType = readManifestType(entryDir);
+            if (manifestType === type) return entryDir;
           }
         } catch { /* skip */ }
       }
@@ -1710,17 +1909,44 @@ export class ProviderLoader {
         return;
       }
 
-      // Check if this directory has provider.json
+      // v1-first manifest selection. provider.v1.json (the SDK-shape
+      // manifest with `overrides`, `tui`, `source`, `canonicalHistory`)
+      // wins over provider.json (legacy). Without this branch the v1
+      // file is silently ignored — that's how the codex-cli `overrides`
+      // path and the tui-block builders went un-honored for the first
+      // pass of SDK rollout.
+      const hasV1 = entries.some(e => e.name === 'provider.v1.json');
       const hasJson = entries.some(e => e.name === 'provider.json');
 
-      if (hasJson) {
-        const jsonPath = path.join(d, 'provider.json');
+      if (hasV1 || hasJson) {
+        const manifestFile = hasV1 ? 'provider.v1.json' : 'provider.json';
+        const jsonPath = path.join(d, manifestFile);
         try {
           const raw = fs.readFileSync(jsonPath, 'utf-8');
           const mod = JSON.parse(raw) as Omit<ProviderModule, 'extensionIdPattern'> & {
             extensionIdPattern?: RegExp | string;
           };
 
+          // Validate v1 manifests against the SDK schema. Failures are
+          // surfaced as a single warning line with all issues attached
+          // so manifest authors don't need to guess which field is wrong.
+          // Loading still proceeds — bricking the daemon on a single
+          // bad field would be worse than running with a known warning.
+          if (hasV1 && mod?.category === 'cli') {
+            try {
+              const { validateCliProviderManifest, formatManifestValidationIssues } =
+                require('./sdk/v1/validators/manifest.js') as typeof import('./sdk/v1/validators/manifest.js');
+              const validation = validateCliProviderManifest(mod);
+              if (!validation.ok) {
+                this.log(`⚠ ${jsonPath}: schema validation failed:\n${formatManifestValidationIssues(validation.issues)}`);
+              }
+            } catch (e: any) {
+              // Validator load failed — log once and continue so a
+              // broken validator can't take down provider loading.
+              this.log(`⚠ ${jsonPath}: validator unavailable: ${e?.message || e}`);
+            }
+          }
+
           // Restore RegExp fields from JSON (extensionIdPattern)
           if (typeof mod.extensionIdPattern === 'string') {
             const flags = mod.extensionIdPattern_flags || '';
@@ -1732,6 +1958,17 @@ export class ProviderLoader {
             ...(extensionIdPattern instanceof RegExp ? { extensionIdPattern } : {}),
           };
 
+          // v1 manifest contract calls this block `nativeHistory`; the
+          // daemon's runtime + downstream code still reads
+          // `canonicalHistory` (the legacy name used since v0). Alias
+          // them when only the v1 spelling is present so authors using
+          // the new contract get the same behavior without having to
+          // duplicate the block. If both are set the explicit
+          // canonicalHistory wins — caller signaled it intentionally.
+          if ((normalizedProvider as any).nativeHistory && !(normalizedProvider as any).canonicalHistory) {
+            (normalizedProvider as any).canonicalHistory = (normalizedProvider as any).nativeHistory;
+          }
+
           const validation = validateProviderDefinition(normalizedProvider);
           for (const warning of validation.warnings) {
             this.log(`⚠ ${jsonPath}: ${warning}`);
@@ -1745,6 +1982,10 @@ export class ProviderLoader {
             const scriptsPath = path.join(d, 'scripts.js');
             if (!hasCompatibility && fs.existsSync(scriptsPath)) {
               try {
+                // Gate the IDE/extension scripts.js (legacy single-file
+                // format) under the same whitelist. `d` here is the
+                // provider dir; its grandparent contains _shared.
+                registerProviderScriptRootSafely(path.dirname(path.dirname(d)));
                 delete require.cache[require.resolve(scriptsPath)];
                 const scripts = require(scriptsPath) as Partial<ProviderScripts>;
                 normalizedProvider.scripts = scripts;

package/src/providers/provider-schema.ts

@@ -38,6 +38,9 @@ const KNOWN_PROVIDER_FIELDS = new Set<string>([
   'sessionIdPattern',
   'historyBehavior',
   'canonicalHistory',
+  // v1 contract spelling; the loader aliases nativeHistory →
+  // canonicalHistory so downstream code reads the legacy name.
+  'nativeHistory',
   'autoFixProfile',
   'ideLevelScripts',
   'allowInputDuringGeneration',

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,
+};