@adhdev/daemon-core 0.9.82-rc.17 → 0.9.82-rc.171

package/src/providers/contracts.ts

@@ -15,6 +15,14 @@ import type { ChatMessageKind } from './chat-message-normalization.js';
 export type ReadChatTurnStatus = 'open' | 'waiting_approval' | 'complete' | 'error';
 
 export interface ReadChatResult {
+  /**
+   * Declared chat contract version. Absent or `'1.0'` → legacy v1 payload
+   * (current shape). `'2.0'` → v2 payload conforming to transcript-v2.ts
+   * (ReadChatResultV2). Validators in read-chat-contract.ts route on this
+   * field. A1 only adds the field; A2 will make v2 the daemon-internal
+   * canonical form and reject unrecognised versions at provider load time.
+   */
+  contractVersion?: import('./transcript-v2.js').ChatContractVersion;
   messages: ChatMessage[];
   status: AgentStatus;
   activeModal?: ModalInfo | null;
@@ -385,8 +393,61 @@ export interface ProviderMeshCoordinatorConfig {
     /** Copyable setup template. Supports {{meshId}}, {{adhdevMcpCommand}}, {{workspace}}, {{serverName}}. */
     template?: string;
   };
+  /**
+   * How the coordinator system prompt reaches the launched CLI. Replaces the
+   * old hard-coded `if (cliType === 'claude-cli') push --append-system-prompt`
+   * branches in router.ts: a new CLI now ships its injection rule in its
+   * provider.v1.json, no daemon code change needed. Users can override the
+   * rendered prompt or the injection mechanism per-provider; if omitted, no
+   * system prompt is injected (safe default — won't crash spawn with a flag
+   * the CLI doesn't recognize).
+   */
+  systemPromptInjection?: MeshCoordinatorSystemPromptInjection;
 }
 
