fluffy-context 0.7.2 → 0.7.7

package/dist/src/compiler/sources.js

@@ -93,7 +93,7 @@ export async function loadCompilerSources(startPath, options) {
         knowledgeLimit: options.knowledgeLimit ?? 10,
         deadendLimit: options.deadendLimit ?? 10,
         noteLimit: options.noteLimit ?? 20,
-    });
+    }, null);
     const projectRoot = orientation.projectRoot;
     const git = await readGitWorktreeState(projectRoot);
     let events = [];
@@ -110,21 +110,17 @@ export async function loadCompilerSources(startPath, options) {
     return { orientation, anchor, events, workspace, fallbackReason };
 }
 export function latestHostIntent(events, anchor) {
-    return [...events].reverse().find((event) => {
-        if (event.type !== 'host.prompt.submitted')
+    const event = [...events].reverse().find((candidate) => {
+        if (candidate.type !== 'host.prompt.submitted')
             return false;
-        if (event.git.worktreeId !== null && event.git.worktreeId !== anchor.worktreeId)
+        if (candidate.git.worktreeId !== null && candidate.git.worktreeId !== anchor.worktreeId)
             return false;
-        if (event.git.ref !== null && event.git.ref !== anchor.ref)
+        if (candidate.git.ref !== null && candidate.git.ref !== anchor.ref)
             return false;
-        const payload = event.payload;
+        const payload = candidate.payload;
         return typeof payload.intent === 'string' && payload.intent.trim().length > 0;
-    })?.payload
-        ? (() => {
-            const event = [...events].reverse().find((item) => item.type === 'host.prompt.submitted' && item.git.worktreeId === anchor.worktreeId && item.git.ref === anchor.ref && typeof item.payload.intent === 'string');
-            if (!event)
-                return null;
-            return { value: event.payload.intent, eventId: event.eventId };
-        })()
-        : null;
+    });
+    if (!event)
+        return null;
+    return { value: event.payload.intent, eventId: event.eventId };
 }

package/dist/src/compiler/types.d.ts

@@ -2,6 +2,8 @@ import type { CognitionGitAnchor, WorkspacePathChange } from '../cognition/types
 import type { ContextOrientResult } from '../agent/types.js';
 import type { Deadend, Knowledge, Note, ResumeSummary, StructuredContext } from '../runtime/types.js';
 export type ContextScenario = 'resume' | 'implementation' | 'debugging' | 'verification' | 'handoff' | 'exploration' | 'unknown';
+export type ContextLevel = 'signal' | 'summary' | 'structured' | 'evidence';
+export type ContextExpandLevel = 'structured' | 'evidence';
 export type ContextSourceKind = 'current-context' | 'checkpoint' | 'note' | 'journal' | 'knowledge' | 'deadend';
 export type ContextCandidateSection = 'summary' | 'pending' | 'decision' | 'risk' | 'note' | 'knowledge' | 'deadend' | 'activity';
 export type ContextSignalOrigin = 'explicit' | 'deterministic';
@@ -41,6 +43,12 @@ export interface ContextBudget {
     reservedForRenderer: number;
     sections?: Partial<Record<ContextCandidateSection, number>>;
 }
