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

package/src/providers/native-history/dispatcher.ts

@@ -0,0 +1,227 @@
+/**
+ * Spec-aware dispatcher for native conversation history.
+ *
+ * The four existing readers (claude/codex/antigravity/hermes) already know
+ * how to parse each agent's on-disk format. This dispatcher just resolves
+ * the right file given a workspace + sessionId hint, then hands it off.
+ *
+ * Wired into ProviderModule.scripts.readNativeHistory by provider-loader
+ * when spec.json declares native_history.reader. The script signature
+ * matches what chat-history.ts expects (see callProviderNativeHistoryRead).
+ */
+'use strict';
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { readSession as readClaudeCliSession } from './claude-cli-transcript.js';
+import { readSession as readCodexCliSession } from './codex-cli-transcript.js';
+import { readSession as readAntigravityCliSession } from './antigravity-cli-transcript.js';
+import { readSession as readHermesCliSession } from './hermes-cli-transcript.js';
+
+export type ReaderId = 'claude-cli' | 'codex-cli' | 'antigravity-cli' | 'hermes-cli';
+
+export interface NativeHistoryInput {
+    agentType?: string;
+    sessionId?: string;
+    providerSessionId?: string;
+    historySessionId?: string;
+    workspace?: string;
+    format?: string;
+    watchPath?: string;
+    args?: Record<string, unknown>;
+}
+
+export interface NativeHistoryResult {
+    messages: Array<{ role: string; content: string; receivedAt?: number; kind?: string }>;
+    providerSessionId?: string;
+    sourcePath: string;
+    sourceMtimeMs: number;
+    nativeHistoryCoverage?: 'full' | 'partial' | 'best-effort';
+}
+
+export function createNativeHistoryDispatcher(reader: ReaderId): (input: NativeHistoryInput) => NativeHistoryResult | null {
+    return (input: NativeHistoryInput) => {
+        const workspace = input.workspace || '';
+        const sessionId = input.sessionId || input.historySessionId || '';
+        // Caller may pass a providerSessionId (the *provider's own* id, e.g.
+        // the uuid claude writes into the jsonl basename). When present, the
+        // dispatcher only returns a transcript whose file id matches —
+        // otherwise the newest_by_mtime fallback can surface a different
+        // session's chat (round 9 part b: the user reported "previous chat
+        // shows up before I type anything" on every provider).
+        const requestedProviderSid = input.providerSessionId || '';
+
+        const sourcePath = resolveSourcePath(reader, workspace, sessionId);
+        if (!sourcePath) return null;
+
+        const session = readByReader(reader, sourcePath, sessionId, workspace);
+        if (!session) return null;
+
+        if (requestedProviderSid && session.providerSessionId && session.providerSessionId !== requestedProviderSid) {
+            return null;
+        }
+
+        return {
+            messages: session.messages.map((m: any) => ({
+                role: normalizeRole(m.role),
+                content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+                receivedAt: typeof m.receivedAt === 'number' ? m.receivedAt : Date.parse(m.timestamp || '') || Date.now(),
+                kind: typeof m.kind === 'string' ? m.kind : 'standard',
+            })),
+            providerSessionId: session.providerSessionId,
+            sourcePath: session.sourcePath,
+            sourceMtimeMs: session.sourceMtimeMs,
+            nativeHistoryCoverage: (session as any).nativeHistoryCoverage || 'full',
+        };
+    };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Per-provider path resolution
+// ────────────────────────────────────────────────────────────────────────────
+
+function resolveSourcePath(reader: ReaderId, workspace: string, sessionId: string): string | null {
+    switch (reader) {
+        case 'claude-cli':   return resolveClaudePath(workspace, sessionId);
+        case 'codex-cli':    return resolveCodexPath(workspace);
+        case 'antigravity-cli': return resolveAntigravityPath(workspace);
+        case 'hermes-cli':   return resolveHermesPath(workspace, sessionId);
+    }
+}
+
+function resolveClaudePath(workspace: string, sessionId: string): string | null {
+    // claude stores per-cwd: ~/.claude/projects/<cwd-as-dashes>/<uuid>.jsonl
+    const dir = path.join(os.homedir(), '.claude', 'projects', cwdAsDashes(workspace));
+    if (!fs.existsSync(dir)) return null;
+    if (sessionId) {
+        const candidate = path.join(dir, `${sessionId}.jsonl`);
+        if (fs.existsSync(candidate)) return candidate;
+    }
+    // No exact match: return null. The newest_by_mtime fallback used to
+    // grab whichever transcript was touched most recently, but that
+    // surfaced a different (often the user's *external* claude session
+    // in the same workspace) chat in the dashboard before the user
+    // typed anything. The right answer is to show nothing until either
+    // the daemon's sessionId actually maps to a file or the caller
+    // passes the correct providerSessionId (round 9 part b).
+    return null;
+}
+
+function resolveCodexPath(workspace: string): string | null {
+    void workspace;
+    // codex stores by UTC date: ~/.codex/sessions/<year>/<month>/<day>/<file>.jsonl
+    const now = new Date();
+    const dir = path.join(
+        os.homedir(), '.codex', 'sessions',
+        String(now.getUTCFullYear()),
+        String(now.getUTCMonth() + 1).padStart(2, '0'),
+        String(now.getUTCDate()).padStart(2, '0'),
+    );
+    if (fs.existsSync(dir)) {
+        const f = newestRecentFile(dir, /\.jsonl$/);
+        if (f) return f;
+    }
+    return null;
+}
+
+function resolveAntigravityPath(workspace: string): string | null {
+    void workspace;
+    // agy brain/<uuid>/.system_generated/logs/transcript.jsonl
+    const brainRoot = path.join(os.homedir(), '.gemini', 'antigravity-cli', 'brain');
+    if (!fs.existsSync(brainRoot)) return null;
+    const cutoff = Date.now() - RECENT_WINDOW_MS;
+    const entries = fs.readdirSync(brainRoot, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => ({ p: path.join(brainRoot, e.name), mtime: safeMtime(path.join(brainRoot, e.name)) }))
+        .filter(e => e.mtime >= cutoff)
+        .sort((a, b) => b.mtime - a.mtime);
+    for (const e of entries) {
+        const t = path.join(e.p, '.system_generated', 'logs', 'transcript.jsonl');
+        if (fs.existsSync(t)) return t;
+    }
+    return null;
+}
+
+function resolveHermesPath(workspace: string, sessionId: string): string | null {
+    void workspace; void sessionId;
+    // Hermes ≥ 0.14 persists all chat to ~/.hermes/state.db (SQLite). The
+    // db file is the "path" we hand to the reader — it pulls the newest
+    // source='cli' session inside readSession.
+    const dbPath = path.join(os.homedir(), '.hermes', 'state.db');
+    if (fs.existsSync(dbPath)) return dbPath;
+    // Legacy fallback: pre-db hermes wrote per-session JSON dumps.
+    const dir = path.join(os.homedir(), '.hermes', 'sessions');
+    if (!fs.existsSync(dir)) return null;
+    return newestRecentFile(dir, /^session_.*\.json$/);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Reader dispatch
+// ────────────────────────────────────────────────────────────────────────────
+
+function readByReader(
+    reader: ReaderId,
+    sourcePath: string,
+    sessionId: string,
+    workspace: string,
+): any | null {
+    switch (reader) {
+        case 'claude-cli':      return readClaudeCliSession(sourcePath);
+        case 'codex-cli':       return readCodexCliSession(sourcePath);
+        case 'antigravity-cli': return readAntigravityCliSession(sourcePath, sessionId || undefined, workspace || undefined);
+        case 'hermes-cli':      return readHermesCliSession(sourcePath);
+    }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+function cwdAsDashes(cwd: string): string {
+    if (!cwd) return '';
+    return cwd.replace(/\//g, '-');
+}
+
+function newestFile(dir: string, pattern: RegExp): string | null {
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true })
+            .filter(e => e.isFile() && pattern.test(e.name))
+            .map(e => ({ p: path.join(dir, e.name), mtime: safeMtime(path.join(dir, e.name)) }))
+            .sort((a, b) => b.mtime - a.mtime);
+        return entries[0]?.p ?? null;
+    } catch { return null; }
+}
+
+/**
+ * Like newestFile but only returns a candidate when its mtime is within
+ * the recent activity window. Prevents the dashboard from surfacing a
+ * prior session's transcript when the daemon's sessionId doesn't match
+ * any file on disk (e.g. claude allocates its own uuid; daemon and
+ * agent disagree about what the "current" session is).
+ */
+const RECENT_WINDOW_MS = 5 * 60 * 1000;
+function newestRecentFile(dir: string, pattern: RegExp): string | null {
+    try {
+        const cutoff = Date.now() - RECENT_WINDOW_MS;
+        const entries = fs.readdirSync(dir, { withFileTypes: true })
+            .filter(e => e.isFile() && pattern.test(e.name))
+            .map(e => ({ p: path.join(dir, e.name), mtime: safeMtime(path.join(dir, e.name)) }))
+            .filter(e => e.mtime >= cutoff)
+            .sort((a, b) => b.mtime - a.mtime);
+        return entries[0]?.p ?? null;
+    } catch { return null; }
+}
+
+function safeMtime(p: string): number {
+    try { return Math.floor(fs.statSync(p).mtimeMs); } catch { return 0; }
+}
+
+function normalizeRole(r: any): 'user' | 'assistant' | 'system' {
+    const s = String(r ?? '').toLowerCase();
+    if (s === 'user' || s === 'human') return 'user';
+    if (s === 'assistant' || s === 'ai' || s === 'model') return 'assistant';
+    // daemon's chat schema rejects 'tool'/'function' — surface as assistant.
+    if (s === 'tool' || s === 'tool_result' || s === 'function') return 'assistant';
+    return 'system';
+}

package/src/providers/native-history/hermes-cli-transcript.ts

@@ -0,0 +1,230 @@
+/**
+ * Hermes Agent — native history adapter.
+ *
+ * Hermes persists state in ~/.hermes/state.db (SQLite, better-sqlite3):
+ *   sessions(id, source, started_at, ended_at, message_count, ...)
+ *   messages(id, session_id, role, content, timestamp, ...)
+ *
+ * Earlier releases dumped per-session JSON files under ~/.hermes/sessions/;
+ * recent hermes (≥ 0.14) writes only to state.db. We read straight from
+ * the db when available and fall back to scanning legacy JSON dumps for
+ * archived sessions.
+ *
+ * The dispatcher hands us a sourcePath (the file the resolveHermesPath
+ * function picks). For the SQLite case the "path" is the db file itself
+ * and we resolve the most recent cli-source session inside readSession.
+ */
+'use strict';
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+export interface NativeHistoryMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    receivedAt: number;
+    kind?: string;
+}
+
+export interface NativeHistorySession {
+    messages: NativeHistoryMessage[];
+    providerSessionId: string;
+    source: 'provider-native';
+    sourcePath: string;
+    sourceMtimeMs: number;
+    nativeHistoryCoverage: 'full';
+    workspace?: string;
+}
+
+export interface NativeHistorySessionMeta {
+    historySessionId: string;
+    sessionId: string;
+    sourcePath: string;
+    sourceMtimeMs: number;
+    messageCount: number;
+    firstMessageAt: number;
+    lastMessageAt: number;
+    sessionTitle?: string;
+    preview?: string;
+    workspace?: string;
+}
+
+const HERMES_STATE_DB = path.join(os.homedir(), '.hermes', 'state.db');
+const HERMES_LEGACY_SESSIONS_DIR = path.join(os.homedir(), '.hermes', 'sessions');
+
+function statMtimeMs(p: string): number {
+    try { return Math.floor(fs.statSync(p).mtimeMs); } catch { return 0; }
+}
+
+function openDb(): any | null {
+    if (!fs.existsSync(HERMES_STATE_DB)) return null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const Database = require('better-sqlite3');
+        return new Database(HERMES_STATE_DB, { readonly: true, fileMustExist: true });
+    } catch {
+        return null;
+    }
+}
+
+function loadMessagesForSession(db: any, sessionId: string): NativeHistoryMessage[] {
+    const rows: any[] = db.prepare(
+        `SELECT id, role, content, timestamp
+         FROM messages
+         WHERE session_id = ? AND content IS NOT NULL AND content != ''
+         ORDER BY timestamp ASC, id ASC`,
+    ).all(sessionId);
+    const out: NativeHistoryMessage[] = [];
+    for (const r of rows) {
+        const role = normalizeHermesRole(r.role);
+        // Hermes stores some tool/system rows under role='tool'; surface as
+        // 'assistant' so they don't get dropped on the daemon's chat schema
+        // validation (role must be user/assistant/system).
+        out.push({
+            id: String(r.id),
+            role,
+            content: String(r.content),
+            receivedAt: Math.floor(Number(r.timestamp) * 1000),
+            kind: 'standard',
+        });
+    }
+    return out;
+}
+
+export function readSession(sessionPath: string): NativeHistorySession | null {
+    if (!sessionPath) return null;
+
+    // Path mode A: SQLite — sourcePath is the state.db path. Pick the
+    // newest source='cli' session that has at least one persisted message.
+    if (sessionPath === HERMES_STATE_DB) {
+        const db = openDb();
+        if (!db) return null;
+        try {
+            const row: any = db.prepare(
+                `SELECT id, started_at FROM sessions
+                 WHERE source = 'cli' AND message_count > 0
+                 ORDER BY started_at DESC LIMIT 1`,
+            ).get();
+            if (!row) return null;
+            const messages = loadMessagesForSession(db, row.id);
+            if (messages.length === 0) return null;
+            return {
+                messages,
+                providerSessionId: String(row.id),
+                source: 'provider-native',
+                sourcePath: sessionPath,
+                sourceMtimeMs: statMtimeMs(sessionPath),
+                nativeHistoryCoverage: 'full',
+            };
+        } finally {
+            try { db.close(); } catch { /* ignore */ }
+        }
+    }
+
+    // Path mode B: legacy JSON dump — keep the old reader for archived
+    // sessions that pre-date the db format.
+    if (!path.isAbsolute(sessionPath) || !fs.existsSync(sessionPath)) return null;
+    let raw: any;
+    try { raw = JSON.parse(fs.readFileSync(sessionPath, 'utf8')); } catch { return null; }
+    if (!raw || typeof raw !== 'object') return null;
+    const rawMessages = Array.isArray(raw.messages) ? raw.messages : [];
+    if (rawMessages.length === 0) return null;
+    const sourceMtimeMs = statMtimeMs(sessionPath);
+    const sessionStart = Number(raw.session_start) || sourceMtimeMs - rawMessages.length * 1000;
+    const messages: NativeHistoryMessage[] = [];
+    for (let i = 0; i < rawMessages.length; i += 1) {
+        const m = rawMessages[i];
+        const content = typeof m?.content === 'string' ? m.content : '';
+        if (!content) continue;
+        messages.push({
+            id: typeof m?.id === 'string' ? m.id : `msg_${i}`,
+            role: normalizeHermesRole(m?.role),
+            content,
+            receivedAt: sessionStart + i * 1000,
+            kind: 'standard',
+        });
+    }
+    if (messages.length === 0) return null;
+    const sessionId = typeof raw.session_id === 'string' && raw.session_id
+        ? raw.session_id
+        : path.basename(sessionPath, '.json').replace(/^session_/, '');
+    return {
+        messages,
+        providerSessionId: sessionId,
+        source: 'provider-native',
+        sourcePath: sessionPath,
+        sourceMtimeMs,
+        nativeHistoryCoverage: 'full',
+    };
+}
+
+export async function listSessions(_watchPath: string): Promise<NativeHistorySessionMeta[]> {
+    const out: NativeHistorySessionMeta[] = [];
+
+    const db = openDb();
+    if (db) {
+        try {
+            const rows: any[] = db.prepare(
+                `SELECT id, started_at, ended_at, message_count, title
+                 FROM sessions
+                 WHERE source = 'cli' AND message_count > 0
+                 ORDER BY started_at DESC LIMIT 100`,
+            ).all();
+            const mtime = statMtimeMs(HERMES_STATE_DB);
+            for (const r of rows) {
+                out.push({
+                    historySessionId: String(r.id),
+                    sessionId: String(r.id),
+                    sourcePath: HERMES_STATE_DB,
+                    sourceMtimeMs: mtime,
+                    messageCount: Number(r.message_count) || 0,
+                    firstMessageAt: Math.floor(Number(r.started_at) * 1000),
+                    lastMessageAt: Math.floor(Number(r.ended_at || r.started_at) * 1000),
+                    sessionTitle: typeof r.title === 'string' ? r.title : undefined,
+                });
+            }
+        } finally {
+            try { db.close(); } catch { /* ignore */ }
+        }
+    }
+
+    if (fs.existsSync(HERMES_LEGACY_SESSIONS_DIR)) {
+        for (const name of fs.readdirSync(HERMES_LEGACY_SESSIONS_DIR)) {
+            if (!/^session_.*\.json$/.test(name)) continue;
+            const p = path.join(HERMES_LEGACY_SESSIONS_DIR, name);
+            const mtime = statMtimeMs(p);
+            if (!mtime) continue;
+            let raw: any;
+            try { raw = JSON.parse(fs.readFileSync(p, 'utf8')); } catch { continue; }
+            const msgs = Array.isArray(raw?.messages) ? raw.messages : [];
+            if (msgs.length === 0) continue;
+            const sessionId = typeof raw.session_id === 'string' && raw.session_id
+                ? raw.session_id
+                : name.replace(/^session_/, '').replace(/\.json$/, '');
+            out.push({
+                historySessionId: sessionId,
+                sessionId,
+                sourcePath: p,
+                sourceMtimeMs: mtime,
+                messageCount: msgs.length,
+                firstMessageAt: Number(raw.session_start) || mtime,
+                lastMessageAt: Number(raw.last_updated) || mtime,
+                sessionTitle: typeof raw.title === 'string' ? raw.title : undefined,
+                preview: typeof msgs[0]?.content === 'string' ? String(msgs[0].content).slice(0, 80) : undefined,
+            });
+        }
+    }
+
+    out.sort((a, b) => b.sourceMtimeMs - a.sourceMtimeMs);
+    return out;
+}
+
+function normalizeHermesRole(r: any): 'user' | 'assistant' | 'system' {
+    const s = String(r ?? '').toLowerCase();
+    if (s === 'user' || s === 'human') return 'user';
+    if (s === 'assistant' || s === 'ai' || s === 'model') return 'assistant';
+    if (s === 'tool' || s === 'tool_result' || s === 'function') return 'assistant';
+    return 'system';
+}

