@gracker/smartperfetto 1.0.13

package/dist/agentv3/selfImprove/skillNotesInjector.d.ts

@@ -0,0 +1,71 @@
+import { type PersistedSkillNote } from './skillNotesWriter';
+export type AnalysisPathMode = 'full' | 'quick' | 'retry';
+export declare const FULL_PATH_TOTAL_TOKENS = 1500;
+export declare const FULL_PATH_PER_SKILL_TOKENS = 200;
+export declare const QUICK_PATH_DEFAULT_TOTAL_TOKENS = 0;
+export declare const QUICK_PATH_MAX_TOTAL_TOKENS = 100;
+/**
+ * Conservative token estimator: 3 chars/token favours English; the budget
+ * intentionally errs short for Chinese which averages 1.5 char/token. The
+ * exact ratio doesn't matter as long as it's stable — we want to *under*
+ * inject when the agent is mid-context-pressure, not blow the budget.
+ */
+declare function estimateTokens(text: string): number;
+export interface BudgetSnapshot {
+    mode: AnalysisPathMode;
+    totalCap: number;
+    perSkillCap: number;
+    totalUsed: number;
+    injectedSkillIds: string[];
+    droppedReasons: {
+        skillId: string;
+        reason: string;
+    }[];
+}
+/**
+ * Per-analysis budget state. Construct once per `analyze()` call and pass
+ * the same instance to every invoke_skill so the running totals stay
+ * consistent.
+ */
+export declare class SkillNotesBudget {
+    private totalUsed;
+    private readonly injected;
+    private readonly dropped;
+    readonly mode: AnalysisPathMode;
+    readonly totalCap: number;
+    readonly perSkillCap: number;
+    constructor(opts: {
+        mode: AnalysisPathMode;
+        quickOverrideTotal?: number;
+    });
+    /**
+     * Best-effort note injection. Returns the rendered text + tokens consumed,
+     * or `null` if the budget rejected the request. Calling twice for the same
+     * `skillId` within the same analysis returns null on the second call (we
+     * don't want to inject the same notes twice).
+     */
+    tryConsume(skillId: string, candidates: ReadonlyArray<PersistedSkillNote>, now?: number): {
+        text: string;
+        tokensUsed: number;
+    } | null;
+    snapshot(): BudgetSnapshot;
+}
+declare function renderNote(note: PersistedSkillNote): string;
+export interface NoteSourceOptions {
+    /** Override for tests. */
+    runtimeDir?: string;
+    curatedDir?: string;
+}
+/**
+ * Load curated + runtime notes for a skill. Curated entries are listed first
+ * so they take precedence under tight budgets.
+ */
+export declare function loadSkillNotes(skillId: string, opts?: NoteSourceOptions): PersistedSkillNote[];
+export declare const __testing: {
+    estimateTokens: typeof estimateTokens;
+    renderNote: typeof renderNote;
+    DEFAULT_RUNTIME_NOTES_DIR: string;
+    DEFAULT_CURATED_NOTES_DIR: string;
+};
+export {};
+//# sourceMappingURL=skillNotesInjector.d.ts.map

package/dist/agentv3/selfImprove/skillNotesInjector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillNotesInjector.d.ts","sourceRoot":"","sources":["../../../src/agentv3/selfImprove/skillNotesInjector.ts"],"names":[],"mappings":"AA0BA,OAAO,EAA2C,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGtG,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1D,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,eAAO,MAAM,+BAA+B,IAAI,CAAC;AACjD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAK/C;;;;;GAKG;AACH,iBAAS,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACvD;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6C;IACrE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,IAAI,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE;IAezE;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,kBAAkB,CAAC,EAAE,GAAG,GAAE,MAAmB,GAAG;QACpG,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI;IAiDR,QAAQ,IAAI,cAAc;CAU3B;AAMD,iBAAS,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAQpD;AAED,MAAM,WAAW,iBAAiB;IAChC,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,iBAAsB,GAC3B,kBAAkB,EAAE,CAmBtB;AAED,eAAO,MAAM,SAAS;;;;;CAKrB,CAAC"}

package/dist/agentv3/selfImprove/skillNotesInjector.js

