Packages

@argus/worker

The agent runtime — everything between "job consumed" and "threads posted" lives here. It exists as one package so the entire review pipeline can be run and tested offline: every external dependency (AdoClient, RulesSource, CheckoutProvider, ModelRunner, stores) is injected behind a @argus/shared or local port interface.

Place in the system

The largest consumer in the graph: depends on @argus/queue (consume loop), @argus/rules (rules resolution + prompt assembly), @argus/ado (reads and writes), @argus/mcp-ado (the tool surface handed to the agent), and @argus/db ports for state. bin/argus-worker.ts is its composition root.

The per-job pipeline

flowchart TD
  job["job from queue<br/>(per-PR session)"] --> sess["upsert reviewer.pr_session<br/>load thread state"]
  sess --> rules["resolve rules<br/>registry packs (routed, default fallback)<br/>+ repo-discovered instruction files"]
  rules --> co["ephemeral read-only checkout<br/>of the PR merge commit"]
  co --> tier{"tier selection<br/>size ≤ threshold and<br/>no risky path?"}
  tier -- yes --> single["single-shot runner call"]
  tier -- no --> agentic["full agentic run<br/>(Agent SDK over the checkout)"]
  single --> validate["validate FindingsOutput<br/>zod, closed enums"]
  agentic --> validate
  validate --> dedup["dedup via findingKey<br/>+ findings / comment-rate /<br/>reply-depth / token caps"]
  dedup --> post["ADO writes via the<br/>five-tool MCP surface"]
  post --> audit["audit: reviewer.event_log<br/>model, prompt_sha, tokens"]

Figure 1 · The per-job pipeline — session to audit, with tier selection choosing between one model call and a full agentic run.

Job types branch inside the same skeleton: review.full reviews the scoped diff, review.incremental only the delta since last_reviewed_sha, thread.reply rebuilds that thread's history and answers in place, mention.answer answers a question with checkout access.

Key exports

createJobHandler() + consumeLoop() (pipeline.ts) — the pipeline above, plus WorkerLimits (limitsFromConfig()): findings cap, hourly comment cap, reply depth, token ceilings.
chooseTier(), isExcludedPath(), touchedPaths() (tier.ts) — single-shot vs agentic from diff size (REVIEW_TIER_MAX_CHANGED_LINES) and RISKY_PATH_GLOBS.
AgentSdkRunner — the Claude Agent SDK harness (fails jobs cleanly when no inference endpoint is configured); MockRunner — deterministic offline runner reading argus.mock.json from the fixture workspace.
LocalGitCheckout / FixtureCheckout (checkout.ts) — credential-free clone URL vs fixture copy (CHECKOUT_MODE). Fetch auth is minted per checkout from the same Entra/PAT credentials as the REST client and passed to git as an ephemeral http.extraHeader — never persisted to the workspace, scrubbed from errors.
assembleSystemPrompt() (prompt.ts) and in-memory WorkerStores for DATABASE_URL=memory.

How it's tested

pipeline.test.ts runs whole jobs against fakes (fake ADO, fixture checkout, mock runner, in-memory stores): finding dedup, cap enforcement, incremental deltas, thread replies, bow-out. tier.test.ts, checkout.test.ts, mockRunner.test.ts, and agentSdkRunner.test.ts cover the pieces — all offline.

← queue ado →