agentic-orchestrator 0.1.0

package/apps/control-plane/src/core/patch.ts

@@ -0,0 +1,152 @@
+export type DiffChangeType = 'add' | 'modify' | 'delete';
+
+export interface DiffHunk {
+  start_line: number;
+  end_line: number;
+  change_type: DiffChangeType;
+}
+
+export interface ParsedDiffFile {
+  oldPath: string;
+  newPath: string;
+  changeType: DiffChangeType;
+  hunks: DiffHunk[];
+}
+
+export class DiffParseError extends Error {
+  readonly code: 'invalid_unified_diff';
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'DiffParseError';
+    this.code = 'invalid_unified_diff';
+  }
+}
+
+function stripGitPath(value: string): string {
+  if (value.startsWith('a/')) {
+    return value.slice(2);
+  }
+  if (value.startsWith('b/')) {
+    return value.slice(2);
+  }
+  return value;
+}
+
+export class DiffParser {
+  parse(diffText: string): ParsedDiffFile[] {
+    if (typeof diffText !== 'string') {
+      throw new DiffParseError('Unified diff input must be a string');
+    }
+
+    const lines = diffText.replace(/\r\n/g, '\n').split('\n');
+    const files: ParsedDiffFile[] = [];
+    let current: ParsedDiffFile | null = null;
+
+    const pushCurrent = (): void => {
+      if (current) {
+        files.push(current);
+        current = null;
+      }
+    };
+
+    for (const line of lines) {
+      if (line.startsWith('diff --git ')) {
+        pushCurrent();
+        const parts = line.split(' ');
+        const oldPath = stripGitPath(parts[2] ?? 'a/unknown');
+        const newPath = stripGitPath(parts[3] ?? 'b/unknown');
+        current = {
+          oldPath,
+          newPath,
+          changeType: 'modify',
+          hunks: []
+        };
+        continue;
+      }
+
+      if (!current) {
+        continue;
+      }
+
+      if (line.startsWith('new file mode ')) {
+        current.changeType = 'add';
+        continue;
+      }
+
+      if (line.startsWith('deleted file mode ')) {
+        current.changeType = 'delete';
+        continue;
+      }
+
+      if (line.startsWith('rename from ')) {
+        current.oldPath = line.replace('rename from ', '').trim();
+        current.changeType = 'modify';
+        continue;
+      }
+
+      if (line.startsWith('rename to ')) {
+        current.newPath = line.replace('rename to ', '').trim();
+        current.changeType = 'modify';
+        continue;
+      }
+
+      if (line.startsWith('--- ')) {
+        const raw = line.replace('--- ', '').trim();
+        if (raw !== '/dev/null') {
+          current.oldPath = stripGitPath(raw);
+        }
+        continue;
+      }
+
+      if (line.startsWith('+++ ')) {
+        const raw = line.replace('+++ ', '').trim();
+        if (raw !== '/dev/null') {
+          current.newPath = stripGitPath(raw);
+        }
+        continue;
+      }
+
+      const hunkMatch = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+      if (hunkMatch) {
+        const oldStart = Number(hunkMatch[1]);
+        const oldCount = Number(hunkMatch[2] ?? 1);
+        const newStart = Number(hunkMatch[3]);
+        const newCount = Number(hunkMatch[4] ?? 1);
+        const changeType: DiffChangeType =
+          current.changeType === 'delete' ? 'delete' : current.changeType === 'add' ? 'add' : 'modify';
+        current.hunks.push({
+          start_line: changeType === 'delete' ? oldStart : newStart,
+          end_line: changeType === 'delete' ? oldStart + oldCount - 1 : newStart + newCount - 1,
+          change_type: changeType
+        });
+      }
+    }
+
+    pushCurrent();
+    return files;
+  }
+
+  touchedPaths(parsedFiles: ParsedDiffFile[]): string[] {
+    const touched = new Set<string>();
+    for (const file of parsedFiles) {
+      if (file.oldPath && file.oldPath !== '/dev/null') {
+        touched.add(file.oldPath);
+      }
+      if (file.newPath && file.newPath !== '/dev/null') {
+        touched.add(file.newPath);
+      }
+    }
+    return [...touched];
+  }
+}
+
+export const diffParser = new DiffParser();
+
+export function parseUnifiedDiff(diffText: string): ParsedDiffFile[] {
+  return diffParser.parse(diffText);
+}
+
+export function touchedPathsFromDiff(parsedFiles: ParsedDiffFile[]): string[] {
+  return diffParser.touchedPaths(parsedFiles);
+}

