solidity-argus 0.1.0

package/src/create-hooks.ts

@@ -0,0 +1,84 @@
+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 { createAuditState } from "./state/audit-state"
+import { createConfigHandler } from "./hooks/config-handler"
+import { createSystemPromptHook } from "./hooks/system-prompt-hook"
+import { createCompactionHook } from "./hooks/compaction-hook"
+import { createToolTrackingHook } from "./hooks/tool-tracking-hook"
+import { createEventHook } from "./hooks/event-hook"
+import { safeCreateHook } from "./hooks/safe-create-hook"
+
+export type Hooks = Pick<
+  PluginHooks,
+  | "config"
+  | "experimental.chat.system.transform"
+  | "experimental.session.compacting"
+  | "tool.execute.after"
+  | "event"
+>
+
+export function createHooks(args: {
+  config: ArgusConfig
+  managers: Managers
+  projectDir: string
+  isHookEnabled: (name: HookName) => boolean
+}): Hooks {
+  const { config, projectDir, isHookEnabled } = args
+
+  const { state: auditState, store: findingStore } = createAuditState(projectDir)
+  const { hook: eventHook, getAuditState, setAuditState } = createEventHook(projectDir)
+  setAuditState(auditState)
+
+  const systemPromptHook = isHookEnabled("system-prompt")
+    ? safeCreateHook(
+        () => createSystemPromptHook(getAuditState),
+        "system-prompt"
+      )
+    : undefined
+
+  const compactionHook = isHookEnabled("compaction")
+    ? safeCreateHook(() => createCompactionHook(getAuditState), "compaction")
+    : undefined
+
+  const toolTrackingHook = isHookEnabled("tool-tracking")
+    ? safeCreateHook(
+        () => createToolTrackingHook(auditState, findingStore),
+        "tool-tracking"
+      )
+    : undefined
+
+  const safeEventHook = isHookEnabled("event")
+    ? safeCreateHook(() => eventHook, "event")
+    : undefined
+
+  return {
+    config: createConfigHandler(config),
+    "experimental.chat.system.transform": systemPromptHook
+      ? async (_input, output) => {
+          const block = await systemPromptHook({
+            system: output.system.join("\n\n"),
+            cwd: projectDir,
+          })
+          if (block) output.system.push(block)
+        }
+      : undefined,
+    "experimental.session.compacting": compactionHook
+      ? async (_input, output) => {
+          const block = await compactionHook({ summary: output.context.join("\n") })
+          if (block) output.context.push(block)
+        }
+      : undefined,
+    "tool.execute.after": toolTrackingHook
+      ? async (input, output) => {
+          await toolTrackingHook({
+            tool: input.tool,
+            args: input.args,
+            result: output.output,
+          })
+        }
+      : undefined,
+    event: safeEventHook,
+  }
+}

package/src/create-managers.ts

@@ -0,0 +1,26 @@
+import type { ArgusConfig } from "./config/types"
+import type { Managers } from "./managers/types"
+import { createBackgroundManager } from "./features/background-agent/background-manager"
+import { createAuditStateManager } from "./features/persistent-state/audit-state-manager"
+import { createLogger } from "./shared/logger"
+
+export function createManagers(args: {
+  projectDir: string
+  config: ArgusConfig
+}): Managers {
+  const { projectDir } = 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()}`
+    },
+  )
+
+  const auditStateManager = createAuditStateManager(projectDir)
+
+  return { backgroundManager, auditStateManager }
+}

package/src/create-tools.ts

@@ -0,0 +1,30 @@
+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 { contractAnalyzerTool } from "./tools/contract-analyzer-tool"
+import { patternCheckerTool } from "./tools/pattern-checker-tool"
+import { soloditSearchTool } from "./tools/solodit-search-tool"
+import { reportGeneratorTool } from "./tools/report-generator-tool"
+import { syncKnowledgeTool } from "./tools/sync-knowledge-tool"
+
+export function createTools(
+  config: ArgusConfig,
+): Record<string, ToolDefinition> {
+  const tools: Record<string, ToolDefinition> = {
+    argus_slither_analyze: slitherTool,
+    argus_forge_test: forgeTestTool,
+    argus_forge_fuzz: forgeFuzzTool,
+    argus_analyze_contract: contractAnalyzerTool,
+    argus_check_patterns: patternCheckerTool,
+    argus_generate_report: reportGeneratorTool,
+    argus_sync_knowledge: syncKnowledgeTool,
+  }
+
+  if (config.solodit?.enabled !== false) {
+    tools.argus_solodit_search = soloditSearchTool
+  }
+
+  return tools
+}

package/src/features/audit-enforcer/audit-enforcer.ts

@@ -0,0 +1,34 @@
+import type { AuditPhase, AuditState } from "../../state/types"
+
+const PHASE_ORDER: AuditPhase[] = [
+  "reconnaissance",
+  "scanning",
+  "manual-review",
+  "attack-surface",
+  "research",
+  "testing",
+  "reporting",
+  "complete",
+]
+
+function getNextPhase(current: AuditPhase): AuditPhase | null {
+  const idx = PHASE_ORDER.indexOf(current)
+  if (idx === -1 || idx >= PHASE_ORDER.length - 1) return null
+  return PHASE_ORDER[idx + 1] ?? null
+}
+
+export function createAuditEnforcer() {
+  return (auditState: AuditState | null): string | null => {
+    if (!auditState) return null
+    if (auditState.currentPhase === "complete") return null
+
+    const nextPhase = getNextPhase(auditState.currentPhase)
+    if (!nextPhase) return null
+
+    return [
+      `[Argus Audit Enforcer] Audit in progress — current phase: ${auditState.currentPhase}.`,
+      `Next phase: ${nextPhase}. Do not stop until audit is complete.`,
+      `Progress: ${auditState.findings.length} findings, ${auditState.contractsReviewed.length} contracts reviewed.`,
+    ].join(" ")
+  }
+}

package/src/features/audit-enforcer/index.ts

@@ -0,0 +1 @@
+export { createAuditEnforcer } from "./audit-enforcer"

package/src/features/background-agent/background-manager.ts

@@ -0,0 +1,200 @@
+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;
+
+export interface BackgroundTaskOptions {
+  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;
+}
+
+interface TaskInfo {
+  status: TaskStatus;
+  agentName: string;
+  prompt: string;
+  options?: BackgroundTaskOptions;
+  result?: unknown;
+  error?: unknown;
+  callbacks: Set<CompletionCallback>;
+}
+
+type Dispatcher = (
+  agentName: string,
+  prompt: string,
+  options?: BackgroundTaskOptions,
+) => Promise<string>;
+
+export function createBackgroundManager(
+  dispatcher: Dispatcher,
+): 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;
+
+  function invokeCallbacks(taskId: string, result: unknown): void {
+    const task = tasks.get(taskId);
+    if (!task) {
+      return;
+    }
+
+    for (const callback of globalCallbacks) {
+      callback(taskId, result);
+    }
+
+    for (const callback of task.callbacks) {
+      callback(taskId, result);
+    }
+
+    task.callbacks.clear();
+  }
+
+  function processQueue(): void {
+    while (runningCount < maxConcurrent && queue.length > 0) {
+      const nextTaskId = queue.shift();
+
+      if (!nextTaskId) {
+        return;
+      }
+
+      const task = tasks.get(nextTaskId);
+      if (!task || task.status === "cancelled") {
+        continue;
+      }
+
+      task.status = "running";
+      runningCount += 1;
+
+      dispatcher(task.agentName, task.prompt, task.options)
+        .then((result) => {
+          const currentTask = tasks.get(nextTaskId);
+
+          if (!currentTask || currentTask.status === "cancelled") {
+            return;
+          }
+
+          currentTask.status = "completed";
+          currentTask.result = result;
+          invokeCallbacks(nextTaskId, result);
+        })
+        .catch((error: unknown) => {
+          const currentTask = tasks.get(nextTaskId);
+
+          if (!currentTask || currentTask.status === "cancelled") {
+            return;
+          }
+
+          currentTask.status = "failed";
+          currentTask.error = error;
+          logger.error(`Background task failed: ${nextTaskId}`, error);
+        })
+        .finally(() => {
+          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}`;
+
+    tasks.set(taskId, {
+      status: "queued",
+      agentName,
+      prompt,
+      options,
+      callbacks: new Set<CompletionCallback>(),
+    });
+
+    queue.push(taskId);
+    processQueue();
+
+    return taskId;
+  }
+
+  function cancel(taskId: string): void {
+    const task = tasks.get(taskId);
+    if (!task) {
+      return;
+    }
+
+    task.status = "cancelled";
+
+    const queuedTaskIndex = queue.indexOf(taskId);
+    if (queuedTaskIndex >= 0) {
+      queue.splice(queuedTaskIndex, 1);
+    }
+  }
+
+  function getResult(taskId: string): Promise<unknown> {
+    const task = tasks.get(taskId);
+    if (!task || task.status !== "completed") {
+      return Promise.resolve(undefined);
+    }
+
+    return Promise.resolve(task.result);
+  }
+
+  function onComplete(taskIdOrCallback: string | CompletionCallback, callback?: CompletionCallback): void {
+    if (typeof taskIdOrCallback === "function") {
+      globalCallbacks.add(taskIdOrCallback);
+      return;
+    }
+
+    if (!callback) {
+      return;
+    }
+
+    const task = tasks.get(taskIdOrCallback);
+    if (!task) {
+      return;
+    }
+
+    if (task.status === "completed") {
+      callback(taskIdOrCallback, task.result);
+      return;
+    }
+
+    task.callbacks.add(callback);
+  }
+
+  function getActiveCount(): number {
+    let activeCount = 0;
+
+    for (const task of tasks.values()) {
+      if (task.status === "queued" || task.status === "running") {
+        activeCount += 1;
+      }
+    }
+
+    return activeCount;
+  }
+
+  return {
+    dispatch,
+    cancel,
+    getResult,
+    onComplete,
+    getActiveCount,
+  };
+}

