Repository navigation
Effect Service Conventions: 2 issues found
Two concrete findings were posted as inline review comments.
apps/server/src/provider/acp/AcpSessionRuntime.ts:577—Effect.cached(connectOnce)memoizes the entireExit, so a failedinitializehandshake is replayed permanently;startstill resets toNotStarted, so the retry path can never re-issueinitialize. The change also deleted the documented invariant onstart("Concurrent calls share the same in-flight startup and a failed startup may be retried") and addedconnect/closewithout docs, contradicting the change-discipline rule to preserve useful invariants/documentation.apps/server/src/provider/acp/AcpAdapterSupport.ts:44-47— the auth-required distinction is expressed as an untypedprovider === "acp"/ magic-32000comparison, and the remediation hint is concatenated onto the agent-supplied wire text indetail(which becomes the caller-visible message). The same magic-code check is duplicated inDrivers/AcpDriver.ts:179via a raw_tagstring compare. Suggested exporting one structural predicate and deriving a stable detail from it, keeping the wire text only incause.
A non-blocking structural note was included in the review body: the generic ACP adapter core (makeAcpAdapter, AcpAdapterProfile, AcpAdapterOptions = Omit<CursorAdapterLiveOptions, ...>) now lives in the Cursor-named Layers/CursorAdapter.ts and is consumed by the generic Drivers/AcpDriver.ts.
Details
Note
Your check run agent prompt is: .macroscope/check-run-agents/effect-service-conventions.md
More information about how Check Run Agents work can be found in our Help Center.
Files reviewed in scope: apps/server/src/provider/Drivers/AcpDriver.ts, apps/server/src/provider/Layers/CursorAdapter.ts, apps/server/src/provider/Layers/CursorAdapter.test.ts, apps/server/src/provider/acp/AcpAdapterSupport.ts, apps/server/src/provider/acp/AcpSessionRuntime.ts, apps/server/src/provider/acp/AcpRuntimeModel.ts, apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts, apps/server/src/provider/Layers/ProviderRegistry.ts, apps/server/src/textGeneration/TextGeneration.ts, packages/contracts/src/settings.ts, packages/effect-acp/src/protocol.ts, plus the web/mobile UI touch points.
Checked and found acceptable:
- Namespace subpath imports (
effect/Effect,effect/Ref,effect/Scope, …) are used consistently; named imports are limited to@t3tools/contractsand pure helper modules, matching the convention. makeUnsupportedTextGenerationreturnsTextGeneration.of({...})and is typed asTextGeneration["Service"], consistent with the existingmakeTextGenerationFromRegistry/make/layerlayout in that module.AcpAdapterProfile.makeRuntimeis a deliberate callback strategy (production driver, Cursor profile, and test harness each supply it), not hidden service injection; thechildProcessSpawnerhand-off mirrors the pre-existingCodexAdapter/GrokAdapter/CursorAcpSupportpattern.- No new
ManagedRuntime.make,runPromise, orLayer.succeed-hidden-runtime usage was introduced in production service code; no new lint/type suppression directives were added. ProviderDriverError({ detail:Failed to build ACP snapshot: ${cause.message ?? String(cause)}, cause })inAcpDriver.ts:230copiescause.messageintodetail, but it is a verbatim copy of the identical construction in all six existing drivers, so it was treated as pre-existing repository-wide style rather than a violation introduced here.- Backend behavior changes are covered by focused tests (standard ACP adapter session in
CursorAdapter.test.ts, permission/auth mapping inAcpAdapterSupport.test.ts, reasoning/model projection inAcpRuntimeModel.test.ts, JSON-RPC error mapping ineffect-acp/src/client.test.ts). The retry-after-failed-handshake path inAcpSessionRuntimeis the one behavior change left untested.
Effect.cached semantics were verified against the vendored Effect v4 source (cached = cachedWithTTL(self, Duration.infinity), cell filled from onExit), confirming failures are cached permanently.
🔍 Agent activity — 17 tool calls
💭 I'm reviewing the diff for Effect service convention violations, particularly around error construction. A few spots—AcpDriver.ts's ProviderDriverError and AcpAdapterSupport.ts's error handling—look like they derive the
detailfield fromcause.messageorerror.message, which conflicts with the rule that wrapper messages must come from stable structural attributes, not the cause itself. I want to check the actual repo code and any existing precedent before flagging these as real violations.
1. browse_code — apps/server/src/provider/Drivers/AcpDriver.ts
2. browse_code — apps/server/src/provider/Errors.ts
💭 I want to check whether this pattern of copying cause.message into a detail field already exists in other drivers, since that would suggest it's a pre-existing convention rather than a new violation introduced by this change—but the guidance is explicit that this detail-copying pattern is forbidden regardless.
3. git_tools — Failed to build .* snapshot
4. git_tools — new ProviderDriverError
💭 This pattern is consistent with all six existing drivers, so it's borderline whether to flag it as new. Since the instructions say to report concrete violations introduced in the changed scope, and this new file is just replicating an established boilerplate pattern, I'm leaning toward not flagging it as a fresh issue. Let me move on and check AcpAdapterSupport.ts fully for stronger findings.
5. browse_code — apps/server/src/provider/acp/AcpAdapterSupport.ts
6. browse_code — apps/server/src/textGeneration/TextGeneration.ts
💭 The naming for makeUnsupportedTextGeneration follows existing conventions like makeTextGenerationFromRegistry, so that's fine. Now I'm examining the AcpAdapterSupport error mapping logic, where it checks the provider string and builds an error detail from the original error message plus an appended sentence—I'm weighing whether this violates the rule against deriving messages from a cause's message, though the underlying behavior of copying error.message already predates this change. That said, this could still be flagged: extending pre-existing behavior that copies cause.message into detail, plus appending a remediation hint onto what might be a raw wire-payload message from the agent, since AcpRequestError likely wraps JSON-RPC error text straight from the agent. I want to dig into the actual CursorAdapter.ts changes, the session runtime file, and the protocol.ts mapping of Die defects to Fail to see if there's something more substantive going on there.
7. browse_code — apps/server/src/provider/Layers/CursorAdapter.ts
💭 I'm reconsidering the file naming: since CursorAdapter.ts now houses the shared ACP adapter core and AcpDriver imports makeAcpAdapter from it, the conventions suggest that a concrete implementation module can just use plain make/layer naming, and when Services/Foo.ts and Layers/Foo.ts combine, they should hoist up to domain/Foo.ts. However, this is arguably a real convention issue worth flagging — the module named for the Cursor implementation is now hosting the generic shared core consumed by the new driver, which conflicts with keeping a service's logic in one canonical module. I need to weigh whether to flag moving makeAcpAdapter out of CursorAdapter.ts, while being careful not to treat genuinely separate implementation/adapter modules as violations just because of naming similarity. Now I want to check AcpSessionRuntime.ts for the Context.Service definition and how connect/close are implemented, plus look at whether AcpAdapterRuntimeFactory passing a service instance directly as a parameter conflicts with the dependency acquisition conventions. The dependency acquisition rule specifically flags factories that accept a
Foo["Service"]value when that dependency belongs to the service itself, so I'm checking whether AcpDriver's makeRuntime does exactly this by manually threading childProcessSpawner through Effect.provideService rather than declaring it as a proper requirement. I need to trace whether this pattern existed before by comparing against the previous makeCursorAcpRuntime signature and checking CursorAcpSupport.ts to see if childProcessSpawner was already passed this way.
8. git_tools — childProcessSpawner
💭 The childProcessSpawner pattern is already established repo-wide, so that's not a new issue. Now I'm examining AcpSessionRuntime.ts, checking the Context.Service setup, the connect implementation with Effect.cached, and the close semantics around Ref.get(startStateRef) to make sure everything is sound, plus scanning for any added lint suppression directives. I don't see any biome-ignore or @ts-expect-error in the diff, so I'm grepping the new files directly. I'm checking how sessionCapabilities close is typed with the null check, confirming the ProviderRegistry change is just a predicate addition, and reviewing the protocol.ts change that maps Die defects containing protocol errors into Fail, verifying the isProtocolError check.
9. browse_code — packages/effect-acp/src/protocol.ts
💭 That protocol plumbing looks fine per conventions. Now I'm checking AcpSessionRuntime.ts for Effect usage patterns like cached connections, and I want to grep the touched files for error handling and runtime patterns to make sure they're consistent.
10. git_tools — catchIf|catchTag(|runPromise|ManagedRuntime|Layer.succeed
11. browse_code — apps/server/src/provider/acp/AcpSessionRuntime.ts
💭 I notice the docstring for
startchanged too—it split off a separateconnectmethod, andstartnow just covers authenticating then loading or creating the session, rather than the whole connection lifecycle. The change discipline rule about preserving invariants and documentation matters here: that dropped sentence about concurrent calls sharing an in-flight startup and failed retries documented behavior that likely still holds, sinceconnecthas no doc comment covering it. I should check the implementation to confirm the invariant is still intact before flagging this as a real issue.
12. browse_code — apps/server/src/provider/acp/AcpSessionRuntime.ts
💭 I'm considering whether Effect.cached memoizes both success and failure outcomes — I believe it does, since it's built on cachedWithTTL with an infinite duration, so a failed connection attempt would also get cached. That raises a concern: previously a failed
startreset the state machine to allow retry, but with cachedconnect, retryingstart()would just replay the cached failure instead of attempting a fresh initialize. Since the removed doc comment explicitly promised retry behavior, this could be a real regression, though it might not matter much if the underlying process is already dead by that point. I'm noting that AcpDriver's checkProvider creates a fresh runtime each call, so it isn't affected — this issue is really about thestartinvariant and the missing documentation preserving it. I want to verify Effect'scachedsemantics for this version to confirm failures are memoized, so I'm checking whether there's vendored documentation in the repo.
13. browse_code — In this repo's Effect version (effect v4 / effect/Effect), what are the semantics of Effect.cached? Does it memoize failures as well as successes (i.e. is a failed effect retried on subsequent evaluation)? Show the implementation or type docs from the installed effect package if available, plus any repo usages of Effect.cached with comments about retry behavior.
💭 This confirms a real regression: since
Effect.cachedpermanently caches failures, onceconnectfails andstartresets to NotStarted for retry, the cached failure gets replayed instead of re-running initialize — so retries can never actually succeed, unlike the previous behavior. Now I'm looking at the error mapper: comparingprovider === "acp"as a raw string against a branded type, plus auth-hint logic tucked into a generic mapper with a magic-32000code that's duplicated in AcpDriver. That's a rule violation around detail derivation and duplicated magic constants — I want to check whether effect-acp already exposes a proper predicate or static factory for auth-required errors, since the test referencesAcpRequestError.authRequired().
14. git_tools — -32000|authRequired|AUTH_REQUIRED
💭 I notice AcpDriver compares the raw
_tagstring against "AcpRequestError" instead of using the exported schema predicate, which goes against the convention of exporting predicates likeSchema.is(Foo)and usingEffect.catchTagsfor statically known tagged failures. There's already a similar private predicate in AcpAdapterSupport that could be reused or exported instead. I don't think I'd flag it strongly. Another candidate is comparing a branded ProviderDriverKind to a bare string inside a shared mapper, plus derivingdetailfromerror.message— copying wire text that the convention says shouldn't leak into detail fields; the new part is just an appended remediation string, so it's a moderate concern. I'm also checkingmakeAcpAdapter, a factory taking aprofilewith amakeRuntimecallback, against the rule about flagging factories or constructors that might need scrutiny. The rule allows deliberate callback strategies, pure configuration, and immutable domain values as non-injection, somakeRuntimepasses as a deliberate callback strategy. I'm also scanningsnapshot.refreshforked indriverScopewith error handling into a warning log, which looks fine, andEffect.forkIn(driverScope)inside a config-change handler, which could spawn unbounded fibers but isn't a convention violation. I'm checking whetherdefaultConfigusingdecodeSettingsandSchema.decodeSyncmatches the pattern other drivers use, and whetherAcpDriverEnvlistsServerSettingsServiceandBackgroundPolicyin its type union without the create function ever actually yielding them. TheProviderRegistry.tschange adding acp handling looks fine. Now I want to verify test coverage -- the PR adds tests for the standard ACP adapter path, adapter support, runtime model, and client, but AcpDriver itself lacks a dedicated test file, so I'm checking whether other drivers similarly go untested.
15. browse_code — apps/server/src/provider/**/*.test.ts
💭 Missing AcpDriver test seems consistent with the existing pattern, so I'll skip that. I'm checking
applyRequestedSessionConfiguration's standard branch and it looks fine skipping model/mode categories, and theresolvedModelfallback logic insendTurnalso seems conventional. Now I want to look at how CursorAdapter handles closing the ACP connection. Actually the more interesting issue is inmapAcpToAdapterError— the auth-string branch derives itsdetailfield directly fromerror.message, which is the cause's message, and then that detail gets used to build the wrapper's error message. That's exactly the pattern the guidelines warn against: constructing a wrapper message fromcause.messagerather than from stable structural attributes. Since this line was touched in the diff, it counts as a retained violation in the changed scope, not something to dismiss as pre-existing. Now I'm ranking candidate findings by strength: theEffect.cachedmemoization issue in AcpSessionRuntime feels like the strongest one, since it silently drops a documented invariant about retryable startup failures, while the provider-specific string/code branching in the shared error mapper is a second, more moderate concern. I'm also noticing AcpDriver duplicates the same-32000magic check with a raw_tagcompare, which overlaps with the mapper issue. I'm deciding whether to combine that into one comment or split it — leaning toward placing a single note on AcpAdapterSupport about the detail-from-message pattern, while briefly flagging the duplicated check in AcpDriver so each finding is still stated once but without redundant comments. Separately, I'm looking atmakeAcpAdapter, the generic ACP adapter core exported from CursorAdapter.ts and imported by the generic AcpDriver.ts, along with its derived Omit-based option types. This seems like a real canonical-module violation — the shared core should live in something likeprovider/acp/AcpAdapter.tsrather than a Cursor-specific file, and the module doc still incorrectly says@module CursorAdapterLive, which reinforces the naming discipline issue. I'm also noting that deriving the generic option type viaOmitfrom the Cursor-specific options type is backwards dependency-wise, so I'll flag it with moderate severity. On theProviderDriverErrordetail copying cause.message point, I'll skip it since it matches six other existing drivers and fixing it would require a repo-wide cleanup rather than a targeted one. Now I want to double-check my confidence on the earlier connect-failure finding — specifically whether CursorAdapter retriesstart()on the same runtime after a failed session initialize, since that affects whether the issue actually matters in practice.
16. git_tools — acp.start()|runtime.start()|.start().pipe
💭 Since no retry-of-start case shows up in production, the practical impact of finding A seems limited, but the removed documented invariant is still real and the cached-failure behavior is a genuine subtle change worth flagging moderately—
Effect.cachedmemoizes failures permanently, contradicting the removed doc line, so I'd suggestEffect.cachedInvalidateWithTTLor invalidating on failure, or at least restoring the docs. Checking against "Effect Service Conventions," this falls within scope since the guidance says to preserve invariants and specification documentation while moving code, and here the invariant doc was dropped while the new caching directly contradicts it. Turning to finding D on module placement, I'm reconsidering whether the conventions actually support flagging it. The rules say to keep a service's schemas, tag, construction, and layer together only when they form one implementation, and not to flag separate adapter modules just for living in an implementation directory. SincemakeAcpAdapterisn't aContext.Service, and there's no explicit rule against generic core code living in an implementation-named file, this looks like a style preference rather than a real violation—so I'm leaning toward skipping D as an optional style preference rather than a real finding. But it's still the most notable structural oddity: an ACP-named driver importing from a CursorAdapter file, plus a stale@module CursorAdapterLivedocblock even though the header comment was updated. I could mention this as a brief non-blocking note in the review body without duplicating an inline comment, but I'll only mark it a failure if I find a genuinely clear violation. Now I'm digging back into finding B to see if it holds up as a real violation, checking it against the rule that error attributes and log fields must stay safe and bounded—no copying raw wire payloads or defect text intodetail,reason, ormessage, and the underlying value should only be preserved ascause. Looking closer, thedetailfield embedserror.messagefor an AcpRequestError, which includes the raw agent-supplied JSON-RPC text, and this flows straight into a caller-visible message. That pattern predates the PR, though the PR did touch these lines. What feels more worth flagging is the structural issue: provider-specific policy hardcoded via aprovider === "acp"string comparison plus a magic-32000code, duplicated again in AcpDriver.ts, rather than using a shared predicate or a static factory on the error type as convention suggests. I'm weighing whether this counts as a clear enough convention violation to justify a failure, leaning toward it being a moderate but real issue tied to how the auth-required case is being distinguished. I also want to check a few other spots — import ordering in AcpDriver.ts looks fine since AcpRuntimeModel is a pure helper module, the provider filtering duplicated across two web components isn't an Effect service concern, and the unmemoized filter in SettingsPanels.tsx falls outside the conventions in scope. Now I'm looking at whether AcpDriver's use ofEffect.catchCauseto log a warning constitutes a misuse of catchTags or an inappropriate new catchCause pattern. I'm also noting that the newcloseandconnectmembers onAcpSessionRuntimelack JSDoc while every other member has one with @see links — I can fold this into the same adjacent comment about the removed invariant and cached-failure contradiction around lines 188-194, which is a clean consolidation. Now I'm mapping out where in the diff hunks these inline comments should land, checking that they fall on the right-side line numbers for the new file version, starting with the interface changes around lines 188-194 in AcpSessionRuntime.ts. I'm confirming theEffect.cached(connectOnce)line lands at the added line 577 in the diff, so that's where I'll place the comment about the caching-failure concern alongside the missing invariant documentation. I'm considering suggesting a switch toEffect.cachedInvalidateWithTTLas a possible fix, though an inline code suggestion here would need careful wording to fit the diff context. Since the fix is contained to that one line and its neighbor, I'll present it as a diff instead, replacing the caching call with a comment explaining that handshake failures shouldn't be memoized. I'm working through the invalidation strategy—usingcachedInvalidateWithTTLso a failed connection can retry, then thinking through which error-tap hook actually exists in this version of Effect, sincetapErrormight not be available andonError(already used elsewhere in the file) also catches interruptions, which isn't quite what I want here. Now I'm moving to the second review comment on AcpAdapterSupport.ts, checking the diff hunk to confirm the exact line numbers for the added error-detail branch before suggesting a cleaner structural check for detecting the auth-required error, keeping any remediation text separate from the wire message. I'm also noting thatprovider === "acp"duplicates the DRIVER_KIND constant elsewhere. Weighing severity, the dropped invariant and failure memoization feel like a clear change-discipline violation, while the duplicated magic-code check is more moderate—so I'm leaning toward treating this as a failing finding given the check's default posture. Since findings exist, I should post the review with both inline comments and mark the state as failure, keeping the body itself minimal—just the verdict and a brief note about where the generic core logic lives, without expanding into the module-placement discussion. I'll add a short non-blocking note about the Cursor-named module dependency, then draft the first inline comment aboutAcpSessionRuntime.tsline 577, explaining that caching the wholeExitmeans a failed initialize handshake gets replayed indefinitely. Confirming line 577 corresponds to the cached connect effect in the diff hunk, so I can now write up the review comment.
17. modify_pr — Non-blocking structural note: the generic ACP adapter core (makeAcpAdapter, AcpAdapterProfile, AcpAdapterOptions) now lives in apps/server/src/provider/Layers/CursorAdapter.ts (module doc still @module CursorAdapterLive), and the generic Drivers/AcpDriver.ts imports it from there, with AcpAdapterOptions derived as Omit<CursorAdapterLiveOptions, "resolveSettings">. Consider hoisting the shared core to a canonically named module (e.g. provider/acp/AcpAdapter.ts) and leaving only the Cursor profile in CursorAdapter.ts, so the generic option/profile types are not defined in terms of the Cursor-specific ones.
Agent Credits: 513 credits
Token usage: 74 uncached input · 4,474,278 cache-read input · 285,567 cache-write input · 34,275 output
Agent Credits may also include non-token charges from external tools such as web research.