package/src/providers/native-history/index.ts

@@ -21,3 +21,10 @@ export {
   readSession as readAntigravityCliSession,
   listSessions as listAntigravityCliSessions,
 } from './antigravity-cli-transcript.js';
+
+export {
+  readSession as readHermesCliSession,
+  listSessions as listHermesCliSessions,
+} from './hermes-cli-transcript.js';
+
+export { createNativeHistoryDispatcher, type ReaderId } from './dispatcher.js';

package/src/providers/provider-loader.ts

@@ -1084,6 +1084,125 @@ export class ProviderLoader {
       };
     }
 
+    // (spec migration) Late-binding spec.json native-history hook. Runs
+    // *after* every script-loading path (compatibility / defaultScriptDir /
+    // overrides) so it deterministically wins over a legacy v1 scripts.js
+    // export. Three modes, picked by spec.json's native_history block:
+    //   1. source     — declarative jsonl/sqlite executor (new-provider path,
+    //                   no daemon change needed for new on-disk formats)
+    //   2. override_path — provider-supplied reader file (escape hatch for
+    //                   exotic formats); module default-exports a reader fn
+    //   3. reader     — built-in reader id (claude-cli / codex-cli /
+    //                   antigravity-cli / hermes-cli), kept for backwards
+    //                   compatibility with the four shipped providers
+    if (providerDir) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const fs = require('node:fs');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const path = require('node:path');
+        // Pick the right spec file for the detected CLI version. Resolution
+        // order:
+        //   1. compatibility[i].spec where ideVersion matches currentVersion
+        //      (lets a provider ship specs/2.0.json, specs/2.1.json, etc.
+        //      alongside the matching scriptDir)
+        //   2. specs/default.json — explicit fallback
+        //   3. spec.json — legacy single-spec layout
+        // Missing files fall through silently to the next candidate.
+        const candidates: string[] = [];
+        if (Array.isArray((base as any).compatibility)) {
+          for (const entry of (base as any).compatibility) {
+            if (typeof entry?.spec !== 'string') continue;
+            // If currentVersion is unknown (cli-manager hasn't probed yet)
+            // we still let compatibility entries that don't pin a version
+            // through, plus any entry whose pin matches.
+            const matches = !entry.ideVersion
+              || (currentVersion && this.matchesVersion(currentVersion, entry.ideVersion))
+              || !currentVersion;
+            if (matches) candidates.push(path.join(providerDir, entry.spec));
+          }
+        }
+        candidates.push(path.join(providerDir, 'specs', 'default.json'));
+        candidates.push(path.join(providerDir, 'spec.json'));
+        const specPath = candidates.find((p: string) => fs.existsSync(p));
+        if (specPath) {
+          // Hand the resolved spec path off to route.ts via a hidden field
+          // so the routing layer doesn't have to repeat the candidate walk.
+          (resolved as any)._resolvedSpecPath = specPath;
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { loadSpec } = require('./spec/loader.js');
+          const r = loadSpec(specPath);
+          // Stub each control_bar entry as a provider.scripts.<id>. The
+          // upstream invoke_provider_script gate checks that the script
+          // name exists on provider.scripts before calling adapter.invokeScript;
+          // for spec providers the *actual* dispatch happens inside
+          // SpecCliAdapter.invokeScript which maps the name to control_bar.
+          // The stub is just a presence marker so the gate doesn't reject.
+          if (r.ok) {
+            const controls = r.spec.control_bar ?? [];
+            if (controls.length > 0) {
+              resolved.scripts = { ...(resolved.scripts || {}) };
+              for (const ctl of controls) {
+                if (!(resolved.scripts as any)[ctl.id]) {
+                  (resolved.scripts as any)[ctl.id] = (..._args: unknown[]) => ({
+                    __spec_control: true,
+                    controlId: ctl.id,
+                    actionType: ctl.action.type,
+                  });
+                }
+              }
+            }
+          }
+          const nh = r.ok ? r.spec.native_history : undefined;
+          if (nh) {
+            let reader: ((input: any) => any) | null = null;
+            let format = 'spec';
+
+            if (nh.source) {
+              // eslint-disable-next-line @typescript-eslint/no-var-requires
+              const { executeNativeHistory } = require('./spec/native-history-executor.js');
+              format = `spec-${nh.source.kind}`;
+              reader = (input: any) => executeNativeHistory(nh, input);
+            } else if (nh.override_path) {
+              const overrideFile = path.resolve(providerDir, nh.override_path);
+              if (fs.existsSync(overrideFile)) {
+                try {
+                  registerProviderScriptRootSafely(path.dirname(path.dirname(providerDir)));
+                  delete require.cache[require.resolve(overrideFile)];
+                  // eslint-disable-next-line @typescript-eslint/no-var-requires
+                  const mod = require(overrideFile);
+                  const fn = typeof mod === 'function' ? mod : (mod && typeof mod.default === 'function' ? mod.default : null);
+                  if (fn) {
+                    format = 'spec-override';
+                    reader = (input: any) => fn(input);
+                  }
+                } catch { /* fall through — leave native unavailable */ }
+              }
+            } else if (nh.reader) {
+              // eslint-disable-next-line @typescript-eslint/no-var-requires
+              const { createNativeHistoryDispatcher } = require('./native-history/dispatcher.js');
+              const dispatch = createNativeHistoryDispatcher(nh.reader);
+              format = nh.reader;
+              reader = (input: any) => dispatch(input);
+            }
+
+            if (reader) {
+              resolved.scripts = { ...(resolved.scripts || {}) };
+              (resolved.scripts as any).readNativeHistory = reader;
+              (resolved as any).nativeHistory = {
+                format,
+                watchPath: undefined,
+                scripts: { readSession: 'readNativeHistory' },
+                mode: 'native-source',
+              };
+            }
+          }
+        }
+      } catch {
+        // Best-effort — spec wiring failure must not break legacy providers.
+      }
+    }
+
     return resolved;
   }
 
