solidity-argus 0.2.0 → 0.3.2

package/src/create-hooks.ts

@@ -1,34 +1,47 @@
+import { join } from "node:path"
 import type { Hooks as PluginHooks } from "@opencode-ai/plugin"
 import type { ArgusConfig } from "./config/types"
-import type { Managers } from "./managers/types"
-import type { HookName } from "./hooks/types"
-import { createConfigHandler } from "./hooks/config-handler"
-import { createCompactionHook } from "./hooks/compaction-hook"
-import { createToolTrackingHook } from "./hooks/tool-tracking-hook"
-import { createEventHookV2 } from "./hooks/event-hook-v2"
-import { createAgentTracker } from "./hooks/agent-tracker"
-import { createSystemPromptHook } from "./hooks/system-prompt-hook"
-import { safeCreateHook } from "./hooks/safe-create-hook"
-import { createContextMonitor, createToolOutputTruncator } from "./features/context-monitor"
 import { createAuditEnforcer } from "./features/audit-enforcer/audit-enforcer"
+import { createContextMonitor, createToolOutputTruncator } from "./features/context-monitor"
+import {
+  createSessionRecoveryHandler,
+  createToolErrorRecoveryHandler,
+} from "./features/error-recovery"
+import { createDebouncedSave } from "./features/persistent-state/audit-state-manager"
+import { recordRun } from "./features/persistent-state/global-run-index"
+import { createRunJournal } from "./features/persistent-state/run-journal"
+import { createAgentTracker } from "./hooks/agent-tracker"
+import { createCompactionHook } from "./hooks/compaction-hook"
+import { createConfigHandler } from "./hooks/config-handler"
 import { getTokenBudgetForAgent } from "./hooks/context-budget"
-import { createSessionRecoveryHandler } from "./features/error-recovery"
-import { createToolErrorRecoveryHandler } from "./features/error-recovery"
-import { detectProject } from "./utils/project-detector"
-import type { ProjectConfig } from "./utils/project-detector"
-import { detectAuditArtifacts } from "./utils/audit-artifact-detector"
+import { createEventHook } from "./hooks/event-hook"
 import type { ReconContext } from "./hooks/recon-context-builder"
 import { buildReconContextBlock } from "./hooks/recon-context-builder"
+import { safeCreateHook } from "./hooks/safe-create-hook"
+import { createSystemPromptHook } from "./hooks/system-prompt-hook"
+import { createToolTrackingHook } from "./hooks/tool-tracking-hook"
+import type { HookName } from "./hooks/types"
+import type { Managers } from "./managers/types"
+import { createLogger } from "./shared/logger"
 import type { AuditState } from "./state/types"
+import { detectAuditArtifacts } from "./utils/audit-artifact-detector"
+import { detectProject, type ProjectConfig } from "./utils/project-detector"
 
-let latestAgentTracker: ReturnType<typeof createAgentTracker> | undefined
+const logger = createLogger()
+
+export type AgentTrackerRef = {
+  getAgentForSession(sessionID: string): string | undefined
+  isArgusAgent(sessionID: string): boolean
+}
+
+let _agentTrackerRef: AgentTrackerRef | undefined
 
 export function getAgentForSession(sessionID: string): string | undefined {
-  return latestAgentTracker?.getAgentForSession(sessionID)
+  return _agentTrackerRef?.getAgentForSession(sessionID)
 }
 
 export function isArgusAgent(sessionID: string): boolean {
-  return latestAgentTracker?.isArgusAgent(sessionID) ?? false
+  return _agentTrackerRef?.isArgusAgent(sessionID) ?? false
 }
 
 export type Hooks = Pick<