@@ -0,0 +1,214 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__testing = exports.SkillNotesBudget = exports.QUICK_PATH_MAX_TOTAL_TOKENS = exports.QUICK_PATH_DEFAULT_TOTAL_TOKENS = exports.FULL_PATH_PER_SKILL_TOKENS = exports.FULL_PATH_TOTAL_TOKENS = void 0;
+exports.loadSkillNotes = loadSkillNotes;
+/**
+ * Inject skill notes into invoke_skill responses, gated by a per-analysis
+ * token budget.
+ *
+ * Notes from `logs/skill_notes/<skillId>.notes.json` (runtime, written by the
+ * review worker) and `backend/skills/curated_skill_notes/<skillId>.notes.json`
+ * (curated baseline, promoted by humans + checked into git) get prepended to
+ * the invoke_skill text content. The agent reads them as context but the
+ * downstream JSON payload is unchanged.
+ *
+ * Budget rules per docs/architecture/self-improving-design.md §8:
+ *   full path:    1500 tokens total / 200 per skill / once per (analysis, skill)
+ *   quick path:   0 by default (env override SELF_IMPROVE_QUICK_NOTES_BUDGET ≤100)
+ *   correction retry: 0 — never injected
+ *
+ * Counted in estimated tokens (not bytes) because Chinese text averages ~1.5
+ * char/token while Latin averages ~3.3 char/token; a byte cap would silently
+ * overshoot Chinese-heavy notes.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const skillNotesWriter_1 = require("./skillNotesWriter");
+const runtimePaths_1 = require("../../runtimePaths");
+exports.FULL_PATH_TOTAL_TOKENS = 1500;
+exports.FULL_PATH_PER_SKILL_TOKENS = 200;
+exports.QUICK_PATH_DEFAULT_TOTAL_TOKENS = 0;
+exports.QUICK_PATH_MAX_TOTAL_TOKENS = 100;
+const DEFAULT_RUNTIME_NOTES_DIR = (0, runtimePaths_1.backendLogPath)('skill_notes');
+const DEFAULT_CURATED_NOTES_DIR = path.join(__dirname, '..', '..', '..', 'skills', 'curated_skill_notes');
+/**
+ * Conservative token estimator: 3 chars/token favours English; the budget
+ * intentionally errs short for Chinese which averages 1.5 char/token. The
+ * exact ratio doesn't matter as long as it's stable — we want to *under*
+ * inject when the agent is mid-context-pressure, not blow the budget.
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 3);
+}
+/**
+ * Per-analysis budget state. Construct once per `analyze()` call and pass
+ * the same instance to every invoke_skill so the running totals stay
+ * consistent.
+ */
+class SkillNotesBudget {
+    constructor(opts) {
+        this.totalUsed = 0;
+        this.injected = new Set();
+        this.dropped = [];
+        this.mode = opts.mode;
+        if (opts.mode === 'full') {
+            this.totalCap = exports.FULL_PATH_TOTAL_TOKENS;
+            this.perSkillCap = exports.FULL_PATH_PER_SKILL_TOKENS;
+        }
+        else if (opts.mode === 'quick') {
+            const requested = clampNonNegative(opts.quickOverrideTotal ?? exports.QUICK_PATH_DEFAULT_TOTAL_TOKENS);
+            this.totalCap = Math.min(requested, exports.QUICK_PATH_MAX_TOTAL_TOKENS);
+            this.perSkillCap = this.totalCap; // single-skill quick allowance
+        }
+        else {
+            this.totalCap = 0;
+            this.perSkillCap = 0;
+        }
+    }
+    /**
+     * Best-effort note injection. Returns the rendered text + tokens consumed,
+     * or `null` if the budget rejected the request. Calling twice for the same
+     * `skillId` within the same analysis returns null on the second call (we
+     * don't want to inject the same notes twice).
+     */
+    tryConsume(skillId, candidates, now = Date.now()) {
+        if (this.totalCap === 0) {
+            this.dropped.push({ skillId, reason: 'budget_disabled' });
+            return null;
+        }
+        if (this.injected.has(skillId)) {
+            this.dropped.push({ skillId, reason: 'already_injected_this_analysis' });
+            return null;
+        }
+        const remainingTotal = this.totalCap - this.totalUsed;
+        if (remainingTotal <= 0) {
+            this.dropped.push({ skillId, reason: 'total_budget_exhausted' });
+            return null;
+        }
+        const skillCeiling = Math.min(this.perSkillCap, remainingTotal);
+        const eligible = candidates
+            .filter(n => n.cooldownUntil <= now)
+            .sort((a, b) => b.createdAt - a.createdAt);
+        if (eligible.length === 0) {
+            this.dropped.push({ skillId, reason: 'no_eligible_notes' });
+            return null;
+        }
+        const lines = [];
+        let used = 0;
+        for (const note of eligible) {
+            const formatted = renderNote(note);
+            const cost = estimateTokens(formatted);
+            if (used + cost > skillCeiling)
+                break;
+            lines.push(formatted);
+            used += cost;
+        }
+        if (lines.length === 0) {
+            // If the per-skill ceiling was clipped by the remaining total budget,
+            // surface that as the more informative reason — it's why callers see
+            // injection drop off across an analysis.
+            const reason = skillCeiling < this.perSkillCap
+                ? 'total_budget_exhausted'
+                : 'first_note_exceeds_per_skill_cap';
+            this.dropped.push({ skillId, reason });
+            return null;
+        }
+        const text = `## Skill Notes (历史踩坑) — ${skillId}\n${lines.join('\n')}`;
+        this.totalUsed += used;
+        this.injected.add(skillId);
+        return { text, tokensUsed: used };
+    }
+    snapshot() {
+        return {
+            mode: this.mode,
+            totalCap: this.totalCap,
+            perSkillCap: this.perSkillCap,
+            totalUsed: this.totalUsed,
+            injectedSkillIds: Array.from(this.injected),
+            droppedReasons: [...this.dropped],
+        };
+    }
+}
+exports.SkillNotesBudget = SkillNotesBudget;
+function clampNonNegative(value) {
+    return Math.max(0, value);
+}
+function renderNote(note) {
+    const parts = [];
+    parts.push(`- [${note.failureCategory}] ${note.evidenceSummary}`);
+    if (note.candidateConstraints)
+        parts.push(`  → ${note.candidateConstraints}`);
+    if (note.candidateCriticalTools.length > 0) {
+        parts.push(`  tools: ${note.candidateCriticalTools.join(', ')}`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Load curated + runtime notes for a skill. Curated entries are listed first
+ * so they take precedence under tight budgets.
+ */
+function loadSkillNotes(skillId, opts = {}) {
+    const runtimeDir = opts.runtimeDir ?? DEFAULT_RUNTIME_NOTES_DIR;
+    const curatedDir = opts.curatedDir ?? DEFAULT_CURATED_NOTES_DIR;
+    const merged = [];
+    for (const dir of [curatedDir, runtimeDir]) {
+        if (!fs.existsSync(dir))
+            continue;
+        const file = path.join(dir, `${skillId}.notes.json`);
+        if (!fs.existsSync(file))
+            continue;
+        const parsed = (0, skillNotesWriter_1.readSkillNotesFile)(file);
+        merged.push(...parsed.notes);
+    }
+    // Dedupe by note id so a curated copy of the same note doesn't double up.
+    const seen = new Set();
+    return merged.filter(n => {
+        if (seen.has(n.id))
+            return false;
+        seen.add(n.id);
+        return true;
+    });
+}
+exports.__testing = {
+    estimateTokens,
+    renderNote,
+    DEFAULT_RUNTIME_NOTES_DIR,
+    DEFAULT_CURATED_NOTES_DIR,
+};
+//# sourceMappingURL=skillNotesInjector.js.map

package/dist/agentv3/selfImprove/skillNotesInjector.js.map

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

package/dist/agentv3/selfImprove/skillNotesWriter.d.ts

@@ -0,0 +1,89 @@
+import { type FailureCategory } from './failureTaxonomy';
+/** Strict JSON shape emitted by the review agent. Anything else is rejected. */
+export interface ReviewAgentNoteEmission {
+    failureCategoryEnum: FailureCategory;
+    evidenceSummary: string;
+    candidateKeywords?: string[];
+    candidateConstraints?: string;
+    candidateCriticalTools?: string[];
+    /** Optional self-supplied failureModeHash; backend recomputes regardless. */
+    failureModeHash?: string;
+    /** Skill that the note targets — required so the writer knows which file. */
+    skillId: string;
+    /** Provenance fields the writer copies into the persisted note. */
+    sourceSessionId?: string;
+    sourceTurnIndex?: number;
+}
+export interface PersistedSkillNote {
+    id: string;
+    failureCategory: FailureCategory;
+    failureModeHash?: string;
+    evidenceSummary: string;
+    candidateKeywords: string[];
+    candidateConstraints: string;
+    candidateCriticalTools: string[];
+    createdAt: number;
+    cooldownUntil: number;
+    byteSize: number;
+    sourceSessionId?: string;
+    sourceTurnIndex?: number;
+}
+export interface SkillNotesFile {
+    schemaVersion: 1;
+    skillId: string;
+    notes: PersistedSkillNote[];
+    lastUpdated: number;
+    totalBytes: number;
+}
+export type WriteOutcome = {
+    ok: true;
+    noteId: string;
+    filePath: string;
+    totalBytes: number;
+} | {
+    ok: false;
+    reason: WriteRejectReason;
+    details: string;
+};
+export type WriteRejectReason = 'invalid_schema' | 'unknown_category' | 'security_scan' | 'capacity_exceeded' | 'invalid_skill_id' | 'io_error';
+export interface WriteOptions {
+    /** Override notes directory — primarily for tests. */
+    notesDir?: string;
+    /** Override `Date.now()` for deterministic tests. */
+    now?: number;
+    /** Optional registry of valid tool/skill IDs; criticalTools are validated against it when supplied. */
+    toolRegistry?: ReadonlySet<string>;
+}
+/**
+ * Validate the agent emission against the schema. Truncates over-long fields
+ * rather than failing on them — matches the validation style elsewhere in
+ * selfImprove. Returns a normalized emission ready to be persisted.
+ */
+export declare function validateEmission(raw: unknown, toolRegistry?: ReadonlySet<string>): {
+    ok: true;
+    value: ReviewAgentNoteEmission;
+} | {
+    ok: false;
+    reason: WriteRejectReason;
+    details: string;
+};
+/**
+ * Run security scanner across the emission's free-form text. Returns the
+ * matches if any are found so the caller can log the offending excerpt.
+ */
+export declare function scanEmission(emission: ReviewAgentNoteEmission): string | null;
+/**
+ * Atomically write a new note to `<notesDir>/<skillId>.notes.json`. The full
+ * pipeline runs here: schema validation → security scan → capacity check →
+ * tmp+rename write. Returns a structured outcome so the worker can log a
+ * reason without throwing.
+ */
+export declare function writeSkillNote(raw: unknown, opts?: WriteOptions): WriteOutcome;
+export declare function readSkillNotesFile(filePath: string): SkillNotesFile;
+export declare const __testing: {
+    MAX_NOTE_BYTES: number;
+    MAX_FILE_BYTES: number;
+    NOTE_COOLDOWN_MS: number;
+    SKILL_ID_RE: RegExp;
+};
+//# sourceMappingURL=skillNotesWriter.d.ts.map

package/dist/agentv3/selfImprove/skillNotesWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillNotesWriter.d.ts","sourceRoot":"","sources":["../../../src/agentv3/selfImprove/skillNotesWriter.ts"],"names":[],"mappings":"AAsBA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAG3B,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC,mBAAmB,EAAE,eAAe,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,eAAe,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,mBAAmB,GACnB,kBAAkB,GAClB,UAAU,CAAC;AAef,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACjC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,uBAAuB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA2D1G;AAcD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,GAAG,IAAI,CAY7E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,YAAiB,GAAG,YAAY,CAwFlF;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAWnE;AAED,eAAO,MAAM,SAAS;;;;;CAKrB,CAAC"}

package/dist/agentv3/selfImprove/skillNotesWriter.js

@@ -0,0 +1,274 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__testing = void 0;
+exports.validateEmission = validateEmission;
+exports.scanEmission = scanEmission;
+exports.writeSkillNote = writeSkillNote;
+exports.readSkillNotesFile = readSkillNotesFile;
+/**
+ * Validate, scan, and persist skill notes emitted by the review agent.
+ *
+ * The review agent only ever emits strict JSON — never writes files itself —
+ * so the pipeline here is the trust boundary. Anything that fails schema,
+ * security scan, or capacity gating is dropped with a logged reason; the
+ * review job is still marked done because the failure is the agent's, not
+ * a transient one we want to retry forever.
+ *
+ * Writes are atomic (tmp + rename) so a partial write never leaves a
+ * corrupt notes file that breaks the next invoke_skill injection.
+ *
+ * See docs/architecture/self-improving-design.md §9 (Trust Boundary), §13.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtimePaths_1 = require("../../runtimePaths");
+const failureTaxonomy_1 = require("./failureTaxonomy");
+const contentScanner_1 = require("./contentScanner");
+/** Match the worktreeRunner whitelist style — keeps file names safe. */
+const SKILL_ID_RE = /^[a-zA-Z0-9_]{1,80}$/;
+const MAX_EVIDENCE_CHARS = 600;
+const MAX_CONSTRAINTS_CHARS = 400;
+const MAX_KEYWORDS = 6;
+const MAX_KEYWORD_CHARS = 40;
+const MAX_TOOLS = 6;
+const MAX_TOOL_CHARS = 80;
+const MAX_NOTE_BYTES = 4 * 1024;
+const MAX_FILE_BYTES = 16 * 1024;
+const NOTE_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_NOTES_DIR = (0, runtimePaths_1.backendLogPath)('skill_notes');
+/**
+ * Validate the agent emission against the schema. Truncates over-long fields
+ * rather than failing on them — matches the validation style elsewhere in
+ * selfImprove. Returns a normalized emission ready to be persisted.
+ */
+function validateEmission(raw, toolRegistry) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, reason: 'invalid_schema', details: 'emission must be a JSON object' };
+    }
+    const r = raw;
+    if (typeof r.skillId !== 'string' || !SKILL_ID_RE.test(r.skillId)) {
+        return { ok: false, reason: 'invalid_skill_id', details: `skillId must match ${SKILL_ID_RE.source}` };
+    }
+    if (!(0, failureTaxonomy_1.isKnownCategory)(r.failureCategoryEnum)) {
+        return {
+            ok: false,
+            reason: 'unknown_category',
+            details: `failureCategoryEnum must be a known FailureCategory (got ${String(r.failureCategoryEnum)})`,
+        };
+    }
+    if (typeof r.evidenceSummary !== 'string' || r.evidenceSummary.trim().length === 0) {
+        return { ok: false, reason: 'invalid_schema', details: 'evidenceSummary must be a non-empty string' };
+    }
+    const keywords = normalizeStringArray(r.candidateKeywords, MAX_KEYWORDS, MAX_KEYWORD_CHARS);
+    if (keywords === 'invalid') {
+        return { ok: false, reason: 'invalid_schema', details: 'candidateKeywords must be an array of strings' };
+    }
+    const constraints = typeof r.candidateConstraints === 'string'
+        ? r.candidateConstraints.substring(0, MAX_CONSTRAINTS_CHARS)
+        : '';
+    const tools = normalizeStringArray(r.candidateCriticalTools, MAX_TOOLS, MAX_TOOL_CHARS);
+    if (tools === 'invalid') {
+        return { ok: false, reason: 'invalid_schema', details: 'candidateCriticalTools must be an array of strings' };
+    }
+    if (toolRegistry && tools.length > 0) {
+        const unknownTool = tools.find(t => !toolRegistry.has(t));
+        if (unknownTool) {
+            return {
+                ok: false,
+                reason: 'invalid_schema',
+                details: `candidateCriticalTools includes unknown tool/skill: ${unknownTool}`,
+            };
+        }
+    }
+    const value = {
+        failureCategoryEnum: r.failureCategoryEnum,
+        evidenceSummary: r.evidenceSummary.substring(0, MAX_EVIDENCE_CHARS),
+        candidateKeywords: keywords,
+        candidateConstraints: constraints,
+        candidateCriticalTools: tools,
+        skillId: r.skillId,
+        failureModeHash: typeof r.failureModeHash === 'string' ? r.failureModeHash : undefined,
+        sourceSessionId: typeof r.sourceSessionId === 'string' ? r.sourceSessionId : undefined,
+        sourceTurnIndex: typeof r.sourceTurnIndex === 'number' ? r.sourceTurnIndex : undefined,
+    };
+    return { ok: true, value };
+}
+function normalizeStringArray(input, maxLen, maxItemChars) {
+    if (input === undefined)
+        return [];
+    if (!Array.isArray(input))
+        return 'invalid';
+    const out = [];
+    for (const item of input) {
+        if (typeof item !== 'string')
+            return 'invalid';
+        out.push(item.substring(0, maxItemChars));
+        if (out.length >= maxLen)
+            break;
+    }
+    return out;
+}
+/**
+ * Run security scanner across the emission's free-form text. Returns the
+ * matches if any are found so the caller can log the offending excerpt.
+ */
+function scanEmission(emission) {
+    const surfaces = [
+        emission.evidenceSummary,
+        emission.candidateConstraints || '',
+        ...(emission.candidateKeywords || []),
+        ...(emission.candidateCriticalTools || []),
+    ];
+    for (const text of surfaces) {
+        const matches = (0, contentScanner_1.scanContent)(text);
+        if (matches.length > 0)
+            return (0, contentScanner_1.formatThreats)(matches);
+    }
+    return null;
+}
+/**
+ * Atomically write a new note to `<notesDir>/<skillId>.notes.json`. The full
+ * pipeline runs here: schema validation → security scan → capacity check →
+ * tmp+rename write. Returns a structured outcome so the worker can log a
+ * reason without throwing.
+ */
+function writeSkillNote(raw, opts = {}) {
+    const validation = validateEmission(raw, opts.toolRegistry);
+    if (!validation.ok)
+        return { ok: false, reason: validation.reason, details: validation.details };
+    const emission = validation.value;
+    const threats = scanEmission(emission);
+    if (threats) {
+        return { ok: false, reason: 'security_scan', details: threats };
+    }
+    const now = opts.now ?? Date.now();
+    const note = {
+        id: `note-${now}-${Math.random().toString(36).substring(2, 8)}`,
+        failureCategory: emission.failureCategoryEnum,
+        failureModeHash: emission.failureModeHash,
+        evidenceSummary: emission.evidenceSummary,
+        candidateKeywords: emission.candidateKeywords ?? [],
+        candidateConstraints: emission.candidateConstraints ?? '',
+        candidateCriticalTools: emission.candidateCriticalTools ?? [],
+        createdAt: now,
+        cooldownUntil: now + NOTE_COOLDOWN_MS,
+        byteSize: 0,
+        sourceSessionId: emission.sourceSessionId,
+        sourceTurnIndex: emission.sourceTurnIndex,
+    };
+    note.byteSize = Buffer.byteLength(JSON.stringify(note), 'utf-8');
+    if (note.byteSize > MAX_NOTE_BYTES) {
+        return { ok: false, reason: 'capacity_exceeded', details: `note=${note.byteSize}B > ${MAX_NOTE_BYTES}B` };
+    }
+    const dir = opts.notesDir ?? DEFAULT_NOTES_DIR;
+    const filePath = path.join(dir, `${emission.skillId}.notes.json`);
+    try {
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        return { ok: false, reason: 'io_error', details: err.message };
+    }
+    const existing = readSkillNotesFile(filePath);
+    const existingFromSameSource = note.sourceSessionId && note.sourceTurnIndex !== undefined
+        ? existing.notes.find(n => n.sourceSessionId === note.sourceSessionId
+            && n.sourceTurnIndex === note.sourceTurnIndex
+            && n.failureModeHash === note.failureModeHash)
+        : undefined;
+    if (existingFromSameSource) {
+        // Same provenance + failure-mode is a duplicate emission (the worker
+        // retried, or the agent looped). Keep the original to preserve audit.
+        return {
+            ok: true,
+            noteId: existingFromSameSource.id,
+            filePath,
+            totalBytes: existing.totalBytes,
+        };
+    }
+    const merged = {
+        schemaVersion: 1,
+        skillId: emission.skillId,
+        notes: [...existing.notes, note],
+        lastUpdated: now,
+        totalBytes: 0,
+    };
+    // Drop oldest notes until the file fits the cap. Newer notes are more
+    // valuable than older ones for cross-arch drift like Flutter Impeller.
+    while (true) {
+        const serialized = JSON.stringify(merged, null, 2);
+        const totalBytes = Buffer.byteLength(serialized, 'utf-8');
+        merged.totalBytes = totalBytes;
+        if (totalBytes <= MAX_FILE_BYTES)
+            break;
+        if (merged.notes.length <= 1) {
+            return { ok: false, reason: 'capacity_exceeded', details: `single note exceeds file cap (${totalBytes}B)` };
+        }
+        merged.notes.shift();
+    }
+    try {
+        const tmp = `${filePath}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(merged, null, 2));
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        return { ok: false, reason: 'io_error', details: err.message };
+    }
+    return { ok: true, noteId: note.id, filePath, totalBytes: merged.totalBytes };
+}
+function readSkillNotesFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return { schemaVersion: 1, skillId: path.basename(filePath, '.notes.json'), notes: [], lastUpdated: 0, totalBytes: 0 };
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (parsed && Array.isArray(parsed.notes))
+            return parsed;
+    }
+    catch (err) {
+        console.warn('[skillNotesWriter] failed to parse', filePath, err.message);
+    }
+    return { schemaVersion: 1, skillId: path.basename(filePath, '.notes.json'), notes: [], lastUpdated: 0, totalBytes: 0 };
+}
+exports.__testing = {
+    MAX_NOTE_BYTES,
+    MAX_FILE_BYTES,
+    NOTE_COOLDOWN_MS,
+    SKILL_ID_RE,
+};
+//# sourceMappingURL=skillNotesWriter.js.map