@adhdev/daemon-core 0.9.82-rc.34 → 0.9.82-rc.340

package/src/providers/sdk/v1/builders/cli/parse-session.ts

@@ -0,0 +1,276 @@
+/**
+ * buildParseSessionFromTui — synthesize a parseSession function from the
+ * manifest tui block alone.
+ *
+ * Composition:
+ *   1. detectStatus from tui.spinner/modal/settledPrompt/dispatchOrder
+ *      (delegated to buildDetectStatusFromTui)
+ *   2. parseApproval from tui.modal (delegated to buildParseApprovalFromTui)
+ *   3. message extraction from tui.transcriptPty (this file)
+ *
+ * The result has the same shape as the legacy parse_output:
+ *   { status, messages, activeModal, transcriptAuthority?, coverage?, providerSessionId? }
+ *
+ * Identity stamping (providerUnitKey, bubbleId, sequence, bubbleState) is
+ * applied by the caller, mirroring _shared/parse_session.js. We export the
+ * stamper as `normalizeMessageIdentity` for reuse.
+ */
+
+import { buildDetectStatusFromTui, type DetectStatusTuiSpec } from './detect-status.js'
+import { buildParseApprovalFromTui, type ModalTuiSpec } from './parse-approval.js'
+import * as crypto from 'node:crypto'
+
+// ─── Schema types ────────────────────────────────
+
+export interface PrefixSpec {
+    regex: string
+    flags?: string
+}
+
+export interface ToolPrefixSpec extends PrefixSpec {
+    skip?: boolean
+}
+
+export interface ChromePatternSpec {
+    regex: string
+    flags?: string
+    label?: string
+}
+
+export interface TranscriptPtySpec {
+    $schema?: 'adhdev:tui/transcript-pty@1'
+    assistantPrefix: PrefixSpec
+    userPrefix?: PrefixSpec
+    toolPrefix?: ToolPrefixSpec
+    continuationLine?: { indented?: boolean }
+    chromePatterns?: ChromePatternSpec[]
+    stripLeadingChrome?: boolean
+    scope?: 'screen' | 'buffer' | 'tail'
+}
+
+export interface SessionIdExtractionSpec {
+    $schema?: 'adhdev:tui/session-id-extraction@1'
+    regex: string
+    flags?: string
+    scope?: 'screen' | 'tail' | 'buffer'
+    label?: string
+}
+
+export interface ParseSessionTuiSpec {
+    spinner?: any
+    settledPrompt?: any
+    modal?: ModalTuiSpec
+    dispatchOrder?: any
+    transcriptPty: TranscriptPtySpec
+    sessionIdExtraction?: SessionIdExtractionSpec
+}
+
+// ─── Output shape ────────────────────────────────
+
+export interface SynthesizedMessage {
+    role: 'user' | 'assistant'
+    kind?: 'standard' | 'tool'
+    content: string
+    receivedAt?: number
+}
+
+export interface SynthesizedSession {
+    status: string | null
+    messages: SynthesizedMessage[]
+    activeModal: { message: string; buttons: string[] } | null
+    modal: { message: string; buttons: string[] } | null
+    parsedStatus: string | null
+    transcriptAuthority?: 'provider' | 'daemon'
+    coverage?: 'full' | 'tail' | 'current-turn'
+    providerSessionId?: string
+}
+
+// ─── ANSI / line helpers ─────────────────────────
+
+const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g
+const OSC_RE = /\x1b\][^\x07\x1b\n]*(?:\x07|\x1b\\|(?=\n|$))/g
+
+function stripAnsi(text: string): string {
+    return String(text || '')
+        .replace(/\x1b\[(\d*)C/g, (_m, n) => ' '.repeat(Math.max(1, Number(n) || 1)))
+        .replace(/\x1b\[\d*D/g, '')
+        .replace(ANSI_RE, '')
+        .replace(OSC_RE, '')
+        .replace(/\x1b[P^_X][\s\S]*?(?:\x07|\x1b\\)/g, '')
+        .replace(/\x1b(?:[@-Z\\-_])/g, '')
+}
+
+function splitLines(text: string): string[] {
+    return stripAnsi(text)
+        .replace(//g, '')
+        .split(/\r?\n/)
+        .map(l => l.replace(/\s+$/, ''))
+}
+
+function pickInputText(input: any, scope: TranscriptPtySpec['scope']): string {
+    if (!input) return ''
+    if (scope === 'screen') return String(input.screenText || input.screen?.text || '')
+    if (scope === 'tail') return String(input.tail || input.recentBuffer || input.buffer || '')
+    return String(input.buffer || input.rawBuffer || input.screenText || '')
+}
+
+// ─── Identity stamping (mirrors _shared/parse_session.js) ─────
+
+function stableHash(value: string): string {
+    return crypto.createHash('sha1').update(String(value || '')).digest('hex').slice(0, 12)
+}
+
+export function normalizeMessageIdentity<T extends { role?: string; kind?: string; content?: string }>(
+    messages: T[],
+    status: string,
+): Array<T & {
+    providerUnitKey: string
+    bubbleId: string
+    sequence: number
+    _turnKey: string
+    bubbleState: 'streaming' | 'final'
+}> {
+    const list = Array.isArray(messages) ? messages : []
+    let turnIndex = -1
+    return list.map((message, index) => {
+        const role = message?.role || 'assistant'
+        const kind = message?.kind || 'standard'
+        const content = typeof message?.content === 'string' ? message.content : ''
+        if (role === 'user' || turnIndex < 0) turnIndex += 1
+        const seed = [role, kind, '', index, content].join('\n')
+        const providerUnitKey = `v2-pty:${role}:${kind}:${index}:${stableHash(seed)}`
+        const bubbleId = `bubble:${providerUnitKey}`
+        const turnKey = `turn:${turnIndex}`
+        const isStreamingTail = status === 'generating' && role === 'assistant' && index === list.length - 1
+        return {
+            ...message,
+            providerUnitKey,
+            bubbleId,
+            sequence: index,
+            _turnKey: turnKey,
+            bubbleState: isStreamingTail ? 'streaming' as const : 'final' as const,
+        }
+    })
+}
+
+// ─── Main builder ────────────────────────────────
+
+export function buildParseSessionFromTui(spec: ParseSessionTuiSpec): (input: any) => SynthesizedSession {
+    if (!spec.transcriptPty) {
+        throw new Error('buildParseSessionFromTui: spec.transcriptPty is required')
+    }
+
+    // Compile regexes once
+    const assistantRe = new RegExp(spec.transcriptPty.assistantPrefix.regex, spec.transcriptPty.assistantPrefix.flags || '')
+    const userRe = spec.transcriptPty.userPrefix
+        ? new RegExp(spec.transcriptPty.userPrefix.regex, spec.transcriptPty.userPrefix.flags || '')
+        : null
+    const toolRe = spec.transcriptPty.toolPrefix
+        ? new RegExp(spec.transcriptPty.toolPrefix.regex, spec.transcriptPty.toolPrefix.flags || '')
+        : null
+    const toolSkip = spec.transcriptPty.toolPrefix?.skip ?? false
+    const chromeRes = (spec.transcriptPty.chromePatterns || []).map(p =>
+        new RegExp(p.regex, p.flags || ''))
+    const requireIndentForContinuation = spec.transcriptPty.continuationLine?.indented ?? false
+    const stripLeadingChrome = spec.transcriptPty.stripLeadingChrome ?? true
+    const scope = spec.transcriptPty.scope ?? 'buffer'
+
+    // Compose detect + approval helpers if their inputs are present.
+    const detectStatus = (spec.spinner || spec.settledPrompt || spec.modal || spec.dispatchOrder)
+        ? buildDetectStatusFromTui({
+            spinner: spec.spinner,
+            settledPrompt: spec.settledPrompt,
+            modal: spec.modal,
+            dispatchOrder: spec.dispatchOrder,
+        })
+        : () => null
+    const parseApproval = spec.modal ? buildParseApprovalFromTui(spec.modal) : () => null
+
+    // Optional session-id extraction (tui/session-id-extraction@1). Compile once
+    // so each parseSession call is a single regex.exec on the chosen scope.
+    const sessionIdRe = spec.sessionIdExtraction
+        ? new RegExp(
+            spec.sessionIdExtraction.regex,
+            spec.sessionIdExtraction.flags ?? 'i',
+        )
+        : null
+    const sessionIdScope: TranscriptPtySpec['scope'] = spec.sessionIdExtraction?.scope ?? 'tail'
+
+    return function parseSession(input: any): SynthesizedSession {
+        // status + modal first
+        const status = detectStatus(input as any) ?? 'idle'
+        const modal = parseApproval(input as any)
+
+        const text = pickInputText(input, scope)
+        const lines = splitLines(text)
+
+        const messages: SynthesizedMessage[] = []
+        let seenFirstRoleLine = !stripLeadingChrome
+
+        for (const raw of lines) {
+            const line = raw
+            if (line.trim() === '') {
+                // Blank line: ends streaming continuation but doesn't add a message.
+                continue
+            }
+
+            // Chrome filter
+            let isChrome = false
+            for (const cre of chromeRes) {
+                if (cre.test(line)) { isChrome = true; break }
+            }
+            if (isChrome) continue
+
+            // Role detection
+            const userMatch = userRe ? line.match(userRe) : null
+            const toolMatch = toolRe ? line.match(toolRe) : null
+            const assistMatch = line.match(assistantRe)
+
+            if (userMatch) {
+                seenFirstRoleLine = true
+                const content = (userMatch[1] ?? userMatch[0]).trim()
+                if (content) messages.push({ role: 'user', kind: 'standard', content })
+                continue
+            }
+            if (toolMatch) {
+                seenFirstRoleLine = true
+                if (toolSkip) continue
+                const content = (toolMatch[1] ?? toolMatch[0]).trim()
+                if (content) messages.push({ role: 'assistant', kind: 'tool', content })
+                continue
+            }
+            if (assistMatch) {
+                seenFirstRoleLine = true
+                const content = (assistMatch[1] ?? assistMatch[0]).trim()
+                if (content) messages.push({ role: 'assistant', kind: 'standard', content })
+                continue
+            }
+
+            if (!seenFirstRoleLine) continue
+
+            // Continuation rule
+            if (requireIndentForContinuation && !/^\s/.test(line)) continue
+            const last = messages[messages.length - 1]
+            if (!last) continue
+            const cont = line.replace(/^\s+/, '')
+            if (cont) last.content = last.content ? `${last.content}\n${cont}` : cont
+        }
+
+        const result: SynthesizedSession = {
+            status,
+            messages,
+            activeModal: modal,
+            modal,
+            parsedStatus: status,
+        }
+
+        if (sessionIdRe) {
+            const haystack = stripAnsi(pickInputText(input, sessionIdScope))
+            const match = haystack.match(sessionIdRe)
+            const captured = match?.[1]?.trim()
+            if (captured) result.providerSessionId = captured
+        }
+
+        return result
+    }
+}

package/src/providers/sdk/v1/builders/cli/visible-region.ts

@@ -0,0 +1,143 @@
+/**
+ * applyVisibleRegion
+ *
+ * Scopes the raw terminal text to the "visible region" declared by a
+ * `tui/visible-region@1` spec before handing it to detect-status and
+ * parse-approval matchers.
+ *
+ * Scope semantics:
+ *   screen   → full text unchanged  (daemon already passes rendered screen)
+ *   buffer   → full text unchanged
+ *   tail     → last `tailChars` characters (default 4000)
+ *   between-anchors → text between most recent (or first) top/bottom anchor
+ *                     regex matches; falls back to full text if anchors not found
+ *
+ * selectAnchor:
+ *   "last"  → use the LAST occurrence of the top anchor — useful for providers
+ *             like Antigravity that redraw a separator + prompt on every turn;
+ *             this excludes all scrollback above the current session frame.
+ *   "first" → use the FIRST occurrence (default per schema).
+ */
+
+// ─── Spec shape (mirrors tui-visible-region-v1.json) ───────────────────
+
+interface AnchorPatternSpec {
+  pattern: string;
+  flags?: string;
+}
+
+interface AnchorsSpec {
+  top?: AnchorPatternSpec;
+  bottom?: AnchorPatternSpec;
+}
+
+export interface VisibleRegionSpec {
+  $schema?: 'adhdev:tui/visible-region@1';
+  scope: 'screen' | 'tail' | 'buffer' | 'between-anchors';
+  tailChars?: number;
+  anchors?: AnchorsSpec;
+  selectAnchor?: 'first' | 'last';
+  stripCues?: string[];
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+function compile(re: string, flags?: string): RegExp {
+  try {
+    return new RegExp(re, flags ?? '');
+  } catch (e) {
+    throw new Error(`Invalid visible-region anchor regex /${re}/${flags ?? ''}: ${(e as Error).message}`);
+  }
+}
+
+/**
+ * Find all non-overlapping matches of `re` in `text`.
+ * Returns them in order of occurrence (earliest first).
+ */
+function findAllMatches(re: RegExp, text: string): RegExpExecArray[] {
+  const results: RegExpExecArray[] = [];
+  // Operate on a non-global copy with sticky-safe iteration to avoid
+  // mutating the caller's RegExp state.
+  const iter = new RegExp(re.source, re.flags.replace('g', '') + 'g');
+  let m: RegExpExecArray | null;
+  while ((m = iter.exec(text)) !== null) {
+    results.push(m);
+    // Advance past zero-width matches to prevent infinite loop.
+    if (m[0].length === 0) iter.lastIndex += 1;
+  }
+  return results;
+}
+
+// ─── Public API ────────────────────────────────────────────────────────
+
+/**
+ * Apply the visible-region spec to `text` and return the scoped substring.
+ * Never throws on missing anchors — falls back to the full text instead.
+ */
+export function applyVisibleRegion(spec: VisibleRegionSpec, text: string): string {
+  if (!text) return text;
+
+  switch (spec.scope) {
+    case 'screen':
+    case 'buffer':
+      return text;
+
+    case 'tail': {
+      const limit = spec.tailChars ?? 4000;
+      if (text.length <= limit) return text;
+      return text.slice(-limit);
+    }
+
+    case 'between-anchors': {
+      const anchors = spec.anchors;
+      if (!anchors?.top && !anchors?.bottom) return text;
+
+      const selectLast = (spec.selectAnchor ?? 'first') === 'last';
+
+      // ── Top anchor ──
+      let topEnd = 0; // default: start of text
+      if (anchors.top) {
+        const topRe = compile(anchors.top.pattern, anchors.top.flags);
+        const topMatches = findAllMatches(topRe, text);
+        if (topMatches.length === 0) {
+          // Top anchor not found — fall back to full text.
+          return text;
+        }
+        const chosen = selectLast
+          ? topMatches[topMatches.length - 1]
+          : topMatches[0];
+        // Region starts just after the end of the top anchor match.
+        topEnd = chosen.index + chosen[0].length;
+      }
+
+      // ── Bottom anchor ──
+      let bottomStart = text.length; // default: end of text
+      if (anchors.bottom) {
+        const bottomRe = compile(anchors.bottom.pattern, anchors.bottom.flags);
+        // Only search the portion that comes AFTER the top anchor end so we
+        // always pick the immediately-following bottom anchor.
+        const searchFrom = topEnd;
+        const suffix = text.slice(searchFrom);
+        const bottomMatches = findAllMatches(bottomRe, suffix);
+        if (bottomMatches.length === 0) {
+          // Bottom anchor not found — fall back to full text.
+          return text;
+        }
+        const chosen = selectLast
+          ? bottomMatches[bottomMatches.length - 1]
+          : bottomMatches[0];
+        bottomStart = searchFrom + chosen.index;
+      }
+
+      if (topEnd >= bottomStart) {
+        // Degenerate / overlapping anchors — fall back to full text.
+        return text;
+      }
+
+      return text.slice(topEnd, bottomStart);
+    }
+
+    default:
+      return text;
+  }
+}

package/src/providers/sdk/v1/fixture-tooling/format.ts

@@ -0,0 +1,130 @@
+/**
+ * Provider fixture format — v1.
+ *
+ * A fixture is two files committed alongside a provider:
+ *
+ *   fixtures/<scenario>.pty             — raw PTY byte capture (binary or text)
+ *   fixtures/<scenario>.expected.json   — expected handler outputs at one
+ *                                          or more anchor frames
+ *
+ * Scenarios cover one concrete agent behaviour: cold start, prompt sent,
+ * generating with tool call, approval modal, idle after assistant complete,
+ * etc.
+ *
+ * The replay runner feeds the .pty bytes through the daemon's terminal
+ * emulator (TerminalTranscriptAccumulator) building up snapshots at each
+ * declared anchor, invokes the provider handlers, and compares results
+ * to the .expected.json shape.
+ *
+ * This file is the source of truth for the format. Schema mirror at
+ * sdk/v1/schemas/fixture-expected.schema.json.
+ */
+
+import type {
+  CliApprovalModal,
+  CliChatMessage,
+  CliStatus,
+} from '../types/cli/index.js';
+
+/**
+ * The top-level shape of <scenario>.expected.json.
+ *
+ * `anchors` is an ordered list; each anchor declares a point in the
+ * PTY stream (by byte offset or by sentinel string) and the expected
+ * handler outputs at that point.
+ */
+export interface FixtureExpected {
+  /** Schema version. Currently always 1. */
+  version: 1;
+  /** Free-form human description of the scenario. */
+  description?: string;
+  /** Provider type this fixture is for. */
+  providerType: string;
+  /** Path (relative to the .expected.json file) of the corresponding .pty file. */
+  ptyFile: string;
+  /** Optional cols/rows the recording was captured under. Defaults to 80x24. */
+  terminal?: { cols: number; rows: number };
+  /** Anchor points. Order matters; bytes are replayed up to each anchor. */
+  anchors: FixtureAnchor[];
+}
+
+export interface FixtureAnchor {
+  /** Human-readable identifier. Used in test reporter output. */
+  name: string;
+  /** Optional description. */
+  description?: string;
+  /**
+   * Where to stop replaying bytes. Exactly one of:
+   *   - `untilByte` — stop after the Nth raw byte
+   *   - `untilSentinel` — stop the first time `sentinel` appears in the
+   *     accumulated rendered screen text
+   */
+  untilByte?: number;
+  untilSentinel?: string;
+  /**
+   * Expected handler outputs. All keys optional; the replay runner only
+   * checks the keys you provide.
+   */
+  expect: {
+    detectStatus?: CliStatus | null;
+    parseApproval?: CliApprovalModal | null;
+    parseSession?: {
+      status?: CliStatus;
+      modal?: CliApprovalModal | null;
+      providerSessionId?: string;
+      /**
+       * Either an exact array (deep-equal) or a shape declaration that lets
+       * you match only the role/kind/content shape without pinning specific
+       * fields. Pin specific message-by-message when you care about content.
+       */
+      messages?: CliChatMessage[] | MessageShape[];
+    };
+  };
+  /**
+   * Optional notes about why this anchor exists. Encouraged for
+   * regression-style fixtures so future maintainers know what bug the
+   * fixture catches.
+   */
+  notes?: string;
+}
+
+/**
+ * A shape declaration that matches a message by role/kind plus optional
+ * content substring or regex. Use this instead of an exact CliChatMessage
+ * when you do not want to pin exact text.
+ */
+export interface MessageShape {
+  role: CliChatMessage['role'];
+  kind?: CliChatMessage['kind'];
+  /** Substring the content must contain. Plain string only. */
+  contentIncludes?: string;
+  /** Regex the content must match. */
+  contentMatches?: { source: string; flags?: string };
+}
+
+/**
+ * Result of replaying one anchor — what the handlers actually emitted.
+ * Used by the test runner to produce diff output.
+ */
+export interface AnchorReplayResult {
+  anchor: FixtureAnchor;
+  passes: boolean;
+  diffs: string[];
+  actual: {
+    detectStatus?: CliStatus | null;
+    parseApproval?: CliApprovalModal | null;
+    parseSession?: {
+      status: CliStatus;
+      modal: CliApprovalModal | null;
+      providerSessionId?: string;
+      messages: CliChatMessage[];
+    };
+  };
+}
+
+export interface FixtureReplayResult {
+  fixturePath: string;
+  expected: FixtureExpected;
+  perAnchor: AnchorReplayResult[];
+  overallPasses: boolean;
+}

package/src/providers/sdk/v1/fixture-tooling/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Fixture tooling — public surface.
+ *
+ * Imported by `adhdev provider test` and by daemon-core's CI regression
+ * suite. Format types and the replay runner are stable v1.
+ */
+
+export type {
+  FixtureExpected,
+  FixtureAnchor,
+  MessageShape,
+  AnchorReplayResult,
+  FixtureReplayResult,
+} from './format.js';
+
+export {
+  loadFixtureExpected,
+  replayFixture,
+  formatReplayReport,
+  type CliProviderHandlers,
+  type ReplayOptions,
+} from './replay.js';