docs: ADR-0007 - Adopt Cloudflare-native infrastructure for internal AI coding agent#350
Open
zacjones93 wants to merge 6 commits intomainfrom
Open
docs: ADR-0007 - Adopt Cloudflare-native infrastructure for internal AI coding agent#350zacjones93 wants to merge 6 commits intomainfrom
zacjones93 wants to merge 6 commits intomainfrom
Conversation
Contributor
WalkthroughProposes ADR-0007: a Cloudflare-native internal AI coding agent architecture using Workers for webhooks, Queues for tasks, per-thread Durable Objects for session/state and container coordination, per-thread Containers running a Python LangGraph agent, and integrations with GitHub, Linear, Slack, and Anthropic. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Webhook as Webhook Source (GitHub/Slack/Linear)
participant Worker as Cloudflare Worker (webhook)
participant Queue as Cloudflare Queue
participant Consumer as Queue Consumer
participant DO as Durable Object (AgentSession)
participant Container as Cloudflare Container (Python Agent)
participant Ext as External APIs (GitHub/Linear/Slack/Anthropic)
rect rgba(200,230,255,0.5)
Webhook->>Worker: POST webhook (signed)
Worker->>Worker: verify signature\nrespond 200
Worker->>Queue: enqueue agent task
end
rect rgba(220,255,200,0.5)
Queue->>Consumer: deliver task
Consumer->>DO: dispatch task to AgentSession
DO->>DO: persist session state\nbuffer follow-ups
DO->>Container: start/attach container\nprovide repo + context
Container->>Container: run LangGraph agent loop\nexecute actions
Container->>Ext: call external APIs (GitHub/Slack/Anthropic)
Ext-->>Container: API responses
Container-->>DO: stream updates / results
DO-->>Consumer: ack / final status
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 issue found across 1 file
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/adr/0007-cloudflare-native-ai-coding-agent.md">
<violation number="1" location="docs/adr/0007-cloudflare-native-ai-coding-agent.md:170">
P2: This ADR standardizes Durable Object SQLite storage for agent state, which conflicts with the repo's PlanetScale-only persistence convention and introduces a second datastore for durable records.
(Based on your team's feedback about keeping database persistence on PlanetScale instead of Cloudflare-local SQLite/D1.) [FEEDBACK_USED]</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md`:
- Around line 19-20: Replace the guidance string "Secrets and auth live in
Cloudflare KV" (the line enumerating KV as the secret store) with a clear
directive to use Worker/Alchemy secret bindings (or other dedicated secret
management) for all sensitive credentials and authentication material, and state
that Cloudflare KV should only be used for non-secret, non-sensitive state;
update the corresponding mentions elsewhere (the repeated text at lines 31-32)
to the same wording so the ADR consistently directs secrets to secret bindings
and reserves KV for non-secret state.
- Around line 75-110: The two fenced code blocks (the ASCII architecture diagram
starting with "Slack / Linear / GitHub Webhooks" and the repository tree
starting with "apps/open-swe-agent/") are missing language identifiers and
trigger markdownlint MD040; update both opening triple-backtick fences to
include a language tag such as ```text (and similarly fix the other fenced
blocks at the noted later range around the repo tree) so the blocks become
```text ... ``` to suppress the warning and preserve formatting.
- Around line 263-295: The doc text and example implementation conflict: the
text states the sandbox invokes the Durable Object (DO) HTTP API to run
commands, but the CloudflareContainerSandbox class implements execute() with
local subprocess.run. Pick one model and make both the description and the
implementation consistent: either (A) update the text to state that
CloudflareContainerSandbox runs commands locally inside the container (keep
BaseSandbox subclass CloudflareContainerSandbox and its execute using
subprocess.run), or (B) change the implementation of
CloudflareContainerSandbox.execute to call the DO HTTP API (e.g., POST to the DO
endpoint with the command and return an ExecuteResponse built from the HTTP
response) and update the doc blurb to describe HTTP callback to the DO; ensure
references to id, execute, and ExecuteResponse remain correct.
- Around line 130-131: The ADR incorrectly lists QueueConsumer as exported from
alchemy/cloudflare v0.82.2; update the document to remove QueueConsumer from the
export list and state that Queue, DurableObjectNamespace, and Container are the
exported symbols, and clarify that Queue handles both producer and consumer
behavior (via bindings/eventSources) rather than a separate QueueConsumer; also
verify the implementation referenced in apps/wodsmith-start/alchemy.run.ts uses
Queue for consumption (not QueueConsumer) and adjust any usage notes to reflect
the Queue-based consumer pattern and direct DO stub RPC support (e.g.,
stub.startTask()).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: a6e625e7-d3ab-4201-8dba-d828b26cc8c5
📒 Files selected for processing (1)
docs/adr/0007-cloudflare-native-ai-coding-agent.md
Comment on lines
+75
to
+110
| ``` | ||
| Slack / Linear / GitHub Webhooks | ||
| ↓ | ||
| ┌──────────────────────────────────────┐ | ||
| │ Cloudflare Worker │ ← thin webhook receiver | ||
| │ apps/wodsmith-start (existing) │ | ||
| │ src/routes/api/webhooks/ │ | ||
| │ - verify signatures │ | ||
| │ - react 👀 immediately │ | ||
| │ - enqueue task to AGENT_QUEUE │ | ||
| └──────────────┬───────────────────────┘ | ||
| ↓ | ||
| ┌──────────────────────────────────────┐ | ||
| │ Cloudflare Queue: agent-tasks │ ← async dispatch | ||
| └──────────────┬───────────────────────┘ | ||
| ↓ | ||
| ┌──────────────────────────────────────┐ | ||
| │ Durable Object: AgentSession │ ← one per thread (deterministic ID) | ||
| │ - owns container lifecycle │ | ||
| │ - persists thread state in DO │ | ||
| │ - buffers follow-up messages │ | ||
| │ - WebSocket for real-time UI │ | ||
| └──────────────┬───────────────────────┘ | ||
| ↓ | ||
| ┌──────────────────────────────────────┐ | ||
| │ Cloudflare Container │ ← isolated Linux sandbox per thread | ||
| │ Image: open-swe Python agent │ | ||
| │ - git clone repo inside │ | ||
| │ - read AGENTS.md │ | ||
| │ - LangGraph agent loop │ | ||
| │ - calls Anthropic API │ | ||
| │ - commits code, opens PR │ | ||
| └──────────────┬───────────────────────┘ | ||
| ↓ | ||
| GitHub API / Linear API / Slack API | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add languages to fenced code blocks (markdownlint MD040).
These two fenced blocks are missing language identifiers, which will keep markdownlint warnings active.
Suggested markdown fix
-```
+```text
Slack / Linear / GitHub Webhooks
...
GitHub API / Linear API / Slack API- +text
apps/open-swe-agent/
├── agent/
...
└── pyproject.toml
</details>
Also applies to: 238-248
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 75-75: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @docs/adr/0007-cloudflare-native-ai-coding-agent.md around lines 75 - 110,
The two fenced code blocks (the ASCII architecture diagram starting with "Slack
/ Linear / GitHub Webhooks" and the repository tree starting with
"apps/open-swe-agent/") are missing language identifiers and trigger
markdownlint MD040; update both opening triple-backtick fences to include a
language tag such as text (and similarly fix the other fenced blocks at the noted later range around the repo tree) so the blocks become text ... ``` to
suppress the warning and preserve formatting.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
Comment on lines
+130
to
+131
| **Infrastructure is managed via Alchemy** in `apps/wodsmith-start/alchemy.run.ts`, following the same pattern as all other resources in the app. Alchemy v0.82.2 (already installed) exports `Queue`, `QueueConsumer`, `DurableObjectNamespace`, and `Container` from `alchemy/cloudflare` — no `wrangler.jsonc` edits required. | ||
|
|
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
`Verify in official docs:
- In alchemy/cloudflare v0.82.2, are Queue, QueueConsumer, DurableObjectNamespace, and Container exported exactly as named?
- In Cloudflare Workers Durable Objects, can a DurableObjectNamespace stub call class methods directly (e.g., stub.startTask()), or is fetch()/RPC setup required?`
💡 Result:
- Yes for Queue, DurableObjectNamespace, and Container. No evidence found for QueueConsumer being exported exactly as named in alchemy/cloudflare v0.82.2; it may not be exported or uses a different name/convention (Queue handles both producer/consumer via bindings/eventSources). 2) Yes, a DurableObjectNamespace stub can call class methods directly via RPC (e.g., stub.startTask) without fetch/RPC setup, for compatibility date 2024-04-03+. Official Cloudflare docs confirm public methods on Durable Object classes are exposed as RPC methods callable via stubs. Alchemy examples use standard Cloudflare DurableObjectNamespace and stubs (env.COUNTER.get(id)), supporting direct RPC calls.
Citations:
- 1: https://alchemy.run/guides/cloudflare-durable-objects/
- 2: https://alchemy.run/providers/cloudflare/queue/
- 3: https://deepwiki.com/alchemy-run/alchemy/1.3-module-exports-and-api-surface
- 4: https://developers.cloudflare.com/durable-objects/api/base/
- 5: https://developers.cloudflare.com/durable-objects/api/stub/
- 6: https://developers.cloudflare.com/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/
- 7: https://developers.cloudflare.com/workers/runtime-apis/rpc/
QueueConsumer is not exported from alchemy/cloudflare v0.82.2 — update the ADR.
Queue, DurableObjectNamespace, and Container are correctly exported and direct RPC calls on DO stubs (e.g., stub.startTask()) are fully supported. However, QueueConsumer does not appear to be exported as a named export from alchemy/cloudflare; the Queue class handles both producer and consumer functionality via bindings/eventSources. Correct the export list in the ADR and verify the Queue usage pattern matches the intended implementation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md` around lines 130 - 131,
The ADR incorrectly lists QueueConsumer as exported from alchemy/cloudflare
v0.82.2; update the document to remove QueueConsumer from the export list and
state that Queue, DurableObjectNamespace, and Container are the exported
symbols, and clarify that Queue handles both producer and consumer behavior (via
bindings/eventSources) rather than a separate QueueConsumer; also verify the
implementation referenced in apps/wodsmith-start/alchemy.run.ts uses Queue for
consumption (not QueueConsumer) and adjust any usage notes to reflect the
Queue-based consumer pattern and direct DO stub RPC support (e.g.,
stub.startTask()).
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/adr/0007-cloudflare-native-ai-coding-agent.md">
<violation number="1" location="docs/adr/0007-cloudflare-native-ai-coding-agent.md:19">
P2: This ADR overstates the KV rule: the app already uses Cloudflare KV for session/auth state, so documenting KV as "non-secret, non-sensitive state only" is inaccurate.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (3)
docs/adr/0007-cloudflare-native-ai-coding-agent.md (3)
75-110:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks (MD040).
These fenced blocks should use a language tag (e.g.,
text) to satisfy markdownlint.Suggested doc fix
-``` +```text Slack / Linear / GitHub Webhooks ... GitHub API / Linear API / Slack API-
+text
apps/open-swe-agent/
...
└── pyproject.toml</details> Also applies to: 238-248 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/adr/0007-cloudflare-native-ai-coding-agent.mdaround lines 75 - 110,
The fenced code blocks in the ADR contain unlabeled backtick blocks (the ASCII
diagram starting "Slack / Linear / GitHub Webhooks ..." and the tree/list
example containing "apps/open-swe-agent/ ... └── pyproject.toml") which violate
MD040; add a language tag (e.g., "text") to each triple-backtick fence so they
becometext ...; update every similar unlabeled fence in the document
(including the other instance noted around the apps/ listing) to use the same
"text" tag to satisfy markdownlint.</details> --- `130-131`: _⚠️ Potential issue_ | _🟠 Major_ **Re-verify `QueueConsumer` usage in ADR against `alchemy/cloudflare` v0.82.2.** The ADR repeatedly treats `QueueConsumer` as a first-class export/resource; please verify the exact API surface and, if needed, rewrite to the queue-consumer pattern actually supported by your installed version. ```web In official Alchemy docs for alchemy/cloudflare v0.82.2, is `QueueConsumer` exported as a named resource, or is queue consumption configured via `Queue`/event-source bindings? Please provide the exact supported API names and a minimal example. ``` Also applies to: 134-140, 148-155, 332-332, 355-355, 387-387 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md` around lines 130 - 131, Update the ADR to accurately reflect the alchemy/cloudflare v0.82.2 API: verify whether QueueConsumer is actually exported or if queue consumption is handled via Queue + event-source bindings, then replace every incorrect reference to QueueConsumer with the correct API names (e.g., Queue, Queue.consumer/event-source binding pattern, DurableObjectNamespace, Container) and include a minimal prose example showing the supported pattern (the exact exported symbols and how to wire consumption). Specifically locate and change mentions of QueueConsumer in the ADR and rewrite the example usage to match the verified v0.82.2 surface (naming the actual exported identifiers and describing how to configure consumption). ``` </details> --- `263-275`: _⚠️ Potential issue_ | _🟠 Major_ **Phase 3 execution model is internally inconsistent.** Line 263 says execution calls back to DO HTTP API, but the implementation shown executes local subprocess commands inside the container. Pick one model and align both text and snippet. <details> <summary>Minimal wording fix (if local in-container execution is intended)</summary> ```diff -**`agent/integrations/cloudflare.py`** — implements `SandboxBackendProtocol` by calling back to the Durable Object's HTTP API to execute commands in the container: +**`agent/integrations/cloudflare.py`** — implements `SandboxBackendProtocol` by executing commands directly inside the Cloudflare Container process: ``` </details> Also applies to: 284-295 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md` around lines 263 - 275, The doc text and code disagree about the execution model: update either the description or the implementation so they match; specifically, align the narrative that currently claims "calling back to the Durable Object's HTTP API" with the actual class implementation CloudflareContainerSandbox (which now runs local subprocesses) and related symbols BaseSandbox and ExecuteResponse — choose one approach and apply it consistently (A) if you intend in-container execution, revise the prose to state the container runs commands via subprocesses and update the other referenced sections (lines 284-295) to the same model, or (B) if you intend DO HTTP callbacks, replace the CloudflareContainerSandbox subprocess logic with an HTTP client implementation that posts commands to the Durable Object API and returns ExecuteResponse, then update the surrounding text accordingly. ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@docs/adr/0007-cloudflare-native-ai-coding-agent.md:
- Line 366: The sentence stating "existing Cloudflare KV session/auth patterns
(ADR-0001) apply unchanged" conflicts with earlier guidance that KV is
non-secret-only; update this line in ADR-0007 to explicitly state that ADR-0001
KV patterns apply for non-secret session/auth data only and that any secret
material must use Cloudflare secret bindings (or the documented secret-storage
pattern), thereby aligning the KV guidance with the secret-binding directives
and removing ambiguity.
Duplicate comments:
In@docs/adr/0007-cloudflare-native-ai-coding-agent.md:
- Around line 75-110: The fenced code blocks in the ADR contain unlabeled
backtick blocks (the ASCII diagram starting "Slack / Linear / GitHub Webhooks
..." and the tree/list example containing "apps/open-swe-agent/ ... └──
pyproject.toml") which violate MD040; add a language tag (e.g., "text") to each
triple-backtick fence so they becometext ...; update every similar
unlabeled fence in the document (including the other instance noted around the
apps/ listing) to use the same "text" tag to satisfy markdownlint.- Around line 130-131: Update the ADR to accurately reflect the
alchemy/cloudflare v0.82.2 API: verify whether QueueConsumer is actually
exported or if queue consumption is handled via Queue + event-source bindings,
then replace every incorrect reference to QueueConsumer with the correct API
names (e.g., Queue, Queue.consumer/event-source binding pattern,
DurableObjectNamespace, Container) and include a minimal prose example showing
the supported pattern (the exact exported symbols and how to wire consumption).
Specifically locate and change mentions of QueueConsumer in the ADR and rewrite
the example usage to match the verified v0.82.2 surface (naming the actual
exported identifiers and describing how to configure consumption).- Around line 263-275: The doc text and code disagree about the execution model:
update either the description or the implementation so they match; specifically,
align the narrative that currently claims "calling back to the Durable Object's
HTTP API" with the actual class implementation CloudflareContainerSandbox (which
now runs local subprocesses) and related symbols BaseSandbox and ExecuteResponse
— choose one approach and apply it consistently (A) if you intend in-container
execution, revise the prose to state the container runs commands via
subprocesses and update the other referenced sections (lines 284-295) to the
same model, or (B) if you intend DO HTTP callbacks, replace the
CloudflareContainerSandbox subprocess logic with an HTTP client implementation
that posts commands to the Durable Object API and returns ExecuteResponse, then
update the surrounding text accordingly.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Run ID**: `7b360348-6684-4df1-9e1d-d2c7f6eacaf4` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 44a83ee39946e652428dee3bf035b665647bf311 and b4ea50f49667abb144bb908b63d7be8445512739. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `docs/adr/0007-cloudflare-native-ai-coding-agent.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| * Good, because single infrastructure provider — no new vendor accounts or billing relationships | ||
| * Good, because Durable Objects are the right primitive for long-running stateful sessions with message queuing | ||
| * Good, because Cloudflare Containers provide true Linux isolation at low cold-start cost | ||
| * Good, because existing Cloudflare KV session/auth patterns (ADR-0001) apply unchanged |
Contributor
There was a problem hiding this comment.
Resolve KV/auth guidance contradiction.
This line says existing KV session/auth patterns apply unchanged, which conflicts with earlier directives that KV is non-secret only. Please align this line with the secret-binding guidance to avoid ambiguous security direction.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md` at line 366, The sentence
stating "existing Cloudflare KV session/auth patterns (ADR-0001) apply
unchanged" conflicts with earlier guidance that KV is non-secret-only; update
this line in ADR-0007 to explicitly state that ADR-0001 KV patterns apply for
non-secret session/auth data only and that any secret material must use
Cloudflare secret bindings (or the documented secret-storage pattern), thereby
aligning the KV guidance with the secret-binding directives and removing
ambiguity.
…dsmith-start unchanged
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/adr/0007-cloudflare-native-ai-coding-agent.md">
<violation number="1" location="docs/adr/0007-cloudflare-native-ai-coding-agent.md:151">
P2: Make `scriptName` stage-aware; the documented `wodsmith-app` name does not match this repo's stage-specific Worker names.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (3)
docs/adr/0007-cloudflare-native-ai-coding-agent.md (3)
75-110:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks.
At Line 75, Line 121, and Line 262, fenced blocks are still unlabeled and will continue to trigger markdownlint MD040.
Suggested doc fix
-``` +```text Slack / Linear / GitHub Webhooks ... GitHub API / Linear API / Slack API-
+text
apps/coding-agent/
...
└── package.json-``` +```text apps/open-swe-agent/ ... └── pyproject.tomlAlso applies to: 121-137, 262-272
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md` around lines 75 - 110, Three fenced code blocks (the one starting "Slack / Linear / GitHub Webhooks", the block beginning "apps/coding-agent (NEW, standalone)", and the block beginning "apps/open-swe-agent/") are unlabeled and trigger markdownlint MD040; fix them by changing their opening backticks from ``` to ```text so the blocks become language-identified text fences, leaving the content unchanged and keeping the closing ``` as-is.
401-401:⚠️ Potential issue | 🟠 MajorAlign KV/auth wording with the secret-binding policy.
Line 401 (“KV session/auth patterns apply unchanged”) conflicts with Lines 19 and 31, which correctly reserve KV for non-secret state and require
alchemy.secret()for sensitive material.Suggested wording update
-* Good, because existing Cloudflare KV session/auth patterns (ADR-0001) apply unchanged +* Good, because ADR-0001 KV patterns apply for non-secret session/auth state, while all sensitive credentials remain in Alchemy/Worker secret bindings🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md` at line 401, The sentence stating "KV session/auth patterns apply unchanged" conflicts with the secret-binding policy; update the ADR text to explicitly state that Cloudflare KV is reserved for non-secret state only and that any sensitive secrets must use the secret-binding API (e.g., alchemy.secret()) in accordance with ADR-0001 and the secret-binding policy; replace or amend the Line 401 wording to reference KV for non-sensitive session/auth state and call out alchemy.secret() for sensitive material so the document is consistent with Lines 19 and 31.
153-161:⚠️ Potential issue | 🟠 MajorResolve QueueConsumer guidance contradictions before implementation.
The ADR currently mixes three incompatible statements: importing
QueueConsumer(Line 159), saying no separate QueueConsumer is needed (Line 206), and claimingQueueConsumeris an exported/already-used resource (Line 422). This can mislead implementation and resource planning.For alchemy/cloudflare v0.82.2, what are the official exports for queue resources? Specifically, is QueueConsumer a named export, or is queue consumption configured via Worker eventSources with Queue only?Also applies to: 206-207, 422-422
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md` around lines 153 - 161, The ADR mixes contradictory guidance about queue consumption: it imports QueueConsumer from alchemy/cloudflare while also claiming no separate QueueConsumer is needed and later stating it's an exported resource; verify the actual exports for alchemy/cloudflare v0.82.2 (whether QueueConsumer is a named export or consumption is done via Worker eventSources with Queue) by checking the package's published exports/types (npm package or the repo types), then update the ADR to a single consistent statement: if QueueConsumer is exported, keep the import examples and document its usage; otherwise remove the QueueConsumer import and change examples to show queue consumption via Worker.eventSources with Queue and remove the contradictory sentences mentioning QueueConsumer as an existing resource (update the import block and the paragraphs referencing QueueConsumer, Queue, and Worker accordingly).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/adr/0007-cloudflare-native-ai-coding-agent.md`:
- Around line 75-110: Three fenced code blocks (the one starting "Slack / Linear
/ GitHub Webhooks", the block beginning "apps/coding-agent (NEW, standalone)",
and the block beginning "apps/open-swe-agent/") are unlabeled and trigger
markdownlint MD040; fix them by changing their opening backticks from ``` to
```text so the blocks become language-identified text fences, leaving the
content unchanged and keeping the closing ``` as-is.
- Line 401: The sentence stating "KV session/auth patterns apply unchanged"
conflicts with the secret-binding policy; update the ADR text to explicitly
state that Cloudflare KV is reserved for non-secret state only and that any
sensitive secrets must use the secret-binding API (e.g., alchemy.secret()) in
accordance with ADR-0001 and the secret-binding policy; replace or amend the
Line 401 wording to reference KV for non-sensitive session/auth state and call
out alchemy.secret() for sensitive material so the document is consistent with
Lines 19 and 31.
- Around line 153-161: The ADR mixes contradictory guidance about queue
consumption: it imports QueueConsumer from alchemy/cloudflare while also
claiming no separate QueueConsumer is needed and later stating it's an exported
resource; verify the actual exports for alchemy/cloudflare v0.82.2 (whether
QueueConsumer is a named export or consumption is done via Worker eventSources
with Queue) by checking the package's published exports/types (npm package or
the repo types), then update the ADR to a single consistent statement: if
QueueConsumer is exported, keep the import examples and document its usage;
otherwise remove the QueueConsumer import and change examples to show queue
consumption via Worker.eventSources with Queue and remove the contradictory
sentences mentioning QueueConsumer as an existing resource (update the import
block and the paragraphs referencing QueueConsumer, Queue, and Worker
accordingly).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: c5eb10bb-5cec-43a3-96f8-d08289fb46d6
📒 Files selected for processing (1)
docs/adr/0007-cloudflare-native-ai-coding-agent.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds ADR-0007 documenting the architecture for running an open-swe-style internal AI coding agent natively on Cloudflare infrastructure.
What's in the ADR
The decision captures how to use Cloudflare's primitives as direct replacements for open-swe's third-party sandbox vendors (Modal, Daytona, Runloop):
ContainerDurableObjectNamespaceQueue+QueueConsumerTanStackStartbindingsKey decisions captured
Queue,QueueConsumer,DurableObjectNamespace,Container) are already exported fromalchemy/cloudflarein v0.82.2 — no new dependenciesapps/wodsmith-start/alchemy.run.tsalongside existing resources (samepnpm alchemy:devworkflow)src/routes/api/webhooks/using the existingcreateAPIFileRoutepatternAGENTS.mdis read from the cloned repo inside the container so the agent knows WODsmith conventions automaticallyFiles changed
docs/adr/0007-cloudflare-native-ai-coding-agent.md(new)Summary by cubic
Adds ADR-0007 defining a Cloudflare‑native architecture for our internal coding agent, replacing external sandboxes with Cloudflare Containers, Durable Objects, Queues, and Workers. The agent runs as a standalone
apps/coding-agentWorker app, leavingwodsmith-startunchanged.It documents managing infra via
alchemy/cloudflare(Queue, Durable Object, Container wired via WorkereventSources), placing webhooks underapps/coding-agent/src/routes/webhooks/, running the Python agent in the container with repoAGENTS.md, executing sandbox commands via local subprocesses (no HTTP callout), and handling secrets withalchemy.secret()(KV only for non‑secret state).Written for commit 3a59a10. Summary will update on new commits.
Summary by CodeRabbit