fix: preserve remote OpenCode auth providers (#3382) (#3421)

This commit is contained in:
Carlos Florêncio
2026-09-05 20:32:25 +00:00
committed by GitHub
parent 73a399472d
commit 782c8a4006
19 changed files with 890 additions and 26 deletions
@@ -0,0 +1,77 @@
---
created: 2026-09-05
status: done
requirements:
- REQ-EXECUTORS-SSH-EXECUTOR-001
system_design:
- ../../specs/executors/system-design/ssh-executor.md
legacy_specs: []
---
# Implementation Plan: Preserve OpenCode SSH Credentials
## Overview
The fix adds an agent-owned policy for credential-file conflicts. OpenCode uses that policy to merge provider maps before a remote write.
One vertical work order changes the descriptor, transfer layer, transports, tests, and public executor reference. This order keeps one regression boundary.
## Scope
### In scope
- Preserve OpenCode providers that exist only in the target `auth.json`.
- Copy source-only providers and replace same-provider target entries with source entries.
- Leave an unreadable or malformed existing target unchanged.
- Keep the existing replace policy for other credential files.
- Document the SSH credential-copy behavior.
### Out of scope
- A user-selectable conflict policy.
- Timestamped credential backups.
- A remote lock for concurrent OpenCode writes.
- Changes to environment-based credential methods.
## Technical approach
Add an internal existing-file policy to `agents.RemoteAuthMethod`. Copy the policy into `remoteauth.Method` without adding a frontend contract.
Set the JSON-object merge policy only on the OpenCode file method. Keep replacement as the zero-value policy.
Add a narrow target-read interface beside `FileUploader`. Implement it for the persistent Sprites and SSH transports.
Isolated local and Kubernetes targets validate and write the source object. They do not require a target read.
Update `UploadCredentialFiles` to read and merge only when the selected method declares the merge policy. Return an error before each write when the merge input is invalid.
Use deterministic JSON encoding and private file mode for merged output. Keep existing write behavior for a missing target and for all replacement methods.
Update the SSH executor reference in `docs/public/executors.md`. State the OpenCode merge and malformed-file behavior.
## Tests
- `AC-EXECUTORS-SSH-EXECUTOR-001.11`: Add transfer tests for target-only, source-only, and same-provider entries.
- `AC-EXECUTORS-SSH-EXECUTOR-001.11`: Add an SSH integration test with an existing remote OpenCode provider map.
- `AC-EXECUTORS-SSH-EXECUTOR-001.12`: Add transfer and SSH tests that preserve malformed target bytes.
- Add a transfer test that keeps an isolated OpenCode credential copy working.
- Add catalog tests that make sure only OpenCode declares the merge policy.
- Keep a replacement test for an opaque credential file.
## Work orders
- [x] [Task 01: Merge OpenCode credential provider maps](task-01-merge-opencode-credential-providers.md)
## Verification results
- Focused Go tests: 19 passed in three packages.
- Specification linter: passed.
- Public documentation tests: 61 passed.
- Published documentation validator: 45 pages passed.
- Git diff check: passed.
## Risks
- A source-wins collision replaces the remote login for the same provider.
- A read-merge-write sequence does not protect against an agent write at the same time.
- Transport-specific missing-file errors must map to one shared absent-target result.
@@ -0,0 +1,109 @@
---
id: "01-merge-opencode-credential-providers"
title: "Merge OpenCode credential provider maps"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-EXECUTORS-SSH-EXECUTOR-001
acceptance_criteria:
- AC-EXECUTORS-SSH-EXECUTOR-001.11
- AC-EXECUTORS-SSH-EXECUTOR-001.12
system_design:
- ../../specs/executors/system-design/ssh-executor.md
---
# Task 01: Merge OpenCode Credential Provider Maps
## Summary
Add an agent-owned merge policy to the remote credential pipeline. Use it to preserve existing OpenCode provider logins on remote executors.
## In scope
- Add the internal credential-file conflict policy to agent and catalog models.
- Declare the JSON-object merge policy for OpenCode.
- Add target reads to persistent credential file transports.
- Keep isolated credential targets on the validated write path.
- Merge provider maps in the shared credential uploader.
- Preserve an existing target when a read or parse fails.
- Add focused unit and SSH integration tests.
- Update the public SSH executor reference.
## Out of scope
- A settings control for conflict behavior.
- Credential backups.
- Provider-specific deep merges below the top-level provider key.
- Remote file locking.
## Acceptance
- A copy preserves target-only providers and adds source-only providers.
- A source provider replaces a target provider with the same key.
- An unreadable or malformed existing target remains byte-for-byte unchanged.
- An unreadable source file reports a credential-copy error and does not write a target.
- A malformed source file reports a credential-copy error and does not write a target.
## Verification
```bash
cd apps/backend && go test ./internal/agent/agents ./internal/agent/remoteauth ./internal/agent/runtime/lifecycle -run 'Test(OpenCodeACPRemoteAuth|BuildCatalog|UploadCredentialFiles|SeedAgentSessionDir_OpenCode|SSHExecutorUploadCredentials|SSHFileUploader)' -count=1
python3 scripts/lint-spec-files.py --all
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
git diff --check
```
## Files likely touched
- `apps/backend/internal/agent/agents/agent.go`
- `apps/backend/internal/agent/agents/opencode_acp.go`
- `apps/backend/internal/agent/agents/opencode_acp_test.go`
- `apps/backend/internal/agent/remoteauth/catalog.go`
- `apps/backend/internal/agent/remoteauth/catalog_test.go`
- `apps/backend/internal/agent/runtime/lifecycle/credential_uploader.go`
- `apps/backend/internal/agent/runtime/lifecycle/credential_uploader_test.go`
- `apps/backend/internal/agent/runtime/lifecycle/agent_session_seeder.go`
- `apps/backend/internal/agent/runtime/lifecycle/executor_sprites.go`
- `apps/backend/internal/agent/runtime/lifecycle/executor_ssh_credentials.go`
- `apps/backend/internal/agent/runtime/lifecycle/executor_ssh_credentials_remote_test.go`
- `docs/public/executors.md`
## Dependencies
None.
## Risks
- Each transport reports a missing file differently. The shared reader contract must normalize this condition.
- The source-wins collision rule can replace one existing provider login by design.
## Parallelism
`sequential`
## Inputs
- `REQ-EXECUTORS-SSH-EXECUTOR-001`
- `docs/specs/executors/system-design/ssh-executor.md`
- `docs/decisions/2026-09-05-agent-owned-credential-file-conflicts.md`
- GitHub issue `kdlbs/kandev#3382`
- Existing `FileUploader` and passthrough JSON merge patterns.
## Results
Implemented the agent-owned JSON-object conflict policy for OpenCode credentials. SSH and Sprites read persistent targets before the merge.
Isolated targets validate and write the source object. Malformed inputs leave an existing target unchanged, and unreadable or malformed sources report a credential-copy error before any write.
Public docs updated: `docs/public/executors.md` (reference).
Verification results:
- Focused Go tests: 19 passed in three packages.
- Specification linter: passed.
- Public documentation tests: 61 passed.
- Published documentation validator: 45 pages passed.
- Git diff check: passed.