moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-tool-opencode/modules/core/providers.md

@@ -0,0 +1,310 @@
+---
+source: https://opencode.ai/docs/providers/
+fetched: 2026-01-08
+title: Providers
+---
+
+# OpenCode Providers Documentation
+
+## Overview
+
+OpenCode supports **75+ LLM providers** through the AI SDK and Models.dev, including local model execution. Setting up a provider requires two steps:
+
+1. Add API keys via the `/connect` command (stored in `~/.local/share/opencode/auth.json`)
+2. Configure the provider in your OpenCode config file
+
+## Base URL Customization
+
+Users can override default endpoints:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "anthropic": {
+      "options": {
+        "baseURL": "https://api.anthropic.com/v1"
+      }
+    }
+  }
+}
+```
+
+## OpenCode Zen
+
+OpenCode Zen provides curated, tested models from the OpenCode team. Setup requires:
+
+1. Run `/connect`, select opencode, visit opencode.ai/auth
+2. Sign in and copy your API key
+3. Use `/models` to view recommendations
+
+## Provider Directory
+
+### Amazon Bedrock
+
+- Requires Model Catalog access
+- Authentication via AWS credentials, profiles, or bearer tokens
+- Supports VPC endpoints with custom endpoint configuration
+- Priority: Bearer Token > AWS Credential Chain
+
+```json
+{
+  "provider": {
+    "amazon-bedrock": {
+      "region": "us-west-2",
+      "profile": "production",
+      "endpoint": "https://bedrock-runtime.us-west-2.amazonaws.com"
+    }
+  }
+}
+```
+
+### Anthropic
+
+- Recommends Claude Pro/Max subscription
+- Supports OAuth flow or manual API key entry
+- Available via `/connect` command
+
+```json
+{
+  "provider": {
+    "anthropic": {
+      "options": {
+        "apiKey": "{env:ANTHROPIC_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Azure OpenAI
+
+- Requires resource creation and model deployment
+- Deployment names must match model names
+- Set `AZURE_RESOURCE_NAME` environment variable
+
+**Note:** "I'm sorry" errors may indicate content filter issues—switch from DefaultV2 to Default.
+
+```json
+{
+  "provider": {
+    "azure-openai": {
+      "options": {
+        "resourceName": "{env:AZURE_RESOURCE_NAME}",
+        "apiKey": "{env:AZURE_OPENAI_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Google Vertex AI
+
+- Requires Google Cloud project with Vertex AI API enabled
+- Key environment variables: `GOOGLE_CLOUD_PROJECT`, `VERTEX_LOCATION`
+- Supports service account authentication
+- "Global" region recommended for availability
+
+```json
+{
+  "provider": {
+    "google-vertex": {
+      "options": {
+        "project": "{env:GOOGLE_CLOUD_PROJECT}",
+        "location": "us-central1"
+      }
+    }
+  }
+}
+```
+
+### Local Models (Ollama, LM Studio, llama.cpp)
+
+Custom provider configuration example:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama (local)",
+      "options": {
+        "baseURL": "http://localhost:11434/v1"
+      },
+      "models": {
+        "llama2": {
+          "name": "Llama 2"
+        }
+      }
+    }
+  }
+}
+```
+
+### Helicone
+
+Observability platform supporting 17+ providers with automatic routing. Optional custom configuration:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "helicone": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Helicone",
+      "options": {
+        "baseURL": "https://ai-gateway.helicone.ai",
+        "headers": {
+          "Helicone-Cache-Enabled": "true",
+          "Helicone-User-Id": "opencode"
+        }
+      }
+    }
+  }
+}
+```
+
+Common headers include:
+- `Helicone-Cache-Enabled`
+- `Helicone-User-Id`
+- `Helicone-Property-[Name]`
+- `Helicone-Prompt-Id`
+- `Helicone-Session-Id`
+
+### OpenRouter & ZenMux
+
+Support custom model additions via config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "openrouter": {
+      "models": {
+        "somecoolnewmodel": {}
+      }
+    }
+  }
+}
+```
+
+OpenRouter supports provider routing:
+
+```json
+{
+  "provider": {
+    "openrouter": {
+      "models": {
+        "anthropic/claude-sonnet-4": {
+          "options": {
+            "order": ["baseten"],
+            "allow_fallbacks": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Vercel AI Gateway
+
+```json
+{
+  "provider": {
+    "vercel": {
+      "models": {
+        "anthropic/claude-sonnet-4": {
+          "options": {
+            "order": ["anthropic", "vertex"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Routing options: `order`, `only`, `zeroDataRetention`.
+
+## Custom Provider (OpenAI-Compatible)
+
+1. Run `/connect` and select "Other"
+2. Enter unique provider ID
+3. Enter API key
+4. Configure in `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "myprovider": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Display Name",
+      "options": {
+        "baseURL": "https://api.myprovider.com/v1",
+        "apiKey": "{env:CUSTOM_API_KEY}",
+        "headers": {
+          "Authorization": "Bearer token"
+        }
+      },
+      "models": {
+        "model-id": {
+          "name": "Display Name",
+          "limit": {
+            "context": 200000,
+            "output": 65536
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Key options: `baseURL`, `apiKey`, `headers`, and model `limit` (context/output tokens).
+
+## Additional Providers Listed
+
+- Amazon Bedrock
+- Anthropic
+- Azure OpenAI
+- Azure Cognitive Services
+- Baseten
+- Cerebras
+- Cloudflare AI Gateway
+- Cortecs
+- DeepSeek
+- Deep Infra
+- Fireworks AI
+- GitHub Copilot
+- Google Vertex AI
+- Groq
+- Hugging Face
+- Helicone
+- llama.cpp
+- IO.NET
+- LM Studio
+- Moonshot AI
+- MiniMax
+- Nebius Token Factory
+- Ollama
+- Ollama Cloud
+- OpenAI
+- OpenRouter
+- SAP AI Core
+- OVHcloud AI Endpoints
+- Together AI
+- Venice AI
+- Vercel AI Gateway
+- xAI
+- Z.AI
+- ZenMux
+
+## Troubleshooting
+
+- Verify credentials: `opencode auth list`
+- Confirm provider ID matches across `/connect` and config
+- Validate npm package (use provider-specific or `@ai-sdk/openai-compatible`)
+- Check `baseURL` correctness

moai_adk/templates/.claude/skills/moai-tool-opencode/modules/core/troubleshooting.md

@@ -0,0 +1,124 @@
+---
+source: https://opencode.ai/docs/troubleshooting/
+fetched: 2026-01-08
+title: Troubleshooting
+---
+
+# OpenCode Troubleshooting Guide
+
+## Overview
+
+OpenCode provides debugging tools through logs and local storage to help resolve issues.
+
+## Logs Location
+
+Log files are stored at:
+
+| Platform | Path |
+|----------|------|
+| macOS/Linux | `~/.local/share/opencode/log/` |
+| Windows | `%USERPROFILE%\.local\share\opencode\log\` |
+
+Files use timestamp naming (e.g., `2025-01-09T123456.log`) with the 10 most recent retained.
+
+### Enable Detailed Logging
+
+```bash
+opencode --log-level DEBUG
+```
+
+## Storage Location
+
+Application data resides at:
+
+| Platform | Path |
+|----------|------|
+| macOS/Linux | `~/.local/share/opencode/` |
+| Windows | `%USERPROFILE%\.local\share\opencode` |
+
+### Contents
+
+- `auth.json` - API keys and OAuth tokens
+- `log/` - Application logs
+- `project/` - Session and message data
+  - `./<project-slug>/storage/` for Git repos
+  - `./global/storage/` otherwise
+
+## Getting Help
+
+### GitHub Issues
+
+Report bugs at github.com/anomalyco/opencode/issues
+
+### Discord Community
+
+Real-time assistance available at opencode.ai/discord
+
+## Common Issues & Solutions
+
+### Won't Start
+
+- Check logs
+- Run with `--print-logs`
+- Verify latest version via `opencode upgrade`
+
+```bash
+opencode --print-logs
+opencode upgrade
+```
+
+### Authentication Problems
+
+- Use `/connect` command in TUI
+- Validate API keys
+- Confirm network access to provider APIs
+
+### Model Unavailable
+
+- Confirm provider authentication
+- Verify correct model naming format (`<providerId>/<modelId>`)
+- Use `opencode models` command to check access
+
+```bash
+opencode models
+```
+
+### ProviderInitError
+
+- Verify provider setup
+- Clear configuration via `rm -rf ~/.local/share/opencode`
+- Re-authenticate
+
+```bash
+rm -rf ~/.local/share/opencode
+opencode
+/connect
+```
+
+### API Call Errors
+
+- Clear provider cache with `rm -rf ~/.cache/opencode`
+- Restart to reinstall latest packages
+
+```bash
+rm -rf ~/.cache/opencode
+opencode
+```
+
+### Linux Copy/Paste Issues
+
+Install clipboard utilities based on your environment:
+
+| Environment | Required Package |
+|-------------|------------------|
+| X11 | `xclip` or `xsel` |
+| Wayland | `wl-clipboard` |
+| Headless | `xvfb` |
+
+```bash
+# For X11
+sudo apt install xclip
+
+# For Wayland
+sudo apt install wl-clipboard
+```

moai_adk/templates/.claude/skills/moai-tool-opencode/modules/develop/ecosystem.md

@@ -0,0 +1,75 @@
+---
+source: https://opencode.ai/docs/ecosystem/
+fetched: 2026-01-08
+title: Ecosystem
+---
+
+# OpenCode Ecosystem
+
+## Overview
+
+This page showcases projects and integrations built with OpenCode. Community members can submit PRs to add projects.
+
+## External Resources
+
+- [awesome-opencode](https://github.com/awesome-opencode/awesome-opencode) - Curated list of OpenCode resources
+- [opencode.cafe](https://opencode.cafe) - Community hub
+
+## Plugins
+
+Community-developed plugins extending OpenCode functionality:
+
+| Plugin | Description |
+|--------|-------------|
+| **opencode-helicone-session** | Automatically inject Helicone session headers for request grouping |
+| **opencode-type-inject** | Auto-inject TypeScript/Svelte types into file reads with lookup tools |
+| **opencode-openai-codex-auth** | Use your ChatGPT Plus/Pro subscription instead of API credits |
+| **opencode-gemini-auth** | Use your existing Gemini plan instead of API billing |
+| **opencode-antigravity-auth** | Use Antigravity's free models instead of API billing |
+| **opencode-devcontainers** | Multi-branch devcontainer isolation with shallow clones and auto-assigned ports |
+| **opencode-dynamic-context-pruning** | Optimize token usage by pruning obsolete tool outputs |
+| **opencode-websearch-cited** | Add native websearch support for supported providers with Google grounded style |
+| **opencode-pty** | Enables AI agents to run background processes in a PTY, send interactive input |
+| **oh-my-opencode** | Background agents, pre-built LSP/AST/MCP tools, curated agents, Claude Code compatible |
+| **opencode-supermemory** | Persistent memory across sessions using Supermemory |
+| **opencode-scheduler** | Schedule recurring jobs using launchd (Mac) or systemd (Linux) with cron syntax |
+
+## Projects
+
+Community projects leveraging OpenCode:
+
+| Project | Description |
+|---------|-------------|
+| **kimaki** | Discord bot to control OpenCode sessions, built on the SDK |
+| **opencode.nvim** | Neovim plugin for editor-aware prompts |
+| **opencode.nvim (variant)** | Terminal-based AI coding in Neovim |
+| **portal** | Mobile-first web UI for OpenCode over Tailscale/VPN |
+| **OpenChamber** | Web / Desktop App and VS Code Extension for OpenCode |
+| **OpenCode-Obsidian** | Obsidian plugin that embeds OpenCode in Obsidian's UI |
+
+## Agents
+
+Agent frameworks and configurations:
+
+| Agent | Description |
+|-------|-------------|
+| **Agentic** | Modular AI agents and commands for structured development |
+| **opencode-agents** | Configs, prompts, agents, and plugins for enhanced workflows |
+
+## Contributing
+
+To add your project:
+
+1. Fork the OpenCode repository
+2. Add your project to the ecosystem page
+3. Submit a pull request
+
+Include:
+- Project name
+- Brief description
+- Link to repository/website
+
+## Community
+
+- **GitHub**: Report issues and contribute
+- **Discord**: Real-time community support

moai_adk/templates/.claude/skills/moai-tool-opencode/modules/develop/plugins.md

@@ -0,0 +1,218 @@
+---
+source: https://opencode.ai/docs/plugins/
+fetched: 2026-01-08
+title: Plugins
+---
+
+# OpenCode Plugins Documentation
+
+## Overview
+
+OpenCode enables extensibility through plugins - JavaScript/TypeScript modules that hook into various system events. Developers can create custom functionality by implementing event handlers and returning a hooks object from their plugin function.
+
+## Loading Plugins
+
+### Local Plugins
+
+Reside in project-level or global directories and load automatically:
+
+| Location | Scope |
+|----------|-------|
+| `.opencode/plugin/` | Project |
+| `~/.config/opencode/plugin/` | Global |
+
+### NPM Plugins
+
+Specify in configuration:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-helicone-session",
+    "@my-org/custom-plugin"
+  ]
+}
+```
+
+Both scoped and unscoped packages work. The system installs dependencies via Bun and caches them in `~/.cache/opencode/node_modules/`.
+
+## Plugin Structure
+
+A basic plugin exports an async function receiving a context object:
+
+```javascript
+export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
+  // Setup code here
+
+  return {
+    // Hook implementations
+  }
+}
+```
+
+### Context Object
+
+| Property | Description |
+|----------|-------------|
+| `project` | Project metadata |
+| `client` | SDK client instance |
+| `$` | Bun's shell API |
+| `directory` | Plugin directory path |
+| `worktree` | Git worktree path |
+
+## Custom Tools
+
+Extend OpenCode's functionality using the `@opencode-ai/plugin` package:
+
+```typescript
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Custom tool description",
+  args: {
+    input: tool.schema.string().describe("Input parameter"),
+  },
+  async execute(args) {
+    return `Result: ${args.input}`
+  },
+})
+```
+
+## Event Subscriptions
+
+React to various system events:
+
+```javascript
+export const MyPlugin = async (ctx) => {
+  return {
+    "session.created": async (event) => {
+      console.log("Session created:", event.session.id)
+    },
+    "file.written": async (event) => {
+      console.log("File written:", event.path)
+    },
+    "tool.executing": async (event) => {
+      console.log("Tool executing:", event.tool)
+    }
+  }
+}
+```
+
+### Available Events
+
+| Event | Description |
+|-------|-------------|
+| `session.created` | Session created |
+| `session.deleted` | Session deleted |
+| `file.written` | File written |
+| `file.deleted` | File deleted |
+| `lsp.diagnostic` | LSP diagnostic received |
+| `permission.requested` | Permission requested |
+| `tool.executing` | Tool about to execute |
+| `tool.executed` | Tool finished executing |
+| `experimental.session.compacting` | Session compaction |
+
+## Structured Logging
+
+Use `client.app.log()` with severity levels:
+
+```javascript
+export const MyPlugin = async ({ client }) => {
+  await client.app.log({
+    level: "info",
+    message: "Plugin initialized"
+  })
+
+  await client.app.log({
+    level: "warn",
+    message: "Something might be wrong"
+  })
+
+  await client.app.log({
+    level: "error",
+    message: "Something went wrong"
+  })
+
+  return {}
+}
+```
+
+**Important:** Use this instead of `console.log()` for proper log handling.
+
+## Session Compaction Hooks
+
+Inject domain-specific context before LLM-generated continuation summaries:
+
+```javascript
+export const MyPlugin = async (ctx) => {
+  return {
+    "experimental.session.compacting": async (event) => {
+      return {
+        context: "Important context to preserve during compaction"
+      }
+    }
+  }
+}
+```
+
+## Dependencies
+
+Local plugins requiring external packages need a `package.json` in the config directory:
+
+```json
+{
+  "dependencies": {
+    "axios": "^1.0.0",
+    "lodash": "^4.0.0"
+  }
+}
+```
+
+OpenCode processes this automatically at startup.
+
+## Full Example
+
+```javascript
+import { tool } from "@opencode-ai/plugin"
+
+// Custom tool
+const myTool = tool({
+  description: "Perform custom operation",
+  args: {
+    data: tool.schema.string().describe("Data to process"),
+  },
+  async execute(args) {
+    return `Processed: ${args.data}`
+  },
+})
+
+// Plugin with hooks
+export const MyPlugin = async ({ client, project }) => {
+  // Initialize
+  await client.app.log({
+    level: "info",
+    message: `Plugin loaded for ${project.name}`
+  })
+
+  return {
+    "session.created": async (event) => {
+      await client.app.log({
+        level: "debug",
+        message: `New session: ${event.session.id}`
+      })
+    },
+
+    "tool.executed": async (event) => {
+      if (event.tool === "bash") {
+        await client.app.log({
+          level: "info",
+          message: `Bash command executed: ${event.input}`
+        })
+      }
+    }
+  }
+}
+
+export { myTool }
+```