agentera 3.0.0-dev.72 → 3.0.0-dev.75

package/dist/analytics/personalGlossaryCandidateProjectionExcerpts.js

@@ -0,0 +1,144 @@
+import { containsGlossaryTerm } from "../registries/glossaryTermOccurrence.js";
+import { compareGlossaryUnicodeStrings } from "../registries/glossaryTermIdentity.js";
+const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u;
+const TOOL_ARGUMENTS_RE = /\b(?:tool[ _-]?arguments?|argv)\b/iu;
+const CONTROL_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/u;
+const PRIVATE_KEY_RE = /-----BEGIN(?: [A-Z]+)? PRIVATE KEY-----/u;
+const ASSIGNED_SENSITIVE_VALUE_RE = /(?:^|[^A-Za-z0-9_])["']?(?:api[_-]?key|access[_-]?token|password|passwd|cookie|private[_-]?key|authorization(?:[_-]?header)?|session(?:[_-]?id)?|email|phone|contact)["']?\s*[:=]\s*(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|([^\s,;}\]]+))/giu;
+const BEARER_VALUE_RE = /\bbearer\s+([A-Za-z0-9._~+/=-]{6,})/giu;
+const BARE_SESSION_VALUE_RE = /\bsession[-_]([A-Za-z0-9._~+/=-]{6,})\b/giu;
+const API_KEY_RE = /\b(?:sk|pk)_(?:live|test)_?[A-Za-z0-9_-]{8,}\b/u;
+const AWS_KEY_RE = /\bAKIA[0-9A-Z]{16}\b/u;
+const JWT_RE = /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/u;
+const EMAIL_RE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/iu;
+const PHONE_RE = /(?:\+?\d[\d .()-]{7,}\d)/u;
+const UNIX_PATH_RE = /(?:^|[\s("'`])(?:~\/|\/)(?:[^\s/]+\/)*[^\s/]+/u;
+const WINDOWS_PATH_RE = /\b[A-Za-z]:\\(?:[^\\\s]+\\)*[^\\\s]+/u;
+const SENSITIVE_CONTENT_PATTERNS = [
+    PRIVATE_KEY_RE,
+    API_KEY_RE,
+    AWS_KEY_RE,
+    JWT_RE,
+    EMAIL_RE,
+    PHONE_RE,
+    UNIX_PATH_RE,
+    WINDOWS_PATH_RE,
+];
+export const EXCERPT_OMISSION_REASONS = [
+    "no_excerpt",
+    "unrelated_context",
+    "source_bound_exceeded",
+    "unsafe_tool_arguments",
+    "unsafe_content",
+];
+function compareText(left, right) {
+    return compareGlossaryUnicodeStrings(left, right);
+}
+function validTimestamp(value) {
+    return typeof value === "string" && TIMESTAMP_RE.test(value) && !Number.isNaN(Date.parse(value));
+}
+export function personalGlossaryCandidateProjectionExcerptExpiry(retainedAt, pendingExcerptDays) {
+    return new Date(Date.parse(retainedAt) + pendingExcerptDays * 24 * 60 * 60 * 1000).toISOString();
+}
+function truncateUtf8(value, maximum) {
+    if (Buffer.byteLength(value, "utf8") <= maximum)
+        return { text: value, truncated: false };
+    let bytes = 0;
+    let text = "";
+    for (const scalar of value) {
+        const scalarBytes = Buffer.byteLength(scalar, "utf8");
+        if (bytes + scalarBytes > maximum)
+            break;
+        text += scalar;
+        bytes += scalarBytes;
+    }
+    return { text, truncated: true };
+}
+/** Classify secret or sensitive values without returning or transforming them. */
+export function containsPersonalGlossarySensitiveContent(value) {
+    if (SENSITIVE_CONTENT_PATTERNS.some((pattern) => pattern.test(value)))
+        return true;
+    for (const match of value.matchAll(ASSIGNED_SENSITIVE_VALUE_RE)) {
+        if (credentialShapedValue(match[1] ?? match[2] ?? match[3] ?? ""))
+            return true;
+    }
+    for (const match of value.matchAll(BEARER_VALUE_RE)) {
+        if (credentialShapedValue(match[1] ?? ""))
+            return true;
+    }
+    for (const match of value.matchAll(BARE_SESSION_VALUE_RE)) {
+        if (credentialShapedValue(match[1] ?? "", false))
+            return true;
+    }
+    return false;
+}
+function credentialShapedValue(value, allowLongLetters = true) {
+    const candidate = value.trim();
+    if (candidate.length === 0 || candidate === "[REDACTED]")
+        return false;
+    const scheme = /^(?:bearer|basic)\s+(.+)$/iu.exec(candidate);
+    if (scheme)
+        return credentialShapedValue(scheme[1] ?? "");
+    if (/\s/u.test(candidate))
+        return false;
+    return ((candidate.length >= 6 && /[A-Za-z]/u.test(candidate) && /\d/u.test(candidate)) ||
+        (candidate.length >= 8 && /[A-Za-z]/u.test(candidate) && /[-_.=+/]/u.test(candidate)) ||
+        (allowLongLetters && candidate.length >= 16 && /^[A-Za-z]+$/u.test(candidate)));
+}
+export function validPersonalGlossarySafeExcerpt(value) {
+    const excerpt = value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+    return (excerpt !== null &&
+        typeof excerpt === "object" &&
+        Object.keys(excerpt).length === 3 &&
+        ["expires_at", "redacted", "text"].every((key) => key in excerpt) &&
+        typeof excerpt.text === "string" &&
+        excerpt.text.length > 0 &&
+        Buffer.byteLength(excerpt.text, "utf8") <= 500 &&
+        !CONTROL_RE.test(excerpt.text) &&
+        !TOOL_ARGUMENTS_RE.test(excerpt.text) &&
+        !containsPersonalGlossarySensitiveContent(excerpt.text) &&
+        validTimestamp(excerpt.expires_at) &&
+        typeof excerpt.redacted === "boolean");
+}
+function safeExcerpt(source, term, retainedAt, contract) {
+    if (Buffer.byteLength(source, "utf8") > contract.sourceExcerptMaxUtf8Bytes) {
+        return { excerpt: null, omission: "source_bound_exceeded", provided: 1, truncated: false };
+    }
+    if (!containsGlossaryTerm(source, term)) {
+        return { excerpt: null, omission: "unrelated_context", provided: 1, truncated: false };
+    }
+    if (CONTROL_RE.test(source) || TOOL_ARGUMENTS_RE.test(source)) {
+        return { excerpt: null, omission: "unsafe_tool_arguments", provided: 1, truncated: false };
+    }
+    if (containsPersonalGlossarySensitiveContent(source)) {
+        return { excerpt: null, omission: "unsafe_content", provided: 1, truncated: false };
+    }
+    const bounded = truncateUtf8(source, 500);
+    if (bounded.text.length === 0) {
+        return { excerpt: null, omission: "unsafe_content", provided: 1, truncated: bounded.truncated };
+    }
+    const excerpt = {
+        text: bounded.text,
+        expires_at: personalGlossaryCandidateProjectionExcerptExpiry(retainedAt, contract.pendingExcerptDays),
+        redacted: false,
+    };
+    if (!validPersonalGlossarySafeExcerpt(excerpt)) {
+        return { excerpt: null, omission: "unsafe_content", provided: 1, truncated: bounded.truncated };
+    }
+    return { excerpt, omission: null, provided: 1, truncated: bounded.truncated };
+}
+export function selectPersonalGlossarySafeExcerpt(excerpts, term, retainedAt, contract) {
+    if (excerpts.size === 0) {
+        return { excerpt: null, omission: "no_excerpt", provided: 0, truncated: false };
+    }
+    let firstOmission = null;
+    for (const source of [...excerpts].sort(compareText)) {
+        const selected = safeExcerpt(source, term, retainedAt, contract);
+        if (selected.excerpt !== null)
+            return selected;
+        firstOmission ??= selected;
+    }
+    return firstOmission;
+}

package/dist/analytics/personalGlossaryCandidateReadView.js

@@ -0,0 +1,23 @@
+import { glossaryCanonicalSha256 } from "../registries/glossaryTermIdentity.js";
+/** Derive the expiry-aware candidate view without mutating its private projection. */
+export function currentPersonalGlossaryCandidateReadView(projection) {
+    const readTime = Date.now();
+    let expiredSafeContexts = 0;
+    const candidates = projection.candidates.map((candidate) => {
+        if (candidate.safe_excerpt !== null && Date.parse(candidate.safe_excerpt.expires_at) <= readTime) {
+            expiredSafeContexts += 1;
+            return { ...candidate, safe_excerpt: null };
+        }
+        return candidate;
+    });
+    const safeContextViewSha256 = glossaryCanonicalSha256({
+        schema_version: "agentera.personalGlossaryCandidateSafeContextView.v1",
+        candidates: candidates.map((candidate) => ({
+            candidate_id: candidate.capsule.candidate_id,
+            candidate_revision: candidate.capsule.candidate_revision,
+            capsule_sha256: candidate.capsule.capsule_sha256,
+            safe_context_available: candidate.safe_excerpt !== null,
+        })),
+    });
+    return { projection, candidates, expiredSafeContexts, safeContextViewSha256 };
+}

package/dist/analytics/personalGlossaryCurrentGeneration.js

@@ -0,0 +1,25 @@
+import { defaultTiersDir, readCurrentGeneration, } from "./extractCorpus/evidenceTiers.js";
+import { readPersonalGlossaryCandidateProjection, } from "./personalGlossaryCandidateProjection.js";
+/**
+ * Read the private candidate projection only when it is bound to the readable
+ * current evidence-tier generation. A projection from a prior generation is
+ * never a current candidate source.
+ */
+export function readCurrentPersonalGlossaryCandidateProjection(options = {}) {
+    const generation = readCurrentGeneration(options.tiersDir ?? defaultTiersDir(options.env, options.platform));
+    if (generation === null ||
+        generation.pointer.generation !== generation.manifest.generation) {
+        return { status: "current_generation_unavailable", projection: null };
+    }
+    const projection = readPersonalGlossaryCandidateProjection(options);
+    if (projection.status === "missing") {
+        return { status: "projection_missing", projection: null };
+    }
+    if (projection.status !== "current" || projection.projection === null) {
+        return { status: "projection_corrupt", projection: null };
+    }
+    if (projection.projection.generation !== generation.pointer.generation) {
+        return { status: "projection_stale", projection: null };
+    }
+    return { status: "current", projection: projection.projection };
+}

package/dist/analytics/personalGlossaryDecision.js

@@ -0,0 +1,203 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { runGlossaryEvaluationProcess } from "../eval/glossaryEvaluationProcess.js";
+import { validateGlossaryEvaluationSuccessReport } from "../eval/glossaryEvaluationSuccessReport.js";
+import { createGlossaryAdmissionDecision, validateGlossaryHostClassificationReceipt, } from "../registries/glossaryCandidateContracts.js";
+import { readCurrentPersonalGlossaryCandidateProjection, } from "./personalGlossaryCurrentGeneration.js";
+import { defaultTiersDir } from "./extractCorpus/evidenceTiers.js";
+import { mineExplicitGlossaryCandidates } from "./personalGlossaryExplicitMining.js";
+const QUALITY_GATE_CACHE_LIMIT = 16;
+const qualityGateCache = new Map();
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function result(status, reason, decision = null) {
+    return {
+        schemaVersion: "agentera.personalGlossaryAdmissionResult.v1",
+        command: "report personal-glossary-decision",
+        status,
+        decision,
+        reason,
+        effects: [],
+    };
+}
+function exactCandidate(candidates, receipt) {
+    const candidateId = receipt.candidate_id;
+    if (typeof candidateId !== "string")
+        return null;
+    const sameIdentity = candidates.filter((candidate) => candidate.capsule.candidate_id === candidateId);
+    const exact = sameIdentity.filter((candidate) => candidate.capsule.candidate_revision === receipt.candidate_revision &&
+        candidate.capsule.capsule_sha256 === receipt.candidate_capsule_sha256 &&
+        candidate.capsule.generation === receipt.generation &&
+        candidate.capsule.policy_version === receipt.policy_version);
+    if (exact.length === 1)
+        return exact[0];
+    return sameIdentity.length === 1 ? sameIdentity[0] : null;
+}
+function hasEntryConflict(candidates, capsule) {
+    return candidates.some(({ capsule: other }) => other.candidate_id === capsule.candidate_id &&
+        other.candidate_revision !== capsule.candidate_revision &&
+        (other.meaning !== capsule.meaning ||
+            other.scope !== capsule.scope ||
+            other.provenance_kind !== capsule.provenance_kind));
+}
+function currentExplicitEvidence(capsule, tiersDir, precomputed) {
+    const mined = precomputed ?? mineExplicitGlossaryCandidates({ tiersDir });
+    if (mined.state !== "current")
+        return "unavailable";
+    if (mined.generation !== capsule.generation)
+        return "changed";
+    if (mined.candidates.some(({ capsule: current }) => current.candidate_revision === capsule.candidate_revision &&
+        current.capsule_sha256 === capsule.capsule_sha256)) {
+        return "current";
+    }
+    if (mined.abstentions.some((item) => item.candidate_id === capsule.candidate_id &&
+        ["retracted_definition", "conflicting_meaning"].includes(item.reason))) {
+        return "retracted_or_conflicted";
+    }
+    return "changed";
+}
+function qualityGateFingerprint(sourceRoot) {
+    const digest = crypto.createHash("sha256");
+    try {
+        for (const relative of [
+            "references/analysis/personal-glossary-evaluation-authority.yaml",
+            "references/analysis/personal-glossary-holdout.yaml",
+            "references/analysis/personal-glossary-evaluation-corpus.yaml",
+            "references/analysis/evidence-tier-authority.yaml",
+            "references/artifacts/glossary-entry-contract.yaml",
+        ]) {
+            digest.update(relative).update("\0").update(fs.readFileSync(path.join(sourceRoot, relative))).update("\0");
+        }
+        return digest.digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+function qualityGate(sourceRoot) {
+    try {
+        const fingerprint = qualityGateFingerprint(sourceRoot);
+        const cached = fingerprint === null ? undefined : qualityGateCache.get(sourceRoot);
+        if (cached?.fingerprint === fingerprint)
+            return cached.status;
+        const evaluation = runGlossaryEvaluationProcess(sourceRoot);
+        const status = validateGlossaryEvaluationSuccessReport(evaluation, sourceRoot) !== null
+            ? "pass"
+            : "fail";
+        if (fingerprint !== null && status === "pass") {
+            qualityGateCache.set(sourceRoot, { fingerprint, status });
+            if (qualityGateCache.size > QUALITY_GATE_CACHE_LIMIT) {
+                qualityGateCache.delete(qualityGateCache.keys().next().value);
+            }
+        }
+        return status;
+    }
+    catch {
+        return "unavailable";
+    }
+}
+function decision(capsule, receipt, outcome, reason) {
+    try {
+        const value = createGlossaryAdmissionDecision({
+            capsule,
+            receipt: receipt,
+            outcome,
+            reason,
+        });
+        return result(outcome, reason, value);
+    }
+    catch {
+        return result("abstain", "decision_validation_failed");
+    }
+}
+/**
+ * Validate one untrusted host classification against current private evidence and
+ * derive its only permitted admission outcome. This function never persists a
+ * review, profile entry, projection, or project artifact.
+ */
+function decidePersonalGlossaryCandidateInternal(receiptInput, options, evaluationQualityGate, precomputedExplicitMining, precomputedCurrentProjection) {
+    let read = precomputedCurrentProjection;
+    if (read === undefined) {
+        try {
+            read = readCurrentPersonalGlossaryCandidateProjection(options);
+        }
+        catch {
+            return result("abstain", "projection_unavailable");
+        }
+    }
+    if (read.status !== "current" || read.projection === null) {
+        return result("abstain", read.status === "current_generation_unavailable"
+            ? "current_generation_unavailable"
+            : read.status === "projection_stale"
+                ? "projection_stale"
+                : "projection_unavailable");
+    }
+    const receipt = mapping(receiptInput);
+    if (!receipt)
+        return result("abstain", "receipt_invalid");
+    const selected = exactCandidate(read.projection.candidates, receipt);
+    if (!selected)
+        return result("abstain", "candidate_unavailable");
+    const capsule = selected.capsule;
+    const receiptErrors = validateGlossaryHostClassificationReceipt(receipt, capsule, {
+        candidateProjectionSha256: read.projection.projection_sha256,
+    });
+    if (receiptErrors.length > 0) {
+        return result("abstain", receiptErrors.includes("host_classification_receipt.candidate_projection_sha256 does not match the current projection")
+            ? "projection_changed"
+            : "receipt_invalid");
+    }
+    const classification = mapping(receipt.classification);
+    if (capsule.scope === "project" || classification.scope === "project") {
+        return decision(capsule, receipt, "abstain", "scope_project");
+    }
+    if (capsule.scope !== "personal" || classification.scope !== "personal") {
+        return decision(capsule, receipt, "review_required", "scope_ambiguous");
+    }
+    if (classification.consistency === "inconsistent") {
+        return decision(capsule, receipt, "review_required", "classification_inconsistent");
+    }
+    if (classification.consistency !== "consistent" ||
+        classification.term !== capsule.term ||
+        classification.meaning !== capsule.meaning) {
+        return decision(capsule, receipt, "review_required", "classification_changed");
+    }
+    if (hasEntryConflict(read.projection.candidates, capsule)) {
+        return decision(capsule, receipt, "review_required", "entry_conflict");
+    }
+    if (capsule.provenance_kind !== "personal_explicit_definition") {
+        return decision(capsule, receipt, "review_required", "inferred_requires_review");
+    }
+    const evidence = currentExplicitEvidence(capsule, options.tiersDir ?? defaultTiersDir(options.env, options.platform), precomputedExplicitMining);
+    if (evidence === "unavailable") {
+        return decision(capsule, receipt, "abstain", "evidence_unavailable");
+    }
+    if (evidence === "changed") {
+        return decision(capsule, receipt, "abstain", "evidence_changed");
+    }
+    if (evidence === "retracted_or_conflicted") {
+        return decision(capsule, receipt, "review_required", "evidence_retracted_or_conflicted");
+    }
+    const gate = evaluationQualityGate ? "pass" : qualityGate(options.sourceRoot ?? resolveSourceRoot());
+    if (gate !== "pass") {
+        return decision(capsule, receipt, "review_required", "quality_gate_not_authorizing");
+    }
+    return decision(capsule, receipt, "automatic_admission", "explicit_current_authorized");
+}
+/** Apply the release-authorizing quality report before an explicit admission. */
+export function decidePersonalGlossaryCandidate(receiptInput, options = {}) {
+    return decidePersonalGlossaryCandidateInternal(receiptInput, options, false);
+}
+/**
+ * Exercise the same bounded decision boundary while measuring the prerequisite
+ * explicit policy. This internal evaluator seam is never wired to CLI dispatch;
+ * inferred candidates still return review_required before the quality branch.
+ */
+export function evaluatePersonalGlossaryCandidate(receiptInput, options = {}, precomputedExplicitMining, precomputedCurrentProjection) {
+    return decidePersonalGlossaryCandidateInternal(receiptInput, options, true, precomputedExplicitMining, precomputedCurrentProjection);
+}