feat(query): unified filter opts across all list-returning APIs
Add sessions() as first-class entry point for session discovery with project/time/branch filters. Extend summaries, workflows, failures, subagents, fileHistory with the same opts vocabulary that search() already had — no more pulling full datasets to filter client-side.
This commit is contained in:
tommy0103
@@ -44,6 +44,17 @@ Returns: `[{ message: {uuid, text, role, timestamp, model}, session: {id, title,
|
||||
|
||||
opts: `{ limit, sessionId, project, after, before }`
|
||||
|
||||
### sessions(opts?)
|
||||
|
||||
Query sessions with filters. Returns session rows ordered by `ended_at` descending.
|
||||
|
||||
opts: `{ project, after, before, limit, branch, sessionId, sessions }`
|
||||
|
||||
```js
|
||||
sessions({ project: '%quiet-zero%' })
|
||||
sessions({ after: '2026-06-01', branch: 'main', limit: 5 })
|
||||
```
|
||||
|
||||
### context(uuid)
|
||||
|
||||
Full story around a message: the message itself, parent chain, session info, subagent/workflow metadata.
|
||||
@@ -52,7 +63,7 @@ Returns: `{ message, parentChain, session, subagent, workflow }`
|
||||
|
||||
### recent(n?)
|
||||
|
||||
Latest n sessions (default 10). Returns session rows with title, project, started_at, ended_at.
|
||||
Shorthand for `sessions({ limit: n })`. Latest n sessions (default 10).
|
||||
|
||||
### sql(query, ...params)
|
||||
|
||||
@@ -64,22 +75,25 @@ Tables: `sessions`, `messages`, `tool_calls`, `tool_results`, `subagents`, `work
|
||||
|
||||
### Other APIs
|
||||
|
||||
All list-returning functions accept a common filter opts object: `{ project, after, before, limit, sessionId, sessions }`. For backward compatibility, passing a string is treated as `sessionId`, a number as `limit`.
|
||||
|
||||
- `trace(uuid)` -- full parent chain from root to message
|
||||
- `thread(sessionId)` -- all messages in a session, ordered by time
|
||||
- `subagents(sessionId)` -- subagent metadata + message counts
|
||||
- `workflows(sessionId?)` -- workflow runs (all if no sessionId)
|
||||
- `subagents(opts?)` -- subagent metadata + message counts. opts: `{ sessionId, project, limit }`
|
||||
- `workflows(opts?)` -- workflow runs. opts: `{ sessionId, project, after, before, limit }`
|
||||
- `workflowTree(runId)` -- workflow + its agents + all their messages
|
||||
- `fileHistory(filePath)` -- every Edit/Write/Read on a file across sessions
|
||||
- `failures(sessionId?)` -- tool calls that returned errors, with surrounding context
|
||||
- `summaries(sessionId?)` -- session summaries (away recaps, compaction summaries when available)
|
||||
- `fileHistory(filePath, opts?)` -- every Edit/Write/Read on a file. opts: `{ after, before, limit }`
|
||||
- `failures(opts?)` -- tool calls that returned errors, with surrounding context. opts: `{ sessionId, project, after, before, limit }`
|
||||
- `summaries(opts?)` -- session summaries (away recaps, compaction summaries). opts: `{ sessionId, project, after, before, limit, sessions }`
|
||||
- `raw(uuid, opts?)` -- windowed access to the original JSONL line (bypasses index truncation)
|
||||
|
||||
### Retrieval strategy
|
||||
|
||||
**Never pull an entire session.** Navigate incrementally:
|
||||
|
||||
1. `summaries()` — read session summaries to judge relevance (cheapest)
|
||||
2. `search()` — find specific messages matching a query
|
||||
1. `sessions({ project: '...' })` or `recent()` — find relevant sessions
|
||||
2. `summaries({ project: '...' })` — read session summaries to judge relevance (cheapest)
|
||||
3. `search()` — find specific messages matching a query
|
||||
3. When you find a relevant message and want more context, expand from that point:
|
||||
- **Horizontally**: use `sql()` to fetch neighboring messages by timestamp
|
||||
```js
|
||||
@@ -124,7 +138,7 @@ return hits.slice(0, 5).map(h => ({
|
||||
### "最近在做什么"
|
||||
|
||||
```js
|
||||
return recent(10).map(s => ({ title: s.title, project: s.project, date: s.started_at }))
|
||||
return sessions({ limit: 10 }).map(s => ({ title: s.title, project: s.project, date: s.started_at }))
|
||||
```
|
||||
|
||||
### "哪些文件被反复修改"
|
||||
@@ -137,15 +151,12 @@ return sql(`
|
||||
`)
|
||||
```
|
||||
|
||||
### "那个 review workflow 的结果是什么"
|
||||
### "这个项目的 workflow 跑过几次"
|
||||
|
||||
```js
|
||||
const wfs = workflows()
|
||||
const review = wfs.find(w =>
|
||||
w.run_id.includes('review') ||
|
||||
JSON.parse(w.result_json || '{}').synthesis
|
||||
)
|
||||
return review ? JSON.parse(review.result_json) : 'No review workflow found'
|
||||
return workflows({ project: '%quiet-zero%' }).map(w => ({
|
||||
run: w.run_id, agents: w.agent_count, time: w.timestamp
|
||||
}))
|
||||
```
|
||||
|
||||
### "上次跑 experiment 用了多少 token"
|
||||
|
||||
+70
-27
@@ -262,26 +262,40 @@ const msgs = thread('session-uuid');
|
||||
return { count: msgs.length, first: msgs[0]?.text?.slice(0, 100) };
|
||||
```
|
||||
|
||||
#### `subagents(sessionId)`
|
||||
#### `subagents(opts?)`
|
||||
|
||||
All subagent spawns for a session, with message counts.
|
||||
All subagent spawns, with message counts. For backward compatibility, passing a string is treated as `sessionId`.
|
||||
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `opts.sessionId` | `string` | Restrict to one session |
|
||||
| `opts.project` | `string` | Filter by project slug (LIKE) |
|
||||
| `opts.limit` | `number` | Max results (default 100) |
|
||||
|
||||
**Returns:** `Array<{ ...subagent_row, messageCount }>`.
|
||||
|
||||
```js
|
||||
const subs = subagents('session-uuid');
|
||||
const subs = subagents({ project: '%quiet-zero%' });
|
||||
return subs.map(s => ({ type: s.agent_type, desc: s.description, msgs: s.messageCount, tokens: s.total_tokens }));
|
||||
```
|
||||
|
||||
#### `workflows(sessionId?)`
|
||||
#### `workflows(opts?)`
|
||||
|
||||
Workflow executions. Pass a session ID to filter, or omit for all workflows (newest first).
|
||||
Workflow executions. For backward compatibility, passing a string is treated as `sessionId`.
|
||||
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `opts.sessionId` | `string` | Restrict to one session |
|
||||
| `opts.project` | `string` | Filter by project slug (LIKE) |
|
||||
| `opts.after` | `string` | ISO 8601 lower bound on timestamp |
|
||||
| `opts.before` | `string` | ISO 8601 upper bound on timestamp |
|
||||
| `opts.limit` | `number` | Max results (default 100) |
|
||||
|
||||
**Returns:** `Array<workflow_row>`.
|
||||
|
||||
```js
|
||||
const wfs = workflows();
|
||||
return wfs.slice(0, 5).map(w => ({ run: w.run_id, agents: w.agent_count, time: w.timestamp }));
|
||||
const wfs = workflows({ project: '%quiet-zero%' });
|
||||
return wfs.map(w => ({ run: w.run_id, agents: w.agent_count, time: w.timestamp }));
|
||||
```
|
||||
|
||||
#### `workflowTree(runId)`
|
||||
@@ -295,31 +309,46 @@ const tree = workflowTree('run-uuid');
|
||||
return tree?.agents.map(a => ({ type: a.agent_type, msgs: a.messages.length }));
|
||||
```
|
||||
|
||||
#### `fileHistory(filePath)`
|
||||
#### `fileHistory(filePath, opts?)`
|
||||
|
||||
All tool calls that touched a specific file, across every session.
|
||||
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `filePath` | `string` | Absolute file path (required) |
|
||||
| `opts.after` | `string` | ISO 8601 lower bound |
|
||||
| `opts.before` | `string` | ISO 8601 upper bound |
|
||||
| `opts.limit` | `number` | Max results (default 200) |
|
||||
|
||||
**Returns:** `Array<{ toolCall, session, timestamp }>`.
|
||||
|
||||
```js
|
||||
const edits = fileHistory('/Users/tomiya/Code/quiet-zero/src/mcts.ts');
|
||||
const edits = fileHistory('/Users/tomiya/Code/quiet-zero/src/mcts.ts', { after: '2026-05-28' });
|
||||
return edits.map(e => ({ tool: e.toolCall.name, session: e.session.title, time: e.timestamp }));
|
||||
```
|
||||
|
||||
#### `failures(sessionId?)`
|
||||
#### `failures(opts?)`
|
||||
|
||||
Tool calls whose results contain error patterns (`Error`, `ENOENT`, `failed`, `permission denied`, etc.). Includes the 3 messages immediately after each failure for retry context.
|
||||
Tool calls whose results contain error patterns (`Error`, `ENOENT`, `failed`, `permission denied`, etc.). Includes the 3 messages immediately after each failure for retry context. For backward compatibility, passing a string is treated as `sessionId`.
|
||||
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `opts.sessionId` | `string` | Restrict to one session |
|
||||
| `opts.project` | `string` | Filter by project slug (LIKE) |
|
||||
| `opts.after` | `string` | ISO 8601 lower bound |
|
||||
| `opts.before` | `string` | ISO 8601 upper bound |
|
||||
| `opts.limit` | `number` | Max results (default 50) |
|
||||
|
||||
**Returns:** `Array<{ toolCall, result, session, nextMessages }>`.
|
||||
|
||||
```js
|
||||
const fails = failures('session-uuid');
|
||||
const fails = failures({ project: '%quiet-zero%', limit: 10 });
|
||||
return fails.map(f => ({ tool: f.toolCall?.name, error: f.result.content?.slice(0, 200) }));
|
||||
```
|
||||
|
||||
#### `recent(n?)`
|
||||
|
||||
Last `n` sessions (default 10), ordered by `ended_at` descending.
|
||||
Shorthand for `sessions({ limit: n })`. Last `n` sessions (default 10), ordered by `ended_at` descending.
|
||||
|
||||
**Returns:** `Array<session_row>`.
|
||||
|
||||
@@ -328,6 +357,27 @@ const last5 = recent(5);
|
||||
return last5.map(s => ({ title: s.title, project: s.project_path, ended: s.ended_at }));
|
||||
```
|
||||
|
||||
#### `sessions(opts?)`
|
||||
|
||||
Query sessions with filters. For backward compatibility, passing a number is treated as `limit`.
|
||||
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `opts.project` | `string` | Filter by project slug (supports LIKE, e.g. `'%quiet-zero%'`) |
|
||||
| `opts.after` | `string` | ISO 8601 lower bound on `started_at` |
|
||||
| `opts.before` | `string` | ISO 8601 upper bound on `started_at` |
|
||||
| `opts.limit` | `number` | Max results (default 50) |
|
||||
| `opts.branch` | `string` | Filter by git branch (exact match) |
|
||||
| `opts.sessionId` | `string` | Restrict to one session |
|
||||
| `opts.sessions` | `string[]` | Restrict to a set of session IDs |
|
||||
|
||||
**Returns:** `Array<session_row>` ordered by `ended_at` descending.
|
||||
|
||||
```js
|
||||
const qz = sessions({ project: '%quiet-zero%', limit: 5 });
|
||||
return qz.map(s => ({ title: s.title, branch: s.git_branch, ended: s.ended_at }));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Common Query Patterns
|
||||
@@ -436,13 +486,9 @@ return rows;
|
||||
### Find sessions by time range
|
||||
|
||||
```js
|
||||
const rows = sql(`
|
||||
SELECT id, title, project_path, started_at, ended_at, message_count
|
||||
FROM sessions
|
||||
WHERE started_at >= ? AND started_at < ?
|
||||
ORDER BY started_at DESC
|
||||
`, '2026-05-28T00:00:00Z', '2026-05-30T00:00:00Z');
|
||||
return rows;
|
||||
return sessions({ after: '2026-05-28T00:00:00Z', before: '2026-05-30T00:00:00Z' }).map(s => ({
|
||||
title: s.title, project: s.project_path, started: s.started_at, messages: s.message_count,
|
||||
}));
|
||||
```
|
||||
|
||||
### Cross-reference subagent findings
|
||||
@@ -460,13 +506,10 @@ return details;
|
||||
### Find all sessions for a project
|
||||
|
||||
```js
|
||||
const rows = sql(`
|
||||
SELECT id, title, started_at, ended_at, message_count, git_branch
|
||||
FROM sessions
|
||||
WHERE project_path = ?
|
||||
ORDER BY started_at DESC
|
||||
`, '/Users/tomiya/Code/quiet-zero');
|
||||
return rows;
|
||||
return sessions({ project: '%quiet-zero%' }).map(s => ({
|
||||
title: s.title, started: s.started_at, ended: s.ended_at,
|
||||
messages: s.message_count, branch: s.git_branch,
|
||||
}));
|
||||
```
|
||||
|
||||
### Reconstruct what happened in a session
|
||||
|
||||
+75
-20
@@ -2,6 +2,28 @@ import { openDb, readLines, fs, path } from './db.mjs';
|
||||
|
||||
const ERROR_PATS = ['error','Error','ENOENT','failed','Failed','FAILED','permission denied','Permission denied','EPERM','EACCES','command not found','No such file','Exit code'];
|
||||
|
||||
function normalizeOpts(optsOrScalar, scalarKey = 'sessionId') {
|
||||
if (optsOrScalar == null) return {};
|
||||
if (typeof optsOrScalar === 'string') return { [scalarKey]: optsOrScalar };
|
||||
if (typeof optsOrScalar === 'number') return { limit: optsOrScalar };
|
||||
return optsOrScalar;
|
||||
}
|
||||
|
||||
function buildWhere(opts, aliases) {
|
||||
const clauses = [];
|
||||
const params = [];
|
||||
if (opts.sessionId) { clauses.push(`${aliases.sessionId} = ?`); params.push(opts.sessionId); }
|
||||
if (opts.sessions?.length) {
|
||||
clauses.push(`${aliases.sessionId} IN (${opts.sessions.map(() => '?').join(',')})`);
|
||||
params.push(...opts.sessions);
|
||||
}
|
||||
if (opts.project) { clauses.push(`${aliases.project} LIKE ?`); params.push(opts.project); }
|
||||
if (opts.after) { clauses.push(`${aliases.timestamp} > ?`); params.push(opts.after); }
|
||||
if (opts.before) { clauses.push(`${aliases.timestamp} < ?`); params.push(opts.before); }
|
||||
if (opts.branch) { clauses.push(`${aliases.branch} = ?`); params.push(opts.branch); }
|
||||
return { where: clauses.length ? clauses.join(' AND ') : '1=1', params };
|
||||
}
|
||||
|
||||
function createQueryApi(db) {
|
||||
const q = (sql, ...p) => db.prepare(sql).all(...p);
|
||||
|
||||
@@ -56,16 +78,28 @@ function createQueryApi(db) {
|
||||
|
||||
const thread = (sid) => db.prepare('SELECT * FROM messages WHERE session_id=? ORDER BY timestamp').all(sid);
|
||||
|
||||
const subagents = (sid) => {
|
||||
return db.prepare('SELECT * FROM subagents WHERE session_id=?').all(sid).map(r => {
|
||||
const subagents = (optsOrSid) => {
|
||||
const opts = normalizeOpts(optsOrSid);
|
||||
const { limit = 100 } = opts;
|
||||
const needsJoin = opts.project || opts.branch;
|
||||
const { where, params } = buildWhere(opts, { sessionId: 'sa.session_id', project: 's.project', timestamp: 'sa.session_id', branch: 's.git_branch' });
|
||||
params.push(limit);
|
||||
const join = needsJoin ? 'LEFT JOIN sessions s ON s.id=sa.session_id' : '';
|
||||
return db.prepare(`SELECT sa.* FROM subagents sa ${join} WHERE ${where} LIMIT ?`).all(...params).map(r => {
|
||||
const c = db.prepare('SELECT COUNT(*) as c FROM messages WHERE agent_id=?').get(r.agent_id);
|
||||
return { ...r, messageCount: c?.c || 0 };
|
||||
});
|
||||
};
|
||||
|
||||
const workflows = (sid) => sid
|
||||
? db.prepare('SELECT * FROM workflows WHERE session_id=? ORDER BY timestamp').all(sid)
|
||||
: db.prepare('SELECT * FROM workflows ORDER BY timestamp DESC').all();
|
||||
const workflows = (optsOrSid) => {
|
||||
const opts = normalizeOpts(optsOrSid);
|
||||
const { limit = 100 } = opts;
|
||||
const needsJoin = opts.project || opts.branch;
|
||||
const { where, params } = buildWhere(opts, { sessionId: 'w.session_id', project: 's.project', timestamp: 'w.timestamp', branch: 's.git_branch' });
|
||||
params.push(limit);
|
||||
const join = needsJoin ? 'LEFT JOIN sessions s ON s.id=w.session_id' : '';
|
||||
return db.prepare(`SELECT w.* FROM workflows w ${join} WHERE ${where} ORDER BY w.timestamp DESC LIMIT ?`).all(...params);
|
||||
};
|
||||
|
||||
const workflowTree = (runId) => {
|
||||
const wf = db.prepare('SELECT * FROM workflows WHERE run_id=?').get(runId);
|
||||
@@ -76,23 +110,32 @@ function createQueryApi(db) {
|
||||
return { ...wf, agents };
|
||||
};
|
||||
|
||||
const fileHistory = (fp) => {
|
||||
const fileHistory = (fp, opts = {}) => {
|
||||
const { limit = 200, after, before } = opts;
|
||||
let where = 'tc.file_path=?';
|
||||
const params = [fp];
|
||||
if (after) { where += ' AND m.timestamp > ?'; params.push(after); }
|
||||
if (before) { where += ' AND m.timestamp < ?'; params.push(before); }
|
||||
params.push(limit);
|
||||
return db.prepare(
|
||||
'SELECT tc.*,s.title as s_title,s.project as s_project FROM tool_calls tc LEFT JOIN sessions s ON s.id=tc.session_id WHERE tc.file_path=? ORDER BY tc.id'
|
||||
).all(fp).map(r => ({
|
||||
`SELECT tc.*,s.title as s_title,s.project as s_project,m.timestamp as ts FROM tool_calls tc LEFT JOIN sessions s ON s.id=tc.session_id LEFT JOIN messages m ON m.uuid=tc.message_uuid WHERE ${where} ORDER BY m.timestamp LIMIT ?`
|
||||
).all(...params).map(r => ({
|
||||
toolCall: { id: r.id, message_uuid: r.message_uuid, name: r.name, input_json: r.input_json },
|
||||
session: { id: r.session_id, title: r.s_title, project: r.s_project },
|
||||
timestamp: db.prepare('SELECT timestamp FROM messages WHERE uuid=?').get(r.message_uuid)?.timestamp,
|
||||
timestamp: r.ts,
|
||||
}));
|
||||
};
|
||||
|
||||
const failures = (sid) => {
|
||||
const likeClauses = ERROR_PATS.map(() => 'content LIKE ?').join(' OR ');
|
||||
const failures = (optsOrSid) => {
|
||||
const opts = normalizeOpts(optsOrSid);
|
||||
const { limit = 50 } = opts;
|
||||
const likeClauses = ERROR_PATS.map(() => 'tr.content LIKE ?').join(' OR ');
|
||||
const likeParams = ERROR_PATS.map(p => `%${p}%`);
|
||||
let query = `SELECT * FROM tool_results WHERE (${likeClauses})`;
|
||||
const params = [...likeParams];
|
||||
if (sid) { query += ' AND session_id=?'; params.push(sid); }
|
||||
const rows = db.prepare(query).all(...params);
|
||||
const needsJoin = opts.project || opts.branch;
|
||||
const { where, params: filterParams } = buildWhere(opts, { sessionId: 'tr.session_id', project: 's.project', timestamp: 'rm.timestamp', branch: 's.git_branch' });
|
||||
const join = needsJoin ? 'LEFT JOIN sessions s ON s.id=tr.session_id' : '';
|
||||
const allParams = [...likeParams, ...filterParams, limit];
|
||||
const rows = db.prepare(`SELECT tr.* FROM tool_results tr ${join} LEFT JOIN messages rm ON rm.uuid=tr.message_uuid WHERE (${likeClauses}) AND ${where} LIMIT ?`).all(...allParams);
|
||||
return rows.map(r => {
|
||||
const tc = db.prepare('SELECT * FROM tool_calls WHERE id=?').get(r.tool_use_id);
|
||||
const session = db.prepare('SELECT * FROM sessions WHERE id=?').get(r.session_id);
|
||||
@@ -102,11 +145,23 @@ function createQueryApi(db) {
|
||||
});
|
||||
};
|
||||
|
||||
const recent = (n = 10) => db.prepare('SELECT * FROM sessions ORDER BY ended_at DESC LIMIT ?').all(n);
|
||||
const sessions = (optsOrN) => {
|
||||
const opts = normalizeOpts(optsOrN, 'sessionId');
|
||||
const { limit = 50 } = opts;
|
||||
const { where, params } = buildWhere(opts, { sessionId: 's.id', project: 's.project', timestamp: 's.started_at', branch: 's.git_branch' });
|
||||
params.push(limit);
|
||||
return db.prepare(`SELECT * FROM sessions s WHERE ${where} ORDER BY ended_at DESC LIMIT ?`).all(...params);
|
||||
};
|
||||
|
||||
const summaries = (sessionId) => sessionId
|
||||
? db.prepare('SELECT * FROM summaries WHERE session_id=? ORDER BY timestamp').all(sessionId)
|
||||
: db.prepare('SELECT su.*, s.title as session_title, s.project FROM summaries su LEFT JOIN sessions s ON s.id=su.session_id ORDER BY su.timestamp DESC').all();
|
||||
const recent = (n = 10) => sessions({ limit: n });
|
||||
|
||||
const summaries = (optsOrSid) => {
|
||||
const opts = normalizeOpts(optsOrSid);
|
||||
const { limit = 100 } = opts;
|
||||
const { where, params } = buildWhere(opts, { sessionId: 'su.session_id', project: 's.project', timestamp: 'su.timestamp', branch: 's.git_branch' });
|
||||
params.push(limit);
|
||||
return db.prepare(`SELECT su.*, s.title as session_title, s.project FROM summaries su LEFT JOIN sessions s ON s.id=su.session_id WHERE ${where} ORDER BY su.timestamp DESC LIMIT ?`).all(...params);
|
||||
};
|
||||
|
||||
const resolveJsonlPath = (messageUuid) => {
|
||||
const msg = db.prepare('SELECT session_id, agent_id FROM messages WHERE uuid=?').get(messageUuid);
|
||||
@@ -153,7 +208,7 @@ function createQueryApi(db) {
|
||||
};
|
||||
};
|
||||
|
||||
return { sql: q, search, context, trace, thread, subagents, workflows, workflowTree, fileHistory, failures, recent, summaries, raw };
|
||||
return { sql: q, search, context, trace, thread, subagents, workflows, workflowTree, fileHistory, failures, sessions, recent, summaries, raw };
|
||||
}
|
||||
|
||||
export { createQueryApi };
|
||||
|
||||
Reference in New Issue
Block a user