@cursor/july 0.1.103 → 0.1.104

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 (186) hide show
  1. package/dist/channels/change-monitors/change-monitors-channel.d.ts +5 -0
  2. package/dist/channels/change-monitors/change-monitors-channel.d.ts.map +1 -0
  3. package/dist/channels/change-monitors/change-monitors-channel.js +41 -0
  4. package/dist/channels/change-monitors/index.d.ts +4 -0
  5. package/dist/channels/change-monitors/index.d.ts.map +1 -0
  6. package/dist/channels/change-monitors/index.js +2 -0
  7. package/dist/channels/change-monitors/types.d.ts +39 -0
  8. package/dist/channels/change-monitors/types.d.ts.map +1 -0
  9. package/dist/channels/change-monitors/types.js +1 -0
  10. package/dist/channels/github/defaults.d.ts.map +1 -1
  11. package/dist/channels/github/defaults.js +4 -0
  12. package/dist/channels/github/progress.d.ts +22 -0
  13. package/dist/channels/github/progress.d.ts.map +1 -1
  14. package/dist/channels/github/progress.js +32 -5
  15. package/dist/channels/issues/index.d.ts +4 -0
  16. package/dist/channels/issues/index.d.ts.map +1 -0
  17. package/dist/channels/issues/index.js +2 -0
  18. package/dist/channels/issues/issues-channel.d.ts +5 -0
  19. package/dist/channels/issues/issues-channel.d.ts.map +1 -0
  20. package/dist/channels/issues/issues-channel.js +37 -0
  21. package/dist/channels/issues/types.d.ts +33 -0
  22. package/dist/channels/issues/types.d.ts.map +1 -0
  23. package/dist/channels/issues/types.js +1 -0
  24. package/dist/docs/404.html +2 -2
  25. package/dist/docs/ab.html +4 -4
  26. package/dist/docs/assets/{app.DW9pXkpL.js → app.DbMWUyGb.js} +1 -1
  27. package/dist/docs/assets/chunks/@localSearchIndexroot.Bqsulb9K.js +1 -0
  28. package/dist/docs/assets/chunks/{VPLocalSearchBox.CdEIUwDg.js → VPLocalSearchBox.DcNeTh9o.js} +1 -1
  29. package/dist/docs/assets/chunks/{theme.YZMHgPgg.js → theme.DMjhY3gl.js} +2 -2
  30. package/dist/docs/assets/{guides_github.md.DKYiT9do.js → guides_github.md.c0gdGJ-D.js} +1 -1
  31. package/dist/docs/assets/{guides_github.md.DKYiT9do.lean.js → guides_github.md.c0gdGJ-D.lean.js} +1 -1
  32. package/dist/docs/assets/{reference_channels.md.Dz8Cnudp.js → reference_channels.md.DBGcaB7m.js} +2 -2
  33. package/dist/docs/assets/{reference_channels.md.Dz8Cnudp.lean.js → reference_channels.md.DBGcaB7m.lean.js} +1 -1
  34. package/dist/docs/building-with-agents.html +4 -4
  35. package/dist/docs/concepts.html +4 -4
  36. package/dist/docs/deployment.html +4 -4
  37. package/dist/docs/design/filesystem.md +376 -0
  38. package/dist/docs/evals.html +4 -4
  39. package/dist/docs/guides/agent-to-agent.html +4 -4
  40. package/dist/docs/guides/cloud-agents.html +4 -4
  41. package/dist/docs/guides/convert-automation.html +4 -4
  42. package/dist/docs/guides/github.html +6 -6
  43. package/dist/docs/guides/github.md +5 -0
  44. package/dist/docs/guides/human-in-the-loop.html +4 -4
  45. package/dist/docs/guides/mcp-oauth.html +4 -4
  46. package/dist/docs/guides/opentelemetry.html +4 -4
  47. package/dist/docs/guides/slack.html +4 -4
  48. package/dist/docs/guides/webhooks.html +4 -4
  49. package/dist/docs/hashmap.json +1 -1
  50. package/dist/docs/hillclimbing.html +4 -4
  51. package/dist/docs/index.html +4 -4
  52. package/dist/docs/llms-full.txt +406 -0
  53. package/dist/docs/llms.txt +1 -0
  54. package/dist/docs/quickstart.html +4 -4
  55. package/dist/docs/reference/agent-config.html +4 -4
  56. package/dist/docs/reference/artifacts.html +4 -4
  57. package/dist/docs/reference/channels.html +6 -6
  58. package/dist/docs/reference/channels.md +20 -0
  59. package/dist/docs/reference/cli.html +4 -4
  60. package/dist/docs/reference/connections.html +4 -4
  61. package/dist/docs/reference/extensions.html +4 -4
  62. package/dist/docs/reference/hooks.html +4 -4
  63. package/dist/docs/reference/http-api.html +4 -4
  64. package/dist/docs/reference/instructions.html +4 -4
  65. package/dist/docs/reference/playground.html +4 -4
  66. package/dist/docs/reference/project-layout.html +4 -4
  67. package/dist/docs/reference/prompt.html +4 -4
  68. package/dist/docs/reference/result.html +4 -4
  69. package/dist/docs/reference/schedules.html +4 -4
  70. package/dist/docs/reference/sessions.html +4 -4
  71. package/dist/docs/reference/skills.html +4 -4
  72. package/dist/docs/reference/subagents.html +4 -4
  73. package/dist/docs/reference/tools.html +4 -4
  74. package/dist/docs/scaffolding-agents.html +4 -4
  75. package/dist/docs/skills/ab.html +4 -4
  76. package/dist/docs/skills/create-agent.html +4 -4
  77. package/dist/docs/skills/debug.html +4 -4
  78. package/dist/docs/skills/evals.html +4 -4
  79. package/dist/docs/skills/framework-map.html +4 -4
  80. package/dist/docs/skills/github.html +4 -4
  81. package/dist/docs/skills/hillclimb.html +4 -4
  82. package/dist/docs/skills/index.html +4 -4
  83. package/dist/docs/skills/mcp-auth.html +4 -4
  84. package/dist/docs/skills/otel.html +4 -4
  85. package/dist/docs/skills/setup-slack.html +4 -4
  86. package/dist/docs/storage.html +4 -4
  87. package/dist/docs/templates/agentic-owners.html +4 -4
  88. package/dist/docs/templates/agents-md.html +4 -4
  89. package/dist/docs/templates/code-wiki.html +4 -4
  90. package/dist/docs/templates/demo.html +4 -4
  91. package/dist/docs/templates/pr-autofixer.html +4 -4
  92. package/dist/docs/templates/security-help.html +4 -4
  93. package/dist/docs/templates/security-reviewer.html +4 -4
  94. package/dist/docs/templates/triage.html +4 -4
  95. package/dist/docs/troubleshooting.html +4 -4
  96. package/dist/filesystem.d.ts +440 -0
  97. package/dist/filesystem.d.ts.map +1 -0
  98. package/dist/filesystem.js +1694 -0
  99. package/dist/index.d.ts +2 -0
  100. package/dist/index.d.ts.map +1 -1
  101. package/dist/index.js +1 -0
  102. package/dist/internal/continuation-channel.d.ts +4 -2
  103. package/dist/internal/continuation-channel.d.ts.map +1 -1
  104. package/dist/internal/continuation-channel.js +21 -12
  105. package/dist/internal/continuation-identity.d.ts +13 -5
  106. package/dist/internal/continuation-identity.d.ts.map +1 -1
  107. package/dist/internal/continuation-identity.js +74 -35
  108. package/dist/internal/discovery/agent.d.ts.map +1 -1
  109. package/dist/internal/discovery/agent.js +80 -8
  110. package/dist/internal/discovery/info.d.ts.map +1 -1
  111. package/dist/internal/discovery/info.js +3 -0
  112. package/dist/internal/factory-resource-channel.d.ts +33 -0
  113. package/dist/internal/factory-resource-channel.d.ts.map +1 -0
  114. package/dist/internal/factory-resource-channel.js +77 -0
  115. package/dist/internal/filesystem/errors.d.ts +64 -0
  116. package/dist/internal/filesystem/errors.d.ts.map +1 -0
  117. package/dist/internal/filesystem/errors.js +175 -0
  118. package/dist/internal/filesystem/format.d.ts +28 -0
  119. package/dist/internal/filesystem/format.d.ts.map +1 -0
  120. package/dist/internal/filesystem/format.js +213 -0
  121. package/dist/internal/filesystem/merge.d.ts +34 -0
  122. package/dist/internal/filesystem/merge.d.ts.map +1 -0
  123. package/dist/internal/filesystem/merge.js +196 -0
  124. package/dist/internal/filesystem/scratch.d.ts +59 -0
  125. package/dist/internal/filesystem/scratch.d.ts.map +1 -0
  126. package/dist/internal/filesystem/scratch.js +212 -0
  127. package/dist/internal/filesystem/sdk-schemas.d.ts +29 -0
  128. package/dist/internal/filesystem/sdk-schemas.d.ts.map +1 -0
  129. package/dist/internal/filesystem/sdk-schemas.js +153 -0
  130. package/dist/internal/filesystem/tools.d.ts +42 -0
  131. package/dist/internal/filesystem/tools.d.ts.map +1 -0
  132. package/dist/internal/filesystem/tools.js +618 -0
  133. package/dist/internal/filesystem/walk.d.ts +74 -0
  134. package/dist/internal/filesystem/walk.d.ts.map +1 -0
  135. package/dist/internal/filesystem/walk.js +339 -0
  136. package/dist/internal/guest-network.d.ts +5 -2
  137. package/dist/internal/guest-network.d.ts.map +1 -1
  138. package/dist/internal/guest-network.js +7 -2
  139. package/dist/internal/hosted-delivery.d.ts.map +1 -1
  140. package/dist/internal/hosted-delivery.js +12 -2
  141. package/dist/internal/sdk-runner.d.ts +1 -1
  142. package/dist/internal/sdk-runner.d.ts.map +1 -1
  143. package/dist/internal/sdk-runner.js +3 -1
  144. package/dist/internal/session-engine.d.ts +22 -0
  145. package/dist/internal/session-engine.d.ts.map +1 -1
  146. package/dist/internal/session-engine.js +362 -40
  147. package/dist/internal/testing/factory-resource-fixtures.d.ts +48 -0
  148. package/dist/internal/testing/factory-resource-fixtures.d.ts.map +1 -0
  149. package/dist/internal/testing/factory-resource-fixtures.js +41 -0
  150. package/dist/playground/assets/{index-59KvgREd.js → index-8YiozU89.js} +38 -38
  151. package/dist/playground/index.html +1 -1
  152. package/dist/types.d.ts +51 -3
  153. package/dist/types.d.ts.map +1 -1
  154. package/docs/design/filesystem.md +376 -0
  155. package/docs/guides/github.md +5 -0
  156. package/docs/reference/channels.md +20 -0
  157. package/package.json +16 -2
  158. package/src/channels/change-monitors/change-monitors-channel.ts +62 -0
  159. package/src/channels/change-monitors/index.ts +8 -0
  160. package/src/channels/change-monitors/types.ts +44 -0
  161. package/src/channels/github/defaults.ts +4 -0
  162. package/src/channels/github/progress.ts +76 -10
  163. package/src/channels/issues/index.ts +9 -0
  164. package/src/channels/issues/issues-channel.ts +51 -0
  165. package/src/channels/issues/types.ts +41 -0
  166. package/src/filesystem.ts +2074 -0
  167. package/src/index.ts +28 -0
  168. package/src/internal/continuation-channel.ts +29 -12
  169. package/src/internal/continuation-identity.ts +122 -37
  170. package/src/internal/discovery/agent.ts +87 -1
  171. package/src/internal/discovery/info.ts +3 -0
  172. package/src/internal/factory-resource-channel.ts +122 -0
  173. package/src/internal/filesystem/errors.ts +220 -0
  174. package/src/internal/filesystem/format.ts +276 -0
  175. package/src/internal/filesystem/merge.ts +195 -0
  176. package/src/internal/filesystem/scratch.ts +255 -0
  177. package/src/internal/filesystem/sdk-schemas.ts +204 -0
  178. package/src/internal/filesystem/tools.ts +821 -0
  179. package/src/internal/filesystem/walk.ts +369 -0
  180. package/src/internal/guest-network.ts +8 -2
  181. package/src/internal/hosted-delivery.ts +18 -1
  182. package/src/internal/sdk-runner.ts +4 -0
  183. package/src/internal/session-engine.ts +439 -29
  184. package/src/internal/testing/factory-resource-fixtures.ts +85 -0
  185. package/src/types.ts +49 -3
  186. package/dist/docs/assets/chunks/@localSearchIndexroot.nrl1ifBq.js +0 -1
