@@ -0,0 +1,53 @@
|
||||
# ADR-2026-09-05-agent-owned-credential-file-conflicts: Agent-owned credential file conflicts
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-09-05
|
||||
**Area:** backend
|
||||
|
||||
## Context
|
||||
|
||||
Remote credential methods identify source files and target directories. The shared transfer layer treats each file as an opaque value and replaces its target.
|
||||
|
||||
This behavior is correct for single-session token files. It is destructive for OpenCode `auth.json`, which is a provider map.
|
||||
|
||||
An SSH target can contain provider logins that do not exist on the Kandev host. A task launch currently removes those target-only entries.
|
||||
|
||||
The transfer layer cannot safely infer a file format from its path. Different agents can also change their credential formats independently.
|
||||
|
||||
## Decision
|
||||
|
||||
The agent remote-auth descriptor owns the existing-file policy. The default policy replaces the target to keep current behavior for opaque credential files.
|
||||
|
||||
OpenCode declares a top-level JSON-object merge for `auth.json`. The shared transfer layer applies this policy before it writes the target.
|
||||
|
||||
The merge preserves target-only providers and adds source-only providers. A source entry replaces the target entry for the same provider.
|
||||
|
||||
The transfer fails closed when an existing target is unreadable or is not a valid JSON object. The transfer does not replace that target.
|
||||
|
||||
## Consequences
|
||||
|
||||
- SSH task launches preserve OpenCode logins that exist only on the target.
|
||||
- A selected host login remains authoritative when both hosts contain the same provider.
|
||||
- Other agents keep their current replacement behavior.
|
||||
- Persistent file transports need a target-read capability for merge policies.
|
||||
- Isolated transports validate and write the source because no user target exists.
|
||||
- New structured credential files can declare a policy without path checks in executor code.
|
||||
- A concurrent agent write can still race with a read-merge-write transfer. This change does not add a remote file-lock protocol.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Refuse every existing credential file
|
||||
|
||||
This policy prevents rotation and makes the selected copy method ineffective on persistent executors.
|
||||
|
||||
### Back up every replaced file
|
||||
|
||||
This policy retains old secrets and creates an unbounded set of credential copies on the remote host.
|
||||
|
||||
### Merge every JSON credential file
|
||||
|
||||
JSON structure does not imply merge semantics. A generic merge can create an invalid credential document for another agent.
|
||||
|
||||
### Add OpenCode path logic to the SSH uploader
|
||||
|
||||
This policy couples the transport to one agent and leaves the same transfer rule inconsistent on other executors.
|
||||
@@ -242,3 +242,4 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
|
||||
| 2026-09-03-separate-system-data-storage-pages | [Separate System Data and Storage Pages](2026-09-03-separate-system-data-storage-pages.md) | accepted | frontend | 2026-09-03 |
|
||||
| 2026-09-04-generation-fenced-task-environment-ownership | [Fence Task Environment Ownership by Generation](2026-09-04-generation-fenced-task-environment-ownership.md) | accepted | backend | 2026-09-04 |
|
||||
| 2026-09-04-use-repository-token-for-runtime-pin-prs | [Use the built-in Actions token for runtime pin PRs](2026-09-04-use-repository-token-for-runtime-pin-prs.md) | accepted | workflow, security | 2026-09-04 |
|
||||
| 2026-09-05-agent-owned-credential-file-conflicts | [Agent-owned credential file conflicts](2026-09-05-agent-owned-credential-file-conflicts.md) | accepted | backend | 2026-09-05 |
|
||||
|
||||
@@ -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.
|
||||
@@ -382,7 +382,11 @@ Run **Test Connection**, independently verify the observed SHA256 host fingerpri
|
||||
|
||||
The profile editor exposes remote shell and agent-readiness checks. Backend/API configuration also recognizes `ssh_workdir_root` (default `~/.kandev`) and `ssh_shell`; the current profile UI exposes `ssh_shell` but not a workdir-root field.
|
||||
|
||||
The remote-auth card is built from the currently enabled agents. Depending on an agent's declared methods, it can copy selected local credential files, resolve a stored secret into that agent's authentication environment variable, or run an agent-specific setup script on the remote host. GitHub can use an explicitly selected `GITHUB_TOKEN` secret as an unmanaged profile override; Kandev does not copy the host-active `gh` token. These transfers write sensitive material under the remote user's home and are best-effort, verify authentication on the remote after saving. Although the profile editor also stores Git name/email controls for SSH, the current SSH runtime does not apply them; configure Git identity on the remote host yourself.
|
||||
The remote-auth card is built from the currently enabled agents. Depending on an agent's declared methods, it can copy selected local credential files, resolve a stored secret into that agent's authentication environment variable, or run an agent-specific setup script on the remote host. GitHub can use an explicitly selected `GITHUB_TOKEN` secret as an unmanaged profile override; Kandev does not copy the host-active `gh` token.
|
||||
|
||||
OpenCode credential copies merge top-level provider entries with the existing remote `auth.json`. Remote-only providers remain, and the selected host entry replaces the same provider on the remote. If either file is unreadable or is not a JSON object, Kandev leaves the remote file unchanged and reports the credential-copy error.
|
||||
|
||||
These transfers write sensitive material under the remote user's home and are best-effort. Verify authentication on the remote after saving. Although the profile editor also stores Git name/email controls for SSH, the current SSH runtime does not apply them; configure Git identity on the remote host yourself.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
@@ -29,6 +29,8 @@ Today the only ways to run an agent are: (1) locally on the user's own machine (
|
||||
- **AC-EXECUTORS-SSH-EXECUTOR-001.8:** One SSH connection per `(host, user, identity-source)`, opened lazily and reused across all the executor's sessions on that host. Each session adds:
|
||||
- **AC-EXECUTORS-SSH-EXECUTOR-001.9:** When a resumable SSH session's prior remote controller is confirmed absent, the system shall start a fresh controller in the preserved task workspace and load the preserved provider conversation.
|
||||
- **AC-EXECUTORS-SSH-EXECUTOR-001.10:** When the system cannot determine whether a prior remote controller is alive because the SSH probe fails, resume shall fail without starting a replacement controller.
|
||||
- **AC-EXECUTORS-SSH-EXECUTOR-001.11:** When Kandev copies OpenCode `auth.json` to an SSH host, it shall preserve target-only providers and copy source providers. The source entry shall replace the target entry when both files contain the same provider.
|
||||
- **AC-EXECUTORS-SSH-EXECUTOR-001.12:** When the source or existing target is unreadable or is not a JSON object, Kandev shall leave the target unchanged. Kandev shall report the credential-copy error.
|
||||
|
||||
## System design
|
||||
|
||||
|
||||
@@ -18,6 +18,7 @@ This design preserves the technical source detail for `REQ-EXECUTORS-SSH-EXECUTO
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-EXECUTORS-SSH-EXECUTOR-001` | [Migrated source detail](#migrated-source-detail) |
|
||||
| `AC-EXECUTORS-SSH-EXECUTOR-001.11` and `AC-EXECUTORS-SSH-EXECUTOR-001.12` | [Credential-file conflict policy](#credential-file-conflict-policy) |
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
@@ -135,6 +136,26 @@ Multiple sessions in the *same* task share the same worktree on disk (same files
|
||||
- The existing `executor_sprites_credentials.go` selection + upload logic for `remote_credentials` / `remote_auth_secrets` is the reference; SSH v1 wires the uploader and writes credentials to the SSH user's home dir.
|
||||
- GitHub CLI token: same special case as Sprites (run `gh auth token` locally, inject as env var).
|
||||
|
||||
### Credential-file conflict policy
|
||||
|
||||
The agent descriptor owns the policy for an existing credential file. The transfer layer must not infer file semantics from a path or an executor type.
|
||||
|
||||
OpenCode declares a top-level JSON-object merge for `auth.json`. The transfer layer reads the target before it writes the source file.
|
||||
|
||||
The transfer layer preserves providers that exist only in the target. It adds providers that exist only in the source.
|
||||
|
||||
When both files contain a provider, the source entry replaces the target entry. This rule preserves the selected host credential as the copy source.
|
||||
|
||||
When the target does not exist, the transfer layer writes the source object. Other agent credential files keep the existing replace policy.
|
||||
|
||||
The merge requires two valid JSON objects. An unreadable or malformed target causes a copy error and remains unchanged.
|
||||
|
||||
The merge runs in the shared credential-upload path. Persistent transports expose target reads only for this policy and keep ordinary writes unchanged.
|
||||
|
||||
An isolated transport has no pre-existing user file. It validates the source object and writes it without a target read.
|
||||
|
||||
This design follows [ADR-2026-09-05-agent-owned-credential-file-conflicts](../../../decisions/2026-09-05-agent-owned-credential-file-conflicts.md).
|
||||
|
||||
### Recovery after backend restart
|
||||
|
||||
- Persist in `ExecutorRunning.Metadata` (allow-listed in `persistentMetadataKeys`): `ssh_host`, `ssh_port`, `ssh_user`, `ssh_host_fingerprint`, `ssh_remote_task_dir`, `ssh_remote_session_dir`, `ssh_remote_agentctl_port`, `ssh_remote_agentctl_pid`, `ssh_local_forward_port`, `ssh_workdir_root`, `ssh_proxy_jump`, `ssh_identity_source`, `ssh_identity_file`.
|
||||
|
||||
Reference in New Issue
Block a user