@adhdev/daemon-core 0.9.82-rc.16 → 0.9.82-rc.160

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;
@@ -1067,13 +1152,17 @@ export class ProviderLoader {
           awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
         });
 
+        let reloadTimer: ReturnType<typeof setTimeout> | null = null;
         const handleChange = (filePath: string) => {
           if (/[\/\\]fixtures[\/\\]/.test(filePath)) {
             return;
           }
           if (filePath.endsWith('.js') || filePath.endsWith('.json')) {
-            this.log(`File changed: ${path.basename(filePath)}, reloading...`);
-            this.reload();
+            if (reloadTimer) clearTimeout(reloadTimer);
+            reloadTimer = setTimeout(() => {
+              this.log(`File changed: ${path.basename(filePath)}, reloading...`);
+              this.reload();
+            }, 300);
           }
         };
 
@@ -1124,13 +1213,118 @@ 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)');
       return { updated: false };
     }
     const https = require('https') as typeof import('https');
-    const { execSync } = require('child_process') as typeof import('child_process');
+    const { exec } = require('child_process') as typeof import('child_process');
+    const { promisify } = require('util');
+    const execAsync = promisify(exec);
 
     const metaPath = path.join(this.upstreamDir, ProviderLoader.META_FILE);
     let prevEtag = '';
@@ -1207,7 +1401,7 @@ export class ProviderLoader {
 
  // Extract
       fs.mkdirSync(tmpExtract, { recursive: true });
-      execSync(`tar -xzf "${tmpTar}" -C "${tmpExtract}"`, { timeout: 30000 });
+      await execAsync(`tar -xzf "${tmpTar}" -C "${tmpExtract}"`, { timeout: 30000 });
 
  // Tarball internal structure: adhdev-providers-main/ide/... → strip 1 level
       const extracted = fs.readdirSync(tmpExtract);
@@ -1315,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 { }
     };
@@ -1372,11 +1568,15 @@ export class ProviderLoader {
       return args ? args.map((arg) => /\s/.test(arg) ? JSON.stringify(arg) : arg).join(' ') : '';
     }
     const schemaDef = this.getSettingsSchema(providerType)[key];
-    const defaultVal = schemaDef
-      ? (key === 'autoApprove' && schemaDef.type === 'boolean'
-        ? true
-        : schemaDef.default)
-      : undefined;
+    // (fix) Previously this hard-coded `autoApprove` boolean default to `true`,
+    // overriding whatever schemaDef.default the provider.json declared. That
+    // surfaced as soon as a provider added an `autoApprove` schema entry with
+    // default=false: the user had never opted in but the daemon treated the
+    // session as auto-approve, which then triggered recordAutoApproval every
+    // time the CLI showed an approval modal — producing a flood of system
+    // "Auto-approved: ..." messages and keeping the session pinned to
+    // generating while modals cycled in and out. Trust the schemaDef.default.
+    const defaultVal = schemaDef ? schemaDef.default : undefined;
 
     const config = this.readConfig();
     const userVal = config?.providerSettings?.[providerType]?.[key];
@@ -1490,10 +1690,17 @@ export class ProviderLoader {
       ...this.getSyntheticSettings(type, provider),
       ...(provider.settings || {}),
     };
