cadet-agent 0.20.2 → 0.24.0

package/src/harness/redaction.mjs

@@ -0,0 +1,133 @@
+/**
+ * Cadet-Agent redaction.
+ *
+ * Removes secrets from structured values and bounded output before ledger
+ * persistence and before report display. Covers: bearer/basic auth headers, API
+ * keys and common provider prefixes, JWTs, private keys/certificates,
+ * passwords and password-like keys, connection strings, cloud access keys,
+ * npm/GitHub tokens, and secret values nested in arrays or objects.
+ *
+ * Contract: docs/core/HarnessContract.md §8.
+ */
+
+export const REDACTED = '[REDACTED]';
+
+/** Key names whose *values* are always redacted, case-insensitive, substring match. */
+const SECRET_KEY_PATTERNS = [
+  /pass(word|phrase)?/i,
+  /secret/i,
+  /token/i,
+  /api[_-]?key/i,
+  /apikey/i,
+  /private[_-]?key/i,
+  /client[_-]?secret/i,
+  /access[_-]?key/i,
+  /auth(orization)?/i,
+  /credential/i,
+  /connection[_-]?string/i,
+  /conn[_-]?str/i,
+  /^pwd$/i,
+  /session[_-]?id/i,
+  /cookie/i,
+];
+
+/** Value patterns redacted regardless of key. Applied in order. */
+const VALUE_RULES = [
+  // Bearer / Basic auth headers
+  { name: 'auth-header', re: /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi },
+  // JWTs (three base64url segments)
+  { name: 'jwt', re: /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/g },
+  // Private key blocks
+  { name: 'private-key', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g },
+  { name: 'certificate', re: /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g },
+  // Provider-prefixed API keys
+  { name: 'openai-key', re: /\bsk-[A-Za-z0-9-]{16,}\b/g },
+  { name: 'anthropic-key', re: /\bsk-ant-[A-Za-z0-9-]{16,}\b/g },
+  { name: 'stripe-key', re: /\b(sk|pk|rk)_(live|test)_[A-Za-z0-9]{16,}\b/g },
+  { name: 'github-token', re: /\b(gh[pousr]|github_pat)_[A-Za-z0-9_]{16,}\b/g },
+  { name: 'npm-token', re: /\bnpm_[A-Za-z0-9]{16,}\b/g },
+  { name: 'aws-access-key', re: /\b(AKIA|ASIA)[0-9A-Z]{16}\b/g },
+  { name: 'google-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { name: 'slack-token', re: /\bxox[abopr]-[A-Za-z0-9-]{10,}\b/g },
+  // Connection strings with embedded credentials
+  { name: 'connection-string', re: /\b[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s:@]+@[^\s'"]+/gi },
+  // Generic long hex/base64 secrets assigned via `=` or `:`
+  { name: 'assigned-secret', re: /\b(secret|password|passwd|pwd|token|apikey|api_key)\s*[=:]\s*["']?([A-Za-z0-9._~+/=-]{12,})["']?/gi, keepPrefix: true },
+];
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** Redact secrets inside a string value. */
+export function redactString(input) {
+  if (typeof input !== 'string') return input;
+  let out = input;
+  for (const rule of VALUE_RULES) {
+    if (rule.keepPrefix) {
+      out = out.replace(rule.re, (match, key) => `${key}=${REDACTED}`);
+    } else {
+      out = out.replace(rule.re, REDACTED);
+    }
+  }
+  return out;
+}
+
+function keyIsSecret(key) {
+  return SECRET_KEY_PATTERNS.some((re) => re.test(key));
+}
+
+/**
+ * Deeply redact a structured value. Arrays and nested objects are traversed.
+ * Secret-like keys always have their values replaced; secret-shaped strings are
+ * redacted regardless of key.
+ */
+export function redact(value, { maxDepth = 12 } = {}) {
+  return redactValue(value, 0, maxDepth);
+}
+
+function redactValue(value, depth, maxDepth) {
+  if (depth > maxDepth) return '[TRUNCATED]';
+  if (typeof value === 'string') return redactString(value);
+  if (Array.isArray(value)) return value.map((v) => redactValue(v, depth + 1, maxDepth));
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+      if (keyIsSecret(key)) {
+        out[key] = v === null || v === undefined ? v : REDACTED;
+      } else {
+        out[key] = redactValue(v, depth + 1, maxDepth);
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Detect whether a value contains anything that would be redacted, without
+ * returning the secret. Useful for tests and for flagging suspicious payloads.
+ */
+export function containsSecret(value) {
+  let found = false;
+  const visit = (v) => {
+    if (found) return;
+    if (typeof v === 'string') {
+      if (redactString(v) !== v) found = true;
+    } else if (Array.isArray(v)) {
+      v.forEach(visit);
+    } else if (isPlainObject(v)) {
+      for (const [k, child] of Object.entries(v)) {
+        if (keyIsSecret(k) && child !== null && child !== undefined && child !== '') { found = true; return; }
+        visit(child);
+      }
+    }
+  };
+  visit(value);
+  return found;
+}
+
+/** Bundled regex source for each named category (used by the fixture coverage test). */
+export const REDACTION_CATEGORIES = Object.freeze(
+  Object.fromEntries(VALUE_RULES.map((r) => [r.name, r.re.source]))
+);

package/src/harness/routing.mjs

@@ -0,0 +1,153 @@
+/**
+ * Cadet-Agent tool routing.
+ *
+ * Applies the tool-selection decision tree (contract §8) and capability
+ * fallbacks. Routing never pretends a live capability exists: when MCP is
+ * unavailable the call falls back to static context and CLI verification.
+ * Live-editor mutation requires explicit user confirmation.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const TOOL_KINDS = Object.freeze(['cli', 'read', 'search', 'mcp', 'write', 'manual']);
+
+export const ROUTING_REASONS = Object.freeze({
+  verification: 'deterministic CLI for verification (exit-code driven)',
+  staticContext: 'repository read/search for static context',
+  liveInspection: 'MCP for live Unity inspection or mutation',
+  unavailable: 'capability unavailable — falling back to a safe alternative',
+});
+
+class RoutingError extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = 'RoutingError';
+    Object.assign(this, detail);
+  }
+}
+
+/**
+ * Detect the capability set. Nothing here contacts the network or the Editor;
+ * it only reports what the environment supports.
+ */
+export function detectCapabilities({ targetDir = process.cwd(), env = process.env, runner = defaultRunner } = {}) {
+  const unity = which('unity', { env, runner });
+  const mcpConfigured = existsSync(join(targetDir, '.vscode', 'mcp.json'))
+    || existsSync(join(targetDir, '.cursor', 'mcp.json'))
+    || existsSync(join(targetDir, '.mcp.json'));
+
+  return {
+    cli: true,
+    unityCli: unity.available ? { available: true, path: unity.path, version: unity.version } : { available: false },
+    mcp: mcpConfigured ? { available: true, configured: true } : { available: false, configured: false },
+    hook: {
+      copilot: existsSync(join(targetDir, '.github', 'hooks', 'git-guard.json')),
+      note: 'Cursor, Continue, and Claude Code have no native PreToolUse hook',
+    },
+    tokenTelemetry: { provider: false, source: 'estimate' },
+    costTelemetry: { available: false, reason: 'no model rate card configured' },
+  };
+}
+
+function defaultRunner(cmd, args) {
+  return spawnSync(cmd, args, { encoding: 'utf-8', windowsHide: true, shell: false });
+}
+
+function which(cmd, { env, runner }) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  const res = runner(probe, [cmd]);
+  if (res && res.status === 0 && res.stdout) {
+    const path = String(res.stdout).split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0];
+    let version = null;
+    try {
+      const v = runner(cmd, ['--version']);
+      if (v && v.status === 0 && v.stdout) version = String(v.stdout).trim().split(/\r?\n/)[0];
+    } catch { /* version is optional */ }
+    return { available: true, path, version };
+  }
+  return { available: false };
+}
+
+/**
+ * Decide which tool to use for a task. Returns a routing decision with a reason
+ * and the fallback that was applied, if any.
+ */
+export function routeTask({ task, capabilities = {} } = {}) {
+  if (!task || !TOOL_KINDS.includes(task.kind)) {
+    throw new RoutingError(`unknown task kind "${task?.kind}"`);
+  }
+
+  const decide = (tool, reason, extra = {}) => ({
+    tool,
+    kind: task.kind,
+    reason,
+    fallbackApplied: false,
+    ...extra,
+  });
+
+  switch (task.kind) {
+    case 'cli':
+    case 'manual':
+      return decide(task.kind, ROUTING_REASONS.verification);
+
+    case 'read':
+    case 'search':
+      return decide(task.kind, ROUTING_REASONS.staticContext);
+
+    case 'write': {
+      // A write to a live Editor is a mutation and needs confirmation.
+      if (task.target === 'live-editor') {
+        if (!task.userConfirmed) {
+          throw new RoutingError('live-editor mutation requires explicit user confirmation', { blocked: true, requiresConfirmation: true });
+        }
+        if (!capabilities.mcp?.available) {
+          return decide('manual', ROUTING_REASONS.unavailable, {
+            fallbackApplied: true,
+            fallback: 'live-editor mutation requested but MCP is unavailable; ask the user to perform it',
+          });
+        }
+        return decide('mcp', ROUTING_REASONS.liveInspection, { userConfirmed: true });
+      }
+      return decide('write', 'repository write within the workspace');
+    }
+
+    case 'mcp': {
+      if (capabilities.mcp?.available) {
+        return decide('mcp', ROUTING_REASONS.liveInspection);
+      }
+      // Never pretend live inspection occurred.
+      const fallback = task.fallback === 'cli' || task.verification
+        ? decide('cli', ROUTING_REASONS.unavailable, { fallbackApplied: true, fallback: 'static context + CLI verification' })
+        : decide('read', ROUTING_REASONS.unavailable, { fallbackApplied: true, fallback: 'static context only' });
+      return { ...fallback, liveInspectionPerformed: false };
+    }
+
+    default:
+      throw new RoutingError(`unhandled task kind "${task.kind}"`);
+  }
+}
+
+/**
+ * Record a tool call. Arguments are sanitized by the caller (see redaction.mjs)
+ * before persistence; this function only shapes the span.
+ */
+export function toolCallSpan({ tool, args = {}, rationale, startedAt, finishedAt, durationMs, resultClass, outputBytes = 0, artifactPath = null, exitCode = null, retryNumber = 0 }) {
+  return {
+    kind: 'tool-call',
+    tool,
+    args,
+    reason: rationale,
+    startedAt,
+    finishedAt,
+    durationMs,
+    result: resultClass,
+    outputBytes,
+    artifactPath,
+    exitCode,
+    retryNumber,
+  };
+}
+
+export { RoutingError };