agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/state/startupAnalysis/contract.js

@@ -0,0 +1,160 @@
+import crypto from "node:crypto";
+export const TRANSCRIPT_KEYS = new Set([
+    "content",
+    "text",
+    "prompt",
+    "message",
+    "preceding_context",
+    "input_text",
+    "output_text",
+    "transcript",
+]);
+export const SESSION_KEYS = new Set(["session_id", "sessionID", "sessionId", "conversation_id"]);
+export const PATH_KEYS = new Set(["path", "project_path", "store_path", "file_path", "cwd", "report_path"]);
+const DEFAULT_CONTRACT = {
+    version: "startup-state-analysis-v1",
+    boundary: {
+        source: "git tag evidence",
+        commit: "b18e3dc7d768d4ad2726880916e7cfe6bd8617d3",
+        committed_at: "2026-05-12T17:50:13+02:00",
+    },
+    degradation_reasons: [
+        "pre_boundary_record",
+        "missing_timestamp",
+        "malformed_record",
+        "missing_conversation_key",
+        "no_agentera_state_sequence",
+        "privacy_redaction_required",
+    ],
+    privacy_boundary: {
+        canonical_artifact_labels: {
+            ".agentera/plan.yaml": "plan",
+            ".agentera/progress.yaml": "progress",
+            ".agentera/docs.yaml": "docs",
+            ".agentera/decisions.yaml": "decisions",
+            ".agentera/health.yaml": "health",
+            ".agentera/vision.yaml": "vision",
+            ".agentera/objective.yaml": "objective",
+            ".agentera/experiments.yaml": "experiments",
+            plan: "plan",
+            progress: "progress",
+            docs: "docs",
+            decisions: "decisions",
+            health: "health",
+            vision: "vision",
+            objective: "objective",
+            experiments: "experiments",
+            "AGENTS.md": "AGENTS.md",
+            "SKILL.md": "SKILL.md",
+        },
+    },
+};
+/** Legacy diagnostic label; startup analysis no longer loads a reference file. */
+export function contractPath() {
+    return "built-in:startup-state-analysis-v1";
+}
+/** Startup analysis is source-only compatibility code with fixed redaction defaults. */
+export function loadContract() {
+    return DEFAULT_CONTRACT;
+}
+export function hashLabel(kind, value, salt) {
+    if (!salt) {
+        throw new Error("salt is required for private labels");
+    }
+    const digest = crypto
+        .createHash("sha256")
+        .update(`${salt}\0${pyStr(value)}`, "utf8")
+        .digest("hex")
+        .slice(0, 16);
+    return `${kind}:${digest}`;
+}
+/** Approximate Python str() for the scalar/id values hashLabel receives. */
+function pyStr(value) {
+    if (value === null)
+        return "None";
+    if (value === undefined)
+        return "None";
+    if (value === true)
+        return "True";
+    if (value === false)
+        return "False";
+    return String(value);
+}
+const FALLBACK_ARTIFACT_LABELS = [
+    [".agentera/plan.yaml", "plan"],
+    [".agentera/progress.yaml", "progress"],
+    [".agentera/docs.yaml", "docs"],
+    [".agentera/decisions.yaml", "decisions"],
+    [".agentera/health.yaml", "health"],
+    [".agentera/vision.yaml", "vision"],
+    [".agentera/objective.yaml", "objective"],
+    [".agentera/experiments.yaml", "experiments"],
+];
+export function canonicalArtifactLabel(value, contract = null) {
+    const text = String(value).replace(/\\/g, "/");
+    const loaded = contract ?? loadContract();
+    const privacyBoundary = loaded.privacy_boundary && typeof loaded.privacy_boundary === "object" && !Array.isArray(loaded.privacy_boundary)
+        ? loaded.privacy_boundary
+        : {};
+    const labels = privacyBoundary.canonical_artifact_labels;
+    if (labels && typeof labels === "object" && !Array.isArray(labels)) {
+        for (const [suffix, label] of Object.entries(labels)) {
+            const normalized = String(suffix).replace(/\\/g, "/");
+            if (text === normalized || text.endsWith("/" + normalized) || text.includes(normalized)) {
+                return String(label);
+            }
+        }
+    }
+    for (const [suffix, label] of FALLBACK_ARTIFACT_LABELS) {
+        if (text === suffix || text.endsWith("/" + suffix) || text.includes(suffix)) {
+            return label;
+        }
+    }
+    if (text.includes(".agentera/")) {
+        return "AGENTERA_ARTIFACTS";
+    }
+    return null;
+}
+export function redactForStartupOutput(value, salt, contract = null) {
+    const loaded = contract ?? loadContract();
+    if (Array.isArray(value)) {
+        return value.map((item) => redactForStartupOutput(item, salt, loaded));
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const redacted = {};
+    for (const [key, item] of Object.entries(value)) {
+        const keyText = String(key);
+        if (TRANSCRIPT_KEYS.has(keyText)) {
+            redacted[keyText] = "<redacted:transcript_text>";
+        }
+        else if (SESSION_KEYS.has(keyText)) {
+            redacted[keyText] = hashLabel("session", item, salt);
+        }
+        else if (PATH_KEYS.has(keyText)) {
+            const label = canonicalArtifactLabel(item, loaded);
+            redacted[keyText] = label || hashLabel("path", item, salt);
+        }
+        else {
+            redacted[keyText] = redactForStartupOutput(item, salt, loaded);
+        }
+    }
+    return redacted;
+}
+// --- Timestamp helpers -----------------------------------------------------
+export function parseTimestamp(value) {
+    if (typeof value !== "string" || !value) {
+        return null;
+    }
+    const text = value.replace("Z", "+00:00");
+    const ms = Date.parse(text);
+    return Number.isNaN(ms) ? null : new Date(ms);
+}
+export function formatTimestamp(value) {
+    if (value === null) {
+        return null;
+    }
+    // ISO 8601 UTC, seconds precision (mirrors Python isoformat(timespec="seconds")).
+    return value.toISOString().replace(/\.\d{3}Z$/, "+00:00");
+}

package/dist/state/startupAnalysis/helpers.js

@@ -0,0 +1,286 @@
+import { pyJsonDumps as pyJsonDumpsCore, pyJsonString as pyJsonStringCore } from "../../core/pyjson.js";
+import { hashLabel } from "./contract.js";
+export const CLI_COMMAND_ARTIFACTS = {
+    plan: new Set(["plan"]),
+    progress: new Set(["progress"]),
+    health: new Set(["health"]),
+    todo: new Set(["todo"]),
+    decisions: new Set(["decisions"]),
+    docs: new Set(["docs"]),
+    objective: new Set(["objective"]),
+    experiments: new Set(["experiments"]),
+    status: new Set(["plan", "progress", "health", "todo", "docs", "decisions"]),
+    prime: new Set(["plan", "progress", "health", "todo", "docs", "decisions", "changelog"]),
+};
+export const QUERY_ARTIFACTS = {
+    plan: "plan",
+    progress: "progress",
+    health: "health",
+    todo: "todo",
+    decisions: "decisions",
+    docs: "docs",
+    vision: "vision",
+    objective: "objective",
+    experiments: "experiments",
+};
+const PRIMARY_ROUTE_TO_CAPABILITY = {
+    build: "build",
+    plan: "plan",
+    status: "status",
+    discuss: "discuss",
+    research: "research",
+    optimize: "optimize",
+    audit: "audit",
+    document: "document",
+    profile: "profile",
+    design: "design",
+    orchestrate: "orchestrate",
+    vision: "vision",
+};
+const CAPABILITIES_WITH_STATUS = new Set([...Object.values(PRIMARY_ROUTE_TO_CAPABILITY)]);
+const MARKER_RE = /─{2,}\s+(\S)\s+(status|vision|discuss|research|plan|build|optimize|audit|document|profile|design|orchestrate)\s+·\s+([a-z]+(?:\s+\d+)?)\s+─{2,}/g;
+const BARE_AGENTERA_ROUTE_RE = /^\s*\/agentera(?:\s+([A-Za-z0-9._:-]+))?/m;
+const BARE_CAPABILITY_ROUTE_RE = /^\s*\/(status|vision|discuss|research|plan|build|optimize|audit|document|profile|design|orchestrate)(?:\s|$)/m;
+const XML_ROUTE_RE = /<command-name>\s*\/(?:agentera\s+)?([A-Za-z0-9._:-]+)\s*<\/command-name>/;
+export const THRESHOLD_WARNING_PATTERNS = [
+    [
+        "self_audit",
+        "verbosity",
+        "self_audit.verbosity",
+        /verbosity(?: mismatch)?|exceeds(?: the)?(?: advisory| compact)?(?: prose| word| entry)? budget|\b\d+\s+words?\s+exceeds\s+\d+\s+budget\b|full plans? exceed/i,
+    ],
+    ["self_audit", "abstraction", "self_audit.abstraction", /abstraction creep/i],
+    ["self_audit", "filler", "self_audit.filler", /\bfiller\s*:/i],
+    ["compaction", "over_limit", "compaction.uniform_10_40_50", /over(?:\s+|_)limit|uniform_(?:10_40_50|20_50_100)/i],
+    ["compaction", "protected_overflow", "compaction.protected_overflow", /protected[-_ ]overflow/i],
+];
+export const POST_AUDIT_FLAG_RE = /\[post-audit-flagged(?::[^\]]*)?\]/gi;
+export const BUDGET_PRESSURE_RE = THRESHOLD_WARNING_PATTERNS[0][3];
+export const FULL_PLAN_BUDGET_RE = /full[- ]plan|full plans?|\bplan\b/i;
+const DETAIL_ANCHOR_RE = /`[^`]+`|\b(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\b|:\d{2,}\b|\b[0-9a-fA-F]{7,}\b/g;
+export function inc(counter, key) {
+    counter[key] = (counter[key] ?? 0) + 1;
+}
+export function counterDict(counter) {
+    const out = {};
+    for (const key of Object.keys(counter).sort())
+        out[key] = counter[key];
+    return out;
+}
+export function countMatches(re, text) {
+    const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
+    let n = 0;
+    while (g.exec(text) !== null)
+        n += 1;
+    return n;
+}
+export function wordCount(text) {
+    return (text.match(/\S+/g) ?? []).length;
+}
+let _fallbackIdSeq = 0;
+const _fallbackIds = new WeakMap();
+export function recordLabel(record, salt) {
+    let key = record.source_id;
+    if (key === null || key === undefined || key === "") {
+        let id = _fallbackIds.get(record);
+        if (id === undefined) {
+            id = ++_fallbackIdSeq;
+            _fallbackIds.set(record, id);
+        }
+        key = id;
+    }
+    return hashLabel("record", key, salt);
+}
+export function extractText(record) {
+    const data = record.data;
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+        const value = data.content || data.text || data.message || data.prompt;
+        return typeof value === "string" ? value : "";
+    }
+    return "";
+}
+export function toolArguments(record) {
+    const data = record.data;
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+        const args = data.arguments;
+        if (args && typeof args === "object" && !Array.isArray(args))
+            return args;
+        if (typeof args === "string") {
+            try {
+                const parsed = JSON.parse(args);
+                return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { value: parsed };
+            }
+            catch {
+                return { raw: args };
+            }
+        }
+        return data;
+    }
+    return record;
+}
+export function toolName(record) {
+    const data = record.data;
+    const values = [record.tool, record.tool_name, record.name];
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+        values.push(data.tool, data.tool_name, data.name);
+    }
+    for (const value of values) {
+        if (typeof value === "string" && value)
+            return value;
+    }
+    return "";
+}
+export function toolArgument(record, ...keys) {
+    const args = toolArguments(record);
+    const candidates = keys.map((k) => args[k]);
+    candidates.push(...keys.map((k) => record[k]));
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate)
+            return candidate;
+    }
+    return "";
+}
+export const pyJsonString = pyJsonStringCore;
+function startupJsonScalar(value) {
+    if (value instanceof Flt)
+        return formatFloat(value.v);
+    return undefined;
+}
+/** Mirror Python json.dumps(value, sort_keys=True) (separators ", "/": ", ensure_ascii). */
+export function pyJsonDumps(value) {
+    return pyJsonDumpsCore(value, startupJsonScalar);
+}
+export function argumentsText(record) {
+    return pyJsonDumps(toolArguments(record));
+}
+export function introCapability(text) {
+    const g = new RegExp(MARKER_RE.source, "g");
+    let m;
+    while ((m = g.exec(text)) !== null) {
+        const word = m[3];
+        if (!["complete", "flagged", "stuck", "waiting"].includes(word)) {
+            return m[2];
+        }
+    }
+    return null;
+}
+export function routeCapability(text) {
+    let m = XML_ROUTE_RE.exec(text);
+    if (m) {
+        const route = m[1].toLowerCase();
+        return CAPABILITIES_WITH_STATUS.has(route) ? route : (PRIMARY_ROUTE_TO_CAPABILITY[route] ?? null);
+    }
+    m = BARE_AGENTERA_ROUTE_RE.exec(text);
+    if (m) {
+        const route = (m[1] || "status").toLowerCase();
+        return CAPABILITIES_WITH_STATUS.has(route) ? route : (PRIMARY_ROUTE_TO_CAPABILITY[route] ?? null);
+    }
+    m = BARE_CAPABILITY_ROUTE_RE.exec(text);
+    if (m) {
+        return m[1].toLowerCase();
+    }
+    return null;
+}
+export function capabilityInvocation(text) {
+    const route = routeCapability(text);
+    if (route)
+        return route;
+    const marker = introCapability(text);
+    if (marker)
+        return marker;
+    const lowered = text.toLowerCase();
+    for (const capability of [...CAPABILITIES_WITH_STATUS].sort()) {
+        if (new RegExp(`\\b${capability.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(lowered)) {
+            return capability;
+        }
+    }
+    if (lowered.includes("agentera"))
+        return "agentera";
+    return null;
+}
+export function recordThresholdText(record) {
+    const parts = [extractText(record)];
+    if (record.source_kind === "tool_call")
+        parts.push(argumentsText(record));
+    return parts.filter((p) => p).join("\n");
+}
+export function detailMetrics(text) {
+    return { word_count: wordCount(text), anchor_count: countMatches(DETAIL_ANCHOR_RE, text) };
+}
+export function thresholdWarnings(text) {
+    const warnings = [];
+    const seen = new Set();
+    for (const [family, category, source, pattern] of THRESHOLD_WARNING_PATTERNS) {
+        if (pattern.test(text)) {
+            const key = `${family}\0${category}\0${source}`;
+            if (!seen.has(key)) {
+                warnings.push({ family, category, threshold_source: source });
+                seen.add(key);
+            }
+        }
+    }
+    return warnings;
+}
+export function detailLossStatus(before, after) {
+    if (before.word_count === 0 || after.word_count === 0)
+        return "not_assessed";
+    const wordDrop = after.word_count < before.word_count * 0.75;
+    const anchorDrop = after.anchor_count < before.anchor_count;
+    if (wordDrop && anchorDrop)
+        return "possible_useful_detail_removed";
+    if (wordDrop)
+        return "possible_compression_without_anchor_loss";
+    return "not_detected";
+}
+/** Python round() — round half to even on IEEE-754 doubles. */
+export function pyRound(x, ndigits) {
+    const m = 10 ** ndigits;
+    const v = x * m;
+    const f = Math.floor(v);
+    const diff = v - f;
+    let r;
+    if (diff > 0.5)
+        r = f + 1;
+    else if (diff < 0.5)
+        r = f;
+    else
+        r = f % 2 === 0 ? f : f + 1;
+    return r / m;
+}
+/** Python float marker: serializes with a trailing .0 for whole numbers. */
+export class Flt {
+    v;
+    constructor(v) {
+        this.v = v;
+    }
+    valueOf() {
+        return this.v;
+    }
+    toJSON() {
+        return this.v;
+    }
+}
+export function flt(n) {
+    return new Flt(n);
+}
+export function formatFloat(v) {
+    return Number.isInteger(v) ? `${v}.0` : String(v);
+}
+/** Python str()/f-string rendering for report scalars. */
+export function pyFmt(value) {
+    if (value instanceof Flt)
+        return formatFloat(value.v);
+    if (value === null || value === undefined)
+        return "None";
+    if (value === true)
+        return "True";
+    if (value === false)
+        return "False";
+    return String(value);
+}
+export function safeInt(value) {
+    return typeof value === "number" && Number.isInteger(value) ? value : 0;
+}
+export function nowIsoSeconds() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "+00:00");
+}

