fluffy-context 0.6.0 → 0.7.6

package/dist/src/mcp/server.js

@@ -1,6 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { contextOrient } from '../agent/api.js';
+import { compileContext } from '../compiler/compile.js';
+import { addNote, listNotes } from '../runtime/notes.js';
+import { contextExpand, contextOrient, loadContext, saveContext } from '../agent/api.js';
+import { ensureRuntimeForSession } from '../cognition/runtime.js';
 import { VERSION } from '../version.js';
 const orientInput = z.object({
     path: z.string().optional(),
@@ -12,28 +15,181 @@ 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(),
+});
 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 {
-            const result = await contextOrient(path, options);
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result) }],
-                structuredContent: result,
-            };
+            await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
+            return successResponse(await contextOrient(path, options));
+        }
+        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));
+        }
+        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 compileContext(path, options));
+        }
+        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));
+        }
+        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_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/storage/layout.d.ts

@@ -28,5 +28,6 @@ export declare function cognitionV1ImportPath(projectRoot: string): string;
 export declare function cognitionRuntimeDirectory(projectRoot: string): string;
 export declare function cognitionRuntimeLeasePath(projectRoot: string): string;
 export declare function cognitionRuntimeSecretPath(projectRoot: string): string;
+export declare function cognitionRuntimeStartupPath(projectRoot: string): string;
 export declare function cognitionV1SyncPath(projectRoot: string): string;
 export declare function cognitionQuarantineDirectory(projectRoot: string): string;

package/dist/src/storage/layout.js

@@ -89,6 +89,9 @@ export function cognitionRuntimeLeasePath(projectRoot) {
 export function cognitionRuntimeSecretPath(projectRoot) {
     return path.join(cognitionRuntimeDirectory(projectRoot), 'secret');
 }
+export function cognitionRuntimeStartupPath(projectRoot) {
+    return path.join(cognitionRuntimeDirectory(projectRoot), 'startup.json');
+}
 export function cognitionV1SyncPath(projectRoot) {
     return path.join(cognitionRuntimeDirectory(projectRoot), 'v1-sync.json');
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.7.6";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.6.0';
+export const VERSION = '0.7.6';

package/package.json

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

package/skills/fluffy-context/SKILL.md

@@ -17,7 +17,11 @@ compatibility: 需要 Node.js >=20.19.0；Git 可选。CLI 通过 npm 全局安
 - 人类需要了解 Agent 发生了什么时使用 `ctx activity`；它是只读时间线，不要求人类参与 Agent 的高频记录操作。
 - 新会话与新任务优先运行 `ctx orient [query] --max-chars <预算>`；它只读地返回有界摘要、匹配的已验证共识和当前 Context 的 open Note，不会创建 Snapshot 或更新 `lastUsedAt`。
 - 仅需要完整详情时再运行 `ctx resume --max-chars <预算>`；它会保留既有的 `lastUsedAt` 更新语义。
-- Agent 集成从 `fluffy-context` 或 `fluffy-context/agent` 导入 `contextOrient`、`saveContext`、`loadContext` 和 `searchContext`，不应直接读写 `.context` 或导入内部 `dist/...` 路径。
+- Agent 集成从 `fluffy-context` 或 `fluffy-context/agent` 导入 `contextOrient`、`compileContext`、`saveContext`、`loadContext` 和 `searchContext`，不应直接读写 `.context` 或导入内部 `dist/...` 路径。
+- `ctx compile` 的 `activity` section 只表示 Runtime 观察到的近期文件 metadata 变化；它不代表文件被读取或理解，也不替代 checkpoint、Note 或已验证 Knowledge。
+- 0.7.6 的 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。
@@ -99,7 +103,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_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
@@ -335,7 +341,8 @@ 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_checkpoint 可调用，且单次错误不会终止 server
+[ ] MCP 只读工具不写入 Context；Note add 和 checkpoint 仅在显式调用时写入
 [ ] Claude 集成预览不写文件，--apply 幂等且拒绝冲突
 [ ] Hook 失败时 fail open，且不会自动 checkpoint
 [ ] npm pack 的安装包可运行 ctx 并导入 contextOrient