@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/slicer.ts

@@ -0,0 +1,166 @@
+/**
+ * scripts/slicer.ts
+ * Dynamic-cluster and window-based trace slicer — PR-017
+ * Type A — Pure Script (deterministic math + cap-of-5 clustering)
+ *
+ * Reads a Tier0Report + TraceMetadata list, emits a slice plan (array of slices,
+ * each being a list of traceIds for one analyzer to process).
+ *
+ * Usage: bun scripts/slicer.ts <tier0-report.json> <traces-metadata.json> [--cap N]
+ */
+
+import { readFileSync } from "fs";
+import type { TraceMetadata } from "./normalize/trace.ts";
+import type { Tier0Report } from "./tier0-scan.ts";
+
+export interface SlicePlan {
+  totalSlices: number;
+  slices: TraceSlice[];
+  /** Why this slicing strategy was chosen */
+  rationale: string;
+}
+
+export interface TraceSlice {
+  sliceId: string;
+  strategy: "dynamic-cluster" | "window-based";
+  /** Cluster label for dynamic-cluster slices */
+  clusterLabel?: string;
+  traceIds: string[];
+  /** Scope context passed to the analyzer */
+  scope: {
+    hasError: boolean;
+    hasFeedback: boolean;
+    isPrimarySignal: boolean;
+    estimatedComplexity: "low" | "medium" | "high";
+  };
+}
+
+const DEFAULT_CAP = 5;
+
+export function computeSlicePlan(
+  tier0: Tier0Report,
+  traces: TraceMetadata[],
+  cap = DEFAULT_CAP
+): SlicePlan {
+  if (traces.length === 0) {
+    return {
+      totalSlices: 0,
+      slices: [],
+      rationale: "No traces to analyze.",
+    };
+  }
+
+  if (tier0.recommendedSlicing === "dynamic-cluster") {
+    return dynamicClusterSlice(tier0, traces, cap);
+  }
+
+  return windowBasedSlice(traces, cap);
+}
+
+function dynamicClusterSlice(
+  tier0: Tier0Report,
+  traces: TraceMetadata[],
+  cap: number
+): SlicePlan {
+  const clusters: Map<string, TraceMetadata[]> = new Map();
+
+  // Cluster 1: errors
+  const errors = traces.filter((t) => t.hasError);
+  if (errors.length > 0) clusters.set("errors", errors);
+
+  // Cluster 2: low-score + feedback
+  const scoredNegative = traces.filter(
+    (t) =>
+      t.hasFeedback ||
+      (t.normalizedScore !== undefined && t.normalizedScore <= 0.4)
+  );
+  if (scoredNegative.length > 0) clusters.set("negative-feedback", scoredNegative);
+
+  // Cluster 3: high-latency (not already in errors)
+  const highLatency = traces.filter(
+    (t) => !t.hasError && t.latencyMs !== undefined && t.latencyMs > 10_000
+  );
+  if (highLatency.length > 0) clusters.set("high-latency", highLatency);
+
+  // Fill remaining slots with unclustered traces
+  const clusteredIds = new Set([...clusters.values()].flatMap((ts) => ts.map((t) => t.traceId)));
+  const unclustered = traces.filter((t) => !clusteredIds.has(t.traceId));
+  if (unclustered.length > 0 && clusters.size < cap) {
+    clusters.set("remaining", unclustered);
+  }
+
+  const slices: TraceSlice[] = [...clusters.entries()]
+    .slice(0, cap)
+    .map(([label, ts], i) => ({
+      sliceId: `slice-${i + 1}`,
+      strategy: "dynamic-cluster" as const,
+      clusterLabel: label,
+      traceIds: ts.map((t) => t.traceId),
+      scope: {
+        hasError: ts.some((t) => t.hasError),
+        hasFeedback: ts.some((t) => t.hasFeedback),
+        isPrimarySignal: label === "negative-feedback" || label === "errors",
+        estimatedComplexity:
+          ts.length > 20 ? "high" : ts.length > 5 ? "medium" : "low",
+      },
+    }));
+
+  return {
+    totalSlices: slices.length,
+    slices,
+    rationale: `Dynamic-cluster slicing: ${slices.length} cluster(s) from ${traces.length} traces. Clusters: ${slices.map((s) => s.clusterLabel).join(", ")}.`,
+  };
+}
+
+function windowBasedSlice(traces: TraceMetadata[], cap: number): SlicePlan {
+  const windowSize = Math.ceil(traces.length / cap);
+  const slices: TraceSlice[] = [];
+
+  for (let i = 0; i < cap && i * windowSize < traces.length; i++) {
+    const window = traces.slice(i * windowSize, (i + 1) * windowSize);
+    slices.push({
+      sliceId: `slice-${i + 1}`,
+      strategy: "window-based",
+      traceIds: window.map((t) => t.traceId),
+      scope: {
+        hasError: window.some((t) => t.hasError),
+        hasFeedback: window.some((t) => t.hasFeedback),
+        isPrimarySignal: false,
+        estimatedComplexity:
+          window.length > 20 ? "high" : window.length > 5 ? "medium" : "low",
+      },
+    });
+  }
+
+  return {
+    totalSlices: slices.length,
+    slices,
+    rationale: `Window-based slicing (no a-priori signal): ${slices.length} window(s) of ~${windowSize} traces each.`,
+  };
+}
+
+// CLI entrypoint
+if (import.meta.main) {
+  const tier0Path = process.argv[2];
+  const tracesPath = process.argv[3];
+  const capArg = process.argv.indexOf("--cap");
+  const cap = capArg >= 0 ? parseInt(process.argv[capArg + 1] ?? "5", 10) : DEFAULT_CAP;
+
+  if (!tier0Path || !tracesPath) {
+    process.stderr.write(
+      "Usage: bun scripts/slicer.ts <tier0-report.json> <traces-metadata.json> [--cap N]\n"
+    );
+    process.exit(1);
+  }
+
+  try {
+    const tier0: Tier0Report = JSON.parse(readFileSync(tier0Path, "utf8"));
+    const traces: TraceMetadata[] = JSON.parse(readFileSync(tracesPath, "utf8"));
+    const plan = computeSlicePlan(tier0, traces, cap);
+    process.stdout.write(JSON.stringify(plan, null, 2) + "\n");
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Error: ${err}\n`);
+    process.exit(1);
+  }
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/source/adapters/claude-code.ts

@@ -0,0 +1,17 @@
+import { SourceAdapterId } from "../types.ts";
+import type { SourceAdapter } from "../types.ts";
+
+// Claude Code source adapter. The bespoke Tier-0 scanner (v0.3 apiErrors /
+// compactionEvents / teammate-ratio patterns) lives in tier0/claude-code.ts and
+// is loaded LAZILY — mirroring the pre-registry dynamic import. runClaudeCodeTier0
+// takes no config, so the `config` param of the Tier0Scan signature is omitted here
+// (TypeScript permits an implementation with fewer params than its type).
+export const claudeCodeSourceAdapter: SourceAdapter = {
+  id: SourceAdapterId.ClaudeCode,
+  label: "Claude Code",
+  live: true,
+  async tier0Scan(traces) {
+    const mod = await import("../../tier0/claude-code.ts");
+    return mod.runClaudeCodeTier0(traces);
+  },
+};

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/source/adapters/codex.ts

@@ -0,0 +1,11 @@
+import { SourceAdapterId } from "../types.ts";
+import type { SourceAdapter } from "../types.ts";
+
+// Codex source adapter — Codex session transcripts. No bespoke Tier-0 scanner;
+// uses the generic scan (omitting `tier0Scan`), unchanged from the pre-registry
+// fallback path (Codex never had a per-platform Tier-0 branch).
+export const codexSourceAdapter: SourceAdapter = {
+  id: SourceAdapterId.Codex,
+  label: "Codex",
+  live: true,
+};

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/source/adapters/langfuse.ts

@@ -0,0 +1,17 @@
+import { SourceAdapterId } from "../types.ts";
+import type { SourceAdapter } from "../types.ts";
+
+// Langfuse source adapter. The bespoke Tier-0 scanner (LF-001 low-score
+// concentration + config-honoring IQR latency fence) lives in tier0/langfuse.ts;
+// it is loaded LAZILY here — exactly as the pre-registry `dispatchPlatformTier0`
+// did — so (a) registering the adapter set is cheap and (b) there is no eval-time
+// import cycle (tier0/langfuse.ts imports iqrUpperFence from tier0-scan.ts).
+export const langfuseSourceAdapter: SourceAdapter = {
+  id: SourceAdapterId.Langfuse,
+  label: "Langfuse",
+  live: true,
+  async tier0Scan(traces, config) {
+    const mod = await import("../../tier0/langfuse.ts");
+    return mod.runLangfuseTier0(traces, config);
+  },
+};

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/source/adapters/local-jsonl.ts

@@ -0,0 +1,12 @@
+import { SourceAdapterId } from "../types.ts";
+import type { SourceAdapter } from "../types.ts";
+
+// Local-JSONL source adapter — the UniTF handover format read directly off disk
+// (no per-platform fetch/normalize; see normalize/read-unitf.ts). No bespoke
+// Tier-0 scanner — uses the generic scan (omitting `tier0Scan`), unchanged from
+// the pre-registry fallback path.
+export const localJsonlSourceAdapter: SourceAdapter = {
+  id: SourceAdapterId.LocalJsonl,
+  label: "Local JSONL (UniTF)",
+  live: true,
+};

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/source/adapters/otel.ts

@@ -0,0 +1,12 @@
+import { SourceAdapterId } from "../types.ts";
+import type { SourceAdapter } from "../types.ts";
+
+// OpenTelemetry source adapter (also the transport for OpenObserve, ingested via
+// the UniTF/local-jsonl handover). No bespoke Tier-0 scanner — OTel batches use
+// the generic scan (omitting `tier0Scan` selects the generic path), preserving
+// the exact pre-registry behavior where only langfuse/claude-code had a branch.
+export const otelSourceAdapter: SourceAdapter = {
+  id: SourceAdapterId.Otel,
+  label: "OpenTelemetry",
+  live: true,
+};

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/source/index.ts

@@ -0,0 +1,54 @@
+import { registerSourceAdapter, clearSourceAdapters } from "./registry.ts";
+import { langfuseSourceAdapter } from "./adapters/langfuse.ts";
+import { otelSourceAdapter } from "./adapters/otel.ts";
+import { localJsonlSourceAdapter } from "./adapters/local-jsonl.ts";
+import { claudeCodeSourceAdapter } from "./adapters/claude-code.ts";
+import { codexSourceAdapter } from "./adapters/codex.ts";
+
+// ---------------------------------------------------------------------------
+// Source-adapter registration entry point (mirrors apply/index.ts
+// registerBuiltinAdapters). The five shipped sources register declaratively
+// here; adding a source = drop an adapter file + one line below (+ the
+// SourcePlatform literal in normalize/trace.ts & config/schema.ts). No consumer
+// switch to edit — see references/source-adapter-contract.md.
+// ---------------------------------------------------------------------------
+
+/** Register the shipped source adapters (idempotent — clears then registers). */
+export function registerBuiltinSourceAdapters(): void {
+  clearSourceAdapters();
+  registerSourceAdapter(langfuseSourceAdapter);
+  registerSourceAdapter(otelSourceAdapter);
+  registerSourceAdapter(localJsonlSourceAdapter);
+  registerSourceAdapter(claudeCodeSourceAdapter);
+  registerSourceAdapter(codexSourceAdapter);
+}
+
+let _builtinsRegistered = false;
+
+/**
+ * Ensure the shipped adapters are registered EXACTLY once. Library callers (e.g.
+ * tier0-scan's platform-aware dispatch) invoke this instead of
+ * registerBuiltinSourceAdapters so a caller-registered custom/fake adapter is not
+ * clobbered on every scan. Tests reset via clearSourceAdapters() +
+ * resetBuiltinSourceAdaptersForTest().
+ */
+export function ensureBuiltinSourceAdapters(): void {
+  if (_builtinsRegistered) return;
+  registerBuiltinSourceAdapters();
+  _builtinsRegistered = true;
+}
+
+/** Test seam — reset the ensure-once latch so a suite can re-exercise registration. */
+export function resetBuiltinSourceAdaptersForTest(): void {
+  _builtinsRegistered = false;
+}
+
+export type { SourceAdapter, SourceAdapterIdValue } from "./types.ts";
+export { SourceAdapterId } from "./types.ts";
+export {
+  registerSourceAdapter,
+  getSourceAdapter,
+  tryGetSourceAdapter,
+  listSourceAdapters,
+  clearSourceAdapters,
+} from "./registry.ts";

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/source/registry.ts

@@ -0,0 +1,45 @@
+import type { SourceAdapter, SourceAdapterIdValue } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Source-adapter registry (mirrors the apply-layer target-adapter registry in
+// @mutagent/tools src/apply/registry.ts). Adapters self-register via ./index.ts
+// (imported once). Kept tiny so the registration graph is obvious.
+// ---------------------------------------------------------------------------
+
+const REGISTRY = new Map<SourceAdapterIdValue, SourceAdapter>();
+
+export function registerSourceAdapter(adapter: SourceAdapter): void {
+  REGISTRY.set(adapter.id, adapter);
+}
+
+/**
+ * Resolve an adapter, THROWING a clear error (with the registered set) when the
+ * source is unknown. Use this for the strict binding path where an unregistered
+ * `source.platform` is a hard error.
+ */
+export function getSourceAdapter(id: SourceAdapterIdValue): SourceAdapter {
+  const a = REGISTRY.get(id);
+  if (!a) {
+    const known = [...REGISTRY.keys()].sort().join(", ") || "(none registered)";
+    throw new Error(`no source adapter registered for id '${id}'. Registered: ${known}.`);
+  }
+  return a;
+}
+
+/**
+ * Resolve an adapter, or `undefined` when unknown. Use this for the tolerant
+ * dispatch path (tier0-scan) that must FALL BACK to the generic scan for an
+ * unregistered / mixed-platform batch rather than throw.
+ */
+export function tryGetSourceAdapter(id: SourceAdapterIdValue): SourceAdapter | undefined {
+  return REGISTRY.get(id);
+}
+
+export function listSourceAdapters(): SourceAdapter[] {
+  return [...REGISTRY.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** Test/reset seam. */
+export function clearSourceAdapters(): void {
+  REGISTRY.clear();
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/source/types.ts

@@ -0,0 +1,86 @@
+// ---------------------------------------------------------------------------
+// mutagent-diagnostics source layer — the SHARED read-side transport (the
+// symmetric twin of the write-side `TargetAdapter` in @mutagent/tools
+// src/apply). One `SourceAdapter` interface, N adapters; the `source.platform`
+// config field binds to an adapter id (see ./registry.ts getSourceAdapter).
+//
+// BEFORE this layer the per-platform read path was ad-hoc: tier0-scan.ts held a
+// hard-coded `if (platform === "langfuse") … if (platform === "claude-code") …`
+// dispatch with inline dynamic imports. A new trace source could not register
+// declaratively — you edited the switch. This layer replaces that switch with a
+// registry, mirroring the apply layer exactly:
+//
+//   apply (write side)                source (read side)
+//   ──────────────────                ──────────────────
+//   AdapterId (const)            ⇄    SourceAdapterId (const)
+//   TargetAdapter (interface)    ⇄    SourceAdapter (interface)
+//   registerTargetAdapter        ⇄    registerSourceAdapter
+//   getTargetAdapter (throws)    ⇄    getSourceAdapter (throws)
+//   listTargetAdapters           ⇄    listSourceAdapters
+//   clearTargetAdapters          ⇄    clearSourceAdapters
+//   registerBuiltinAdapters      ⇄    registerBuiltinSourceAdapters
+//   apply.kind → adapterIdForKind ⇄   source.platform → id (1:1, identity)
+//
+// Asymmetry (intentional): the apply layer needs a binding.ts because `apply.kind`
+// (4 config values) maps NON-1:1 onto adapter ids (code-pr AND markdown → worktree-pr;
+// cloud-deploy → rest OR vendor). On the read side `source.platform` → adapter id is
+// 1:1 (the id IS the platform literal), so no binding module is warranted — the
+// registry key IS the platform. See references/source-adapter-contract.md.
+// ---------------------------------------------------------------------------
+
+import type { SourcePlatform, TraceMetadata } from "../normalize/trace.ts";
+import type { Tier0Report, Tier0ScanConfig } from "../tier0-scan.ts";
+
+/**
+ * The source transports — `source.platform` binds directly to one of these ids
+ * (1:1). Mirrors `AdapterId` in the apply layer. Declared as a const object (not
+ * a bare union) so callers can reference `SourceAdapterId.Langfuse` symbolically
+ * and so `listSourceAdapters()` / tests can enumerate the shipped set.
+ */
+export const SourceAdapterId = {
+  /** Langfuse traces — explicit score + feedback + latency signals as first-class fields. */
+  Langfuse: "langfuse",
+  /** OpenTelemetry spans (incl. OpenObserve, ingested via the UniTF/local-jsonl handover). */
+  Otel: "otel",
+  /** Local JSONL export (the UniTF handover format) — read directly, no per-platform fetch. */
+  LocalJsonl: "local-jsonl",
+  /** Claude Code session transcripts — v0.3 apiErrors / compactionEvents extensions. */
+  ClaudeCode: "claude-code",
+  /** Codex session transcripts. */
+  Codex: "codex",
+} as const;
+
+/** An adapter id === a `SourcePlatform` literal (the read-side ids are 1:1 with platforms). */
+export type SourceAdapterIdValue = SourcePlatform;
+
+/**
+ * Optional per-platform Tier-0 enrichment capability. When an adapter provides
+ * this, `runTier0ScanPlatformAware` dispatches a homogeneous batch here for signal
+ * extraction tuned to the source's signal density (e.g. Langfuse LF-001 low-score
+ * concentration, Claude-Code compaction clusters). When ABSENT, the generic
+ * `runTier0Scan` runs — identical to the pre-registry fallback for otel /
+ * local-jsonl / codex. Implementations should lazily `import()` their heavy scan
+ * module (as the pre-registry dispatch did) so registration stays cheap + cycle-free.
+ */
+// eslint-disable-next-line no-unused-vars -- fn-type-alias param names (pkg convention, see setup/ensure-cli.ts)
+export type Tier0ScanFn = (traces: TraceMetadata[], config: Tier0ScanConfig) => Tier0Report | Promise<Tier0Report>;
+
+/**
+ * The contract every source adapter implements — the read-side twin of
+ * `TargetAdapter`. Adapters self-register through the registry (./index.ts).
+ */
+export interface SourceAdapter {
+  /** The source platform this adapter serves — binds to config `source.platform`. */
+  id: SourceAdapterIdValue;
+  /** Human-readable label (onboarding pickers / diagnostics). */
+  label: string;
+  /** false for a SEAM stub (a source declared but not yet live); true when shipped. */
+  live: boolean;
+  /**
+   * Optional per-platform Tier-0 scan. Present for platforms with a bespoke scanner
+   * (langfuse, claude-code); absent for platforms that use the generic scan (otel,
+   * local-jsonl, codex). Absence is a first-class, behavior-defining value — it
+   * selects the generic path, NOT an error.
+   */
+  tier0Scan?: Tier0ScanFn;
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/stale-detector.ts

@@ -0,0 +1,74 @@
+/**
+ * scripts/stale-detector.ts
+ * Hash comparison for target freshness check — PR-011
+ * Type A — Pure Script (pure hash compare, no I/O side effects)
+ *
+ * Before any apply, the orchestrator calls this script to check if the target
+ * has changed since the diagnostic was run.
+ *
+ * Usage: bun scripts/stale-detector.ts <diagnosed-at-hash> <current-hash>
+ * Exit 0 = fresh (hashes match), Exit 1 = stale (hashes differ), Exit 2 = error
+ */
+
+import { createHash } from "crypto";
+import { readFileSync, existsSync } from "fs";
+
+export interface StalenessResult {
+  stale: boolean;
+  diagnosedAtHash: string;
+  currentHash: string;
+  reason?: string;
+}
+
+/**
+ * Compare two content hashes.
+ * Returns stale=true if they differ.
+ */
+export function checkStaleness(
+  diagnosedAtHash: string,
+  currentHash: string
+): StalenessResult {
+  const stale = diagnosedAtHash !== currentHash;
+  return {
+    stale,
+    diagnosedAtHash,
+    currentHash,
+    reason: stale
+      ? "Target has changed since diagnostic was run. Re-diagnose recommended."
+      : undefined,
+  };
+}
+
+/**
+ * Compute SHA-256 hash of a file's content.
+ * Returns null if file doesn't exist.
+ */
+export function hashFile(filePath: string): string | null {
+  if (!existsSync(filePath)) return null;
+  const content = readFileSync(filePath);
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Compute SHA-256 hash of a string value.
+ */
+export function hashString(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+// CLI entrypoint
+if (import.meta.main) {
+  const diagnosedAtHash = process.argv[2];
+  const currentHash = process.argv[3];
+
+  if (!diagnosedAtHash || !currentHash) {
+    process.stderr.write(
+      "Usage: bun scripts/stale-detector.ts <diagnosed-at-hash> <current-hash>\n"
+    );
+    process.exit(2);
+  }
+
+  const result = checkStaleness(diagnosedAtHash, currentHash);
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exit(result.stale ? 1 : 0);
+}