chore: warn when coder_agent dir breaks Desktop file sync

[zenithwolf1000]

Adds a warning to the dir attribute on the coder_agent resource for Coder Desktop file sync compatibility.

Two mechanisms:

1. Doc callout: A ~> Warning block in the dir schema description, rendered on the Terraform Registry.
2. Runtime diagnostic: A diag.Warn in CreateContext and ReadWithoutTimeout that fires during terraform plan/apply when dir is set to a non-$HOME value. This warning flows through Terraform output into Coder build logs.

Refs DEVEX-227

Generated by Coder Agents

[johnstcn]

Suggestion: you could also add a diag.Warn in agentResource() so that this will show up in the Terraform log output. May be too noisy though.

[code-asher]

so that this will show up in the Terraform log output. May be too noisy though.

Ooo that sounds good, and I think that would obviate the need for coder/coder#24951? Feels to me like having the warning in the provider makes more sense.

[matifali]

Should we also mark this as a deprecated attribute?

[zenithwolf1000]

I wasn't sure if we wanna fully deprecate the attribute as part of this ticket, was expecting we would have a separate push to properly deprecate and clean up which will take a couple of releases. @matifali I can adjust the warning to say it's deprecated as well if you want

[matifali]

Deprecate means we start emitting a warning in terraform build logs, but it will keep working until next major release when we remove it.
I think there is a field you can set and it should take care of that.

[zenithwolf1000]

Okay, will update to add a deprecation warning too

[zenithwolf1000]

/coder-agents-review

[mafredri]

I'm happy about the deprecation of this attribute, but it's potentially a pretty big breaking change for DX. Currently we use dir in our dogfood template and I've had to change my mental model for ssh, scp and rsync when working in coder. While this fact alone makes it clear that the behavior of dir is actively harmful and non-unixy, deprecating it somewhat silently seems like the wrong approach. We should convey to customers how they can migrate and also think about what else may break.

Re: breakage, for instance in Coder Agents dir is currently load-bearing for chats being able to automatically include project-level AGENTS.md, .mcp.json, and skills.

//cc @matifali @johnstcn

[matifali]

This is the first phase where we started emitting warnings to discourage it's use. It should still work the same as before. It's a good chance to talk about possible alternatives here.

dir was overloaded which we are here trying to solve. I didn't consider that agents also use it.

[matifali]

Also this repo need more verbose agent instructions to check any use of attributes in the coder/coder repo too so LLMs can have more context to suggest better completions.

[mafredri]

@matifali I think it isn't a great user/customer experience for us to deprecate it without making it clear what our future plans are. Will we support the use-case(s) through some other name? Will we support part of the use-cases, or none at all? Will we split it out into multiple parameters? Customers updating the provider will wonder what they should do now that it's deprecated, and they can't find any answers. To make matters worse the reasoning can't even be discovered in the changelog as this is riding behind the "desktop file sync warning".

[matifali]

These are all great points.
The two use cases we had in mind when this was being done was

1. Used in Coder Desktop for Filesync. (Which was broken adn we are trying to avoid that)
2. Set folder for the builtinvscode display_apps of coder_agent.

The recommendation for 2, is to use our modules from registry.coder.com which allows explicitly setting folder
For 1. It is to just not set dirat all or set it to $HOME.

I wasn;t aware of any other use cases of this thats whay I said above that this semmes overlaoded attribute.

@zenithwolf1000 suggsted above to add a follow up instrcutions and deprecation of case 2 here.