@besales/ops-framework 0.1.0

package/bin/run-check.mjs

@@ -0,0 +1,559 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  appendOrchestrationLog,
+  buildCheckerContextPack,
+  buildCheckContext,
+  buildCheckerFailureResult,
+  buildEvidenceMarkdown,
+  computePromptSha,
+  computeTaskContextInputs,
+  getFlag,
+  isCheckContextCurrent,
+  normalizeCheckResult,
+  parseCliArgs,
+  pipelineRoot,
+  readAgentsConfig,
+  readCheckContext,
+  readMemorySnapshot,
+  readPrompt,
+  readTaskFile,
+  repoRoot,
+  cacheRoot,
+  resolveConfigValue,
+  resolveTaskDir,
+  sha256Json,
+  writeTaskFile,
+} from './lib/check-context-utils.mjs';
+import {
+  resolveExternalCliProvider,
+  runExternalCliChecker,
+} from './providers/external-cli-checker.mjs';
+import { runOpenAiChecker } from './providers/openai-checker.mjs';
+import {
+  buildCheckerLlmInputPack,
+  buildContextModeSequence,
+  isContextInsufficientResult,
+  resolveLlmContextMode,
+  summarizePackForConsole,
+} from './lib/llm-input-pack-utils.mjs';
+import { recordLlmInputUsage } from './lib/task-manifest-utils.mjs';
+
+function main() {
+  runMain().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+async function runMain() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0];
+  if (!taskArg) {
+    throw new Error('Usage: node ops/agent-pipeline/bin/run-check.mjs <TASK-id-or-task-path> [--checker-provider openai] [--checker-model model] [--dry-run]');
+  }
+
+  const taskDir = resolveTaskDir(taskArg);
+  const taskId = path.basename(taskDir);
+  const dryRun = getFlag(args, 'dry-run', false) === true;
+  const noCache = getFlag(args, 'no-cache', false) === true;
+  const checkerConfig = resolveCheckerConfig(args);
+
+  const checkContext = ensureFreshCheckContext(taskDir, taskId);
+  const initialContextMode = resolveLlmContextMode({
+    requestedMode: getFlag(args, 'context-mode') || getFlag(args, 'llm-context-mode'),
+    riskTriggers: checkContext.riskTriggers,
+  });
+  const checkerPrompt = readPrompt('checker.md');
+  const checkerPromptSha = computePromptSha('checker.md');
+
+  if (dryRun) {
+    const cacheKey = buildCheckerCacheKey({
+      taskId,
+      checkContext,
+      checkerConfig,
+      checkerPromptSha,
+      contextMode: initialContextMode,
+    });
+    const promptPayload = buildCheckerPromptPayload({
+      taskDir,
+      taskId,
+      checkerPrompt,
+      checkerPromptSha,
+      checkContext,
+      cacheKey,
+      contextMode: initialContextMode,
+    });
+    console.log(`Checker dry-run ok for ${taskId}`);
+    console.log(`- provider: ${checkerConfig.provider}`);
+    console.log(`- model: ${checkerConfig.model || '(missing)'}`);
+    console.log(`- reasoningEffort: ${checkerConfig.reasoningEffort}`);
+    console.log(`- providerConfig: ${describeProviderConfig(checkerConfig)}`);
+    console.log(`- cacheKeySha: ${sha256Json(cacheKey)}`);
+    console.log(`- promptMessages: ${promptPayload.messages.length}`);
+    for (const line of summarizePackForConsole(promptPayload.pack)) {
+      console.log(line);
+    }
+    return;
+  }
+
+  let providerOutput = null;
+  let cacheKey = null;
+  let cacheKeySha = null;
+  let promptPayload = null;
+  let rerunCount = 0;
+  const llmInputAttempts = [];
+
+  for (const contextMode of buildContextModeSequence(initialContextMode)) {
+    cacheKey = buildCheckerCacheKey({
+      taskId,
+      checkContext,
+      checkerConfig,
+      checkerPromptSha,
+      contextMode,
+    });
+    cacheKeySha = sha256Json(cacheKey);
+    promptPayload = buildCheckerPromptPayload({
+      taskDir,
+      taskId,
+      checkerPrompt,
+      checkerPromptSha,
+      checkContext,
+      cacheKey,
+      contextMode,
+    });
+
+    console.log(`Checker LLM input for ${taskId}`);
+    for (const line of summarizePackForConsole(promptPayload.pack)) {
+      console.log(line);
+    }
+    if (promptPayload.pack.meta.overCap && contextMode !== 'strict') {
+      llmInputAttempts.push(buildAttemptRecord(promptPayload.pack.meta, 'skipped_over_cap'));
+      appendOrchestrationLog(taskDir, `checker LLM input exceeded ${contextMode} cap; rerunning pack builder with expanded context`);
+      continue;
+    }
+    if (promptPayload.pack.meta.overCap) {
+      llmInputAttempts.push(buildAttemptRecord(promptPayload.pack.meta, 'over_cap_blocked'));
+      writeFailureArtifacts({
+        taskDir,
+        taskId,
+        checkContext,
+        checkerConfig,
+        checkerPromptSha,
+        cacheKey,
+        failureReason: 'context_overflow',
+        message: `Strict LLM input pack exceeds cap: estimatedTokens=${promptPayload.pack.meta.estimatedTokens}, capTokens=${promptPayload.pack.meta.capTokens}`,
+        rawOutput: null,
+      });
+      recordLlmInputUsage({
+        taskDir,
+        stage: 'check',
+        packMeta: promptPayload.pack.meta,
+        attempts: llmInputAttempts,
+        rerunCount,
+      });
+      runValidator(taskArg);
+      console.log(`Checker blocked for ${taskId}: strict context pack over cap`);
+      return;
+    }
+
+    if (!noCache && restoreFromCache({ taskDir, taskArg, cacheKeySha })) {
+      llmInputAttempts.push(buildAttemptRecord(promptPayload.pack.meta, 'cache_hit'));
+      recordLlmInputUsage({
+        taskDir,
+        stage: 'check',
+        packMeta: promptPayload.pack.meta,
+        attempts: llmInputAttempts,
+        rerunCount,
+      });
+      console.log(`Checker cache hit for ${taskId}: ${cacheKeySha}`);
+      return;
+    }
+
+    try {
+      providerOutput = await runProvider({
+        checkerConfig,
+        messages: promptPayload.messages,
+        prompt: promptPayload.prompt,
+      });
+    } catch (error) {
+      const failureReason = error.failureReason || 'unknown';
+      writeFailureArtifacts({
+        taskDir,
+        taskId,
+        checkContext,
+        checkerConfig,
+        checkerPromptSha,
+        cacheKey,
+        failureReason,
+        message: error.message,
+        rawOutput: error.rawOutput || null,
+      });
+      llmInputAttempts.push(buildAttemptRecord(promptPayload.pack.meta, `provider_failed:${failureReason}`));
+      recordLlmInputUsage({
+        taskDir,
+        stage: 'check',
+        packMeta: promptPayload.pack.meta,
+        attempts: llmInputAttempts,
+        rerunCount,
+      });
+      runValidator(taskArg);
+      throw new Error(`Checker provider failed with ${failureReason}: ${error.message}`);
+    }
+
+    if (!isContextInsufficientResult(providerOutput.checkResultJson) || contextMode === 'strict') {
+      llmInputAttempts.push(buildAttemptRecord(promptPayload.pack.meta, providerOutput.checkResultJson?.verdict || 'completed'));
+      break;
+    }
+    llmInputAttempts.push(buildAttemptRecord(promptPayload.pack.meta, 'context_insufficient'));
+    rerunCount += 1;
+    appendOrchestrationLog(taskDir, `checker returned context_insufficient in ${contextMode}; rerunning with expanded context`);
+  }
+
+  writeSuccessArtifacts({
+    taskDir,
+    taskId,
+    checkContext,
+    checkerConfig,
+    checkerPromptSha,
+    cacheKey,
+    providerOutput,
+  });
+  if (!isContextInsufficientResult(providerOutput.checkResultJson)) {
+    storeInCache({ taskDir, cacheKeySha });
+  }
+  recordLlmInputUsage({
+    taskDir,
+    stage: 'check',
+    packMeta: promptPayload.pack.meta,
+    attempts: llmInputAttempts,
+    rerunCount,
+  });
+  runValidator(taskArg);
+  console.log(`Checker run completed for ${taskId}: ${providerOutput.checkResultJson?.verdict}`);
+  console.log(`- finalLlmInputMode: ${promptPayload.pack.meta.mode}`);
+  console.log(`- finalEstimatedInputTokens: ${promptPayload.pack.meta.estimatedTokens}`);
+}
+
+function buildAttemptRecord(packMeta, outcome) {
+  return {
+    mode: packMeta.mode,
+    estimatedTokens: packMeta.estimatedTokens,
+    bytes: packMeta.bytes,
+    capTokens: packMeta.capTokens,
+    overCap: packMeta.overCap,
+    outcome,
+  };
+}
+
+function buildCheckerCacheKey({
+  taskId,
+  checkContext,
+  checkerConfig,
+  checkerPromptSha,
+  contextMode,
+}) {
+  return {
+    taskId,
+    planSha: checkContext.planSha,
+    memorySha: checkContext.memorySha,
+    checkerProvider: checkerConfig.provider,
+    checkerModel: checkerConfig.model,
+    checkerReasoningEffort: checkerConfig.reasoningEffort,
+    checkerPromptSha,
+    riskProfile: checkContext.riskProfile,
+    contextMode,
+  };
+}
+
+function ensureFreshCheckContext(taskDir, taskId) {
+  const currentState = isCheckContextCurrent(taskDir);
+  if (currentState.current) {
+    return currentState.actual;
+  }
+
+  const inputs = computeTaskContextInputs(taskDir);
+  const checkContext = buildCheckContext({ taskId, inputs });
+  const evidence = buildEvidenceMarkdown({
+    taskId,
+    risk: inputs.risk,
+    qualityGates: inputs.qualityGates,
+    referencedFiles: inputs.referencedFiles,
+    structuralLines: inputs.structuralLines,
+    planFingerprint: inputs.planFingerprint,
+    memorySha: inputs.memorySha,
+    taskArtifacts: inputs.taskArtifacts,
+  });
+  const checkerContextPack = buildCheckerContextPack({
+    taskId,
+    risk: inputs.risk,
+    qualityGates: inputs.qualityGates,
+    referencedFiles: inputs.referencedFiles,
+    structuralLines: inputs.structuralLines,
+    taskArtifacts: inputs.taskArtifacts,
+  });
+
+  writeTaskFile(taskDir, 'check-context.json', JSON.stringify(checkContext, null, 2));
+  writeTaskFile(taskDir, 'check-evidence.md', evidence);
+  writeTaskFile(taskDir, checkContext.checkerContextPackFile, checkerContextPack);
+  return readCheckContext(taskDir);
+}
+
+function resolveCheckerConfig(args) {
+  const config = readAgentsConfig();
+  const configuredProvider = resolveConfigValue(config.checker?.provider);
+  const configuredModel = resolveConfigValue(config.checker?.model);
+  const configuredReasoningEffort = resolveConfigValue(config.checker?.reasoningEffort);
+  const provider = getFlag(args, 'checker-provider')
+    || process.env.CHECKER_PROVIDER
+    || configuredProvider
+    || 'codex-cli';
+  const providerDefaults = config.checkerProviders?.[provider] || {};
+  const providerDefaultModel = resolveConfigValue(providerDefaults.model);
+  const providerDefaultReasoningEffort = resolveConfigValue(providerDefaults.reasoningEffort);
+  const model = getFlag(args, 'checker-model')
+    || process.env.CHECKER_MODEL
+    || providerDefaultModel
+    || configuredModel
+    || (provider === 'cloud-cli' || provider === 'claude-cli' ? 'claude-opus-4-7' : provider === 'openai' ? 'gpt-4.1-mini' : 'gpt-5.5');
+  const reasoningEffort = getFlag(args, 'checker-reasoning-effort')
+    || process.env.CHECKER_REASONING_EFFORT
+    || providerDefaultReasoningEffort
+    || configuredReasoningEffort
+    || 'medium';
+
+  return {
+    provider,
+    model,
+    reasoningEffort,
+    readOnly: config.checker?.readOnly !== false,
+    isolatedContext: config.checker?.isolatedContext !== false,
+    providerConfig: resolveExternalCliProvider(provider, config),
+  };
+}
+
+function buildCheckerPromptPayload({
+  taskDir,
+  taskId,
+  checkerPrompt,
+  checkerPromptSha,
+  checkContext,
+  cacheKey,
+  contextMode,
+}) {
+  const memorySnapshot = readMemorySnapshot(checkContext.memoryFiles);
+  const evidence = readTaskFile(taskDir, checkContext.evidenceFile);
+  const checkerContextPack = readTaskFile(taskDir, checkContext.checkerContextPackFile || 'checker-context-pack.md');
+  const taskManifest = readTaskFile(taskDir, 'task-manifest.json');
+  const pack = buildCheckerLlmInputPack({
+    taskDir,
+    taskId,
+    checkerPromptSha,
+    cacheKey,
+    checkContext,
+    checkEvidence: evidence,
+    checkerContextPack,
+    taskManifest,
+    projectMemory: memorySnapshot.map((item) => ({
+      path: item.path,
+      sha: item.sha,
+      content: item.content,
+    })),
+    mode: contextMode,
+  });
+
+  const system = [
+    checkerPrompt,
+    '',
+    'Fresh-context enforcement:',
+    '- You are an independent Checker invocation.',
+    '- You do not have access to conversation history or Planner reasoning.',
+    '- Treat research.md and plan.md as claims to review, not as truth.',
+    '- Do not write or request source mutations. Return review artifacts only.',
+    '',
+    'Return one JSON object with exactly:',
+    '- checkMarkdown: markdown content for check.md',
+    '- checkResultJson: object matching check.result.json contract',
+  ].join('\n');
+
+  const user = JSON.stringify(pack.input, null, 2);
+
+  return {
+    messages: [
+      { role: 'system', content: system },
+      { role: 'user', content: user },
+    ],
+    prompt: `${system}\n\n<checker_input_json>\n${user}\n</checker_input_json>\n`,
+    pack,
+  };
+}
+
+async function runProvider({ checkerConfig, messages, prompt }) {
+  if (checkerConfig.provider === 'openai') {
+    return runOpenAiChecker({
+      apiKey: process.env.OPENAI_API_KEY,
+      model: checkerConfig.model,
+      messages,
+    });
+  }
+
+  if (checkerConfig.providerConfig) {
+    return runExternalCliChecker({
+      providerName: checkerConfig.provider,
+      providerConfig: checkerConfig.providerConfig,
+      model: checkerConfig.model,
+      reasoningEffort: checkerConfig.reasoningEffort,
+      prompt,
+      cwd: repoRoot,
+    });
+  }
+
+  const error = new Error(`Unsupported checker provider: ${checkerConfig.provider}`);
+  error.failureReason = 'provider_unavailable';
+  throw error;
+}
+
+function writeSuccessArtifacts({
+  taskDir,
+  taskId,
+  checkContext,
+  checkerConfig,
+  checkerPromptSha,
+  cacheKey,
+  providerOutput,
+}) {
+  const checkMarkdown = typeof providerOutput.checkMarkdown === 'string'
+    ? providerOutput.checkMarkdown
+    : '# Check\n\nChecker did not provide markdown.';
+  const normalizedResult = normalizeCheckResult(providerOutput.checkResultJson || {}, {
+    taskId,
+    checkContext,
+    checkerProvider: checkerConfig.provider,
+    checkerModel: checkerConfig.model,
+  });
+
+  writeTaskFile(taskDir, 'check.md', appendRunnerMetadata(checkMarkdown, checkerPromptSha, cacheKey));
+  writeTaskFile(taskDir, 'check.result.json', JSON.stringify(normalizedResult, null, 2));
+  if (providerOutput.rawOutput) {
+    writeTaskFile(taskDir, 'checker-output.raw.md', providerOutput.rawOutput);
+  }
+}
+
+function writeFailureArtifacts({
+  taskDir,
+  taskId,
+  checkContext,
+  checkerConfig,
+  checkerPromptSha,
+  cacheKey,
+  failureReason,
+  message,
+  rawOutput,
+}) {
+  const result = buildCheckerFailureResult({
+    taskId,
+    checkContext,
+    checkerProvider: checkerConfig.provider,
+    checkerModel: checkerConfig.model,
+    failureReason,
+  });
+  const markdown = [
+    '# Check',
+    '',
+    '## Итоговая оценка',
+    '',
+    '`checker_failed`',
+    '',
+    '## Failure',
+    '',
+    `- Reason: \`${failureReason}\``,
+    `- Message: ${message}`,
+    '',
+  ].join('\n');
+
+  writeTaskFile(taskDir, 'check.md', appendRunnerMetadata(markdown, checkerPromptSha, cacheKey));
+  writeTaskFile(taskDir, 'check.result.json', JSON.stringify(result, null, 2));
+  if (rawOutput) {
+    writeTaskFile(taskDir, 'checker-output.raw.md', rawOutput);
+  }
+}
+
+function appendRunnerMetadata(markdown, checkerPromptSha, cacheKey) {
+  return `${markdown.trimEnd()}\n\n## Runner Metadata\n\n\`\`\`json\n${JSON.stringify({
+    checkerPromptSha,
+    cacheKey,
+    cacheKeySha: sha256Json(cacheKey),
+  }, null, 2)}\n\`\`\`\n`;
+}
+
+function runValidator(taskArg) {
+  const validatorPath = path.join(pipelineRoot, 'bin', 'validate-check-artifacts.mjs');
+  const result = spawnSync(process.execPath, [validatorPath, taskArg, '--skip-resolution'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+  if (result.status !== 0) {
+    throw new Error(`Checker artifacts failed validation with exit code ${result.status}.`);
+  }
+}
+
+function restoreFromCache({ taskDir, taskArg, cacheKeySha }) {
+  const cacheDir = path.join(cacheRoot, 'check-results', sanitizeCacheKey(cacheKeySha));
+  const cachedCheck = path.join(cacheDir, 'check.md');
+  const cachedResult = path.join(cacheDir, 'check.result.json');
+  if (!fs.existsSync(cachedCheck) || !fs.existsSync(cachedResult)) {
+    return false;
+  }
+
+  let cachedResultJson;
+  try {
+    cachedResultJson = JSON.parse(fs.readFileSync(cachedResult, 'utf8'));
+  } catch {
+    return false;
+  }
+  if (isContextInsufficientResult(cachedResultJson)) {
+    return false;
+  }
+  fs.copyFileSync(cachedCheck, path.join(taskDir, 'check.md'));
+  fs.copyFileSync(cachedResult, path.join(taskDir, 'check.result.json'));
+  const cachedRaw = path.join(cacheDir, 'checker-output.raw.md');
+  if (fs.existsSync(cachedRaw)) {
+    fs.copyFileSync(cachedRaw, path.join(taskDir, 'checker-output.raw.md'));
+  }
+  runValidator(taskArg);
+  return true;
+}
+
+function storeInCache({ taskDir, cacheKeySha }) {
+  const cacheDir = path.join(cacheRoot, 'check-results', sanitizeCacheKey(cacheKeySha));
+  fs.mkdirSync(cacheDir, { recursive: true });
+  for (const fileName of ['check.md', 'check.result.json', 'checker-output.raw.md']) {
+    const source = path.join(taskDir, fileName);
+    if (fs.existsSync(source)) {
+      fs.copyFileSync(source, path.join(cacheDir, fileName));
+    }
+  }
+}
+
+function sanitizeCacheKey(cacheKeySha) {
+  return cacheKeySha.replace(/^sha256:/, '');
+}
+
+function describeProviderConfig(checkerConfig) {
+  if (checkerConfig.provider === 'openai') {
+    return process.env.OPENAI_API_KEY ? 'ok' : 'missing OPENAI_API_KEY';
+  }
+  if (checkerConfig.providerConfig) {
+    return `external CLI command=${checkerConfig.providerConfig.command}`;
+  }
+  return 'missing provider preset';
+}
+
+main();