| import type { Environment } from './environment'; | |
| import type { KaosProcess } from './process'; | |
| import type { StatResult } from './types'; | |
| /** | |
| * Kimi Agent Operating System (KAOS) interface. | |
| * | |
| * This is the core abstraction that allows the agent to interact with | |
| * different execution environments (local, SSH, containers, etc.) | |
| * through a unified API. | |
| */ | |
| export interface Kaos { | |
| /** Human-readable name for this environment (e.g. `"local"`, `"ssh:host"`). */ | |
| readonly name: string; | |
| /** | |
| * OS / shell probe describing the target environment. Populated by the | |
| * concrete Kaos implementation (e.g. `detectEnvironmentFromNode()` for | |
| * `LocalKaos`, a remote probe for `SSHKaos`). | |
| */ | |
| readonly osEnv: Environment; | |
| // ── Path operations (sync) ────────────────────────────────────────── | |
| /** Return the path style used by this environment. */ | |
| pathClass(): 'posix' | 'win32'; | |
| /** Normalize the given path string (resolve `.` / `..` segments). */ | |
| normpath(path: string): string; | |
| /** Return the home directory of the current user. */ | |
| gethome(): string; | |
| /** Return the current working directory. */ | |
| getcwd(): string; | |
| // ── Directory operations (async) ──────────────────────────────────── | |
| /** Change the working directory to `path`. */ | |
| chdir(path: string): Promise<void>; | |
| /** Return a new Kaos with the given `cwd`. */ | |
| withCwd(cwd: string): Kaos; | |
| /** | |
| * Return a new Kaos that overlays `env` onto every spawned process. | |
| * | |
| * The provided record is read when a process is spawned, so callers may | |
| * mutate a stable record to update future executions. | |
| */ | |
| withEnv(env: Record<string, string>): Kaos; | |
| /** Return stat metadata for `path`. */ | |
| stat(path: string, options?: { followSymlinks?: boolean }): Promise<StatResult>; | |
| /** Yield entry names in the directory at `path`. */ | |
| iterdir(path: string): AsyncGenerator<string>; | |
| /** Yield paths matching `pattern` under `path`. */ | |
| glob( | |
| path: string, | |
| pattern: string, | |
| options?: { caseSensitive?: boolean }, | |
| ): AsyncGenerator<string>; | |
| // ── File operations (async) ───────────────────────────────────────── | |
| /** Read up to `n` bytes from `path` (all bytes if `n` is omitted). */ | |
| readBytes(path: string, n?: number): Promise<Buffer>; | |
| /** | |
| * Read the file at `path` as a string. | |
| * | |
| * `errors` controls how decode errors are handled — mirrors Python's | |
| * `open(..., errors=)` parameter: | |
| * - `'strict'` (default): throw on any invalid byte for the encoding | |
| * - `'replace'`: substitute each invalid byte with U+FFFD (REPLACEMENT CHARACTER) | |
| * - `'ignore'`: drop invalid bytes silently | |
| */ | |
| readText( | |
| path: string, | |
| options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' }, | |
| ): Promise<string>; | |
| /** Yield lines from the file at `path` one by one. */ | |
| readLines( | |
| path: string, | |
| options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' }, | |
| ): AsyncGenerator<string>; | |
| /** Write raw bytes to `path`, returning the number of bytes written. */ | |
| writeBytes(path: string, data: Buffer): Promise<number>; | |
| /** Write text to `path`, returning the number of characters written. */ | |
| writeText( | |
| path: string, | |
| data: string, | |
| options?: { mode?: 'w' | 'a'; encoding?: BufferEncoding }, | |
| ): Promise<number>; | |
| /** Create a directory at `path`. */ | |
| mkdir(path: string, options?: { parents?: boolean; existOk?: boolean }): Promise<void>; | |
| // ── Process execution ─────────────────────────────────────────────── | |
| /** Spawn a process with the given arguments. */ | |
| exec(...args: string[]): Promise<KaosProcess>; | |
| /** Spawn a process with explicit environment variables. */ | |
| execWithEnv(args: string[], env?: Record<string, string>): Promise<KaosProcess>; | |
| } | |