@aiwayds/dsh-mcp-adapter 0.5.1 → 0.7.0

package/lib/jev/gate.js

@@ -0,0 +1,141 @@
+/**
+ * Outbound secret gate (design 2026-09-25 §3.3) — ported verbatim from
+ * dsh-topics-memory `src/jev/gate.ts`, a self-contained port of the
+ * dsh-jev-mcp `server.mjs` mechanism. The COMPLETE serialized request body
+ * (model, state, questions — byte-identical to what goes on the wire) is
+ * scanned for credential patterns BEFORE anything leaves the process; a hit
+ * aborts the call with a structured descriptor that never echoes the secret.
+ *
+ * SECURITY INVARIANT: hit descriptors carry static metadata only (pattern
+ * name, offset, ≤10 printable chars before the hit) — never the matched
+ * text, and never text at or after the hit point.
+ *
+ * @module jev/gate
+ */
+import { readFileSync, statSync } from 'node:fs';
+function safeWarn(log, message) {
+    try {
+        log?.warn?.(message);
+    }
+    catch {
+        // contained — diagnostics never take the feature down
+    }
+}
+// Prefix-style patterns require a 20+ char continuation so that merely
+// DISCUSSING a prefix (e.g. "set OPENROUTER_API_KEY to an sk-or-v1- key")
+// never trips the gate — only an actual long token does.
+export const BUILTIN_PATTERNS = [
+    { name: 'jwt', re: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+    { name: 'openrouter-key', re: /sk-or-v1-[A-Za-z0-9_-]{20,}/ },
+    { name: 'anthropic-key', re: /sk-ant-[A-Za-z0-9_-]{20,}/ },
+    { name: 'openai-project-key', re: /sk-proj-[A-Za-z0-9_-]{20,}/ },
+    { name: 'openai-sk-key', re: /sk-[A-Za-z0-9]{20,}/ },
+    { name: 'github-token', re: /ghp_[A-Za-z0-9]{20,}/ },
+    { name: 'github-pat', re: /github_pat_[A-Za-z0-9_]{20,}/ },
+    { name: 'gitlab-token', re: /glpat-[A-Za-z0-9_-]{20,}/ },
+    { name: 'slack-token', re: /xox[baprs]-[A-Za-z0-9-]{20,}/ },
+    { name: 'aws-access-key-id', re: /AKIA[0-9A-Z]{16}/ },
+    { name: 'aws-temp-key-id', re: /ASIA[0-9A-Z]{16}/ },
+    { name: 'google-api-key', re: /AIza[A-Za-z0-9_-]{20,}/ },
+    { name: 'private-key-block', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+];
+const MAX_SECRET_LINE = 512; // longer lines WARN; matching ALWAYS uses the full line
+const MIN_EXTERNAL_SECRET = 8; // shorter entries would cause runaway false hits
+/** Literal secrets from the external list file (JEV_SECRET_FILE semantics:
+ *  one entry per line, ≥8 chars, `#` comments skipped, matched at FULL
+ *  length — a >512-char line warns but is never truncated, or everything
+ *  past char 512 would silently escape the gate). */
+export function loadExternalSecrets(file, log) {
+    if (file === '')
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        safeWarn(log, `mcp-adapter jev: cannot read jevSecretFile (${file}): ${err instanceof Error ? err.message : String(err)}; continuing without it.`);
+        return [];
+    }
+    const secrets = [];
+    raw.split(/\r?\n/).forEach((line, i) => {
+        const s = line.trim();
+        if (s === '' || s.startsWith('#'))
+            return;
+        if (s.length < MIN_EXTERNAL_SECRET) {
+            safeWarn(log, `mcp-adapter jev: jevSecretFile line ${i + 1} shorter than ${MIN_EXTERNAL_SECRET} chars, skipped (false-positive guard).`);
+            return;
+        }
+        if (s.length > MAX_SECRET_LINE) {
+            safeWarn(log, `mcp-adapter jev: jevSecretFile line ${i + 1} is ${s.length} chars (> ${MAX_SECRET_LINE}); matching uses the FULL line (no truncation).`);
+        }
+        secrets.push(s);
+    });
+    return secrets;
+}
+// Cached external list, keyed by path, so the file is read once instead of on
+// every outbound payload. The `jevSecretFile` config is VOLATILE — an operator
+// can repoint it AND edit the file in place — and nothing in the plugin calls
+// reloadSecrets on a settings write, so a cache hit is validated against the
+// file's mtime+size (one stat, far cheaper than a re-read) before it is
+// served. Without that, adding a secret to the file by hand would not be gated
+// until the path changed or the process restarted.
+let cache = { file: '', secrets: [], stamp: '' };
+/** mtime+size of the list file, or '' when it cannot be stat'ed. */
+function fileStamp(file) {
+    if (file === '')
+        return '';
+    try {
+        const { mtimeMs, size } = statSync(file);
+        return `${mtimeMs}:${size}`;
+    }
+    catch {
+        return '';
+    }
+}
+export function currentSecrets(file, log) {
+    // A new path, or the same path whose file changed under us, re-reads.
+    if (cache.file !== file || cache.stamp !== fileStamp(file))
+        reloadSecrets(file, log);
+    return cache.secrets;
+}
+export function reloadSecrets(file, log) {
+    cache = { file, secrets: loadExternalSecrets(file, log), stamp: fileStamp(file) };
+    return cache.secrets;
+}
+/**
+ * Redacted context: at most 10 printable chars BEFORE the hit plus an
+ * explicit [REDACTED:<pattern>] marker. Content at or after the hit point is
+ * NEVER shown — when a prefix regex under-matches, the secret tail sits
+ * right there. Belt and suspenders: if the matched text or any known
+ * external secret still appears in the context, the whole context collapses
+ * to '[REDACTED]'.
+ */
+export function describeHit(pattern, offset, matched, payload, externalSecrets = []) {
+    const before = payload.slice(Math.max(0, offset - 10), offset).replace(/[^\x20-\x7e]/g, '.'); // keep it printable
+    const context = `${before}[REDACTED:${pattern}]`;
+    if (context.includes(matched) || externalSecrets.some((s) => s !== '' && context.includes(s))) {
+        return { pattern, offset, context: '[REDACTED]' };
+    }
+    return { pattern, offset, context };
+}
+/**
+ * Scan the serialized outbound payload for secrets.
+ * @param payload JSON.stringify({model, state, questions}) — the exact wire body
+ * @param externalSecrets literal secrets from the external list (cached via currentSecrets)
+ * @param externalSource label for hit descriptors (the list file path)
+ */
+export function scanForSecrets(payload, externalSecrets = [], externalSource = '') {
+    for (const { name, re } of BUILTIN_PATTERNS) {
+        const m = re.exec(payload);
+        if (m)
+            return describeHit(name, m.index, m[0], payload, externalSecrets);
+    }
+    for (const secret of externalSecrets) {
+        const idx = payload.indexOf(secret);
+        if (idx !== -1) {
+            return describeHit(externalSource !== '' ? `external(${externalSource})` : 'external', idx, secret, payload, externalSecrets);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=gate.js.map

package/lib/jev/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/jev/gate.ts"],"names":[],"mappings":"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"}

package/lib/jev/log.d.ts

@@ -0,0 +1,93 @@
+/**
+ * decisions.jsonl — System One usage/optimization telemetry (design
+ * 2026-09-25 §6), always on while jevEnabled is on. Ported from
+ * dsh-topics-memory `src/jev/log.ts` with ONE structural change: the
+ * destination directory is no longer resolved from an env/paths module
+ * inside the log, it is INJECTED by the caller
+ * ({@link createDecisionLog}). Everything else is carried over unchanged:
+ * 512KB auto-compaction keeping the most recent quarter, line JSON, and
+ * write failures swallowed silently — fail-open extends to the stats itself.
+ *
+ * The caller owns the directory; the plugin's own gate directory
+ * (`<dsh home>/storages/mcp-adapter`, see resolveGateDir in ../index.ts) is
+ * the intended one, so decisions.jsonl lands beside gate.json. Nothing here
+ * reads the dsh home, which keeps the module testable against a temp dir.
+ *
+ * REDACTION INVARIANT (§6.1): metadata and probabilities only — reference
+ * hash/question type/score/latency/token count. NEVER the state text or
+ * conclusion bodies. Writers copy an explicit field whitelist, so extra
+ * fields on caller objects cannot leak into the file.
+ *
+ * @module jev/log
+ */
+import type { JevBand } from './thresholds.ts';
+/** This plugin's three jev seams. A row must be attributable to exactly one
+ *  of them — the seam identity is what makes the usage/calibration analysis
+ *  separable per seam. */
+export type JevLane = 'usage-suggest' | 'list-rank' | 'didyoumean';
+export type JevOutcome = 'ok' | 'timeout' | 'network' | 'http_4xx' | 'http_5xx' | 'bad_json' | 'secret_gate_blocked' | 'missing_key'
+/** Local pre-flight refusal (e.g. questions violate the decisions/openrouter
+ *  wire contract) — nothing was sent. Reserved outcome beyond §6.2's v1 list. */
+ | 'invalid_request';
+export interface JevUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+/** Call layer (§6.2): one row per HTTP call, failures included — the
+ *  fallback rate is the health metric, so failed calls must be counted. */
+export interface JevCallRecord {
+    at: string;
+    lane: JevLane;
+    backend: string;
+    model: string;
+    questionCount: number;
+    stateChars: number;
+    latencyMs: number;
+    usage: JevUsage | null;
+    outcome: JevOutcome;
+    fallback: boolean;
+}
+/** Verdict layer (§6.2): one row per question, batch requests expanded. */
+export interface JevVerdictRecord {
+    at: string;
+    lane: JevLane;
+    questionId: string;
+    qtype: 'noul' | 'choice' | 'score';
+    /** Candidate reference without content: `tool:xxx` | `server:name`. */
+    ref: string;
+    /** §6.2 digest — stable key for the repeat-decision-rate analysis. */
+    digest: string;
+    probability: number;
+    band: JevBand;
+    agree: 'hit' | 'nearFloor' | 'gate-blocked' | 'wouldBlock' | 'n/a';
+    /** Which backend produced this verdict: 'primary' (default — the configured
+     *  backend) or 'laya' (the local pace-maker). Design §3.4. */
+    backend?: string;
+    /** True when this row's source DROVE the decision because the primary
+     *  backend was unavailable (degraded mode). Comparison rows from the
+     *  pace-maker are degraded=false; laya rows are excluded from ECE either
+     *  way (uncalibrated probabilities). */
+    degraded?: boolean;
+}
+/** The log file for one directory. The directory is created lazily on the
+ *  first append — `createDecisionLog` itself touches nothing on disk. */
+export declare function decisionsFile(logDir: string): string;
+/** digest(state, questionId, instructions): `h1:` + first 16 hex of
+ *  sha256(state + NUL + questionId + NUL + instructions) — the key the
+ *  repeat-decision-rate analysis joins on. */
+export declare function digestFor(state: string, questionId: string, instructions: string): string;
+/** One injected log handle. jevAsk takes this as a required argument so the
+ *  "row on EVERY path" invariant cannot be skipped by a caller. */
+export interface DecisionLog {
+    /** Absolute path this log appends to. */
+    file(): string;
+    /** Call-layer row (field whitelist enforced). */
+    logCall(rec: JevCallRecord): Promise<void>;
+    /** Verdict-layer rows (batch expanded by the caller). */
+    logVerdicts(recs: readonly JevVerdictRecord[]): Promise<void>;
+}
+/**
+ * Build a decisions.jsonl log over one directory. Cheap and side-effect
+ * free: build it once (apply time), keep the handle, pass it to jevAsk.
+ */
+export declare function createDecisionLog(logDir: string): DecisionLog;

package/lib/jev/log.js

@@ -0,0 +1,138 @@
+/**
+ * decisions.jsonl — System One usage/optimization telemetry (design
+ * 2026-09-25 §6), always on while jevEnabled is on. Ported from
+ * dsh-topics-memory `src/jev/log.ts` with ONE structural change: the
+ * destination directory is no longer resolved from an env/paths module
+ * inside the log, it is INJECTED by the caller
+ * ({@link createDecisionLog}). Everything else is carried over unchanged:
+ * 512KB auto-compaction keeping the most recent quarter, line JSON, and
+ * write failures swallowed silently — fail-open extends to the stats itself.
+ *
+ * The caller owns the directory; the plugin's own gate directory
+ * (`<dsh home>/storages/mcp-adapter`, see resolveGateDir in ../index.ts) is
+ * the intended one, so decisions.jsonl lands beside gate.json. Nothing here
+ * reads the dsh home, which keeps the module testable against a temp dir.
+ *
+ * REDACTION INVARIANT (§6.1): metadata and probabilities only — reference
+ * hash/question type/score/latency/token count. NEVER the state text or
+ * conclusion bodies. Writers copy an explicit field whitelist, so extra
+ * fields on caller objects cannot leak into the file.
+ *
+ * @module jev/log
+ */
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+const COMPACT_LIMIT = 512 * 1024; // ~512KB cap, same as the ilog sidecars
+/** The log file for one directory. The directory is created lazily on the
+ *  first append — `createDecisionLog` itself touches nothing on disk. */
+export function decisionsFile(logDir) {
+    return join(logDir, 'decisions.jsonl');
+}
+/** Digest field separator — a NUL byte, spelled this way so the source file
+ *  itself stays plain text (a raw NUL would make the file binary). */
+const NUL_SEP = String.fromCharCode(0);
+/** digest(state, questionId, instructions): `h1:` + first 16 hex of
+ *  sha256(state + NUL + questionId + NUL + instructions) — the key the
+ *  repeat-decision-rate analysis joins on. */
+export function digestFor(state, questionId, instructions) {
+    const h = createHash('sha256');
+    h.update(state);
+    h.update(NUL_SEP);
+    h.update(questionId);
+    h.update(NUL_SEP);
+    h.update(instructions);
+    return `h1:${h.digest('hex').slice(0, 16)}`;
+}
+/**
+ * Build a decisions.jsonl log over one directory. Cheap and side-effect
+ * free: build it once (apply time), keep the handle, pass it to jevAsk.
+ */
+export function createDecisionLog(logDir) {
+    const file = decisionsFile(logDir);
+    // Serialized like the store's write queue: single-record appends are
+    // line-atomic anyway, but the compaction rewrite must not interleave with
+    // an append. Per-log, so two logs never block each other.
+    let queue = Promise.resolve();
+    function enqueue(op) {
+        const run = queue.then(op, op);
+        queue = run.catch(() => undefined);
+        return run;
+    }
+    /** All write failures die HERE — never upstream. */
+    async function appendJsonl(lines) {
+        await enqueue(async () => {
+            try {
+                await mkdir(logDir, { recursive: true });
+                await appendFile(file, lines.map((l) => `${l}\n`).join(''), 'utf8');
+                await compactIfNeeded(file);
+            }
+            catch {
+                // fail-open: a broken stats sink must never break the feature (§6.1)
+            }
+        });
+    }
+    // ~512KB cap; keep the most recent quarter when exceeded (headroom for
+    // the next window).
+    async function compactIfNeeded(target) {
+        let raw;
+        try {
+            raw = await readFile(target, 'utf8');
+        }
+        catch {
+            return;
+        }
+        if (raw.length <= COMPACT_LIMIT)
+            return;
+        const lines = raw.split('\n').filter((l) => l.trim() !== '');
+        const keep = lines.slice(-Math.max(1, Math.floor(lines.length / 4)));
+        const tmp = `${target}.tmp-${randomUUID()}`;
+        try {
+            await writeFile(tmp, keep.map((l) => `${l}\n`).join(''), 'utf8');
+            await rename(tmp, target);
+        }
+        catch {
+            // swallow — the next append retries the compaction
+        }
+    }
+    /** Call-layer row. Field whitelist enforced here: anything extra on the
+     *  caller's object is dropped, so no state/conclusion text can sneak in. */
+    async function logCall(rec) {
+        await appendJsonl([
+            JSON.stringify({
+                at: rec.at,
+                lane: rec.lane,
+                backend: rec.backend,
+                model: rec.model,
+                questionCount: rec.questionCount,
+                stateChars: rec.stateChars,
+                latencyMs: rec.latencyMs,
+                usage: rec.usage === null
+                    ? null
+                    : { input_tokens: rec.usage.input_tokens, output_tokens: rec.usage.output_tokens },
+                outcome: rec.outcome,
+                fallback: rec.fallback,
+            }),
+        ]);
+    }
+    /** Verdict-layer rows (batch expanded by the caller). */
+    async function logVerdicts(recs) {
+        if (recs.length === 0)
+            return;
+        await appendJsonl(recs.map((rec) => JSON.stringify({
+            at: rec.at,
+            lane: rec.lane,
+            questionId: rec.questionId,
+            qtype: rec.qtype,
+            ref: rec.ref,
+            digest: rec.digest,
+            probability: rec.probability,
+            band: rec.band,
+            agree: rec.agree,
+            backend: rec.backend ?? 'primary',
+            degraded: rec.degraded === true,
+        })));
+    }
+    return { file: () => file, logCall, logVerdicts };
+}
+//# sourceMappingURL=log.js.map

package/lib/jev/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/jev/log.ts"],"names":[],"mappings":"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"}

package/lib/jev/seams.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The three System One seams (jev business wiring) — and ONLY these three
+ * places in the plugin may call out to a decision backend.
+ *
+ * WHERE THEY ARE ALLOWED TO RUN (red line ①, hot paths stay remote-free):
+ *  - {@link askKeepSuggestions} — the background keep-suggestion batch, fired
+ *    by the usage counter and awaited by nobody;
+ *  - {@link rankListQuery} — `mcp_list {query}` only, i.e. when the MODEL
+ *    explicitly asked for a ranked view;
+ *  - {@link rankDidYouMean} — `mcp_call`'s unknown-tool branch, i.e. an error
+ *    the model is going to read anyway.
+ *  The assemble waterfall, `mcp_list` without a query, and a SUCCESSFUL
+ *  dispatch never appear in this file's call graph.
+ *
+ * FAIL-OPEN (red line ②): every export returns a "no opinion" value on ANY
+ * failure — disabled, timeout, 5xx, bad JSON, a thrown hook, an unparseable
+ * answer. None of them throws. The caller's lexical order then stands, which
+ * is the pre-seam behavior; a jev outage is indistinguishable from jev being
+ * off.
+ *
+ * CALIBRATION: the batch in {@link askKeepSuggestions} is the one seam that
+ * reads a band (thresholds.ts, kind 'suggest') — and only as a DISPLAY label
+ * on a suggestion row, and only for a PRIMARY probability. The two ranking
+ * seams log their probabilities with band 'record': a rank is relative
+ * ordering, and adopting/vetoing thresholds ported from another plugin's
+ * protocol would be a category error. An laya probability is not calibrated at
+ * all (dual.ts: relative use only), so a pace-maker answer NEVER takes a band
+ * and NEVER becomes a suggestion row — see {@link askKeepSuggestions}.
+ *
+ * @module jev/seams
+ */
+import type { JevDualConfig } from './dual.ts';
+import type { DecisionLog } from './log.ts';
+import type { RankCandidate } from '../rank.ts';
+import type { SuggestCandidate, SuggestionRecord } from '../usage.ts';
+/**
+ * Everything a seam needs from the host, read PER CALL so a settings-page
+ * write takes effect on the next request (0.1.7 volatile config contract).
+ * Production builds one of these in apply() over the live config refs.
+ */
+export interface JevRuntime {
+    /** The master switch; false means "no call, and no failure". */
+    enabled(): boolean;
+    /** Resolved backend/model/timeout/secret/pace-maker settings. */
+    config(): JevDualConfig;
+    /** decisions.jsonl sink (createDecisionLog over the gate directory). */
+    log(): DecisionLog;
+}
+/** A tool as the ranking seams see it: a name plus a blurb for the criteria. */
+export type { RankCandidate } from '../rank.ts';
+/** A probability is usable only when it is a finite 0..1 number. */
+export declare function noulProbability(answer: unknown): number | undefined;
+/**
+ * Turn one jev ranking answer into an order. A full probability map sorts by
+ * probability descending (ties keep the lexical order); a bare `choice` field
+ * only moves the winner to the front; anything unparseable reports "no
+ * opinion" so the caller keeps the order it already had.
+ *
+ * @param candidates - the pool the question was asked about, in lexical order.
+ * @param answer - the raw answer value for {@link RANK_QUESTION_ID}.
+ * @returns the reordered names, or undefined for "no opinion".
+ */
+export declare function orderFromChoice(candidates: readonly RankCandidate[], answer: unknown): readonly string[] | undefined;
+/**
+ * Seam B: rerank `mcp_list {query}` candidates by relevance.
+ *
+ * The incoming order is the LEXICAL one (see ../rank.ts) and is also the
+ * fail-open result: any failure, disabled switch, or unusable answer returns
+ * `undefined`, which the caller reads as "keep what you had".
+ *
+ * A DEGRADED answer (the local laya pace-maker took over because the primary
+ * backend failed) is usable here: relative ordering is exactly what a rank
+ * is, and jev/dual.ts's contract allows degraded results for relative use
+ * only — which is all this seam does.
+ *
+ * @param query - the model's query text.
+ * @param ordered - lexical order (best first), already capped by the caller.
+ * @param env - the live jev runtime.
+ * @returns the jev order, or undefined for "no opinion".
+ */
+export declare function rankListQuery(query: string, ordered: readonly RankCandidate[], env: JevRuntime): Promise<readonly string[] | undefined>;
+/**
+ * Seam C: rerank the near-miss candidates of an unregistered tool name.
+ *
+ * Same fail-open contract as {@link rankListQuery}. Only runs when the lexical
+ * prefilter found MORE THAN ONE candidate — a single lexical hit needs no
+ * ranking, so the cold branch stays free when it has nothing to offer.
+ *
+ * @param tool - the name dispatch could not resolve.
+ * @param ordered - lexical near-miss order (best first).
+ * @param env - the live jev runtime.
+ * @returns the jev order, or undefined for "no opinion".
+ */
+export declare function rankDidYouMean(tool: string, ordered: readonly RankCandidate[], env: JevRuntime): Promise<readonly string[] | undefined>;
+/**
+ * Seam A: ask, in ONE batched noul request, whether each folded-and-used tool
+ * earns a permanent place in every prompt.
+ *
+ * Fire-and-forget by contract: the caller never awaits this on a hot path.
+ * `null` means "this round produced nothing" (disabled, call failed, no
+ * candidates, unusable answers, DEGRADED primary) — the caller then keeps the
+ * PREVIOUS batch in suggestions.json, and the usage record is unaffected
+ * either way.
+ *
+ * ABSOLUTE SCORES ONLY FROM THE PRIMARY: a suggestion row is a calibrated
+ * probability plus a band plus an actionable "keep it resident" line that a
+ * human reads in `/mcp suggest`. When the primary failed and the local laya
+ * pace-maker took over, that answer is usable for RELATIVE ranking only
+ * (dual.ts) and laya's negatives sit in the same band as its positives — so a
+ * degraded round returns `null` instead of rendering uncalibrated numbers. The
+ * answer is still logged (band 'record', degraded=true): the laya-vs-jev bench
+ * and the fallback-rate health metric must not lose a round.
+ *
+ * @param candidates - folded tools with recorded calls, most-used first.
+ * @param env - the live jev runtime.
+ * @returns one row per answered candidate, or null.
+ */
+export declare function askKeepSuggestions(candidates: readonly SuggestCandidate[], env: JevRuntime): Promise<SuggestionRecord[] | null>;