solidity-argus 0.1.7 → 0.2.0

package/src/hooks/context-budget.ts

@@ -0,0 +1,45 @@
+/**
+ * Context budget allocation for Argus agents.
+ *
+ * Provides per-agent token budgets for system-prompt injection sizing.
+ * Under context pressure (>70%), budgets are reduced by 50% to prevent
+ * context window overflow during long audits.
+ *
+ * Decoupled from system-prompt-hook.ts — consumed by the hook when available.
+ */
+
+const ARGUS_BUDGET = 2000
+const SUBAGENT_BUDGET = 1000
+const PRESSURE_THRESHOLD = 0.70
+const PRESSURE_REDUCTION = 0.5
+
+const ARGUS_AGENTS = new Set(["argus"])
+const SUBAGENTS = new Set(["sentinel", "pythia", "scribe"])
+
+/**
+ * Returns the token budget for a given agent, adjusted for context pressure.
+ *
+ * @param agent - Agent name (e.g. "argus", "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 {
+  let budget: number
+
+  if (ARGUS_AGENTS.has(agent)) {
+    budget = ARGUS_BUDGET
+  } else if (SUBAGENTS.has(agent)) {
+    budget = SUBAGENT_BUDGET
+  } else {
+    return 0
+  }
+
+  if (contextPressure > PRESSURE_THRESHOLD) {
+    budget = Math.floor(budget * PRESSURE_REDUCTION)
+  }
+
+  return budget
+}

package/src/hooks/event-hook-v2.ts

@@ -1,4 +1,4 @@
-import type { AuditState, AuditPhase } from "../state/types"
+import type { AuditState } from "../state/types"
 import { createAuditState } from "../state/audit-state"
 import { createLogger } from "../shared/logger"
 
@@ -19,6 +19,7 @@ export type EventSubHandler = (event: {
   type: string
   sessionId?: string
   auditState: AuditState | null
+  setAuditState: (state: AuditState | null) => void
 }) => Promise<void>
 
 export function createEventHookV2(
@@ -82,7 +83,12 @@ export function createEventHookV2(
 
     for (const handler of subHandlers) {
       try {
-        await handler({ type, sessionId, auditState: currentAuditState })
+        await handler({
+          type,
+          sessionId,
+          auditState: currentAuditState,
+          setAuditState,
+        })
       } catch (error) {
         logger.error(`Sub-handler failed for event ${type}:`, error)
       }

package/src/hooks/event-hook.ts

@@ -1,5 +1,6 @@
 import type { AuditState } from "../state/types"
 import { createAuditState } from "../state/audit-state"
+import { createLogger } from "../shared/logger"
 
 export type EventHookFn = (input: {
   event: { type: string; sessionId?: string }
@@ -38,8 +39,8 @@ export function createEventHook(projectDir?: string): {
 
       case "session.idle": {
          if (currentAuditState) {
-           console.error(
-             `[argus-state] Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}, contracts: ${currentAuditState.contractsReviewed.length}`
+           createLogger().debug(
+             `[state] Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}, contracts: ${currentAuditState.contractsReviewed.length}`
            )
          }
          break
@@ -47,8 +48,8 @@ export function createEventHook(projectDir?: string): {
 
       case "session.error": {
         if (currentAuditState) {
-          console.error(
-            `[argus-error] Session error — state snapshot: ${JSON.stringify({
+          createLogger().error(
+            `Session error — state snapshot: ${JSON.stringify({
               sessionId: currentAuditState.sessionId,
               phase: currentAuditState.currentPhase,
               findingsCount: currentAuditState.findings.length,

package/src/hooks/knowledge-sync-hook.ts

@@ -3,6 +3,7 @@ import path from "node:path"
 import { ScvdClient } from "../knowledge/scvd-client"
 import { syncIncremental, type SyncResult } from "../knowledge/scvd-sync"
 import type { ArgusConfig } from "../config/types"
+import { createLogger } from "../shared/logger"
 
 export type KnowledgeSyncDependencies = {
   createClient?: (apiUrl: string) => unknown
@@ -18,7 +19,7 @@ function defaultDependencies(): Required<KnowledgeSyncDependencies> {
     syncIncrementalFn: async (client: unknown, indexPath: string) =>
       syncIncremental(client as ScvdClient, indexPath),
     log: (message: string) => {
-       console.error(message)
+       createLogger().info(message)
      },
   }
 }

package/src/hooks/recon-context-builder.ts

@@ -0,0 +1,66 @@
+import type { ProjectConfig } from "../utils/project-detector"
+import type { DependencyRisk } from "../utils/dependency-scanner"
+import type { AuditArtifact } from "../utils/audit-artifact-detector"
+
+export interface ReconContext {
+  projectConfig: ProjectConfig | null
+  dependencyRisks: DependencyRisk[]
+  auditArtifacts: AuditArtifact[]
+}
+
+/**
+ * Builds an XML-like reconnaissance context block from project data.
+ * Returns null if no data is available (all fields empty/null).
+ *
+ * The block is injected into compaction output so Argus agents retain
+ * project intelligence across context window compressions.
+ */
+export function buildReconContextBlock(recon: ReconContext): string | null {
+  if (
+    !recon.projectConfig &&
+    recon.dependencyRisks.length === 0 &&
+    recon.auditArtifacts.length === 0
+  ) {
+    return null
+  }
+
+  const lines: string[] = ["<argus-recon>"]
+
+  if (recon.projectConfig) {
+    const frameworks: string[] = []
+    if (recon.projectConfig.hasFoundry) frameworks.push("Foundry")
+    if (recon.projectConfig.hasHardhat) frameworks.push("Hardhat")
+    if (frameworks.length > 0) {
+      lines.push(`Framework: ${frameworks.join(", ")}`)
+    }
+    if (recon.projectConfig.optimizer) {
+      lines.push(`Optimizer: runs=${recon.projectConfig.optimizer.runs}`)
+    }
+    if (recon.projectConfig.evmVersion) {
+      lines.push(`EVM Version: ${recon.projectConfig.evmVersion}`)
+    }
+    if (recon.projectConfig.isUpgradeable) {
+      lines.push(`Upgradeable: yes`)
+    }
+    if (recon.projectConfig.profiles && recon.projectConfig.profiles.length > 0) {
+      lines.push(`Profiles: ${recon.projectConfig.profiles.join(", ")}`)
+    }
+  }
+
+  if (recon.dependencyRisks.length > 0) {
+    lines.push("Dependency Risks:")
+    for (const risk of recon.dependencyRisks.slice(0, 5)) {
+      lines.push(`  - ${risk.package}@${risk.version}: ${risk.risk}`)
+    }
+  }
+
+  if (recon.auditArtifacts.length > 0) {
+    lines.push("Existing Audit Artifacts:")
+    for (const artifact of recon.auditArtifacts.slice(0, 5)) {
+      lines.push(`  - ${artifact.type}: ${artifact.path}`)
+    }
+  }
+
+  lines.push("</argus-recon>")
+  return lines.join("\n")
+}

