OpenHands / OpenHands/software-agent-sdk

Define typed ACP capability and session contracts

Open
#4,973 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement ready-for-dev sdk typing
Dominant language
Python
Stars
1.1k
Forks
539
Avg merge
1d 19h
Merged PRs (30d)
137

Description

Parent tracking issue: #4905

Desired Behavior

ACP integration code should express config options, model selection, MCP capabilities, protocol errors, file-credential revisions, tracing nodes, and background task slots through explicit typed models or protocols. ACPAgent and its helpers should use direct attribute access against those contracts instead of probing arbitrary objects with getattr/setattr.

Prefer shared base classes, protocols, or discriminated models where multiple ACP implementations expose the same capability; keep compatibility normalization at the ACP boundary.

Scope

  • openhands-sdk/openhands/sdk/agent/acp_agent.py
  • openhands-sdk/openhands/sdk/agent/acp_models.py
  • openhands-sdk/openhands/sdk/agent/acp_file_credentials.py
  • openhands-sdk/openhands/sdk/agent/acp_tracing.py
  • Relevant ACP tests and the dynamic-attribute baseline

Acceptance Criteria

  • ACP option, model, capability, error, credential, tracing, and task access uses explicit typed contracts and direct attributes.
  • Existing ACP compatibility behavior is preserved at external-library boundaries.
  • Targeted ACP tests cover each normalized input shape and task cleanup path.
  • The forbidden dynamic-attribute baseline shrinks for every call removed by this issue.
  • The full dynamic-attribute checker and relevant type checks pass.

This issue was created by an AI agent (OpenHands) on behalf of the user.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read acp_agent.py and acp_models.py first, then inspect acp_file_credentials.py, acp_tracing.py, the relevant ACP tests, and the dynamic-attribute baseline. Trace the existing compatibility normalization and task cleanup paths before defining the typed contracts. Done means the targeted ACP tests, type checks, and full dynamic-attribute checker pass while preserving external-library compatibility.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend-api-design, testing
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.