fluffy-context 0.7.6 → 0.8.0

package/dist/src/agent/api.js

@@ -4,11 +4,17 @@ import { contextsRoot, contextMetadataPath } from '../storage/layout.js';
 import { isRecord, readJson } from '../storage/json-store.js';
 import { checkpoint, rebuildSnapshot, resume, resumeSnapshot } from '../runtime/runtime.js';
 import { recordUse } from '../cognition/feedback.js';
+import { inspectRecipe, listRecipes, materializeRecipe, transitionRecipe } from '../cognition/recipes.js';
+import { inspectSkill, listSkills, materializeSkill, recordSkillInvocation, recordSkillOutcome, transitionSkill } from '../cognition/skills.js';
+import { acceptEvolutionCandidate, inspectEvolutionProposal, listEvolutionProposals, proposeEvolution, transitionEvolutionProposal } from '../cognition/evolution.js';
 import { selectV2Orientation } from '../cognition/orient.js';
 import { discoverV2Deadends, discoverV2Knowledge } from '../cognition/retrieval.js';
 import { discoverDeadends, discoverKnowledge, listDeadends } from '../runtime/knowledge.js';
 import { listNotes } from '../runtime/notes.js';
 import { expandContext } from '../compiler/expand.js';
+import { compileContext } from '../compiler/compile.js';
+import { withUsageTelemetry } from '../cognition/usage.js';
+import { buildUsageReport } from '../cognition/usage-report.js';
 function normalized(value) {
     return value.trim().toLocaleLowerCase();
 }
@@ -139,155 +145,201 @@ export async function saveContext(startPath, input, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     return { projectRoot, result: await checkpoint(projectRoot, input, options) };
 }
-export async function contextExpand(startPath, input) {
-    const projectRoot = await resolveProjectRoot(startPath);
-    return expandContext(projectRoot, input);
+export async function contextExpand(startPath, input, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'expand', 'agent', input, () => resolveProjectRoot(startPath).then((projectRoot) => expandContext(projectRoot, input)), interfaceName);
 }
-export async function loadContext(startPath, options = {}) {
-    const projectRoot = await resolveProjectRoot(startPath);
-    const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);
-    const knowledge = options.query === undefined ? null : await discoverKnowledge(projectRoot, options.query, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
-    const verifiedDeadends = await listDeadends(projectRoot);
-    return {
-        projectRoot,
-        context: result.context,
-        snapshot: result.snapshot,
-        resumeSummary: result.resumeSummary,
-        ...(options.includeDetails ? { details: result.details } : {}),
-        knowledge,
-        verifiedDeadendIds: verifiedDeadends.map((item) => item.deadendId),
-    };
+export async function contextCompile(startPath, options = {}, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'compile', 'agent', options, () => compileContext(startPath, options), interfaceName);
 }
