@hiveai/core 0.10.8 → 0.11.0

package/dist/index.d.ts

@@ -66,6 +66,32 @@ declare const SensorSchema: z.ZodObject<{
     autogen?: boolean | undefined;
     last_fired?: string | null | undefined;
 }>;
+/**
+ * Progressive-disclosure activation triggers for a `skill` memory.
+ *
+ * A skill is a reusable playbook (feedforward harness guide). Injecting every skill
+ * on every briefing bloats the context and dilutes signal (the "instruction budget"
+ * problem). An `activation` block makes a skill surface ONLY when it is relevant:
+ * its keywords match the task, or its globs match the files being edited. A skill
+ * that defines `activation` and matches none of it is suppressed from the briefing;
+ * a skill with no `activation` block keeps the legacy always-eligible behavior.
+ */
+declare const ActivationSchema: z.ZodObject<{
+    /** Case-insensitive substrings matched against the task text. */
+    keywords: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Glob-ish path patterns matched against the files being edited. */
+    globs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Always activate (rare — for truly universal playbooks). */
+    always: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    keywords: string[];
+    globs: string[];
+    always: boolean;
+}, {
+    keywords?: string[] | undefined;
+    globs?: string[] | undefined;
+    always?: boolean | undefined;
+}>;
 declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     id: z.ZodString;
     scope: z.ZodDefault<z.ZodEnum<["personal", "team", "module", "shared"]>>;
@@ -125,6 +151,23 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         autogen?: boolean | undefined;
         last_fired?: string | null | undefined;
     }>>;
+    /** Optional progressive-disclosure triggers — only meaningful for `type: skill`. */
+    activation: z.ZodOptional<z.ZodObject<{
+        /** Case-insensitive substrings matched against the task text. */
+        keywords: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Glob-ish path patterns matched against the files being edited. */
+        globs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Always activate (rare — for truly universal playbooks). */
+        always: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        keywords: string[];
+        globs: string[];
+        always: boolean;
+    }, {
+        keywords?: string[] | undefined;
+        globs?: string[] | undefined;
+        always?: boolean | undefined;
+    }>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     domain: z.ZodOptional<z.ZodString>;
     author: z.ZodOptional<z.ZodString>;
@@ -174,6 +217,11 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         flags?: string | undefined;
         command?: string | undefined;
     } | undefined;
+    activation?: {
+        keywords: string[];
+        globs: string[];
+        always: boolean;
+    } | undefined;
     domain?: string | undefined;
     author?: string | undefined;
     topic?: string | undefined;
@@ -200,6 +248,11 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         autogen?: boolean | undefined;
         last_fired?: string | null | undefined;
     } | undefined;
+    activation?: {
+        keywords?: string[] | undefined;
+        globs?: string[] | undefined;
+        always?: boolean | undefined;
+    } | undefined;
     tags?: string[] | undefined;
     domain?: string | undefined;
     author?: string | undefined;
@@ -242,6 +295,11 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         flags?: string | undefined;
         command?: string | undefined;
     } | undefined;
+    activation?: {
+        keywords: string[];
+        globs: string[];
+        always: boolean;
+    } | undefined;
     domain?: string | undefined;
     author?: string | undefined;
     topic?: string | undefined;
@@ -268,6 +326,11 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         autogen?: boolean | undefined;
         last_fired?: string | null | undefined;
     } | undefined;
+    activation?: {
+        keywords?: string[] | undefined;
+        globs?: string[] | undefined;
+        always?: boolean | undefined;
+    } | undefined;
     tags?: string[] | undefined;
     domain?: string | undefined;
     author?: string | undefined;
@@ -302,6 +365,7 @@ type MemoryStatus = z.infer<typeof MemoryStatusSchema>;
 type MemoryType = z.infer<typeof MemoryTypeSchema>;
 type Anchor = z.infer<typeof AnchorSchema>;
 type Sensor = z.infer<typeof SensorSchema>;
