storkit/.story_kit/specs/functional/AGENT_CAPABILITIES.md

Functional Spec: Agent Capabilities

Overview

The Agent interacts with the Target Project through a set of deterministic Tools. These tools are exposed as Tauri Commands to the frontend, which acts as the orchestrator for the LLM.

1. Filesystem Tools

All filesystem operations are strictly scoped to the active SessionState.project_root. Attempting to access paths outside this root (e.g., ../foo) must return an error.

read_file

• Input: path: String (Relative to project root)
• Output: Result<String, AppError>
• Behavior: Returns the full text content of the file.

write_file

• Input: path: String, content: String
• Output: Result<(), AppError>
• Behavior: Overwrites the file. Creates parent directories if they don't exist.

list_directory

• Input: path: String (Relative)
• Output: Result<Vec<FileEntry>, AppError>
• Data Structure: FileEntry { name: String, kind: "file" | "dir" }

2. Search Tools

High-performance text search is critical for the Agent to "read" the codebase without dumping all files into context.

search_files

• Input: query: String (Regex or Literal), glob: Option<String>
• Output: Result<Vec<Match>, AppError>
• Engine: Rust ignore crate (WalkBuilder) + grep_searcher.
• Constraints:
  • Must respect .gitignore.
  • Limit results (e.g., top 100 matches) to prevent freezing.

3. Shell Tools

The Agent needs to compile code, run tests, and manage git.

exec_shell

• Input: command: String, args: Vec<String>
• Output: Result<CommandOutput, AppError>
• Data Structure: CommandOutput { stdout: String, stderr: String, exit_code: i32 }
• Security Policy:
  • Allowlist: git, cargo, npm, yarn, pnpm, node, bun, ls, find, grep, mkdir, rm, mv, cp, touch.
  • cwd: Always executed in SessionState.project_root.
  • Timeout: Hard limit (e.g., 30s) to prevent hanging processes.

Error Handling

All tools must return a standardized JSON error object to the frontend so the LLM knows why a tool failed (e.g., "File not found", "Permission denied").