solidity-argus 0.1.8 → 0.2.0

package/src/hooks/recon-context-builder.ts

@@ -0,0 +1,66 @@
+import type { ProjectConfig } from "../utils/project-detector"
+import type { DependencyRisk } from "../utils/dependency-scanner"
+import type { AuditArtifact } from "../utils/audit-artifact-detector"
+
+export interface ReconContext {
+  projectConfig: ProjectConfig | null
+  dependencyRisks: DependencyRisk[]
+  auditArtifacts: AuditArtifact[]
+}
+
+/**
+ * Builds an XML-like reconnaissance context block from project data.
+ * Returns null if no data is available (all fields empty/null).
+ *
+ * The block is injected into compaction output so Argus agents retain
+ * project intelligence across context window compressions.
+ */
+export function buildReconContextBlock(recon: ReconContext): string | null {
+  if (
+    !recon.projectConfig &&
+    recon.dependencyRisks.length === 0 &&
+    recon.auditArtifacts.length === 0
+  ) {
+    return null
+  }
+
+  const lines: string[] = ["<argus-recon>"]
+
+  if (recon.projectConfig) {
+    const frameworks: string[] = []
+    if (recon.projectConfig.hasFoundry) frameworks.push("Foundry")
+    if (recon.projectConfig.hasHardhat) frameworks.push("Hardhat")
+    if (frameworks.length > 0) {
+      lines.push(`Framework: ${frameworks.join(", ")}`)
+    }
+    if (recon.projectConfig.optimizer) {
+      lines.push(`Optimizer: runs=${recon.projectConfig.optimizer.runs}`)
+    }
+    if (recon.projectConfig.evmVersion) {
+      lines.push(`EVM Version: ${recon.projectConfig.evmVersion}`)
+    }
+    if (recon.projectConfig.isUpgradeable) {
+      lines.push(`Upgradeable: yes`)
+    }
+    if (recon.projectConfig.profiles && recon.projectConfig.profiles.length > 0) {
+      lines.push(`Profiles: ${recon.projectConfig.profiles.join(", ")}`)
+    }
+  }
+
+  if (recon.dependencyRisks.length > 0) {
+    lines.push("Dependency Risks:")
+    for (const risk of recon.dependencyRisks.slice(0, 5)) {
+      lines.push(`  - ${risk.package}@${risk.version}: ${risk.risk}`)
+    }
+  }
+
+  if (recon.auditArtifacts.length > 0) {
+    lines.push("Existing Audit Artifacts:")
+    for (const artifact of recon.auditArtifacts.slice(0, 5)) {
+      lines.push(`  - ${artifact.type}: ${artifact.path}`)
+    }
+  }
+
+  lines.push("</argus-recon>")
+  return lines.join("\n")
+}

package/src/hooks/safe-create-hook.ts