@@ -0,0 +1,440 @@
1
+ import type { ToolName } from "@cursor/sdk";
2
+ export { DeleteNotSupportedError, EditError, FileNotFoundError, InvalidGrepPatternError, isFileNotFoundError, isInvalidGrepPatternError, NoMountError, PathError, ReadOnlyMountError, WriteFailedError, } from "./internal/filesystem/errors.js";
3
+ import type { HostFilesApi, HostFilesScope } from "./types.js";
4
+ /**
5
+ * Status envelope used by walk helpers such as `lsFromList`.
6
+ * FileSystem methods throw; they do not return this.
7
+ * `@cursor/july` does not export it.
8
+ */
9
+ export type FileSystemResult<T> = {
10
+ status: "success";
11
+ value: T;
12
+ } | {
13
+ status: "error";
14
+ error: {
15
+ message: string;
16
+ };
17
+ };
18
+ /**
19
+ * One file in a `list` / `glob` stream.
20
+ *
21
+ * `path` is an absolute posix path (`/src/a.ts`). No trailing slash
22
+ * except `/`. `size` is optional byte length of the file contents.
23
+ */
24
+ export interface DirEntry {
25
+ path: string;
26
+ size?: number;
27
+ }
28
+ /**
29
+ * Existence probe. `directory` means this path is a prefix of at
30
+ * least one file (virtual trees infer directories) or a real
31
+ * directory on disk. `missing` is a value, not an error.
32
+ */
33
+ export type FileInfo = {
34
+ kind: "file";
35
+ } | {
36
+ kind: "directory";
37
+ } | {
38
+ kind: "missing";
39
+ };
40
+ /**
41
+ * Native Grep `output_mode` envelope. Not a FileSystem method
42
+ * result. The `grep` verb yields {@link GrepResult}; synthesis
43
+ * shapes this union after draining the stream.
44
+ */
45
+ export type GrepUnionResult = {
46
+ type: "content";
47
+ output: {
48
+ matches: Array<{
49
+ file: string;
50
+ lineNumber?: number;
51
+ line: string;
52
+ beforeContext?: string[];
53
+ afterContext?: string[];
54
+ }>;
55
+ totalMatches: number;
56
+ };
57
+ } | {
58
+ type: "files";
59
+ output: {
60
+ files: string[];
61
+ count: number;
62
+ };
63
+ } | {
64
+ type: "count";
65
+ output: {
66
+ counts: Array<{
67
+ file: string;
68
+ count: number;
69
+ }>;
70
+ total: number;
71
+ };
72
+ };
73
+ /**
74
+ * One content hit from `grep`. `path` is absolute posix.
75
+ * `lineNumber` is 1-indexed. `line` is the full matching line,
76
+ * without the trailing newline.
77
+ */
78
+ export interface GrepResult {
79
+ path: string;
80
+ lineNumber: number;
81
+ line: string;
82
+ }
83
+ /**
84
+ * Content-search query. No `output_mode` or `offset` (those
85
+ * belong to the native Grep tool).
86
+ *
87
+ * `pattern` is a JavaScript regular expression source. Invalid
88
+ * source must throw {@link InvalidGrepPatternError} with message
89
+ * `invalid grep pattern: ${pattern}`. `path` omitted / `""` /
90
+ * `"/"` searches the whole tree; a file path searches that file
91
+ * only. A slash-free `glob` (`*.ts`) matches the basename at any
92
+ * depth under `path`.
93
+ *
94
+ * `maxResults` is optional predicate pushdown: stop after this
95
+ * many hits so a remote or large tree does not materialize a
96
+ * full scan. Native Grep still applies `head_limit` / `offset`
97
+ * after the merge. Omitted means no FileSystem-level cap.
98
+ */
99
+ export interface GrepQuery {
100
+ pattern: string;
101
+ path?: string;
102
+ glob?: string;
103
+ caseInsensitive?: boolean;
104
+ maxResults?: number;
105
+ }
106
+ /**
107
+ * One semantic hit from `search`. `path` is absolute posix.
108
+ * `score` is higher-is-better. Trees without an index yield
109
+ * nothing; they do not invent lexical stand-ins.
110
+ */
111
+ export interface SearchResult {
112
+ path: string;
113
+ snippet: string;
114
+ score: number;
115
+ }
116
+ /**
117
+ * Semantic-search query. `targetDirectories` limits the scan
118
+ * when an index exists; omitted means the whole tree.
119
+ *
120
+ * `maxResults` is optional predicate pushdown: stop after this
121
+ * many hits so an index does not retrieve a large recall set.
122
+ * Native SemanticSearch still applies `numResults` after the
123
+ * merge. Omitted means no FileSystem-level cap.
124
+ */
125
+ export interface SearchQuery {
126
+ query: string;
127
+ targetDirectories?: string[];
128
+ maxResults?: number;
129
+ }
130
+ /**
131
+ * Exact, non-overlapping str-replace. `oldText` / `newText` are
132
+ * literal strings, not regex. Splice must keep `$`, `$&`, `$1`
133
+ * in `newText` as written (`String.prototype.replace` must not
134
+ * be used).
135
+ */
136
+ export interface EditQuery {
137
+ path: string;
138
+ oldText: string;
139
+ newText: string;
140
+ replaceAll?: boolean;
141
+ }
142
+ /**
143
+ * StrReplace success. `occurrencesModified` is the number of
144
+ * non-overlapping replacements (1 unless `replaceAll`).
145
+ */
146
+ export interface EditResult {
147
+ occurrencesModified: number;
148
+ }
149
+ /**
150
+ * Path verbs for the tree the agent runs on.
151
+ *
152
+ * Every method is required. Trees without an index implement
153
+ * `search` as an empty iterator. Methods do not fall back to the
154
+ * host tree. Diagnostics are not a FileSystem concern.
155
+ *
156
+ * Paths are a single posix namespace rooted at `/`. Query paths
157
+ * and yielded paths are absolute (`/src/a.ts`). No trailing
158
+ * slash except `/`. `""`, `"/"`, and an omitted `prefix` / `dir`
159
+ * / `path` (where optional) mean the root. Prefix tests are
160
+ * path-segment: `/agent` matches `/agent/skills`, not
161
+ * `/agent-tools`.
162
+ *
163
+ * Async iterators are already sorted. `unionFs` k-way merges
164
+ * them and does not re-sort a source.
165
+ *
166
+ * - `list` / `glob`: lexicographic by `path`. Paths are unique.
167
+ * - `grep`: by `path`, then `lineNumber` ascending. Keep every hit.
168
+ * - `search`: by `score` descending, then `path` ascending.
169
+ *
170
+ * Native-tool pagination (`head_limit`, `offset`, `output_mode`,
171
+ * `numResults`) stays on the synthesized tools. `grep` /
172
+ * `search` take optional `maxResults` as predicate pushdown so
173
+ * a tree can stop retrieving once the tool's cap is known.
174
+ * Native `LS` is built from `list` + `stat`; there is no `ls`
175
+ * method.
176
+ *
177
+ * Errors (authors must follow these, not invent parallel
178
+ * spellings):
179
+ *
180
+ * - `list` / `stat` / `glob` must not throw for a missing path.
181
+ * Missing is an empty iterator or `{ kind: "missing" }`.
182
+ * - `read` / `write` / `delete` throw {@link PathError}
183
+ * for recoverable failures. `error.message` is the string the
184
+ * synthesized native tool shows the model. `error.path` is the
185
+ * absolute posix path the composer remaps.
186
+ * - `grep` throws for an invalid regex (and a missing host
187
+ * search root). A missing virtual path yields nothing.
188
+ * - `search` yields nothing when there is no index. An index
189
+ * failure may throw.
190
+ * - Missing-file message on `read` / `delete` is
191
+ * `not found: ${path}` (normalized absolute posix).
192
+ */
193
+ export interface FileSystem {
194
+ /**
195
+ * Recursive file scan under `prefix`. Files only; directories
196
+ * are inferred from path prefixes. A file is not under itself,
197
+ * so listing a file path is empty. Empty is not "missing"
198
+ * (`stat` answers that). Yields lexicographic unique
199
+ * {@link DirEntry} rows. Omitted / `""` / `"/"` means the root.
200
+ *
201
+ * Errors: none. A missing or file-path prefix yields an empty
202
+ * iterator. Do not throw.
203
+ */
204
+ list(prefix?: string): AsyncIterable<DirEntry>;
205
+ /**
206
+ * Existence probe: exact file, a prefix that has files, or
207
+ * missing. Does not throw. Native LS lists first and calls
208
+ * this only when the iterator is empty.
209
+ *
210
+ * Errors: none. Unknown paths are `{ kind: "missing" }`.
211
+ */
212
+ stat(path: string): Promise<FileInfo>;
213
+ /**
214
+ * Same scan as `list`, filtered by `pattern` relative to
215
+ * `dir`. Yields lexicographic unique {@link DirEntry} rows.
216
+ * `dir` omitted / `""` / `"/"` means the tree root. Matching
217
+ * is relative to `dir`, not basename-anywhere (`*.ts` under
218
+ * `/src` is `/src/a.ts`, not `/src/nested/c.ts`).
219
+ *
220
+ * Errors: none. A missing `dir` or a pattern that matches
221
+ * nothing yields an empty iterator. Do not throw for a bad
222
+ * glob (it matches nothing).
223
+ */
224
+ glob(pattern: string, dir?: string): AsyncIterable<DirEntry>;
225
+ /**
226
+ * Read the whole file. Text files return a string. Image
227
+ * bytes (`jpeg` / `png` / `gif` / `webp`) return a
228
+ * `Uint8Array` so native Read can base64 them into an image
229
+ * content part. Native Read applies `offset` / `limit` and
230
+ * numbers lines on text only.
231
+ *
232
+ * Errors (throw `Error`):
233
+ * - Missing file, or a virtual directory with no file inode:
234
+ * `not found: ${path}`.
235
+ * - Host I/O (EISDIR, EACCES, …): the OS message, or the same
236
+ * `not found: ${path}` fallback.
237
+ * - `unionFs` with no mount: `no mount for path: ${path}`.
238
+ */
239
+ read(path: string): Promise<string | Uint8Array>;
240
+ /**
241
+ * Content matches. No output-mode or offset. Honor
242
+ * `maxResults` when set. Yields {@link GrepResult} ordered
243
+ * by path, then line number.
244
+ *
245
+ * Errors (throw `Error`):
246
+ * - Invalid `pattern`: `invalid grep pattern: ${pattern}`.
247
+ * - Host search root does not exist: the OS message, or
248
+ * `not found: ${searchRoot}`. Native Grep turns the throw
249
+ * into `{ status: "error" }`.
250
+ *
251
+ * A missing virtual `path` yields nothing (not an error).
252
+ */
253
+ grep(query: GrepQuery): AsyncIterable<GrepResult>;
254
+ /**
255
+ * Create or overwrite a file. Parents are created as needed.
256
+ * Native Write formats `Wrote contents to ${path}` from the
257
+ * path. The Write tool maps native `fileText` onto `contents`.
258
+ *
259
+ * Errors (throw `Error`):
260
+ * - Host I/O: the OS message, or `write failed: ${path}`.
261
+ * - `unionFs` with no mount: `no mount for path: ${path}`.
262
+ * - A read-only mount may use `read-only mount` or
263
+ * `read-only mount: ${path}`.
264
+ *
265
+ * Missing parents are not an error; create them. There is no
266
+ * `not found` for `write`.
267
+ */
268
+ write(path: string, contents: string): Promise<void>;
269
+ /**
270
+ * Remove one file. Directories are not deleted; listing them
271
+ * is empty and they have no inode of their own on a virtual
272
+ * tree.
273
+ *
274
+ * Errors (throw `Error`):
275
+ * - Missing file, or a virtual directory: `not found: ${path}`.
276
+ * - Host I/O: the OS message, or `not found: ${path}`.
277
+ * - `unionFs` with no mount: `no mount for path: ${path}`.
278
+ */
279
+ delete(path: string): Promise<void>;
280
+ /**
281
+ * Semantic hits. Trees without an index yield nothing (do
282
+ * not register the host index). Honor `maxResults` when set.
283
+ * Ordered by score descending, then path.
284
+ *
285
+ * Errors: none for a tree without an index (empty iterator).
286
+ * An index that fails mid-scan may throw; native
287
+ * SemanticSearch turns that into `{ status: "error" }` with
288
+ * the thrown message or `search failed`.
289
+ */
290
+ search(query: SearchQuery): AsyncIterable<SearchResult>;
291
+ }
292
+ export declare const FILE_SYSTEM_TOOL_NAMES: readonly ["Read", "LS", "Glob", "Grep", "Write", "StrReplace", "Delete", "SemanticSearch"];
293
+ export type FileSystemToolName = (typeof FILE_SYSTEM_TOOL_NAMES)[number];
294
+ export declare function canonicalizeFileSystemToolName(name: string): FileSystemToolName | undefined;
295
+ export declare function isFileSystemToolName(name: string): name is FileSystemToolName;
296
+ export declare function isFileSystemToolAlias(name: string): boolean;
297
+ /** Direct `callTool` names that mutate the tree and must wait on a busy turn. */
298
+ export declare function isMutatingFileSystemTool(name: string): boolean;
299
+ export declare function isFileSystemMethodPresent(root: FileSystem, method: keyof FileSystem): boolean;
300
+ export declare function fileSystemToolNames(_root?: FileSystem): FileSystemToolName[];
301
+ export declare class FileSystemConfigError extends Error {
302
+ constructor(message: string);
303
+ }
304
+ export declare function resolveRootHarnessAllowlist(tools?: readonly ToolName[]): ToolName[];
305
+ export declare function resolveFileSystemTools(options: {
306
+ root: FileSystem;
307
+ tools?: readonly ToolName[];
308
+ }): ToolName[];
309
+ export declare function withMcpGrant(tools: readonly ToolName[]): ToolName[];
310
+ /**
311
+ * Native Cursor SDK file tools replaced by synthesized FileSystem tools
312
+ * on every local turn. SDK allowlist names (`edit`, not `Write`).
313
+ */
314
+ export declare const REPLACED_NATIVE_FILE_TOOLS: ToolName[];
315
+ /**
316
+ * Host-default harness options: keep shell / webSearch / sandbox, but
317
+ * hide the native file tools the synthesized FileSystem now owns.
318
+ *
319
+ * Omitted `tools` leaves the SDK default set and only excludes the
320
+ * replaced natives. `[]` stays empty. A non-empty allowlist drops file
321
+ * aliases (those ride synthesized tools) and grants `mcp`.
322
+ */
323
+ export declare function resolveHostHarnessToolOptions(tools?: readonly ToolName[]): {
324
+ tools?: ToolName[];
325
+ disallowedTools?: ToolName[];
326
+ };
327
+ export type GrepOutputMode = "content" | "files_with_matches" | "count";
328
+ /** Decode a {@link FileSystem.read} result as UTF-8 text. */
329
+ export declare function fileSystemText(content: string | Uint8Array): string;
330
+ /**
331
+ * Native Read image formats. Magic bytes first, then extension.
332
+ * Returns undefined for text (and for any other binary).
333
+ */
334
+ export declare function detectImageMimeType(bytes: Uint8Array, filePath?: string): string | undefined;
335
+ export declare function fileSystemImage(content: string | Uint8Array, path: string): {
336
+ mimeType: string;
337
+ bytes: Uint8Array;
338
+ } | undefined;
339
+ export declare function collectGrepMatches(root: FileSystem, query: GrepQuery, opts: {
340
+ outputMode: GrepOutputMode;
341
+ headLimit?: number;
342
+ offset?: number;
343
+ }): Promise<GrepResult[]>;
344
+ export type GrepContentHit = GrepResult & {
345
+ beforeContext?: string[];
346
+ afterContext?: string[];
347
+ };
348
+ export declare function shapeGrepUnion(matches: GrepContentHit[], outputMode: GrepOutputMode): GrepUnionResult;
349
+ export declare function normalizeFsPath(input: string): string;
350
+ /** Path-segment prefix: `/agent` matches `/agent/skills`, not `/agent-tools`. */
351
+ export declare function pathHasSegmentPrefix(args: {
352
+ path: string;
353
+ prefix: string;
354
+ }): boolean;
355
+ /**
356
+ * Resolve a per-send `workspaceFiles` key onto the virtual `/` namespace.
357
+ * Refuses paths that escape the root, and the reserved `memory` name.
358
+ * Host-default workspaces symlink `memory/` to durable agent state, so a
359
+ * seed under that name would write through the link.
360
+ */
361
+ export declare function virtualWorkspaceWritePath(relativePath: string): string;
362
+ export declare function writeWorkspaceFilesToRoot(root: FileSystem, files: Record<string, string | {
363
+ encoding: "base64";
364
+ data: string;
365
+ mimeType?: string;
366
+ }>): Promise<void>;
367
+ /**
368
+ * Exact str-replace as `read` + apply + `write`. Uniqueness is
369
+ * this helper's contract; FileSystem implementations do not
370
+ * implement edit. Native StrReplace calls this.
371
+ */
372
+ export declare function strReplaceOnFileSystem(root: Pick<FileSystem, "read" | "write">, query: EditQuery): Promise<EditResult>;
373
+ /** Native Read offset/limit: 1-indexed, negative offset counts from the end. */
374
+ export declare function sliceReadContent(content: string, offset?: number, limit?: number): string;
375
+ /**
376
+ * A FileSystem with no files. Use as an overlay leaf or a missing
377
+ * catalog so a miss stays {@link FileNotFoundError} instead of
378
+ * {@link NoMountError}. Writes and deletes throw
379
+ * {@link ReadOnlyMountError} — an empty tree is never a sink.
380
+ */
381
+ export declare function emptyFs(): FileSystem;
382
+ /**
383
+ * In-memory FileSystem for tests and fixtures. Keys are absolute
384
+ * posix paths (`/a.txt`) and are normalized on ingest. Honors the
385
+ * {@link FileSystem} order and path contracts.
386
+ * `search` is empty. Creates `/agent-tools` on first scratch
387
+ * write the same way any other path is created.
388
+ */
389
+ export declare function tempFs(files?: Record<string, string | Uint8Array>): FileSystem;
390
+ /**
391
+ * Host-disk FileSystem. Relative paths resolve against `cwd`; absolute
392
+ * paths are used as-is — the same contract as Cursor SDK native file
393
+ * tools. `search` yields empty results (no host index).
394
+ *
395
+ * Internal. Not part of the public Agent SDK surface.
396
+ */
397
+ export declare function localFileSystem(options: {
398
+ cwd: string;
399
+ }): FileSystem;
400
+ /**
401
+ * Longest-prefix compose, path-segment match. Every verb is
402
+ * defined. Does not synthesize `shell`. `/agent` is not a
403
+ * prefix of `/agent-tools`.
404
+ *
405
+ * The record keys are mount points. Each child is a FileSystem
406
+ * rooted at `/`. `unionFs` strips the prefix on the way in and
407
+ * re-prefixes yields (and error paths) on the way out:
408
+ * `unionFs({ "/host": hostFs(...) })` — the child never sees
409
+ * `/host`.
410
+ *
411
+ * A path with no mount:
412
+ * - `read` / `write` / `delete`: throw
413
+ * `no mount for path: ${path}`
414
+ * - `list` / `glob` / `grep`: empty iterator
415
+ * - `stat`: `{ kind: "missing" }` (`/` and exact mount prefixes
416
+ * are `{ kind: "directory" }`)
417
+ *
418
+ * Root `list` / `glob` / `grep` / `search` k-way merge already
419
+ * sorted sources. List and glob use `unique` so an earlier
420
+ * mount shadows a later one; grep and search keep every hit.
421
+ */
422
+ export declare function unionFs(mounts: Record<string, FileSystem>): FileSystem;
423
+ /**
424
+ * Same-root overlay: earlier layers win. Read-only.
425
+ *
426
+ * A downed layer costs its own files, not the overlay. Mutations
427
+ * throw `read-only mount` / `read-only mount: ${path}`. Empty
428
+ * `layers` throws `overlayFs needs at least one layer.`
429
+ */
430
+ export declare function overlayFs(layers: readonly FileSystem[]): FileSystem;
431
+ /**
432
+ * `HostFilesApi` as a FileSystem rooted at `/`.
433
+ *
434
+ * Mount it with `unionFs({ "/host": hostFs(files, scope) })`. The
435
+ * child never sees `/host` — `unionFs` owns the prefix. `scope` is
436
+ * the HostFiles partition, not a path prefix. `search` is empty
437
+ * (HostFiles is not an index).
438
+ */
439
+ export declare function hostFs(files: HostFilesApi, scope: HostFilesScope): FileSystem;
440
+ //# sourceMappingURL=filesystem.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../src/filesystem.ts"],"names":[],"mappings":"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"}