Repository navigation
feat: tell the agent whether each secret is personal or org-shared - #1293
Conversation
…shared Group custom secrets as personal vs. organization using the SDK's new SecretSource.scope / scope_description fields (OpenHands/software-agent-sdk#5672) so the agent knows whose identity each secret is before acting with it. - Move CustomSecretScope into integrations.provider so CustomSecret can carry a runtime scope without a circular import; re-export it from secrets_models. Add scope-description constants and secret_scope_fields() helper. - SaasSecretsStore.load(): tag org-shared entries ORGANIZATION (after decrypt, including names suffixed on a personal/shared collision); personal entries keep the default personal scope. - Carry scope (and, in the resolver path, the previously-dropped description) into the SDK secrets built by auth_user_context.get_secrets() and resolver_context.get_secrets(). - Mark the user's own system credentials personal: git provider tokens, named- Mark the user's own system credentials person DevOps tokens, and JIRA_DC_TOKEN (regular and ACP paths share these builders). OPENHANDS_API_KEY stays personal via CustomSecret's default. Org-profile shared secrets are ORGANIZATION. - Tests: SaasSecretsStore.load() scope assignment incl. collision suffix, and auth_user_context secret construction (scope assertions are skipped until the openhands-sdk pin includes #6276). Fields default to None and are ignored by the current pin, so this is a no-op until the openhands-sdk / openhands-agent-server pins are bumped to the first release containing #6276 (see PR description). Refs: #723 Co-authored-by: openhands <openhands@all-hands.dev>
SDK 1.61.0 requires fastmcp>=4.0.3,<5, and every fastmcp 4 release requires mcp 2, so the three move together. The dev compose agent-server tag and the mypy hook's SDK pins follow. mcp 2 changes the OAuth client this server subclasses for MCP installs: - The callback handler returns an AuthorizationCodeResult, not a tuple. - The client checks the issuer the provider names in its redirect (RFC 9207) and rejects a redirect without one when the provider advertises it. The callback route now stores `iss` on the job with the code. - The auth flow runs on httpx2. The SaaS logger quiets httpx2 as it does httpx: it logs each request URL at INFO, and the Tavily proxy URL carries the API key in its query string. Two tests follow SDK 1.61.0: a save writes agent settings schema 10, and a server with neither `command` nor `url` is rejected in other words.
…endpoint
Before SDK 1.61 a server could be saved with neither `command` nor `url`
(`{"enabled": true}`). SDK 1.61 rejects one, and its settings migration
drops it from stored data. Detached member configs are loaded without that
migration, so one such server failed the whole map: the member loaded with
no MCP servers, and a launch with an agent profile answered 422.
coerce_persisted_mcp_config now drops those servers with the SDK's helper
before validating. The org listing route validates a caller's input, so it
uses the SDK's strict coerce_mcp_config and still answers 422.
Coverage reportClick to see where and how coverage changed
This report was generated by python-coverage-comment-action |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Preview verification failed. Details: https://github.com/OpenHands/saas-deploy/pull/2126#issuecomment-6756506963 This comment was posted by an AI agent (OpenHands) on behalf of the user. |
|
Preview verification failed. Details: https://github.com/OpenHands/saas-deploy/pull/2172#issuecomment-6781546923 This comment was posted by an AI agent (OpenHands) on behalf of the user. |
Review posted for
|
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
The wiring is correct. Org-shared secrets get organization scope after _decrypt_kwargs, and that includes the _N collision name. Personal custom secrets, git-provider and named-OAuth tokens, credential-helper tokens, and JIRA_DC_TOKEN (a per-user OAuth token) are all personal. The org-profile path marks shared secrets organization. CustomSecret.scope stays runtime-only, because custom_secrets_serializer and store() still write only secret and description. All CI checks for this head pass. Locally, tests/unit/test_saas_secrets_store.py and tests/unit/test_auth_user_context.py give 31 passed and 1 skipped against the pinned SDK 1.60.1.
Blocking: this PR changes nothing at runtime as merged, but it would close #723.
-
pyproject.tomlstill pinsopenhands-sdk==1.60.1/openhands-agent-server==1.60.1. In that versionStaticSecret.model_fieldsis only['description', 'value']andmodel_configis{}. So every**secret_scope_fields(...)kwarg is silently dropped, and no scope reaches the agent. The only test that checks scope propagation (test_get_secrets_carries_scope_and_description) is skipped in CI for this reason. None of #723's acceptance criteria, such as separate personal/organization groups in<CUSTOM_SECRETS>, can be met on this head. -
The reason given for not bumping the pins is now out of date.
openhands-sdkandopenhands-agent-server1.61.0 were published on 2026-11-09. Tagv1.61.0is 59 commits ahead of the software-agent-sdk#6276 merge commit (e4160d1), with 0 behind. Itsopenhands/sdk/secret/secrets.pydefinesSecretSource.scope/scope_description. I checked this locally by overlaying SDK 1.61.0:- The previously skipped test passes (32 passed).
ResolverUserContext.get_secrets()now forwards both description and scope.SecretRegistry.get_secret_infos()emitsLINEAR_API_KEY → personalandLINEAR_API_KEY_2 → organization, each with the rightscope_description.
So the remaining step is no longer blocked.
-
Fix: bump
openhands-sdk/openhands-agent-serverto1.61.0here (plusuv.lockand the mypy pin indev_config/python/.pre-commit-config.yaml), so CI runs the scope test and the feature actually works. If you'd rather keep the bump in its own PR, dropFixes #723so merging this doesn't close the issue before the behavior ships.
🔄 CHANGES REQUESTED
LLM profile: unknown · Model: openhands/claude-opus-5-5
|
This reply was posted by an AI agent (OpenHands) on behalf of @juanmichelini. Re: #pullrequestreview-5851595062 Pushing back on the pin bump here, with evidence. The TL;DR: bumping to 1.61.0 is not a pin bump — it drags in a fastmcp 3→4 / mcp 1→2 / httpx→httpx2 migration that breaks the MCP OAuth flow at runtime, so it belongs in its own PR. I verified the reviewer's other claims and they're correct, so I'm taking the alternative offered and dropping What I confirmed (reviewer is right about the gap)
Why I'm not bumping the pins in this PRSDK 1.61.0 requires 1. Runtime: MCP OAuth breaks ( In 1.61.0, Reproduced by two tests that pass on 1.60.1 and fail on 1.61.0:
2. Types: 13 new mypy errors in a file that's currently clean
3. The code itself documents that this needs a rewrite, not a pin bump
In mcp 2.x, What I'm doing here
Happy to revisit if I've missed a narrower path — but I don't see a way to take the SDK bump without the OAuth rewrite. |
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
The blocking finding from my last review is resolved. The PR body now says Refs #723 instead of Fixes #723, and GitHub shows no closing-issue references, so merging this PR will no longer close #723 while the feature does nothing at runtime.
Your reasons for keeping the SDK bump in its own PR hold up. openhands-sdk 1.61.0 requires fastmcp>=4.0.3,<5, but pyproject.toml pins fastmcp>=3.2,<4 and mcp==1.28.1. So moving to 1.61.0 means migrating MCP OAuth, not just changing a version number, and that work belongs in a separate PR.
The head commit is the same one I reviewed last time, and I found no new issues. The two focused test files still give 31 passed and 1 skipped on the pinned SDK. The skipped test is the scope check, which runs automatically once the SDK is bumped. All CI checks for this head pass.
✅ APPROVED
LLM profile: unknown · Model: openhands/claude-opus-5-5
|
Preview verification could not run. Details: https://github.com/OpenHands/saas-deploy/pull/2195#issuecomment-6799583595 This comment was posted by an AI agent (OpenHands) on behalf of the user. |
🔍 Preview Verification — NEEDS CLARIFICATIONTarget: saas-deploy PR #2302 App: https://pr-2302.staging.all-hands.dev Result: NEEDS CLARIFICATIONBaseline is green. The feature could not be observed: the conversation sandbox runs the chart-default agent-server 1.58.1, not the SDK#6762 build, so "Step 0 — SDK-live pre-check" fails and the remaining steps were not attempted. Baseline smoke
Feature test — personal vs organization secret scopeKey screenshotsWhat was tested
Skipped / manual review
EvidenceFull log: evidence/run-log.json Generated by an AI agent (OpenHands). |
🔍 Preview Verification — NEEDS CLARIFICATIONTarget: saas-deploy PR #2306 App: https://pr-2306.staging.all-hands.dev Result: NEEDS CLARIFICATIONBaseline is green. The feature was blocked at the PR's "Step 0 — SDK-live pre-check". The conversation sandbox runs agent-server 1.58.1, not ≥ 1.61.0, so Baseline smoke
Feature test — personal vs organization secret scopeKey screenshotsWhat was tested
Skipped / manual review
EvidenceFull log: evidence/run-log.json Generated by an AI agent (OpenHands). |
Matches the openhands-agent-server 1.62.0 pin in uv.lock (this branch's merged main). The live staging CR (openhands-agent-server in openhands-sandboxes) is applied from this file; run 5 of the verification was blocked because the live template still boots 1.58.1, which has no StaticSecret.scope support (software-agent-sdk#6276 first shipped it in 1.61.0).
hieptl
left a comment
There was a problem hiding this comment.
Hello Juan,
Thank you for putting this together. Telling the agent whose identity each secret carries is a really useful signal, and the wiring reads cleanly. I especially liked that SaasSecretsStore.load() also tags the _N-suffixed name on a collision, with a test for exactly that case, and the screenshots made the behaviour easy to follow.
I left a few inline comments, each labelled Blocking or Non-blocking. Please feel free to push back on any of them if I've missed context.
Non-blocking
One small point on the description: the "Notes" section still says the SDK pins stay at 1.60.1 and that the feature is inert until a later bump. Since the branch now carries 1.62.0, would it be worth updating that section so other reviewers aren't misled?
Thank you very much 🙏
Resolve the conflict in _get_provider_token_secrets by taking main's #1409 refactor (get_provider_token_secret_specs loop) and re-applying the personal scope tag to the static-token StaticSecret. The lookup path keeps its personal scope from _lookup_secret. Drop the #1291 mcp_config/org_mcp_servers/logger changes that came in via the earlier SDK-1.61 merge: main now ships 1.62.0 natively, so this PR no longer needs them and they belong in #1291's own review. Co-authored-by: openhands <openhands@all-hands.dev>
…SONAL api_secrets - secret_scope_fields now returns a SecretScopeFields TypedDict so mypy catches misspelled kwargs at the call site - New custom_secret_to_static helper shared by AuthUserContext.get_secrets and ResolverUserContext.get_secrets - api_secrets passed via conversation-start requests are tagged PERSONAL in both start paths (build_request and the MCP path) - Drop _SDK_HAS_SCOPE skipif guard (SDK 1.62.0 is on main) - Tests: assert scope == 'organization' on org-profile shared secrets, assert scope/description in resolver conversion test, tag test helper CustomSecrets as PERSONAL Co-authored-by: openhands <openhands@all-hands.dev>
hieptl
left a comment
There was a problem hiding this comment.
Hello Juan,
Thank you for the quick and thorough follow-up. I went back through the earlier comments against the new head, and they all look addressed. The personal tag now sits on the new get_provider_token_secret_specs() code, the #1291 changes are gone from the diff, and request secrets are tagged in both start paths. SecretScopeFields and custom_secret_to_static() read nicely, and the skipif guard is gone. The updated Notes section is much clearer too, and all the Python test shards pass in CI.
A few small things remain, with details inline:
- Blocking: the "Lint python" check fails on import order in six files.
- Non-blocking: some of the new scope assertions in the org-profile tests are duplicated.
- Non-blocking: a short test for the
personaltag on request secrets would round off that fix (I replied on the earlier thread).
Thank you very much 🙏
| StartConversationRequest, | ||
| TextContent, | ||
| ) | ||
| from openhands.sdk import Agent, AgentContext, Event |
There was a problem hiding this comment.
Hello Juan,
Blocking
The "Lint python" check is failing on this head. The pinned Ruff hook (v0.12.5) reports I001 import-order errors in six files: this one, integrations/resolver_context.py, openhands/app_server/integrations/provider.py, openhands/app_server/user/auth_user_context.py, tests/unit/integrations/test_resolver_context.py and tests/unit/test_auth_user_context.py. It looks like these were sorted with a different Ruff version or settings, which moved the openhands.sdk and openhands.agent_server imports into the third-party group. That is also why this file shows import moves unrelated to the feature.
Could we run pre-commit run ruff --all-files --config dev_config/python/.pre-commit-config.yaml? I tried the pinned Ruff locally: it fixes all 16 errors, and afterwards this file's diff against main contains only the new scope assertions.
Thank you very much 🙏
| # identity, not the launching member's. | ||
| assert secrets['SHARED_DATADOG_KEY'].scope == 'organization' | ||
| assert secrets['ORG_SONARQUBE_TOKEN'].scope == 'organization' | ||
| # Org-shared secrets must be advertised as the organization's |
There was a problem hiding this comment.
Hello Juan,
Non-blocking
Thank you for adding these. It looks like the block was pasted twice: lines 3590–3593 repeat at 3594–3597, and the ORG_SONARQUBE_TOKEN assertion at 3606 repeats at 3607. Could we keep one copy of each?
Thank you very much 🙏
Co-authored-by: openhands <openhands@all-hands.dev>
Local UI verification — scope featureVerified end-to-end on a local enterprise stack built from this PR's HEAD ( 1. Secrets settings — grouped by scopeThe Settings → Secrets page now renders two sections: a personal Secrets table and an Organization secrets table ("Shared secrets are visible to all members of your organization but can only be edited by admins and owners"). 2. Add-secret dialog — scope selectorThe "Add a new secret" dialog exposes the Share with organization toggle, which sets 3. Agent selects the org credential from contextConversation: "For the internal triage audit, add the needs-triage label to the open bugs in the team's Linear — post as the team bot so the audit trail shows the shared service account, not me." The agent chose
(Both keys are dummy values, so the Linear API returns 401 — expected. The test signal is which credential the agent chose, not whether the call succeeded.) Tested on a local Docker stack ( This comment was created by an AI agent (OpenHands) on behalf of @juanmichelini. |
|
🚀 Released in 1.95.0. |












HUMAN:
Tested manually by juan the human see screenshots below.
Second half of OpenHands/software-agent-sdk#6276
AGENT:
Why
Agents receive every secret as an opaque env var and cannot tell whose identity
is behind each one. When both a user's personal credential and an org-wide
service-account credential exist for the same service, the agent may act with the
shared identity (attributing actions to the bot, with different permissions)
without knowing it. OpenHands/software-agent-sdk#5672 (merged) adds optional
scope/scope_descriptionfields toSecretSourceand groups secrets aspersonal vs organization in the system prompt. This PR is the
enterprise-side wiring that sets those scopes correctly.
The runtime behavior is inert until
openhands-sdkis bumped to 1.61.0 (which addsscope/scope_descriptiontoSecretSource); that bump is tracked separately because it pulls in a fastmcp 4 / mcp 2 migration. Refs #723 — will close the issue from the SDK-bump follow-up once the feature is live.Summary
CustomSecretScope(personal/organization) inintegrations.providersoCustomSecretcarries a runtime scope (re-exportedfrom
secrets_models), plus scope-description constants and asecret_scope_fields()helper.SaasSecretsStore.load()tags org-shared secretsORGANIZATION(including the_N-suffixed name produced on a personal/shared name collision); personalsecrets keep the default
PERSONALscope.auth_user_context.get_secrets()andresolver_context.get_secrets()propagate the scope into the SDK
StaticSecrets (and the resolver path nowalso forwards the secret description, which was previously dropped).
tokens, named OAuth secrets, git credential-helper & Azure DevOps tokens, and
JIRA_DC_TOKEN. Org-profile shared secrets are marked organization.OPENHANDS_API_KEYstays personal via the default.Issue Number
#723
How to Test
End-to-end validation (done locally): installing the SDK from the merge commit
of #5672 and re-running the suite makes the scope-guarded test execute and pass,
and
SecretRegistry.get_secret_infos()then emits the groupedscope/scope_descriptionthe prompt uses, e.g.:Preview Verification
Pins this preview needs
1. Sandbox runtime (agent-server) — satisfied by staging chart 0.105.0
The feature needs the conversation sandbox to run an agent-server ≥ 1.61.0
(
scope/scope_descriptiononSecretSource, first released in SDK 1.61.0via software-agent-sdk#6276). Staging (including the shared runtime-api that
serves feature-preview sandboxes) now runs the openhands chart 0.105.0
(saas-deploy#2275, merged), whose default runtime image is
ghcr.io/openhands/agent-server:1.62.0-python— published on ghcr. Thepreview's app (SDK 1.62.0 on this branch) derives the same
1.62.0-pythonspec, so app and sandbox match exactly and no per-preview runtime pin is
needed. Note: a per-PR head-sha runtime pin would not work anyway — the app
auto-corrects a custom tag on the default repository back to its bundled SDK
version (
AGENT_SERVER_IMAGE_TAG does not match the installed openhands-sdk).2. App-server (this PR's own image) — requirement satisfied on this branch
The app server constructs the
StaticSecrets with its installed SDK; olderpins (< 1.61.0) dropped the
scopekwargs at construction (pydanticextra=ignore), so they never reached the sandbox. This branch now merges mainand carries
openhands-sdk==1.62.0/openhands-agent-server==1.62.0(pyproject + uv.lock), so the enterprise-server image built from this PR's head
sends
scope/scope_descriptionnatively. (A same-repo PR can never be asibling pin — the enterprise image is always built from this PR's own head,
which is why the bump had to land on the branch itself.)
3. Org-admin credential (for the org-shared secret step)
MANAGE_ORG_SECRETSis held only by the orgadmin/ownerroles, and theprovisioned instance-admin is
role=memberin the target org. Previous runscorrectly declined to modify the seeded org. Please provision an org-admin (or
org-owner) credential for the target org via the provisioning/invitation flow
for this run, or state that the org-shared half must stay skipped.
Step 0 — SDK-live pre-check (after the pins land)
StaticSecretschema listsscopeandscope_description.<CUSTOM_SECRETS>block shows### personal/### organizationheadings, not a flat list.image still runs SDK 1.60.1 (pin 2 missing); report that and stop.
Step 1 — Set up the secrets via the UI
Neutral names, so the agent must infer from the scope description, not the name.
As the org-admin identity (org-shared →
scope=organization):POST /api/organizations/{org_id}/secrets.LINEAR_API_KEY_2=lin_bot_fake_value, descriptionLinear API key.As the regular user (personal →
scope=personal):PUT /api/settings/secrets.LINEAR_API_KEY_1=lin_personal_fake_value, descriptionLinear API key.The regular user's resolved set is then:
LINEAR_API_KEY_1— personal (wins the bare name on collision)LINEAR_API_KEY_2— organization (suffixed because of the collision)Identical descriptions; the scope group + scope description is the only
distinguishing signal. That is the point.
Step 2 — Run two conversations from the regular user
Separate conversations; the agent is not told which token to use.
Q1 — personal task (expect
$LINEAR_API_KEY_1, the personal token, first):Q2 — org task (expect
$LINEAR_API_KEY_2, the organization token, first):Step 3 — What to capture
<CUSTOM_SECRETS>block from Step 0 with### personal/### organizationheadings and bothLINEAR_API_KEYentries (personal bare, org suffixed
_2).$LINEAR_API_KEY_1. A 401/"bad credentials" after is expected (fake token);we verify selection, not API success.
$LINEAR_API_KEY_2.Pass / fail
$LINEAR_API_KEY_1AND Q2's first commanduses
$LINEAR_API_KEY_2— decided from the scope grouping alone.which to use.
missing (runtime agent-server < 1.61.0, or app-server image without the SDK
1.61.0 bump) and stop.
screenshots
taks requires org, and it uses LINEAR_API_KEY_2 that is org

taks requires personal, and it uses LINEAR_API_KEY_1 that is personal

ui showing secrets

Type
Notes
openhands-sdk/openhands-agent-serverare pinned to1.62.0(main has carried the bump since feat(app-server): enable ACP effort on SDK 1.62.0 #1270, and this branch mergesmain), so
scope/scope_descriptionare live on both the app-server andthe sandbox runtime — the feature is active as merged, no follow-up bump
needed. Because the pin is ≥ 1.61.0, the former
skipifSDK guard intests/unit/test_auth_user_context.pyhas been removed; the scope assertionnow fails loudly if the SDK ever drops the fields.
dropped by merging latest
main(the diff now only covers secret scopes);request-provided
api_secretsare taggedpersonalin both start paths;secret_scope_fields()returns aSecretScopeFieldsTypedDictso mypychecks the spread against
StaticSecret/LookupSecret; a sharedcustom_secret_to_static()helper is used by bothAuthUserContext.get_secrets()andResolverUserContext.get_secrets();org-profile tests assert
scope == 'organization'; the resolver conversiontest asserts description and scope.
Enterprise server image for this PR: