From 997007439ec1e42266185cffeb454951fbb86d24 Mon Sep 17 00:00:00 2001 From: vikingowl Date: Fri, 26 Dec 2025 18:30:56 +0100 Subject: [PATCH] docs(platform): Add README.md for all platform crates --- crates/platform/auth/README.md | 17 +++++++++++++++++ crates/platform/config/README.md | 18 ++++++++++++++++++ crates/platform/credentials/README.md | 18 ++++++++++++++++++ crates/platform/hooks/README.md | 17 +++++++++++++++++ crates/platform/permissions/README.md | 19 +++++++++++++++++++ crates/platform/plugins/README.md | 14 ++++++++++++++ 6 files changed, 103 insertions(+) create mode 100644 crates/platform/auth/README.md create mode 100644 crates/platform/config/README.md create mode 100644 crates/platform/credentials/README.md create mode 100644 crates/platform/hooks/README.md create mode 100644 crates/platform/permissions/README.md create mode 100644 crates/platform/plugins/README.md diff --git a/crates/platform/auth/README.md b/crates/platform/auth/README.md new file mode 100644 index 0000000..2eb8297 --- /dev/null +++ b/crates/platform/auth/README.md @@ -0,0 +1,17 @@ +# Owlen Auth Manager + +Unified authentication management for the Owlen AI agent. + +## Overview +This crate manages the lifecycle of authentication credentials for various LLM providers. It supports both API key-based authentication and OAuth flows with automatic token refresh. + +## Features +- **Multi-Source Credentials:** Load credentials from environment variables, secure storage, or command-line helpers. +- **OAuth Integration:** Built-in support for device code flows and standard OAuth 2.0. +- **Token Refresh:** Automatic background refreshing of expiring OAuth tokens. +- **Secure Handling:** Leverages the `credentials` crate for encrypted storage. + +## Components +- `AuthManager`: The central coordinator for all authentication logic. +- `LoginFlow`: Manages the interactive login process for providers. +- `Refresher`: Handles periodic checks and updates for expiring credentials. diff --git a/crates/platform/config/README.md b/crates/platform/config/README.md new file mode 100644 index 0000000..417740a --- /dev/null +++ b/crates/platform/config/README.md @@ -0,0 +1,18 @@ +# Owlen Config Agent + +Configuration management for the Owlen AI agent. + +## Overview +This crate handles loading, parsing, and persisting configuration settings. It uses a hierarchical approach, allowing global user settings to be overridden by project-specific configurations and environment variables. + +## Features +- **Hierarchical Configuration:** Merges defaults, user config, project config, and env vars. +- **Strong Typing:** Provides a type-safe `Settings` struct for application-wide use. +- **Provider Preferences:** Manage model selections and provider-specific URLs. +- **Permission Mapping:** Integrates with the `permissions` crate to define tool-use policies. + +## Usage +Configuration is typically loaded via `load_settings()`, which looks for: +1. `~/.config/owlen/config.toml` (Global) +2. `/.owlen.toml` (Project-specific) +3. `OWLEN_*` environment variables (Overriding) diff --git a/crates/platform/credentials/README.md b/crates/platform/credentials/README.md new file mode 100644 index 0000000..2274d0e --- /dev/null +++ b/crates/platform/credentials/README.md @@ -0,0 +1,18 @@ +# Owlen Credentials + +Secure credential storage for the Owlen AI agent. + +## Overview +This crate provides a cross-platform abstraction for storing sensitive data like API keys and OAuth tokens. It prioritizes system-native keychains and falls back to encrypted file storage when necessary. + +## Features +- **Keyring Support:** Native integration with macOS Keychain, Windows Credential Manager, and Linux Secret Service. +- **Encrypted Fallback:** AES-encrypted JSON file storage (`~/.config/owlen/credentials.json`). +- **Credential Helpers:** Support for external tools like `op` (1Password) or `bw` (Bitwarden). +- **Security First:** Implements proper zeroing of sensitive memory where possible. + +## Components +- `CredentialManager`: Primary interface for store/retrieve operations. +- `KeyringStore`: System-native backend. +- `FileStore`: Encrypted local file backend. +- `HelperManager`: Integration with external credential CLI tools. diff --git a/crates/platform/hooks/README.md b/crates/platform/hooks/README.md new file mode 100644 index 0000000..858de2a --- /dev/null +++ b/crates/platform/hooks/README.md @@ -0,0 +1,17 @@ +# Owlen Hooks + +Plugin hook system for the Owlen AI agent. + +## Overview +This crate enables extending the agent's behavior through a flexible hook system. It allows various parts of the application to emit events that plugins can intercept and respond to. + +## Features +- **Lifecycle Hooks:** Register callbacks for key agent events (session start, tool execution, response generated). +- **Synchronous & Asynchronous:** Supports both immediate and future-based hook handlers. +- **Priority-Based Execution:** Fine-grained control over the order in which hooks are processed. + +## Common Hooks +- `on_session_start`: Setup tasks when a new conversation begins. +- `before_tool_execution`: Validate or modify tool arguments before they run. +- `after_tool_execution`: Process or log tool results. +- `on_message_received`: Intercept incoming user messages. diff --git a/crates/platform/permissions/README.md b/crates/platform/permissions/README.md new file mode 100644 index 0000000..cc800cf --- /dev/null +++ b/crates/platform/permissions/README.md @@ -0,0 +1,19 @@ +# Owlen Permissions + +Safety and permission system for the Owlen AI agent. + +## Overview +This crate implements the security policies that govern what tools the agent can execute. It ensures that dangerous operations (like `bash` or `write`) are only performed with explicit user consent or according to predefined rules. + +## Features +- **Operation Modes:** + - `Plan`: Read-only mode for planning. + - `AcceptEdits`: Automatically allow file modifications but prompt for system changes. + - `Code`: Full access mode. +- **Rule-Based Access:** Define granular permissions for specific tools or path patterns. +- **Decision Logic:** Centralized logic for `Allow`, `Ask`, and `Deny` decisions. + +## Components +- `PermissionManager`: The core policy engine. +- `Tool`: Enum representing all available system operations. +- `PermissionRule`: A specific grant or restriction for a tool/context. diff --git a/crates/platform/plugins/README.md b/crates/platform/plugins/README.md new file mode 100644 index 0000000..80ff0e7 --- /dev/null +++ b/crates/platform/plugins/README.md @@ -0,0 +1,14 @@ +# Owlen Plugins + +Plugin management system for the Owlen AI agent. + +## Overview +This crate manages the loading and discovery of Owlen plugins. It handles plugin metadata, dependency resolution, and provides the interface for plugins to register their tools and hooks. + +## Features +- **Discovery:** Scan directories for compatible plugin manifests. +- **Isolation:** (Future) Ensure plugins run in a secure, isolated environment. +- **Registration:** Seamlessly add new tools and command handlers to the agent. + +## Usage +Plugins are typically located in `~/.owlen/plugins/` or project-local `.owlen/plugins/` directories. Each plugin is defined by a manifest file (e.g., `plugin.toml` or `.owlen-plugin.json`).