Return content-free path and executable diagnostics without running command.

This resolves the working directory, symlink target, detectable Git repository root, and first executable token. Shell expansion, aliases, pipelines, redirections, environment changes, and arbitrary shell logic cannot be verified here. The requested command is never executed.

Run a sequential, durably checkpointed set of command phases.

Each phase is an object with name and command plus optional cwd, timeout_seconds, max_output_bytes, structured_metrics, and side_effects (none or unsafe). A completed phase is never rerun by resume_execution. An unsafe phase that must be retried after failure, timeout, or interruption requires confirm_unsafe=True or the explicit resume_policy='allow-unsafe'. Outputs and phase event history are stored under EPHEMERAL_EXECUTION_STATE_DIR.

Resume an execution from its first incomplete phase.

Completed phases are skipped. Failed and timed-out phases require retry_failed=True; a safe phase recovered as interrupted resumes on the normal call. Retries of unsafe phases additionally need confirm_unsafe=True unless the execution was created with the explicit allow-unsafe resume policy.

Return durable phase metadata and event history for one execution.

Retrieve one bounded output chunk for all phases or one named phase.

List durable executions with compact partial/completion summaries.

Ingest already-collected text and return capture metadata.

Use this when the caller already has output to index. For a noisy or potentially long command, use execute_and_capture so output remains bounded before it reaches the agent context. The return value is a compact versioned JSON summary; optional named metrics are retained in structured_metrics.

Reads a file or log output from disk and ingests it into the ephemeral search index. Returns a compact versioned JSON summary and preserves optional named metrics in structured_metrics.

Validate the intended file path before calling: resolve symlinks when path identity matters, confirm the file belongs to the expected workspace, and use an explicit bounded max_bytes for large or untrusted files. Capture limits control output handling; they do not validate filesystem intent.

Runs a shell command, captures stdout/stderr, indexes it, and returns a compact versioned JSON summary without flooding the prompt context with thousands of lines. The summary includes status, duration, sizes, approximate token counts, truncation, signals, and optional named metrics.

Use this for noisy tests, builds, logs, and other output that benefits from bounded capture and later search. Direct command execution is usually faster for a small, targeted inspection; use capture once output may be noisy, large, or uncertain. This is an advisory routing heuristic, not an enforced threshold. Before running, verify the command, intended repository, and working directory: an omitted cwd inherits the server process directory, and symlinks or shell expansion can target a different path than expected. This tool bounds output but does not validate command intent, path identity, or filesystem safety.

Args: command: Shell command line to execute. cwd: Optional working directory for command execution; pass an explicit validated path for repository-sensitive commands. label: Optional human-readable description/label for this capture. content_type: Content type hint - 'auto' (default, detects diff/log/text), 'diff', 'log', or 'text'. max_output_bytes: Maximum command output retained (default: configured buffer byte limit). timeout_seconds: Optional maximum runtime; timed-out commands return exit code 124.

Create one bounded, searchable JSON capture from multiple captures.

The consolidated capture keeps source capture IDs and source line numbers. If records do not fit, the complete source captures remain available through their original IDs until normal LRU eviction. The operation fails if the consolidated capture cannot be admitted while retaining those sources.

Searches the captured command output using BM25, Semantic embedding, or Hybrid (RRF) ranking. Semantic prefetch is on by default. Hybrid search waits at most the configured semantic wait budget for a capture's index; on a very large capture it then returns BM25 results with 'semantic pending' noted, and repeating the search once indexing finishes returns hybrid ranking. Semantic mode waits for the index.

Args: query: Search keywords or natural language question (e.g. 'auth failure', 'ECONNREFUSED', 'why did the build fail?'). mode: Search mode - 'hybrid' (recommended, lexically weighted BM25 + Semantic), 'bm25' (keyword terms), or 'semantic' (vector concepts). capture_id: The capture ID to query (defaults to 'latest'). top_k: Number of matching snippets to return (default: 5). context_lines: Number of surrounding lines of context to include with each match (default: 3; must be non-negative).

Fetches an exact range of lines (1-indexed) from a capture to inspect full context around a match.

Returns a compact versioned JSON summary. Set include_previews when head and tail samples are needed; full output remains available through get_capture_slice.

Lists all captures currently retained in the ephemeral ring buffer.

Clears all or a specific capture from the ephemeral buffer to free memory.

Returns aggregate capture, accounting, prefetch, and process RSS metrics.

Returns opt-in runtime metadata without exposing captured content.

Adjust this session's semantic-index chunk budget when explicitly enabled.