nexakit 0.0.0-stage → 0.2.0

package/src/memory-mcp-transport.js

@@ -0,0 +1,59 @@
+import { deserializeMessage, serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
+import { MEMORY_MCP_LIMITS, MemoryMcpError } from "./memory-mcp-policy.js";
+import { decode, parseEventJson } from "./client-output-json.js";
+
+/** Byte-framed STDIO: limits apply to each message, not a batch of valid lines. */
+export class MemoryMcpTransport {
+  constructor(input, output, hooks = {}) {
+    this.input = input; this.output = output; this.hooks = hooks;
+    this.parts = []; this.bytes = 0; this.closed = false; this.started = false;
+    this.data = chunk => this.accept(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    this.end = () => { void this.close(); };
+    this.error = () => this.fail("RG_PROTOCOL_ERROR");
+  }
+  async start() {
+    if (this.started || this.closed) throw new MemoryMcpError("RG_PROTOCOL_ERROR");
+    this.started = true;
+    this.input.on("data", this.data); this.input.on("end", this.end); this.input.on("error", this.error);
+  }
+  fail(code) { this.hooks.onFatal?.(code); this.onerror?.(new MemoryMcpError(code, true)); void this.close(); }
+  accept(chunk) {
+    if (this.closed) return;
+    let offset = 0;
+    while (offset < chunk.length && !this.closed) {
+      const newline = chunk.indexOf(10, offset), stop = newline === -1 ? chunk.length : newline;
+      this.bytes += stop - offset;
+      if (this.bytes > MEMORY_MCP_LIMITS.requestBytes) { this.fail("RG_INPUT_LIMIT"); return; }
+      this.parts.push(chunk.subarray(offset, stop));
+      if (newline === -1) return;
+      const bytes = Buffer.concat(this.parts, this.bytes); this.parts = []; this.bytes = 0;
+      try {
+        // Reject invalid UTF-8 and duplicate JSON keys before SDK dispatch.
+        const message = deserializeMessage(JSON.stringify(parseEventJson(decode(bytes))));
+        if ("id" in message && !(Number.isSafeInteger(message.id) || typeof message.id === "string" && message.id.length <= 128)) throw Error();
+        if ("method" in message && (message.method.length > 128 || /[\x00-\x1f]/.test(message.method))) throw Error();
+        this.onmessage?.(message);
+      } catch { this.fail("RG_PROTOCOL_ERROR"); return; }
+      offset = newline + 1;
+    }
+  }
+  async send(message) {
+    if (this.closed) throw new MemoryMcpError("RG_SESSION_CLOSED");
+    if (message.error) {
+      const code = message.error.message.match(/^(?:MCP error -\d+: )?(RG_[A-Z_]+)$/)?.[1];
+      message = { jsonrpc: "2.0", id: message.id, error: { code: message.error.code, message: code ?? "RG_PROTOCOL_ERROR" } };
+    }
+    const line = serializeMessage(message);
+    if (Buffer.byteLength(line) > MEMORY_MCP_LIMITS.responseBytes) { this.fail("RG_RESPONSE_LIMIT"); throw new MemoryMcpError("RG_RESPONSE_LIMIT", true); }
+    await new Promise((resolve, reject) => {
+      try { this.output.write(line, error => error ? reject(new MemoryMcpError("RG_PROTOCOL_ERROR", true)) : resolve()); }
+      catch { reject(new MemoryMcpError("RG_PROTOCOL_ERROR", true)); }
+    });
+  }
+  async close() {
+    if (this.closed) return; this.closed = true; this.parts = []; this.bytes = 0;
+    this.input.off("data", this.data); this.input.off("end", this.end); this.input.off("error", this.error);
+    if (!this.input.listenerCount("data")) this.input.pause();
+    this.onclose?.(); this.hooks.onClose?.();
+  }
+}

package/src/missing-dependencies.js

@@ -0,0 +1,21 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isEphemeralPath } from './link-states.js';
+
+// This file must stay free of third-party imports: it has to run exactly when they are missing.
+const copyRoot = () => path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+
+// Loads a module of nexakit. If a third-party package is missing in a checkout, says how to install it instead
+// of showing a stack trace. Any other failure is raised untouched, and so is a missing package under npx,
+// where `npm ci` would be the wrong advice.
+export async function loadWithDependencyCheck(load, { root = copyRoot(), write = text => process.stderr.write(text) } = {}) {
+  try {
+    return await load();
+  } catch (error) {
+    const missingPackage = error?.code === 'ERR_MODULE_NOT_FOUND' && /^Cannot find package '/u.test(error.message ?? '');
+    if (!missingPackage || isEphemeralPath(root)) throw error;
+    write(`Faltan las dependencias de esta copia. Ejecuta \`npm ci\` en ${root}.\n`);
+    process.exitCode = 1;
+    return null;
+  }
+}

package/src/model-command.js

@@ -0,0 +1,147 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { getStaticTOMLValue, parseTOML } from 'toml-eslint-parser';
+import { agentModels } from './agent-models.js';
+import { resolveCliInvocation } from './cli-executable.js';
+import { runRevisionProcess } from './revision-process.js';
+import pkg from '../package.json' with { type: 'json' };
+
+export async function inspectModels({
+  homeDirectory = os.homedir(),
+  environment = process.env,
+  codexProfile,
+  runCommand,
+  includeAntigravity = true,
+} = {}) {
+  const codexHome = environment.CODEX_HOME ?? path.join(homeDirectory, '.codex');
+  const claudeHome = environment.CLAUDE_CONFIG_DIR ?? path.join(homeDirectory, '.claude');
+  const old = await agentModels({ codexHome, claudeHome });
+  let cache = {},
+    config = {},
+    settings = {};
+  try {
+    cache = JSON.parse(await fs.readFile(path.join(codexHome, 'models_cache.json'), 'utf8'));
+  } catch {}
+  try {
+    config = getStaticTOMLValue(parseTOML(await fs.readFile(path.join(codexHome, 'config.toml'), 'utf8')));
+  } catch {}
+  try {
+    settings = JSON.parse(await fs.readFile(path.join(claudeHome, 'settings.json'), 'utf8'));
+  } catch {}
+  const profile = codexProfile ?? config.profile;
+  const selected = profile ? config.profiles?.[profile] : null;
+  let storedCodex =
+    profile && !selected
+      ? null
+      : {
+          model: selected?.model ?? config.model ?? null,
+          effort: selected?.model_reasoning_effort ?? config.model_reasoning_effort ?? null,
+        };
+  // Modern Codex profiles can also be separate files; no shell interpolation.
+  if (profile && /^[a-zA-Z0-9._-]+$/u.test(profile)) {
+    try {
+      const layer = getStaticTOMLValue(
+        parseTOML(await fs.readFile(path.join(codexHome, `${profile}.config.toml`), 'utf8')),
+      );
+      storedCodex = {
+        model: layer.model ?? config.model ?? null,
+        effort: layer.model_reasoning_effort ?? config.model_reasoning_effort ?? null,
+      };
+    } catch {}
+  }
+  let antigravity = [],
+    error = null;
+  if (includeAntigravity) {
+    try {
+      let result;
+      if (runCommand) result = await runCommand('agy', ['models']);
+      else {
+        const cli = await resolveCliInvocation({ name: 'agy', environment });
+        result = await runRevisionProcess(
+          { executable: cli.executable, args: [...cli.argsPrefix, 'models'], env: environment },
+          { prompt: '', timeoutMs: 20000 },
+        );
+      }
+      if (result.status !== 0 || result.timedOut) throw new Error('No se pudo consultar agy models.');
+      antigravity = result.stdout.split('\n').flatMap((line) => {
+        const [model, label] = line.split('\t');
+        const effort = model?.match(/-(low|medium|high|xhigh|max)$/u)?.[1];
+        return model && label && effort
+          ? [{ model, description: label, efforts: [effort], defaultEffort: effort }]
+          : [];
+      });
+    } catch (e) {
+      error = e.message;
+    }
+  }
+  const codex = old.codex.models.map((item) => ({
+    ...item,
+    defaultEffort: cache.models?.find((m) => m.slug === item.model)?.default_reasoning_level ?? null,
+  }));
+  return {
+    catalogs: { claude: old.claude.map((m) => ({ ...m, defaultEffort: 'medium' })), codex, antigravity },
+    stored: {
+      claude: {
+        model: settings.model ?? null,
+        effort: settings.modelSettings?.[settings.model]?.effortLevel ?? settings.effortLevel ?? null,
+      },
+      codex: storedCodex,
+      antigravity: null,
+    },
+    sources: {
+      claude: `lista incluida en nexakit ${pkg.version}`,
+      codex: 'models_cache.json de Codex',
+      antigravity: error ?? 'agy models; el esfuerzo forma parte del id',
+    },
+    levels: old.levels,
+  };
+}
+
+export async function validateReviewChoice(options) {
+  const data = await inspectModels({ ...options, includeAntigravity: options.client === 'antigravity' });
+  const match = data.catalogs[options.client]?.find((item) => item.model === options.model);
+  if (!match || !match.efforts.includes(options.effort))
+    throw new Error('Modelo o esfuerzo no disponible en el catálogo real; consulta nexakit modelo.');
+}
+export async function runModelCommand(args, { out, err }, options = {}) {
+  let level, client, profile;
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i],
+      value = args[++i];
+    if (seen.has(flag) || !value) {
+      await err('Argumentos de modelo inválidos.\n');
+      return 2;
+    }
+    seen.add(flag);
+    if (flag === '--nivel') level = value;
+    else if (flag === '--ia') client = value;
+    else if (flag === '--perfil-codex') profile = value;
+    else return 2;
+  }
+  if (client && !['claude', 'codex', 'antigravity'].includes(client)) return 2;
+  const data = await inspectModels({ ...options, codexProfile: profile });
+  const row = level ? data.levels.find((x) => x.level.toLowerCase() === level.toLowerCase()) : null;
+  if (level && !row) return 2;
+  for (const ia of client ? [client] : ['claude', 'codex', 'antigravity']) {
+    await out(`${ia}: ${data.sources[ia]}\n`);
+    for (const model of data.catalogs[ia])
+      await out(
+        `  ${model.model} · ${model.efforts.join(', ')} · defecto ${model.defaultEffort ?? 'no informado'}\n`,
+      );
+    const stored = data.stored[ia],
+      wanted = row?.[ia];
+    const mark =
+      !stored?.model || !stored?.effort || !wanted
+        ? '?'
+        : stored.model === wanted.model && stored.effort === wanted.effort
+          ? '✓'
+          : '→';
+    await out(
+      `${mark} Guardado: ${stored?.model ?? 'no comprobable'} · ${stored?.effort ?? 'no informado'}${wanted ? ` · recomendado ${wanted.model} · ${wanted.effort}` : ''}\n`,
+    );
+  }
+  await out('Compara lo guardado; una sesión abierta puede diferir. Compruébalo en /model.\n');
+  return 0;
+}

