solidity-argus 0.2.0 → 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 = "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)) {

package/src/hooks/event-hook.ts

@@ -1,33 +1,45 @@
-import type { AuditState } from "../state/types"
-import { createAuditState } from "../state/audit-state"
 import { createLogger } from "../shared/logger"
+import { createAuditState } from "../state/audit-state"
+import type { AuditState } from "../state/types"
+
+export type AuditEventType =
+  | "session.created"
+  | "session.idle"
+  | "session.error"
+  | "session.deleted"
+  | "audit.phase-changed"
+  | "audit.finding-added"
+  | "audit.complete"
 
 export type EventHookFn = (input: {
-  event: { type: string; sessionId?: string }
+  event: { type: string; sessionId?: string; properties?: Record<string, unknown> }
 }) => Promise<void>
 
-/**
- * Creates a session lifecycle event hook that manages audit state.
- *
- * Returns the hook function plus accessors for reading/writing the
- * closure-held audit state. Other hooks (compaction, tool tracking,
- * system prompt) share the same state instance via these accessors.
- */
-export function createEventHook(projectDir?: string): {
+export type EventSubHandler = (event: {
+  type: string
+  sessionId?: string
+  auditState: AuditState | null
+  setAuditState: (state: AuditState | null) => void
+}) => Promise<void>
+
+export function createEventHook(
+  projectDir?: string,
+  subHandlers: EventSubHandler[] = [],
+): {
   hook: EventHookFn
   getAuditState: () => AuditState | null
   setAuditState: (state: AuditState | null) => void
 } {
+  const logger = createLogger()
   let currentAuditState: AuditState | null = null
 
   const getAuditState = (): AuditState | null => currentAuditState
-
   const setAuditState = (state: AuditState | null): void => {
     currentAuditState = state
   }
 
   const hook: EventHookFn = async (input): Promise<void> => {
-    const { type } = input.event
+    const { type, sessionId } = input.event
 
     switch (type) {
       case "session.created": {
@@ -38,23 +50,23 @@ export function createEventHook(projectDir?: string): {
       }
 
       case "session.idle": {
-         if (currentAuditState) {
-           createLogger().debug(
-             `[state] Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}, contracts: ${currentAuditState.contractsReviewed.length}`
-           )
-         }
-         break
-       }
+        if (currentAuditState) {
+          logger.debug(
+            `Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}`,
+          )
+        }
+        break
+      }
 
       case "session.error": {
         if (currentAuditState) {
-          createLogger().error(
+          logger.error(
             `Session error — state snapshot: ${JSON.stringify({
               sessionId: currentAuditState.sessionId,
               phase: currentAuditState.currentPhase,
               findingsCount: currentAuditState.findings.length,
               contractsReviewed: currentAuditState.contractsReviewed,
-            })}`
+            })}`,
           )
         }
         break
@@ -65,10 +77,22 @@ export function createEventHook(projectDir?: string): {
         break
       }
 
-      // Unknown events: no-op — never throw
       default:
         break
     }
+
+    for (const handler of subHandlers) {
+      try {
+        await handler({
+          type,
+          sessionId,
+          auditState: currentAuditState,
+          setAuditState,
+        })
+      } catch (error) {
+        logger.error(`Sub-handler failed for event ${type}:`, error)
+      }
+    }
   }
 
   return { hook, getAuditState, setAuditState }

package/src/hooks/hook-system.ts

@@ -1,9 +1,9 @@
-import type { HookName } from "./types";
+import type { HookName } from "./types"
 
 export function createHookGuard(disabledHooks: string[]) {
-  const disabledSet = new Set(disabledHooks);
+  const disabledSet = new Set(disabledHooks)
 
   return function isHookEnabled(name: HookName): boolean {
-    return !disabledSet.has(name);
-  };
+    return !disabledSet.has(name)
+  }
 }

package/src/hooks/index.ts

@@ -1,5 +1,5 @@
-export { createHookGuard } from "./hook-system";
-export { safeCreateHook } from "./safe-create-hook";
-export { createEventHookV2 } from "./event-hook-v2";
-export type { HookName } from "./types";
-export type { EventHookV2Fn, AuditEventType, EventSubHandler } from "./event-hook-v2";
+export type { AuditEventType, EventHookFn, EventSubHandler } from "./event-hook"
+export { createEventHook } from "./event-hook"
+export { createHookGuard } from "./hook-system"
+export { safeCreateHook } from "./safe-create-hook"
+export type { HookName } from "./types"