@hegel-dev/companion 1.0.0

package/dist/state.js

@@ -0,0 +1,77 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+const STATE_DIR = ".hegel-state";
+const SAFE_CONVERSATION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+function createEmptyState(conversationId) {
+    return {
+        conversationId,
+        startedAt: Date.now(),
+        prompts: [],
+        responses: [],
+        fileEdits: [],
+        turnCount: 0,
+        compactionCount: 0,
+        concerns: [],
+    };
+}
+export function isSafeConversationId(conversationId) {
+    return SAFE_CONVERSATION_ID.test(conversationId);
+}
+function statePath(conversationId) {
+    if (!isSafeConversationId(conversationId))
+        return null;
+    return join(STATE_DIR, `${conversationId}.json`);
+}
+export async function loadState(conversationId) {
+    const path = statePath(conversationId);
+    if (!path)
+        return createEmptyState(conversationId);
+    try {
+        const raw = await readFile(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return createEmptyState(conversationId);
+    }
+}
+export async function saveState(state) {
+    const path = statePath(state.conversationId);
+    if (!path)
+        return;
+    await mkdir(STATE_DIR, { recursive: true });
+    await writeFile(path, JSON.stringify(state, null, 2), "utf-8");
+}
+export function addPrompt(state, record) {
+    state.prompts.push(record);
+    state.turnCount++;
+}
+export function addResponse(state, record) {
+    state.responses.push(record);
+}
+export function addFileEdit(state, record) {
+    state.fileEdits.push(record);
+}
+export function addConcern(state, concern) {
+    state.concerns.push(concern);
+}
+export function recentPrompts(state, count = 5) {
+    return state.prompts.slice(-count);
+}
+export function sessionDurationMinutes(state) {
+    return (Date.now() - state.startedAt) / 60_000;
+}
+export function totalFilesEdited(state) {
+    const paths = new Set(state.fileEdits.map((e) => e.filePath));
+    return paths.size;
+}
+export function totalLinesChanged(state) {
+    return state.fileEdits.reduce((sum, e) => sum + e.totalLinesChanged, 0);
+}
+export function recordModel(state, model) {
+    if (!state.modelsUsed)
+        state.modelsUsed = [];
+    if (!state.modelsUsed.includes(model)) {
+        state.modelsUsed.push(model);
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/transcript.d.ts

@@ -0,0 +1,32 @@
+import type { TranscriptContext, TranscriptTurn } from "./types.js";
+export declare function isSafeTranscriptPath(transcriptPath: string): boolean;
+/**
+ * Reads and parses a Cursor transcript JSONL file into structured turns.
+ * Returns null if the file is unreadable or empty — callers should
+ * treat null as "no transcript available" and fall back to heuristics.
+ *
+ * The parser is intentionally lenient: malformed lines are skipped,
+ * and the hook should never fail because of a transcript issue.
+ */
+export declare function loadTranscript(transcriptPath: string | null): Promise<TranscriptContext | null>;
+/**
+ * Returns the last N user turns from the transcript.
+ */
+export declare function recentUserTurns(ctx: TranscriptContext, count: number): TranscriptTurn[];
+/**
+ * Returns the last N assistant turns from the transcript.
+ */
+export declare function recentAssistantTurns(ctx: TranscriptContext, count: number): TranscriptTurn[];
+/**
+ * Checks whether the current prompt appears to be a follow-up that references
+ * content from the last assistant response (numbered items, file names, etc.).
+ * This is critical for reducing false positives on short directives like
+ * "fix #3 and #5" or "do that for utils.ts too".
+ */
+export declare function isContextualFollowUp(prompt: string, ctx: TranscriptContext): boolean;
+/**
+ * Detects whether the assistant's last response contained a plan, proposal,
+ * or question that naturally invites a short directive follow-up.
+ */
+export declare function lastResponseInvitesFollowUp(ctx: TranscriptContext): boolean;
+//# sourceMappingURL=transcript.d.ts.map

package/dist/transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA6CpE,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA0CnC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,MAAM,GACZ,cAAc,EAAE,CAIlB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,MAAM,GACZ,cAAc,EAAE,CAIlB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAiCT;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAc3E"}

package/dist/transcript.js

@@ -0,0 +1,156 @@
+import { readFile } from "node:fs/promises";
+import { extname, isAbsolute } from "node:path";
+/**
+ * Extracts plain text from a transcript line's content blocks.
+ * Strips tool_use blocks, image blocks, and other non-text content.
+ * For user messages, strips the <user_query> wrapper tags that Cursor injects.
+ */
+function extractText(line) {
+    const blocks = line.message?.content ?? [];
+    const textParts = [];
+    for (const block of blocks) {
+        if (block.type === "text" && block.text) {
+            textParts.push(block.text);
+        }
+    }
+    let combined = textParts.join("\n").trim();
+    // Cursor wraps user prompts in <user_query>...</user_query> tags
+    const queryMatch = combined.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/);
+    if (queryMatch) {
+        combined = queryMatch[1].trim();
+    }
+    return combined;
+}
+function wordCount(text) {
+    if (!text)
+        return 0;
+    return text.split(/\s+/).filter(Boolean).length;
+}
+export function isSafeTranscriptPath(transcriptPath) {
+    return isAbsolute(transcriptPath) && extname(transcriptPath).toLowerCase() === ".jsonl";
+}
+/**
+ * Reads and parses a Cursor transcript JSONL file into structured turns.
+ * Returns null if the file is unreadable or empty — callers should
+ * treat null as "no transcript available" and fall back to heuristics.
+ *
+ * The parser is intentionally lenient: malformed lines are skipped,
+ * and the hook should never fail because of a transcript issue.
+ */
+export async function loadTranscript(transcriptPath) {
+    if (!transcriptPath)
+        return null;
+    if (!isSafeTranscriptPath(transcriptPath))
+        return null;
+    try {
+        const raw = await readFile(transcriptPath, "utf-8");
+        const lines = raw.split("\n").filter((l) => l.trim());
+        const turns = [];
+        for (const line of lines) {
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed.role !== "user" && parsed.role !== "assistant")
+                    continue;
+                const text = extractText(parsed);
+                if (!text)
+                    continue;
+                turns.push({
+                    role: parsed.role,
+                    text,
+                    wordCount: wordCount(text),
+                });
+            }
+            catch {
+                // Skip malformed lines — don't break the hook
+            }
+        }
+        if (turns.length === 0)
+            return null;
+        const userTurns = turns.filter((t) => t.role === "user");
+        const assistantTurns = turns.filter((t) => t.role === "assistant");
+        return {
+            turns,
+            userTurnCount: userTurns.length,
+            assistantTurnCount: assistantTurns.length,
+            lastAssistantText: assistantTurns.at(-1)?.text ?? "",
+            lastUserText: userTurns.at(-1)?.text ?? "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns the last N user turns from the transcript.
+ */
+export function recentUserTurns(ctx, count) {
+    return ctx.turns
+        .filter((t) => t.role === "user")
+        .slice(-count);
+}
+/**
+ * Returns the last N assistant turns from the transcript.
+ */
+export function recentAssistantTurns(ctx, count) {
+    return ctx.turns
+        .filter((t) => t.role === "assistant")
+        .slice(-count);
+}
+/**
+ * Checks whether the current prompt appears to be a follow-up that references
+ * content from the last assistant response (numbered items, file names, etc.).
+ * This is critical for reducing false positives on short directives like
+ * "fix #3 and #5" or "do that for utils.ts too".
+ */
+export function isContextualFollowUp(prompt, ctx) {
+    const lastResponse = ctx.lastAssistantText;
+    if (!lastResponse)
+        return false;
+    const trimmed = prompt.trim().toLowerCase();
+    // References to numbered items from the assistant's response
+    const numberRefs = trimmed.match(/#(\d+)/g);
+    if (numberRefs && numberRefs.length > 0) {
+        const responseHasNumbers = /#?\d+[.):]\s/.test(lastResponse);
+        if (responseHasNumbers)
+            return true;
+    }
+    // References to file/function names that appear in the last response
+    const identifiers = trimmed.match(/\b[\w.-]+\.(ts|js|tsx|jsx|py|rs|go|css|html|json|md)\b/gi);
+    if (identifiers) {
+        for (const id of identifiers) {
+            if (lastResponse.includes(id))
+                return true;
+        }
+    }
+    // "that", "those", "the same" referring to something the assistant just listed
+    const deicticPatterns = /\b(do that|do those|the same|same thing|like above|as above|mentioned above)\b/i;
+    if (deicticPatterns.test(trimmed) && lastResponse.length > 100) {
+        return true;
+    }
+    // Short affirmative after a question or proposal from the assistant
+    const assistantAskedQuestion = /\?[\s]*$/.test(lastResponse.trim());
+    const isShortAffirmative = /^(yes|yeah|yep|sure|go ahead|do it|proceed|ok|okay|correct|exactly|please|go)[\s.,!]?$/i.test(trimmed);
+    if (assistantAskedQuestion && isShortAffirmative)
+        return true;
+    return false;
+}
+/**
+ * Detects whether the assistant's last response contained a plan, proposal,
+ * or question that naturally invites a short directive follow-up.
+ */
+export function lastResponseInvitesFollowUp(ctx) {
+    const text = ctx.lastAssistantText;
+    if (!text)
+        return false;
+    // Ends with a question
+    if (/\?\s*$/.test(text.trim()))
+        return true;
+    // Contains a numbered list (plan/options)
+    if (/\n\s*\d+[.)]\s/.test(text))
+        return true;
+    // Explicit invitation patterns
+    if (/\b(which (one|item|option)|ready when you are|want me to|shall I|let me know|would you like)\b/i.test(text))
+        return true;
+    return false;
+}
+//# sourceMappingURL=transcript.js.map

package/dist/transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+export interface HookBaseInput {
+    conversation_id: string;
+    generation_id: string;
+    model: string;
+    hook_event_name: string;
+    cursor_version: string;
+    workspace_roots: string[];
+    user_email: string | null;
+    transcript_path: string | null;
+    session_id?: string;
+    composer_mode?: "agent" | "ask" | "edit";
+}
+export interface BeforeSubmitPromptInput extends HookBaseInput {
+    prompt: string;
+    attachments: Array<{
+        type: "file" | "rule";
+        file_path: string;
+    }>;
+}
+export interface AfterAgentResponseInput extends HookBaseInput {
+    text: string;
+}
+export interface AfterAgentThoughtInput extends HookBaseInput {
+    text: string;
+    duration_ms?: number;
+}
+export interface AfterFileEditInput extends HookBaseInput {
+    file_path: string;
+    edits: Array<{
+        old_string: string;
+        new_string: string;
+    }>;
+}
+export interface StopInput extends HookBaseInput {
+    status: "completed" | "aborted" | "error";
+    loop_count: number;
+}
+export interface SessionStartInput extends HookBaseInput {
+    is_background_agent: boolean;
+}
+export interface SessionEndInput extends HookBaseInput {
+    reason: "completed" | "aborted" | "error" | "window_close" | "user_close";
+    duration_ms: number;
+    is_background_agent: boolean;
+    final_status: string;
+    error_message?: string;
+}
+export interface PreCompactInput extends HookBaseInput {
+    trigger: "auto" | "manual";
+    context_usage_percent: number;
+    context_tokens: number;
+    context_window_size: number;
+    message_count: number;
+    messages_to_compact: number;
+    is_first_compaction: boolean;
+}
+export interface BeforeSubmitPromptOutput {
+    continue: boolean;
+    user_message?: string;
+}
+export interface AfterAgentResponseOutput {
+}
+export interface StopOutput {
+    followup_message?: string;
+}
+export interface SessionStartOutput {
+    env?: Record<string, string>;
+    additional_context?: string;
+}
+export interface TranscriptTurn {
+    role: "user" | "assistant";
+    /** Plain text content (tool calls and non-text blocks stripped). */
+    text: string;
+    wordCount: number;
+}
+/**
+ * Parsed conversation context from the Cursor transcript file.
+ * Provides the full dialogue history so analyzers can make
+ * context-aware decisions instead of relying on heuristics alone.
+ */
+export interface TranscriptContext {
+    turns: TranscriptTurn[];
+    /** Number of user messages in the transcript. */
+    userTurnCount: number;
+    /** Number of assistant messages in the transcript. */
+    assistantTurnCount: number;
+    /** The last assistant response text (empty string if none). */
+    lastAssistantText: string;
+    /** The last user message text (empty string if none). */
+    lastUserText: string;
+}
+export type Severity = "info" | "warning" | "critical";
+export interface Concern {
+    severity: Severity;
+    category: string;
+    message: string;
+    suggestion?: string;
+    sourceText?: string;
+    sourceType?: "prompt" | "response" | "session";
+}
+export interface PromptRecord {
+    timestamp: number;
+    prompt: string;
+    wordCount: number;
+    concerns: Concern[];
+}
+export interface ResponseRecord {
+    timestamp: number;
+    textLength: number;
+    concerns: Concern[];
+    /** True when the response had no preceding beforeSubmitPrompt event. */
+    unprompted?: boolean;
+}
+export interface FileEditRecord {
+    timestamp: number;
+    filePath: string;
+    editCount: number;
+    totalLinesChanged: number;
+}
+export interface SessionState {
+    conversationId: string;
+    sessionId?: string;
+    composerMode?: "agent" | "ask" | "edit";
+    startedAt: number;
+    prompts: PromptRecord[];
+    responses: ResponseRecord[];
+    fileEdits: FileEditRecord[];
+    turnCount: number;
+    compactionCount: number;
+    concerns: Concern[];
+    lastBlockedPrompt?: string;
+    /** turnCount at last session review, used to suppress redundant stop reviews. */
+    lastReviewedAtTurn?: number;
+    /** Actual model(s) observed on prompt/response events (not sessionStart). */
+    modelsUsed?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// ── Cursor Hook Payloads ──
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6BAA6B"}

package/hegel.config.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Hegel Configuration",
+  "description": "Configuration for Hegel dialectical companion",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path to the JSON schema for this config file."
+    },
+    "model": {
+      "anyOf": [
+        {
+          "enum": [
+            "auto",
+            "gpt-5.4",
+            "claude-4.6-opus",
+            "gemini-3.1-pro",
+            "grok-4.20",
+            "gemini-3-flash",
+            "composer-2",
+            "composer-1.5",
+            "claude-4.6-sonnet",
+            "gpt-5.2",
+            "claude-4.5-haiku",
+            "gpt-5.1",
+            "gemini-2.5-flash"
+          ]
+        },
+        {
+          "type": "string",
+          "description": "Or type any other valid Cursor model name available in your subscription."
+        }
+      ],
+      "description": "Model to use for LLM-powered analysis. Use 'auto' for Cursor's default fast model, or specify a model name from your subscription.",
+      "default": "auto"
+    },
+    "enableLlmAnalysis": {
+      "type": "boolean",
+      "description": "Enable the LLM-powered deep analysis layer (Layer 2). When false, only fast rule-based checks (Layer 1) run. Uses tokens from your Cursor subscription.",
+      "default": true
+    },
+    "timeoutSeconds": {
+      "type": "number",
+      "description": "Timeout in seconds for LLM-powered hooks.",
+      "default": 15,
+      "minimum": 5,
+      "maximum": 60
+    },
+    "strictness": {
+      "type": "string",
+      "enum": ["relaxed", "balanced", "strict"],
+      "description": "How aggressively Hegel intervenes. 'relaxed' = only obvious issues, 'balanced' = default, 'strict' = questions most prompts.",
+      "default": "balanced"
+    },
+    "observeOnly": {
+      "type": "boolean",
+      "description": "Observe-Only Mode: When true, both layers still run full analysis and collect stats, but the user never sees any intervention in the chat (no blocking, no messages).",
+      "default": false
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@hegel-dev/companion",
+  "version": "1.0.0",
+  "description": "Dialectical companion for AI-assisted development — real-time critical thinking oversight for Cursor IDE sessions",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "dev:watch": "node dist/dev-watch.js",
+    "hook": "node dist/hook.js",
+    "setup": "node dist/setup.js",
+    "mcp": "node dist/mcp.js",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "bin": {
+    "hegel-companion": "./dist/setup.js",
+    "hegel-mcp": "./dist/mcp.js"
+  },
+  "keywords": [
+    "cursor",
+    "cursor-plugin",
+    "ai-assistant",
+    "critical-thinking",
+    "code-review",
+    "dialectical"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CreatoR682/hegel.git"
+  },
+  "author": "Hegel Contributors",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "hegel.config.schema.json",
+    "hegel-vscode/*.vsix"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@emnapi/core": "^1.9.2",
+    "@emnapi/runtime": "^1.9.2",
+    "@types/node": "^20.19.39",
+    "@vitest/coverage-v8": "^4.1.4",
+    "typescript": "^5.7",
+    "vitest": "^4.1.4"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}