[refactor] PR #4893 follow-up: rename platform-op bind to context_bindings

[mmabrouk]

What this changes

A follow-up to the merged PR #4893 (platform-op catalog) that acts on Mahmoud's review.
It renames one catalog field for clarity:

PlatformOp.bind -> PlatformOp.context_bindings

The field maps an endpoint body path to a $ctx.<key> run-context token (the self-targeting
fields the runner fills server-side). bind read as a bare verb; context_bindings says what
the dict holds.

Why it is safe

The rename is SDK-internal only:

• The wire field is unchanged — to_call() still emits context, and ToolCall.context is
  untouched. No wire/golden-contract change.
• The agent-config arm (PlatformToolConfig = {type, op, needs_approval, permission}) does not
  expose this field, so the public config schema is unchanged.
• Only catalog authors write context_bindings (in op_catalog.py); agents never see it.

Files

• sdks/python/agenta/sdk/agents/platform/op_catalog.py — the field, validator, schema-strip,
  to_call, and the commit_revision entry.
• platform/platform_tools.py, tools/models.py, tools/resolver.py — docstring references.
• docs/.../documentation/tools.md + docs/.../interfaces/in-service/tool-models-and-resolution.md
  (the interface inventory) — kept in sync.
• oss/tests/.../platform/test_op_catalog.py — the test name + the construction kwargs.

Tests

• ruff format --check + ruff check clean over the touched SDK paths.
• Platform + tools + skill-catalog suites: 149 passed; test_op_catalog.py +
  test_wire_contract.py: 44 passed.

Scope note

This PR does the one contained naming fix. The other review items (the op abbreviation, the
cross-service args_into wire field, and the method GET/POST question) are interface-level or
design changes and are tracked as separate issues — see the mapping comment on #4893.

https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 28, 2026 12:42pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2a05de31-ae9f-47b2-831d-38f82f8e4527

📥 Commits

Reviewing files that changed from the base of the PR and between d54a8b3 and 8e3ad52.

📒 Files selected for processing (7)

• docs/design/agent-workflows/documentation/tools.md
• docs/design/agent-workflows/interfaces/in-service/tool-models-and-resolution.md
• sdks/python/agenta/sdk/agents/platform/op_catalog.py
• sdks/python/agenta/sdk/agents/platform/platform_tools.py
• sdks/python/agenta/sdk/agents/tools/models.py
• sdks/python/agenta/sdk/agents/tools/resolver.py
• sdks/python/oss/tests/pytest/unit/agents/platform/test_op_catalog.py

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation

  • Clarified platform tool guidance and terminology around run-context bindings.
  • Updated examples and references to use context_bindings consistently.

• Refactor

  • Renamed the SDK field for bound context values from bind to context_bindings.
  • Aligned validation and schema handling with the new naming.

• Tests

  • Updated unit coverage to reflect the renamed context-binding field and expected validation behavior.

Walkthrough

Renames the PlatformOp field bind to context_bindings across the Python SDK (op_catalog.py, platform_tools.py, models.py, resolver.py), the PLATFORM_OPS table entry, the unit test file, and two design documentation files.

Changes

bind → context_bindings rename

Layer / File(s)	Summary
PlatformOp field rename and logic update sdks/python/agenta/sdk/agents/platform/op_catalog.py, sdks/python/agenta/sdk/agents/platform/platform_tools.py, sdks/python/agenta/sdk/agents/tools/models.py, sdks/python/agenta/sdk/agents/tools/resolver.py	PlatformOp.bind renamed to context_bindings; validator, resolved_input_schema, to_call, and PLATFORM_OPS["commit_revision"] updated to use the new field name.
Test updates sdks/python/oss/tests/pytest/unit/agents/platform/test_op_catalog.py	Validation test renamed and updated to pass context_bindings= instead of bind=; module docstring and commit_revision test comment updated.
Documentation updates docs/design/agent-workflows/documentation/tools.md, docs/design/agent-workflows/interfaces/in-service/tool-models-and-resolution.md	All references to bind replaced with context_bindings in resolution descriptions, catalog field tables, and "Watch for when changing" guidance.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 60.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main change: renaming platform-op bind to context_bindings.
Description check	✅ Passed	The description matches the change and explains the rename, safety, files, and tests.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/4893-followups

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says:

Do not merge — needs your review.

What I need reviewed

This is the small, contained slice of your #4893 naming feedback: I renamed the catalog field
PlatformOp.bind -> context_bindings. Please confirm:

1. The chosen name. context_bindings (the dict of endpoint-body-path -> $ctx.<key>
   run-context token). Happy to use a different one — it is SDK-internal, so the cost to change is low.
2. The scope call. I kept this PR to the one field that is internal only (the wire stays
   context, the agent-config arm is unchanged). The other two names you flagged — op (public
   config arm + ~60 refs) and args_into (a SDK<->runner wire field) — are interface-level renames,
   so I tracked them in [refactor] Use full words for abbreviated tool-interface field names (op, args_into) #4909 to be done as one deliberate design-interfaces pass rather than
   crammed in here. Tell me if you'd rather fold op/args_into into this PR instead.

Triage of your #4893 comments

See the mapping comment on #4893 — each comment is
either fixed here or filed as an issue (#4907 methods, #4908 drift, #4909 naming).

Tests: 149 passed (platform + tools + skill-catalog); ruff clean.

[mmabrouk]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[mmabrouk]

lgtm\