@adhdev/daemon-core 0.9.82-rc.15 → 0.9.82-rc.151

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';

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

@@ -0,0 +1,352 @@
+/**
+ * Fixture replay runner.
+ *
+ * Given a `.pty` byte capture and `.expected.json` declaration, replay the
+ * bytes through the daemon's TerminalTranscriptAccumulator, invoke the
+ * provider handlers at each anchor, and diff against expectations.
+ *
+ * Used by:
+ *   - `adhdev provider test` (daemon-cloud CLI)
+ *   - daemon-core CI suite for production-provider regression tests
+ *   - external authors as `adhdev provider test ./`
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import {
+  TerminalTranscriptAccumulator,
+  buildCliScreenSnapshot,
+  type CliScriptInput as InternalCliScriptInput,
+  type CliStatusInput as InternalCliStatusInput,
+  type CliApprovalInput as InternalCliApprovalInput,
+  type ParsedSession as InternalParsedSession,
+} from '../../../../cli-adapters/provider-cli-shared.js';
+import type {
+  CliApprovalModal,
+  CliChatMessage,
+  CliStatus,
+} from '../types/cli/index.js';
+import type {
+  FixtureExpected,
+  FixtureAnchor,
+  AnchorReplayResult,
+  FixtureReplayResult,
+  MessageShape,
+} from './format.js';
+
+// ─── Provider handler shape (matches the contract) ─────────────────────
+
+export interface CliProviderHandlers {
+  createState?: () => Record<string, unknown>;
+  parseSession: (state: unknown, input: InternalCliScriptInput) => InternalParsedSession;
+  detectStatus: (input: InternalCliStatusInput) => string | null;
+  parseApproval: (input: InternalCliApprovalInput) => { message: string; buttons: string[] } | null;
+  parseOutput?: (state: unknown, input: InternalCliScriptInput) => unknown;
+}
+
+export interface ReplayOptions {
+  /** Override accumulator dimensions. Defaults to the fixture's terminal block or 80x24. */
+  cols?: number;
+  rows?: number;
+  /** Provided manually (e.g. by tests). Defaults to wall-clock at replay start. */
+  spawnAt?: number;
+}
+
+// ─── Helpers — build the inputs the handlers expect ────────────────────
+
+function makeStatusInput(buffer: string, rawBuffer: string): InternalCliStatusInput {
+  const tail = buffer.slice(-1000);
+  const screenText = buffer;
+  return {
+    tail,
+    screenText,
+    rawBuffer,
+    isWaitingForResponse: false,
+    screen: buildCliScreenSnapshot(screenText),
+    tailScreen: buildCliScreenSnapshot(tail),
+  };
+}
+
+function makeApprovalInput(buffer: string, rawBuffer: string): InternalCliApprovalInput {
+  const tail = buffer.slice(-1000);
+  const screenText = buffer;
+  return {
+    buffer,
+    screenText,
+    rawBuffer,
+    tail,
+    screen: buildCliScreenSnapshot(screenText),
+    bufferScreen: buildCliScreenSnapshot(buffer),
+    tailScreen: buildCliScreenSnapshot(tail),
+  };
+}
+
+function makeScriptInput(
+  buffer: string,
+  rawBuffer: string,
+  spawnAt: number,
+): InternalCliScriptInput {
+  const recentBuffer = buffer.slice(-1000);
+  const screenText = buffer;
+  return {
+    buffer,
+    rawBuffer,
+    recentBuffer,
+    screenText,
+    screen: buildCliScreenSnapshot(screenText),
+    bufferScreen: buildCliScreenSnapshot(buffer),
+    recentScreen: buildCliScreenSnapshot(recentBuffer),
+    messages: [],
+    partialResponse: '',
+    isWaitingForResponse: false,
+    spawnAt,
+  };
+}
+
+// ─── Anchor stop condition ─────────────────────────────────────────────
+
+function nextStopIndex(anchor: FixtureAnchor, startIdx: number, raw: string): number {
+  if (typeof anchor.untilByte === 'number') {
+    return Math.min(anchor.untilByte, raw.length);
+  }
+  if (anchor.untilSentinel) {
+    const idx = raw.indexOf(anchor.untilSentinel, startIdx);
+    return idx < 0 ? raw.length : idx + anchor.untilSentinel.length;
+  }
+  // Default: replay everything.
+  return raw.length;
+}
+
+// ─── Shape matching for messages ───────────────────────────────────────
+
+function isShapeArray(input: unknown): input is MessageShape[] {
+  if (!Array.isArray(input) || input.length === 0) return false;
+  return input.every((m) => {
+    if (!m || typeof m !== 'object') return false;
+    const keys = Object.keys(m as object);
+    // Detect by absence of CliChatMessage-only required fields like `content` typed string.
+    return (
+      keys.some((k) => k === 'contentIncludes' || k === 'contentMatches') ||
+      (keys.includes('role') && !keys.includes('content'))
+    );
+  });
+}
+
+function messageMatchesShape(actual: CliChatMessage, shape: MessageShape): string | null {
+  if (actual.role !== shape.role) {
+    return `role mismatch: expected "${shape.role}", got "${actual.role}"`;
+  }
+  if (shape.kind && actual.kind && actual.kind !== shape.kind) {
+    return `kind mismatch: expected "${shape.kind}", got "${actual.kind}"`;
+  }
+  const content = typeof actual.content === 'string'
+    ? actual.content
+    : JSON.stringify(actual.content);
+  if (shape.contentIncludes && !content.includes(shape.contentIncludes)) {
+    return `content missing substring "${shape.contentIncludes.slice(0, 40)}"`;
+  }
+  if (shape.contentMatches) {
+    const re = new RegExp(shape.contentMatches.source, shape.contentMatches.flags ?? '');
+    if (!re.test(content)) {
+      return `content does not match /${shape.contentMatches.source}/${shape.contentMatches.flags ?? ''}`;
+    }
+  }
+  return null;
+}
+
+// ─── Diffing ───────────────────────────────────────────────────────────
+
+function diffStatus(
+  label: string,
+  expected: unknown,
+  actual: unknown,
+  diffs: string[],
+): void {
+  if (expected === undefined) return;
+  if (expected !== actual) {
+    diffs.push(`${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+function diffModal(
+  label: string,
+  expected: CliApprovalModal | null | undefined,
+  actual: CliApprovalModal | null,
+  diffs: string[],
+): void {
+  if (expected === undefined) return;
+  if (expected === null) {
+    if (actual !== null) {
+      diffs.push(`${label}: expected null modal, got ${JSON.stringify(actual)}`);
+    }
+    return;
+  }
+  if (actual === null) {
+    diffs.push(`${label}: expected modal, got null`);
+    return;
+  }
+  if (expected.message !== actual.message) {
+    diffs.push(`${label}.message: expected "${expected.message}", got "${actual.message}"`);
+  }
+  if (expected.buttons.length !== actual.buttons.length) {
+    diffs.push(`${label}.buttons.length: expected ${expected.buttons.length}, got ${actual.buttons.length}`);
+  } else {
+    for (let i = 0; i < expected.buttons.length; i += 1) {
+      if (expected.buttons[i] !== actual.buttons[i]) {
+        diffs.push(`${label}.buttons[${i}]: expected "${expected.buttons[i]}", got "${actual.buttons[i]}"`);
+      }
+    }
+  }
+}
+
+function diffMessages(
+  label: string,
+  expected: CliChatMessage[] | MessageShape[] | undefined,
+  actual: CliChatMessage[],
+  diffs: string[],
+): void {
+  if (expected === undefined) return;
+  if (expected.length !== actual.length) {
+    diffs.push(`${label}.length: expected ${expected.length}, got ${actual.length}`);
+    return;
+  }
+  if (isShapeArray(expected)) {
+    for (let i = 0; i < expected.length; i += 1) {
+      const reason = messageMatchesShape(actual[i], expected[i] as MessageShape);
+      if (reason) diffs.push(`${label}[${i}]: ${reason}`);
+    }
+  } else {
+    for (let i = 0; i < expected.length; i += 1) {
+      const e = expected[i] as CliChatMessage;
+      const a = actual[i];
+      if (e.role !== a.role) diffs.push(`${label}[${i}].role: ${e.role} vs ${a.role}`);
+      const ec = typeof e.content === 'string' ? e.content : JSON.stringify(e.content);
+      const ac = typeof a.content === 'string' ? a.content : JSON.stringify(a.content);
+      if (ec !== ac) diffs.push(`${label}[${i}].content: differs`);
+    }
+  }
+}
+
+// ─── Replay one anchor ─────────────────────────────────────────────────
+
+function replayAnchor(
+  raw: string,
+  startIdx: number,
+  acc: TerminalTranscriptAccumulator,
+  anchor: FixtureAnchor,
+  handlers: CliProviderHandlers,
+  spawnAt: number,
+): { result: AnchorReplayResult; nextIdx: number } {
+  const stop = nextStopIndex(anchor, startIdx, raw);
+  const chunk = raw.slice(startIdx, stop);
+  const buffer = acc.append(chunk);
+  const rawBufferSnapshot = raw.slice(0, stop);
+
+  const detect = handlers.detectStatus(makeStatusInput(buffer, rawBufferSnapshot));
+  const modal = handlers.parseApproval(makeApprovalInput(buffer, rawBufferSnapshot));
+  const state = handlers.createState ? handlers.createState() : undefined;
+  const session = handlers.parseSession(state, makeScriptInput(buffer, rawBufferSnapshot, spawnAt));
+
+  const diffs: string[] = [];
+  diffStatus('detectStatus', anchor.expect.detectStatus, detect as CliStatus | null, diffs);
+  diffModal('parseApproval', anchor.expect.parseApproval, modal, diffs);
+  if (anchor.expect.parseSession) {
+    diffStatus('parseSession.status', anchor.expect.parseSession.status, session.status as CliStatus, diffs);
+    diffModal('parseSession.modal', anchor.expect.parseSession.modal, session.modal as CliApprovalModal | null, diffs);
+    if (anchor.expect.parseSession.providerSessionId !== undefined) {
+      diffStatus(
+        'parseSession.providerSessionId',
+        anchor.expect.parseSession.providerSessionId,
+        session.providerSessionId,
+        diffs,
+      );
+    }
+    diffMessages(
+      'parseSession.messages',
+      anchor.expect.parseSession.messages,
+      session.messages as CliChatMessage[],
+      diffs,
+    );
+  }
+
+  return {
+    result: {
+      anchor,
+      passes: diffs.length === 0,
+      diffs,
+      actual: {
+        detectStatus: detect as CliStatus | null,
+        parseApproval: modal,
+        parseSession: {
+          status: session.status as CliStatus,
+          modal: session.modal as CliApprovalModal | null,
+          providerSessionId: session.providerSessionId,
+          messages: session.messages as CliChatMessage[],
+        },
+      },
+    },
+    nextIdx: stop,
+  };
+}
+
+// ─── Public API ────────────────────────────────────────────────────────
+
+export function loadFixtureExpected(expectedPath: string): FixtureExpected {
+  const raw = readFileSync(expectedPath, 'utf-8');
+  const parsed = JSON.parse(raw) as FixtureExpected;
+  if (parsed.version !== 1) {
+    throw new Error(`Fixture format version ${parsed.version} not supported (this runner is v1).`);
+  }
+  if (!parsed.providerType) throw new Error('Fixture missing providerType');
+  if (!parsed.ptyFile) throw new Error('Fixture missing ptyFile');
+  if (!Array.isArray(parsed.anchors) || parsed.anchors.length === 0) {
+    throw new Error('Fixture must declare at least one anchor');
+  }
+  return parsed;
+}
+
+export function replayFixture(
+  expectedPath: string,
+  handlers: CliProviderHandlers,
+  options: ReplayOptions = {},
+): FixtureReplayResult {
+  const expected = loadFixtureExpected(expectedPath);
+  const ptyFullPath = resolve(dirname(expectedPath), expected.ptyFile);
+  const rawBytes = readFileSync(ptyFullPath, 'utf-8');
+  const acc = new TerminalTranscriptAccumulator();
+  const spawnAt = options.spawnAt ?? Date.now();
+  let idx = 0;
+  const perAnchor: AnchorReplayResult[] = [];
+  for (const anchor of expected.anchors) {
+    const { result, nextIdx } = replayAnchor(rawBytes, idx, acc, anchor, handlers, spawnAt);
+    perAnchor.push(result);
+    idx = nextIdx;
+  }
+  return {
+    fixturePath: expectedPath,
+    expected,
+    perAnchor,
+    overallPasses: perAnchor.every((a) => a.passes),
+  };
+}
+
+/**
+ * Format a result as a human-readable report. Returns the multi-line string;
+ * caller decides whether to print or assert.
+ */
+export function formatReplayReport(result: FixtureReplayResult): string {
+  const lines: string[] = [];
+  lines.push(`Fixture: ${result.fixturePath}`);
+  lines.push(`Provider: ${result.expected.providerType}`);
+  lines.push(`Anchors: ${result.perAnchor.length}`);
+  for (const a of result.perAnchor) {
+    if (a.passes) {
+      lines.push(`  ✓ ${a.anchor.name}`);
+    } else {
+      lines.push(`  ✗ ${a.anchor.name}`);
+      for (const d of a.diffs) lines.push(`      ${d}`);
+    }
+  }
+  lines.push(result.overallPasses ? 'OVERALL: PASS' : 'OVERALL: FAIL');
+  return lines.join('\n');
+}