solidity-argus 0.1.8 → 0.3.0

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: {

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

@@ -1,15 +1,61 @@
 import { createLogger } from "../../shared/logger"
+import type { AuditState } from "../../state/types"
 
-const RECOVERY_HINTS: Record<string, string> = {
-  slither: "Install Slither: pip install slither-analyzer",
-  forge: "Install Foundry: curl -L https://foundry.paradigm.xyz | bash && foundryup",
-  solodit: "Check network connectivity or Solodit API status",
-  scvd: "Check SCVD API at https://api.scvd.dev — may be temporarily unavailable",
+type ToolFallbackEntry = {
+  install: string
+  fallback: string
 }
 
-const VIA_IR_HINT = "Project uses via_ir — Slither uses forge-flatten fallback automatically. Ensure forge and solc-select are installed."
+const TOOL_FALLBACKS: Record<string, ToolFallbackEntry> = {
+  slither: {
+    install: "pip install slither-analyzer",
+    fallback:
+      'Slither is unavailable. PROCEED with the audit using `argus_analyze_contract` for structural profiling and `argus_check_patterns` for vulnerability scanning. Note in the final report: "Automated static analysis (Slither) was unavailable; manual review intensity increased."',
+  },
+  forge: {
+    install: "curl -L https://foundry.paradigm.xyz | bash && foundryup",
+    fallback:
+      'Foundry/Forge is unavailable. SKIP automated testing and fuzzing. Verify findings through manual code tracing and static analysis. Note in the final report: "Dynamic testing (Forge) was unavailable; findings verified via manual analysis."',
+  },
+  solodit: {
+    install: "",
+    fallback:
+      'Solodit API is unreachable. PROCEED using `argus_check_patterns` with local vulnerability rules. Note in the final report: "External vulnerability databases were inaccessible; research limited to local patterns."',
+  },
+  scvd: {
+    install: "",
+    fallback:
+      "SCVD API is unavailable. PROCEED with local patterns and Solodit search if available.",
+  },
+}
+
+const VIA_IR_HINT =
+  "Project uses via_ir — Slither uses forge-flatten fallback automatically. Ensure forge and solc-select are installed."
+
+function isToolUnavailable(lowerResult: string): boolean {
+  return (
+    lowerResult.includes("enoent") ||
+    lowerResult.includes("not found") ||
+    lowerResult.includes("not installed")
+  )
+}
+
+function isToolError(lowerResult: string): boolean {
+  return (
+    isToolUnavailable(lowerResult) ||
+    lowerResult.includes("command failed") ||
+    lowerResult.includes("error:")
+  )
+}
+
+function resolveToolBase(tool: string): string {
+  return tool.replace("argus_", "").split("_")[0] ?? ""
+}
 
-export function createToolErrorRecoveryHandler() {
+export function createToolErrorRecoveryHandler(
+  getAuditState?: () => AuditState | null,
+  updateAuditState?: (patch: Partial<AuditState>) => Promise<void>,
+) {
   const logger = createLogger()
 
   return (toolResult: { tool: string; result: string }): string | null => {
@@ -27,22 +73,36 @@ export function createToolErrorRecoveryHandler() {
       return `\n[Argus Recovery Hint] ${VIA_IR_HINT}`
     }
 
-    const isError =
-      lowerResult.includes("enoent") ||
-      lowerResult.includes("not found") ||
-      lowerResult.includes("command failed") ||
-      lowerResult.includes("error:")
+    if (!isToolError(lowerResult)) return null
 
-    if (!isError) return null
+    const toolBase = resolveToolBase(tool)
+    const entry = TOOL_FALLBACKS[toolBase]
+    if (!entry) return null
 
-    const toolBase = tool.replace("argus_", "").split("_")[0] ?? ""
-    const hint = RECOVERY_HINTS[toolBase]
+    const unavailable = isToolUnavailable(lowerResult)
+
+    if (unavailable && getAuditState && updateAuditState) {
+      const state = getAuditState()
+      if (state) {
+        const existing = state.unavailableTools ?? []
+        if (!existing.includes(toolBase)) {
+          void updateAuditState({
+            unavailableTools: [...existing, toolBase],
+          }).catch((error: unknown) => {
+            logger.warn(`Failed to persist unavailable tool state for ${toolBase}`, error)
+          })
+          logger.info(`Recorded ${toolBase} as unavailable — fallback activated`)
+        }
+      }
+    }
 
-    if (hint) {
-      logger.info(`Tool error recovery hint for ${tool}: ${hint}`)
-      return `\n[Argus Recovery Hint] ${hint}`
+    if (unavailable) {
+      logger.info(`Tool unavailable fallback for ${tool}`)
+      return `\n[Argus Fallback] ${entry.fallback}`
     }
 
-    return null
+    const installHint = entry.install ? ` (install: ${entry.install})` : ""
+    logger.info(`Tool error recovery hint for ${tool}`)
+    return `\n[Argus Recovery Hint] ${toolBase} error${installHint}. ${entry.fallback}`
   }
 }

package/src/features/index.ts

@@ -1,5 +1,5 @@
-export * from './background-agent'
-export * from './persistent-state'
-export * from './context-monitor'
-export * from './audit-enforcer'
-export * from './error-recovery'
+export * from "./audit-enforcer"
+export * from "./background-agent"
+export * from "./context-monitor"
+export * from "./error-recovery"
+export * from "./persistent-state"