antigravity-plugin-context-mode 1.4.0 → 1.5.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/CHANGELOG.md CHANGED
@@ -2,20 +2,31 @@
2
2
 
3
3
  All notable changes to `antigravity-plugin-context-mode` will be documented in this file.
4
4
 
5
- ## [1.4.0] - 2026-11-21
5
+ ## [1.5.0] - 2026-11-21
6
6
 
7
7
  ### Added
8
+ - **SQLite Schema v3 (`path` as Primary Key Everywhere)**: Migrated database schema to v3, promoting `path` to the primary key on `sources(path TEXT PRIMARY KEY)` and foreign reference on `chunks(path UNINDEXED)` / `chunks_tri(path UNINDEXED)`. Seamless automatic migration from existing v2 databases preserves database integrity while eliminating all legacy surrogate ID generators.
9
+ - **Just-In-Time On-Demand Indexing (`ctx_search`)**: Refactored `ctx_search` to support `path` for individual files, directory paths, and remote URLs. Unindexed or modified files are automatically checked against file modification timestamps (`mtime`) and indexed Just-In-Time before searching, returning instant, fresh hits in a single call.
10
+ - **Reverse Search for Log Files (`reverse: true`)**: Added optional `reverse` parameter to `ctx_search` to sort search hits by chunk order in reverse (`b.ord - a.ord`). Prioritizes the latest events, errors, and fatal crashes at the end of large log files first.
11
+ - **Snippet Centering on Search Hits**: Window search snippets around the matched query term position rather than slicing from offset 0, ensuring matching context is visible even in large chunks.
12
+ - **Intra-File Search Priority in Agent Standards (`rules/AGENTS.md`)**: Instructs agents to always prioritize `ctx_search(queries: [...], path: "path/to/target")` for all intra-file and directory searches without manual indexing or pre-reading into context.
8
13
  - **Live Active Cutoff & Exemption Injections (`SessionStart` & `PreInvocation`)**: Injected system messages dynamically report the active single-operation read cutoff and enumerate all active exempt file categories and custom extensions. Explicitly clarifies to LLM agents that the cutoff is a single-read tool threshold, not the model's context window.
9
14
  - **Mid-Session Dynamic Configuration Tracking (`PreInvocation`)**: Added `hooks/pre-invocation.js` registered under `PreInvocation` in `hooks.json`. Automatically detects when cutoff limits or file exemptions are modified mid-session (via dashboard or API) and immediately informs the agent on the subsequent turn while remaining completely quiet when unchanged.
10
- - **Automatic Indexing Redirection on Interception (`PreToolUse`)**: Instead of simply rejecting large `read_file` operations or un-paged file dump commands (`cat`, `Get-Content`, `type`), `PreToolUse` now automatically reads and indexes the target file into SQLite FTS5 (up to a configurable 50 MB ceiling) and returns `[context-mode protection: auto-indexed]` with the intuitive workspace-relative `sourceId` and immediate search instructions (`ctx_search(queries: [...], sourceId: "...")`).
11
- - **Workspace-Relative Source IDs (`resolveFileSourceId`)**: Normalized file `sourceId` generation in `lib/store.js` and `ctx_index`. Files inside the active project directory resolve to clean, intuitive relative paths (e.g. `src/utils.js`, `Logs/Editor.log`) rather than opaque hashes, making `ctx_search` queries with `sourceId` natural and effortless for LLM agents.
15
+ - **Automatic Indexing Redirection on Interception (`PreToolUse`)**: Instead of simply rejecting large `read_file` operations or un-paged file dump commands (`cat`, `Get-Content`, `type`), `PreToolUse` now automatically reads and indexes the target file into SQLite FTS5 (up to a configurable 50 MB ceiling) and returns `[context-mode protection: auto-indexed]` with the intuitive workspace-relative path and immediate search instructions (`ctx_search(queries: [...], path: "...")`).
12
16
  - **Auto-Index Limit Dashboard Control & API**: Added a Max Auto-Index dropdown selector (`1 MB`, `5 MB`, `10 MB`, `50 MB`, `100 MB`, `Off`) directly adjacent to the Cutoff dropdown in the sidecar dashboard. Added `/api/auto-index-limit` (`GET` and `POST`) endpoint in `server.mjs`.
13
17
  - **Configurable Auto-Index Limits Cascade**: Configurable via `CONTEXT_MODE_MAX_AUTO_INDEX_BYTES` env variable, session overrides, or SQLite global setting (`store.getMaxAutoIndexBytes()` and `store.setMaxAutoIndexBytes()`).
14
- - **Idempotent File Re-indexing**: Re-indexing an existing file sourceId cleans up prior chunk entries before writing new ones, preventing chunk duplication when files are edited and re-indexed.
18
+ - **Idempotent File Re-indexing**: Re-indexing an existing file path cleans up prior chunk entries before writing new ones, preventing chunk duplication when files are edited and re-indexed.
15
19
  - **Active Limit & Exemption Diagnostics in MCP Tools**: Enhanced `ctx_stats` and `ctx_doctor` to return active cutoff bytes, formatted cutoff strings, and active exempt categories/extensions.
16
20
 
21
+ ### Removed
22
+ - **Retired `ctx_index` Tool**: Removed `ctx_index` from MCP tool definitions, server schemas, rules, and skills. Because `ctx_search` automatically indexes files, directories, and URLs on-demand, manual indexing is completely obsolete.
23
+ - **Eliminated `sourceId` Parameter**: Replaced internal database identifier `sourceId` across all tool schemas, denial messages, and agent instructions with standard `path`.
24
+ - **Stripped `mcp_context-mode_` Prefix from Denial Messages**: Simplified all guidance messages so tool calls are referred to cleanly as `ctx_search` and `ctx_execute`.
25
+
17
26
  ### Fixed
18
- - **Debunked 8 KB Context Window Hallucination in Agent Rules (`rules/AGENTS.md`)**: Updated behavioral guidelines to explicitly distinguish between the tool-level read cutoff and the model's actual context window, and instructed agents that exempt files (PDFs, images, Office documents, 3D models, audio, video, archives, and prompt attachments) bypass cutoff protection and can be read directly with `read_file` without hesitation.
27
+ - **Dynamic Maximum Line Ranges**: Replaced arbitrary hardcoded line numbers (`-First 50`, `head -n 50`) in denial messages and rules with dynamic maximum limits (`getMaxLineRange(maxReadBytes)`) and explicit instructions to read only the lines needed.
28
+ - **Zero Redundant Instructions**: Stripped repetitive tutorial text, hardcoded exemption catalogs, and false guarantees from rules, session-start notices, and tool denial reasons.
29
+ - **Debunked 8 KB Context Window Hallucination in Agent Rules (`rules/AGENTS.md`)**: Updated behavioral guidelines to explicitly distinguish between the tool-level read cutoff and the model's actual context window, and instructed agents that exempt files bypass cutoff protection.
19
30
  - **Dynamic PreToolUse Denial Messages**: Refactored denial messages in `hooks/pre-tool-use.js` to dynamically generate the live active exempt categories and custom extensions from SQLite rather than displaying a static hardcoded note.
20
31
  - **Double-Counting Prevention in Statistics**: Updated `getStats()` in `lib/store.js` to ensure auto-indexed files logged through `read_file` or `run_command` interceptions are not double-counted between `events` and `sources`.
21
32
  - **Safe ES Module Hook Imports**: Added `isMain` execution guards to `hooks/pre-tool-use.js` and `hooks/session-start.js` to prevent unintended top-level execution when importing helper utilities across hooks and test suites.
package/README.md CHANGED
@@ -99,13 +99,12 @@ Tested live on real-world build logs and source files in the Antigravity App:
99
99
 
100
100
  ## Available MCP Tools
101
101
 
102
- Once installed, Context Mode provides 8 specialized tools for your agent:
102
+ Once installed, Context Mode provides 7 specialized tools for your agent:
103
103
 
104
104
  | Tool | What It Does |
105
105
  | :--- | :--- |
106
106
  | **`ctx_execute`** | Runs sandboxed Node.js, Python, or PowerShell scripts to inspect files and extract answers without context dumps. |
107
- | **`ctx_search`** | Searches indexed logs and documentation using local SQLite FTS5 BM25 stemming. |
108
- | **`ctx_index`** | Indexes local files or documentation into searchable chunks for the agent. |
107
+ | **`ctx_search`** | Searches files, directories, or URLs with Just-In-Time auto-indexing using local SQLite FTS5 BM25 + Trigram RRF. |
109
108
  | **`ctx_batch`** | Runs multiple terminal commands in batch and indexes the combined output. |
