@kentwynn/kgraph 0.1.21 → 0.1.23

package/dist/integrations/instruction-blocks.d.ts

@@ -1,2 +1,6 @@
+import type { IntegrationMode } from "../types/config.js";
+export declare const KGRAPH_CONTEXT_POLICY_PLACEHOLDER = "{{KGRAPH_CONTEXT_POLICY}}";
 export declare function upsertManagedBlock(content: string, integrationName: string, instructions: string): string;
 export declare function removeManagedBlock(content: string, integrationName: string): string;
+export declare function applyContextPolicy(content: string, mode: IntegrationMode): string;
+export declare function renderContextPolicy(mode: IntegrationMode): string;

package/dist/integrations/instruction-blocks.js

@@ -1,5 +1,6 @@
 const MARKER_PREFIX = "<!--";
 const MARKER_SUFFIX = "-->";
+export const KGRAPH_CONTEXT_POLICY_PLACEHOLDER = "{{KGRAPH_CONTEXT_POLICY}}";
 export function upsertManagedBlock(content, integrationName, instructions) {
     const normalized = content.trimEnd();
     const block = renderManagedBlock(integrationName, instructions);
@@ -25,3 +26,19 @@ function managedBlockPattern(integrationName) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+export function applyContextPolicy(content, mode) {
+    return content.replaceAll(KGRAPH_CONTEXT_POLICY_PLACEHOLDER, renderContextPolicy(mode));
+}
+export function renderContextPolicy(mode) {
+    switch (mode) {
+        case "always":
+            return 'Every chat in this repository must start by running `kgraph "<topic>"` before answering or exploring files. Infer the topic from the user\'s message; no exceptions, including simple or conversational requests.';
+        case "manual":
+            return 'Do not run KGraph automatically. Run `kgraph "<topic>"` only when the user explicitly asks for KGraph context or invokes the KGraph command.';
+        case "off":
+            return "KGraph is disabled for this integration.";
+        case "smart":
+        default:
+            return 'For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run `kgraph "<topic>"` before broad repository exploration. Infer the topic from the user\'s message. Skip KGraph for simple conversational requests that do not depend on repo knowledge.';
+    }
+}

package/dist/integrations/integration-store.d.ts

@@ -1,10 +1,12 @@
-import type { IntegrationConfig, IntegrationName, KGraphWorkspace } from "../types/config.js";
+import type { IntegrationConfig, IntegrationMode, IntegrationName, KGraphWorkspace } from "../types/config.js";
 export interface IntegrationStatus {
     name: IntegrationName;
     enabled: boolean;
+    mode: IntegrationMode;
     targetPath: string;
     targetExists: boolean;
 }
 export declare function listIntegrations(workspace: KGraphWorkspace): Promise<IntegrationStatus[]>;
-export declare function addIntegrations(workspace: KGraphWorkspace, names: IntegrationName[]): Promise<IntegrationConfig[]>;
+export declare function addIntegrations(workspace: KGraphWorkspace, names: IntegrationName[], mode?: IntegrationMode): Promise<IntegrationConfig[]>;
+export declare function setIntegrationMode(workspace: KGraphWorkspace, names: IntegrationName[], mode: IntegrationMode): Promise<IntegrationConfig[]>;
 export declare function removeIntegrations(workspace: KGraphWorkspace, names: IntegrationName[]): Promise<IntegrationName[]>;

package/dist/integrations/integration-store.js

@@ -3,18 +3,19 @@ import path from "node:path";
 import { loadConfig, saveConfig } from "../config/config.js";
 import { pathExists } from "../storage/kgraph-paths.js";
 import { getIntegrationAdapter } from "./integration-registry.js";
-import { removeManagedBlock, upsertManagedBlock } from "./instruction-blocks.js";
+import { applyContextPolicy, removeManagedBlock, upsertManagedBlock } from "./instruction-blocks.js";
 export async function listIntegrations(workspace) {
     const config = await loadConfig(workspace);
     const statuses = await Promise.all(config.integrations.map(async (integration) => ({
         name: integration.name,
         enabled: integration.enabled,
+        mode: integration.mode,
         targetPath: integration.targetPath,
         targetExists: await pathExists(path.join(workspace.rootPath, integration.targetPath))
     })));
     return statuses.sort((left, right) => left.name.localeCompare(right.name));
 }
-export async function addIntegrations(workspace, names) {
+export async function addIntegrations(workspace, names, mode = "always") {
     const config = await loadConfig(workspace);
     const byName = new Map(config.integrations.map((integration) => [integration.name, integration]));
     const changed = [];
@@ -22,19 +23,32 @@ export async function addIntegrations(workspace, names) {
         const adapter = getIntegrationAdapter(name);
         const next = {
             name: adapter.name,
-            enabled: true,
+            enabled: mode !== "off",
+            mode,
             targetPath: adapter.targetPath
         };
         byName.set(adapter.name, next);
-        await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, adapter.instructions);
+        if (mode === "off") {
+            await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
+            await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
+        }
+        else {
+            await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode));
+            await writeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).map((file) => ({
+                ...file,
+                content: applyContextPolicy(file.content, mode)
+            })));
+        }
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
-        await writeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
         changed.push(next);
     }
     config.integrations = [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
     await saveConfig(workspace, config);
     return changed;
 }