package/src/features/background-agent/index.ts

@@ -0,0 +1 @@
+export * from "./background-manager";

package/src/features/context-monitor/context-monitor.ts

@@ -0,0 +1,48 @@
+import type { AuditState } from "../../state/types"
+import { createLogger } from "../../shared/logger"
+
+const DEFAULT_MAX_TOKENS = 200_000
+const REMINDER_THRESHOLD = 0.70
+const COMPACTION_THRESHOLD = 0.85
+
+export interface ContextMonitorConfig {
+  maxTokens?: number
+}
+
+export function createContextMonitor(config: ContextMonitorConfig = {}) {
+  const logger = createLogger()
+  const maxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS
+
+  function estimateTokens(text: string): number {
+    return Math.ceil(text.length / 4)
+  }
+
+  function getContextStatus(
+    systemText: string,
+    auditState: AuditState | null,
+  ): { usage: number; reminder: string | null; shouldCompact: boolean } {
+    const tokens = estimateTokens(systemText)
+    const usage = tokens / maxTokens
+
+    if (usage >= COMPACTION_THRESHOLD) {
+      logger.info(`Context at ${Math.round(usage * 100)}% — triggering compaction`)
+      return {
+        usage,
+        reminder: `[Argus Context Warning] Context window at ${Math.round(usage * 100)}%. Compaction triggered. Prioritize critical findings.`,
+        shouldCompact: true,
+      }
+    }
+
+    if (usage >= REMINDER_THRESHOLD) {
+      return {
+        usage,
+        reminder: `[Argus Context Notice] Context at ${Math.round(usage * 100)}% — maintain audit thoroughness, be concise.`,
+        shouldCompact: false,
+      }
+    }
+
+    return { usage, reminder: null, shouldCompact: false }
+  }
+
+  return { estimateTokens, getContextStatus }
+}

package/src/features/context-monitor/index.ts

@@ -0,0 +1,4 @@
+export { createContextMonitor } from "./context-monitor"
+export type { ContextMonitorConfig } from "./context-monitor"
+export { createToolOutputTruncator } from "./tool-output-truncator"
+export type { TruncatorConfig } from "./tool-output-truncator"

package/src/features/context-monitor/tool-output-truncator.ts

@@ -0,0 +1,17 @@
+const DEFAULT_MAX_CHARS = 50_000
+const MIN_CHARS = 1000
+
+export interface TruncatorConfig {
+  maxChars?: number
+}
+
+export function createToolOutputTruncator(config: TruncatorConfig = {}) {
+  const maxChars = Math.max(config.maxChars ?? DEFAULT_MAX_CHARS, MIN_CHARS)
+
+  return (output: string): string => {
+    if (output.length <= maxChars) return output
+
+    const truncated = output.slice(0, maxChars)
+    return `${truncated}\n\n[Truncated: ${output.length.toLocaleString()} → ${maxChars.toLocaleString()} chars]`
+  }
+}

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

@@ -0,0 +1,2 @@
+export { createSessionRecoveryHandler } from "./session-recovery"
+export { createToolErrorRecoveryHandler } from "./tool-error-recovery"

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

@@ -0,0 +1,27 @@
+import type { AuditStateManager } from "../../managers/types"
+import { createLogger } from "../../shared/logger"
+
+export function createSessionRecoveryHandler(
+  auditStateManager: AuditStateManager,
+) {
+  const logger = createLogger()
+
+  return async (event: { type: string; sessionId?: string }): Promise<void> => {
+    if (event.type !== "session.error") return
+
+    logger.info("Session error detected, attempting state recovery...")
+
+    try {
+      const recovered = await auditStateManager.load()
+      if (recovered) {
+        logger.info(
+          `State recovered: phase=${recovered.currentPhase}, findings=${recovered.findings.length}`,
+        )
+      } else {
+        logger.warn("No persisted state available for recovery")
+      }
+    } catch (error) {
+      logger.error("State recovery failed:", error)
+    }
+  }
+}

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

