solidity-argus 0.2.0 → 0.3.2

package/src/features/error-recovery/tool-error-recovery.ts

@@ -10,17 +10,17 @@ const TOOL_FALLBACKS: Record<string, ToolFallbackEntry> = {
   slither: {
     install: "pip install slither-analyzer",
     fallback:
-      "Slither is unavailable. PROCEED with the audit using `argus_analyze_contract` for structural profiling and `argus_check_patterns` for vulnerability scanning. Note in the final report: \"Automated static analysis (Slither) was unavailable; manual review intensity increased.\"",
+      'Slither is unavailable. PROCEED with the audit using `argus_analyze_contract` for structural profiling and `argus_check_patterns` for vulnerability scanning. Note in the final report: "Automated static analysis (Slither) was unavailable; manual review intensity increased."',
   },
   forge: {
     install: "curl -L https://foundry.paradigm.xyz | bash && foundryup",
     fallback:
-      "Foundry/Forge is unavailable. SKIP automated testing and fuzzing. Verify findings through manual code tracing and static analysis. Note in the final report: \"Dynamic testing (Forge) was unavailable; findings verified via manual analysis.\"",
+      'Foundry/Forge is unavailable. SKIP automated testing and fuzzing. Verify findings through manual code tracing and static analysis. Note in the final report: "Dynamic testing (Forge) was unavailable; findings verified via manual analysis."',
   },
   solodit: {
     install: "",
     fallback:
-      "Solodit API is unreachable. PROCEED using `argus_check_patterns` with local vulnerability rules. Note in the final report: \"External vulnerability databases were inaccessible; research limited to local patterns.\"",
+      'Solodit API is unreachable. PROCEED using `argus_check_patterns` with local vulnerability rules. Note in the final report: "External vulnerability databases were inaccessible; research limited to local patterns."',
   },
   scvd: {
     install: "",
@@ -54,6 +54,7 @@ function resolveToolBase(tool: string): string {
 
 export function createToolErrorRecoveryHandler(
   getAuditState?: () => AuditState | null,
+  updateAuditState?: (patch: Partial<AuditState>) => Promise<void>,
 ) {
   const logger = createLogger()
 
@@ -80,12 +81,16 @@ export function createToolErrorRecoveryHandler(
 
     const unavailable = isToolUnavailable(lowerResult)
 
-    if (unavailable && getAuditState) {
+    if (unavailable && getAuditState && updateAuditState) {
       const state = getAuditState()
       if (state) {
-        state.unavailableTools ??= []
-        if (!state.unavailableTools.includes(toolBase)) {
-          state.unavailableTools.push(toolBase)
+        const existing = state.unavailableTools ?? []
+        if (!existing.includes(toolBase)) {
+          void updateAuditState({
+            unavailableTools: [...existing, toolBase],
+          }).catch((error: unknown) => {
+            logger.warn(`Failed to persist unavailable tool state for ${toolBase}`, error)
+          })
           logger.info(`Recorded ${toolBase} as unavailable — fallback activated`)
         }
       }

package/src/features/index.ts

@@ -1,5 +1,5 @@
-export * from './background-agent'
-export * from './persistent-state'
-export * from './context-monitor'
-export * from './audit-enforcer'
-export * from './error-recovery'
+export * from "./audit-enforcer"
+export * from "./background-agent"
+export * from "./context-monitor"
+export * from "./error-recovery"
+export * from "./persistent-state"

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 = "2";
+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,107 +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";
+  const hasSupportedVersion = value.version === "1" || value.version === "2"
 
   return (
-    typeof value.savedAt === "number" &&
-    hasSupportedVersion &&
-    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, filePath: _filePath, ...state } = parsed;
+      const { savedAt: _savedAt, version, filePath: _filePath, ...state } = parsed
 
       if (version === "1") {
         if (!state.soloditResults) {
-          state.soloditResults = [];
+          state.soloditResults = []
         }
         if (!state.fuzzCounterexamples) {
-          state.fuzzCounterexamples = [];
+          state.fuzzCounterexamples = []
         }
       }
 
-      currentState = state;
-      return currentState;
-    } catch (_error) {
-      return null;
+      currentState = state
+      return currentState
+    } catch (err) {
+      logger.warn("Failed to load persisted audit state", err)
+      return null
     }
   }
 
-  let saveInFlight = false;
+  let saveInFlight = false
 
   async function save(state: AuditState): Promise<void> {
-    currentState = state;
+    currentState = state
 
-    if (saveInFlight) return;
-    saveInFlight = true;
+    if (saveInFlight) return
+    saveInFlight = true
 
     try {
-      const persistentState: PersistentAuditState = {
-        ...state,
-        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);
-    } catch {
-      // Non-critical: state persistence is best-effort
+      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;
+      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 {
@@ -140,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/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,14 +96,18 @@ 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",
         },
@@ -100,6 +115,7 @@ export function createConfigHandler(
       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: {
@@ -112,6 +128,7 @@ export function createConfigHandler(
       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: {

package/src/hooks/context-budget.ts

@@ -10,7 +10,7 @@
 
 const ARGUS_BUDGET = 2000
 const SUBAGENT_BUDGET = 1000
-const PRESSURE_THRESHOLD = 0.70
+const PRESSURE_THRESHOLD = 0.7
 const PRESSURE_REDUCTION = 0.5
 
 const ARGUS_AGENTS = new Set(["argus"])
@@ -23,10 +23,7 @@ const SUBAGENTS = new Set(["sentinel", "pythia", "scribe"])
  * @param contextPressure - Current context usage ratio (0.0–1.0), from ContextMonitor
  * @returns Token budget in tokens. 0 for non-Argus agents.
  */
-export function getTokenBudgetForAgent(
-  agent: string,
-  contextPressure: number = 0,
-): number {
+export function getTokenBudgetForAgent(agent: string, contextPressure: number = 0): number {
   let budget: number
 
   if (ARGUS_AGENTS.has(agent)) {