dsh-locator 0.8.2 → 0.10.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.
Files changed (58) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/README-es.md +30 -5
  3. package/README-hi.md +31 -5
  4. package/README-pt.md +31 -5
  5. package/README.en.md +31 -5
  6. package/README.md +31 -5
  7. package/bin/darwin-arm64/indexd +0 -0
  8. package/bin/darwin-x64/indexd +0 -0
  9. package/bin/linux-arm64/indexd +0 -0
  10. package/bin/linux-x64/indexd +0 -0
  11. package/bin/win32-arm64/indexd.exe +0 -0
  12. package/bin/win32-x64/indexd.exe +0 -0
  13. package/client.js +1198 -117
  14. package/lib/combined.d.ts +20 -3
  15. package/lib/combined.d.ts.map +1 -1
  16. package/lib/combined.js +85 -15
  17. package/lib/combined.js.map +1 -1
  18. package/lib/content-search-worker.d.ts +8 -3
  19. package/lib/content-search-worker.d.ts.map +1 -1
  20. package/lib/content-search-worker.js +54 -27
  21. package/lib/content-search-worker.js.map +1 -1
  22. package/lib/content-search.d.ts +127 -7
  23. package/lib/content-search.d.ts.map +1 -1
  24. package/lib/content-search.js +571 -36
  25. package/lib/content-search.js.map +1 -1
  26. package/lib/content.d.ts +83 -5
  27. package/lib/content.d.ts.map +1 -1
  28. package/lib/content.js +351 -87
  29. package/lib/content.js.map +1 -1
  30. package/lib/export.d.ts +61 -0
  31. package/lib/export.d.ts.map +1 -1
  32. package/lib/export.js +217 -52
  33. package/lib/export.js.map +1 -1
  34. package/lib/find.d.ts.map +1 -1
  35. package/lib/find.js +73 -16
  36. package/lib/find.js.map +1 -1
  37. package/lib/http.d.ts +38 -2
  38. package/lib/http.d.ts.map +1 -1
  39. package/lib/http.js +279 -82
  40. package/lib/http.js.map +1 -1
  41. package/lib/reveal.d.ts +69 -3
  42. package/lib/reveal.d.ts.map +1 -1
  43. package/lib/reveal.js +140 -11
  44. package/lib/reveal.js.map +1 -1
  45. package/lib/tools.d.ts +30 -0
  46. package/lib/tools.d.ts.map +1 -1
  47. package/lib/tools.js +65 -3
  48. package/lib/tools.js.map +1 -1
  49. package/package.json +1 -1
  50. package/src/combined.ts +107 -17
  51. package/src/content-search-worker.ts +52 -24
  52. package/src/content-search.ts +710 -36
  53. package/src/content.ts +349 -73
  54. package/src/export.ts +240 -50
  55. package/src/find.ts +83 -16
  56. package/src/http.ts +271 -83
  57. package/src/reveal.ts +148 -10
  58. package/src/tools.ts +83 -6
package/src/export.ts CHANGED
@@ -5,13 +5,31 @@
5
5
  * page and writes a normal SQLite database so external tools can query it.
6
6
  * `node:sqlite` is loaded lazily: hosts below Node 22.5 get a clear error
7
7
  * instead of a plugin that fails to load.
8
+ *
9
+ * The export is a *controlled* write, not an arbitrary filesystem write:
10
+ * - the target must live inside the plugin state directory unless the caller
11
+ * explicitly opts into an outside path (`allowOutsideStateDir`), and a
12
+ * relative path always resolves inside the state directory;
13
+ * - an existing target is only replaced when it is a database this tool
14
+ * created (SQLite header + our `user_version` marker + the `entries`
15
+ * schema), so `overwrite` can never clobber an unrelated file;
16
+ * - the database is built in a sibling temporary file and moved into place
17
+ * with an atomic rename, so a failed export never leaves a half-written
18
+ * database at the requested path.
8
19
  * @module dsh-locator/export
9
20
  */
10
21
 
