@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/agent/learning/skill-background-writes.js

@@ -0,0 +1,270 @@
+/**
+ * Closed-learning-loop background SKILL writes (Hermes parity — opt-in, OFF by default).
+ *
+ * This is the skill-side companion to `learning-background-writes.ts` (which
+ * auto-writes user-model OBSERVATIONS). Hermes' background review writes skills
+ * DIRECTLY with no human gate. Code Buddy matches that autonomy while keeping a
+ * reversible objective net that Hermes does not have:
+ *
+ *   1. OFF BY DEFAULT. Without `CODEBUDDY_LEARNING_BACKGROUND_WRITE_SKILLS=true`
+ *      (which itself requires `CODEBUDDY_LEARNING_BACKGROUND_WRITES=true`), this
+ *      is a no-op and skill candidates stay in the human review queue.
+ *   2. SENTINEL APPROVER. Auto-installs route through the SAME
+ *      `installResearchScriptSkillCandidate(...)` path used by human review,
+ *      stamped with a non-human reviewer sentinel (`auto:gate-passed`) so the
+ *      provenance is auditable and distinguishable from human approval.
+ *   3. CONTENT SCREEN. A secret/omission screen (shared with the empirical gate)
+ *      runs before any write, fail-closed.
+ *   4. OBJECTIVE GATE (optional, see S3). When a behavioural gate is supplied it
+ *      must accept before install; an inert/regressing skill is left pending.
+ *   5. REVERSIBILITY + AUDIT. Installs are recorded in an auditable side-car
+ *      (`.codebuddy/learning/skill-writes.json`) and remain reversible through
+ *      SkillsHub (new skill → uninstall; existing-skill patch → snapshot rollback).
+ */
+import fs from 'fs';
+import path from 'path';
+import { logger } from '../../utils/logger.js';
+import { getBackgroundWritePolicy } from '../learning-background-writes.js';
+import { OMISSION_RE, SECRET_RE } from '../self-improvement/empirical-gate.js';
+import { installResearchScriptSkillCandidate, } from '../research-script-skill-candidate.js';
+/** Reviewer sentinel stamped on every gate-passed background skill install. */
+export const SKILL_BACKGROUND_WRITE_REVIEWER = 'auto:gate-passed';
+export const SKILL_WRITE_AUDIT_SCHEMA_VERSION = 1;
+const AUDIT_DIR = path.join('.codebuddy', 'learning');
+const AUDIT_FILE = 'skill-writes.json';
+const TRUTHY = new Set(['1', 'true', 'on', 'yes', 'enabled']);
+/**
+ * Whether autonomous (no-review) skill writes are enabled. Gates the LIVE
+ * background-review skill mutations, mirroring the S1 promotion-path flag.
+ */
+export function isBackgroundSkillWriteEnabled() {
+    return TRUTHY.has((process.env.CODEBUDDY_LEARNING_BACKGROUND_WRITE_SKILLS ?? '').trim().toLowerCase());
+}
+/**
+ * Promote a single materialized skill candidate to an installed workspace skill
+ * in the background, WITHOUT human review — gated by the opt-in flag, a content
+ * screen, and (when supplied) a behavioural gate. Always a no-op when the flag
+ * is OFF, so callers can invoke it unconditionally.
+ */
+export async function promoteSkillCandidate(candidate, options = {}) {
+    const workDir = options.workDir ?? process.cwd();
+    const skillName = candidate.skillName;
+    const policy = getBackgroundWritePolicy();
+    if (!policy.enabled || !policy.allowSkillWrites) {
+        return { installed: false, reason: 'background skill writes disabled', skillName };
+    }
+    if (!candidate.eligible) {
+        return { installed: false, reason: candidate.reason || 'candidate not eligible', skillName };
+    }
+    // Reversibility guard: the candidate path (installFromContent) does NOT snapshot.
+    // If a skill of this name is already installed, refuse to clobber it here and
+    // direct the change through the snapshotting edit/patch primitives instead, so
+    // every background mutation of an existing skill stays roll-back-able.
+    if (!options.overwrite && isSkillInstalled(workDir, skillName)) {
+        return {
+            installed: false,
+            reason: 'skill already installed; background patches must go through snapshotting edit/patch',
+            skillName,
+        };
+    }
+    const screenProblem = screenSkillContent(candidate.markdown);
+    if (screenProblem) {
+        logger.warn('[skill-background-writes] candidate refused by content screen; left pending', {
+            skillName,
+            reason: screenProblem,
+        });
+        return { installed: false, reason: screenProblem, skillName };
+    }
+    if (options.gate) {
+        const verdict = await options.gate(candidate);
+        if (verdict.decision === 'reject') {
+            logger.info('[skill-background-writes] behavioural gate rejected candidate; left pending', {
+                skillName,
+                reason: verdict.reason,
+            });
+            return { installed: false, reason: verdict.reason, skillName };
+        }
+        // 'accept' and 'abstain' both proceed: 'accept' is behaviourally validated;
+        // 'abstain' falls back to the structural/secret/reversibility nets.
+    }
+    let installed;
+    try {
+        installed = await installResearchScriptSkillCandidate(candidate, {
+            approvedBy: SKILL_BACKGROUND_WRITE_REVIEWER,
+            overwrite: options.overwrite ?? false,
+            rootDir: workDir,
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.warn('[skill-background-writes] auto-install failed; left pending', { skillName, reason });
+        return { installed: false, reason, skillName };
+    }
+    recordSkillWriteAudit(workDir, {
+        candidateId: candidate.id,
+        installedPath: installed.installedPath,
+        reviewer: SKILL_BACKGROUND_WRITE_REVIEWER,
+        rollbackPlan: buildSkillWriteRollbackPlan({
+            action: 'create',
+            skillName,
+        }),
+        skillName,
+        sourceCandidatePath: installed.sourceCandidatePath,
+        writtenAt: new Date().toISOString(),
+    });
+    logger.info('[skill-background-writes] auto-installed skill from background review', {
+        skillName,
+        installedPath: installed.installedPath,
+    });
+    return {
+        installed: true,
+        reason: 'installed',
+        skillName,
+        installedPath: installed.installedPath,
+    };
+}
+/** True when a workspace skill of this name already has an installed SKILL.md. */
+function isSkillInstalled(workDir, skillName) {
+    const installedPath = path.join(path.resolve(workDir), '.codebuddy', 'skills', skillName, 'SKILL.md');
+    return fs.existsSync(installedPath);
+}
+/** Secret/omission screen with no length constraint (for memory + arbitrary writes). */
+export function screenContentForSecrets(content) {
+    const text = content ?? '';
+    if (OMISSION_RE.test(text))
+        return 'content contains an omission placeholder';
+    if (SECRET_RE.test(text))
+        return 'content looks like it contains a secret';
+    return null;
+}
+/** Returns a problem string if the skill markdown must not be auto-written, else null. */
+export function screenSkillContent(markdown) {
+    const content = markdown?.trim() ?? '';
+    if (content.length < 12)
+        return 'skill content too short to be useful';
+    return screenContentForSecrets(content);
+}
+/** Public recorder so the live review path can append to the same audit trail. */
+export function recordSkillWriteAuditEntry(workDir, entry) {
+    recordSkillWriteAudit(workDir, entry);
+}
+export function buildSkillWriteRollbackPlan(input) {
+    const action = (input.action ?? '').trim();
+    const skillName = input.skillName.trim();
+    const snapshotId = extractRollbackSnapshotId(input.output);
+    // A captured snapshot wins over everything else: even an `candidate_install`
+    // that OVERWROTE an existing skill snapshots the prior version first, so
+    // rolling back restores the original instead of deleting the package.
+    if (snapshotId) {
+        return {
+            command: `buddy skills rollback ${shellArg(skillName)} --snapshot ${shellArg(snapshotId)} --approved-by <reviewer> --json`,
+            kind: 'rollback',
+            reason: `snapshot ${snapshotId} captured before the autonomous mutation`,
+            snapshotId,
+        };
+    }
+    // No snapshot id + an install action. `installFromContent` /
+    // `installResearchScriptSkillCandidate` currently overwrite without
+    // snapshotting, so we cannot tell a brand-new install from an overwrite at
+    // plan time. `delete` is the correct inverse ONLY for a genuinely new skill;
+    // on an overwrite it would destroy the pre-existing version, so the reason
+    // tells the operator to verify first instead of implying clean reversibility.
+    if (action === 'create' || action === 'candidate_install') {
+        return {
+            command: `buddy skills delete ${shellArg(skillName)} --json`,
+            kind: 'uninstall',
+            reason: 'install with no captured snapshot; `delete` removes the package and is the correct inverse ONLY if this was a brand-new skill. ' +
+                'If it overwrote an existing skill, delete destroys the original — verify with `buddy skills history` / `list` before running.',
+        };
+    }
+    if (['edit', 'patch', 'write_file', 'remove_file', 'reset', 'update', 'rollback'].includes(action)) {
+        return {
+            command: `buddy skills rollback ${shellArg(skillName)} --approved-by <reviewer> --json`,
+            kind: 'rollback',
+            reason: 'mutation should have a SkillsHub snapshot; use latest rollback if no snapshot id was captured',
+        };
+    }
+    return {
+        command: `buddy skills list --json`,
+        kind: 'manual-review',
+        reason: `no automatic rollback command is known for skill_manage action "${action || 'unknown'}"; inspect installed skills and roll back manually`,
+    };
+}
+/** Read the background skill-write audit trail (newest entries appended last). */
+export function listSkillWriteAudit(workDir = process.cwd()) {
+    const filePath = path.join(path.resolve(workDir), AUDIT_DIR, AUDIT_FILE);
+    return readAuditFile(filePath).entries;
+}
+function recordSkillWriteAudit(workDir, entry) {
+    const filePath = path.join(path.resolve(workDir), AUDIT_DIR, AUDIT_FILE);
+    const file = readAuditFile(filePath);
+    file.entries.push(entry);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, `${JSON.stringify(file, null, 2)}\n`, 'utf-8');
+    }
+    catch (err) {
+        logger.warn('[skill-background-writes] failed to persist audit entry', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+function readAuditFile(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (parsed.schemaVersion === SKILL_WRITE_AUDIT_SCHEMA_VERSION && Array.isArray(parsed.entries)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through to a fresh file.
+    }
+    return { schemaVersion: SKILL_WRITE_AUDIT_SCHEMA_VERSION, entries: [] };
+}
+function extractRollbackSnapshotId(output) {
+    if (!output)
+        return undefined;
+    try {
+        const parsed = JSON.parse(output);
+        return findSnapshotId(parsed, 0);
+    }
+    catch {
+        return undefined;
+    }
+}
+function findSnapshotId(value, depth) {
+    if (depth > 6 || value === null || typeof value !== 'object')
+        return undefined;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = findSnapshotId(item, depth + 1);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    const record = value;
+    for (const key of ['rollbackSnapshotId', 'snapshotId']) {
+        if (typeof record[key] === 'string' && record[key].trim()) {
+            return record[key].trim();
+        }
+    }
+    if (record.snapshot && typeof record.snapshot === 'object') {
+        const snapshot = record.snapshot;
+        if (typeof snapshot.id === 'string' && snapshot.id.trim()) {
+            return snapshot.id.trim();
+        }
+    }
+    for (const nested of Object.values(record)) {
+        const found = findSnapshotId(nested, depth + 1);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function shellArg(value) {
+    if (/^[A-Za-z0-9._:/\\-]+$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=skill-background-writes.js.map

package/dist/agent/learning/skill-background-writes.js.map

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

package/dist/agent/learning/skill-paired-gate.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Paired-gate adapter for background SKILL writes (S3).
+ *
+ * The paired live gate (`runPairedGate`) validates a piece of TEXT by BEHAVIOUR:
+ * it runs an injected agent WITH and WITHOUT the text on a set of graded tasks
+ * and accepts only if the text makes the agent solve tasks it otherwise would
+ * not, with statistical confidence and no safety regression. It is text-agnostic,
+ * so a skill's SKILL.md can be fed as the `lessonText`.
+ *
+ * The honest constraint: a freshly-generated skill rarely ships with DETERMINISTIC
+ * graded tasks. Rather than fabricate keyword graders (which the paired gate
+ * explicitly rejects as a signal), this adapter ABSTAINS when no gradeable
+ * behavioural evidence is available — the skill then falls back to the structural
+ * + secret-screen + reversibility nets in `promoteSkillCandidate`. When a caller
+ * DOES supply graded tasks (e.g. a skill that ships a regression harness, or a
+ * future derivation from recorded run contracts), the gate runs for real and can
+ * REJECT an inert / regressing / unconvincing skill.
+ *
+ * @module agent/learning/skill-paired-gate
+ */
+import { type AgentRunner, type GradedTask, type PairedGateOptions } from '../self-improvement/paired-gate.js';
+import type { ResearchScriptSkillCandidate } from '../research-script-skill-candidate.js';
+import type { SkillGate } from './skill-background-writes.js';
+export interface MakeSkillGateOptions {
+    /** Injected agent runner (production wraps the headless review loop). */
+    runner: AgentRunner;
+    /**
+     * Explicit graded tasks for this gate. When omitted, the gate tries
+     * `deriveSkillGradedTasks(candidate)` and abstains if none can be derived.
+     */
+    tasks?: GradedTask[];
+    /** Confidence threshold for the paired sign test. Default 0.95. */
+    threshold?: number;
+    /** Forwarded paired-gate options (earlyStop, baseLessons). */
+    pairedOptions?: Omit<PairedGateOptions, 'threshold'>;
+}
+/**
+ * Derive deterministic graded tasks from a materialized skill candidate.
+ *
+ * Conservative by design: returns `[]` for the generic case so the gate abstains
+ * (falling back to the reversible nets) rather than rubber-stamping with a
+ * keyword grader. This is the documented extension seam — when a candidate gains
+ * a checkable input→expected-output run contract, emit one `GradedTask` per
+ * recorded successful run whose grader asserts that contract.
+ */
+export declare function deriveSkillGradedTasks(_candidate: ResearchScriptSkillCandidate): GradedTask[];
+/**
+ * Build a `SkillGate` bound to an injected runner. The returned gate is the
+ * `gate` option of `promoteSkillCandidate`.
+ */
+export declare function makeSkillGate(options: MakeSkillGateOptions): SkillGate;

package/dist/agent/learning/skill-paired-gate.js

@@ -0,0 +1,63 @@
+/**
+ * Paired-gate adapter for background SKILL writes (S3).
+ *
+ * The paired live gate (`runPairedGate`) validates a piece of TEXT by BEHAVIOUR:
+ * it runs an injected agent WITH and WITHOUT the text on a set of graded tasks
+ * and accepts only if the text makes the agent solve tasks it otherwise would
+ * not, with statistical confidence and no safety regression. It is text-agnostic,
+ * so a skill's SKILL.md can be fed as the `lessonText`.
+ *
+ * The honest constraint: a freshly-generated skill rarely ships with DETERMINISTIC
+ * graded tasks. Rather than fabricate keyword graders (which the paired gate
+ * explicitly rejects as a signal), this adapter ABSTAINS when no gradeable
+ * behavioural evidence is available — the skill then falls back to the structural
+ * + secret-screen + reversibility nets in `promoteSkillCandidate`. When a caller
+ * DOES supply graded tasks (e.g. a skill that ships a regression harness, or a
+ * future derivation from recorded run contracts), the gate runs for real and can
+ * REJECT an inert / regressing / unconvincing skill.
+ *
+ * @module agent/learning/skill-paired-gate
+ */
+import { runPairedGate, } from '../self-improvement/paired-gate.js';
+/**
+ * Derive deterministic graded tasks from a materialized skill candidate.
+ *
+ * Conservative by design: returns `[]` for the generic case so the gate abstains
+ * (falling back to the reversible nets) rather than rubber-stamping with a
+ * keyword grader. This is the documented extension seam — when a candidate gains
+ * a checkable input→expected-output run contract, emit one `GradedTask` per
+ * recorded successful run whose grader asserts that contract.
+ */
+export function deriveSkillGradedTasks(_candidate) {
+    return [];
+}
+/**
+ * Build a `SkillGate` bound to an injected runner. The returned gate is the
+ * `gate` option of `promoteSkillCandidate`.
+ */
+export function makeSkillGate(options) {
+    const threshold = options.threshold ?? 0.95;
+    return async (candidate) => {
+        const tasks = options.tasks ?? deriveSkillGradedTasks(candidate);
+        if (tasks.length === 0) {
+            return {
+                decision: 'abstain',
+                reason: 'no gradeable behavioural evidence; relying on structural + screen + reversible nets',
+            };
+        }
+        const result = await runPairedGate(candidate.markdown, tasks, options.runner, {
+            threshold,
+            ...(options.pairedOptions ?? {}),
+        });
+        if (result.accepted) {
+            return { decision: 'accept', reason: result.notes.join('; ') || 'paired gate accepted' };
+        }
+        return {
+            decision: 'reject',
+            reason: result.rejectionReason
+                ? `paired gate rejected (${result.rejectionReason})`
+                : 'paired gate did not accept',
+        };
+    };
+}
+//# sourceMappingURL=skill-paired-gate.js.map

package/dist/agent/learning/skill-paired-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-paired-gate.js","sourceRoot":"","sources":["../../../src/agent/learning/skill-paired-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,aAAa,GAId,MAAM,oCAAoC,CAAC;AAkB5C;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAwC;IAC7E,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,OAAO,KAAK,EAAE,SAAS,EAA6B,EAAE;QACpD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,sBAAsB,CAAC,SAAS,CAAC,CAAC;QACjE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,qFAAqF;aAC9F,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;YAC5E,SAAS;YACT,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;SACjC,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,sBAAsB,EAAE,CAAC;QAC3F,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,MAAM,CAAC,eAAe;gBAC5B,CAAC,CAAC,yBAAyB,MAAM,CAAC,eAAe,GAAG;gBACpD,CAAC,CAAC,4BAA4B;SACjC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/agent/learning-agent.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Learning Agent — Hermes-style retrospective loop.
+ *
+ * This agent runs on durable RunStore trajectories, not chat guesses. It reads
+ * the redacted trajectory export, extracts tool-order/friction/pattern signals,
+ * proposes review-gated lessons, materializes review-gated SKILL.md candidates,
+ * and keeps lightweight skill/pattern telemetry for continuous improvement.
+ */
+import { type RunTrajectoryExport } from '../observability/run-trajectory-export.js';
+import type { RunStore } from '../observability/run-store.js';
+import type { LessonCategory } from './lessons-tracker.js';
+export declare const LEARNING_RETROSPECTIVE_SCHEMA_VERSION = 1;
+export declare const LEARNING_PATTERN_LIBRARY_SCHEMA_VERSION = 1;
+export declare const LEARNING_SKILL_USAGE_SCHEMA_VERSION = 1;
+export declare const LEARNING_SKILL_CANDIDATE_REVIEW_SCHEMA_VERSION = 1;
+export declare const LEARNING_AGENT_SYSTEM_PROMPT = "Tu es le Learning Agent de Code Buddy.\n\nTon r\u00F4le unique et exclusif est d'analyser les trajectoires d'ex\u00E9cution des autres agents apr\u00E8s chaque t\u00E2che complexe ou longue, d'en extraire les le\u00E7ons, et de cr\u00E9er ou d'am\u00E9liorer des skills au format officiel Hermes Agent (fichier SKILL.md).\n\nTu as acc\u00E8s \u00E0 :\n- Le plan initial de la t\u00E2che\n- L'historique complet (pens\u00E9es, d\u00E9cisions, outils appel\u00E9s, r\u00E9sultats, erreurs)\n- La biblioth\u00E8que actuelle de skills (via lessons_search ou skill_view si besoin)\n- Les outils existants dont create_skill (ou \u00E9quivalent pour enregistrer un SKILL.md)\n\nProcessus en 4 \u00E9tapes obligatoires :\n\n1. Analyse critique : Ce qui a bien march\u00E9, ce qui \u00E9tait redondant, inefficace ou source d'erreur.\n2. Pattern recognition : Identifier les s\u00E9quences r\u00E9p\u00E9titives qui m\u00E9ritent d'\u00EAtre transform\u00E9es en un seul skill r\u00E9utilisable.\n3. Cr\u00E9ation / Am\u00E9lioration : G\u00E9n\u00E9rer un skill nouveau ou une version am\u00E9lior\u00E9e d'un skill existant.\n4. Structuration Hermes : Produire uniquement le fichier SKILL.md complet au format officiel Hermes.\n\nR\u00E8gles strictes :\n- Ne cr\u00E9e un skill que s'il fait vraiment gagner du temps significatif sur des t\u00E2ches futures (priorise les patterns r\u00E9currents dans le d\u00E9veloppement logiciel).\n- Le nom du skill doit \u00EAtre en kebab-case (ex: setup-nextjs-project).\n- La description doit \u00EAtre courte, claire et orient\u00E9e usage (ce que l'agent voit en premier).\n- Sois extr\u00EAmement pr\u00E9cis, robuste et r\u00E9utilisable.\n- Utilise les outils d'enregistrement de skills quand c'est pertinent.\n\n\u00C0 la fin de ton raisonnement, tu DOIS sortir UNIQUEMENT le contenu complet du fichier SKILL.md, sans aucun texte avant ou apr\u00E8s (ni explication, ni cl\u00F4ture Markdown). Le fichier doit commencer directement par ---.\n\nTemplate exact \u00E0 suivre :\n\n---\nname: nom-du-skill-en-kebab-case\ndescription: Description courte et pr\u00E9cise de ce que fait le skill (1 phrase max, ce que voit l'agent au niveau 0).\nversion: 1.0.0\nauthor: Code Buddy Learning Agent\nlicense: MIT\nplatforms: [linux, macos]\nmetadata:\n  hermes:\n    tags: [tag1, tag2, tag3]\n    category: web_development | refactoring | testing | security | architecture | debugging | devops | general\n---\n\n# Titre du Skill (humainement lisible)\n\n## When to Use\nConditions pr\u00E9cises dans lesquelles ce skill doit \u00EAtre activ\u00E9 (triggers clairs).\n\n## Procedure\n1. \u00C9tape 1 d\u00E9taill\u00E9e\n2. \u00C9tape 2 d\u00E9taill\u00E9e\n3. ...\n\n## Pitfalls\n- Mode d'\u00E9chec 1 et comment l'\u00E9viter\n- Mode d'\u00E9chec 2\n\n## Verification\n- Crit\u00E8re 1 de succ\u00E8s\n- Crit\u00E8re 2 de succ\u00E8s\n\n## Quick Reference\nCommande ou usage ultra-court (une ligne).";
+export declare const LEARNING_AGENT_OUTPUT_SCHEMA: {
+    readonly type: "string";
+    readonly description: "Complete Hermes Agent SKILL.md content. It must start with --- and contain no wrapper text.";
+};
+type PatternStatus = 'observed' | 'reinforced' | 'deprecated';
+type LearningSkillRecommendation = 'observe' | 'reinforce' | 'improve' | 'deprecate';
+export interface LearningToolStat {
+    averageDurationMs?: number;
+    failureCount: number;
+    successCount: number;
+    toolName: string;
+    totalDurationMs: number;
+    useCount: number;
+}
+export interface LearningFrictionPoint {
+    detail: string;
+    evidence: string;
+    severity: 'low' | 'medium' | 'high';
+    toolName?: string;
+}
+export interface LearningPattern {
+    confidence: 'low' | 'medium' | 'high';
+    detail: string;
+    evidence: string;
+    toolSequence: string[];
+}
+export interface LearningLessonCandidate {
+    category: LessonCategory;
+    content: string;
+    context?: string;
+}
+export interface LearningSkillCandidate {
+    eligible: boolean;
+    reason: string;
+    reviewManifestPath?: string;
+    skillName: string;
+    skillPath: string;
+    toolSequence: string[];
+    title: string;
+}
+export interface LearningRetrospective {
+    schemaVersion: typeof LEARNING_RETROSPECTIVE_SCHEMA_VERSION;
+    generatedAt: string;
+    kind: 'learning_retrospective';
+    run: {
+        artifactCount: number;
+        durationMs?: number;
+        objective: string;
+        runId: string;
+        status: RunTrajectoryExport['run']['status'];
+        toolCallCount: number;
+    };
+    complexity: {
+        eventCount: number;
+        isComplex: boolean;
+        reasons: string[];
+    };
+    toolSequence: string[];
+    toolStats: LearningToolStat[];
+    frictionPoints: LearningFrictionPoint[];
+    effectivePatterns: LearningPattern[];
+    redundantPatterns: LearningPattern[];
+    lessonCandidates: LearningLessonCandidate[];
+    skillCandidates: LearningSkillCandidate[];
+    summary: string;
+}
+export interface LearningPatternRecord {
+    key: string;
+    candidateSkillName?: string;
+    candidateSkillPath?: string;
+    failureCount: number;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    lastSeenRunId: string;
+    observationCount: number;
+    status: PatternStatus;
+    successCount: number;
+    toolSequence: string[];
+}
+export interface LearningPatternLibrary {
+    schemaVersion: typeof LEARNING_PATTERN_LIBRARY_SCHEMA_VERSION;
+    updatedAt: string;
+    patterns: LearningPatternRecord[];
+}
+export interface LearningSkillUsageRecord {
+    averageDurationMs?: number;
+    deprecated: boolean;
+    failureCount: number;
+    invocationCount: number;
+    lastMutation?: LearningSkillMutationEvent;
+    lastDurationMs?: number;
+    lastError?: string;
+    lastRunId?: string;
+    lastUsedAt: string;
+    mutationCount: number;
+    mutationHistory: LearningSkillMutationEvent[];
+    reinforced: boolean;
+    score: number;
+    scoreHistory: LearningSkillScoreEvent[];
+    scoreReason: string;
+    skillName: string;
+    successCount: number;
+    recommendation: LearningSkillRecommendation;
+    nextAction: string;
+}
+export interface LearningSkillUsageFile {
+    schemaVersion: typeof LEARNING_SKILL_USAGE_SCHEMA_VERSION;
+    updatedAt: string;
+    skills: LearningSkillUsageRecord[];
+}
+export interface LearningSkillUsageInput {
+    durationMs?: number;
+    error?: string;
+    mutation?: LearningSkillMutationInput;
+    runId?: string;
+    success: boolean;
+    usedAt?: number | string;
+}
+export interface LearningSkillMutationInput {
+    action: string;
+    approvedBy?: string;
+    currentSnapshotId?: string;
+    error?: string;
+    reason?: string;
+    restoredSnapshotId?: string;
+    rollbackSnapshotId?: string;
+    rollbackableCount?: number;
+}
+export interface LearningSkillMutationEvent extends LearningSkillMutationInput {
+    recordedAt: string;
+    runId?: string;
+    success: boolean;
+}
+export interface LearningSkillScoreEvent {
+    failureCount: number;
+    invocationCount: number;
+    recommendation: LearningSkillRecommendation;
+    runId?: string;
+    score: number;
+    scoredAt: string;
+    successCount: number;
+    reason: string;
+}
+export interface RunLearningRetrospectiveOptions {
+    force?: boolean;
+    materializeSkillCandidates?: boolean;
+    proposeLessonCandidates?: boolean;
+    saveArtifacts?: boolean;
+    workDir?: string;
+}
+export interface LearningAgentRunResult {
+    lessonCandidateCount: number;
+    patternLibraryPath?: string;
+    retrospective?: LearningRetrospective;
+    retrospectiveArtifact?: string;
+    skillCandidateCount: number;
+    skillUsageCount: number;
+    skipped: boolean;
+    skippedReason?: string;
+}
+export declare function buildLearningRetrospective(runId: string, options?: {
+    store?: RunStore;
+    workDir?: string;
+}): LearningRetrospective | null;
+export declare function runLearningRetrospective(store: RunStore, runId: string, options?: RunLearningRetrospectiveOptions): Promise<LearningAgentRunResult>;
+export declare function renderLearningRetrospective(retrospective: LearningRetrospective): string;
+export declare function recordLearningSkillUsage(skillName: string, record: LearningSkillUsageInput, workDir?: string): LearningSkillUsageRecord;
+export declare function listLearningSkillUsage(workDir?: string): LearningSkillUsageRecord[];
+export declare function isLearningAgentEnabled(): boolean;
+export {};