110
109
  | **`ctx_stats`** | Displays a formatted context savings report and token metrics. |
111
110
  | **`ctx_resume`** | Returns recent indexed sources and state pointers after context compactions. |
@@ -2,7 +2,7 @@
2
2
  import fs from "node:fs";
3
3
  import path from "node:path";
4
4
  import { fileURLToPath } from "node:url";
5
- import { ContextModeStore, DEFAULT_MAX_AUTO_INDEX_BYTES, resolveFileSourceId } from "../lib/store.js";
5
+ import { ContextModeStore, DEFAULT_MAX_AUTO_INDEX_BYTES, resolveFilePath } from "../lib/store.js";
6
6
 
7
7
  export const DEFAULT_MAX_READ_BYTES = 8192; // 8 KB default cutoff
8
8
  export const DEFAULT_MAX_LINE_RANGE = 200; // 200 lines max un-indexed slice
@@ -308,7 +308,7 @@ export function inspectCommand({ commandLine, cwd, sessionId }) {
308
308
  shouldDeny: true,
309
309
  reason:
310
310
  `[context-mode protection] 'git log' without a count limiter risks dumping thousands of commits into context. ` +
311
- `Please specify a count (e.g. 'git log -n 10') or run inside 'mcp_context-mode_ctx_execute'.`,
311
+ `Please specify a count (e.g. 'git log -n 10') or run inside 'ctx_execute'.`,
312
312
  size: 32768,
313
313
  targetPath: "git log"
314
314
  };
@@ -336,7 +336,7 @@ export function inspectCommand({ commandLine, cwd, sessionId }) {
336
336
  shouldDeny: true,
337
337
  reason:
338
338
  `[context-mode protection] Direct curl/wget download to stdout risks flooding the context window. ` +
339
- `Please use 'mcp_context-mode_ctx_execute', save to disk ('-o <file>'), or limit output (e.g. '| head -n <lines>').`,
339
+ `Please use 'ctx_execute', save to disk ('-o <file>'), or limit output (e.g. '| head -n <lines>').`,
340
340
  size: 32768,
341
341
  targetPath: urlMatch ? urlMatch[0] : cleanCmd
342
342
  };
@@ -366,7 +366,7 @@ export function inspectCommand({ commandLine, cwd, sessionId }) {
366
366
  shouldDeny: true,
367
367
  reason:
368
368
  `[context-mode protection] Wildcard file dump ('${rawTarget}') risks flooding the context window. ` +
369
- `Please use 'mcp_context-mode_ctx_execute' or limit output to only the needed lines (<= ${maxLineRange} lines, e.g. '| Select-Object -First <lines>').`,
369
+ `Please use 'ctx_execute' or limit output to only the needed lines (<= ${maxLineRange} lines, e.g. '| Select-Object -First <lines>').`,
370
370
  size: 32768,
371
371
  targetPath: rawTarget
372
372
  };
