[anolisa] feat: [anolisa] define adapter framework contract for agent integrations

[kongche-jbw]

Component

anolisa

Problem Statement

ANOLISA components may need to integrate with different agent frameworks after installation, such as OpenClaw, Cosh, Hermes Agent, Claude Code, Codex, Qoder CLI, and QwenCode.

Today this integration path is not fully standardized across raw and RPM artifacts. For example, a raw artifact can carry .anolisa/component.toml, while an RPM package also needs a component contract so anolisa install <component> and later anolisa adapter enable <component> <framework> can share the same lifecycle semantics.

We need a clear adapter manifest contract and framework-driver skeleton so component owners can ship framework-specific resources without embedding scripts or command behavior in the manifest.

Proposed Solution

Define the first-stage adapter framework contract in component.toml.

The manifest should declare adapter publishing metadata only:

• target framework, e.g. openclaw, cosh, hermes, claude-code, codex, qodercli, qwencode
• adapter resource source path inside the artifact
• installed adapter resource root under {datadir}/adapters/{component}/{framework}/
• framework-native plugin id when applicable
• optional display metadata
• optional bundle metadata such as schema version and entry file
• optional compatibility metadata such as driver schema and framework version

The manifest must not declare executable behavior such as shell scripts, argv, post-install hooks, uninstall commands, or arbitrary DSL steps.

Framework-specific behavior should live in built-in Rust drivers managed by AdapterManager. The manager owns locking, state receipts, claim validation, central logging, and safe execution boundaries. Drivers own framework-specific enable/disable/status semantics.

First-stage implementation should focus on:

• extending the adapter schema in component.toml
• keeping raw and future RPM contracts aligned
• preserving current install behavior: install lays resources only
• keeping adapter enable/disable/status/scan as the framework lifecycle surface
• validating OpenClaw as the first vertical slice

Alternatives Considered

1. Component-owned shell scripts for each adapter
   Rejected because behavior becomes hard to audit, test, and manage safely.

2. A generic manifest DSL for copy/symlink/run/merge operations
   Rejected for the first stage because adapter behavior is framework-specific and would likely grow into a shell-like DSL.

3. Pure directory discovery without manifest declarations
   Rejected because component owners need an explicit publishing contract, and packaging/linting should detect declared-but-missing or undeclared resources.

Additional Context

Target frameworks to account for in the contract:

• OpenClaw
• Cosh
• Hermes Agent
• Claude Code
• Codex
• Qoder CLI
• QwenCode

The initial issue should not require implementing every framework driver. It should establish the adapter manifest schema and driver skeleton so each framework can be added incrementally.

[github-actions]

🔀 Issue Triage

This issue has been automatically assigned to @kongche-jbw @ikunkun-sys as the maintainer(s) of anolisa.

Maintainers, please review and triage this issue. Set a priority label and update the status as needed. Thanks! 🙏

[kongche-jbw]

Closing rationale: the first-stage adapter framework contract has landed through #999, and was extended by #1048, #1066, #1077, and #1158. The current contract supports declarative adapter metadata, framework-specific drivers, resource roots, package-managed contract discovery, and skill-only bundles. Additional framework drivers such as Cosh/Codex/QwenCode should be tracked independently.