@aria_asi/cli 0.2.36 → 0.2.37

package/runtime-src/coach-kernel.mjs

@@ -0,0 +1,371 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const COACH_EVENT_SCHEMA = 'aria.coach_kernel_event.v1';
+export const COACH_STATE_SCHEMA = 'aria.coach_kernel_state.v1';
+export const DEFAULT_COACH_STATE_DIR = join(__dirname, 'state');
+export const DEFAULT_COACH_LEDGER_PATH = join(DEFAULT_COACH_STATE_DIR, 'coach-events.jsonl');
+export const DEFAULT_COACH_STATE_PATH = join(DEFAULT_COACH_STATE_DIR, 'coach-state.json');
+
+export const COACH_PHASES = Object.freeze([
+  'pre_turn',
+  'pre_cognition',
+  'post_cognition',
+  'pre_generation',
+  'post_generation',
+  'pre_tool',
+  'post_tool',
+  'pre_output',
+  'post_output',
+  'background_start',
+  'background_checkpoint',
+  'background_complete',
+  'claim_or_release',
+]);
+
+const ALLOWED_PHASES = new Set(COACH_PHASES);
+const OUTPUT_PHASES = new Set(['post_generation', 'pre_output', 'post_output', 'claim_or_release']);
+const TOOL_PHASES = new Set(['pre_tool', 'post_tool']);
+const SECRET_KEY_RX = /\b(?:api[_-]?key|secret|token|authorization|password|credential|private[_-]?key)\b/i;
+const SECRET_VALUE_RX = /\b(?:sk-[A-Za-z0-9_-]{16,}|xox[baprs]-[A-Za-z0-9-]{20,}|gh[pousr]_[A-Za-z0-9_]{20,}|Bearer\s+[A-Za-z0-9._~+\/-]{20,}|AKIA[0-9A-Z]{16})\b/i;
+const COGNITION_RX = /<cognition>[\s\S]*?<\/cognition>/i;
+const APPLIED_COGNITION_RX = /<applied_cognition>[\s\S]*?<\/applied_cognition>/i;
+const VERIFY_RX = /<verify>[\s\S]*?(?:verified|rollback|target|predicate)[\s\S]*?<\/verify>/i;
+const COMPLETION_CLAIM_RX = /\b(?:done|complete|completed|ready|verified|fixed|shipped|production-ready|release-ready|passing|passed)\b/i;
+const MEASURABLE_EVIDENCE_RX = /\b(?:exit\s*0|0\s+failures?|passed|status\s*[:=]\s*(?:ok|200|healthy|pass)|verified\s*[:=]\s*true|ledger_record_id|receiptId|sha256|http\s*2\d\d)\b/i;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function stableString(value) {
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value || '');
+  }
+}
+
+function hashValue(value) {
+  return createHash('sha256').update(stableString(value)).digest('hex');
+}
+
+function normalizeString(value, fallback = '') {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function normalizeStringArray(values) {
+  return Array.from(new Set((Array.isArray(values) ? values : [])
+    .map((value) => normalizeString(value))
+    .filter(Boolean)))
+    .sort();
+}
+
+function redactPotentialSecrets(text) {
+  return String(text || '')
+    .replace(/Bearer\s+[A-Za-z0-9._~+\/-]{12,}/gi, 'Bearer [redacted]')
+    .replace(/\bsk-[A-Za-z0-9_-]{12,}\b/g, '[redacted-secret]')
+    .replace(/\bgh[pousr]_[A-Za-z0-9_]{12,}\b/g, '[redacted-secret]')
+    .replace(/\bxox[baprs]-[A-Za-z0-9-]{12,}\b/g, '[redacted-secret]')
+    .replace(/\bAKIA[0-9A-Z]{16}\b/g, '[redacted-secret]');
+}
+
+function redactedClone(value, depth = 0) {
+  if (depth > 5) return '[truncated]';
+  if (typeof value === 'string') return redactPotentialSecrets(value).slice(0, 2000);
+  if (typeof value === 'number' || typeof value === 'boolean' || value == null) return value;
+  if (Array.isArray(value)) return value.slice(0, 50).map((entry) => redactedClone(entry, depth + 1));
+  if (typeof value !== 'object') return String(value);
+  const out = {};
+  for (const [key, entry] of Object.entries(value).slice(0, 80)) {
+    if (SECRET_KEY_RX.test(key)) {
+      out[key] = '[redacted]';
+      continue;
+    }
+    out[key] = redactedClone(entry, depth + 1);
+  }
+  return out;
+}
+
+function normalizeEvidenceRefs(values) {
+  const raw = Array.isArray(values) ? values : [];
+  return raw.slice(0, 50).map((entry) => {
+    if (typeof entry === 'string') return redactPotentialSecrets(entry).slice(0, 500);
+    if (entry && typeof entry === 'object') return redactedClone(entry);
+    return String(entry || '').slice(0, 500);
+  }).filter((entry) => Boolean(typeof entry === 'string' ? entry.trim() : entry));
+}
+
+function phaseOrDefault(phase) {
+  const candidate = normalizeString(phase, 'pre_turn');
+  return ALLOWED_PHASES.has(candidate) ? candidate : 'pre_turn';
+}
+
+function hasEvidence(event, text) {
+  if (Array.isArray(event.evidence_refs) && event.evidence_refs.length > 0) return true;
+  if (event.validation?.passed === true || event.validation?.severity === 'pass') return true;
+  if (event.layer3?.pass === true) return true;
+  if (event.metadata?.validated_output === true || event.metadata?.verified === true) return true;
+  return MEASURABLE_EVIDENCE_RX.test(text || event.text_preview || '');
+}
+
+function hasVerifyEvidence(event, text) {
+  if (event.metadata?.requireVerify === false) return true;
+  if (event.metadata?.verify === true || event.metadata?.verified === true) return true;
+  if (VERIFY_RX.test(text || event.text_preview || '')) return true;
+  return hasEvidence(event, text) && /\b(?:rollback|verify|verified|deployment|rollout|kubectl|terraform|helm|docker)\b/i.test(text || event.text_preview || '');
+}
+
+function inferRiskClass(highRisk, repairable) {
+  if (highRisk.length > 0) return 'high';
+  if (repairable.length > 0) return 'medium';
+  return 'low';
+}
+
+function decisionFromSignals(highRisk, repairable, warnings) {
+  if (highRisk.length > 0) {
+    return {
+      decision: 'hard_block',
+      permitted: false,
+      nextAction: 'do_not_release; write operator evidence and re-author only after the high-risk condition is removed',
+      reasons: highRisk,
+    };
+  }
+  if (repairable.length > 0) {
+    return {
+      decision: 'repair_once',
+      permitted: false,
+      nextAction: 'repair_or_regenerate_once_before_user_visible_release',
+      reasons: repairable,
+    };
+  }
+  if (warnings.length > 0) {
+    return {
+      decision: 'warn_operator_only',
+      permitted: true,
+      nextAction: 'continue_and_preserve_operator_warning',
+      reasons: warnings,
+    };
+  }
+  return {
+    decision: 'allow',
+    permitted: true,
+    nextAction: 'continue',
+    reasons: [],
+  };
+}
+
+export function normalizeCoachEvent(input = {}) {
+  const phase = phaseOrDefault(input.phase);
+  const rawText = normalizeString(input.text || input.output || input.message || input.target || '');
+  const metadata = redactedClone(input.metadata && typeof input.metadata === 'object' ? input.metadata : {});
+  const record = {
+    coach_event_id: normalizeString(input.coachEventId || input.coach_event_id) || `coach_${randomUUID().replace(/-/g, '')}`,
+    request_id: normalizeString(input.requestId || input.request_id) || `req_${randomUUID().replace(/-/g, '')}`,
+    session_id: normalizeString(input.sessionId || input.session_id, 'unknown'),
+    surface: normalizeString(input.surface || input.client || input.platform, 'aria-runtime'),
+    lane: normalizeString(input.lane, 'managed_aria_provider'),
+    phase,
+    action: normalizeString(input.action),
+    target_hash: input.target ? hashValue(input.target) : null,
+    target_preview: input.target ? redactPotentialSecrets(String(input.target)).slice(0, 500) : null,
+    text_hash: rawText ? hashValue(rawText) : null,
+    text_preview: rawText ? redactPotentialSecrets(rawText).slice(0, 1000) : '',
+    harness_packet_hash: normalizeString(input.harnessPacketHash || input.harness_packet_hash),
+    role_profile: normalizeString(input.roleProfile || input.role_profile),
+    required_skill_ids: normalizeStringArray(input.requiredSkillIds || input.required_skill_ids),
+    loaded_skill_ids: normalizeStringArray(input.loadedSkillIds || input.loaded_skill_ids),
+    missing_skill_ids: normalizeStringArray(input.missingSkillIds || input.missing_skill_ids),
+    evidence_refs: normalizeEvidenceRefs(input.evidenceRefs || input.evidence_refs),
+    validation: redactedClone(input.validation || null),
+    layer3: redactedClone(input.layer3 || null),
+    quality_gate_status: normalizeString(input.qualityGateStatus || input.quality_gate_status, 'pending'),
+    compliance_gate_status: normalizeString(input.complianceGateStatus || input.compliance_gate_status, 'pending'),
+    metadata,
+  };
+  Object.defineProperty(record, 'rawText', { value: rawText, enumerable: false });
+  return record;
+}
+
+export function evaluateCoachEvent(event = {}) {
+  const normalized = event.phase ? event : normalizeCoachEvent(event);
+  const text = normalized.rawText || normalized.text_preview || '';
+  const highRisk = [];
+  const repairable = [];
+  const warnings = [];
+  const action = String(normalized.action || '').toLowerCase();
+
+  if (!ALLOWED_PHASES.has(normalized.phase)) {
+    highRisk.push('unknown_coach_phase');
+  }
+  if (SECRET_VALUE_RX.test(text) || SECRET_VALUE_RX.test(stableString(normalized.metadata))) {
+    highRisk.push('secret_or_credential_exposure');
+  }
+  if (normalized.phase === 'pre_generation' && normalized.missing_skill_ids.length > 0) {
+    highRisk.push('required_skill_unavailable_before_generation');
+  }
+  if (TOOL_PHASES.has(normalized.phase) || action) {
+    if ((action === 'delete' || /\b(?:rm\s+-rf|drop\s+(?:table|database|schema)|git\s+reset\s+--hard)\b/i.test(text)) && normalized.metadata?.approved !== true) {
+      highRisk.push('unapproved_destructive_action');
+    }
+    if ((action === 'deploy' || /\b(?:kubectl\s+(?:apply|set|rollout|delete)|helm\s+upgrade|terraform\s+apply|docker\s+push)\b/i.test(text)) && !hasVerifyEvidence(normalized, text)) {
+      highRisk.push('unverified_deploy_or_infra_mutation');
+    }
+  }
+  if (OUTPUT_PHASES.has(normalized.phase)) {
+    const nonTrivial = text.length >= 300 || COMPLETION_CLAIM_RX.test(text);
+    if (nonTrivial && !COGNITION_RX.test(text) && normalized.metadata?.requireCognitionBlock !== false) {
+      repairable.push('missing_readable_cognition_before_release');
+    }
+    if (nonTrivial && !APPLIED_COGNITION_RX.test(text) && normalized.metadata?.requireAppliedCognition !== false) {
+      repairable.push('missing_applied_cognition_before_release');
+    }
+    if (COMPLETION_CLAIM_RX.test(text) && !hasEvidence(normalized, text)) {
+      repairable.push('unsupported_completion_or_verification_claim');
+    }
+  }
+  if (normalized.lane.includes('unmanaged') || normalized.metadata?.complianceGuarantee === 'best_effort_only') {
+    warnings.push('unmanaged_direct_provider_best_effort_only');
+  }
+
+  const verdict = decisionFromSignals(highRisk, repairable, warnings);
+  return {
+    ...verdict,
+    riskClass: inferRiskClass(highRisk, repairable),
+    highRisk,
+    repairable,
+    warnings,
+  };
+}
+
+function readJson(pathname, fallback) {
+  if (!existsSync(pathname)) return fallback;
+  try {
+    return JSON.parse(readFileSync(pathname, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function summarizeRecord(record) {
+  return {
+    at: record.at,
+    coach_event_id: record.coach_event_id,
+    request_id: record.request_id,
+    session_id: record.session_id,
+    surface: record.surface,
+    lane: record.lane,
+    phase: record.phase,
+    decision: record.decision,
+    risk_class: record.risk_class,
+    action: record.action || null,
+    reasons: Array.isArray(record.reasons) ? record.reasons.slice(0, 6) : [],
+    evidence_count: Array.isArray(record.evidence_refs) ? record.evidence_refs.length : 0,
+  };
+}
+
+function updateCoachState(record, statePath) {
+  const state = readJson(statePath, {
+    schema: COACH_STATE_SCHEMA,
+    updated_at: null,
+    counts: { total: 0, by_phase: {}, by_decision: {} },
+    last_events: [],
+    last_by_session: {},
+  });
+  state.schema = COACH_STATE_SCHEMA;
+  state.updated_at = record.at;
+  state.counts = state.counts || { total: 0, by_phase: {}, by_decision: {} };
+  state.counts.total = Number(state.counts.total || 0) + 1;
+  state.counts.by_phase = state.counts.by_phase || {};
+  state.counts.by_decision = state.counts.by_decision || {};
+  state.counts.by_phase[record.phase] = Number(state.counts.by_phase[record.phase] || 0) + 1;
+  state.counts.by_decision[record.decision] = Number(state.counts.by_decision[record.decision] || 0) + 1;
+  const summary = summarizeRecord(record);
+  state.last_events = [...(Array.isArray(state.last_events) ? state.last_events : []), summary].slice(-100);
+  state.last_by_session = state.last_by_session || {};
+  state.last_by_session[record.session_id] = summary;
+  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  return state;
+}
+
+export function recordCoachPhase(input = {}, options = {}) {
+  const ledgerPath = options.ledgerPath || DEFAULT_COACH_LEDGER_PATH;
+  const statePath = options.statePath || DEFAULT_COACH_STATE_PATH;
+  mkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });
+  mkdirSync(dirname(statePath), { recursive: true, mode: 0o700 });
+  const event = normalizeCoachEvent(input);
+  const evaluation = evaluateCoachEvent(event);
+  const record = {
+    schema: COACH_EVENT_SCHEMA,
+    at: nowIso(),
+    ...event,
+    risk_class: evaluation.riskClass,
+    decision: evaluation.decision,
+    permitted: evaluation.permitted,
+    reasons: evaluation.reasons,
+    high_risk_signals: evaluation.highRisk,
+    repairable_signals: evaluation.repairable,
+    warnings: evaluation.warnings,
+    next_action: evaluation.nextAction,
+  };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  const state = updateCoachState(record, statePath);
+  return {
+    ok: true,
+    permitted: record.permitted,
+    decision: record.decision,
+    ledgerPath,
+    statePath,
+    record,
+    state: summarizeCoachState(state),
+    clientMessage: formatCoachClientBlock(record),
+  };
+}
+
+export function summarizeCoachState(state = null) {
+  const source = state || readJson(DEFAULT_COACH_STATE_PATH, null);
+  if (!source) {
+    return {
+      schema: COACH_STATE_SCHEMA,
+      updated_at: null,
+      counts: { total: 0, by_phase: {}, by_decision: {} },
+      last_events: [],
+    };
+  }
+  return {
+    schema: source.schema || COACH_STATE_SCHEMA,
+    updated_at: source.updated_at || null,
+    counts: source.counts || { total: 0, by_phase: {}, by_decision: {} },
+    last_events: Array.isArray(source.last_events) ? source.last_events.slice(-25) : [],
+  };
+}
+
+export function readCoachState(options = {}) {
+  const statePath = options.statePath || DEFAULT_COACH_STATE_PATH;
+  const state = readJson(statePath, null);
+  return options.includeState === true ? state : summarizeCoachState(state);
+}
+
+export function formatCoachClientBlock(recordOrResult = {}) {
+  const record = recordOrResult.record || recordOrResult;
+  const reasons = Array.isArray(record.reasons) && record.reasons.length
+    ? record.reasons
+    : ['coach_kernel_policy_block'];
+  const status = record.decision === 'repair_once'
+    ? 'Aria Coach held this turn for repair before release.'
+    : record.decision === 'hard_block'
+      ? 'Aria Coach blocked this turn before release.'
+      : 'Aria Coach recorded an operator warning for this turn.';
+  const next = record.next_action || (record.decision === 'hard_block' ? 'remove the high-risk condition before retrying' : 'continue');
+  return [
+    status,
+    '',
+    `Reason: ${reasons.slice(0, 3).join('; ')}`,
+    `Next: ${next}`,
+  ].join('\n');
+}