+export async function setIntegrationMode(workspace, names, mode) {
+    return addIntegrations(workspace, names, mode);
+}
 export async function removeIntegrations(workspace, names) {
     const config = await loadConfig(workspace);
     const removeNames = new Set(names);

package/dist/scanner/repo-scanner.js

@@ -10,6 +10,7 @@ import { extractJvmSymbols } from './jvm-symbol-extractor.js';
 import { extractPythonSymbols } from './python-symbol-extractor.js';
 import { extractRustSymbols } from './rust-symbol-extractor.js';
 import { extractTsSymbols } from './ts-symbol-extractor.js';
+import { estimateTokens } from '../session/token-estimator.js';
 const C_EXTS = new Set(['.c', '.h', '.cpp', '.cc', '.cxx', '.hpp', '.hxx']);
 const JVM_EXTS = new Set(['.java', '.kt', '.kts']);
 function extractSymbols(text, repoPath) {
@@ -73,6 +74,7 @@ export async function scanRepository(rootPath, config, previous) {
                 sizeBytes: info.size,
                 modifiedAt: info.mtime.toISOString(),
                 contentHash,
+                tokenEstimate: estimateTokens(text, repoPath),
                 scanStatus: isPreciseLanguage(repoPath, config) ? 'mapped' : 'generic',
                 warnings: [],
             };

package/dist/session/session-store.d.ts

@@ -0,0 +1,15 @@
+import type { KGraphWorkspace } from '../types/config.js';
+import type { FileMap } from '../types/maps.js';
+import type { SessionAgent, SessionCaptureSource, SessionEvent, SessionEventType, SessionLedgerEntry, SessionReport, SessionState } from '../types/session.js';
+export declare function assertSessionAgent(value: string): SessionAgent;
+export declare function readSessionState(workspace: KGraphWorkspace): Promise<SessionState>;
+export declare function resetSession(workspace: KGraphWorkspace): Promise<void>;
+export declare function readSessionLedger(workspace: KGraphWorkspace): Promise<SessionLedgerEntry[]>;
+export declare function recordSessionEvent(workspace: KGraphWorkspace, input: {
+    agent: SessionAgent;
+    type: SessionEventType;
+    path?: string;
+    captureSource: SessionCaptureSource;
+    fileMap?: FileMap;
+}): Promise<SessionEvent>;
+export declare function buildSessionReport(workspace: KGraphWorkspace): Promise<SessionReport>;

package/dist/session/session-store.js

@@ -0,0 +1,170 @@
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getIntegrationAdapter } from '../integrations/integration-registry.js';
+import { pathExists } from '../storage/kgraph-paths.js';
+import { KGraphError } from '../cli/errors.js';
+import { estimateTokens } from './token-estimator.js';
+const EMPTY_STATE = {
+    active: {},
+    events: [],
+    updatedAt: '',
+};
+export function assertSessionAgent(value) {
+    return getIntegrationAdapter(value).name;
+}
+export async function readSessionState(workspace) {
+    const filePath = currentPath(workspace);
+    if (!(await pathExists(filePath))) {
+        return { ...EMPTY_STATE, active: {}, events: [] };
+    }
+    return JSON.parse(await readFile(filePath, 'utf8'));
+}
+export async function resetSession(workspace) {
+    await rm(currentPath(workspace), { force: true });
+}
+export async function readSessionLedger(workspace) {
+    const filePath = ledgerPath(workspace);
+    if (!(await pathExists(filePath))) {
+        return [];
+    }
+    return JSON.parse(await readFile(filePath, 'utf8'));
+}
+export async function recordSessionEvent(workspace, input) {
+    const now = new Date().toISOString();
+    const state = await readSessionState(workspace);
+    const active = state.active[input.agent] ?? {
+        agent: input.agent,
+        sessionId: `${input.agent}-${now.replace(/[:.]/g, '-')}`,
+        startedAt: now,
+        lastEventAt: now,
+    };
+    const normalizedPath = input.path ? normalizeRepoPath(input.path) : undefined;
+    const tokenEstimate = normalizedPath && (input.type === 'read' || input.type === 'write')
+        ? await estimatePathTokens(workspace, normalizedPath, input.fileMap)
+        : undefined;
+    const repeated = input.type === 'read' && normalizedPath
+        ? state.events.some((event) => event.agent === input.agent &&
+            event.type === 'read' &&
+            event.path === normalizedPath)
+        : undefined;
+    const event = {
+        id: `${now}-${state.events.length + 1}`,
+        agent: input.agent,
+        type: input.type,
+        ...(normalizedPath ? { path: normalizedPath } : {}),
+        ...(tokenEstimate !== undefined ? { tokenEstimate } : {}),
+        ...(repeated !== undefined ? { repeated } : {}),
+        captureSource: input.captureSource,
+        timestamp: now,
+    };
+    if (input.type === 'start') {
+        state.active[input.agent] = active;
+    }
+    else if (!state.active[input.agent]) {
+        state.active[input.agent] = active;
+    }
+    state.active[input.agent].lastEventAt = now;
+    state.events.push(event);
+    state.updatedAt = now;
+    if (input.type === 'end') {
+        await appendLedgerEntry(workspace, summarizeAgentSession(input.agent, state, now));
+        delete state.active[input.agent];
+    }
+    await writeSessionState(workspace, state);
+    return event;
+}
+export async function buildSessionReport(workspace) {
+    const [state, ledger] = await Promise.all([
+        readSessionState(workspace),
+        readSessionLedger(workspace),
+    ]);
+    const readEvents = state.events.filter((event) => event.type === 'read');
+    const writeEvents = state.events.filter((event) => event.type === 'write');
+    const repeatedReads = readEvents.filter((event) => event.repeated);
+    return {
+        activeAgents: Object.values(state.active),
+        readCount: readEvents.length,
+        writeCount: writeEvents.length,
+        repeatedReadCount: repeatedReads.length,
+        estimatedReadTokens: sumTokens(readEvents),
+        estimatedRepeatedReadTokens: sumTokens(repeatedReads),
+        topRepeatedReads: topRepeatedReads(readEvents),
+        recentEvents: state.events.slice(-10),
+        ledger: ledger.slice(-10),
+    };
+}
+async function estimatePathTokens(workspace, repoPath, fileMap) {
+    const mapped = fileMap?.files.find((file) => file.path === repoPath);
+    if (mapped?.tokenEstimate !== undefined) {
+        return mapped.tokenEstimate;
+    }
+    const fullPath = path.join(workspace.rootPath, repoPath);
+    try {
+        const info = await stat(fullPath);
+        if (!info.isFile()) {
+            return undefined;
+        }
+        const content = await readFile(fullPath, 'utf8');
+        return estimateTokens(content, repoPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeSessionState(workspace, state) {
+    await mkdir(workspace.sessionsPath, { recursive: true });
+    await writeFile(currentPath(workspace), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+async function appendLedgerEntry(workspace, entry) {
+    const ledger = await readSessionLedger(workspace);
+    ledger.push(entry);
+    await mkdir(workspace.sessionsPath, { recursive: true });
+    await writeFile(ledgerPath(workspace), `${JSON.stringify(ledger, null, 2)}\n`, 'utf8');
+}
+function summarizeAgentSession(agent, state, endedAt) {
+    const active = state.active[agent];
+    if (!active) {
+        throw new KGraphError(`No active session for agent "${agent}".`);
+    }
+    const events = state.events.filter((event) => event.agent === agent && event.timestamp >= active.startedAt);
+    const reads = events.filter((event) => event.type === 'read');
+    const repeatedReads = reads.filter((event) => event.repeated);
+    return {
+        sessionId: active.sessionId,
+        agent,
+        startedAt: active.startedAt,
+        endedAt,
+        readCount: reads.length,
+        writeCount: events.filter((event) => event.type === 'write').length,
+        repeatedReadCount: repeatedReads.length,
+        estimatedReadTokens: sumTokens(reads),
+        estimatedRepeatedReadTokens: sumTokens(repeatedReads),
+    };
+}
+function topRepeatedReads(events) {
+    const byPath = new Map();
+    for (const event of events) {
+        if (!event.path)
+            continue;
+        const current = byPath.get(event.path) ?? { path: event.path, count: 0, estimatedTokens: 0 };
+        current.count += 1;
+        current.estimatedTokens += event.tokenEstimate ?? 0;
+        byPath.set(event.path, current);
+    }
+    return [...byPath.values()]
+        .filter((item) => item.count > 1)
+        .sort((left, right) => right.estimatedTokens - left.estimatedTokens)
+        .slice(0, 5);
+}
+function sumTokens(events) {
+    return events.reduce((total, event) => total + (event.tokenEstimate ?? 0), 0);
+}
+function normalizeRepoPath(value) {
+    return value.split(path.sep).join('/').replace(/^\.\//, '');
+}
+function currentPath(workspace) {
+    return path.join(workspace.sessionsPath, 'current.json');
+}
+function ledgerPath(workspace) {
+    return path.join(workspace.sessionsPath, 'ledger.json');
+}

package/dist/session/token-estimator.d.ts

@@ -0,0 +1 @@
+export declare function estimateTokens(content: string, filePath?: string): number;

package/dist/session/token-estimator.js

@@ -0,0 +1,17 @@
+export function estimateTokens(content, filePath = '') {
+    if (content.length === 0) {
+        return 0;
+    }
+    const ratio = tokenRatio(filePath);
+    return Math.max(1, Math.ceil(content.length / ratio));
+}
+function tokenRatio(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith('.md') || lower.endsWith('.txt'))
+        return 4.8;
+    if (lower.endsWith('.json') || lower.endsWith('.yaml') || lower.endsWith('.yml'))
+        return 3.8;
+    if (lower.endsWith('.html') || lower.endsWith('.css'))
+        return 3.6;
+    return 4.0;
+}

package/dist/storage/kgraph-paths.js

@@ -7,7 +7,8 @@ const WORKSPACE_DIRS = [
     "domains",
     "inbox",
     "interactions/processed",
-    "context"
+    "context",
+    "sessions"
 ];
 export function resolveWorkspace(rootPath = process.cwd()) {
     const kgraphPath = path.join(rootPath, ".kgraph");
@@ -20,7 +21,8 @@ export function resolveWorkspace(rootPath = process.cwd()) {
         domainsPath: path.join(kgraphPath, "domains"),
         inboxPath: path.join(kgraphPath, "inbox"),
         processedInteractionsPath: path.join(kgraphPath, "interactions", "processed"),
-        contextPath: path.join(kgraphPath, "context")
+        contextPath: path.join(kgraphPath, "context"),
+        sessionsPath: path.join(kgraphPath, "sessions")
     };
 }
 export async function pathExists(targetPath) {

package/dist/types/config.d.ts

@@ -13,9 +13,11 @@ export interface DomainHint {
     tags?: string[];
 }
 export type IntegrationName = "claude-code" | "cline" | "codex" | "copilot" | "cursor" | "gemini" | "windsurf";
+export type IntegrationMode = "smart" | "always" | "manual" | "off";
 export interface IntegrationConfig {
     name: IntegrationName;
     enabled: boolean;
+    mode: IntegrationMode;
     targetPath: string;
 }
 export interface KGraphWorkspace {
@@ -28,4 +30,5 @@ export interface KGraphWorkspace {
     inboxPath: string;
     processedInteractionsPath: string;
     contextPath: string;
+    sessionsPath: string;
 }

package/dist/types/maps.d.ts

@@ -10,6 +10,7 @@ export interface RepositoryFile {
     sizeBytes: number;
     modifiedAt?: string;
     contentHash: string;
+    tokenEstimate?: number;
     scanStatus: ScanStatus;
     warnings: string[];
 }

package/dist/types/session.d.ts

@@ -0,0 +1,51 @@
+import type { IntegrationName } from './config.js';
+export type SessionAgent = IntegrationName;
+export type SessionEventType = 'start' | 'read' | 'write' | 'end';
+export type SessionCaptureSource = 'automatic' | 'agent-reported' | 'manual';
+export interface SessionEvent {
+    id: string;
+    agent: SessionAgent;
+    type: SessionEventType;
+    path?: string;
+    tokenEstimate?: number;
+    repeated?: boolean;
+    captureSource: SessionCaptureSource;
+    timestamp: string;
+}
+export interface AgentSession {
+    agent: SessionAgent;
+    sessionId: string;
+    startedAt: string;
+    lastEventAt: string;
+}
+export interface SessionState {
+    active: Record<string, AgentSession>;
+    events: SessionEvent[];
+    updatedAt: string;
+}
+export interface SessionLedgerEntry {
+    sessionId: string;
+    agent: SessionAgent;
+    startedAt: string;
+    endedAt: string;
+    readCount: number;
+    writeCount: number;
+    repeatedReadCount: number;
+    estimatedReadTokens: number;
+    estimatedRepeatedReadTokens: number;
+}
+export interface SessionReport {
+    activeAgents: AgentSession[];
+    readCount: number;
+    writeCount: number;
+    repeatedReadCount: number;
+    estimatedReadTokens: number;
+    estimatedRepeatedReadTokens: number;
+    topRepeatedReads: Array<{
+        path: string;
+        count: number;
+        estimatedTokens: number;
+    }>;
+    recentEvents: SessionEvent[];
+    ledger: SessionLedgerEntry[];
+}

package/dist/types/session.js

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

package/dist/visualization/graph-builder.d.ts

@@ -10,6 +10,7 @@ export interface GraphData {
         fileCount: number;
         symbolCount: number;
         cognitionCount: number;
+        tokenEstimate: number;
         generatedAt: string;
     };
 }

package/dist/visualization/graph-builder.js

@@ -24,7 +24,9 @@ export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, c
     const elements = [];
     const edgeIds = new Set();
     const nodeIds = new Set();
+    const tokenEstimate = fileMap.files.reduce((total, file) => total + (file.tokenEstimate ?? 0), 0);
     for (const file of fileMap.files) {
+        const tokenBucket = getTokenBucket(file.tokenEstimate);
         nodeIds.add(file.id);
         elements.push({
             data: {
@@ -35,9 +37,11 @@ export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, c
                 color: LANGUAGE_COLORS[file.language] ?? '#94a3b8',
                 type: 'file',
                 size: file.sizeBytes,
+                tokenEstimate: file.tokenEstimate ?? 0,
+                tokenBucket,
                 scanStatus: file.scanStatus,
             },
-            classes: `file ${file.language}`,
+            classes: `file ${file.language} token-${tokenBucket}`,
         });
     }
     for (const symbol of symbolMap.symbols) {
@@ -139,7 +143,16 @@ export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, c
             fileCount: fileMap.files.length,
             symbolCount: symbolMap.symbols.length,
             cognitionCount: cognitionNotes.length,
+            tokenEstimate,
             generatedAt: new Date().toISOString(),
         },
     };
 }
+function getTokenBucket(tokenEstimate) {
+    const tokens = tokenEstimate ?? 0;
+    if (tokens >= 1000)
+        return 'large';
+    if (tokens >= 200)
+        return 'medium';
+    return 'small';
+}

package/dist/visualization/html-template.js

@@ -51,7 +51,7 @@ select:hover,button:hover{background:#475569}
 <body>
 <div id="toolbar">
   <span id="t-title">\u29e1 KGraph \u00b7 ${repoName}</span>
-  <span id="t-stats">${meta.fileCount} files &middot; ${meta.symbolCount} symbols &middot; ${meta.cognitionCount} notes</span>
+  <span id="t-stats">${meta.fileCount} files &middot; ${meta.symbolCount} symbols &middot; ${meta.cognitionCount} notes &middot; ~${meta.tokenEstimate} tokens</span>
   <div id="t-controls">
     <label class="clabel"><input type="checkbox" id="tog-cog" checked> Cognition</label>
     <select id="sel-layout" title="Graph layout algorithm">
@@ -81,6 +81,8 @@ select:hover,button:hover{background:#475569}
   <span class="li"><span class="li-dot" style="background:#10b981"></span>Markdown</span>
   <span class="li"><span class="li-dot" style="background:#8b5cf6"></span>YAML</span>
   <span class="li"><span class="li-dot" style="background:#94a3b8"></span>Other</span>
+  <span class="li"><span class="li-dot" style="background:#475569"></span>200+ tok</span>
+  <span class="li"><span class="li-dot" style="background:#ef4444"></span>1000+ tok</span>
   <span class="li-sep"></span>
   <span class="li-head">Cognition</span>
   <span class="li"><span class="li-dia" style="background:#10b981"></span>Current</span>
@@ -162,6 +164,20 @@ select:hover,button:hover{background:#475569}
           'overlay-color': '#7dd3fc'
         }
       },
+      {
+        selector: 'node.token-medium',
+        style: {
+          'border-color': '#f59e0b',
+          'border-width': 2
+        }
+      },
+      {
+        selector: 'node.token-large',
+        style: {
+          'border-color': '#ef4444',
+          'border-width': 3
+        }
+      },
       {
         selector: 'edge.import',
         style: {
@@ -217,7 +233,8 @@ select:hover,button:hover{background:#475569}
     return '<div class="sb-badge" style="background:' + esc(d.color) + '22;color:' + esc(d.color) + ';border:1px solid ' + esc(d.color) + '44">' + esc(d.language) + '</div>' +
       '<div class="sb-title">' + esc(d.path) + '</div>' +
       '<div class="sb-sect"><div class="sb-lbl">Scan Status</div><div class="sb-val">' + esc(d.scanStatus) + '</div></div>' +
-      '<div class="sb-sect"><div class="sb-lbl">File Size</div><div class="sb-val">' + bytes(d.size) + '</div></div>';
+      '<div class="sb-sect"><div class="sb-lbl">File Size</div><div class="sb-val">' + bytes(d.size) + '</div></div>' +
+      '<div class="sb-sect"><div class="sb-lbl">Estimated Tokens</div><div class="sb-val">~' + esc(d.tokenEstimate || 0) + ' tokens</div></div>';
   }
 
   function renderCognitionPanel(d) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {