parallax-opencode 0.2.0 → 0.3.0

package/dist/tests/detect.test.js

@@ -0,0 +1,75 @@
+/**
+ * Tests for project detection logic.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+// Mock fs functions used by detectProject
+vi.mock("fs", () => ({
+    existsSync: vi.fn(),
+    statSync: vi.fn(),
+    readFileSync: vi.fn(),
+}));
+function testDetect(files, dirs) {
+    const mockExists = vi.fn((p) => {
+        const path = typeof p === "string" ? p : String(p);
+        return files[path] === true;
+    });
+    const mockStat = vi.fn((p) => {
+        const path = typeof p === "string" ? p : String(p);
+        if (dirs[path])
+            return { isDirectory: () => true };
+        return { isDirectory: () => false };
+    });
+    // Inline the detection logic from plugin.ts
+    try {
+        if (mockExists("Cargo.toml"))
+            return "cargo";
+        if (mockExists("package.json")) {
+            if (mockExists("node_modules") && mockStat("node_modules").isDirectory()) {
+                if (mockExists("tsconfig.json"))
+                    return "tsc";
+                return "lint";
+            }
+        }
+        if (mockExists("pyproject.toml") || mockExists("requirements.txt"))
+            return "python";
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+describe("Project detection", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it("detects cargo project", () => {
+        const result = testDetect({ "Cargo.toml": true }, {});
+        expect(result).toBe("cargo");
+    });
+    it("detects TypeScript project (tsconfig + node_modules)", () => {
+        const result = testDetect({ "package.json": true, "node_modules": true, "tsconfig.json": true }, { "node_modules": true });
+        expect(result).toBe("tsc");
+    });
+    it("detects JS/lint project (package.json + node_modules, no tsconfig)", () => {
+        const result = testDetect({ "package.json": true, "node_modules": true }, { "node_modules": true });
+        expect(result).toBe("lint");
+    });
+    it("detects Python project (pyproject.toml)", () => {
+        const result = testDetect({ "pyproject.toml": true }, {});
+        expect(result).toBe("python");
+    });
+    it("detects Python project (requirements.txt)", () => {
+        const result = testDetect({ "requirements.txt": true }, {});
+        expect(result).toBe("python");
+    });
+    it("returns null for unknown project", () => {
+        const result = testDetect({}, {});
+        expect(result).toBeNull();
+    });
+    it("handles errors gracefully", () => {
+        // The try/catch should return null on any exception
+        const result = testDetect({ "Cargo.toml": true }, {});
+        // Should be "cargo" since we're not throwing
+        expect(result).toBe("cargo");
+    });
+});

package/dist/tests/friction.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/friction.test.js

@@ -0,0 +1,87 @@
+/**
+ * Tests for friction loop state machine.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+const MAX_FRICTION_RETRIES = 3;
+function createState() {
+    return {
+        successes: 0,
+        trials: 0,
+        retriesLeft: MAX_FRICTION_RETRIES,
+        lastObservation: null,
+    };
+}
+function recordSuccess(state) {
+    state.successes++;
+    state.trials++;
+    state.retriesLeft = MAX_FRICTION_RETRIES;
+    state.lastObservation = null;
+}
+function recordFailure(state, msg) {
+    state.trials++;
+    state.retriesLeft--;
+    state.lastObservation = msg;
+}
+// Helper for debounce-like behavior
+function simulateTimeout() {
+    vi.advanceTimersByTime(1000);
+}
+describe("Friction loop state machine", () => {
+    let state;
+    beforeEach(() => {
+        state = createState();
+        vi.useFakeTimers();
+    });
+    it("starts with full retries and no observation", () => {
+        expect(state.successes).toBe(0);
+        expect(state.trials).toBe(0);
+        expect(state.retriesLeft).toBe(3);
+        expect(state.lastObservation).toBeNull();
+    });
+    it("resets retries on success", () => {
+        recordSuccess(state);
+        expect(state.successes).toBe(1);
+        expect(state.trials).toBe(1);
+        expect(state.retriesLeft).toBe(3);
+        expect(state.lastObservation).toBeNull();
+    });
+    it("decrements retries on failure", () => {
+        recordFailure(state, "error: syntax error");
+        expect(state.successes).toBe(0);
+        expect(state.trials).toBe(1);
+        expect(state.retriesLeft).toBe(2);
+        expect(state.lastObservation).toBe("error: syntax error");
+    });
+    it("blocks after 3 consecutive failures", () => {
+        recordFailure(state, "fail 1");
+        expect(state.retriesLeft).toBe(2);
+        recordFailure(state, "fail 2");
+        expect(state.retriesLeft).toBe(1);
+        recordFailure(state, "fail 3");
+        expect(state.retriesLeft).toBe(0);
+        expect(state.lastObservation).toBe("fail 3");
+    });
+    it("recovers after success following failures", () => {
+        recordFailure(state, "fail 1");
+        recordFailure(state, "fail 2");
+        expect(state.retriesLeft).toBe(1);
+        recordSuccess(state);
+        expect(state.retriesLeft).toBe(3);
+        expect(state.successes).toBe(1);
+    });
+    it("accumulates trials correctly", () => {
+        recordSuccess(state);
+        recordSuccess(state);
+        recordFailure(state, "an error");
+        recordSuccess(state);
+        expect(state.trials).toBe(4);
+        expect(state.successes).toBe(3);
+    });
+    it("isolates state per session", () => {
+        const state2 = createState();
+        recordFailure(state, "session A error");
+        expect(state.retriesLeft).toBe(2);
+        expect(state2.retriesLeft).toBe(3);
+        expect(state2.lastObservation).toBeNull();
+    });
+});

package/dist/tests/protocol.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/protocol.test.js

@@ -0,0 +1,80 @@
+/**
+ * Tests for protocol step ordering and enforcement.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+const STEP_LABELS = {
+    ambiguity: "Ambiguity Check",
+    invariants: "4 Invariants",
+    gate: "Verification Gate",
+    commit: "Commit Decision",
+    summary: "Summarize",
+};
+function createProtocol() {
+    return {
+        ambiguityDone: false,
+        invariantsDone: false,
+        gateDone: false,
+        commitDone: false,
+        summaryDone: false,
+        writesBeforeGate: 0,
+        gateBlocked: false,
+    };
+}
+function checkin(p, step) {
+    if (step === "ambiguity" && !p.ambiguityDone) {
+        p.ambiguityDone = true;
+        return "[parallax] Step 1/6: Ambiguity Check marked complete.";
+    }
+    if (step === "invariants") {
+        if (!p.ambiguityDone)
+            return "[parallax] ERROR: Complete Ambiguity Check first (Step 1).";
+        p.invariantsDone = true;
+        return "[parallax] Step 2/6: 4 Invariants marked complete.";
+    }
+    if (step === "gate") {
+        if (!p.invariantsDone)
+            return "[parallax] ERROR: Complete 4 Invariants first (Step 2).";
+        p.gateDone = true;
+        return "[parallax] Step 3/6: Verification Gate marked complete.";
+    }
+    if (step === "commit") {
+        p.commitDone = true;
+        return "[parallax] Step 5/6: Commit Decision marked complete.";
+    }
+    if (step === "summary") {
+        p.summaryDone = true;
+        return "[parallax] Step 6/6: Summary marked complete. Protocol finished.";
+    }
+    return `[parallax] Unknown step "${step}".`;
+}
+describe("Protocol step enforcement", () => {
+    let p;
+    beforeEach(() => {
+        p = createProtocol();
+    });
+    it("enforces correct order: ambiguity -> invariants -> gate", () => {
+        expect(checkin(p, "ambiguity")).toContain("Step 1/6");
+        expect(checkin(p, "invariants")).toContain("Step 2/6");
+        expect(checkin(p, "gate")).toContain("Step 3/6");
+    });
+    it("blocks invariants before ambiguity", () => {
+        expect(checkin(p, "invariants")).toContain("ERROR");
+        expect(p.invariantsDone).toBe(false);
+    });
+    it("blocks gate before invariants", () => {
+        checkin(p, "ambiguity");
+        expect(checkin(p, "gate")).toContain("ERROR");
+        expect(p.gateDone).toBe(false);
+    });
+    it("allows commit and summary at any time after gate", () => {
+        checkin(p, "ambiguity");
+        checkin(p, "invariants");
+        checkin(p, "gate");
+        expect(checkin(p, "commit")).toContain("Step 5/6");
+        expect(checkin(p, "summary")).toContain("Step 6/6");
+        expect(p.summaryDone).toBe(true);
+    });
+    it("rejects unknown steps", () => {
+        expect(checkin(p, "bogus")).toContain("Unknown step");
+    });
+});

package/dist/tests/score.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/score.test.js

@@ -0,0 +1,106 @@
+/**
+ * Tests for coherence score computation.
+ */
+import { describe, it, expect } from "vitest";
+function computeCoherenceScore(trace) {
+    // 1. Protocol Coverage (30 points max)
+    const required = ["ambiguity_check", "four_invariants", "verification_gate", "commit_decision", "summary"];
+    const phaseNames = new Set(trace.phases.map((p) => p.phase));
+    const completed = required.filter((r) => phaseNames.has(r)).length;
+    const protocolScore = (completed / required.length) * 30;
+    // 2. Verification Integrity (35 points max)
+    let integrityScore = 0;
+    if (trace.writes.length > 0) {
+        const firstPass = trace.writes.filter((w) => w.verification === "pass" && w.frictionRetriesLeft === 3).length;
+        integrityScore = (firstPass / trace.writes.length) * 35;
+    }
+    // 3. Edge Case Coverage (20 points max)
+    // For now, check if analyze phases recorded edge categories
+    const analyzePhases = trace.phases.filter((p) => p.phase === "mode_switch" && p.data.analysisTopic);
+    const edgeScore = Math.min(analyzePhases.length / 3, 1) * 20;
+    // 4. Timing Discipline (15 points max)
+    const order = ["ambiguity_check", "four_invariants", "verification_gate", "commit_decision", "summary"];
+    let inOrder = 0;
+    let lastIdx = -1;
+    for (const phase of trace.phases) {
+        const idx = order.indexOf(phase.phase);
+        if (idx > lastIdx) {
+            inOrder++;
+            lastIdx = idx;
+        }
+    }
+    // Normalize to 5 possible
+    const timingScore = Math.min(inOrder / order.length, 1) * 15;
+    return Math.round(protocolScore + integrityScore + edgeScore + timingScore);
+}
+function makeTrace(phases, writes) {
+    return {
+        schemaVersion: "1.0",
+        session: {
+            id: "test",
+            agent: "parallax",
+            agentVersion: "0.2.0",
+            startedAt: "2026-01-01T00:00:00.000Z",
+            endedAt: "2026-01-01T01:00:00.000Z",
+        },
+        phases: phases.map((p) => ({
+            phase: p,
+            timestamp: "2026-01-01T00:00:00.000Z",
+            data: {},
+        })),
+        writes,
+        coherenceScore: null,
+    };
+}
+describe("Coherence score", () => {
+    it("returns 0 for empty trace", () => {
+        const trace = makeTrace([], []);
+        const score = computeCoherenceScore(trace);
+        expect(score).toBe(0);
+    });
+    it("returns near-perfect for complete protocol with all passes", () => {
+        const trace = makeTrace(["ambiguity_check", "four_invariants", "verification_gate", "commit_decision", "summary"], [
+            { file: "a.ts", timestamp: "", verification: "pass", frictionRetriesLeft: 3 },
+            { file: "b.ts", timestamp: "", verification: "pass", frictionRetriesLeft: 3 },
+            { file: "c.ts", timestamp: "", verification: "pass", frictionRetriesLeft: 3 },
+        ]);
+        const score = computeCoherenceScore(trace);
+        // Protocol coverage: 5/5 * 30 = 30
+        // Integrity: 3/3 * 35 = 35
+        // Edge: 0/3 * 20 = 0 (no analyze phases)
+        // Timing: 5/5 * 15 = 15
+        // Total: 80
+        expect(score).toBe(80);
+    });
+    it("penalizes verification failures", () => {
+        const trace = makeTrace(["ambiguity_check", "four_invariants", "verification_gate", "commit_decision", "summary"], [
+            { file: "a.ts", timestamp: "", verification: "pass", frictionRetriesLeft: 3 },
+            { file: "b.ts", timestamp: "", verification: "fail", frictionRetriesLeft: 2 },
+        ]);
+        const score = computeCoherenceScore(trace);
+        // Protocol: 5/5 * 30 = 30
+        // Integrity: 1/2 * 35 = 17.5
+        // Edge: 0
+        // Timing: 5/5 * 15 = 15
+        // Total: 62.5 -> 63
+        expect(score).toBe(63);
+    });
+    it("penalizes missing protocol steps", () => {
+        const trace = makeTrace(["ambiguity_check", "verification_gate"], [
+            { file: "a.ts", timestamp: "", verification: "pass", frictionRetriesLeft: 3 },
+        ]);
+        const score = computeCoherenceScore(trace);
+        // Protocol: 2/5 * 30 = 12
+        // Integrity: 1/1 * 35 = 35
+        // Edge: 0
+        // Timing: inOrder starts with ambiguity (idx 0), then verification_gate (idx 2) -> 2
+        // 2/5 * 15 = 6
+        // Total: 53
+        expect(score).toBe(53);
+    });
+    it("handles partial trace without crashing", () => {
+        const trace = makeTrace([], []);
+        // Should not crash
+        expect(() => computeCoherenceScore(trace)).not.toThrow();
+    });
+});

