solidity-argus 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Solidity smart contract security auditing plugin for OpenCode — 4 specialized agents, 12 tools (11 core + optional Solodit), and a curated vulnerability knowledge base",
   "keywords": [
     "solidity",

package/src/agents/argus-prompt.ts

@@ -272,7 +272,7 @@ Your subagents have access to these specialized tools. Know when to delegate eac
 - **\`argus_generate_report\`**:
   - **Use**: During Reporting.
   - **Purpose**: Generates the final artifact.
-  - **Note**: Requires structured input of findings. Ensure the tone is objective and helpful.
+  - **Note**: Requires a versioned report_input JSON string matching the ReportInput contract (schema_version 1.0.0). Do not send natural-language-only findings to Scribe for tool invocation.
 
 - **\`argus_sync_knowledge\`**:
   - **Use**: Maintenance.
@@ -422,18 +422,26 @@ Tools may fail. You must be resilient.
 
 **An audit without a report is an incomplete audit.** Your FINAL action before finishing MUST be delegating to Scribe. No exceptions.
 
-After you have synthesized your findings, compile them into a structured list and invoke Scribe:
+After you have synthesized your findings, build a canonical ReportInput payload and invoke Scribe:
 
 \`\`\`
 Task(subagent_type="scribe", prompt="Generate the final security audit report.
 
 Project: {name}
 Scope: {list of audited files}
-
-Findings (pass ALL of these):
-1. [SEVERITY] Title — File:Lines — Description — Impact — Recommendation
-2. [SEVERITY] Title — File:Lines — Description — Impact — Recommendation
-...
+ReportInput JSON (pass EXACTLY, no prose substitution):
+{
+  "run_id": "{run-id}",
+  "seq": {last-seq},
+  "session_id": "{session-id}",
+  "tool_call_id": "{tool-call-id}",
+  "source": "argus",
+  "schema_version": "1.0.0",
+  "projectDir": "{project-dir}",
+  "findings": [canonical findings],
+  "toolsExecuted": [canonical tool executions],
+  "scope": ["..."]
+}
 
 Additional context:
 - Tools used: Slither, Forge, Pattern Checker, Solodit
@@ -442,7 +450,12 @@ Additional context:
 ")
 \`\`\`
 
-You do NOT need to pass raw JSON or serialized audit state. Just pass your findings as a structured list in natural language — Scribe will format them professionally.
+Scribe must call argus_generate_report with:
+- project_name: project name
+- scope: audited file list
+- report_input: serialized ReportInput JSON string
+
+Legacy audit_state is transitional-only and deprecated.
 
 **If you have zero findings, still invoke Scribe** with an empty findings list. A clean report is still a report.
 

package/src/agents/scribe-prompt.ts

@@ -8,7 +8,7 @@ Your core responsibilities are:
 1.  **Aggregation**: Collecting findings from various tools and subagents.
 2.  **Deduplication**: Merging similar findings (e.g., multiple Slither warnings for the same issue).
 3.  **Contextualization**: Explaining *why* a finding matters in the context of the specific protocol.
-4.  **Report Generation**: Producing the final Markdown artifact using \`argus_generate_report\`.
+4.  **Report Generation**: Producing the final Markdown artifact via \`argus_generate_report\`.
 
 ## REPORT STRUCTURE
 
@@ -41,34 +41,17 @@ You must adhere to these strict writing standards:
 
 ## HOW TO GENERATE THE REPORT
 
-You have two approaches. Use whichever fits the input you receive from Argus.
-
-### Approach 1: Use \`argus_generate_report\` tool
-If you have structured findings data, call the tool:
--   \`project_name\` (string): The name of the protocol or project.
--   \`scope\` (string[]): List of files or contracts that were audited.
--   \`include_executive_summary\` (boolean): Default \`true\`.
--   \`severity_threshold\` (string): "critical", "high", "medium", "low", or "informational". Usually "low" or "informational" to include everything.
--   \`audit_state\` (string): JSON string of findings. Format each finding as: \`{"id":"f1","check":"name","severity":"High","confidence":"High","description":"...","file":"Contract.sol","lines":[1,10],"source":"manual"}\`
-
-### Approach 2: Write the report directly as Markdown
-If Argus passes findings in natural language (which is common), write the full report yourself in Markdown following the Report Structure below. This is often faster and produces better results than trying to serialize findings into JSON for the tool.
-
-**Choose Approach 2 when**: Argus gives you a natural language list of findings, descriptions, and context. Just write the report.
-**Choose Approach 1 when**: You have structured JSON finding data ready to pass.
-
-## FILE PERSISTENCE
-
-**Critical Operational Block**: You must ALWAYS use the \`argus_generate_report\` tool to write the audit report to disk. This tool now automatically writes the report to the filesystem via \`Bun.write()\` and returns the file path in its result.
+Argus passes you structured report data. Use that payload directly and keep it schema-accurate.
 
 **Your workflow**:
-1. Prepare your findings data (either structured JSON or natural language context).
-2. Call \`argus_generate_report\` with the appropriate parameters.
-3. After the tool returns, extract the \`filePath\` field from the result.
-4. **Always confirm the file path in your response to Argus**: "Report written to: {filePath}".
-5. If the result does not include a \`filePath\` field, warn Argus: "Warning: filePath missing from tool result. The report may not have been written to disk."
+1. Validate Argus provided a serialized ReportInput JSON string (schema_version 1.0.0) with required fields: run_id, seq, session_id, tool_call_id, source, schema_version, projectDir, findings, toolsExecuted, scope.
+2. Write the complete report in Markdown following the Report Structure and Output Format sections.
+3. Call \`argus_generate_report\` with arguments { project_name, scope, report_input }. Use legacy \`audit_state\` only for transitional compatibility and treat it as deprecated.
+4. Confirm the report was generated in your response to Argus: "Report generated via argus_generate_report: {filePath}".
+
+## SINGLE-WRITER POLICY
 
-This ensures the audit report is persisted and Argus can verify the output location.
+**CRITICAL**: You must NEVER write final report files directly to disk. All report persistence MUST go through \`argus_generate_report\`. This tool enforces the single-writer policy — it is the sole component authorized to create report artifacts on disk. Direct file writes for report output are a policy violation and will be rejected.
 
 ## QUALITY STANDARDS
 

package/src/config/schema.ts

@@ -43,6 +43,10 @@ const BackgroundConfigSchema = z.object({
   max_concurrent: z.number().positive().default(3),
 })
 
+const MigrationConfigSchema = z.object({
+  mode: z.enum(["legacy", "dual", "strict"]).default("legacy"),
+})
+
 export const ArgusConfigSchema = z.object({
   agents: z
     .object({
@@ -82,4 +86,5 @@ export const ArgusConfigSchema = z.object({
   background: BackgroundConfigSchema.default({
     max_concurrent: 3,
   }),
+  migration: MigrationConfigSchema.optional(),
 })

package/src/create-hooks.ts

@@ -8,6 +8,8 @@ import {
   createToolErrorRecoveryHandler,
 } from "./features/error-recovery"
 import { createDebouncedSave } from "./features/persistent-state/audit-state-manager"
+import { getMigrationMode } from "./features/migration"
+import { createEventSink, type EventSink } from "./features/persistent-state/event-sink"
 import { recordRun } from "./features/persistent-state/global-run-index"
 import { createRunJournal } from "./features/persistent-state/run-journal"
 import { createAgentTracker } from "./hooks/agent-tracker"
@@ -23,6 +25,7 @@ import { createToolTrackingHook } from "./hooks/tool-tracking-hook"
 import type { HookName } from "./hooks/types"
 import type { Managers } from "./managers/types"
 import { createLogger } from "./shared/logger"
+import { createAuditArtifactResolver } from "./shared/audit-artifact-resolver"
 import type { AuditState } from "./state/types"
 import { detectAuditArtifacts } from "./utils/audit-artifact-detector"
 import { detectProject, type ProjectConfig } from "./utils/project-detector"
@@ -77,6 +80,9 @@ export function createHooks(args: {
   const agentTracker = createAgentTracker()
   _agentTrackerRef = agentTracker
 
+  const migrationMode = getMigrationMode(config)
+  logger.debug(`Migration mode: ${migrationMode}`)
+
   const contextMonitor = createContextMonitor()
   const sessionRecoveryHandler = createSessionRecoveryHandler(auditStateManager)
   const debouncedSave = createDebouncedSave(auditStateManager.save)
@@ -88,15 +94,21 @@ export function createHooks(args: {
   )
   const outputTruncator = createToolOutputTruncator()
 
+  let currentEventSink: EventSink | null = null
+  let currentOpencodeSessionId = ""
+
   // Sub-handlers run sequentially. The state persistence handler MUST be first:
   // it loads persisted state on session.created, overriding the fresh default.
   const {
     hook: eventHook,
     getAuditState,
     setAuditState,
+    setEventSink,
+    getLastFinalizationResult,
   } = createEventHook(projectDir, [
     async ({ type, sessionId, auditState, setAuditState: setState }) => {
       if (type === "session.created") {
+        currentOpencodeSessionId = sessionId ?? ""
         const timestamp = Date.now()
         let recoveredState: AuditState | null = null
 
@@ -123,6 +135,21 @@ export function createHooks(args: {
 
         const effectiveState = recoveredState ?? auditStateManager.get()
         if (effectiveState) {
+          try {
+            // createAuditArtifactResolver is the canonical source for all run artifact paths.
+            // The journal file path is: {projectDir}/.opencode/runs/{runId}/events.jsonl
+            const resolver = createAuditArtifactResolver(effectiveState.sessionId, projectDir)
+            const journalFile = resolver.paths().journalFile
+            // createEventSink builds the same path internally; the resolver makes it explicit.
+            currentEventSink = createEventSink(effectiveState.sessionId, projectDir)
+            setEventSink(currentEventSink)
+            logger.debug(`Event sink journal path: ${journalFile}`)
+          } catch (error) {
+            logger.error(
+              `Failed to create event sink: ${error instanceof Error ? error.message : String(error)}`,
+            )
+          }
+
           void recordRun({
             runId: effectiveState.sessionId,
             opencodeSessionId: sessionId,
@@ -176,15 +203,14 @@ export function createHooks(args: {
       }
 
       if (type === "session.deleted") {
-        if (sessionId) {
-          agentTracker.clearSession(sessionId)
+        await debouncedSave.flush()
+        if (auditState) {
+          await auditStateManager.save(auditState)
         }
-
-        await auditStateManager.archive()
         runJournal.log({
-          type: "session.deleted",
+          type: "state.saved",
           timestamp: Date.now(),
-          archived: true,
+          success: true,
         })
       }
     },
@@ -248,25 +274,60 @@ export function createHooks(args: {
   const toolTrackingHook = isHookEnabled("tool-tracking")
     ? safeCreateHook(
         () =>
-          createToolTrackingHook(getAuditState, ({ tool, findingsCount }) => {
-            const currentState = getAuditState()
-            if (currentState) {
-              debouncedSave.save(currentState)
-            }
-
-            runJournal.log({
-              type: "tool.executed",
-              tool,
-              timestamp: Date.now(),
-              findingsCount,
-            })
-          }),
+          createToolTrackingHook(
+            getAuditState,
+            ({ tool, findingsCount }) => {
+              const currentState = getAuditState()
+              if (currentState) {
+                debouncedSave.save(currentState)
+              }
+
+              runJournal.log({
+                type: "tool.executed",
+                tool,
+                timestamp: Date.now(),
+                findingsCount,
+              })
+            },
+            {
+              getEventSink: () => currentEventSink,
+              getSessionId: () => currentOpencodeSessionId,
+            },
+          ),
         "tool-tracking",
       )
     : undefined
 
   const safeEventHook = isHookEnabled("event")
-    ? safeCreateHook(() => eventHook, "event")
+    ? safeCreateHook(
+        () => async (input: Parameters<typeof eventHook>[0]) => {
+          const isSessionDeleted = input.event.type === "session.deleted"
+
+          try {
+            await eventHook(input)
+          } finally {
+            if (isSessionDeleted) {
+              await auditStateManager.archive()
+
+              const deletedSessionId = input.event.sessionId
+              if (deletedSessionId) {
+                agentTracker.clearSession(deletedSessionId)
+              }
+
+              runJournal.log({
+                type: "session.deleted",
+                timestamp: Date.now(),
+                archived: true,
+                finalizationPassed: getLastFinalizationResult()?.invariantsPassed ?? null,
+              })
+
+              currentEventSink = null
+              currentOpencodeSessionId = ""
+            }
+          }
+        },
+        "event",
+      )
     : undefined
 
   return {

package/src/features/migration/index.ts

@@ -0,0 +1,14 @@
+export {
+  adaptLegacyFindings,
+  adaptLegacyStateToReportInput,
+  getMigrationMode,
+  type MigrationMode,
+  validateStrictCompatibility,
+} from "./migration-adapter"
+
+export {
+  computeParityMetrics,
+  formatParityReport,
+  type ParityMetrics,
+  type SeverityDistribution,
+} from "./parity-telemetry"

package/src/features/migration/migration-adapter.ts

@@ -0,0 +1,151 @@
+import {
+  createDropDiagnosticsCollector,
+  type DropDiagnosticsCollector,
+} from "../../shared/drop-diagnostics"
+import { normalizeLegacyFindingsArray, normalizeToCanonicalFinding } from "../../state/adapters"
+import type { CanonicalFinding, ReportInput } from "../../state/schemas"
+import { SCHEMA_VERSION } from "../../state/schemas"
+import type { AuditState, Finding } from "../../state/types"
+
+export type MigrationMode = "legacy" | "dual" | "strict"
+
+/**
+ * Returns the active migration mode from config, defaulting to "legacy".
+ */
+export function getMigrationMode(config: { migration?: { mode?: MigrationMode } }): MigrationMode {
+  return config.migration?.mode ?? "legacy"
+}
+
+/**
+ * Adapts a legacy `AuditState` into canonical `CanonicalFinding[]`.
+ *
+ * In legacy mode: returns the raw findings as-is (backward compatible).
+ * In dual mode: normalizes findings to canonical AND returns both.
+ * In strict mode: normalizes to canonical, rejects payloads missing required canonical fields.
+ */
+export function adaptLegacyFindings(
+  state: AuditState,
+  mode: MigrationMode,
+  runId: string,
+): {
+  legacyFindings: Finding[]
+  canonicalFindings: CanonicalFinding[]
+  diagnostics: ReturnType<DropDiagnosticsCollector["getDiagnostics"]>
+} {
+  const legacyFindings = state.findings
+
+  if (mode === "legacy") {
+    return {
+      legacyFindings,
+      canonicalFindings: [],
+      diagnostics: [],
+    }
+  }
+
+  const policy = mode === "strict" ? "strict-fail" : "warn"
+  const diag = createDropDiagnosticsCollector(policy, "migration-adapter")
+
+  const { findings: canonicalFindings, diagnostics: adapterDiags } = normalizeLegacyFindingsArray(
+    legacyFindings as unknown as unknown[],
+    runId,
+  )
+
+  for (const d of adapterDiags) {
+    if (d.level === "error") {
+      diag.error(d.code, d.message, d.field)
+    } else {
+      diag.warn(d.code, d.message, d.field)
+    }
+  }
+
+  // In strict mode, validate that all legacy findings survived normalization
+  if (mode === "strict" && canonicalFindings.length < legacyFindings.length) {
+    const dropped = legacyFindings.length - canonicalFindings.length
+    diag.error(
+      "STRICT_FINDINGS_DROPPED",
+      `${dropped} legacy finding(s) could not be normalized to canonical format`,
+    )
+  }
+
+  // Throws DropDiagnosticsError in strict mode if errors exist
+  diag.throwIfStrict()
+
+  return {
+    legacyFindings,
+    canonicalFindings,
+    diagnostics: diag.getDiagnostics(),
+  }
+}
+
+/**
+ * Adapts a legacy `AuditState` into a canonical `ReportInput`.
+ *
+ * Maps legacy AuditState fields to the canonical ReportInput contract.
+ */
+export function adaptLegacyStateToReportInput(
+  state: AuditState,
+  mode: MigrationMode,
+  runId: string,
+): {
+  reportInput: ReportInput
+  diagnostics: ReturnType<DropDiagnosticsCollector["getDiagnostics"]>
+} {
+  const { canonicalFindings, diagnostics } = adaptLegacyFindings(
+    state,
+    mode === "legacy" ? "dual" : mode,
+    runId,
+  )
+
+  const reportInput: ReportInput = {
+    run_id: runId,
+    seq: 0,
+    session_id: state.sessionId,
+    tool_call_id: "",
+    source: "migration-adapter",
+    schema_version: SCHEMA_VERSION,
+    projectDir: state.projectDir,
+    findings: canonicalFindings,
+    toolsExecuted: state.toolsExecuted.map((t) => ({
+      ...t,
+      run_id: runId,
+      schema_version: SCHEMA_VERSION,
+    })),
+    scope: state.scope,
+    soloditResults: state.soloditResults,
+    fuzzCounterexamples: state.fuzzCounterexamples,
+    coverageReport: state.coverageReport,
+    gasHotspots: state.gasHotspots,
+    proxyContracts: state.proxyContracts,
+  }
+
+  return { reportInput, diagnostics }
+}
+
+/**
+ * Validates that a legacy AuditState is compatible with strict mode.
+ * Returns true if ALL findings can be normalized without errors.
+ */
+export function validateStrictCompatibility(
+  state: AuditState,
+  runId: string,
+): { compatible: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  for (const [index, finding] of state.findings.entries()) {
+    const result = normalizeToCanonicalFinding(
+      finding as unknown as Record<string, unknown>,
+      runId,
+      index + 1,
+    )
+    const hasErrors = result.diagnostics.some((d) => d.level === "error")
+    if (hasErrors) {
+      errors.push(
+        ...result.diagnostics
+          .filter((d) => d.level === "error")
+          .map((d) => `[finding:${index}] ${d.message}`),
+      )
+    }
+  }
+
+  return { compatible: errors.length === 0, errors }
+}

package/src/features/migration/parity-telemetry.ts

@@ -0,0 +1,133 @@
+import { stableHash } from "../../state/projectors"
+import type { CanonicalFinding } from "../../state/schemas"
+import type { Finding, FindingSeverity } from "../../state/types"
+
+const SEVERITIES: readonly FindingSeverity[] = [
+  "Critical",
+  "High",
+  "Medium",
+  "Low",
+  "Informational",
+] as const
+
+export interface SeverityDistribution {
+  Critical: number
+  High: number
+  Medium: number
+  Low: number
+  Informational: number
+}
+
+export interface ParityMetrics {
+  legacyFindingCount: number
+  canonicalFindingCount: number
+  findingCountDiff: number
+  legacySeverityDistribution: SeverityDistribution
+  canonicalSeverityDistribution: SeverityDistribution
+  severityDiffs: Partial<Record<FindingSeverity, number>>
+  legacyContentHash: string
+  canonicalContentHash: string
+  hashMatch: boolean
+  onlyInLegacy: string[]
+  onlyInCanonical: string[]
+  timestamp: number
+}
+
+function computeSeverityDistribution(
+  findings: Array<{ severity: FindingSeverity }>,
+): SeverityDistribution {
+  const dist: SeverityDistribution = {
+    Critical: 0,
+    High: 0,
+    Medium: 0,
+    Low: 0,
+    Informational: 0,
+  }
+  for (const f of findings) {
+    if (f.severity in dist) {
+      dist[f.severity]++
+    }
+  }
+  return dist
+}
+
+function findingIds(findings: Array<{ id: string }>): Set<string> {
+  return new Set(findings.map((f) => f.id))
+}
+
+export function computeParityMetrics(
+  legacyFindings: Finding[],
+  canonicalFindings: CanonicalFinding[],
+): ParityMetrics {
+  const legacySeverity = computeSeverityDistribution(legacyFindings)
+  const canonicalSeverity = computeSeverityDistribution(canonicalFindings)
+
+  const severityDiffs: Partial<Record<FindingSeverity, number>> = {}
+  for (const sev of SEVERITIES) {
+    const diff = canonicalSeverity[sev] - legacySeverity[sev]
+    if (diff !== 0) {
+      severityDiffs[sev] = diff
+    }
+  }
+
+  const legacyIds = findingIds(legacyFindings)
+  const canonicalIds = findingIds(canonicalFindings)
+
+  const onlyInLegacy = [...legacyIds].filter((id) => !canonicalIds.has(id))
+  const onlyInCanonical = [...canonicalIds].filter((id) => !legacyIds.has(id))
+
+  const legacyContentHash = stableHash(
+    legacyFindings.map((f) => ({ id: f.id, check: f.check, severity: f.severity, file: f.file })),
+  )
+  const canonicalContentHash = stableHash(
+    canonicalFindings.map((f) => ({
+      id: f.id,
+      check: f.check,
+      severity: f.severity,
+      file: f.file,
+    })),
+  )
+
+  return {
+    legacyFindingCount: legacyFindings.length,
+    canonicalFindingCount: canonicalFindings.length,
+    findingCountDiff: canonicalFindings.length - legacyFindings.length,
+    legacySeverityDistribution: legacySeverity,
+    canonicalSeverityDistribution: canonicalSeverity,
+    severityDiffs,
+    legacyContentHash,
+    canonicalContentHash,
+    hashMatch: legacyContentHash === canonicalContentHash,
+    onlyInLegacy,
+    onlyInCanonical,
+    timestamp: Date.now(),
+  }
+}
+
+export function formatParityReport(metrics: ParityMetrics): string {
+  const lines: string[] = [
+    "=== Migration Parity Report ===",
+    `Finding count: legacy=${metrics.legacyFindingCount} canonical=${metrics.canonicalFindingCount} diff=${metrics.findingCountDiff}`,
+    `Content hash match: ${metrics.hashMatch}`,
+  ]
+
+  const sevDiffs = Object.entries(metrics.severityDiffs)
+  if (sevDiffs.length > 0) {
+    lines.push(
+      `Severity diffs: ${sevDiffs.map(([k, v]) => `${k}=${v > 0 ? "+" : ""}${v}`).join(", ")}`,
+    )
+  }
+
+  if (metrics.onlyInLegacy.length > 0) {
+    lines.push(
+      `Only in legacy (${metrics.onlyInLegacy.length}): ${metrics.onlyInLegacy.join(", ")}`,
+    )
+  }
+  if (metrics.onlyInCanonical.length > 0) {
+    lines.push(
+      `Only in canonical (${metrics.onlyInCanonical.length}): ${metrics.onlyInCanonical.join(", ")}`,
+    )
+  }
+
+  return lines.join("\n")
+}