auxilo-mcp 0.9.11 → 0.9.13

package/scripts/providers/provider.interface.js

@@ -0,0 +1,98 @@
+/**
+ * scripts/providers/provider.interface.js — Model Provider Interface (EXTRACT-PER-CLIENT W1 PART A)
+ *
+ * Doc-only contract, no runtime logic — mirrors scripts/sources/source.interface.js's
+ * role for transcript sources, but for the model that DOES the extraction/dedup-judge
+ * work. A provider module (scripts/providers/claude-code.js, codex-cli.js, byo-key.js)
+ * is any object exposing the shape documented below; there is no base class to extend
+ * because every provider's actual invocation mechanics (CLI spawn vs HTTP call) differ
+ * too much to share an implementation, only the contract.
+ *
+ * @module providers/provider.interface
+ */
+
+'use strict';
+
+/**
+ * @typedef {'extract'|'judge'} RunModelMode
+ *   'extract' (default) — draft learnings from a transcript.
+ *   'judge' — binary anchored-dedup decision against previously captured lessons.
+ *   A CLI provider may pick a different argv/parsing variant per mode (Claude Code
+ * does — extraction and judge invocations differ today). A provider that has no
+ * mode-specific behavior (e.g. codex-cli, PART B) may ignore `mode` and always use
+ * the same invocation shape.
+ */
+
+/**
+ * @typedef {object} RunModelUsage
+ * @property {number} input_tokens
+ * @property {number} output_tokens
+ */
+
+/**
+ * @typedef {object} RunModelOptions
+ * @property {string} prompt - The instruction text. Combined with `input` as the
+ *   model's full instruction: `prompt + (input || '')` — stdin for CLI providers,
+ *   message body for HTTP providers. This is the existing convention
+ *   `extractWithClaudeCode` already used; providers do not change it.
+ * @property {string} [input] - The transcript (extract mode) or empty (judge mode,
+ *   where the full payload already lives in `prompt`).
+ * @property {number} [timeoutMs] - Invocation timeout in milliseconds.
+ * @property {Function} [log] - Logger sink, `(line: string) => void`.
+ * @property {Function} [spawnSyncImpl] - Injectable `child_process.spawnSync`
+ *   replacement (CLI providers only) — the test-injection seam.
+ * @property {Function} [fetchImpl] - Injectable `fetch` replacement (HTTP providers
+ *   only) — the test-injection seam.
+ * @property {RunModelMode} [mode] - 'extract' (default) or 'judge'.
+ * @property {object} [schema] - Optional JSON-Schema hint a provider MAY use to
+ *   constrain its output. Claude Code ignores this — `extractJsonValue`'s
+ *   fence-strip + brace-scan parser is already model-agnostic and needs no schema
+ *   hint to do its job.
+ */
+
+/**
+ * @typedef {object} RunModelResult
+ * @property {boolean} ok
+ * @property {string} text - Raw model output (empty string on failure).
+ * @property {RunModelUsage|null} usage - Normalized token usage, or null when the
+ *   provider cannot report it (e.g. codex-cli's `-o` file carries no token counts).
+ *   Callers that need an estimate when usage is null do their own text-length
+ *   fallback (see scripts/extract-local.js's judge-usage bookkeeping) — providers
+ *   are not required to estimate on the caller's behalf.
+ * @property {string} [reasonCode] - Machine-matchable failure/skip classifier
+ *   (e.g. 'cli-unauthenticated', 'cli-billing-helper-configured', 'model-error',
+ *   'unknown'). Present on both success and failure paths where applicable.
+ * @property {string|null} [reason] - Human-readable reason, present when !ok.
+ * @property {string} [authStatus] - 'logged-in' | 'logged-out' | 'unknown', when
+ *   the provider has a meaningful concept of local auth state.
+ * @property {object} [identity] - {provider, model, version, vendor} — which
+ *   provider/model actually ran this call, for the extraction_model stamp
+ *   (scripts/extract-local.js's resolveExtractionModelIdentity reads THIS
+ *   field, not any other name). byo-key.js always sets it (full identity,
+ *   read from its stored config). codex-cli.js sets it (provider/version;
+ *   model/vendor null — codex exposes no per-call model id without --json).
+ *   claude-code.js does not set one yet; resolveExtractionModelIdentity
+ *   falls back to the resolved provider id alone when absent (EXTRACT-PER-
+ *   CLIENT W1 FIX GATE-A item (a) — codex-cli.js used to export this same
+ *   data under the field name `extraction_model`, which nothing here ever
+ *   read, so its real version silently never reached the stamp; that field
+ *   name survives one more release as a deprecated alias of `identity`).
+ */
+
+/**
+ * @callback RunModel
+ * @param {RunModelOptions} opts
+ * @returns {Promise<RunModelResult>}
+ */
+
+/**
+ * Contract a provider module implements:
+ *   - runModel(opts) → Promise<RunModelResult>   (see typedefs above)
+ *   - detect(opts) → boolean|Promise<boolean>     (installed/usable on this host?)
+ *   - checkAuthStatus(opts) → string               ('logged-in'|'logged-out'|'unknown')
+ *
+ * No base class — see module comment. Nothing here is imported for its runtime
+ * value; this file exists so the contract has one canonical, grep-able location.
+ */
+
+module.exports = {};

