solidity-argus 0.1.8 → 0.3.0

package/src/hooks/context-budget.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.7
+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.ts

@@ -1,32 +1,45 @@
-import type { AuditState } from "../state/types"
+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>
+
+export type EventSubHandler = (event: {
+  type: string
+  sessionId?: string
+  auditState: AuditState | null
+  setAuditState: (state: AuditState | null) => void
 }) => 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 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": {
@@ -37,23 +50,23 @@ 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}`
-           )
-         }
-         break
-       }
+        if (currentAuditState) {
+          logger.debug(
+            `Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}`,
+          )
+        }
+        break
+      }
 
       case "session.error": {
         if (currentAuditState) {
-          console.error(
-            `[argus-error] Session error — state snapshot: ${JSON.stringify({
+          logger.error(
+            `Session error — state snapshot: ${JSON.stringify({
               sessionId: currentAuditState.sessionId,
               phase: currentAuditState.currentPhase,
               findingsCount: currentAuditState.findings.length,
               contractsReviewed: currentAuditState.contractsReviewed,
-            })}`
+            })}`,
           )
         }
         break
@@ -64,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"

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

@@ -1,8 +1,9 @@
 import os from "node:os"
 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 { ScvdClient } from "../knowledge/scvd-client"
+import { type SyncResult, syncIncremental } from "../knowledge/scvd-sync"
+import { createLogger } from "../shared/logger"
 
 export type KnowledgeSyncDependencies = {
   createClient?: (apiUrl: string) => unknown
@@ -18,14 +19,14 @@ function defaultDependencies(): Required<KnowledgeSyncDependencies> {
     syncIncrementalFn: async (client: unknown, indexPath: string) =>
       syncIncremental(client as ScvdClient, indexPath),
     log: (message: string) => {
-       console.error(message)
-     },
+      createLogger().info(message)
+    },
   }
 }
 
 export function createKnowledgeSyncHook(
   argusConfig: ArgusConfig,
-  deps: KnowledgeSyncDependencies = {}
+  deps: KnowledgeSyncDependencies = {},
 ): () => void {
   const dependencies = { ...defaultDependencies(), ...deps }
 
@@ -35,23 +36,20 @@ export function createKnowledgeSyncHook(
     }
 
     const apiUrl = argusConfig.knowledge?.scvd?.apiUrl ?? DEFAULT_SCVD_API_URL
-    const indexPath = path.join(
-      os.homedir(),
-      ".cache",
-      "solidity-argus",
-      "scvd-index.json"
-    )
+    const indexPath = path.join(os.homedir(), ".cache", "solidity-argus", "scvd-index.json")
 
     Promise.resolve().then(async () => {
-       try {
-         const client = dependencies.createClient(apiUrl)
-         const result = await dependencies.syncIncrementalFn(client, indexPath)
-         if (result.newFindings > 0) {
-           dependencies.log(
-             `[argus] SCVD index updated: ${result.newFindings} new findings (total: ${result.totalIndexed})`
-           )
-         }
-       } catch (_e) { /* non-critical: sync errors are logged above */ }
-     })
+      try {
+        const client = dependencies.createClient(apiUrl)
+        const result = await dependencies.syncIncrementalFn(client, indexPath)
+        if (result.newFindings > 0) {
+          dependencies.log(
+            `[argus] SCVD index updated: ${result.newFindings} new findings (total: ${result.totalIndexed})`,
+          )
+        }
+      } catch (_e) {
+        createLogger().debug("Knowledge sync failed during auto-sync")
+      }
+    })
   }
 }

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

@@ -0,0 +1,66 @@
+import type { AuditArtifact } from "../utils/audit-artifact-detector"
+import type { DependencyRisk } from "../utils/dependency-scanner"
+import type { ProjectConfig } from "../utils/project-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,15 +1,13 @@
-export function safeCreateHook<T>(
-  factory: () => T,
-  hookName: string
-): T | undefined {
+import { createLogger } from "../shared/logger"
+
+export function safeCreateHook<T>(factory: () => T, hookName: string): T | undefined {
   try {
-    return factory();
+    return factory()
   } catch (error) {
-    console.error(
-      `[argus-hook-error] Failed to create hook "${hookName}": ${
-        error instanceof Error ? error.message : String(error)
-      }`
-    );
-    return undefined;
+    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

@@ -0,0 +1,128 @@
+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
+}
+
+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.",
+}
+
+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
+}
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / TOKENS_PER_CHAR)
+}
+
+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 auditState.findings) {
+    severityCounts[finding.severity]++
+  }
+
+  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))
+  }
+
+  lines.push("</argus-context>")
+
+  let summary = lines.join("\n")
+
+  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 summary
+}
+
+export function createSystemPromptHook(deps: SystemPromptHookDeps) {
+  return async (
+    input: { sessionID?: string; model: unknown },
+    output: { system: string[] },
+  ): Promise<void> => {
+    if (!input.sessionID) {
+      return
+    }
+
+    if (!deps.isArgusAgent(input.sessionID)) {
+      return
+    }
+
+    const auditState = deps.getAuditState()
+    if (!auditState) {
+      return
+    }
+
+    const agent = deps.getAgentForSession(input.sessionID)
+    if (!agent) {
+      return
+    }
+
+    const currentSystem = output.system.join("\n")
+    const pressure = deps.getContextPressure?.(currentSystem) ?? 0
+    const budget = deps.getTokenBudget?.(agent, pressure) ?? DEFAULT_TOKEN_BUDGET
+
+    output.system.push(buildDynamicContext(auditState, agent, budget))
+
+    if (deps.getReconBlock) {
+      const reconBlock = deps.getReconBlock()
+      if (reconBlock && estimateTokens(reconBlock) <= budget) {
+        output.system.push(reconBlock)
+      }
+    }
+
+    if (agent === "argus" && deps.getEnforcerReminder) {
+      const reminder = deps.getEnforcerReminder(auditState)
+      if (reminder) {
+        output.system.push(reminder)
+      }
+    }
+  }
+}