fluffy-context 0.6.0 → 0.7.2

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

@@ -0,0 +1,187 @@
+import type { CognitionGitAnchor, WorkspacePathChange } from '../cognition/types.js';
+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 ContextSourceKind = 'current-context' | 'checkpoint' | 'note' | 'journal' | 'knowledge' | 'deadend';
+export type ContextCandidateSection = 'summary' | 'pending' | 'decision' | 'risk' | 'note' | 'knowledge' | 'deadend' | 'activity';
+export type ContextSignalOrigin = 'explicit' | 'deterministic';
+export interface ContextAnchor {
+    projectRoot: string;
+    worktreeId: string | null;
+    branch: string | null;
+    ref: string | null;
+    head: string | null;
+}
+export interface ContextIntentSignal {
+    source: 'explicit-query' | 'explicit-scenario' | 'context-state' | 'host-prompt' | 'path' | 'git';
+    value: string;
+    origin: ContextSignalOrigin;
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface ContextIntent {
+    schemaVersion: 1;
+    trigger: 'session-start' | 'prompt' | 'manual' | 'tool-call';
+    query: string | null;
+    normalizedTerms: string[];
+    scenario: ContextScenario;
+    scope: string | null;
+    paths: string[];
+    contextId: string | null;
+    anchor: ContextAnchor;
+    signals: ContextIntentSignal[];
+    requestedSections: ContextCandidateSection[];
+    budget: ContextBudget;
+    adapter: string;
+    sessionId: string | null;
+    eventId: string | null;
+}
+export interface ContextBudget {
+    unit: 'chars';
+    total: number;
+    reservedForRenderer: number;
+    sections?: Partial<Record<ContextCandidateSection, number>>;
+}
+export interface ContextSourceApplicability {
+    project: true;
+    branchMode: 'global' | 'exact' | 'unsupported';
+    branches: string[];
+    paths: string[];
+    worktreeId: string | null;
+    ref: string | null;
+}
+export interface ContextProvenance {
+    origin: 'v1-file' | 'v2-journal' | 'mixed' | 'live';
+    eventId: string | null;
+    eventType: string | null;
+    occurredAt: string | null;
+    sourcePath: string | null;
+    sourceHash: string | null;
+    anchorProvenance: 'snapshot' | 'live' | 'global' | null;
+}
+export interface ContextSourceDescriptor {
+    sourceId: string;
+    kind: ContextSourceKind;
+    entityId: string;
+    contextId: string | null;
+    snapshotId: string | null;
+    status: string | null;
+    scope: string | null;
+    paths: string[];
+    anchor: ContextAnchor;
+    applicability: ContextSourceApplicability;
+    privacy: {
+        classification: 'metadata' | 'redacted-text' | 'unknown';
+        redactionCount: number;
+    };
+    provenance: ContextProvenance;
+}
+export interface ContextActivityRecord {
+    eventId: string;
+    occurredAt: string;
+    anchor: ContextAnchor;
+    paths: string[];
+    changes: WorkspacePathChange[];
+    pathCount: number;
+    coalesced: boolean;
+    truncated: boolean;
+    focusMatch: boolean;
+}
+export interface ContextCandidate<T = unknown> {
+    candidateId: string;
+    section: ContextCandidateSection;
+    source: ContextSourceDescriptor;
+    content: T;
+    text: string;
+    priority: number;
+    score: number;
+    matchedTerms: string[];
+    matchedFields: string[];
+    originalChars: number;
+    selectedChars: number;
+    selected: boolean;
+    truncated: 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 {
+    candidateId: string;
+    source: ContextSourceDescriptor | null;
+    reason: ContextExclusionReason;
+    detail?: string;
+}
+export interface ContextTruncation {
+    truncated: boolean;
+    summary: boolean;
+    pending: boolean;
+    decisions: boolean;
+    risks: boolean;
+    notes: boolean;
+    knowledge: boolean;
+    deadends: boolean;
+    activity: boolean;
+    candidatesOmittedByBudget: number;
+    candidatesPartiallyTruncated: number;
+}
+export interface ContextBudgetReport {
+    requested: ContextBudget;
+    usedChars: number;
+    remainingChars: number;
+    sections: Partial<Record<ContextCandidateSection, {
+        allocated: number;
+        consumed: number;
+        truncated: boolean;
+    }>>;
+}
+export interface ContextManifestProvenance {
+    journalRead: boolean;
+    journalEventCount: number;
+    selectedSourceIds: string[];
+    selectedEventIds: string[];
+    fallbackReason: string | null;
+}
+export interface ContextCompileOptions {
+    contextId?: string;
+    query?: string;
+    scenario?: ContextScenario;
+    scope?: string;
+    paths?: string[];
+    maxChars?: number;
+    knowledgeLimit?: number;
+    deadendLimit?: number;
+    noteLimit?: number;
+    activityLimit?: number;
+    trigger?: ContextIntent['trigger'];
+    adapter?: string;
+    sessionId?: string;
+    eventId?: string;
+}
+export interface ContextManifest {
+    schemaVersion: 1;
+    compilerVersion: '0.7.2';
+    rankingVersion: 'compiler-ranking-v2';
+    status: 'ready' | 'no_context';
+    projectRoot: string;
+    mode: 'v2' | 'v1-fallback';
+    anchor: ContextAnchor;
+    intent: ContextIntent;
+    context: ContextOrientResult['context'];
+    snapshot: ContextOrientResult['snapshot'];
+    resumeSummary: ResumeSummary | null;
+    sections: {
+        summary: ContextCandidate[];
+        pending: ContextCandidate[];
+        decision: ContextCandidate[];
+        risk: ContextCandidate[];
+        notes: ContextCandidate[];
+        knowledge: ContextCandidate[];
+        deadends: ContextCandidate[];
+        activity: ContextCandidate<ContextActivityRecord>[];
+    };
+    selected: ContextCandidate[];
+    excluded: ContextExclusion[];
+    budget: ContextBudgetReport;
+    truncation: ContextTruncation;
+    provenance: ContextManifestProvenance;
+    text: string;
+}
+export type CompilerRecord = StructuredContext | Note | Knowledge | Deadend;
+export type CompilerGitAnchor = CognitionGitAnchor;

package/dist/src/compiler/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/claude-code.js

@@ -1,11 +1,10 @@
 import { contextOrient } from '../agent/api.js';
 import { appendEvent } from '../cognition/journal.js';
 import { v2Enabled } from '../cognition/orient.js';
-import { startRuntime } from '../cognition/runtime.js';
+import { ensureRuntimeForSession, touchRuntime } from '../cognition/runtime.js';
+import { loadRuntimePolicy } from '../cognition/policy.js';
 import { readGitWorktreeState } from '../git/git-adapter.js';
 import { resolveProjectRoot } from '../project/project-resolver.js';
-import { cognitionPolicyPath } from '../storage/layout.js';
-import { readJson } from '../storage/json-store.js';
 const HOOK_RESPONSE = '{}\n';
 function text(value) {
     return typeof value === 'string' ? value : undefined;
@@ -68,15 +67,12 @@ function redactIntent(value) {
         .replace(/\b(?:sk|ghp|gho|github_pat)_[A-Za-z0-9_-]+\b/g, () => { redactionCount += 1; return '[REDACTED]'; });
     return { intent, redactionCount };
 }
-async function within(task, milliseconds) {
-    return Promise.race([task, new Promise((_, reject) => setTimeout(() => reject(new Error('hook deadline exceeded')), milliseconds))]);
-}
 async function capture(event, input) {
     const cwd = text(input.cwd);
     const projectRoot = await resolveProjectRoot(cwd);
     if (!await v2Enabled(projectRoot))
         return;
-    const policy = await readJson(cognitionPolicyPath(projectRoot));
+    const policy = await loadRuntimePolicy(projectRoot);
     const sessionId = stableId(input, 'session');
     const eventId = stableId(input, 'event');
     if (!sessionId || !eventId)
@@ -94,12 +90,7 @@ async function capture(event, input) {
     });
 }
 async function maybeStartRuntime(input) {
-    const projectRoot = await resolveProjectRoot(text(input.cwd));
-    if (!await v2Enabled(projectRoot))
-        return;
-    const policy = await readJson(cognitionPolicyPath(projectRoot));
-    if (policy.allowHookStartup)
-        await within(startRuntime(projectRoot), 1_000);
+    await ensureRuntimeForSession(text(input.cwd), { source: 'claude-hook', timeoutMs: 1_000 });
 }
 async function parseInput(raw) {
     try {
@@ -115,9 +106,10 @@ export async function runClaudeCodeHook(event, raw) {
     if (!input)
         return HOOK_RESPONSE;
     try {
-        if (event === 'session-start')
-            await maybeStartRuntime(input).catch(() => undefined);
+        await maybeStartRuntime(input).catch(() => undefined);
+        await touchRuntime(text(input.cwd)).catch(() => false);
         await capture(event, input).catch(() => undefined);
+        await touchRuntime(text(input.cwd)).catch(() => false);
         const cwd = text(input.cwd);
         const result = event === 'session-start'
             ? await contextOrient(cwd, { maxChars: 1200, noteLimit: 8 })

package/dist/src/mcp/main.js

@@ -1,5 +1,7 @@
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { ensureRuntimeForSession } from '../cognition/runtime.js';
 import { createMcpServer } from './server.js';
+await ensureRuntimeForSession(process.cwd(), { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
 serveStdio(createMcpServer, {
     onerror: (error) => process.stderr.write(`MCP server error: ${error.message}\n`),
 });

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 { ensureRuntimeForSession } from '../cognition/runtime.js';
 import { VERSION } from '../version.js';
 const orientInput = z.object({
     path: z.string().optional(),
@@ -23,6 +24,7 @@ export function createMcpServer() {
         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) }],

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.2";

package/dist/src/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "0.6.0",
+  "version": "0.7.2",
   "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,8 @@ 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。
 - 新任务先发现已验证共识，再开始实现；候选项只在显式审查时使用。
 - 普通查询只使用已验证 Knowledge 和 Deadend；需要审查候选项时显式使用 `--all`。
 - CLI 业务命令的标准输出是 JSON；错误写入标准错误并返回非零退出码。解析输出时不要把 `--help` 的纯文本当作 JSON。