Interface: SandboxSearch

Defined in: src/batteries/sandbox/contracts/search.ts:6

Search capability; every result is lazy, complete, and terminal-framed.

Properties

Property	Modifier	Type	Description	Defined in
supportsFollow?	readonly	boolean	Whether this adapter can CONTAIN symlinked descendants when follow is enabled. rg --follow traverses links whose targets never pass through the path translator, so an uncontained backend turns follow: true into an unbounded read of wherever they point. The tools layer cannot inspect what is behind this interface, so an adapter declares it: omitted or false means the forged search_files/find_files schemas REJECT follow: true outright rather than accepting it and failing at execution. Set it only if you have verified containment; the bundled ripgrep adapter has not, and does not set it.	src/batteries/sandbox/contracts/search.ts:17

Methods

findPaths()

findPaths(o: {
  follow?: boolean;
  glob: string;
  hidden?: boolean;
  iglob?: string;
  limit?: number;
  maxDepth?: number;
  noIgnore?: boolean;
  root: string;
  signal?: AbortSignal;
}): AsyncIterable<PathFrame>;

Defined in: src/batteries/sandbox/contracts/search.ts:57

Lazily yield every matching path, then one done frame.

Parameters

Parameter	Type	Description
o	{ follow?: boolean; glob: string; hidden?: boolean; iglob?: string; limit?: number; maxDepth?: number; noIgnore?: boolean; root: string; signal?: AbortSignal; }	-
o.follow?	boolean	-
o.glob	string	-
o.hidden?	boolean	-
o.iglob?	string	-
o.limit?	number	Maximum results to yield. Omit for an unbounded search; an explicit value MUST be an integer >= 1, and adapters reject anything else — see searchContent (issue #48).
o.maxDepth?	number	Traversal depth. Omit for an unbounded scan; an explicit value must be a non-negative integer. Remarks An adapter MUST NOT name a depth on its own initiative when omitted — see searchContent.
o.noIgnore?	boolean	-
o.root	string	-
o.signal?	AbortSignal	-

Returns

AsyncIterable<PathFrame>

---

searchContent()

searchContent(o: {
  follow?: boolean;
  glob?: string;
  hidden?: boolean;
  iglob?: string;
  ignoreCase?: boolean;
  limit?: number;
  literal?: boolean;
  maxDepth?: number;
  noIgnore?: boolean;
  pattern: string;
  root: string;
  signal?: AbortSignal;
}): AsyncIterable<HitFrame>;

Defined in: src/batteries/sandbox/contracts/search.ts:19

Lazily yield every whole matching line, then one done frame.

Parameters

Parameter	Type	Description
o	{ follow?: boolean; glob?: string; hidden?: boolean; iglob?: string; ignoreCase?: boolean; limit?: number; literal?: boolean; maxDepth?: number; noIgnore?: boolean; pattern: string; root: string; signal?: AbortSignal; }	-
o.follow?	boolean	-
o.glob?	string	-
o.hidden?	boolean	-
o.iglob?	string	-
o.ignoreCase?	boolean	-
o.limit?	number	Maximum results to yield. Omit for an unbounded search; an explicit value MUST be an integer >= 1, and adapters reject anything else. Remarks Omission is the documented unbounded mode, NOT a default cap: every match is returned and the scan finishes { kind: 'done', complete: true }. There is deliberately no sentinel —undefined cannot be confused with an explicit number, so Infinity/NaN/0/negatives stay rejections even though they conceptually mean the same thing (issue #48). MEMORY: an unbounded search is collected by the adapter before results are yielded (rg's stdout is buffered whole), so peak memory grows in proportion to the OUTPUT on very large trees — an explicit limit truncates only after collection. Pass a limit (or maxDepth) wherever the tree size is untrusted or unknown.
o.literal?	boolean	-
o.maxDepth?	number	Traversal depth. Omit for an unbounded scan; an explicit value must be a non-negative integer. Remarks An adapter MUST NOT name a depth on its own initiative when omitted — the unbounded request is the caller's choice, and Number.MAX_SAFE_INTEGER is a disguised cap, not an implementation of it (issue #48).
o.noIgnore?	boolean	-
o.pattern	string	-
o.root	string	-
o.signal?	AbortSignal	-

Returns

AsyncIterable<HitFrame>