11
- import { existsSync, mkdirSync, rmSync, statSync } from 'node:fs'
12
- import { dirname, isAbsolute, resolve } from 'node:path'
22
+ import { existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs'
23
+ import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
13
24
  import { defineTool } from '@deepseek-ai/dsh-tools'
14
25
  import type { LocatorRuntime } from './runtime.ts'
26
+ import { resolveWithinRoots } from './reveal.ts'
27
+
28
+ /** `PRAGMA user_version` stamped into every database this tool creates. */
29
+ export const EXPORT_DB_USER_VERSION = 1
30
+
31
+ /** Default file name inside the state directory when `path` is omitted. */
32
+ export const DEFAULT_EXPORT_NAME = 'locator-export.sqlite'
15
33
 
16
34
  const OUTPUT_SCHEMA = {
17
35
  type: 'object',
@@ -26,6 +44,104 @@ const OUTPUT_SCHEMA = {
26
44
  },
27
45
  } as const
28
46
 
47
+ /** Minimal shape of `node:sqlite` used here (the real typings are platform-dependent). */
48
+ interface SqliteDatabaseLike {
49
+ exec(sql: string): unknown
50
+ prepare(sql: string): {
51
+ run(...parameters: unknown[]): unknown
52
+ get(...parameters: unknown[]): unknown
53
+ }
54
+ close(): void
55
+ }
56
+
57
+ /** The lazily imported `node:sqlite` module slice. */
58
+ export interface SqliteModuleLike {
59
+ DatabaseSync: new (path: string, options?: { readOnly?: boolean }) => SqliteDatabaseLike
60
+ }
61
+
62
+ /** Authorization result for one export target. */
63
+ export type ExportTargetResult =
64
+ | { ok: true; path: string }
65
+ | { ok: false; error: string }
66
+
67
+ /**
68
+ * Authorize the requested export path.
69
+ *
70
+ * With no `path`, the export goes to `<stateDir>/locator-export.sqlite`. A
71
+ * relative path resolves inside the state directory (and may not escape it by
72
+ * `..`). An absolute path is accepted only inside the state directory unless
73
+ * the caller explicitly passes `allowOutsideStateDir`.
74
+ * @param requested - raw `path` argument, if any.
75
+ * @param stateDir - the plugin's state directory.
76
+ * @param allowOutsideStateDir - explicit opt-in for an absolute path elsewhere.
77
+ * @returns the absolute output path, or a refusal message.
78
+ */
79
+ export function resolveExportTarget(
80
+ requested: string | undefined,
81
+ stateDir: string,
82
+ allowOutsideStateDir: boolean,
83
+ ): ExportTargetResult {
84
+ const state = resolve(stateDir)
85
+ const raw = typeof requested === 'string' ? requested.trim() : ''
86
+ if (raw === '') return { ok: true, path: resolve(state, DEFAULT_EXPORT_NAME) }
87
+ const candidate = isAbsolute(raw) ? resolve(raw) : resolve(state, raw)
88
+ if (isAbsolute(raw) && !allowOutsideStateDir) {
89
+ const inside = resolveWithinRoots(candidate, [state])
90
+ if (inside === undefined) {
91
+ return {
92
+ ok: false,
93
+ error: `path must stay inside the plugin state directory (${state}); pass allowOutsideStateDir: true to export elsewhere`,
94
+ }
95
+ }
96
+ return { ok: true, path: inside.path }
97
+ }
98
+ if (!isAbsolute(raw)) {
99
+ // A relative path is resolved against the state directory; containment is
100
+ // still checked so `..` cannot turn the default into an escape hatch.
101
+ const inside = resolveWithinRoots(candidate, [state])
102
+ if (inside === undefined) {
103
+ return { ok: false, error: `relative path escapes the plugin state directory (${state})` }
104
+ }
105
+ return { ok: true, path: inside.path }
106
+ }
107
+ return { ok: true, path: candidate }
108
+ }
109
+
110
+ /**
111
+ * Whether `target` is a SQLite database produced by this tool: it must open,
112
+ * carry our `user_version` marker and expose the exported `entries` schema.
113
+ * An arbitrary SQLite file (even with a parent directory deliberately named
114
+ * like an export) is refused, so `overwrite` cannot destroy user data.
115
+ * @param sqlite - the `node:sqlite` module.
116
+ * @param target - existing file to inspect.
117
+ */
118
+ export function isOwnExportDatabase(sqlite: SqliteModuleLike, target: string): boolean {
119
+ let db: SqliteDatabaseLike | undefined
120
+ try {
121
+ db = new sqlite.DatabaseSync(target, { readOnly: true })
122
+ } catch {
123
+ return false
124
+ }
125
+ try {
126
+ const version = db.prepare('PRAGMA user_version').get()
127
+ const value = typeof version === 'object' && version !== null
128
+ ? Number((version as Record<string, unknown>).user_version)
129
+ : Number.NaN
130
+ if (value !== EXPORT_DB_USER_VERSION) return false
131
+ // Prepares (and thereby validates) the documented schema without rows.
132
+ db.prepare('SELECT path, name, dir, size, mtime_ms, ext FROM entries LIMIT 0').get()
133
+ return true
134
+ } catch {
135
+ return false
136
+ } finally {
137
+ try {
138
+ db.close()
139
+ } catch {
140
+ // A read-only handle that already failed to close does not change the verdict.
141
+ }
142
+ }
143
+ }
144
+
29
145
  /** Build the locator_export tool. */
30
146
  export function makeExportTool(rt: LocatorRuntime) {
31
147
  return defineTool({
@@ -35,11 +151,17 @@ export function makeExportTool(rt: LocatorRuntime) {
35
151
  '',
36
152
  'The database has one table, `entries(path TEXT PRIMARY KEY, name TEXT, dir INTEGER, size INTEGER, mtime_ms INTEGER, ext TEXT)`. It is a snapshot: run the tool again to refresh it. The index itself stays in its compact binary form; this is for external SQL tools, dashboards or scripts.',
37
153
  '',
154
+ 'The output path must stay inside the plugin state directory: omit `path` for `<stateDir>/locator-export.sqlite`, use a relative `path`, or pass an absolute path under the reported state directory. Set `allowOutsideStateDir: true` to export somewhere else deliberately. `overwrite` only replaces a database this tool created; any other existing file is left untouched and the call fails. Writes are atomic (temporary file + rename).',
155
+ '',
38
156
  'Use it when the user asks for a queryable copy of their file index, wants to run SQL against it, or needs the data in another program. It is expensive on a million-entry index (tens of seconds and a large file), so do not call it routinely.',
39
157
  ].join('\n'),
40
158
  parameters: {
41
- path: { type: 'string', required: true, description: 'Absolute path of the .sqlite/.db file to create.' },
42
- overwrite: { type: 'boolean', description: 'Replace an existing file (default false).' },
159
+ path: {
160
+ type: 'string',
161
+ description: 'Output .sqlite/.db file. Defaults to <stateDir>/locator-export.sqlite; relative paths resolve inside the state directory, absolute paths must be inside it unless allowOutsideStateDir is true.',
162
+ },
163
+ overwrite: { type: 'boolean', description: 'Replace an existing file created by this tool (default false). Any other existing file is never overwritten.' },
164
+ allowOutsideStateDir: { type: 'boolean', description: 'Allow an absolute path outside the plugin state directory (explicit opt-in, default false).' },
43
165
  pageSize: { type: 'integer', description: 'Rows per engine request (default 5000, max 10000).' },
44
166
  },
45
167
  timeoutMs: 180_000,
@@ -56,73 +178,141 @@ export function makeExportTool(rt: LocatorRuntime) {
56
178
  },
57
179
  async execute(args) {
58
180
  const started = Date.now()
59
- const target = resolve(args.path)
60
- if (!isAbsolute(args.path)) return { ok: false as const, error: 'path must be absolute' }
61
- if (existsSync(target) && args.overwrite !== true) {
62
- return { ok: false as const, error: `refusing to overwrite ${target}; pass overwrite: true` }
181
+ const target = resolveExportTarget(args.path, rt.stateDir, args.allowOutsideStateDir === true)
182
+ if (!target.ok) return { ok: false as const, error: target.error }
183
+ const output = target.path
184
+ const existed = existsSync(output)
185
+ if (existed && args.overwrite !== true) {
186
+ return { ok: false as const, error: `refusing to overwrite ${output}; pass overwrite: true` }
63
187
  }
64
- const pageSize = Math.min(10_000, Math.max(100, args.pageSize ?? 5000))
65
- mkdirSync(dirname(target), { recursive: true })
66
188
 
67
- let sqlite: typeof import('node:sqlite')
189
+ let sqlite: SqliteModuleLike
68
190
  try {
69
- sqlite = await import('node:sqlite')
191
+ sqlite = await import('node:sqlite') as unknown as SqliteModuleLike
70
192
  } catch {
71
193
  return { ok: false as const, error: 'node:sqlite is unavailable; Node 22.5 or newer is required' }
72
194
  }
195
+ // Overwrite is a deletion: only this tool's own database may be deleted.
196
+ if (existed && !isOwnExportDatabase(sqlite, output)) {
197
+ return { ok: false as const, error: `refusing to overwrite ${output}: not a database created by locator_export` }
198
+ }
73
199
 
74
- if (existsSync(target)) rmSync(target)
75
- rt.start()
76
- const db = new sqlite.DatabaseSync(target)
200
+ const pageSize = Math.min(10_000, Math.max(100, args.pageSize ?? 5000))
201
+ try {
202
+ mkdirSync(dirname(output), { recursive: true })
203
+ } catch (error) {
204
+ return { ok: false as const, error: messageOf(error) }
205
+ }
206
+
207
+ // Build in a sibling temp file so the destination is only ever the old
208
+ // complete database or the new complete one, never a partial write.
209
+ const temporary = temporaryPathFor(output)
77
210
  let rows = 0
78
211
  try {
79
- db.exec('PRAGMA journal_mode = MEMORY')
80
- db.exec('PRAGMA synchronous = OFF')
81
- db.exec(`CREATE TABLE entries (
82
- path TEXT PRIMARY KEY,
83
- name TEXT NOT NULL,
84
- dir INTEGER NOT NULL,
85
- size INTEGER NOT NULL,
86
- mtime_ms INTEGER NOT NULL,
87
- ext TEXT NOT NULL
88
- ) WITHOUT ROWID`)
89
- db.exec('CREATE INDEX entries_mtime ON entries(mtime_ms)')
90
- const insert = db.prepare('INSERT OR REPLACE INTO entries (path, name, dir, size, mtime_ms, ext) VALUES (?, ?, ?, ?, ?, ?)')
91
- db.exec('BEGIN')
92
- let after = 0
93
- for (;;) {
94
- const page = await rt.dump(after, pageSize)
95
- for (const entry of page.entries) {
96
- insert.run(entry.path, entry.name, entry.dir ? 1 : 0, entry.size, entry.mtime, entry.ext)
97
- rows++
98
- }
99
- after = page.next
100
- if (page.done || page.entries.length === 0) break
101
- await new Promise(resolve => setImmediate(resolve))
102
- }
103
- db.exec('COMMIT')
212
+ rows = await writeDatabase(sqlite, rt, temporary, pageSize)
104
213
  } catch (error) {
105
- try {
106
- db.exec('ROLLBACK')
107
- } catch {
108
- // The transaction may already be closed; the file is removed below.
109
- }
110
- db.close()
111
- rmSync(target, { force: true })
214
+ rmSync(temporary, { force: true })
215
+ return { ok: false as const, error: messageOf(error) }
216
+ }
217
+ try {
218
+ replaceWithRename(sqlite, temporary, output)
219
+ } catch (error) {
220
+ rmSync(temporary, { force: true })
112
221
  return { ok: false as const, error: messageOf(error) }
113
222
  }
114
- db.close()
115
223
  return {
116
224
  ok: true as const,
117
- path: target,
225
+ path: output,
118
226
  rows,
119
- bytes: statSync(target).size,
227
+ bytes: statSync(output).size,
120
228
  tookMs: Date.now() - started,
121
229
  }
122
230
  },
123
231
  })
124
232
  }
125
233
 
234
+ /** Stream the index dump into a fresh database at `temporary`; returns the row count. */
235
+ async function writeDatabase(
236
+ sqlite: SqliteModuleLike,
237
+ rt: LocatorRuntime,
238
+ temporary: string,
239
+ pageSize: number,
240
+ ): Promise<number> {
241
+ rt.start()
242
+ const db = new sqlite.DatabaseSync(temporary)
243
+ let rows = 0
244
+ try {
245
+ db.exec('PRAGMA journal_mode = MEMORY')
246
+ db.exec('PRAGMA synchronous = OFF')
247
+ db.exec(`CREATE TABLE entries (
248
+ path TEXT PRIMARY KEY,
249
+ name TEXT NOT NULL,
250
+ dir INTEGER NOT NULL,
251
+ size INTEGER NOT NULL,
252
+ mtime_ms INTEGER NOT NULL,
253
+ ext TEXT NOT NULL
254
+ ) WITHOUT ROWID`)
255
+ db.exec('CREATE INDEX entries_mtime ON entries(mtime_ms)')
256
+ // Ownership marker: only a database carrying it can be replaced later.
257
+ db.exec(`PRAGMA user_version = ${String(EXPORT_DB_USER_VERSION)}`)
258
+ const insert = db.prepare('INSERT OR REPLACE INTO entries (path, name, dir, size, mtime_ms, ext) VALUES (?, ?, ?, ?, ?, ?)')
259
+ db.exec('BEGIN')
260
+ let after = 0
261
+ for (;;) {
262
+ const page = await rt.dump(after, pageSize)
263
+ for (const entry of page.entries) {
264
+ insert.run(entry.path, entry.name, entry.dir ? 1 : 0, entry.size, entry.mtime, entry.ext)
265
+ rows++
266
+ }
267
+ after = page.next
268
+ if (page.done || page.entries.length === 0) break
269
+ await new Promise(resolve => setImmediate(resolve))
270
+ }
271
+ db.exec('COMMIT')
272
+ return rows
273
+ } catch (error) {
274
+ try {
275
+ db.exec('ROLLBACK')
276
+ } catch {
277
+ // The transaction may already be closed; the temp file is removed by the caller.
278
+ }
279
+ throw error
280
+ } finally {
281
+ try {
282
+ db.close()
283
+ } catch {
284
+ // Closing a failed build must not mask the real error.
285
+ }
286
+ }
287
+ }
288
+
289
+ /**
290
+ * Move the finished temp database over the destination. POSIX `rename`
291
+ * replaces atomically; on Windows the replace can be refused while the old
292
+ * database is briefly open, in which case the (re-validated) old file is
293
+ * removed first. The destination is never removed unless it is still a
294
+ * database this tool created.
295
+ */
296
+ function replaceWithRename(sqlite: SqliteModuleLike, temporary: string, output: string): void {
297
+ try {
298
+ renameSync(temporary, output)
299
+ return
300
+ } catch (error) {
301
+ if (!existsSync(output)) throw error
302
+ if (!isOwnExportDatabase(sqlite, output)) {
303
+ throw new Error(`refusing to replace ${output}: it is no longer a database created by locator_export`)
304
+ }
305
+ rmSync(output, { force: true })
306
+ renameSync(temporary, output)
307
+ }
308
+ }
309
+
310
+ /** A unique sibling temp path; never a path derived from user input components. */
311
+ function temporaryPathFor(target: string): string {
312
+ const random = Math.random().toString(36).slice(2, 10)
313
+ return join(dirname(target), `.${basename(target)}.${String(process.pid)}.${Date.now().toString(36)}.${random}.tmp`)
314
+ }
315
+
126
316
  function messageOf(error: unknown): string {
127
317
  return error instanceof Error ? error.message : String(error)
128
318
  }
package/src/find.ts CHANGED
@@ -5,6 +5,7 @@
5
5
 
6
6
  import { defineTool } from '@deepseek-ai/dsh-tools'
7
7
  import type { ContentIndex, ContentState } from './content.ts'
8
+ import type { ContentSearchOptions } from './content-search.ts'
8
9
 
9
10
  const HIT = {
10
11
  type: 'object',
@@ -17,10 +18,26 @@ const HIT = {
17
18
  sessionId: { type: 'string' },
18
19
  messageId: { type: 'string' },
19
20
  nodeKey: { type: 'string' },
21
+ line: { type: 'integer', description: '1-based line of the first match in the stored body (file hits).' },
20
22
  score: { type: 'number' },
21
23
  },
22
24
  } as const
23
25
 
26
+ const STATE = {
27
+ type: 'object',
28
+ additionalProperties: false,
29
+ properties: {
30
+ building: { type: 'boolean' },
31
+ files: { type: 'integer' },
32
+ sessions: { type: 'integer' },
33
+ messages: { type: 'integer' },
34
+ truncated: { type: 'boolean' },
35
+ updatedAt: { type: 'integer' },
36
+ error: { type: 'string' },
37
+ warnings: { type: 'array', items: { type: 'string' }, description: 'Non-fatal build problems, e.g. an unreadable session log.' },
38
+ },
39
+ } as const
40
+
24
41
  /** Build the locator_find tool. */
25
42
  export function makeFindTool(content: ContentIndex, ensure?: () => void) {
26
43
  return defineTool({
@@ -30,11 +47,19 @@ export function makeFindTool(content: ContentIndex, ensure?: () => void) {
30
47
  '',
31
48
  'Use it when the user remembers a phrase, a sentence, a decision or a code snippet rather than a file name. `locator_search` searches names and paths; this searches bodies and returns snippets plus `sessionId`/`messageId` for session hits, so the result can be opened at its source.',
32
49
  '',
33
- 'Content is built asynchronously after start: results may be partial while `state.building` is true. Text files are capped by `contentMaxFileBytes`; session logs are decompressed from `$DSH_HOME/sessions`.',
50
+ 'Content is substring search over an FTS5 trigram index: every term must be at least 3 characters (shorter queries are rejected with `content-query-too-short` instead of scanning the whole corpus). Text files are capped by `contentMaxFileBytes`; session logs are decompressed from `$DSH_HOME/sessions`.',
34
51
  ].join('\n'),
35
52
  parameters: {
36
53
  query: { type: 'string', required: true, description: 'Words or a phrase to find in file/session content.' },
37
54
  limit: { type: 'integer', description: 'Maximum hits (default 30, at most 100).' },
55
+ matchMode: { type: 'string', enum: ['normal', 'extended'], description: 'normal: whitespace-separated substring terms. extended: one literal phrase with Notepad++ escapes (\\n, \\r, \\t, \\0, \\xNN, \\\\).' },
56
+ caseSensitive: { type: 'boolean', description: 'Match letter case exactly.' },
57
+ wholeWord: { type: 'boolean', description: 'Only match whole words ([A-Za-z0-9_] boundaries; CJK counts as non-word).' },
58
+ sessionId: { type: 'string', description: 'Only search messages of one DSH session id (defaults to the caller session in workspace scope).' },
59
+ scope: { type: 'string', enum: ['workspace', 'all'], description: 'workspace (default) restricts file hits to the caller workspace/cwd and session hits to the caller session; all searches every indexed file and session (explicit cross-workspace access).' },
60
+ count: { type: 'string', enum: ['exact', 'bounded', 'none'], description: 'How much counting work to spend; bounded stops at countLimit.' },
61
+ countLimit: { type: 'integer', description: 'Counting cap for bounded counts (default 1000, at most 5000).' },
62
+ pathPrefix: { type: 'string', description: 'Only return file hits whose path starts with this directory (session hits are unaffected).' },
38
63
  },
39
64
  output: {
40
65
  schema: {
@@ -44,40 +69,82 @@ export function makeFindTool(content: ContentIndex, ensure?: () => void) {
44
69
  ok: { type: 'boolean', required: true },
45
70
  query: { type: 'string' },
46
71
  hits: { type: 'array', items: HIT },
47
- state: {
72
+ count: {
48
73
  type: 'object',
49
74
  additionalProperties: false,
50
75
  properties: {
51
- building: { type: 'boolean' },
52
- files: { type: 'integer' },
53
- sessions: { type: 'integer' },
54
- messages: { type: 'integer' },
55
- truncated: { type: 'boolean' },
56
- updatedAt: { type: 'integer' },
57
- error: { type: 'string' },
76
+ value: { type: 'integer' },
77
+ kind: { type: 'string', enum: ['exact', 'bounded', 'unknown'] },
78
+ limit: { type: 'integer' },
58
79
  },
59
80
  },
81
+ warnings: { type: 'array', items: { type: 'string' } },
82
+ state: STATE,
60
83
  error: { type: 'string' },
61
84
  },
62
85
  },
63
86
  render: (_args, value) => {
64
- const v = value as { ok: boolean; hits?: Array<{ kind: string; title?: string; snippet?: string; path?: string }>; error?: string; state?: ContentState }
65
- if (!v.ok) return [{ type: 'text', text: `locator_find failed: ${v.error ?? 'unknown'}` }]
66
- const lines = (v.hits ?? []).map((hit, index) => `${String(index + 1)}. [${hit.kind}] ${hit.title ?? ''} — ${hit.snippet ?? ''}\n ${hit.path ?? ''}`)
87
+ const v = value as {
88
+ ok: boolean
89
+ hits?: Array<{ kind: string; title?: string; snippet?: string; path?: string; line?: number; sessionId?: string; messageId?: string }>
90
+ count?: { value: number; kind: 'exact' | 'bounded' | 'unknown' }
91
+ warnings?: string[]
92
+ error?: string
93
+ state?: ContentState
94
+ }
95
+ if (!v.ok) {
96
+ const detail = v.warnings !== undefined && v.warnings.length > 0 ? ` (${[...new Set(v.warnings)].join(', ')})` : ''
97
+ return [{ type: 'text', text: `locator_find failed: ${v.error ?? 'unknown'}${detail}` }]
98
+ }
99
+ const lines = (v.hits ?? []).map((hit, index) => {
100
+ const ref = hit.kind === 'session' && (hit.sessionId !== undefined || hit.messageId !== undefined)
101
+ ? `\n session ${String(hit.sessionId ?? '')}${hit.messageId === undefined ? '' : ` message ${String(hit.messageId)}`}`
102
+ : ''
103
+ return `${String(index + 1)}. [${hit.kind}] ${hit.title ?? ''} — ${hit.snippet ?? ''}\n ${hit.path ?? ''}${typeof hit.line === 'number' ? ` (line ${String(hit.line)})` : ''}${ref}`
104
+ })
105
+ const count = v.count === undefined
106
+ ? ''
107
+ : v.count.kind === 'bounded'
108
+ ? `, count ≥ ${String(v.count.value)}`
109
+ : v.count.kind === 'exact'
110
+ ? `, count ${String(v.count.value)}`
111
+ : ''
112
+ const warnings = [...new Set([...(v.warnings ?? []), ...(v.state?.warnings ?? [])])]
67
113
  const notes = [
68
114
  v.state?.building ? ' (index still building)' : '',
69
115
  v.state?.truncated === true ? ' (content budget reached: raise contentMaxTotalBytes or trim contentExcludes; later files are not searchable)' : '',
116
+ warnings.length > 0 ? ` (warnings: ${warnings.join(', ')})` : '',
70
117
  ].join('')
71
- return [{ type: 'text', text: `${String(v.hits?.length ?? 0)} content hit(s)${notes}\n${lines.join('\n')}` }]
118
+ return [{ type: 'text', text: `${String(v.hits?.length ?? 0)} content hit(s)${count}${notes}\n${lines.join('\n')}` }]
72
119
  },
73
120
  },
74
- async execute(args) {
121
+ async execute(args, exec) {
75
122
  ensure?.()
76
123
  const query = args.query.trim()
77
124
  if (query === '') return { ok: false as const, error: 'query is empty' }
78
125
  const limit = Math.max(1, Math.min(100, args.limit ?? 30))
79
- const hits = await content.search(query, limit)
80
- return { ok: true as const, query, hits, state: content.status() }
126
+ const scope = args.scope === 'all' ? 'all' : 'workspace'
127
+ const callerSessionId = scope === 'workspace' ? exec?.agent?.session?.id : undefined
128
+ const callerCwd = scope === 'workspace' ? exec?.agent?.session?.header?.cwd : undefined
129
+ const options: ContentSearchOptions = {
130
+ ...(args.matchMode === undefined ? {} : { matchMode: args.matchMode }),
131
+ ...(args.caseSensitive === undefined ? {} : { caseSensitive: args.caseSensitive }),
132
+ ...(args.wholeWord === undefined ? {} : { wholeWord: args.wholeWord }),
133
+ ...(args.sessionId !== undefined && args.sessionId !== ''
134
+ ? { sessionId: args.sessionId }
135
+ : callerSessionId === undefined ? {} : { sessionId: String(callerSessionId) }),
136
+ ...(args.count === undefined ? {} : { count: args.count }),
137
+ ...(args.countLimit === undefined ? {} : { countLimit: args.countLimit }),
138
+ ...(args.pathPrefix !== undefined && args.pathPrefix !== ''
139
+ ? { pathPrefix: args.pathPrefix }
140
+ : callerCwd === undefined ? {} : { pathPrefix: callerCwd }),
141
+ }
142
+ const result = await content.search(query, limit, options)
143
+ const state = content.status()
144
+ if (result.error !== undefined) {
145
+ return { ok: false as const, query, error: result.error, warnings: result.warnings, hits: [], state }
146
+ }
147
+ return { ok: true as const, query, hits: result.hits, count: result.count, warnings: result.warnings, state }
81
148
  },
82
149
  })
83
150
  }