Skip to content

docs: define AI provider migration language#25411

Open
ibetitsmike wants to merge 6 commits into
mainfrom
mike/ai-providers/docs-decisions
Open

docs: define AI provider migration language#25411
ibetitsmike wants to merge 6 commits into
mainfrom
mike/ai-providers/docs-decisions

Conversation

@ibetitsmike
Copy link
Copy Markdown
Collaborator

Mux prepared this PR on behalf of Mike.

Stack Context

This stack migrates Agents chat provider configuration from legacy chat provider tables to the unified AI provider tables used by the AI provider administration surface.

What?

Defines the migration language and records the core source-of-truth decisions for AI providers, provider-scoped keys, user BYOK keys, and Agents as the consuming feature area.

Why?

The later schema, API, runtime, frontend, and cleanup PRs are easier to review with the terminology and trade-offs captured first.

@github-actions
Copy link
Copy Markdown

Docs preview

📖 View docs preview for docs/adr/0001-ai-providers-for-agents.md

@ibetitsmike
Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

Copy link
Copy Markdown

@coder-agents-review coder-agents-review Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Flagged ambiguities section at the end of CONTEXT.md is genuine work: naming three specific terms that could cause confusion and resolving each. The audit decision for user keys is consistent with existing code.

5 P2, 5 P3, 1 P4, 2 Nit.

The central issue is that several definitions contradict committed artifacts in the same repository. The AI Bridge relationship claim contradicts the ai_providers table comment (7 of 10 reviewers flagged this independently). "Provider Kind" uses a term and example values that don't match the target schema. BYOK is described as deployment-wide while the code implements per-provider control. "Central API key" and "provider type" are told to be avoided while being the active terms in code, database, and shipped documentation.

As Zoro put it: "A terminology document that names a concept differently from every layer of the codebase that implements it will force every reader to maintain a mental translation table."

For a document whose purpose is to be the source of truth for downstream migration PRs, these contradictions are likely to produce the exact confusion the document aims to prevent.

🤖 This review was automatically generated with Coder Agents.

Comment thread CONTEXT.md Outdated
Comment thread CONTEXT.md Outdated
Comment thread CONTEXT.md Outdated
Comment thread CONTEXT.md
Comment thread CONTEXT.md
Comment thread CONTEXT.md
Comment thread docs/adr/0001-ai-providers-for-agents.md Outdated
Comment thread CONTEXT.md Outdated
Comment thread docs/adr/0001-ai-providers-for-agents.md Outdated
Comment thread docs/adr/0001-ai-providers-for-agents.md Outdated
@ibetitsmike
Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

Copy link
Copy Markdown

@coder-agents-review coder-agents-review Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The R1 commit addressed 4 of 15 findings: DEREM-3 (AI Bridge contradiction reframed), DEREM-4 (Provider Kind renamed to Provider Type), DEREM-6 (BYOK now acknowledges both levels), DEREM-7 (Central API key migration path noted).

11 findings remain silent with no author response or code changes. Further review is blocked until these are addressed, acknowledged, or contested.

Silent P2:

  • DEREM-5: Provider Type examples still list bedrock and openai-compat, which do not exist in the ai_provider_type enum. The rename from "Kind" to "Type" targeted DEREM-4 but did not fix the invalid enum values.

Silent P3:

  • DEREM-1: CONTEXT.md still unreferenced by any file.
  • DEREM-2: ADR still not in docs/manifest.json; docs/adr/ has no index.
  • DEREM-8: ADR still packs 5+ decisions into two paragraphs.
  • DEREM-9: Example dialogue still uses present tense for a future capability (model configs referencing by ID).
  • DEREM-10: Agents definition still mentions chatd then says to avoid it.
  • DEREM-11: User AI Provider Key still has no target table in schema.
  • DEREM-12: ADR still names only one of five legacy tables.

Silent P4/Nit:

  • DEREM-13: "model config" still used but undefined.
  • DEREM-14: ADR audit decision still justified by precedent only.
  • DEREM-15: ADR tense still mixes present and future.

The ADR file was not modified at all in the R1 commit. If these findings are intentionally out of scope, a brief response on the threads would unblock the next review round.

🤖 This review was automatically generated with Coder Agents.

