knodin 0.8.2 → 0.8.4

package/README.md

@@ -31,16 +31,32 @@ one persistent local graph.
 - **Adopt locally:** initialize the checkout you already have and use the CLI or
   connect one MCP gateway.
 
-The practical payoff is less manual context assembly, fewer agent round trips,
-and fewer dependencies missed during review—with no hosted-service or
-source-egress overhead.
-
-The checked [behavioral-contract work](docs/BEHAVIORAL-CONTRACT.md) declares
-each production operation's intended guarantees and release-gates
-composition, recovery, confidence, and locality fixtures across every production
-operation/action path and declared egress boundary. C95 is implemented and
-terminal under the checked verifier and roadmap acceptance criteria; its stated
-limitations remain product bounds, not unsupported superiority claims.
+The practical value is less manual context assembly and fewer dependencies
+missed during review, with no hosted-service or source-egress overhead. Fewer
+agent round trips are an intended payoff; the narrow C93 replay measured no
+round-trip difference, so knodin does not claim a general productivity effect.
+
+Four checked answers define the product rather than a feature-count claim:
+
+- **Value:** less manual context assembly and fewer missed dependencies. C93
+  records the paired task method; C100 narrows one missed-dependency result from
+  a Salesforce class file to the exact Flow-invoked Apex method.
+- **ROI:** the intended mechanism is fewer corrective agent round trips without
+  hosted-service, authentication, or source-egress overhead. C93's accepted
+  two-task replay measured no round-trip benefit (both arms required one
+  correction), so this remains a product hypothesis rather than a measured
+  productivity claim. Billed cost and unobserved tokens remain unknown.
+- **Tomorrow:** run `knodin init`, check `knodin status`, then use the local CLI
+  or single MCP gateway against the checkout already on disk.
+- **Secret sauce:** stable identity, exact source evidence, explicit freshness,
+  and truthful budgets compose behind one compact local tool.
+
+The checked [behavioral contract](docs/BEHAVIORAL-CONTRACT.md) release-gates
+that composition. C101 binds the bounded resource-reachability, TypeScript DI,
+and Salesforce Flow-to-Apex evidence to the retained one-process semantic
+design. It rejects stale, truncated, ambiguous, or omission-only output when a
+mutation tries to promote it into a complete or exact claim. These are
+fixture-scoped guarantees with recorded limits, not universal superiority.
 
 ## How it compares
 
@@ -50,10 +66,11 @@ context over one locally persisted index.
 
 | Job | Typical specialized tools | knodin |
 |---|---|---|
-| Symbol navigation | CodeGraph, Serena, Sourcegraph | Ambiguity-safe definitions, callers, callees, paths, and verbatim source |
+| Symbol navigation | CodeGraph, Serena, Sourcegraph | Ambiguity-safe definitions, callers, callees, paths, bounded Inversify/tsyringe DI edges, and verbatim source |
 | Change impact and review | code-review-graph, Greptile, Graphify | Diff-aware review, impact traversal, tests, risks, and PR triage |
 | Architecture mapping | Graphify, GitNexus | Communities, hubs, boundaries, flows, wiki, and local visualization |
 | Search and context assembly | Aider repo map, Repomix, semantic search tools | Hybrid search, bounded source packs, and recoverable diagnostic compression |
+| Bounded resource and framework relationships | Code-Graph-RAG and framework-aware analyzers | Literal TS/JS resource paths, declared Inversify/tsyringe wiring, and one exact Salesforce Flow-to-Apex boundary, each with explicit omissions |
 | Deployment | Hosted services or separate local tools | One local process, SQLite graph, CLI, and one MCP gateway |
 
 ### Measured results
@@ -159,7 +176,7 @@ knodin repair
 | Command | Purpose |
 |---|---|
 | `knodin context` | Compact repository orientation and next-operation hint |