package/apps/control-plane/src/core/path-layout.ts

@@ -0,0 +1,113 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ensureDir, pathExists } from './fs.js';
+
+export class AopPathLayout {
+  readonly repoRoot: string;
+
+  constructor(repoRoot: string) {
+    this.repoRoot = repoRoot;
+  }
+
+  get orchestratorRoot(): string {
+    return path.join(this.repoRoot, 'agentic', 'orchestrator');
+  }
+
+  get runtimeRoot(): string {
+    return path.join(this.repoRoot, '.aop');
+  }
+
+  get featuresRoot(): string {
+    return path.join(this.runtimeRoot, 'features');
+  }
+
+  get runtimeDataRoot(): string {
+    return path.join(this.runtimeRoot, 'runtime');
+  }
+
+  get operationLedgerRoot(): string {
+    return path.join(this.runtimeDataRoot, 'operation-ledger');
+  }
+
+  get legacyFeaturesRoot(): string {
+    return path.join(this.repoRoot, 'agentic', 'features');
+  }
+
+  get legacyRuntimeRoot(): string {
+    return path.join(this.repoRoot, 'agentic', 'runtime');
+  }
+
+  get indexPath(): string {
+    return path.join(this.featuresRoot, 'index.json');
+  }
+
+  get indexLockPath(): string {
+    return path.join(this.featuresRoot, '.index.lock');
+  }
+
+  featureRoot(featureId: string): string {
+    return path.join(this.featuresRoot, featureId);
+  }
+
+  featureLockPath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), '.feature.lock');
+  }
+
+  statePath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'state.md');
+  }
+
+  planPath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'plan.json');
+  }
+
+  qaIndexPath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'qa_test_index.json');
+  }
+
+  decisionsPath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'decisions.md');
+  }
+
+  logsPath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'logs');
+  }
+
+  evidencePath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'evidence');
+  }
+
+  specPath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'spec.md');
+  }
+}
+
+async function copyLegacyRuntimeTree(sourcePath: string, targetPath: string): Promise<void> {
+  await fs.cp(sourcePath, targetPath, {
+    recursive: true,
+    force: false,
+    errorOnExist: false
+  });
+}
+
+export async function ensureAopRuntimeLayout(layout: AopPathLayout): Promise<void> {
+  const runtimeRootExists = await pathExists(layout.runtimeRoot);
+  const legacyFeaturesExists = await pathExists(layout.legacyFeaturesRoot);
+  const legacyRuntimeExists = await pathExists(layout.legacyRuntimeRoot);
+
+  // Deterministic compatibility window:
+  // if .aop exists it is authoritative; only migrate when .aop is absent.
+  if (!runtimeRootExists && (legacyFeaturesExists || legacyRuntimeExists)) {
+    await ensureDir(layout.runtimeRoot);
+    if (legacyFeaturesExists) {
+      await copyLegacyRuntimeTree(layout.legacyFeaturesRoot, layout.featuresRoot);
+    }
+    if (legacyRuntimeExists) {
+      await copyLegacyRuntimeTree(layout.legacyRuntimeRoot, layout.runtimeDataRoot);
+    }
+  }
+
+  await ensureDir(layout.featuresRoot);
+  await ensureDir(layout.runtimeDataRoot);
+  await ensureDir(layout.operationLedgerRoot);
+}