package/dist/tests/trace.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/trace.test.js

@@ -0,0 +1,109 @@
+/**
+ * Tests for trace recording and export.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+function createTrace() {
+    return {
+        schemaVersion: "1.0",
+        session: {
+            id: "test-session",
+            agent: "parallax",
+            agentVersion: "0.2.0",
+            startedAt: new Date().toISOString(),
+            endedAt: null,
+        },
+        phases: [],
+        writes: [],
+        coherenceScore: null,
+    };
+}
+function addPhase(trace, phase, data = {}) {
+    trace.phases.push({ phase, timestamp: new Date().toISOString(), data });
+}
+function addWrite(trace, file, verdict, retries) {
+    trace.writes.push({
+        file,
+        timestamp: new Date().toISOString(),
+        verification: verdict,
+        frictionRetriesLeft: retries,
+    });
+}
+function computeMetrics(trace) {
+    const totalWrites = trace.writes.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 phaseNames = new Set(trace.phases.map((p) => p.phase));
+    const required = [
+        "ambiguity_check",
+        "four_invariants",
+        "verification_gate",
+        "commit_decision",
+        "summary",
+    ];
+    const completed = required.filter((r) => phaseNames.has(r)).length;
+    return {
+        totalWrites,
+        verificationPassRate: totalWrites > 0 ? passes / totalWrites : 0,
+        firstAttemptPassRate: totalWrites > 0 ? firstPass / totalWrites : 0,
+        protocolStepsCompleted: completed,
+    };
+}
+describe("Trace recording", () => {
+    let trace;
+    beforeEach(() => {
+        trace = createTrace();
+    });
+    it("creates an empty trace with correct schema", () => {
+        expect(trace.schemaVersion).toBe("1.0");
+        expect(trace.session.id).toBe("test-session");
+        expect(trace.phases).toHaveLength(0);
+        expect(trace.writes).toHaveLength(0);
+    });
+    it("records phases in order", () => {
+        addPhase(trace, "ambiguity_check", { level: "LOW" });
+        addPhase(trace, "four_invariants");
+        addPhase(trace, "verification_gate");
+        expect(trace.phases).toHaveLength(3);
+        expect(trace.phases[0].phase).toBe("ambiguity_check");
+        expect(trace.phases[1].phase).toBe("four_invariants");
+        expect(trace.phases[2].phase).toBe("verification_gate");
+        expect(trace.phases[0].data.level).toBe("LOW");
+    });
+    it("records writes with verification status", () => {
+        addWrite(trace, "src/main.ts", "pass", 3);
+        addWrite(trace, "src/lib.ts", "fail", 2);
+        addWrite(trace, "src/utils.ts", "pass", 3);
+        expect(trace.writes).toHaveLength(3);
+        expect(trace.writes[0].file).toBe("src/main.ts");
+        expect(trace.writes[1].verification).toBe("fail");
+        expect(trace.writes[2].frictionRetriesLeft).toBe(3);
+    });
+    it("computes metrics from trace data", () => {
+        addPhase(trace, "ambiguity_check");
+        addPhase(trace, "four_invariants");
+        addPhase(trace, "verification_gate");
+        addPhase(trace, "commit_decision");
+        addPhase(trace, "summary");
+        addWrite(trace, "a.ts", "pass", 3);
+        addWrite(trace, "b.ts", "pass", 3);
+        addWrite(trace, "c.ts", "fail", 1);
+        addWrite(trace, "d.ts", "pass", 3);
+        const metrics = computeMetrics(trace);
+        expect(metrics.totalWrites).toBe(4);
+        expect(metrics.verificationPassRate).toBe(0.75);
+        expect(metrics.firstAttemptPassRate).toBe(0.75); // 3 out of 4 passed on first attempt
+        expect(metrics.protocolStepsCompleted).toBe(5);
+    });
+    it("handles empty trace metrics", () => {
+        const metrics = computeMetrics(trace);
+        expect(metrics.totalWrites).toBe(0);
+        expect(metrics.verificationPassRate).toBe(0);
+        expect(metrics.protocolStepsCompleted).toBe(0);
+    });
+    it("isolates traces by session", () => {
+        const trace2 = createTrace();
+        addPhase(trace, "ambiguity_check");
+        expect(trace.phases).toHaveLength(1);
+        expect(trace2.phases).toHaveLength(0);
+    });
+});

package/dist/types.d.ts

@@ -8,7 +8,7 @@
  * Copyright (c) 2026 Master0fFate
  */
 export type AgentMode = "free" | "plan" | "build" | "debug";
