RFC: Runtime Plugin Pattern for Executable Tools

# RFC: Runtime Plugin Pattern for Agent-Plugins

## Summary

Introduce a **runtime plugin pattern** that enables plugin authors to ship **executable tools** alongside skill guidance, allowing agent hosts to register these tools directly into the agent's tool system for fully autonomous workflows.

Currently, agent-plugins ships **skill-only plugins** that provide markdown guidance for AI agents. This RFC proposes extending the pattern to also support **runtime plugins** that execute code directly within the agent host environment.

## Use Case

**Problem**: Some workflows benefit from tools that execute within the agent host rather than requiring the agent to make external API calls. Examples:
- **Agent payments**: Agent needs to transparently pay for paywalled content without human-in-the-loop for each transaction
- **File system operations**: Direct file access without shelling out to CLI tools
- **Local database queries**: Query local SQLite without external service
- **Crypto operations**: Sign transactions or verify signatures locally

**Current limitation**: Skills can only provide guidance. The agent must either:
1. Shell out to CLI tools (brittle, platform-dependent)
2. Make HTTP requests to external services (requires hosting, auth, network)
3. Ask the user to install and configure external tooling

**Desired state**: Plugin authors can ship executable tools that agent hosts register directly, enabling seamless autonomous workflows.

## Proposal

### Recommended Repository Layout (Multi-Harness)

Based on guidance from the OpenClaw Foundation, plugin authors targeting multiple agent harnesses should use a monorepo with shared core logic and harness-specific adapters:

```
acme-agent-plugin/
├── packages/
│ ├── core/ # Shared business logic (protocol, API calls)
│ ├── openclaw/
│ │ ├── openclaw.plugin.json # Native OpenClaw runtime manifest
│ │ ├── package.json
│ │ └── src/index.ts
│ └── hermes/
│ ├── plugin.yaml # Native Hermes manifest
│ ├── pyproject.toml
│ └── src/acme_plugin/
```

**Key principles:**
- **Core logic lives once** — business logic (e.g., x402 protocol handling, API calls) is written once in `packages/core/` and imported by each harness adapter
- **Each harness owns its manifest format** — `openclaw.plugin.json`, `plugin.yaml`, etc. No universal manifest schema
- **Language flexibility** — core can be TypeScript, Python, or a shared spec/schema when crossing language boundaries
- **Independent publishing** — each `packages//` subfolder publishes independently to its respective registry (ClawHub for OpenClaw, PyPI for Python harnesses, etc.)

For single-harness plugins, the flat structure remains valid:

```
plugins/aws-agent-payments/
├── skills/x402-payments/SKILL.md # Agent guidance (works standalone)
├── openclaw.plugin.json # Runtime manifest
├── src/ # TypeScript source
├── dist/ # Compiled JS
└── README.md
```

### Runtime Plugin Manifest (`openclaw.plugin.json`)

```json
{
"name": "aws-agent-payments",
"version": "1.0.0",
"description": "Payment tools for autonomous agents",
"main": "dist/index.js",
"exports": {
"tools": "./dist/index.js",
"skills": "./skills/"
},
"pluginApi": "2026.4.0",
"permissions": ["network", "secrets"],
"dependencies": {
"@aws-sdk/client-bedrock-agentcore": "^1.0.0"
}
}
```

### Tool Export Interface

The main entry point exports tools in a standard format:

```typescript
export const tools = {
setup_payments: {
description: "Set up payment infrastructure",
parameters: {
type: "object",
properties: {
role_arn: { type: "string" }
},
required: ["role_arn"]
},
handler: async (params, context) => {
return { success: true, payment_manager_arn: "..." };
}
}
};
```

### Agent Host Integration

Agent hosts that support runtime plugins:

1. **Discover** plugins with runtime manifests during startup
2. **Validate** permissions and compatibility
3. **Load** the module and register tools into the agent's tool system
4. **Execute** tools when invoked by the agent during conversation

### Coexistence with Skills

Runtime plugins **supplement** skills, not replace them:

- **Skill provides** agent guidance, protocol knowledge, error handling strategies
- **Runtime tools provide** the executable implementations
- **Agent uses** runtime tools (if available) OR follows skill guidance to use external APIs

### Security Requirements

1. **IAM role separation** — plugins with payment/write capabilities must recommend separate IAM roles for setup vs runtime execution. The running agent should not be able to modify its own infrastructure.
2. **Credential isolation** — credentials must be read from environment variables or secure config at execution time, NEVER passed as tool parameters to the LLM
3. **User approval gates** — spending/mutating tools must require explicit user approval by default (opt-out, not opt-in)
4. **Budget controls** — tools that can spend money must surface budget caps and session TTLs
5. **Permissions model** — manifest declares required permissions (`network`, `filesystem`, `secrets`, etc.) for audit and enforcement

## Out of Scope

- Plugin sandboxing/isolation (security is handled by each agent host's existing trust model)
- Package management changes (uses existing distribution channels per harness)
- MCP server integration (separate concern, can coexist)
- Universal manifest schema (each harness defines its own)

## Potential Challenges

### Security

**Challenge**: Runtime plugins execute arbitrary code in the agent host.

**Mitigation**:
- Permissions model in manifest
- Agent hosts restrict which plugins can be installed/enabled via config
- Code signing and trusted publisher verification via distribution registries (e.g., ClawHub)

### Compatibility

**Challenge**: Plugin API may evolve between agent host versions.

**Mitigation**:
- Semantic versioning on `pluginApi` field
- Hosts validate compatibility at load time
- Graceful degradation: if runtime tools can't load, skill-only mode still works

### Maintenance

**Challenge**: Runtime plugins require building, testing, dependency management.

**Mitigation**:
- Standard language-native build pipelines (tsc, setuptools, etc.)
- Template repositories for new runtime plugins
- Plugin can start as skill-only, add runtime later

## Dependencies and Integrations

- **Distribution**: ClawHub (OpenClaw), PyPI (Python harnesses), etc.
- **Build toolchain**: Standard TypeScript/Python tooling
- **Testing**: Jest/Vitest or pytest for tool implementations
- **Reference implementation**: [`@aws/aws-agent-payments`](https://clawhub.ai/packages/@aws/aws-agent-payments)

## Implementation Plan

1. Define `openclaw.plugin.json` manifest schema (this RFC)
2. Implement plugin discovery and loading in OpenClaw core
3. Ship aws-agent-payments as reference implementation
4. Document authoring guidelines (single-harness + multi-harness patterns)
5. Create plugin authoring template repos

---

**This RFC is extracted from practical experience building agent payments for autonomous agents, where the skill-only approach works for coding agents but stateful autonomous agents benefit from direct tool registration.**

Related: [awslabs/agent-plugins#243](https://github.com/awslabs/agent-plugins/pull/243), [awslabs/agentcore-samples#1797](https://github.com/awslabs/agentcore-samples/pull/1797)

/cc @peterjiang-dev

No existing implementation files or tests are named. Start by reviewing the proposed openclaw.plugin.json manifest, the implementation plan, and related PRs #243 and #1797; done would require an agreed manifest and plugin-loading design, plus the planned reference implementation and authoring documentation.

Written by the indexing model from the issue text.