Skip to content

Commit 3ea6a8b

Browse files
tpaetpae
committed
updated readme
1 parent 2c9ab5b commit 3ea6a8b

File tree

4 files changed

+646
-12
lines changed

4 files changed

+646
-12
lines changed

‎README.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ Osaurus is the AI edge runtime for macOS. It brings together:
5252
- **OpenAI, Anthropic & Ollama APIs** — Drop-in compatible endpoints for existing tools
5353
- **MCP Server** — Expose tools to AI agents via Model Context Protocol
5454
- **Remote MCP Providers** — Connect to external MCP servers and aggregate their tools
55-
- **Plugin System** — Extend functionality with community and custom tools
55+
- **Plugin System** — Extend functionality with community and custom tools, HTTP routes, persistent storage, and native configuration UI
5656
- **Agents** — Create custom AI assistants with unique prompts, tools, and visual themes
5757
- **Identity** — Cryptographic identity system for humans and agents with address-based authentication
5858
- **Relay** — Expose agents to the public internet via secure tunnels through `agent.osaurus.ai`
@@ -207,6 +207,10 @@ Install tools from the [central registry](https://github.com/osaurus-ai/osaurus-
207207
| `osaurus.fetch` | `fetch`, `fetch_json`, `fetch_html`, `download` |
208208
| `osaurus.time` | `current_time`, `format_date` |
209209

210+
**Plugin Capabilities (v2 ABI):**
211+
212+
Plugins can go beyond tools — they can register HTTP route handlers (for OAuth flows, webhooks, and APIs), serve static web apps, persist data in a sandboxed SQLite database, and declare a native configuration UI rendered in Osaurus settings.
213+
210214
```bash
211215
# Install from registry
212216
osaurus tools install osaurus.browser
@@ -216,6 +220,9 @@ osaurus tools list
216220

217221
# Create your own plugin
218222
osaurus tools create MyPlugin --language swift
223+
224+
# Dev mode with hot reload
225+
osaurus tools dev com.acme.my-plugin
219226
```
220227

221228
See the [Plugin Authoring Guide](docs/PLUGIN_AUTHORING.md) for details.
@@ -512,6 +519,7 @@ See [Voice Input Guide](docs/VOICE_INPUT.md) for details.
512519
| `osaurus run <model>` | Interactive chat with a model |
513520
| `osaurus mcp` | Start MCP stdio transport |
514521
| `osaurus tools <cmd>` | Manage plugins (install, list, search, etc.) |
522+
| `osaurus tools dev` | Dev mode with hot reload and web proxy |
515523
| `osaurus version` | Show version |
516524

517525
**Tip:** Set `OSU_PORT` to override the default port.

‎docs/CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ Good documentation is just as important as good code. Here's how to contribute t
7777
| [REMOTE_PROVIDERS.md](REMOTE_PROVIDERS.md) | Remote provider setup and configuration |
7878
| [REMOTE_MCP_PROVIDERS.md](REMOTE_MCP_PROVIDERS.md) | Remote MCP provider setup |
7979
| [DEVELOPER_TOOLS.md](DEVELOPER_TOOLS.md) | Insights and Server Explorer guide |
80-
| [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) | Creating custom plugins |
80+
| [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) | Plugin authoring: tools, routes, storage, config UI, and web apps |
8181
| [OpenAI_API_GUIDE.md](OpenAI_API_GUIDE.md) | API usage, tool calling, streaming |
8282
| [SHARED_CONFIGURATION_GUIDE.md](SHARED_CONFIGURATION_GUIDE.md) | Shared configuration for teams |
8383

‎docs/FEATURES.md‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Canonical reference for all Osaurus features, their status, and documentation.
1414
| Remote Providers | Stable | "Key Features" | REMOTE_PROVIDERS.md | Services/RemoteProviderManager.swift, Services/RemoteProviderService.swift |
1515
| Remote MCP Providers | Stable | "Key Features" | REMOTE_MCP_PROVIDERS.md | Services/MCPProviderManager.swift, Tools/MCPProviderTool.swift |
1616
| MCP Server | Stable | "MCP Server" | (in README) | Networking/OsaurusServer.swift, Services/MCPServerManager.swift |
17-
| Tools & Plugins | Stable | "Tools & Plugins" | PLUGIN_AUTHORING.md | Tools/, Managers/PluginManager.swift |
17+
| Tools & Plugins | Stable | "Tools & Plugins" | PLUGIN_AUTHORING.md | Tools/, Managers/PluginManager.swift, Services/PluginHostAPI.swift, Storage/PluginDatabase.swift, Models/PluginHTTP.swift, Views/PluginConfigView.swift |
1818
| Skills | Stable | "Skills" | SKILLS.md | Managers/SkillManager.swift, Views/SkillsView.swift, Services/CapabilityService.swift |
1919
| Memory | Stable | "Key Features" | MEMORY.md | Services/MemoryService.swift, Services/MemorySearchService.swift, Services/MemoryContextAssembler.swift |
2020
| Agents | Stable | "Agents" | (in README) | Managers/AgentManager.swift, Models/Agent.swift, Views/AgentsView.swift |
@@ -53,7 +53,7 @@ Canonical reference for all Osaurus features, their status, and documentation.
5353
│ ├── ManagementView │
5454
│ │ ├── ModelDownloadView (Models) │
5555
│ │ ├── RemoteProvidersView (Providers) │
56-
│ │ ├── ToolsManagerView (Tools) │
56+
│ │ ├── ToolsManagerView (Tools & Plugin Config) │
5757
│ │ ├── AgentsView (Agents) │
5858
│ │ ├── SkillsView (Skills) │
5959
│ │ ├── MemoryView (Memory) │
@@ -77,6 +77,8 @@ Canonical reference for all Osaurus features, their status, and documentation.
7777
│ ├── Tools │
7878
│ │ ├── ToolRegistry │
7979
│ │ ├── PluginManager │
80+
│ │ ├── PluginHostAPI (v2 host callbacks: config, db, log) │
81+
│ │ ├── PluginDatabase (Sandboxed per-plugin SQLite) │
8082
│ │ └── MCPProviderTool (Wrapped remote MCP tools) │
8183
│ ├── Agents │
8284
│ │ └── AgentManager (Agent lifecycle and active agent) │
@@ -116,7 +118,7 @@ Canonical reference for all Osaurus features, their status, and documentation.
116118
│ └── HTTPHandler (OpenAI/Anthropic/Ollama API handlers) │
117119
├─────────────────────────────────────────────────────────────────────────┤
118120
│ CLI (OsaurusCLI Package) │
119-
│ └── Commands: serve, stop, status, ui, list, show, run, mcp, tools, version │
121+
│ └── Commands: serve, stop, status, ui, list, show, run, mcp, tools (install, dev, ...), version │
120122
└─────────────────────────────────────────────────────────────────────────┘
121123
```
122124

@@ -341,6 +343,7 @@ Canonical reference for all Osaurus features, their status, and documentation.
341343
| `description` | Brief description of the agent |
342344
| `systemPrompt` | Instructions prepended to all chats |
343345
| `enabledTools` | Map of tool name → enabled/disabled |
346+
| `enabledPlugins` | Map of plugin ID → enabled/disabled |
344347
| `themeId` | Optional custom theme to apply |
345348
| `defaultModel` | Optional model ID for this agent |
346349
| `temperature` | Optional temperature override |
@@ -559,22 +562,41 @@ Canonical reference for all Osaurus features, their status, and documentation.
559562

560563
### Tools & Plugins
561564

562-
**Purpose:** Extend Osaurus with custom functionality.
565+
**Purpose:** Extend Osaurus with custom functionality including tools, HTTP routes, storage, configuration UI, and web apps.
563566

564567
**Components:**
565568

566569
- `Tools/OsaurusTool.swift` — Tool protocol
567570
- `Tools/ExternalTool.swift` — External plugin wrapper
568571
- `Tools/ToolRegistry.swift` — Tool registration
569572
- `Tools/SchemaValidator.swift` — JSON schema validation
570-
- `Managers/PluginManager.swift` — Plugin lifecycle
573+
- `Managers/PluginManager.swift` — Plugin discovery, loading, unloading
574+
- `Services/PluginHostAPI.swift` — v2 host API callbacks (config, db, log)
575+
- `Storage/PluginDatabase.swift` — Sandboxed per-plugin SQLite database
576+
- `Models/PluginHTTP.swift` — HTTP request/response models, rate limiter, MIME types
577+
- `Models/ExternalPlugin.swift` — C ABI wrapper with v1/v2 support
578+
- `Views/PluginConfigView.swift` — Native SwiftUI config UI renderer
579+
- `Views/PluginsView.swift` — Plugin detail view (README, Settings, Changelog, Routes)
571580

572581
**Plugin Types:**
573582

583+
- **v1 plugins** — Tools only, via `osaurus_plugin_entry`
584+
- **v2 plugins** — Tools + routes + storage + config, via `osaurus_plugin_entry_v2`
574585
- **System plugins** — Built-in tools (filesystem, browser, git, etc.)
575-
- **External plugins** — Compiled binaries communicating via stdin/stdout
576586
- **MCP provider tools** — Tools from remote MCP servers
577587

588+
**Plugin Capabilities (v2):**
589+
590+
| Capability | Manifest Key | Description |
591+
| ---------- | --------------------- | ---------------------------------------------------- |
592+
| Tools | `capabilities.tools` | AI-callable functions |
593+
| Routes | `capabilities.routes` | HTTP endpoints (OAuth, webhooks, APIs) |
594+
| Config | `capabilities.config` | Native settings UI with validation |
595+
| Web | `capabilities.web` | Static frontend serving with context injection |
596+
| Docs | `docs` | README, changelog, and external links |
597+
598+
Routes are agent-scoped via the `enabledPlugins` map on each agent. See [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) for the full reference.
599+
578600
---
579601

580602
### Skills

0 commit comments

Comments
 (0)