-export type ProtocolStep = "ambiguity" | "invariants" | "gate" | "commit" | "summary";
+export type ProtocolStep = "ambiguity" | "invariants" | "gate" | "design" | "commit" | "summary";
 export type ProjectType = "cargo" | "tsc" | "lint" | "python" | null;
 export interface FrictionState {
     successes: number;
@@ -23,6 +23,7 @@ export interface ProtocolState {
     ambiguityDone: boolean;
     invariantsDone: boolean;
     gateDone: boolean;
+    designDone: boolean;
     commitDone: boolean;
     summaryDone: boolean;
     writesBeforeGate: number;
@@ -34,7 +35,7 @@ export interface VerifyResult {
     stderr: string;
     combined: string;
 }
-export type PhaseName = "ambiguity_check" | "four_invariants" | "verification_gate" | "mode_switch" | "execution" | "commit_decision" | "summary";
+export type PhaseName = "ambiguity_check" | "four_invariants" | "verification_gate" | "design_check" | "mode_switch" | "execution" | "commit_decision" | "summary";
 export type WriteVerdict = "pass" | "fail" | "skipped" | "unknown";
 export interface PhaseRecord {
     phase: PhaseName;
@@ -92,3 +93,11 @@ export interface CliCommand {
     usage: string;
     run: (args: string[]) => Promise<number>;
 }
+export interface ParallaxConfig {
+    strictness?: "strict" | "standard" | "relaxed";
+    minScore?: number;
+    adaptiveProtocol?: boolean;
+    designDocRequired?: boolean;
+    trivialPatterns?: string[];
+    highRiskPatterns?: string[];
+}

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

@@ -60,6 +60,16 @@ declare const _default: {
                     pretty?: boolean | undefined;
                 }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
             };
+            parallax_trace_pr_comment: {
+                description: string;
+                args: {};
+                execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            parallax_trace_view: {
+                description: string;
+                args: {};
+                execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
         };
         "tool.execute.before": (input: {
             tool: string;
@@ -74,19 +84,11 @@ declare const _default: {
                 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;
-            };
+        "shell.env": (input: {
+            cwd: string;
+            sessionID?: string;
+        }, output: {
+            env: Record<string, string>;
         }) => Promise<void>;
         "experimental.chat.system.transform": (_input: unknown, output: {
             system?: string[];