solidity-argus 0.1.0

package/src/hooks/compaction-hook.ts

@@ -0,0 +1,50 @@
+import type { AuditState, FindingSeverity } from "../state/types"
+
+/**
+ * Creates a compaction hook that serializes audit state into XML format
+ * so findings survive context window compression.
+ *
+ * The returned hook is called by OpenCode's `experimental.session.compacting`
+ * event, receiving `{ summary: string }` and returning the enriched summary.
+ */
+export function createCompactionHook(
+  getAuditState: () => AuditState | null
+): (input: { summary: string }) => Promise<string | null> {
+  return async (_input: { summary: string }): Promise<string | null> => {
+    const state = getAuditState()
+    if (!state) {
+      return null
+    }
+
+    const severityCounts: Record<FindingSeverity, number> = {
+      Critical: 0,
+      High: 0,
+      Medium: 0,
+      Low: 0,
+      Informational: 0,
+    }
+
+    for (const finding of state.findings) {
+      severityCounts[finding.severity]++
+    }
+
+    const toolNames = state.toolsExecuted.map((t) => t.tool).join(", ")
+    const contracts = state.contractsReviewed.join(", ")
+    const started = new Date(state.startTime).toISOString()
+
+    return [
+      "<argus-audit-state>",
+      `Phase: ${state.currentPhase}`,
+      `Contracts Reviewed: ${contracts}`,
+      "Findings:",
+      `  Critical: ${severityCounts.Critical}`,
+      `  High: ${severityCounts.High}`,
+      `  Medium: ${severityCounts.Medium}`,
+      `  Low: ${severityCounts.Low}`,
+      `  Informational: ${severityCounts.Informational}`,
+      `Tools Executed: ${toolNames}`,
+      `Started: ${started}`,
+      "</argus-audit-state>",
+    ].join("\n")
+  }
+}

package/src/hooks/config-handler.ts

@@ -0,0 +1,116 @@
+import { resolve, join } from "node:path"
+import { existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { execSync } from "node:child_process"
+import type { Config } from "@opencode-ai/sdk/v2"
+import type { ArgusConfig } from "../config/types"
+import { DEFAULT_MODELS } from "../constants/defaults"
+import { createKnowledgeSyncHook } from "./knowledge-sync-hook"
+import { ARGUS_PROMPT } from "../agents/argus-prompt"
+import { SENTINEL_PROMPT } from "../agents/sentinel-prompt"
+import { PYTHIA_PROMPT } from "../agents/pythia-prompt"
+import { SCRIBE_PROMPT } from "../agents/scribe-prompt"
+
+const TOB_CACHE_DIR = join(homedir(), ".cache", "solidity-argus", "trailofbits-skills")
+const TOB_REPO_URL = "https://github.com/trailofbits/skills.git"
+
+function ensureTrailOfBitsSkills(): string | undefined {
+  if (existsSync(TOB_CACHE_DIR)) return TOB_CACHE_DIR
+  try {
+    execSync(`git clone --depth 1 ${TOB_REPO_URL} "${TOB_CACHE_DIR}"`, {
+      stdio: "ignore",
+      timeout: 30_000,
+    })
+    return TOB_CACHE_DIR
+  } catch (_e) {
+    return undefined
+  }
+}
+
+export function createConfigHandler(
+  argusConfig: ArgusConfig
+): (config: Config) => Promise<void> {
+  const triggerKnowledgeSync = createKnowledgeSyncHook(argusConfig)
+
+  return async (config: Config): Promise<void> => {
+    config.agent = {
+      ...config.agent,
+      argus: {
+        mode: "primary",
+        model: argusConfig.agents?.argus?.model ?? DEFAULT_MODELS.argus,
+        description: "Solidity security auditor — the All-Seeing Guardian",
+        prompt: ARGUS_PROMPT,
+        tools: {
+          "argus_*": false,
+          "solodit-mcp_*": false,
+        },
+        permission: {
+          task: {
+            sentinel: "allow",
+            pythia: "allow",
+            scribe: "allow",
+          },
+        },
+      },
+      sentinel: {
+        mode: "subagent",
+        model: argusConfig.agents?.sentinel?.model ?? DEFAULT_MODELS.sentinel,
+        description: "Static analysis and testing specialist",
+        prompt: SENTINEL_PROMPT,
+        tools: {
+          argus_slither_analyze: true,
+          argus_forge_test: true,
+          argus_forge_fuzz: true,
+          argus_analyze_contract: true,
+          argus_check_patterns: true,
+        } satisfies Record<string, boolean>,
+      },
+      pythia: {
+        mode: "subagent",
+        model: argusConfig.agents?.pythia?.model ?? DEFAULT_MODELS.pythia,
+        description: "Vulnerability researcher",
+        prompt: PYTHIA_PROMPT,
+        tools: {
+          argus_solodit_search: true,
+          argus_check_patterns: true,
+        } satisfies Record<string, boolean>,
+      },
+      scribe: {
+        mode: "subagent",
+        model: argusConfig.agents?.scribe?.model ?? DEFAULT_MODELS.scribe,
+        description: "Audit report writer",
+        prompt: SCRIBE_PROMPT,
+        tools: {
+          argus_generate_report: true,
+        } satisfies Record<string, boolean>,
+      },
+    }
+
+    if (argusConfig.solodit?.enabled !== false) {
+      const port = argusConfig.solodit?.port ?? 3000
+      config.mcp = {
+        ...(config.mcp ?? {}),
+        "solodit-mcp": {
+          type: "remote",
+          url: `http://localhost:${port}/mcp`,
+          enabled: true,
+        },
+      }
+    }
+
+    const skillsPaths = [...(config.skills?.paths ?? [])]
+    skillsPaths.push(resolve(import.meta.dir, "../../skills"))
+
+    const tobDir = ensureTrailOfBitsSkills()
+    if (tobDir) skillsPaths.push(tobDir)
+
+    config.skills = {
+      ...(config.skills ?? {}),
+      paths: skillsPaths,
+    }
+
+    if (argusConfig.knowledge?.autoSync !== false) {
+      triggerKnowledgeSync()
+    }
+  }
+}

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

@@ -0,0 +1,93 @@
+import type { AuditState, AuditPhase } from "../state/types"
+import { createAuditState } from "../state/audit-state"
+import { createLogger } from "../shared/logger"
+
+export type AuditEventType =
+  | "session.created"
+  | "session.idle"
+  | "session.error"
+  | "session.deleted"
+  | "audit.phase-changed"
+  | "audit.finding-added"
+  | "audit.complete"
+
+export type EventHookV2Fn = (input: {
+  event: { type: string; sessionId?: string; properties?: Record<string, unknown> }
+}) => Promise<void>
+
+export type EventSubHandler = (event: {
+  type: string
+  sessionId?: string
+  auditState: AuditState | null
+}) => Promise<void>
+
+export function createEventHookV2(
+  projectDir?: string,
+  subHandlers: EventSubHandler[] = [],
+): {
+  hook: EventHookV2Fn
+  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: EventHookV2Fn = async (input): Promise<void> => {
+    const { type, sessionId } = input.event
+
+    switch (type) {
+      case "session.created": {
+        const dir = projectDir ?? process.cwd()
+        const { state } = createAuditState(dir)
+        currentAuditState = state
+        break
+      }
+
+      case "session.idle": {
+        if (currentAuditState) {
+          logger.debug(
+            `Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}`,
+          )
+        }
+        break
+      }
+
+      case "session.error": {
+        if (currentAuditState) {
+          logger.error(
+            `Session error — state snapshot: ${JSON.stringify({
+              sessionId: currentAuditState.sessionId,
+              phase: currentAuditState.currentPhase,
+              findingsCount: currentAuditState.findings.length,
+              contractsReviewed: currentAuditState.contractsReviewed,
+            })}`,
+          )
+        }
+        break
+      }
+
+      case "session.deleted": {
+        currentAuditState = null
+        break
+      }
+
+      default:
+        break
+    }
+
+    for (const handler of subHandlers) {
+      try {
+        await handler({ type, sessionId, auditState: currentAuditState })
+      } catch (error) {
+        logger.error(`Sub-handler failed for event ${type}:`, error)
+      }
+    }
+  }
+
+  return { hook, getAuditState, setAuditState }
+}

package/src/hooks/event-hook.ts

@@ -0,0 +1,74 @@
+import type { AuditState } from "../state/types"
+import { createAuditState } from "../state/audit-state"
+
+export type EventHookFn = (input: {
+  event: { type: string; sessionId?: string }
+}) => 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): {
+  hook: EventHookFn
+  getAuditState: () => AuditState | null
+  setAuditState: (state: AuditState | null) => void
+} {
+  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
+
+    switch (type) {
+      case "session.created": {
+        const dir = projectDir ?? process.cwd()
+        const { state } = createAuditState(dir)
+        currentAuditState = state
+        break
+      }
+
+      case "session.idle": {
+         if (currentAuditState) {
+           console.error(
+             `[argus-state] Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}, contracts: ${currentAuditState.contractsReviewed.length}`
+           )
+         }
+         break
+       }
+
+      case "session.error": {
+        if (currentAuditState) {
+          console.error(
+            `[argus-error] Session error — state snapshot: ${JSON.stringify({
+              sessionId: currentAuditState.sessionId,
+              phase: currentAuditState.currentPhase,
+              findingsCount: currentAuditState.findings.length,
+              contractsReviewed: currentAuditState.contractsReviewed,
+            })}`
+          )
+        }
+        break
+      }
+
+      case "session.deleted": {
+        currentAuditState = null
+        break
+      }
+
+      // Unknown events: no-op — never throw
+      default:
+        break
+    }
+  }
+
+  return { hook, getAuditState, setAuditState }
+}

