solidity-argus 0.1.8 → 0.3.0

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

@@ -0,0 +1,118 @@
+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 { cliOutput } from "../cli-output"
+
+const GREEN = "\x1b[32m"
+const RED = "\x1b[31m"
+const RESET = "\x1b[0m"
+
+function findSkillFiles(dir: string, maxDepth = 8): string[] {
+  const files: string[] = []
+  const stack: Array<{ path: string; depth: number }> = [{ path: dir, depth: 0 }]
+
+  while (stack.length > 0) {
+    const current = stack.pop()
+    if (!current || current.depth > maxDepth) continue
+
+    try {
+      const entries = readdirSync(current.path, { withFileTypes: true })
+      for (const entry of entries) {
+        const fullPath = join(current.path, entry.name)
+        if (entry.isDirectory()) {
+          stack.push({ path: fullPath, depth: current.depth + 1 })
+        } else if (entry.isFile() && entry.name.toUpperCase() === "SKILL.MD") {
+          files.push(fullPath)
+        }
+      }
+    } catch {}
+  }
+
+  return files
+}
+
+export interface LintResult {
+  valid: number
+  invalid: number
+  skipped: number
+  errors: Array<{ file: string; errors: string[] }>
+}
+
+export function lintSkillFiles(skillFiles: Array<{ path: string; content: string }>): LintResult {
+  let valid = 0
+  let invalid = 0
+  let skipped = 0
+  const errors: Array<{ file: string; errors: string[] }> = []
+
+  for (const { path, content } of skillFiles) {
+    const fm = parseFrontmatter(content)
+    if (!fm) {
+      skipped++
+      continue
+    }
+
+    const result = validateSkillFrontmatter(fm)
+    if (result.success) {
+      valid++
+    } else {
+      invalid++
+      errors.push({ file: path, errors: result.errors })
+    }
+  }
+
+  return { valid, invalid, skipped, errors }
+}
+
+export const lintSkillsCommand: CliCommand = {
+  name: "lint-skills",
+  description: "Validate all SKILL.md files against schema",
+  async execute(): Promise<number> {
+    const cwd = process.cwd()
+    let config: ReturnType<typeof loadArgusConfig> | undefined
+    try {
+      config = loadArgusConfig(cwd)
+    } catch {
+      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 = findSkillFiles(root.path)
+      for (const file of files) {
+        try {
+          skillFiles.push({ path: file, content: readFileSync(file, "utf8") })
+        } catch {
+          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)`,
+    )
+
+    if (result.errors.length > 0) {
+      for (const { file, errors } of result.errors) {
+        cliOutput.log(`\n${RED}✗${RESET} ${file}`)
+        for (const err of errors) {
+          cliOutput.log(`  - ${err}`)
+        }
+      }
+    } else if (result.valid > 0) {
+      cliOutput.log(`${GREEN}✓${RESET} All skills pass schema validation`)
+    }
+
+    return result.invalid > 0 ? 1 : 0
+  },
+}

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/tui-prompts.ts

@@ -1,3 +1,5 @@
+import { cliOutput } from "./cli-output"
+
 const NON_INTERACTIVE =
   !process.stdin.isTTY || process.env.CI === "true" || process.env.ARGUS_NON_INTERACTIVE === "true"
 
@@ -29,10 +31,10 @@ export async function select(
 ): Promise<string> {
   if (NON_INTERACTIVE) return options[defaultIndex] ?? options[0] ?? ""
 
-  console.log(message)
+  cliOutput.log(message)
   for (let i = 0; i < options.length; i++) {
     const marker = i === defaultIndex ? ">" : " "
-    console.log(`  ${marker} ${i + 1}. ${options[i]}`)
+    cliOutput.log(`  ${marker} ${i + 1}. ${options[i]}`)
   }
 
   return new Promise((resolve) => {

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(),
 })
@@ -23,17 +24,16 @@ const KnowledgeConfigSchema = z.object({
   }),
   autoSync: z.boolean().default(true),
   customSkillsDir: z.string().optional(),
+  skillPrecedence: z.enum(["bundled-first", "custom-first"]).default("bundled-first"),
 })
 
 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),
 })
@@ -63,13 +63,14 @@ export const ArgusConfigSchema = z.object({
       apiUrl: "https://api.scvd.dev",
     },
     autoSync: true,
+    skillPrecedence: "bundled-first",
   }),
   reporting: ReportingConfigSchema.default({
     format: "markdown",
     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,25 +1,71 @@
+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 { 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 { createToolTrackingHook } from "./hooks/tool-tracking-hook"
-import { createEventHookV2 } from "./hooks/event-hook-v2"
+import { createConfigHandler } from "./hooks/config-handler"
+import { getTokenBudgetForAgent } from "./hooks/context-budget"
+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 { createToolOutputTruncator } from "./features/context-monitor"
-import { createSessionRecoveryHandler } from "./features/error-recovery"
-import { createToolErrorRecoveryHandler } from "./features/error-recovery"
+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"
+
+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 _agentTrackerRef?.getAgentForSession(sessionID)
+}
+
+export function isArgusAgent(sessionID: string): boolean {
+  return _agentTrackerRef?.isArgusAgent(sessionID) ?? false
+}
 
 export type Hooks = Pick<
   PluginHooks,
   | "config"
+  | "chat.params"
+  | "chat.message"
   | "experimental.chat.system.transform"
   | "experimental.session.compacting"
   | "tool.execute.after"
   | "event"
 >
 
+/**
+ * Creates the hook handlers for the Argus plugin.
+ *
+ * Context Delivery Strategy:
+ * - Prompt: Static agent identity (src/agents/*-prompt.ts) — methodology, personality, tool instructions
+ * - Hook: Dynamic state injection via experimental.chat.system.transform — audit progress, findings, phase
+ * - Skill-load: On-demand knowledge via argus_skill_load tool — vulnerability patterns, protocol knowledge
+ *
+ * The system.transform hook injects dynamic audit context only for Argus-family agents
+ * (argus, sentinel, pythia, scribe). Non-audit agents receive no injection.
+ */
 export function createHooks(args: {
   config: ArgusConfig
   managers: Managers
@@ -28,28 +74,118 @@ export function createHooks(args: {
 }): Hooks {
   const { config, managers, projectDir, isHookEnabled } = args
   const { auditStateManager, backgroundManager } = managers
+  const agentTracker = createAgentTracker()
+  _agentTrackerRef = agentTracker
 
-   const sessionRecoveryHandler = createSessionRecoveryHandler(auditStateManager)
-   const toolErrorRecoveryHandler = createToolErrorRecoveryHandler()
-   const outputTruncator = createToolOutputTruncator()
+  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,
+    (patch) => auditStateManager.update(patch),
+  )
+  const outputTruncator = createToolOutputTruncator()
 
-  const { hook: eventHook, getAuditState, setAuditState } = createEventHookV2(projectDir, [
-    async ({ type, auditState, setAuditState: setState }) => {
+  // 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
       }
 
       if (type === "session.deleted") {
-        await auditStateManager.reset()
+        if (sessionId) {
+          agentTracker.clearSession(sessionId)
+        }
+
+        await auditStateManager.archive()
+        runJournal.log({
+          type: "session.deleted",
+          timestamp: Date.now(),
+          archived: true,
+        })
       }
     },
     async ({ type, sessionId, setAuditState: setState }) => {
@@ -62,26 +198,88 @@ export function createHooks(args: {
     },
   ])
 
-   const initialState = auditStateManager.get()
-   if (initialState) {
-     setAuditState(initialState)
-   }
+  auditStateGetter = getAuditState
+
+  const initialState = auditStateManager.get()
+  if (initialState) {
+    setAuditState(initialState)
+  }
+
+  const auditEnforcer = createAuditEnforcer()
+
+  const systemPromptHook = createSystemPromptHook({
+    getAuditState,
+    getAgentForSession: agentTracker.getAgentForSession,
+    isArgusAgent: agentTracker.isArgusAgent,
+    getContextPressure: (systemText: string) => {
+      const status = contextMonitor.getContextStatus(systemText, getAuditState())
+      return status.usage
+    },
+    getTokenBudget: getTokenBudgetForAgent,
+    getEnforcerReminder: auditEnforcer,
+    getReconBlock: () =>
+      buildReconContextBlock({
+        projectConfig: reconProjectConfig,
+        dependencyRisks: reconProjectConfig?.dependencyRisks ?? [],
+        auditArtifacts: detectAuditArtifacts(projectDir),
+      }),
+  })
+
+  let reconProjectConfig: ProjectConfig | null = null
+
+  detectProject(projectDir)
+    .then((config) => {
+      reconProjectConfig = config
+    })
+    .catch(() => {
+      logger.debug("Project detection failed, using fallback recon context")
+    })
 
-   const compactionHook = isHookEnabled("compaction")
-    ? safeCreateHook(() => createCompactionHook(getAuditState), "compaction")
+  const getReconContext = (): ReconContext => ({
+    projectConfig: reconProjectConfig,
+    dependencyRisks: reconProjectConfig?.dependencyRisks ?? [],
+    auditArtifacts: detectAuditArtifacts(projectDir),
+  })
+
+  const compactionHook = isHookEnabled("compaction")
+    ? safeCreateHook(() => createCompactionHook(getAuditState, getReconContext), "compaction")
     : 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")
     ? safeCreateHook(() => eventHook, "event")
     : undefined
 
-   return {
-     config: createConfigHandler(config, projectDir),
-     "experimental.chat.system.transform": undefined,
+  return {
+    config: createConfigHandler(config, projectDir),
+    "chat.params": async (input) => {
+      agentTracker.chatParamsHook(input)
+    },
+    "chat.message": async (input) => {
+      agentTracker.chatMessageHook(input)
+    },
+    "experimental.chat.system.transform": async (input, output) => {
+      await systemPromptHook(input, output)
+    },
     "experimental.session.compacting": compactionHook
       ? async (_input, output) => {
           const block = await compactionHook({ summary: output.context.join("\n") })
@@ -101,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,29 +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"
 
-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