+/**
+ * Declarative description of how a CLI accepts a session-scoped system prompt.
+ *
+ * Modes:
+ *   - cli_arg          → push `flag` + prompt onto spawn args                (Claude)
+ *   - config_override  → push `flag` + a templated key=value config override (Codex)
+ *   - context_file     → write prompt into a workspace markdown the CLI
+ *                        auto-loads as project context                       (Gemini, Antigravity)
+ *   - env_var          → expose prompt to the spawned process as $name       (Hermes)
+ *
+ * The prompt text is templated with `{prompt}` (raw) or `{prompt_json}`
+ * (JSON-encoded for embedding inside config-override strings).
+ */
+export type MeshCoordinatorSystemPromptInjection =
+  | {
+      mode: 'cli_arg';
+      /** Spawn-args flag, e.g. '--append-system-prompt'. The prompt becomes the next argv. */
+      flag: string;
+    }
+  | {
+      mode: 'config_override';
+      /** Spawn-args flag, e.g. '-c'. Followed by `template` with placeholders rendered. */
+      flag: string;
+      /** Template using {prompt} or {prompt_json}, e.g. 'developer_instructions={prompt_json}'. */
+      template: string;
+    }
+  | {
+      mode: 'context_file';
+      /** Workspace-relative file path the CLI auto-loads, e.g. 'AGENTS.md' or 'GEMINI.md'. */
+      path: string;
+      /**
+       * Optional wrapper around the prompt. Use `{prompt}` placeholder. Existing
+       * wrapper-delimited blocks are replaced rather than duplicated, so re-launching
+       * a coordinator doesn't pile up copies. If omitted, the prompt is appended raw.
+       */
+      wrapper?: string;
+    }
+  | {
+      mode: 'env_var';
+      /** Env-var name, e.g. 'HERMES_EPHEMERAL_SYSTEM_PROMPT'. */
+      name: string;
+    };
+
 export interface ProviderCompatibilityEntry {
   ideVersion: string;
   scriptDir: string;
@@ -472,6 +533,14 @@ export interface ProviderModule {
   extensionIdPattern_flags?: string;
   compatibility?: ProviderCompatibilityEntry[];
   defaultScriptDir?: string;
+  /**
+   * v1 declarative tui block (spinner/settledPrompt/modal/dispatchOrder/etc).
+   * When present, the daemon's CliScriptRunner builds canonical
+   * (input → verdict) functions from this and injects them into provider
+   * scripts as `sdk.declarativeDetectStatus` and `sdk.declarativeParseApproval`.
+   * v0 / verified-tier providers can omit this entirely.
+   */
+  tui?: Record<string, unknown>;
   /**
    * Scripts that can run at the IDE main-page level (not just inside the extension webview session frame).
    * Default: ['listModes', 'setMode', 'listModels', 'setModel'].
@@ -525,8 +594,16 @@ export interface ProviderModule {
   /** History behavior config — controls message filtering and collapse during replay */
   historyBehavior?: ProviderHistoryBehavior;
   /**
-   * Canonical history sync config — for providers that maintain native history files.
-   * When set, daemon syncs from native format into ADHDev JSONL store on each tick.
+   * Native history config — for providers that maintain native history files.
+   * When set, daemon reads/lists provider-native transcripts directly. This is
+   * the canonical v1 field name; the legacy `canonicalHistory` field name is
+   * still accepted by the loader and aliased onto this field at load time.
+   */
+  nativeHistory?: NativeHistoryConfig;
+  /**
+   * @deprecated Legacy v0 alias for {@link ProviderModule.nativeHistory}.
+   * Loader populates this from `nativeHistory` so existing internal readers
+   * keep working during the transition. Remove after one release.
    */
   canonicalHistory?: ProviderCanonicalHistoryConfig;
   /**
@@ -672,7 +749,7 @@ export interface ProviderHistoryBehavior {
  * daemon-core. They let each provider own native transcript file discovery and
  * parsing while daemon-core only validates/pages the normalized result.
  */
-export interface ProviderCanonicalHistoryScriptsConfig {
+export interface NativeHistoryScriptsConfig {
   /** Reads one native session. Default: 'readNativeHistory'. */
   readSession?: string;
   /** Lists native sessions with summary metadata. Default: 'listNativeHistory'. */
@@ -680,13 +757,19 @@ export interface ProviderCanonicalHistoryScriptsConfig {
 }
 
 /**
- * Canonical history sync config — for providers that maintain their own native history files.
+ * @deprecated Use {@link NativeHistoryScriptsConfig}. Retained as an alias for
+ * one release so external consumers that referenced the old name keep compiling.
+ */
+export type ProviderCanonicalHistoryScriptsConfig = NativeHistoryScriptsConfig;
+
+/**
+ * Native history config — for providers that maintain their own native history files.
  *
  * Preferred mode is provider-owned scripts via `scripts`. `format` is now an
  * opaque provider label retained for diagnostics/backward compatibility; daemon
  * live paths must not branch on provider-specific format values.
  */
-export interface ProviderCanonicalHistoryConfig {
+export interface NativeHistoryConfig {
   /** Opaque provider-owned history format label. */
   format?: string;
   /** Optional native history glob/template for diagnostics only. */
@@ -702,8 +785,25 @@ export interface ProviderCanonicalHistoryConfig {
    * Omitted mode defaults to 'native-source'.
    */
   mode?: 'native-source' | 'materialized-mirror' | 'disabled';
+  /**
+   * Chat transcript contract version this provider's read_chat output
+   * conforms to. See transcript-v2.ts for the v2 invariants. Absent or `'1.0'`
+   * → legacy v1 payload (current behaviour). `'2.0'` → strict v2 payload
+   * (stable providerUnitKey/bubbleId/sequence, strict enums, honest coverage).
+   *
+   * A1 only surfaces this field; validators in read-chat-contract.ts route
+   * on it. A2 makes v2 the daemon-internal canonical form and rejects
+   * unrecognised values at provider load time.
+   */
+  contractVersion?: import('./transcript-v2.js').ChatContractVersion;
 }
 
+/**
+ * @deprecated Use {@link NativeHistoryConfig}. Retained as an alias for one
+ * release so external consumers that referenced the old name keep compiling.
+ */
+export type ProviderCanonicalHistoryConfig = NativeHistoryConfig;
+
 /**
  * Auto-implement spawn config — controls how the provider is spawned for autonomous AI-driven
  * provider script implementation (dev-auto-implement.ts).

package/src/providers/external-sources.ts

@@ -0,0 +1,218 @@
+/**
+ * External provider sources — registry + active-selection state.
+ *
+ * A user can register one or more 3rd-party git URLs as provider sources.
+ * Each source clones into ~/.adhdev/external/<source-name>/, namespaced so
+ * that two sources can disk-coexist providing the same provider type.
+ *
+ * When two sources expose the same type, only one is "active" at a time.
+ * The active selection is persisted so a user's choice survives daemon
+ * restarts. When only one source provides a type, no explicit selection
+ * is needed and the loader falls through to that source.
+ */
+'use strict';
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export interface ExternalSource {
+    /** Unique short identifier, e.g. "@vendor-x". User-supplied or derived from the URL. */
+    name: string;
+    /** Full git URL (https://, git@, …). */
+    url: string;
+    /** Branch / tag / commit-ish to track. Defaults to `main`. */
+    ref: string;
+    /** ISO timestamp when first registered. */
+    addedAt: string;
+}
+
+export interface ExternalSourcesFile {
+    /** Schema version — bump if shape changes. */
+    schema: 1;
+    sources: ExternalSource[];
+}
+
+/**
+ * Per-type active source selection. Only types reachable from more than
+ * one source need an entry — single-source types have no ambiguity.
+ *
+ * Shape: { active: { "<type>": "<source-name>" } }
+ */
+export interface ProvidersActiveFile {
+    schema: 1;
+    active: Record<string, string>;
+}
+
+const SOURCES_FILENAME = 'providers-sources.json';
+const ACTIVE_FILENAME = 'providers-active.json';
+
+function adhdevDir(): string {
+    return path.join(os.homedir(), '.adhdev');
+}
+
+export function externalRoot(): string {
+    return path.join(adhdevDir(), 'external');
+}
+
+export function sourcesFilePath(): string {
+    return path.join(adhdevDir(), SOURCES_FILENAME);
+}
+
+export function activeFilePath(): string {
+    return path.join(adhdevDir(), ACTIVE_FILENAME);
+}
+
+function ensureAdhdevDir(): void {
+    const d = adhdevDir();
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}
+
+export function loadExternalSources(): ExternalSourcesFile {
+    const p = sourcesFilePath();
+    if (!fs.existsSync(p)) return { schema: 1, sources: [] };
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (!raw || typeof raw !== 'object') return { schema: 1, sources: [] };
+        const sources = Array.isArray(raw.sources) ? raw.sources.filter(isValidSource) : [];
+        return { schema: 1, sources };
+    } catch {
+        return { schema: 1, sources: [] };
+    }
+}
+
+export function saveExternalSources(file: ExternalSourcesFile): void {
+    ensureAdhdevDir();
+    const tmp = sourcesFilePath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, sourcesFilePath());
+}
+
+export function loadProvidersActive(): ProvidersActiveFile {
+    const p = activeFilePath();
+    if (!fs.existsSync(p)) return { schema: 1, active: {} };
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (!raw || typeof raw !== 'object') return { schema: 1, active: {} };
+        const active = raw.active && typeof raw.active === 'object' ? raw.active : {};
+        return { schema: 1, active };
+    } catch {
+        return { schema: 1, active: {} };
+    }
+}
+
+export function saveProvidersActive(file: ProvidersActiveFile): void {
+    ensureAdhdevDir();
+    const tmp = activeFilePath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, activeFilePath());
+}
+
+function isValidSource(x: unknown): x is ExternalSource {
+    if (!x || typeof x !== 'object') return false;
+    const s = x as Record<string, unknown>;
+    return typeof s.name === 'string' && s.name.length > 0
+        && typeof s.url === 'string' && s.url.length > 0
+        && typeof s.ref === 'string' && s.ref.length > 0
+        && typeof s.addedAt === 'string';
+}
+
+/**
+ * Derive a short identifier from a git URL when the user didn't supply one.
+ *   https://github.com/vendor/extra-providers.git → "@vendor-extra-providers"
+ *   git@github.com:vendor/extra-providers       → "@vendor-extra-providers"
+ *
+ * Idempotent; safe to call before validation since it produces a string
+ * regardless of input shape.
+ */
+export function deriveSourceName(url: string): string {
+    const m = url.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?$/);
+    if (!m) return '@source';
+    const owner = m[1].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    const repo = m[2].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    return `@${owner}-${repo}`;
+}
+
+/**
+ * Return the per-source category/type tree currently on disk under
+ * ~/.adhdev/external/<source>/. Used by the conflict detector and by
+ * list_provider_sources.
+ */
+export interface SourceInventoryEntry {
+    sourceName: string;
+    /** Map: category → list of provider types. */
+    providers: Record<string, string[]>;
+}
+
+export function inventoryExternalSources(): SourceInventoryEntry[] {
+    const root = externalRoot();
+    if (!fs.existsSync(root)) return [];
+    const out: SourceInventoryEntry[] = [];
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(root, { withFileTypes: true }); }
+    catch { return []; }
+    for (const sourceEntry of entries) {
+        if (!sourceEntry.isDirectory()) continue;
+        const sourceName = sourceEntry.name;
+        const sourceDir = path.join(root, sourceName);
+        const providers: Record<string, string[]> = {};
+        let categoryEntries: fs.Dirent[];
+        try { categoryEntries = fs.readdirSync(sourceDir, { withFileTypes: true }); }
+        catch { continue; }
+        for (const categoryEntry of categoryEntries) {
+            if (!categoryEntry.isDirectory()) continue;
+            const category = categoryEntry.name;
+            const categoryDir = path.join(sourceDir, category);
+            let typeEntries: fs.Dirent[];
+            try { typeEntries = fs.readdirSync(categoryDir, { withFileTypes: true }); }
+            catch { continue; }
+            const types: string[] = [];
+            for (const typeEntry of typeEntries) {
+                if (!typeEntry.isDirectory()) continue;
+                // Only count it as a provider if a manifest file exists
+                const typeDir = path.join(categoryDir, typeEntry.name);
+                const hasV1 = fs.existsSync(path.join(typeDir, 'provider.v1.json'));
+                const hasV0 = fs.existsSync(path.join(typeDir, 'provider.json'));
+                if (hasV1 || hasV0) types.push(typeEntry.name);
+            }
+            if (types.length > 0) providers[category] = types;
+        }
+        out.push({ sourceName, providers });
+    }
+    return out;
+}
+
+/**
+ * For a given category+type, list every source that currently exposes it.
+ * Returns source names in disk-walk order; callers can use the first one
+ * when no explicit active selection exists.
+ */
+export function sourcesProviding(category: string, type: string): string[] {
+    const inventory = inventoryExternalSources();
+    return inventory
+        .filter(s => (s.providers[category] || []).includes(type))
+        .map(s => s.sourceName);
+}
+
+/**
+ * Resolve which source should be active for a given category+type.
+ *   - If exactly one source provides it → that source.
+ *   - If multiple sources provide it → the one named in providers-active.json
+ *     (when present) or null (ambiguous; loader should warn and pick
+ *     the first deterministically so daemon doesn't refuse to boot).
+ *   - If none → null.
+ */
+export function resolveActiveSource(
+    category: string,
+    type: string,
+    activeFile?: ProvidersActiveFile,
+): { source: string | null; ambiguous: boolean; candidates: string[] } {
+    const candidates = sourcesProviding(category, type);
+    if (candidates.length === 0) return { source: null, ambiguous: false, candidates };
+    if (candidates.length === 1) return { source: candidates[0], ambiguous: false, candidates };
+    const explicit = (activeFile ?? loadProvidersActive()).active[type];
+    if (explicit && candidates.includes(explicit)) {
+        return { source: explicit, ambiguous: false, candidates };
+    }
+    return { source: candidates[0], ambiguous: true, candidates };
+}