package/apps/control-plane/src/core/path-rules.ts

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Minimatch } from 'minimatch';
+
+function normalizeSeparators(value: string): string {
+  return value.replaceAll('\\\\', '/');
+}
+
+export class RepoPathNormalizer {
+  async normalize(repoRoot: string, candidatePath: string, allowSymlinkTraversal = false): Promise<string> {
+    const absoluteInput = path.isAbsolute(candidatePath) ? candidatePath : path.resolve(repoRoot, candidatePath);
+
+    const realPath = await fs.realpath(absoluteInput).catch(() => absoluteInput);
+    if (!allowSymlinkTraversal && !realPath.startsWith(repoRoot)) {
+      throw new Error('path_out_of_bounds');
+    }
+
+    const relative = normalizeSeparators(path.relative(repoRoot, absoluteInput));
+    const normalized = path.posix.normalize(relative);
+
+    if (
+      normalized === '' ||
+      normalized === '.' ||
+      normalized.startsWith('../') ||
+      normalized === '..' ||
+      normalized.startsWith('/')
+    ) {
+      throw new Error('path_out_of_bounds');
+    }
+
+    return normalized;
+  }
+}
+
+export class AreaMatchingPolicy {
+  areaMatches(repoRelativePath: string, area: string, matchingMode = 'repo_prefix'): boolean {
+    if (matchingMode === 'glob') {
+      return new Minimatch(area, { dot: true, nocase: false }).match(repoRelativePath);
+    }
+
+    const normalizedArea = area.endsWith('/') ? area : `${area}/`;
+    return repoRelativePath === area || repoRelativePath.startsWith(normalizedArea);
+  }
+
+  anyAreaMatch(repoRelativePath: string, areas: string[], matchingMode = 'repo_prefix'): boolean {
+    return areas.some((area) => this.areaMatches(repoRelativePath, area, matchingMode));
+  }
+}
+
+export const repoPathNormalizer = new RepoPathNormalizer();
+export const areaMatchingPolicy = new AreaMatchingPolicy();
+
+export async function normalizeRepoPath(
+  repoRoot: string,
+  candidatePath: string,
+  allowSymlinkTraversal = false
+): Promise<string> {
+  return await repoPathNormalizer.normalize(repoRoot, candidatePath, allowSymlinkTraversal);
+}
+
+export function areaMatches(repoRelativePath: string, area: string, matchingMode = 'repo_prefix'): boolean {
+  return areaMatchingPolicy.areaMatches(repoRelativePath, area, matchingMode);
+}
+
+export function anyAreaMatch(repoRelativePath: string, areas: string[], matchingMode = 'repo_prefix'): boolean {
+  return areaMatchingPolicy.anyAreaMatch(repoRelativePath, areas, matchingMode);
+}
+
+export function sortResourcesDeterministically(resources: string[]): string[] {
+  return [...new Set(resources)].sort((a, b) => a.localeCompare(b));
+}

package/apps/control-plane/src/core/qa-index.ts