+    // (fix) Previously this clause forced `autoApprove.default = true` for any
+    // boolean autoApprove schema, even when the provider.json explicitly set
+    // `default: false`. Combined with the synthetic-settings fallback at
+    // getSyntheticSettings (which also defaults autoApprove to true when the
+    // provider doesn't supply one), that meant CLI providers silently turned on
+    // auto-approval, producing a flood of "Auto-approved: ..." system messages
+    // every time an approval modal appeared and pinning the session to
+    // generating while modals cycled. Trust the provider's declared default.
     if (result.autoApprove?.type === 'boolean') {
       result.autoApprove = {
         ...result.autoApprove,
-        default: true,
         public: true,
         label: result.autoApprove.label || 'Auto Approve',
         description: result.autoApprove.description || 'Automatically approve actionable prompts without sending approval alerts.',
@@ -1518,7 +1725,10 @@ export class ProviderLoader {
     if (!provider.settings?.autoApprove) {
       result.autoApprove = {
         type: 'boolean',
-        default: true,
+        // (fix) Safe default is *off*. Auto-approving every modal without the
+        // user opting in produced silent-bash-execution surprises and the
+        // "Auto-approved: ..." system-message flood seen on AGY/Codex.
+        default: false,
         public: true,
         label: 'Auto Approve',
         description: 'Automatically approve actionable prompts without sending approval alerts.',
@@ -1581,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 */ }
       }
@@ -1690,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 || '';
@@ -1712,6 +1958,22 @@ export class ProviderLoader {
             ...(extensionIdPattern instanceof RegExp ? { extensionIdPattern } : {}),
           };
 
+          // v1 manifests use `nativeHistory` as the canonical field name.
+          // Legacy v0 manifests use `canonicalHistory`. The daemon's
+          // runtime + downstream code reads `provider.nativeHistory`, so
+          // for legacy manifests we copy `canonicalHistory` into
+          // `nativeHistory` here. We also keep `canonicalHistory`
+          // populated in both directions (deprecated alias) so any
+          // external consumers still reading the old name keep working
+          // during the one-release deprecation window.
+          const nh = (normalizedProvider as any).nativeHistory;
+          const ch = (normalizedProvider as any).canonicalHistory;
+          if (nh && !ch) {
+            (normalizedProvider as any).canonicalHistory = nh;
+          } else if (ch && !nh) {
+            (normalizedProvider as any).nativeHistory = ch;
+          }
+
           const validation = validateProviderDefinition(normalizedProvider);
           for (const warning of validation.warnings) {
             this.log(`⚠ ${jsonPath}: ${warning}`);
@@ -1725,6 +1987,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

@@ -37,6 +37,12 @@ const KNOWN_PROVIDER_FIELDS = new Set<string>([
   'approvalPositiveHints',
   'sessionIdPattern',
   'historyBehavior',
+  // v1 canonical field name. The loader fills this in for legacy v0
+  // manifests that ship the old `canonicalHistory` spelling.
+  'nativeHistory',
+  // Deprecated v0 alias for `nativeHistory`. Kept in the allowed-keys
+  // list so legacy provider.json manifests don't trip the unknown-key
+  // warning during the one-release deprecation window.
   'canonicalHistory',
   'autoFixProfile',
   'ideLevelScripts',
@@ -64,6 +70,8 @@ const KNOWN_PROVIDER_FIELDS = new Set<string>([
   'sendKey',
   'submitStrategy',
   'requirePromptEchoBeforeSubmit',
+  'requiresFinalAssistantBeforeIdle',
+  'augmentStaleSnapshot',
   'timeouts',
   'disableUpstream',
 ])
@@ -128,7 +136,7 @@ export function validateProviderDefinition(raw: unknown): ProviderValidationResu
   }
 
   validateCapabilities(provider as unknown as ProviderModule, controls, errors)
-  validateCanonicalHistory(provider.canonicalHistory, errors)
+  validateNativeHistory(provider.nativeHistory, errors)
   validateMeshCoordinator(provider.meshCoordinator, errors)
 
   for (const control of controls) {
@@ -228,33 +236,43 @@ function validateCapabilities(provider: ProviderModule, controls: ProviderContro
   }
 }
 
-function validateCanonicalHistory(raw: unknown, errors: string[]): void {
+function validateNativeHistory(raw: unknown, errors: string[]): void {
   if (raw === undefined) return
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    errors.push('canonicalHistory must be an object')
+    errors.push('nativeHistory must be an object')
     return
   }
 
-  const canonicalHistory = raw as Record<string, unknown>
-  const format = canonicalHistory.format
+  const nativeHistory = raw as Record<string, unknown>
+  const format = nativeHistory.format
   if (format !== undefined && (typeof format !== 'string' || !format.trim())) {
-    errors.push('canonicalHistory.format must be a non-empty string when provided')
+    errors.push('nativeHistory.format must be a non-empty string when provided')
   }
 
-  const watchPath = canonicalHistory.watchPath
+  const watchPath = nativeHistory.watchPath
   if (watchPath !== undefined && (typeof watchPath !== 'string' || !watchPath.trim())) {
-    errors.push('canonicalHistory.watchPath must be a non-empty string when provided')
+    errors.push('nativeHistory.watchPath must be a non-empty string when provided')
   }
 
-  const mode = canonicalHistory.mode
+  const mode = nativeHistory.mode
   if (mode !== undefined && !['native-source', 'materialized-mirror', 'disabled'].includes(String(mode))) {
-    errors.push('canonicalHistory.mode must be one of: native-source, materialized-mirror, disabled')
+    errors.push('nativeHistory.mode must be one of: native-source, materialized-mirror, disabled')
   }
 
-  const scripts = canonicalHistory.scripts
+  // Chat transcript contract version (transcript-v2.ts). Absent → treated as
+  // v1 by readDeclaredChatContractVersion(). A2 will reject unrecognised
+  // values at load time; A1 only validates the field shape.
+  const chatContractVersion = nativeHistory.contractVersion
+  if (chatContractVersion !== undefined
+      && chatContractVersion !== '1.0'
+      && chatContractVersion !== '2.0') {
+    errors.push(`nativeHistory.contractVersion must be '1.0' or '2.0' when provided (got ${JSON.stringify(chatContractVersion)})`)
+  }
+
+  const scripts = nativeHistory.scripts
   if (scripts === undefined) return
   if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts)) {
-    errors.push('canonicalHistory.scripts must be an object')
+    errors.push('nativeHistory.scripts must be an object')
     return
   }
 
@@ -262,7 +280,7 @@ function validateCanonicalHistory(raw: unknown, errors: string[]): void {
   for (const key of ['readSession', 'listSessions']) {
     const value = scriptConfig[key]
     if (typeof value !== 'string' || !value.trim()) {
-      errors.push(`canonicalHistory.scripts.${key} must be a non-empty string`)
+      errors.push(`nativeHistory.scripts.${key} must be a non-empty string`)
     }
   }
 }