Build a Coding-Agent Service That Takes Requests from Chat and Issue Trackers

## Give Each Runtime Role One Job and Keep the Reviewer Read-Only Give each runtime role one clear responsibility: - a main coding-agent graph creates a fresh agent per thread while durable state remains in the thread sandbox and metadata; - a reviewer graph performs read-only code review through a findings model and a dedicated publishing action, without mutation, commit, push, or review-opening tools; - an analyzer graph builds repository-specific review guidance in bootstrap and continual-learning modes, saving it through one dedicated tool; - a web application receives code-host, issue-tracker, and chat webhooks, resolves a stable thread, and starts or streams the corresponding graph run; - a dashboard owns sign-in, user profiles, team defaults, enabled repositories, review-style administration, and the thread API used by the interface. Serve analyzer procedures as versioned, read-only virtual skills instead of copying them into each sandbox. Register scheduled continual refinement only after bootstrap completes. Keep all graph entry points and application routes in one runtime manifest, while allowing a full development runtime and a narrower web-only process. ## Pick One Set of Dev Tools and Run the Smallest Test First Declare one dependency manager, test runner, linter, formatter, type checker, minimum language version, and deployed runtime version. The repository must remain valid for both the supported minimum and any newer version pinned by deployment metadata. Provide documented commands for: 1. installing development dependencies; 2. starting the complete graph and web runtime; 3. starting only the web application; 4. running the full unit-test directory; 5. running one test file or test case; 6. checking lint and formatting without mutation; 7. applying the formatter and safe automatic fixes; 8. type-checking production and test code. Use unit tests by default. Reserve a dedicated directory for integration tests, and make an absent integration suite an explicit no-op rather than an ambiguous failure. During development, run a single test or the smallest relevant suite before broad repository checks. ## Keep One Sandbox per Thread and Recreate It When It Breaks Keep an in-process sandbox cache keyed by thread identifier, and persist the sandbox identifier in thread metadata. Handle lifecycle state explicitly: 1. If a sandbox is cached, probe it; recreate it when the probe fails, and refresh its authenticated network proxy when healthy. 2. If metadata contains a creation sentinel but no cached sandbox, clear the stale sentinel before creating a replacement. 3. If no sandbox exists, write the creation sentinel, create the sandbox, and replace the sentinel with the real identifier. 4. If metadata has an identifier but the process cache is empty, reconnect and fall back to recreation when reconnection fails. For providers that support an authenticated proxy, obtain a fresh short-lived installation credential on every creation or refresh. Let the proxy inject code-host and API authentication so sandbox commands can use a harmless placeholder instead of storing the real credential. Providers without that facility must skip the proxy path explicitly. Reapply the automation identity configuration on every run. Reused or reconnected environments can lose global settings, and downstream deployment checks may reject commits whose author identity is not recognized. ## Run the Middleware Around Model Calls in a Fixed Order Run middleware around model calls in a deliberate sequence: 1. sanitize and normalize tool inputs; 2. cap model calls and end gracefully at the limit; 3. convert tool exceptions into tool messages; 4. append applicable ancestor instructions to file reads once per run; 5. inject issue or chat messages that arrived mid-run before the next model call; 6. update external assistant-status indicators; 7. replace an empty model response with a synthetic continuation or completion-confirmation tool call; 8. notify the source channel when the overall step limit is reached; 9. trip a circuit breaker after repeated sandbox failures; 10. add model fallback only when a distinct fallback is configured; 11. remove malformed provider-specific reasoning blocks immediately before provider calls. Pair the system instruction to keep acting with the empty-response guard so work does not end silently. Keep reviewer middleware leaner when it does not need scoped file instructions, message-queue injection, fallback, or sandbox recovery. The existence of an unused middleware component does not make it active; register new middleware explicitly at the correct position. ## Give Each Role Only the Tools It Needs Maintain a small flat registry of custom tools. The main agent may receive approved network requests, search, issue-tracker actions, review requests, wakeups, and chat replies. The reviewer should receive only read-oriented network tools plus finding creation, finding updates, finding listing, and review publication. The analyzer should receive only the action needed to save review guidance. Let the agent framework provide generic file, shell, search, task, and planning primitives. Do not duplicate those tools in the custom registry. Do not rely on an after-agent safety net to publish work. The agent workflow must explicitly perform each authorized commit, push, review opening or update, and source-channel reply. A read-only reviewer must never inherit these mutation capabilities. ## Choose the Model in a Set Order and Encrypt Credentials Resolve the model and reasoning effort for every run in this order: 1. per-thread configuration supplied by the triggering event or interface; 2. the resolved user's profile override; 3. the team default. Centralize supported model identifiers, effort rules, provider arguments, construction, and fallback selection. Keep behavior flags, such as permission to create reviews automatically, in the user profile rather than scattering them through webhook code. Encrypt user authorization credentials at rest and cache them only in process during a run. When a user credential is unavailable, fall back to a short-lived application installation credential. Use the same application credential to configure an authenticated sandbox proxy, but never persist the raw credential inside the sandbox. Verify webhook authenticity before routing an event. Keep code-host signature checks, chat verification, issue-tracker verification, and dashboard sign-in handling in their owning modules. ## Send Follow-Up Messages Back to the Same Thread and Sandbox Derive stable thread identifiers from the external conversation identity so every follow-up on the same issue, chat thread, branch, or review returns to the same agent state and sandbox. Give reviewer runs a separate deterministic namespace and mark their thread kind in metadata. When messages arrive during a run, place them in the thread queue and inject them before the next model call. This preserves continuity without abandoning the current run or creating a competing agent. Keep status updates aligned with model-call boundaries so external users can distinguish active work, completion, and step-limit termination. ## Run Automatic CI Repair Only When It Is Switched On An automated repair flow may react to failed checks, merge conflicts, or actionable feedback on an agent-authored review. Locate the originating thread through durable review metadata, then dispatch a confidence-gated repair run on the main agent graph. Require layered enablement: - a per-user automation flag; - repository opt-in; - a per-review on-or-off override. Centralize skip rules for failures already present on the base branch, human-authored commits, repeated processing of the same head revision, batching while another repair run is active, and a hard loop limit. Use a periodic monitor only as a fallback that sweeps open agent-authored reviews for missed events. ## Add New Providers and Tools in Their Registries and Keep the Code Async Add a sandbox provider in its integration module and register it in the provider factory map. Add a custom tool in the tool package, export it once, and include it only in the role-specific tool list that needs it. Add middleware in its own module, export it, and place it deliberately in the ordered stack. Add dashboard endpoints to the mounted router and new graphs to the runtime manifest. Keep an asynchronous-only application asynchronous. Do not build parallel synchronous implementations. Omit the synchronous method when the interface permits; when an abstract contract requires it, provide only a minimal method that raises an unsupported-operation error. Default to unit tests, use the dedicated integration-test area for true integrations, and keep comments rare. Comments should explain a non-obvious reason or ordering constraint, not restate the implementation.