@linxiraos/pi-natives 1.0.0

package/native/index.d.ts

@@ -0,0 +1,2013 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * Default-microphone capture converted to mono `f32` at the requested sample
+ * rate.
+ */
+export declare class AudioCapture {
+  /** Open the default microphone and deliver low-latency mono PCM chunks. */
+  constructor(sampleRate: number, onAudio: (error: Error | null, samples: Float32Array) => void)
+  /** Stop capture immediately and release the microphone. */
+  stop(): void
+}
+
+/** Gapless mono `f32` playback through the default speaker. */
+export declare class AudioPlayback {
+  /** Open the default speaker at the requested logical sample rate. */
+  constructor(sampleRate: number)
+  /** Queue mono floating-point PCM in playback order. */
+  write(samples: Float32Array): void
+  /** Scale audio at render time so gain changes affect already queued samples. */
+  setGain(gain: number): void
+  /**
+   * Close input, wait until queued samples reach the speaker, then release
+   * it.
+   */
+  end(): Promise<void>
+  /** Stop immediately and discard all queued samples. */
+  stop(): void
+}
+
+/** Persistent, serialized native desktop capture/input/accessibility session. */
+export declare class DesktopSession {
+  constructor(options?: DesktopSessionOptions | undefined | null)
+  get capabilities(): DesktopCapabilities
+  listDisplays(): Promise<Array<DesktopDisplay>>
+  listWindows(): Promise<Array<DesktopWindow>>
+  capture(target: string, caps?: CaptureCaps | undefined | null): Promise<DesktopCapture>
+  click(target: string, x: number, y: number, opts?: PointerOptions | undefined | null): Promise<undefined>
+  moveMouse(target: string, x: number, y: number, opts?: PointerOptions | undefined | null): Promise<undefined>
+  drag(target: string, path: Array<DesktopPoint>, opts?: PointerOptions | undefined | null): Promise<undefined>
+  scroll(target: string, x: number, y: number, dx: number, dy: number, opts?: PointerOptions | undefined | null): Promise<undefined>
+  typeText(target: string, text: string, opts?: PointerOptions | undefined | null): Promise<undefined>
+  keyChord(target: string, keys: Array<string>, opts?: PointerOptions | undefined | null): Promise<undefined>
+  raiseWindow(windowId: string): Promise<undefined>
+  axSnapshot(target: string, opts?: AxSnapshotOptions | undefined | null): Promise<AxSnapshot>
+  axQuery(target: string, query: AxQuery): Promise<Array<AxNode>>
+  /**
+   * Accessibility hit-test at global logical desktop coordinates; needs no
+   * prior capture.
+   */
+  axElementAt(target: string, x: number, y: number): Promise<AxNode | undefined | null>
+  axFocused(): Promise<AxNode | undefined | null>
+  axNode(reference: string): Promise<AxNode>
+  axAttributes(reference: string): Promise<Array<[string, string]>>
+  axChildren(reference: string): Promise<Array<AxNode>>
+  axParent(reference: string): Promise<AxNode | undefined | null>
+  axPerform(reference: string, action: string): Promise<undefined>
+  axSetValue(reference: string, value: string): Promise<undefined>
+  axFocus(reference: string): Promise<undefined>
+  axClick(reference: string, opts?: PointerOptions | undefined | null): Promise<undefined>
+  close(): Promise<undefined>
+}
+
+/**
+ * Process-owned cross-platform advisory lock.
+ *
+ * `tryAcquire()` is non-blocking; its returned handle reports whether it won
+ * through `acquired`. Ownership ends on `release()`, garbage collection, or
+ * process exit; `release()` is idempotent.
+ */
+export declare class FileLock {
+  /** Try to acquire `path` without blocking. */
+  static tryAcquire(path: string): FileLock
+  /** Whether this handle owns the requested lock. */
+  get acquired(): boolean
+  /** Release this handle's ownership without affecting a successor. */
+  release(): void
+}
+
+/** WebRTC peer that accepts 16 kHz mono PCM and renders remote Opus audio. */
+export declare class LiveWebRtcPeer {
+  /**
+   * Create an idle peer and register its event, output-level, and failure
+   * callbacks.
+   */
+  constructor(onEvent: (error: Error | null, payload: string) => void, onLevel: (error: Error | null, level: number) => void, onFailure: (error: Error | null, message: string) => void)
+  /** Start the native media peer and return its SDP offer. */
+  createOffer(): Promise<string>
+  /** Apply the remote SDP answer returned by Codex signaling. */
+  acceptAnswer(sdp: string): Promise<void>
+  /** Wait until the `oai-events` data channel is open. */
+  waitForOpen(timeoutMs?: number | undefined | null): Promise<void>
+  /** Queue 16 kHz mono floating-point PCM for Opus transmission. */
+  pushAudio(samples: Float32Array): void
+  /**
+   * Enable or disable microphone transmission, discarding partial muted
+   * frames.
+   */
+  setMuted(muted: boolean): void
+  /** Close media, the data channel, the peer connection, and speaker playback. */
+  close(): Promise<void>
+}
+
+/**
+ * Long-lived macOS appearance observer.
+ *
+ * Subscribes to `AppleInterfaceThemeChangedNotification` via
+ * `CFDistributedNotificationCenter` and calls the provided callback
+ * with `"dark"` or `"light"` on each change (and once on start).
+ *
+ * A 2-second polling timer also runs as fallback — distributed
+ * notifications may not reliably reach background threads on all
+ * macOS versions.
+ *
+ * On non-macOS platforms, `start()` returns a no-op observer.
+ */
+export declare class MacAppearanceObserver {
+  static start(callback: (err: null | Error, appearance: MacOSAppearance) => void): MacAppearanceObserver
+  stop(): void
+}
+
+/**
+ * Long-lived macOS power assertion.
+ *
+ * On macOS this acquires one or more `IOKit` assertions that prevent the
+ * requested sleep modes until the handle is stopped or dropped. On other
+ * platforms it is a no-op handle so the caller can keep one cross-platform
+ * code path.
+ */
+export declare class MacOSPowerAssertion {
+  /**
+   * Acquire a macOS power assertion. On non-macOS platforms returns a
+   * no-op handle so callers can stay cross-platform.
+   */
+  static start(options?: MacOSPowerAssertionOptions | undefined | null): MacOSPowerAssertion
+  /**
+   * Release every assertion held by this handle. Safe to call multiple
+   * times; subsequent calls are a no-op.
+   */
+  stop(): void
+}
+
+/** Stable process reference. */
+export declare class Process {
+  /** Open a stable process reference from a PID. */
+  static fromPid(pid: number): Process | null
+  /** Open stable process references whose executable path matches exactly. */
+  static fromPath(path: string): Array<Process>
+  /** Operating-system process identifier for this process reference. */
+  get pid(): number
+  /** Parent process id for this process, when available. */
+  get ppid(): number | null
+  /** Launch arguments for this process. */
+  args(): Array<string>
+  /**
+   * Send `signal` to this process and its descendants, children first.
+   *
+   * On Linux and macOS the signal is forwarded as-is. On Windows there is no
+   * signal abstraction, so the `signal` argument is ignored and the entire
+   * tree is hard-killed via `TerminateProcess`. Defaults to the POSIX
+   * hard-kill signal.
+   */
+  killTree(signal?: number | undefined | null): number
+  /**
+   * Gracefully terminate this process and its descendants.
+   *
+   * By default this waits 1000ms after polite termination before
+   * hard-killing. Pass `graceful_ms < 0` to skip the graceful phase.
+   */
+  terminate(options?: ProcessTerminateOptions | undefined | null): Promise<boolean>
+  /**
+   * Wait until this process exits.
+   *
+   * When `options.timeout_ms` is omitted, waits until the process exits.
+   */
+  waitForExit(options?: ProcessWaitOptions | undefined | null): Promise<boolean>
+  /** Process group id for this process, when supported by the platform. */
+  groupId(): number | null
+  /** Direct children of this process as stable process references. */
+  children(): Array<Process>
+  /** Current status of this process reference. */
+  status(): ProcessStatus
+}
+
+/** Stateful PTY session for interactive stdin/stdout passthrough. */
+export declare class PtySession {
+  constructor()
+  /**
+   * Start a shell command, stream output chunks, and report the spawned child
+   * PID.
+   */
+  start(options: PtyStartOptions, onChunk?: ((error: Error | null, chunk: string) => void) | undefined | null, onStart?: ((error: Error | null, pid: number) => void) | undefined | null): Promise<PtyRunResult>
+  /**
+   * Start an executable with separate arguments, stream output chunks, and
+   * report the spawned child PID.
+   */
+  startArgv(options: PtyArgvStartOptions, onChunk?: ((error: Error | null, chunk: string) => void) | undefined | null, onStart?: ((error: Error | null, pid: number) => void) | undefined | null): Promise<PtyRunResult>
+  /** Write raw input bytes to PTY stdin. */
+  write(data: string): void
+  /** Resize the active PTY. */
+  resize(cols: number, rows: number): void
+  /** Force-kill the active PTY command. */
+  kill(): void
+}
+
+/** Persistent brush-core shell session. */
+export declare class Shell {
+  /**
+   * Create a new shell session from optional configuration.
+   *
+   * The options set session-scoped environment variables and a snapshot path.
+   */
+  constructor(options?: ShellOptions | undefined | null)
+  /**
+   * Run a shell command using the provided options.
+   *
+   * The `on_chunk` callback receives streamed stdout/stderr output. Returns
+   * the exit code when the command completes, or flags when cancelled or
+   * timed out.
+   */
+  run(options: ShellRunOptions, onChunk?: ((error: Error | null, chunk: string) => void) | undefined | null): Promise<ShellRunResult>
+  /**
+   * Abort all running commands for this shell session.
+   *
+   * Returns `Ok(())` even when no commands are running.
+   */
+  abort(): Promise<void>
+  /**
+   * Count live background jobs (`&`/`nohup` children still running) on this
+   * session. Completed jobs are reaped first. The host uses this to retain a
+   * per-call shell whose background processes are still running instead of
+   * dropping it (which would SIGKILL them via kill-on-drop).
+   */
+  liveBackgroundJobCount(): Promise<number>
+}
+
+/**
+ * Install the bounded Tokio runtime napi-rs adopts for async exports and the
+ * bounded Rayon global pool used by native parallel iterators.
+ *
+ * The JS loader calls this exactly once, synchronously, right *after* `dlopen`
+ * returns and *before* any async native or parallel iterator runs — never from
+ * `#[module_init]`. Building a multi-thread runtime eagerly spawns worker
+ * threads, and doing that during module init (while the dynamic-loader lock is
+ * held) deadlocks on some hosts: a fresh worker blocks acquiring the loader
+ * lock that the init thread still owns. napi-rs only materializes its runtime
+ * on the first async call (`RT` is a `LazyLock`) and
+ * `create_custom_tokio_runtime` merely records the runtime in a `OnceLock`, so
+ * installing it post-load is still honored.
+ *
+ * Without the Tokio override napi builds its own default (one worker per CPU,
+ * spawned eagerly), which aborts the process (`os error 1455`) on a
+ * memory-constrained Windows host before any JS error can surface;
+ * [`create_windows_napi_tokio_runtime`] pre-flights the spawn instead. Rayon
+ * has the same one-thread-per-core lazy default, so [`configure_rayon_pool`]
+ * installs a probed global pool before `count_tokens` or vendored `sort` can
+ * trigger it across a N-API nounwind boundary. If no worker thread is
+ * spawnable, patched Rayon callsites stay sequential rather than registering a
+ * current-thread-only global pool that cannot steal work from later native
+ * calls. Idempotent.
+ */
+export declare function __ompInstallTokioRuntime(): void
+
+/**
+ * Version sentinel — exists solely so the JS loader can prove at load time
+ * that the `.node` file on disk is from the same package release as the
+ * `index.js` ESM wrapper invoking it.
+ *
+ * The `js_name` is bumped by `scripts/release.ts` to match the new
+ * `Cargo.toml` / `package.json` version on every release. The JS loader
+ * computes the expected name from `package.json#version` and refuses to use
+ * a `.node` that doesn't expose it, turning the silent
+ * `<sym> is not a function` crash from a locked-file update (the canonical
+ * Windows `bun install -g` failure mode) into a clear load-time error.
+ *
+ * Bump policy: `__piNativesV{major}_{minor}_{patch}` — non-alphanumerics in
+ * the version string are mapped to `_` to keep it a valid JS identifier.
+ * MUST stay in sync with `VERSION_SENTINEL_EXPORT` in
+ * `packages/natives/native/index.js` (which derives the name from
+ * `package.json#version`).
+ */
+export declare function __piNativesV1_0_0(): void
+
+/**
+ * Apply ast-grep rewrite rules to matching files; honors `dryRun` and returns
+ * a promise.
+ */
+export declare function astEdit(options: AstReplaceOptions): Promise<AstReplaceResult>
+
+/** One ast-grep match with source range and optional meta-variables. */
+export interface AstFindMatch {
+  /** Display path of the matching file. */
+  path: string
+  /** Matched source text. */
+  text: string
+  /** Start byte offset in the file (UTF-8 byte index). */
+  byteStart: number
+  /** End byte offset in the file (exclusive UTF-8 byte index). */
+  byteEnd: number
+  /** 1-based start line. */
+  startLine: number
+  /** 1-based start column. */
+  startColumn: number
+  /** 1-based end line. */
+  endLine: number
+  /** 1-based end column. */
+  endColumn: number
+  /** Meta-variable name to captured text, when `includeMeta` was enabled. */
+  metaVariables?: Record<string, string>
+}
+
+/** Options for `astGrep`: patterns, scan scope, and match limits. */
+export interface AstFindOptions {
+  /** ast-grep patterns to search for (OR across patterns). */
+  patterns?: Array<string>
+  /** Language override; otherwise inferred from file extension per candidate. */
+  lang?: string
+  /** Single file or directory to scan (combined with `glob` when set). */
+  path?: string
+  /** Optional glob filter relative to the search root. */
+  glob?: string
+  /** Rule selector for multi-rule ast-grep configurations. */
+  selector?: string
+  /** Pattern strictness; defaults to smart matching when omitted. */
+  strictness?: AstMatchStrictness
+  /** Maximum matches to return after `offset` (default applies when omitted). */
+  limit?: number
+  /** Number of leading matches to skip before applying `limit`. */
+  offset?: number
+  /** When true, include meta-variable bindings per match. */
+  includeMeta?: boolean
+  /**
+   * Reserved for contextual snippets; not used by the current native find
+   * path.
+   */
+  context?: number
+  /** Optional cancellation handle (library-specific). */
+  signal?: unknown
+  /** Wall-clock timeout for the worker task in milliseconds. */
+  timeoutMs?: number
+}
+
+/** Aggregated search statistics and any parse or compile diagnostics. */
+export interface AstFindResult {
+  /** Page of matches after sort, offset, and limit. */
+  matches: Array<AstFindMatch>
+  /** Total matches found before paging (can exceed `matches.length`). */
+  totalMatches: number
+  /** Distinct files that contained at least one match. */
+  filesWithMatches: number
+  /** Files examined for the query. */
+  filesSearched: number
+  /** True when results were truncated by `limit`. */
+  limitReached: boolean
+  /** Non-fatal parse or pattern errors collected during the run. */
+  parseErrors?: Array<string>
+}
+
+/**
+ * Search source files with ast-grep patterns; returns a promise resolved on a
+ * worker thread.
+ */
+export declare function astGrep(options: AstFindOptions): Promise<AstFindResult>
+
+/**
+ * Match ast-grep patterns against an in-memory source string; returns a
+ * promise resolved on a worker thread.
+ *
+ * This is the file-free counterpart to [`ast_grep`]: callers that already hold
+ * the source (streaming buffers, generated code, editor contents) avoid a
+ * temp-file round trip. `lang` is required since there is no path to infer it
+ * from.
+ */
+export declare function astMatch(options: AstMatchOptions): Promise<AstMatchResult>
+
+/**
+ * Options for `astMatch`: run ast-grep patterns against an in-memory source
+ * string instead of files on disk.
+ */
+export interface AstMatchOptions {
+  /** Source code to match against (parsed in memory, never read from disk). */
+  source: string
+  /** Language of `source` (required; e.g. "ts", "tsx", "rust", "python"). */
+  lang: string
+  /** ast-grep patterns to search for (OR across patterns). */
+  patterns: Array<string>
+  /** Rule selector for multi-rule ast-grep configurations. */
+  selector?: string
+  /** Pattern strictness; defaults to smart matching when omitted. */
+  strictness?: AstMatchStrictness
+  /** Maximum matches to return after `offset` (default applies when omitted). */
+  limit?: number
+  /** Number of leading matches to skip before applying `limit`. */
+  offset?: number
+  /** When true, include meta-variable bindings per match. */
+  includeMeta?: boolean
+  /** Optional cancellation handle (library-specific). */
+  signal?: unknown
+  /** Wall-clock timeout for the worker task in milliseconds. */
+  timeoutMs?: number
+}
+
+/** Result of an in-memory `astMatch` run. */
+export interface AstMatchResult {
+  /** Page of matches after sort, offset, and limit. */
+  matches: Array<AstFindMatch>
+  /** Total matches found before paging (can exceed `matches.length`). */
+  totalMatches: number
+  /** True when results were truncated by `limit`. */
+  limitReached: boolean
+  /** Non-fatal parse or pattern-compile errors collected during the run. */
+  parseErrors?: Array<string>
+}
+
+/** ast-grep pattern strictness (controls how patterns match syntax). */
+export declare enum AstMatchStrictness {
+  /** Match at the concrete syntax tree level. */
+  Cst = 'cst',
+  /** Balanced default suitable for most searches. */
+  Smart = 'smart',
+  /** Match at the AST level. */
+  Ast = 'ast',
+  /** More permissive matching. */
+  Relaxed = 'relaxed',
+  /** Match structural signatures. */
+  Signature = 'signature',
+  /** Template-style pattern matching. */
+  Template = 'template'
+}
+
+/**
+ * One textual replacement applied to a file (before/after slice and
+ * coordinates).
+ */
+export interface AstReplaceChange {
+  /** File path for this change. */
+  path: string
+  /** Original matched text. */
+  before: string
+  /** Replacement text. */
+  after: string
+  /** Start byte offset of the replaced span. */
+  byteStart: number
+  /** End byte offset of the replaced span (exclusive). */
+  byteEnd: number
+  /**
+   * Length of deleted text in bytes (may differ from `byteEnd - byteStart`
+   * for edge cases).
+   */
+  deletedLength: number
+  /** 1-based start line of the match. */
+  startLine: number
+  /** 1-based start column. */
+  startColumn: number
+  /** 1-based end line. */
+  endLine: number
+  /** 1-based end column. */
+  endColumn: number
+}
+
+/** Per-file replacement count after an `astEdit` run. */
+export interface AstReplaceFileChange {
+  /** File that had replacements. */
+  path: string
+  /** Number of replacements in that file. */
+  count: number
+}
+
+/**
+ * Options for `astEdit`: rewrite rules, scan scope, safety limits, and
+ * dry-run.
+ */
+export interface AstReplaceOptions {
+  /** Map of pattern string to replacement template. */
+  rewrites?: Record<string, string>
+  /**
+   * Language override applied to every file; otherwise inferred per file, so
+   * mixed-language paths rewrite each file in its own language.
+   */
+  lang?: string
+  /** Single file or directory to rewrite. */
+  path?: string
+  /** Optional glob filter within the search root. */
+  glob?: string
+  /** Rule selector for multi-rule configurations. */
+  selector?: string
+  /** Pattern strictness for rewrites. */
+  strictness?: AstMatchStrictness
+  /** When true (default), compute changes without writing files. */
+  dryRun?: boolean
+  /** Cap on replacement applications across all files. */
+  maxReplacements?: number
+  /** Cap on distinct files that may be modified. */
+  maxFiles?: number
+  /** Fail the operation when a file cannot be parsed for rewriting. */
+  failOnParseError?: boolean
+  /** Optional cancellation handle. */
+  signal?: unknown
+  /** Wall-clock timeout for the worker task in milliseconds. */
+  timeoutMs?: number
+}
+
+/** Summary of an ast-grep rewrite pass, including whether disk writes occurred. */
+export interface AstReplaceResult {
+  /** Individual replacement records (may be large). */
+  changes: Array<AstReplaceChange>
+  /** Replacement counts grouped by file. */
+  fileChanges: Array<AstReplaceFileChange>
+  /** Total replacements applied or previewed. */
+  totalReplacements: number
+  /** Files that had at least one replacement. */
+  filesTouched: number
+  /** Files considered for rewriting. */
+  filesSearched: number
+  /** False when `dryRun` prevented writing. */
+  applied: boolean
+  /** True when limits stopped further replacements. */
+  limitReached: boolean
+  /** Parse or pattern errors when not failing the whole operation. */
+  parseErrors?: Array<string>
+}
+
+export interface AxNode {
+  ref: string
+  role: string
+  nativeRole: string
+  title?: string
+  value?: string
+  description?: string
+  enabled: boolean
+  focused: boolean
+  x?: number
+  y?: number
+  width?: number
+  height?: number
+  actions?: Array<string>
+  childCount: number
+}
+
+export interface AxQuery {
+  role?: string
+  title?: string
+  value?: string
+  limit?: number
+}
+
+export interface AxSnapshot {
+  text: string
+  nodeCount: number
+  truncated: boolean
+}
+
+export interface AxSnapshotOptions {
+  maxDepth?: number
+  maxNodes?: number
+  all?: boolean
+}
+
+export interface BlockRange {
+  /** 1-indexed inclusive first line of the resolved block. */
+  startLine: number
+  /** 1-indexed inclusive last line of the resolved block. */
+  endLine: number
+}
+
+/**
+ * Find the outermost named tree-sitter node that begins on `options.line`.
+ *
+ * Returns its 1-indexed inclusive line span, or `null` when the language is
+ * unrecognized, the line is out of range / blank, no node begins on that line,
+ * or the resolved subtree contains a syntax error.
+ */
+export declare function blockRangeAt(options: BlockRangeOptions): BlockRange | null
+
+export interface BlockRangeOptions {
+  /** Source code to inspect. */
+  code: string
+  /** Language alias (e.g. "rust", "typescript") used before path inference. */
+  lang?: string
+  /** File path used to infer language by extension when `lang` is omitted. */
+  path?: string
+  /** 1-indexed source line the block must begin on. */
+  line: number
+}
+
+export interface CaptureCaps {
+  maxWidth?: number
+  maxHeight?: number
+}
+
+/** Clipboard image payload encoded as PNG bytes. */
+export interface ClipboardImage {
+  /** PNG-encoded image bytes. */
+  data: Uint8Array
+  /** MIME type for the encoded image payload. */
+  mimeType: string
+}
+
+/** A context line (before or after a match). */
+export interface ContextLine {
+  /** 1-indexed line number in the source file. */
+  lineNumber: number
+  /** Raw line content (trimmed line ending). */
+  line: string
+}
+
+/**
+ * Copy plain text to the system clipboard.
+ *
+ * # Parameters
+ * - `text`: UTF-8 text to place on the clipboard.
+ *
+ * # Errors
+ * Returns an error if clipboard access fails.
+ */
+export declare function copyToClipboard(text: string): void
+
+/**
+ * All pairs `(i, j)` with `i < j` whose cosine similarity meets `threshold`.
+ *
+ * `vectors` is `count` vectors flattened row-major at `dim` `f64` elements
+ * per row (zero-padded, which matches the TS `?? 0` missing-element
+ * semantics), so the similarity is bit-identical to the TS pairwise loop in
+ * `clusterBySimilarity`. Returns pairs flattened as `[i0, j0, i1, j1, ...]`
+ * in the same `(i, j)` visit order as the TS nested loop.
+ */
+export declare function cosineSimilarityPairs(vectors: Float64Array, count: number, dim: number, threshold: number): Uint32Array
+
+/**
+ * Count tokens in `input`.
+ *
+ * `input` may be a single string or an array of strings; an array returns
+ * the sum across all elements (encoded in parallel via rayon when the global
+ * pool is available). Always returns a single token total — use this for any
+ * aggregate budget question without paying a per-element napi crossing.
+ *
+ * Uses ordinary encoding (no special-token handling), which is the right
+ * choice for measuring user/model content rather than wire-protocol tokens.
+ * Defaults to `o200k_base`; pass `Cl100kBase` for older `OpenAI` models.
+ */
+export declare function countTokens(input: string | Array<string>, encoding?: Encoding | undefined | null): number
+
+export interface DesktopCapabilities {
+  backend: string
+  displayServer?: string
+  capture: boolean
+  input: boolean
+  ax: boolean
+  backgroundWindowInput: boolean
+  deliveryModes: Array<string>
+  capturePermission: string
+  inputPermission: string
+  axPermission: string
+  displayCount: number
+}
+
+export interface DesktopCapture {
+  data: Uint8Array
+  width: number
+  height: number
+  /** Pre-scaling capture width in native pixels; equals `width` when unscaled. */
+  sourceWidth: number
+  /**
+   * Pre-scaling capture height in native pixels; equals `height` when
+   * unscaled.
+   */
+  sourceHeight: number
+  target: string
+  displays: Array<DesktopDisplay>
+  backend: string
+  displayServer?: string
+}
+
+/**
+ * Monitor geometry in both global logical desktop coordinates and composite
+ * screenshot pixels.
+ */
+export interface DesktopDisplay {
+  id: string
+  name: string
+  x: number
+  y: number
+  width: number
+  height: number
+  scale: number
+  pixelX: number
+  pixelY: number
+  pixelWidth: number
+  pixelHeight: number
+  isPrimary: boolean
+}
+
+export interface DesktopPoint {
+  x: number
+  y: number
+}
+
+export interface DesktopSessionOptions {
+  display?: string
+}
+
+/** One capturable top-level window in global logical desktop coordinates. */
+export interface DesktopWindow {
+  /**
+   * Backend-defined opaque window id, valid as a capture target while the
+   * window lives. Numeric on X11/Win32/macOS; a composite AT-SPI string on
+   * Wayland (e.g. `atspi::1.31:/org/a11y/atspi/accessible/1`). Never parse
+   * it.
+   */
+  id: string
+  /** Window title; may be empty for untitled windows. */
+  title: string
+  /** Owning application name. */
+  app: string
+  /** Owning process id when the platform exposes it. */
+  pid?: number
+  x: number
+  y: number
+  width: number
+  height: number
+  /** Whether the window currently holds input focus. */
+  focused: boolean
+}
+
+/**
+ * Detect macOS system appearance via CoreFoundation.
+ * Returns `"dark"` or `"light"` on macOS, `null` on other platforms.
+ */
+export declare function detectMacOSAppearance(): MacOSAppearance | null
+
+/**
+ * Generate an Apple `DeviceCheck` attestation token.
+ *
+ * Resolves with the token (or the error reason) after at most a 1-second
+ * wait, matching the upstream `devicecheck.node` addon contract.
+ */
+export declare function deviceCheckGenerateToken(): Promise<DeviceCheckTokenResult>
+
+/** Outcome of a single `DCDevice.generateToken` request. */
+export interface DeviceCheckTokenResult {
+  /** Whether `DCDevice.isSupported` reported attestation support. */
+  supported: boolean
+  /**
+   * Base64-encoded `DeviceCheck` token; present only when generation
+   * succeeded.
+   */
+  tokenBase64?: string
+  /** Human-readable failure reason when no token was produced. */
+  error?: string
+  /** Wall-clock time spent in the native call, in milliseconds. */
+  latencyMs: number
+}
+
+/** One jsdiff change object: a run of added, removed, or common tokens. */
+export interface DiffChange {
+  /** Joined token text for this run (lines keep their `
+  ` terminators). */
+  value: string
+  /** Number of tokens in this run. */
+  count: number
+  /** True when this run exists only in the new text. */
+  added: boolean
+  /** True when this run exists only in the old text. */
+  removed: boolean
+}
+
+/**
+ * Diff `oldText.split("
+")` against `newText.split("
+")` with jsdiff
+ * `diffArrays` semantics (exact code-unit equality, empty lines preserved),
+ * returning only run lengths.
+ *
+ * Callers that map line numbers — like hashline recovery — need the counts,
+ * not another copy of the text.
+ */
+export declare function diffLineRuns(oldText: string, newText: string): Array<DiffRun>
+
+/**
+ * Line diff with jsdiff `diffLines(oldText, newText)` semantics (default
+ * options). Change values keep line terminators, and common runs are joined
+ * from the new text.
+ */
+export declare function diffLines(oldText: string, newText: string): Array<DiffChange>
+
+/** A change run without its token text, for callers that only need counts. */
+export interface DiffRun {
+  /** Number of tokens in this run. */
+  count: number
+  /** True when this run exists only in the new text. */
+  added: boolean
+  /** True when this run exists only in the old text. */
+  removed: boolean
+}
+
+/**
+ * Word diff with jsdiff `diffWords(oldText, newText)` semantics (default
+ * options).
+ *
+ * Tokens carry surrounding whitespace, equality ignores it, and the
+ * post-pass dedupes whitespace across change boundaries.
+ */
+export declare function diffWords(oldText: string, newText: string): Array<DiffChange>
+
+/** Ellipsis strategy for [`truncate_to_width`]. */
+export declare enum Ellipsis {
+  /** Use a single Unicode ellipsis character ("…"). */
+  Unicode = 0,
+  /** Use three ASCII dots ("..."). */
+  Ascii = 1,
+  /** Omit ellipsis entirely. */
+  Omit = 2
+}
+
+/**
+ * Matching-bracket context for an arbitrary tree-sitter language.
+ *
+ * For each multi-line named node whose span crosses the visible window, return
+ * the boundary line sitting *outside* that window (the closer when the opener
+ * is shown, the opener when the closer is shown). Covers brace and indentation
+ * languages alike using real syntactic spans.
+ *
+ * Returns `null` when the language is unrecognized or the source fails to
+ * parse / carries a syntax error (caller should fall back to a lexical scan);
+ * a sorted, unique list of 1-indexed boundary lines otherwise.
+ */
+export declare function enclosingBlockBoundaries(options: EnclosingBoundaryOptions): Array<number> | null
+
+export interface EnclosingBoundaryOptions {
+  /** Source code to inspect. */
+  code: string
+  /** Language alias (e.g. "rust", "typescript") used before path inference. */
+  lang?: string
+  /** File path used to infer language by extension when `lang` is omitted. */
+  path?: string
+  /** 1-indexed inclusive visible line ranges (the lines actually shown). */
+  ranges: Array<LineRange>
+}
+
+/**
+ * Encode image bytes into a SIXEL escape sequence for terminal rendering.
+ *
+ * The input image is decoded and resized to the requested pixel dimensions
+ * before encoding.
+ *
+ * # Errors
+ * Returns an error if decoding, resizing, or SIXEL encoding fails.
+ */
+export declare function encodeSixel(bytes: Uint8Array, targetWidthPx: number, targetHeightPx: number): string
+
+/** Tokenizer encoding to use. */
+export declare enum Encoding {
+  /** GPT-4o / o1 / GPT-5 (default). */
+  O200kBase = 'O200kBase',
+  /** GPT-3.5 / GPT-4 / older. */
+  Cl100kBase = 'Cl100kBase'
+}
+
+/**
+ * Execute a brush shell command.
+ *
+ * Creates a fresh session for each call. The `on_chunk` callback receives
+ * streamed stdout/stderr output. Returns the exit code when the command
+ * completes, or flags when cancelled or timed out.
+ */
+export declare function executeShell(options: ShellExecuteOptions, onChunk?: ((error: Error | null, chunk: string) => void) | undefined | null): Promise<ShellRunResult>
+
+/**
+ * Extract the before/after slices around an overlay region.
+ *
+ * Preserves ANSI state so the `after` segment renders correctly after
+ * truncation.
+ */
+export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean, tabWidth: number): ExtractSegmentsResult
+
+/** Before/after UTF-16 segments around an overlay region, with measured widths. */
+export interface ExtractSegmentsResult {
+  /** UTF-16 content before the overlay region. */
+  before: string
+  /** Visible width of the `before` segment. */
+  beforeWidth: number
+  /** UTF-16 content after the overlay region. */
+  after: string
+  /** Visible width of the `after` segment. */
+  afterWidth: number
+}
+
+/** Resolved filesystem entry kind for glob filters and match metadata. */
+export declare enum FileType {
+  /** Regular file. */
+  File = 1,
+  /** Directory. */
+  Dir = 2,
+  /** Symbolic link. */
+  Symlink = 3
+}
+
+/** Fuzzy file path search for autocomplete. */
+export declare function fuzzyFind(options: FuzzyFindOptions): Promise<FuzzyFindResult>
+
+/** A single match in fuzzy find results. */
+export interface FuzzyFindMatch {
+  /** Relative path from the search root (uses `/` separators). */
+  path: string
+  /** Whether this entry is a directory. */
+  isDirectory: boolean
+  /** Match quality score (higher is better). */
+  score: number
+}
+
+/** Options for fuzzy file path search. */
+export interface FuzzyFindOptions {
+  /** Fuzzy query to match against file paths (case-insensitive). */
+  query: string
+  /** Directory to search. */
+  path: string
+  /** Include hidden files (default: false). */
+  hidden?: boolean
+  /** Respect .gitignore (default: true). */
+  gitignore?: boolean
+  /** Enable walker scan caching (default: false). */
+  cache?: boolean
+  /** Maximum number of matches to return (default: 100). */
+  maxResults?: number
+  /** Abort signal for cancelling the operation. */
+  signal?: unknown
+  /** Timeout in milliseconds for the operation. */
+  timeoutMs?: number
+}
+
+/** Result of fuzzy file path search. */
+export interface FuzzyFindResult {
+  /** Matched entries (up to `maxResults`). */
+  matches: Array<FuzzyFindMatch>
+  /** Total number of matches found (may exceed `matches.len()`). */
+  totalMatches: number
+}
+
+/** Get list of supported languages. */
+export declare function getSupportedLanguages(): Array<string>
+
+/**
+ * Get work profile data from the last N seconds.
+ *
+ * Always-on profiling - no need to start/stop. Just call this to get
+ * recent activity.
+ */
+export declare function getWorkProfile(lastSeconds: number): WorkProfile
+
+/**
+ * Find filesystem entries matching a glob pattern.
+ *
+ * Resolves the search root, scans entries, applies glob and optional file-type
+ * filters, and optionally streams each accepted match through `on_match`.
+ *
+ * When `sortByMtime` is enabled, the walker ranks matches by mtime before the
+ * native layer applies final symlink-aware file-type filtering and callback
+ * emission.
+ *
+ * # Errors
+ * Returns an error when the search path cannot be resolved, the path is not a
+ * directory, the glob pattern is invalid, or cancellation/timeout is
+ * triggered.
+ */
+export declare function glob(options: GlobOptions, onMatch?: ((error: Error | null, match: GlobMatch) => void) | undefined | null): Promise<GlobResult>
+
+/** A single filesystem entry from a directory scan. */
+export interface GlobMatch {
+  /** Relative path from the search root, using forward slashes. */
+  path: string
+  /** Resolved filesystem type for the match. */
+  fileType: FileType
+  /** Modification time in milliseconds since Unix epoch. */
+  mtime?: number
+  /** File size in bytes for regular files. */
+  size?: number
+}
+
+/** Input options for `glob`, including traversal, filtering, and cancellation. */
+export interface GlobOptions {
+  /** Glob pattern to match (e.g., "*.ts"). */
+  pattern: string
+  /** Directory to search. */
+  path: string
+  /**
+   * Filter by file type: "file", "dir", or "symlink". Symlinks are
+   * matched for file/dir filters based on their target type.
+   */
+  fileType?: FileType
+  /** Match simple patterns recursively by default (`*.ts` -> recursive). */
+  recursive?: boolean
+  /** Include hidden files (default: false). */
+  hidden?: boolean
+  /** Maximum number of results to return. */
+  maxResults?: number
+  /** Respect .gitignore files (default: true). */
+  gitignore?: boolean
+  /** Enable walker scan caching (default: false). */
+  cache?: boolean
+  /** Sort results by mtime (most recent first) before applying limit. */
+  sortByMtime?: boolean
+  /**
+   * Include `node_modules` entries when the pattern does not explicitly
+   * mention them.
+   */
+  includeNodeModules?: boolean
+  /** Abort signal for cancelling the operation. */
+  signal?: unknown
+  /** Timeout in milliseconds for the operation. */
+  timeoutMs?: number
+}
+
+/** Result payload returned by a glob operation. */
+export interface GlobResult {
+  /** Matched filesystem entries. */
+  matches: Array<GlobMatch>
+  /** Number of returned matches (`matches.len()`), clamped to `u32::MAX`. */
+  totalMatches: number
+}
+
+/**
+ * Search files for a regex pattern.
+ *
+ * # Arguments
+ * - `options`: Pattern, path, filters, and output mode.
+ * - `on_match`: Optional callback invoked per match/result.
+ *
+ * # Returns
+ * Aggregated results across matching files.
+ */
+export declare function grep(options: GrepOptions, onMatch?: ((error: Error | null, match: GrepMatch) => void) | undefined | null): Promise<GrepResult>
+
+/** A single match in a grep result. */
+export interface GrepMatch {
+  /** File path for the match (relative for directory searches). */
+  path: string
+  /** 1-indexed line number (0 for count-only entries). */
+  lineNumber: number
+  /** The matched line content (empty for count-only entries). */
+  line: string
+  /** Context lines before the match. */
+  contextBefore?: Array<ContextLine>
+  /** Context lines after the match. */
+  contextAfter?: Array<ContextLine>
+  /** Whether the line was truncated. */
+  truncated?: boolean
+  /** Per-file match count (count mode only). */
+  matchCount?: number
+}
+
+/** Options for searching files on disk. */
+export interface GrepOptions {
+  /** Regex pattern to search for. */
+  pattern: string
+  /** Directory or file to search. */
+  path: string
+  /** Glob filter for filenames (e.g., "*.ts"). */
+  glob?: string
+  /** Filter by file type (e.g., "js", "py", "rust"). */
+  type?: string
+  /** Case-insensitive search. */
+  ignoreCase?: boolean
+  /** Enable multiline matching. */
+  multiline?: boolean
+  /** Include hidden files (default: true). */
+  hidden?: boolean
+  /** Respect .gitignore files (default: true). */
+  gitignore?: boolean
+  /** Maximum number of matches to return. */
+  maxCount?: number
+  /** Skip first N matches. */
+  offset?: number
+  /** Lines of context before matches. */
+  contextBefore?: number
+  /** Lines of context after matches. */
+  contextAfter?: number
+  /** Lines of context before/after matches (legacy). */
+  context?: number
+  /** Truncate lines longer than this (characters). */
+  maxColumns?: number
+  /** Output mode (content, filesWithMatches, or count). */
+  mode?: GrepOutputMode
+  /**
+   * Maximum matches collected per file (content mode). Keeps one hot file
+   * from exhausting the global `max_count` budget before other files are
+   * reached.
+   */
+  maxCountPerFile?: number
+  /** Abort signal for cancelling the operation. */
+  signal?: unknown
+  /** Timeout in milliseconds for the operation. */
+  timeoutMs?: number
+}
+
+/** Output mode for [`search`] and [`grep`] (string values match JS callers). */
+export declare enum GrepOutputMode {
+  /** Emit matched lines (and optional context lines). */
+  Content = 'content',
+  /** Emit per-file or total counts instead of line content. */
+  Count = 'count',
+  /** Emit one row per file that matched, without line content. */
+  FilesWithMatches = 'filesWithMatches'
+}
+
+/** Result of searching files. */
+export interface GrepResult {
+  /** Matches or per-file counts, depending on output mode. */
+  matches: Array<GrepMatch>
+  /**
+   * Total matches across all files, or matched file count in filesWithMatches
+   * mode.
+   */
+  totalMatches: number
+  /** Number of files with at least one match. */
+  filesWithMatches: number
+  /** Number of files searched. */
+  filesSearched: number
+  /** Whether the limit/offset stopped the search early. */
+  limitReached?: boolean
+  /** Number of files skipped because they exceed the size limit. */
+  skippedOversized?: number
+}
+
+/**
+ * Quick check if content matches a pattern.
+ *
+ * # Arguments
+ * - `content`: `Uint8Array`/`Buffer` (zero-copy) or `string` (UTF-8).
+ * - `pattern`: `Uint8Array`/`Buffer` (zero-copy) or `string` (UTF-8).
+ * - `ignore_case`: Case-insensitive matching.
+ * - `multiline`: Enable multiline regex mode.
+ *
+ * # Returns
+ * True if any match exists; false on no match.
+ */
+export declare function hasMatch(content: string | Uint8Array, pattern: string | Uint8Array, ignoreCase?: boolean | undefined | null, multiline?: boolean | undefined | null): boolean
+
+/**
+ * Highlight code and return ANSI-colored lines.
+ *
+ * # Arguments
+ * * `code` - The source code to highlight
+ * * `lang` - Language identifier (e.g., "rust", "typescript", "python")
+ * * `colors` - Theme colors as ANSI escape sequences
+ *
+ * # Returns
+ * Highlighted code with ANSI color codes, or the original code if highlighting
+ * fails.
+ */
+export declare function highlightCode(code: string, lang: string | undefined | null, colors: HighlightColors): string
+
+/**
+ * Theme colors for syntax highlighting.
+ * Each color is an ANSI escape sequence (e.g., "\x1b[38;2;255;0;0m").
+ */
+export interface HighlightColors {
+  /** ANSI color for comments. */
+  comment: string
+  /** ANSI color for keywords. */
+  keyword: string
+  /** ANSI color for function names. */
+  function: string
+  /** ANSI color for variables and identifiers. */
+  variable: string
+  /** ANSI color for string literals. */
+  string: string
+  /** ANSI color for numeric literals. */
+  number: string
+  /** ANSI color for type identifiers. */
+  type: string
+  /** ANSI color for operators. */
+  operator: string
+  /** ANSI color for punctuation tokens. */
+  punctuation: string
+  /** ANSI color for diff inserted lines. */
+  inserted?: string
+  /** ANSI color for diff deleted lines. */
+  deleted?: string
+}
+
+/**
+ * Convert HTML source to Markdown with optional preprocessing.
+ *
+ * # Errors
+ * Returns an error if the conversion fails or the worker task aborts.
+ */
+export declare function htmlToMarkdown(html: string, options?: HtmlToMarkdownOptions | undefined | null): Promise<string>
+
+/** Options for HTML to Markdown conversion. */
+export interface HtmlToMarkdownOptions {
+  /** Remove navigation elements, forms, headers, footers. */
+  cleanContent?: boolean
+  /** Skip images during conversion. */
+  skipImages?: boolean
+}
+
+/**
+ * Invalidate the walker scan cache.
+ *
+ * When called with a path, removes entries for roots containing that path.
+ * When called without a path, clears the entire cache.
+ *
+ * Intended to be called after agent file mutations: write, edit, rename, or
+ * delete.
+ */
+export declare function invalidateFsScanCache(path?: string | undefined | null): void
+
+/** Kind enum of the backend selected by default for this build target. */
+export declare function isoBackend(): IsoBackendKind
+
+/**
+ * Isolation backend identifier. Numeric so the JS side can `switch` on
+ * the enum without string comparisons.
+ */
+export declare enum IsoBackendKind {
+  Apfs = 0,
+  Btrfs = 1,
+  Zfs = 2,
+  LinuxReflink = 3,
+  Overlayfs = 4,
+  WindowsBlockClone = 5,
+  Projfs = 6,
+  Rcopy = 7
+}
+
+/** How a single file changed between `lower` and `merged`. */
+export declare enum IsoChangeKind {
+  Added = 0,
+  Modified = 1,
+  Removed = 2
+}
+
+/**
+ * Capture the changes between `lower` and `merged`.
+ *
+ * Uses [`pi_iso::IsolationBackend::diff`]'s default implementation —
+ * `git diff` when `merged/.git` exists, otherwise a mtime-skipped tree
+ * walk. The backend selection only affects the lifecycle methods; diff
+ * behaviour is uniform.
+ */
+export declare function isoDiff(lower: string, merged: string): Promise<IsoDiff>
+
+export interface IsoDiff {
+  files: Array<IsoFileChange>
+}
+
+/** One entry in an [`IsoDiff`]. */
+export interface IsoFileChange {
+  /** Path relative to `merged`. */
+  path: string
+  op: IsoChangeKind
+  /**
+   * Unified-diff text. `None` (`null` in JS) means the file is binary;
+   * read it directly from `merged` if you need the bytes.
+   */
+  diff?: string
+}
+
+/**
+ * True if `message` is an error message produced by [`IsoError::Unavailable`].
+ * Use this to distinguish "this backend isn't installed" from a hard
+ * failure when handling caught errors on the JS side.
+ */
+export declare function isoIsUnavailableError(message: string): boolean
+
+/**
+ * Probe whether the requested backend can start on this host. Pass
+ * `null`/omit `kind` to probe the platform-native backend.
+ */
+export declare function isoProbe(kind?: IsoBackendKind | undefined | null): IsoProbeResult
+
+/** Probe result for a specific isolation backend. */
+export interface IsoProbeResult {
+  /** True when the backend's prerequisites are satisfied. */
+  available: boolean
+  /** Human-readable explanation when `available` is false. */
+  reason?: string
+  /** Resolved backend kind. */
+  kind: IsoBackendKind
+}
+
+/**
+ * Pick the best backend available right now. `preferred` is treated as
+ * a hint — see [`pi_iso::resolve`] for the exact priority rules.
+ */
+export declare function isoResolve(preferred?: IsoBackendKind | undefined | null): IsoResolveResult
+
+/** Outcome of [`iso_resolve`]. */
+export interface IsoResolveResult {
+  /** Backend that will actually be tried first. */
+  kind: IsoBackendKind
+  /** Host-available backends in retry order, starting with `kind`. */
+  candidates: Array<IsoBackendKind>
+  /**
+   * True when the resolver fell back from `preferred` (or from the
+   * first automatic candidate) to a different backend.
+   */
+  fellBack: boolean
+  /** Human-readable reason for the fallback, if any. */
+  reason?: string
+}
+
+/**
+ * Materialise `merged` as a writable view of `lower` using the requested
+ * backend. `kind` defaults to the native backend.
+ */
+export declare function isoStart(kind: IsoBackendKind | undefined | null, lower: string, merged: string): Promise<void>
+
+/** Tear down a previously started backend at `merged`. */
+export declare function isoStop(kind: IsoBackendKind | undefined | null, merged: string): Promise<void>
+
+/** Event types from Kitty keyboard protocol (flag 2). */
+export declare enum KeyEventType {
+  /** Key press event. */
+  Press = 1,
+  /** Key repeat event. */
+  Repeat = 2,
+  /** Key release event. */
+  Release = 3
+}
+
+export interface LineRange {
+  /** 1-indexed inclusive first visible line. */
+  startLine: number
+  /** 1-indexed inclusive last visible line. */
+  endLine: number
+}
+
+/**
+ * Walk the workspace once and return tree entries plus AGENTS.md candidates.
+ *
+ * File-level ignore rules for AGENTS.md are bypassed by checking each
+ * traversed directory directly when `collectAgentsMd` is enabled, but ignored
+ * directories are still pruned by the walker and are not searched.
+ */
+export declare function listWorkspace(options: ListWorkspaceOptions): Promise<ListWorkspaceResult>
+
+/** Input options for `listWorkspace`, the single-pass workspace startup scan. */
+export interface ListWorkspaceOptions {
+  /** Directory to scan. */
+  path: string
+  /** Maximum depth for returned tree entries. Root children are depth 1. */
+  maxDepth: number
+  /** Include hidden files and directories. Default: false. */
+  hidden?: boolean
+  /** Respect .gitignore files. Default: true. */
+  gitignore?: boolean
+  /**
+   * Also surface AGENTS.md files in directories at depth 1..=4, even when
+   * gitignore would otherwise hide the file. Walks deeper than `maxDepth`
+   * to find them. Default: false.
+   */
+  collectAgentsMd?: boolean
+  /** Timeout in milliseconds for the operation. */
+  timeoutMs?: number
+  /** Abort signal for cancelling the operation. */
+  signal?: unknown
+}
+
+/** Result payload returned by a workspace scan. */
+export interface ListWorkspaceResult {
+  /** Entries within `maxDepth`, with mtime and regular-file size metadata. */
+  entries: Array<GlobMatch>
+  /**
+   * Directory-scoped AGENTS.md files within depth 1..=4 (capped at 200).
+   * Always empty when `collectAgentsMd` is false.
+   */
+  agentsMdFiles: Array<string>
+  /** True when any output cap was hit. */
+  truncated: boolean
+}
+
+/**
+ * System UI appearance reported by native macOS APIs (`detectMacOSAppearance`
+ * and observer).
+ */
+export declare enum MacOSAppearance {
+  /** Dark color scheme. */
+  Dark = 'dark',
+  /** Light color scheme. */
+  Light = 'light'
+}
+
+/**
+ * Options for starting a macOS power assertion.
+ *
+ * Each boolean maps to a `caffeinate(8)` flag and a corresponding `IOKit`
+ * `IOPMAssertion` type. Multiple flags can be combined; when set, one
+ * assertion is taken per flag and all are released together when the
+ * handle is stopped or dropped.
+ *
+ * If every flag is unset (or omitted), the handle behaves as if `idle`
+ * were `true` — preserving the historical default of `caffeinate -i`.
+ */
+export interface MacOSPowerAssertionOptions {
+  /** Human-readable reason shown in macOS power diagnostics. */
+  reason?: string
+  /** `caffeinate -i`: prevent the system from idle-sleeping. */
+  idle?: boolean
+  /** `caffeinate -s`: prevent the system from sleeping (AC power only). */
+  system?: boolean
+  /** `caffeinate -u`: declare the user is active (wakes the display). */
+  user?: boolean
+  /** `caffeinate -d`: prevent the display from idle-sleeping. */
+  display?: boolean
+}
+
+/** A single match in the content. */
+export interface Match {
+  /** 1-indexed line number. */
+  lineNumber: number
+  /** The matched line content. */
+  line: string
+  /** Context lines before the match. */
+  contextBefore?: Array<ContextLine>
+  /** Context lines after the match. */
+  contextAfter?: Array<ContextLine>
+  /** Whether the line was truncated. */
+  truncated?: boolean
+}
+
+/**
+ * Match input data against a key identifier string.
+ *
+ * Returns true when the bytes represent the specified key with modifiers.
+ */
+export declare function matchesKey(data: string, keyId: string, kittyProtocolActive: boolean): boolean
+
+/**
+ * Match Kitty protocol input against a codepoint and modifier mask.
+ *
+ * Returns true when the parsed sequence matches the expected codepoint (or
+ * base layout key) and modifier bits.
+ */
+export declare function matchesKittySequence(data: string, expectedCodepoint: number, expectedModifier: number): boolean
+
+/**
+ * Check if input matches a legacy escape sequence for the given key name.
+ *
+ * Returns true only when the byte sequence maps to the exact key identifier.
+ */
+export declare function matchesLegacySequence(data: string, keyName: string): boolean
+
+/** N-API opt-in handle for the minimizer. */
+export interface MinimizerOptions {
+  /** Master switch. Absent / false = disabled. */
+  enabled?: boolean
+  /**
+   * Optional path to a TOML settings file whose values override
+   * field-level defaults. `~` is expanded.
+   */
+  settingsPath?: string
+  /**
+   * Optional xxHash64 digest (hex) of the settings file contents. When
+   * supplied, the engine refuses to honor a settings file whose hash does
+   * not match — a lightweight trust gate for agent-controllable paths.
+   */
+  settingsHash?: string
+  /**
+   * Opt-in allowlist of program names (e.g. `"git"`). When empty or
+   * absent, all built-in filters are active.
+   */
+  only?: Array<string>
+  /** Program names explicitly excluded from minimization. */
+  except?: Array<string>
+  /**
+   * Maximum captured bytes per command before the engine falls back to
+   * the raw, un-minimized output. Default 4 MiB.
+   */
+  maxCaptureBytes?: number
+  /**
+   * Source-outline level for `cat <source-file>` minimization. Accepts
+   * `"default"` (current behavior) or `"aggressive"` (strip function bodies).
+   */
+  sourceOutlineLevel?: string
+  /**
+   * Kill-switch to fall back to the pre-PR (legacy) filter behavior for
+   * grep / find / pytest. When `Some(true)`, filters that opted into the
+   * always-shrink Tier 1 / Tier 2 behavior skip the new code path. When
+   * `None`, defers to the `OMP_MINIMIZER_LEGACY_FILTERS` env var.
+   */
+  legacyFilters?: boolean
+}
+
+/**
+ * Telemetry for a single minimization.
+ *
+ * Surfaced when the minimizer actually rewrote the command's output. The
+ * session layer is expected to persist `original_text` via its
+ * `ArtifactManager`, splice the resulting `artifact://<id>` reference
+ * into `text`, and replace any previously streamed raw output with the
+ * minimized text.
+ */
+export interface MinimizerResult {
+  /**
+   * Dispatch label produced by the minimizer (e.g. `"git"`,
+   * `"pipeline:gradle"`, `"pipeline+builtin"`).
+   */
+  filter: string
+  /**
+   * The minimized replacement text. Callers that streamed raw chunks
+   * during execution should clear and replace their accumulated output
+   * with this text.
+   */
+  text: string
+  /** The full original capture, before minimization. */
+  originalText: string
+  /** Captured byte length before minimization. */
+  inputBytes: number
+  /** Byte length of the minimized text the consumer received. */
+  outputBytes: number
+}
+
+/**
+ * MMR selection over pre-sorted candidates using Jaccard word similarity.
+ *
+ * `contents[i]` and `scores[i]` describe candidate `i`, already sorted by
+ * relevance exactly as the TS `mmrRerank` sorts them (the JS stable sort
+ * stays on the TS side so its tie and NaN semantics are preserved).
+ * Replicates the TS selection loop exactly: candidate `0` is always taken
+ * first; each round picks the remaining candidate maximizing
+ * `lambda * score - (1 - lambda) * maxSimilarity(selected)` with strict
+ * `>` comparisons, so ties keep the earliest remaining candidate — and a
+ * round where every score is `NaN` picks the first remaining candidate,
+ * matching the TS `bestIdx = 0` initialisation. Returns the selected
+ * indices into the input order.
+ *
+ * Word tokenization matches `text.toLowerCase().split(/\s+/)` (ECMA `\s`,
+ * Unicode default full case conversion). Known divergence: unpaired
+ * surrogates arrive here as U+FFFD, while JS keeps the lone surrogate; both
+ * tokenize to a single non-whitespace word so Jaccard counts still agree
+ * unless a text mixes U+FFFD words with lone-surrogate words.
+ */
+export declare function mmrRerankIndices(contents: Array<string>, scores: Float64Array, lambdaParam: number, topK: number): Uint32Array
+
+/** Parsed Kitty keyboard protocol sequence result for a Kitty input sequence. */
+export interface ParsedKittyResult {
+  /** Primary codepoint associated with the key. */
+  codepoint: number
+  /** Optional shifted key codepoint from the sequence. */
+  shiftedKey?: number
+  /** Optional base layout key codepoint from the sequence. */
+  baseLayoutKey?: number
+  /** Modifier bitmask (shift/alt/ctrl), excluding lock bits. */
+  modifier: number
+  /** Optional event type (1 = press, 2 = repeat, 3 = release). */
+  eventType?: KeyEventType
+}
+
+/**
+ * Parse terminal input and return a normalized key identifier.
+ *
+ * Returns a key id like "escape" or "ctrl+c", or None if unrecognized.
+ */
+export declare function parseKey(data: string, kittyProtocolActive: boolean): string | null
+
+/**
+ * Parse a Kitty keyboard protocol sequence.
+ *
+ * Returns a structured parse result when the input is a valid Kitty sequence.
+ */
+export declare function parseKittySequence(data: string): ParsedKittyResult | null
+
+/** One hunk of a unified diff, matching jsdiff `structuredPatch` hunks. */
+export interface PatchHunk {
+  /** 1-based first line of the hunk in the old text. */
+  oldStart: number
+  /** Number of old-text lines covered by the hunk. */
+  oldLines: number
+  /** 1-based first line of the hunk in the new text. */
+  newStart: number
+  /** Number of new-text lines covered by the hunk. */
+  newLines: number
+  /**
+   * Hunk body: `+`/`-`/` `-prefixed lines without trailing newlines, plus
+   * `` markers where applicable.
+   */
+  lines: Array<string>
+}
+
+export interface PointerOptions {
+  button?: string
+  count?: number
+  modifiers?: Array<string>
+  deliveryMode?: string
+}
+
+/** Current state of a process reference. */
+export declare enum ProcessStatus {
+  /** The referenced process is still running. */
+  Running = 'running',
+  /** The referenced process has exited or is no longer observable. */
+  Exited = 'exited'
+}
+
+export interface ProcessTerminateOptions {
+  /** Also signal the process group when supported by the platform. */
+  group?: boolean
+  /**
+   * Milliseconds to wait after polite termination before hard-killing.
+   * Omit to use the default grace period. Pass a negative value to skip the
+   * graceful phase and hard-kill immediately.
+   */
+  gracefulMs?: number
+  /** Milliseconds to wait after hard-kill for the process tree to exit. */
+  timeoutMs?: number
+  /** Abort signal for cancelling termination while waiting. */
+  signal?: unknown
+}
+
+/** Options for waiting on a process exit. */
+export interface ProcessWaitOptions {
+  /** Milliseconds to wait before returning false. Omit to wait indefinitely. */
+  timeoutMs?: number
+  /** Abort signal for cancelling the wait. */
+  signal?: unknown
+}
+
+/** Options for running an executable and argument vector in a PTY session. */
+export interface PtyArgvStartOptions {
+  /** Executable name or path. */
+  application: string
+  /** Arguments passed directly to the executable. */
+  args: Array<string>
+  /** Working directory for command execution. */
+  cwd?: string
+  /** Environment variables for this command. */
+  env?: Record<string, string>
+  /** Timeout in milliseconds before cancelling. */
+  timeoutMs?: number
+  /** Abort signal for cancelling the operation. */
+  signal?: unknown
+  /** PTY column count. */
+  cols?: number
+  /** PTY row count. */
+  rows?: number
+}
+
+/** Result of a PTY command run. */
+export interface PtyRunResult {
+  /** Exit code when the command completes. */
+  exitCode?: number
+  /** Whether command was cancelled by signal/user kill. */
+  cancelled: boolean
+  /** Whether command timed out. */
+  timedOut: boolean
+}
+
+/** Options for running a command in a PTY session. */
+export interface PtyStartOptions {
+  /** Command string to execute. */
+  command: string
+  /** Working directory for command execution. */
+  cwd?: string
+  /** Environment variables for this command. */
+  env?: Record<string, string>
+  /** Timeout in milliseconds before cancelling. */
+  timeoutMs?: number
+  /** Abort signal for cancelling the operation. */
+  signal?: unknown
+  /** PTY column count. */
+  cols?: number
+  /** PTY row count. */
+  rows?: number
+  /**
+   * Shell binary to use (e.g. "sh", "bash", or an absolute path).
+   * Defaults to "sh" if not provided.
+   */
+  shell?: string
+}
+
+/**
+ * Read an image from the system clipboard.
+ *
+ * Returns `Ok(None)` when no image data is available.
+ *
+ * # Errors
+ * Returns an error if clipboard access fails or image encoding fails.
+ */
+export declare function readImageFromClipboard(): Promise<ClipboardImage | undefined | null>
+
+/**
+ * Render one snapcompact frame on a libuv worker: print pre-normalized text
+ * onto a `size`-wide bitmap and encode it as PNG.
+ *
+ * The bitmap height hugs the rows the text actually occupies
+ * (`usedRows * lineRepeat * cellHeight`), so a partially filled frame never
+ * pays for blank padding rows. The glyph grid holds `floor(size/cellWidth) *
+ * floor(size/cellHeight/lineRepeat)` characters; input beyond that is ignored.
+ * Native-cell bitmap-font shapes encode as indexed PNG; stretched bitmap-font
+ * shapes (target cell != font cell) encode as RGB. TrueType shapes encode RGB
+ * directly from grayscale coverage.
+ * `stretch: false` pins bitmap fonts to the indexed path, printing
+ * natural-size glyphs on the requested cell box; `columns: 2` flows
+ * pre-wrapped newline-separated lines down two newspaper columns.
+ * `U+000E`/`U+000F` in `text` toggle dim-gray ink spans without occupying a
+ * cell.
+ * Returns a promise for the PNG encoded as base64, created as a one-byte
+ * (Latin-1) JS string straight from native code — no `Uint8Array` hop or
+ * JS-side re-encode.
+ */
+export declare function renderSnapcompactPng(text: string, options: SnapcompactRenderOptions): Promise<string>
+
+/**
+ * Search content for a pattern (one-shot, compiles pattern each time).
+ * For repeated searches with the same pattern, use [`grep`] with file filters.
+ *
+ * # Arguments
+ * - `content`: `Uint8Array`/`Buffer` (zero-copy) or `string` (UTF-8).
+ * - `options`: Regex settings, context, and output mode.
+ *
+ * # Returns
+ * Match list plus counts/limit status; errors are surfaced in `error`.
+ */
+export declare function search(content: string | Uint8Array, options: SearchOptions): SearchResult
+
+/** Options for searching file content. */
+export interface SearchOptions {
+  /** Regex pattern to search for. */
+  pattern: string
+  /** Case-insensitive search. */
+  ignoreCase?: boolean
+  /** Enable multiline matching. */
+  multiline?: boolean
+  /** Maximum number of matches to return. */
+  maxCount?: number
+  /** Skip first N matches. */
+  offset?: number
+  /** Lines of context before matches. */
+  contextBefore?: number
+  /** Lines of context after matches. */
+  contextAfter?: number
+  /** Lines of context before/after matches (legacy). */
+  context?: number
+  /** Truncate lines longer than this (characters). */
+  maxColumns?: number
+  /** Output mode (content or count). */
+  mode?: GrepOutputMode
+}
+
+/** Result of searching content. */
+export interface SearchResult {
+  /** All matches found. */
+  matches: Array<Match>
+  /** Total number of matches (may exceed `matches.len()` due to offset/limit). */
+  matchCount: number
+  /** Whether the limit was reached. */
+  limitReached: boolean
+  /** Error message, if any. */
+  error?: string
+}
+
+export declare function setHangulCompatJamoWidthOverride(value: number): void
+
+/** Options for executing a shell command via brush-core. */
+export interface ShellExecuteOptions {
+  /** Command string to execute in the shell. */
+  command: string
+  /** Working directory for the command. */
+  cwd?: string
+  /** Environment variables to apply for this command only. */
+  env?: Record<string, string>
+  /** Environment variables to apply once per session. */
+  sessionEnv?: Record<string, string>
+  /** Timeout in milliseconds before cancelling the command. */
+  timeoutMs?: number
+  /** Optional snapshot file to source on session creation. */
+  snapshotPath?: string
+  /** Optional per-command output minimizer configuration. */
+  minimizer?: MinimizerOptions
+  /** Abort signal for cancelling the operation. */
+  signal?: unknown
+}
+
+/** Options for configuring a persistent shell session. */
+export interface ShellOptions {
+  /** Environment variables to apply once per session. */
+  sessionEnv?: Record<string, string>
+  /** Optional snapshot file to source on session creation. */
+  snapshotPath?: string
+  /** Optional per-command output minimizer configuration. */
+  minimizer?: MinimizerOptions
+}
+
+/** Options for running a shell command. */
+export interface ShellRunOptions {
+  /** Command string to execute in the shell. */
+  command: string
+  /** Working directory for the command. */
+  cwd?: string
+  /** Environment variables to apply for this command only. */
+  env?: Record<string, string>
+  /** Timeout in milliseconds before cancelling the command. */
+  timeoutMs?: number
+  /** Abort signal for cancelling the operation. */
+  signal?: unknown
+}
+
+/** Result of running a shell command. */
+export interface ShellRunResult {
+  /** Exit code when the command completes normally. */
+  exitCode?: number
+  /** Whether the command was cancelled via abort. */
+  cancelled: boolean
+  /** Whether the command timed out before completion. */
+  timedOut: boolean
+  /**
+   * When the minimizer rewrote the captured output, this carries the
+   * original buffer + telemetry so the session layer can persist it as
+   * an artifact and splice an `artifact://<id>` reference into the
+   * minimized text shown to the agent. `None` when nothing was rewritten.
+   */
+  minimized?: MinimizerResult
+  /** Shell working directory after command completion. */
+  workingDir?: string
+}
+
+/**
+ * Visible slice of a line after ANSI-aware column selection
+ * (`sliceWithWidth`).
+ */
+export interface SliceResult {
+  /** UTF-16 slice containing the selected text. */
+  text: string
+  /** Visible width of the slice in terminal cells. */
+  width: number
+}
+
+/**
+ * Slice a range of visible columns from a line.
+ *
+ * Counts terminal cells, skipping ANSI escapes, and optionally enforces strict
+ * width.
+ */
+export declare function sliceWithWidth(line: string, startCol: number, length: number, strict: boolean | undefined | null, tabWidth: number): SliceResult
+
+/** Shape options for one snapcompact frame. */
+export interface SnapcompactRenderOptions {
+  /**
+   * Frame width in pixels; also bounds the grid rows
+   * (`floor(size/cellHeight/lineRepeat)`). Output height hugs the rows the
+   * text actually uses instead of padding to a square.
+   */
+  size: number
+  /**
+   * Bundled font: `"5x8"`, `"6x12"`, `"8x13"` (X.org BDF), `"8x8"`
+   * (unscii-8), or `"silver"` (embedded TrueType). Default `"5x8"`.
+   */
+  font?: string
+  /**
+   * Target cell advance in pixels. Differing from the font's natural cell
+   * triggers the Lanczos stretch path. Default: font natural width.
+   */
+  cellWidth?: number
+  /** Target cell pitch in pixels. Default: font natural height. */
+  cellHeight?: number
+  /**
+   * Ink variant: `"sent"` (six-hue sentence cycling) or `"bw"` (black).
+   * Default `"sent"`.
+   */
+  variant?: string
+  /**
+   * Print each text line this many times; copies after the first sit on a
+   * pale highlight band. Default 1.
+   */
+  lineRepeat?: number
+  /**
+   * Stretch behavior. Unset: auto — Lanczos-stretch whenever the target
+   * cell differs from the font's natural cell. `false`: never stretch —
+   * render indexed with glyphs at natural size on the requested cell box
+   * (e.g. 8x13 glyphs on an 8x16 pitch, the "8on16" shapes). `true`: force
+   * the stretch path (identical to auto; natural cells render indexed).
+   */
+  stretch?: boolean
+  /**
+   * Layout columns: `1` (default) row-major grid; `2` two newspaper "doc"
+   * columns of pre-wrapped newline-separated lines.
+   */
+  columns?: number
+}
+
+/**
+ * Return the subset of `chars` that the named snapcompact font can render.
+ *
+ * The TypeScript normalizer uses this to keep Unicode text intact only when
+ * the selected native font has a glyph for it; renderer control codes are
+ * considered renderable because they are interpreted outside font lookup.
+ */
+export declare function snapcompactSupportedChars(font: string, chars: string): string
+
+/**
+ * Unified-diff hunks with jsdiff
+ * `structuredPatch(_, _, oldText, newText, _, _, { context }).hunks`
+ * semantics. `context` defaults to 4 like jsdiff.
+ */
+export declare function structuredPatchHunks(oldText: string, newText: string, context?: number | undefined | null): Array<PatchHunk>
+
+export declare function summarizeCode(options: SummaryOptions): SummaryResult
+
+export interface SummaryOptions {
+  /** Source code to summarize. */
+  code: string
+  /** Language alias (e.g. "rust", "typescript") used before path inference. */
+  lang?: string
+  /** File path used to infer language by extension when `lang` is omitted. */
+  path?: string
+  /** Minimum total node lines before eliding a body/literal node. */
+  minBodyLines?: number
+  /** Minimum total comment lines before eliding a multiline block comment. */
+  minCommentLines?: number
+  /**
+   * Target visible-line count for BFS unfold. `None` or `0` keeps only
+   * the outermost elisions (no progressive unfolding).
+   */
+  unfoldUntilLines?: number
+  /**
+   * Hard ceiling for BFS unfold. Defaults to `unfold_until_lines * 2`
+   * when omitted.
+   */
+  unfoldLimitLines?: number
+}
+
+export interface SummaryResult {
+  /** Canonical language name when parsing succeeded. */
+  language?: string
+  /** True when tree-sitter parsed the source without syntax errors. */
+  parsed: boolean
+  /** True when at least one elision span was emitted. */
+  elided: boolean
+  /** Total source lines. */
+  totalLines: number
+  /** Kept/elided segments in source order. */
+  segments: Array<SummarySegment>
+}
+
+export interface SummarySegment {
+  /** "kept" or "elided". */
+  kind: string
+  /** 1-based inclusive start line. */
+  startLine: number
+  /** 1-based inclusive end line. */
+  endLine: number
+  /** Verbatim text for kept segments; absent for elided segments. */
+  text?: string
+}
+
+/**
+ * Check if a language is supported for highlighting.
+ * Returns true if the language has either direct support or a fallback
+ * mapping.
+ */
+export declare function supportsLanguage(lang: string): boolean
+
+/**
+ * Truncate text to a visible width, preserving ANSI codes.
+ *
+ * Pads with spaces when requested.
+ */
+export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind: Ellipsis | undefined | null, pad: boolean | undefined | null, tabWidth: number): string
+
+/**
+ * Score every row of a normalized `f32` matrix against `query` and return
+ * the top `limit` rows.
+ *
+ * Mirrors the TS `searchExactVectorIndex` loop bit-exactly: the query is
+ * normalized by the L2 norm of its *full* length, each row score sums
+ * `matrix[row][col] * (query[col] / norm)` over
+ * `min(query.len, dimensions)` columns in column order. Ranking matches the
+ * TS stable sort: score descending, lower row index first on exact ties
+ * (`-0.0` and `+0.0` compare equal). Callers are expected to enforce the TS
+ * guards first (finite query with a positive norm, non-empty matrix).
+ */
+export declare function vectorIndexTopK(matrix: Float32Array, dimensions: number, query: Float64Array, limit: number): VectorTopK
+
+/**
+ * Top-k rows of a normalized vector matrix ranked by dot product with a
+ * normalized query.
+ */
+export interface VectorTopK {
+  /** Row indices of the selected hits, best score first. */
+  indices: Uint32Array
+  /** Scores aligned with `indices`. */
+  scores: Float64Array
+}
+
+/**
+ * Calculate visible width of text, excluding ANSI escape sequences.
+ *
+ * Tabs count as a fixed-width cell.
+ */
+export declare function visibleWidth(text: string, tabWidth: number): number
+
+/** Profiling results returned to JavaScript. */
+export interface WorkProfile {
+  /** Folded stack format for flamegraph tools. */
+  folded: string
+  /** Markdown summary of profiling results. */
+  summary: string
+  /** SVG flamegraph (if generation succeeded). */
+  svg?: string
+  /** Total profiled duration in milliseconds. */
+  totalMs: number
+  /** Number of samples collected. */
+  sampleCount: number
+}
+
+/**
+ * Wrap text to a visible width, preserving ANSI escape codes across line
+ * breaks.
+ *
+ * Returns UTF-16 lines with active SGR codes carried across line boundaries.
+ */
+export declare function wrapTextWithAnsi(text: string, width: number, tabWidth: number): Array<string>