package/src/hooks/hook-system.ts

@@ -0,0 +1,9 @@
+import type { HookName } from "./types";
+
+export function createHookGuard(disabledHooks: string[]) {
+  const disabledSet = new Set(disabledHooks);
+
+  return function isHookEnabled(name: HookName): boolean {
+    return !disabledSet.has(name);
+  };
+}

package/src/hooks/index.ts

@@ -0,0 +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";

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

@@ -0,0 +1,57 @@
+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"
+
+export type KnowledgeSyncDependencies = {
+  createClient?: (apiUrl: string) => unknown
+  syncIncrementalFn?: (client: unknown, indexPath: string) => Promise<SyncResult>
+  log?: (message: string) => void
+}
+
+const DEFAULT_SCVD_API_URL = "https://api.scvd.dev"
+
+function defaultDependencies(): Required<KnowledgeSyncDependencies> {
+  return {
+    createClient: (apiUrl: string) => new ScvdClient(apiUrl),
+    syncIncrementalFn: async (client: unknown, indexPath: string) =>
+      syncIncremental(client as ScvdClient, indexPath),
+    log: (message: string) => {
+       console.error(message)
+     },
+  }
+}
+
+export function createKnowledgeSyncHook(
+  argusConfig: ArgusConfig,
+  deps: KnowledgeSyncDependencies = {}
+): () => void {
+  const dependencies = { ...defaultDependencies(), ...deps }
+
+  return function triggerAutoSync(): void {
+    if (!argusConfig.knowledge?.scvd?.enabled) {
+      return
+    }
+
+    const apiUrl = argusConfig.knowledge?.scvd?.apiUrl ?? DEFAULT_SCVD_API_URL
+    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 */ }
+     })
+  }
+}

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

@@ -0,0 +1,15 @@
+export function safeCreateHook<T>(
+  factory: () => T,
+  hookName: string
+): T | undefined {
+  try {
+    return factory();
+  } catch (error) {
+    console.error(
+      `[argus-hook-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,126 @@
+import { join } from "node:path";
+import type { AuditState, FindingSeverity } from "../state/types";
+
+interface SystemPromptInput {
+  system: string;
+  cwd: string;
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Counts findings by severity from the audit state
+ */
+function countFindingsBySeverity(
+  findings: AuditState["findings"]
+): Record<FindingSeverity, number> {
+  const counts: 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.";
+  }
+
+  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");
+}
+
+/**
+ * Builds the full audit context block to inject into the system prompt.
+ * Designed to be concise (500-800 tokens).
+ */
+function buildAuditContextBlock(state: AuditState | null): 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)
+
+### Audit State
+${buildAuditStateSummary(state)}
+
+### 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();
+}
+
+/**
+ * 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
+): (input: SystemPromptInput) => Promise<string | null> {
+  return async (input: SystemPromptInput): Promise<string | null> => {
+    const isSolidity = await isSolidityProject(input.cwd);
+
+    if (!isSolidity) {
+      return null;
+    }
+
+    const auditState = getAuditState();
+    return buildAuditContextBlock(auditState);
+  };
+}
+
+export default createSystemPromptHook;