solidity-argus 0.3.2 → 0.3.4

package/src/features/persistent-state/event-sink.ts

@@ -0,0 +1,171 @@
+import { mkdir, rename } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import type { AuditEvent, AuditEventType } from "../../state/schemas"
+
+export type EventSinkErrorCode = "SEQUENCE_CONFLICT" | "INVALID_EVENT" | "IO_ERROR"
+
+export class EventSinkError extends Error {
+  readonly code: EventSinkErrorCode
+
+  constructor(code: EventSinkErrorCode, message: string) {
+    super(message)
+    this.name = "EventSinkError"
+    this.code = code
+  }
+}
+
+export interface EventSink {
+  append(event: AuditEvent): Promise<void>
+  readAll(): Promise<AuditEvent[]>
+}
+
+const VALID_EVENT_TYPES: ReadonlySet<string> = new Set<AuditEventType>([
+  "session.created",
+  "session.idle",
+  "session.deleted",
+  "tool.started",
+  "tool.completed",
+  "finding.added",
+  "phase.changed",
+  "run.finalized",
+])
+
+function createMutex() {
+  let chain = Promise.resolve()
+
+  return {
+    async run<T>(fn: () => Promise<T>): Promise<T> {
+      const prev = chain
+      let release!: () => void
+      chain = new Promise<void>((r) => {
+        release = r
+      })
+
+      await prev
+
+      try {
+        return await fn()
+      } finally {
+        release()
+      }
+    },
+  }
+}
+
+function buildJournalPath(runId: string, projectDir: string): string {
+  return join(projectDir, ".opencode", "runs", runId, "events.jsonl")
+}
+
+async function readRawContent(path: string): Promise<string> {
+  const file = Bun.file(path)
+  if (!(await file.exists())) {
+    return ""
+  }
+  return file.text()
+}
+
+function parseJournalLines(content: string): AuditEvent[] {
+  if (!content.trim()) return []
+
+  const lines = content.split("\n").filter(Boolean)
+  const events: AuditEvent[] = []
+
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line) as AuditEvent)
+    } catch {
+      /* skip malformed lines */
+    }
+  }
+
+  events.sort((a, b) => a.seq - b.seq)
+  return events
+}
+
+/**
+ * Replay-safe stateless read — returns all events for a run sorted by seq.
+ */
+export async function readEvents(runId: string, projectDir: string): Promise<AuditEvent[]> {
+  const journalPath = buildJournalPath(runId, projectDir)
+  const content = await readRawContent(journalPath)
+  return parseJournalLines(content)
+}
+
+/**
+ * Append-only event sink with monotonic seq allocation, in-process mutex,
+ * and atomic temp-file-then-rename writes. Restart-safe via journal replay.
+ */
+export function createEventSink(runId: string, projectDir: string): EventSink {
+  const journalPath = buildJournalPath(runId, projectDir)
+  const mutex = createMutex()
+  let lastSeq = 0
+  let initialized = false
+
+  async function ensureInitialized(): Promise<void> {
+    if (initialized) return
+
+    try {
+      const content = await readRawContent(journalPath)
+      const events = parseJournalLines(content)
+      const lastEvent = events.at(-1)
+      if (lastEvent) {
+        lastSeq = lastEvent.seq
+      }
+    } catch (err) {
+      throw new EventSinkError("IO_ERROR", `Failed to initialize event sink: ${String(err)}`)
+    }
+
+    initialized = true
+  }
+
+  return {
+    async append(event: AuditEvent): Promise<void> {
+      return mutex.run(async () => {
+        await ensureInitialized()
+
+        if (event.run_id !== runId) {
+          throw new EventSinkError(
+            "INVALID_EVENT",
+            `Event run_id "${event.run_id}" does not match sink run_id "${runId}"`,
+          )
+        }
+
+        if (!event.type || !VALID_EVENT_TYPES.has(event.type)) {
+          throw new EventSinkError("INVALID_EVENT", `Invalid event type "${String(event.type)}"`)
+        }
+
+        if (event.seq > 0 && event.seq <= lastSeq) {
+          throw new EventSinkError(
+            "SEQUENCE_CONFLICT",
+            `Event seq ${event.seq} conflicts with last assigned seq ${lastSeq}; must be > ${lastSeq}`,
+          )
+        }
+
+        const nextSeq = lastSeq + 1
+        const eventToWrite: AuditEvent = { ...event, seq: nextSeq }
+
+        const currentContent = await readRawContent(journalPath)
+        const newContent = `${currentContent}${JSON.stringify(eventToWrite)}\n`
+
+        await mkdir(dirname(journalPath), { recursive: true })
+
+        const suffix = `${Date.now()}.${Math.random().toString(36).slice(2)}`
+        const tempPath = `${journalPath}.${suffix}.tmp`
+
+        try {
+          await Bun.write(tempPath, newContent)
+          await rename(tempPath, journalPath)
+        } catch (err) {
+          throw new EventSinkError("IO_ERROR", `Failed to write event to journal: ${String(err)}`)
+        }
+
+        lastSeq = nextSeq
+      })
+    },
+
+    async readAll(): Promise<AuditEvent[]> {
+      const content = await readRawContent(journalPath)
+      return parseJournalLines(content)
+    },
+  }
+}

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

@@ -1 +1,3 @@
 export { createAuditStateManager } from "./audit-state-manager"
+export { createEventSink, readEvents, EventSinkError } from "./event-sink"
+export type { EventSink, EventSinkErrorCode } from "./event-sink"

package/src/features/persistent-state/run-finalizer.ts

@@ -0,0 +1,175 @@
+import { validateEventSequence } from "../../state/projectors"
+import type { AuditEvent } from "../../state/schemas"
+import { SCHEMA_VERSION } from "../../state/schemas"
+import type { EventSink } from "./event-sink"
+import { readEvents } from "./event-sink"
+
+export type FinalizationResult = {
+  success: boolean
+  invariantsPassed: boolean
+  errors: string[]
+  runId: string
+  timestamp: number
+}
+
+function hasSessionCreated(events: AuditEvent[]): boolean {
+  return events.some((event) => event.type === "session.created")
+}
+
+function hasSessionDeleted(events: AuditEvent[]): boolean {
+  return events.some((event) => event.type === "session.deleted")
+}
+
+function collectOrphanedToolStarts(events: AuditEvent[]): string[] {
+  const startedCallIds = new Set<string>()
+  const completedCallIds = new Set<string>()
+  const errors: string[] = []
+
+  for (const event of events) {
+    if (event.type !== "tool.started" && event.type !== "tool.completed") {
+      continue
+    }
+
+    if (typeof event.tool_call_id !== "string" || event.tool_call_id.length === 0) {
+      errors.push(`${event.type} at seq ${event.seq} missing tool_call_id`)
+      continue
+    }
+
+    if (event.type === "tool.started") {
+      startedCallIds.add(event.tool_call_id)
+    }
+
+    if (event.type === "tool.completed") {
+      completedCallIds.add(event.tool_call_id)
+    }
+  }
+
+  for (const toolCallId of startedCallIds) {
+    if (!completedCallIds.has(toolCallId)) {
+      errors.push(`orphaned tool.started without matching tool.completed: ${toolCallId}`)
+    }
+  }
+
+  return errors
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return null
+}
+
+function collectParentChildIntegrityErrors(events: AuditEvent[]): string[] {
+  const errors: string[] = []
+  const parentByChild = new Map<string, string>()
+  const correlationByChild = new Map<string, string>()
+
+  for (const event of events) {
+    const payload = asRecord(event.payload)
+    if (!payload) {
+      continue
+    }
+
+    const childSessionId = payload.child_session_id
+    if (typeof childSessionId !== "string" || childSessionId.length === 0) {
+      continue
+    }
+
+    const parentSessionId = event.session_id
+    if (!parentSessionId) {
+      errors.push(`child session edge at seq ${event.seq} missing parent session_id`)
+      continue
+    }
+
+    if (parentSessionId === childSessionId) {
+      errors.push(`child session edge at seq ${event.seq} is self-referential`)
+    }
+
+    const correlationId = payload.correlation_id
+    if (typeof correlationId !== "string" || correlationId.length === 0) {
+      errors.push(`child session edge at seq ${event.seq} missing correlation_id`)
+      continue
+    }
+
+    const existingParent = parentByChild.get(childSessionId)
+    if (existingParent && existingParent !== parentSessionId) {
+      errors.push(
+        `child session ${childSessionId} mapped to multiple parents: ${existingParent}, ${parentSessionId}`,
+      )
+    } else {
+      parentByChild.set(childSessionId, parentSessionId)
+    }
+
+    const existingCorrelation = correlationByChild.get(childSessionId)
+    if (existingCorrelation && existingCorrelation !== correlationId) {
+      errors.push(
+        `child session ${childSessionId} has inconsistent correlation_id: ${existingCorrelation}, ${correlationId}`,
+      )
+    } else {
+      correlationByChild.set(childSessionId, correlationId)
+    }
+  }
+
+  return errors
+}
+
+function collectInvariantErrors(events: AuditEvent[]): string[] {
+  const errors: string[] = []
+
+  try {
+    validateEventSequence(events)
+  } catch (error) {
+    errors.push(`invalid event sequence: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  if (!hasSessionCreated(events)) {
+    errors.push("missing required lifecycle event: session.created")
+  }
+
+  if (!hasSessionDeleted(events)) {
+    errors.push("missing required lifecycle event: session.deleted")
+  }
+
+  errors.push(...collectOrphanedToolStarts(events))
+  errors.push(...collectParentChildIntegrityErrors(events))
+  return errors
+}
+
+export async function finalizeRun(
+  runId: string,
+  projectDir: string,
+  sink: EventSink | null,
+): Promise<FinalizationResult> {
+  const timestamp = Date.now()
+  const events = sink ? await sink.readAll() : await readEvents(runId, projectDir)
+  const errors = collectInvariantErrors(events)
+  const invariantsPassed = errors.length === 0
+  const sessionId = events.at(-1)?.session_id ?? ""
+
+  if (sink) {
+    await sink.append({
+      type: "run.finalized",
+      run_id: runId,
+      seq: 0,
+      session_id: sessionId,
+      source: "run-finalizer",
+      schema_version: SCHEMA_VERSION,
+      timestamp,
+      payload: {
+        finalized: invariantsPassed,
+        invariantsPassed,
+        errors,
+        status: invariantsPassed ? "finalized" : "failed-finalization",
+      },
+    })
+  }
+
+  return {
+    success: invariantsPassed,
+    invariantsPassed,
+    errors,
+    runId,
+    timestamp,
+  }
+}

package/src/features/persistent-state/run-journal.ts

@@ -15,7 +15,7 @@ export type JournalEvent =
       findingsCount: number
       toolsExecutedCount: number
     }
-  | { type: "session.deleted"; timestamp: number; archived: boolean }
+  | { type: "session.deleted"; timestamp: number; archived: boolean; finalizationPassed: boolean | null }
   | {
       type: "tool.executed"
       tool: string

package/src/hooks/agent-tracker.ts

@@ -11,6 +11,7 @@ export type AgentTracker = ReturnType<typeof createAgentTracker>
 
 export function createAgentTracker() {
   const sessions = new Map<string, string>()
+  const childSessions = new Map<string, Set<string>>()
 
   const trackSession = (sessionID: string, agent?: string): void => {
     if (!agent) {
@@ -49,5 +50,19 @@ export function createAgentTracker() {
     getTrackedSessions: (): Map<string, string> => {
       return sessions
     },
+
+    trackChildSession: (parentSessionId: string, childSessionId: string): void => {
+      let children = childSessions.get(parentSessionId)
+      if (!children) {
+        children = new Set()
+        childSessions.set(parentSessionId, children)
+      }
+      children.add(childSessionId)
+    },
+
+    getChildSessions: (parentSessionId: string): string[] => {
+      const children = childSessions.get(parentSessionId)
+      return children ? Array.from(children) : []
+    },
   }
 }

package/src/hooks/event-hook.ts

@@ -1,5 +1,10 @@
+import type { EventSink } from "../features/persistent-state/event-sink"
+import { finalizeRun } from "../features/persistent-state/run-finalizer"
+import type { FinalizationResult } from "../features/persistent-state/run-finalizer"
 import { createLogger } from "../shared/logger"
 import { createAuditState } from "../state/audit-state"
+import type { AuditEvent } from "../state/schemas"
+import { SCHEMA_VERSION } from "../state/schemas"
 import type { AuditState } from "../state/types"
 
 export type AuditEventType =
@@ -29,17 +34,50 @@ export function createEventHook(
   hook: EventHookFn
   getAuditState: () => AuditState | null
   setAuditState: (state: AuditState | null) => void
+  setEventSink: (sink: EventSink | null) => void
+  getLastFinalizationResult: () => FinalizationResult | null
 } {
   const logger = createLogger()
   let currentAuditState: AuditState | null = null
+  let eventSink: EventSink | null = null
+  let lastFinalizationResult: FinalizationResult | null = null
 
   const getAuditState = (): AuditState | null => currentAuditState
   const setAuditState = (state: AuditState | null): void => {
     currentAuditState = state
   }
+  const setEventSink = (sink: EventSink | null): void => {
+    eventSink = sink
+  }
+
+  async function emitToSink(
+    type: AuditEvent["type"],
+    runId: string,
+    sessionId: string | undefined,
+    payload: unknown,
+  ): Promise<void> {
+    if (!eventSink) return
+    try {
+      await eventSink.append({
+        type,
+        run_id: runId,
+        seq: 0, // auto-assigned by sink
+        session_id: sessionId ?? "",
+        source: "event-hook",
+        schema_version: SCHEMA_VERSION,
+        timestamp: Date.now(),
+        payload,
+      })
+    } catch (error) {
+      logger.error(
+        `Failed to emit ${type} event to sink: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
 
   const hook: EventHookFn = async (input): Promise<void> => {
     const { type, sessionId } = input.event
+    let preDeleteState: AuditState | null = null
 
     switch (type) {
       case "session.created": {
@@ -73,6 +111,7 @@ export function createEventHook(
       }
 
       case "session.deleted": {
+        preDeleteState = currentAuditState
         currentAuditState = null
         break
       }
@@ -93,7 +132,60 @@ export function createEventHook(
         logger.error(`Sub-handler failed for event ${type}:`, error)
       }
     }
+
+    // Emit canonical events to sink (after sub-handlers, so sink may have been set during session.created)
+    switch (type) {
+      case "session.created": {
+        if (currentAuditState) {
+          await emitToSink("session.created", currentAuditState.sessionId, sessionId, {
+            projectDir: currentAuditState.projectDir,
+            sessionId: currentAuditState.sessionId,
+          })
+        }
+        break
+      }
+
+      case "session.idle": {
+        if (currentAuditState) {
+          await emitToSink("session.idle", currentAuditState.sessionId, sessionId, {
+            findingsCount: currentAuditState.findings.length,
+            toolsExecutedCount: currentAuditState.toolsExecuted.length,
+            phase: currentAuditState.currentPhase,
+          })
+        }
+        break
+      }
+
+      case "session.deleted": {
+        if (preDeleteState) {
+          await emitToSink("session.deleted", preDeleteState.sessionId, sessionId, {
+            archived: true,
+          })
+
+          if (eventSink) {
+            try {
+              lastFinalizationResult = await finalizeRun(
+                preDeleteState.sessionId,
+                preDeleteState.projectDir,
+                eventSink,
+              )
+            } catch (error) {
+              logger.error(
+                `Failed to finalize run ${preDeleteState.sessionId}: ${error instanceof Error ? error.message : String(error)}`,
+              )
+            }
+          }
+        }
+        eventSink = null
+        break
+      }
+
+      default:
+        break
+    }
   }
 
-  return { hook, getAuditState, setAuditState }
+  const getLastFinalizationResult = (): FinalizationResult | null => lastFinalizationResult
+
+  return { hook, getAuditState, setAuditState, setEventSink, getLastFinalizationResult }
 }