package/src/hooks/safe-create-hook.ts

@@ -1,3 +1,5 @@
+import { createLogger } from "../shared/logger"
+
 export function safeCreateHook<T>(
   factory: () => T,
   hookName: string
@@ -5,11 +7,8 @@ export function safeCreateHook<T>(
   try {
     return factory();
   } catch (error) {
-    console.error(
-      `[argus-hook-error] Failed to create hook "${hookName}": ${
-        error instanceof Error ? error.message : String(error)
-      }`
-    );
+    const logger = createLogger()
+    logger.error(`Failed to create hook "${hookName}": ${error instanceof Error ? error.message : String(error)}`)
     return undefined;
   }
 }

package/src/hooks/system-prompt-hook.ts

@@ -1,257 +1,128 @@
-import { existsSync, readdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
-import type { ArgusConfig } from "../config/types";
-import type { AuditState, FindingSeverity } from "../state/types";
-
-interface SystemPromptInput {
-  system: string;
-  cwd: string;
+import type { AuditState, FindingSeverity } from "../state/types"
+
+const DEFAULT_TOKEN_BUDGET = 2000
+const TOKENS_PER_CHAR = 4
+
+export interface SystemPromptHookDeps {
+  getAuditState: () => AuditState | null
+  getAgentForSession: (sessionID: string) => string | undefined
+  isArgusAgent: (sessionID: string) => boolean
+  getContextPressure?: (systemText: string) => number
+  getTokenBudget?: (agent: string, contextPressure: number) => number
+  getEnforcerReminder?: (state: AuditState) => string | null
+  getReconBlock?: () => string | null
 }
 
-interface SkillIndexEntry {
-  count: number;
-  sample: string[];
+const FALLBACK_DIRECTIVES: Record<string, string> = {
+  slither:
+    "DO NOT re-attempt argus_slither_analyze. Use `argus_analyze_contract` and `argus_check_patterns` instead. Note limitation in report.",
+  forge:
+    "DO NOT re-attempt argus_forge_test or argus_forge_fuzz. Verify findings via manual code tracing. Note limitation in report.",
+  solodit:
+    "DO NOT re-attempt argus_solodit_search. Use `argus_check_patterns` with local rules. Note limitation in report.",
 }
 
-interface SkillIndexSnapshot {
-  bundled: SkillIndexEntry;
-  trailOfBits: SkillIndexEntry;
-  custom: SkillIndexEntry;
+export function buildFallbackDirectives(unavailableTools: string[]): string[] {
+  const directives: string[] = []
+  for (const tool of unavailableTools) {
+    const directive = FALLBACK_DIRECTIVES[tool]
+    if (directive) directives.push(directive)
+  }
+  return directives
 }
 
-const TOB_CACHE_DIR = join(homedir(), ".cache", "solidity-argus", "trailofbits-skills");
-
-/**
- * Checks if the given directory contains a Solidity project
- * by looking for foundry.toml or hardhat.config.{js,ts}
- */
-async function isSolidityProject(cwd: string): Promise<boolean> {
-  const checks = [
-    Bun.file(join(cwd, "foundry.toml")).exists(),
-    Bun.file(join(cwd, "hardhat.config.js")).exists(),
-    Bun.file(join(cwd, "hardhat.config.ts")).exists(),
-  ];
-
-  const results = await Promise.all(checks);
-  return results.some(Boolean);
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / TOKENS_PER_CHAR)
 }
 
-/**
- * Counts findings by severity from the audit state
- */
-function countFindingsBySeverity(
-  findings: AuditState["findings"]
-): Record<FindingSeverity, number> {
-  const counts: Record<FindingSeverity, number> = {
+export function buildDynamicContext(
+  auditState: AuditState,
+  agent: string,
+  tokenBudget: number = DEFAULT_TOKEN_BUDGET,
+): string {
+  const severityCounts: Record<FindingSeverity, number> = {
     Critical: 0,
     High: 0,
     Medium: 0,
     Low: 0,
     Informational: 0,
-  };
-
-  for (const finding of findings) {
-    counts[finding.severity]++;
   }
 
-  return counts;
-}
-
-/**
- * Builds the audit state summary section for the injected context
- */
-function buildAuditStateSummary(state: AuditState | null): string {
-  if (!state) {
-    return "No active audit session. Use @argus to start an audit.";
+  for (const finding of auditState.findings) {
+    severityCounts[finding.severity]++
   }
 
-  const counts = countFindingsBySeverity(state.findings);
-  const scopeList =
-    state.scope.length > 0 ? state.scope.join(", ") : "not defined";
-  const reviewedList =
-    state.contractsReviewed.length > 0
-      ? state.contractsReviewed.join(", ")
-      : "none yet";
-
-  return [
-    `Phase: ${state.currentPhase}`,
-    `Scope: ${scopeList}`,
-    `Contracts reviewed: ${reviewedList}`,
-    `Findings: ${state.findings.length} total — Critical: ${counts.Critical}, High: ${counts.High}, Medium: ${counts.Medium}, Low: ${counts.Low}, Info: ${counts.Informational}`,
-  ].join("\n");
-}
-
-function collectSkillNamesFromRoot(rootPath: string): string[] {
-  if (!existsSync(rootPath)) {
-    return [];
+  const tools = auditState.toolsExecuted.map((tool) => tool.tool).join(", ") || "none"
+  const unavailable = auditState.unavailableTools ?? []
+  const lines: string[] = [
+    `<argus-context agent="${agent}">`,
+    `Phase: ${auditState.currentPhase}`,
+    `Contracts: ${auditState.contractsReviewed.length} reviewed`,
+    `Findings: Critical=${severityCounts.Critical} High=${severityCounts.High} Medium=${severityCounts.Medium} Low=${severityCounts.Low} Info=${severityCounts.Informational}`,
+    `Tools: ${tools}`,
+  ]
+
+  if (unavailable.length > 0) {
+    lines.push(`Unavailable: ${unavailable.join(", ")}`)
+    lines.push(...buildFallbackDirectives(unavailable))
   }
 
-  const rootEntries = readdirSync(rootPath, { withFileTypes: true });
-  const names = new Set<string>();
+  lines.push("</argus-context>")
 
-  for (const rootEntry of rootEntries) {
-    if (!rootEntry.isDirectory()) continue;
+  let summary = lines.join("\n")
 
-    const directSkill = join(rootPath, rootEntry.name, "SKILL.md");
-    if (existsSync(directSkill)) {
-      names.add(rootEntry.name);
-      continue;
-    }
-
-    const categoryDir = join(rootPath, rootEntry.name);
-    const categoryEntries = readdirSync(categoryDir, { withFileTypes: true });
-
-    for (const categoryEntry of categoryEntries) {
-      if (!categoryEntry.isDirectory()) continue;
-      const categorySkill = join(categoryDir, categoryEntry.name, "SKILL.md");
-      if (existsSync(categorySkill)) {
-        names.add(`${rootEntry.name}/${categoryEntry.name}`);
-      }
-    }
+  if (estimateTokens(summary) > tokenBudget) {
+    summary = [
+      `<argus-context agent="${agent}">`,
+      `Phase: ${auditState.currentPhase} | Findings: ${auditState.findings.length} | Contracts: ${auditState.contractsReviewed.length}`,
+      "</argus-context>",
+    ].join("\n")
   }
 
-  return Array.from(names).sort();
+  return summary
 }
 
-function getTrailOfBitsSkillRoots(): string[] {
-  const pluginsDir = join(TOB_CACHE_DIR, "plugins");
-  if (!existsSync(pluginsDir)) {
-    return [];
-  }
-
-  const pluginEntries = readdirSync(pluginsDir, { withFileTypes: true });
-  const roots: string[] = [];
-
-  for (const pluginEntry of pluginEntries) {
-    if (!pluginEntry.isDirectory()) continue;
-    const pluginSkillsRoot = join(pluginsDir, pluginEntry.name, "skills");
-    if (existsSync(pluginSkillsRoot)) {
-      roots.push(pluginSkillsRoot);
+export function createSystemPromptHook(deps: SystemPromptHookDeps) {
+  return async (
+    input: { sessionID?: string; model: unknown },
+    output: { system: string[] },
+  ): Promise<void> => {
+    if (!input.sessionID) {
+      return
     }
-  }
 
-  return roots;
-}
-
-function toSkillIndexEntry(skillNames: string[]): SkillIndexEntry {
-  return {
-    count: skillNames.length,
-    sample: skillNames.slice(0, 3),
-  };
-}
-
-function buildSkillIndexSnapshot(args: {
-  argusConfig?: ArgusConfig;
-  projectDir?: string;
-}): SkillIndexSnapshot {
-  const bundledRoot = resolve(import.meta.dir, "../../skills");
-  const bundledSkills = collectSkillNamesFromRoot(bundledRoot);
-
-  const trailOfBitsSkills = new Set<string>();
-  for (const tobRoot of getTrailOfBitsSkillRoots()) {
-    for (const name of collectSkillNamesFromRoot(tobRoot)) {
-      trailOfBitsSkills.add(name);
+    if (!deps.isArgusAgent(input.sessionID)) {
+      return
     }
-  }
-
-  const customDir = args.argusConfig?.knowledge?.customSkillsDir;
-  const customRoot = customDir
-    ? customDir.startsWith("/")
-      ? customDir
-      : resolve(args.projectDir ?? process.cwd(), customDir)
-    : undefined;
-  const customSkills = customRoot ? collectSkillNamesFromRoot(customRoot) : [];
-
-  return {
-    bundled: toSkillIndexEntry(bundledSkills),
-    trailOfBits: toSkillIndexEntry(Array.from(trailOfBitsSkills).sort()),
-    custom: toSkillIndexEntry(customSkills),
-  };
-}
-
-function formatSkillSample(entry: SkillIndexEntry): string {
-  return entry.sample.length > 0 ? entry.sample.join(", ") : "none";
-}
-
-/**
- * Builds the full audit context block to inject into the system prompt.
- * Designed to be concise (500-800 tokens).
- */
-function buildAuditContextBlock(
-  state: AuditState | null,
-  skillIndex: SkillIndexSnapshot
-): string {
-  return `
-<argus-context>
-## Solidity Audit Context
-
-### Severity Classification
-- **Critical**: Direct theft/freezing of funds, unauthorized admin access, contract destruction
-- **High**: Indirect fund loss, business logic manipulation, DoS on critical functions
-- **Medium**: Degraded functionality, edge-case bugs, partial DoS, poor validation
-- **Low**: Code quality issues, suboptimal patterns, missing events, minor logic issues
-- **Informational**: Gas optimizations, style suggestions, best practices, non-security notes
 
-### Available Argus Tools
-- \`argus_slither_analyze\`: Run Slither static analysis on Solidity codebase
-- \`argus_forge_test\`: Execute Foundry/Forge tests for vulnerability verification
-- \`argus_forge_fuzz\`: Fuzz specific functions to discover edge cases
-- \`argus_analyze_contract\`: Generate deep structural profile of a contract
-- \`argus_check_patterns\`: Scan code against known vulnerability pattern library
-- \`argus_solodit_search\`: Search real-world audit reports and known vulnerabilities
-- \`argus_generate_report\`: Compile findings into structured audit report
-- \`argus_sync_knowledge\`: Update local vulnerability database (SCVD)
-
-### Available Skills
-- \`vulnerability-patterns/*\`: 35+ exploit classes (reentrancy, oracle manipulation, flash loans)
-- \`protocol-patterns/*\`: AMM/DEX, lending, bridges, governance, staking-specific heuristics
-- \`methodology/*\`: audit workflow, severity calibration, and report structure guidance
-- \`checklists/*\`: structured review checklists for upgrades, integrations, and DeFi best practices
-- \`references/*\`: exploit references and vulnerable examples for historical precedent
-- Trail of Bits skills include both audit-relevant and general engineering skills; prioritize security-audit-oriented skills
-
-### Skill Index Snapshot
-- Bundled skills: ${skillIndex.bundled.count} (examples: ${formatSkillSample(skillIndex.bundled)})
-- Trail of Bits skills: ${skillIndex.trailOfBits.count} (examples: ${formatSkillSample(skillIndex.trailOfBits)})
-- Custom project skills: ${skillIndex.custom.count} (examples: ${formatSkillSample(skillIndex.custom)})
-- Use the \`skill\` tool with exact skill names from the catalog
-
-### Audit State
-${buildAuditStateSummary(state)}
+    const auditState = deps.getAuditState()
+    if (!auditState) {
+      return
+    }
 
-### Quick Reference
-Use @argus for full audits, @sentinel for testing, @pythia for research, @scribe for reports.
-Severity must follow classification above. Do not inflate severity.
-</argus-context>`.trim();
-}
+    const agent = deps.getAgentForSession(input.sessionID)
+    if (!agent) {
+      return
+    }
 
-/**
- * Factory function that creates a system prompt transform hook.
- * The hook injects Solidity audit context when working in a Solidity project.
- *
- * @param getAuditState - Accessor function for current audit state (may return null)
- * @returns Async transform function compatible with OpenCode's experimental.chat.system.transform
- */
-export function createSystemPromptHook(
-  getAuditState: () => AuditState | null,
-  options?: { argusConfig?: ArgusConfig; projectDir?: string }
-): (input: SystemPromptInput) => Promise<string | null> {
-  const skillIndex = buildSkillIndexSnapshot({
-    argusConfig: options?.argusConfig,
-    projectDir: options?.projectDir,
-  });
+    const currentSystem = output.system.join("\n")
+    const pressure = deps.getContextPressure?.(currentSystem) ?? 0
+    const budget = deps.getTokenBudget?.(agent, pressure) ?? DEFAULT_TOKEN_BUDGET
 
-  return async (input: SystemPromptInput): Promise<string | null> => {
-    const isSolidity = await isSolidityProject(input.cwd);
+    output.system.push(buildDynamicContext(auditState, agent, budget))
 
-    if (!isSolidity) {
-      return null;
+    if (deps.getReconBlock) {
+      const reconBlock = deps.getReconBlock()
+      if (reconBlock && estimateTokens(reconBlock) <= budget) {
+        output.system.push(reconBlock)
+      }
     }
 
-    const auditState = getAuditState();
-    return buildAuditContextBlock(auditState, skillIndex);
-  };
+    if (agent === "argus" && deps.getEnforcerReminder) {
+      const reminder = deps.getEnforcerReminder(auditState)
+      if (reminder) {
+        output.system.push(reminder)
+      }
+    }
+  }
 }
-
-export default createSystemPromptHook;