+type Activation = z.infer<typeof ActivationSchema>;
 type MemoryFrontmatter = z.infer<typeof MemoryFrontmatterSchema>;
 interface Memory {
     frontmatter: MemoryFrontmatter;
@@ -327,6 +391,7 @@ declare function buildFrontmatter(input: {
     status?: MemoryFrontmatter["status"];
     relatedIds?: string[];
     sensor?: Sensor;
+    activation?: Activation;
 }): MemoryFrontmatter;
 
 declare const HAIVE_DIR = ".ai";
@@ -395,6 +460,15 @@ interface MemoryUsage {
     rejected_count: number;
     last_rejected_at: string | null;
     rejection_reason: string | null;
+    /**
+     * Number of times the memory was explicitly confirmed *useful* — i.e. an agent
+     * or human recorded that it changed what they did (the closed-loop "applied"
+     * outcome, recorded via `mem_feedback`). A far stronger utility signal than a
+     * read: a memory can be surfaced many times and ignored, but `applied` means it
+     * demonstrably steered work. Drives impact scoring in {@link ./impact.js}.
+     */
+    applied_count: number;
+    last_applied_at: string | null;
 }
 interface UsageIndex {
     version: 1;
@@ -410,10 +484,172 @@ declare function saveUsageIndex(paths: HaivePaths, index: UsageIndex): Promise<v
 declare function getUsage(index: UsageIndex, id: string): MemoryUsage;
 declare function bumpRead(index: UsageIndex, ids: string[]): UsageIndex;
 declare function recordRejection(index: UsageIndex, id: string, reason: string | null): UsageIndex;
+/**
+ * Record that a memory was *applied* — explicitly confirmed to have changed what
+ * the agent/human did. This is the closed-loop utility signal that distinguishes
+ * a memory that merely got surfaced from one that demonstrably steered work.
+ */
+declare function recordApplied(index: UsageIndex, id: string): UsageIndex;
 declare const DECAY_DAYS = 90;
 declare function isDecaying(usage: MemoryUsage, createdAt: string): boolean;
 declare function trackReads(paths: HaivePaths, ids: string[]): Promise<UsageIndex>;
 
+/**
+ * Closed-loop memory-utility scoring — the "did this memory actually help?" layer.
+ *
+ * hAIve already tracks reads ({@link ./usage.js}) and derives a trust level from
+ * status + read_count ({@link ./confidence.js}). But a read only means a memory was
+ * *surfaced*, not that it *helped* — a memory can be injected on every briefing and
+ * silently ignored. Harness engineering's core loop (Fowler / LangChain) is to
+ * measure what demonstrably steers work and let that feed back into recall.
+ *
+ * `computeImpact` combines the signals hAIve already records but never correlated:
+ *   POSITIVE  reads · applied outcomes (mem_feedback) · a sensor that actually fired
+ *   NEGATIVE  rejections · stale/deprecated/rejected status · dormancy
+ * into a single 0..1 utility score, a tier, and a prune-candidate flag. It is a pure
+ * function (no I/O), unit-tested in `packages/core/test/impact.test.ts`.
+ */
+type ImpactTier = "high" | "medium" | "low" | "dormant";
+interface ImpactScore {
+    /** Normalized utility score in [0, 1]. */
+    score: number;
+    tier: ImpactTier;
+    /** Human-readable breakdown of the signals that produced the score. */
+    signals: string[];
+    /**
+     * True when the memory looks like dead weight worth reviewing/pruning:
+     * more rejections than reads, or never used with no guardrail, or already
+     * stale/deprecated/rejected. A memory carrying a `sensor` or with `applied`
+     * outcomes is never a prune candidate — it earns its keep as a guardrail.
+     */
+    pruneCandidate: boolean;
+}
+interface ImpactOptions {
+    /** Days with no read AND no applied outcome after which a memory is "dormant". */
+    dormantDays?: number;
+    now?: Date;
+}
+/** Default dormancy window — half the confidence hard-decay (365d), so impact reacts sooner. */
+declare const DEFAULT_DORMANT_DAYS = 120;
+/**
+ * Compute the demonstrated utility of a single memory from its frontmatter + usage.
+ * Pure and deterministic given `now`.
+ */
+declare function computeImpact(fm: MemoryFrontmatter, usage: MemoryUsage, options?: ImpactOptions): ImpactScore;
+/** Sort comparator: highest impact first, prune candidates last on ties. */
+declare function compareImpact(a: ImpactScore, b: ImpactScore): number;
+interface ImpactSummary {
+    total: number;
+    high: number;
+    medium: number;
+    low: number;
+    dormant: number;
+    prune_candidates: number;
+}
+/** Roll up a set of impact scores into tier counts. */
+declare function summarizeImpact(scores: ImpactScore[]): ImpactSummary;
+
+/**
+ * A rigorous, model-free, repeatable evaluation of hAIve's core promise: surfacing
+ * the right knowledge and guardrails at the right moment. Unlike the agent benchmark
+ * (which parses human-written reports), this is deterministic and CI-runnable — it
+ * produces a chiffré quality score from labeled cases, so a regression in ranking or
+ * sensor coverage fails the build instead of silently degrading every agent session.
+ *
+ * Two case families:
+ *   - RETRIEVAL — given a task (+optional files/symbols), do the expected memories
+ *     surface in the briefing top-k? Measured by recall and mean reciprocal rank.
+ *   - SENSORS — given a known-bad diff, does the expected memory's sensor fire?
+ *     Measured by catch-rate.
+ *
+ * This module is pure: it defines the case/result types, the scoring math, and case
+ * synthesis from a repo's own anchored memories. Orchestration (calling get_briefing
+ * / anti_patterns_check) lives in the CLI, since core cannot depend on the MCP layer.
+ */
+interface RetrievalCase {
+    name: string;
+    task: string;
+    files?: string[];
+    symbols?: string[];
+    /** Memory ids that SHOULD surface in the briefing for this case. */
+    expect_ids: string[];
+}
+interface SensorCase {
+    name: string;
+    /** Unified diff (or added-line text) the sensors run against. */
+    diff: string;
+    paths?: string[];
+    /** Memory ids whose sensor SHOULD fire on this diff. */
+    expect_fire_ids: string[];
+}
+interface EvalSpec {
+    retrieval?: RetrievalCase[];
+    sensors?: SensorCase[];
+}
+interface RetrievalCaseResult {
+    name: string;
+    expect_ids: string[];
+    /** Surfaced memory ids, in ranked order, capped at k. */
+    surfaced_ids: string[];
+    hits: string[];
+    misses: string[];
+    precision: number;
+    recall: number;
+    /** 1-based rank of the first expected id among surfaced ids; null if none surfaced. */
+    best_rank: number | null;
+}
+interface SensorCaseResult {
+    name: string;
+    expect_fire_ids: string[];
+    fired_ids: string[];
+    hits: string[];
+    misses: string[];
+    recall: number;
+}
+interface RetrievalAggregate {
+    cases: RetrievalCaseResult[];
+    mean_precision: number;
+    mean_recall: number;
+    /** Mean reciprocal rank of the first expected hit — rewards ranking the right memory high. */
+    mrr: number;
+}
+interface SensorAggregate {
+    cases: SensorCaseResult[];
+    catch_rate: number;
+}
+interface EvalReport {
+    retrieval: RetrievalAggregate | null;
+    sensors: SensorAggregate | null;
+    /** Overall quality score 0..100. */
+    score: number;
+}
+/**
+ * Score one retrieval case from the (ranked) ids the briefing surfaced.
+ * `surfacedRanked` should already be capped to the top-k the caller cares about.
+ */
+declare function scoreRetrievalCase(name: string, expectIds: string[], surfacedRanked: string[]): RetrievalCaseResult;
+declare function aggregateRetrieval(cases: RetrievalCaseResult[]): RetrievalAggregate;
+declare function scoreSensorCase(name: string, expectFireIds: string[], firedIds: string[]): SensorCaseResult;
+declare function aggregateSensors(cases: SensorCaseResult[]): SensorAggregate;
+/** Combine retrieval + sensor aggregates into a single 0..100 quality score. */
+declare function overallScore(retrieval: RetrievalAggregate | null, sensors: SensorAggregate | null): number;
+declare function buildReport(retrieval: RetrievalAggregate | null, sensors: SensorAggregate | null): EvalReport;
+/** Extract a short task-like title from a memory body (first heading or first line). */
+declare function titleFromBody(body: string): string;
+interface SelfEvalOptions {
+    /** Include each memory's anchor paths as the case files (tests anchored retrieval). */
+    includeFiles?: boolean;
+    /** Skip memories with these statuses (default: stale/deprecated/rejected). */
+    skipStatuses?: string[];
+}
+/**
+ * Synthesize retrieval cases from a repo's own anchored memories — zero-setup eval.
+ * Each anchored, non-recap, non-dead memory becomes a case: "when working on the
+ * file(s) this memory anchors, with its title as the task, does hAIve surface it?".
+ * With `includeFiles: false` it becomes a harder semantic-only probe (title alone).
+ */
+declare function synthesizeSelfEvalCases(memories: LoadedMemory[], options?: SelfEvalOptions): RetrievalCase[];
+
 type ConfidenceLevel = "unverified" | "low" | "trusted" | "authoritative" | "stale";
 interface ConfidenceThresholds {
     trustedReads: number;
@@ -482,6 +718,34 @@ declare function isGlobPath(p: string): boolean;
 declare function globToRegExp(pattern: string): RegExp;
 declare function relPathFrom(root: string, abs: string): string;
 
+/**
+ * Progressive disclosure for `skill` memories.
+ *
+ * Skills are reusable playbooks. Surfacing all of them on every briefing wastes the
+ * instruction budget and buries the relevant one. A skill with an `activation` block
+ * is disclosed ONLY when it is relevant to the current task/files; a skill without
+ * one keeps the legacy always-eligible behavior. This module is pure (no I/O).
+ */
+interface ActivationContext {
+    task?: string;
+    files?: string[];
+}
+interface SkillActivation {
+    applicable: boolean;
+    activated: boolean;
+    reasons: string[];
+}
+declare function isSkill(fm: Pick<MemoryFrontmatter, "type">): boolean;
+/**
+ * Decide whether a skill should be disclosed for the given context.
+ * For non-skills, or skills with no `activation` block, returns `activated: true`
+ * (never suppress them). Otherwise activates on `always`, a keyword substring match
+ * against the task, or a glob match against the edited files.
+ */
+declare function evaluateSkillActivation(fm: Pick<MemoryFrontmatter, "type" | "activation">, ctx: ActivationContext): SkillActivation;
+/** Convenience: true when a skill defines activation triggers that the context does NOT satisfy. */
+declare function isSkillSuppressed(fm: Pick<MemoryFrontmatter, "type" | "activation">, ctx: ActivationContext): boolean;
+
 /**
  * Specificity ("surprise") scoring for memories.
  *
@@ -1153,4 +1417,4 @@ interface SensorSuggestionOptions {
  */
 declare function suggestSensorFromMemory(body: string, anchorPaths: string[], options?: SensorSuggestionOptions): Sensor | null;
 
-export { AUTOPILOT_DEFAULTS, type Anchor, AnchorSchema, type AntiPatternGate, type AutoPromoteRule, BRIEFING_MARKER_TTL_MS, BRIEFING_PRESET_DEFAULTS, type BreakingChange, type BriefingBudgetNumbers, type BriefingBudgetPreset, type BriefingMarker, type BudgetPart, type BudgetSlice, type BuildCodeMapOptions, CHARS_PER_TOKEN, CODE_MAP_FILE, CONFIG_FILE, type CodeExport, type CodeExportKind, type CodeFileEntry, type CodeMap, type CodeMapQueryOptions, type CollectTimelineOpts, type ConfidenceLevel, type ConfidenceThresholds, type ConflictCandidatePair, type ConflictCandidatesOpts, type ContractDiffResult, type ContractFile, type ContractSnapshot, CrossRepoProvenanceSchema, type CrossRepoReport, type CrossRepoSource, DECAY_DAYS, DEFAULT_AUTO_PROMOTE_RULE, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_CONFIG, type DepChange, type DepTrackResult, type DependencySnapshot, GUESSABLE_THRESHOLD, HAIVE_DIR, type HaiveConfig, type HaivePaths, type LexicalRankResult, type LoadedMemory, MEMORIES_DIR, type Memory, type MemoryFrontmatter, MemoryFrontmatterSchema, type MemoryScope, MemoryScopeSchema, type MemoryStatus, MemoryStatusSchema, type MemoryType, MemoryTypeSchema, type MemoryUsage, PROJECT_CONTEXT_FILE, RUNTIME_JOURNAL_FILENAME, type ResolveProjectInfo, type RetirementSignal, type RuntimeJournalEntry, SESSION_RECAP_TTL_MS, STACK_PACK_TAG, type Sensor, type SensorHit, SensorSchema, type SensorSuggestionOptions, type SensorTarget, type TimelineEntry, type TopicStatusPair, type TruncateOptions, type TruncateResult, USAGE_FILE, USAGE_LOG_DIR, USAGE_LOG_FILE, type UsageAggregate, type UsageEvent, type UsageIndex, type VerifyOptions, type VerifyResult, addedLinesFromDiff, aggregateUsage, allocateBudget, antiPatternGateParams, appendRuntimeJournalEntry, appendUsageEvent, briefingMarkerPath, briefingMarkersDir, buildCodeMap, buildFrontmatter, bumpRead, codeMapPath, collectTimelineEntries, compileRegexSensor, configPath, contractLockPath, deriveConfidence, diffContract, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, extractActionsBriefBody, extractSnippet, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, firstMemoryOneLine, getUsage, globToRegExp, hasRecentBriefingMarker, inferModulesFromPaths, isAutoPromoteEligible, isDecaying, isFreshIsoDate, isGlobPath, isLikelyGuessable, isRetiredMemory, isStackPackSeed, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadConfigSync, loadMemoriesFromDir, loadMemory, loadUsageIndex, memoryFilePath, memoryMatchesAnchorPaths, newMemoryId, normalizeSessionId, parseMemory, parseSince, pathsOverlap, pickSnippetNeedle, pullCrossRepoSources, queryCodeMap, rankMemoriesLexical, readRecentBriefingMarker, readRuntimeJournalTail, readUsageEvents, recordRejection, relPathFrom, resolveBriefingBudget, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, runRegexSensor, runSensors, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, sensorAppliesToPath, sensorTargetsFromDiff, serializeMemory, snapshotContract, specificityScore, stripPrivate, suggestSensorFromMemory, suggestTopicKey, tokenizeQuery, trackDependencies, trackReads, truncateToTokens, usageLogPath, usageLogSize, usagePath, verifyAnchor, watchContracts, writeBriefingMarker };
+export { AUTOPILOT_DEFAULTS, type Activation, type ActivationContext, ActivationSchema, type Anchor, AnchorSchema, type AntiPatternGate, type AutoPromoteRule, BRIEFING_MARKER_TTL_MS, BRIEFING_PRESET_DEFAULTS, type BreakingChange, type BriefingBudgetNumbers, type BriefingBudgetPreset, type BriefingMarker, type BudgetPart, type BudgetSlice, type BuildCodeMapOptions, CHARS_PER_TOKEN, CODE_MAP_FILE, CONFIG_FILE, type CodeExport, type CodeExportKind, type CodeFileEntry, type CodeMap, type CodeMapQueryOptions, type CollectTimelineOpts, type ConfidenceLevel, type ConfidenceThresholds, type ConflictCandidatePair, type ConflictCandidatesOpts, type ContractDiffResult, type ContractFile, type ContractSnapshot, CrossRepoProvenanceSchema, type CrossRepoReport, type CrossRepoSource, DECAY_DAYS, DEFAULT_AUTO_PROMOTE_RULE, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_CONFIG, DEFAULT_DORMANT_DAYS, type DepChange, type DepTrackResult, type DependencySnapshot, type EvalReport, type EvalSpec, GUESSABLE_THRESHOLD, HAIVE_DIR, type HaiveConfig, type HaivePaths, type ImpactOptions, type ImpactScore, type ImpactSummary, type ImpactTier, type LexicalRankResult, type LoadedMemory, MEMORIES_DIR, type Memory, type MemoryFrontmatter, MemoryFrontmatterSchema, type MemoryScope, MemoryScopeSchema, type MemoryStatus, MemoryStatusSchema, type MemoryType, MemoryTypeSchema, type MemoryUsage, PROJECT_CONTEXT_FILE, RUNTIME_JOURNAL_FILENAME, type ResolveProjectInfo, type RetirementSignal, type RetrievalAggregate, type RetrievalCase, type RetrievalCaseResult, type RuntimeJournalEntry, SESSION_RECAP_TTL_MS, STACK_PACK_TAG, type SelfEvalOptions, type Sensor, type SensorAggregate, type SensorCase, type SensorCaseResult, type SensorHit, SensorSchema, type SensorSuggestionOptions, type SensorTarget, type SkillActivation, type TimelineEntry, type TopicStatusPair, type TruncateOptions, type TruncateResult, USAGE_FILE, USAGE_LOG_DIR, USAGE_LOG_FILE, type UsageAggregate, type UsageEvent, type UsageIndex, type VerifyOptions, type VerifyResult, addedLinesFromDiff, aggregateRetrieval, aggregateSensors, aggregateUsage, allocateBudget, antiPatternGateParams, appendRuntimeJournalEntry, appendUsageEvent, briefingMarkerPath, briefingMarkersDir, buildCodeMap, buildFrontmatter, buildReport, bumpRead, codeMapPath, collectTimelineEntries, compareImpact, compileRegexSensor, computeImpact, configPath, contractLockPath, deriveConfidence, diffContract, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evaluateSkillActivation, extractActionsBriefBody, extractSnippet, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, firstMemoryOneLine, getUsage, globToRegExp, hasRecentBriefingMarker, inferModulesFromPaths, isAutoPromoteEligible, isDecaying, isFreshIsoDate, isGlobPath, isLikelyGuessable, isRetiredMemory, isSkill, isSkillSuppressed, isStackPackSeed, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadConfigSync, loadMemoriesFromDir, loadMemory, loadUsageIndex, memoryFilePath, memoryMatchesAnchorPaths, newMemoryId, normalizeSessionId, overallScore, parseMemory, parseSince, pathsOverlap, pickSnippetNeedle, pullCrossRepoSources, queryCodeMap, rankMemoriesLexical, readRecentBriefingMarker, readRuntimeJournalTail, readUsageEvents, recordApplied, recordRejection, relPathFrom, resolveBriefingBudget, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, runRegexSensor, runSensors, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, scoreRetrievalCase, scoreSensorCase, sensorAppliesToPath, sensorTargetsFromDiff, serializeMemory, snapshotContract, specificityScore, stripPrivate, suggestSensorFromMemory, suggestTopicKey, summarizeImpact, synthesizeSelfEvalCases, titleFromBody, tokenizeQuery, trackDependencies, trackReads, truncateToTokens, usageLogPath, usageLogSize, usagePath, verifyAnchor, watchContracts, writeBriefingMarker };