-| `knodin explain <symbol>` | Source, identity, callers, callees, and blast radius |
+| `knodin explain <symbol>` | Source, identity, typed callers/callees, static-analysis omissions, and blast radius |
 | `knodin review` | Itemized graph impact, test gaps, centrality, and bounded Git-history evidence |
 | `knodin query …` | Impact, paths, callers, callees, tests, flows, and structured graph queries |
 | `knodin search <query>` | Explainable structural-first search with a bounded local embedding fallback |
@@ -173,6 +190,8 @@ knodin repair
 | `knodin status --deep` | Index freshness, health, hooks, and integration status |
 | `knodin repair` | Repair or rebuild unhealthy local graph state |
 | `knodin diagnostics …` | Preview and archive explicit-allowlist local support evidence |
+| `knodin agent-hooks …` | Explicitly install, inspect, or remove optional user-global Claude lifecycle hooks |
+| `knodin telemetry …` | Opt into private repository-local adoption evidence and render the local dashboard |
 
 Run `knodin --help` or read the [CLI reference](docs/CLI.md) for complete syntax.
 
@@ -201,7 +220,11 @@ repository, and lifecycle capabilities. See the [MCP guide](docs/MCP.md).
 Each checkout stores its graph and lifecycle state in `.knodin/`. Shared model
 files live in the user cache rather than being duplicated per repository.
 Source and graph data stay local. Telemetry is metadata-only, disabled by
-default, and never sent by knodin. Troubleshooting diagnostics are also
+default, and never sent by knodin. Optional Claude hooks are installed only by
+`knodin agent-hooks install --client claude`; they inject bounded, freshness-aware
+session orientation and no-op outside initialized repositories. Adoption
+capture remains a separate opt-in through `knodin telemetry enable`.
+Troubleshooting diagnostics are also
 explicitly enabled, local-only, bounded, and never uploaded automatically.
 
 The optional `prs` command invokes the user's authenticated `gh` CLI. Network

package/dist/bin/cli.js

@@ -16,6 +16,8 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { canUseSessionContextCache, parseClaudeHookPayload, readSessionContextCache, recordClaudeLifecycleEvent, renderSessionContext, SESSION_CONTEXT_BUDGET_LINE, sessionStartHookOutput, writeSessionContextCache, } from "../src/agent-events.js";
+import { inspectClaudeAgentHooks, installClaudeAgentHooks, uninstallClaudeAgentHooks, } from "../src/agent-hooks.js";
 import { detectSupportedAgents, parseInitScope, } from "../src/agent-integration.js";
 import { refreshExternalGraphArtifacts, writeArtifactRefreshRecord, } from "../src/artifact-refresh.js";
 import { checkIndexed, extractPositionals, extractRepoFlag, parseReviewArgs, planIndex, resolveCliRuntimeCommand, resolveRepo, } from "../src/cli-args.js";