package/src/model-preference.js

@@ -0,0 +1,235 @@
+import Ajv2020 from "ajv/dist/2020.js";
+
+const SCHEMA_ID = "https://agent-toolkit.local/schemas/agent-model-preference.schema.json";
+const DOCUMENTS = ["request", "catalog", "policy"];
+
+// Internal extension: helpers and both schemas come from the trusted factory.
+// This module performs no file, network, account or client operations.
+export function createPreferenceSelector(baseSchema, schema, helpers) {
+  const {
+    hashJson, isUtcTimestamp, emptyReport, finish, semanticIssues, taskBlocks,
+    profileExclusions, matchingEvaluations, compareText, uniqueIssues,
+    hasDuplicates, REQUIRED_REQUEST_FIELDS, REQUIRED_REQUIREMENTS
+  } = helpers;
+  if (schema.$id !== SCHEMA_ID) throw new Error("Unsupported preference schema");
+  const ajv = new Ajv2020({ strict: true, allErrors: true });
+  ajv.addFormat("date-time", { type: "string", validate: isUtcTimestamp });
+  ajv.addSchema(baseSchema);
+  ajv.addSchema(schema);
+  const validators = Object.fromEntries(DOCUMENTS.map((name) => [
+    name, ajv.compile({ $ref: `${SCHEMA_ID}#/$defs/${name}` })
+  ]));
+  const schemaSha256 = hashJson(schema);
+  const baseSchemaSha256 = hashJson(baseSchema);
+  const comboKey = (profileId, effort) => JSON.stringify([profileId, effort]);
+  const scopeKey = (rule) => JSON.stringify([rule.category, rule.difficulty, rule.risk]);
+  const sameScope = (rule, request) => rule.category === request.category &&
+    rule.difficulty === request.difficulty && rule.risk === request.risk;
+
+  return function selectPreference(data) {
+    const report = emptyReport(schemaSha256);
+    report.schemaVersion = "2.0.0";
+    report.selectorVersion = "2.0.0";
+    report.audit.baseSchemaSha256 = baseSchemaSha256;
+    report.effortExcluded = [];
+    report.alternatives = [];
+    for (const name of DOCUMENTS) {
+      report.audit[`${name}Sha256`] = data[name] === undefined ? null : hashJson(data[name]);
+      if (!validators[name](data[name])) report.issues.push({ code: "schema-invalid", document: name });
+    }
+    if (validators.request(data.request)) {
+      const { projectId, taskId, revision, role, mode } = data.request;
+      report.identity = { projectId, taskId, revision, role, mode };
+    }
+    if (report.issues.length) return finish(report, "invalid", "invalid-structure-or-version-mix");
+
+    const { request, catalog, policy } = data;
+    report.audit.catalog = { id: catalog.catalogId, revision: catalog.revision };
+    report.audit.policy = { id: policy.policyId, revision: policy.revision };
+    report.constraints = {
+      provider: request.provider ?? null, client: request.client ?? null,
+      mode: request.mode, authorizationContext: request.authorizationContext ?? null,
+      history: request.history ?? null, maxCorrectionRounds: policy.maxCorrectionRounds,
+      maxFutureExecutions: policy.maxFutureExecutions,
+      maxFutureDurationSeconds: policy.maxFutureDurationSeconds,
+      accessType: policy.accessType, execution: policy.execution
+    };
+    const profiles = new Map(catalog.profiles.map((entry) => [entry.profileId, entry]));
+    // Reuse v1 invariants only; this projection never selects or migrates data.
+    const invariantPolicy = {
+      ...policy,
+      routes: policy.routes.map((route) => ({
+        ...route,
+        priorities: [...new Set(route.families.flatMap((family) => family.profileIds))]
+          .map((profileId) => ({ profileId, rank: 0 }))
+      }))
+    };
+    const issues = semanticIssues(request, catalog, invariantPolicy, profiles);
+    const add = (code, document) => issues.push({ code, document });
+    const versions = new Set();
+    const models = new Set();
+    for (const profile of catalog.profiles) {
+      const modelKey = JSON.stringify([profile.provider, profile.client, profile.requestedModel]);
+      if (models.has(modelKey)) add("duplicate-model-identity", "catalog");
+      models.add(modelKey);
+      if (profile.versionOrdinal !== null) {
+        const key = JSON.stringify([profile.provider, profile.client, profile.familyId, profile.versionOrdinal]);
+        if (versions.has(key)) add("duplicate-version-ordinal", "catalog");
+        versions.add(key);
+      }
+      for (const evaluation of profile.evaluations) {
+        if (!supportsEffort(profile, evaluation.effort)) add("unsupported-evaluation-effort", "catalog");
+      }
+    }
+    for (const route of policy.routes) {
+      if (hasDuplicates(route.families.map((family) => family.familyId))) add("duplicate-family", "policy");
+      if (hasDuplicates(route.families.map((family) => family.rank))) add("ambiguous-family-order", "policy");
+      if (hasDuplicates(route.families.flatMap((family) => family.profileIds))) add("duplicate-family-profile", "policy");
+      const ruleIds = [];
+      const combinations = new Map();
+      const effortRanks = new Map();
+      for (const family of route.families) {
+        if (hasDuplicates(family.effortRules.map(scopeKey))) add("overlapping-effort-rules", "policy");
+        for (const id of family.profileIds) {
+          const profile = profiles.get(id);
+          if (profile && profile.familyId !== family.familyId) add("family-profile-mismatch", "policy");
+        }
+        for (const rule of family.effortRules) {
+          ruleIds.push(rule.ruleId);
+          if (!route.categories.includes(rule.category)) add("rule-category-not-permitted", "policy");
+          if (hasDuplicates(rule.options.map((option) => comboKey(option.profileId, option.effort)))) {
+            add("duplicate-effort-option", "policy");
+          }
+          for (const option of rule.options) {
+            const profile = profiles.get(option.profileId);
+            if (!profile) { add("unknown-effort-profile", "policy"); continue; }
+            if (!family.profileIds.includes(option.profileId)) add("effort-profile-outside-family", "policy");
+            if (!supportsEffort(profile, option.effort)) add("unsupported-effort", "policy");
+            const key = comboKey(option.profileId, option.effort);
+            const previous = combinations.get(key);
+            if (previous && (previous.effortRank !== option.effortRank ||
+                previous.progressionRank !== option.progressionRank)) add("inconsistent-effort-order", "policy");
+            combinations.set(key, option);
+            const rankKey = JSON.stringify([option.profileId, option.effortRank]);
+            if (effortRanks.has(rankKey) && effortRanks.get(rankKey) !== key) add("ambiguous-effort-order", "policy");
+            effortRanks.set(rankKey, key);
+          }
+        }
+      }
+      if (hasDuplicates(ruleIds)) add("duplicate-effort-rule-id", "policy");
+      for (const profileId of new Set([...combinations.values()].map((option) => option.profileId))) {
+        const ordered = [...combinations.values()].filter((option) => option.profileId === profileId)
+          .sort((a, b) => a.effortRank - b.effortRank);
+        if (ordered.some((option, index) => index > 0 && option.progressionRank < ordered[index - 1].progressionRank)) {
+          add("contradictory-quality-progression", "policy");
+        }
+      }
+    }
+    if (request.explicitEffort !== undefined && !request.explicitProfileId) add("explicit-effort-without-profile", "request");
+    if (request.history?.previousEffort !== undefined && !request.history.previousProfileId) {
+      add("previous-effort-without-profile", "request");
+    }
+    report.issues = uniqueIssues(issues);
+    if (report.issues.length) return finish(report, "invalid", "invalid-references-or-data");
+
+    report.missing = REQUIRED_REQUEST_FIELDS.filter((key) => request[key] === undefined);
+    if (request.requirements) report.missing.push(...REQUIRED_REQUIREMENTS
+      .filter((key) => request.requirements[key] === undefined).map((key) => `requirements.${key}`));
+    if (request.escalation && request.history) {
+      if (!request.history.previousProfileId) report.missing.push("history.previousProfileId");
+      if (request.history.previousEffort === undefined) report.missing.push("history.previousEffort");
+    }
+    report.missing.sort(compareText);
+    if (report.missing.length) return finish(report, "needs-info", "missing-task-information");
+    const blocks = taskBlocks(request, policy);
+    if (blocks.length) {
+      report.reasons.push(...blocks);
+      return finish(report, "blocked");
+    }
+    const route = policy.routes.find((entry) => entry.role === request.role &&
+      entry.provider === request.provider && entry.client === request.client);
+    if (!route || !route.modes.includes(request.mode) || !route.categories.includes(request.category)) {
+      return finish(report, "blocked", "route-not-permitted");
+    }
+    let previousCombination;
+    if (request.escalation) {
+      previousCombination = route.families.flatMap((family) => family.effortRules)
+        .flatMap((rule) => rule.options).find((option) =>
+          option.profileId === request.history.previousProfileId && option.effort === request.history.previousEffort);
+      if (!previousCombination) return finish(report, "blocked", "previous-combination-not-in-route");
+    }
+
+    const availability = new Map(request.availability.map((entry) => [entry.profileId, entry]));
+    const families = new Map(route.families.map((family) => [family.familyId, family]));
+    const candidates = [];
+    for (const profile of [...catalog.profiles].sort((a, b) => compareText(a.profileId, b.profileId))) {
+      const family = families.get(profile.familyId);
+      const permitted = family?.profileIds.includes(profile.profileId);
+      const record = availability.get(profile.profileId);
+      const reasons = profileExclusions(profile, permitted ? { rank: family.rank } : undefined, record, request, policy);
+      if (!permitted) {
+        report.excluded.push({ profileId: profile.profileId, reasons });
+        continue;
+      }
+      if (family.profileIds.some((id) => profiles.get(id).versionOrdinal === null)) reasons.push("family-version-order-unknown");
+      const rule = family.effortRules.find((entry) => sameScope(entry, request));
+      if (!rule) reasons.push("no-matching-effort-rule");
+      if (reasons.length) {
+        report.excluded.push({ profileId: profile.profileId, reasons });
+        continue;
+      }
+      let admitted = 0;
+      for (const option of rule.options.filter((entry) => entry.profileId === profile.profileId)
+        .sort((a, b) => a.effortRank - b.effortRank)) {
+        const optionReasons = [];
+        const evaluations = matchingEvaluations(profile, request).filter((entry) => entry.effort === option.effort);
+        if (!evaluations.length) optionReasons.push("effort-scope-not-evaluated");
+        if (option.effortRank > rule.maxEffortRank) optionReasons.push("effort-limit-exceeded");
+        if (previousCombination && option.progressionRank <= previousCombination.progressionRank) {
+          optionReasons.push("not-higher-approved-progression");
+        }
+        if (optionReasons.length) report.effortExcluded.push({ profileId: profile.profileId, effort: option.effort, reasons: optionReasons });
+        else {
+          candidates.push({ profile, family, rule, option, record, evaluations });
+          admitted++;
+        }
+      }
+      if (!admitted) report.excluded.push({ profileId: profile.profileId, reasons: ["no-admissible-effort"] });
+    }
+    candidates.sort((a, b) => a.family.rank - b.family.rank ||
+      b.profile.versionOrdinal - a.profile.versionOrdinal || a.option.effortRank - b.option.effortRank ||
+      compareText(a.profile.profileId, b.profile.profileId));
+    report.alternatives = candidates.map(({ profile, family, option }) => ({
+      profileId: profile.profileId, familyId: family.familyId, familyRank: family.rank,
+      versionOrdinal: profile.versionOrdinal, effort: option.effort,
+      effortRank: option.effortRank, progressionRank: option.progressionRank
+    }));
+    const chosen = request.explicitProfileId ? candidates.find((entry) =>
+      entry.profile.profileId === request.explicitProfileId &&
+      (request.explicitEffort === undefined || entry.option.effort === request.explicitEffort)) : candidates[0];
+    if (!chosen) return finish(report, "blocked", request.explicitProfileId
+      ? "explicit-choice-not-admissible" : "no-admissible-combination");
+    const { profile, family, rule, option, record, evaluations } = chosen;
+    report.recommendation = {
+      profileId: profile.profileId, provider: profile.provider, client: profile.client,
+      requestedModel: profile.requestedModel, versionPolicy: profile.versionPolicy,
+      familyId: family.familyId, familyRank: family.rank,
+      familyEvidenceRefs: family.evidenceRefs,
+      versionOrdinal: profile.versionOrdinal, versionEvidenceRefs: profile.versionEvidenceRefs,
+      effort: option.effort, effortRank: option.effortRank, effortRuleId: rule.ruleId,
+      effortEvidenceRefs: [...new Set([...rule.evidenceRefs, ...option.evidenceRefs])].sort(compareText),
+      progressionRank: option.progressionRank,
+      evaluationEvidenceRefs: [...new Set(evaluations.flatMap((entry) => entry.evidenceRefs))].sort(compareText),
+      availabilityEvidence: record
+    };
+    const knownOrdinals = family.profileIds.map((id) => profiles.get(id).versionOrdinal);
+    if (profile.versionOrdinal < Math.max(...knownOrdinals)) report.reasons.push("older-than-known-version");
+    if (request.escalation) report.reasons.push("quality-escalation-with-declared-evidence");
+    return finish(report, "recommended", request.explicitProfileId
+      ? "explicit-compatible-choice" : "preferred-family-latest-admissible-version-and-effort");
+  };
+}
+
+function supportsEffort(profile, effort) {
+  return effort === null ? profile.effortOptions.length === 0 : profile.effortOptions.includes(effort);
+}