AFT (Agentic File Tools)

The benchmarks/ directory provides reproducible harnesses for evaluating AFT performance. Using Docker is the recommended approach as it eliminates the need to install AFT, Bun, Rust, CodeGraph, or OpenCode on your host machine. Results are automatically written to a results/ directory within each specific benchmark folder.

Important Distinction:

• Path A (Retrieval): Focuses on retrieval quality without LLM involvement. Do not use these results to infer agent behavior.
• Path B (Agent): Uses an LLM and involves real agent runs, meaning results will have run-to-run variance.

The AFT repository is organized into several key functional areas:

• Core Engine (crates/aft/): The Rust-based execution engine, including the stdin/stdout protocol, shared analysis logic, and command handlers.
• Tokenizer (crates/aft-tokenizer/): A standalone Rust crate for counting Claude API tokens.
• Plugins (packages/opencode-plugin/, packages/pi-plugin/): TypeScript packages that resolve the AFT binary and register tools for specific coding agent harnesses (OpenCode and Pi).
• Bridge (packages/aft-bridge/): The shared transport layer used by plugins to communicate with the subc daemon.
• CLI (packages/aft-cli/): A unified entry point via npx @cortexkit/aft for setup, diagnostics (doctor), and LSP management.
• Platform Binaries (packages/npm/): Platform-specific npm packages used to distribute bundled binaries for Darwin, Linux, and Win32.

The AFT agent-text habit audit (2026-07) evaluates the text presented to agents (e.g., tool descriptions, workflow hints, error messages, and system notifications) against six ALF fleet habit-training defect classes. The goal is to identify strings that might inadvertently train an agent to develop incorrect, unbounded, or unsafe habits, such as infinite polling loops or assuming stale data is current.

Defect Classes referenced in the audit:

• A, B, C, D, E, F: These represent specific categories of agent habit defects (e.g., training an agent to treat a partial transaction as complete, or training an agent to use a polling loop instead of waiting for a notification).

Key Audit Areas:

• Formatter sets (crates/aft/src/subc_format.rs)
• Response finalization and orchestration paths
• Tool descriptions and schemas (crates/aft/src/subc_tool_schemas.json)
• Plugin-injected workflow hints and permission/steering messages

When debugging or writing tests for AFT, especially in CI environments, failures often fall into one of four mechanism classes. Understanding these helps in choosing the correct fix pattern:

• S (Scheduler time charged as work time): A wall-clock budget starts before the operation enters the measured lifecycle state. Descheduling or queuing can exhaust the budget without the operation actually violating its contract.
• P (Completion proxy): The test fixture waits on a correlated signal (like a PID, filesystem sample, or status request) instead of the producer's actual terminal event and authoritative store.
• G (Unscoped global test control): A process-global variable or environment value is consumed by unrelated parallel tests, causing assertions to observe the wrong lifecycle.
• F (Filesystem/PID observation race): A path or liveness probe is sampled while a deletion, rename, or process exit is still in progress, leading to race conditions.

AFT tool responses follow a tri-state contract to help agents distinguish between different execution outcomes. This ensures the agent knows if a result is complete, partial, or if the operation failed entirely.

Success States

• Failure: success: false indicates the work could not be performed. This response must include a code (e.g., path_not_found, no_lsp_server, project_too_large, invalid_request, ambiguous_match) and a message.
• Complete Success: success: true with complete: true means the result is trustworthy. If the result is empty, it means the tool genuinely found nothing.
• Partial Success: success: true with complete: false means the tool ran but the result is incomplete. The response will specify the gap using keys like:
  • pending_files, unchecked_files, walk_truncated: Files the tool did not reach.
  • skipped_files: [{file, reason}]: Files intentionally skipped (e.g., due to parse errors or unsupported languages).
  • scope_warnings, no_files_matched_scope: Paths or globs that resolved to zero files.

Side-effect Skips

If the primary task succeeded but a non-essential post-step (like formatting or validation) was skipped, the response includes a <step>_skipped_reason.

format_skipped_reason values:

• unsupported_language
• no_formatter_configured
• formatter_not_installed
• formatter_excluded_path
• timeout
• error

validate_skipped_reason values:

• unsupported_language
• no_checker_configured
• checker_not_installed
• timeout
• error

AFT manages background bash tasks through two primary mechanisms: the Delivery arm and the Visibility arm.

Delivery Arm (Pattern Matching)

When a terminal performs an output scan, matches are written to bash_pattern_watches via persist_watch_match and emitted as a BashPatternMatch push.

• Reliability: To prevent matches from being stranded, the system uses a repeating 'subc wake' (nudge).
• Lifecycle: Terminalization marks task completion as delivered, preserves the pending durable watch until an acknowledgment (ack) is received, and then clears the in-memory watch state.
• Fix/Best Practice: Ensure that pattern matches receive the same repeating subc wake as completions to prevent them from sitting indefinitely in the database if a direct push is missed during a route rebinding window.

Visibility Arm (Status Lookups)

bash_status determines task visibility through a tiered lookup:

1. In-memory registry: The primary check.
2. Metadata-only fallback: If the in-memory lookup misses (e.g., due to a registry rebind) or if the task bundle is missing, the system reads the intact terminal DB row into a metadata-only status snapshot.

Note on Artifacts: A missing or corrupt task bundle does not mean the task is invisible. With the metadata fallback, missing artifacts result in empty/unavailable output rather than an invisible task. However, a task requires a valid bundle under the currently selected storage/session path to reconstruct a full in-memory task.

Ripwire provides several risk annotations for ranked symbols during ingest and graph construction. These are computed when using flags like --for, --metrics, or --exemplar.

Key metrics include:

• tested=1: Indicates a symbol is transitively reachable from a syntactically identified test symbol via resolved outgoing calls. Note that dynamic dispatch, unbound callbacks, and subprocess tests are excluded.
• purity: A least fixpoint metric where calls to a specific set of side-effecting intrinsics seed impurity, which then propagates backward to callers via the incoming CSR.
• churn: The count of commits touching the symbol's file within a 12-month window, derived from an 18-month history walk.
• amp: A mixed-granularity metric defined as direct caller count + number of distinct files that co-changed with this symbol's file.

Note: While Ripwire uses these metrics, AFT approaches these questions differently (e.g., using Tree-sitter for complexity and path predicates like is_test_file for test origin).