From fb35cca8feeb613fc887e619fa8e7be008413cf6 Mon Sep 17 00:00:00 2001 From: tommy0103 Date: Tue, 2 Jun 2026 01:36:47 +0800 Subject: [PATCH] feat(query): unified filter opts across all list-returning APIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- SKILL.md | 43 ++++++++++++-------- references/schema.md | 97 ++++++++++++++++++++++++++++++++------------ scripts/query.mjs | 95 ++++++++++++++++++++++++++++++++++--------- 3 files changed, 172 insertions(+), 63 deletions(-) diff --git a/SKILL.md b/SKILL.md index df191d2..dc892c8 100644 --- a/SKILL.md +++ b/SKILL.md @@ -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" diff --git a/references/schema.md b/references/schema.md index 2c8dc18..a4e8525 100644 --- a/references/schema.md +++ b/references/schema.md @@ -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`. ```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`. @@ -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` 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 diff --git a/scripts/query.mjs b/scripts/query.mjs index 2cca679..a3a2872 100644 --- a/scripts/query.mjs +++ b/scripts/query.mjs @@ -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 };