+export interface ContextTokenEstimate {
+    input: number;
+    output: number;
+    unit: 'estimated-tokens';
+    method: 'chars-div-four';
+}
 export interface ContextSourceApplicability {
     project: true;
     branchMode: 'global' | 'exact' | 'unsupported';
@@ -100,6 +108,10 @@ export interface ContextCandidate<T = unknown> {
     selectedChars: number;
     selected: boolean;
     truncated: boolean;
+    level: ContextLevel;
+    itemHash: string;
+    tokenEstimate: number;
+    expandable: boolean;
 }
 export type ContextExclusionReason = 'no_active_context' | 'context_mismatch' | 'status_not_verified' | 'not_open' | 'absorbed' | 'applicability_mismatch' | 'scope_mismatch' | 'path_mismatch' | 'query_no_match' | 'result_limit' | 'budget' | 'unsupported_applicability' | 'v2_unavailable';
 export interface ContextExclusion {
@@ -138,6 +150,11 @@ export interface ContextManifestProvenance {
     selectedEventIds: string[];
     fallbackReason: string | null;
 }
+export interface ContextManifestIdentity {
+    manifestHash: string;
+    selectedItemHashes: string[];
+    tokenEstimate: ContextTokenEstimate;
+}
 export interface ContextCompileOptions {
     contextId?: string;
     query?: string;
@@ -154,9 +171,37 @@ export interface ContextCompileOptions {
     sessionId?: string;
     eventId?: string;
 }
+export interface ContextExpandInput {
+    manifestHash: string;
+    candidateId?: string;
+    itemHash?: string;
+    level: ContextExpandLevel;
+    maxChars?: number;
+    compile: ContextCompileOptions;
+}
+export interface ContextExpandResult {
+    status: 'complete' | 'partial';
+    projectRoot: string;
+    manifestHash: string;
+    candidateId: string;
+    itemHash: string;
+    previousLevel: ContextLevel;
+    requestedLevel: ContextExpandLevel;
+    resolvedLevel: ContextExpandLevel;
+    source: ContextSourceDescriptor;
+    content: unknown | null;
+    text: string;
+    budget: {
+        requestedChars: number;
+        usedChars: number;
+        remainingChars: number;
+        truncated: boolean;
+    };
+    provenance: ContextManifestProvenance;
+}
 export interface ContextManifest {
     schemaVersion: 1;
-    compilerVersion: '0.7.2';
+    compilerVersion: '0.7.7';
     rankingVersion: 'compiler-ranking-v2';
     status: 'ready' | 'no_context';
     projectRoot: string;
@@ -178,6 +223,7 @@ export interface ContextManifest {
     };
     selected: ContextCandidate[];
     excluded: ContextExclusion[];
+    identity: ContextManifestIdentity;
     budget: ContextBudgetReport;
     truncation: ContextTruncation;
     provenance: ContextManifestProvenance;

package/dist/src/mcp/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { contextOrient } from '../agent/api.js';
+import { addNote, listNotes } from '../runtime/notes.js';
+import { contextCompile, contextExpand, contextOrient, contextUsageReport, loadContext, saveContext } from '../agent/api.js';
 import { ensureRuntimeForSession } from '../cognition/runtime.js';
 import { VERSION } from '../version.js';
 const orientInput = z.object({
@@ -13,29 +14,203 @@ const orientInput = z.object({
     deadendLimit: z.int().nonnegative().optional(),
     noteLimit: z.int().nonnegative().optional(),
 });
+const scenario = z.enum(['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']);
+const trigger = z.enum(['session-start', 'prompt', 'manual', 'tool-call']);
+const noteKind = z.enum(['problem', 'action', 'observation', 'decision']);
+const noteActor = z.enum(['agent', 'human']);
+const noteStatus = z.enum(['open', 'resolved']);
+const compileOptions = z.object({
+    contextId: z.string().optional(),
+    query: z.string().optional(),
+    scenario: scenario.optional(),
+    scope: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    maxChars: z.int().nonnegative().optional(),
+    knowledgeLimit: z.int().nonnegative().optional(),
+    deadendLimit: z.int().nonnegative().optional(),
+    noteLimit: z.int().nonnegative().optional(),
+    activityLimit: z.int().nonnegative().optional(),
+    trigger: trigger.optional(),
+    adapter: z.string().optional(),
+    sessionId: z.string().optional(),
+    eventId: z.string().optional(),
+});
+const expandInput = z.object({
+    path: z.string().optional(),
+    manifestHash: z.string(),
+    candidateId: z.string().optional(),
+    itemHash: z.string().optional(),
+    level: z.enum(['structured', 'evidence']),
+    maxChars: z.int().nonnegative().optional(),
+    compile: compileOptions,
+});
+const compileInput = z.object({ path: z.string().optional(), ...compileOptions.shape });
+const resumeInput = z.object({
+    path: z.string().optional(),
+    contextId: z.string().optional(),
+    maxChars: z.int().nonnegative().optional(),
+    includeDetails: z.boolean().optional(),
+    query: z.string().optional(),
+    scope: z.string().optional(),
+});
+const noteListInput = z.object({
+    path: z.string().optional(),
+    contextId: z.string().optional(),
+    openOnly: z.boolean().optional(),
+    limit: z.int().nonnegative().optional(),
+    maxChars: z.int().nonnegative().optional(),
+});
+const noteAddInput = z.object({
+    path: z.string().optional(),
+    message: z.string(),
+    kind: noteKind.optional(),
+    actor: noteActor.optional(),
+    contextId: z.string().optional(),
+    snapshotId: z.string().optional(),
+    relatedFiles: z.array(z.string()).optional(),
+    status: noteStatus.optional(),
+});
+const checkpointInput = z.object({
+    path: z.string().optional(),
+    contextId: z.string().optional(),
+    absorbNotes: z.boolean().optional(),
+    title: z.string().optional(),
+    progressSummary: z.string().optional(),
+    lastError: z.string().nullable().optional(),
+    completed: z.array(z.string()).optional(),
+    pendingTasks: z.array(z.string()).optional(),
+    decisions: z.array(z.string()).optional(),
+    risks: z.array(z.string()).optional(),
+    relatedFiles: z.array(z.string()).optional(),
+});
+const usageReportInput = z.object({
+    path: z.string().optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    days: z.int().nonnegative().optional(),
+    month: z.string().optional(),
+    granularity: z.enum(['day', 'week', 'month']).optional(),
+    baselineTokens: z.number().nonnegative().optional(),
+    baselineSource: z.enum(['manual', 'recorded-control']).optional(),
+});
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function successResponse(result) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+        structuredContent: result,
+    };
+}
+function failureResponse(tool, error) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: `${tool} failed: ${errorMessage(error)}` }],
+    };
+}
 export function createMcpServer() {
     const server = new McpServer({ name: 'fluffy-context', version: VERSION });
     server.registerTool('context_orient', {
         title: 'Orient context',
-        description: 'Load bounded, read-only task context with verified consensus and open notes.',
+        description: 'Load bounded, read-only task context with verified consensus and open notes. Compiler manifests expose deterministic levels, hashes, and estimated tokens through the Agent API and CLI.',
         inputSchema: orientInput,
     }, async ({ path, ...options }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            const result = await contextOrient(path, options);
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result) }],
-                structuredContent: result,
-            };
+            return successResponse(await contextOrient(path, options, 'mcp'));
+        }
+        catch (error) {
+            return failureResponse('context_orient', error);
+        }
+    });
+    server.registerTool('context_expand', {
+        title: 'Expand context candidate',
+        description: 'Read a selected compiler candidate at structured or evidence level without writing project state or reading file contents.',
+        inputSchema: expandInput,
+    }, async ({ path, ...input }) => {
+        try {
+            await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
+            return successResponse(await contextExpand(path, input, 'mcp'));
+        }
+        catch (error) {
+            return failureResponse('context_expand', error);
+        }
+    });
+    server.registerTool('context_compile', {
+        title: 'Compile context manifest',
+        description: 'Compile a bounded, deterministic, read-only context manifest without writing project state or reading file contents.',
+        inputSchema: compileInput,
+    }, async ({ path, ...options }) => {
+        try {
+            await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
+            return successResponse(await contextCompile(path, options, 'mcp'));
+        }
+        catch (error) {
+            return failureResponse('context_compile', error);
+        }
+    });
+    server.registerTool('context_resume', {
+        title: 'Resume context',
+        description: 'Resume the selected active context with a bounded summary and optional details. This may update the existing lastUsedAt field.',
+        inputSchema: resumeInput,
+    }, async ({ path, ...options }) => {
+        try {
+            await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
+            return successResponse(await loadContext(path, options, 'mcp'));
+        }
+        catch (error) {
+            return failureResponse('context_resume', error);
+        }
+    });
+    server.registerTool('context_note_list', {
+        title: 'List context notes',
+        description: 'List bounded notes without modifying project state or absorbing or resolving notes.',
+        inputSchema: noteListInput,
+    }, async ({ path, ...query }) => {
+        try {
+            await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
+            return successResponse({ notes: await listNotes(path, query) });
+        }
+        catch (error) {
+            return failureResponse('context_note_list', error);
+        }
+    });
+    server.registerTool('context_note_add', {
+        title: 'Add context note',
+        description: 'Append one explicit note to project state. This writes the local context store but does not create a Snapshot.',
+        inputSchema: noteAddInput,
+    }, async ({ path, message, ...input }) => {
+        try {
+            await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
+            return successResponse(await addNote(path, message, input));
+        }
+        catch (error) {
+            return failureResponse('context_note_add', error);
+        }
+    });
+    server.registerTool('context_usage_report', {
+        title: 'Context usage report',
+        description: 'Build a read-only report of context assets, explicit reuse, estimated token investment, and operation metrics.',
+        inputSchema: usageReportInput,
+    }, async ({ path, ...options }) => {
+        try {
+            return successResponse(await contextUsageReport(path, options));
+        }
+        catch (error) {
+            return failureResponse('context_usage_report', error);
+        }
+    });
+    server.registerTool('context_checkpoint', {
+        title: 'Checkpoint context',
+        description: 'Explicitly save context progress and create a Snapshot when changes are present; runtime rate limits remain enforced.',
+        inputSchema: checkpointInput,
+    }, async ({ path, ...input }) => {
+        try {
+            await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
+            return successResponse(await saveContext(path, input));
         }
         catch (error) {
-            return {
-                isError: true,
-                content: [{ type: 'text', text: `context_orient failed: ${errorMessage(error)}` }],
-            };
+            return failureResponse('context_checkpoint', error);
         }
     });
     return server;

