parallax-opencode 0.2.0

package/dist/score.js

@@ -0,0 +1,160 @@
+/**
+ * PARALLAX ENGINE -- Coherence Score Computation
+ *
+ * Computes an evidence-based quality score (0-100) from a Parallax trace.
+ * Measures how well the agent followed the methodology.
+ *
+ * Score components:
+ *   - Protocol Coverage (30%): Did all 5 protocol phases execute?
+ *   - Verification Integrity (35%): Pass rate on first attempt?
+ *   - Edge Case Coverage (20%): How many edge categories analyzed?
+ *   - Timing Discipline (15%): Were phases in correct order?
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+import { join } from "path";
+import { existsSync, appendFileSync, readFileSync, mkdirSync } from "fs";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const REQUIRED_PHASES = [
+    "ambiguity_check",
+    "four_invariants",
+    "verification_gate",
+    "commit_decision",
+    "summary",
+];
+const PHASE_ORDER = [
+    "ambiguity_check",
+    "four_invariants",
+    "verification_gate",
+    "mode_switch",
+    "execution",
+    "commit_decision",
+    "summary",
+];
+// ---------------------------------------------------------------------------
+// Score computation
+// ---------------------------------------------------------------------------
+/**
+ * Compute the coherence score (0-100) from a trace.
+ * Handles missing data and partial traces gracefully.
+ */
+export function computeCoherenceScore(trace) {
+    // 1. Protocol Coverage (30 points max)
+    const phaseNames = new Set(trace.phases.map((p) => p.phase));
+    const completed = REQUIRED_PHASES.filter((r) => phaseNames.has(r)).length;
+    const protocolCoverage = Math.round((completed / REQUIRED_PHASES.length) * 30);
+    // 2. Verification Integrity (35 points max)
+    let verificationIntegrity = 0;
+    const writesWithData = trace.writes.filter((w) => w.verification !== "unknown");
+    if (writesWithData.length > 0) {
+        const firstPass = writesWithData.filter((w) => w.verification === "pass" && w.frictionRetriesLeft >= 3).length;
+        verificationIntegrity = Math.round((firstPass / writesWithData.length) * 35);
+    }
+    // 3. Edge Case Coverage (20 points max)
+    // Count unique edge categories from analyze phases
+    const analyzePhases = trace.phases.filter((p) => p.phase === "mode_switch" && p.data && typeof p.data.analysisTopic === "string");
+    // Each unique analysis topic counts as an edge category
+    const edgeCategories = new Set(analyzePhases.map((p) => p.data.analysisTopic));
+    const edgeCaseCoverage = Math.min(Math.round((edgeCategories.size / 7) * 20), 20);
+    // 4. Timing Discipline (15 points max)
+    let inOrder = 0;
+    let lastIdx = -1;
+    for (const phase of trace.phases) {
+        const idx = PHASE_ORDER.indexOf(phase.phase);
+        if (idx > lastIdx) {
+            inOrder++;
+            lastIdx = idx;
+        }
+    }
+    const timingDiscipline = Math.min(Math.round((inOrder / REQUIRED_PHASES.length) * 15), 15);
+    const total = Math.min(protocolCoverage + verificationIntegrity + edgeCaseCoverage + timingDiscipline, 100);
+    return {
+        total,
+        protocolCoverage,
+        verificationIntegrity,
+        edgeCaseCoverage,
+        timingDiscipline,
+    };
+}
+// ---------------------------------------------------------------------------
+// Score display helpers
+// ---------------------------------------------------------------------------
+/**
+ * Get a human-readable grade for a score.
+ */
+export function scoreToGrade(score) {
+    if (score >= 90)
+        return "S";
+    if (score >= 80)
+        return "A";
+    if (score >= 70)
+        return "B";
+    if (score >= 60)
+        return "C";
+    if (score >= 40)
+        return "D";
+    return "F";
+}
+/**
+ * Format score breakdown for display.
+ */
+export function formatScoreBreakdown(breakdown) {
+    return [
+        `Coherence Score: ${breakdown.total}/100 (${scoreToGrade(breakdown.total)})`,
+        ``,
+        `  Protocol Coverage:     ${breakdown.protocolCoverage}/30  (phases completed)`,
+        `  Verification Integrity: ${breakdown.verificationIntegrity}/35  (first-pass rate)`,
+        `  Edge Case Coverage:    ${breakdown.edgeCaseCoverage}/20  (categories analyzed)`,
+        `  Timing Discipline:     ${breakdown.timingDiscipline}/15  (phase ordering)`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Trend tracking
+// ---------------------------------------------------------------------------
+const SCORES_DIR = ".parallax";
+const SCORES_FILE = join(SCORES_DIR, "scores.jsonl");
+function getScoresFilePath() {
+    return join(process.cwd(), SCORES_FILE);
+}
+/**
+ * Record a score entry to the append-only scores file.
+ */
+export function recordScore(entry) {
+    const filePath = getScoresFilePath();
+    const dir = join(process.cwd(), SCORES_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    appendFileSync(filePath, JSON.stringify(entry) + "\n", "utf8");
+}
+/**
+ * Read all score entries from the scores file.
+ */
+export function readScoreHistory() {
+    const filePath = getScoresFilePath();
+    if (!existsSync(filePath))
+        return [];
+    try {
+        const raw = readFileSync(filePath, "utf8");
+        return raw
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Compute a simple sparkline representation of scores over time.
+ */
+export function sparkline(scores) {
+    if (scores.length === 0)
+        return "";
+    const chars = ["_", "▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+    const max = Math.max(...scores, 1);
+    return scores.map((s) => chars[Math.min(Math.floor((s / max) * (chars.length - 1)), chars.length - 1)]).join("");
+}

package/dist/trace.d.ts

@@ -0,0 +1,62 @@
+/**
+ * PARALLAX ENGINE -- Trace Recording & Export
+ *
+ * Manages the per-session structured reasoning trace. Traces capture every
+ * protocol phase, write operation, verification result, and mode switch.
+ *
+ * Traces persist to `.parallax/traces/<session-id>.json` on demand or
+ * on session compaction.
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+import type { ParallaxTrace, PhaseName, WriteVerdict, TraceMetrics, ProjectType } from "./types";
+/**
+ * Get or create a trace for the given session ID.
+ */
+export declare function getTrace(sessionId: string): ParallaxTrace;
+/**
+ * Initialize trace with session and project metadata.
+ */
+export declare function initTrace(sessionId: string, project: string | null, projectType: ProjectType): void;
+/**
+ * Record a protocol phase in the trace.
+ */
+export declare function addPhase(sessionId: string, phase: PhaseName, data?: Record<string, unknown>): void;
+/**
+ * Record a write/edit operation in the trace.
+ */
+export declare function addWrite(sessionId: string, file: string, verification: WriteVerdict, frictionRetriesLeft: number): void;
+/**
+ * Compute metrics for the trace.
+ */
+export declare function computeMetrics(trace: ParallaxTrace): TraceMetrics;
+/**
+ * Finalize the trace (set end time and compute metrics).
+ */
+export declare function finalizeTrace(sessionId: string): ParallaxTrace;
+/**
+ * Export the current trace to a JSON file on disk.
+ * Returns the file path.
+ */
+export declare function exportTrace(sessionId: string, pretty?: boolean): string;
+/**
+ * Export trace with pretty formatting (human-readable).
+ */
+export declare function exportTracePretty(sessionId: string): string;
+/**
+ * List all trace files in the project's trace directory.
+ */
+export declare function listTraceFiles(): Array<{
+    sessionId: string;
+    filePath: string;
+    mtime: Date;
+}>;
+/**
+ * Load a trace from disk by session ID.
+ */
+export declare function loadTrace(sessionId: string): ParallaxTrace | null;
+/**
+ * Delete all in-memory trace state for a session (cleanup).
+ */
+export declare function cleanupTrace(sessionId: string): void;

package/dist/trace.js

@@ -0,0 +1,206 @@
+/**
+ * PARALLAX ENGINE -- Trace Recording & Export
+ *
+ * Manages the per-session structured reasoning trace. Traces capture every
+ * protocol phase, write operation, verification result, and mode switch.
+ *
+ * Traces persist to `.parallax/traces/<session-id>.json` on demand or
+ * on session compaction.
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const TRACE_DIR_RELATIVE = join(".parallax", "traces");
+const TRACE_SCHEMA_VERSION = "1.0";
+// ---------------------------------------------------------------------------
+// In-memory trace store (per session ID)
+// ---------------------------------------------------------------------------
+const traceStore = new Map();
+/**
+ * Get or create a trace for the given session ID.
+ */
+export function getTrace(sessionId) {
+    if (!traceStore.has(sessionId)) {
+        traceStore.set(sessionId, createEmptyTrace(sessionId));
+    }
+    return traceStore.get(sessionId);
+}
+/**
+ * Create a fresh empty trace for a session.
+ */
+function createEmptyTrace(sessionId) {
+    return {
+        schemaVersion: TRACE_SCHEMA_VERSION,
+        session: {
+            id: sessionId,
+            agent: "parallax",
+            agentVersion: "0.2.0",
+            startedAt: new Date().toISOString(),
+            endedAt: null,
+            project: null,
+            projectType: null,
+        },
+        phases: [],
+        writes: [],
+        metrics: null,
+        coherenceScore: null,
+    };
+}
+/**
+ * Initialize trace with session and project metadata.
+ */
+export function initTrace(sessionId, project, projectType) {
+    const trace = getTrace(sessionId);
+    trace.session.project = project;
+    trace.session.projectType = projectType;
+}
+/**
+ * Record a protocol phase in the trace.
+ */
+export function addPhase(sessionId, phase, data = {}) {
+    const trace = getTrace(sessionId);
+    const record = {
+        phase,
+        timestamp: new Date().toISOString(),
+        data,
+    };
+    trace.phases.push(record);
+}
+/**
+ * Record a write/edit operation in the trace.
+ */
+export function addWrite(sessionId, file, verification, frictionRetriesLeft) {
+    const trace = getTrace(sessionId);
+    const record = {
+        file,
+        timestamp: new Date().toISOString(),
+        verification,
+        frictionRetriesLeft,
+    };
+    trace.writes.push(record);
+}
+/**
+ * Compute metrics for the trace.
+ */
+export function computeMetrics(trace) {
+    const started = new Date(trace.session.startedAt).getTime();
+    const now = Date.now();
+    const durationSeconds = Math.round((now - started) / 1000);
+    const totalWrites = trace.writes.length;
+    const totalWritesWithData = trace.writes.filter((w) => w.verification !== "unknown").length;
+    const passes = trace.writes.filter((w) => w.verification === "pass").length;
+    const firstPass = trace.writes.filter((w) => w.verification === "pass" && w.frictionRetriesLeft >= 3).length;
+    const totalFrictionRetries = trace.writes.reduce((sum, w) => sum + (3 - w.frictionRetriesLeft), 0);
+    const requiredPhases = [
+        "ambiguity_check",
+        "four_invariants",
+        "verification_gate",
+        "commit_decision",
+        "summary",
+    ];
+    const uniqueRequiredPhases = new Set(trace.phases
+        .filter((p) => requiredPhases.includes(p.phase))
+        .map((p) => p.phase));
+    return {
+        durationSeconds,
+        totalPhases: trace.phases.length,
+        totalWrites,
+        verificationPassRate: totalWritesWithData > 0 ? passes / totalWritesWithData : 0,
+        firstAttemptPassRate: totalWrites > 0 ? firstPass / totalWrites : 0,
+        totalFrictionRetries,
+        protocolStepsCompleted: uniqueRequiredPhases.size,
+    };
+}
+/**
+ * Finalize the trace (set end time and compute metrics).
+ */
+export function finalizeTrace(sessionId) {
+    const trace = getTrace(sessionId);
+    trace.session.endedAt = new Date().toISOString();
+    trace.metrics = computeMetrics(trace);
+    return trace;
+}
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+/**
+ * Get the trace directory path for the current project.
+ * Creates the directory if it doesn't exist.
+ */
+function getTraceDir() {
+    const dir = join(process.cwd(), TRACE_DIR_RELATIVE);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+/**
+ * Export the current trace to a JSON file on disk.
+ * Returns the file path.
+ */
+export function exportTrace(sessionId, pretty = false) {
+    const trace = finalizeTrace(sessionId);
+    const dir = getTraceDir();
+    const filePath = join(dir, `${sessionId}.json`);
+    const json = pretty ? JSON.stringify(trace, null, 2) : JSON.stringify(trace);
+    writeFileSync(filePath, json, "utf8");
+    return filePath;
+}
+/**
+ * Export trace with pretty formatting (human-readable).
+ */
+export function exportTracePretty(sessionId) {
+    return exportTrace(sessionId, true);
+}
+/**
+ * List all trace files in the project's trace directory.
+ */
+export function listTraceFiles() {
+    const dir = getTraceDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => {
+        const filePath = join(dir, f);
+        let mtime = new Date();
+        try {
+            mtime = statSync(filePath).mtime;
+        }
+        catch {
+            // fall through to current time
+        }
+        return {
+            sessionId: f.replace(/\.json$/, ""),
+            filePath,
+            mtime,
+        };
+    });
+}
+/**
+ * Load a trace from disk by session ID.
+ */
+export function loadTrace(sessionId) {
+    const dir = getTraceDir();
+    const filePath = join(dir, `${sessionId}.json`);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete all in-memory trace state for a session (cleanup).
+ */
+export function cleanupTrace(sessionId) {
+    traceStore.delete(sessionId);
+}

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * PARALLAX ENGINE -- Shared Types
+ *
+ * Central type definitions used across the plugin, trace system, score
+ * computation, and CLI.
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+export type AgentMode = "free" | "plan" | "build" | "debug";
+export type ProtocolStep = "ambiguity" | "invariants" | "gate" | "commit" | "summary";
+export type ProjectType = "cargo" | "tsc" | "lint" | "python" | null;
+export interface FrictionState {
+    successes: number;
+    trials: number;
+    retriesLeft: number;
+    lastObservation: string | null;
+}
+export interface ModeState {
+    mode: AgentMode;
+}
+export interface ProtocolState {
+    ambiguityDone: boolean;
+    invariantsDone: boolean;
+    gateDone: boolean;
+    commitDone: boolean;
+    summaryDone: boolean;
+    writesBeforeGate: number;
+    gateBlocked: boolean;
+}
+export interface VerifyResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    combined: string;
+}
+export type PhaseName = "ambiguity_check" | "four_invariants" | "verification_gate" | "mode_switch" | "execution" | "commit_decision" | "summary";
+export type WriteVerdict = "pass" | "fail" | "skipped" | "unknown";
+export interface PhaseRecord {
+    phase: PhaseName;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+export interface WriteRecord {
+    file: string;
+    timestamp: string;
+    verification: WriteVerdict;
+    frictionRetriesLeft: number;
+}
+export interface TraceSessionMeta {
+    id: string | null;
+    agent: "parallax";
+    agentVersion: string;
+    startedAt: string;
+    endedAt: string | null;
+    project: string | null;
+    projectType: string | null;
+}
+export interface TraceMetrics {
+    durationSeconds: number;
+    totalPhases: number;
+    totalWrites: number;
+    verificationPassRate: number;
+    firstAttemptPassRate: number;
+    totalFrictionRetries: number;
+    protocolStepsCompleted: number;
+}
+export interface ParallaxTrace {
+    schemaVersion: "1.0";
+    session: TraceSessionMeta;
+    phases: PhaseRecord[];
+    writes: WriteRecord[];
+    metrics: TraceMetrics | null;
+    coherenceScore: number | null;
+}
+export interface ScoreBreakdown {
+    total: number;
+    protocolCoverage: number;
+    verificationIntegrity: number;
+    edgeCaseCoverage: number;
+    timingDiscipline: number;
+}
+export interface ScoreEntry {
+    sessionId: string;
+    date: string;
+    score: number;
+    project: string | null;
+}
+export interface CliCommand {
+    name: string;
+    description: string;
+    usage: string;
+    run: (args: string[]) => Promise<number>;
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * PARALLAX ENGINE -- Shared Types
+ *
+ * Central type definitions used across the plugin, trace system, score
+ * computation, and CLI.
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+export {};

package/dist-standalone/parallax-engine.d.ts

@@ -0,0 +1,99 @@
+/**
+ * PARALLAX ENGINE -- Canonical TypeScript Plugin
+ *
+ * Consolidated source of truth for the Parallax Engine OpenCode plugin.
+ * Contains all 7 custom tools, mode state machine (free/plan/build/debug),
+ * protocol enforcement, friction-loop verification, skill injection,
+ * session state preservation, and trace recording.
+ *
+ * License: MIT
+ * Copyright (c) 2026 Master0fFate
+ */
+declare const _default: {
+    id: string;
+    server: ({ client }: import("@opencode-ai/plugin").PluginInput) => Promise<{
+        tool: {
+            parallax_verify: {
+                description: string;
+                args: {};
+                execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            parallax_analyze: {
+                description: string;
+                args: {
+                    topic: import("zod").ZodString;
+                };
+                execute(args: {
+                    topic: string;
+                }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            parallax_checkin: {
+                description: string;
+                args: {
+                    step: import("zod").ZodString;
+                };
+                execute(args: {
+                    step: string;
+                }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            parallax_plan: {
+                description: string;
+                args: {};
+                execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            parallax_build: {
+                description: string;
+                args: {};
+                execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            parallax_debug: {
+                description: string;
+                args: {};
+                execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            parallax_trace_export: {
+                description: string;
+                args: {
+                    pretty: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                };
+                execute(args: {
+                    pretty?: boolean | undefined;
+                }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+        };
+        "tool.execute.before": (input: {
+            tool: string;
+        }) => Promise<void>;
+        "tool.execute.after": (input: {
+            tool: string;
+            args?: Record<string, unknown>;
+        }) => Promise<void>;
+        event: (input: {
+            event: {
+                type: string;
+                properties?: Record<string, unknown>;
+            };
+        }) => Promise<void>;
+        "chat.message": (input: {
+            sessionID: string;
+            agent?: string;
+            model?: {
+                modelID?: string;
+            };
+        }) => Promise<void>;
+        "chat.params": (input: {
+            sessionID: string;
+            agent: string;
+            model: {
+                id: string;
+            };
+        }) => Promise<void>;
+        "experimental.chat.system.transform": (_input: unknown, output: {
+            system?: string[];
+        }) => Promise<void>;
+        "experimental.session.compacting": (_input: unknown, output: {
+            context?: string[];
+        }) => Promise<void>;
+    }>;
+};
+export default _default;