@@ -388,7 +388,7 @@ export function inspectCommand({ commandLine, cwd, sessionId }) {
388
388
  // Dynamic cutoff check against active setting
389
389
  if (maxReadBytes > 0 && stat.size > maxReadBytes) {
390
390
  const maxAutoIndexBytes = getMaxAutoIndexBytes(sessionId);
391
- const sourceId = resolveFileSourceId(absPath, cwd) || cleanTarget;
391
+ const targetPath = resolveFilePath(absPath, cwd) || cleanTarget;
392
392
 
393
393
  let isAutoIndexed = false;
394
394
  if (maxAutoIndexBytes > 0 && stat.size <= maxAutoIndexBytes) {
@@ -400,9 +400,10 @@ export function inspectCommand({ commandLine, cwd, sessionId }) {
400
400
  worktree: cwd,
401
401
  agent: "antigravity",
402
402
  kind: "file",
403
- label: sourceId,
404
- sourceId,
405
- content
403
+ label: targetPath,
404
+ path: targetPath,
405
+ content,
406
+ mtime: Math.round(stat.mtimeMs)
406
407
  });
407
408
  store.close();
408
409
  isAutoIndexed = true;
@@ -414,20 +415,20 @@ export function inspectCommand({ commandLine, cwd, sessionId }) {
414
415
  reason =
415
416
  `[context-mode protection: auto-indexed] Command attempts an un-paged dump of '${cleanTarget}' (${formatBytes(stat.size)}), ` +
416
417
  `exceeding the active ${formatBytes(maxReadBytes)} context limit. ` +
417
- `The file has been automatically indexed as source '${sourceId}'. ` +
418
- `Query it with 'mcp_context-mode_ctx_search(queries: [...], sourceId: "${sourceId}")' or limit output to only needed lines (<= ${maxLineRange} lines, e.g. -Head <lines> or '| Select-Object -First <lines>').`;
418
+ `The file has been automatically indexed into Context Mode. ` +
419
+ `Query it with 'ctx_search(queries: [...], path: "${targetPath}")' or limit output to only needed lines (<= ${maxLineRange} lines, e.g. -Head <lines> or '| Select-Object -First <lines>').`;
419
420
  } else {
420
421
  reason =
421
422
  `[context-mode protection] Command attempts an un-paged dump of '${cleanTarget}' (${formatBytes(stat.size)}), ` +
422
423
  `exceeding the active ${formatBytes(maxReadBytes)} context limit. ` +
423
- `Please use 'mcp_context-mode_ctx_execute' or limit output to only needed lines (<= ${maxLineRange} lines, e.g. -Head <lines> or '| Select-Object -First <lines>').`;
424
+ `Please use 'ctx_execute' or limit output to only needed lines (<= ${maxLineRange} lines, e.g. -Head <lines> or '| Select-Object -First <lines>').`;
424
425
  }
425
426
 
426
427
  return {
427
428
  shouldDeny: true,
428
429
  reason,
429
430
  size: stat.size,
430
- targetPath: sourceId
431
+ targetPath
431
432
  };
432
433
  }
433
434
 
@@ -441,7 +442,7 @@ export function inspectCommand({ commandLine, cwd, sessionId }) {
441
442
  shouldDeny: true,
442
443
  reason:
443
444
  `[context-mode protection] Command matches an un-paged file dump ('${rawTarget}') that could flood the context window. ` +
444
- `Please use 'mcp_context-mode_ctx_execute' or limit output to only needed lines (<= ${maxLineRange} lines, e.g. '| Select-Object -First <lines>' or '| head -n <lines>').`,
445
+ `Please use 'ctx_execute' or limit output to only needed lines (<= ${maxLineRange} lines, e.g. '| Select-Object -First <lines>' or '| head -n <lines>').`,
445
446
  size: 32768,
446
447
  targetPath: cleanTarget || rawTarget
447
448
  };
@@ -511,7 +512,7 @@ async function main() {
511
512
  if (isLargeFile && isWideRange) {
512
513
  const lineInstruction = maxLineRange > 0 ? ` or read only the needed lines with StartLine/EndLine (<= ${maxLineRange} lines).` : "";
513
514
  const maxAutoIndexBytes = getMaxAutoIndexBytes(sessionId);
514
- const sourceId = resolveFileSourceId(absPath, cwd) || filePath;
515
+ const targetPath = resolveFilePath(absPath, cwd) || filePath;
515
516
 
516
517
  let isAutoIndexed = false;
517
518
  if (maxAutoIndexBytes > 0 && stat.size <= maxAutoIndexBytes) {
@@ -523,9 +524,10 @@ async function main() {
523
524
  worktree: cwd,
524
525
  agent: agentName,
525
526
  kind: "file",
526
- label: sourceId,
527
- sourceId,
528
- content
527
+ label: targetPath,
528
+ path: targetPath,
529
+ content,
530
+ mtime: Math.round(stat.mtimeMs)
529
531
  });
530
532
  store.close();
531
533
  isAutoIndexed = true;
@@ -535,17 +537,17 @@ async function main() {
535
537
  let reason = "";
536
538
  if (isAutoIndexed) {
537
539
  reason =
538
- `[context-mode protection: auto-indexed] File '${sourceId}' (${formatBytes(stat.size)}) ` +
540
+ `[context-mode protection: auto-indexed] File '${targetPath}' (${formatBytes(stat.size)}) ` +
539
541
  `exceeded the active ${formatBytes(maxReadBytes)} context limit. ` +
540
- `The file has been automatically indexed into Context Mode as source '${sourceId}'. ` +
541
- `Query it immediately using 'mcp_context-mode_ctx_search(queries: [...], sourceId: "${sourceId}")'${lineInstruction}`;
542
+ `The file has been automatically indexed into Context Mode. ` +
543
+ `Query it immediately using 'ctx_search(queries: [...], path: "${targetPath}")'${lineInstruction}`;
542
544
  } else {
543
545
  const ceilingNote = maxAutoIndexBytes > 0 && stat.size > maxAutoIndexBytes
544
546
  ? ` and the ${formatBytes(maxAutoIndexBytes)} auto-indexing ceiling`
545
547
  : "";
546
548
  reason =
547
549
  `[context-mode protection] File is ${formatBytes(stat.size)}, exceeding the active ${formatBytes(maxReadBytes)} context limit${ceilingNote}. ` +
548
- `Please use 'mcp_context-mode_ctx_index(path: "${filePath}")' or 'mcp_context-mode_ctx_execute'${lineInstruction}`;
550
+ `Please use 'ctx_execute'${lineInstruction}`;
549
551
  }
550
552
 
551
553
  // Record interception event in SQLite store so dashboard telemetry updates immediately
@@ -554,7 +556,7 @@ async function main() {
554
556
  agent: agentName,
555
557
  cwd,
556
558
  toolName,
557
- path: sourceId,
559
+ path: targetPath,
558
560
  size: stat.size,
559
561
  reason
560
562
  });
package/lib/store.js CHANGED
@@ -88,8 +88,8 @@ export function formatExemptSummary({ activeCats = [], customs = [] } = {}) {
88
88
  /** Default max file size (50 MB) automatically indexed on cutoff block */
89
89
  export const DEFAULT_MAX_AUTO_INDEX_BYTES = 50 * 1024 * 1024; // 52,428,800 bytes
90
90
 
91
- /** Resolve intuitive file sourceId: workspace-relative when inside project, normalized absolute when outside */
92
- export function resolveFileSourceId(filePath, cwd = process.cwd()) {
91
+ /** Resolve intuitive file path: workspace-relative when inside project, normalized absolute when outside */
92
+ export function resolveFilePath(filePath, cwd = process.cwd()) {
93
93
  if (!filePath) return null;
94
94
  const absPath = path.isAbsolute(filePath) ? path.normalize(filePath) : path.resolve(cwd, filePath);
95
95
  const normCwd = path.normalize(cwd);
@@ -101,6 +101,8 @@ export function resolveFileSourceId(filePath, cwd = process.cwd()) {
101
101
  return absPath.replace(/\\/g, "/");
102
102
  }
103
103
 
104
+ export const resolveFileSourceId = resolveFilePath;
105
+
104
106
  /** Default path to context database (~/.context-mode/context.db) */
105
107
  export function getDefaultDbPath() {
106
108
  if (process.env.CONTEXT_MODE_DB_PATH && process.env.CONTEXT_MODE_DB_PATH.trim()) {
@@ -137,7 +139,6 @@ export class ContextModeStore {
137
139
  this.dbPath = getDefaultDbPath();
138
140
  }
139
141
  this.db = null;
140
- this.sourceCounter = 0;
141
142
  }
142
143
 
143
144
  /** Open or initialize SQLite database */
@@ -182,7 +183,7 @@ export class ContextModeStore {
182
183
  );
183
184
 
184
185
  CREATE TABLE IF NOT EXISTS sources (
185
- id TEXT PRIMARY KEY,
186
+ path TEXT PRIMARY KEY,
186
187
  session_id TEXT NOT NULL,
187
188
  worktree TEXT NOT NULL,
188
189
  agent TEXT NOT NULL,
@@ -192,7 +193,8 @@ export class ContextModeStore {
192
193
  chunk_count INTEGER NOT NULL DEFAULT 0,
193
194
  created_ts INTEGER NOT NULL,
194
195
  created_at TEXT NOT NULL,
195
- accessed_ts INTEGER NOT NULL
196
+ accessed_ts INTEGER NOT NULL,
197
+ mtime INTEGER DEFAULT 0
196
198
  );
197
199
 
198
200
  CREATE INDEX IF NOT EXISTS idx_sources_session ON sources(session_id);
@@ -225,7 +227,7 @@ export class ContextModeStore {
225
227
  // Virtual FTS5 tables
226
228
  this.db.exec(`
227
229
  CREATE VIRTUAL TABLE IF NOT EXISTS chunks USING fts5(
228
- source_id UNINDEXED,
230
+ path UNINDEXED,
229
231
  session_id UNINDEXED,
230
232
  worktree UNINDEXED,
231
233
  agent UNINDEXED,
@@ -236,7 +238,7 @@ export class ContextModeStore {
236
238
  );
237
239
 
238
240
  CREATE VIRTUAL TABLE IF NOT EXISTS chunks_tri USING fts5(
239
- source_id UNINDEXED,
241
+ path UNINDEXED,
240
242
  session_id UNINDEXED,
241
243
  ord UNINDEXED,
242
244
  body,
@@ -244,9 +246,47 @@ export class ContextModeStore {
244
246
  );
245
247
  `);
246
248
 
249
+ // Schema migration check: upgrade existing v2 databases to v3
250
+ try {
251
+ const sourceCols = this.db.prepare("PRAGMA table_info(sources)").all().map((c) => c.name);
252
+ if (sourceCols.includes("id") && !sourceCols.includes("path")) {
253
+ this.db.exec("ALTER TABLE sources RENAME COLUMN id TO path;");
254
+ this.db.exec("DROP TABLE IF EXISTS chunks;");
255
+ this.db.exec("DROP TABLE IF EXISTS chunks_tri;");
256
+ this.db.exec(`
257
+ CREATE VIRTUAL TABLE IF NOT EXISTS chunks USING fts5(
258
+ path UNINDEXED,
259
+ session_id UNINDEXED,
260
+ worktree UNINDEXED,
261
+ agent UNINDEXED,
262
+ ord UNINDEXED,
263
+ body,
264
+ title,
265
+ tokenize = 'porter unicode61 remove_diacritics 2'
266
+ );
267
+
268
+ CREATE VIRTUAL TABLE IF NOT EXISTS chunks_tri USING fts5(
269
+ path UNINDEXED,
270
+ session_id UNINDEXED,
271
+ ord UNINDEXED,
272
+ body,
273
+ tokenize = 'trigram'
274
+ );
275
+ `);
276
+ this.db.exec("DELETE FROM sources;");
277
+ }
278
+ if (!sourceCols.includes("mtime")) {
279
+ this.db.exec("ALTER TABLE sources ADD COLUMN mtime INTEGER DEFAULT 0;");
280
+ }
281
+ } catch {
282
+ // Best-effort migration
283
+ }
284
+
247
285
  const versionRow = this.db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
248
286
  if (!versionRow) {
249
- this.db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', '2')").run();
287
+ this.db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', '3')").run();
288
+ } else {
289
+ this.db.prepare("UPDATE meta SET value = '3' WHERE key = 'schema_version'").run();
250
290
  }
251
291
  }
252
292
 
@@ -280,17 +320,27 @@ export class ContextModeStore {
280
320
  }
281
321
 
282
322
  /** Index a text, file output, or tool response into SQLite FTS5 */
283
- indexContent({ sessionId, worktree, agent, kind, label, content, sourceId }) {
323
+ indexContent({
324
+ sessionId = null,
325
+ worktree = null,
326
+ agent = "antigravity",
327
+ kind = "content",
328
+ label = null,
329
+ content,
330
+ path: filePath = null,
331
+ sourceId = null,
332
+ mtime = 0
333
+ }) {
284
334
  this.open();
285
335
  const sid = sessionId || "default";
286
336
  const wt = worktree || process.cwd();
287
337
  const ag = agent || "antigravity";
288
338
  const k = kind || "content";
289
- const lbl = label || "untitled";
290
339
  const rawText = typeof content === "string" ? content : String(content || "");
291
340
  const totalBytes = Buffer.byteLength(rawText, "utf8");
292
341
 
293
- const id = sourceId || `s_${Date.now()}_${(++this.sourceCounter).toString(36)}`;
342
+ const targetPath = filePath || sourceId || label || "output";
343
+ const lbl = label || targetPath;
294
344
  const now = Date.now();
295
345
  const isoDate = new Date(now).toISOString();
296
346
 
@@ -299,36 +349,36 @@ export class ContextModeStore {
299
349
 
300
350
  const insertSource = this.db.prepare(`
301
351
  INSERT OR REPLACE INTO sources (
302
- id, session_id, worktree, agent, kind, label, bytes_total, chunk_count, created_ts, created_at, accessed_ts
303
- ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
352
+ path, session_id, worktree, agent, kind, label, bytes_total, chunk_count, created_ts, created_at, accessed_ts, mtime
353
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
304
354
  `);
305
355
 
306
356
  const insertChunk = this.db.prepare(`
307
- INSERT INTO chunks (source_id, session_id, worktree, agent, ord, body, title)
357
+ INSERT INTO chunks (path, session_id, worktree, agent, ord, body, title)
308
358
  VALUES (?, ?, ?, ?, ?, ?, ?)
309
359
  `);
310
360
 
311
361
  const insertChunkTri = this.db.prepare(`
312
- INSERT INTO chunks_tri (source_id, session_id, ord, body)
362
+ INSERT INTO chunks_tri (path, session_id, ord, body)
313
363
  VALUES (?, ?, ?, ?)
314
364
  `);
315
365
 
316
- insertSource.run(id, sid, wt, ag, k, lbl, totalBytes, chunkCount, now, isoDate, now);
366
+ insertSource.run(targetPath, sid, wt, ag, k, lbl, totalBytes, chunkCount, now, isoDate, now, mtime || 0);
317
367
 
318
- // Clean up any existing chunks for this sourceId to ensure idempotent re-indexing
319
- this.db.prepare("DELETE FROM chunks WHERE source_id = ?").run(id);
320
- this.db.prepare("DELETE FROM chunks_tri WHERE source_id = ?").run(id);
368
+ // Clean up any existing chunks for this path to ensure idempotent re-indexing
369
+ this.db.prepare("DELETE FROM chunks WHERE path = ?").run(targetPath);
370
+ this.db.prepare("DELETE FROM chunks_tri WHERE path = ?").run(targetPath);
321
371
 
322
372
  for (let ord = 0; ord < chunkCount; ord++) {
323
373
  const chunkText = chunks[ord];
324
- insertChunk.run(id, sid, wt, ag, ord, chunkText, lbl);
325
- insertChunkTri.run(id, sid, ord, chunkText);
374
+ insertChunk.run(targetPath, sid, wt, ag, ord, chunkText, lbl);
375
+ insertChunkTri.run(targetPath, sid, ord, chunkText);
326
376
  }
327
377
 
328
378
  this.pruneStaleSources();
329
379
 
330
380
  return {
331
- sourceId: id,
381
+ path: targetPath,
332
382
  bytesTotal: totalBytes,
333
383
  chunkCount,
334
384
  label: lbl,
@@ -336,13 +386,147 @@ export class ContextModeStore {
336
386
  };
337
387
  }
338
388
 
389
+ /**
390
+ * Ensures a file, directory, or URL is indexed and fresh in SQLite based on file mtime.
391
+ * - If URL: indexes content if not already present.
392
+ * - If File: checks mtime & size; if unindexed or modified, re-indexes Just-In-Time.
393
+ * - If Directory: scans non-exempt files, indexes any unindexed or modified files.
394
+ */
395
+ ensurePathIndexed(targetPath, { cwd = process.cwd(), sessionId = null, agent = "antigravity" } = {}) {
396
+ if (!targetPath || typeof targetPath !== "string") return null;
397
+ this.open();
398
+
399
+ // 1. Remote URL
400
+ if (/^https?:\/\//i.test(targetPath)) {
401
+ const existing = this.db.prepare("SELECT path FROM sources WHERE path = ?").get(targetPath);
402
+ return { path: targetPath, isDir: false, isUrl: true, exists: Boolean(existing) };
403
+ }
404
+
405
+ // 2. Local File or Directory
406
+ const normCwd = cwd || process.cwd();
407
+ const absPath = path.isAbsolute(targetPath) ? path.normalize(targetPath) : path.resolve(normCwd, targetPath);
408
+ if (!fs.existsSync(absPath)) {
409
+ return { path: targetPath, isDir: false, exists: false };
410
+ }
411
+
412
+ let stat;
413
+ try {
414
+ stat = fs.statSync(absPath);
415
+ } catch {
416
+ return { path: targetPath, isDir: false, exists: false };
417
+ }
418
+
419
+ // 2a. Single File
420
+ if (stat.isFile()) {
421
+ const canonicalPath = this.resolveFilePath(absPath, normCwd);
422
+ const currentMtime = Math.round(stat.mtimeMs);
423
+
424
+ const existing = this.db.prepare("SELECT path, mtime, bytes_total FROM sources WHERE path = ?").get(canonicalPath);
425
+ if (existing && existing.mtime === currentMtime && existing.bytes_total === stat.size) {
426
+ return { path: canonicalPath, isDir: false, exists: true, wasReindexed: false };
427
+ }
428
+
429
+ try {
430
+ const content = fs.readFileSync(absPath, "utf8");
431
+ this.indexContent({
432
+ sessionId,
433
+ worktree: normCwd,
434
+ agent,
435
+ kind: "file",
436
+ label: canonicalPath,
437
+ path: canonicalPath,
438
+ content,
439
+ mtime: currentMtime
440
+ });
441
+ return { path: canonicalPath, isDir: false, exists: true, wasReindexed: true };
442
+ } catch {
443
+ return { path: canonicalPath, isDir: false, exists: true, wasReindexed: false };
444
+ }
445
+ }
446
+
447
+ // 2b. Directory
448
+ if (stat.isDirectory()) {
449
+ let canonicalDir = this.resolveFilePath(absPath, normCwd);
450
+ if (!canonicalDir.endsWith("/")) canonicalDir += "/";
451
+
452
+ const maxBytes = this.getMaxAutoIndexBytes(sessionId);
453
+ const exemptExts = this.getExemptExtensions(sessionId);
454
+ const files = [];
455
+
456
+ const scan = (dir, depth = 0) => {
457
+ if (depth > 5) return;
458
+ let entries = [];
459
+ try {
460
+ entries = fs.readdirSync(dir, { withFileTypes: true });
461
+ } catch {
462
+ return;
463
+ }
464
+ for (const ent of entries) {
465
+ if (ent.name.startsWith(".") || ent.name === "node_modules") continue;
466
+ const full = path.join(dir, ent.name);
467
+ if (ent.isDirectory()) {
468
+ scan(full, depth + 1);
469
+ } else if (ent.isFile()) {
470
+ const ext = path.extname(ent.name).toLowerCase();
471
+ if (exemptExts.includes(ext)) continue;
472
+ files.push(full);
473
+ }
474
+ }
475
+ };
476
+
477
+ scan(absPath);
478
+
479
+ for (const f of files) {
480
+ try {
481
+ const fStat = fs.statSync(f);
482
+ if (maxBytes > 0 && fStat.size > maxBytes) continue;
483
+ const fCanonical = this.resolveFilePath(f, normCwd);
484
+ const fMtime = Math.round(fStat.mtimeMs);
485
+ const exist = this.db.prepare("SELECT path, mtime, bytes_total FROM sources WHERE path = ?").get(fCanonical);
486
+ if (!exist || exist.mtime !== fMtime || exist.bytes_total !== fStat.size) {
487
+ const content = fs.readFileSync(f, "utf8");
488
+ this.indexContent({
489
+ sessionId,
490
+ worktree: normCwd,
491
+ agent,
492
+ kind: "file",
493
+ label: fCanonical,
494
+ path: fCanonical,
495
+ content,
496
+ mtime: fMtime
497
+ });
498
+ }
499
+ } catch {}
500
+ }
501
+
502
+ return { path: canonicalDir, isDir: true, exists: true };
503
+ }
504
+
505
+ return { path: targetPath, isDir: false, exists: false };
506
+ }
507
+
339
508
  /** Search indexed chunks using BM25 + Trigram Reciprocal Rank Fusion */
340
- search({ queries, sourceId, sessionId, worktree, scope = "session", limit = 5, offset = 0 }) {
509
+ search({ queries, path: searchPath, sourceId, sessionId, worktree, scope = "session", limit = 5, offset = 0, reverse = false }) {
341
510
  this.open();
342
511
  const queryList = Array.isArray(queries) ? queries : [queries];
343
512
  const maxHits = Math.min(Math.max(1, limit || 5), 20);
344
513
  const skipHits = Math.max(0, offset || 0);
345
514
 
515
+ const target = searchPath || sourceId || null;
516
+ let pathFilter = null;
517
+ let isDir = false;
518
+
519
+ if (target) {
520
+ const indexed = this.ensurePathIndexed(target, { cwd: worktree, sessionId });
521
+ if (indexed) {
522
+ pathFilter = indexed.path;
523
+ isDir = Boolean(indexed.isDir);
524
+ } else {
525
+ pathFilter = target;
526
+ isDir = target.endsWith("/");
527
+ }
528
+ }
529
+
346
530
  const scores = new Map();
347
531
 
348
532
  for (const q of queryList) {
@@ -353,15 +537,20 @@ export class ContextModeStore {
353
537
  // 1. Porter FTS5 with BM25 ranking
354
538
  if (porterQ) {
355
539
  let sql = `
356
- SELECT rowid, source_id, ord, body, title, session_id, worktree, bm25(chunks) AS rank
540
+ SELECT rowid, path, ord, body, title, session_id, worktree, bm25(chunks) AS rank
357
541
  FROM chunks
358
542
  WHERE chunks MATCH ?
359
543
  `;
360
544
  const params = [porterQ];
361
545
 
362
- if (sourceId) {
363
- sql += " AND source_id = ?";
364
- params.push(sourceId);
546
+ if (pathFilter) {
547
+ if (isDir) {
548
+ sql += " AND path LIKE ?";
549
+ params.push(`${pathFilter}%`);
550
+ } else {
551
+ sql += " AND path = ?";
552
+ params.push(pathFilter);
553
+ }
365
554
  } else if (scope === "session" && sessionId) {
366
555
  sql += " AND session_id = ?";
367
556
  params.push(sessionId);
@@ -375,7 +564,7 @@ export class ContextModeStore {
375
564
  try {
376
565
  const rows = this.db.prepare(sql).all(...params);
377
566
  rows.forEach((row, rankIdx) => {
378
- const key = `${row.source_id}:${row.ord}`;
567
+ const key = `${row.path}:${row.ord}`;
379
568
  const rrf = 1.0 / (RRF_K + rankIdx + 1);
380
569
  const existing = scores.get(key);
381
570
  if (existing) {
@@ -384,7 +573,7 @@ export class ContextModeStore {
384
573
  } else {
385
574
  scores.set(key, {
386
575
  rowid: row.rowid,
387
- sourceId: row.source_id,
576
+ path: row.path,
388
577
  ord: row.ord,
389
578
  body: row.body,
390
579
  title: row.title,
@@ -403,15 +592,20 @@ export class ContextModeStore {
403
592
  // 2. Trigram FTS5
404
593
  if (trigramQ) {
405
594
  let sqlTri = `
406
- SELECT rowid, source_id, ord, body, session_id
595
+ SELECT rowid, path, ord, body, session_id
407
596
  FROM chunks_tri
408
597
  WHERE chunks_tri MATCH ?
409
598
  `;
410
599
  const paramsTri = [trigramQ];
411
600
 
412
- if (sourceId) {
413
- sqlTri += " AND source_id = ?";
414
- paramsTri.push(sourceId);
601
+ if (pathFilter) {
602
+ if (isDir) {
603
+ sqlTri += " AND path LIKE ?";
604
+ paramsTri.push(`${pathFilter}%`);
605
+ } else {
606
+ sqlTri += " AND path = ?";
607
+ paramsTri.push(pathFilter);
608
+ }
415
609
  } else if (scope === "session" && sessionId) {
416
610
  sqlTri += " AND session_id = ?";
417
611
  paramsTri.push(sessionId);
@@ -422,7 +616,7 @@ export class ContextModeStore {
422
616
  try {
423
617
  const rowsTri = this.db.prepare(sqlTri).all(...paramsTri);
424
618
  rowsTri.forEach((row, rankIdx) => {
425
- const key = `${row.source_id}:${row.ord}`;
619
+ const key = `${row.path}:${row.ord}`;
426
620
  const rrf = 1.0 / (RRF_K + rankIdx + 1);
427
621
  const existing = scores.get(key);
428
622
  if (existing) {
@@ -431,7 +625,7 @@ export class ContextModeStore {
431
625
  } else {
432
626
  scores.set(key, {
433
627
  rowid: row.rowid,
434
- sourceId: row.source_id,
628
+ path: row.path,
435
629
  ord: row.ord,
436
630
  body: row.body,
437
631
  title: "",
@@ -448,18 +642,44 @@ export class ContextModeStore {
448
642
  }
449
643
  }
450
644
 
451
- const allHits = Array.from(scores.values()).sort((a, b) => b.rrfScore - a.rrfScore);
645
+ const allHits = Array.from(scores.values());
646
+ if (reverse) {
647
+ // Prioritize tail chunks (newest lines / latest events in logs) first
648
+ allHits.sort((a, b) => {
649
+ if (b.ord !== a.ord) {
650
+ return b.ord - a.ord; // Highest ord (tail of file) first
651
+ }
652
+ return b.rrfScore - a.rrfScore;
653
+ });
654
+ } else {
655
+ allHits.sort((a, b) => b.rrfScore - a.rrfScore);
656
+ }
657
+
452
658
  const paginated = allHits.slice(skipHits, skipHits + maxHits);
453
659
 
454
660
  const formatted = paginated.map((hit) => {
455
661
  let snippet = hit.body;
456
662
  if (Buffer.byteLength(snippet, "utf8") > SNIPPET_MAX_BYTES) {
457
- snippet = snippet.slice(0, SNIPPET_MAX_BYTES) + "\n... [truncated, use ctx_search or ctx_index to inspect full]";
663
+ let matchPos = -1;
664
+ const lowerBody = hit.body.toLowerCase();
665
+ for (const q of queryList) {
666
+ if (!q || typeof q !== "string") continue;
667
+ const pos = lowerBody.indexOf(q.toLowerCase());
668
+ if (pos !== -1 && (matchPos === -1 || pos < matchPos)) {
669
+ matchPos = pos;
670
+ }
671
+ }
672
+ if (matchPos > 100) {
673
+ const start = Math.max(0, matchPos - 60);
674
+ snippet = "... " + hit.body.slice(start, start + SNIPPET_MAX_BYTES) + "\n... [truncated]";
675
+ } else {
676
+ snippet = hit.body.slice(0, SNIPPET_MAX_BYTES) + "\n... [truncated]";
677
+ }
458
678
  }
459
679
  return {
460
- sourceId: hit.sourceId,
680
+ path: hit.path,
461
681
  ord: hit.ord,
462
- title: hit.title || hit.sourceId,
682
+ title: hit.title || hit.path,
463
683
  rrfScore: parseFloat(hit.rrfScore.toFixed(5)),
464
684
  matches: hit.matches.length,
465
685
  snippet
@@ -467,6 +687,9 @@ export class ContextModeStore {
467
687
  });
468
688
 
469
689
  return {
690
+ queries: queryList,
691
+ path: pathFilter || null,
692
+ reverse: Boolean(reverse),
470
693
  hits: formatted,
471
694
  totalMatches: allHits.length,
472
695
  returned: formatted.length,
@@ -552,7 +775,7 @@ export class ContextModeStore {
552
775
  } else if (sid === "app" && sinceIso) {
553
776
  sources = this.db
554
777
  .prepare(`
555
- SELECT id, label, kind, bytes_total, chunk_count, created_at
778
+ SELECT path, label, kind, bytes_total, chunk_count, created_at
556
779
  FROM sources
557
780
  WHERE created_at >= ? OR created_ts >= ?
558
781
  ORDER BY created_ts DESC
@@ -571,7 +794,7 @@ export class ContextModeStore {
571
794
  } else {
572
795
  sources = this.db
573
796
  .prepare(`
574
- SELECT id, label, kind, bytes_total, chunk_count, created_at
797
+ SELECT path, label, kind, bytes_total, chunk_count, created_at
575
798
  FROM sources
576
799
  WHERE session_id = ?
577
800
  ORDER BY created_ts DESC
@@ -603,13 +826,13 @@ export class ContextModeStore {
603
826
  return row || null;
604
827
  }
605
828
 
606
- /** Retrieve all chunks for a specific source */
607
- getSourceChunks(sourceId) {
829
+ /** Retrieve all chunks for a specific path */
830
+ getSourceChunks(targetPath) {
608
831
  this.open();
609
- if (!sourceId) return [];
832
+ if (!targetPath) return [];
610
833
  return this.db
611
- .prepare("SELECT ord, body, title FROM chunks WHERE source_id = ? ORDER BY ord ASC")
612
- .all(sourceId);
834
+ .prepare("SELECT ord, body, title FROM chunks WHERE path = ? ORDER BY ord ASC")
835
+ .all(targetPath);
613
836
  }
614
837
 
615
838
  /** Calculate token savings & statistics */
@@ -649,7 +872,7 @@ export class ContextModeStore {
649
872
  SELECT 1 FROM events e
650
873
  WHERE (
651
874
  (e.tool = 'ctx_index' AND e.sandbox_bytes = s.bytes_total)
652
- OR e.path = s.id
875
+ OR e.path = s.path
653
876
  OR e.path = s.label
654
877
  )
655
878
  )
@@ -683,7 +906,7 @@ export class ContextModeStore {
683
906
  SELECT 1 FROM events e
684
907
  WHERE (
685
908
  (e.tool = 'ctx_index' AND e.sandbox_bytes = s.bytes_total)
686
- OR e.path = s.id
909
+ OR e.path = s.path
687
910
  OR e.path = s.label
688
911
  )
689
912
  )
@@ -718,7 +941,7 @@ export class ContextModeStore {
718
941
  WHERE e.session_id = s.session_id
719
942
  AND (
720
943
  (e.tool = 'ctx_index' AND e.sandbox_bytes = s.bytes_total)
721
- OR e.path = s.id
944
+ OR e.path = s.path
722
945
  OR e.path = s.label
723
946
  )
724
947
  )
@@ -761,14 +984,14 @@ export class ContextModeStore {
761
984
 
762
985
  if (scope === "app" && sinceTs) {
763
986
  const sinceIso = new Date(sinceTs).toISOString();
764
- const sourceIds = this.db.prepare("SELECT id FROM sources WHERE created_at >= ? OR created_ts >= ?").all(sinceIso, sinceTs).map((r) => r.id);
765
- for (const sId of sourceIds) {
766
- this.db.prepare("DELETE FROM chunks WHERE source_id = ?").run(sId);
767
- this.db.prepare("DELETE FROM chunks_tri WHERE source_id = ?").run(sId);
987
+ const paths = this.db.prepare("SELECT path FROM sources WHERE created_at >= ? OR created_ts >= ?").all(sinceIso, sinceTs).map((r) => r.path);
988
+ for (const p of paths) {
989
+ this.db.prepare("DELETE FROM chunks WHERE path = ?").run(p);
990
+ this.db.prepare("DELETE FROM chunks_tri WHERE path = ?").run(p);
768
991
  }
769
992
  this.db.prepare("DELETE FROM sources WHERE created_at >= ? OR created_ts >= ?").run(sinceIso, sinceTs);
770
993
  this.db.prepare("DELETE FROM events WHERE created_at >= ?").run(sinceIso);
771
- return { ok: true, purged: "app", count: sourceIds.length };
994
+ return { ok: true, purged: "app", count: paths.length };
772
995
  }
773
996
 
774
997
  if (scope === "worktree" && worktree) {
@@ -949,9 +1172,13 @@ export class ContextModeStore {
949
1172
  return numVal;
950
1173
  }
951
1174
 
952
- /** Resolve intuitive file sourceId: workspace-relative when inside project, normalized absolute when outside */
1175
+ /** Resolve intuitive file path: workspace-relative when inside project, normalized absolute when outside */
1176
+ resolveFilePath(filePath, cwd = process.cwd()) {
1177
+ return resolveFilePath(filePath, cwd);
1178
+ }
1179
+
953
1180
  resolveFileSourceId(filePath, cwd = process.cwd()) {
954
- return resolveFileSourceId(filePath, cwd);
1181
+ return this.resolveFilePath(filePath, cwd);
955
1182
  }
956
1183
 
957
1184
  /** Internal helper to recompute and save the combined exempt_ext list */
@@ -1250,9 +1477,9 @@ export class ContextModeStore {
1250
1477
  // 1. Prune sources exceeding per-session cap
1251
1478
  const excessSessionSources = this.db
1252
1479
  .prepare(`
1253
- SELECT id FROM sources
1254
- WHERE id NOT IN (
1255
- SELECT id FROM sources s2
1480
+ SELECT path FROM sources
1481
+ WHERE path NOT IN (
1482
+ SELECT path FROM sources s2
1256
1483
  WHERE s2.session_id = sources.session_id
1257
1484
  ORDER BY s2.created_ts DESC
1258
1485
  LIMIT ?
@@ -1261,11 +1488,11 @@ export class ContextModeStore {
1261
1488
  .all(maxSourcesPerSession);
1262
1489
 
1263
1490
  if (excessSessionSources.length > 0) {
1264
- const ids = excessSessionSources.map((r) => r.id);
1265
- const placeholders = ids.map(() => "?").join(",");
1266
- this.db.prepare(`DELETE FROM chunks WHERE source_id IN (${placeholders})`).run(...ids);
1267
- this.db.prepare(`DELETE FROM chunks_tri WHERE source_id IN (${placeholders})`).run(...ids);
1268
- this.db.prepare(`DELETE FROM sources WHERE id IN (${placeholders})`).run(...ids);
1491
+ const paths = excessSessionSources.map((r) => r.path);
1492
+ const placeholders = paths.map(() => "?").join(",");
1493
+ this.db.prepare(`DELETE FROM chunks WHERE path IN (${placeholders})`).run(...paths);
1494
+ this.db.prepare(`DELETE FROM chunks_tri WHERE path IN (${placeholders})`).run(...paths);
1495
+ this.db.prepare(`DELETE FROM sources WHERE path IN (${placeholders})`).run(...paths);
1269
1496
  }
1270
1497
 
1271
1498
  // 2. Prune global total sources if over cap
@@ -1273,15 +1500,15 @@ export class ContextModeStore {
1273
1500
  if (totalCountRow && totalCountRow.count > maxTotalSources) {
1274
1501
  const deleteCount = totalCountRow.count - maxTotalSources;
1275
1502
  const oldest = this.db
1276
- .prepare("SELECT id FROM sources ORDER BY created_ts ASC LIMIT ?")
1503
+ .prepare("SELECT path FROM sources ORDER BY created_ts ASC LIMIT ?")
1277
1504
  .all(deleteCount);
1278
1505
 
1279
1506
  if (oldest.length > 0) {
1280
- const ids = oldest.map((r) => r.id);
1281
- const placeholders = ids.map(() => "?").join(",");
1282
- this.db.prepare(`DELETE FROM chunks WHERE source_id IN (${placeholders})`).run(...ids);
1283
- this.db.prepare(`DELETE FROM chunks_tri WHERE source_id IN (${placeholders})`).run(...ids);
1284
- this.db.prepare(`DELETE FROM sources WHERE id IN (${placeholders})`).run(...ids);
1507
+ const paths = oldest.map((r) => r.path);
1508
+ const placeholders = paths.map(() => "?").join(",");
1509
+ this.db.prepare(`DELETE FROM chunks WHERE path IN (${placeholders})`).run(...paths);
1510
+ this.db.prepare(`DELETE FROM chunks_tri WHERE path IN (${placeholders})`).run(...paths);
1511
+ this.db.prepare(`DELETE FROM sources WHERE path IN (${placeholders})`).run(...paths);
1285
1512
  }
1286
1513
  }
1287
1514
  } catch {
package/lib/tools.js CHANGED
@@ -3,7 +3,7 @@ import path from "node:path";
3
3
  import http from "node:http";
4
4
  import https from "node:https";
5
5
  import { executeCode, runProcess, OUTPUT_CAP } from "./executor.js";
6
- import { SNIPPET_MAX_BYTES, resolveFileSourceId } from "./store.js";
6
+ import { SNIPPET_MAX_BYTES, resolveFilePath } from "./store.js";
7
7
 
8
8
  const EXEC_PREVIEW_BYTES = 4096;
9
9
 
@@ -76,17 +76,19 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
76
76
  const fullOutput = (result.stdout ? result.stdout : "") + (result.stderr ? "\n" + result.stderr : "");
77
77
  const fullBytes = Buffer.byteLength(fullOutput, "utf8");
78
78
 
79
- let sourceId = null;
79
+ let outputPath = null;
80
80
  if (fullBytes > 0) {
81
+ outputPath = file ? `${file}.output.log` : `ctx_execute_${Date.now()}.log`;
81
82
  const indexed = store.indexContent({
82
83
  sessionId,
83
84
  worktree: cwd,
84
85
  agent: "antigravity",
85
86
  kind: "execution",
86
87
  label: intent || `${language} script (${elapsedMs}ms)`,
88
+ path: outputPath,
87
89
  content: fullOutput
88
90
  });
89
- sourceId = indexed.sourceId;
91
+ outputPath = indexed.path;
90
92
  }
91
93
 
92
94
  const cutoffBytes = store.getCutoff(sessionId);
@@ -109,7 +111,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
109
111
  kind: "execution",
110
112
  tool: "ctx_execute",
111
113
  key: language,
112
- path: file || null,
114
+ path: file || outputPath || null,
113
115
  ok: result.ok ? 1 : 0,
114
116
  exitCode: result.exitCode,
115
117
  bytes: fullBytes,
@@ -120,7 +122,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
120
122
 
121
123
  let responseText = returnedText;
122
124
  if (truncated) {
123
- responseText += `\n\n... [${formatBytes(fullBytes - returnedBytes)} truncated to protect context window; full output indexed into ${sourceId}. Use ctx_search(queries: [...], sourceId: "${sourceId}") to query it]`;
125
+ responseText += `\n\n... [${formatBytes(fullBytes - returnedBytes)} truncated to protect context window; full output indexed into ${outputPath}. Use ctx_search(queries: [...], path: "${outputPath}") to query it]`;
124
126
  }
125
127
 
126
128
  return {
@@ -129,7 +131,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
129
131
  elapsedMs,
130
132
  language,
131
133
  intent: intent || null,
132
- sourceId,
134
+ path: outputPath,
133
135
  rawBytes: fullBytes,
134
136
  returnedBytes,
135
137
  output: responseText
@@ -153,12 +155,14 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
153
155
  }
154
156
 
155
157
  const combined = outputs.join("\n");
158
+ const batchPath = `ctx_batch_${Date.now()}.log`;
156
159
  const indexed = store.indexContent({
157
160
  sessionId,
158
161
  worktree: cwd,
159
162
  agent: "antigravity",
160
163
  kind: "batch",
161
164
  label: `batch: ${cmdList.length} commands`,
165
+ path: batchPath,
162
166
  content: combined
163
167
  });
164
168
 
@@ -166,7 +170,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
166
170
  if (queries && queries.length > 0) {
167
171
  const searchRes = store.search({
168
172
  queries,
169
- sourceId: indexed.sourceId,
173
+ path: indexed.path,
170
174
  sessionId,
171
175
  limit: 10
172
176
  });
@@ -174,7 +178,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
174
178
  } else {
175
179
  returnedContent = combined.slice(0, EXEC_PREVIEW_BYTES);
176
180
  if (totalRawBytes > EXEC_PREVIEW_BYTES) {
177
- returnedContent += `\n\n... [truncated. Use ctx_search(queries: [...], sourceId: "${indexed.sourceId}") to search full batch output]`;
181
+ returnedContent += `\n\n... [truncated. Use ctx_search(queries: [...], path: "${indexed.path}") to search full batch output]`;
178
182
  }
179
183
  }
180
184
 
@@ -194,92 +198,66 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
194
198
 
195
199
  return {
196
200
  commandsRun: cmdList.length,
197
- sourceId: indexed.sourceId,
201
+ path: indexed.path,
198
202
  rawBytes: totalRawBytes,
199
203
  returnedBytes,
200
204
  content: returnedContent
201
205
  };
202
206
  },
203
207
 
204
- // 3. ctx_index
205
- async ctx_index({ path: filePath = "", url = "", content = "", label = "" } = {}) {
208
+ // 3. ctx_search (Just-In-Time auto-indexing for files, directories, and URLs)
209
+ async ctx_search({ queries = [], path: targetPath = null, scope = "session", limit = 5, offset = 0, reverse = false } = {}) {
206
210
  const cwd = getCwd();
207
211
  const sessionId = getSessionId();
208
- let rawText = content || "";
209
- let resolvedLabel = label;
210
-
211
- if (url) {
212
- resolvedLabel = resolvedLabel || url;
213
- rawText = await fetchUrlText(url);
214
- } else if (filePath) {
215
- resolvedLabel = resolvedLabel || filePath;
216
- const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
217
- if (!fs.existsSync(absPath)) {
218
- throw new Error(`File not found: ${filePath}`);
212
+ const effectivePath = targetPath || null;
213
+
214
+ if (effectivePath && /^https?:\/\//i.test(effectivePath)) {
215
+ try {
216
+ const rawText = await fetchUrlText(effectivePath);
217
+ store.indexContent({
218
+ sessionId,
219
+ worktree: cwd,
220
+ agent: "antigravity",
221
+ kind: "web",
222
+ label: effectivePath,
223
+ path: effectivePath,
224
+ content: rawText
225
+ });
226
+ } catch (err) {
227
+ throw new Error(`Failed to fetch URL for search: ${err.message}`);
219
228
  }
220
- rawText = fs.readFileSync(absPath, "utf8");
221
229
  }
222
230
 
223
- if (!rawText) {
224
- throw new Error("No content, file path, or url provided to index");
225
- }
226
-
227
- const fileSourceId = filePath ? resolveFileSourceId(filePath, cwd) : null;
228
-
229
- const indexed = store.indexContent({
231
+ const res = store.search({
232
+ queries,
233
+ path: effectivePath,
230
234
  sessionId,
231
235
  worktree: cwd,
232
- agent: "antigravity",
233
- kind: url ? "web" : filePath ? "file" : "text",
234
- label: resolvedLabel || fileSourceId || "manual_index",
235
- sourceId: fileSourceId || undefined,
236
- content: rawText
236
+ scope,
237
+ limit,
238
+ offset,
239
+ reverse: Boolean(reverse)
237
240
  });
238
241
 
239
- const returnObj = {
240
- sourceId: indexed.sourceId,
241
- label: indexed.label,
242
- bytesTotal: indexed.bytesTotal,
243
- chunkCount: indexed.chunkCount,
244
- message: `Indexed ${formatBytes(indexed.bytesTotal)} into ${indexed.chunkCount} chunks. Query with ctx_search.`
245
- };
246
-
247
- const returnedBytes = Buffer.byteLength(JSON.stringify(returnObj), "utf8");
248
-
242
+ const returnedBytes = Buffer.byteLength(JSON.stringify(res), "utf8");
249
243
  store.recordEvent({
250
244
  sessionId,
251
245
  worktree: cwd,
252
246
  agent: "antigravity",
253
- kind: "index",
254
- tool: "ctx_index",
255
- path: filePath || url || null,
247
+ kind: "search",
248
+ tool: "ctx_search",
249
+ path: res.path || effectivePath,
256
250
  ok: 1,
257
- bytes: indexed.bytesTotal,
258
- body: returnObj.message,
259
- sandboxBytes: indexed.bytesTotal,
251
+ bytes: returnedBytes,
252
+ body: `ctx_search: ${res.returned} hits`,
253
+ sandboxBytes: 0,
260
254
  returnedBytes
261
255
  });
262
256
 
263
- return returnObj;
264
- },
265
-
266
- // 4. ctx_search
267
- async ctx_search({ queries = [], sourceId = null, scope = "session", limit = 5, offset = 0 } = {}) {
268
- const cwd = getCwd();
269
- const sessionId = getSessionId();
270
-
271
- const res = store.search({
272
- queries,
273
- sourceId,
274
- sessionId,
275
- worktree: cwd,
276
- scope,
277
- limit,
278
- offset
279
- });
280
-
281
257
  return {
282
258
  queries,
259
+ path: res.path,
260
+ reverse: Boolean(reverse),
283
261
  totalMatches: res.totalMatches,
284
262
  returned: res.returned,
285
263
  offset: res.offset,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "antigravity-plugin-context-mode",
3
- "version": "1.4.0",
3
+ "version": "1.5.0",
4
4
  "description": "Native Antigravity plugin for context-mode: SQLite FTS5 indexing, sandboxed execution, and lifecycle hook protection against context window bloat",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/plugin.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "antigravity-plugin-context-mode",
3
3
  "displayName": "Context Mode",
4
4
  "description": "Context window protection for Antigravity: local SQLite FTS5 search, sandboxed execution, and lifecycle hook gating against token bloat.",
5
- "version": "1.4.0",
5
+ "version": "1.5.0",
6
6
  "author": "Phillip Webber <github@webbsense.com>",
7
7
  "repository": {
8
8
  "type": "git",
package/rules/AGENTS.md CHANGED
@@ -7,11 +7,12 @@ When `antigravity-plugin-context-mode` is active, agents MUST adhere to context
7
7
  - It is **NOT your LLM context window**. Your LLM context window is vastly larger. Do NOT assume your context window is 8 KB.
8
8
  - Files or command outputs within the active cutoff limit can always be read directly.
9
9
 
10
- 2. **Non-Exempt Text and Code Files & Automatic Indexing**:
11
- - For non-exempt text files (code, logs, json, yaml, etc.) that exceed the active cutoff:
12
- - **Automatic Indexing**: Intercepted file reads and unpaged dumps of files up to 50 MB are **automatically indexed** into Context Mode. The denial notice provides the intuitive file-path `sourceId` (e.g. `Logs/Editor.log`) so you can immediately search it via `ctx_search(queries: [...], sourceId: "...")` without needing to call `ctx_index` manually.
13
- - **Line Slices**: Or read only the lines needed with `StartLine` and `EndLine` (within the active line limit).
14
- - **Script Filtering**: Or inspect/filter with short scripts via `ctx_execute`.
10
+ 2. **Intra-File & Directory Searches (Prioritize `ctx_search`)**:
11
+ - **Always prioritize `ctx_search(queries: [...], path: "path/to/target")`** whenever you need to search for specific functions, symbols, error patterns, or text inside any file or directory.
12
+ - `ctx_search` automatically indexes and updates files Just-In-Time based on file modification timestamps—you do NOT need to read files into context first or run any manual indexing.
13
+ - **Log & Chronological Files**: When searching logs, traces, or events, pass `reverse: true` (e.g. `ctx_search(queries: ["error"], path: "Logs/app.log", reverse: true)`) to inspect the newest lines and most recent errors at the tail of the file first.
14
+ - **Line Slices**: Read files directly with `StartLine` and `EndLine` only when you already know the specific lines needed (within the active line limit).
15
+ - **Script Filtering**: Or inspect/filter with short scripts via `ctx_execute`.
15
16
 
16
17
  3. **Zero Raw Log Dumps**: Never run unbounded terminal commands (`cat`, `Get-Content`, `type`, unpaged `git log`, direct `curl`/`wget` to stdout). Pipe to limiters for only the specific lines needed (e.g. `| Select-Object -First <lines>` or `| head -n <lines>`) or run via `ctx_execute`.
17
18
 
package/server.js CHANGED
@@ -166,35 +166,29 @@ const TOOL_DEFINITIONS = [
166
166
  required: ["commands"]
167
167
  }
168
168
  },
169
- {
170
- name: "ctx_index",
171
- description: "Index a file, URL, or raw text into SQLite FTS5 for fast BM25/trigram searching.",
172
- inputSchema: {
173
- type: "object",
174
- properties: {
175
- path: { type: "string", description: "Path to local file to index" },
176
- url: { type: "string", description: "HTTP/HTTPS URL to fetch and index" },
177
- content: { type: "string", description: "Raw string content to index" },
178
- label: { type: "string", description: "Descriptive label for this source" }
179
- }
180
- }
181
- },
182
169
  {
183
170
  name: "ctx_search",
184
171
  description:
185
- "Search the local SQLite FTS5 database across indexed logs, tool outputs, and documentation using Reciprocal Rank Fusion (Porter BM25 + Trigram).",
172
+ "Search the local SQLite FTS5 database across indexed logs, files, tool outputs, and documentation using BM25 + Trigram RRF. If path is a file, directory, or URL, it is automatically indexed Just-In-Time if unindexed or modified.",
186
173
  inputSchema: {
187
174
  type: "object",
188
175
  properties: {
189
176
  queries: { type: "array", items: { type: "string" }, description: "Search queries or tokens to match" },
190
- sourceId: { type: "string", description: "Optional sourceId to restrict search" },
177
+ path: {
178
+ type: "string",
179
+ description: "Path to a file, directory, or URL to search (auto-indexed Just-In-Time if unindexed or changed). Omit to search active session."
180
+ },
191
181
  scope: {
192
182
  type: "string",
193
183
  enum: ["session", "worktree", "all"],
194
- description: "Search scope (default: session)"
184
+ description: "Search scope when path is omitted (default: session)"
195
185
  },
196
186
  limit: { type: "integer", description: "Max number of snippets to return (default 5)" },
197
- offset: { type: "integer", description: "Offset for pagination" }
187
+ offset: { type: "integer", description: "Offset for pagination" },
188
+ reverse: {
189
+ type: "boolean",
190
+ description: "Search in reverse order (tail-first), prioritizing the newest lines/entries at the end of log files (default: false)"
191
+ }
198
192
  },
199
193
  required: ["queries"]
200
194
  }
@@ -17,7 +17,7 @@ Context Mode enforces a single-operation read/command cutoff (default 8 KB, conf
17
17
  * **Tool-Level Read Cutoff**: This threshold applies strictly to individual `read_file` calls or terminal dump commands (`cat`, `Get-Content`, `type`) on non-exempt text/code files to protect against accidental bloat.
18
18
  * **NOT the LLM Context Window**: The model retains its full, large context window capacity. Do **not** confuse the tool-level read cutoff (e.g. 8 KB) with the model's context window.
19
19
  * **Dynamic Active Exemptions**: Active file category exemptions and custom extensions are dynamically loaded from SQLite and injected into your session by the `SessionStart` and `PreInvocation` hooks. Files matching active exemptions bypass cutoff protection. Use `ctx_stats` or `ctx_doctor` to check live exemptions at any time.
20
- * **Automatic Indexing on Interception**: When a non-exempt file read or unpaged command dump exceeds the active cutoff, Context Mode automatically indexes files up to 50 MB (configurable) into SQLite FTS5. The denial message returns the intuitive file-path `sourceId` (e.g. `Logs/Editor.log`), enabling you to immediately search it using `ctx_search(queries: [...], sourceId: "...")` without having to run `ctx_index` first.
20
+ * **Intra-File & Directory Searches (Prioritize `ctx_search`)**: Whenever you need to locate symbols, methods, config values, or error patterns in any file or directory, use `ctx_search(queries: [...], path: "path/to/target")`. If the file is unindexed or has been modified on disk, `ctx_search` automatically indexes or updates it on-demand before searching.
21
21
 
22
22
  ---
23
23
 
@@ -25,8 +25,8 @@ Context Mode enforces a single-operation read/command cutoff (default 8 KB, conf
25
25
 
26
26
  | Task | Traditional Tool (High Bloat) | Context Mode Solution (Zero Bloat) |
27
27
  | :--- | :--- | :--- |
28
+ | **Searching code, logs, or docs** | Full un-paged `read_file` | `ctx_search(queries: ["..."], path: "path/to/target")` (JIT auto-indexed) |
28
29
  | **Analyzing build or server logs** | `run_command("Get-Content Logs/Editor.log")` | `ctx_execute(code: "...", intent: "Find compile errors in Editor.log")` |
29
- | **Searching huge documentation or code** | Full un-paged `read_file` | `ctx_index(path: "...")` $\rightarrow$ `ctx_search(queries: ["..."])` |
30
30
  | **Processing API JSON responses** | Fetching and dumping 5,000 JSON items | `ctx_execute(language: "javascript", code: "fetch(...)")` |
31
31
  | **Running multi-command batches** | Running 10 commands in separate tool calls | `ctx_batch(commands: [...], queries: [...])` |
32
32
  | **Session recovery & token stats** | Re-reading entire past conversation | `ctx_resume()` / `ctx_stats()` |
@@ -46,25 +46,21 @@ Executes a short script in a local sandbox (Node.js, Python, PowerShell, or Shel
46
46
  }
47
47
  ```
48
48
 
49
- ### 2. `ctx_index`
50
- Indexes a local file, web URL, or raw string into SQLite FTS5 chunks:
51
- ```json
52
- {
53
- "path": "Documentation/Architecture.md",
54
- "label": "Architecture Guide"
55
- }
56
- ```
49
+ ### 2. `ctx_search` (On-Demand / JIT Search)
50
+ Queries indexed chunks using Reciprocal Rank Fusion (Porter BM25 stemming + Trigram matching). If `path` is specified (file, directory, or URL), Context Mode checks if the target is unindexed or modified, automatically indexes it Just-In-Time, and scopes the search.
51
+
52
+ For log files, pass `"reverse": true` to prioritize tail-first inspection (latest errors and timestamps first):
57
53
 
58
- ### 3. `ctx_search`
59
- Queries indexed chunks using Reciprocal Rank Fusion (Porter BM25 stemming + Trigram matching). Returns ranked snippets:
60
54
  ```json
61
55
  {
62
- "queries": ["NullReferenceException", "ShipMovementService"],
56
+ "queries": ["FATAL", "Exception"],
57
+ "path": "Logs/Editor.log",
58
+ "reverse": true,
63
59
  "limit": 5
64
60
  }
65
61
  ```
66
62
 
67
- ### 4. `ctx_batch`
63
+ ### 3. `ctx_batch`
68
64
  Executes multiple shell commands in batch. The combined outputs are indexed and filtered by your queries:
69
65
  ```json
70
66
  {