docs: document TypeScript client boundaries

[neubig]

HUMAN:

I reviewed the TypeScript client architecture and contributor guidance, then documented its API ownership boundaries and cross-repository workflow.

AGENT:

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

Why

Contributors need to distinguish typed Agent Server API access from backend behavior, Agent Canvas UI, and automation lifecycle code. This prevents duplicated logic and PRs being opened in the wrong repository.

Summary

• Document repository ownership in AGENTS.md and README.md.
• Add cross-repository placement rules to CONTRIBUTING.md.
• Clarify the SDK → OpenAPI → TypeScript client → Canvas flow.
• Explain that misplaced PRs should be closed and moved to the owning repository.

Issue Number

Fixes #355

How to Test

Review the three changed Markdown files for accurate repository links, API ownership, and contribution guidance.

Video/Screenshots

Not applicable: documentation-only change.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

[github-actions]

Endpoint audit

⚠️ 12 actionable Agent Server contract divergence(s) · report-only

Contract: pinned release artifact

Category	Count
Actionable client-only calls	0
Actionable server-only operations	12
Documented non-divergences	13
Agent Server contract operations	123
Audited handwritten client endpoints	119

Actionable client-only calls (0)

none

Actionable server-only operations (12)

• DELETE /api/llm/provider-connections/{}
• GET /api/conversations/{}/events
• GET /api/file/archive
• GET /api/git/commits
• GET /api/git/commits/{}/changes
• GET /api/init
• GET /api/llm/provider-connections
• PATCH /api/llm/provider-connections/{}
• POST /api/conversations/{}/load_plugin
• POST /api/file/create_directory
• POST /api/init
• POST /api/llm/provider-connections

Documented non-divergences (13)

Client calls intentionally absent from the filtered contract (11)

• GET /
• GET /alive
• GET /health
• GET /ready
• GET /server_info

Reason: Operational Agent Server endpoints intentionally excluded from the filtered public release artifact.
Owner: OpenHands runtime maintainers

• DELETE /api/meta-profiles/{}
• GET /api/meta-profiles
• GET /api/meta-profiles/{}
• POST /api/meta-profiles/{}
• POST /api/meta-profiles/{}/activate

Reason: Client-ahead API stacked on the pending Agent Server meta-profiles implementation.
Owner: OpenHands SDK maintainers
Tracking: OpenHands/software-agent-sdk#3744

• POST /api/profiles/{}/validate

Reason: Client-ahead API stacked on the pending Agent Server pre-flight LLM validation endpoint.
Owner: OpenHands TypeScript client maintainers
Tracking: OpenHands/software-agent-sdk#4422

Server operations covered by an exposed browser URL (2)

• GET /api/conversations/{}/workspace
• GET /api/conversations/{}/workspace/{}

Reason: RemoteWorkspace.startWorkspaceSession exposes these authenticated URLs for browser iframe and file requests; they are not HttpClient method calls.
Owner: OpenHands TypeScript client maintainers

[all-hands-bot]

🤖 OpenHands is reviewing this PR.

Head commit: 3c5e4aa68fbe39cf35145bd29e7810329a345d06
View the conversation: https://oss-agent-canvas.ngrok.dev/conversations/25d165a2-9760-4748-a3c5-61b4693f1474

This comment was posted by an AI agent (OpenHands).

[all-hands-bot]

This review was created by an AI agent (OpenHands) on behalf of the repository maintainers.

Verdict: Approve. Risk: Low.

This is a documentation-only PR (+18/-1 across three Markdown files) that adds repository ownership boundaries and cross-repository placement guidance to AGENTS.md, README.md, and CONTRIBUTING.md. The content is accurate and consistent with the repository's existing architecture description:

• The SDK → OpenAPI contract → TypeScript client → Agent Canvas flow is correctly described.
• Repository links to software-agent-sdk, OpenHands/OpenHands, and OpenHands/automation are valid and correctly attributed.
• The guidance to close and relocate misplaced PRs rather than merge them here aligns with the cross-repository boundary policy already documented in AGENTS.md.
• The CONTRIBUTING.md additions integrate cleanly with the existing PR checklist.

No material bugs, security concerns, or design flaws were found. The change is internally consistent across the three files (minor wording variation between them is acceptable for audience/context). No inline comments are warranted.

[all-hands-bot]

🤖 OpenHands is reviewing this PR.

Head commit: 3a6383fda0b3406ab8e4688d50b907fd315ef8fa
View the conversation: https://oss-agent-canvas.ngrok.dev/conversations/a4760905-542f-4184-8c40-4d5a7115739f

This comment was posted by an AI agent (OpenHands).

[all-hands-bot]

This review was created by an AI agent (OpenHands) on behalf of the repository maintainers.

Verdict: No material findings. Risk: Low.

This is a documentation-only PR (+18/-1 across AGENTS.md, CONTRIBUTING.md, and README.md) that adds repository ownership boundaries and cross-repository placement guidance.

The content is accurate and internally consistent:

• The SDK → OpenAPI contract → TypeScript client → Agent Canvas flow is correctly described in all three files.
• Repository links to software-agent-sdk, OpenHands/OpenHands, extensions, and automation are valid and correctly attributed.
• The ownership split (backend behavior in the SDK, typed API access here, UI in Canvas, automation lifecycle in automation) is consistent with the repository's existing architecture documentation.
• The guidance to close and relocate misplaced PRs aligns with the cross-repository boundary policy.
• The CONTRIBUTING.md checklist additions integrate cleanly with the existing PR guidance.

One minor inconsistency (not blocking): CONTRIBUTING.md omits OpenHands/extensions from its ownership list, while AGENTS.md and README.md both include it. This is a minor completeness gap rather than an error, since CONTRIBUTING.md focuses on the most common misplacement targets.

No bugs, security concerns, or design flaws were found. No inline comments are warranted.