package/dist/src/runtime/runtime.js

@@ -253,6 +253,16 @@ export async function checkpoint(startPath, input, options = {}) {
         }
         const content = await contextFromInput(projectRoot, input, previous);
         const patch = diffContext(previous, content);
+        const hasContent = content.progressSummary.length > 0
+            || content.lastError !== null
+            || content.completed.length > 0
+            || content.pendingTasks.length > 0
+            || content.decisions.length > 0
+            || content.risks.length > 0
+            || content.relatedFiles.length > 0;
+        if (!hasContent && !previousSnapshot) {
+            return { status: 'no_change', context, snapshot: null };
+        }
         if (previousSnapshot && Object.keys(patch).length === 0)
             return { status: 'no_change', context, snapshot: previousSnapshot };
         const minSaveIntervalMs = options.minSaveIntervalMs ?? 10_000;

package/dist/src/runtime/types.d.ts

@@ -304,7 +304,7 @@ export type CheckpointResult = {
 } | {
     status: 'no_change';
     context: ContextMetadata;
-    snapshot: Snapshot;
+    snapshot: Snapshot | null;
 } | {
     status: 'rate_limited';
     context: ContextMetadata;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.7.2";
+export declare const VERSION = "0.7.7";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.7.2';
+export const VERSION = '0.7.7';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "0.7.2",
+  "version": "0.7.7",
   "description": "Local context management CLI and MCP tools for AI coding agents",
   "license": "MIT",
   "author": "FluffyChi-Xing",

package/skills/fluffy-context/SKILL.md

@@ -19,9 +19,16 @@ compatibility: 需要 Node.js >=20.19.0；Git 可选。CLI 通过 npm 全局安
 - 仅需要完整详情时再运行 `ctx resume --max-chars <预算>`；它会保留既有的 `lastUsedAt` 更新语义。
 - Agent 集成从 `fluffy-context` 或 `fluffy-context/agent` 导入 `contextOrient`、`compileContext`、`saveContext`、`loadContext` 和 `searchContext`，不应直接读写 `.context` 或导入内部 `dist/...` 路径。
 - `ctx compile` 的 `activity` section 只表示 Runtime 观察到的近期文件 metadata 变化；它不代表文件被读取或理解，也不替代 checkpoint、Note 或已验证 Knowledge。
+- 0.7.7 的 Compiler Manifest 提供稳定 `identity.manifestHash`、候选 `itemHash`、`tokenEstimate` 和 `level` 契约；默认输出 `summary` 层。
+- 只对 selected candidate 使用 `ctx expand --manifest-hash ... --candidate-id ... --level structured|evidence`。必须带上原始 compile 参数和相同的 compile budget；Manifest 过期时应重新 compile，不要绕过 hash 校验。
+- `expand` 是无状态、只读的渐进式展开：`complete` 才提供完整 `content`，`partial` 提供有界 `text` 且 `content` 为 null。它不写入 Context/journal、不记录 feedback、不读取项目文件正文、diff、命令输出或敏感数据。Agent API 使用 `contextExpand`，MCP 使用 `context_expand`。
 - 新任务先发现已验证共识，再开始实现；候选项只在显式审查时使用。
 - 普通查询只使用已验证 Knowledge 和 Deadend；需要审查候选项时显式使用 `--all`。
 - CLI 业务命令的标准输出是 JSON；错误写入标准错误并返回非零退出码。解析输出时不要把 `--help` 的纯文本当作 JSON。
+- 每周或每月复盘时使用 `ctx usage report`，不要为每条 prompt 运行；它只读 journal 和 v1 数据，不创建事件或修改项目状态。
+- Report 中的 `chars / 4` 是明确标注的 estimated token，不是真实 Provider token；Provider token 和计费金额当前 unavailable。
+- 只有显式 `record.used` 才算 Knowledge/Deadend reuse；compile 命中或 orient 返回不等于复用。
+- 没有显式 baseline 时，report 不生成 savings、ROI 或 payback 数字；report 不能替代 `doctor`、`journal verify` 或人工治理。
 
 ## 快速工作流
 
@@ -43,6 +50,21 @@ ctx learn ... / ctx deadend ... → 显式 verify
 
 `ctx orient` 不带查询时也有效，用于恢复当前任务和 open Note。带查询时只发现已验证的 Knowledge 与 Deadend；不要以候选项驱动普通实现。
 
+### Usage report
+
+在阶段性复盘、周报或月报时运行只读观测报告：
+
+```bash
+ctx usage report --days 30
+ctx usage report --month 2026-08 --granularity week
+ctx usage report --since 2026-08-01T00:00:00.000Z --until 2026-09-01T00:00:00.000Z --baseline-tokens 12000 --baseline-source manual
+ctx usage report --format ascii
+```
+
+JSON 是默认输出；`--format ascii` 仅用于终端展示。报告分别统计 v1 文件资产和 v2 journal 事件，展示 Knowledge、Deadend、Note、Context、Snapshot、显式 reuse、操作趋势与 estimated token 投入。`record.used` 是唯一的 reuse 信号，候选项命中、compile 选择和普通检索都不算复用。
+
+`--baseline-tokens` 必须是显式对照输入。未提供 baseline 时 savings、ROI 和 payback 为 `null` 或 `no_baseline`；字符换算不代表 Provider 真实 token，也不提供默认单价。报告失败时应使用 `ctx doctor` 与 `ctx journal verify` 进一步诊断，而不是把 report 当作数据修复工具。
+
 ### 初始化
 
 ```bash
@@ -100,7 +122,9 @@ ctx resume --path path/to/project --max-chars 2000
 
 ## MCP 与 Claude Code 集成
 
-`ctx agent serve` 提供 MCP stdio server，注册 `context_orient` 工具。标准输入和输出都是 MCP 协议，不能输出提示、日志或交互文本；调用错误是单次工具错误，不应让 server 退出。
+`ctx agent serve` 提供 MCP stdio server，注册以下工具：`context_orient`、`context_expand`、`context_compile`、`context_resume`、`context_note_list`、`context_note_add`、`context_usage_report` 和 `context_checkpoint`。标准输入和输出都是 MCP 协议，不能输出提示、日志或交互文本；调用错误是单次工具错误，不应让 server 退出。
+
+读取工作流通常是 `context_orient → context_compile → context_expand`。`context_compile` 与 `context_expand` 继续保持有界、确定性和不读取文件正文的边界；`context_resume` 复用 `loadContext`，可能更新 `lastUsedAt`。`context_note_list` 是只读的，`context_note_add` 和 `context_checkpoint` 是显式写入操作，分别新增 Note 或保存 Snapshot；它们不会自动记录 feedback、Knowledge、Deadend 或重复 checkpoint。Knowledge/Deadend 的完整记录和治理仍使用 CLI/Agent API。
 
 ```bash
 ctx agent serve
@@ -336,7 +360,9 @@ ctx learn "订单取消后不能再次进入支付中状态"
 [ ] .contextignored 排除敏感和越界路径
 [ ] Knowledge candidate → verified
 [ ] Deadend candidate → verified
-[ ] MCP context_orient 的 no_context 和单次错误不会终止 server
+[ ] MCP context_orient/context_expand/context_compile/context_resume/context_note_list/context_note_add/context_usage_report/context_checkpoint 可调用，且单次错误不会终止 server
+[ ] ctx usage report 的 JSON/ASCII 输出、baseline 边界和只读性符合预期
+[ ] MCP 只读工具不写入 Context；Note add 和 checkpoint 仅在显式调用时写入
 [ ] Claude 集成预览不写文件，--apply 幂等且拒绝冲突
 [ ] Hook 失败时 fail open，且不会自动 checkpoint
 [ ] npm pack 的安装包可运行 ctx 并导入 contextOrient