@@ -0,0 +1,179 @@
+import { nowIso, stableHash } from './fs.js';
+import type { ParsedDiffFile, DiffHunk } from './patch.js';
+
+export type QaStatus = 'pending' | 'running' | 'passed' | 'failed' | 'waived';
+
+export interface QaIndexItem {
+  path: string;
+  hunks: DiffHunk[];
+  required_tests: string[];
+  status: QaStatus;
+  last_run_at?: string;
+  evidence_refs?: string[];
+}
+
+export interface QaIndex {
+  feature_id: string;
+  version: number;
+  source_diff_ref: string;
+  items: QaIndexItem[];
+}
+
+export interface QaUpdate {
+  path: string;
+  hunk: DiffHunk;
+  status: QaStatus;
+}
+
+export class QaIndexDomainService {
+  private hunkKey(filePath: string, hunk: DiffHunk): string {
+    return `${filePath}:${hunk.start_line}:${hunk.end_line}:${hunk.change_type}`;
+  }
+
+  makeRequiredTests(gateProfile: string, profile: { modes?: Record<string, Array<{ name: string }>> }): string[] {
+    const required: string[] = [];
+    for (const [mode, steps] of Object.entries(profile.modes ?? {})) {
+      for (const step of steps) {
+        required.push(`${gateProfile}:${mode}:${step.name}`);
+      }
+    }
+    return required;
+  }
+
+  buildIndex(
+    featureId: string,
+    parsedDiffFiles: ParsedDiffFile[],
+    requiredTests: string[],
+    previousIndex: QaIndex | null = null
+  ): QaIndex {
+    const previousItemsByKey = new Map<string, QaIndexItem>();
+    for (const item of previousIndex?.items ?? []) {
+      for (const hunk of item.hunks ?? []) {
+        previousItemsByKey.set(this.hunkKey(item.path, hunk), item);
+      }
+    }
+
+    const items: QaIndexItem[] = [];
+    for (const file of parsedDiffFiles) {
+      const filePath = file.newPath === '/dev/null' ? file.oldPath : file.newPath;
+      if (!filePath) {
+        continue;
+      }
+      const hunks =
+        file.hunks?.length > 0
+          ? file.hunks
+          : ([{ start_line: 1, end_line: 1, change_type: file.changeType }] as DiffHunk[]);
+
+      const existing = previousItemsByKey.get(this.hunkKey(filePath, hunks[0]));
+      items.push({
+        path: filePath,
+        hunks,
+        required_tests: requiredTests,
+        status: existing?.status ?? 'pending',
+        last_run_at: existing?.last_run_at,
+        evidence_refs: existing?.evidence_refs ?? []
+      });
+    }
+
+    const sourceDiffRef = stableHash(JSON.stringify(parsedDiffFiles));
+
+    return {
+      feature_id: featureId,
+      version: Number(previousIndex?.version ?? 0) + 1,
+      source_diff_ref: sourceDiffRef,
+      items
+    };
+  }
+
+  summarize(index: QaIndex): {
+    summary: Record<QaStatus, number>;
+    pending_by_file: Record<string, Array<{ hunks: DiffHunk[]; required_tests: string[] }>>;
+  } {
+    const summary: Record<QaStatus, number> = {
+      pending: 0,
+      running: 0,
+      passed: 0,
+      failed: 0,
+      waived: 0
+    };
+
+    const pendingByFile: Record<string, Array<{ hunks: DiffHunk[]; required_tests: string[] }>> = {};
+
+    for (const item of index.items ?? []) {
+      summary[item.status] = (summary[item.status] ?? 0) + 1;
+      if (item.status === 'pending') {
+        pendingByFile[item.path] = pendingByFile[item.path] ?? [];
+        pendingByFile[item.path].push({
+          hunks: item.hunks,
+          required_tests: item.required_tests
+        });
+      }
+    }
+
+    return { summary, pending_by_file: pendingByFile };
+  }
+
+  applyUpdates(index: QaIndex, expectedVersion: number, updates: QaUpdate[], evidenceRefs: string[] = []): QaIndex {
+    if (index.version !== expectedVersion) {
+      throw new Error('qa_index_version_conflict');
+    }
+
+    const keyedItems = new Map<string, QaIndexItem>();
+    for (const item of index.items ?? []) {
+      for (const hunk of item.hunks ?? []) {
+        keyedItems.set(this.hunkKey(item.path, hunk), item);
+      }
+    }
+
+    for (const update of updates) {
+      if (!update.path || !update.hunk) {
+        throw new Error('invalid_argument');
+      }
+      const key = this.hunkKey(update.path, update.hunk);
+      const item = keyedItems.get(key);
+      if (!item) {
+        throw new Error('invalid_argument');
+      }
+
+      item.status = update.status;
+      item.last_run_at = nowIso();
+      item.evidence_refs = [...new Set([...(item.evidence_refs ?? []), ...evidenceRefs])];
+    }
+
+    return {
+      ...index,
+      version: index.version + 1
+    };
+  }
+}
+
+export const qaIndexDomainService = new QaIndexDomainService();
+
+export function makeRequiredTests(gateProfile: string, profile: { modes?: Record<string, Array<{ name: string }>> }): string[] {
+  return qaIndexDomainService.makeRequiredTests(gateProfile, profile);
+}
+
+export function buildQaIndex(
+  featureId: string,
+  parsedDiffFiles: ParsedDiffFile[],
+  requiredTests: string[],
+  previousIndex: QaIndex | null = null
+): QaIndex {
+  return qaIndexDomainService.buildIndex(featureId, parsedDiffFiles, requiredTests, previousIndex);
+}
+
+export function summarizeQaIndex(index: QaIndex): {
+  summary: Record<QaStatus, number>;
+  pending_by_file: Record<string, Array<{ hunks: DiffHunk[]; required_tests: string[] }>>;
+} {
+  return qaIndexDomainService.summarize(index);
+}
+
+export function applyQaUpdates(
+  index: QaIndex,
+  expectedVersion: number,
+  updates: QaUpdate[],
+  evidenceRefs: string[] = []
+): QaIndex {
+  return qaIndexDomainService.applyUpdates(index, expectedVersion, updates, evidenceRefs);
+}

