@hegemonart/get-design-done 1.25.0 → 1.27.0

package/scripts/lib/session-runner/index.ts

@@ -86,6 +86,221 @@ const RATE_GUARD_PROVIDER = 'anthropic';
 /** Default retries (first attempt + 1 retry). */
 const DEFAULT_MAX_RETRIES = 2;
 
+// ── Plan 27-06 — Peer-CLI delegation primitives ─────────────────────────────
+//
+// Lazy registry loader: the registry is a .cjs module under scripts/lib/peer-cli
+// landed by Plan 27-05. Tests inject a stub via SessionRunnerOptions.registryOverride;
+// real callers fall through to the live module. Resolution is anchored to the
+// repo root via the same `_nodeRequire` we use for jittered-backoff/rate-guard
+// so the runner survives test sandboxes that chdir.
+//
+// We swallow load errors and return null → caller treats as "no peer available"
+// → falls back to local SDK. This keeps the session-runner functional even on
+// fresh checkouts where Plan 27-05 hasn't landed yet.
+
+interface PeerRegistry {
+  dispatch: (
+    role: string,
+    tier: string | null,
+    text: string,
+    opts: { cwd?: string; [k: string]: unknown },
+  ) => Promise<{ result: unknown; peer: string; protocol: 'acp' | 'asp' } | null>;
+}
+
+let _peerRegistryCache: PeerRegistry | null | undefined;
+
+/**
+ * Resolve the peer-CLI registry. Memoized; returns null if the module
+ * isn't installable (missing file, require throws, shape mismatch).
+ * Tests bypass this entirely by passing `registryOverride` on the
+ * SessionRunnerOptions.
+ */
+function loadPeerRegistry(): PeerRegistry | null {
+  if (_peerRegistryCache !== undefined) return _peerRegistryCache;
+  try {
+    const mod = _nodeRequire(
+      _resolve(_REPO_ROOT, 'scripts/lib/peer-cli/registry.cjs'),
+    );
+    if (mod && typeof mod === 'object' && typeof (mod as { dispatch?: unknown }).dispatch === 'function') {
+      _peerRegistryCache = mod as PeerRegistry;
+      return _peerRegistryCache;
+    }
+  } catch {
+    // registry.cjs missing or threw on require — treat as "no peers available"
+  }
+  _peerRegistryCache = null;
+  return _peerRegistryCache;
+}
+
+/**
+ * Visible-for-testing reset of the peer-registry cache. The session-runner
+ * caches the registry module after first resolve so production runs don't
+ * re-require it per call; tests that swap process state (chdir into a
+ * sandbox, write a different registry.cjs, etc.) can call this between
+ * tests to force reload. Production code never calls this.
+ */
+export function _resetPeerRegistryCache(): void {
+  _peerRegistryCache = undefined;
+}
+
+/**
+ * Parse a `delegate_to` value into (peer, role). Returns null when the
+ * value is missing, the literal "none" opt-out, or doesn't match the
+ * `<peer>-<role>` shape. The session-runner uses this to figure out
+ * which role to ask the registry for.
+ *
+ * Note: validate-frontmatter.ts already enforces the value shape at lint
+ * time — by the time a `delegate_to` reaches session-runner it's been
+ * validated against the capability matrix. We re-parse here defensively
+ * because the runner is consumed by tests that may pass arbitrary
+ * strings, and the cost of an extra split is trivial.
+ */
+function parseDelegateTo(value: string | undefined): { peer: string; role: string } | null {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  if (value === 'none') return null;
+  const dashIdx = value.indexOf('-');
+  if (dashIdx <= 0 || dashIdx >= value.length - 1) return null;
+  return {
+    peer: value.slice(0, dashIdx),
+    role: value.slice(dashIdx + 1),
+  };
+}
+
+/**
+ * Try to dispatch a session via peer-CLI before falling back to the
+ * Anthropic SDK. Returns either a fully-built SessionResult on peer
+ * success, or null when the caller should continue to the local path.
+ *
+ * Per CONTEXT D-07 (transparent fallback): every failure path inside
+ * this helper returns null — peer-absent, registry-load-failure,
+ * adapter-error, dispatch-throw, anything. The local SDK path then
+ * runs as if the delegation never happened. Failure is observable
+ * only as a placeholder log call (and, once Plan 27-08 wires real
+ * events, as a `peer_call_failed` chain entry).
+ */
+async function tryDelegate(args: {
+  opts: SessionRunnerOptions;
+  sanitizedPrompt: string;
+  transcriptPath: string;
+  sessionId: string;
+  sanitizer: { sanitized: string; applied: readonly string[]; removedSections: readonly string[] };
+}): Promise<SessionResult | null> {
+  const { opts, sanitizedPrompt, transcriptPath, sanitizer } = args;
+  const parsed = parseDelegateTo(opts.delegateTo);
+  if (parsed === null) return null; // not configured / explicit opt-out
+
+  const role = typeof opts.delegateRole === 'string' && opts.delegateRole.length > 0
+    ? opts.delegateRole
+    : parsed.role;
+  const tier = opts.delegateTier === undefined ? null : opts.delegateTier;
+
+  const dispatcher: PeerRegistry['dispatch'] | null = (() => {
+    if (typeof opts.registryOverride === 'function') return opts.registryOverride;
+    const reg = loadPeerRegistry();
+    return reg !== null ? reg.dispatch : null;
+  })();
+  if (dispatcher === null) {
+    // No registry available at all — fall through to local. Phase 22
+    // event emission (Plan 27-08) hooks here as `peer_call_failed`
+    // with reason="registry_missing". For now, a placeholder stderr
+    // breadcrumb so operators can grep for delegation drops without
+    // CI-failing on stdout pollution.
+    _logPeerCallFailed({ peer: parsed.peer, role, errorClass: 'registry_missing' });
+    return null;
+  }
+
+  let dispatchResult: { result: unknown; peer: string; protocol: 'acp' | 'asp' } | null = null;
+  try {
+    dispatchResult = await dispatcher(role, tier, sanitizedPrompt, { cwd: process.cwd() });
+  } catch (err) {
+    _logPeerCallFailed({
+      peer: parsed.peer,
+      role,
+      errorClass: 'dispatch_threw',
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return null; // transparent fallback
+  }
+
+  if (dispatchResult === null) {
+    // Registry returned null — peer absent, capability mismatch, or
+    // adapter-side error. Per D-07 we fall back silently.
+    _logPeerCallFailed({ peer: parsed.peer, role, errorClass: 'registry_returned_null' });
+    return null;
+  }
+
+  // Peer succeeded. Build a SessionResult that mirrors the local path's
+  // shape so downstream consumers (stage-handlers, transcript readers,
+  // tests) treat both paths uniformly. We do NOT write a transcript file
+  // for delegated calls in v1.27.0 — the peer broker (Plan 27-03) keeps
+  // its own logs and Plan 27-08 wires the events that observers need.
+  // The transcript_path field still points at the would-be path so any
+  // consumer that probes it sees a stable string (existsSync will be
+  // false, which is correct: the file isn't ours to write).
+  const finalText = _coerceFinalText(dispatchResult.result);
+  return {
+    status: 'completed',
+    transcript_path: transcriptPath,
+    turns: 1,
+    usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+    ...(finalText !== undefined ? { final_text: finalText } : {}),
+    tool_calls: [],
+    sanitizer: {
+      applied: [...sanitizer.applied],
+      removedSections: [...sanitizer.removedSections],
+    },
+  };
+}
+
+/** Best-effort extract a final text string from the adapter's free-form result. */
+function _coerceFinalText(result: unknown): string | undefined {
+  if (typeof result === 'string' && result.length > 0) return result;
+  if (result !== null && typeof result === 'object') {
+    const obj = result as Record<string, unknown>;
+    if (typeof obj['final_text'] === 'string' && obj['final_text'].length > 0) {
+      return obj['final_text'] as string;
+    }
+    if (typeof obj['text'] === 'string' && obj['text'].length > 0) {
+      return obj['text'] as string;
+    }
+    if (typeof obj['output'] === 'string' && obj['output'].length > 0) {
+      return obj['output'] as string;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Placeholder for Plan 27-08's `peer_call_failed` event. Until 27-08
+ * wires real `appendEvent('peer_call_failed', ...)`, we write a single
+ * stderr line so operators can grep for silent delegation drops. We
+ * deliberately don't go through `appendEvent` here because the Phase 22
+ * event-stream hasn't gained a `peer_call_failed` type yet (that's
+ * 27-08's job) and pushing an unknown event type today would create a
+ * migration mess for the reflector.
+ */
+function _logPeerCallFailed(args: {
+  peer: string;
+  role: string;
+  errorClass: string;
+  message?: string;
+}): void {
+  // One-line, machine-greppable. Quiet by default in test runs (NODE_ENV)
+  // so the test output stays clean. Operators set GDD_PEER_DEBUG=1 to see
+  // the breadcrumb in production logs.
+  if (process.env['GDD_PEER_DEBUG'] !== '1') return;
+  const payload = JSON.stringify({
+    type: 'peer_call_failed',
+    peer_id: args.peer,
+    role: args.role,
+    error_class: args.errorClass,
+    ...(args.message !== undefined ? { message: args.message } : {}),
+    ts: new Date().toISOString(),
+  });
+  // eslint-disable-next-line no-console
+  console.error(`[peer-cli] ${payload}`);
+}
+
 /** Baseline retry backoff parameters (matches jittered-backoff defaults for
  *  the SDK-retry case; 1s base → 30s cap). */
 const RETRY_BACKOFF = { baseMs: 1000, maxMs: 30_000 } as const;

package/scripts/lib/session-runner/types.ts

@@ -118,6 +118,66 @@ export interface SessionRunnerOptions {
     applied: readonly string[];
     removedSections: readonly string[];
   };
+
+  /**
+   * Phase 27 (Plan 27-06) — peer-CLI delegation.
+   *
+   * Optional. When set to `<peer>-<role>` (e.g. `gemini-research`), the
+   * session-runner attempts to dispatch the call to the named peer-CLI
+   * via `scripts/lib/peer-cli/registry.cjs#dispatch` BEFORE invoking the
+   * local Anthropic SDK. The peer's response, when successful, becomes
+   * the SessionResult — no SDK call is made.
+   *
+   * Fallback (CONTEXT D-07): if the registry returns `null` (peer
+   * absent / opt-out / adapter error / dispatch error) OR throws, the
+   * session-runner silently retries with the local Anthropic SDK. The
+   * caller never sees the peer failure — failure is a measurement
+   * signal, not a cycle-breaker.
+   *
+   * Special values:
+   *   - `none`      → explicit opt-out; never delegate. Same as omitting the field.
+   *   - undefined   → default behavior; never delegate.
+   *
+   * The session-runner never reads agent frontmatter on its own. Callers
+   * (pipeline-runner, explore, discuss, etc.) are responsible for
+   * resolving the agent's `delegate_to:` frontmatter and passing it
+   * through this option.
+   */
+  delegateTo?: string;
+
+  /**
+   * Phase 27 (Plan 27-06) — role hint for peer-CLI dispatch.
+   *
+   * Used only when `delegateTo` is set. Defaults to the role parsed out
+   * of `delegateTo` (e.g. `delegateTo: "gemini-research"` → role
+   * `"research"`). Provide explicitly when the caller wants to override
+   * the parsed value (rare).
+   */
+  delegateRole?: string;
+
+  /**
+   * Phase 27 (Plan 27-06) — tier hint for peer-CLI dispatch.
+   *
+   * Currently advisory; the registry's capability matrix doesn't gate
+   * on tier. Used by adapters for telemetry and by Plan 27-08 events.
+   * Defaults to null (let the adapter pick).
+   */
+  delegateTier?: string | null;
+
+  /**
+   * Phase 27 (Plan 27-06) — registry override for tests.
+   *
+   * Default loads `scripts/lib/peer-cli/registry.cjs` lazily on first
+   * delegation attempt. Tests inject a stub `dispatch()` to avoid
+   * spawning real peers. The override mirrors the registry's `dispatch`
+   * signature: `(role, tier, text, opts) => Promise<{result,peer,protocol} | null>`.
+   */
+  registryOverride?: (
+    role: string,
+    tier: string | null,
+    text: string,
+    opts: { cwd?: string; [k: string]: unknown },
+  ) => Promise<{ result: unknown; peer: string; protocol: 'acp' | 'asp' } | null>;
 }
 
 /**

package/scripts/lib/tier-resolver.cjs

@@ -0,0 +1,311 @@
+// scripts/lib/tier-resolver.cjs
+//
+// Plan 26-02 — tier→model resolver with fallback chain.
+//
+// `resolve(runtime, tier, opts?) → model-string | null`
+//
+// Translates the tier vocabulary frontmatter speaks (`opus`, `sonnet`,
+// `haiku`) into the concrete model name a specific runtime understands
+// (e.g. `gpt-5`, `gemini-2.5-pro`, `qwen3-max`). Source-of-truth for the
+// mapping is `reference/runtime-models.md` (plan 26-01); this module
+// reads the parsed form via 26-01's parser helper at
+// `scripts/lib/install/parse-runtime-models.cjs`.
+//
+// Parsed-models shape (from 26-01):
+//   {
+//     schema_version: 1,
+//     runtimes: [
+//       { id: 'claude',
+//         tier_to_model: { opus: { model: 'claude-opus-4-7' }, … },
+//         reasoning_class_to_model: { high: { model: '…' }, … },
+//         provenance: [...]
+//       },
+//       …
+//     ]
+//   }
+//
+// Fallback chain (D-04):
+//   1. runtime-specific entry has the tier → use directly (no event).
+//   2. runtime row missing OR tier missing on the row → fall back to the
+//      `claude` row (Anthropic-default convention 26-01 baked into every
+//      placeholder runtime), emit `tier_resolution_fallback`.
+//   3. neither available (e.g. a parsed map with no claude row, or a
+//      claude row missing the requested tier) → return null, emit
+//      `tier_resolution_failed`.
+//
+// Never throws. null is a valid output the caller (router, budget-
+// enforcer) must handle gracefully. Garbage input (undefined runtime,
+// bogus tier, malformed models) returns null + failure event.
+//
+// `.cjs` to match Phase 22 primitives and let .ts hooks require it
+// under --experimental-strip-types without ESM-interop friction.
+//
+// Pure module — no top-level side effects beyond reading the parsed
+// runtime-models document on first call. The parsed form is cached per-
+// process; callers that need a fresh read between cycles call `reset()`.
+//
+// Test-injection contract: callers may pass `opts.models` to bypass the
+// on-disk lookup entirely. Used by `tests/tier-resolver.test.cjs` to
+// exercise the fallback branches deterministically.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const VALID_TIERS = Object.freeze(['opus', 'sonnet', 'haiku']);
+
+/**
+ * Runtime-id whose row supplies the fallback for missing entries.
+ * 26-01's runtime-models.md uses Anthropic models as the closest-
+ * published-equivalent placeholder for every runtime that lacks a
+ * confirmed tier-map; that convention makes `claude` the natural
+ * D-04-branch-2 default. If 26-01 ever changes that convention,
+ * update this constant in lockstep.
+ */
+const DEFAULT_RUNTIME_ID = 'claude';
+
+const DEFAULT_EVENTS_PATH = path.join('.design', 'telemetry', 'events.jsonl');
+
+/**
+ * Cached parsed-models data. `null` until first lazy load (or after
+ * `reset()`).
+ */
+let _cachedModels = null;
+
+/**
+ * Lazy soft-import of the 26-01 parser. Returns null if the parser
+ * file is unreachable — the resolver then degrades to "always emit
+ * failed" for on-disk callers, while test callers using `opts.models`
+ * are unaffected.
+ */
+function loadParser() {
+  try {
+    const modPath = path.join(__dirname, 'install', 'parse-runtime-models.cjs');
+    if (!fs.existsSync(modPath)) return null;
+    return require(modPath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lazy load + cache the parsed runtime-models map. Returns null when
+ * the parser is unavailable or throws on the source markdown.
+ */
+function loadModels() {
+  if (_cachedModels !== null) return _cachedModels;
+  const parser = loadParser();
+  if (parser === null) return null;
+  try {
+    const fn = typeof parser.parseRuntimeModels === 'function'
+      ? parser.parseRuntimeModels
+      : (typeof parser === 'function' ? parser : null);
+    if (fn === null) return null;
+    const out = fn();
+    if (out && typeof out === 'object') {
+      _cachedModels = out;
+      return out;
+    }
+    return null;
+  } catch {
+    // Parser throws on schema validation failure — treat as
+    // "no usable models" so the resolver fails open with events
+    // rather than crashing the consumer.
+    return null;
+  }
+}
+
+/**
+ * Reset the parsed-models cache. Tests use this after writing fixture
+ * runtime-models.md to a temp cwd; production callers rarely need it.
+ */
+function reset() {
+  _cachedModels = null;
+}
+
+/**
+ * Append a single event line to the on-disk events.jsonl. Honors
+ * `GDD_EVENTS_PATH` for test isolation (matches the TS EventWriter's
+ * env-var contract). Never throws — diagnostic on stderr only.
+ *
+ * We don't `require` the .ts EventWriter from .cjs (would force every
+ * consumer to run under --experimental-strip-types); instead we write
+ * the same JSONL line shape directly. The envelope matches BaseEvent
+ * so downstream consumers don't care which producer wrote the line.
+ */
+function emitEvent(type, payload) {
+  const line = JSON.stringify({
+    type,
+    timestamp: new Date().toISOString(),
+    sessionId: process.env.GDD_SESSION_ID || 'tier-resolver',
+    payload,
+    _meta: {
+      pid: process.pid,
+      host: 'tier-resolver',
+      source: 'tier-resolver',
+    },
+  });
+  const envPath = process.env.GDD_EVENTS_PATH;
+  const target = envPath && envPath.length > 0
+    ? envPath
+    : path.join(process.cwd(), DEFAULT_EVENTS_PATH);
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.appendFileSync(target, line + '\n', { encoding: 'utf8' });
+  } catch (err) {
+    // Don't let event-emission failure cascade into resolver failure;
+    // the resolver's job is to return a model (or null), not to
+    // guarantee telemetry. The event-stream has its own resilience
+    // story (Phase 20-14 / Phase 22).
+    try {
+      process.stderr.write(
+        `[tier-resolver] event emit failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+}
+
+/**
+ * Find a runtime row by id. Accepts both the 26-01 array shape
+ * (`runtimes: [{id, …}, …]`) and a plain-object map shape
+ * (`runtimes: {id: {…}}`) used by some test fixtures. Returns the row
+ * or null when not found / malformed.
+ */
+function findRuntimeRow(models, id) {
+  if (!models || typeof models !== 'object') return null;
+  const r = models.runtimes;
+  if (Array.isArray(r)) {
+    for (const row of r) {
+      if (row && typeof row === 'object' && row.id === id) return row;
+    }
+    return null;
+  }
+  if (r && typeof r === 'object') {
+    const row = r[id];
+    return row && typeof row === 'object' ? row : null;
+  }
+  return null;
+}
+
+/**
+ * Read the model string for `tier` from a runtime row. The 26-01
+ * shape nests one level: `tier_to_model.opus = { model: '…' }`. A
+ * flat shape (`tier_to_model.opus = '…'`) is also accepted to keep
+ * test fixtures terse. Returns the model string or null when absent
+ * or malformed.
+ */
+function lookupTier(row, tier) {
+  if (!row || typeof row !== 'object') return null;
+  const map = row.tier_to_model;
+  if (!map || typeof map !== 'object') return null;
+  const v = map[tier];
+  if (typeof v === 'string' && v.length > 0) return v;
+  if (v && typeof v === 'object' && typeof v.model === 'string' && v.model.length > 0) {
+    return v.model;
+  }
+  return null;
+}
+
+/**
+ * Resolve a `(runtime, tier)` pair to a concrete model string. Returns
+ * null when neither the runtime-specific entry nor the runtime-default
+ * fallback supplies a value for the tier; emits a structured event in
+ * both the fallback and failure branches.
+ *
+ * @param {string | null | undefined} runtime
+ *   Runtime ID (e.g. 'claude', 'codex'). Garbage input returns null +
+ *   failure event.
+ * @param {string | null | undefined} tier
+ *   Tier name. Must be one of `opus`/`sonnet`/`haiku`. Anything else
+ *   returns null + failure event.
+ * @param {object} [opts]
+ * @param {object} [opts.models]
+ *   Pre-parsed models map. When supplied, bypasses the on-disk lookup
+ *   entirely (tests use this).
+ * @param {boolean} [opts.silent]
+ *   When true, suppresses event emission on the fallback / failure
+ *   paths. Used by callers that batch-resolve and prefer to roll up
+ *   their own diagnostics. Default false.
+ * @returns {string | null}
+ */
+function resolve(runtime, tier, opts) {
+  const models = (opts && opts.models) || loadModels();
+  const silent = !!(opts && opts.silent);
+
+  // Validate inputs FIRST so the failure event payload carries the
+  // garbage values verbatim — useful for telemetry diagnosis.
+  const runtimeOk = typeof runtime === 'string' && runtime.length > 0;
+  const tierOk = typeof tier === 'string' && VALID_TIERS.indexOf(tier) >= 0;
+
+  if (!runtimeOk || !tierOk || !models || typeof models !== 'object') {
+    if (!silent) {
+      emitEvent('tier_resolution_failed', {
+        runtime: runtimeOk ? runtime : (runtime === undefined ? null : runtime),
+        tier: tierOk ? tier : (tier === undefined ? null : tier),
+        reason: !runtimeOk
+          ? 'invalid_runtime'
+          : !tierOk
+            ? 'invalid_tier'
+            : 'models_unavailable',
+      });
+    }
+    return null;
+  }
+
+  const row = findRuntimeRow(models, runtime);
+
+  // Branch 1: runtime-specific hit.
+  const direct = lookupTier(row, tier);
+  if (direct !== null) return direct;
+
+  // Branch 2: fall back to the default-runtime row. 26-01 inlines
+  // Anthropic-default models on every placeholder runtime, so this
+  // branch primarily catches "runtime id not in the 14-runtime map"
+  // and "claude row itself missing the tier" — the latter being
+  // structurally near-impossible if 26-01's schema validation is on,
+  // but we still handle it.
+  const defaultRow = findRuntimeRow(models, DEFAULT_RUNTIME_ID);
+  // Don't double-fall-back if the runtime IS the default and we
+  // already missed the tier — that's a true failure.
+  const fallbackModel = runtime === DEFAULT_RUNTIME_ID
+    ? null
+    : lookupTier(defaultRow, tier);
+  if (fallbackModel !== null) {
+    if (!silent) {
+      emitEvent('tier_resolution_fallback', {
+        runtime,
+        tier,
+        model: fallbackModel,
+        reason: row === null ? 'runtime_not_in_map' : 'tier_missing_for_runtime',
+        fallback_runtime: DEFAULT_RUNTIME_ID,
+      });
+    }
+    return fallbackModel;
+  }
+
+  // Branch 3: nothing usable.
+  if (!silent) {
+    emitEvent('tier_resolution_failed', {
+      runtime,
+      tier,
+      reason: row === null
+        ? 'runtime_not_in_map'
+        : (runtime === DEFAULT_RUNTIME_ID
+          ? 'tier_missing_on_default_runtime'
+          : 'tier_missing_no_default'),
+    });
+  }
+  return null;
+}
+
+module.exports = {
+  resolve,
+  reset,
+  VALID_TIERS,
+  DEFAULT_RUNTIME_ID,
+  // internals surfaced for tests only — stable API = `resolve` + `reset`.
+  _internal: { lookupTier, findRuntimeRow, emitEvent, loadParser, loadModels },
+};