hyntx 3.0.1 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +118 -963
- package/dist/cli.d.ts +1 -440
- package/dist/cli.js +5183 -6762
- package/dist/index.d.ts +696 -2
- package/dist/index.js +5392 -1
- package/package.json +22 -36
- package/dist/api/index.d.ts +0 -1083
- package/dist/api/index.js +0 -1
- package/dist/chunk-24U3LCZC.js +0 -3347
- package/dist/chunk-TLJ2AIHG.js +0 -389
- package/dist/shell-config-VEIMSP5W.js +0 -2
package/dist/index.d.ts
CHANGED
|
@@ -1,2 +1,696 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Shared types for Hyntx v4.
|
|
3
|
+
*
|
|
4
|
+
* Two layers live here:
|
|
5
|
+
* 1. The raw session model (`Session`, `Turn`, `ToolCall`...) produced by the
|
|
6
|
+
* session reader. It is in-memory only and may hold unsanitized text.
|
|
7
|
+
* 2. The serializable `Report` contract. Every string in a `Report` has been
|
|
8
|
+
* sanitized; HTML report, plugin and LLM engines build on this layer.
|
|
9
|
+
*/
|
|
10
|
+
type TokenUsage = {
|
|
11
|
+
readonly input: number;
|
|
12
|
+
readonly output: number;
|
|
13
|
+
readonly cacheRead: number;
|
|
14
|
+
readonly cacheCreation: number;
|
|
15
|
+
};
|
|
16
|
+
declare const DenialKind: {
|
|
17
|
+
/** The human rejected the tool call in the permission dialog. */
|
|
18
|
+
readonly USER: "user";
|
|
19
|
+
/** A settings permission rule denied the call. */
|
|
20
|
+
readonly RULE: "rule";
|
|
21
|
+
/** The auto-mode classifier blocked the call. */
|
|
22
|
+
readonly CLASSIFIER: "classifier";
|
|
23
|
+
/** A PreToolUse hook blocked the call. */
|
|
24
|
+
readonly HOOK: "hook";
|
|
25
|
+
};
|
|
26
|
+
type DenialKind = (typeof DenialKind)[keyof typeof DenialKind];
|
|
27
|
+
type ToolResult = {
|
|
28
|
+
readonly timestamp: string;
|
|
29
|
+
readonly isError: boolean;
|
|
30
|
+
readonly denial: DenialKind | null;
|
|
31
|
+
/** First characters of the result text (sanitized at read time). */
|
|
32
|
+
readonly excerpt: string;
|
|
33
|
+
};
|
|
34
|
+
type ToolCall = {
|
|
35
|
+
readonly id: string;
|
|
36
|
+
readonly name: string;
|
|
37
|
+
readonly timestamp: string;
|
|
38
|
+
readonly sidechain: boolean;
|
|
39
|
+
/** File path, URL, pattern or subagent type, depending on the tool. */
|
|
40
|
+
readonly target: string | null;
|
|
41
|
+
/** Bash command line (sanitized at read time, truncated). */
|
|
42
|
+
readonly command: string | null;
|
|
43
|
+
readonly result: ToolResult | null;
|
|
44
|
+
};
|
|
45
|
+
declare const PromptSource: {
|
|
46
|
+
readonly TYPED: "typed";
|
|
47
|
+
readonly SUGGESTION: "suggestion";
|
|
48
|
+
readonly UNKNOWN: "unknown";
|
|
49
|
+
};
|
|
50
|
+
type PromptSource = (typeof PromptSource)[keyof typeof PromptSource];
|
|
51
|
+
type Prompt = {
|
|
52
|
+
readonly uuid: string;
|
|
53
|
+
readonly timestamp: string;
|
|
54
|
+
/** Text sanitized at read time, then truncated. */
|
|
55
|
+
readonly text: string;
|
|
56
|
+
readonly source: PromptSource;
|
|
57
|
+
readonly permissionMode: string | null;
|
|
58
|
+
};
|
|
59
|
+
type Interruption = {
|
|
60
|
+
readonly timestamp: string;
|
|
61
|
+
readonly duringToolUse: boolean;
|
|
62
|
+
};
|
|
63
|
+
declare const TurnKind: {
|
|
64
|
+
/** Started by a human-typed prompt. */
|
|
65
|
+
readonly TYPED: "typed";
|
|
66
|
+
/** Started by a prompt-expanding slash command (skill/custom command). */
|
|
67
|
+
readonly COMMAND: "command";
|
|
68
|
+
};
|
|
69
|
+
type TurnKind = (typeof TurnKind)[keyof typeof TurnKind];
|
|
70
|
+
type Turn = {
|
|
71
|
+
readonly index: number;
|
|
72
|
+
readonly kind: TurnKind;
|
|
73
|
+
readonly command: string | null;
|
|
74
|
+
readonly prompt: Prompt;
|
|
75
|
+
readonly startedAt: string;
|
|
76
|
+
readonly endedAt: string;
|
|
77
|
+
readonly tokens: TokenUsage;
|
|
78
|
+
readonly assistantMessages: number;
|
|
79
|
+
readonly toolCalls: readonly ToolCall[];
|
|
80
|
+
readonly interruptions: readonly Interruption[];
|
|
81
|
+
readonly models: readonly string[];
|
|
82
|
+
/** Last assistant text of the turn (sanitized, truncated). */
|
|
83
|
+
readonly assistantExcerpt: string | null;
|
|
84
|
+
};
|
|
85
|
+
type Compaction = {
|
|
86
|
+
readonly timestamp: string;
|
|
87
|
+
readonly trigger: string | null;
|
|
88
|
+
readonly preTokens: number | null;
|
|
89
|
+
};
|
|
90
|
+
type ModelUsage = {
|
|
91
|
+
readonly messages: number;
|
|
92
|
+
readonly tokens: TokenUsage;
|
|
93
|
+
};
|
|
94
|
+
type SlashCommandUse = {
|
|
95
|
+
readonly name: string;
|
|
96
|
+
readonly timestamp: string;
|
|
97
|
+
};
|
|
98
|
+
type SubagentActivity = {
|
|
99
|
+
readonly agentIds: readonly string[];
|
|
100
|
+
/** Task/Agent tool calls issued by the main thread. */
|
|
101
|
+
readonly invocations: number;
|
|
102
|
+
readonly tokens: TokenUsage;
|
|
103
|
+
readonly toolCalls: number;
|
|
104
|
+
};
|
|
105
|
+
type Session = {
|
|
106
|
+
readonly id: string;
|
|
107
|
+
readonly project: string;
|
|
108
|
+
readonly projectDir: string;
|
|
109
|
+
readonly cwd: string | null;
|
|
110
|
+
readonly gitBranch: string | null;
|
|
111
|
+
readonly entrypoint: string | null;
|
|
112
|
+
readonly versions: readonly string[];
|
|
113
|
+
readonly title: string | null;
|
|
114
|
+
readonly startedAt: string;
|
|
115
|
+
readonly endedAt: string;
|
|
116
|
+
readonly turns: readonly Turn[];
|
|
117
|
+
readonly toolCalls: readonly ToolCall[];
|
|
118
|
+
readonly tokens: TokenUsage;
|
|
119
|
+
readonly models: Readonly<Record<string, ModelUsage>>;
|
|
120
|
+
readonly assistantMessages: number;
|
|
121
|
+
readonly apiErrors: number;
|
|
122
|
+
readonly subagents: SubagentActivity;
|
|
123
|
+
/** Typed prompts per permission mode. */
|
|
124
|
+
readonly permissionModes: Readonly<Record<string, number>>;
|
|
125
|
+
readonly permissionModesSeen: readonly string[];
|
|
126
|
+
readonly planModeUsed: boolean;
|
|
127
|
+
readonly slashCommands: readonly SlashCommandUse[];
|
|
128
|
+
readonly compactions: readonly Compaction[];
|
|
129
|
+
readonly interruptionsOutsideTurns: number;
|
|
130
|
+
readonly sourceFiles: readonly string[];
|
|
131
|
+
};
|
|
132
|
+
type ReadStats = {
|
|
133
|
+
readonly filesRead: number;
|
|
134
|
+
readonly subagentFilesRead: number;
|
|
135
|
+
readonly recordsRead: number;
|
|
136
|
+
/** Lines that were not valid JSON objects. */
|
|
137
|
+
readonly recordsSkipped: number;
|
|
138
|
+
readonly unknownRecordTypes: Readonly<Record<string, number>>;
|
|
139
|
+
/** Assistant/user records already seen (resumed or streamed copies). */
|
|
140
|
+
readonly duplicateRecords: number;
|
|
141
|
+
readonly orphanToolResults: number;
|
|
142
|
+
readonly claudeCodeVersions: readonly string[];
|
|
143
|
+
/** Files that could not be read (deleted or unreadable mid-run). */
|
|
144
|
+
readonly filesFailed: number;
|
|
145
|
+
/** First few failures, as "file: reason". */
|
|
146
|
+
readonly failedFiles: readonly string[];
|
|
147
|
+
/** Sessions with no typed prompt, tool call or reply, left out. */
|
|
148
|
+
readonly emptySessions: number;
|
|
149
|
+
};
|
|
150
|
+
type ReadSessionsOptions = {
|
|
151
|
+
readonly projectsDir?: string;
|
|
152
|
+
readonly from?: Date;
|
|
153
|
+
readonly to?: Date;
|
|
154
|
+
/** Case-insensitive substring of the project name or directory. */
|
|
155
|
+
readonly project?: string;
|
|
156
|
+
readonly onProgress?: (filesRead: number) => void;
|
|
157
|
+
};
|
|
158
|
+
type ReadSessionsResult = {
|
|
159
|
+
readonly sessions: readonly Session[];
|
|
160
|
+
readonly stats: ReadStats;
|
|
161
|
+
};
|
|
162
|
+
type TokenTotals = TokenUsage & {
|
|
163
|
+
/** input + output + cacheRead + cacheCreation */
|
|
164
|
+
readonly total: number;
|
|
165
|
+
/** cacheRead / (input + cacheRead + cacheCreation); null without input. */
|
|
166
|
+
readonly cacheHitRatio: number | null;
|
|
167
|
+
};
|
|
168
|
+
type ToolStat = {
|
|
169
|
+
readonly name: string;
|
|
170
|
+
readonly calls: number;
|
|
171
|
+
/** Failed calls, excluding denials. */
|
|
172
|
+
readonly errors: number;
|
|
173
|
+
readonly denied: number;
|
|
174
|
+
readonly errorRate: number;
|
|
175
|
+
};
|
|
176
|
+
type ModelMix = {
|
|
177
|
+
readonly model: string;
|
|
178
|
+
readonly messages: number;
|
|
179
|
+
readonly tokens: number;
|
|
180
|
+
readonly share: number;
|
|
181
|
+
};
|
|
182
|
+
type Distribution = {
|
|
183
|
+
readonly median: number;
|
|
184
|
+
readonly p90: number;
|
|
185
|
+
readonly max: number;
|
|
186
|
+
readonly buckets: readonly {
|
|
187
|
+
readonly label: string;
|
|
188
|
+
readonly count: number;
|
|
189
|
+
}[];
|
|
190
|
+
};
|
|
191
|
+
type AggregateMetrics = {
|
|
192
|
+
readonly sessions: number;
|
|
193
|
+
readonly turns: number;
|
|
194
|
+
readonly typedPrompts: number;
|
|
195
|
+
readonly acceptedSuggestions: number;
|
|
196
|
+
readonly assistantMessages: number;
|
|
197
|
+
readonly toolCalls: number;
|
|
198
|
+
readonly toolErrors: number;
|
|
199
|
+
readonly toolDenied: number;
|
|
200
|
+
readonly toolErrorRate: number;
|
|
201
|
+
readonly tools: readonly ToolStat[];
|
|
202
|
+
readonly tokens: TokenTotals;
|
|
203
|
+
readonly models: readonly ModelMix[];
|
|
204
|
+
readonly subagents: {
|
|
205
|
+
readonly invocations: number;
|
|
206
|
+
readonly sessionsUsing: number;
|
|
207
|
+
readonly tokens: number;
|
|
208
|
+
readonly toolCalls: number;
|
|
209
|
+
};
|
|
210
|
+
readonly permissionModes: Readonly<Record<string, number>>;
|
|
211
|
+
readonly planMode: {
|
|
212
|
+
readonly sessionsUsing: number;
|
|
213
|
+
readonly typedPrompts: number;
|
|
214
|
+
};
|
|
215
|
+
readonly slashCommands: readonly {
|
|
216
|
+
readonly name: string;
|
|
217
|
+
readonly count: number;
|
|
218
|
+
}[];
|
|
219
|
+
readonly interruptions: number;
|
|
220
|
+
readonly compactions: number;
|
|
221
|
+
readonly apiErrors: number;
|
|
222
|
+
/** Distribution of active minutes per session (idle gaps > 10m excluded). */
|
|
223
|
+
readonly sessionMinutes: Distribution;
|
|
224
|
+
readonly sessionTurns: Distribution;
|
|
225
|
+
};
|
|
226
|
+
type SessionMetrics = {
|
|
227
|
+
readonly sessionId: string;
|
|
228
|
+
readonly project: string;
|
|
229
|
+
readonly title: string | null;
|
|
230
|
+
readonly startedAt: string;
|
|
231
|
+
readonly endedAt: string;
|
|
232
|
+
/** Wall-clock span. */
|
|
233
|
+
readonly durationMinutes: number;
|
|
234
|
+
/** Span excluding idle gaps longer than 10 minutes. */
|
|
235
|
+
readonly activeMinutes: number;
|
|
236
|
+
readonly turns: number;
|
|
237
|
+
readonly typedPrompts: number;
|
|
238
|
+
readonly toolCalls: number;
|
|
239
|
+
readonly toolErrors: number;
|
|
240
|
+
readonly toolDenied: number;
|
|
241
|
+
readonly tokens: TokenTotals;
|
|
242
|
+
readonly primaryModel: string | null;
|
|
243
|
+
readonly subagentInvocations: number;
|
|
244
|
+
readonly interruptions: number;
|
|
245
|
+
readonly compactions: number;
|
|
246
|
+
readonly planModeUsed: boolean;
|
|
247
|
+
};
|
|
248
|
+
type Metrics = {
|
|
249
|
+
readonly overall: AggregateMetrics;
|
|
250
|
+
readonly byProject: readonly (AggregateMetrics & {
|
|
251
|
+
readonly project: string;
|
|
252
|
+
})[];
|
|
253
|
+
readonly byDay: readonly (AggregateMetrics & {
|
|
254
|
+
readonly date: string;
|
|
255
|
+
})[];
|
|
256
|
+
readonly sessions: readonly SessionMetrics[];
|
|
257
|
+
readonly activity: {
|
|
258
|
+
/** Typed prompts per local hour, index 0-23. */
|
|
259
|
+
readonly byHour: readonly number[];
|
|
260
|
+
/** Typed prompts per weekday, index 0 = Sunday. */
|
|
261
|
+
readonly byWeekday: readonly number[];
|
|
262
|
+
};
|
|
263
|
+
};
|
|
264
|
+
/** Compact per-day record; persisted under ~/.hyntx so trends outlive logs. */
|
|
265
|
+
type DailyPoint = {
|
|
266
|
+
readonly date: string;
|
|
267
|
+
readonly sessions: number;
|
|
268
|
+
readonly turns: number;
|
|
269
|
+
readonly typedPrompts: number;
|
|
270
|
+
readonly toolCalls: number;
|
|
271
|
+
readonly toolErrors: number;
|
|
272
|
+
readonly toolDenied: number;
|
|
273
|
+
readonly interruptions: number;
|
|
274
|
+
readonly corrections: number;
|
|
275
|
+
readonly compactions: number;
|
|
276
|
+
readonly subagentInvocations: number;
|
|
277
|
+
readonly activeMinutes: number;
|
|
278
|
+
readonly tokens: TokenUsage;
|
|
279
|
+
};
|
|
280
|
+
declare const EpisodeType: {
|
|
281
|
+
readonly INTERRUPTION: "interruption";
|
|
282
|
+
readonly CORRECTION: "correction";
|
|
283
|
+
readonly TOOL_ERROR_LOOP: "tool-error-loop";
|
|
284
|
+
readonly TOOL_DENIED: "tool-denied";
|
|
285
|
+
readonly REWORK: "rework";
|
|
286
|
+
readonly CONTEXT_PRESSURE: "context-pressure";
|
|
287
|
+
readonly REPEATED_INSTRUCTION: "repeated-instruction";
|
|
288
|
+
readonly READONLY_COMMAND: "frequent-readonly-command";
|
|
289
|
+
readonly MODEL_SWITCH: "model-switch";
|
|
290
|
+
};
|
|
291
|
+
type EpisodeType = (typeof EpisodeType)[keyof typeof EpisodeType];
|
|
292
|
+
type EpisodeRef = {
|
|
293
|
+
readonly sessionId: string;
|
|
294
|
+
readonly project: string;
|
|
295
|
+
readonly timestamp: string;
|
|
296
|
+
readonly prompt: string;
|
|
297
|
+
};
|
|
298
|
+
type EpisodeContext = {
|
|
299
|
+
/** Prompt that opened the previous turn (what the user originally asked). */
|
|
300
|
+
readonly previousPrompt: string | null;
|
|
301
|
+
/** Tail of the assistant's last text before the episode. */
|
|
302
|
+
readonly assistantExcerpt: string | null;
|
|
303
|
+
/** Tool usage counts in the surrounding turn. */
|
|
304
|
+
readonly tools: Readonly<Record<string, number>>;
|
|
305
|
+
/** Type-specific facts (counts, file, command, reason...). */
|
|
306
|
+
readonly detail: Readonly<Record<string, string | number | boolean | null>>;
|
|
307
|
+
};
|
|
308
|
+
type Episode = {
|
|
309
|
+
readonly id: string;
|
|
310
|
+
readonly type: EpisodeType;
|
|
311
|
+
readonly sessionId: string;
|
|
312
|
+
readonly project: string;
|
|
313
|
+
readonly timestamp: string;
|
|
314
|
+
/** 0-1. Heuristic detectors say so explicitly; the LLM step confirms. */
|
|
315
|
+
readonly confidence: number;
|
|
316
|
+
/** Occurrences collapsed into this episode (>= 1). */
|
|
317
|
+
readonly count: number;
|
|
318
|
+
/** Sanitized excerpt of the triggering prompt, when there is one. */
|
|
319
|
+
readonly prompt: string | null;
|
|
320
|
+
readonly summary: string;
|
|
321
|
+
readonly context: EpisodeContext;
|
|
322
|
+
/** Other occurrences (repeated instructions); at most a few. */
|
|
323
|
+
readonly related: readonly EpisodeRef[];
|
|
324
|
+
};
|
|
325
|
+
type PromptTraitFinding = {
|
|
326
|
+
readonly trait: string;
|
|
327
|
+
readonly outcome: string;
|
|
328
|
+
readonly withTrait: {
|
|
329
|
+
readonly n: number;
|
|
330
|
+
readonly value: number;
|
|
331
|
+
};
|
|
332
|
+
readonly withoutTrait: {
|
|
333
|
+
readonly n: number;
|
|
334
|
+
readonly value: number;
|
|
335
|
+
};
|
|
336
|
+
/** Smallest group size used to decide significance. */
|
|
337
|
+
readonly sampleSize: number;
|
|
338
|
+
/**
|
|
339
|
+
* True when both groups reach the minimum size and the gap clears a fixed
|
|
340
|
+
* threshold. Not a statistical test: exploratory only, never an insight.
|
|
341
|
+
*/
|
|
342
|
+
readonly meetsThreshold: boolean;
|
|
343
|
+
readonly description: string;
|
|
344
|
+
};
|
|
345
|
+
declare const Severity: {
|
|
346
|
+
readonly HIGH: "high";
|
|
347
|
+
readonly MEDIUM: "medium";
|
|
348
|
+
readonly LOW: "low";
|
|
349
|
+
};
|
|
350
|
+
type Severity = (typeof Severity)[keyof typeof Severity];
|
|
351
|
+
declare const InsightKind: {
|
|
352
|
+
readonly INTERRUPTIONS: "interruptions";
|
|
353
|
+
readonly CORRECTIONS: "corrections";
|
|
354
|
+
readonly TOOL_ERROR_LOOPS: "tool-error-loops";
|
|
355
|
+
readonly TOOL_DENIALS: "tool-denials";
|
|
356
|
+
readonly REWORK: "rework";
|
|
357
|
+
readonly CONTEXT_PRESSURE: "context-pressure";
|
|
358
|
+
readonly REPEATED_INSTRUCTION: "repeated-instruction";
|
|
359
|
+
readonly READONLY_COMMANDS: "readonly-commands";
|
|
360
|
+
readonly MODEL_SWITCHES: "model-switches";
|
|
361
|
+
};
|
|
362
|
+
type InsightKind = (typeof InsightKind)[keyof typeof InsightKind];
|
|
363
|
+
type EvidenceExample = {
|
|
364
|
+
readonly project: string;
|
|
365
|
+
/** YYYY-MM-DD, local time. */
|
|
366
|
+
readonly date: string;
|
|
367
|
+
readonly sessionId: string;
|
|
368
|
+
readonly quote: string;
|
|
369
|
+
readonly note: string | null;
|
|
370
|
+
};
|
|
371
|
+
type InsightEvidence = {
|
|
372
|
+
readonly count: number;
|
|
373
|
+
readonly sessions: number;
|
|
374
|
+
readonly projects: readonly string[];
|
|
375
|
+
/** Out of how many comparable items (e.g. typed prompts); null if n/a. */
|
|
376
|
+
readonly outOf: number | null;
|
|
377
|
+
readonly examples: readonly EvidenceExample[];
|
|
378
|
+
};
|
|
379
|
+
type InsightAction = {
|
|
380
|
+
readonly kind: 'claude-md-rule';
|
|
381
|
+
readonly scope: 'project' | 'user';
|
|
382
|
+
readonly project: string | null;
|
|
383
|
+
readonly file: string;
|
|
384
|
+
/** Exact line(s) to append. */
|
|
385
|
+
readonly text: string;
|
|
386
|
+
} | {
|
|
387
|
+
readonly kind: 'permission-allow';
|
|
388
|
+
readonly patterns: readonly string[];
|
|
389
|
+
readonly file: string;
|
|
390
|
+
/** JSON fragment to merge into the settings file. */
|
|
391
|
+
readonly snippet: string;
|
|
392
|
+
} | {
|
|
393
|
+
readonly kind: 'slash-command';
|
|
394
|
+
readonly name: string;
|
|
395
|
+
readonly file: string;
|
|
396
|
+
readonly content: string;
|
|
397
|
+
} | {
|
|
398
|
+
readonly kind: 'prompt-habit';
|
|
399
|
+
readonly habit: string;
|
|
400
|
+
readonly before: string | null;
|
|
401
|
+
readonly after: string | null;
|
|
402
|
+
} | {
|
|
403
|
+
readonly kind: 'workflow';
|
|
404
|
+
readonly suggestion: string;
|
|
405
|
+
readonly steps: readonly string[];
|
|
406
|
+
};
|
|
407
|
+
type Insight = {
|
|
408
|
+
readonly id: string;
|
|
409
|
+
readonly kind: InsightKind;
|
|
410
|
+
readonly title: string;
|
|
411
|
+
readonly severity: Severity;
|
|
412
|
+
/** One line, with real numbers. */
|
|
413
|
+
readonly finding: string;
|
|
414
|
+
readonly evidence: InsightEvidence;
|
|
415
|
+
readonly action: InsightAction;
|
|
416
|
+
readonly confidence: number;
|
|
417
|
+
/** Ranking score; higher first. */
|
|
418
|
+
readonly score: number;
|
|
419
|
+
readonly episodeIds: readonly string[];
|
|
420
|
+
};
|
|
421
|
+
declare const REPORT_SCHEMA_VERSION: 1;
|
|
422
|
+
type DataQuality = {
|
|
423
|
+
readonly filesRead: number;
|
|
424
|
+
readonly subagentFilesRead: number;
|
|
425
|
+
readonly recordsRead: number;
|
|
426
|
+
readonly recordsSkipped: number;
|
|
427
|
+
readonly unknownRecordTypes: Readonly<Record<string, number>>;
|
|
428
|
+
readonly duplicateRecords: number;
|
|
429
|
+
readonly orphanToolResults: number;
|
|
430
|
+
readonly claudeCodeVersions: readonly string[];
|
|
431
|
+
readonly sessionsInPeriod: number;
|
|
432
|
+
readonly typedPrompts: number;
|
|
433
|
+
/** Log files that could not be read this run. */
|
|
434
|
+
readonly filesFailed?: number;
|
|
435
|
+
/** Sessions with no prompt, tool call or reply that were left out. */
|
|
436
|
+
readonly emptySessionsSkipped?: number;
|
|
437
|
+
/** False when there is too little data for trustworthy findings. */
|
|
438
|
+
readonly enoughData: boolean;
|
|
439
|
+
/** Human-readable caveats; engines append theirs. */
|
|
440
|
+
readonly notes: readonly string[];
|
|
441
|
+
};
|
|
442
|
+
type InterpretationVerdict = 'confirmed' | 'rejected' | 'unclear';
|
|
443
|
+
type InsightState = 'confirmed' | 'dismissed' | 'unverified';
|
|
444
|
+
/**
|
|
445
|
+
* What the interpretation step did with one insight. Renderers and the plugin
|
|
446
|
+
* digest all read this, so they agree on what is shown and what is hidden.
|
|
447
|
+
* `dismissed` requires every episode of the insight to have been reviewed and
|
|
448
|
+
* rejected; partial review only changes the counts.
|
|
449
|
+
*/
|
|
450
|
+
type InsightReview = {
|
|
451
|
+
readonly insightId: string;
|
|
452
|
+
readonly state: InsightState;
|
|
453
|
+
/** Episodes behind the insight. */
|
|
454
|
+
readonly episodes: number;
|
|
455
|
+
/** Episodes that received a verdict. */
|
|
456
|
+
readonly reviewed: number;
|
|
457
|
+
readonly confirmed: number;
|
|
458
|
+
readonly rejected: number;
|
|
459
|
+
readonly unclear: number;
|
|
460
|
+
};
|
|
461
|
+
/** Filled by the LLM interpretation step (phase 2). */
|
|
462
|
+
type Interpretation = {
|
|
463
|
+
readonly engine: string;
|
|
464
|
+
readonly model: string | null;
|
|
465
|
+
readonly generatedAt: string;
|
|
466
|
+
readonly summary: string;
|
|
467
|
+
readonly episodeVerdicts: readonly {
|
|
468
|
+
readonly episodeId: string;
|
|
469
|
+
readonly verdict: InterpretationVerdict;
|
|
470
|
+
readonly note: string;
|
|
471
|
+
}[];
|
|
472
|
+
readonly recommendations: readonly {
|
|
473
|
+
readonly title: string;
|
|
474
|
+
readonly body: string;
|
|
475
|
+
readonly basedOn: readonly string[];
|
|
476
|
+
}[];
|
|
477
|
+
};
|
|
478
|
+
type ReportPeriod = {
|
|
479
|
+
/** YYYY-MM-DD, local time, inclusive. */
|
|
480
|
+
readonly from: string;
|
|
481
|
+
readonly to: string;
|
|
482
|
+
readonly days: number;
|
|
483
|
+
};
|
|
484
|
+
type Report = {
|
|
485
|
+
readonly schemaVersion: typeof REPORT_SCHEMA_VERSION;
|
|
486
|
+
readonly generator: {
|
|
487
|
+
readonly name: 'hyntx';
|
|
488
|
+
readonly version: string;
|
|
489
|
+
};
|
|
490
|
+
readonly generatedAt: string;
|
|
491
|
+
readonly period: ReportPeriod;
|
|
492
|
+
readonly filters: {
|
|
493
|
+
readonly project: string | null;
|
|
494
|
+
};
|
|
495
|
+
readonly dataQuality: DataQuality;
|
|
496
|
+
readonly metrics: Metrics;
|
|
497
|
+
/** Merged daily history (persisted + current run), ascending by date. */
|
|
498
|
+
readonly daily: readonly DailyPoint[];
|
|
499
|
+
readonly episodes: readonly Episode[];
|
|
500
|
+
readonly promptTraits: readonly PromptTraitFinding[];
|
|
501
|
+
readonly insights: readonly Insight[];
|
|
502
|
+
/** One entry per insight; all `unverified` without an interpretation. */
|
|
503
|
+
readonly insightReviews: readonly InsightReview[];
|
|
504
|
+
readonly interpretation: Interpretation | null;
|
|
505
|
+
};
|
|
506
|
+
declare const InterpretationEngine: {
|
|
507
|
+
readonly CLAUDE: "claude";
|
|
508
|
+
readonly OLLAMA: "ollama";
|
|
509
|
+
};
|
|
510
|
+
type InterpretationEngine = (typeof InterpretationEngine)[keyof typeof InterpretationEngine];
|
|
511
|
+
type InterpretOptions = {
|
|
512
|
+
readonly engine: InterpretationEngine;
|
|
513
|
+
readonly model?: string;
|
|
514
|
+
readonly signal?: AbortSignal;
|
|
515
|
+
};
|
|
516
|
+
declare const OutputFormat: {
|
|
517
|
+
readonly TERMINAL: "terminal";
|
|
518
|
+
readonly JSON: "json";
|
|
519
|
+
readonly MARKDOWN: "markdown";
|
|
520
|
+
};
|
|
521
|
+
type OutputFormat = (typeof OutputFormat)[keyof typeof OutputFormat];
|
|
522
|
+
|
|
523
|
+
/**
|
|
524
|
+
* Deterministic metrics over sessions. Pure functions only.
|
|
525
|
+
*
|
|
526
|
+
* Tokens are reported as counts. There is deliberately no price table: prices
|
|
527
|
+
* go stale and a wrong dollar figure destroys trust.
|
|
528
|
+
*/
|
|
529
|
+
|
|
530
|
+
declare function computeMetrics(sessions: readonly Session[]): Metrics;
|
|
531
|
+
|
|
532
|
+
/**
|
|
533
|
+
* Deterministic friction detectors.
|
|
534
|
+
*
|
|
535
|
+
* Each detector turns sessions into `Episode`s: a moment where the workflow
|
|
536
|
+
* visibly cost the user something. Heuristic detectors (corrections) carry an
|
|
537
|
+
* honest confidence; the optional LLM step confirms or rejects them later.
|
|
538
|
+
* Everything placed in an episode is sanitized.
|
|
539
|
+
*/
|
|
540
|
+
|
|
541
|
+
type FrictionResult = {
|
|
542
|
+
readonly episodes: readonly Episode[];
|
|
543
|
+
readonly promptTraits: readonly PromptTraitFinding[];
|
|
544
|
+
/** Caveats about what the detectors could not cover. */
|
|
545
|
+
readonly notes: readonly string[];
|
|
546
|
+
};
|
|
547
|
+
declare function detectFriction(sessions: readonly Session[]): FrictionResult;
|
|
548
|
+
|
|
549
|
+
/**
|
|
550
|
+
* Persistent daily-metrics history under ~/.hyntx so trends outlive Claude
|
|
551
|
+
* Code's log retention. Only aggregate numbers are stored, never text.
|
|
552
|
+
*/
|
|
553
|
+
|
|
554
|
+
type LoadedHistory = {
|
|
555
|
+
readonly days: readonly DailyPoint[];
|
|
556
|
+
/** True when a history file existed but could not be used. */
|
|
557
|
+
readonly unreadable: boolean;
|
|
558
|
+
};
|
|
559
|
+
/**
|
|
560
|
+
* A missing file is normal. A corrupt one is set aside (not overwritten
|
|
561
|
+
* silently) and reported, so the user knows older trends may be gone.
|
|
562
|
+
*/
|
|
563
|
+
declare function loadDailyHistory(filePath?: string): Promise<LoadedHistory>;
|
|
564
|
+
/**
|
|
565
|
+
* Merges by day. A fresh point replaces the stored one unless the stored one
|
|
566
|
+
* saw more activity, which means Claude Code already pruned part of that day.
|
|
567
|
+
*/
|
|
568
|
+
declare function mergeDaily(stored: readonly DailyPoint[], fresh: readonly DailyPoint[]): readonly DailyPoint[];
|
|
569
|
+
/**
|
|
570
|
+
* Re-reads the file right before writing and merges, so a run that finished
|
|
571
|
+
* while this one was analyzing is not overwritten. The write itself is atomic.
|
|
572
|
+
*/
|
|
573
|
+
declare function saveDailyHistory(days: readonly DailyPoint[], filePath?: string): Promise<void>;
|
|
574
|
+
|
|
575
|
+
/**
|
|
576
|
+
* Reads existing Claude Code permission rules (read-only) so the tool never
|
|
577
|
+
* suggests a rule that is already allowed, or that a deny/ask rule overrides.
|
|
578
|
+
*
|
|
579
|
+
* Current syntax (code.claude.com/docs/en/permissions): `Bash(git status *)`,
|
|
580
|
+
* where `*` matches any text and a trailing ` *` also matches the bare
|
|
581
|
+
* command. `Bash(git status:*)` is the equivalent legacy suffix form. Rules
|
|
582
|
+
* are evaluated deny, then ask, then allow; the first match wins.
|
|
583
|
+
*/
|
|
584
|
+
type RuleLists = {
|
|
585
|
+
/** Rules from user settings; apply to every project. */
|
|
586
|
+
readonly user: readonly string[];
|
|
587
|
+
/** Rules from a project's own settings files, by project name. */
|
|
588
|
+
readonly byProject: Readonly<Record<string, readonly string[]>>;
|
|
589
|
+
};
|
|
590
|
+
type AllowedRules = RuleLists & {
|
|
591
|
+
/** `deny` and `ask` rules: a suggested allow must never meet one of these. */
|
|
592
|
+
readonly restricted?: RuleLists;
|
|
593
|
+
};
|
|
594
|
+
|
|
595
|
+
/**
|
|
596
|
+
* Deterministic insights: metrics + episodes -> ranked, evidence-backed,
|
|
597
|
+
* apply-ready suggestions. An insight is only produced when its evidence
|
|
598
|
+
* clears a minimum bar; with little data the result is simply empty.
|
|
599
|
+
*/
|
|
600
|
+
|
|
601
|
+
type InsightInput = {
|
|
602
|
+
readonly metrics: Metrics;
|
|
603
|
+
readonly episodes: readonly Episode[];
|
|
604
|
+
/** Existing permission rules, so allowlist suggestions skip allowed ones. */
|
|
605
|
+
readonly allowedRules?: AllowedRules;
|
|
606
|
+
};
|
|
607
|
+
declare function generateInsights(input: InsightInput): readonly Insight[];
|
|
608
|
+
|
|
609
|
+
/**
|
|
610
|
+
* Builds the serializable `Report` from sessions. Pure: all IO (reading logs,
|
|
611
|
+
* history, writing files) happens in the caller.
|
|
612
|
+
*/
|
|
613
|
+
|
|
614
|
+
type BuildReportOptions = {
|
|
615
|
+
readonly sessions: readonly Session[];
|
|
616
|
+
readonly stats: ReadStats;
|
|
617
|
+
readonly from: Date;
|
|
618
|
+
readonly to: Date;
|
|
619
|
+
readonly project: string | null;
|
|
620
|
+
readonly history?: readonly DailyPoint[];
|
|
621
|
+
/** The stored history file existed but could not be used. */
|
|
622
|
+
readonly historyUnreadable?: boolean;
|
|
623
|
+
readonly allowedRules?: AllowedRules;
|
|
624
|
+
readonly version: string;
|
|
625
|
+
readonly now?: Date;
|
|
626
|
+
};
|
|
627
|
+
/**
|
|
628
|
+
* Final safety net: run every free-text string of the report through the
|
|
629
|
+
* sanitizer, whatever produced it (detectors, insights, LLM engines).
|
|
630
|
+
*/
|
|
631
|
+
declare function sanitizeReport(report: Report): Report;
|
|
632
|
+
declare function buildReport(options: BuildReportOptions): Report;
|
|
633
|
+
|
|
634
|
+
/**
|
|
635
|
+
* Secret Sanitizer for Hyntx
|
|
636
|
+
*
|
|
637
|
+
* This module provides functionality to automatically redact secrets and sensitive
|
|
638
|
+
* information from prompts before sending them to AI providers.
|
|
639
|
+
*/
|
|
640
|
+
/**
|
|
641
|
+
* Result of sanitizing a single text.
|
|
642
|
+
*/
|
|
643
|
+
type SanitizeResult = {
|
|
644
|
+
readonly text: string;
|
|
645
|
+
readonly redacted: number;
|
|
646
|
+
};
|
|
647
|
+
/**
|
|
648
|
+
* Sanitizes a single text by redacting all detected secrets.
|
|
649
|
+
*
|
|
650
|
+
* @param text - Text to sanitize
|
|
651
|
+
* @returns Sanitized text and count of redactions
|
|
652
|
+
*
|
|
653
|
+
* @example
|
|
654
|
+
* ```typescript
|
|
655
|
+
* const result = sanitize('My API key is sk-1234567890abcdef...');
|
|
656
|
+
* // { text: 'My API key is [REDACTED_OPENAI_KEY]', redacted: 1 }
|
|
657
|
+
* ```
|
|
658
|
+
*/
|
|
659
|
+
declare function sanitize(text: string): SanitizeResult;
|
|
660
|
+
|
|
661
|
+
declare function readSessions(options?: ReadSessionsOptions): Promise<ReadSessionsResult>;
|
|
662
|
+
|
|
663
|
+
/**
|
|
664
|
+
* Interpretation engines: the optional LLM step that confirms heuristic
|
|
665
|
+
* episodes and phrases recommendations. Engines receive the sanitized
|
|
666
|
+
* `Report` and return an `Interpretation`; returning null means "not
|
|
667
|
+
* available", which is recorded as a data-quality note, never an error.
|
|
668
|
+
*/
|
|
669
|
+
|
|
670
|
+
declare function interpretReport(report: Report, options: InterpretOptions): Promise<Report>;
|
|
671
|
+
|
|
672
|
+
/**
|
|
673
|
+
* Self-contained HTML report: inline CSS/JS/SVG, no network access.
|
|
674
|
+
* Every report string is untrusted log text and goes through `esc`.
|
|
675
|
+
*/
|
|
676
|
+
|
|
677
|
+
declare function renderHtml(report: Report): string;
|
|
678
|
+
|
|
679
|
+
/**
|
|
680
|
+
* Markdown renderer: the full report, suited for sharing or committing.
|
|
681
|
+
*/
|
|
682
|
+
|
|
683
|
+
declare function renderMarkdown(report: Report): string;
|
|
684
|
+
|
|
685
|
+
/**
|
|
686
|
+
* Terminal renderer: compact and scannable. Headline numbers, top insights
|
|
687
|
+
* with evidence and an apply-ready action, then a short metrics summary.
|
|
688
|
+
*/
|
|
689
|
+
|
|
690
|
+
type TerminalOptions = {
|
|
691
|
+
readonly color?: boolean;
|
|
692
|
+
readonly maxInsights?: number;
|
|
693
|
+
};
|
|
694
|
+
declare function renderTerminal(report: Report, options?: TerminalOptions): string;
|
|
695
|
+
|
|
696
|
+
export { type AggregateMetrics, type Compaction, type DailyPoint, type DataQuality, DenialKind, type Distribution, type Episode, type EpisodeContext, type EpisodeRef, EpisodeType, type EvidenceExample, type Insight, type InsightAction, type InsightEvidence, InsightKind, type InsightReview, type InsightState, type InterpretOptions, type Interpretation, InterpretationEngine, type InterpretationVerdict, type Interruption, type Metrics, type ModelMix, type ModelUsage, OutputFormat, type Prompt, PromptSource, type PromptTraitFinding, REPORT_SCHEMA_VERSION, type ReadSessionsOptions, type ReadSessionsResult, type ReadStats, type Report, type ReportPeriod, type Session, type SessionMetrics, Severity, type SlashCommandUse, type SubagentActivity, type TokenTotals, type TokenUsage, type ToolCall, type ToolResult, type ToolStat, type Turn, TurnKind, buildReport, computeMetrics, detectFriction, generateInsights, interpretReport, loadDailyHistory, mergeDaily, readSessions, renderHtml, renderMarkdown, renderTerminal, sanitize, sanitizeReport, saveDailyHistory };
|