solidity-argus 0.1.8 → 0.3.0

package/src/features/persistent-state/audit-state-manager.ts

@@ -1,25 +1,25 @@
-import { mkdir, rename } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import type { AuditStateManager } from "../../managers/types";
-import { createAuditState } from "../../state/audit-state";
-import type { AuditState, PersistentAuditState } from "../../state/types";
-import { createLogger } from "../../shared/logger";
+import { mkdir, rename } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import type { AuditStateManager } from "../../managers/types"
+import { createLogger } from "../../shared/logger"
+import { createAuditState } from "../../state/audit-state"
+import type { AuditState, PersistentAuditState } from "../../state/types"
 
-const STATE_FILE_DIR = ".opencode";
-const STATE_FILE_NAME = "argus-state.json";
-const STATE_VERSION = "1";
+const STATE_FILE_DIR = ".opencode"
+const STATE_FILE_NAME = "argus-state.json"
+const STATE_VERSION = "2"
 
 function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
+  return typeof value === "object" && value !== null
 }
 
 function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((item) => typeof item === "string");
+  return Array.isArray(value) && value.every((item) => typeof item === "string")
 }
 
 function isAuditState(value: unknown): value is AuditState {
   if (!isObject(value)) {
-    return false;
+    return false
   }
 
   return (
@@ -31,84 +31,189 @@ function isAuditState(value: unknown): value is AuditState {
     typeof value.currentPhase === "string" &&
     isStringArray(value.scope) &&
     typeof value.startTime === "number"
-  );
+  )
 }
 
 function isPersistentAuditState(value: unknown): value is PersistentAuditState {
   if (!isAuditState(value) || !isObject(value)) {
-    return false;
+    return false
   }
 
+  const hasSupportedVersion = value.version === "1" || value.version === "2"
+
   return (
-    typeof value.savedAt === "number" &&
-    typeof value.version === "string" &&
-    typeof value.filePath === "string"
-  );
+    typeof value.savedAt === "number" && hasSupportedVersion && typeof value.filePath === "string"
+  )
+}
+
+export function createDebouncedSave(
+  saveState: (state: AuditState) => Promise<void>,
+  delayMs = 5_000,
+): {
+  save: (state: AuditState) => void
+  flush: () => Promise<void>
+} {
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let pendingState: AuditState | null = null
+
+  async function persistPendingState(): Promise<void> {
+    if (!pendingState) {
+      return
+    }
+
+    const stateToPersist = pendingState
+    pendingState = null
+
+    try {
+      await saveState(stateToPersist)
+    } catch {
+      createLogger().debug("Debounced state persistence failed")
+    }
+  }
+
+  return {
+    save(state: AuditState): void {
+      pendingState = state
+
+      if (timer) {
+        clearTimeout(timer)
+      }
+
+      timer = setTimeout(() => {
+        timer = null
+        void persistPendingState()
+      }, delayMs)
+    },
+    async flush(): Promise<void> {
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+
+      await persistPendingState()
+    },
+  }
 }
 
 export function createAuditStateManager(projectDir: string): AuditStateManager {
-  const logger = createLogger();
-  const stateFilePath = join(projectDir, STATE_FILE_DIR, STATE_FILE_NAME);
-  let currentState: AuditState = createAuditState(projectDir).state;
+  const logger = createLogger()
+  const stateFilePath = join(projectDir, STATE_FILE_DIR, STATE_FILE_NAME)
+  let currentState: AuditState = createAuditState(projectDir).state
 
   async function load(): Promise<AuditState | null> {
     try {
-      const file = Bun.file(stateFilePath);
+      const file = Bun.file(stateFilePath)
       if (!(await file.exists())) {
-        return null;
+        return null
       }
 
-      const content = await file.text();
+      const content = await file.text()
       if (!content.trim()) {
-        return null;
+        return null
       }
 
-      const parsed: unknown = JSON.parse(content);
+      const parsed: unknown = JSON.parse(content)
       if (!isPersistentAuditState(parsed)) {
-        logger.warn("Persistent audit state is invalid, ignoring", stateFilePath);
-        return null;
+        logger.warn("Persistent audit state is invalid, ignoring", stateFilePath)
+        return null
       }
 
-      const { savedAt: _savedAt, version: _version, filePath: _filePath, ...state } = parsed;
-      currentState = state;
-      return currentState;
-    } catch (_error) {
-      return null;
+      const { savedAt: _savedAt, version, filePath: _filePath, ...state } = parsed
+
+      if (version === "1") {
+        if (!state.soloditResults) {
+          state.soloditResults = []
+        }
+        if (!state.fuzzCounterexamples) {
+          state.fuzzCounterexamples = []
+        }
+      }
+
+      currentState = state
+      return currentState
+    } catch (err) {
+      logger.warn("Failed to load persisted audit state", err)
+      return null
     }
   }
 
+  let saveInFlight = false
+
   async function save(state: AuditState): Promise<void> {
-    currentState = state;
-
-    const persistentState: PersistentAuditState = {
-      ...state,
-      savedAt: Date.now(),
-      version: STATE_VERSION,
-      filePath: stateFilePath,
-    };
-
-    const tempFilePath = `${stateFilePath}.tmp`;
-    await mkdir(dirname(stateFilePath), { recursive: true });
-    await Bun.write(tempFilePath, `${JSON.stringify(persistentState, null, 2)}\n`);
-    await rename(tempFilePath, stateFilePath);
+    currentState = state
+
+    if (saveInFlight) return
+    saveInFlight = true
+
+    try {
+      while (true) {
+        const stateToSave = currentState
+
+        const persistentState: PersistentAuditState = {
+          ...stateToSave,
+          savedAt: Date.now(),
+          version: STATE_VERSION,
+          filePath: stateFilePath,
+        }
+
+        const tempFilePath = `${stateFilePath}.${Date.now()}.tmp`
+        await mkdir(dirname(stateFilePath), { recursive: true })
+        await Bun.write(tempFilePath, `${JSON.stringify(persistentState, null, 2)}\n`)
+        await rename(tempFilePath, stateFilePath)
+
+        if (currentState === stateToSave) break
+      }
+    } catch (err) {
+      logger.warn("Failed to persist audit state", err)
+      throw err
+    } finally {
+      saveInFlight = false
+    }
   }
 
   function get(): AuditState {
-    return currentState;
+    return currentState
   }
 
   async function update(patch: Partial<AuditState>): Promise<void> {
     currentState = {
       ...currentState,
       ...patch,
-    };
+    }
 
-    await save(currentState);
+    await save(currentState)
   }
 
   async function reset(): Promise<void> {
-    currentState = createAuditState(projectDir).state;
-    await save(currentState);
+    currentState = createAuditState(projectDir).state
+    await save(currentState)
+  }
+
+  async function archive(): Promise<void> {
+    const hasContent =
+      currentState.findings.length > 0 ||
+      currentState.toolsExecuted.length > 0 ||
+      currentState.currentPhase !== "reconnaissance"
+
+    if (hasContent) {
+      try {
+        const archivesDir = join(dirname(stateFilePath), "archives")
+        await mkdir(archivesDir, { recursive: true })
+        const archivePath = join(archivesDir, `argus-state.${Date.now()}.json`)
+        const persistentState: PersistentAuditState = {
+          ...currentState,
+          savedAt: Date.now(),
+          version: STATE_VERSION,
+          filePath: archivePath,
+        }
+        await Bun.write(archivePath, `${JSON.stringify(persistentState, null, 2)}\n`)
+      } catch {
+        logger.debug("Failed to archive audit state")
+      }
+    }
+
+    currentState = createAuditState(projectDir).state
+    await save(currentState)
   }
 
   return {
@@ -117,5 +222,6 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
     get,
     update,
     reset,
-  };
+    archive,
+  }
 }