@@ -1094,13 +1213,17 @@ export class ProviderLoader {
   private loadScriptsFromDir(type: string, scriptDir: string): Partial<ProviderScripts> | null {
     const providerDir = this.findProviderDirInternal(type);
     if (!providerDir) {
-      this.log(`  [loadScriptsFromDir] ${type}: providerDir not found`);
+      // No provider dir for this type — a spec-only provider with no
+      // legacy scripts/v1 layout is a normal configuration, not a
+      // problem to surface at INFO. resolve() calls this on every
+      // request; INFO spam every 200ms drowns out the real signal.
+      this.debugLog(`[loadScriptsFromDir] ${type}: providerDir not found`);
       return null;
     }
 
     const dir = path.join(providerDir, scriptDir);
     if (!fs.existsSync(dir)) {
-      this.log(`  [loadScriptsFromDir] ${type}: dir not found: ${dir}`);
+      this.debugLog(`[loadScriptsFromDir] ${type}: dir not found: ${dir}`);
       return null;
     }
 
@@ -1121,7 +1244,7 @@ export class ProviderLoader {
       try {
         delete require.cache[require.resolve(scriptsJs)];
         const loaded = require(scriptsJs);
-        this.log(`  [loadScriptsFromDir] ${type}: loaded scripts.js from ${dir} (${Object.keys(loaded).length} exports)`);
+        this.debugLog(`[loadScriptsFromDir] ${type}: loaded scripts.js from ${dir} (${Object.keys(loaded).length} exports)`);
         this.scriptsCache.set(dir, loaded);
         return loaded;
       } catch (e) {

package/src/providers/sdk/v1/schemas/cli/provider.schema.json

@@ -306,6 +306,19 @@
             "instructions":        { "type": "string" },
             "template":            { "type": "string" }
           }
+        },
+        "systemPromptInjection": {
+          "description": "How the coordinator system prompt reaches the launched CLI. Replaces hard-coded router branches per CLI type; users may override the prompt body or the injection mechanism here.",
+          "oneOf": [
+            { "type": "object", "additionalProperties": false, "required": ["mode", "flag"],
+              "properties": { "mode": { "const": "cli_arg" }, "flag": { "type": "string" } } },
+            { "type": "object", "additionalProperties": false, "required": ["mode", "flag", "template"],
+              "properties": { "mode": { "const": "config_override" }, "flag": { "type": "string" }, "template": { "type": "string" } } },
+            { "type": "object", "additionalProperties": false, "required": ["mode", "path"],
+              "properties": { "mode": { "const": "context_file" }, "path": { "type": "string" }, "wrapper": { "type": "string" } } },
+            { "type": "object", "additionalProperties": false, "required": ["mode", "name"],
+              "properties": { "mode": { "const": "env_var" }, "name": { "type": "string" } } }
+          ]
         }
       }
     },