package/apps/control-plane/src/core/response.ts

@@ -0,0 +1,62 @@
+import { ERROR_CODES, type ErrorCode } from './error-codes.js';
+
+export interface OkResponse<T = Record<string, unknown>> {
+  ok: true;
+  data: T;
+  evidence?: Record<string, unknown>;
+}
+
+export interface FailResponse {
+  ok: false;
+  error: {
+    code: ErrorCode;
+    message: string;
+    details: Record<string, unknown>;
+  };
+  evidence?: Record<string, unknown>;
+}
+
+export type ToolResponse<T = Record<string, unknown>> = OkResponse<T> | FailResponse;
+
+export function ok<T = Record<string, unknown>>(data: T = {} as T, evidence?: Record<string, unknown>): OkResponse<T> {
+  const response: OkResponse<T> = { ok: true, data };
+  if (evidence) {
+    response.evidence = evidence;
+  }
+  return response;
+}
+
+export function fail(
+  code: string,
+  message: string,
+  details: Record<string, unknown> = {},
+  evidence?: Record<string, unknown>
+): FailResponse {
+  const normalizedCode = (Object.values(ERROR_CODES) as string[]).includes(code)
+    ? (code as ErrorCode)
+    : ERROR_CODES.INTERNAL_ERROR;
+  const response: FailResponse = {
+    ok: false,
+    error: {
+      code: normalizedCode,
+      message,
+      details
+    }
+  };
+  if (evidence) {
+    response.evidence = evidence;
+  }
+  return response;
+}
+
+export function withSuggestedActions(
+  details: Record<string, unknown>,
+  actions: string[] = []
+): Record<string, unknown> {
+  return {
+    ...details,
+    retryable: (details.retryable as boolean | undefined) ?? false,
+    requires_human: (details.requires_human as boolean | undefined) ?? false,
+    suggested_next_actions: actions
+  };
+}

package/apps/control-plane/src/core/runtime-sessions.ts

@@ -0,0 +1,20 @@
+export interface RuntimeFeatureSessions {
+  planner_session_id: string;
+  builder_session_id: string;
+  qa_session_id: string;
+}
+
+export interface RuntimeSessionsSnapshot {
+  run_id: string;
+  orchestrator_session_id: string;
+  provider: string;
+  model: string;
+  provider_config_ref_hash: string;
+  owner_instance_id: string;
+  lease_id: string;
+  started_at: string;
+  last_heartbeat_at: string;
+  lease_expires_at: string;
+  orchestrator_epoch?: number;
+  feature_sessions?: Record<string, RuntimeFeatureSessions>;
+}