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

package/dist/mesh/coordinator-prompt.d.ts

@@ -8,6 +8,17 @@
  *   3. How to orchestrate work across nodes
  *
  * The prompt is generated dynamically from the current mesh state.
+ *
+ * User customization:
+ *   ~/.adhdev/coordinator-prompts/<cliType>.md         — full override
+ *   ~/.adhdev/coordinator-prompts/<cliType>.append.md  — appended to default
+ *   ~/.adhdev/coordinator-prompts/default.md           — full override (any CLI)
+ *   ~/.adhdev/coordinator-prompts/default.append.md    — appended to default (any CLI)
+ *
+ * CLI-specific files take precedence over default.* files. The override file
+ * still gets the node/policy facts substituted via the same {{placeholders}}
+ * the daemon understands; an override that doesn't reference them just gets
+ * a static prompt, which is also fine.
  */
 import type { LocalMeshEntry, RepoMeshStatus } from '../repo-mesh-types.js';
 export interface CoordinatorPromptContext {
@@ -16,4 +27,23 @@ export interface CoordinatorPromptContext {
     userInstruction?: string;
     coordinatorCliType?: string;
 }
+/**
+ * Compose the final coordinator prompt from four layers, in this precedence:
+ *
+ *   1. Per-launch `extraSystemPrompt` (always appended, as "## Additional
+ *      Context"). Never wins as a base — it's launch-scope context.
+ *   2. Mesh-level append (`mesh.coordinator.systemPromptAppend` or the legacy
+ *      `systemPromptSuffix`). Stacks after whichever base won.
+ *   3. User-file append (`~/.adhdev/coordinator-prompts/<cli>.append.md` or
+ *      `default.append.md`). Also stacks; same placeholder expansion as the
+ *      override path.
+ *   4. Base prompt, picked in this order:
+ *      a. `mesh.coordinator.systemPromptOverride` (mesh-level override)
+ *      b. user-file override (`~/.adhdev/coordinator-prompts/<cli>.md` or
+ *         `default.md`)
+ *      c. daemon default (assembled from identity/nodes/policy/tools/…)
+ *
+ * That layering lets a user customize prompts at three increasing scopes
+ * (machine, mesh, single launch) without losing the daemon's stock rules.
+ */
 export declare function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string;

package/dist/mesh/coordinator-registry.d.ts

@@ -12,12 +12,46 @@ export interface CoordinatorRegistryEntry {
     sessionId: string;
     workspace?: string;
     startedAt: number;
+    /** CLI type used to launch the coordinator (claude-cli / codex-cli / …). */
+    cliType?: string;
+    /** Final system prompt sent to the coordinator after all overrides, appends,
+     *  and extraSystemPrompt have been applied. Surfaced via the session-info
+     *  endpoint so users can audit exactly what prompt the agent saw. */
+    systemPrompt?: string;
+    /** Per-launch extraSystemPrompt the caller passed in, if any. Stored
+     *  separately from `systemPrompt` so the UI can show what the user
+     *  added vs. what the daemon's default template produced. */
+    extraSystemPrompt?: string;
+    /** How the prompt was actually injected (cli_arg / context_file / …). */
+    injection?: {
+        mode: string;
+        target?: string;
+    };
+    /** Path of the MCP config file the daemon wrote for this session. */
+    mcpConfigPath?: string;
 }
 /** Load persisted coordinator registry from disk into in-memory map. Called once on daemon boot. */
 export declare function loadMeshCoordinatorRegistry(): void;
 /** Register a coordinator session. Persists to disk immediately. */
 export declare function registerMeshCoordinator(entry: CoordinatorRegistryEntry): void;
-/** Remove a coordinator session by sessionId. Persists to disk. */
+/** Remove a coordinator session by sessionId. Persists to disk.
+ *
+ * Also best-effort strips any context_file wrapper block we wrote into
+ * the workspace at launch time (AGENTS.md / GEMINI.md), because those
+ * files are auto-loaded by their CLIs on every subsequent launch — and
+ * a wrapper block surviving the coordinator session would silently
+ * inject the coordinator system prompt into ordinary non-coordinator
+ * sessions in the same workspace, which is exactly the bug we're
+ * fixing here.
+ *
+ * Stripping rules:
+ *   - Look for the start sentinel anywhere in the file; if absent,
+ *     leave the file alone (user-authored content).
+ *   - If the wrapper block was the only thing in the file, delete the
+ *     file outright so we don't leave behind an empty AGENTS.md.
+ *   - Otherwise drop only the block between the sentinels and trim a
+ *     leading/trailing blank line so we don't leave dangling separators.
+ */
 export declare function unregisterMeshCoordinator(sessionId: string): void;
 /** Look up a coordinator entry by session ID. Returns undefined if not registered. */
 export declare function getCoordinatorForSession(sessionId: string): CoordinatorRegistryEntry | undefined;

package/dist/providers/cli-provider-instance.d.ts

@@ -94,7 +94,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     setPresentationMode(mode: 'terminal' | 'chat'): void;
     getPresentationMode(): 'terminal' | 'chat';
     getHotChatSessionState(): HotChatSessionState;
-    getSessionModalState(): SessionModalState;
+    getSessionModalState(sessionId?: string): SessionModalState;
     updateSettings(newSettings: Record<string, any>): void;
     onEvent(event: string, data?: any): void;
     recordAcknowledgedUserInput(input: InputEnvelope | string): void;

package/dist/providers/contracts.d.ts

@@ -305,7 +305,55 @@ 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;

package/dist/providers/native-history/antigravity-cli-transcript.d.ts

@@ -86,7 +86,7 @@ export interface NativeHistorySessionMeta {
  *
  * Returns `null` when the file is missing, empty, or yields no parseable messages.
  */
-export declare function readSession(sessionPath: string, sessionId?: string, workspace?: string): Promise<NativeHistorySession | null>;
+export declare function readSession(sessionPath: string, sessionId?: string, workspace?: string): NativeHistorySession | null;
 /**
  * List all Antigravity CLI sessions found across all watchPath locations.
  *

package/dist/providers/native-history/claude-cli-transcript.d.ts

@@ -56,7 +56,7 @@ export interface NativeHistorySessionMeta {
  * `sessionPath` is the absolute path to a `<uuid>.jsonl` file.
  * Returns `null` when the file is missing, empty, or yields no parseable messages.
  */
-export declare function readSession(sessionPath: string): Promise<NativeHistorySession | null>;
+export declare function readSession(sessionPath: string): NativeHistorySession | null;
 /**
  * List all Claude Code sessions under the given glob-style watchPath base dir.
  *

package/dist/providers/native-history/codex-cli-transcript.d.ts

@@ -60,7 +60,7 @@ export interface NativeHistorySessionMeta {
  * under ~/.codex/sessions/.
  * Returns `null` when the file is missing, empty, or yields no parseable messages.
  */
-export declare function readSession(sessionPath: string): Promise<NativeHistorySession | null>;
+export declare function readSession(sessionPath: string): NativeHistorySession | null;
 /**
  * List all Codex CLI sessions under the given watchPath base dir.
  *

package/dist/providers/native-history/dispatcher.d.ts

@@ -0,0 +1,24 @@
+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 declare function createNativeHistoryDispatcher(reader: ReaderId): (input: NativeHistoryInput) => NativeHistoryResult | null;

package/dist/providers/native-history/hermes-cli-transcript.d.ts

@@ -0,0 +1,30 @@
+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;
+}
+export declare function readSession(sessionPath: string): NativeHistorySession | null;
+export declare function listSessions(_watchPath: string): Promise<NativeHistorySessionMeta[]>;

package/dist/providers/native-history/index.d.ts

@@ -9,3 +9,5 @@
 export { readSession as readClaudeCliSession, listSessions as listClaudeCliSessions, } from './claude-cli-transcript.js';
 export { readSession as readCodexCliSession, listSessions as listCodexCliSessions, } from './codex-cli-transcript.js';
 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/dist/providers/spec/adapter.d.ts

@@ -0,0 +1,56 @@
+import { type PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+export interface TerminalAdapterOpts {
+    binary: string;
+    args?: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    /** Coalesce screen snapshots: emit on_screen_changed at most this often. */
+    screenChangeDebounceMs?: number;
+    /** tick() period. 0 disables ticks. */
+    tickIntervalMs?: number;
+    /**
+     * Optional PTY transport factory. When the daemon supplies a
+     * SessionHostPtyTransportFactory (standalone runs the PTY inside the
+     * session-host so the runtime/<sid>/snapshot endpoint can serve it),
+     * forward it here. Without it the PTY spawns locally inside the
+     * daemon process and the dashboard's terminal pane reports
+     * "Runtime terminal unavailable: Unknown session".
+     */
+    transportFactory?: PtyTransportFactory;
+}
+export interface TerminalAdapterHandlers {
+    init?(info: {
+        pid: number;
+    }): void;
+    on_pty_data?(chunk: string): void;
+    on_screen_changed?(snapshot: string): void;
+    tick?(): void;
+    on_exit?(info: {
+        exitCode: number;
+    }): void;
+}
+export declare class TerminalAdapter {
+    private readonly opts;
+    private readonly handlers;
+    private term;
+    private pty;
+    private factory;
+    private cols;
+    private rows;
+    private screenDebounceMs;
+    private tickIntervalMs;
+    private screenTimer;
+    private tickTimer;
+    private lastScreen;
+    constructor(opts: TerminalAdapterOpts, handlers: TerminalAdapterHandlers);
+    start(): void;
+    send_keys(s: string): void;
+    resize(cols: number, rows: number): void;
+    snapshot(): string;
+    kill(): void;
+    private onChunk;
+    private computeScreen;
+    private stopTimers;
+}

package/dist/providers/spec/cli-adapter.d.ts

@@ -0,0 +1,76 @@
+import type { CliAdapter, CliAdapterStatus } from '../../cli-adapter-types.js';
+import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+export declare class SpecCliAdapter implements CliAdapter {
+    readonly cliType: string;
+    readonly cliName: string;
+    readonly workingDir: string;
+    private driver;
+    private spec;
+    private lastEvent;
+    private latestState;
+    private latestModal;
+    private statusCallback;
+    private ptyDataCallback;
+    private partialResponse;
+    private exited;
+    private spawned;
+    private providerSessionId;
+    /** Wall clock at the moment spawn() ran. Used as the cutoff for
+     *  native-history file selection so a prior session's transcript
+     *  can't leak into this session before the agent has written its
+     *  own records. */
+    private spawnedAtMs;
+    /** Env vars the daemon set on the spawned child. Mesh coordinator
+     *  points hermes at a per-coordinator HERMES_HOME so the dashboard's
+     *  native-history reader needs that override to find the right
+     *  state.db; without it the reader sees ~/.hermes/state.db which
+     *  the coordinator-launched hermes never writes to. The choice to
+     *  redirect HERMES_HOME is a workaround for an unresolved hermes
+     *  upstream feature gap (see hermes-agent#23130 — runtime-supplied
+     *  MCP config), so this routing keeps the dashboard honest until
+     *  hermes ships a runtime MCP override. */
+    private spawnedEnv;
+    constructor(specPath: string, workingDir: string, cliArgs: string[], extraEnv: Record<string, string>, transportFactory?: PtyTransportFactory);
+    spawn(): Promise<void>;
+    sendMessage(text: string): Promise<void>;
+    getStatus(): CliAdapterStatus;
+    private maybeRefreshNativeHistory;
+    getScriptParsedStatus(): unknown;
+    getPartialResponse(): string;
+    shutdown(): void;
+    cancel(): void;
+    isProcessing(): boolean;
+    isReady(): boolean;
+    setOnStatusChange(cb: () => void): void;
+    setOnPtyData(cb: (data: string) => void): void;
+    writeRaw(data: string): void;
+    resize(cols: number, rows: number): void;
+    resolveModal(buttonIndex: number): void;
+    resolveAction(data: unknown): Promise<void>;
+    isApprovalRecentlyResolved(): boolean;
+    clearHistory(): void;
+    updateRuntimeSettings(): void;
+    setServerConn(): void;
+    /**
+     * Map an invokeScript(name, args) call onto a control_bar entry.
+     *
+     * scriptName is matched against control.id. The control's action.type
+     * drives the dispatch:
+     *
+     *   send_keys     → click_control                   (e.g. stop)
+     *   open_picker   → click_control then resolve when extract_choices
+     *                   surface; choice index comes from args.choiceIndex
+     *                   or args.choice (string label match), defaulting to 0
+     *   attach_image  → attach_image dispatch; expects args.blob (data url
+     *                   or base64) and args.mime
+     *
+     * Callers that pass an unknown control id get a { not_found } response.
+     * No control matched, no driver call — keeps the surface honest.
+     */
+    invokeScript(scriptName: string, args?: Record<string, unknown>): Promise<unknown>;
+    getDebugSnapshot(): unknown;
+    getRuntimeMetadata(): unknown;
+    updateRuntimeMeta(meta?: Record<string, unknown>): void;
+    refreshProviderDefinition(): void;
+    private handleEvent;
+}

package/dist/providers/spec/driver.d.ts

@@ -0,0 +1,148 @@
+import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import { type TraceEntry } from './evaluator.js';
+export type DashboardEvent = {
+    kind: 'pty_data';
+    chunk: string;
+} | {
+    kind: 'state_changed';
+    state: {
+        id: string;
+        label: string;
+        title: string | null;
+    };
+    modal: {
+        title: string | null;
+        buttons: {
+            index: number;
+            label: string;
+        }[];
+    } | null;
+    controls: {
+        id: string;
+        label: string;
+        action_type: string;
+    }[];
+} | {
+    kind: 'notification';
+    id: string;
+    title: string;
+    body: string;
+} | {
+    kind: 'delegate';
+    id: string;
+    task: string;
+} | {
+    kind: 'spec_trace';
+    entries: TraceEntry[];
+} | {
+    kind: 'exit';
+    exit_code: number;
+} | {
+    kind: 'spec_error';
+    errors: string[];
+};
+export type DashboardCommand = {
+    kind: 'send_message';
+    text: string;
+} | {
+    kind: 'pty_write';
+    data: string;
+} | {
+    kind: 'click_control';
+    control_id: string;
+    payload?: unknown;
+} | {
+    kind: 'click_modal_button';
+    index: number;
+} | {
+    kind: 'attach_image';
+    blob: string;
+    mime: string;
+} | {
+    kind: 'resize';
+    cols: number;
+    rows: number;
+} | {
+    kind: 'cancel';
+} | {
+    kind: 'shutdown';
+};
+export interface SpecDriverOpts {
+    specPath: string;
+    workingDir: string;
+    extraEnv?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    /** Set false to skip the spec.json fs.watch. */
+    hotReload?: boolean;
+    /** Set true to forward trace entries on every state_changed. */
+    emitTrace?: boolean;
+    /** Inject the daemon's PTY transport (typically SessionHostPtyTransportFactory). */
+    transportFactory?: PtyTransportFactory;
+    /**
+     * Extra CLI args appended to spec.spawn_args. Used by the daemon to
+     * pass per-launch arguments like `--session-id <uuid>` so the agent
+     * uses the daemon's providerSessionId instead of generating its own.
+     */
+    extraCliArgs?: string[];
+}
+export declare class SpecDriver {
+    private readonly opts;
+    private spec;
+    private adapter;
+    private listeners;
+    private currentStateId;
+    /** Have we ever seen the spec's idle state *after* the startup grace
+     *  window? Until we do, the agent's startup banner may still be
+     *  painting and any send_message we forward to the PTY will be wiped
+     *  when the banner clears the screen. Queue + drain on first valid
+     *  idle. */
+    private idleSeenOnce;
+    private startedAtMs;
+    private pendingSends;
+    private currentEval;
+    private pickerInProgress;
+    private delegateTimers;
+    /** Timestamp of the last time the evaluator returned busy. Used to debounce
+     *  the busy → idle transition (see reevaluate). */
+    private lastBusyAt;
+    /** The exact busy state object we last saw — held alongside lastBusyAt so
+     *  the hold can re-emit the same { id: 'busy', label, title } payload the
+     *  dashboard already learned about. currentEval can't fill this role
+     *  because the evaluator already moved past busy by the time the hold
+     *  kicks in. */
+    private lastBusyState;
+    /** Timer that re-runs evaluate() once the hold window expires. Needed
+     *  because the PTY stops emitting once the agent finishes; without an
+     *  explicit wake-up there's nothing to trigger the busy → idle
+     *  downshift. */
+    private busyExpiryTimer;
+    private specWatcher;
+    constructor(opts: SpecDriverOpts);
+    /** Subscribe to outbound events. Returns an unsubscribe fn. */
+    subscribe(listener: (ev: DashboardEvent) => void): () => void;
+    start(): void;
+    dispatch(cmd: DashboardCommand): void;
+    shutdown(): void;
+    private loadSpecOrThrow;
+    private buildAdapterOpts;
+    private armSpecWatcher;
+    private emitInitialState;
+    /** Re-arm the timer that wakes the driver up after BUSY_HOLD_MS so it
+     *  can decide whether to downshift to idle. Always uses the most recent
+     *  hold value so a spec hot-reload that shortens the hold takes effect
+     *  on the next busy entry. Safe to call repeatedly; only the last call
+     *  fires. */
+    private scheduleBusyExpiry;
+    private reevaluate;
+    private armOrCancelDelegateTimers;
+    private fireDelegate;
+    private handleSendMessage;
+    private actuallySendMessage;
+    private handleClickControl;
+    private handleClickModalButton;
+    private handleAttachImage;
+    private tryAdvancePicker;
+    private handleExit;
+    private emit;
+}

package/dist/providers/spec/evaluator.d.ts

@@ -0,0 +1,47 @@
+import type { CliSpec } from './types.js';
+export interface ResolvedSection {
+    id: string;
+    fromLine: number;
+    toLine: number;
+    text: string;
+}
+export interface ModalSnapshot {
+    title: string | null;
+    buttons: {
+        index: number;
+        label: string;
+        key: string;
+    }[];
+}
+export interface VisibleControl {
+    id: string;
+    label: string;
+    actionType: 'send_keys' | 'open_picker' | 'attach_image';
+}
+export interface FiredNotification {
+    id: string;
+    title: string;
+    body: string;
+}
+export interface FiredDelegate {
+    id: string;
+    task: string;
+}
+export interface TraceEntry {
+    kind: 'section' | 'state_match' | 'state_skip' | 'modal' | 'control' | 'notification' | 'delegate';
+    text: string;
+}
+export interface SpecEvaluation {
+    state: {
+        id: string;
+        label: string;
+        title: string | null;
+    };
+    modal: ModalSnapshot | null;
+    controls: VisibleControl[];
+    notifications: FiredNotification[];
+    delegates: FiredDelegate[];
+    sections: ResolvedSection[];
+    trace: TraceEntry[];
+}
+export declare function evaluate(spec: CliSpec, screenText: string): SpecEvaluation;

package/dist/providers/spec/loader.d.ts

@@ -0,0 +1,14 @@
+import type { CliSpec } from './types.js';
+export interface SpecLoadResult {
+    ok: true;
+    spec: CliSpec;
+    sourcePath: string;
+}
+export interface SpecLoadError {
+    ok: false;
+    errors: string[];
+    sourcePath: string;
+}
+export declare function loadSpec(sourcePath: string): SpecLoadResult | SpecLoadError;
+/** Convenience: look up a provider's spec.json next to its provider dir. */
+export declare function resolveSpecPath(providerDir: string): string;

package/dist/providers/spec/native-history-executor.d.ts

@@ -0,0 +1,39 @@
+import type { NativeHistoryConfig } from './types.js';
+export interface NativeHistoryInput {
+    agentType?: string;
+    sessionId?: string;
+    providerSessionId?: string;
+    historySessionId?: string;
+    workspace?: string;
+    /** Daemon-side wall clock at the moment the session was registered.
+     *  Native-history file lookups use this as the lower bound: any file
+     *  whose mtime is before the current session started can't be from
+     *  this session, so it's excluded from newest-recent matching. The
+     *  caller (chat-history pipeline) populates this from the session
+     *  registry; specs/executor never need to know how it's sourced. */
+    sessionStartedAtMs?: number;
+    /** Env overrides the daemon set on the spawned CLI. The mesh
+     *  coordinator points hermes at a per-coordinator HERMES_HOME so
+     *  the hermes process writes its state.db into a tmp directory
+     *  instead of ~/.hermes. expandPath consults this map before
+     *  process.env so the native-history reader follows the spawned
+     *  child's view of HERMES_HOME / similar overrides; without it
+     *  the reader would always look at ~/.hermes and miss every
+     *  coordinator-session transcript. */
+    envOverrides?: Record<string, string>;
+    args?: Record<string, unknown>;
+}
+export interface NativeHistoryMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    receivedAt: number;
+    kind?: string;
+}
+export interface NativeHistoryResult {
+    messages: NativeHistoryMessage[];
+    providerSessionId?: string;
+    sourcePath: string;
+    sourceMtimeMs: number;
+    nativeHistoryCoverage?: 'full' | 'partial' | 'best-effort';
+}
+export declare function executeNativeHistory(cfg: NativeHistoryConfig, input: NativeHistoryInput): NativeHistoryResult | null;

package/dist/providers/spec/route.d.ts

@@ -0,0 +1,4 @@
+import type { CliProviderModule } from '../../cli-adapters/provider-cli-adapter.js';
+import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import type { CliAdapter } from '../../cli-adapter-types.js';
+export declare function createCliAdapter(provider: CliProviderModule, workingDir: string, cliArgs: string[], extraEnv: Record<string, string>, transportFactory?: PtyTransportFactory): CliAdapter;