solidity-argus 0.2.0 → 0.3.0

package/src/cli/commands/init.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
-import type { CliCommand } from "../types"
 import { cliOutput } from "../cli-output"
+import type { CliCommand } from "../types"
 
 const GREEN = "\x1b[32m"
 const YELLOW = "\x1b[33m"
@@ -18,13 +18,15 @@ const DEFAULT_CONFIG = {
 export const initCommand: CliCommand = {
   name: "init",
   description: "Initialize Argus configuration for this project",
-  async execute(args: string[]): Promise<number> {
+  async execute(_args: string[]): Promise<number> {
     const cwd = process.cwd()
     const configDir = join(cwd, ".opencode")
     const configPath = join(configDir, "solidity-argus.json")
 
     if (existsSync(configPath)) {
-      cliOutput.error(`${YELLOW}⚠${RESET} Config already exists: ${configPath} — remove it first if you want to reinitialize.`)
+      cliOutput.error(
+        `${YELLOW}⚠${RESET} Config already exists: ${configPath} — remove it first if you want to reinitialize.`,
+      )
       return 1
     }
 

package/src/cli/commands/install.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs"
-import { join } from "node:path"
 import { homedir } from "node:os"
-import type { CliCommand } from "../types"
+import { join } from "node:path"
 import { cliOutput } from "../cli-output"
+import type { CliCommand } from "../types"
 
 const GREEN = "\x1b[32m"
 const YELLOW = "\x1b[33m"
@@ -23,11 +23,13 @@ export function findOpencodeConfig(homeOverride?: string): string | null {
 export const installCommand: CliCommand = {
   name: "install",
   description: "Register solidity-argus in your OpenCode config",
-  async execute(args: string[]): Promise<number> {
+  async execute(_args: string[]): Promise<number> {
     const configPath = findOpencodeConfig()
 
     if (!configPath) {
-      cliOutput.error(`${YELLOW}⚠${RESET} opencode.json not found — create one first, or run: opencode init`)
+      cliOutput.error(
+        `${YELLOW}⚠${RESET} opencode.json not found — create one first, or run: opencode init`,
+      )
       return 1
     }
 
@@ -47,7 +49,7 @@ export const installCommand: CliCommand = {
 
       cliOutput.log(`${GREEN}✓${RESET} Added solidity-argus to ${configPath}`)
       return 0
-    } catch (error) {
+    } catch (_error) {
       cliOutput.error(`${YELLOW}⚠${RESET} Failed to update ${configPath}`)
       return 1
     }

package/src/cli/commands/lint-skills.ts

@@ -1,16 +1,20 @@
-import { readFileSync, readdirSync } from "node:fs"
-import { extname, join } from "node:path"
+import { readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { createLogger } from "../../shared/logger"
 import type { CliCommand } from "../types"
+
+const logger = createLogger()
+
+import { loadArgusConfig } from "../../config/loader"
 import { resolveSkillRoots } from "../../skills/argus-skill-resolver"
 import { parseFrontmatter, validateSkillFrontmatter } from "../../skills/skill-schema"
-import { loadArgusConfig } from "../../config/loader"
 import { cliOutput } from "../cli-output"
 
 const GREEN = "\x1b[32m"
 const RED = "\x1b[31m"
 const RESET = "\x1b[0m"
 
-function findMarkdownFiles(dir: string, maxDepth = 8): string[] {
+function findSkillFiles(dir: string, maxDepth = 8): string[] {
   const files: string[] = []
   const stack: Array<{ path: string; depth: number }> = [{ path: dir, depth: 0 }]
 
@@ -24,13 +28,11 @@ function findMarkdownFiles(dir: string, maxDepth = 8): string[] {
         const fullPath = join(current.path, entry.name)
         if (entry.isDirectory()) {
           stack.push({ path: fullPath, depth: current.depth + 1 })
-        } else if (entry.isFile() && extname(entry.name).toLowerCase() === ".md") {
+        } else if (entry.isFile() && entry.name.toUpperCase() === "SKILL.MD") {
           files.push(fullPath)
         }
       }
-    } catch {
-      continue
-    }
+    } catch {}
   }
 
   return files
@@ -77,26 +79,28 @@ export const lintSkillsCommand: CliCommand = {
     try {
       config = loadArgusConfig(cwd)
     } catch {
-      // fallback to undefined, resolveSkillRoots handles this
+      logger.debug("Config load failed, using defaults")
     }
 
     const roots = resolveSkillRoots(cwd, config)
     const skillFiles: Array<{ path: string; content: string }> = []
 
     for (const root of roots) {
-      const files = findMarkdownFiles(root.path)
+      const files = findSkillFiles(root.path)
       for (const file of files) {
         try {
           skillFiles.push({ path: file, content: readFileSync(file, "utf8") })
         } catch {
-          // continue on read errors
+          logger.debug("Skipping unreadable skill file")
         }
       }
     }
 
     const result = lintSkillFiles(skillFiles)
 
-    cliOutput.log(`Skill Lint: ${result.valid} valid, ${result.invalid} invalid, ${result.skipped} skipped (no frontmatter)`)
+    cliOutput.log(
+      `Skill Lint: ${result.valid} valid, ${result.invalid} invalid, ${result.skipped} skipped (no frontmatter)`,
+    )
 
     if (result.errors.length > 0) {
       for (const { file, errors } of result.errors) {

package/src/cli/index.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
-import { createCliProgram } from "./cli-program";
+import { createCliProgram } from "./cli-program"
 
-const program = createCliProgram();
-const args = Bun.argv.slice(2);
-const exitCode = await program.dispatch(args);
+const program = createCliProgram()
+const args = Bun.argv.slice(2)
+const exitCode = await program.dispatch(args)
 
 // Set exit code without process.exit() so stdout flushes before termination
-process.exitCode = exitCode;
+process.exitCode = exitCode

package/src/cli/types.ts

@@ -3,7 +3,7 @@
  * Defines the contract for all CLI subcommands
  */
 export interface CliCommand {
-  name: string;
-  description: string;
-  execute: (args: string[]) => Promise<number>;
+  name: string
+  description: string
+  execute: (args: string[]) => Promise<number>
 }

package/src/config/index.ts

@@ -1,3 +1,3 @@
+export { loadArgusConfig } from "./loader"
 export { ArgusConfigSchema } from "./schema"
 export type { ArgusConfig } from "./types"
-export { loadArgusConfig } from "./loader"

package/src/config/loader.ts

@@ -1,10 +1,10 @@
 import { homedir } from "node:os"
 import { join } from "node:path"
-import { ArgusConfigSchema } from "./schema"
-import type { ArgusConfig } from "./types"
-import { detectConfigFile, readJsoncFile } from "../shared/file-utils"
 import { deepMerge } from "../shared/deep-merge"
+import { detectConfigFile, readJsoncFile } from "../shared/file-utils"
 import { createLogger } from "../shared/logger"
+import { ArgusConfigSchema } from "./schema"
+import type { ArgusConfig } from "./types"
 
 export function _mergeConfigs(
   userRaw: Record<string, unknown> | null,
@@ -28,9 +28,7 @@ export function loadArgusConfig(projectDir: string): ArgusConfig {
   const userRaw = userConfigInfo.path ? readJsoncFile(userConfigInfo.path) : null
 
   const projectConfigInfo = detectConfigFile(projectDir)
-  const projectRaw = projectConfigInfo.path
-    ? readJsoncFile(projectConfigInfo.path)
-    : null
+  const projectRaw = projectConfigInfo.path ? readJsoncFile(projectConfigInfo.path) : null
 
   return _mergeConfigs(userRaw, projectRaw)
 }

package/src/config/schema.ts

@@ -2,6 +2,7 @@ import { z } from "zod"
 
 const AgentConfigSchema = z.object({
   model: z.string().optional(),
+  steps: z.number().positive().optional(),
   permission: z.record(z.string(), z.any()).optional(),
   tools: z.record(z.string(), z.boolean()).optional(),
 })
@@ -28,13 +29,11 @@ const KnowledgeConfigSchema = z.object({
 
 const ReportingConfigSchema = z.object({
   format: z.enum(["markdown"]).default("markdown"),
-  severityThreshold: z
-    .enum(["critical", "high", "medium", "low", "informational"])
-    .default("low"),
+  severityThreshold: z.enum(["critical", "high", "medium", "low", "informational"]).default("low"),
   gasAnalysis: z.boolean().default(false),
 })
 
-const SolditConfigSchema = z.object({
+const SoloditConfigSchema = z.object({
   enabled: z.boolean().default(true),
   port: z.number().default(3000),
 })
@@ -71,7 +70,7 @@ export const ArgusConfigSchema = z.object({
     severityThreshold: "low",
     gasAnalysis: false,
   }),
-  solodit: SolditConfigSchema.default({
+  solodit: SoloditConfigSchema.default({
     enabled: true,
     port: 3000,
   }),

package/src/config/types.ts

@@ -1,4 +1,4 @@
-import { z } from "zod"
-import { ArgusConfigSchema } from "./schema"
+import type { z } from "zod"
+import type { ArgusConfigSchema } from "./schema"
 
 export type ArgusConfig = z.infer<typeof ArgusConfigSchema>

package/src/constants/defaults.ts

@@ -4,3 +4,5 @@ export const DEFAULT_MODELS = {
   pythia: "anthropic/claude-sonnet-4-6",
   scribe: "anthropic/claude-sonnet-4-6",
 } as const
+
+export const DEFAULT_STEPS = 50 as const

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