@ibetitsmike
Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

Copy link
Copy Markdown

@coder-agents-review coder-agents-review Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

14 of 15 findings now addressed across two commits. The R2 commit tackled the remaining 10 open findings from R1: CONTEXT.md is now linked from AGENTS.md (DEREM-1), docs/adr/ has a README (DEREM-2), the ADR is restructured with Status/Context/Decision/Consequences (DEREM-8), temporal framing uses future tense (DEREM-9, DEREM-15), the Agents definition no longer leaks chatd (DEREM-10), User AI Provider Key is marked target-state (DEREM-11), legacy scope is explicit (DEREM-12), Model Config is defined (DEREM-13), and the audit decision has threat-model reasoning (DEREM-14).

1 finding remains silent:

  • DEREM-5 (P2): Provider Type examples still list bedrock and openai-compat, which do not exist in the ai_provider_type enum (only openai and anthropic). This line was not touched in either commit and has no author response. A brief acknowledgment or fix would unblock the panel review.

🤖 This review was automatically generated with Coder Agents.

@ibetitsmike
Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

1 similar comment
@ibetitsmike
Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

Copy link
Copy Markdown

@coder-agents-review coder-agents-review Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All 15 R1 findings resolved. The document is substantially improved: schema references verified, temporal framing consistent, ADR structured, discoverability addressed.

1 P2, 2 Nit new this round.

The DEREM-6 fix (BYOK granularity) introduced a new factual claim about chatd behavior that three reviewers independently disproved: chatd has zero references to the deployment BYOK setting. As Pariston noted: "The deployment AllowBYOK is a global gate at the AI Bridge middleware, and the per-provider key policy columns are independent controls on chat_providers that chatd reads directly." The same unverified-claim pattern that caused several R1 findings.

🤖 This review was automatically generated with Coder Agents.

Comment thread CONTEXT.md Outdated
Comment thread docs/adr/0001-ai-providers-for-agents.md Outdated
Comment thread CONTEXT.md
Copy link
Copy Markdown

@coder-agents-review coder-agents-review Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new commits since R4 (head unchanged at 32f176a). All 3 open findings remain silent.

  • DEREM-17 (P2): BYOK definition claims chatd maps the deployment BYOK setting into per-provider capability. Chatd has zero references to AllowBYOK. A fix or acknowledgment is needed.
  • DEREM-18 (Nit): ADR says events "will remain unaudited" then calls them "audit records."
  • DEREM-19 (Nit): "SDK" should read "generated database types" since AIProviderType is not in codersdk.

Further review is blocked until the author responds or pushes fixes.

🤖 This review was automatically generated with Coder Agents.

@ibetitsmike
Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@ibetitsmike
Copy link
Copy Markdown
Collaborator Author

Mux working on behalf of Mike.

Responses to the remaining docs review findings:

  • DEREM-17: fixed in 80702c7b2e. The glossary no longer describes BYOK as a per-provider runtime capability and now frames it against the legacy per-provider key policy.
  • DEREM-18: fixed in 80702c7b2e. The ADR now says we intentionally do not create audit records for user-owned secret changes.
  • DEREM-19: fixed in 80702c7b2e. The glossary now says the database schema uses ai_provider_type and the generated database model defines database.AIProviderType.

@ibetitsmike
Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

Copy link
Copy Markdown

@coder-agents-review coder-agents-review Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All 18 findings resolved across 6 rounds. No new findings from the R6 panel (10 reviewers, 0 findings). Multiple reviewers independently verified every schema reference, temporal framing marker, and code claim against the codebase.

As Mafu-san observed: "Three iterations on the BYOK definition, each more precise, each grounded in what the code actually shows. That is genuine convergence, not mechanical compliance."

The document lands in a solid state: terminology anchored to real schema objects, target-state language clearly distinguished from current behavior, ADR structured with context and consequences, and discoverability addressed via AGENTS.md.

🤖 This review was automatically generated with Coder Agents.

Copy link
Copy Markdown

@coder-agents-review coder-agents-review Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Head unchanged from R6 (80702c7). The R6 panel (10 reviewers, 0 findings) already approved this exact code. All 18 findings resolved. The R6 APPROVE still stands.

🤖 This review was automatically generated with Coder Agents.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant