frankcode 0.1.0__py3-none-any.whl

frankcode/cli.py

@@ -0,0 +1,69 @@
+import typer
+import asyncio
+import logging
+from typing import Optional
+from rich.console import Console
+from rich.logging import RichHandler
+
+from .environment import LocalEnvironment
+from .setup import FrankSetup
+from .orchestrator import FrankOrchestrator, resolve_nvm_path
+
+app = typer.Typer()
+console = Console()
+
+def setup_logging(verbose: bool):
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=[RichHandler(rich_tracebacks=True)]
+    )
+
+@app.command()
+def main(
+    prompt: str,
+    model: str = typer.Option("google/gemini-3.1-pro-preview", help="LLM model to use"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show debug logs"),
+    verify: bool = typer.Option(True, help="Enable verification and fix passes"),
+    clean: bool = typer.Option(False, help="Wipe .frankcode directory before starting"),
+    harbor_mode: bool = typer.Option(False, help="Exit with code 0 even if verification fails (for harbor compatibility)")
+):
+    setup_logging(verbose)
+    
+    if clean:
+        import shutil
+        import os
+        if os.path.exists(".frankcode"):
+            shutil.rmtree(".frankcode")
+
+    env = LocalEnvironment()
+    setup = FrankSetup(env, ".")
+    orchestrator = FrankOrchestrator(env, setup, model)
+
+    async def run():
+        # Step 0: Resolve NVM paths so npm/opencode are available
+        await resolve_nvm_path(env)
+
+        # Step 1: Install plugins and write configs
+        console.print("[bold blue]Installing safety plugins and generating configs...[/bold blue]")
+        await setup.ensure_directories()
+        await setup.install_plugins()
+        await setup.inject_plugins_into_system_configs()
+        
+        # Step 3: Run the task
+        console.print(f"[bold green]Executing task:[/bold green] {prompt}")
+        success = await orchestrator.run_task(prompt, verify=verify)
+        
+        if success:
+            console.print("[bold green]Task completed successfully![/bold green]")
+        else:
+            console.print("[bold red]Task failed to verify.[/bold red]")
+            if not harbor_mode:
+                raise typer.Exit(code=1)
+
+    asyncio.run(run())
+
+if __name__ == "__main__":
+    app()

frankcode/configs/oh-my-opencode-slim.json

@@ -0,0 +1,78 @@
+{
+  "preset": "harbor",
+  "presets": {
+    "harbor": {
+      "build": {
+        "model": "google/gemini-3.1-pro-preview"
+      },
+      "orchestrator": {
+        "model": "google/gemini-3.1-pro-preview",
+        "skills": [
+          "*"
+        ],
+        "mcps": [
+          "websearch",
+          "ast-grep"
+        ]
+      },
+      "oracle": {
+        "model": "openai/gpt-5.4",
+        "variant": "high",
+        "skills": [
+          "simplify"
+        ],
+        "mcps": []
+      },
+      "librarian": {
+        "model": "openai/gpt-5.4-mini",
+        "variant": "low",
+        "skills": [],
+        "mcps": [
+          "websearch",
+          "context7"
+        ]
+      },
+      "explorer": {
+        "model": "openai/gpt-5.4-mini",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      },
+      "designer": {
+        "model": "openai/gpt-5.4-mini",
+        "variant": "medium",
+        "skills": [
+          "agent-browser"
+        ],
+        "mcps": []
+      },
+      "fixer": {
+        "model": "google/gemini-3.1-pro-preview",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      },
+      "momus": {
+        "model": "google/gemini-3.1-pro-preview",
+        "skills": [],
+        "mcps": []
+      },
+      "data-scientist": {
+        "model": "google/gemini-3.1-pro-preview",
+        "skills": [],
+        "mcps": []
+      },
+      "allison": {
+        "model": "google/gemini-3.1-pro-preview",
+        "skills": [],
+        "mcps": []
+      },
+      "recon": {
+        "model": "openai/gpt-5.4-mini",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      }
+    }
+  }
+}

frankcode/configs/opencode-verify.json

@@ -0,0 +1,125 @@
+{
+  "snapshot": false,
+  "permission": {
+    "github_create_or_update_file": "deny"
+  },
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "__CONTEXT7_API_KEY__"
+      },
+      "enabled": true
+    }
+  },
+  "plugin": [
+    "oh-my-opencode-slim@latest",
+    "opencode-pty",
+    [
+      "opencode-auto-resume",
+      {
+        "loopMaxContinues": 3,
+        "loopWindowMs": 600000
+      }
+    ]
+  ],
+  "provider": {
+    "google": {
+      "options": {
+        "timeout": 600000,
+        "chunkTimeout": 90000
+      },
+      "models": {
+        "gemini-3.1-pro-preview": {
+          "name": "Gemini 3.1 Pro Preview",
+          "limit": {
+            "context": 1048576,
+            "output": 65535
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image",
+              "pdf"
+            ],
+            "output": [
+              "text"
+            ]
+          }
+        }
+      }
+    },
+    "openai": {
+      "models": {
+        "gpt-5.4": {
+          "name": "GPT-5.4"
+        },
+        "gpt-5.4-mini": {
+          "name": "GPT-5.4-mini"
+        }
+      }
+    }
+  },
+  "agent": {
+    "explore": {
+      "disable": true
+    },
+    "general": {
+      "disable": true
+    },
+    "build": {
+      "permission": {
+        "bash": {
+          "git add*": "deny",
+          "git commit*": "deny",
+          "sed": "deny"
+        }
+      }
+    },
+    "chat": {
+      "permission": {
+        "bash": {
+          "git add*": "deny",
+          "git commit*": "deny",
+          "python": "deny",
+          "sed": "deny"
+        }
+      }
+    },
+    "plan": {
+      "permission": {
+        "bash": {
+          "git add*": "deny",
+          "git commit*": "deny",
+          "sed": "deny"
+        }
+      }
+    },
+    "momus": {
+      "model": "google/gemini-3.1-pro-preview"
+    },
+    "data-scientist": {
+      "model": "google/gemini-3.1-pro-preview"
+    },
+    "allison": {
+      "model": "google/gemini-3.1-pro-preview"
+    },
+    "recon": {
+      "description": "Data reconnaissance specialist. Inspects unknown file formats, binary data, and APIs. Returns a concise structural summary.",
+      "mode": "subagent",
+      "model": "openai/gpt-5.4-mini",
+      "prompt": "You are a data reconnaissance agent. Your ONLY job is to inspect unknown files and report their structure.\n\nRules:\n1. You have a STRICT 3-script limit. Do not write more than 3 inspection scripts.\n2. Each script must print a concise summary (not raw data). Never dump large binary content.\n3. Always wrap execution with `timeout` and output limiting: `timeout 10s python3 script.py 2>&1 | head -n 50`\n4. When done, return a structured summary: file format, data layout, key dimensions, and any gotchas.\n5. Do NOT write implementation code. Only inspect and report.\n6. If a file is too large to read, sample it (first/last N bytes, random offsets).",
+      "permission": {
+        "bash": "allow",
+        "read": "allow",
+        "glob": "allow",
+        "grep": "allow",
+        "write": "deny",
+        "edit": "deny",
+        "task": "deny"
+      }
+    }
+  },
+  "model": "google/gemini-3.1-pro-preview"
+}

frankcode/configs/opencode.json

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

frankcode/configs/prompt-rules.json

@@ -0,0 +1,104 @@
+{
+  "recon_protocol": {
+    "name": "recon_protocol",
+    "weight": 10,
+    "applies_to_all": true,
+    "instruction": "MANDATORY FIRST ACTIONS — before writing ANY code or installing ANY packages:\n1. Run `ls -la` in the working directory to understand what files are already provided.\n2. Read any source files that look relevant (e.g., model definitions, config files, existing scripts, READMEs).\n2a. For tasks involving BINARY DATA FILES (.ckpt, .bin, .weights, .safetensors, raw tensor dumps), spawn a `recon` subagent BEFORE writing any implementation. The recon agent will inspect the files and return a structural report. Do NOT write your own diagnostic scripts — that is the recon agent's job.\n3. Identify what's already given vs. what you need to build.\n4. NEVER overwrite files that came with the task environment (images, model weights, test data, config files). These are test fixtures — the verifier expects them unchanged.\n5. If libraries or headers are already present in the working directory (e.g., cJSON.h, lodepng.h), use them instead of downloading alternatives.\n6. Put all intermediate/scratch files (helper scripts, test code, temporary build artifacts) in /tmp/work/ — keep the task directory clean with ONLY the final deliverables the task asks for.\n7. IMPLEMENTATION WORKFLOW: After building a first working version (compiles, runs, produces output), test it against the reference/expected output. If there are precision issues (pixel diffs, off-by-one errors, floating-point mismatches, partial test failures), do NOT iterate more than 3 times in your current session. Instead, spawn a `fixer` subagent using the Task tool. Give it: (a) the path to your implementation file, (b) the exact diff/error output, (c) any diagnostic data you've gathered. A fixer subagent with fresh context is more effective for precision work than continuing in a polluted context."
+  },
+  "cleanup_rules": {
+    "name": "cleanup_rules",
+    "weight": 9,
+    "applies_to_all": true,
+    "instruction": "CLEANUP RULES: If you test your solution by creating mock data, making test commits, or altering state, you must clean up TEST ARTIFACTS before finishing — but be precise about WHAT you clean up.\n- CLEAN UP: temporary test scripts, test clones/repos you created to verify, mock data files, test outputs, scratch directories (e.g., /tmp/test-repo).\n- DO NOT CLEAN UP: infrastructure you built as part of the solution — servers, daemons, hooks, config files, databases, repositories that the TASK asked you to create. These are deliverables, not artifacts.\n- If you pushed test content to a repository or server that should start EMPTY for the verifier, reset only the DATA — do NOT destroy and recreate the infrastructure itself.\n- RULE OF THUMB: If the task asked you to 'set up X' or 'configure X', then X must still be running and properly configured when you finish."
+  },
+  "environment_isolation": {
+    "name": "environment_isolation",
+    "weight": 9,
+    "applies_to_all": true,
+    "instruction": "ENVIRONMENT ISOLATION: The verifier runs in a separate, clean environment. Only files inside the task directory (/app/) are carried over. Everything else — installed packages (pip, apt, npm, cargo), running services, environment variables, config files outside /app/, symlinks to external paths — will NOT exist when the verifier runs. Your deliverables must be fully self-contained. If a script requires a non-stdlib library, it must either self-install its dependencies at runtime or use an alternative approach that relies only on tools already present in the base image (see AVAILABLE TOOLS above). Do NOT assume any package you install during your session will be available to the verifier."
+  },
+  "verify_deliverables": {
+    "name": "verify_deliverables",
+    "weight": 9,
+    "applies_to_all": true,
+    "instruction": "DELIVERABLE VERIFICATION: Before calling task_complete, run `ls -la /app/` and confirm that every file the task asked you to create actually exists there. If you wrote files to /tmp/work/ but not to /app/, copy them now. The verifier only checks /app/ — files anywhere else will not be found."
+  },
+  "deliverables_manifest": {
+    "name": "deliverables_manifest",
+    "weight": 9,
+    "applies_to_all": true,
+    "instruction": "DELIVERABLES MANIFEST: Before calling task_complete or finishing your work, write a file at /tmp/deliverables.manifest listing one absolute path per line for every file in the task directory (/app/) that must exist for the verifier to succeed. Include: source files you modified, compiled binaries or shared libraries (.so, .pyd, .dll) you built, generated data files, config files you created — anything the tests will need at runtime. Do NOT include intermediate build artifacts (object files, build/ directories, dist/ directories, caches). Do NOT include files that existed before you started (fixtures). Example:\n/app/portfolio_optimized.c\n/app/portfolio_optimized.py\n/app/portfolio_optimized_c.cpython-313-x86_64-linux-gnu.so\nIf you are unsure whether to include a file, include it — it is safer to over-include than to omit a file the verifier needs."
+  },
+  "circuit_breaker": {
+    "name": "circuit_breaker",
+    "weight": 8,
+    "applies_to_all": true,
+    "instruction": "CRITICAL SYSTEM INSTRUCTION:\n1. LOOP DETECTION: If you are stuck tweaking the same file/parameters more than 5 times without passing tests, STOP. Abandon your current approach and escalate: (a) Search the web for known issues, bugs, or bypasses specific to the technology you're working with (e.g., 'BeautifulSoup XSS bypass', 'Coq 8.18 compatibility'). (b) If web search doesn't help, spawn a fixer subagent with fresh context. (c) If neither works, delete the file and try a fundamentally different architecture.\n2. BINARY FILE SAFETY: NEVER `cat` or `read` large binary or image files (.ppm, .png, etc) into your context. Write a short script to extract the properties you need and print only the summary.\n3. DEFENSIVE EXECUTION: When running any compiled binary, untrusted script, or unfamiliar command for the first time, ALWAYS wrap it: `timeout 5s ./binary arg1 arg2 2>&1 | head -c 2000`. Never run untrusted executables without both a time limit and an output cap.\n4. CONTEXT PROTECTION: If your context becomes polluted with massive error logs or repeated output, DO NOT continue in the current session. Summarize your progress and use the `Task` tool to spawn a subagent (`fixer` or `explorer`) with fresh context.\n5. DIAGNOSIS BUDGET: You get 3 read-only diagnostic steps before you must write your first implementation. If the task names a specific interface, library, or framework that requires API exploration, you get 8 read-only steps instead. After your first implementation attempt, the stricter budget applies to each debug cycle: diagnose(max 3) → fix → diagnose(max 3) → fix. NEVER write more than 3 consecutive diagnostic scripts after implementation without attempting a code change.\n6. LONG-RUNNING COMMANDS: The bash tool has a 120-second timeout. For commands that take longer (make, opam install, cargo build, training, hash cracking, large downloads), use `pty_spawn` with `notifyOnExit: true`. Use `pty_read` to check progress. If bash says 'shell tool terminated command after exceeding timeout', switch to `pty_spawn`. For multi-step pipelines (train → evaluate → save, compile → test → install), write a single wrapper shell script that runs all steps end-to-end, then spawn that script with pty_spawn. Do not spawn individual pipeline steps and poll between them — if your session ends before the pipeline completes, intermediate results will be lost."
+  },
+  "programmatic_verification": {
+    "name": "programmatic_verification",
+    "weight": 5,
+    "applies_to_all": true,
+    "instruction": "PROGRAMMATIC VERIFICATION: For tasks requiring precise analytical answers (chess moves, mathematical proofs, regex patterns, logic puzzles, cryptographic challenges), do NOT trust your reasoning alone. Write a short script to verify your answer programmatically before writing it to the output file."
+  },
+  "interface_fidelity": {
+    "name": "interface_fidelity",
+    "weight": 7,
+    "keywords": ["installed", "at version", "at revision", "using the", "package at", "have the"],
+    "instruction": "SPECIFIED INTERFACE FIDELITY: The task names a specific library, framework, tool, or versioned runtime. Treat that choice as semantically load-bearing — use the named interface as your primary API. Do not substitute a lower-level or different-stack alternative you happen to know better. Before implementing, inspect the named interface: Python lib → inspect.signature() / help(); CLI tool → --help / --version; compiler/runtime → sample invocation or docs. The task author chose that interface for a reason — it likely handles defaults, conventions, or edge cases the lower-level alternative does not."
+  },
+  "performance_awareness": {
+    "name": "performance_awareness",
+    "weight": 6,
+    "keywords": ["train", "inference", "compute", "gpu", "neural", "benchmark", "optimization", "faster", "optimize", "performance", "simulation", "parallelism", "parallel", "eigenval", "sampling", "sampler"],
+    "instruction": "PERFORMANCE AWARENESS: If your solution involves compute-intensive operations (matrix math, large data processing, inference, image generation, simulation), benchmark it with `time` before declaring it complete. If it takes more than 60 seconds on your test inputs, you must optimize the hot path before finishing. Verifiers typically enforce strict timeouts."
+  },
+  "binary_data_format": {
+    "name": "binary_data_format",
+    "weight": 8,
+    "keywords": ["checkpoint", ".ckpt", ".bin", "binary", "weight", "tensor", "forward pass", "inference", "model weights", "data layout", "HuggingFace", "GPT-2", "weights.json"],
+    "instruction": "BINARY DATA FORMAT RULE: The task involves binary data files (checkpoints, weight files, serialized tensors). You MUST follow this workflow:\n\nPHASE 1 — RECON (mandatory before writing implementation):\nSpawn a `recon` subagent using the Task tool with this information:\n  - The binary file paths and their sizes\n  - What format you suspect (TF checkpoint, PyTorch, raw floats, protobuf, etc.)\n  - What you need to know: tensor names, shapes, byte offsets, and ordering\n\nWait for the recon report before proceeding. If the recon agent cannot determine the layout, try ONE of these escalation paths:\n  (a) Download the format's companion metadata file (TF checkpoints have .index files; PyTorch has state_dict keys; safetensors has a JSON header). Parse it to get exact tensor names and offsets.\n  (b) Install the canonical library (pip install tensorflow/torch/safetensors) and run a 5-line script to print variable names, shapes, and dtypes.\n  (c) Search the web for the exact format specification.\n\nPHASE 2 — IMPLEMENT (only after recon is complete):\nWrite your implementation in ONE shot based on the recon report. Do not write the implementation incrementally with diagnostic scripts interleaved.\n\nANTI-PATTERN: Writing separate small C/Python programs to probe different byte offsets one at a time. This burns your entire time budget. The recon subagent does this in parallel and with a script budget."
+  },
+  "size_constraint": {
+    "name": "size_constraint",
+    "weight": 8,
+    "keywords": ["bytes", "must be <", "must be under", "at most", "maximum size", "size limit", "under 100"],
+    "instruction": "SIZE-CONSTRAINED DELIVERABLE: The task specifies a maximum file size or count. After EVERY write to a deliverable file, immediately check the constraint (wc -c for bytes, wc -l for lines, jq length for JSON arrays). If you exceed the limit, STOP adding features and reduce size: use short variable names, remove comments and whitespace, merge functions, eliminate redundancy. The size constraint is as important as correctness — a correct solution that exceeds the limit scores 0. Plan for the constraint from the start: estimate your budget before writing, not after."
+  },
+  "persistent_servers": {
+    "name": "persistent_servers",
+    "weight": 6,
+    "keywords": ["pypi server", "web server", "API server", "daemon", "running on port", "run on port", "on port", "webserver", "listen on", "service should run", "run the service", "Flask"],
+    "instruction": "PERSISTENT SERVERS: If your task requires a server or long-running process to remain running AFTER your session ends, you MUST start it as a background daemon using `nohup command &>/dev/null &` or `setsid command &>/dev/null &`, NOT via `pty_spawn` or foreground execution. PTY sessions and foreground processes are destroyed when your session ends. Always verify the server is actually listening with `curl` or `ss -tlnp` before declaring the task complete."
+  },
+  "client_perspective_testing": {
+    "name": "client_perspective_testing",
+    "weight": 5,
+    "keywords": ["git server", "webserver", "curl http", "git clone user@"],
+    "instruction": "CLIENT-PERSPECTIVE TESTING: When your task involves setting up any network service (web server, git server, API, database), always test it the way an external client would — over HTTP, SSH, or TCP, not via local filesystem paths. The verifier accesses your services over the network."
+  },
+  "data_preservation": {
+    "name": "data_preservation",
+    "weight": 6,
+    "keywords": ["corrupted", "deleted file", "forensic", "damaged", "WAL file", "recover the", "recovery task"],
+    "instruction": "DATA PRESERVATION: When the task involves recovering, repairing, or analyzing corrupted or damaged files, ALWAYS back up the original files before running any tools on them. Copy them to /tmp/ first. Tools like sqlite3, git, fsck may automatically 'fix' corrupted files, destroying the data you need to recover."
+  },
+  "decomposed_search": {
+    "name": "decomposed_search",
+    "weight": 5,
+    "keywords": ["disk image", "fragment", "PASSWORD=", "launchcode"],
+    "instruction": "DECOMPOSED SEARCH: When searching for a pattern with known start and end markers in binary data, disk images, or large files, ALWAYS search for each marker independently. Deleted or fragmented data is often scattered across non-contiguous disk regions. Find all fragments first, then reconstruct the complete value."
+  },
+  "prefer_binary_packages": {
+    "name": "prefer_binary_packages",
+    "weight": 4,
+    "keywords": ["set up a", "configure a", "build from source", "build the", "pypi server", "git server", "webserver"],
+    "instruction": "PREFER BINARY PACKAGES: When installing dependencies, always try pre-built binary packages first (apt-get install, pip binary wheels) before building from source. Building from source can take 10-30 minutes. Also check if tools are already installed — run `which <tool>` or `dpkg -l | grep <tool>` before installing anything. However, if a configure script or build tool specifies exact version requirements and the system package has a different version, use a language-specific version manager (opam for OCaml/Coq, pyenv for Python, nvm for Node, rustup for Rust) to install the required version. Do not force through version checks with flags like --ignore-version or --skip-check."
+  },
+  "qemu_vm": {
+    "name": "qemu_vm",
+    "weight": 6,
+    "keywords": ["qemu", "QEMU", "virtual machine", "VM", "alpine"],
+    "instruction": "QEMU VM MANAGEMENT: When booting a VM with QEMU, do NOT use pty_spawn. Instead, daemonize QEMU with a serial console socket: `qemu-system-x86_64 -display none -serial unix:/tmp/vm-serial.sock,server,nowait -monitor unix:/tmp/vm-monitor.sock,server,nowait -daemonize -pidfile /tmp/vm.pid`. Connect to the console with `nc -U /tmp/vm-serial.sock` and use `expect` for automated interaction (login, password, service config). For user-mode networking with port forwarding: `-netdev user,id=n0,hostfwd=tcp::PORT-:GUESTPORT -device e1000,netdev=n0`. Wait for the login prompt before configuring services. Test SSH locally before declaring complete."
+  }
+}

frankcode/environment.py

@@ -0,0 +1,53 @@
+import asyncio
+import os
+import subprocess
+from dataclasses import dataclass
+from typing import Optional, Dict
+
+@dataclass
+class ExecResult:
+    stdout: str
+    stderr: str
+    exit_code: Optional[int]
+
+class LocalEnvironment:
+    def __init__(self):
+        self._extra_path: str = ""
+
+    def prepend_path(self, path_entry: str):
+        """Prepend a directory to PATH for all future exec() calls."""
+        if self._extra_path:
+            self._extra_path = f"{path_entry}:{self._extra_path}"
+        else:
+            self._extra_path = path_entry
+
+    async def exec(
+        self,
+        command: str,
+        cwd: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None
+    ) -> ExecResult:
+        # Merge current env with provided env
+        full_env = os.environ.copy()
+        if env:
+            full_env.update(env)
+
+        # Prepend resolved paths (e.g. NVM bin dir) so node/npm/opencode are found
+        if self._extra_path:
+            full_env["PATH"] = f"{self._extra_path}:{full_env.get('PATH', '')}"
+
+        process = await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd or os.getcwd(),
+            env=full_env
+        )
+
+        stdout, stderr = await process.communicate()
+        
+        return ExecResult(
+            stdout=stdout.decode().strip(),
+            stderr=stderr.decode().strip(),
+            exit_code=process.returncode
+        )

frankcode/orchestrator.py

@@ -0,0 +1,343 @@
+import asyncio
+import logging
+import os
+import time
+import hashlib
+import shlex
+import re
+import json
+from pathlib import Path
+from typing import Optional, List, Tuple, Dict
+
+from .environment import LocalEnvironment
+from .setup import FrankSetup
+from .utils import check_error_loop
+
+logger = logging.getLogger(__name__)
+
+def _load_config(name: str) -> dict:
+    """Load a JSON config from the configs/ directory."""
+    config_dir = Path(__file__).parent / "configs"
+    try:
+        with open(config_dir / name) as f:
+            return json.load(f)
+    except FileNotFoundError:
+        logger.warning(f"Config {name} not found in {config_dir}")
+        return {}
+
+
+async def resolve_nvm_path(env: LocalEnvironment) -> None:
+    """Find and register the NVM bin directory so node/npm/opencode are on PATH."""
+    home = Path.home()
+
+    candidates = [home / ".nvm"]
+    if str(home) != "/root":
+        candidates.append(Path("/root/.nvm"))
+
+    nvm_dir = None
+    for candidate in candidates:
+        if candidate.exists():
+            nvm_dir = candidate
+            break
+
+    if nvm_dir is None:
+        logger.warning("NVM directory not found in any of: %s", [str(c) for c in candidates])
+        return
+
+    # Strategy: find the node bin directory directly via filesystem.
+    # This avoids sourcing nvm.sh (which may contain bashisms) in /bin/sh.
+    result = await env.exec(
+        f'find "{nvm_dir}/versions/node" -maxdepth 2 -name bin -type d 2>/dev/null | sort -V | tail -1'
+    )
+
+    if result.exit_code == 0 and result.stdout.strip():
+        bin_dir = result.stdout.strip()
+        logger.info("Resolved NVM bin directory: %s", bin_dir)
+        env.prepend_path(bin_dir)
+    else:
+        logger.warning("Could not resolve NVM bin directory under %s", nvm_dir)
+
+class FrankOrchestrator:
+    def __init__(self, env: LocalEnvironment, setup: FrankSetup, model: str):
+        self.env = env
+        self.setup = setup
+        self.model = model
+        self.error_history = []
+        self.initial_file_listing = ""
+
+    def _select_rules(self, instruction: str) -> List[str]:
+        """Port of _select_rules from original agent.py."""
+        config = _load_config("prompt-rules.json")
+        selected = []
+
+        for rule_name, rule in config.items():
+            if rule.get("applies_to_all"):
+                selected.append(rule["instruction"])
+                continue
+            keywords = rule.get("keywords", [])
+            for kw in keywords:
+                if kw.lower() in instruction.lower():
+                    selected.append(rule["instruction"])
+                    break
+
+        return selected
+
+    async def run_task(self, prompt: str, verify: bool = True):
+        await self.setup.ensure_directories()
+
+        # Capture initial file listing
+        try:
+            initial_result = await self.env.exec(
+                "find . -type f -not -path '*/.git/*' -not -path './.frankcode/*' 2>/dev/null | sort"
+            )
+            self.initial_file_listing = initial_result.stdout.strip()
+            logger.info(f"Captured initial file listing ({len(self.initial_file_listing.splitlines())} files).")
+        except Exception:
+            pass
+
+        # Select and inject rules
+        rules = self._select_rules(prompt)
+        enhanced_prompt = prompt + "\n\n" + "\n\n".join(rules)
+
+        logger.info("Starting main agent session...")
+        success = await self._run_main_session(enhanced_prompt)
+        
+        if not verify:
+            return success
+
+        logger.info("Starting cleanup pass...")
+        await self._run_cleanup(prompt)
+
+        logger.info("Starting verification/fix loop...")
+        for i in range(3):
+            iteration = i + 1
+            logger.info(f"Verification iteration {iteration}/3")
+            verified, feedback = await self._run_verification(prompt, iteration)
+            if verified:
+                logger.info("Task verified successfully!")
+                return True
+            
+            logger.info(f"Verification failed. Feedback: {feedback[:100]}...")
+            logger.info("Starting fix pass...")
+            await self._run_fix(prompt, feedback, iteration)
+            
+        return False
+
+    async def _run_opencode_session(
+        self,
+        prompt: str,
+        output_path: Path,
+        config_name: str = "opencode.json",
+        timeout_seconds: int | None = None,
+    ) -> bool:
+        config_dir = Path.home() / ".config" / "opencode"
+        
+        env = os.environ.copy()
+        # Do not override OPENCODE_CONFIG_DIR so it uses system defaults.
+        
+        # Swap config if needed
+        if config_name != "opencode.json":
+            await self.env.exec(f"cp {config_dir}/{config_name} {config_dir}/opencode.json")
+
+        escaped_prompt = shlex.quote(prompt)
+        timeout_prefix = f"timeout {timeout_seconds}s " if timeout_seconds else ""
+        
+        cmd = (
+            f"{timeout_prefix}opencode --model={self.model} run --format=json --thinking --dangerously-skip-permissions -- {escaped_prompt} </dev/null > {output_path} 2>&1"
+        )
+        
+        result = await self.env.exec(cmd, env=env)
+        
+        if config_name != "opencode.json":
+             # Restore the main config backup
+             await self.env.exec(f"cp {config_dir}/opencode-main.json {config_dir}/opencode.json")
+             
+        return result.exit_code == 0
+
+    async def _run_main_session(self, prompt: str):
+        log_path = self.setup.logs_dir / "opencode.txt"
+        config_dir = Path.home() / ".config" / "opencode"
+        
+        env = os.environ.copy()
+        
+        escaped_prompt = shlex.quote(prompt)
+        cmd = (
+            f"opencode --model={self.model} run --format=json --thinking --dangerously-skip-permissions -- {escaped_prompt} </dev/null > {log_path} 2>&1"
+        )
+
+        process_task = asyncio.create_task(self.env.exec(cmd, env=env))
+        
+        last_size = -1
+        last_activity = time.time()
+        last_error_hash = None
+        same_error_streak = 0
+        
+        while not process_task.done():
+            await asyncio.sleep(5)
+            if not log_path.exists():
+                continue
+                
+            current_size = log_path.stat().st_size
+            if current_size != last_size:
+                last_size = current_size
+                last_activity = time.time()
+            
+            # Error-repeat detection (simplified port from agent.py)
+            try:
+                err_check = await self.env.exec(
+                    f"tail -c 5000 {log_path} 2>/dev/null | grep -oiE '(Error|Traceback|FAILED|AssertionError|Exception|Arity mismatch)[^\"}}]*' 2>/dev/null | tail -5"
+                )
+                error_lines = err_check.stdout.strip()
+                if error_lines:
+                    current_hash = hashlib.md5(error_lines.encode()).hexdigest()
+                    if current_hash == last_error_hash:
+                        same_error_streak += 1
+                    else:
+                        same_error_streak = 1
+                        last_error_hash = current_hash
+                    
+                    if same_error_streak >= 36: # Approx 3 minutes at 5s polling
+                        logger.warning("Watchdog: Same error detected for 3+ minutes. Terminating session.")
+                        # We cannot directly kill the asyncio.create_subprocess_shell from outside unless we restructure LocalEnvironment.
+                        # For now, let it run or rely on opencode's internal timeout/loop breaking.
+                        break
+            except Exception:
+                pass
+                
+            if time.time() - last_activity > 600:
+                logger.warning("Watchdog: Process idle for 10 minutes. Terminating.")
+                break
+                
+        result = await process_task
+        if result.exit_code != 0:
+            logger.error(f"Main session failed with exit code {result.exit_code}")
+        return result.exit_code == 0
+
+    async def _run_cleanup(self, instruction: str):
+        try:
+            await self.env.exec(
+                "find . -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null; "
+                "find . -name '*.pyc' -delete 2>/dev/null; "
+                "true"
+            )
+        except Exception:
+            pass
+
+        if not self.initial_file_listing:
+            return
+
+        try:
+            current_result = await self.env.exec(
+                "find . -type f -not -path '*/.git/*' -not -path './.frankcode/*' 2>/dev/null | sort"
+            )
+            current_file_listing = current_result.stdout.strip()
+        except Exception:
+            return
+
+        initial_set = set(self.initial_file_listing.splitlines())
+        current_set = set(current_file_listing.splitlines())
+        new_files = sorted(current_set - initial_set)
+
+        if not new_files:
+            return
+
+        cleanup_prompt = (
+            "You are a cleanup agent. Your ONLY job is to remove scratch files "
+            "and build artifacts that a previous agent left behind in the task "
+            "directory. You must NOT remove deliverable files.\n\n"
+            f"TASK SPEC (what deliverables were requested):\n{instruction}\n\n"
+            "FILES THAT EXISTED BEFORE THE AGENT RAN (fixtures — never touch):\n"
+            f"{self.initial_file_listing}\n\n"
+            "NEW FILES TO EVALUATE FOR CLEANUP:\n"
+            + "\n".join(new_files) + "\n\n"
+            "RULES:\n"
+            "1. Files in the INITIAL listing are FIXTURES — never remove them.\n"
+            "2. Deliverables named or implied by the task spec — never remove them.\n"
+            "3. Everything else is a scratch artifact — move it to .frankcode/quarantine/ using mv.\n"
+            "4. When UNSURE whether a file is a deliverable, KEEP it.\n\n"
+            "Execute mv commands to move artifacts to .frankcode/quarantine/. "
+            "Do NOT use rm. Do NOT run tests, modify deliverables, or write any new files."
+        )
+
+        await self._run_opencode_session(
+            cleanup_prompt,
+            self.setup.logs_dir / "cleanup.txt",
+            config_name="opencode-verify.json",
+            timeout_seconds=60
+        )
+
+    async def _run_verification(self, instruction: str, iteration: int) -> Tuple[bool, str]:
+        verify_prompt = (
+            "You are an ADVERSARIAL VERIFICATION agent. Your job is to independently "
+            "verify the deliverables — not by re-running the implementation, but by "
+            "designing your own tests that check the answer from a different angle.\n\n"
+            f"ORIGINAL TASK SPEC:\n{instruction}\n\n"
+            "VERIFICATION PROCESS:\n"
+            "1. Read the deliverable files AND the implementation code/scripts to understand what approach was used.\n"
+            "2. Extract every testable condition from the task spec.\n"
+            "3. For each condition, write a verification script that checks the answer using a DIFFERENT method than the implementation.\n"
+            "4. If ANY of your independent tests produces a mismatch, you MUST report NEEDS_FIX.\n"
+            "5. Do NOT modify any files in the task directory. Put all your verification scripts in .frankcode/verify/.\n"
+            "6. Produce your verdict as the LAST line of output:\n"
+            "   - VERIFIED\n"
+            "   - NEEDS_FIX: followed by a detailed description\n"
+        )
+
+        log_path = self.setup.logs_dir / f"verify_{iteration}.txt"
+        await self._run_opencode_session(
+            verify_prompt,
+            log_path,
+            config_name="opencode-verify.json",
+            timeout_seconds=300
+        )
+
+        if not log_path.exists():
+            return False, "Verification log not found"
+
+        with open(log_path, "r") as f:
+            raw_tail = f.read()[-5000:]
+            
+        verdict = self._extract_verdict(raw_tail)
+        return verdict == "VERIFIED", raw_tail
+
+    async def _run_fix(self, instruction: str, feedback: str, iteration: int):
+        fix_prompt = (
+            "A previous agent attempted this task but the solution may have bugs. "
+            "The implementation files are already in place.\n\n"
+            f"ORIGINAL TASK:\n{instruction}\n\n"
+            f"VERIFICATION RESULT:\n{feedback[-2000:]}\n\n"
+            "Read the existing files, understand what's failing, and fix it. "
+            "Test your fix before declaring complete."
+        )
+
+        await self._run_opencode_session(
+            fix_prompt,
+            self.setup.logs_dir / f"fix_{iteration}.txt",
+            config_name="opencode-verify.json",
+            timeout_seconds=300
+        )
+
+    @staticmethod
+    def _extract_verdict(raw_tail: str) -> str:
+        for line in reversed(raw_tail.splitlines()):
+            line = line.strip()
+            if not line:
+                continue
+
+            if '"text"' in line or '"output"' in line:
+                text_matches = re.findall(r'"(?:text|output)"\s*:\s*"((?:[^"\\]|\\.)*)"', line)
+                for text_value in reversed(text_matches):
+                    text_value = text_value.replace("\\n", "\n").replace('\\"', '"')
+                    for verdict_line in reversed(text_value.splitlines()):
+                        verdict_line = verdict_line.strip()
+                        if verdict_line.startswith("VERIFIED"):
+                            return "VERIFIED"
+                        if verdict_line.startswith("NEEDS_FIX"):
+                            return "NEEDS_FIX"
+
+            if line.startswith("VERIFIED"):
+                return "VERIFIED"
+            if line.startswith("NEEDS_FIX"):
+                return "NEEDS_FIX"
+
+        return "UNKNOWN"

frankcode/setup.py

@@ -0,0 +1,112 @@
+import sys
+import os
+import json
+import logging
+from pathlib import Path
+from typing import Dict, List, Any
+from .environment import LocalEnvironment
+
+logger = logging.getLogger(__name__)
+
+class FrankSetup:
+    def __init__(self, env: LocalEnvironment, work_dir: str):
+        self.env = env
+        self.work_dir = Path(work_dir)
+        self.frank_dir = self.work_dir / ".frankcode"
+        self.logs_dir = self.frank_dir / "logs"
+        self.quarantine_dir = self.frank_dir / "quarantine"
+
+    async def ensure_directories(self):
+        self.frank_dir.mkdir(parents=True, exist_ok=True)
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+        self.quarantine_dir.mkdir(parents=True, exist_ok=True)
+
+    def get_os(self) -> str:
+        if sys.platform == "darwin":
+            return "macos"
+        return "linux"
+
+    async def install_plugins(self):
+        plugins = [
+            "opencode-anti-loop",
+            "opencode-auto-reviewer",
+            "opencode-context-warning",
+            "opencode-deadline-pressure",
+            "opencode-heartbeat",
+            "opencode-ledger"
+        ]
+        logger.info(f"Installing plugins via npm into {self.frank_dir}...")
+        cmd = f"npm install --prefix {self.frank_dir} {' '.join(plugins)}"
+        return await self.env.exec(cmd)
+
+    async def inject_plugins_into_system_configs(self):
+        # We find ~/.config/opencode
+        config_dir = Path.home() / ".config" / "opencode"
+        if not config_dir.exists():
+            config_dir.mkdir(parents=True, exist_ok=True)
+            
+        plugin_paths = [
+            str(self.frank_dir.resolve() / "node_modules" / "opencode-anti-loop"),
+            str(self.frank_dir.resolve() / "node_modules" / "opencode-auto-reviewer"),
+            str(self.frank_dir.resolve() / "node_modules" / "opencode-context-warning"),
+            str(self.frank_dir.resolve() / "node_modules" / "opencode-deadline-pressure"),
+            str(self.frank_dir.resolve() / "node_modules" / "opencode-heartbeat"),
+            str(self.frank_dir.resolve() / "node_modules" / "opencode-ledger")
+        ]
+        
+        # 1. Inject into main opencode.json
+        main_config_path = config_dir / "opencode.json"
+        main_config = {}
+        if main_config_path.exists():
+            try:
+                with open(main_config_path, "r") as f:
+                    main_config = json.load(f)
+            except Exception as e:
+                logger.warning(f"Failed to read {main_config_path}: {e}")
+        
+        existing_plugins = main_config.get("plugin", [])
+        if not isinstance(existing_plugins, list):
+            existing_plugins = [existing_plugins]
+            
+        # Deduplicate
+        final_plugins = existing_plugins.copy()
+        for p in plugin_paths:
+            if p not in final_plugins:
+                final_plugins.append(p)
+                
+        main_config["plugin"] = final_plugins
+        
+        with open(main_config_path, "w") as f:
+            json.dump(main_config, f, indent=2)
+            
+        # 2. Inject into opencode-verify.json if it exists
+        verify_config_path = config_dir / "opencode-verify.json"
+        if verify_config_path.exists():
+            try:
+                with open(verify_config_path, "r") as f:
+                    verify_config = json.load(f)
+                
+                v_existing = verify_config.get("plugin", [])
+                if not isinstance(v_existing, list):
+                    v_existing = [v_existing]
+                    
+                v_final = v_existing.copy()
+                for p in plugin_paths:
+                    if p not in v_final:
+                        v_final.append(p)
+                        
+                verify_config["plugin"] = v_final
+                with open(verify_config_path, "w") as f:
+                    json.dump(verify_config, f, indent=2)
+            except Exception as e:
+                logger.warning(f"Failed to read/write {verify_config_path}: {e}")
+                
+        # 3. Create a backup of the original injected main config so we can restore it after verify passes
+        backup_path = config_dir / "opencode-main.json"
+        with open(backup_path, "w") as f:
+            json.dump(main_config, f, indent=2)
+
+    # We do not use preinstall_deps in CLI anymore because it lacks root permissions.
+    # It is handled in agent.py now.
+    async def preinstall_deps(self, instruction: str):
+        pass

frankcode/utils.py

@@ -0,0 +1,16 @@
+import hashlib
+from typing import List
+
+def check_error_loop(hash_history: List[str], threshold: int = 3) -> bool:
+    if len(hash_history) < threshold:
+        return False
+    
+    last_hash = hash_history[-1]
+    streak = 0
+    for h in reversed(hash_history):
+        if h == last_hash:
+            streak += 1
+        else:
+            break
+            
+    return streak >= threshold

frankcode-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: frankcode
+Version: 0.1.0
+Summary: Advanced multi-agent orchestrator for OpenCode
+Author: joeyism
+License: MIT
+Project-URL: Homepage, https://github.com/joeyism/frankcode
+Project-URL: Repository, https://github.com/joeyism/frankcode
+Project-URL: Issues, https://github.com/joeyism/frankcode/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# FrankCode
+
+Advanced multi-agent orchestrator for OpenCode.
+
+FrankCode acts as a wrapper and orchestration layer around OpenCode, managing specialized agent setups, safety plugins, verification passes, and environment configurations to accomplish complex development tasks safely and robustly.
+
+## Requirements
+
+Before installing FrankCode, ensure you have the following prerequisites installed on your system:
+
+- **Python**: `>= 3.10`
+- **Node.js & npm**: Required to install OpenCode plugins and manage the environment dynamically. FrankCode will attempt to automatically resolve Node via `nvm` if available.
+- **OpenCode**: Make sure the `opencode` CLI is installed and available in your `PATH`.
+
+## Installation
+
+You can install FrankCode directly via pip:
+
+```bash
+pip install frankcode
+```
+
+Alternatively, to run from source:
+
+```bash
+git clone https://github.com/joeyism/frankcode.git
+cd frankcode
+pip install -e .
+```
+
+## Usage
+
+FrankCode provides a simple CLI. To execute a task using the default multi-agent orchestrator:
+
+```bash
+frankcode "Create a new React component that fetches data from an API and displays it in a table"
+```
+
+### Options
+
+- `--model`: Specify the LLM model to use (default: `google/gemini-3.1-pro-preview`).
+- `--verbose`, `-v`: Show debug logs.
+- `--no-verify`: Disable the autonomous verification and fix passes.
+- `--clean`: Wipe the `.frankcode` execution environment before starting.
+
+Example:
+
+```bash
+frankcode "Refactor the auth logic to use JWT" --model openai/gpt-5.4 --verbose
+```
+
+## How It Works
+
+1. **Environment Setup**: FrankCode creates an isolated `.frankcode` directory to store logs, quarantine artifacts, and install specific OpenCode plugins dynamically.
+2. **Execution**: Your prompt is passed into an enhanced OpenCode session. FrankCode actively monitors the process for infinite error loops or idle timeouts.
+3. **Verification Loop (Optional but enabled by default)**: After the main task completes, an adversarial validation agent reads the outputs and devises independent tests. If the tests fail, FrankCode triggers a "fix pass" and repeats the verification.
+4. **Cleanup**: Temporary artifacts generated during agent reasoning are quarantined.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

frankcode-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+frankcode/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+frankcode/cli.py,sha256=xp8tCCuEIU3thx9eYLdMxv5_Wi9vkzeGpUQLeigSDDE,2297
+frankcode/environment.py,sha256=IdRl2Evqo5sU1x472diLBUvA3laWpw1L3urDadD1QlQ,1504
+frankcode/orchestrator.py,sha256=eSw5Cypz7seWM0QeDDqKGaseQDRfsOAE1EzQMVDcdAA,13767
+frankcode/setup.py,sha256=VrX8S6J_v5y9YOj3DKTAGmVjb_kJNzmeSy99i_uhaZg,4472
+frankcode/utils.py,sha256=_AyIggd0_X6omVlGh4QGdfjG82b2DawjlI6jiD24vkk,391
+frankcode/configs/oh-my-opencode-slim.json,sha256=oQmCCxQrGGGyCaRkQfDCSbndDvqw4bdnyZxsiJul5X0,1638
+frankcode/configs/opencode-verify.json,sha256=vsPenxhDqXS3ZSLTLkU00ng_MHmxkI-HSjn1rA2PApI,3218
+frankcode/configs/opencode.json,sha256=yj0WO6sFU4GCciYUBWjzvvfqrBh869doeOC2Pp5EI1Y,3
+frankcode/configs/prompt-rules.json,sha256=kRbDHHkr9cefWRblRMaPU7rTvmSVnKD2iIJT2zK5P3I,16102
+frankcode-0.1.0.dist-info/licenses/LICENSE,sha256=Efkiyt9ImfICPljcBeVuDTPhI2oOwih_twu6quBoePI,1063
+frankcode-0.1.0.dist-info/METADATA,sha256=rL0ZyA-KiACm3S9OYwSNu7DGvLGUkce78g0orIo5G3g,3141
+frankcode-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+frankcode-0.1.0.dist-info/entry_points.txt,sha256=womlESdSPcIMJppDxJ5VPkAc1J2GBQkAnegxRcAIJXo,48
+frankcode-0.1.0.dist-info/top_level.txt,sha256=bQRmX59A1cyP_gMp7iHbbIQ2yRLrxQsTtlGRcI3W_9E,10
+frankcode-0.1.0.dist-info/RECORD,,

frankcode-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

frankcode-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+frankcode = frankcode.cli:app

frankcode-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joeyism
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frankcode-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+frankcode