agentsmesh 0.22.0 → 0.23.0

package/dist/lessons.d.ts

@@ -1,155 +1,106 @@
-import { z } from 'zod';
-
-declare function hashBullet(bullet: string): string;
-
-interface ParsedBullet {
-    text: string;
-    lineNumber: number;
-}
-declare function parseBullets(markdown: string): ParsedBullet[];
-
-declare const ClusterSchema: z.ZodObject<{
-    topic: z.ZodString;
-    file: z.ZodString;
-    summary: z.ZodString;
-    triggers: z.ZodObject<{
-        file_globs: z.ZodArray<z.ZodString>;
-        command_patterns: z.ZodArray<z.ZodString>;
-        keywords: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-declare const LessonsIndexSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    clusters: z.ZodArray<z.ZodObject<{
-        topic: z.ZodString;
-        file: z.ZodString;
-        summary: z.ZodString;
-        triggers: z.ZodObject<{
-            file_globs: z.ZodArray<z.ZodString>;
-            command_patterns: z.ZodArray<z.ZodString>;
-            keywords: z.ZodArray<z.ZodString>;
-        }, z.core.$strip>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-type LessonsIndex = z.infer<typeof LessonsIndexSchema>;
-type LessonsCluster = z.infer<typeof ClusterSchema>;
-declare function parseIndex(raw: unknown): LessonsIndex;
-
-type ToolEvent = {
-    kind: 'edit' | 'write';
-    filePath: string;
-} | {
-    kind: 'bash';
-    command: string;
-} | {
-    kind: 'task';
-    text: string;
-};
-declare function matchTriggers(clusters: readonly LessonsCluster[], event: ToolEvent): LessonsCluster[];
-
-declare const LedgerSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    assignments: z.ZodRecord<z.ZodString, z.ZodString>;
-}, z.core.$strip>;
-type Ledger = z.infer<typeof LedgerSchema>;
-declare function loadLedger(path: string): Ledger;
-declare function saveLedger(path: string, ledger: Ledger): void;
-
-interface ScoredCluster {
-    cluster: LessonsCluster;
-    score: number;
-}
-declare function scoreBullet(bullet: string, clusters: readonly LessonsCluster[]): ScoredCluster[];
-
-interface TriggeredLesson {
-    readonly cluster: LessonsCluster;
-    readonly relativePath: string;
-    readonly filePath: string;
-    readonly content: string;
-}
-interface LessonCaptureInput {
-    readonly heading: string;
-    readonly whatWentWrong: string;
-    readonly rootCause: string;
-    readonly rule: string;
-}
-interface AppendLessonResult {
-    readonly journalPath: string;
-    readonly bullet: string;
-    readonly lineNumber: number;
-}
-declare function loadLessonsIndex(projectRoot: string): LessonsIndex;
-declare function readTriggeredLessons(projectRoot: string, event: ToolEvent): TriggeredLesson[];
-declare function formatLessonBullet(input: LessonCaptureInput): string;
-declare function appendLessonToJournal(projectRoot: string, input: LessonCaptureInput): AppendLessonResult;
+import { o as RankedLesson, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult, j as LessonsQuery } from './init-YKxF2zpQ.js';
+export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, _ as lessonsLockPath, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-YKxF2zpQ.js';
+import 'zod';
 
 /**
- * Default on-disk locations for the lessons subsystem.
+ * Migration-aware application APIs for the lessons subsystem.
  *
- * All artifacts live under `<projectRoot>/.agentsmesh/lessons/`, so the lessons
- * subsystem is a self-contained canonical feature — `agentsmesh init --lessons`
- * scaffolds this directory and the procedural rule, and removal is a single
- * directory delete.
+ * The WRITE path migrates automatically: `mutateLessonsGraph` (and everything
+ * built on it — `addLesson`, `mergeLessons`, deprecate, strip-markers) runs the
+ * legacy→JSON migration before mutating, so even a first raw write can never
+ * create an empty `lessons.json` over an unmigrated `index.yaml`. (The migrator
+ * and scaffolding use the internal `mutateLessonsGraphLocked` to avoid
+ * recursing.)
  *
- * Path values are absolute; `*Rel` helpers return forward-slash project-relative
- * paths suitable for embedding in markdown rules consumed by any agent target.
+ * The low-level READ primitives (`tryLoadLessonsGraph`, `loadLessonsGraph`,
+ * `queryLessons`) do NOT migrate — a first read through them on a legacy project
+ * would see no graph. `recallLessons` closes that: it migrates first, then
+ * loads + ranks. `captureLesson` is the symmetric capture entry point. Prefer
+ * these application APIs; reach for the read primitives only post-migration.
  */
-interface LessonsPaths {
-    /** Directory containing every lessons artifact. */
-    readonly base: string;
-    /** Append-only journal — point of capture for new lessons. */
-    readonly journal: string;
-    /** Trigger index — maps file_globs / command_patterns / keywords to topic files. */
-    readonly index: string;
-    /** Distill ledger — bullet hash → assigned topic (or "skip"). */
-    readonly ledger: string;
-    /** Distill proposal file — generated by `distill`, consumed by `distill:apply`. */
-    readonly proposal: string;
-    /** Directory holding one markdown file per topic cluster. */
-    readonly topicsDir: string;
+interface RecallOptions {
+    /** Max ranked lessons to return. Defaults to {@link DEFAULT_RECALL_LIMIT}. */
+    readonly limit?: number;
+    /**
+     * Cumulative rule-token budget. Defaults to {@link DEFAULT_RECALL_MAX_TOKENS};
+     * pass `null` to disable the budget (return up to `limit` results).
+     */
+    readonly maxTokens?: number | null;
+    /**
+     * Session correlator for recall dedup. Defaults to `AGENTSMESH_SESSION_ID`;
+     * when set, lessons already delivered this session are suppressed.
+     */
+    readonly sessionId?: string;
+    /** Force dedup off even when a session correlator is present. */
+    readonly noDedup?: boolean;
+}
+interface RecallResult {
+    /** Relevance-ranked, capped lessons (compact metadata lives on each entry). */
+    readonly lessons: RankedLesson[];
+    /** How many active lessons matched the query before the caps were applied. */
+    readonly totalMatches: number;
+    /**
+     * True when the canonical graph existed but could not be read (corrupt JSON /
+     * schema drift). Recall degrades to empty instead of throwing; callers surface
+     * this so a corrupt graph is a visible warning, not silent zero recall.
+     */
+    readonly corrupt?: boolean;
+    /**
+     * Set to the on-disk schema version when the graph is newer than this build
+     * understands. Recall degrades to empty (like `corrupt`) but callers surface
+     * an upgrade hint rather than a "corrupt" warning.
+     */
+    readonly newerVersion?: number;
+    /**
+     * Count of matched lessons suppressed because they were already delivered
+     * earlier in this session (dedup). 0 when dedup is off or nothing repeated.
+     */
+    readonly suppressed: number;
 }
-declare function lessonsPaths(projectRoot: string): LessonsPaths;
-/**
- * Project-relative path for a given absolute path, normalized to forward
- * slashes for cross-platform consistency in markdown rule files.
- */
-declare function toRelPath(projectRoot: string, absolute: string): string;
 /**
- * Empty-journal contents used by init scaffolding. The journal grows from here
- * as failures get recorded.
+ * Recall primitive for applications: migrate if needed, then return the active
+ * lessons matching `query`, relevance-ranked and capped by limit + token budget.
  */
-declare const LESSONS_JOURNAL_TEMPLATE = "# Lessons Learned\n\n";
+declare function recallLessons(projectRoot: string, query: LessonsQuery, options?: RecallOptions): Promise<RecallResult>;
 /**
- * Empty index used by init scaffolding. Schema allows zero clusters; topics
- * accumulate via `distill:apply` as failures are captured.
+ * Capture primitive for applications: migrate if needed, then add the lesson
+ * through the transactional write path. Idempotent on repeat (same rule+topic).
+ *
+ * Both CLI `lessons add` and MCP `lessons_add` route through here, so capture
+ * telemetry is recorded once at this single entry point (mirroring how every
+ * recall records through `recallLessons`). Every rejection — a dead trigger, an
+ * unknown topic, a write-barrier failure — is recorded as a BLOCKED capture
+ * before being rethrown, so `stats` never undercounts blocks.
  */
-declare const LESSONS_INDEX_TEMPLATE = "version: 1\nclusters: []\n";
+declare function captureLesson(projectRoot: string, input: AddLessonInput, options?: AddLessonOptions): Promise<AddLessonResult>;
+
 /**
- * Procedural rule paragraph that must live in the project's root rule
- * (`.agentsmesh/rules/_root.md`) for both recall and capture to be enforced.
- *
- * Universal across every agent target: only requires the ability to read
- * project files. No `Skill` tool, no description-match, no per-target
- * projection.
+ * One-shot legacy→JSON migration on first access. Shared by the CLI dispatcher
+ * AND the MCP handlers so that an MCP-only agent (query/add) does not strand a
+ * legacy store: if it added first it would create `lessons.json`, which then
+ * permanently blocks the absent-graph auto-migration. Returns true if it
+ * migrated. No-op when a graph already exists or no legacy index is present.
  */
-declare const LESSONS_PROCEDURAL_RULE = "## Lessons (MUST do \u2014 non-negotiable)\n\nTwo rituals. Universal across every agent harness \u2014 described in tool-agnostic action verbs (\"read a file\", \"edit a file\", \"run a shell command\"); use whatever read / write-patch / shell-exec tool your harness exposes. Skipping either ritual is a process violation; the same paid-for failure recurs next session.\n\n**Recall \u2014 BEFORE editing any file or running any shell command:**\n\n1. Read `.agentsmesh/lessons/index.yaml`.\n2. For every cluster whose triggers match \u2014 `file_globs` against the target file path, `command_patterns` (regex) against the shell command, or `keywords` (case-insensitive substring) against the active task description \u2014 read its `file` (e.g. `.agentsmesh/lessons/topics/<topic>.md`).\n3. Apply the loaded rules to the action.\n4. Then \u2014 and only then \u2014 perform the edit or run the command.\n\nRejected excuses: *\"the edit is small\"* \u2192 apply it. *\"I read this earlier in the session\"* \u2192 context may have compacted; re-read. *\"no trigger fires\"* \u2192 proceed; you've done your part.\n\n**Capture \u2014 IMMEDIATELY after any failure** (test, CI, lint, code review, user correction, regression you spotted yourself, OR any mistake by anyone in the loop):\n\n1. Append one bullet to `.agentsmesh/lessons/journal.md` in this exact shape:\n   `- **<short heading>**: <what went wrong>. <root cause>. <imperative rule that prevents recurrence>.`\n2. Read `.agentsmesh/lessons/index.yaml` and identify which topic the lesson belongs to (use the `summary:` fields).\n3. If the lesson teaches a NEW rule: edit that topic's `## Rules` section to add it, citing `(Evidence: L<journal-line>)`. If it only reinforces an existing rule, the journal entry alone suffices.\n\nRejected excuses: *\"it wasn't really a failure\"* \u2192 if you fixed something, it was. *\"I'll capture it later\"* \u2192 no; do it now while context is fresh. *\"no topic fits\"* \u2192 still record in journal; an unrouted bullet is recoverable, a forgotten one is not.\n\n**These two rituals are load-bearing. Treat them with the same discipline as TDD.**";
+declare function maybeAutoMigrateLessons(projectRoot: string): Promise<boolean>;
 
-interface ScaffoldLessonsResult {
-    readonly created: string[];
-    readonly skipped: string[];
-    readonly rootRuleUpdated: boolean;
-}
 /**
- * Idempotent scaffolder for the lessons subsystem. Intended for a future
- * `agentsmesh init --lessons` flag (project mode); safe to call repeatedly.
+ * Safety gate for `command_pattern` triggers.
  *
- * Creates `.agentsmesh/lessons/` with an empty journal, an empty index, and a
- * `topics/` directory. Appends the procedural rule to
- * `.agentsmesh/rules/_root.md` if not already present.
+ * Recall is mandatory (it runs before every edit/command) and matches
+ * author-supplied patterns against the command string. A backtracking `RegExp`
+ * can be driven super-linear by a crafted pattern — `(a+)+`, `(a|aa)+`, `a+a+`,
+ * or even `a+b` (quadratic on a long non-matching input) — so one lesson could
+ * hang recall. Local inspection of quantifier shape CANNOT prove a backtracking
+ * regex linear, so we do not try: command patterns are matched by an in-repo
+ * non-backtracking engine ({@link compileLinearMatcher}), which is provably
+ * linear in the input length for any pattern it can compile.
  *
- * Never overwrites existing files. The ledger and proposal are not created —
- * they are auto-managed by the distill tool on first run.
+ * A pattern is "safe" iff the linear engine can compile it. Patterns it cannot
+ * evaluate (invalid syntax, backreferences, lookarounds) are rejected at capture
+ * (UNSAFE_TRIGGER_PATTERN) and skipped at read time — fail closed.
  */
-declare function scaffoldLessons(projectRoot: string): ScaffoldLessonsResult;
 
-export { type AppendLessonResult, LESSONS_INDEX_TEMPLATE, LESSONS_JOURNAL_TEMPLATE, LESSONS_PROCEDURAL_RULE, type Ledger, type LessonCaptureInput, type LessonsCluster, type LessonsIndex, LessonsIndexSchema, type LessonsPaths, type ParsedBullet, type ScaffoldLessonsResult, type ScoredCluster, type ToolEvent, type TriggeredLesson, appendLessonToJournal, formatLessonBullet, hashBullet, lessonsPaths, loadLedger, loadLessonsIndex, matchTriggers, parseBullets, parseIndex, readTriggeredLessons, saveLedger, scaffoldLessons, scoreBullet, toRelPath };
+/** True when `pattern` can be matched by the linear engine (no ReDoS risk). */
+declare function isSafeRegexPattern(pattern: string): boolean;
+
+export { AddLessonInput, AddLessonOptions, AddLessonResult, LessonsQuery, RankedLesson, type RecallOptions, type RecallResult, captureLesson, isSafeRegexPattern, maybeAutoMigrateLessons, recallLessons };