package/scripts/providers/schemas/extraction-envelope.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$comment": "EXTRACT-PER-CLIENT W1 PART B — passed to `codex exec --output-schema` for mode:'extract'. Mirrors scripts/extract-local.js's parseExtractionOutput (line 252) and normalizeLearningArray (line 208, title>=10 chars / body>=50 chars gate at the filter on line ~211-212) exactly as they exist at this wave's base. A bare array of the same learning shape is ALSO accepted by the parser (parseExtractionOutput's Array.isArray(value) branch) — hence the oneOf. This file is a HINT to codex, not the parser: extract-local.js's extractJsonValue + parseExtractionOutput remain the actual source of truth and are model-agnostic already. Keep this file in sync if that shape ever changes; a schema/parser drift fails soft (codex ignores an unmet hint, parseExtractionOutput still runs) rather than throwing.",
+  "oneOf": [
+    { "type": "array", "items": { "$ref": "#/definitions/learning" } },
+    {
+      "type": "object",
+      "properties": {
+        "learnings": { "type": "array", "items": { "$ref": "#/definitions/learning" } },
+        "dedup_drops": { "type": "array", "items": {} }
+      },
+      "required": ["learnings"]
+    }
+  ],
+  "definitions": {
+    "learning": {
+      "type": "object",
+      "properties": {
+        "title": { "type": "string", "minLength": 10 },
+        "body": { "type": "string", "minLength": 50 },
+        "category": {
+          "type": "string",
+          "enum": ["data-processing", "web-interaction", "code-execution", "storage-state", "payment-financial", "monitoring", "non-technical"]
+        },
+        "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 8 },
+        "task_context": { "type": "string" },
+        "outcome": { "type": "string", "enum": ["success", "partial", "failure", "workaround"] },
+        "quality_self_assessment": {
+          "type": "object",
+          "properties": {
+            "specificity": { "type": "integer", "minimum": 1, "maximum": 5 },
+            "actionability": { "type": "integer", "minimum": 1, "maximum": 5 },
+            "novelty": { "type": "integer", "minimum": 1, "maximum": 5 },
+            "completeness": { "type": "integer", "minimum": 1, "maximum": 5 },
+            "total": { "type": "integer" }
+          }
+        }
+      },
+      "required": ["title", "body", "category"]
+    }
+  }
+}

package/scripts/providers/schemas/judge-decisions.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$comment": "EXTRACT-PER-CLIENT W1 PART B — passed to `codex exec --output-schema` for mode:'judge'. Mirrors scripts/extract-local.js's parseJudgeDecisions (line 447): one decision object per candidate, keyed by candidate_index, matched_index_id only meaningful when duplicate:true. The 'required id must be inside the candidate's own top-K rankings list' rule and the 'exactly one decision per candidate, no duplicate indices' rule are enforced by parseJudgeDecisions itself, not expressible in JSON Schema — a schema-conformant response can still fail the parser. This file is a HINT to codex; parseJudgeDecisions remains the source of truth.",
+  "type": "object",
+  "properties": {
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "candidate_index": { "type": "integer", "minimum": 0 },
+          "duplicate": { "type": "boolean" },
+          "matched_index_id": { "type": "string" }
+        },
+        "required": ["candidate_index", "duplicate"]
+      }
+    }
+  },
+  "required": ["decisions"]
+}

package/scripts/runner.js

@@ -243,6 +243,12 @@ function zeroExtractionSkipState() {
     first_skip_at: null,
     last_skip_at: null,
     last_alert_at: null,
+    // EXTRACT-PER-CLIENT W1 PART C: the reasonCode of the most recent
+    // extraction outcome (skip or real), so `auxilo status` can print WHY
+    // (cli-billing-helper-configured / cli-unauthenticated /
+    // no-model-provider-available) without re-running extraction. null on a
+    // real full success (nothing to report) and on a fresh/zeroed state.
+    last_reason_code: null,
   };
 }
 
