kaish_tool_api/
backend.rs

1//! The `KernelBackend` trait — kaish's abstract I/O and tool-dispatch layer.
2//!
3//! The trait lives here (not in `kaish-types`) because it is async and refers
4//! to [`ToolCtx`](crate::ToolCtx). Its data types (errors, results, ops) and
5//! the concrete implementations (`LocalBackend`, overlay, …) live elsewhere —
6//! the data in `kaish-types::backend`, the impls in `kaish-kernel`.
7
8use std::path::{Path, PathBuf};
9
10use async_trait::async_trait;
11
12use kaish_types::backend::{
13    BackendResult, MountInfo, PatchOp, ReadRange, ToolInfo, ToolResult, WriteMode,
14};
15use kaish_types::{DirEntry, ToolArgs};
16
17use crate::ctx::ToolCtx;
18
19/// Abstract backend interface for file operations and tool dispatch.
20///
21/// Implementations select where a path resolves and how tools are dispatched:
22/// - `LocalBackend` — VfsRouter-backed local filesystem (the default).
23/// - `KaijutsuBackend` — CRDT-backed blocks when embedded in kaijutsu.
24#[async_trait]
25pub trait KernelBackend: Send + Sync {
26    // ═══════════════════════════════════════════════════════════════════════
27    // File Operations
28    // ═══════════════════════════════════════════════════════════════════════
29
30    /// Read file contents, optionally with a range specification.
31    async fn read(&self, path: &Path, range: Option<ReadRange>) -> BackendResult<Vec<u8>>;
32
33    /// Write content to a file with the specified mode.
34    async fn write(&self, path: &Path, content: &[u8], mode: WriteMode) -> BackendResult<()>;
35
36    /// Append content to a file.
37    async fn append(&self, path: &Path, content: &[u8]) -> BackendResult<()>;
38
39    /// Apply a sequence of patch operations to a file.
40    async fn patch(&self, path: &Path, ops: &[PatchOp]) -> BackendResult<()>;
41
42    /// List a directory's entries.
43    async fn list(&self, path: &Path) -> BackendResult<Vec<DirEntry>>;
44
45    /// Stat a path (following symlinks).
46    async fn stat(&self, path: &Path) -> BackendResult<DirEntry>;
47
48    /// Create a directory.
49    async fn mkdir(&self, path: &Path) -> BackendResult<()>;
50
51    /// Set the modification time of an existing path.
52    ///
53    /// Read-only or purely-virtual mounts reject rather than silently
54    /// succeeding — `touch` on an existing file must route through here, never
55    /// escape to the host via `resolve_real_path`.
56    async fn set_mtime(&self, path: &Path, mtime: std::time::SystemTime) -> BackendResult<()>;
57
58    /// Remove a file or directory.
59    async fn remove(&self, path: &Path, recursive: bool) -> BackendResult<()>;
60
61    /// Rename/move a path.
62    async fn rename(&self, from: &Path, to: &Path) -> BackendResult<()>;
63
64    /// Whether a path exists.
65    async fn exists(&self, path: &Path) -> bool;
66
67    /// Stat a path without following symlinks.
68    async fn lstat(&self, path: &Path) -> BackendResult<DirEntry>;
69
70    /// Read a symlink's target.
71    async fn read_link(&self, path: &Path) -> BackendResult<PathBuf>;
72
73    /// Create a symlink.
74    async fn symlink(&self, target: &Path, link: &Path) -> BackendResult<()>;
75
76    // ═══════════════════════════════════════════════════════════════════════
77    // Tool Dispatch
78    // ═══════════════════════════════════════════════════════════════════════
79
80    /// Call a tool by name with the given arguments and execution context.
81    ///
82    /// For local backends, this executes the tool directly via ToolRegistry.
83    /// For remote backends (e.g. kaijutsu), this may serialize the call and
84    /// forward it to the parent process.
85    async fn call_tool(
86        &self,
87        name: &str,
88        args: ToolArgs,
89        ctx: &mut dyn ToolCtx,
90    ) -> BackendResult<ToolResult>;
91
92    /// List available external tools.
93    async fn list_tools(&self) -> BackendResult<Vec<ToolInfo>>;
94
95    /// Get information about a specific tool.
96    async fn get_tool(&self, name: &str) -> BackendResult<Option<ToolInfo>>;
97
98    // ═══════════════════════════════════════════════════════════════════════
99    // Backend Information
100    // ═══════════════════════════════════════════════════════════════════════
101
102    /// Returns true if this backend is read-only.
103    fn read_only(&self) -> bool;
104
105    /// Returns the backend type identifier (e.g. "local", "kaijutsu").
106    fn backend_type(&self) -> &str;
107
108    /// List all mount points.
109    fn mounts(&self) -> Vec<MountInfo>;
110
111    /// Resolve a VFS path to a real filesystem path.
112    ///
113    /// Returns `Some(path)` if the VFS path maps to a real filesystem (like
114    /// LocalFs), or `None` if the path is virtual (like MemoryFs). Tools like
115    /// `git` that hand paths to external C libraries need the real path.
116    fn resolve_real_path(&self, path: &Path) -> Option<PathBuf>;
117}
kaish_tool_api/backend.rs

kaish_tool_api/
backend.rs