package/src/features/persistent-state/global-run-index.ts

@@ -0,0 +1,38 @@
+import { appendFileSync } from "node:fs"
+import { mkdir } from "node:fs/promises"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { createLogger } from "../../shared/logger"
+
+const logger = createLogger()
+
+const CACHE_DIR = join(homedir(), ".cache", "solidity-argus", "runs")
+const INDEX_FILE = join(CACHE_DIR, "index.jsonl")
+
+export type RunIndexEntry = {
+  runId: string
+  opencodeSessionId?: string
+  projectDir: string
+  statePath: string
+  journalPath: string
+  startedAt: number
+  phase: string
+  findingsCount: number
+}
+
+let dirEnsured = false
+
+async function ensureDir(): Promise<void> {
+  if (dirEnsured) return
+  await mkdir(CACHE_DIR, { recursive: true })
+  dirEnsured = true
+}
+
+export async function recordRun(entry: RunIndexEntry): Promise<void> {
+  try {
+    await ensureDir()
+    appendFileSync(INDEX_FILE, `${JSON.stringify(entry)}\n`)
+  } catch {
+    logger.debug("Failed to write global run index entry")
+  }
+}

package/src/features/persistent-state/index.ts

@@ -1 +1 @@
-export { createAuditStateManager } from "./audit-state-manager";
+export { createAuditStateManager } from "./audit-state-manager"