@@ -0,0 +1,35 @@
+import { createLogger } from "../../shared/logger"
+
+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",
+}
+
+export function createToolErrorRecoveryHandler() {
+  const logger = createLogger()
+
+  return (toolResult: { tool: string; result: string }): string | null => {
+    const { tool, result } = toolResult
+    const lowerResult = result.toLowerCase()
+
+    const isError =
+      lowerResult.includes("enoent") ||
+      lowerResult.includes("not found") ||
+      lowerResult.includes("command failed") ||
+      lowerResult.includes("error:")
+
+    if (!isError) return null
+
+    const toolBase = tool.replace("argus_", "").split("_")[0] ?? ""
+    const hint = RECOVERY_HINTS[toolBase]
+
+    if (hint) {
+      logger.info(`Tool error recovery hint for ${tool}: ${hint}`)
+      return `\n[Argus Recovery Hint] ${hint}`
+    }
+
+    return null
+  }
+}

package/src/features/index.ts

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

package/src/features/persistent-state/audit-state-manager.ts

@@ -0,0 +1,121 @@
+import { mkdir, rename } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { AuditStateManager } from "../../managers/types";
+import { createAuditState } from "../../state/audit-state";
+import type { AuditState, PersistentAuditState } from "../../state/types";
+import { createLogger } from "../../shared/logger";
+
+const STATE_FILE_DIR = ".opencode";
+const STATE_FILE_NAME = "argus-state.json";
+const STATE_VERSION = "1";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isAuditState(value: unknown): value is AuditState {
+  if (!isObject(value)) {
+    return false;
+  }
+
+  return (
+    typeof value.sessionId === "string" &&
+    typeof value.projectDir === "string" &&
+    isStringArray(value.contractsReviewed) &&
+    Array.isArray(value.findings) &&
+    Array.isArray(value.toolsExecuted) &&
+    typeof value.currentPhase === "string" &&
+    isStringArray(value.scope) &&
+    typeof value.startTime === "number"
+  );
+}
+
+function isPersistentAuditState(value: unknown): value is PersistentAuditState {
+  if (!isAuditState(value) || !isObject(value)) {
+    return false;
+  }
+
+  return (
+    typeof value.savedAt === "number" &&
+    typeof value.version === "string" &&
+    typeof value.filePath === "string"
+  );
+}
+
+export function createAuditStateManager(projectDir: string): AuditStateManager {
+  const logger = createLogger();
+  const stateFilePath = join(projectDir, STATE_FILE_DIR, STATE_FILE_NAME);
+  let currentState: AuditState = createAuditState(projectDir).state;
+
+  async function load(): Promise<AuditState | null> {
+    try {
+      const file = Bun.file(stateFilePath);
+      if (!(await file.exists())) {
+        return null;
+      }
+
+      const content = await file.text();
+      if (!content.trim()) {
+        return null;
+      }
+
+      const parsed: unknown = JSON.parse(content);
+      if (!isPersistentAuditState(parsed)) {
+        logger.warn("Persistent audit state is invalid, ignoring", stateFilePath);
+        return null;
+      }
+
+      const { savedAt: _savedAt, version: _version, filePath: _filePath, ...state } = parsed;
+      currentState = state;
+      return currentState;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  async function save(state: AuditState): Promise<void> {
+    currentState = state;
+
+    const persistentState: PersistentAuditState = {
+      ...state,
+      savedAt: Date.now(),
+      version: STATE_VERSION,
+      filePath: stateFilePath,
+    };
+
+    const tempFilePath = `${stateFilePath}.tmp`;
+    await mkdir(dirname(stateFilePath), { recursive: true });
+    await Bun.write(tempFilePath, `${JSON.stringify(persistentState, null, 2)}\n`);
+    await rename(tempFilePath, stateFilePath);
+  }
+
+  function get(): AuditState {
+    return currentState;
+  }
+
+  async function update(patch: Partial<AuditState>): Promise<void> {
+    currentState = {
+      ...currentState,
+      ...patch,
+    };
+
+    await save(currentState);
+  }
+
+  async function reset(): Promise<void> {
+    currentState = createAuditState(projectDir).state;
+    await save(currentState);
+  }
+
+  return {
+    load,
+    save,
+    get,
+    update,
+    reset,
+  };
+}

package/src/features/persistent-state/index.ts

@@ -0,0 +1 @@
+export { createAuditStateManager } from "./audit-state-manager";