@@ -62,26 +75,103 @@ export function createHooks(args: {
   const { config, managers, projectDir, isHookEnabled } = args
   const { auditStateManager, backgroundManager } = managers
   const agentTracker = createAgentTracker()
-  latestAgentTracker = agentTracker
+  _agentTrackerRef = agentTracker
 
   const contextMonitor = createContextMonitor()
   const sessionRecoveryHandler = createSessionRecoveryHandler(auditStateManager)
+  const debouncedSave = createDebouncedSave(auditStateManager.save)
+  const runJournal = createRunJournal(projectDir)
   let auditStateGetter: (() => AuditState | null) | undefined
-  const toolErrorRecoveryHandler = createToolErrorRecoveryHandler(() => auditStateGetter?.() ?? null)
+  const toolErrorRecoveryHandler = createToolErrorRecoveryHandler(
+    () => auditStateGetter?.() ?? null,
+    (patch) => auditStateManager.update(patch),
+  )
   const outputTruncator = createToolOutputTruncator()
 
-  const { hook: eventHook, getAuditState, setAuditState } = createEventHookV2(projectDir, [
+  // Sub-handlers run sequentially. The state persistence handler MUST be first:
+  // it loads persisted state on session.created, overriding the fresh default.
+  const {
+    hook: eventHook,
+    getAuditState,
+    setAuditState,
+  } = createEventHook(projectDir, [
     async ({ type, sessionId, auditState, setAuditState: setState }) => {
       if (type === "session.created") {
-        const recoveredState = await auditStateManager.load()
+        const timestamp = Date.now()
+        let recoveredState: AuditState | null = null
+
+        try {
+          recoveredState = await auditStateManager.load()
+        } finally {
+          runJournal.log({
+            type: "state.loaded",
+            timestamp,
+            success: recoveredState !== null,
+            findingsCount: recoveredState?.findings.length ?? 0,
+          })
+        }
+
         if (recoveredState) {
           setState(recoveredState)
         }
+
+        runJournal.log({
+          type: "session.created",
+          sessionId,
+          timestamp: Date.now(),
+        })
+
+        const effectiveState = recoveredState ?? auditStateManager.get()
+        if (effectiveState) {
+          void recordRun({
+            runId: effectiveState.sessionId,
+            opencodeSessionId: sessionId,
+            projectDir: effectiveState.projectDir,
+            statePath: join(effectiveState.projectDir, ".opencode", "argus-state.json"),
+            journalPath: join(effectiveState.projectDir, ".opencode", "argus-journal.jsonl"),
+            startedAt: effectiveState.startTime,
+            phase: effectiveState.currentPhase,
+            findingsCount: effectiveState.findings.length,
+          })
+        }
+
         return
       }
 
       if (type === "session.idle" && auditState) {
-        await auditStateManager.save(auditState)
+        await debouncedSave.flush()
+
+        let saveSuccess = true
+        try {
+          await auditStateManager.save(auditState)
+        } catch {
+          saveSuccess = false
+        } finally {
+          runJournal.log({
+            type: "state.saved",
+            timestamp: Date.now(),
+            success: saveSuccess,
+          })
+        }
+
+        runJournal.log({
+          type: "session.idle",
+          timestamp: Date.now(),
+          findingsCount: auditState.findings.length,
+          toolsExecutedCount: auditState.toolsExecuted.length,
+        })
+
+        void recordRun({
+          runId: auditState.sessionId,
+          opencodeSessionId: sessionId,
+          projectDir: auditState.projectDir,
+          statePath: join(auditState.projectDir, ".opencode", "argus-state.json"),
+          journalPath: join(auditState.projectDir, ".opencode", "argus-journal.jsonl"),
+          startedAt: auditState.startTime,
+          phase: auditState.currentPhase,
+          findingsCount: auditState.findings.length,
+        })
+
         return
       }
 
@@ -89,7 +179,13 @@ export function createHooks(args: {
         if (sessionId) {
           agentTracker.clearSession(sessionId)
         }
-        await auditStateManager.reset()
+
+        await auditStateManager.archive()
+        runJournal.log({
+          type: "session.deleted",
+          timestamp: Date.now(),
+          archived: true,
+        })
       }
     },
     async ({ type, sessionId, setAuditState: setState }) => {
@@ -121,11 +217,12 @@ export function createHooks(args: {
     },
     getTokenBudget: getTokenBudgetForAgent,
     getEnforcerReminder: auditEnforcer,
-    getReconBlock: () => buildReconContextBlock({
-      projectConfig: reconProjectConfig,
-      dependencyRisks: reconProjectConfig?.dependencyRisks ?? [],
-      auditArtifacts: detectAuditArtifacts(projectDir),
-    }),
+    getReconBlock: () =>
+      buildReconContextBlock({
+        projectConfig: reconProjectConfig,
+        dependencyRisks: reconProjectConfig?.dependencyRisks ?? [],
+        auditArtifacts: detectAuditArtifacts(projectDir),
+      }),
   })
 
   let reconProjectConfig: ProjectConfig | null = null
@@ -135,7 +232,7 @@ export function createHooks(args: {
       reconProjectConfig = config
     })
     .catch(() => {
-      // Silent fallback — audit artifacts remain available
+      logger.debug("Project detection failed, using fallback recon context")
     })
 
   const getReconContext = (): ReconContext => ({
@@ -149,7 +246,23 @@ export function createHooks(args: {
     : undefined
 
   const toolTrackingHook = isHookEnabled("tool-tracking")
-    ? safeCreateHook(() => createToolTrackingHook(getAuditState), "tool-tracking")
+    ? safeCreateHook(
+        () =>
+          createToolTrackingHook(getAuditState, ({ tool, findingsCount }) => {
+            const currentState = getAuditState()
+            if (currentState) {
+              debouncedSave.save(currentState)
+            }
+
+            runJournal.log({
+              type: "tool.executed",
+              tool,
+              timestamp: Date.now(),
+              findingsCount,
+            })
+          }),
+        "tool-tracking",
+      )
     : undefined
 
   const safeEventHook = isHookEnabled("event")
@@ -186,9 +299,7 @@ export function createHooks(args: {
             result: output.output,
           })
 
-          const outputWithHint = recoveryHint
-            ? `${output.output}${recoveryHint}`
-            : output.output
+          const outputWithHint = recoveryHint ? `${output.output}${recoveryHint}` : output.output
           output.output = outputTruncator(outputWithHint)
         }
       : undefined,

package/src/create-managers.ts

@@ -1,23 +1,25 @@
 import type { ArgusConfig } from "./config/types"
-import type { Managers } from "./managers/types"
+import type { Dispatcher } from "./features/background-agent/background-manager"
 import { createBackgroundManager } from "./features/background-agent/background-manager"
 import { createAuditStateManager } from "./features/persistent-state/audit-state-manager"
+import type { Managers } from "./managers/types"
 import { createLogger } from "./shared/logger"
 
 export function createManagers(args: {
   projectDir: string
   config: ArgusConfig
+  backgroundDispatcher?: Dispatcher
 }): Managers {
-  const { projectDir } = args
+  const { projectDir, config, backgroundDispatcher } = args
   const logger = createLogger()
 
   const backgroundManager = createBackgroundManager(
-    async (agentName: string, prompt: string) => {
-      logger.warn(
-        `Background dispatch not wired: ${agentName} (${prompt.slice(0, 50)}...)`,
-      )
-      return `noop-${Date.now()}`
-    },
+    backgroundDispatcher ??
+      (async (agentName: string, prompt: string) => {
+        logger.warn(`Background dispatch not wired: ${agentName} (${prompt.slice(0, 50)}...)`)
+        return `noop-${Date.now()}`
+      }),
+    { maxConcurrent: config.background?.max_concurrent ?? 3 },
   )
 
   const auditStateManager = createAuditStateManager(projectDir)

package/src/create-tools.ts

@@ -1,31 +1,35 @@
 import type { ToolDefinition } from "@opencode-ai/plugin"
 import type { ArgusConfig } from "./config/types"
-import { slitherTool } from "./tools/slither-tool"
-import { forgeTestTool } from "./tools/forge-test-tool"
-import { forgeFuzzTool } from "./tools/forge-fuzz-tool"
+import { argusSkillLoadTool } from "./tools/argus-skill-load-tool"
 import { contractAnalyzerTool } from "./tools/contract-analyzer-tool"
+import { forgeCoverageTool } from "./tools/forge-coverage-tool"
+import { forgeFuzzTool } from "./tools/forge-fuzz-tool"
+import { forgeTestTool } from "./tools/forge-test-tool"
+import { gasAnalysisTool } from "./tools/gas-analysis-tool"
 import { patternCheckerTool } from "./tools/pattern-checker-tool"
-import { soloditSearchTool } from "./tools/solodit-search-tool"
+import { proxyDetectionTool } from "./tools/proxy-detection-tool"
 import { reportGeneratorTool } from "./tools/report-generator-tool"
+import { slitherTool } from "./tools/slither-tool"
+import { createSoloditSearchTool } from "./tools/solodit-search-tool"
 import { syncKnowledgeTool } from "./tools/sync-knowledge-tool"
-import { argusSkillLoadTool } from "./tools/argus-skill-load-tool"
 
-export function createTools(
-  config: ArgusConfig,
-): Record<string, ToolDefinition> {
+export function createTools(config: ArgusConfig): Record<string, ToolDefinition> {
   const tools: Record<string, ToolDefinition> = {
     argus_slither_analyze: slitherTool,
     argus_forge_test: forgeTestTool,
+    argus_gas_analysis: gasAnalysisTool,
     argus_forge_fuzz: forgeFuzzTool,
+    argus_forge_coverage: forgeCoverageTool,
     argus_analyze_contract: contractAnalyzerTool,
     argus_check_patterns: patternCheckerTool,
+    argus_proxy_detection: proxyDetectionTool,
     argus_skill_load: argusSkillLoadTool,
     argus_generate_report: reportGeneratorTool,
     argus_sync_knowledge: syncKnowledgeTool,
   }
 
   if (config.solodit?.enabled !== false) {
-    tools.argus_solodit_search = soloditSearchTool
+    tools.argus_solodit_search = createSoloditSearchTool(config.solodit?.port ?? 3000)
   }
 
   return tools

package/src/features/background-agent/background-manager.ts

@@ -1,122 +1,125 @@
-import type { BackgroundManager } from "../../managers/types";
-import { createLogger } from "../../shared/logger";
+import type { BackgroundManager } from "../../managers/types"
+import { createLogger } from "../../shared/logger"
 
-type TaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
-type CompletionCallback = (taskId: string, result: unknown) => void;
+type TaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled"
+type CompletionCallback = (taskId: string, result: unknown) => void
 
 export interface BackgroundTaskOptions {
-  priority?: number;
-  max_concurrent?: number;
+  priority?: number
+  max_concurrent?: number
 }
 
 export interface BackgroundManagerWithTaskCallbacks extends BackgroundManager {
-  dispatch(agentName: string, prompt: string, options?: BackgroundTaskOptions): string;
-  onComplete(callback: CompletionCallback): void;
-  onComplete(taskId: string, callback: CompletionCallback): void;
+  dispatch(agentName: string, prompt: string, options?: BackgroundTaskOptions): string
+  onComplete(callback: CompletionCallback): void
+  onComplete(taskId: string, callback: CompletionCallback): void
 }
 
 interface TaskInfo {
-  status: TaskStatus;
-  agentName: string;
-  prompt: string;
-  options?: BackgroundTaskOptions;
-  result?: unknown;
-  error?: unknown;
-  callbacks: Set<CompletionCallback>;
+  status: TaskStatus
+  agentName: string
+  prompt: string
+  options?: BackgroundTaskOptions
+  result?: unknown
+  error?: unknown
+  callbacks: Set<CompletionCallback>
 }
 
-type Dispatcher = (
+export type Dispatcher = (
   agentName: string,
   prompt: string,
   options?: BackgroundTaskOptions,
-) => Promise<string>;
+) => Promise<string>
 
 export function createBackgroundManager(
-  dispatcher: Dispatcher,
+  initialDispatcher: Dispatcher,
+  options?: { maxConcurrent?: number },
 ): BackgroundManagerWithTaskCallbacks {
-  const logger = createLogger();
-  const tasks = new Map<string, TaskInfo>();
-  const queue: string[] = [];
-  const globalCallbacks = new Set<CompletionCallback>();
-
-  let runningCount = 0;
-  let maxConcurrent = 3;
-  let taskCount = 0;
+  const logger = createLogger()
+  const tasks = new Map<string, TaskInfo>()
+  const queue: string[] = []
+  const globalCallbacks = new Set<CompletionCallback>()
+
+  const dispatcher = initialDispatcher
+  let runningCount = 0
+  const maxConcurrent = options?.maxConcurrent ?? 3
+  let taskCount = 0
+
+  function safeInvokeCallback(callback: CompletionCallback, taskId: string, result: unknown): void {
+    try {
+      callback(taskId, result)
+    } catch (error: unknown) {
+      logger.error(`Background callback failed: ${taskId}`, error)
+    }
+  }
 
   function invokeCallbacks(taskId: string, result: unknown): void {
-    const task = tasks.get(taskId);
+    const task = tasks.get(taskId)
     if (!task) {
-      return;
+      return
     }
 
     for (const callback of globalCallbacks) {
-      callback(taskId, result);
+      safeInvokeCallback(callback, taskId, result)
     }
 
     for (const callback of task.callbacks) {
-      callback(taskId, result);
+      safeInvokeCallback(callback, taskId, result)
     }
 
-    task.callbacks.clear();
+    task.callbacks.clear()
   }
 
   function processQueue(): void {
     while (runningCount < maxConcurrent && queue.length > 0) {
-      const nextTaskId = queue.shift();
+      const nextTaskId = queue.shift()
 
       if (!nextTaskId) {
-        return;
+        return
       }
 
-      const task = tasks.get(nextTaskId);
+      const task = tasks.get(nextTaskId)
       if (!task || task.status === "cancelled") {
-        continue;
+        continue
       }
 
-      task.status = "running";
-      runningCount += 1;
+      task.status = "running"
+      runningCount += 1
 
       dispatcher(task.agentName, task.prompt, task.options)
         .then((result) => {
-          const currentTask = tasks.get(nextTaskId);
+          const currentTask = tasks.get(nextTaskId)
 
           if (!currentTask || currentTask.status === "cancelled") {
-            return;
+            return
           }
 
-          currentTask.status = "completed";
-          currentTask.result = result;
-          invokeCallbacks(nextTaskId, result);
+          currentTask.status = "completed"
+          currentTask.result = result
+          invokeCallbacks(nextTaskId, result)
         })
         .catch((error: unknown) => {
-          const currentTask = tasks.get(nextTaskId);
+          const currentTask = tasks.get(nextTaskId)
 
           if (!currentTask || currentTask.status === "cancelled") {
-            return;
+            return
           }
 
-          currentTask.status = "failed";
-          currentTask.error = error;
-          logger.error(`Background task failed: ${nextTaskId}`, error);
+          currentTask.status = "failed"
+          currentTask.error = error
+          logger.error(`Background task failed: ${nextTaskId}`, error)
+          invokeCallbacks(nextTaskId, error)
         })
         .finally(() => {
-          runningCount = Math.max(0, runningCount - 1);
-          processQueue();
-        });
+          runningCount = Math.max(0, runningCount - 1)
+          processQueue()
+        })
     }
   }
 
-  function dispatch(
-    agentName: string,
-    prompt: string,
-    options?: BackgroundTaskOptions,
-  ): string {
-    if (typeof options?.max_concurrent === "number" && options.max_concurrent > 0) {
-      maxConcurrent = options.max_concurrent;
-    }
-
-    taskCount += 1;
-    const taskId = `task-${taskCount}`;
+  function dispatch(agentName: string, prompt: string, options?: BackgroundTaskOptions): string {
+    taskCount += 1
+    const taskId = `task-${taskCount}`
 
     tasks.set(taskId, {
       status: "queued",
@@ -124,70 +127,73 @@ export function createBackgroundManager(
       prompt,
       options,
       callbacks: new Set<CompletionCallback>(),
-    });
+    })
 
-    queue.push(taskId);
-    processQueue();
+    queue.push(taskId)
+    processQueue()
 
-    return taskId;
+    return taskId
   }
 
   function cancel(taskId: string): void {
-    const task = tasks.get(taskId);
+    const task = tasks.get(taskId)
     if (!task) {
-      return;
+      return
     }
 
-    task.status = "cancelled";
+    task.status = "cancelled"
 
-    const queuedTaskIndex = queue.indexOf(taskId);
+    const queuedTaskIndex = queue.indexOf(taskId)
     if (queuedTaskIndex >= 0) {
-      queue.splice(queuedTaskIndex, 1);
+      queue.splice(queuedTaskIndex, 1)
     }
   }
 
   function getResult(taskId: string): Promise<unknown> {
-    const task = tasks.get(taskId);
+    const task = tasks.get(taskId)
     if (!task || task.status !== "completed") {
-      return Promise.resolve(undefined);
+      return Promise.resolve(undefined)
     }
 
-    return Promise.resolve(task.result);
+    return Promise.resolve(task.result)
   }
 
-  function onComplete(taskIdOrCallback: string | CompletionCallback, callback?: CompletionCallback): void {
+  function onComplete(
+    taskIdOrCallback: string | CompletionCallback,
+    callback?: CompletionCallback,
+  ): void {
     if (typeof taskIdOrCallback === "function") {
-      globalCallbacks.add(taskIdOrCallback);
-      return;
+      globalCallbacks.add(taskIdOrCallback)
+      return
     }
 
     if (!callback) {
-      return;
+      return
     }
 
-    const task = tasks.get(taskIdOrCallback);
+    const task = tasks.get(taskIdOrCallback)
     if (!task) {
-      return;
+      return
     }
 
     if (task.status === "completed") {
-      callback(taskIdOrCallback, task.result);
-      return;
+      safeInvokeCallback(callback, taskIdOrCallback, task.result)
+      return
     }
 
-    task.callbacks.add(callback);
+    task.callbacks.add(callback)
   }
 
   function getActiveCount(): number {
-    let activeCount = 0;
+    let activeCount = 0
 
     for (const task of tasks.values()) {
       if (task.status === "queued" || task.status === "running") {
-        activeCount += 1;
+        activeCount += 1
       }
     }
 
-    return activeCount;
+    return activeCount
   }
 
   return {
@@ -196,5 +202,5 @@ export function createBackgroundManager(
     getResult,
     onComplete,
     getActiveCount,
-  };
+  }
 }

package/src/features/background-agent/index.ts

@@ -1 +1 @@
-export * from "./background-manager";
+export * from "./background-manager"

package/src/features/context-monitor/context-monitor.ts

@@ -1,8 +1,8 @@
-import type { AuditState } from "../../state/types"
 import { createLogger } from "../../shared/logger"
+import type { AuditState } from "../../state/types"
 
 const DEFAULT_MAX_TOKENS = 200_000
-const REMINDER_THRESHOLD = 0.70
+const REMINDER_THRESHOLD = 0.7
 const COMPACTION_THRESHOLD = 0.85
 
 export interface ContextMonitorConfig {
@@ -19,7 +19,7 @@ export function createContextMonitor(config: ContextMonitorConfig = {}) {
 
   function getContextStatus(
     systemText: string,
-    auditState: AuditState | null,
+    _auditState: AuditState | null,
   ): { usage: number; reminder: string | null; shouldCompact: boolean } {
     const tokens = estimateTokens(systemText)
     const usage = tokens / maxTokens

package/src/features/context-monitor/index.ts

@@ -1,4 +1,4 @@
-export { createContextMonitor } from "./context-monitor"
 export type { ContextMonitorConfig } from "./context-monitor"
-export { createToolOutputTruncator } from "./tool-output-truncator"
+export { createContextMonitor } from "./context-monitor"
 export type { TruncatorConfig } from "./tool-output-truncator"
+export { createToolOutputTruncator } from "./tool-output-truncator"

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

@@ -1,10 +1,8 @@
-import type { AuditState } from "../../state/types"
 import type { AuditStateManager } from "../../managers/types"
 import { createLogger } from "../../shared/logger"
+import type { AuditState } from "../../state/types"
 
-export function createSessionRecoveryHandler(
-  auditStateManager: AuditStateManager,
-) {
+export function createSessionRecoveryHandler(auditStateManager: AuditStateManager) {
   const logger = createLogger()
 
   return async (event: {