ai-hist 0.3.2 → 0.3.3
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 +3 -3
- package/dist/index.d.ts +86 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +433 -13
- package/dist/index.js.map +1 -1
- package/dist/jsonl-sources.d.ts +1 -0
- package/dist/jsonl-sources.d.ts.map +1 -1
- package/dist/jsonl-sources.js +3 -0
- package/dist/jsonl-sources.js.map +1 -1
- package/dist/mcp-server.js +154 -12
- package/dist/mcp-server.js.map +1 -1
- package/dist/mcp-smoke.test.js +141 -2
- package/dist/mcp-smoke.test.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
TypeScript reader for the [ai-hist](../README.md) history database, plus an MCP server for searching local AI coding-agent history from Claude Code, Codex, Cursor, and Agent Relay.
|
|
4
4
|
|
|
5
|
-
The SDK uses `sql.js`, so it has no native build step. It reads the same SQLite file
|
|
5
|
+
The SDK uses `sql.js`, so it has no native build step. It reads the same SQLite file that `ai-hist sync` writes, or falls back to scanning local Claude/Codex/Cursor JSONL files and compacted trajectory JSON when the database is missing.
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
@@ -27,7 +27,7 @@ try {
|
|
|
27
27
|
}
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
To require the
|
|
30
|
+
To require the ai-hist SQLite database instead of JSONL fallback:
|
|
31
31
|
|
|
32
32
|
```ts
|
|
33
33
|
const hist = await openAiHist({ fallback: 'error' });
|
|
@@ -145,7 +145,7 @@ The runtime contract is one JSON file per completed run:
|
|
|
145
145
|
|
|
146
146
|
## Schema
|
|
147
147
|
|
|
148
|
-
The canonical schema is
|
|
148
|
+
The canonical ai-hist SQLite schema is:
|
|
149
149
|
|
|
150
150
|
```sql
|
|
151
151
|
CREATE TABLE history (
|
package/dist/index.d.ts
CHANGED
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Backed by sql.js (WASM SQLite) so the package has zero native build
|
|
5
5
|
* requirements — works in Electron, Node, and browser contexts without
|
|
6
|
-
* needing electron-rebuild. The SDK reads the same
|
|
7
|
-
*
|
|
8
|
-
* `$AI_HIST_DB`)
|
|
6
|
+
* needing electron-rebuild. The SDK reads the same ai-hist SQLite database
|
|
7
|
+
* that `ai-hist sync` writes (default
|
|
8
|
+
* `~/.local/share/ai-hist/ai-history.db`, or `$AI_HIST_DB`).
|
|
9
9
|
*
|
|
10
10
|
* Trade-off vs better-sqlite3: sql.js loads the whole DB file into
|
|
11
11
|
* memory. Fine for the ai-hist scale (tens of thousands of rows, MBs
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
*/
|
|
14
14
|
import { type Database } from 'sql.js';
|
|
15
15
|
import { type TrajectoryDecision, type TrajectoryRetrospective } from './trajectory-sources.js';
|
|
16
|
-
export type Source = 'claude' | 'codex' | 'cursor' | 'relay' | 'trajectory';
|
|
16
|
+
export type Source = 'claude' | 'codex' | 'cursor' | 'relay' | 'trajectory' | 'opencode';
|
|
17
17
|
export interface HistoryEntry {
|
|
18
18
|
id: number;
|
|
19
19
|
source: Source;
|
|
@@ -21,6 +21,48 @@ export interface HistoryEntry {
|
|
|
21
21
|
project: string | null;
|
|
22
22
|
prompt: string;
|
|
23
23
|
timestampMs: number;
|
|
24
|
+
gitBranch: string | null;
|
|
25
|
+
}
|
|
26
|
+
export interface SessionMeta {
|
|
27
|
+
sessionId: string;
|
|
28
|
+
source: Source;
|
|
29
|
+
cwd: string | null;
|
|
30
|
+
gitBranch: string | null;
|
|
31
|
+
firstActivityMs: number | null;
|
|
32
|
+
lastActivityMs: number | null;
|
|
33
|
+
lastAssistantText: string | null;
|
|
34
|
+
rawPath: string | null;
|
|
35
|
+
}
|
|
36
|
+
export interface HandoffCandidate {
|
|
37
|
+
sessionId: string;
|
|
38
|
+
source: Source;
|
|
39
|
+
cwd: string | null;
|
|
40
|
+
gitBranch: string | null;
|
|
41
|
+
firstActivityMs: number | null;
|
|
42
|
+
lastActivityMs: number | null;
|
|
43
|
+
promptCount: number;
|
|
44
|
+
goal: string;
|
|
45
|
+
lastState: string;
|
|
46
|
+
lastAssistantText: string | null;
|
|
47
|
+
filesTouched: string[];
|
|
48
|
+
resumeCommand: string | null;
|
|
49
|
+
warmStartCommand: string;
|
|
50
|
+
confidence: number;
|
|
51
|
+
}
|
|
52
|
+
export interface Tag {
|
|
53
|
+
name: string;
|
|
54
|
+
displayName: string;
|
|
55
|
+
color: string | null;
|
|
56
|
+
sessionCount: number;
|
|
57
|
+
firstTaggedMs: number | null;
|
|
58
|
+
lastTaggedMs: number | null;
|
|
59
|
+
}
|
|
60
|
+
export interface TaggedSession {
|
|
61
|
+
source: Source;
|
|
62
|
+
sessionId: string;
|
|
63
|
+
project: string | null;
|
|
64
|
+
entryCount: number;
|
|
65
|
+
lastActivityMs: number | null;
|
|
24
66
|
}
|
|
25
67
|
export interface SessionSummary {
|
|
26
68
|
sessionId: string;
|
|
@@ -34,6 +76,7 @@ export interface SessionSummary {
|
|
|
34
76
|
export interface ListOptions {
|
|
35
77
|
source?: Source;
|
|
36
78
|
project?: string;
|
|
79
|
+
tag?: string;
|
|
37
80
|
/** Default 50. */
|
|
38
81
|
limit?: number;
|
|
39
82
|
/**
|
|
@@ -78,7 +121,17 @@ export interface TrajectorySearchOptions {
|
|
|
78
121
|
/** Filter to a trajectory projectId or path. */
|
|
79
122
|
project?: string;
|
|
80
123
|
}
|
|
81
|
-
|
|
124
|
+
export interface GetHandoffOptions {
|
|
125
|
+
/** Substring match against session cwd. */
|
|
126
|
+
repo?: string;
|
|
127
|
+
/** Substring match against git_branch. */
|
|
128
|
+
branch?: string;
|
|
129
|
+
/** Filter to a specific CLI source. */
|
|
130
|
+
source?: 'claude' | 'codex';
|
|
131
|
+
/** Max candidates to return. Default 3. */
|
|
132
|
+
limit?: number;
|
|
133
|
+
}
|
|
134
|
+
/** Resolve the SQLite path that ai-hist writes to. */
|
|
82
135
|
export declare function defaultDbPath(): string;
|
|
83
136
|
export interface OpenOptions {
|
|
84
137
|
/** Override the SQLite path (default: `$AI_HIST_DB` or `~/.local/share/ai-hist/ai-history.db`). */
|
|
@@ -129,6 +182,24 @@ export declare class AiHist {
|
|
|
129
182
|
/** Server/client-wide project scope applied to every read, if configured. */
|
|
130
183
|
get projectScope(): string | undefined;
|
|
131
184
|
close(): void;
|
|
185
|
+
private persistIfWritable;
|
|
186
|
+
private ensureTag;
|
|
187
|
+
private matchingSessions;
|
|
188
|
+
tagSession(sessionId: string, tagName: string, opts?: {
|
|
189
|
+
source?: Source;
|
|
190
|
+
color?: string | null;
|
|
191
|
+
}): TaggedSession[];
|
|
192
|
+
untagSession(sessionId: string, tagName: string, opts?: {
|
|
193
|
+
source?: Source;
|
|
194
|
+
}): number;
|
|
195
|
+
listTags(opts?: {
|
|
196
|
+
tag?: string;
|
|
197
|
+
includeSessions?: boolean;
|
|
198
|
+
}): Array<Tag & {
|
|
199
|
+
sessions?: TaggedSession[];
|
|
200
|
+
}>;
|
|
201
|
+
sessionsByTag(tagName: string): TaggedSession[];
|
|
202
|
+
searchByTag(tagName: string, opts?: Omit<SearchOptions, 'tag'>): HistoryEntry[];
|
|
132
203
|
/** Most recent prompts, newest first. */
|
|
133
204
|
recent(opts?: ListOptions): HistoryEntry[];
|
|
134
205
|
/**
|
|
@@ -145,7 +216,7 @@ export declare class AiHist {
|
|
|
145
216
|
*/
|
|
146
217
|
listSessions(opts?: ListOptions): SessionSummary[];
|
|
147
218
|
/** All prompts in a session, ordered oldest → newest. */
|
|
148
|
-
getSession(sessionId: string): HistoryEntry[];
|
|
219
|
+
getSession(sessionId: string, opts?: Pick<ListOptions, 'source' | 'tag'>): HistoryEntry[];
|
|
149
220
|
/**
|
|
150
221
|
* Substring search across prompt + project, case-insensitive, recent
|
|
151
222
|
* matches first. The Python CLI uses FTS5; this SDK uses LIKE because
|
|
@@ -168,6 +239,15 @@ export declare class AiHist {
|
|
|
168
239
|
* timestampMs + windowMs], ordered oldest first. Used by get_context.
|
|
169
240
|
*/
|
|
170
241
|
getInTimeWindow(timestampMs: number, windowMs: number): HistoryEntry[];
|
|
242
|
+
/**
|
|
243
|
+
* Find sessions matching the given repo/branch/source and return ranked
|
|
244
|
+
* handoff candidates with a warm-start command for the target CLI.
|
|
245
|
+
*
|
|
246
|
+
* Queries the `sessions` table (populated by `ai-hist sync`) for objective
|
|
247
|
+
* metadata, then joins the last N user prompts from `history` to generate
|
|
248
|
+
* a brief on demand — no pre-computed summaries.
|
|
249
|
+
*/
|
|
250
|
+
getHandoff(opts?: GetHandoffOptions): HandoffCandidate[];
|
|
171
251
|
/** Counts + date range, mirroring `ai-hist stats`. */
|
|
172
252
|
stats(): Stats;
|
|
173
253
|
}
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAkB,EAAE,KAAK,QAAQ,EAAoB,MAAM,QAAQ,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|