package/src/providers/ide-provider-instance.ts

@@ -20,7 +20,7 @@ import { LOG } from '../logging/logger.js';
 import { buildPersistedProviderEffectMessage, normalizeProviderEffects } from './control-effects.js';
 import { validateReadChatResultPayload } from './read-chat-contract.js';
 import type { ChatMessage } from '../types.js';
-import { formatAutoApprovalMessage, pickApprovalButton } from './approval-utils.js';
+import { formatAutoApprovalMessage, pickAutoApprovalButton } from './approval-utils.js';
 import { mergeProviderPatchState, resolveProviderStateSurface } from './provider-patch-state.js';
 import { buildChatMessage, buildRuntimeSystemChatMessage, normalizeChatMessages, extractFinalSummaryFromMessages } from './chat-message-normalization.js';
 import { getProviderSessionCapabilities, IDE_PROVIDER_SESSION_CAPABILITIES_BASE } from './open-panel-support.js';
@@ -43,6 +43,20 @@ type ReadChatPayload = {
     [key: string]: unknown;
 };
 
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise<never>((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    } finally {
+        if (timer) clearTimeout(timer);
+    }
+}
+
 export class IdeProviderInstance implements ProviderInstance {
     readonly type: string;
     readonly category = 'ide' as const;
@@ -320,7 +334,7 @@ export class IdeProviderInstance implements ProviderInstance {
                 if (webviewScript) {
                     const matchText = this.provider.webviewMatchText;
                     const matchFn = matchText ? (body: string) => body.includes(matchText) : undefined;
-                    const webviewRaw = await cdp.evaluateInWebviewFrame(webviewScript, matchFn);
+                    const webviewRaw = await withTimeout(cdp.evaluateInWebviewFrame(webviewScript, matchFn), 30000, 'evaluateInWebviewFrame');
                     if (webviewRaw) {
                         raw = typeof webviewRaw === 'string' ? (() => { try { return JSON.parse(webviewRaw); } catch { return null; } })() : webviewRaw;
                     }
@@ -331,7 +345,7 @@ export class IdeProviderInstance implements ProviderInstance {
             if (!raw) {
                 const readChatScript = this.getReadChatScript();
                 if (!readChatScript) return;
-                raw = await cdp.evaluate(readChatScript, 30000);
+                raw = await withTimeout(cdp.evaluate(readChatScript, 30000), 30000, 'evaluate.readChatScript');
                 if (typeof raw === 'string') {
                     try { raw = JSON.parse(raw); } catch { return; }
                 }
@@ -694,7 +708,7 @@ export class IdeProviderInstance implements ProviderInstance {
 
         this.autoApproveBusy = true;
         try {
-            const { label: targetButton } = pickApprovalButton(_chatData?.activeModal?.buttons, this.provider);
+            const { label: targetButton } = pickAutoApprovalButton(_chatData?.activeModal?.buttons);
 
             const script = scriptFn({ action: 'approve', button: targetButton, buttonText: targetButton });
             if (!script) return;
@@ -706,7 +720,7 @@ export class IdeProviderInstance implements ProviderInstance {
             );
 
             LOG.info('IdeInstance', `[IdeInstance:${this.type}] autoApprove: executing resolveAction for "${targetButton}"`);
-            let rawResult = await cdp.evaluate(script, 10000);
+            let rawResult = await withTimeout(cdp.evaluate(script, 10000), 10000, 'evaluate.autoApprove');
             if (typeof rawResult === 'string') {
                 try { rawResult = JSON.parse(rawResult); } catch { }
             }