agentsmesh 0.30.2 → 0.32.0

package/dist/{init-PvpXanVd.d.ts → init-CrZhoNTj.d.ts}

@@ -73,6 +73,79 @@ type TriggerKind = z.infer<typeof TriggerKindSchema>;
 type LessonStatus = z.infer<typeof LessonStatusSchema>;
 declare function parseGraph(raw: unknown): LessonsGraph;
 
+interface LessonsQuery {
+    /** Project-relative path of the file about to be edited. */
+    readonly file?: string;
+    /** Shell command about to be executed. */
+    readonly command?: string;
+    /** Free-form text describing the current task. */
+    readonly keyword?: string;
+}
+interface MatchedLesson {
+    readonly id: string;
+    readonly lesson: Lesson;
+}
+/**
+ * Recall primitive — returns every active lesson whose triggers match any of
+ * the supplied query fields. The query fields combine as OR across triggers:
+ * a lesson matches if ANY of its triggers match ANY supplied field.
+ * Deprecated and superseded lessons are excluded.
+ */
+declare function queryLessons(graph: LessonsGraph, query: LessonsQuery): MatchedLesson[];
+
+interface RankReason {
+    readonly matchedTriggers: string[];
+    readonly bm25: number;
+    readonly specificity: number;
+    readonly topicCoherence: number;
+}
+interface RankedLesson {
+    readonly id: string;
+    readonly lesson: Lesson;
+    readonly score: number;
+    readonly reason: RankReason;
+}
+interface RankOptions {
+    /** Keep at most this many results (after ranking). */
+    readonly limit?: number;
+    /**
+     * Best-effort token budget: keep results while their cumulative estimated
+     * rule-token cost fits. The single most-relevant result is ALWAYS returned
+     * even if it alone exceeds the budget — an empty recall for a matched query is
+     * worse for the agent than one slightly-over-budget rule.
+     */
+    readonly maxTokens?: number;
+    /**
+     * Per-lesson effectiveness score in [0,1] from the outcome log (1 = always
+     * helped; absent = neutral). Fed as a LOW-weight RRF signal so a proven
+     * fire-but-fail lesson sinks below an equally-matched effective one — a
+     * corrective nudge, never a driver. Empty/absent ⇒ every lesson ties on this
+     * signal ⇒ ordering is unchanged from the pre-effectiveness ranker.
+     */
+    readonly effectiveness?: ReadonlyMap<string, number>;
+}
+/** Default recall cap: a broad trigger match returns the most-relevant few, not the whole topic. */
+declare const DEFAULT_RECALL_LIMIT = 10;
+/**
+ * Default recall token budget applied by the application APIs (CLI `query`, MCP
+ * `lessons_query`, {@link recallLessons}) when the caller does not specify one.
+ * Mandatory recall runs before every edit/command, so its payload must stay
+ * lean; without a budget a broad match can return ~450+ rule-tokens. `--all`
+ * (CLI) bypasses both caps. The top result is always kept (see RankOptions).
+ */
+declare const DEFAULT_RECALL_MAX_TOKENS = 400;
+/**
+ * Rank matched lessons by relevance and apply optional caps. Three lightweight
+ * signals are weighted-reciprocal-rank-fused (RRF): trigger specificity (inverse
+ * fanout — a discriminating trigger beats a topic-wide one; highest weight),
+ * per-query topic coherence (a lesson in the topic that dominates this query's
+ * matched set is boosted; middle weight), and BM25 over the rule text (so the
+ * lesson whose wording best fits breaks ties the structural signals cannot;
+ * lowest weight). Ties break by recency (createdAt) then id. No embeddings, no
+ * I/O — pure and sub-millisecond.
+ */
+declare function rankLessons(graph: LessonsGraph, query: LessonsQuery, matches: readonly MatchedLesson[], options?: RankOptions): RankedLesson[];
+
 interface AutoPruneSummary {
     readonly removedTriggers: number;
     readonly removedTopics: number;
@@ -93,7 +166,7 @@ interface AutoPruneSummary {
  * because that lesson is captured then silently never recalled. These guardrails
  * are the warn-only complement to that single hard block.
  */
-type GuardrailCode = 'OVERSIZED_LESSON_TRIGGERS' | 'BROAD_GLOB_TRIGGER' | 'WIDE_GLOB_MATCH' | 'KEYWORD_ONLY_LESSON' | 'LOW_SIGNAL_KEYWORD' | 'STOPWORD_KEYWORD' | 'DEAD_GLOB' | 'NEAR_DUPLICATE_LESSON';
+type GuardrailCode = 'OVERSIZED_LESSON_TRIGGERS' | 'BROAD_GLOB_TRIGGER' | 'WIDE_GLOB_MATCH' | 'KEYWORD_ONLY_LESSON' | 'LOW_SIGNAL_KEYWORD' | 'STOPWORD_KEYWORD' | 'DEAD_GLOB' | 'NEAR_DUPLICATE_LESSON' | 'NARROWED_GLOB' | 'KEYWORD_VARIANT_ADDED' | 'DROPPED_KEYWORD';
 interface GuardrailWarning {
     readonly code: GuardrailCode;
     readonly message: string;
@@ -159,79 +232,6 @@ interface AddLessonResult {
 }
 declare function addLesson(projectRoot: string, input: AddLessonInput, options?: AddLessonOptions): Promise<AddLessonResult>;
 
-interface LessonsQuery {
-    /** Project-relative path of the file about to be edited. */
-    readonly file?: string;
-    /** Shell command about to be executed. */
-    readonly command?: string;
-    /** Free-form text describing the current task. */
-    readonly keyword?: string;
-}
-interface MatchedLesson {
-    readonly id: string;
-    readonly lesson: Lesson;
-}
-/**
- * Recall primitive — returns every active lesson whose triggers match any of
- * the supplied query fields. The query fields combine as OR across triggers:
- * a lesson matches if ANY of its triggers match ANY supplied field.
- * Deprecated and superseded lessons are excluded.
- */
-declare function queryLessons(graph: LessonsGraph, query: LessonsQuery): MatchedLesson[];
-
-interface RankReason {
-    readonly matchedTriggers: string[];
-    readonly bm25: number;
-    readonly specificity: number;
-    readonly topicCoherence: number;
-}
-interface RankedLesson {
-    readonly id: string;
-    readonly lesson: Lesson;
-    readonly score: number;
-    readonly reason: RankReason;
-}
-interface RankOptions {
-    /** Keep at most this many results (after ranking). */
-    readonly limit?: number;
-    /**
-     * Best-effort token budget: keep results while their cumulative estimated
-     * rule-token cost fits. The single most-relevant result is ALWAYS returned
-     * even if it alone exceeds the budget — an empty recall for a matched query is
-     * worse for the agent than one slightly-over-budget rule.
-     */
-    readonly maxTokens?: number;
-    /**
-     * Per-lesson effectiveness score in [0,1] from the outcome log (1 = always
-     * helped; absent = neutral). Fed as a LOW-weight RRF signal so a proven
-     * fire-but-fail lesson sinks below an equally-matched effective one — a
-     * corrective nudge, never a driver. Empty/absent ⇒ every lesson ties on this
-     * signal ⇒ ordering is unchanged from the pre-effectiveness ranker.
-     */
-    readonly effectiveness?: ReadonlyMap<string, number>;
-}
-/** Default recall cap: a broad trigger match returns the most-relevant few, not the whole topic. */
-declare const DEFAULT_RECALL_LIMIT = 10;
-/**
- * Default recall token budget applied by the application APIs (CLI `query`, MCP
- * `lessons_query`, {@link recallLessons}) when the caller does not specify one.
- * Mandatory recall runs before every edit/command, so its payload must stay
- * lean; without a budget a broad match can return ~450+ rule-tokens. `--all`
- * (CLI) bypasses both caps. The top result is always kept (see RankOptions).
- */
-declare const DEFAULT_RECALL_MAX_TOKENS = 400;
-/**
- * Rank matched lessons by relevance and apply optional caps. Three lightweight
- * signals are weighted-reciprocal-rank-fused (RRF): trigger specificity (inverse
- * fanout — a discriminating trigger beats a topic-wide one; highest weight),
- * per-query topic coherence (a lesson in the topic that dominates this query's
- * matched set is boosted; middle weight), and BM25 over the rule text (so the
- * lesson whose wording best fits breaks ties the structural signals cannot;
- * lowest weight). Ties break by recency (createdAt) then id. No embeddings, no
- * I/O — pure and sub-millisecond.
- */
-declare function rankLessons(graph: LessonsGraph, query: LessonsQuery, matches: readonly MatchedLesson[], options?: RankOptions): RankedLesson[];
-
 interface MutateOptions {
     readonly retries?: number;
 }

package/dist/lessons.d.ts

@@ -1,5 +1,5 @@
-import { o as RankedLesson, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult, j as LessonsQuery } from './init-PvpXanVd.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-PvpXanVd.js';
+import { o as RankedLesson, j as LessonsQuery, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult } from './init-CrZhoNTj.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-CrZhoNTj.js';
 import 'zod';
 
 /**
@@ -15,8 +15,9 @@ import 'zod';
  * 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.
+ * loads + ranks. `captureLesson` (capture.ts) is the symmetric capture entry
+ * point. Prefer these application APIs; reach for the read primitives only
+ * post-migration.
  */
 interface RecallOptions {
     /** Max ranked lessons to return. Defaults to {@link DEFAULT_RECALL_LIMIT}. */
@@ -62,9 +63,12 @@ interface RecallResult {
  * lessons matching `query`, relevance-ranked and capped by limit + token budget.
  */
 declare function recallLessons(projectRoot: string, query: LessonsQuery, options?: RecallOptions): Promise<RecallResult>;
+
 /**
  * Capture primitive for applications: migrate if needed, then add the lesson
  * through the transactional write path. Idempotent on repeat (same rule+topic).
+ * The symmetric counterpart of `recallLessons` (recall.ts), split out for the
+ * 200-line limit.
  *
  * 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