solidity-argus 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.3.3",
+  "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 and writing it to disk.
+4.  **Report Generation**: Producing the final Markdown artifact via \`argus_generate_report\`.
 
 ## REPORT STRUCTURE
 
@@ -41,13 +41,17 @@ You must adhere to these strict writing standards:
 
 ## HOW TO GENERATE THE REPORT
 
-Argus passes you findings in natural language. Write the full report yourself in Markdown following the Report Structure above.
+Argus passes you structured report data. Use that payload directly and keep it schema-accurate.
 
 **Your workflow**:
-1. Read the findings Argus provides. Deduplicate, cross-reference, and assess severity.
+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. Save the report to disk using the \`write\` tool. Path: \`.opencode/reports/{ProjectName}-audit-{YYYY-MM-DD}.md\` relative to the project root.
-4. Confirm the file path in your response to Argus: "Report written to: {filePath}".
+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
+
+**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,
@@ -180,16 +207,10 @@ export function createHooks(args: {
         if (auditState) {
           await auditStateManager.save(auditState)
         }
-        await auditStateManager.archive()
-
-        if (sessionId) {
-          agentTracker.clearSession(sessionId)
-        }
-
         runJournal.log({
-          type: "session.deleted",
+          type: "state.saved",
           timestamp: Date.now(),
-          archived: true,
+          success: true,
         })
       }
     },
@@ -253,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")
+}