package/src/features/persistent-state/run-journal.ts

@@ -0,0 +1,86 @@
+import { appendFile, mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { createLogger } from "../../shared/logger"
+
+const logger = createLogger()
+
+const JOURNAL_DIR = ".opencode"
+const JOURNAL_FILE = "argus-journal.jsonl"
+
+export type JournalEvent =
+  | { type: "session.created"; sessionId?: string; timestamp: number }
+  | {
+      type: "session.idle"
+      timestamp: number
+      findingsCount: number
+      toolsExecutedCount: number
+    }
+  | { type: "session.deleted"; timestamp: number; archived: boolean }
+  | {
+      type: "tool.executed"
+      tool: string
+      timestamp: number
+      findingsCount: number
+    }
+  | { type: "state.saved"; timestamp: number; success: boolean }
+  | {
+      type: "state.loaded"
+      timestamp: number
+      success: boolean
+      findingsCount: number
+    }
+
+export function createRunJournal(projectDir: string): {
+  log(event: JournalEvent): void
+  close(): Promise<void>
+  getPath(): string
+} {
+  const journalPath = join(projectDir, JOURNAL_DIR, JOURNAL_FILE)
+  let ensureDirPromise: Promise<void> | null = null
+  const pendingWrites = new Set<Promise<void>>()
+
+  function ensureDirectory(): Promise<void> {
+    if (!ensureDirPromise) {
+      ensureDirPromise = (async () => {
+        try {
+          await mkdir(dirname(journalPath), { recursive: true })
+        } catch {
+          logger.debug("Failed to create run journal directory")
+        }
+      })()
+    }
+
+    return ensureDirPromise
+  }
+
+  function trackWrite(writePromise: Promise<void>): void {
+    pendingWrites.add(writePromise)
+    void writePromise.finally(() => {
+      pendingWrites.delete(writePromise)
+    })
+  }
+
+  function log(event: JournalEvent): void {
+    const line = `${JSON.stringify(event)}\n`
+
+    const writePromise = ensureDirectory()
+      .then(async () => {
+        await appendFile(journalPath, line, "utf8")
+      })
+      .catch(() => {
+        logger.debug("Failed to append run journal event")
+      })
+
+    trackWrite(writePromise)
+  }
+
+  async function close(): Promise<void> {
+    await Promise.allSettled(Array.from(pendingWrites))
+  }
+
+  return {
+    log,
+    close,
+    getPath: () => journalPath,
+  }
+}

package/src/hooks/agent-tracker.ts

@@ -0,0 +1,53 @@
+import type { Hooks as PluginHooks } from "@opencode-ai/plugin"
+
+type ChatParamsInput = Parameters<NonNullable<PluginHooks["chat.params"]>>[0] & {
+  agent?: string
+}
+type ChatMessageInput = Parameters<NonNullable<PluginHooks["chat.message"]>>[0]
+
+const ARGUS_FAMILY = new Set(["argus", "sentinel", "pythia", "scribe"])
+
+export type AgentTracker = ReturnType<typeof createAgentTracker>
+
+export function createAgentTracker() {
+  const sessions = new Map<string, string>()
+
+  const trackSession = (sessionID: string, agent?: string): void => {
+    if (!agent) {
+      return
+    }
+
+    sessions.set(sessionID, agent)
+  }
+
+  return {
+    chatParamsHook: (input: ChatParamsInput): void => {
+      trackSession(input.sessionID, input.agent)
+    },
+
+    chatMessageHook: (input: ChatMessageInput): void => {
+      trackSession(input.sessionID, input.agent)
+    },
+
+    getAgentForSession: (sessionID: string): string | undefined => {
+      return sessions.get(sessionID)
+    },
+
+    isArgusAgent: (sessionID: string): boolean => {
+      const agent = sessions.get(sessionID)
+      if (!agent) {
+        return false
+      }
+
+      return ARGUS_FAMILY.has(agent)
+    },
+
+    clearSession: (sessionID: string): void => {
+      sessions.delete(sessionID)
+    },
+
+    getTrackedSessions: (): Map<string, string> => {
+      return sessions
+    },
+  }
+}

package/src/hooks/compaction-hook.ts

@@ -1,50 +1,59 @@
 import type { AuditState, FindingSeverity } from "../state/types"
+import type { ReconContext } from "./recon-context-builder"
+import { buildReconContextBlock } from "./recon-context-builder"
 
-/**
- * Creates a compaction hook that serializes audit state into XML format
- * so findings survive context window compression.
- *
- * The returned hook is called by OpenCode's `experimental.session.compacting`
- * event, receiving `{ summary: string }` and returning the enriched summary.
- */
 export function createCompactionHook(
-  getAuditState: () => AuditState | null
+  getAuditState: () => AuditState | null,
+  getReconContext?: () => ReconContext | null,
 ): (input: { summary: string }) => Promise<string | null> {
   return async (_input: { summary: string }): Promise<string | null> => {
     const state = getAuditState()
-    if (!state) {
-      return null
-    }
 
-    const severityCounts: Record<FindingSeverity, number> = {
-      Critical: 0,
-      High: 0,
-      Medium: 0,
-      Low: 0,
-      Informational: 0,
+    const parts: string[] = []
+
+    if (state) {
+      const severityCounts: Record<FindingSeverity, number> = {
+        Critical: 0,
+        High: 0,
+        Medium: 0,
+        Low: 0,
+        Informational: 0,
+      }
+
+      for (const finding of state.findings) {
+        severityCounts[finding.severity]++
+      }
+
+      const toolNames = state.toolsExecuted.map((t) => t.tool).join(", ")
+      const contracts = state.contractsReviewed.join(", ")
+      const started = new Date(state.startTime).toISOString()
+
+      parts.push(
+        [
+          "<argus-audit-state>",
+          `Phase: ${state.currentPhase}`,
+          `Contracts Reviewed: ${contracts}`,
+          "Findings:",
+          `  Critical: ${severityCounts.Critical}`,
+          `  High: ${severityCounts.High}`,
+          `  Medium: ${severityCounts.Medium}`,
+          `  Low: ${severityCounts.Low}`,
+          `  Informational: ${severityCounts.Informational}`,
+          `Tools Executed: ${toolNames}`,
+          `Started: ${started}`,
+          "</argus-audit-state>",
+        ].join("\n"),
+      )
     }
 
-    for (const finding of state.findings) {
-      severityCounts[finding.severity]++
+    if (getReconContext) {
+      const recon = getReconContext()
+      if (recon) {
+        const reconBlock = buildReconContextBlock(recon)
+        if (reconBlock) parts.push(reconBlock)
+      }
     }
 
-    const toolNames = state.toolsExecuted.map((t) => t.tool).join(", ")
-    const contracts = state.contractsReviewed.join(", ")
-    const started = new Date(state.startTime).toISOString()
-
-    return [
-      "<argus-audit-state>",
-      `Phase: ${state.currentPhase}`,
-      `Contracts Reviewed: ${contracts}`,
-      "Findings:",
-      `  Critical: ${severityCounts.Critical}`,
-      `  High: ${severityCounts.High}`,
-      `  Medium: ${severityCounts.Medium}`,
-      `  Low: ${severityCounts.Low}`,
-      `  Informational: ${severityCounts.Informational}`,
-      `Tools Executed: ${toolNames}`,
-      `Started: ${started}`,
-      "</argus-audit-state>",
-    ].join("\n")
+    return parts.length > 0 ? parts.join("\n") : null
   }
 }

package/src/hooks/config-handler.ts

@@ -1,17 +1,19 @@
-import { resolve, join } from "node:path"
 import { existsSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
+import { join, resolve } from "node:path"
 import type { Config } from "@opencode-ai/sdk/v2"
-import type { ArgusConfig } from "../config/types"
-import { DEFAULT_MODELS } from "../constants/defaults"
-import { createKnowledgeSyncHook } from "./knowledge-sync-hook"
 import { ARGUS_PROMPT } from "../agents/argus-prompt"
-import { SENTINEL_PROMPT } from "../agents/sentinel-prompt"
 import { PYTHIA_PROMPT } from "../agents/pythia-prompt"
 import { SCRIBE_PROMPT } from "../agents/scribe-prompt"
+import { SENTINEL_PROMPT } from "../agents/sentinel-prompt"
+import type { ArgusConfig } from "../config/types"
+import { DEFAULT_MODELS, DEFAULT_STEPS } from "../constants/defaults"
+import { createLogger } from "../shared/logger"
+import { createKnowledgeSyncHook } from "./knowledge-sync-hook"
 
 const TOB_CACHE_DIR = join(homedir(), ".cache", "solidity-argus", "trailofbits-skills")
 const TOB_REPO_URL = "https://github.com/trailofbits/skills.git"
+const TOB_BRANCH = "main"
 let tobCloneInFlight = false
 
 function getTrailOfBitsSkillsPaths(rootDir: string): string[] {
@@ -40,24 +42,32 @@ function ensureTrailOfBitsSkills(): string[] {
   if (!tobCloneInFlight) {
     tobCloneInFlight = true
     const cloneProcess = Bun.spawn(
-      ["git", "clone", "--depth", "1", TOB_REPO_URL, TOB_CACHE_DIR],
+      ["git", "clone", "--depth", "1", "--branch", TOB_BRANCH, TOB_REPO_URL, TOB_CACHE_DIR],
       {
         stdin: "ignore",
         stdout: "ignore",
         stderr: "ignore",
+        signal: AbortSignal.timeout(60_000),
       },
     )
-    cloneProcess.exited.finally(() => {
-      tobCloneInFlight = false
-    })
+    cloneProcess.exited
+      .then((code) => {
+        if (code !== 0) {
+          const logger = createLogger()
+          logger.warn(`Trail of Bits skills clone failed with exit code ${code}`)
+        }
+      })
+      .finally(() => {
+        tobCloneInFlight = false
+      })
   }
 
-    return []
+  return []
 }
 
 export function createConfigHandler(
   argusConfig: ArgusConfig,
-  projectDir: string = process.cwd()
+  projectDir: string = process.cwd(),
 ): (config: Config) => Promise<void> {
   const triggerKnowledgeSync = createKnowledgeSyncHook(argusConfig)
 
@@ -67,6 +77,7 @@ export function createConfigHandler(
       argus: {
         mode: "primary",
         model: argusConfig.agents?.argus?.model ?? DEFAULT_MODELS.argus,
+        steps: argusConfig.agents?.argus?.steps ?? DEFAULT_STEPS,
         description: "Solidity security auditor — the All-Seeing Guardian",
         prompt: ARGUS_PROMPT,
         tools: {
@@ -85,35 +96,44 @@ export function createConfigHandler(
       sentinel: {
         mode: "subagent",
         model: argusConfig.agents?.sentinel?.model ?? DEFAULT_MODELS.sentinel,
+        steps: argusConfig.agents?.sentinel?.steps ?? DEFAULT_STEPS,
         description: "Static analysis and testing specialist",
         prompt: SENTINEL_PROMPT,
         permission: {
           argus_slither_analyze: "allow",
           argus_forge_test: "allow",
+          argus_gas_analysis: "allow",
           argus_forge_fuzz: "allow",
           argus_analyze_contract: "allow",
           argus_check_patterns: "allow",
+          argus_proxy_detection: "allow",
+          argus_forge_coverage: "allow",
+          argus_skill_load: "allow",
           skill: "allow",
         },
       },
       pythia: {
         mode: "subagent",
         model: argusConfig.agents?.pythia?.model ?? DEFAULT_MODELS.pythia,
+        steps: argusConfig.agents?.pythia?.steps ?? DEFAULT_STEPS,
         description: "Vulnerability researcher",
         prompt: PYTHIA_PROMPT,
         permission: {
           argus_solodit_search: "allow",
           argus_check_patterns: "allow",
+          argus_skill_load: "allow",
           skill: "allow",
         },
       },
       scribe: {
         mode: "subagent",
         model: argusConfig.agents?.scribe?.model ?? DEFAULT_MODELS.scribe,
+        steps: argusConfig.agents?.scribe?.steps ?? DEFAULT_STEPS,
         description: "Audit report writer",
         prompt: SCRIBE_PROMPT,
         permission: {
           argus_generate_report: "allow",
+          argus_skill_load: "allow",
           skill: "allow",
         },
       },