Repository navigation
Effect Service Conventions: 2 issues found
Two error-modelling convention violations in the new task-stop path:
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts(~606-610): thestopTaskprecondition throws a manufacturedErrorinsideEffect.tryPromisesolely so it becomes thecauseofClaudeAgentSdkQueryRunnerError. Fail with the typed error directly instead.apps/server/src/orchestration-v2/ProviderTurnControlService.ts(~294):Schema.is(ProviderTaskStopError)is constructed inline per failure; export a direct predicate (export const isProviderTaskStopError = Schema.is(ProviderTaskStopError)) as done forProviderTurnControlErrorin the same module.
Both findings were posted as inline review comments with suggested fixes.
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.
Scope reviewed: changed .ts/.tsx under apps/**, packages/**, infra/**, plus directly affected call sites.
Checked and found compliant:
- Effect library modules imported as subpath namespaces (
effect/Effect,effect/Layer,effect/Schema,effect/DateTime) in all touched files; no consolidatedfrom "effect"imports introduced. ProviderTurnControlServiceV2.stopTaskacquiresProviderSessionManagerV2from the environment via the existingLayer.effectconstruction; no service instances passed as constructor parameters in production code.Layer.succeedoccurrences are confined to test layers (ProviderTurnControlService.test.ts); noManagedRuntime.make,runPromise, orrunPromiseExitadded in domain services.- New failure
ProviderTaskStopErrorusesSchema.TaggedErrorClasswith structural attributes (threadId,providerSessionId,nativeTaskId) and preservescause; nodetailfield copyingcause.message, no redundant single-value discriminator. - New optional runtime capability (
ProviderAdapterV2SessionRuntime.stopTask?) models unavailability as a typed failure in the service operation rather than bypassing the layer. - Worker/orchestrator wiring for
subagent.stopfollows the existing effect-execution error mapping;providerSessionIdForSubagentStopis a pure exported helper with focused tests, and behavior changes are covered by tests rather than mocks of core logic. - Client-side additions (
AgentsPanelV2,WorkflowRunCardV2,orchestrationV2Subagents.ts) contain no Effect services; command dispatch goes through the existingcreateEnvironmentCommandboundary.
🔍 Agent activity — 1 tool call
💭 Looking at the changed files in the Effect service, I'm checking
ProviderTurnControlService.tsfor convention violations — specifically the newProviderTaskStopErrorthat usesSchema.TaggedErrorClasswith an optionalDefectcause. The code appliesSchema.is(ProviderTaskStopError)inline within mapError, but the convention expects exporting direct schema predicates likeexport const isFoo = Schema.is(Foo)instead of using them inline. I'm also examiningClaudeAdapterV2.tswherequeryRunnerErrorappears to be a helper that constructs errors — the convention flags helpers whose only behavior is wrapping arguments into a new error instance, though this one might already exist in the codebase. Let me pull the actual files to verify the exact patterns and check what conventions are already established in the repo. Looking at the existing patterns in this file, I see thatProviderTaskStopErrorand similar error types usecause: Schema.optional(Schema.Defect())but then assign string messages directly to thecausefield when handling unsupported cases. This is a pre-existing convention in the codebase, even thoughSchema.Defect()isn't really the right fit for modeling generic errors this way. The structural identification comes from the error tag itself plus the specific fields likethreadId,providerSessionId, andnativeTaskId, so the convention about identifying failures structurally is satisfied. Usingcauseas a string explanation rather than a real underlying failure is technically a mild violation of the rules, but since it's consistent with the surrounding module's approach, I'd lean toward not flagging it. I'm also noticing the inline use ofSchema.is(ProviderTaskStopError)at line 294, which follows the same pattern already established in the file with similar type guards. TheProviderTurnControlServiceV2Shapeinterface is pre-existing and the PR only extends it withstopTask, so I won't flag the standalone shape definition even though convention prefers inline service interfaces. Moving toClaudeAdapterV2.ts, I'm noticing it throws a plainErrorinsideEffect.tryPromisefor the "runtime doesn't expose stopTask" case, which then gets caught and wrapped with that manufactured error as the cause — this violates the convention against creating errors just to populate the cause field. A better approach would be to check whether the method exists before entering the effect, then fail directly with the typed error if it's missing, rather than throwing and catching. But I need to check whetherClaudeAgentSdkQueryRunnerErrorrequires a cause parameter in its definition. I'm noticing thatClaudeAgentSdkQueryRunnerErrorrequires acauseparameter, but the code is manufacturing anErrorjust to satisfy this requirement when there's no actual underlying failure—it's really just a validation or domain error. This seems like a minor violation of the convention that you shouldn't create errors artificially just to populate thecausefield. The alternative would be to pass a string directly as the cause, sinceSchema.Defect()accepts any value, which would align with howProviderTurnControlErrorhandles it. So the suggestion is to instantiate the typed error directly without wrapping it in a try-catch. I'm weighing whether this is a clear enough convention violation to fail the check or if it just warrants an inline comment—it's borderline since the manufactured error is being used as a control-flow signal rather than representing a genuine underlying failure. Looking at the bigger picture, I should focus on more impactful issues. The optionalstopTaskmethod follows the allowed "optional-service" pattern. ButProviderTaskStopErroris worth examining more closely—it usescauseto hold a human-readable string without deriving amessagegetter from structured attributes, which goes against the convention of defining service failures with proper schema and derived messages. That said, the same pattern already exists in the module withProviderTurnControlError, so flagging this as a new issue would be inconsistent. A more concrete suggestion: the module definesisProviderTurnControlErroras a module-level const but uses inlineSchema.is(ProviderTaskStopError)elsewhere. The convention calls for exporting direct schema predicates likeexport const isProviderTaskStopError = Schema.is(ProviderTaskStopError), which would be a small but real improvement. I'm also checking whether the code usesEffect.catchTagsfor known tagged failures — in this case it'smapErrorfor translation, which is fine. The imports look correct across the touched files, with proper Effect module imports and test utilities in place. Now I'm looking at the specific implementations:Orchestrator.subagentStopusesemitandRefcorrectly,EffectWorker.tsaccessesproviderTurnControlfrom the environment as expected, and the pure helpers in the orchestration state file don't need Effect at all. So far the main issue I'm tracking is the manufacturedErrorinClaudeAdapterV2.stopTask. Checking EffectWorker.ts to confirm how providerTurnControl is acquired and that ProviderTaskStopError is properly exported and handled. Looking at ClaudeAdapterV2's stopTask implementation, which wraps errors in ProviderAdapterProtocolError with a descriptive message about the failed stop operation. I should scan through the other places where ProviderAdapterProtocolError gets instantiated to verify this pattern holds consistently. I'm weighing whether these findings are significant enough to report. The linting rule says to only flag concrete violations that were introduced or changed in the pull request, and I'm reconsidering whether the manufactured Error case in ClaudeAdapterV2 actually violates the convention about not creating Errors just to populate the cause field. Looking at the stopTask block more carefully, the throw statement is definitely within the diff lines, so I can comment on it inline. The issue is that an Error gets thrown inside the try block of Effect.tryPromise, which automatically wraps it in ClaudeAgentSdkQueryRunnerError with the original Error as the cause—that's exactly the pattern the convention warns against. I think this is a legitimate finding worth flagging, and the fix would be to fail with the typed error directly instead. For the second finding about inlining the Schema.is predicate check, I'm less certain whether this rises to the level of a concrete violation or if it's just an optional style preference. The convention does mention exporting direct schema predicates, and the file already hoists a similar predicate, but I need to think through whether this is actually a violation or just a suggestion. Restructuring the code to use Effect.suspend would let them return a Promise properly within the try callback, which aligns with the convention. I'll suggest this as an inline diff and then decide on the final state—the check defaults to failure when findings are present, though I'm weighing whether this particular issue is severe enough to warrant that, since it's more of a pragmatic trade-off than a clear violation. I'll post both findings since the convention explicitly requires exporting schema predicates. Now I need to identify the exact line numbers in the diff for inline comments — the stopTask function spans lines 597-625 in ClaudeAdapterV2.ts, so I'll target the throw statement around lines 606-611, and then locate the relevant section in ProviderTurnControlService.ts. I'm adding an inline comment on the ClaudeAdapterV2.ts file pointing out that throwing a plain Error just to have tryPromise wrap it is unnecessary—instead, I should fail directly with the typed ClaudeAgentSdkQueryRunnerError and pass the defect as the cause, avoiding the extra wrapping layer. Restructuring the error handling...
1. modify_pr — Effect service conventions review of the new stopTask surface (adapter runtime, ProviderTurnControlServiceV2, worker effect). Two findings, both in the error-modelling rules; the rest of the touched Effect code (namespace imports, layer/dependency acquisition, Layer.succeed only in test seams, no ManagedRuntime/runPromise outside boundaries) looks consistent with the conventions.
Agent Credits: 120 credits