@@ -43,6 +45,7 @@ import { createRepairPlan, createRepairProgressRenderer, parseRepairCliArgs, res
 import { runRepositoryInitializationProcess } from "../src/repository-init-process.js";
 import { detectRepositorySignals, discoverRepositories, formatRepositoryHuman, initializeRepositories, inventoryRepository, parseFleetInitArgs, parseRepositoryCommandArgs, repositorySignalInspectionLimit, searchRepositories, withRepositorySignals, } from "../src/repository-management.js";
 import { applyResponseBudget } from "../src/response-budget.js";
+import { appendSessionEvent, clearSessionTelemetry, disableSessionTelemetry, enableSessionTelemetry, readSessionEvents, sessionTelemetryStatus, } from "../src/session-telemetry.js";
 import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../src/system-config.js";
 import { applyTrustedUpdate, checkTrustedUpdate, claimScheduledUpdateCheck, detectUpdateInstallMethod, explainTrustedUpdate, releaseScheduledUpdateCheck, rollbackTrustedUpdate, trustedUpdateStatus, } from "../src/update-policy.js";
 import { KNODIN_VERSION } from "../src/version.js";
@@ -158,7 +161,11 @@ function formatRepairHuman(result) {
             return `Repair verified: graph is healthy (${coverage.indexedFiles} indexed files, ${coverage.filesWithSymbols} files with symbols), but lifecycle routing is degraded. Run \`knodin init\`, then \`knodin status\`.\n`;
         return `Repair verified: graph is healthy (${coverage.indexedFiles} indexed files, ${coverage.filesWithSymbols} files with symbols).\n`;
     }
-    return `Repair finished with remaining issues. Run \`knodin status --deep\` for details.\n`;
+    const outstanding = result.outstandingIssues?.total ??
+        result.after.missing.files.length + result.after.missing.records.length;
+    const firstIssue = result.after.missing.files[0] ?? result.after.missing.records[0];
+    const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
+    return `Repair finished with ${outstanding.toLocaleString()} remaining issue(s).${detail} Run \`knodin status --deep\` for details.\n`;
 }
 function formatIndexHuman(result) {
     if (result.indexed.length === 0 && result.unchanged.length > 0) {
@@ -680,9 +687,9 @@ async function main() {
     };
     const repoFlag = selectorValue("--repo");
     const runtimeCommand = resolveCliRuntimeCommand(process);
-    // hook-refresh is an internal machine-to-machine command. Keep it JSON even
+    // Internal machine-to-machine commands stay JSON regardless of TTY state.
     // when an older installed hook predates the explicit --json argument.
-    const jsonOutput = invocation.options.json === true || cmd === "hook-refresh";
+    const jsonOutput = invocation.options.json === true || cmd === "hook-refresh" || cmd === "agent-event";
     // `--json` is a shared output flag. Repair owns its richer --json/--jsonl
     // parser; all other commands receive their original arguments minus it.
     const rest = cmd === "repair" ? rawRest : rawRest.filter((argument) => argument !== "--json");
@@ -1071,12 +1078,43 @@ async function main() {
             background.unref();
         }
     }
+    if (cmd === "agent-hooks") {
+        const action = invocation.commandPath[1];
+        const client = selectorValue("--client") ?? "claude";
+        if (client !== "claude")
+            throw new Error("knodin agent-hooks: only --client claude is supported");
+        if (invocation.options.dryRun === true && action !== "install")
+            throw new Error("knodin agent-hooks: --dry-run applies only to install");
+        let hookResult;
+        if (action === "install") {
+            const quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+            hookResult = installClaudeAgentHooks({
+                command: runtimeCommand.map(quote).join(" "),
+                dryRun: invocation.options.dryRun === true,
+            });
+        }
+        else if (action === "status")
+            hookResult = inspectClaudeAgentHooks();
+        else if (action === "uninstall")
+            hookResult = uninstallClaudeAgentHooks();
+        else
+            throw new Error("knodin agent-hooks requires install, status, or uninstall");
+        process.stdout.write(jsonOutput
+            ? `${JSON.stringify(hookResult)}\n`
+            : formatGenericHuman("agent-hooks", hookResult));
+        return;
+    }
     const resolved = resolveRepo(repoFlag, process.cwd());
     if (!resolved.ok) {
+        // Global agent hooks also run outside repositories and must fail open.
+        if (cmd === "agent-event")
+            return;
         process.stderr.write(`${resolved.error}\n`);
         process.exit(1);
     }
     const repo = resolved.repo;
+    if (cmd === "agent-event" && !fs.existsSync(resolveDbPath(repo)))
+        return;
     if (cmd === "doctor") {
         const gitProbe = spawnSync(gitExecutable(), ["rev-parse", "--is-inside-work-tree"], {
             cwd: repo,
@@ -1227,6 +1265,7 @@ async function main() {
     let repairWasPlan = false;
     let repairExitCode = 0;
     let statusWasWatched = false;
+    let agentEventOutput = false;
     const graphRead = async (run) => {
         const health = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
         if (!health.available) {
@@ -1242,6 +1281,103 @@ async function main() {
         return decorateGraphQueryResult(value, verified.state, verified.graph.freshness);
     };
     switch (cmd) {
+        case "agent-event": {
+            agentEventOutput = true;
+            const event = invocation.positionals[0];
+            if (!event)
+                throw new Error("knodin agent-event requires an event");
+            let payload;
+            try {
+                payload = parseClaudeHookPayload(await readBoundedStdin(65_536));
+            }
+            catch {
+                result = null;
+                break;
+            }
+            if (event !== "session-start") {
+                try {
+                    recordClaudeLifecycleEvent(repo, event, payload);
+                }
+                catch {
+                    // Optional telemetry must never interrupt the agent.
+                }
+                result = null;
+                break;
+            }
+            const startedAt = performance.now();
+            let status;
+            try {
+                status = await engine.status(repo, { audit: "cached" });
+            }
+            catch {
+                if (payload.session_id)
+                    try {
+                        appendSessionEvent(repo, {
+                            event: "session_start",
+                            sessionId: payload.session_id,
+                            context: "unavailable",
+                            freshness: "unavailable",
+                            latencyMs: Math.round((performance.now() - startedAt) * 100) / 100,
+                            cacheHit: false,
+                        });
+                    }
+                    catch {
+                        // Best-effort local recording remains fail-open.
+                    }
+                result = sessionStartHookOutput(`## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status before relying on graph evidence.`);
+                break;
+            }
+            const freshness = status.freshness?.state ?? "unknown";
+            const cacheKey = JSON.stringify({
+                schemaVersion: 1,
+                head: status.freshness?.currentHead,
+                fingerprint: status.freshness?.workingTree?.indexedFingerprint,
+                generation: status.indexGeneration,
+                budgets: [600, 8192, 12],
+            });
+            const cacheEligible = canUseSessionContextCache(status.status, freshness);
+            let text = cacheEligible ? readSessionContextCache(repo, cacheKey) : null;
+            let cacheHit = text !== null;
+            let contextState = "delivered";
+            if (!cacheEligible) {
+                contextState = "degraded";
+                text = `## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nGraph evidence is ${freshness}. Run knodin status and follow its repair or reindex guidance before relying on graph evidence.`;
+            }
+            else if (!text) {
+                cacheHit = false;
+                try {
+                    const context = await buildKnodinContext(engine, "Orient this coding session", repo, undefined, []);
+                    text = renderSessionContext(context, freshness);
+                    writeSessionContextCache(repo, cacheKey, text);
+                }
+                catch {
+                    contextState = "unavailable";
+                    text = `## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status, then call the connected knodin context operation when needed.`;
+                }
+            }
+            if (payload.session_id)
+                try {
+                    appendSessionEvent(repo, {
+                        event: "session_start",
+                        sessionId: payload.session_id,
+                        context: contextState,
+                        freshness: freshness === "fresh"
+                            ? "fresh"
+                            : status.status === "repair-needed"
+                                ? "repair-needed"
+                                : freshness === "unknown"
+                                    ? "unavailable"
+                                    : "stale",
+                        latencyMs: Math.round((performance.now() - startedAt) * 100) / 100,
+                        cacheHit,
+                    });
+                }
+                catch {
+                    // Best-effort local recording remains fail-open.
+                }
+            result = sessionStartHookOutput(text);
+            break;
+        }
         case "doctor": {
             const client = selectorValue("--client");
             if (client !== undefined &&
@@ -1781,7 +1917,7 @@ async function main() {
                 ? ""
                 : (rest[1] ?? "");
             if (!pattern) {
-                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|batch_outline|project_overview|shortest_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
+                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
                 process.exit(1);
             }
             const directionValue = selectorValue("--direction");
@@ -1800,7 +1936,15 @@ async function main() {
             }
             // shortest_path: `knodin query shortest_path <from> <to>`
             // rename_preview: `knodin query rename_preview <old> <new>`
-            const to = pattern === "shortest_path" || pattern === "rename_preview" ? rest[2] : undefined;
+            const to = pattern === "shortest_path" ||
+                pattern === "cross_substrate_path" ||
+                pattern === "rename_preview"
+                ? rest[2]
+                : undefined;
+            if (pattern === "cross_substrate_path" && !to) {
+                process.stderr.write("knodin query cross_substrate_path requires <from> and <to>\n");
+                process.exit(1);
+            }
             if (pattern === "rename_preview" && !to) {
                 process.stderr.write("knodin query rename_preview requires <old> and <new>\n");
                 process.exit(1);
@@ -1863,6 +2007,11 @@ async function main() {
                     : undefined,
                 includeDataFlow: pattern === "traverse" ? rest.includes("--data-flow") : undefined,
                 flowVariable: pattern === "flow_analysis" ? selectorValue("--variable") : undefined,
+                resourceOffset: pattern === "resource_reachability" && selectorValue("--offset")
+                    ? Number(selectorValue("--offset"))
+                    : undefined,
+                resourceMaxBytes: pattern === "resource_reachability" ? responseBudget.bytes : undefined,
+                resourceMaxTokens: pattern === "resource_reachability" ? responseBudget.tokens : undefined,
                 architectureFacets: facetsValue,
                 topN: selectorValue("--top") ? Number(selectorValue("--top")) : undefined,
                 sort: selectorValue("--sort"),
@@ -1956,16 +2105,23 @@ async function main() {
             if (!Number.isInteger(retentionDays) || retentionDays < 1 || retentionDays > 3650)
                 throw new Error("knodin telemetry: --retention-days must be an integer from 1 to 3650");
             const input = selectorValue("--input");
-            if (action === "status")
-                result = telemetryStatus(repo, input, retentionDays);
+            if (action === "enable")
+                result = enableSessionTelemetry(repo);
+            else if (action === "disable")
+                result = disableSessionTelemetry(repo);
+            else if (action === "status")
+                result = {
+                    ...telemetryStatus(repo, input, retentionDays),
+                    session: sessionTelemetryStatus(repo, retentionDays),
+                };
             else if (action === "report")
-                result = writeTelemetryReport(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"));
+                result = writeTelemetryReport(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"), readSessionEvents(repo, retentionDays));
             else if (action === "export")
-                result = exportTelemetry(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"));
+                result = exportTelemetry(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"), readSessionEvents(repo, retentionDays));
             else if (action === "clear")
-                result = clearTelemetry(repo, input);
+                result = { ...clearTelemetry(repo, input), session: clearSessionTelemetry(repo) };
             else
-                throw new Error("knodin telemetry requires status, report, export, or clear");
+                throw new Error("knodin telemetry requires enable, disable, status, report, export, or clear");
             break;
         }
         case "diagnostics": {
@@ -2057,6 +2213,11 @@ async function main() {
             process.exit(1);
     }
     await engine.close();
+    if (agentEventOutput) {
+        if (result !== null && result !== undefined)
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+        return;
+    }
     if (statusWasWatched)
         return;
     const boundedResult = applyResponseBudget(result, cmd, responseBudget, {
@@ -2111,55 +2272,80 @@ try {
 }
 catch (err) {
     const argv = process.argv.slice(2);
-    const repoIndex = argv.indexOf("--repo");
-    const equalsRepo = argv.find((argument) => argument.startsWith("--repo="));
-    const explicitRepo = repoIndex >= 0 ? argv[repoIndex + 1] : undefined;
-    let candidate = process.cwd();
-    if (explicitRepo)
-        candidate = explicitRepo;
-    else if (equalsRepo)
-        candidate = equalsRepo.slice("--repo=".length);
-    const command = argv.find((argument, index) => {
-        if (argument.startsWith("-"))
-            return false;
-        return !(index > 0 && argv[index - 1] === "--repo") && argument !== candidate;
-    });
-    const knownCommands = new Set([
-        "init",
-        "configure",
-        "index",
-        "doctor",
-        "status",
-        "wait",
-        "repair",
-        "serve",
-        "context",
-        "explain",
-        "review",
-        "map",
-        "search",
-        "query",
-        "rename",
-        "wiki",
-        "visualize",
-        "pack",
-        "compress",
-        "prs",
-        "worktrees",
-        "telemetry",
-        "diagnostics",
-        "system",
-        "repos",
-        "remote",
-        "update",
-    ]);
-    const diagnostic = recordDiagnosticFailure(candidate, {
-        surface: "cli",
-        operation: command && knownCommands.has(command) ? command : "unknown",
-        phase: "dispatch",
-        error: err,
-    });
-    const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
-    console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
-    process.exit(1);
+    let invokedCommand;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--repo") {
+            index += 1;
+            continue;
+        }
+        if (argument?.startsWith("--repo=") || argument === "--json")
+            continue;
+        if (!argument?.startsWith("-")) {
+            invokedCommand = argument;
+            break;
+        }
+    }
+    if (invokedCommand === "agent-event") {
+        const eventIndex = argv.indexOf("agent-event");
+        if (argv[eventIndex + 1] === "session-start") {
+            process.stdout.write(`${JSON.stringify(sessionStartHookOutput(`## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status before relying on graph evidence.`))}\n`);
+        }
+        process.exitCode = 0;
+    }
+    else {
+        const repoIndex = argv.indexOf("--repo");
+        const equalsRepo = argv.find((argument) => argument.startsWith("--repo="));
+        const explicitRepo = repoIndex >= 0 ? argv[repoIndex + 1] : undefined;
+        let candidate = process.cwd();
+        if (explicitRepo)
+            candidate = explicitRepo;
+        else if (equalsRepo)
+            candidate = equalsRepo.slice("--repo=".length);
+        const command = argv.find((argument, index) => {
+            if (argument.startsWith("-"))
+                return false;
+            return !(index > 0 && argv[index - 1] === "--repo") && argument !== candidate;
+        });
+        const knownCommands = new Set([
+            "init",
+            "configure",
+            "agent-hooks",
+            "agent-event",
+            "index",
+            "doctor",
+            "status",
+            "wait",
+            "repair",
+            "serve",
+            "context",
+            "explain",
+            "review",
+            "map",
+            "search",
+            "query",
+            "rename",
+            "wiki",
+            "visualize",
+            "pack",
+            "compress",
+            "prs",
+            "worktrees",
+            "telemetry",
+            "diagnostics",
+            "system",
+            "repos",
+            "remote",
+            "update",
+        ]);
+        const diagnostic = recordDiagnosticFailure(candidate, {
+            surface: "cli",
+            operation: command && knownCommands.has(command) ? command : "unknown",
+            phase: "dispatch",
+            error: err,
+        });
+        const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
+        console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
+        process.exit(1);
+    }
 }

package/dist/src/agent-events.js

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import path from "node:path";
+import { countOutputTokens } from "./output-telemetry.js";
+import { appendSessionEvent, } from "./session-telemetry.js";
+export const SESSION_CONTEXT_BUDGET_LINE = "Budget: at most 600 tokens, 8 KiB, 12 items.";
+const KNOWN_OPERATIONS = new Set([
+    "context",
+    "explain",
+    "review",
+    "map",
+    "search",
+    "query",
+    "pack",
+    "compress",
+    "execute",
+    "prs",
+    "wiki",
+    "docs",
+    "remote",
+]);
+function knownOperation(value) {
+    return typeof value === "string" && KNOWN_OPERATIONS.has(value) ? value : undefined;
+}
+export function parseClaudeHookPayload(raw) {
+    if (Buffer.byteLength(raw) > 65_536)
+        throw new Error("knodin agent-event: hook input exceeds 65536 bytes");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("knodin agent-event: hook input must be a JSON object");
+    return parsed;
+}
+export function classifyTool(payload) {
+    const name = payload.tool_name ?? "";
+    if (name === "mcp__knodin__knodin") {
+        const operation = knownOperation(payload.tool_input?.operation);
+        return {
+            toolCategory: "knodin",
+            ...(operation ? { operation } : {}),
+        };
+    }
+    if (["Read", "Glob", "Grep"].includes(name))
+        return { toolCategory: "manual_traversal" };
+    if (["Edit", "Write", "NotebookEdit", "MultiEdit"].includes(name))
+        return { toolCategory: "edit" };
+    if (name === "Bash") {
+        const command = typeof payload.tool_input?.command === "string" ? payload.tool_input.command : "";
+        const knodin = command.match(/(?:^|[;&|]\s*)knodin\s+([a-z][a-z0-9-]*)/i);
+        if (knodin) {
+            const operation = knownOperation(knodin[1]?.toLowerCase());
+            return { toolCategory: "knodin", ...(operation ? { operation } : {}) };
+        }
+        if (/(?:^|[;&|]\s*)(?:rg|grep|find)\b/.test(command))
+            return { toolCategory: "manual_traversal" };
+    }
+    return { toolCategory: "other" };
+}
+function cachePath(repo) {
+    return path.join(repo, ".knodin", "session-context-cache.json");
+}
+export function readSessionContextCache(repo, key, now = Date.now()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath(repo), "utf8"));
+        return parsed.key === key && typeof parsed.at === "number" && now - parsed.at <= 300_000
+            ? (parsed.text ?? null)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSessionContextCache(repo, key, text) {
+    const filePath = cachePath(repo);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify({ schemaVersion: 1, key, at: Date.now(), text }), {
+        mode: 0o600,
+        flag: "wx",
+    });
+    fs.renameSync(temporary, filePath);
+}
+export function canUseSessionContextCache(status, freshness) {
+    return status === "healthy" && freshness === "fresh";
+}
+export function renderSessionContext(context, freshness) {
+    const list = (values, render) => (values ?? []).slice(0, 3).map(render).join(", ") || "none reported";
+    let text = [
+        "## knodin session context",
+        `Graph evidence: ${freshness}. Treat stale or unavailable evidence as incomplete.`,
+        SESSION_CONTEXT_BUDGET_LINE,
+        `Repository: ${context.stats?.files ?? "?"} files, ${context.stats?.symbols ?? "?"} symbols.`,
+        `Subsystems: ${list(context.communities, (value) => `${value.name} (${value.size})`)}`,
+        `Hubs: ${list(context.hubs, (value) => `${value.symbol} (${value.degree})`)}`,
+        `Flows: ${list(context.flows, (value) => value.symbol ?? "unnamed")}`,
+        `Suggested next operation: ${context.suggestedOperation ?? "context"} (heuristic only).`,
+        "Use exact source evidence and preserve ambiguity, freshness, omissions, and response budgets.",
+    ].join("\n");
+    while ((countOutputTokens(text) > 600 || Buffer.byteLength(text) > 8192) && text.includes("\n")) {
+        text = `${text.slice(0, text.lastIndexOf("\n"))}\nContext truncated to the configured session budget.`;
+    }
+    return text;
+}
+export function recordClaudeLifecycleEvent(repo, event, payload) {
+    const sessionId = payload.session_id;
+    if (!sessionId)
+        return false;
+    const names = {
+        "session-start": "session_start",
+        "session-end": "session_end",
+        "turn-start": "turn_start",
+        "turn-end": "turn_end",
+        "pre-tool": "tool_start",
+        "post-tool": "tool_success",
+        "tool-failure": "tool_failure",
+    };
+    const mapped = names[event];
+    if (!mapped)
+        return false;
+    const tool = event.includes("tool") ? classifyTool(payload) : undefined;
+    return appendSessionEvent(repo, { event: mapped, sessionId, ...tool });
+}
+export function sessionStartHookOutput(text) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: text,
+        },
+    };
+}