-export async function contextOrient(startPath, options = {}) {
-    const projectRoot = await resolveProjectRoot(startPath);
-    const query = options.query === undefined ? null : options.query.trim();
-    if (query === '')
-        throw new Error('context orient query must not be empty');
-    let loaded;
-    try {
-        const v2 = await selectV2Orientation(projectRoot, options.contextId);
-        loaded = v2
-            ? await resumeSnapshot(projectRoot, v2.contextId, v2.snapshotId, options.maxChars ?? 4000)
-            : await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
-    }
-    catch (error) {
-        if (error instanceof Error && error.message === 'no active context found') {
-            return {
-                status: 'no_context',
-                projectRoot,
-                query,
-                context: null,
-                snapshot: null,
-                resumeSummary: null,
-                knowledge: emptyKnowledge(query ?? ''),
-                deadends: emptyDeadends(query ?? ''),
-                notes: [],
-                truncated: false,
-                explanation: {
-                    mode: 'v1-fallback',
-                    selection: 'v1',
-                    retrieval: { knowledge: {}, deadends: {} },
-                    truncation: { summary: false, knowledge: false, deadends: false, notes: false },
-                },
-            };
+export async function loadContext(startPath, options = {}, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'resume', 'agent', options, async () => {
+        const projectRoot = await resolveProjectRoot(startPath);
+        const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);
+        const knowledge = options.query === undefined ? null : await discoverKnowledge(projectRoot, options.query, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+        const verifiedDeadends = await listDeadends(projectRoot);
+        return {
+            projectRoot,
+            context: result.context,
+            snapshot: result.snapshot,
+            resumeSummary: result.resumeSummary,
+            ...(options.includeDetails ? { details: result.details } : {}),
+            knowledge,
+            verifiedDeadendIds: verifiedDeadends.map((item) => item.deadendId),
+        };
+    }, interfaceName);
+}
+export async function contextOrient(startPath, options = {}, interfaceName = 'agent') {
+    const action = async () => {
+        const projectRoot = await resolveProjectRoot(startPath);
+        const query = options.query === undefined ? null : options.query.trim();
+        if (query === '')
+            throw new Error('context orient query must not be empty');
+        let loaded;
+        try {
+            const v2 = await selectV2Orientation(projectRoot, options.contextId);
+            loaded = v2
+                ? await resumeSnapshot(projectRoot, v2.contextId, v2.snapshotId, options.maxChars ?? 4000)
+                : await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
         }
-        throw error;
-    }
-    const v2 = await selectV2Orientation(projectRoot, options.contextId);
-    const notes = (await listNotes(projectRoot, {
-        contextId: loaded.context.id,
-        openOnly: true,
-        limit: v2 ? Number.MAX_SAFE_INTEGER : options.noteLimit ?? 20,
-        maxChars: options.maxChars ?? 4000,
-    })).filter((note) => !v2 || v2.noteIds.has(note.noteId)).slice(0, options.noteLimit ?? 20);
-    const v2Knowledge = query === null || !v2 ? null : discoverV2Knowledge(v2.retrieval, query, v2.currentGit, {
-        scope: options.scope,
-        limit: options.knowledgeLimit ?? 10,
-        maxChars: options.maxChars ?? 4000,
-    });
-    const v2Deadends = query === null || !v2 ? null : discoverV2Deadends(v2.retrieval, query, v2.currentGit, {
-        scope: options.scope,
-        limit: options.deadendLimit ?? 10,
-        maxChars: options.maxChars ?? 4000,
-    });
-    const applicableKnowledge = query === null
-        ? emptyKnowledge('')
-        : v2Knowledge?.result ?? await discoverKnowledge(projectRoot, query, {
+        catch (error) {
+            if (error instanceof Error && error.message === 'no active context found') {
+                return {
+                    status: 'no_context',
+                    projectRoot,
+                    query,
+                    context: null,
+                    snapshot: null,
+                    resumeSummary: null,
+                    knowledge: emptyKnowledge(query ?? ''),
+                    deadends: emptyDeadends(query ?? ''),
+                    notes: [],
+                    truncated: false,
+                    explanation: {
+                        mode: 'v1-fallback',
+                        selection: 'v1',
+                        retrieval: { knowledge: {}, deadends: {} },
+                        truncation: { summary: false, knowledge: false, deadends: false, notes: false },
+                    },
+                };
+            }
+            throw error;
+        }
+        const v2 = await selectV2Orientation(projectRoot, options.contextId);
+        const notes = (await listNotes(projectRoot, {
+            contextId: loaded.context.id,
+            openOnly: true,
+            limit: v2 ? Number.MAX_SAFE_INTEGER : options.noteLimit ?? 20,
+            maxChars: options.maxChars ?? 4000,
+        })).filter((note) => !v2 || v2.noteIds.has(note.noteId)).slice(0, options.noteLimit ?? 20);
+        const v2Knowledge = query === null || !v2 ? null : discoverV2Knowledge(v2.retrieval, query, v2.currentGit, {
             scope: options.scope,
             limit: options.knowledgeLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
-    const applicableDeadends = query === null
-        ? emptyDeadends('')
-        : v2Deadends?.result ?? await discoverDeadends(projectRoot, query, {
+        const v2Deadends = query === null || !v2 ? null : discoverV2Deadends(v2.retrieval, query, v2.currentGit, {
             scope: options.scope,
             limit: options.deadendLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
-    const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
-    const resumeSummary = {
-        progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
-        lastError: loaded.resumeSummary.lastError === null ? null : limited(loaded.resumeSummary.lastError, budget),
-        completed: limitedList(loaded.resumeSummary.completed, budget),
-        pendingTasks: limitedList(loaded.resumeSummary.pendingTasks, budget),
-        decisions: limitedList(loaded.resumeSummary.decisions, budget),
-        risks: limitedList(loaded.resumeSummary.risks, budget),
-        relatedFiles: limitedList(loaded.resumeSummary.relatedFiles, budget),
-        branchOrCommitDrift: loaded.resumeSummary.branchOrCommitDrift,
-    };
-    const resumeTruncated = textLength(resumeSummary.progressSummary) < textLength(loaded.resumeSummary.progressSummary)
-        || textLength(resumeSummary.lastError) < textLength(loaded.resumeSummary.lastError)
-        || textLength(resumeSummary.completed) < textLength(loaded.resumeSummary.completed)
-        || textLength(resumeSummary.pendingTasks) < textLength(loaded.resumeSummary.pendingTasks)
-        || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
-        || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
-        || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
-    const limitedKnowledgeResult = limitKnowledge(applicableKnowledge, budget);
-    const limitedDeadendResult = limitDeadends(applicableDeadends, budget);
-    const limitedNotesResult = limitNotes(notes, budget);
-    return {
-        status: 'ready',
-        projectRoot,
-        query,
-        context: {
-            id: loaded.context.id,
-            title: loaded.context.title,
-            status: loaded.context.status,
-            branch: loaded.context.branch,
-            commit: loaded.context.commit,
-            updatedAt: loaded.context.updatedAt,
-        },
-        snapshot: {
-            snapshotId: loaded.snapshot.snapshotId,
-            mode: loaded.snapshot.mode,
-            createdAt: loaded.snapshot.createdAt,
-            branch: loaded.snapshot.branch,
-            commit: loaded.snapshot.commit,
-        },
-        resumeSummary,
-        knowledge: limitedKnowledgeResult.result,
-        deadends: limitedDeadendResult.result,
-        notes: limitedNotesResult.notes,
-        truncated: resumeTruncated || limitedKnowledgeResult.truncated || limitedDeadendResult.truncated || limitedNotesResult.truncated,
-        explanation: {
-            mode: v2 ? 'v2' : 'v1-fallback',
-            selection: v2?.selection ?? 'v1',
-            retrieval: {
-                knowledge: v2Knowledge?.exclusions ?? {},
-                deadends: v2Deadends?.exclusions ?? {},
+        const applicableKnowledge = query === null
+            ? emptyKnowledge('')
+            : v2Knowledge?.result ?? await discoverKnowledge(projectRoot, query, {
+                scope: options.scope,
+                limit: options.knowledgeLimit ?? 10,
+                maxChars: options.maxChars ?? 4000,
+            });
+        const applicableDeadends = query === null
+            ? emptyDeadends('')
+            : v2Deadends?.result ?? await discoverDeadends(projectRoot, query, {
+                scope: options.scope,
+                limit: options.deadendLimit ?? 10,
+                maxChars: options.maxChars ?? 4000,
+            });
+        const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
+        const resumeSummary = {
+            progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
+            lastError: loaded.resumeSummary.lastError === null ? null : limited(loaded.resumeSummary.lastError, budget),
+            completed: limitedList(loaded.resumeSummary.completed, budget),
+            pendingTasks: limitedList(loaded.resumeSummary.pendingTasks, budget),
+            decisions: limitedList(loaded.resumeSummary.decisions, budget),
+            risks: limitedList(loaded.resumeSummary.risks, budget),
+            relatedFiles: limitedList(loaded.resumeSummary.relatedFiles, budget),
+            branchOrCommitDrift: loaded.resumeSummary.branchOrCommitDrift,
+        };
+        const resumeTruncated = textLength(resumeSummary.progressSummary) < textLength(loaded.resumeSummary.progressSummary)
+            || textLength(resumeSummary.lastError) < textLength(loaded.resumeSummary.lastError)
+            || textLength(resumeSummary.completed) < textLength(loaded.resumeSummary.completed)
+            || textLength(resumeSummary.pendingTasks) < textLength(loaded.resumeSummary.pendingTasks)
+            || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
+            || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
+            || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
+        const limitedKnowledgeResult = limitKnowledge(applicableKnowledge, budget);
+        const limitedDeadendResult = limitDeadends(applicableDeadends, budget);
+        const limitedNotesResult = limitNotes(notes, budget);
+        return {
+            status: 'ready',
+            projectRoot,
+            query,
+            context: {
+                id: loaded.context.id,
+                title: loaded.context.title,
+                status: loaded.context.status,
+                branch: loaded.context.branch,
+                commit: loaded.context.commit,
+                updatedAt: loaded.context.updatedAt,
             },
-            truncation: {
-                summary: resumeTruncated,
-                knowledge: limitedKnowledgeResult.truncated,
-                deadends: limitedDeadendResult.truncated,
-                notes: limitedNotesResult.truncated,
+            snapshot: {
+                snapshotId: loaded.snapshot.snapshotId,
+                mode: loaded.snapshot.mode,
+                createdAt: loaded.snapshot.createdAt,
+                branch: loaded.snapshot.branch,
+                commit: loaded.snapshot.commit,
             },
-        },
+            resumeSummary,
+            knowledge: limitedKnowledgeResult.result,
+            deadends: limitedDeadendResult.result,
+            notes: limitedNotesResult.notes,
+            truncated: resumeTruncated || limitedKnowledgeResult.truncated || limitedDeadendResult.truncated || limitedNotesResult.truncated,
+            explanation: {
+                mode: v2 ? 'v2' : 'v1-fallback',
+                selection: v2?.selection ?? 'v1',
+                retrieval: {
+                    knowledge: v2Knowledge?.exclusions ?? {},
+                    deadends: v2Deadends?.exclusions ?? {},
+                },
+                truncation: {
+                    summary: resumeTruncated,
+                    knowledge: limitedKnowledgeResult.truncated,
+                    deadends: limitedDeadendResult.truncated,
+                    notes: limitedNotesResult.truncated,
+                },
+            },
+        };
     };
+    return interfaceName === null
+        ? action()
+        : withUsageTelemetry(startPath, 'orient', 'agent', options, action, interfaceName);
+}
+export async function contextUsageReport(startPath, options = {}) {
+    return buildUsageReport(startPath, options);
 }
 export async function recordContextUse(startPath, input) {
     return recordUse(startPath, input);
 }
+export { inspectRecipe, inspectSkill, listRecipes, listSkills };
+export async function proposeContextEvolution(startPath, input = {}) {
+    return proposeEvolution(startPath, input);
+}
+export async function listContextEvolutionProposals(startPath) {
+    return listEvolutionProposals(startPath);
+}
+export async function inspectContextEvolutionProposal(startPath, proposalId) {
+    return inspectEvolutionProposal(startPath, proposalId);
+}
+export async function acceptContextEvolutionCandidate(startPath, input) {
+    return acceptEvolutionCandidate(startPath, input);
+}
+export async function transitionContextEvolutionProposal(startPath, input) {
+    return transitionEvolutionProposal(startPath, input);
+}
+export async function materializeContextRecipe(startPath, input) {
+    return materializeRecipe(startPath, input);
+}
+export async function transitionContextRecipe(startPath, input) {
+    return transitionRecipe(startPath, input);
+}
+export async function materializeContextSkill(startPath, input) {
+    return materializeSkill(startPath, input);
+}
+export async function transitionContextSkill(startPath, input) {
+    return transitionSkill(startPath, input);
+}
+export async function recordContextSkillInvocation(startPath, input) {
+    return recordSkillInvocation(startPath, input);
+}
+export async function recordContextSkillOutcome(startPath, input) {
+    return recordSkillOutcome(startPath, input);
+}
 export async function searchContext(startPath, query, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     const cleanQuery = query.trim();

package/dist/src/agent/index.d.ts

@@ -1,6 +1,12 @@
 export * from './api.js';
+export type { MaterializeRecipeInput, TransitionRecipeInput, } from '../cognition/recipes.js';
+export type { MaterializeSkillInput, RecordSkillInvocationInput, RecordSkillOutcomeInput, TransitionSkillInput, } from '../cognition/skills.js';
+export type { AcceptEvolutionCandidateInput, ProposeEvolutionInput, ProposeEvolutionResult, TransitionEvolutionProposalInput, } from '../cognition/evolution.js';
+export type { EvolutionCandidateArtifact, EvolutionLineageReference, EvolutionProposal, EvolutionProposalState, Experience, } from '../cognition/types.js';
 export type { ContextOrientContext, ContextUseInput, ContextOrientExplanation, ContextOrientNoContextResult, ContextOrientOptions, ContextOrientReadyResult, ContextOrientResult, ContextOrientSnapshot, } from './types.js';
 export type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, ContextSearchHit, ContextSearchOptions, ContextSearchResult, } from '../runtime/types.js';
+export { contextCompile } from './api.js';
 export { compileContext } from '../compiler/compile.js';
 export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';
-export type { ContextActivityRecord, ContextAnchor, ContextBudget, ContextBudgetReport, ContextCandidate, ContextCandidateSection, ContextCompileOptions, ContextExpandInput, ContextExpandLevel, ContextExpandResult, ContextExclusion, ContextExclusionReason, ContextIntent, ContextIntentSignal, ContextLevel, ContextManifest, ContextProvenance, ContextScenario, ContextSourceDescriptor, ContextTruncation, } from '../compiler/types.js';
+export type { ContextActivityRecord, ContextAnchor, ContextBudget, ContextBudgetReport, ContextCandidate, ContextCandidateSection, ContextCompileOptions, ContextRecipeParticipation, ContextExpandInput, ContextExpandLevel, ContextExpandResult, ContextExclusion, ContextExclusionReason, ContextIntent, ContextIntentSignal, ContextLevel, ContextManifest, ContextProvenance, ContextScenario, ContextSourceDescriptor, ContextTruncation, } from '../compiler/types.js';
+export type { CompilerRecipe, CompilerRecipeState } from '../cognition/types.js';

package/dist/src/agent/index.js

@@ -1,3 +1,4 @@
 export * from './api.js';
+export { contextCompile } from './api.js';
 export { compileContext } from '../compiler/compile.js';
 export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';