effect: Effect bridge package (LanguageModel over gateway + agent, schema interop, scoped sandbox layers)

[ThomasK33]

Tracking issue for an Effect bridge to the Coder AI SDK — a new packages/effect package (@coder/ai-sdk-effect) exposing the three existing packages through Effect-native abstractions.

Architecture

The bridge adapts our imperative SDK surfaces to Effect's service/Layer/Stream model without changing the underlying packages:

• LanguageModel service over AI Gateway (@coder/ai-sdk-provider): implement Effect's LanguageModel interface on top of the gateway endpoints, mapping Effect Prompt/Response to the provider's chat-completions/messages calls and HTTP failures to typed AiErrors (auth, quota, provider-unavailable, malformed-response), preserving the centralized vs BYOK auth modes.
• Schema interop: helpers bridging Standard Schema / Effect Schema to the SDK's tool-definition and structured-output surfaces, so Effect users define tools and output schemas in Effect Schema and get correct wire types both directions.
• Scoped resource management for sandboxes (@coder/ai-sdk-sandbox): ensureCoderWorkspace + session lifecycle as Effect.acquireRelease / scoped Layers, so workspace acquisition, agent-readiness waits, and teardown compose with Effect scopes and interruption.
• LanguageModel over CoderAgent/chatd (@coder/ai-sdk-agent): server-side agent loop as an Effect service — TurnTranslator output mapped onto Effect Stream, fiber interruption wired to agent.interrupt(), and the SDK's retryable/terminal error taxonomy (CoderStreamError.isRetryable, timeout vs cancellation) surfaced as tagged errors usable with Effect retry policies.

Roadmap

Phase 1 — Spike (in flight)

• packages/effect scaffold (private, excluded from release-please until graduation)
• Effect LanguageModel implementation over @coder/ai-sdk-provider (AI Gateway): Prompt/Response mapping + typed AiError hierarchy for HTTP errors
• Standard Schema / Effect Schema interop helpers for tool definitions and structured outputs
• Scoped Layers for workspace sandbox lifecycle (ensureCoderWorkspace + session as Effect.acquireRelease)
• Unit tests + live validation against dev.coder.com

Phase 2

• LanguageModel implementation over CoderAgent/chatd: TurnTranslator → Effect Stream mapping
• Fiber interruption → agent.interrupt()
• Retryable error tagging aligned with Effect retry policies
• Publishing decision: versioning, peerDependency policy on effect/@effect/ai, release-please wiring

Notes

• Spike ships as a private package: no npm publish and no release-please manifest entry until Phase 1 review concludes the API shape is right.
• Effect / @effect/ai are fast-moving; the spike should pin exact versions and record the pinned API surface in the package README.

---

Generated with mux • Model: anthropic:claude-fable-5 • Thinking: xhigh

[ThomasK33]

Phase 1 spike is up: #145.

Scope: packages/effect (@coder/ai-sdk-effect, private, unpublished, outside release-please) with the Effect LanguageModel over AI Gateway (generateText/generateObject/streamText, both auth modes), lossless mapping into @effect/ai's closed AiError union plus classifyError/isTransient for the auth/rate-limit/provider-unavailable/malformed-response taxonomy, Effect Schema → AI SDK schema interop (toAiSdkSchema), and scoped Layers wrapping ensureCoderWorkspace/createSession in Effect.acquireRelease with release-on-interrupt. 40 unit tests on fakes; gateway paths (generate, structured output, streaming, auth-error classification) validated live against dev.coder.com. API deltas vs. the sketch (closed AiError union, Standard-Schema JSON-conversion gap, published-release deps instead of workspace:*) are documented in the PR body.

---

Generated with mux • Model: anthropic:claude-fable-5 • Thinking: xhigh

[ThomasK33]

Phase 1 spike merged: #145 → main @ 1dce33f5aecb44d46e71a0a690cc9323ee02dd11.

Phase 1 checklist state:

• packages/effect scaffold (private, excluded from release-please until graduation) — verified post-merge: not in release-please config/manifest, release-please run on main produced no release PR for it; publint/attw skip it.
• Effect LanguageModel implementation over @coder/ai-sdk-provider (AI Gateway): Prompt/Response mapping + typed AiError mapping for HTTP errors. Delta vs. sketch: @effect/ai@0.37.0's AiError is a closed union, so the bridge maps losslessly into it and ships classifyError/isTransient (auth / rate-limit / provider-unavailable / malformed-response / transport / unknown) for retry policies.
• Standard Schema / Effect Schema interop helpers for tool definitions and structured outputs. Delta: bare Effect standard schemas can't produce JSON schema for AI SDK v7 (~standard.jsonSchema missing — throws in asSchema; pinned by a test), so toAiSdkSchema emits the AI SDK's own Schema container (Effect-derived JSON schema + Effect-decode validation).
• Scoped Layers for workspace sandbox lifecycle (ensureCoderWorkspace + session as Effect.acquireRelease), incl. teardown policies, release-on-interrupt, and rollback of workspaces created by acquisitions that later fail (ownership via observed create-call success, never existence probing).
• Unit tests + live validation against dev.coder.com — 45 unit tests on fakes; live tier: generateText, generateObject, streamText, and auth-error classification verified against dev.coder.com (temp token, expired after use). Sandbox layers are unit-tier only (documented gap; live provisioning would churn workspaces for a path owned by the already-released sandbox package).

Review: 3 codex rounds (3×P2 → 1×P1+1×P2+1×P3 → 1×P3), all fixed inline; both loops clean on the merged head a81f80f; zero unresolved threads. Notable hardening from review: concurrent-creation race in rollback (P1) fixed by tracking create-call ownership through a wrapped transport.

Phase 2 (open here): LanguageModel over CoderAgent/chatd with TurnTranslator → Effect.Stream, fiber interruption → agent.interrupt(), retryable tagging aligned with CoderStreamError.isRetryable, per-call generation-config channel, and the publishing decision (versioning, effect/@effect/ai peer policy, workspace:* deps, release-please wiring).

---

Generated with mux • Model: anthropic:claude-fable-5 • Thinking: xhigh