@yahyahammad/venastine 0.3.8 → 0.3.9

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 (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2715 -2715
  28. package/core/commands.py +460 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +234 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +458 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +108 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +733 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +295 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
@@ -1,280 +1,280 @@
1
- """Project path completion and mention grammar (ROADMAP_v3 §54).
2
-
3
- Only names are indexed. No file contents or access decisions belong here.
4
- Git is optional; its ignore semantics are used when available. Snapshots are
5
- bounded and replaced by a worker, never walked by the keystroke handler.
6
- """
7
-
8
- from __future__ import annotations
9
-
10
- import json
11
- import os
12
- import re
13
- import shutil
14
-
15
- # Optional git listing uses fixed argv and no shell.
16
- import subprocess # nosec B404
17
- import threading
18
- import time
19
- import weakref
20
- from collections import deque
21
- from dataclasses import dataclass
22
-
23
- INDEX_LIMIT = 50_000
24
- MATCH_LIMIT = 200
25
- SCAN_SECONDS = 5
26
- GIT_BYTE_LIMIT = 16 * 1024 * 1024
27
- SKIP_DIRS = frozenset({
28
- "__pycache__", ".venv", "venv", "node_modules", ".pytest_cache",
29
- ".mypy_cache", ".ruff_cache", "dist", "build",
30
- })
31
- _START = re.compile(r'(?<![\w@/\\])@(?=\S|$)')
32
- _BARE = re.compile(r'[\w./\\:-]+', re.UNICODE)
33
- _indexes: weakref.WeakSet = weakref.WeakSet()
34
- _indexes_lock = threading.Lock()
35
-
36
-
37
- @dataclass(frozen=True)
38
- class Mention:
39
- start: int
40
- end: int
41
- path: str
42
-
43
-
44
- def mentions(text: str, *, incomplete: bool = False) -> list[Mention]:
45
- """Parse standalone @paths and JSON-quoted @\"paths with spaces\".
46
-
47
- Bare email addresses and package scopes embedded in a path do not
48
- trigger. Quoting also permits punctuation in a filename, unambiguously.
49
- The incomplete form is used only by completion, never by the prompt.
50
- """
51
- found = []
52
- consumed = 0
53
- for match in _START.finditer(text):
54
- if match.start() < consumed:
55
- continue
56
- begin = match.end()
57
- if text[begin:begin + 1] == '"':
58
- try:
59
- path, length = json.JSONDecoder().raw_decode(text[begin:])
60
- end = begin + length
61
- except ValueError:
62
- if not incomplete:
63
- continue
64
- end = text.find("\n", begin)
65
- end = len(text) if end < 0 else end
66
- path = text[begin + 1:end]
67
- else:
68
- token = _BARE.match(text, begin)
69
- end = token.end() if token else begin
70
- path = text[begin:end]
71
- if isinstance(path, str) and (path or incomplete):
72
- found.append(Mention(match.start(), end, path))
73
- consumed = end
74
- return found
75
-
76
-
77
- def active_mention(text: str, cursor: int) -> Mention | None:
78
- for item in mentions(text, incomplete=True):
79
- if item.start < cursor <= item.end:
80
- return item
81
- return None
82
-
83
-
84
- def quote_path(path: str) -> str:
85
- return path if _BARE.fullmatch(path) else json.dumps(path, ensure_ascii=False)
86
-
87
-
88
- @dataclass(frozen=True)
89
- class FileSuggestion:
90
- path: str
91
- prefix: str = "@"
92
- usage: str | None = None
93
-
94
- @property
95
- def name(self) -> str:
96
- return quote_path(self.path)
97
-
98
- @property
99
- def summary(self) -> str:
100
- return "folder" if self.path.endswith("/") else "file"
101
-
102
-
103
- @dataclass(frozen=True)
104
- class Snapshot:
105
- visible: tuple[str, ...] = ()
106
- ignored: tuple[str, ...] = ()
107
- source: str = "indexing"
108
- limited: bool = False
109
-
110
-
111
- def _git_paths(root: str, ignored: bool):
112
- """Stream bounded NUL records; fixed argv, no shell or fsmonitor hook."""
113
- git = shutil.which("git")
114
- if not git:
115
- raise OSError("git unavailable")
116
- args = [git, "-c", "core.fsmonitor=false", "ls-files", "-z",
117
- "--others", "--exclude-standard"]
118
- args += ["--ignored"] if ignored else ["--cached"]
119
- # B603: executable from PATH, fixed options; root is cwd, never argv.
120
- process = subprocess.Popen( # nosec B603
121
- args, cwd=root, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
122
- expired = threading.Event()
123
-
124
- def stop():
125
- expired.set()
126
- try:
127
- process.kill()
128
- except OSError: # process exited as the timer fired
129
- pass
130
-
131
- timer = threading.Timer(SCAN_SECONDS, stop)
132
- timer.daemon = True
133
- timer.start()
134
- try:
135
- pending = b""
136
- received = 0
137
- while chunk := process.stdout.read1(65536):
138
- received += len(chunk)
139
- if received > GIT_BYTE_LIMIT:
140
- raise TimeoutError("git listing byte limit")
141
- records = (pending + chunk).split(b"\0")
142
- pending = records.pop()
143
- for raw in records:
144
- yield os.fsdecode(raw)
145
- if process.wait() or expired.is_set():
146
- raise OSError("git listing failed or timed out")
147
- finally:
148
- timer.cancel()
149
- if process.poll() is None:
150
- process.kill()
151
- process.wait()
152
- process.stdout.close()
153
-
154
-
155
- def _safe_name(path: str) -> bool:
156
- return (bool(path) and not os.path.isabs(path)
157
- and not any(part in ("..", ".git") for part in path.split("/"))
158
- and not any(ord(char) < 32 or 127 <= ord(char) < 160
159
- or 0xD800 <= ord(char) < 0xE000 for char in path))
160
-
161
-
162
- def scan(root: str) -> Snapshot:
163
- visible, ignored = set(), set()
164
- limited = False
165
-
166
- def add(path, hidden):
167
- nonlocal limited
168
- path = path.replace(os.sep, "/")
169
- if not _safe_name(path):
170
- return
171
- target = ignored if hidden else visible
172
- parts = path.rstrip("/").split("/")
173
- entries = ["/".join(parts[:n]) + "/" for n in range(1, len(parts))]
174
- entries.append(path)
175
- for entry in entries:
176
- if entry in visible or entry in ignored:
177
- continue
178
- if len(visible) + len(ignored) >= INDEX_LIMIT:
179
- limited = True
180
- return
181
- target.add(entry)
182
-
183
- try:
184
- for hidden in (False, True):
185
- listing = _git_paths(root, hidden)
186
- try:
187
- for path in listing:
188
- add(path, hidden)
189
- if limited:
190
- break
191
- finally:
192
- listing.close()
193
- if limited:
194
- break
195
- source = "git ignores"
196
- except (OSError, TimeoutError):
197
- visible.clear()
198
- ignored.clear()
199
- limited = False
200
- source = "fallback skips"
201
- pending = deque([(root, False)])
202
- deadline = time.monotonic() + SCAN_SECONDS
203
- visited = 0
204
- while pending and not limited:
205
- directory, hidden = pending.popleft()
206
- try:
207
- with os.scandir(directory) as entries:
208
- for entry in entries:
209
- visited += 1
210
- if visited > INDEX_LIMIT or time.monotonic() >= deadline:
211
- limited = True
212
- break
213
- if entry.name.casefold() == ".git":
214
- continue
215
- is_dir = entry.is_dir(follow_symlinks=False)
216
- child_hidden = hidden or (is_dir and entry.name in SKIP_DIRS)
217
- rel = os.path.relpath(entry.path, root).replace(os.sep, "/")
218
- add(rel + ("/" if is_dir else ""), child_hidden)
219
- if is_dir:
220
- pending.append((entry.path, child_hidden))
221
- if limited:
222
- break
223
- except OSError:
224
- # An unreadable subtree makes the snapshot partial, visibly.
225
- limited = True
226
- return Snapshot(tuple(sorted(visible)), tuple(sorted(ignored)), source, limited)
227
-
228
-
229
- class FileIndex:
230
- def __init__(self, root: str | None):
231
- self.root = os.path.realpath(root) if root else None
232
- self.snapshot = Snapshot(source="indexing" if root else "no project")
233
- self.show_ignored = False
234
- self.dirty = threading.Event()
235
- if root:
236
- self.dirty.set()
237
- with _indexes_lock:
238
- _indexes.add(self)
239
-
240
- def refresh(self):
241
- self.dirty.clear()
242
- if self.root:
243
- self.snapshot = scan(self.root)
244
-
245
- def matching(self, query: str) -> tuple[list[FileSuggestion], str]:
246
- snapshot = self.snapshot
247
- query = query.replace("\\", "/").casefold()
248
- paths = snapshot.visible + (snapshot.ignored if self.show_ignored else ())
249
- # Keep bounded prefix/substring buckets instead of sorting 50,000
250
- # rows at every keystroke. Snapshot order breaks ties predictably.
251
- prefixes, others = [], []
252
- total = 0
253
- for path in paths:
254
- folded = path.casefold()
255
- if query not in folded:
256
- continue
257
- total += 1
258
- starts = folded.startswith(query) or folded.rstrip("/").rsplit("/", 1)[-1].startswith(query)
259
- bucket = prefixes if starts else others
260
- if len(bucket) < MATCH_LIMIT:
261
- bucket.append(FileSuggestion(path))
262
- notices = []
263
- if total > MATCH_LIMIT:
264
- notices.append(f"first {MATCH_LIMIT} of {total} matches")
265
- if snapshot.limited:
266
- notices.append(f"partial index (limit {INDEX_LIMIT:,})")
267
- notices += [snapshot.source, f"ignored {'shown' if self.show_ignored else 'hidden'}"]
268
- return (prefixes + others)[:MATCH_LIMIT], " · ".join(notices)
269
-
270
-
271
- def note_file_created(path: str) -> None:
272
- """Called only after write succeeds; subagents use the same producer."""
273
- with _indexes_lock:
274
- indexes = list(_indexes)
275
- for index in indexes:
276
- try:
277
- if os.path.commonpath((index.root, path)) == index.root:
278
- index.dirty.set()
279
- except ValueError: # different drives
280
- continue
1
+ """Project path completion and mention grammar (ROADMAP_v3 §54).
2
+
3
+ Only names are indexed. No file contents or access decisions belong here.
4
+ Git is optional; its ignore semantics are used when available. Snapshots are
5
+ bounded and replaced by a worker, never walked by the keystroke handler.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import os
12
+ import re
13
+ import shutil
14
+
15
+ # Optional git listing uses fixed argv and no shell.
16
+ import subprocess # nosec B404
17
+ import threading
18
+ import time
19
+ import weakref
20
+ from collections import deque
21
+ from dataclasses import dataclass
22
+
23
+ INDEX_LIMIT = 50_000
24
+ MATCH_LIMIT = 200
25
+ SCAN_SECONDS = 5
26
+ GIT_BYTE_LIMIT = 16 * 1024 * 1024
27
+ SKIP_DIRS = frozenset({
28
+ "__pycache__", ".venv", "venv", "node_modules", ".pytest_cache",
29
+ ".mypy_cache", ".ruff_cache", "dist", "build",
30
+ })
31
+ _START = re.compile(r'(?<![\w@/\\])@(?=\S|$)')
32
+ _BARE = re.compile(r'[\w./\\:-]+', re.UNICODE)
33
+ _indexes: weakref.WeakSet = weakref.WeakSet()
34
+ _indexes_lock = threading.Lock()
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class Mention:
39
+ start: int
40
+ end: int
41
+ path: str
42
+
43
+
44
+ def mentions(text: str, *, incomplete: bool = False) -> list[Mention]:
45
+ """Parse standalone @paths and JSON-quoted @\"paths with spaces\".
46
+
47
+ Bare email addresses and package scopes embedded in a path do not
48
+ trigger. Quoting also permits punctuation in a filename, unambiguously.
49
+ The incomplete form is used only by completion, never by the prompt.
50
+ """
51
+ found = []
52
+ consumed = 0
53
+ for match in _START.finditer(text):
54
+ if match.start() < consumed:
55
+ continue
56
+ begin = match.end()
57
+ if text[begin:begin + 1] == '"':
58
+ try:
59
+ path, length = json.JSONDecoder().raw_decode(text[begin:])
60
+ end = begin + length
61
+ except ValueError:
62
+ if not incomplete:
63
+ continue
64
+ end = text.find("\n", begin)
65
+ end = len(text) if end < 0 else end
66
+ path = text[begin + 1:end]
67
+ else:
68
+ token = _BARE.match(text, begin)
69
+ end = token.end() if token else begin
70
+ path = text[begin:end]
71
+ if isinstance(path, str) and (path or incomplete):
72
+ found.append(Mention(match.start(), end, path))
73
+ consumed = end
74
+ return found
75
+
76
+
77
+ def active_mention(text: str, cursor: int) -> Mention | None:
78
+ for item in mentions(text, incomplete=True):
79
+ if item.start < cursor <= item.end:
80
+ return item
81
+ return None
82
+
83
+
84
+ def quote_path(path: str) -> str:
85
+ return path if _BARE.fullmatch(path) else json.dumps(path, ensure_ascii=False)
86
+
87
+
88
+ @dataclass(frozen=True)
89
+ class FileSuggestion:
90
+ path: str
91
+ prefix: str = "@"
92
+ usage: str | None = None
93
+
94
+ @property
95
+ def name(self) -> str:
96
+ return quote_path(self.path)
97
+
98
+ @property
99
+ def summary(self) -> str:
100
+ return "folder" if self.path.endswith("/") else "file"
101
+
102
+
103
+ @dataclass(frozen=True)
104
+ class Snapshot:
105
+ visible: tuple[str, ...] = ()
106
+ ignored: tuple[str, ...] = ()
107
+ source: str = "indexing"
108
+ limited: bool = False
109
+
110
+
111
+ def _git_paths(root: str, ignored: bool):
112
+ """Stream bounded NUL records; fixed argv, no shell or fsmonitor hook."""
113
+ git = shutil.which("git")
114
+ if not git:
115
+ raise OSError("git unavailable")
116
+ args = [git, "-c", "core.fsmonitor=false", "ls-files", "-z",
117
+ "--others", "--exclude-standard"]
118
+ args += ["--ignored"] if ignored else ["--cached"]
119
+ # B603: executable from PATH, fixed options; root is cwd, never argv.
120
+ process = subprocess.Popen( # nosec B603
121
+ args, cwd=root, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
122
+ expired = threading.Event()
123
+
124
+ def stop():
125
+ expired.set()
126
+ try:
127
+ process.kill()
128
+ except OSError: # process exited as the timer fired
129
+ pass
130
+
131
+ timer = threading.Timer(SCAN_SECONDS, stop)
132
+ timer.daemon = True
133
+ timer.start()
134
+ try:
135
+ pending = b""
136
+ received = 0
137
+ while chunk := process.stdout.read1(65536):
138
+ received += len(chunk)
139
+ if received > GIT_BYTE_LIMIT:
140
+ raise TimeoutError("git listing byte limit")
141
+ records = (pending + chunk).split(b"\0")
142
+ pending = records.pop()
143
+ for raw in records:
144
+ yield os.fsdecode(raw)
145
+ if process.wait() or expired.is_set():
146
+ raise OSError("git listing failed or timed out")
147
+ finally:
148
+ timer.cancel()
149
+ if process.poll() is None:
150
+ process.kill()
151
+ process.wait()
152
+ process.stdout.close()
153
+
154
+
155
+ def _safe_name(path: str) -> bool:
156
+ return (bool(path) and not os.path.isabs(path)
157
+ and not any(part in ("..", ".git") for part in path.split("/"))
158
+ and not any(ord(char) < 32 or 127 <= ord(char) < 160
159
+ or 0xD800 <= ord(char) < 0xE000 for char in path))
160
+
161
+
162
+ def scan(root: str) -> Snapshot:
163
+ visible, ignored = set(), set()
164
+ limited = False
165
+
166
+ def add(path, hidden):
167
+ nonlocal limited
168
+ path = path.replace(os.sep, "/")
169
+ if not _safe_name(path):
170
+ return
171
+ target = ignored if hidden else visible
172
+ parts = path.rstrip("/").split("/")
173
+ entries = ["/".join(parts[:n]) + "/" for n in range(1, len(parts))]
174
+ entries.append(path)
175
+ for entry in entries:
176
+ if entry in visible or entry in ignored:
177
+ continue
178
+ if len(visible) + len(ignored) >= INDEX_LIMIT:
179
+ limited = True
180
+ return
181
+ target.add(entry)
182
+
183
+ try:
184
+ for hidden in (False, True):
185
+ listing = _git_paths(root, hidden)
186
+ try:
187
+ for path in listing:
188
+ add(path, hidden)
189
+ if limited:
190
+ break
191
+ finally:
192
+ listing.close()
193
+ if limited:
194
+ break
195
+ source = "git ignores"
196
+ except (OSError, TimeoutError):
197
+ visible.clear()
198
+ ignored.clear()
199
+ limited = False
200
+ source = "fallback skips"
201
+ pending = deque([(root, False)])
202
+ deadline = time.monotonic() + SCAN_SECONDS
203
+ visited = 0
204
+ while pending and not limited:
205
+ directory, hidden = pending.popleft()
206
+ try:
207
+ with os.scandir(directory) as entries:
208
+ for entry in entries:
209
+ visited += 1
210
+ if visited > INDEX_LIMIT or time.monotonic() >= deadline:
211
+ limited = True
212
+ break
213
+ if entry.name.casefold() == ".git":
214
+ continue
215
+ is_dir = entry.is_dir(follow_symlinks=False)
216
+ child_hidden = hidden or (is_dir and entry.name in SKIP_DIRS)
217
+ rel = os.path.relpath(entry.path, root).replace(os.sep, "/")
218
+ add(rel + ("/" if is_dir else ""), child_hidden)
219
+ if is_dir:
220
+ pending.append((entry.path, child_hidden))
221
+ if limited:
222
+ break
223
+ except OSError:
224
+ # An unreadable subtree makes the snapshot partial, visibly.
225
+ limited = True
226
+ return Snapshot(tuple(sorted(visible)), tuple(sorted(ignored)), source, limited)
227
+
228
+
229
+ class FileIndex:
230
+ def __init__(self, root: str | None):
231
+ self.root = os.path.realpath(root) if root else None
232
+ self.snapshot = Snapshot(source="indexing" if root else "no project")
233
+ self.show_ignored = False
234
+ self.dirty = threading.Event()
235
+ if root:
236
+ self.dirty.set()
237
+ with _indexes_lock:
238
+ _indexes.add(self)
239
+
240
+ def refresh(self):
241
+ self.dirty.clear()
242
+ if self.root:
243
+ self.snapshot = scan(self.root)
244
+
245
+ def matching(self, query: str) -> tuple[list[FileSuggestion], str]:
246
+ snapshot = self.snapshot
247
+ query = query.replace("\\", "/").casefold()
248
+ paths = snapshot.visible + (snapshot.ignored if self.show_ignored else ())
249
+ # Keep bounded prefix/substring buckets instead of sorting 50,000
250
+ # rows at every keystroke. Snapshot order breaks ties predictably.
251
+ prefixes, others = [], []
252
+ total = 0
253
+ for path in paths:
254
+ folded = path.casefold()
255
+ if query not in folded:
256
+ continue
257
+ total += 1
258
+ starts = folded.startswith(query) or folded.rstrip("/").rsplit("/", 1)[-1].startswith(query)
259
+ bucket = prefixes if starts else others
260
+ if len(bucket) < MATCH_LIMIT:
261
+ bucket.append(FileSuggestion(path))
262
+ notices = []
263
+ if total > MATCH_LIMIT:
264
+ notices.append(f"first {MATCH_LIMIT} of {total} matches")
265
+ if snapshot.limited:
266
+ notices.append(f"partial index (limit {INDEX_LIMIT:,})")
267
+ notices += [snapshot.source, f"ignored {'shown' if self.show_ignored else 'hidden'}"]
268
+ return (prefixes + others)[:MATCH_LIMIT], " · ".join(notices)
269
+
270
+
271
+ def note_file_created(path: str) -> None:
272
+ """Called only after write succeeds; subagents use the same producer."""
273
+ with _indexes_lock:
274
+ indexes = list(_indexes)
275
+ for index in indexes:
276
+ try:
277
+ if os.path.commonpath((index.root, path)) == index.root:
278
+ index.dirty.set()
279
+ except ValueError: # different drives
280
+ continue