Repository navigation
Effect Service Conventions: 1 issue found
Reviewed the new/changed Effect service code in this PR against the service conventions.
Finding
apps/server/src/scheduledTasks/ScheduledTaskService.ts— the newly createdScheduledTaskServicedefines a standaloneScheduledTaskServiceShapeinterface and passes it into theContext.Servicegeneric. The convention requires the service interface be defined inline in theContext.Servicedeclaration and referenced asScheduledTaskService["Service"]. An inline review comment with the suggested fix has been posted.
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 examined
apps/server/src/scheduledTasks/ScheduledTaskService.ts(new service)apps/server/src/scheduledTasks/Schedule.ts(pure helper module — namespaced Effect imports, no service definition)apps/server/src/mcp/OrchestratorMcpService.ts,apps/server/src/mcp/toolkits/orchestrator/*,apps/server/src/ws.ts,apps/server/src/orchestration-v2/runtimeLayer.ts(consumers)packages/contracts/src/scheduledTask.ts,orchestratorMcp.ts,rpc.ts(schemas/errors)
Notes / not flagged
packages/contracts/src/scheduledTask.tscorrectly modelsScheduledTaskErrorwithSchema.TaggedErrorClass, structuredtaskId/causeattributes, and preserves the underlying failure ascause.apps/server/src/ws.tsimports the service as a namespace (import * as ScheduledTasks) and usesScheduledTasks.ScheduledTaskService, matching the convention.- The
import { layer as scheduledTaskServiceLayer }alias inruntimeLayer.tsfollows that file's established local pattern for every sibling layer import; treated as consistent with existing layer-wiring rather than a newly introduced deviation, and not flagged to avoid demanding unrelated repo-wide cleanup. - The
ServiceShapeinterface pattern is used pervasively across the existing codebase; per the check's guidance that these instructions are authoritative when older code differs, the finding applies only to the service newly created in this PR.
🔍 Agent activity — 1 tool call
💭 Looking at the diff for the new
ScheduledTaskService.tsfile, I'm checking it against the Effect service conventions, particularly around how the service interface should be defined inline within theContext.Servicedeclaration. The issue I'm spotting is that the new service creates a standaloneScheduledTaskServiceShapeinterface, which violates the convention that says not to retain separateFooShapeorFooServiceShapetypes. The interface should be defined directly in theContext.Servicedeclaration instead. I noticeOrchestratorMcpServiceShapealready exists in the codebase, but that's pre-existing code being extended, not newly created, so it's legacy. TheScheduledTaskServiceShapebeing introduced here is a fresh violation of the pattern. There's also an import pattern issue inruntimeLayer.tswhere the new code usesimport { layer as scheduledTaskServiceLayer }to import the service layer. The convention flags this kind of aliasing that erases the module namespace at service boundaries, though I'm seeing this same pattern already established throughout the file with other layer imports. Looking at howScheduledTaskServiceis imported elsewhere—as a namespace import inws.tsbut as a direct named import inOrchestratorMcpService.ts—there's some inconsistency in how the service is being accessed across the codebase. The convention prefers namespace imports at service boundaries, but I need to determine whether importing just the service class by name constitutes a violation or if that's acceptable when accessing specific service members. The clearest violation I can identify is the standaloneScheduledTaskServiceShapeinterface. The convention explicitly states to define the service interface inline within theContext.Servicedeclaration rather than as a separate exported type. This is new code being introduced in the PR. I'm also noticing the file structure doesn't follow the canonical single-file order—there's no separatemakeexport, with construction logic instead inlined in theLayer.effectcall. The convention expects a realmakeexport when the module is complex enough to warrant it. I need to restructure the repo parameter as an object instead of its current form. I'm noticing that the newScheduledTaskServiceis keeping a separateScheduledTaskServiceShapeinterface instead of defining it inline within theContext.Servicedeclaration, which goes against the established pattern. Let me verify how the other services in the codebase handle this to ensure I'm applying the rule consistently. The*ServiceShapepattern is actually a widespread convention throughout the codebase used by dozens of services, not something introduced by this PR. Given the review criteria that focus on concrete violations within the changed scope rather than optional style preferences or existing legacy patterns, this doesn't constitute a reportable issue. The convention is explicit and the PR creates a new service, so by the customer's authoritative rules I should flag the standaloneScheduledTaskServiceShapeinterface as a violation. But I'm genuinely uncertain whether to report it given the entire codebase follows this pattern consistently—it feels like flagging the new code alone for matching what every existing service does could be a false positive that frustrates the customer, especially since these conventions might be aspirational target-state rather than current-state rules. I'll flag it anyway because the customer stated it deliberately and specifically, and they explicitly said to treat these as authoritative when older code differs. The error modeling also looks like it might violate the convention about deriving messages from structured attributes rather than storing unstructured message strings. The Shape interface is explicitly introduced in this PR's new file, and the convention is clear: define service interfaces inline in the Context.Service declaration rather than as standalone types. Even though the codebase widely uses this pattern, the customer's instruction to treat their conventions as authoritative when older code differs applies here. I should flag this violation with a precise inline comment and fail the check. I'm also noticing theimport { layer as scheduledTaskServiceLayer }pattern in the new file—this erases the module namespace, which the convention flags. But I need to verify whether this is a new addition in the PR or part of the existing pattern in that file. I'm noticing that ws.ts already uses proper namespace import syntax for ScheduledTasks, while runtimeLayer.ts uses an alias import following that file's local convention. The Shape interface is the clearest violation since it's explicitly called out in the convention guidelines, so I'll focus the review on that as the primary finding and mention the runtimeLayer alias as a secondary note since it matches the convention's literal example. I need to find the exact line number in the runtimeLayer file where that import was added so I can target it with the second inline comment. I'm seeing that line 42 follows the same import aliasing pattern as lines 38-41, so flagging it alone would be inconsistent with the file's established convention. Since the guidelines say not to demand unrelated repository-wide cleanup, I'll skip flagging this particular import. Now I'm wrestling with the*ServiceShapeinterface pattern. It's used universally across the codebase—literally every service, including the two this new service depends on—but the customer's convention explicitly says to treat their instructions as authoritative when legacy code differs. They anticipated this exact situation and want new services to adopt the inline interface pattern instead. Since this PR creates a new service and the Shape interface is a convention-backed violation introduced in the new code, I should flag it. The runtimeLayer import stays unflagged because it's the dominant local pattern here. I'll draft a review comment explaining the fix: inline the interface definition directly in theContext.Servicegeneric and update all five usages accordingly. Since this spans multiple locations, I can't use an inline suggestion—I'll just describe the change clearly in the comment on the relevant lines. Now I need to submit the review with a failure state since there's a violation, and include the inline comment positioned at lines 67–85 on the right side.
1. modify_pr — One Effect service convention issue in the newly added ScheduledTaskService. See the inline comment.
💭 Generating check run result JSON...
Agent Credits: 106 credits