package/dist/state/startupAnalysis/index.js

@@ -0,0 +1,6 @@
+export { TRANSCRIPT_KEYS, SESSION_KEYS, PATH_KEYS, contractPath, loadContract, hashLabel, canonicalArtifactLabel, redactForStartupOutput, parseTimestamp, formatTimestamp, } from "./contract.js";
+export { THRESHOLD_EVIDENCE_ENVELOPE, THRESHOLD_CLASSIFICATION_ENVELOPE, STATE_EVENT_CLASSES, BOUNDARY_DEGRADATION_REASONS, BOUNDED_RUNTIME_STATUSES, BOUNDED_RUNTIME_REASONS, STATE_CLI_COMMANDS, classifyStartupEvent, boundedRuntimeStatus, startupConversationKey, scanThresholdEvidence, scanRetainedThresholdEvidence, classifyThresholdEvidence, } from "./threshold.js";
+export { classifyStartupRecords } from "./records.js";
+export { STARTUP_METRICS_ENVELOPE, TOKEN_ESTIMATOR_VERSION, aggregateStartupMetrics, } from "./metrics.js";
+export { STARTUP_REPORT_MARKDOWN, STARTUP_REPORT_JSON, renderStartupReport, writeStartupReports, } from "./report.js";
+export { STARTUP_INTERMEDIATE_ENVELOPE, BENCHMARK_HISTORY_JSONL, BENCHMARK_LATEST_REPORT_JSON, BENCHMARK_LATEST_REPORT_MARKDOWN, previousBenchmarkWatermark, buildBenchmarkHistoryRow, persistStartupBenchmark, buildStartupIntermediate, buildNoRuntimeStartupIntermediate, extractStartupIntermediateFromCorpusFile, } from "./benchmark.js";