@@ -263,12 +269,17 @@ function normalizeExtractionSkipState(value) {
   for (const key of ['first_skip_at', 'last_skip_at', 'last_alert_at']) {
     if (!isCanonicalIsoTimestamp(value[key])) return null;
   }
+  // PART C: optional, back-compat with every state file written before this
+  // field existed — absent (old shape) normalizes to null, not a rejection.
+  const lastReasonCode = value.last_reason_code === undefined ? null : value.last_reason_code;
+  if (lastReasonCode !== null && typeof lastReasonCode !== 'string') return null;
   return {
     consecutive_skips: value.consecutive_skips,
     consecutive_unknown: consecutiveUnknown,
     first_skip_at: value.first_skip_at,
     last_skip_at: value.last_skip_at,
     last_alert_at: value.last_alert_at,
+    last_reason_code: lastReasonCode,
   };
 }
 
@@ -328,6 +339,19 @@ function resolveSkipAlertThreshold(value, env = process.env) {
   return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_SKIP_ALERT_THRESHOLD;
 }
 
+/**
+ * PART C: the reasonCode of the last row in this batch that carries one
+ * (rows are processed in order; postExtractDetailed sets reasonCode:null on
+ * a real success, per the shape at its two return sites above). Used only to
+ * populate last_reason_code for `auxilo status` — never affects streak logic.
+ */
+function latestReasonCode(rows) {
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    if (rows[i] && typeof rows[i].reasonCode === 'string') return rows[i].reasonCode;
+  }
+  return null;
+}
+
 async function finalizeExtractionRun(outcomes, opts = {}) {
   const rows = Array.isArray(outcomes) ? outcomes.filter(Boolean) : [];
   const state = opts.state
@@ -345,6 +369,7 @@ async function finalizeExtractionRun(outcomes, opts = {}) {
       // The streak resets, but alert delivery remains globally deduplicated
       // for 20h even if a real extraction lands between two skip streaks.
       last_alert_at: state.last_alert_at,
+      last_reason_code: latestReasonCode(rows),
     };
     persistExtractionSkipState(reset, opts);
     return reset;
@@ -360,6 +385,7 @@ async function finalizeExtractionRun(outcomes, opts = {}) {
       ...state,
       // R1: UNKNOWN never increments, resets, or alerts on the auth streak.
       consecutive_unknown: state.consecutive_unknown + 1,
+      last_reason_code: latestReasonCode(rows),
     };
     persistExtractionSkipState(unknown, opts);
     return unknown;
@@ -374,6 +400,7 @@ async function finalizeExtractionRun(outcomes, opts = {}) {
       : timestamp,
     last_skip_at: timestamp,
     last_alert_at: state.last_alert_at,
+    last_reason_code: latestReasonCode(rows),
   };
   const threshold = resolveSkipAlertThreshold(opts.threshold, opts.env || process.env);
   const lastAlertMs = next.last_alert_at ? Date.parse(next.last_alert_at) : NaN;
@@ -557,6 +584,10 @@ async function submitLearnings(learnings, sourceType, opts = {}) {
           submission_channel: 'extraction',
           ...(captureVisibility === 'private' && { visibility: 'private' }),
           ...(l.quality_self_assessment && { quality_self_assessment: l.quality_self_assessment }),
+          // EXTRACT-PER-CLIENT W1 PART C: which provider/model extracted this
+          // learning (extract-local.js attaches it per-learning; absent for
+          // pre-PART-C learnings and for the sourceless direct-submit paths).
+          ...(l.extraction_model && { extraction_model: l.extraction_model }),
         }),
       });
       if (!res.ok) { rejected += 1; continue; }
@@ -1511,6 +1542,7 @@ module.exports = {
   parseArgs, writeQueueFile, deleteQueueFile, listPendingFiles,
   loadLedger, saveLedger, ledgerHighWater, ledgerHas, ledgerMark,
   loadExtractionSkipState, saveExtractionSkipState, finalizeExtractionRun,
+  normalizeExtractionSkipState, zeroExtractionSkipState,
   isSkippedExtraction, recordRealExtractionCompletion, persistRealExtractionCompletion,
   renderExtractionStatus, renderExtractionResult,
   installHooks, installSweeper, installDigest, printStatus, scrubAndVerify, enumerateActiveSources,