@@ -1,3 +1,5 @@
+import { createLogger } from "../shared/logger"
+
 export function safeCreateHook<T>(
   factory: () => T,
   hookName: string
@@ -5,11 +7,8 @@ export function safeCreateHook<T>(
   try {
     return factory();
   } catch (error) {
-    console.error(
-      `[argus-hook-error] Failed to create hook "${hookName}": ${
-        error instanceof Error ? error.message : String(error)
-      }`
-    );
+    const logger = createLogger()
+    logger.error(`Failed to create hook "${hookName}": ${error instanceof Error ? error.message : String(error)}`)
     return undefined;
   }
 }

package/src/hooks/system-prompt-hook.ts

@@ -0,0 +1,128 @@
+import type { AuditState, FindingSeverity } from "../state/types"
+
+const DEFAULT_TOKEN_BUDGET = 2000
+const TOKENS_PER_CHAR = 4
+
+export interface SystemPromptHookDeps {
+  getAuditState: () => AuditState | null
+  getAgentForSession: (sessionID: string) => string | undefined
+  isArgusAgent: (sessionID: string) => boolean
+  getContextPressure?: (systemText: string) => number
+  getTokenBudget?: (agent: string, contextPressure: number) => number
+  getEnforcerReminder?: (state: AuditState) => string | null
+  getReconBlock?: () => string | null
+}
+
+const FALLBACK_DIRECTIVES: Record<string, string> = {
+  slither:
+    "DO NOT re-attempt argus_slither_analyze. Use `argus_analyze_contract` and `argus_check_patterns` instead. Note limitation in report.",
+  forge:
+    "DO NOT re-attempt argus_forge_test or argus_forge_fuzz. Verify findings via manual code tracing. Note limitation in report.",
+  solodit:
+    "DO NOT re-attempt argus_solodit_search. Use `argus_check_patterns` with local rules. Note limitation in report.",
+}
+
+export function buildFallbackDirectives(unavailableTools: string[]): string[] {
+  const directives: string[] = []
+  for (const tool of unavailableTools) {
+    const directive = FALLBACK_DIRECTIVES[tool]
+    if (directive) directives.push(directive)
+  }
+  return directives
+}
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / TOKENS_PER_CHAR)
+}
+
+export function buildDynamicContext(
+  auditState: AuditState,
+  agent: string,
+  tokenBudget: number = DEFAULT_TOKEN_BUDGET,
+): string {
+  const severityCounts: Record<FindingSeverity, number> = {
+    Critical: 0,
+    High: 0,
+    Medium: 0,
+    Low: 0,
+    Informational: 0,
+  }
+
+  for (const finding of auditState.findings) {
+    severityCounts[finding.severity]++
+  }
+
+  const tools = auditState.toolsExecuted.map((tool) => tool.tool).join(", ") || "none"
+  const unavailable = auditState.unavailableTools ?? []
+  const lines: string[] = [
+    `<argus-context agent="${agent}">`,
+    `Phase: ${auditState.currentPhase}`,
+    `Contracts: ${auditState.contractsReviewed.length} reviewed`,
+    `Findings: Critical=${severityCounts.Critical} High=${severityCounts.High} Medium=${severityCounts.Medium} Low=${severityCounts.Low} Info=${severityCounts.Informational}`,
+    `Tools: ${tools}`,
+  ]
+
+  if (unavailable.length > 0) {
+    lines.push(`Unavailable: ${unavailable.join(", ")}`)
+    lines.push(...buildFallbackDirectives(unavailable))
+  }
+
+  lines.push("</argus-context>")
+
+  let summary = lines.join("\n")
+
+  if (estimateTokens(summary) > tokenBudget) {
+    summary = [
+      `<argus-context agent="${agent}">`,
+      `Phase: ${auditState.currentPhase} | Findings: ${auditState.findings.length} | Contracts: ${auditState.contractsReviewed.length}`,
+      "</argus-context>",
+    ].join("\n")
+  }
+
+  return summary
+}
+
+export function createSystemPromptHook(deps: SystemPromptHookDeps) {
+  return async (
+    input: { sessionID?: string; model: unknown },
+    output: { system: string[] },
+  ): Promise<void> => {
+    if (!input.sessionID) {
+      return
+    }
+
+    if (!deps.isArgusAgent(input.sessionID)) {
+      return
+    }
+
+    const auditState = deps.getAuditState()
+    if (!auditState) {
+      return
+    }
+
+    const agent = deps.getAgentForSession(input.sessionID)
+    if (!agent) {
+      return
+    }
+
+    const currentSystem = output.system.join("\n")
+    const pressure = deps.getContextPressure?.(currentSystem) ?? 0
+    const budget = deps.getTokenBudget?.(agent, pressure) ?? DEFAULT_TOKEN_BUDGET
+
+    output.system.push(buildDynamicContext(auditState, agent, budget))
+
+    if (deps.getReconBlock) {
+      const reconBlock = deps.getReconBlock()
+      if (reconBlock && estimateTokens(reconBlock) <= budget) {
+        output.system.push(reconBlock)
+      }
+    }
+
+    if (agent === "argus" && deps.getEnforcerReminder) {
+      const reminder = deps.getEnforcerReminder(auditState)
+      if (reminder) {
+        output.system.push(reminder)
+      }
+    }
+  }
+}

package/src/hooks/tool-tracking-hook.ts

@@ -1,4 +1,4 @@
-import type { AuditState, FindingSeverity } from "../state/types"
+import type { AuditState, FindingSeverity, FuzzCounterexample, SoloditResult } from "../state/types"
 import type { FindingStore } from "../state/finding-store"
 import { createFindingStore } from "../state/finding-store"
 
@@ -166,16 +166,91 @@ function processContractAnalyzerResult(
   }
 }
 
+function processFuzzResult(
+  parsed: Record<string, unknown>,
+  state: AuditState
+): void {
+  const counterexamples = parsed.counterexamples
+  if (!Array.isArray(counterexamples) || counterexamples.length === 0) return
+
+  const totalRuns =
+    typeof parsed.totalRuns === "number" ? parsed.totalRuns : 0
+
+  state.fuzzCounterexamples ??= []
+
+  for (const raw of counterexamples) {
+    const ce = toRecord(raw)
+    if (!ce) continue
+
+    const testName = ce.testName
+    if (typeof testName !== "string") continue
+
+    const rawInputs = toRecord(ce.inputs)
+    const inputs = rawInputs ? Object.values(rawInputs).map(String) : []
+
+    const entry: FuzzCounterexample = {
+      testName,
+      inputs,
+      runs: totalRuns,
+      timestamp: Date.now(),
+    }
+
+    if (typeof ce.revertReason === "string") {
+      entry.revertReason = ce.revertReason
+    }
+
+    state.fuzzCounterexamples.push(entry)
+  }
+}
+
+function processSoloditResult(
+  parsed: Record<string, unknown>,
+  state: AuditState
+): void {
+  const query = typeof parsed.query === "string" ? parsed.query : ""
+  const results = Array.isArray(parsed.results) ? parsed.results : []
+  const totalFound =
+    typeof parsed.totalFound === "number" ? parsed.totalFound : results.length
+
+  const topResults: SoloditResult["topResults"] = results
+    .slice(0, 5)
+    .map((raw) => {
+      const r = toRecord(raw)
+      return {
+        title: typeof r?.title === "string" ? r.title : "",
+        severity: typeof r?.severity === "string" ? r.severity : "",
+        url: typeof r?.url === "string" ? r.url : "",
+        protocol: typeof r?.protocol === "string" ? r.protocol : "",
+      }
+    })
+
+  state.soloditResults ??= []
+  state.soloditResults.push({
+    query,
+    timestamp: Date.now(),
+    resultCount: totalFound,
+    topResults,
+  })
+}
+
+/**
+ * Records a tool execution in the audit state.
+ *
+ * Multiple entries per tool name are allowed — if the same tool runs multiple times
+ * (e.g., argus_slither_analyze on different targets), each execution is recorded
+ * with its own findingsCount.
+ *
+ * Timing limitation: startTime and endTime are both set to Date.now() because this
+ * hook fires in the tool.execute.after phase, after execution has already completed.
+ * We cannot capture the actual start time. This is a known limitation of the hook
+ * architecture. For accurate timing, the hook would need to fire in tool.execute.before
+ * and tool.execute.after phases separately.
+ */
 function recordToolExecution(
   state: AuditState,
   toolName: string,
   findingsCount: number
 ): void {
-  const alreadyRecorded = state.toolsExecuted.some(
-    (execution) => execution.tool === toolName
-  )
-  if (alreadyRecorded) return
-
   const now = Date.now()
   state.toolsExecuted.push({
     tool: toolName,
@@ -243,9 +318,13 @@ export function createToolTrackingHook(
       case "argus_analyze_contract":
         processContractAnalyzerResult(record, auditState)
         break
+      case "argus_solodit_search":
+        processSoloditResult(record, auditState)
+        break
       case "argus_forge_test":
+        break
       case "argus_forge_fuzz":
-        // No findings to extract — counterexamples are informational
+        processFuzzResult(record, auditState)
         break
     }
 

package/src/index.ts

@@ -5,8 +5,19 @@ import { createTools } from "./create-tools"
 import { createHooks } from "./create-hooks"
 import { createManagers } from "./create-managers"
 import { createPluginInterface } from "./plugin-interface"
+import { checkSoloditHealth } from "./utils/solodit-health"
+import { createLogger } from "./shared/logger"
+
+async function startSoloditMcp(port: number): Promise<void> {
+  const logger = createLogger()
+
+  // Health check before spawn: if already reachable, skip spawn
+  const health = await checkSoloditHealth(port, true)
+  if (health.reachable) {
+    logger.debug(`Solodit MCP already running on port ${port} — skipping spawn`)
+    return
+  }
 
-function startSoloditMcp(port: number): void {
   const child = Bun.spawn(["npx", "-y", "@lyuboslavlyubenov/solodit-mcp"], {
     stdin: "ignore",
     stdout: "ignore",
@@ -14,6 +25,16 @@ function startSoloditMcp(port: number): void {
     env: { ...process.env, PORT: String(port) },
   })
   child.unref()
+
+  // Health check after spawn: wait 2s, then ping
+  setTimeout(async () => {
+    const health = await checkSoloditHealth(port, true)
+    if (!health.reachable) {
+      logger.debug(`Solodit MCP not yet reachable on port ${port} — will retry on first use`)
+    } else {
+      logger.debug(`Solodit MCP healthy on port ${port}`)
+    }
+  }, 2000)
 }
 
 const ArgusPlugin: Plugin = async (ctx) => {
@@ -21,6 +42,8 @@ const ArgusPlugin: Plugin = async (ctx) => {
   const config = loadArgusConfig(projectDir)
 
   if (config.solodit?.enabled !== false) {
+    // Fire-and-forget: startSoloditMcp is now async but we don't await
+    // to avoid blocking plugin initialization
     startSoloditMcp(config.solodit?.port ?? 3000)
   }
 

package/src/knowledge/retry.ts

@@ -0,0 +1,53 @@
+export interface RetryOptions<T> {
+  maxAttempts: number;
+  baseDelayMs: number;
+  shouldRetry: (error: unknown) => boolean;
+  onRetry?: (attempt: number, error: unknown) => void;
+  _valueType?: T;
+}
+
+export interface RetryResult<T> {
+  success: boolean;
+  value?: T;
+  error?: unknown;
+  attempts: number;
+}
+
+function sleep(delayMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions<T>
+): Promise<RetryResult<T>> {
+  const maxAttempts = options.maxAttempts > 0 ? options.maxAttempts : 1;
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const value = await fn();
+      return { success: true, value, attempts: attempt };
+    } catch (error) {
+      lastError = error;
+      const canRetry = attempt < maxAttempts && options.shouldRetry(error);
+
+      if (!canRetry) {
+        return { success: false, error, attempts: attempt };
+      }
+
+      if (options.onRetry) {
+        options.onRetry(attempt, error);
+      }
+
+      const delay = options.baseDelayMs * 2 ** (attempt - 1);
+      await sleep(delay);
+    }
+  }
+
+  return {
+    success: false,
+    error: lastError,
+    attempts: maxAttempts,
+  };
+}

package/src/knowledge/scvd-client.ts

@@ -150,6 +150,24 @@ function parseStats(raw: unknown): ScvdStats {
   };
 }
 
+export class ScvdNetworkError extends Error {
+  override readonly name = "ScvdNetworkError" as const;
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class ScvdApiError extends Error {
+  override readonly name = "ScvdApiError" as const;
+  readonly httpStatus: number;
+
+  constructor(httpStatus: number, message?: string) {
+    super(message ?? `SCVD API error: HTTP ${httpStatus}`);
+    this.httpStatus = httpStatus;
+  }
+}
+
 export class ScvdClient {
   private readonly baseUrl: string;
   private readonly signal?: AbortSignal;
@@ -167,11 +185,14 @@ export class ScvdClient {
       response = await fetch(url, { signal: this.signal });
     } catch (error) {
       const message = error instanceof Error ? error.message : "unknown network error";
-      throw new Error(`Failed to fetch SCVD stats from ${url}: ${message}`);
+      throw new ScvdNetworkError(`Failed to fetch SCVD stats from ${url}: ${message}`);
     }
 
     if (!response.ok) {
-      throw new Error(`Failed to fetch SCVD stats from ${url}: HTTP ${response.status}`);
+      throw new ScvdApiError(
+        response.status,
+        `Failed to fetch SCVD stats from ${url}: HTTP ${response.status}`
+      );
     }
 
     const body = (await response.json()) as unknown;
@@ -198,17 +219,23 @@ export class ScvdClient {
     const query = searchParams.toString();
     const url = `${this.baseUrl}/findings${query.length > 0 ? `?${query}` : ""}`;
 
+    let response: Response;
     try {
-      const response = await fetch(url, { signal: this.signal });
-      if (!response.ok) {
-        return [];
-      }
+      response = await fetch(url, { signal: this.signal });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "unknown network error";
+      throw new ScvdNetworkError(`Failed to fetch SCVD findings from ${url}: ${message}`);
+    }
 
-      const body = (await response.json()) as unknown;
-      return parseFindings(body);
-    } catch {
-      return []; // network error — treat as empty page
+    if (!response.ok) {
+      throw new ScvdApiError(
+        response.status,
+        `SCVD API error: HTTP ${response.status} for ${url}`
+      );
     }
+
+    const body = (await response.json()) as unknown;
+    return parseFindings(body);
   }
 
   async fetchAllFindings(onProgress?: (count: number) => void): Promise<ScvdFinding[]> {

package/src/knowledge/scvd-errors.ts

@@ -0,0 +1,89 @@
+export type SyncError = {
+  status: "error";
+  success: false;
+  reason: "network" | "api" | "parse";
+  message: string;
+  error: string;
+  httpStatus?: number;
+  newFindings: 0;
+  totalIndexed: 0;
+  lastSync: string;
+  attempts?: number;
+};
+
+export type SyncSuccess = {
+  status: "success";
+  success: true;
+  newFindings: number;
+  totalIndexed: number;
+  lastSync: string;
+  error?: undefined;
+  attempts?: number;
+};
+
+export type SyncStale = {
+  status: "stale";
+  success: false;
+  newFindings: 0;
+  totalIndexed: 0;
+  lastSync: string;
+  error?: undefined;
+  daysSinceSync: number;
+  attempts?: number;
+};
+
+export type SyncOutcome = SyncSuccess | SyncError | SyncStale;
+
+export function createNetworkError(message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "network",
+    message,
+    error: message,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  };
+}
+
+export function createApiError(httpStatus: number, message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "api",
+    message,
+    error: message,
+    httpStatus,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  };
+}
+
+export function createParseError(message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "parse",
+    message,
+    error: message,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  };
+}
+
+export function createSyncSuccess(
+  data: Omit<SyncSuccess, "status" | "success" | "error"> & { attempts?: number }
+): SyncSuccess {
+  return {
+    status: "success",
+    success: true,
+    ...data,
+  };
+}
+
+export function isRetryableError(outcome: SyncOutcome): boolean {
+  return outcome.status === "error" && outcome.reason === "network";
+}

package/src/knowledge/scvd-index.ts

@@ -10,15 +10,42 @@ export interface ScvdIndexEntry {
   repoUrl: string;
 }
 
+export interface ScvdIndexMetadata {
+  lastSuccess: string | null;
+  lastAttempt: string | null;
+  errorCount: number;
+  lastError: string | null;
+  lastErrorReason: string | null;
+}
+
 export interface ScvdIndex {
   version: number;
   lastSync: string;
   totalFindings: number;
   entries: ScvdIndexEntry[];
+  metadata?: ScvdIndexMetadata;
 }
 
 const INDEX_VERSION = 1;
 const DEFAULT_LIMIT = 10;
+let syncInProgress = false;
+
+export function acquireSyncLock(): boolean {
+  if (syncInProgress) {
+    return false;
+  }
+
+  syncInProgress = true;
+  return true;
+}
+
+export function releaseSyncLock(): void {
+  syncInProgress = false;
+}
+
+export function isSyncLocked(): boolean {
+  return syncInProgress;
+}
 
 function normalizeKeywordInput(value: string): string[] {
   return value
@@ -96,8 +123,10 @@ export function searchIndex(
 }
 
 export async function saveIndex(index: ScvdIndex, filePath: string): Promise<void> {
-  const json = JSON.stringify(index, null, 2);
-  await Bun.write(filePath, json);
+  const tmpPath = `${filePath}.tmp.${Date.now()}`;
+  await Bun.write(tmpPath, JSON.stringify(index, null, 2));
+  const { renameSync } = await import("node:fs");
+  renameSync(tmpPath, filePath);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -142,6 +171,20 @@ function parseEntry(value: unknown): ScvdIndexEntry | null {
   };
 }
 
+function parseNullableString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function parseMetadata(raw: Record<string, unknown>): ScvdIndexMetadata {
+  return {
+    lastSuccess: parseNullableString(raw.lastSuccess),
+    lastAttempt: parseNullableString(raw.lastAttempt),
+    errorCount: typeof raw.errorCount === "number" ? raw.errorCount : 0,
+    lastError: parseNullableString(raw.lastError),
+    lastErrorReason: parseNullableString(raw.lastErrorReason),
+  };
+}
+
 export async function loadIndex(filePath: string): Promise<ScvdIndex | null> {
   const file = Bun.file(filePath);
   const exists = await file.exists();
@@ -174,10 +217,17 @@ export async function loadIndex(filePath: string): Promise<ScvdIndex | null> {
     .map(parseEntry)
     .filter((entry): entry is ScvdIndexEntry => entry !== null);
 
-  return {
+  const index: ScvdIndex = {
     version,
     lastSync,
     totalFindings,
     entries,
   };
+
+  const rawMetadata = raw.metadata;
+  if (isRecord(rawMetadata)) {
+    index.metadata = parseMetadata(rawMetadata);
+  }
+
+  return index;
 }